@sofya-sdk/qr

QR code generation, backend contract helpers, and parsing utilities for Sofya SDK.

Installation

pnpm add @sofya-sdk/qr

Usage

Backend Integration (Contract Helpers)

Receptor (Desktop) Flow

import {
  createCanalSession,
  buildEventRoomsConnection,
  getQrCodeUrlFromContract,
  getQrCodeAssetLinkFromContract,
} from '@sofya-sdk/qr';

const canal = await createCanalSession({
  baseUrl: 'https://api.your-backend.com',
});

const qrCodeForPwa =
  canal.qrCodeUrl ?? getQrCodeUrlFromContract(canal.contract);

const qrCodeImage =
  canal.qrCodeBucketLink ?? getQrCodeAssetLinkFromContract(canal.contract);

const eventRooms = buildEventRoomsConnection(canal.contract, 'desktop');
// eventRooms = { url: 'wss://host/ws', canalId: 'CANAL123', role: 'desktop' }

Emissor (PWA) Flow

import { fetchCanalConfiguration, buildEventRoomsConnection } from '@sofya-sdk/qr';
import { parseCanalFromQR, parseApiKeyFromQR } from '@sofya-sdk/qr';

const canalId = parseCanalFromQR(window.location.href);

const config = await fetchCanalConfiguration({
  canalId: canalId ?? '',
  baseUrl: 'https://api.your-backend.com',
});

const eventRooms = buildEventRoomsConnection(config.contract, 'mic');
// Connect using eventRooms.url + config.canalId

Emissor Flow with API Key from QR Code

import { fetchCanalConfiguration, buildEventRoomsConnection } from '@sofya-sdk/qr';
import { parseCanalFromQR, parseApiKeyFromQR } from '@sofya-sdk/qr';

// Extract both canal ID and API key from the QR code URL
// URL format: https://emissor.com/?x-api-key=123456&room_id=id
const canalId = parseCanalFromQR(window.location.href);
const apiKey = parseApiKeyFromQR(window.location.href);

const config = await fetchCanalConfiguration({
  canalId: canalId ?? '',
  baseUrl: 'https://api.your-backend.com',
  apiKey: apiKey ?? 'fallback-api-key', // Use extracted API key from QR
});

const eventRooms = buildEventRoomsConnection(config.contract, 'mic');
// Connect using eventRooms.url + config.canalId

Generate QR Code (Data URL)

import { generateQRCode } from '@sofya-sdk/qr';

const dataUrl = await generateQRCode('https://pwa.sofya.app?canal=123456', {
  width: 256,
  margin: 4,
  errorCorrectionLevel: 'M',
  color: {
    dark: '#000000',
    light: '#FFFFFF',
  },
});

// Use in img tag
<img src={dataUrl} alt="QR Code" />

Generate QR Code (SVG)

import { generateQRCodeSVG } from '@sofya-sdk/qr';

const svg = await generateQRCodeSVG('https://pwa.sofya.app?canal=123456');

Generate QR Code (Canvas)

import { generateQRCodeCanvas } from '@sofya-sdk/qr';

const canvas = document.getElementById('canvas') as HTMLCanvasElement;
await generateQRCodeCanvas('https://pwa.sofya.app?canal=123456', canvas);

Parse Canal from QR Code

import { parseCanalFromQR } from '@sofya-sdk/qr';

const canalId = parseCanalFromQR('https://pwa.sofya.app?room_id=123456');
// Returns: "123456"

Parse API Key from QR Code

import { parseApiKeyFromQR } from '@sofya-sdk/qr';

const apiKey = parseApiKeyFromQR('https://emissor.com/?x-api-key=secret-key&room_id=123456');
// Returns: "secret-key"

Parse Both Canal ID and API Key from QR Code

import { parseCanalFromQR, parseApiKeyFromQR } from '@sofya-sdk/qr';

const url = 'https://emissor.com/?x-api-key=secret-key&room_id=canal-123';

const canalId = parseCanalFromQR(url);
// Returns: "canal-123"

const apiKey = parseApiKeyFromQR(url);
// Returns: "secret-key"

Build PWA URL

import { buildPWAUrl } from '@sofya-sdk/qr';

const url = buildPWAUrl('https://pwa.sofya.app', '123456');
// Returns: "https://pwa.sofya.app?canal=123456"

API

generateQRCode(url, options?)

Generate QR code as a data URL (base64 PNG).

Returns: Promise<string>

generateQRCodeSVG(url, options?)

Generate QR code as SVG string.

Returns: Promise<string>

generateQRCodeCanvas(url, canvas, options?)

Generate QR code on a canvas element (browser only).

Returns: Promise<void>

parseCanalFromQR(url)

Extract canal ID from QR code URL.

Returns: string | null

parseApiKeyFromQR(url)

Extract API key from QR code URL.

Returns: string | null

buildPWAUrl(pwaBaseUrl, canalId)

Build PWA URL with canal parameter.

Returns: string

createCanalSession(options)

Create a canal through the backend contract and return normalized data (Receptor).

Returns: Promise<CreateCanalResponse>

fetchCanalConfiguration(options)

Fetch canal configuration from the backend contract (Emissor).

Returns: Promise<CanalConfig>

buildEventRoomsConnection(contract, role)

Derive EventRooms connection parameters (WebSocket URL, canalId, role) from the returned contract.

Returns: EventRoomsConnectionParams | null

getQrCodeUrlFromContract(contract)

Resolve the best URL encoded in the QR code (typically the PWA URL).

Returns: string | null

getQrCodeAssetLinkFromContract(contract)

Resolve the best QR code asset URL (PNG/SVG) from the contract.

Returns: string | null

Options

interface QRCodeOptions {
  errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'; // default: 'M'
  width?: number; // default: 256
  margin?: number; // default: 4
  color?: {
    dark?: string; // default: '#000000'
    light?: string; // default: '#FFFFFF'
  };
}

License

ISC