@wtfalch/calls 0.1.0 → 0.2.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/README.md CHANGED
@@ -23,7 +23,7 @@ Member requests use same-origin cookies and exact-origin requests. Guest link re
23
23
  - `devices()` and `useDevice(kind, deviceId)` — list and switch microphone, camera and speaker.
24
24
  - `ready()` and `leave()`.
25
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`.
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), `session_ended` (the host ended it, or its window closed), `participant_removed` (a moderator removed you) or `admission_lapsed` (your own admission or credential expired, or lost eligibility). `connection_unavailable` remains for the cases the service still cannot tell apart: a race with a sweep that has not run yet, or a still-admitted row whose binding/media credential alone lapsed.
27
27
 
28
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
29
 
package/browser.d.ts CHANGED
@@ -78,12 +78,19 @@ export interface CallEnded {
78
78
  // established -- any refusal join() does not retry, including one that
79
79
  // outlived its provisioning wait.
80
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';
81
+ // That same refusal reaching an endpoint whose call was already running,
82
+ // where the service cannot say more -- a race with a sweep that has not
83
+ // yet run, a still-admitted row whose binding/media credential alone
84
+ // lapsed, or a mismatch that was never really this caller's call.
85
+ | 'connection_unavailable'
86
+ // The host ended the session, or its own validity window simply closed.
87
+ | 'session_ended'
88
+ // A moderator removed this participant specifically, with remove().
89
+ | 'participant_removed'
90
+ // This participant's own admission or credential expired, or it lost
91
+ // eligibility (a revoked grant, a suspended namespace, a logged-out
92
+ // source session), without the wider session ending.
93
+ | 'admission_lapsed';
87
94
  }
88
95
  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
96
  export interface CallHandle {
package/browser.mjs CHANGED
@@ -70,12 +70,16 @@ export function createCallEndpoint({ adapter, store, fetchImpl = (...input) => f
70
70
  // calling leave(). 'admission_expired' is a guest whose wait for admission
71
71
  // never resolved. 'control_refused' is a terminal control-plane refusal
72
72
  // reaching join() before a call was ever established. 'connection_unavailable'
73
- // is that same refusal reaching an endpoint whose call was already
74
- // running -- the service's one code for "this endpoint's binding no longer
75
- // holds" (control.mjs), covering the host ending the session, this
76
- // participant being removed, and an admission or credential expiring or
77
- // being revoked alike, because control.mjs never reports which one.
78
- // join() clears it at the start of every attempt.
73
+ // is that same refusal reaching an endpoint whose call was already running,
74
+ // and control.mjs cannot say more -- a race with a sweep that has not yet
75
+ // run, a still-admitted row whose binding/media credential alone lapsed, or
76
+ // a mismatch that is not really this caller's call to begin with.
77
+ // 'session_ended', 'participant_removed' and 'admission_lapsed' are that
78
+ // same refusal where the service could say which: the host ending the
79
+ // session, this participant being removed, or this participant's own
80
+ // admission or credential expiring or losing eligibility (Sessions.endReason,
81
+ // packages/service/src/sessions.mjs). join() clears it at the start of
82
+ // every attempt.
79
83
  let endedCause = null;
80
84
  // Every subscriber the application has registered, and the fingerprint of
81
85
  // the last snapshot they were told about. notify() below is the only
@@ -395,8 +399,15 @@ export function createCallEndpoint({ adapter, store, fetchImpl = (...input) => f
395
399
  // this endpoint holds has passed its expiry is it permanent: each has
396
400
  // had its own renewal window (rotateCredentials) and none came back.
397
401
  // A member has no control expiry (it stays 0), so the gateway
398
- // credential's is the one that counts for it.
399
- if (error.code === 'connection_unavailable' && !endedCause && Date.now() >= Math.max(controlExpiresAt, gatewayExpiresAt)) { endedCause = { reason: 'connection_unavailable' }; await notify(); }
402
+ // credential's is the one that counts for it. session_ended,
403
+ // participant_removed and admission_lapsed are the same terminal
404
+ // refusal as connection_unavailable, with a cause attached; a call
405
+ // already under way never gets these until it is genuinely over, so
406
+ // they need no expiry wait of their own.
407
+ const terminal = ['connection_unavailable', 'session_ended', 'participant_removed', 'admission_lapsed'];
408
+ if (terminal.includes(error.code) && !endedCause) {
409
+ if (error.code !== 'connection_unavailable' || Date.now() >= Math.max(controlExpiresAt, gatewayExpiresAt)) { endedCause = { reason: error.code }; await notify(); }
410
+ }
400
411
  throw error;
401
412
  }
402
413
  try {
package/index.d.ts CHANGED
@@ -11,6 +11,12 @@ export interface CallsClient {
11
11
  waiting(sessionId: string): Promise<{ waiting: { admissionId: string; displayName: string | null; waitingSince: number }[] }>;
12
12
  record(sessionId: string): Promise<{ sessionId: string; startedAt: number; endedAt: number | null; participants: { admissionId: string; kind: 'member' | 'guest'; actorId?: string; displayName: string | null; admittedAt: number; departedAt: number | null }[] }>;
13
13
  removeParticipant(sessionId: string, input: { admissionId: string; requestId: string }): Promise<OperationResult & { admissionId: string }>;
14
+ // A one-shot server mute of that participant's microphone publication; they
15
+ // can unmute themselves again afterward, and there is no server unmute.
16
+ muteParticipant(sessionId: string, input: { admissionId: string; requestId: string }): Promise<OperationResult & { admissionId: string }>;
17
+ // Mutes every other currently-published microphone, excluding the caller's
18
+ // own admission if it has one. admissionIds lists who was actually muted.
19
+ muteAllParticipants(sessionId: string, input: { requestId: string }): Promise<OperationResult & { admissionIds: string[] }>;
14
20
  leave(sessionId: string, input: { requestId: string }): Promise<OperationResult & { admissionId: string }>;
15
21
  decline(sessionId: string, input: { reason: string; requestId: string }): Promise<OperationResult & { sessionId: string }>;
16
22
  endSession(sessionId: string, input: { requestId: string }): Promise<OperationResult & { sessionId: string }>;
package/index.mjs CHANGED
@@ -36,6 +36,11 @@ function guestResult(value, expectedSession, expectedAdmission, requireCredentia
36
36
  if (requireCredential && (typeof value.credential !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(value.credential))) throw new CallsError('invalid_response');
37
37
  return { sessionId: value.sessionId, admissionId: value.admissionId, expiresAt: value.expiresAt, ...(requireState ? { state: value.state } : {}), ...(requireCredential ? { credential: value.credential } : {}) };
38
38
  }
39
+ function muteAllResult(value) {
40
+ value = object(value); responseId(value.operationId); enforcement(value.enforcement);
41
+ if (!Array.isArray(value.admissionIds) || !value.admissionIds.every(a => typeof a === 'string' && ID.test(a))) throw new CallsError('invalid_response');
42
+ return { operationId: value.operationId, admissionIds: value.admissionIds, enforcement: value.enforcement };
43
+ }
39
44
  function roomStatusResult(value) {
40
45
  value = object(value);
41
46
  if (typeof value.live !== 'boolean') throw new CallsError('invalid_response');
@@ -162,6 +167,12 @@ export function createCallsClient(options) {
162
167
  removeParticipant(sessionId, { admissionId, requestId: rid } = {}) {
163
168
  return run(sessionPath(sessionId, 'remove'), { admissionId: id(admissionId, 'admissionId'), requestId: requestId(rid) }).then(v => operationResult(v, ['admissionId']));
164
169
  },
170
+ muteParticipant(sessionId, { admissionId, requestId: rid } = {}) {
171
+ return run(sessionPath(sessionId, 'mute'), { admissionId: id(admissionId, 'admissionId'), requestId: requestId(rid) }).then(v => operationResult(v, ['admissionId']));
172
+ },
173
+ muteAllParticipants(sessionId, { requestId: rid } = {}) {
174
+ return run(sessionPath(sessionId, 'mute-all'), { requestId: requestId(rid) }).then(v => muteAllResult(v));
175
+ },
165
176
  leave(sessionId, { requestId: rid } = {}) {
166
177
  return run(sessionPath(sessionId, 'leave'), { requestId: requestId(rid) }).then(v => operationResult(v, ['admissionId']));
167
178
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wtfalch/calls",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Framework-independent SDK for Agora calls: session control (admission, guest links, moderation) and a media-ready browser call handle.",
5
5
  "license": "MIT",
6
6
  "type": "module",