@q9labsai/chalk-client 5.2.2 → 5.2.4

package/README.md

@@ -311,7 +311,7 @@ SpaceClient negotiates `collaboration_v2` for the 24-emoji set and per-message r
 
 `await client.media.setScreenShareEnabled(true, { surface: "browser", audio: true })` requests tab audio. The browser picker remains authoritative: selecting a window or declining audio still shares video normally. Audio is published separately as `screen_audio`; it starts, stops, and is revoked with the share, never with the microphone. `media.screenShare.hasAudio` reports local live audio; `participants.roster[].media.screenShareHasAudio` reports the remote publication. `media.remote` contains the received track.
 
-The sharer keeps local playback (`suppressLocalAudioPlayback: false`). Display audio disables echo cancellation, noise suppression and automatic gain control to preserve music; microphone capture and its processing are unchanged. System audio is excluded to avoid sending the call back to itself. Headphones avoid acoustic doubling through the microphone; local playback cannot be preserved while guaranteeing that loudspeakers never leak into it. Chrome documents [local playback control](https://developer.chrome.com/blog/screen-sharing-improvements-in-chrome-109) and [system-audio feedback](https://developer.chrome.com/docs/web-platform/screen-sharing-controls). [Meet documents the same “Also share tab audio” picker control](https://support.google.com/meet/answer/9308856?hl=en). No public X documentation establishing its echo default was found.
+The sharer keeps local playback (`suppressLocalAudioPlayback: false`). Display audio disables echo cancellation, noise suppression and automatic gain control to preserve music; microphone capture and its processing are unchanged. System audio is excluded to avoid sending the call back to itself. Headphones avoid acoustic doubling through the microphone; local playback cannot be preserved while guaranteeing that loudspeakers never leak into it. Chrome documents [local playback control](https://developer.chrome.com/blog/screen-sharing-improvements-in-chrome-109) and [system-audio feedback](https://developer.chrome.com/docs/web-platform/screen-sharing-controls). [Meet documents the same “Also share tab audio” picker control](https://support.google.com/meet/answer/9308856?hl=en).
 
 Shared tab audio is excluded from recordings until the recording format supports it. React Native display capture behavior is unchanged.
 

package/dist/{chunk-DWKTGBHR.js → chunk-3ASKGMD3.js}

@@ -1428,12 +1428,17 @@ function createCloudflareSFUHTTPTransport(options) {
     const token = await withDeadline(CREDENTIAL_TIMEOUT_MS, (signal) => credential(signal));
     if (!token.trim()) throw new CloudflareSFUError("The media credential provider returned an empty token", "signaling_failed");
     return withDeadline(timeoutMs, async (signal) => {
+      const startedAt = performance.now();
       const response = await fetch(`${mediaPath}/${path}`, {
         ...init,
         signal,
-        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...init?.headers }
+        headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...options.traceparent ? { traceparent: options.traceparent } : {}, ...init?.headers }
       });
       if (!response.ok) {
+        try {
+          options.onDiagnostic?.({ event: "media_http_error", http_status: response.status, duration_ms: performance.now() - startedAt });
+        } catch {
+        }
         throw new CloudflareSFUError(`Chalk SFU signaling failed with HTTP ${response.status}`, "signaling_failed", {
           status: response.status,
           retryableConnection: response.status === 404 || response.status === 410 || response.status >= 500 && response.status < 600

package/dist/{chunk-AIJ5Z6HA.js → chunk-5YPQNMJE.js}

@@ -120,7 +120,7 @@ var BrowserSyncSocket = class {
     this.#socket = socket;
     this.#socket.addEventListener("open", () => this.onopen?.());
     this.#socket.addEventListener("message", (event) => this.onmessage?.({ data: event.data }));
-    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason }));
+    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason, ...typeof event.wasClean === "boolean" ? { wasClean: event.wasClean } : {} }));
     this.#socket.addEventListener("error", () => this.onerror?.());
   }
   send(data) {
@@ -178,7 +178,7 @@ var ReactNativeSyncSocket = class {
     this.#socket = socket;
     this.#socket.onopen = () => this.onopen?.();
     this.#socket.onmessage = (event) => this.onmessage?.({ data: event.data });
-    this.#socket.onclose = (event) => this.onclose?.({ code: typeof event.code === "number" ? event.code : 1006, reason: typeof event.reason === "string" ? event.reason : void 0 });
+    this.#socket.onclose = (event) => this.onclose?.({ code: typeof event.code === "number" ? event.code : 1006, reason: typeof event.reason === "string" ? event.reason : void 0, ...typeof event.wasClean === "boolean" ? { wasClean: event.wasClean } : {} });
     this.#socket.onerror = () => this.onerror?.();
   }
   send(data) {
@@ -198,7 +198,7 @@ var BrowserFallbackSyncSocket = class {
     this.#socket = socket;
     this.#socket.addEventListener("open", () => this.onopen?.());
     this.#socket.addEventListener("message", (event) => this.onmessage?.({ data: event.data }));
-    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason }));
+    this.#socket.addEventListener("close", (event) => this.onclose?.({ code: event.code, reason: event.reason, ...typeof event.wasClean === "boolean" ? { wasClean: event.wasClean } : {} }));
     this.#socket.addEventListener("error", () => this.onerror?.());
   }
   send(data) {
@@ -339,7 +339,7 @@ var SyncProtocolMetadata = {
       accepts: ["entered", "command", "live_target", "directed_request", "delivery_ack", "request_ack", "reaction_send", "chat_send", "chat_page_request", "chat_read_set", "chat_reaction_set", "ping"],
       heartbeat: {
         intervalMs: 2e4,
-        missedDeadlinesBeforeClose: 2
+        missedDeadlinesBeforeClose: 5
       }
     },
     {
@@ -3028,6 +3028,9 @@ var V1SyncClient = class {
   #dialTimeoutCount = 0;
   #connectStartedAt = null;
   #connectAttemptCount = 0;
+  #socketCloses = [];
+  #omittedSocketCloses = 0;
+  #lastHeartbeatReplyAt = null;
   #opened = false;
   #connectFailure;
   #connectDiagnostic() {
@@ -3095,6 +3098,9 @@ var V1SyncClient = class {
     if (this.#started) return;
     this.#started = true;
     this.#connectAttemptCount = 0;
+    this.#socketCloses = [];
+    this.#omittedSocketCloses = 0;
+    this.#lastHeartbeatReplyAt = null;
     this.#connectFailure = void 0;
     const startupGeneration = ++this.#startupGeneration;
     let stored;
@@ -3150,6 +3156,7 @@ var V1SyncClient = class {
     return {
       connection: {
         ...this.#phase,
+        recoveryDiagnostic: { socketAttempts: this.#connectAttemptCount, socketCloses: this.#socketCloses.slice(), omittedSocketCloses: this.#omittedSocketCloses, lastHeartbeatReplyAt: this.#lastHeartbeatReplyAt },
         ...this.#connectStartedAt !== null && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering") ? { connectAttempt: this.#connectDiagnostic() } : {},
         ...this.#connectFailure && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering") ? { connectFailure: this.#connectFailure } : {},
         ...this.#phase.phase === "live" ? { noticeUnresponsive: this.#health.health === "recovering", health: this.#health.health } : {},
@@ -3296,6 +3303,7 @@ var V1SyncClient = class {
     this.#phase = { phase: "connecting" };
     this.#connectAttemptCount += 1;
     this.#connectStartedAt = this.#clock().now();
+    const socketStartedAt = this.#connectStartedAt;
     this.#opened = false;
     if (this.#connectFailure?.opened) this.#connectFailure = void 0;
     this.#emit();
@@ -3324,6 +3332,7 @@ var V1SyncClient = class {
       if (socket !== this.#socket) return;
       this.#clearDial();
       this.#opened = true;
+      this.#diagnostic({ event: "sync_socket_open", attempt: this.#connectAttemptCount, duration_ms: this.#clock().now() - socketStartedAt });
       this.#connectFailure = void 0;
       void this.#authenticate(socket);
     };
@@ -3331,6 +3340,14 @@ var V1SyncClient = class {
       this.#inbound = this.#inbound.then(() => this.#receive(socket, event.data));
     };
     socket.onclose = (event) => {
+      this.#diagnostic({ event: "sync_socket_close", close_code: event.code, duration_ms: this.#clock().now() - socketStartedAt, ...this.#lastHeartbeatReplyAt === null ? {} : { heartbeat_gap_ms: this.#now() - this.#lastHeartbeatReplyAt } });
+      if (this.#started) {
+        this.#socketCloses.push({ code: event.code, wasClean: event.wasClean ?? null });
+        if (this.#socketCloses.length > 50) {
+          this.#socketCloses.shift();
+          this.#omittedSocketCloses += 1;
+        }
+      }
       if (socket === this.#socket && (this.#phase.phase === "connecting" || this.#phase.phase === "recovering")) {
         this.#connectFailure = { ...this.#connectDiagnostic(), closeCode: event.code, closeReason: safeSyncCloseReason(event.reason) };
         this.#emit();
@@ -3362,6 +3379,7 @@ var V1SyncClient = class {
       const hello = {
         type: "hello",
         protocol: 1,
+        ...this.#options.traceparent ? { traceparent: this.#options.traceparent } : {},
         token,
         streams: {
           control: { cursor: this.#control && { revision: this.#control.revision, state_schema_version: this.#control.stateSchemaVersion, state_digest: this.#control.stateDigest } },
@@ -3501,6 +3519,7 @@ var V1SyncClient = class {
       case "pong": {
         this.#requireLive();
         this.#missedHeartbeats = 0;
+        this.#lastHeartbeatReplyAt = this.#now();
         const previous = this.#health.health;
         this.#health.observePong(this.#now());
         if (previous !== this.#health.health) this.#emit();
@@ -3814,12 +3833,19 @@ var V1SyncClient = class {
   #updateLocalMediaStates() {
     this.#liveTargets.updateFromPublications(this.#localPublications);
   }
+  #diagnostic(event) {
+    try {
+      this.#options.onDiagnostic?.(event);
+    } catch {
+    }
+  }
   #startHeartbeat() {
     this.#clearHeartbeat();
     this.#heartbeatTimer = this.#clock().setTimeout(() => {
       this.#heartbeatTimer = void 0;
       if (this.#phase.phase !== "live") return;
       this.#missedHeartbeats += 1;
+      if (this.#missedHeartbeats > 1) this.#diagnostic({ event: "sync_heartbeat_gap", duration_ms: this.#missedHeartbeats * 2e4, ...this.#lastHeartbeatReplyAt === null ? {} : { heartbeat_gap_ms: this.#now() - this.#lastHeartbeatReplyAt } });
       if (this.#missedHeartbeats > 2) {
         this.#socket?.close(CLIENT_RESTART_CLOSE_CODE, "heartbeat timeout");
         return;

package/dist/{chunk-GA3JDPFI.js → chunk-AZONR3Q3.js}

@@ -243,6 +243,71 @@ var CloudflareSFUTracksRequestSchema = Schema.Struct({
     })
   )
 });
+var ConnectionReportRequestSchema = Schema.Struct({
+  events: Schema.Array(
+    Schema.Struct({
+      attempt: Schema.optional(Schema.NullOr(Schema.Number)),
+      close_code: Schema.optional(Schema.NullOr(Schema.Number)),
+      code: Schema.optional(
+        Schema.Literals([
+          "invalid_state",
+          "invalid_access",
+          "access_unavailable",
+          "permission_denied",
+          "device_not_found",
+          "device_busy",
+          "device_constraint_invalid",
+          "media_capture_failed",
+          "sync_start_failed",
+          "state_digest_recovery_failed",
+          "sync_hello_timeout",
+          "media_start_failed",
+          "join_cleanup_unconfirmed",
+          "sync_recovery_exhausted",
+          "media_recovery_exhausted",
+          "command_rejected",
+          "leave_unconfirmed",
+          "episode_ended",
+          "unsupported_environment",
+          "internal_error",
+          "collaboration_unavailable",
+          "chat_cursor_reset_required",
+          "rate_limited",
+          "invalid_payload"
+        ])
+      ),
+      duration_ms: Schema.optional(Schema.NullOr(Schema.Number)),
+      elapsed_ms: Schema.Number,
+      event: Schema.Literals([
+        "space_join_span",
+        "state_changed",
+        "connection_failed",
+        "sync_connect_failed",
+        "sync_dial_timeout",
+        "access_refreshed",
+        "access_refresh_failed",
+        "recovery_attempt",
+        "recovery_succeeded",
+        "recovery_exhausted",
+        "cleanup_completed",
+        "cleanup_unconfirmed",
+        "sync_socket_open",
+        "sync_socket_close",
+        "sync_heartbeat_gap",
+        "media_state",
+        "media_http_error"
+      ]),
+      heartbeat_gap_ms: Schema.optional(Schema.NullOr(Schema.Number)),
+      http_status: Schema.optional(Schema.NullOr(Schema.Number)),
+      outcome: Schema.optional(Schema.Literals(["started", "succeeded", "failed", "cancelled"])),
+      phase: Schema.optional(Schema.Literals(["idle", "connecting", "live", "recovering", "failed", "stopped", "new", "connected", "disconnected", "closed"])),
+      state: Schema.optional(Schema.Literals(["idle", "joining", "live", "reconnecting", "leaving", "left", "failed"])),
+      step: Schema.optional(Schema.Literals(["join", "acquire_initial_media", "access_initialize", "create_media_client", "create_sync_client", "start_media", "start_sync", "wait_for_sync_live", "confirm_entered"]))
+    })
+  ).check(Schema.isMinLength(1), Schema.isMaxLength(64)),
+  trigger: Schema.Literals(["join_failed", "connection_lost", "recovery_exhausted"]),
+  version: Schema.Literal(1)
+});
 var CreateAPIKeyRequestSchema = Schema.Struct({
   expires_at: DateTimeStringSchema,
   name: Schema.String.check(Schema.isMinLength(1)),
@@ -1687,6 +1752,15 @@ var RenegotiateCloudflareSFU429ResponseHeadersSchema = Schema.Struct({
   "X-RateLimit-Limit": RateLimitLimitHeaderSchema,
   "X-RateLimit-Remaining": RateLimitRemainingHeaderSchema
 });
+var ReportConnectionFailurePathParamsSchema = Schema.Struct({
+  tenant_id: TenantIdSchema
+});
+var ReportConnectionFailureRequestBodySchema = ConnectionReportRequestSchema;
+var ReportConnectionFailure429ResponseHeadersSchema = Schema.Struct({
+  "Retry-After": RetryAfterHeaderSchema,
+  "X-RateLimit-Limit": RateLimitLimitHeaderSchema,
+  "X-RateLimit-Remaining": RateLimitRemainingHeaderSchema
+});
 var RequestRecordingExportPathParamsSchema = Schema.Struct({
   recording_id: RecordingIdSchema,
   tenant_id: TenantIdSchema
@@ -4794,6 +4868,16 @@ var RenegotiateCloudflareSFUErrorSchema = Schema.Union([
   SpaceInvalidIdErrorSchema,
   TenantInvalidIdErrorSchema
 ]);
+var ReportConnectionFailureErrorSchema = Schema.Union([
+  AccessForbiddenErrorSchema,
+  AccessUnauthenticatedErrorSchema,
+  RequestInvalidErrorSchema,
+  RequestPayloadTooLargeErrorSchema,
+  RequestRateLimitedErrorSchema,
+  ServiceInternalErrorSchema,
+  ServiceUnavailableErrorSchema,
+  TenantInvalidIdErrorSchema
+]);
 var RequestRecordingExportErrorSchema = Schema.Union([
   AccessForbiddenErrorSchema,
   AccessUnauthenticatedErrorSchema,
@@ -5087,6 +5171,7 @@ var ChalkOperationPolicies = {
   refreshSpacePublicInviteAccess: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
   removeEpisodeParticipant: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
   renegotiateCloudflareSFU: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
+  reportConnectionFailure: { maxBodyBytes: 32768, rateLimit: { limit: 6, policy: "connection_reports.participant", windowSeconds: 600 } },
   requestRecordingExport: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
   requestTranscript: { maxBodyBytes: 1048576, rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
   restoreSpace: { rateLimit: { limit: 60, policy: "v1.authenticated.write", windowSeconds: 60 } },
@@ -5528,6 +5613,22 @@ var defaultGroup = HttpApiGroup.make("default").add(
       ServiceUnavailableErrorSchema.pipe(HttpApiSchema.status(503))
     ]
   })
+).add(
+  HttpApiEndpoint.post("reportConnectionFailure", "/v1/tenants/:tenant_id/connection-reports", {
+    params: ReportConnectionFailurePathParamsSchema,
+    payload: ReportConnectionFailureRequestBodySchema,
+    success: HttpApiSchema.Empty(204).pipe(HttpApiSchema.status(204)),
+    error: [
+      RequestInvalidErrorSchema.pipe(HttpApiSchema.status(400)),
+      TenantInvalidIdErrorSchema.pipe(HttpApiSchema.status(400)),
+      AccessUnauthenticatedErrorSchema.pipe(HttpApiSchema.status(401)),
+      AccessForbiddenErrorSchema.pipe(HttpApiSchema.status(403)),
+      RequestPayloadTooLargeErrorSchema.pipe(HttpApiSchema.status(413)),
+      RequestRateLimitedErrorSchema.pipe(HttpApiSchema.status(429)),
+      ServiceInternalErrorSchema.pipe(HttpApiSchema.status(500)),
+      ServiceUnavailableErrorSchema.pipe(HttpApiSchema.status(503))
+    ]
+  })
 ).add(
   HttpApiEndpoint.delete("revokeAPIKey", "/v1/tenants/:tenant_id/api-keys/:api_key_id", {
     params: RevokeAPIKeyPathParamsSchema,
@@ -6877,6 +6978,7 @@ export {
   CloudflareSFURenegotiateResponseSchema,
   CloudflareSFUTracksAPIResponseSchema,
   CloudflareSFUTracksRequestSchema,
+  ConnectionReportRequestSchema,
   CreateAPIKeyRequestSchema,
   CreateEpisodeRequestSchema,
   CreateMembershipRequestSchema,
@@ -7174,6 +7276,9 @@ export {
   RenegotiateCloudflareSFURequestBodySchema,
   RenegotiateCloudflareSFUResponseSchema,
   RenegotiateCloudflareSFU429ResponseHeadersSchema,
+  ReportConnectionFailurePathParamsSchema,
+  ReportConnectionFailureRequestBodySchema,
+  ReportConnectionFailure429ResponseHeadersSchema,
   RequestRecordingExportPathParamsSchema,
   RequestRecordingExportRequestBodySchema,
   RequestRecordingExportResponseSchema,
@@ -7642,6 +7747,7 @@ export {
   RefreshSpacePublicInviteAccessErrorSchema,
   RemoveEpisodeParticipantErrorSchema,
   RenegotiateCloudflareSFUErrorSchema,
+  ReportConnectionFailureErrorSchema,
   RequestRecordingExportErrorSchema,
   RequestTranscriptErrorSchema,
   RestoreSpaceErrorSchema,