@qencode/calls 0.2.0

package/dist/regions.d.ts

@@ -0,0 +1,22 @@
+import type { Region } from './credential';
+export interface RegionChoice {
+    region: Region;
+    /** Probe result per region name in milliseconds; Infinity when unreachable. Empty when no probe ran. */
+    probe: Record<string, number>;
+    /** How the choice was made. */
+    how: 'single' | 'pinned' | 'probe' | 'fallback';
+}
+export interface ProbeOptions {
+    timeoutMs?: number;
+    fetchFn?: typeof fetch;
+    now?: () => number;
+}
+/** Turns a signaling URL into the media node's HTTPS root, which LiveKit answers with "OK". */
+export declare function probeUrl(signalingUrl: string): string;
+/**
+ * Times one request to a region after one warm-up request. `no-cors` so the timing works even
+ * when the node sends no CORS headers; the body is not readable and does not need to be.
+ */
+export declare function probeRegion(region: Region, opts?: ProbeOptions): Promise<number>;
+/** Picks the region to connect through. Pinned wins; one region skips the probe; otherwise the fastest probe. */
+export declare function chooseRegion(regions: Region[], pinned?: string | null, opts?: ProbeOptions): Promise<RegionChoice>;

package/dist/render.d.ts

@@ -0,0 +1,35 @@
+/** A renderable track. `attach` returns the element for chaining; `detach` with no element releases all. */
+export interface VideoHandle {
+    readonly kind: 'video' | 'audio';
+    readonly mediaStreamTrack: MediaStreamTrack;
+    /** Accepts a `<video>`/`<audio>` element or a `<qencode-video>` element; returns the media element that plays it. */
+    attach(element: HTMLMediaElement | QencodeVideoElement): HTMLMediaElement;
+    detach(element?: HTMLMediaElement | QencodeVideoElement): void;
+}
+type EngineTrack = {
+    kind: string;
+    mediaStreamTrack: MediaStreamTrack;
+    attach(element: HTMLMediaElement): HTMLMediaElement;
+    detach(element?: HTMLMediaElement): HTMLMediaElement | HTMLMediaElement[];
+};
+/** @internal Wraps an engine track so no engine type reaches the public API. */
+export declare function wrapTrack(track: EngineTrack): VideoHandle;
+/**
+ * `<qencode-video>`: a frame that renders a VideoHandle at its own aspect ratio.
+ * Attributes: `mirror` (self view), `fit="contain|cover"`. Property: `track` (VideoHandle | null).
+ * Audio is never played by this element; the SDK plays remote audio itself.
+ */
+export declare class QencodeVideoElement extends HTMLElement {
+    private _track;
+    private readonly video;
+    constructor();
+    /** The inner `<video>` that plays the track. */
+    get videoElement(): HTMLVideoElement;
+    get track(): VideoHandle | null;
+    set track(t: VideoHandle | null);
+    disconnectedCallback(): void;
+    private updateAspect;
+}
+/** Registers `<qencode-video>` once; safe to call repeatedly and outside browsers. */
+export declare function registerVideoElement(tag?: string): boolean;
+export {};

