@q9labsai/chalk-client 5.1.0 → 5.2.1

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # Changelog
 
+## 5.2.0
+
+### board-draw-policy
+
+Add a call-wide drawing policy for the board: everyone, only hosts, or picked people.
+Hosts set it with `setDrawPolicy` on the whiteboard transport and pick people with the
+existing `setDrawPermission`. Sync computes each person's permission and sends it with
+the policy over the new `draw_policy_v1` extension, so the summary and
+`useWhiteboard().access` now carry `canDraw`, `drawPolicy` and the host's per-person
+choices. The React board follows that permission instead of the role capability, and
+hosts get a "Who can draw" section with a person picker in the board menu.
+
+The whiteboard client now steps its hello down only when Sync can't decode it (close
+1009). A rejected token or a late hello (close 1008) is retried at the same level up to
+four times, so a brief token problem no longer hides the drawing policy for the rest of
+the connection. On a Sync without the drawing policy, a host's waiting policy change is
+refused as `unavailable`, and also reported on the summary, instead of being replayed.
+
+### confirmed-call-entry
+
+Count a person in a call only after they have fully entered it. The built-in
+browser and React Native Sync clients ask Sync for entry confirmation on the Sync
+URL (`entry_confirmation=1`). When Sync's `welcome` grants it, the client sends
+`entered` once Sync is live and media has started, so a failed connection no
+longer leaves a ghost participant or an attendance record. Against an older Sync,
+the client sends the previous hello and Sync confirms entry at hello as before.
+
+`confirmEntered()` on a custom `createSyncClient` implementation is optional.
+Implementing it, and building `V1SyncClient` with `entryConfirmation: true`, adds
+the confirmed entry above. Without it, the client never asks for entry
+confirmation and Sync confirms the entry at hello, as in 5.0.x. `V1SyncClient`
+asks only when it is built with `entryConfirmation: true`.
+
+When entry fails, the client cancels the pending admission through the new
+`cancelEpisodeParticipantJoin` endpoint (`POST .../participants/:participant_id/cancel-join`),
+and a retry keeps the same person. If Sync reports `entry timeout` because the
+pending seat expired before entry, the connection fails as a retryable
+`sync_start_failed` instead of rejected access, and the client does not reconnect
+the expired seat with the same grant.
+
+The admission contract declares the 409 `participant.not_active` response when
+a retried admission names a participant that has already left. The public
+`AdmitEpisodeParticipantError` union stays compatible with 5.1.0; this response
+uses the existing `HttpClientError` channel, with its code in the response body.
+The dashboard reads that code and retries once with a fresh join key.
+
+Sync assigns each entry a participant-local generation and returns it in
+`welcome`. The client resumes that generation through the `entry_generation`
+WebSocket query, even after refreshing its credential. Confirmation advances
+ownership only forward and voids older pending Leaves. Acceptance and completion
+both fence a Leave against the confirmed generation, so reattaching the same
+seat cannot let the previous mount remove it. Previous Sync ignores this query.
+Legacy sockets receive a server generation internally without changing their
+welcome frame, and still confirm at hello. Participants created before seat
+storage acquire it on their first live hello. When recovery replaces the Sync
+client, it confirms the replacement entry before reporting recovery complete.
+Completed startup also survives reconnecting from an older Sync to an upgraded
+one. Recovery can finish while a previous entry's Leave is pending, and an
+uncertain confirmation reply checks that entry's generation before acknowledging it.
+A claimed Leave blocks later entry
+admission until its provider work settles. An entry admitted before that claim
+defers the older provider work until confirmation or its two-minute startup
+lease expires, preventing old cleanup from closing the new entry's media.
+
+Rollout: apply the database migrations first, then upgrade Sync, then the API and
+this client. This client also works with an older Sync, and published 5.0.x
+clients keep hello confirmation with the new Sync.
+
+### follow-view-owner
+
+Converge Follow views on one Episode owner, recover from its canonical snapshot,
+and preserve real camera moves during recovery and tab switches. Zoom controls
+and keyboard moves now consistently leave Follow and lead the person's view.
+
+Keep all 500 active people's views using internal schema-generated limits in the client and React caches. The client's public bounds, event unions and decoded-frame unions are unchanged. The client now exports `ChalkWhiteboardViewVersions`, which the React SDK uses to order view moves, and whiteboard view events now carry `ownerId`, `ownerSequence` and `originEpoch`, so both releases are minor.
+
+### honest-chat-file-errors
+
+Report chat attachment network and browser access failures without blaming storage.
+Keep token acquisition failures separate with a diagnostic stage while preserving
+the published error codes and original cause. Preserve recoverable access and
+connection failures through SpaceClient, including signed storage uploads. Show
+the storage-unavailable message only when a readable 503 response confirms
+`chat.storage_unavailable`.
+
+### problem-reporting
+
+Add the problem-report API contract and reusable report dialog, with opt-in diagnostics,
+editable delivery failures and bounded Unicode input. Call details and failed or ended
+call screens can expose reporting when an integration supplies a delivery callback.
+Use `reportUnavailableReason` to show expired access inside an editable report.
+Live report drafts survive call termination. Integrations with their own terminal
+screens can use `onOpenReportProblem` to keep one app-owned dialog across those screens.
+Give `ReportProblemDialog` a `focusScope` containing the current call or terminal screen,
+so closing it returns focus to its usable opener, or to a visible current control
+when the opener has disappeared. Hidden, inert and disabled targets are skipped.
+
+### recording-auto-render
+
+Expose recording expiry reasons through additive failure fields while preserving the existing export status enum.
+
+Add the Tenant recording_render_mode setting, defaulting to on_demand, with opt-in automatic MP4 rendering.
+
+### recording-transcription-expiry
+
+Recordings now report when their transcription source expires, as
+`transcription_preparation.expires_at`. A transcript can be requested only
+while `transcription_preparation.status` is `ready` and this time is ahead. It
+is never later than `source.expires_at`, and it can be much earlier, because a
+Space's transcription source window is often shorter than its video retention. The field is
+absent when transcription is disabled or no transcription source exists yet.
+
+### space-activity-read
+
+Add `spaces.listSpaceActivity` (`GET /v1/tenants/{tenant_id}/space-activity`) and
+its generated schemas and types. One read returns, for up to 300 Spaces, whether each
+is archived, the live Episode with its full participant count and first five Participants, the latest
+Episode with its status and start and end times, and up to five Participants who
+most recently joined that Episode. It needs `episodes:read`; an unknown or other
+Tenant's Space returns `404` for the whole batch. Existing operations are unchanged.
+
+### sync-connect-diagnostics
+
+Report Sync connection failures with the existing `connection.sync_hello_timeout` code without adding values to the public `ErrorCode` union. Add the current attempt's safe diagnostics to client errors, telemetry, and the call failure reference: opening/hello stage, close code and bounded reason, whether the socket opened, and elapsed time. Earlier attempts remain in the diagnostic history. Browsers do not expose DNS, TCP, or TLS progress. Unrecognized peer reasons are redacted. This is a compatible patch for the next client and React releases; released 5.1.0 files are unchanged.
+
 ## 5.1.0
 
 - Add shared board views: `ChalkWhiteboardView`, `ChalkWhiteboardViewBounds`, and the whiteboard client's `supportsViews` and `sendView()`, so participants can follow a person's board view or bring everyone to theirs. The board stream also carries a `view` event.

