@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 +21 -0
- package/README.md +57 -0
- package/browser.d.ts +162 -0
- package/browser.mjs +607 -0
- package/engine/call-loop.mjs +71 -0
- package/engine/generation-keys.mjs +69 -0
- package/engine/media-lifecycle.mjs +188 -0
- package/index.d.ts +22 -0
- package/index.mjs +211 -0
- package/livekit.d.ts +59 -0
- package/livekit.mjs +343 -0
- package/package.json +64 -0
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;
|