@wtfalch/calls 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 William Tallis Falch
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,57 @@
1
+ # @wtfalch/calls
2
+
3
+ Framework-independent Calls SDK, in two entries.
4
+
5
+ `@wtfalch/calls` is the control client: session admission, guest links, moderation and guest credential status/rotation.
6
+
7
+ ```js
8
+ import { createCallsClient } from '@wtfalch/calls';
9
+ const calls = createCallsClient({ baseUrl: 'https://calls.example' });
10
+ await calls.joinAdmission(sessionId, { video: false, requestId: crypto.randomUUID() });
11
+ ```
12
+
13
+ `waiting(sessionId)` lists the guests waiting in the lobby, oldest first, for a host who holds `calls.participants:admit`. `record(sessionId)` reads what happened in a call: when it started and ended, and when each participant was admitted and left. Anyone who was in the call can read it, and so can holders of `calls.records:read`. A guest's copy carries no member's `actorId`.
14
+
15
+ Member requests use same-origin cookies and exact-origin requests. Guest link redemption returns a handle whose opaque credential remains private to the handle. Errors are typed `CallsError`; requests are bounded and are never retried automatically.
16
+
17
+ `@wtfalch/calls/browser` is the media-ready call handle. `join()` returns a `CallHandle` with:
18
+
19
+ - `state()` and `subscribe()` — a snapshot now and again on every change. It carries `participants`, the roster as `{ participantId, self, displayName, actorId?, media? }`, so a changing roster needs no polling. `media` is `{ microphone, camera, screen, speaking, quality }`, present when the adapter reports it, and a subscriber hears it change.
20
+ - `publish('audio' | 'video' | 'screen')` and `stopShare()`.
21
+ - `setMicrophoneEnabled()` and `setMode()` — mute and camera without leaving the call.
22
+ - `attach(participantId, 'camera' | 'screen', videoElement)` draws that participant's video and returns its detach. Your own id gives a local preview.
23
+ - `devices()` and `useDevice(kind, deviceId)` — list and switch microphone, camera and speaker.
24
+ - `ready()` and `leave()`.
25
+
26
+ When the call ends, the last snapshot a subscriber hears has `ended: { reason }`: `left` (you called `leave()`), `admission_expired` (a guest was never let in), `control_refused` (joining failed) or `connection_unavailable` (the service stopped serving the call). The service does not yet say whether the host ended it, you were removed or your credential lapsed, so all three arrive as `connection_unavailable`.
27
+
28
+ The handle renders nothing itself. You inject the media adapter; `@wtfalch/calls/livekit` below is the shipped one. With an adapter that lacks `attach`, `devices` or `useDevice`, those methods throw an error with code `media_unsupported`.
29
+
30
+ `displayName` is untrusted text. A guest declares its own and the service bounds it by length only, so whatever draws it owns the escaping.
31
+
32
+ The handle also takes an endpoint store, so this entry touches no device and picks no storage itself. It needs the peer dependency `@matrix-org/matrix-sdk-crypto-wasm@18.8.0`, which is required rather than optional: `browser.mjs` imports the crypto machine statically, so importing this entry without the peer throws `ERR_MODULE_NOT_FOUND` before any of your code runs. It is a peer and not a dependency because the engine needs exactly one instance of it.
33
+
34
+ ## `@wtfalch/calls/livekit`
35
+
36
+ A real media adapter for `@wtfalch/calls/browser`, built on `livekit-client`. It owns devices, tracks and the LiveKit room; `createCallEndpoint` owns authority, keys and lifecycle. It needs the peer dependency `livekit-client@2.22.3`, and it is optional: only import this entry if you use it.
37
+
38
+ `livekit-client`'s E2EE worker is your file to serve, not this package's. Create it once and hand it in:
39
+
40
+ ```js
41
+ import { createLiveKitAdapter } from '@wtfalch/calls/livekit';
42
+ import { createCallEndpoint } from '@wtfalch/calls/browser';
43
+
44
+ const worker = new Worker(
45
+ new URL('livekit-client/dist/livekit-client.e2ee.worker.mjs', import.meta.url),
46
+ { type: 'module' },
47
+ );
48
+ const endpoint = createCallEndpoint({ adapter: createLiveKitAdapter({ worker }), store });
49
+ const call = await endpoint.join(/* ... */);
50
+ const detach = call.attach(participantId, 'camera', videoElement);
51
+ ```
52
+
53
+ The adapter never terminates that worker, so the same instance carries through every reconnect the engine drives. Terminate it yourself when you are done with the endpoint for good.
54
+
55
+ `attach()` throws an error with code `track_unavailable` when that source is not published and subscribed yet. Call it again once the participant's `media` shows the source on. Mute keeps the capture, so unmuting never asks for the microphone again. Remote audio plays on its own; there is nothing to attach for it.
56
+
57
+ For a test, pass `capture: { audio, video, screen }`, each a function returning a `MediaStreamTrack`, to publish synthetic media instead of opening real devices.
package/browser.d.ts ADDED
@@ -0,0 +1,162 @@
1
+ // @wtfalch/calls/browser — a media-ready endpoint. Media capture and endpoint
2
+ // storage are injected, so this entry touches no device and picks no storage.
3
+ export interface CallEndpointAdapter {
4
+ stopCapture(): void;
5
+ leave(): Promise<void>;
6
+ // onMediaChange fires whenever anything media() below would now report
7
+ // differently. A call from a connection this engine has since replaced is
8
+ // harmless -- the engine itself guards that, not the adapter.
9
+ connect(input: { url: string; token: string; keys: MediaKey[]; localIdentity: string; controlled: true; onUnsafe: () => void; onMediaChange: () => void }): Promise<{ encryption: boolean }>;
10
+ installKeys(entries: MediaKey[]): Promise<void>;
11
+ publishAudio(authority: { canPublish(): boolean }): Promise<void>;
12
+ publishVideo(authority: { canPublish(): boolean }): Promise<void>;
13
+ // A third publication, with its own track. onEnded fires when the browser's
14
+ // own UI ends the share, outside unpublishScreen() -- the one stop path
15
+ // this module does not own.
16
+ publishScreen(authority: { canPublish(): boolean }, onEnded: () => void): Promise<void>;
17
+ unpublishScreen(): Promise<void>;
18
+ // Local capture toggles, not a publish/unpublish: no renegotiation, no new
19
+ // lease. Mirrors the LiveKit local-participant methods of the same name.
20
+ setMicrophoneEnabled(enabled: boolean): Promise<void>;
21
+ setCameraEnabled(enabled: boolean): Promise<void>;
22
+ stats(): Promise<Record<string, unknown>>;
23
+ retainedToken(): string | null;
24
+ // Optional. An adapter that cannot encrypt media in this engine says so here,
25
+ // and createCallEndpoint refuses rather than failing once a call starts.
26
+ supported?(): boolean;
27
+ // Optional. Synchronous per-participant media state, keyed by LiveKit
28
+ // identity -- the local identity included. Everything below reads it
29
+ // through this one call rather than polling the adapter piecemeal, so an
30
+ // adapter that has nothing new to say just returns what it returned last.
31
+ media?(): Record<string, ParticipantMedia>;
32
+ // Optional. Draws identity's camera or screen track into element and
33
+ // returns a function that detaches it. The local identity gives a local
34
+ // preview.
35
+ attach?(identity: string, source: 'camera' | 'screen', element: HTMLVideoElement): () => void;
36
+ // Optional. The devices this adapter can offer right now.
37
+ devices?(): Promise<MediaDeviceOption[]>;
38
+ // Optional. Switches this adapter's capture to the given device.
39
+ useDevice?(kind: 'audioinput' | 'videoinput' | 'audiooutput', deviceId: string): Promise<void>;
40
+ }
41
+ export interface MediaKey { identity: string; key: string; index: number }
42
+ // One participant's media state as the adapter reports it. Present on
43
+ // Participant only when the adapter actually has an entry for that
44
+ // participant's userId -- an adapter without media() leaves Participant
45
+ // exactly as it was before media() existed.
46
+ export interface ParticipantMedia { microphone: boolean; camera: boolean; screen: boolean; speaking: boolean; quality: 'excellent' | 'good' | 'poor' | 'lost' | 'unknown' }
47
+ // One device an adapter can switch capture to.
48
+ export interface MediaDeviceOption { kind: 'audioinput' | 'videoinput' | 'audiooutput'; deviceId: string; label: string }
49
+ export interface EndpointIdentity { userId: string; deviceId: string }
50
+ export interface CallEndpointStore {
51
+ read(): Record<string, any>;
52
+ save(value: Record<string, any>): void;
53
+ open(rust: unknown, identity: EndpointIdentity): Promise<{ machine: unknown; deviceKeys: unknown; upload?: { id: string; type: unknown; body: unknown }; close(): void }>;
54
+ }
55
+ export interface CallEndpointOptions { adapter: CallEndpointAdapter; store: CallEndpointStore; fetchImpl?: typeof fetch; wasmUrl?: string }
56
+ // A stable identity per participant, not the userId, deviceId or key pins
57
+ // roster.peers carries for key delivery -- those are not what draws a tile.
58
+ // self marks the local endpoint's own entry. actorId is present on every
59
+ // entry or none, mirroring the service's own asymmetry: present only when
60
+ // this reader is a member. displayName is untrusted text. A guest declares
61
+ // its own, and the service bounds it by length only -- 1 to 80 characters, no
62
+ // charset check (packages/service/src/guest-links.mjs). Whatever draws it
63
+ // owns the escaping. media is the adapter's own media() entry for this
64
+ // participant's userId -- the roster the service returns carries no media
65
+ // state of its own -- present only when the adapter reports one, so an
66
+ // adapter without media() leaves this shape exactly as it was before media()
67
+ // existed.
68
+ export interface Participant { participantId: string; self: boolean; displayName: string | null; actorId?: string; media?: ParticipantMedia }
69
+ // Why this endpoint's call is over. null while it is not.
70
+ export interface CallEnded {
71
+ reason:
72
+ // The application called leave().
73
+ | 'left'
74
+ // A guest's wait for admission ended without being admitted, whether the
75
+ // wait simply timed out or the service stopped honouring the redemption.
76
+ | 'admission_expired'
77
+ // A terminal control-plane refusal reached join() before a call was ever
78
+ // established -- any refusal join() does not retry, including one that
79
+ // outlived its provisioning wait.
80
+ | 'control_refused'
81
+ // That same refusal reaching an endpoint whose call was already running:
82
+ // the service's one code for "this endpoint's binding no longer holds,"
83
+ // covering the host ending the session, this participant being removed,
84
+ // and an admission or credential expiring or being revoked alike, since
85
+ // the service reports none of those more specifically.
86
+ | 'connection_unavailable';
87
+ }
88
+ export interface CallStats { lifecycle: 'paused' | 'connecting' | 'ready'; microphoneEnabled: boolean; cameraEnabled: boolean; screenSharing: boolean; senderIndex?: number; peers: number; keyedPeers: number; participants: Participant[]; gatewayExpiresAt: number; controlExpiresAt: number; awaitingKeys: number | null; ended: CallEnded | null }
89
+ export interface CallHandle {
90
+ state(): Promise<CallStats>;
91
+ // Delivers a snapshot at once, and again whenever the call's own state
92
+ // moves: lifecycle, roster, keys, local capture, share, credential expiry
93
+ // and ended. The adapter's transport numbers are not watched, because
94
+ // nothing tells the engine they changed -- poll state() for those. Rapid
95
+ // changes coalesce into one delivery of the newest snapshot, so a
96
+ // subscriber sees current state rather than every state on the way.
97
+ // leave() delivers one final snapshot with ended set before it stops this
98
+ // subscription, whether or not the returned function was called.
99
+ subscribe(fn: (snapshot: CallStats) => void): () => void;
100
+ // 'screen' adds a share track the same way 'audio' and 'video' add theirs.
101
+ // stopShare() is its stop, because starting and stopping is not something
102
+ // the other two modes do. Starting a share that is already live does
103
+ // nothing, rather than asking the browser for a second one.
104
+ //
105
+ // A share does not survive a reconnect, and a mute does. The engine pauses
106
+ // media by itself on every roster and generation change, which releases the
107
+ // display capture; the browser only grants another to a user gesture, and
108
+ // this has none. So screenSharing goes false and the next snapshot says so.
109
+ // Watch it, and offer to share again rather than assuming it held.
110
+ publish(mode: 'audio' | 'video' | 'screen'): Promise<void>;
111
+ stopShare(): Promise<void>;
112
+ // Mute/unmute the microphone and turn the camera on/off. Both are local
113
+ // capture decisions: no reconnect, no key rotation, no new lease.
114
+ setMicrophoneEnabled(enabled: boolean): Promise<void>;
115
+ setMode(mode: 'audio' | 'video'): Promise<void>;
116
+ renewKey(): void;
117
+ // The UI speaks participant ids, never LiveKit identities: attach() maps
118
+ // participantId to the roster peer's userId before reaching the adapter.
119
+ // An id no current peer carries is refused. A missing adapter hook throws
120
+ // media_unsupported, on attach, devices and useDevice alike.
121
+ attach(participantId: string, source: 'camera' | 'screen', element: HTMLVideoElement): () => void;
122
+ devices(): Promise<MediaDeviceOption[]>;
123
+ useDevice(kind: 'audioinput' | 'videoinput' | 'audiooutput', deviceId: string): Promise<void>;
124
+ ready(ms?: number): Promise<true>;
125
+ leave(): Promise<void>;
126
+ }
127
+ export interface CallEndpoint {
128
+ join(input?: { sessionId?: string; guest?: { secret: string; displayName: string }; mode?: 'audio' | 'video'; maxLeaseMs?: number; readyMs?: number; admissionMs?: number; provisioningMs?: number }): Promise<CallHandle>;
129
+ redeem(value: { secret: string; displayName: string }): Promise<{ sessionId: string; admissionId: string; expiresAt: number; state: 'waiting' | 'admitted' }>;
130
+ awaitAdmission(ms?: number): Promise<{ sessionId: string; admissionId: string; state: 'admitted'; expiresAt: number }>;
131
+ bootstrap(value?: { sessionId: string }): Promise<EndpointIdentity & { bootstrapId: string; expiresAt: number }>;
132
+ configure(): Promise<void>;
133
+ discover(): Promise<void>;
134
+ connect(input?: { mode?: 'audio' | 'video'; maxLeaseMs?: number }): Promise<void>;
135
+ connectWhenReady(input?: { mode?: 'audio' | 'video'; maxLeaseMs?: number }): void;
136
+ whenReady(ms?: number): Promise<true>;
137
+ publish(mode: 'audio' | 'video' | 'screen'): Promise<void>;
138
+ stopShare(): Promise<void>;
139
+ setMicrophoneEnabled(enabled: boolean): Promise<void>;
140
+ setMode(mode: 'audio' | 'video'): Promise<void>;
141
+ renewKey(): void;
142
+ attach(participantId: string, source: 'camera' | 'screen', element: HTMLVideoElement): () => void;
143
+ devices(): Promise<MediaDeviceOption[]>;
144
+ useDevice(kind: 'audioinput' | 'videoinput' | 'audiooutput', deviceId: string): Promise<void>;
145
+ rejoin(): void;
146
+ renewCredentials(): Promise<void>;
147
+ stats(): Promise<CallStats>;
148
+ // As on CallHandle, except that this subscription belongs to the endpoint:
149
+ // it survives leave() and sees the next join() too. The returned function
150
+ // is the only thing that stops it.
151
+ subscribe(fn: (snapshot: CallStats) => void): () => void;
152
+ // pause() keeps credential renewal, because a paused endpoint means to come
153
+ // back. leave() ends it.
154
+ pause(): Promise<void>;
155
+ pauseMedia(): Promise<void>;
156
+ leave(): Promise<void>;
157
+ }
158
+ export type MissingCapability = 'secure_context' | 'crypto_random_uuid' | 'crypto_random_values' | 'web_crypto' | 'webassembly' | 'structured_clone' | 'base64' | 'abort_timeout';
159
+ // What this module needs from its engine. Capture and storage are injected, so
160
+ // an adapter declares its own support through the optional supported() below.
161
+ export function environmentSupport(scope?: unknown): MissingCapability[];
162
+ export function createCallEndpoint(options: CallEndpointOptions): CallEndpoint;