@q9labsai/chalk-client 5.2.5 → 5.3.0

package/dist/media/plane.d.ts

@@ -1,3 +1,6 @@
+import type { operations } from "../generated/openapi-types";
+export type MediaConnectionReplacementCause = NonNullable<NonNullable<operations["addCloudflareSFUTracks"]["parameters"]["query"]>["replacement_cause"]>;
+export type LocalPublicationRetirementCause = Exclude<MediaConnectionReplacementCause, "local_signaling_failure" | "remote_signaling_failure" | "dormant_connection" | "access_refresh" | "receive_stalled">;
 export type ScreenShareSurface = "monitor" | "window" | "browser";
 export type ScreenShareOptions = {
     readonly surface?: ScreenShareSurface;
@@ -24,6 +27,7 @@ export type ConnectionMediaRemoteTrack = Pick<MediaPublication, "participantId"
     readonly track: MediaStreamTrack;
 };
 export type ConnectionMediaSnapshot = {
+    readonly receiveStalls?: readonly import("./receive-stall").ReceiveStallObservation[];
     readonly connection: {
         readonly phase: ConnectionMediaPhase;
         readonly peerConnectionState: RTCPeerConnectionState | null;
@@ -54,11 +58,13 @@ export type MediaPlaneResult = {
 };
 export type ClientMediaPlane = {
     readonly setLocalPublicationTarget: (target: MediaPlaneTarget) => Promise<MediaPlaneResult>;
-    readonly setLocalSourceIntent?: (source: MediaSource, enabled: boolean) => void;
-    readonly closeForcedLocalPublication?: (source: MediaSource) => Promise<void>;
+    readonly pauseLocalCapture?: (source: "microphone" | "camera") => Promise<void>;
+    readonly setLocalSourceIntent?: (source: MediaSource, enabled: boolean, cause?: LocalPublicationRetirementCause) => void;
+    readonly closeForcedLocalPublication?: (source: MediaSource, cause?: LocalPublicationRetirementCause) => Promise<void>;
     readonly observeLocalPublications: (listener: (publications: readonly MediaPublication[]) => void) => () => void;
     readonly observeRemotePublications: (listener: (publications: readonly MediaPublication[]) => void) => () => void;
-    readonly remotePublicationsChanged?: () => void;
+    /** Unavailable suspends receive eligibility without withdrawing publication identities. */
+    readonly remotePublicationsChanged?: (publications?: readonly MediaPublication[], projectionState?: "available" | "unavailable") => void;
     readonly remoteParticipantsChanged?: (participantIds: readonly string[]) => void;
     readonly remotePublicationResumed?: (publicationId: string) => void;
 };

package/dist/media/receive-stall.d.ts

@@ -0,0 +1,43 @@
+import type { MediaPublication } from "./plane";
+import type { CloudflareSFURemoteTrack } from "./types";
+export declare const RECEIVE_STALL_WINDOW_MS = 7000;
+export declare const RECEIVE_STARTUP_GRACE_MS = 20000;
+export type ReceivePacketSample = {
+    readonly publicationId: string;
+    readonly trackId: string;
+    readonly packets: number;
+};
+/** Only consecutive, timely observations of expected media establish a stall. */
+export declare class ReceiveStallDetector {
+    #private;
+    forget(publicationId: string): void;
+    clear(): void;
+    sample(now: number, tracks: readonly ReceivePacketSample[]): {
+        readonly stalled: readonly string[];
+        readonly advanced: readonly string[];
+        readonly resumed: readonly string[];
+    };
+}
+export type ReceiveStallObservation = {
+    readonly event: "receive_stalled";
+    readonly scope: "partial" | "all";
+    readonly observedAtMs: number;
+    readonly expectedTracks: number;
+    readonly stalledTracks: number;
+};
+/** Owns eligibility, pending stalls and the budget across replacement peers. */
+export declare class ReceiveStallRecovery {
+    #private;
+    get observations(): readonly ReceiveStallObservation[];
+    expect(publications: readonly MediaPublication[], participantId: string): void;
+    suspend(): void;
+    isStalled(publicationId: string): boolean;
+    canRebuild(): boolean;
+    reserveRebuild(): boolean;
+    clear(): void;
+    sample(now: number, connection: RTCPeerConnection, report: RTCStatsReport, tracks: Iterable<CloudflareSFURemoteTrack>): {
+        readonly stalled: readonly string[];
+        readonly advanced: readonly string[];
+        readonly newlyStalled: readonly string[];
+    };
+}

package/dist/media/types.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
-import type { MediaPublication, MediaPublicationSource } from "./plane";
+import type { MediaConnectionReplacementCause, MediaPublication, MediaPublicationSource } from "./plane";
 export type CloudflareSFUBootstrap = {
     readonly connectionId: string;
     readonly stunServer: string;
@@ -52,6 +52,7 @@ export type CloudflareSFUSignalingTransport = {
         readonly sessionDescription?: CloudflareSFUSessionDescription;
         readonly tracks: readonly CloudflareSFUTrackRequest[];
         readonly allowPartialRemoteTracks?: boolean;
+        readonly replacementCause?: MediaConnectionReplacementCause;
     }) => Promise<CloudflareSFUTracksResponse>;
     readonly closeTracks: (input: {
         readonly connectionId: string;
@@ -76,6 +77,8 @@ export type CloudflareSFUFailureCode = CloudflareSFUErrorCode;
 export type CloudflareSFUConnectionPhase = "idle" | "connecting" | "live" | "recovering" | "failed" | "stopped";
 export type CloudflareSFUPhase = CloudflareSFUConnectionPhase;
 export type CloudflareSFUSnapshot = {
+    /** Omitted by media adapters without receive diagnostics; treat as empty. */
+    readonly receiveStalls?: readonly import("./receive-stall").ReceiveStallObservation[];
     readonly connection: {
         readonly phase: CloudflareSFUConnectionPhase;
         readonly peerConnectionState: RTCPeerConnectionState | null;

package/dist/public-invites/index.js

@@ -2,12 +2,12 @@ import {
   createChalkPublicClient,
   createChalkPublicInviteClient,
   parseInviteCode
-} from "../chunk-LKNT6XFD.js";
+} from "../chunk-O26BHHMI.js";
 import {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,
   SpacePublicInviteUnavailableError
-} from "../chunk-UMAE5GCV.js";
+} from "../chunk-GOSWSXTH.js";
 export {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,

package/dist/server/index.cjs

@@ -602,6 +602,7 @@ function participantAdmissionRequest(input) {
     name: input.name,
     role: input.role,
     ...input.identityId === void 0 ? {} : { identity_id: input.identityId },
+    ...input.identityExternalId === void 0 ? {} : { identity_external_id: input.identityExternalId },
     ...input.metadata === void 0 ? {} : { metadata: input.metadata },
     ...input.participantId === void 0 ? {} : { participant_id: input.participantId }
   };

package/dist/server/index.js

@@ -504,6 +504,7 @@ function participantAdmissionRequest(input) {
     name: input.name,
     role: input.role,
     ...input.identityId === void 0 ? {} : { identity_id: input.identityId },
+    ...input.identityExternalId === void 0 ? {} : { identity_external_id: input.identityExternalId },
     ...input.metadata === void 0 ? {} : { metadata: input.metadata },
     ...input.participantId === void 0 ? {} : { participant_id: input.participantId }
   };

package/dist/server/types.d.cts

@@ -104,6 +104,8 @@ export type EpisodeEnd = {
     readonly status: string;
 };
 export type AdmitParticipantInput = {
+    /** Stable person key scoped to this tenant. Mutually exclusive with identityId. */
+    readonly identityExternalId?: string;
     readonly identityId?: string;
     readonly metadata?: unknown;
     readonly name: string;

package/dist/server/types.d.ts

@@ -104,6 +104,8 @@ export type EpisodeEnd = {
     readonly status: string;
 };
 export type AdmitParticipantInput = {
+    /** Stable person key scoped to this tenant. Mutually exclusive with identityId. */
+    readonly identityExternalId?: string;
     readonly identityId?: string;
     readonly metadata?: unknown;
     readonly name: string;

package/dist/space-client/promise-facade.d.ts

@@ -1,11 +1,11 @@
 import { Effect } from "effect";
-type ControllerCommand = (...args: any[]) => unknown;
-type PromiseRuntime = {
-    readonly runPromise: (effect: Effect.Effect<any, any, any>) => Promise<any>;
+type ControllerCommand = (...args: never[]) => unknown;
+type PromiseRuntime<Services> = {
+    readonly runPromise: (effect: Effect.Effect<unknown, unknown, Services>) => Promise<unknown>;
 };
-export type PromiseCommand<Command> = Command extends (...args: infer Arguments) => infer Result ? (Result extends Effect.Effect<infer Success, any, any> ? (...args: Arguments) => Promise<Success> : (...args: Arguments) => Result) : never;
+export type PromiseCommand<Command> = Command extends (...args: infer Arguments) => infer Result ? (Result extends Effect.Effect<infer Success, unknown, unknown> ? (...args: Arguments) => Promise<Success> : (...args: Arguments) => Result) : never;
 export type PromiseController<Controller extends Record<string, ControllerCommand>> = {
     readonly [Key in keyof Controller]: PromiseCommand<Controller[Key]>;
 };
-export declare function toPromiseController<Controller extends Record<string, ControllerCommand>>(runtime: PromiseRuntime, controller: Controller): PromiseController<Omit<Controller, "configure" | "dispose">>;
+export declare function toPromiseController<Services, Controller extends Record<string, ControllerCommand>>(runtime: PromiseRuntime<Services>, controller: Controller): PromiseController<Omit<Controller, "configure" | "dispose">>;
 export {};

package/dist/space-client/same-identity.d.ts

@@ -0,0 +1,6 @@
+import type { Participant } from "./types";
+import type { V1EpisodeSnapshot } from "../sync/v1-types";
+type PersonSeat = Pick<Participant, "participantId" | "identityId">;
+export declare function otherDevices<Seat extends PersonSeat>(participants: readonly Seat[], participantId: string | null, ownIdentityId?: string): readonly Seat[];
+export declare function otherDeviceHasMicrophone(snapshot: V1EpisodeSnapshot, participants: readonly PersonSeat[]): boolean;
+export {};

package/dist/space-client/types.d.ts

@@ -77,6 +77,8 @@ export type ConnectionSlice = {
 };
 export type SelfSlice = {
     readonly participantId: string | null;
+    /** Verified person association, including before this seat confirms entry. */
+    readonly identityId?: string;
     readonly displayName: string | null;
     readonly role: string | null;
     readonly capabilities: readonly Capability[];
@@ -89,6 +91,9 @@ export type ParticipantPresence = {
     readonly activeSpeaker: boolean;
 };
 export type Participant = {
+    /** Stable person identity, independent of the per-device participant ID. */
+    readonly identityId?: string;
+    readonly deviceType?: "phone" | "tablet" | "computer";
     readonly participantId: string;
     readonly displayName: string;
     readonly role: string;
@@ -128,6 +133,7 @@ export type RemoteMedia = {
 export type IncomingMediaRequest = ChalkIncomingMediaRequest;
 export type { ScreenShareSurface, ScreenShareOptions, ScreenShareCapture } from "../media/plane";
 export type MediaSlice = {
+    readonly microphoneMutedByOtherDevice?: boolean;
     readonly devices: {
         readonly microphones: readonly MediaDevice[];
         readonly cameras: readonly MediaDevice[];

package/dist/sync/index.js

@@ -22,7 +22,7 @@ import {
   encodeV1ClientFrame,
   optimisticV1Control,
   restoreV1Snapshot
-} from "../chunk-5YPQNMJE.js";
+} from "../chunk-XSB2GDRW.js";
 export {
   AsyncStorageV1PendingTargetStore,
   InMemoryV1PendingTargetStore,

package/dist/sync/v1-types.d.ts

@@ -52,6 +52,10 @@ export type V1ControlState = {
 };
 export type V1MediaPublication = MediaPublication;
 export type V1Presence = {
+    readonly admissionRevision?: number;
+    /** Stable person identity, independent of the per-device participant ID. */
+    readonly identityId?: string;
+    readonly deviceType?: "phone" | "tablet" | "computer";
     readonly participantId: string;
     readonly state: "connected" | "disconnected";
     readonly speaking: boolean;
@@ -86,6 +90,8 @@ export type V1EpisodeSnapshot = {
     };
     readonly participantId: string | null;
     readonly participantGeneration: number | null;
+    /** Verified own-seat identity, available before admission confirmation on negotiated servers. */
+    readonly participantIdentityId?: string;
     readonly control: V1ControlState | null;
     readonly optimisticControl: V1ControlState | null;
     readonly media: V1Projection<V1MediaPublication> | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q9labsai/chalk-client",
-  "version": "5.2.5",
+  "version": "5.3.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -221,6 +221,7 @@
     "test": "node ../../../scripts/test/run.mjs pnpm exec vitest run",
     "test:webhooks-package": "pnpm run build && node ./scripts/check-webhook-package.mjs",
     "test:server-package": "pnpm run build && node ./scripts/check-server-package.mjs",
+    "test:receive-stall-sfu": "node ./scripts/real-sfu-receive-stall.mjs",
     "test:sync-browser": "pnpm run build && node ./scripts/real-browser-sync.mjs",
     "test:sync-node-restart": "pnpm run build && node ./scripts/real-node-restart-sync.mjs",
     "check-types": "tsc-rs --project tsconfig.check-types.json --noEmit",