@q9labsai/chalk-client 5.2.3 → 5.2.5

package/dist/index.js

@@ -15,7 +15,7 @@ import {
   createSpaceClient,
   decodeWhiteboardV1ServerFrame,
   encodeWhiteboardV1ClientFrame
-} from "./chunk-4ZUN55Z2.js";
+} from "./chunk-BUNSEDXL.js";
 import {
   CloudflareSFUClient,
   CloudflareSFUError,
@@ -28,19 +28,19 @@ import {
   requireSFUDescription,
   validatePublicationSnapshot,
   waitFor
-} from "./chunk-DWKTGBHR.js";
+} from "./chunk-FD25AMLG.js";
 import {
   createChalkPublicClient,
   createChalkPublicInviteClient,
   parseInviteCode
-} from "./chunk-6LNRDKJF.js";
+} from "./chunk-LKNT6XFD.js";
 import {
   ArrivalInvalidHandleError,
   ArrivalUnavailableError,
   SpacePublicInviteUnavailableError,
   parseParsedAccessGrant,
   requireAccessGrant
-} from "./chunk-GA3JDPFI.js";
+} from "./chunk-UMAE5GCV.js";
 import {
   AsyncStorageV1PendingTargetStore,
   InMemoryV1PendingTargetStore,
@@ -69,7 +69,7 @@ import {
   optimisticV1Control,
   reactionFromFrame,
   restoreV1Snapshot
-} from "./chunk-IMMT22US.js";
+} from "./chunk-5YPQNMJE.js";
 
 // src/space-client/reload-rejoin.ts
 import { Schema } from "effect";

package/dist/media/client.d.ts

@@ -15,7 +15,7 @@ export declare class CloudflareSFUClient implements ClientMediaPlane {
     start(localMedia: MediaStream): Promise<void>;
     refreshRemotePublications(): Promise<void>;
     setLocalPublicationTarget(target: MediaPlaneTarget): Promise<MediaPlaneResult>;
-    setLocalSourceIntent(source: MediaPublicationSource, enabled: boolean): void;
+    setLocalSourceIntent(source: MediaPublicationSource, enabled: boolean): Promise<void>;
     closeForcedLocalPublication(source: MediaPublicationSource): Promise<void>;
     observeLocalPublications(listener: (publications: readonly MediaPublication[]) => void): () => void;
     observeRemotePublications(listener: (publications: readonly MediaPublication[]) => void): () => void;

package/dist/media/failure-diagnostics.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectionReport } from "../transport-diagnostics";
+type ReportEvent = ConnectionReport["events"][number];
+export type MediaFailureDiagnostic = Required<Pick<ReportEvent, "media_error_kind" | "media_error_step">> & Pick<ReportEvent, "http_status">;
+export type GrantedMedia = Required<Pick<ReportEvent, "granted_audio" | "granted_video">>;
+type MediaFailureStep = NonNullable<ReportEvent["media_error_step"]>;
+export declare function grantedMediaFromStream(stream: MediaStream): GrantedMedia;
+export declare function markMediaFetchFailure(error: unknown): void;
+export declare function markMediaFailure(error: unknown, step: MediaFailureStep): void;
+export declare function classifyMediaFailure(cause: unknown, fallbackStep: MediaFailureStep): MediaFailureDiagnostic;
+export {};

package/dist/media/index.js