package/dist/stats.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Per-second quality numbers from WebRTC getStats, ported from the bench page. Everything here is
+ * pure over an RTCStatsReport-like map so it can be tested without a browser.
+ */
+export type Transport = 'udp' | 'tcp' | 'relay-udp' | 'relay-tcp';
+export type CandidateType = 'host' | 'srflx' | 'prflx' | 'relay';
+export type AudioRoute = 'speaker' | 'earpiece' | 'wired' | 'bluetooth' | 'unknown';
+export type Quality = 'good' | 'fair' | 'poor';
+export type Direction = 'recv' | 'send';
+/** What this participant receives from the peer. */
+export interface RecvStats {
+    rttMs: number | null;
+    jitterBufferMs: number | null;
+    decodeMs: number | null;
+    fps: number | null;
+    width: number | null;
+    height: number | null;
+    kbps: number | null;
+    lossPct: number | null;
+    jitterMs: number | null;
+    freezes: number | null;
+    freezeMs: number | null;
+    /** Receive-to-render time per frame: Δ`totalProcessingDelay` / Δ`framesDecoded`. */
+    processingMs: number | null;
+    /**
+     * Sender capture to local now through the abs-capture-time header extension, when the
+     * browser and the media node carry it (Chromium; null elsewhere). A cross-check for the
+     * estimate, not a substitute for a measured glass-to-glass number.
+     */
+    absCaptureLatencyMs: number | null;
+    codec: string | null;
+    transport: Transport | null;
+    candidateType: CandidateType | null;
+}
+/** What this participant sends. */
+export interface SendStats {
+    rttMs: number | null;
+    encodeMs: number | null;
+    fps: number | null;
+    width: number | null;
+    height: number | null;
+    kbps: number | null;
+    /** The encoder's current bitrate target, kbps. */
+    targetKbps: number | null;
+    qualityLimitation: string | null;
+    /** Loss the media node reports for our outbound stream (remote-inbound-rtp), percent. */
+    lossPct: number | null;
+    codec: string | null;
+    transport: Transport | null;
+    candidateType: CandidateType | null;
+}
+/** One snapshot, emitted once per second on `stats`. */
+export interface CallStats {
+    /** Epoch milliseconds. */
+    ts: number;
+    recv: RecvStats;
+    send: SendStats;
+    /** The peer's own RTT to the media node, exchanged over the data channel; null until received. */
+    peerRttMs: number | null;
+    /** rtt/2 + peerRtt/2 + jitter buffer + decode + one frame interval. An estimate, not a measurement. */
+    estimatedLatencyMs: number | null;
+    quality: {
+        recv: Quality;
+        send: Quality;
+    };
+    region: string | null;
+    nodeId: string | null;
+    serverVersion: string | null;
+    joinMs: number | null;
+    audioRoute: AudioRoute;
+}
+type StatsLike = {
+    forEach(cb: (s: any) => void): void;
+    get(id: string): any;
+};
+/** Delta tracker across polls; one instance per direction per call. */
+export declare class DeltaTracker {
+    private prev;
+    /** Returns per-interval deltas of the given counters, or null on the first sample. */
+    step(nowMs: number, counters: Record<string, number | undefined>): {
+        dt: number;
+        d: (k: string) => number;
+    } | null;
+    reset(): void;
+}
+export declare function pickSelectedPair(report: StatsLike): any | null;
+export declare function transportOf(report: StatsLike, pair: any | null): {
+    transport: Transport | null;
+    candidateType: CandidateType | null;
+    rttMs: number | null;
+};
+export declare function collectRecv(report: StatsLike, tracker: DeltaTracker, nowMs: number): RecvStats;
+export declare function collectSend(report: StatsLike, tracker: DeltaTracker, nowMs: number): SendStats;
+type SyncSource = {
+    timestamp: number;
+    captureTimestamp?: number;
+    senderCaptureTimeOffset?: number;
+};
+/**
+ * Latency from the sender's capture clock to now, from `RTCRtpReceiver.getSynchronizationSources()`
+ * when the abs-capture-time extension is present. `captureTimestamp` and `senderCaptureTimeOffset`
+ * are milliseconds since the NTP epoch on the sender's clock (already offset-corrected by the
+ * browser); `timestamp` is when the last frame reached the track, relative either to the epoch
+ * (spec) or to the page's time origin (some builds), so both are accepted. Null when absent.
+ */
+export declare function absCaptureLatency(sources: ArrayLike<SyncSource> | null | undefined, unixNowMs: number, perfNowMs: number): number | null;
+/** rtt/2 + peerRtt/2 + jitter buffer + decode + one frame interval. Null until the pieces exist. */
+export declare function estimateLatency(p: {
+    rttMs: number | null;
+    peerRttMs: number | null;
+    jitterBufferMs: number | null;
+    decodeMs: number | null;
+    fps: number | null;
+}): number | null;
+/**
+ * good / fair / poor with hysteresis: a new level must be observed on two consecutive polls
+ * before it is reported, so a single bad second does not flip the indicator.
+ *
+ * poor: loss > 3 % or jitter buffer > 200 ms or any freeze in the interval
+ * fair: loss > 1 % or jitter buffer > 120 ms or rtt > 300 ms
+ * good: otherwise
+ */
+export declare class QualityTracker {
+    private current;
+    private candidate;
+    private streak;
+    static classify(s: {
+        lossPct: number | null;
+        jitterBufferMs: number | null;
+        freezes: number | null;
+        rttMs: number | null;
+    }): Quality;
+    /** Feed one poll; returns the reported level after hysteresis. */
+    update(s: {
+        lossPct: number | null;
+        jitterBufferMs: number | null;
+        freezes: number | null;
+        rttMs: number | null;
+    }): Quality;
+    get value(): Quality;
+    reset(): void;
+}
+export {};

package/dist/telemetry.d.ts