package/dist/chat-files/types.d.ts

@@ -1,16 +1,19 @@
 import type { ChalkChatAttachment, ChalkChatAttachmentMimeType } from "../collaboration/types";
 export type ChalkChatFileOperation = "initiate_upload" | "finalize_upload" | "get_download";
+export declare const CHAT_FILE_REACHABILITY_MESSAGE = "Could not reach the chat attachment service (network or browser access failure).";
 export type ChalkChatFileErrorCode = "access.invalid" | "unavailable" | "permission_denied" | "invalid_payload" | "conflict" | "not_found" | "expired" | "file_transfer_failed";
 export type ChalkChatFileFailure = {
     readonly operation: ChalkChatFileOperation;
     readonly code: ChalkChatFileErrorCode;
     readonly recoverable: boolean;
     readonly message: string;
+    readonly stage?: "token" | "request";
 };
 export declare class ChalkChatFileError extends Error {
     readonly operation: ChalkChatFileOperation;
     readonly code: ChalkChatFileErrorCode;
     readonly recoverable: boolean;
+    readonly stage: "token" | "request";
     constructor(failure: ChalkChatFileFailure, options?: ErrorOptions);
 }
 export type ChalkChatFileTransport = {

package/dist/chunk-6LNRDKJF.js

@@ -0,0 +1,162 @@
+import {
+  createChalkEffectClient,
+  parseAccessGrant
+} from "./chunk-GA3JDPFI.js";
+
+// src/public-invites/client.ts
+import { Effect } from "effect";
+function createChalkPublicClient(options) {
+  const baseClientOptions = {
+    baseUrl: options.baseUrl,
+    credentials: options.credentials ?? (options.runtime === "react-native" ? void 0 : "include"),
+    fetch: options.fetch
+  };
+  const createClient = (guestCredential, requestInit) => createChalkEffectClient({
+    ...baseClientOptions,
+    ...requestInit ? { fetch: requestInitFetch(options.fetch, requestInit) } : {},
+    headers: requestHeaders(options, guestCredential)
+  });
+  const createPublicSpace = async (input, idempotency) => {
+    const client = await Effect.runPromise(createClient(void 0));
+    const response = await Effect.runPromise(
+      client.spaces.createPublicSpace({
+        headers: { "Idempotency-Key": idempotencyKey(idempotency) },
+        payload: { display_name: required(input.displayName, "displayName") }
+      })
+    );
+    return publicSpaceCreated(response);
+  };
+  const arriveBySpacePublicInvite = async (input, arrival) => {
+    const client = await Effect.runPromise(createClient(arrival?.guestCredential ?? options.guestCredential));
+    const response = await Effect.runPromise(
+      client.spaces.arriveBySpacePublicInvite({
+        headers: {
+          "Idempotency-Key": idempotencyKey(arrival),
+          ...arrival?.arrivalHandle === void 0 ? {} : { "X-Chalk-Arrival-Handle": required(arrival.arrivalHandle, "arrivalHandle") }
+        },
+        payload: {
+          display_name: required(input.displayName, "displayName"),
+          space_invite_token: required(input.spaceInviteToken, "spaceInviteToken")
+        }
+      })
+    );
+    return publicSpaceArrival(response);
+  };
+  const getSpacePublicInviteArrival = async (reference) => {
+    const normalized = arrivalReference(reference);
+    const client = await Effect.runPromise(createClient(normalized.guestCredential ?? options.guestCredential));
+    const response = await Effect.runPromise(
+      client.spaces.getSpacePublicInviteArrival({
+        headers: { "X-Chalk-Arrival-Handle": normalized.arrivalHandle }
+      })
+    );
+    return publicSpaceArrival(response);
+  };
+  const refreshSpacePublicInviteAccess = async (input, arrival) => {
+    const normalized = refreshInput(input, arrival);
+    const client = await Effect.runPromise(createClient(normalized.guestCredential ?? options.guestCredential, normalized.signal ? { signal: normalized.signal } : void 0));
+    const response = await Effect.runPromise(
+      client.spaces.refreshSpacePublicInviteAccess({
+        headers: { "X-Chalk-Arrival-Handle": normalized.arrivalHandle },
+        payload: { media_proof: required(normalized.mediaProof, "mediaProof"), replace_media_connection: normalized.replaceMediaConnection ?? false }
+      })
+    );
+    return parseAccessGrant(response);
+  };
+  const leaveSpacePublicInviteArrival = async (reference, leaveOptions) => {
+    const normalized = arrivalReference(reference);
+    const client = await Effect.runPromise(createClient(normalized.guestCredential ?? options.guestCredential, requestInitForLeave(leaveOptions)));
+    await Effect.runPromise(
+      client.spaces.leaveSpacePublicInviteArrival({
+        headers: { "X-Chalk-Arrival-Handle": normalized.arrivalHandle }
+      })
+    );
+  };
+  return {
+    prepareSpaceEntrance: async (spaceInviteToken) => {
+      const client = await Effect.runPromise(createClient(void 0));
+      await Effect.runPromise(client.spaces.preparePublicSpaceEntrance({ payload: { space_invite_token: required(spaceInviteToken, "spaceInviteToken") } }));
+    },
+    arrive: arriveBySpacePublicInvite,
+    arriveBySpacePublicInvite,
+    create: createPublicSpace,
+    createPublicSpace,
+    getSpacePublicInviteArrival,
+    leave: leaveSpacePublicInviteArrival,
+    leaveSpacePublicInviteArrival,
+    refresh: refreshSpacePublicInviteAccess,
+    refreshSpacePublicInviteAccess,
+    status: getSpacePublicInviteArrival
+  };
+}
+var createChalkPublicInviteClient = createChalkPublicClient;
+function requestHeaders(options, guestCredential) {
+  const headers = { ...options.headers };
+  if (options.runtime === "react-native") {
+    headers["X-Chalk-Client"] = "react-native";
+    const credential = guestCredential ?? options.guestCredential;
+    if (credential !== void 0) headers.Authorization = `ChalkGuest ${required(credential, "guestCredential")}`;
+  }
+  return headers;
+}
+function idempotencyKey(options) {
+  return options?.idempotencyKey === void 0 ? globalThis.crypto.randomUUID() : required(options.idempotencyKey, "idempotencyKey");
+}
+function arrivalReference(reference) {
+  if (typeof reference === "string") return { arrivalHandle: required(reference, "arrivalHandle") };
+  return { arrivalHandle: required(reference.arrivalHandle, "arrivalHandle"), guestCredential: reference.guestCredential };
+}
+function refreshInput(input, arrival) {
+  const values = typeof input === "string" ? { arrivalHandle: arrival?.arrivalHandle, guestCredential: arrival?.guestCredential, mediaProof: input } : { arrivalHandle: input.arrivalHandle ?? arrival?.arrivalHandle, guestCredential: input.guestCredential ?? arrival?.guestCredential, mediaProof: input.mediaProof, replaceMediaConnection: input.replaceMediaConnection, signal: input.signal };
+  return {
+    ...values,
+    arrivalHandle: required(values.arrivalHandle ?? "", "arrivalHandle")
+  };
+}
+function requestInitForLeave(options) {
+  if (options?.keepalive === void 0) return void 0;
+  return { keepalive: options.keepalive };
+}
+function requestInitFetch(fetchImplementation, requestInit) {
+  const implementation = fetchImplementation ?? globalThis.fetch;
+  return (input, init) => implementation(input, { ...init, ...requestInit });
+}
+function publicSpaceCreated(value) {
+  const { arrival, ...created } = value;
+  return { ...created, arrival: publicSpaceArrival(arrival) };
+}
+function publicSpaceArrival(value) {
+  const { access, ...arrival } = value;
+  if (access === void 0) return arrival;
+  return { ...arrival, access: access === null ? null : parseAccessGrant(access) };
+}
+function required(value, name) {
+  const normalized = value.trim();
+  if (!normalized) throw new TypeError(`${name} is required`);
+  return normalized;
+}
+
+// src/public-invites/words.ts
+var INVITE_WORD_COUNT = 4;
+var INVITE_WORDS = new Set(
+  "abacus able accent acorn acoustic acre acrobat active actor adore aerial agenda agent agile ahead aim airport album alike alive almond aloe aloha alone alpaca alto alumni amber amend ample amuse anchor angle animal anthem antique anvil apple april apron aqua arcade arctic area arena arise aroma array art artist aspire astute atlas atom attach attain attic audio autumn avenue avocado awake award awning bacon badge bagel baked baker bakery bamboo banana banjo banner barge barn basil basket batch baton beacon beetle blank blanket blaze blend blink blog blossom bluebird boat bobcat bolt bonsai bonus book booth boots boss botany both bottle boulder bounce bowler branch breeze brick bright brim bring brisk broil bronze brook broom brush bubble bucket budget buffalo builder bulb bulk bunch bundle bunny busy butter button buzz cabana cable cactus cake calm cameo camera camper campus canal canary candle candy canopy canyon cape captain carbon card cargo carrot carry cartoon case castle catalog cedar celery chair charm cheer cheese chef cherry chess chief chill chip chunk churn cinema circle circus citrus city civic civil claim clamp clap clasp class clay clean clear clever click cling clip cloak clock clone closet cloth cloud clover clump coach coast coat cobalt cocoa coconut coffee coil cola cold colony comfy comic compass concert condor cone cookie cope copper copy coral cork corner cosmic cost cotton couch cover craft crane crate crave crawl crayon create cricket crisp crop crowd crown crumb crust crystal cub cube cupcake curl curry cursor curve cut cycle daffodil daily daisy dance dash date dawn deal debug decaf deck decor delta deluxe denim depth desk device dial diary dice dig dime diner dinner disco dish dock doing doll dolphin domain dome donut dot down dragon dragonfly drama draw drawing dress dried drift drill drive drizzle drove drum dry duck duke duo dusk dust duty eagle early earth easel east echo eclipse edge editor eel effort elder elf elk elm email ember emblem emboss emerald encore energy engine enrich enter entry equal equator eraser errand even evolve exact exit expert fable fabric fact factory falcon fall fame family fancy feast feather feed fence fern ferry fetch fiber fiddle figure film filter final finale finch firefly fit five flag flame flap flick flight flip float flock flower foam fog foil folk font food forest fossil found fountain fox frame fresh fridge friend from front frost fruit gala galaxy game gap garage garden garlic gave gazebo gear gecko gem gerbil giant gift gig ginger giraffe glacier glad glass glide glitter glory gloss glove glow glue goal going golden golf good gown grab grain granite grant grape graph grasp grass gravy green greet grew grid grill grip groom groove guide guitar gulf gummy gush habit half hamster happy harvest hatch haven hazel hazy heap heat hedge helium helmet help heron hickory holiday honey horizon hub hula hull human humid hurry hut ice iceberg icing icon igloo image insect iron island item ivory ivy jacket jaguar jam jasmine jazz jelly jersey jet jigsaw job jog jolly jolt journal joy judge juice juicy july jumbo jump jungle keep kettle kilt king kite kitten kiwi koala ladder lady lagoon lake lamp land lantern laptop large latch laurel lavender leaflet legend lemon length lens leopard letter lettuce level lever library lid life lift lilac lily limit line linen lint lion liquid list little lively lizard lobster locket lotus luggage lumber lunar lunch lyric magnet maker mango manor many map maple marble marine market mascot mash match math meadow melon mercury meteor mitten mocha monkey mop mosaic motor motto mount mouse move movie mud muffin mug mural muse museum mushroom music nacho nail name nap napkin nature neat nectar neon nest net next nickel noodle nugget nutmeg nylon oak oasis oat oatmeal ocean octagon octopus oil olive onion opal open opera orchid origami otter outdoor outer oval oven owl oxygen oyster ozone pace packet pager palace palm panda panther pantry pants papaya paper parade parcel park parrot parsley party pasta pastel patch path patio pebble pecan pelican pencil penguin penny pepper perch petal photo picnic pigeon pillow plank plant plaza plenty pluck plug plus pod poem poet point polar polka polo pond pony poppy portal poster pouch pound power press print prism prize proof pug pull pulp pulse puma pupil puppet puppy purse push puzzle quiet quilt quota quote race rack radar radio radish raft rail rake rally ramp ranch range ranger rank raven reach react recap relax relay relic remix repay reply rerun reset rhyme ribbon rice rich ride rinse ripple rise river robe robin rock rocket rope rover royal ruby rug rule rush safari sage salad salon salsa salt sample sandy satin say scale scan scarf scoop scoot scope score scout scrap screen script scrub scuba scuff sedan send serve seven shack shade shaky shape shed sheep shelf shell shine shiny ship shirt shop shore sift silk silly silver simple single sip size skate sketch skid skip skirt sky slab slack slate sled sleek sleep slice slick sling slip slush small smile snack snap snowy speak speed spend spent spill spiny spoke sponge spool spoon sport spot spout spray spring sprint sprout spruce spur squad squid stack staff stage stall stamp stand staple start state statue steam steep stem step stereo stew stick sting stir stock stool stop storm stove straw stream street strut stuck studio stuff stump stunt subway sugar surf sushi swan sway sweep swell swim swing swipe swirl swoop syrup tablet taco tag take tall task taste tasty thaw theme think thread thumb tiara tidal tidy tiger tile tilt tint tiny trace track trade train travel tray treat tree trek trend trial trick trio trophy trout truck trunk try tug tulip turf turtle tutor tweak tweet twice twins twirl twist uncle undo unify unit untie update upper urban user valley value velvet venue verify verse vest video view violet vista vocal voice volt vowel voyage wafer wagon wake walk walnut wand watch water wavy wheat whoop widen width willow wing wink wipe wise wish wizard wok wolf wool word work woven yam yard year yelp yield yoga yogurt yummy zebra zero zesty zippy zone zoom".split(
+    " "
+  )
+);
+
+// src/public-invites/code.ts
+var INVITE_CODE_PATTERN = /^(?:[a-z]{10}|[a-z]{3}-[a-z]{4}-[a-z]{3})$/;
+function parseInviteCode(value) {
+  const normalized = value.trim().toLowerCase();
+  const words = normalized.split(/[-.\s]+/u);
+  if (words.length === INVITE_WORD_COUNT && words.every((word) => INVITE_WORDS.has(word))) return words.join("-");
+  if (!INVITE_CODE_PATTERN.test(normalized)) return void 0;
+  const code = normalized.replaceAll("-", "");
+  return `${code.slice(0, 3)}-${code.slice(3, 7)}-${code.slice(7)}`;
+}
+
+export {
+  createChalkPublicClient,
+  createChalkPublicInviteClient,
+  parseInviteCode
+};