@@ -10,7 +10,7 @@ import {
   requireSFUDescription,
   validatePublicationSnapshot,
   waitFor
-} from "../chunk-DWKTGBHR.js";
+} from "../chunk-FD25AMLG.js";
 export {
   CloudflareSFUClient,
   CloudflareSFUError,

package/dist/media/plane.d.ts

@@ -38,6 +38,7 @@ export type ConnectionMediaSnapshot = {
     readonly failure: {
         readonly code: string;
         readonly recoverable: boolean;
+        readonly diagnostic?: import("./failure-diagnostics").MediaFailureDiagnostic;
     } | null;
 };
 export type MediaPlaneOutcome = "confirmed" | "satisfied" | "retryable_failure" | "terminal_failure" | "ambiguous";

package/dist/media/types.d.ts

@@ -1,3 +1,4 @@
+import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
 import type { MediaPublication, MediaPublicationSource } from "./plane";
 export type CloudflareSFUBootstrap = {
     readonly connectionId: string;
@@ -89,6 +90,7 @@ export type CloudflareSFUSnapshot = {
     readonly failure: {
         readonly code: CloudflareSFUFailureCode;
         readonly recoverable: boolean;
+        readonly diagnostic?: import("./failure-diagnostics").MediaFailureDiagnostic;
     } | null;
 };
 export type CloudflareSFUClientOptions = {
@@ -97,7 +99,7 @@ export type CloudflareSFUClientOptions = {
     readonly transport: CloudflareSFUSignalingTransport;
     readonly replaceMediaConnection?: () => Promise<CloudflareSFUBootstrap>;
     readonly pollIntervalMs?: number;
-    readonly onError?: (error: unknown) => void;
+    readonly onError?: (error: unknown, mediaConnectionId: string) => void;
     readonly onRemoteTrack?: (publication: CloudflareSFURemoteTrack) => void;
     readonly onScreenEnded?: () => void;
     readonly peerConnectionFactory?: (configuration: RTCConfiguration) => RTCPeerConnection;
@@ -108,6 +110,8 @@ export type CloudflareSFURestartOptions = {
 };
 export type CloudflareSFUCredentialProvider = (signal?: AbortSignal) => string | Promise<string>;
 export type CloudflareSFUHTTPTransportOptions = {
+    readonly traceparent?: string;
+    readonly onDiagnostic?: (event: ConnectionReportTransportEvent) => void;
     readonly apiBaseURL: string;
     readonly credential?: CloudflareSFUCredentialProvider;
     /** @deprecated Use credential so refreshed media access is read before every request. */

package/dist/public-invites/index.js

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

package/dist/server/access-refresh.d.cts

@@ -2,7 +2,7 @@ import type { AccessContext } from "../space-client/types.cjs";
 import type { IssueAccessGrantInput } from "./types.cjs";
 import { type AccessGrant, type ParticipantMediaCredential } from "../access/grant.cjs";
 /** Forward the browser request unchanged; only Chalk decides whether media needs replacing. */
-export type AccessRefreshRequest = Pick<AccessContext, "replaceMediaConnection">;
+export type AccessRefreshRequest = Pick<AccessContext, "replaceMediaConnection" | "expectedMediaConnectionId" | "currentMediaToken">;
 /** Keep this on your backend, scoped to the authenticated Participant. Never send it to a browser or log it. */
 export type AccessRefreshState = {
     readonly participantGeneration: number;

package/dist/server/access-refresh.d.ts

@@ -2,7 +2,7 @@ import type { AccessContext } from "../space-client/types.js";
 import type { IssueAccessGrantInput } from "./types.js";
 import { type AccessGrant, type ParticipantMediaCredential } from "../access/grant.js";
 /** Forward the browser request unchanged; only Chalk decides whether media needs replacing. */
-export type AccessRefreshRequest = Pick<AccessContext, "replaceMediaConnection">;
+export type AccessRefreshRequest = Pick<AccessContext, "replaceMediaConnection" | "expectedMediaConnectionId" | "currentMediaToken">;
 /** Keep this on your backend, scoped to the authenticated Participant. Never send it to a browser or log it. */
 export type AccessRefreshState = {
     readonly participantGeneration: number;

package/dist/server/index.cjs

@@ -38,11 +38,13 @@ function decodeBase64Url(value) {
 // src/access/grant.ts
 var accessGrantBrand = /* @__PURE__ */ Symbol("AccessGrant");
 var AccessGrantError = class extends TypeError {
-  code = "access.invalid";
-  constructor(message = "Access grant is invalid") {
+  constructor(message = "Access grant is invalid", reason) {
     super(message);
+    this.reason = reason;
     this.name = "AccessGrantError";
   }
+  reason;
+  code = "access.invalid";
 };
 function parseParsedAccessGrant(value) {
   if (!isRecord(value)) throw new AccessGrantError();
@@ -165,7 +167,12 @@ function getAccessRefreshState(access) {
   });
 }
 function accessRefreshInput(state, request) {
-  if (request?.replaceMediaConnection === true) return { participantGeneration: state.participantGeneration, replaceMediaConnection: true };
+  if (request?.replaceMediaConnection === true)
+    return {
+      participantGeneration: state.participantGeneration,
+      replaceMediaConnection: true,
+      ...request.expectedMediaConnectionId === void 0 ? {} : { expectedMediaConnectionId: request.expectedMediaConnectionId, ...request.currentMediaToken === void 0 ? {} : { currentMediaToken: request.currentMediaToken } }
+    };
   return state;
 }
 
@@ -326,7 +333,9 @@ function setOptionalHeader(headers, name, value) {
   if (value !== void 0) headers.set(name, value);
 }
 async function responseError(response, retryable) {
-  return new ChalkAPIError({ code: errorCode(await errorBody(response)), requestId: requestId(response.headers), retryable: retryable && retryableStatuses.has(response.status), status: response.status });
+  const code = errorCode(await errorBody(response));
+  const pendingReplacement = response.status === 409 && code === "participant.media_replacement_pending";
+  return new ChalkAPIError({ code, requestId: requestId(response.headers), retryable: pendingReplacement || retryable && retryableStatuses.has(response.status), status: response.status });
 }
 async function errorBody(response) {
   try {
@@ -601,7 +610,8 @@ function accessGrantRequest(input) {
   return {
     participant_generation: input.participantGeneration,
     replace_media_connection: input.replaceMediaConnection ?? false,
-    ...input.currentMediaToken ? { current_media_token: input.currentMediaToken } : {}
+    ...input.currentMediaToken ? { current_media_token: input.currentMediaToken } : {},
+    ...input.replaceMediaConnection && input.expectedMediaConnectionId !== void 0 ? { expected_media_connection_id: input.expectedMediaConnectionId } : {}
   };
 }
 function participantRemovalRequest(input) {

package/dist/server/index.js

@@ -16,11 +16,13 @@ function decodeBase64Url(value) {
 // src/access/grant.ts
 var accessGrantBrand = /* @__PURE__ */ Symbol("AccessGrant");
 var AccessGrantError = class extends TypeError {
-  code = "access.invalid";
-  constructor(message = "Access grant is invalid") {
+  constructor(message = "Access grant is invalid", reason) {
     super(message);
+    this.reason = reason;
     this.name = "AccessGrantError";
   }
+  reason;
+  code = "access.invalid";
 };
 function parseParsedAccessGrant(value) {
   if (!isRecord(value)) throw new AccessGrantError();
@@ -143,7 +145,12 @@ function getAccessRefreshState(access) {
   });
 }
 function accessRefreshInput(state, request) {
-  if (request?.replaceMediaConnection === true) return { participantGeneration: state.participantGeneration, replaceMediaConnection: true };
+  if (request?.replaceMediaConnection === true)
+    return {
+      participantGeneration: state.participantGeneration,
+      replaceMediaConnection: true,
+      ...request.expectedMediaConnectionId === void 0 ? {} : { expectedMediaConnectionId: request.expectedMediaConnectionId, ...request.currentMediaToken === void 0 ? {} : { currentMediaToken: request.currentMediaToken } }
+    };
   return state;
 }
 
@@ -228,7 +235,9 @@ function setOptionalHeader(headers, name, value) {
   if (value !== void 0) headers.set(name, value);
 }
 async function responseError(response, retryable) {
-  return new ChalkAPIError({ code: errorCode(await errorBody(response)), requestId: requestId(response.headers), retryable: retryable && retryableStatuses.has(response.status), status: response.status });
+  const code = errorCode(await errorBody(response));
+  const pendingReplacement = response.status === 409 && code === "participant.media_replacement_pending";
+  return new ChalkAPIError({ code, requestId: requestId(response.headers), retryable: pendingReplacement || retryable && retryableStatuses.has(response.status), status: response.status });
 }
 async function errorBody(response) {
   try {
@@ -503,7 +512,8 @@ function accessGrantRequest(input) {
   return {
     participant_generation: input.participantGeneration,
     replace_media_connection: input.replaceMediaConnection ?? false,
-    ...input.currentMediaToken ? { current_media_token: input.currentMediaToken } : {}
+    ...input.currentMediaToken ? { current_media_token: input.currentMediaToken } : {},
+    ...input.replaceMediaConnection && input.expectedMediaConnectionId !== void 0 ? { expected_media_connection_id: input.expectedMediaConnectionId } : {}
   };
 }
 function participantRemovalRequest(input) {

package/dist/server/types.d.cts

@@ -158,8 +158,9 @@ export type IssueAccessGrantInput = {
     readonly replaceMediaConnection?: false;
 } | {
     readonly participantGeneration: number;
-    readonly currentMediaToken?: never;
+    readonly currentMediaToken?: string;
     readonly replaceMediaConnection: true;
+    readonly expectedMediaConnectionId?: string;
 };
 export type APIKey = {
     readonly created_at: string;

package/dist/server/types.d.ts

@@ -158,8 +158,9 @@ export type IssueAccessGrantInput = {
     readonly replaceMediaConnection?: false;
 } | {
     readonly participantGeneration: number;
-    readonly currentMediaToken?: never;
+    readonly currentMediaToken?: string;
     readonly replaceMediaConnection: true;
+    readonly expectedMediaConnectionId?: string;
 };
 export type APIKey = {
     readonly created_at: string;

package/dist/space-client/media-projection-monitor.d.ts

@@ -0,0 +1,26 @@
+import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
+type Source = "microphone" | "camera";
+type Observation = {
+    readonly revision: number;
+    readonly publicationId: string | null;
+    readonly enabled: boolean;
+    readonly projectedEnabled: boolean;
+    readonly projectedPublicationId: string | null;
+};
+type Options = {
+    readonly now: () => number;
+    readonly schedule: (callback: () => void, milliseconds: number) => unknown;
+    readonly cancel: (timer: unknown) => void;
+    readonly report: (event: ConnectionReportTransportEvent) => void;
+    readonly pause: (source: Source, revision: number) => void;
+    readonly changed: () => void;
+};
+/** Observes authority without sending targets that could affect another client. */
+export declare class MediaProjectionMonitor {
+    #private;
+    constructor(options: Options);
+    observe(source: Source, observation: Observation): void;
+    state(source: Source): "requesting" | "failed" | null;
+    reset(): void;
+}
+export {};

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

@@ -17,6 +17,10 @@ export type AccessContext = {
     readonly reason: AccessReason;
     /** Forward to the access endpoint so media recovery can obtain a fresh connection. */
     readonly replaceMediaConnection: boolean;
+    /** Automatic replacement succeeds only while this media binding is current. Omit for explicit takeover. */
+    readonly expectedMediaConnectionId?: string;
+    /** Forward unchanged for replay-safe recovery. Never log credentials. */
+    readonly currentMediaToken?: string;
     readonly signal?: AbortSignal;
 };
 /**

package/dist/sync/index.js

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

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

@@ -1,3 +1,4 @@
+import type { ConnectionReportTransportEvent } from "../transport-diagnostics";
 import type { SetAdmissionPolicyCommandFrame, SyncV1ServerFrame } from "../generated/sync";
 import type { ClientMediaPlane, MediaPlaneOutcome, MediaPlaneResult, MediaPlaneTarget, MediaPublication, MediaSource } from "../media/plane";
 import type { ChalkChatReactionInput, ChalkChatReactions, ChalkChatMessage, ChalkChatPageResult, ChalkChatReadReceipt, ChalkReaction, ChalkReactionEvent, ChalkSendChatMessageInput, ChalkSyncV1CollaborationCapability } from "../collaboration/types";
@@ -189,6 +190,8 @@ export type V1CollaborationClient = {
     }) => Promise<ChalkChatPageResult>;
 };
 export type V1SyncClientOptions = {
+    readonly traceparent?: string;
+    readonly onDiagnostic?: (event: ConnectionReportTransportEvent) => void;
     readonly url: string;
     readonly token: () => Promise<string>;
     readonly webSocket: SyncWebSocketFactory;

package/dist/transport-diagnostics.d.ts

@@ -0,0 +1,3 @@
+import type { components } from "./generated/openapi-types";
+export type ConnectionReport = components["schemas"]["ConnectionReportRequest"];
+export type ConnectionReportTransportEvent = Pick<ConnectionReport["events"][number], "event" | "phase" | "attempt" | "duration_ms" | "heartbeat_gap_ms" | "close_code" | "http_status" | "source" | "publication_state" | "projection_state" | "outcome">;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@q9labsai/chalk-client",
-  "version": "5.2.3",
+  "version": "5.2.5",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -218,7 +218,7 @@
     "dev": "tsup ./src/index.ts ./src/effect.ts ./src/media/index.ts ./src/sync/index.ts --format esm --out-dir ./dist --platform browser --external effect --watch",
     "generate:webhooks": "node ./scripts/generate-webhook-contract.mjs",
     "check:webhooks-generated": "node ./scripts/generate-webhook-contract.mjs --check",
-    "test": "pnpm exec vitest run",
+    "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:sync-browser": "pnpm run build && node ./scripts/real-browser-sync.mjs",