@@ -0,0 +1,73 @@
+import type { CallStats, Direction } from './stats';
+/** App-supplied fields for one telemetry row; see `Telemetry.push`. */
+export type TelemetryFields = Record<string, unknown>;
+/** Contract columns an app may fill: its own measured glass-to-glass latency over the last window. */
+export declare const MEASURED_COLUMNS: ReadonlySet<string>;
+/** One row of the calls stats contract (`POST /v1/calls/{id}/stats`). */
+export interface TelemetrySample {
+    ts: number;
+    direction: Direction;
+    peer_identity?: string | null;
+    /** App-measured glass-to-glass latency, ms, over the app's own window; the SDK never fills these. */
+    g2g_p50?: number | null;
+    g2g_p95?: number | null;
+    g2g_samples?: number | null;
+    rtt_ms?: number | null;
+    net_one_way_ms?: number | null;
+    jb_ms?: number | null;
+    decode_ms?: number | null;
+    encode_ms?: number | null;
+    fps?: number | null;
+    kbps?: number | null;
+    loss_pct?: number | null;
+    jitter_ms?: number | null;
+    freezes?: number | null;
+    freeze_ms?: number | null;
+    transport?: string | null;
+    candidate_type?: string | null;
+    codec?: string | null;
+    width?: number | null;
+    height?: number | null;
+    server_region?: string | null;
+    server_version?: string | null;
+    node_id?: string | null;
+    join_ms?: number | null;
+    extra?: Record<string, unknown>;
+}
+export interface TelemetryOptions {
+    apiBase: string;
+    callId: string | null;
+    token: string;
+    enabled: boolean;
+    sdkVersion: string;
+    /** Flush interval in ms; 5000 by default. */
+    intervalMs?: number;
+    fetchFn?: typeof fetch;
+    userAgent?: string;
+}
+/**
+ * Batches stats snapshots and posts them every 5 s with the participant token. Silent when
+ * disabled or when the credential carries no call id (manual credentials). Never throws.
+ */
+export declare class Telemetry {
+    private readonly opts;
+    private queue;
+    private timer;
+    private firstPost;
+    private joinMs;
+    readonly enabled: boolean;
+    readonly url: string | null;
+    constructor(opts: TelemetryOptions);
+    start(joinMs: number | null): void;
+    /**
+     * Converts one snapshot into the two contract rows and queues them. `extra` adds app fields per
+     * direction: the measured-latency columns (`MEASURED_COLUMNS`) are stored as columns, anything
+     * else goes under `extra` next to the SDK's own keys, which win on a name clash.
+     */
+    push(s: CallStats, peerIdentity: string | null, extra?: {
+        recv?: TelemetryFields | null;
+        send?: TelemetryFields | null;
+    }): void;
+    flush(): Promise<void>;
+    stop(): Promise<void>;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** SDK version, reported in telemetry as `extra.sdk`. Kept in sync with package.json by the build. */
+export declare const SDK_VERSION = "0.2.0";

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@qencode/calls",
+  "version": "0.2.0",
+  "description": "Qencode Calls web SDK: low-latency 1:1 audio and video calls inside your own UI.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/qencode-calls.umd.js",
+  "module": "./dist/qencode-calls.esm.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/qencode-calls.esm.js",
+      "require": "./dist/qencode-calls.umd.js",
+      "default": "./dist/qencode-calls.esm.js"
+    },
+    "./bundle": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/qencode-calls.esm.bundle.js",
+      "default": "./dist/qencode-calls.esm.bundle.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": [
+    "./dist/qencode-calls.umd.js"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "build:esm": "esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2020 --external:livekit-client --outfile=dist/qencode-calls.esm.js --sourcemap --minify",
+    "build:umd": "esbuild src/index.ts --bundle --format=iife --global-name=QencodeCalls --platform=browser --target=es2020 --outfile=dist/qencode-calls.umd.js --sourcemap --minify",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build": "npm run typecheck && npm run build:esm && npm run build:esm-bundle && npm run build:umd && npm run build:types",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:esm-bundle": "esbuild src/index.ts --bundle --format=esm --platform=browser --target=es2020 --outfile=dist/qencode-calls.esm.bundle.js --sourcemap --minify"
+  },
+  "dependencies": {
+    "livekit-client": "2.22.2"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "jsdom": "^25.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Qencode-Corp/calls-sdk.git",
+    "directory": "web"
+  },
+  "homepage": "https://github.com/Qencode-Corp/calls-sdk#readme",
+  "bugs": {
+    "url": "https://github.com/Qencode-Corp/calls-sdk/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "qencode",
+    "webrtc",
+    "video-calls",
+    "calls",
+    "sdk",
+    "livekit"
+  ]
+}