@wibly/sdk 0.1.0

package/src/client.ts

@@ -0,0 +1,650 @@
+/**
+ * The Studio SDK's `createSession` factory.
+ *
+ * Per chunk B7 build: "client.ts — `createSession({ wsUrl,
+ * sessionId, auth, onConsentRequired })` returns a `Session` with
+ * the typed API used by the Player shell (B6) and any future Studio
+ * SDK consumer."
+ *
+ * The factory composes the dependencies — transport, store,
+ * event bus, lifecycle bindings — into a single `Session` value and
+ * is the only place anything in the SDK constructs a transport or a
+ * store. Consumers never see the internals; they get a documented
+ * surface.
+ *
+ * **Single store per session.** The chunk-B7 trap is "do not let the
+ * AI inline state stores per call site". The factory enforces it:
+ * the returned `Session.store` is a getter that reads from the
+ * factory-owned store. React hooks (in `react.ts`) read from the
+ * same store via `useSyncExternalStore`.
+ *
+ * **Auth pass-through.** The `auth` field is the bearer token the
+ * Runtime expects on the WebSocket subprotocol (chunk B8a). It is
+ * threaded into the WebSocket URL's `Sec-WebSocket-Protocol` header
+ * the way `apps-shells/player-web` already does. The SDK never
+ * logs it.
+ *
+ * **Consent callback.** When the Runtime emits a `consent_required`
+ * event, the SDK calls the registered callback and (on
+ * `accepted`) calls `session.requestConsent(...)` to forward the
+ * grant to the User Portal endpoint (chunk B17a).
+ */
+
+import { ok, type Result } from '@wibly/internal-shared';
+import type {
+  ErrorPayload,
+  EventPayload,
+  LifecyclePayload,
+  MessageId,
+  ServerMessage,
+  SessionId,
+  StateDiffPayload,
+} from '@wibly/internal-protocol';
+
+import {
+  CONSENT_REQUIRED_EVENT_TYPE,
+  type ConsentDecision,
+  type ConsentRequiredCallback,
+  type ConsentRequiredPayload,
+} from './consent.js';
+import { createEventBus, type EventBus } from './events.js';
+import {
+  createLifecycleBindings,
+  type LifecycleBindings,
+} from './lifecycle.js';
+import { createSessionStore, type SessionStore } from './store.js';
+import {
+  buildEmitPayload,
+  buildSubmitPayload,
+  type EmitArgs,
+  type PendingSubmit,
+  type SubmitArgs,
+} from './submit.js';
+import { buildHostEmitPayload, HOST_EVENT_TYPES } from './control.js';
+import {
+  buildInferenceRequest,
+  type InferenceCallInput,
+  type SessionInference,
+  INFERENCE_EVENT_PREFIX,
+} from './inference.js';
+import {
+  type SessionVoice,
+  type SpeakSuccess,
+  VOICE_EVENT_PREFIX,
+} from './voice.js';
+import {
+  createServerTimeSource,
+  type ServerTimeSource,
+} from './time.js';
+import {
+  createTransport,
+  type Transport,
+  type TransportConfig,
+  type WebSocketFactory,
+} from './transport.js';
+import { registerProjection } from './predictive.js';
+import { formatSdkError, type SdkError } from './errors.js';
+import type { ZodTypeAny } from 'zod';
+import type { ConnectionState, OptimisticProjection } from './store.js';
+import type {
+  InferenceCallSuccess,
+} from './inference.js';
+
+export type SessionConfig = {
+  readonly wsUrl: string;
+  readonly sessionId: SessionId;
+  readonly auth?: string;
+  readonly onConsentRequired?: ConsentRequiredCallback;
+  /** Test seam — pass a fake WebSocket constructor. */
+  readonly factory?: WebSocketFactory;
+  /** Test seam for transport timing. */
+  readonly schedule?: TransportConfig['schedule'];
+  /** Test seam for `Math.random` (used in backoff jitter). */
+  readonly random?: () => number;
+  /** Test seam for `Date.now`. */
+  readonly now?: () => number;
+  /**
+   * Submit confirmation timeout. Default 30s. See `submit.ts`.
+   */
+  readonly submitTimeoutMs?: number;
+  /**
+   * Persistence endpoint for accepted consents. When the player
+   * accepts a consent prompt, the SDK invokes `persistConsent` to
+   * write the grant. Chunk B17a wires the real implementation
+   * against the User Portal; MVP leaves it `undefined` and
+   * `requestConsent` returns `consent_persistence_not_wired`.
+   */
+  readonly persistConsent?: (
+    payload: ConsentRequiredPayload,
+  ) => Promise<Result<void, SdkError>>;
+};
+
+export type SessionState = {
+  readonly connectionState: ConnectionState;
+  /** Authoritative server projection. */
+  readonly state: unknown;
+  /** Projected state — server + active optimistic projections. */
+  readonly projectedState: unknown;
+  /** Last applied server seq. */
+  readonly appliedSeq: number;
+  /** Current phase id from the most recent snapshot. */
+  readonly phaseId: string | null;
+};
+
+export type Session = {
+  readonly sessionId: SessionId;
+  /** Current snapshot — calling getter triggers no work. */
+  readonly getState: () => SessionState;
+  /** Reactive subscription. The callback fires on store changes. */
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Submit an Active input. */
+  readonly submit: (args: SubmitArgs) => PendingSubmit;
+  /** Emit a non-Active wire event. */
+  readonly emit: (args: EmitArgs) => Result<{ readonly id: string }, SdkError>;
+  /** Host-only control verbs. The Runtime gates host privilege. */
+  readonly host: {
+    readonly pause: () => Result<{ readonly id: string }, SdkError>;
+    readonly resume: () => Result<{ readonly id: string }, SdkError>;
+    readonly advancePhase: (
+      detail?: unknown,
+    ) => Result<{ readonly id: string }, SdkError>;
+    readonly reclaim: () => Result<{ readonly id: string }, SdkError>;
+  };
+  readonly inference: SessionInference;
+  readonly voice: SessionVoice;
+  readonly events: Pick<EventBus, 'onEvent' | 'onAnyEvent'>;
+  readonly lifecycle: LifecycleBindings;
+  /** Server-time helper. See `time.ts`. */
+  readonly time: Pick<ServerTimeSource, 'serverNow' | 'recordEvent'>;
+  /** Internal — the live store; exported for `react.ts`. */
+  readonly store: SessionStore;
+  /**
+   * Forward an accepted consent decision to the persistence path.
+   * Returns `consent_persistence_not_wired` until chunk B17a binds
+   * the User Portal endpoint.
+   */
+  readonly requestConsent: (
+    payload: ConsentRequiredPayload,
+  ) => Promise<Result<void, SdkError>>;
+  /** Close the underlying WebSocket and dispose subscriptions. */
+  readonly close: () => void;
+};
+
+type PendingRecord = {
+  readonly id: MessageId;
+  readonly resolve: (r: Result<void, SdkError>) => void;
+  readonly projectionId?: string;
+  readonly timer?: () => void;
+};
+
+export const createSession = (config: SessionConfig): Session => {
+  const store = createSessionStore();
+  const bus = createEventBus();
+  const time = createServerTimeSource({ now: config.now });
+  const lifecycle = createLifecycleBindings(bus);
+  const pendingSubmits = new Map<MessageId, PendingRecord>();
+  const pendingInference = new Map<
+    MessageId,
+    (r: Result<unknown, SdkError>) => void
+  >();
+  const pendingVoice = new Map<
+    MessageId,
+    (r: Result<unknown, SdkError>) => void
+  >();
+
+  const handleStateDiff = (payload: StateDiffPayload): void => {
+    const action = store.applyDiff(
+      payload.patches,
+      payload.fromSeq,
+      payload.toSeq,
+    );
+    if (action === 'resync_required') {
+      // The seq window slipped — ask the Runtime for a fresh
+      // snapshot. The transport's `resubscribe` reuses the current
+      // resumeFromSeq; the server falls back to `snapshot` when it
+      // can't satisfy the resume from its buffer.
+      transport.resubscribe();
+    }
+  };
+
+  const handleEvent = (payload: EventPayload): void => {
+    bus.dispatchEvent(payload);
+    if (payload.eventType.startsWith(INFERENCE_EVENT_PREFIX)) {
+      maybeResolveInference(payload);
+    } else if (payload.eventType.startsWith(VOICE_EVENT_PREFIX)) {
+      maybeResolveVoice(payload);
+    } else if (payload.eventType === CONSENT_REQUIRED_EVENT_TYPE) {
+      maybeHandleConsent(payload);
+    }
+  };
+
+  const handleLifecycle = (payload: LifecyclePayload): void => {
+    bus.dispatchLifecycle(payload);
+  };
+
+  const handleError = (payload: ErrorPayload): void => {
+    if (payload.causeMessageId === undefined) return;
+    const causeId = payload.causeMessageId as unknown as MessageId;
+    const submit = pendingSubmits.get(causeId);
+    if (submit !== undefined) {
+      if (submit.projectionId !== undefined) {
+        store.removeProjection(submit.projectionId);
+      }
+      submit.timer?.();
+      pendingSubmits.delete(causeId);
+      submit.resolve({
+        ok: false,
+        error: {
+          kind: 'submit_rejected',
+          code: payload.code,
+          message: payload.message,
+          causeMessageId: causeId,
+        },
+      });
+      transport.confirmSend(causeId);
+      return;
+    }
+    const infer = pendingInference.get(causeId);
+    if (infer !== undefined) {
+      pendingInference.delete(causeId);
+      transport.confirmSend(causeId);
+      infer({
+        ok: false,
+        error: {
+          kind: 'submit_rejected',
+          code: payload.code,
+          message: payload.message,
+          causeMessageId: causeId,
+        },
+      });
+      return;
+    }
+    const voice = pendingVoice.get(causeId);
+    if (voice !== undefined) {
+      pendingVoice.delete(causeId);
+      transport.confirmSend(causeId);
+      voice({
+        ok: false,
+        error: {
+          kind: 'submit_rejected',
+          code: payload.code,
+          message: payload.message,
+          causeMessageId: causeId,
+        },
+      });
+    }
+  };
+
+  const transport: Transport = createTransport(
+    {
+      url: buildUrl(config),
+      sessionId: config.sessionId,
+      ...(config.factory ? { factory: config.factory } : {}),
+      ...(config.schedule ? { schedule: config.schedule } : {}),
+      ...(config.random ? { random: config.random } : {}),
+      ...(config.now ? { now: config.now } : {}),
+    },
+    {
+      onServerMessage: (msg: ServerMessage) => {
+        switch (msg.kind) {
+          case 'snapshot':
+            store.applySnapshot(
+              msg.payload.state,
+              msg.payload.phaseId,
+              msg.payload.baseSeq,
+            );
+            break;
+          case 'state_diff':
+            handleStateDiff(msg.payload);
+            // A state_diff implicitly confirms every pending submit
+            // whose id <= toSeq's caused-by set (which we can't see
+            // from this side). For MVP we resolve the *oldest*
+            // pending submit on each diff; the chunk B8a Runtime
+            // emits a dedicated `submit.confirmed` event on the same
+            // wire kind that supersedes this heuristic once it ships.
+            confirmOldestPendingSubmit();
+            break;
+          case 'event':
+            handleEvent(msg.payload);
+            break;
+          case 'lifecycle':
+            handleLifecycle(msg.payload);
+            break;
+          case 'error':
+            handleError(msg.payload);
+            break;
+          case 'pong': {
+            const echo = msg.payload.echoTs;
+            const now = (config.now ?? Date.now)();
+            // Clock skew estimate: midpoint of round trip.
+            time.updateSkew(Math.round(msg.ts - (now + echo) / 2));
+            break;
+          }
+        }
+      },
+      onDecodeError: () => {
+        // Drop silently. The Runtime emits well-formed frames; a
+        // decode failure here is either a corrupt buffer or a
+        // forward-compat artifact. Either way the SDK can't
+        // recover from a malformed frame.
+      },
+      onConnectionState: (next) => {
+        store.setConnectionState(next);
+      },
+      onReconnectReady: () => {
+        // The transport's onopen handler already sent the subscribe.
+        // Hook reserved for future bootstrap; intentionally empty.
+      },
+      getResumeFromSeq: () => {
+        const snap = store.getSnapshot();
+        return snap.appliedSeq > 0 ? snap.appliedSeq : undefined;
+      },
+    },
+  );
+
+  const confirmOldestPendingSubmit = (): void => {
+    const next = pendingSubmits.entries().next();
+    if (next.done) return;
+    const [id, record] = next.value;
+    if (record.projectionId !== undefined) {
+      store.removeProjection(record.projectionId);
+    }
+    record.timer?.();
+    pendingSubmits.delete(id);
+    transport.confirmSend(id);
+    record.resolve(ok(undefined));
+  };
+
+  const maybeResolveInference = (payload: EventPayload): void => {
+    const data = payload.data as { causeMessageId?: string } | null;
+    if (!data || typeof data.causeMessageId !== 'string') return;
+    const causeId = data.causeMessageId as unknown as MessageId;
+    const cb = pendingInference.get(causeId);
+    if (cb === undefined) return;
+    pendingInference.delete(causeId);
+    transport.confirmSend(causeId);
+    cb(ok(payload.data));
+  };
+
+  const maybeResolveVoice = (payload: EventPayload): void => {
+    const data = payload.data as { causeMessageId?: string } | null;
+    if (!data || typeof data.causeMessageId !== 'string') return;
+    const causeId = data.causeMessageId as unknown as MessageId;
+    const cb = pendingVoice.get(causeId);
+    if (cb === undefined) return;
+    pendingVoice.delete(causeId);
+    transport.confirmSend(causeId);
+    cb(ok(payload.data));
+  };
+
+  const maybeHandleConsent = (payload: EventPayload): void => {
+    if (config.onConsentRequired === undefined) return;
+    const data = payload.data as ConsentRequiredPayload | null;
+    if (!data || typeof data !== 'object') return;
+    void (async () => {
+      let decision: ConsentDecision = 'declined';
+      try {
+        decision = await config.onConsentRequired!(data);
+      } catch {
+        decision = 'declined';
+      }
+      if (decision !== 'accepted') return;
+      const result = await session.requestConsent(data);
+      // The bridge informs the runtime of the outcome via an
+      // `emit('consent.decision', …)`. The Runtime forwards the
+      // grant to the Persona Service (chunk B3) on its next read.
+      transport.send(
+        'emit',
+        buildEmitPayload(config.sessionId, {
+          eventType: 'consent.decision',
+          data: {
+            personaId: data.personaId,
+            scope: data.scope,
+            decision,
+            persistOk: result.ok,
+            persistError: result.ok ? null : result.error.kind,
+          },
+        }),
+      );
+    })();
+  };
+
+  const session: Session = {
+    sessionId: config.sessionId,
+    getState: () => {
+      const snap = store.getSnapshot();
+      return {
+        connectionState: snap.connectionState,
+        state: snap.state,
+        projectedState: store.getProjectedState(),
+        appliedSeq: snap.appliedSeq,
+        phaseId: snap.phaseId,
+      };
+    },
+    subscribe: (listener) => store.subscribe(listener),
+    submit: (args) => {
+      const payload = buildSubmitPayload(config.sessionId, args);
+      const sent = transport.send('submit', payload);
+      const id = sent.id;
+      let projectionId: string | undefined;
+      if (args.predictive !== undefined) {
+        projectionId = id as unknown as string;
+        registerProjection(
+          store,
+          projectionId,
+          args.predictive as OptimisticProjection,
+        );
+      }
+      let resolveFn!: (r: Result<void, SdkError>) => void;
+      const promise = new Promise<Result<void, SdkError>>((res) => {
+        resolveFn = res;
+      });
+      const timeoutMs = args.timeoutMs ?? config.submitTimeoutMs ?? 30_000;
+      const timer = scheduleTimeout(timeoutMs, () => {
+        if (!pendingSubmits.has(id)) return;
+        const record = pendingSubmits.get(id);
+        pendingSubmits.delete(id);
+        if (record?.projectionId !== undefined) {
+          store.removeProjection(record.projectionId);
+        }
+        resolveFn({ ok: false, error: { kind: 'timeout' } });
+      });
+      pendingSubmits.set(id, {
+        id,
+        resolve: resolveFn,
+        ...(projectionId ? { projectionId } : {}),
+        timer,
+      });
+      return {
+        id: id as unknown as string,
+        promise,
+        cancel: () => {
+          const record = pendingSubmits.get(id);
+          if (record === undefined) return;
+          pendingSubmits.delete(id);
+          if (record.projectionId !== undefined) {
+            store.removeProjection(record.projectionId);
+          }
+          record.timer?.();
+          resolveFn({ ok: false, error: { kind: 'timeout' } });
+        },
+      };
+    },
+    emit: (args) => {
+      const payload = buildEmitPayload(config.sessionId, args);
+      const sent = transport.send('emit', payload);
+      return ok({ id: sent.id as unknown as string });
+    },
+    host: {
+      pause: () => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.pause,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
+      resume: () => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.resume,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
+      advancePhase: (detail?: unknown) => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.advancePhase,
+          detail ?? {},
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
+      reclaim: () => {
+        const payload = buildHostEmitPayload(
+          config.sessionId,
+          HOST_EVENT_TYPES.reclaim,
+        );
+        const sent = transport.send('emit', payload);
+        return ok({ id: sent.id as unknown as string });
+      },
+    },
+    inference: buildInferenceVerbs(
+      config.sessionId,
+      transport,
+      pendingInference,
+    ),
+    voice: buildVoiceVerbs(config.sessionId, transport, pendingVoice),
+    events: { onEvent: bus.onEvent, onAnyEvent: bus.onAnyEvent },
+    lifecycle,
+    time: { serverNow: time.serverNow, recordEvent: time.recordEvent },
+    store,
+    requestConsent: async (payload) => {
+      if (config.persistConsent === undefined) {
+        return { ok: false, error: { kind: 'consent_persistence_not_wired' } };
+      }
+      return config.persistConsent(payload);
+    },
+    close: () => {
+      transport.close(1000, 'sdk close');
+      for (const [, record] of pendingSubmits) {
+        record.timer?.();
+        record.resolve({ ok: false, error: { kind: 'not_connected' } });
+      }
+      pendingSubmits.clear();
+      for (const [, cb] of pendingInference) {
+        cb({ ok: false, error: { kind: 'not_connected' } });
+      }
+      pendingInference.clear();
+      for (const [, cb] of pendingVoice) {
+        cb({ ok: false, error: { kind: 'not_connected' } });
+      }
+      pendingVoice.clear();
+      bus.dispose();
+    },
+  };
+
+  transport.start();
+  return session;
+};
+
+/**
+ * Build a wire-form URL with the bearer token threaded onto the
+ * query string. The Runtime accepts the token via either
+ * `Sec-WebSocket-Protocol` or `?token=` for browser compatibility
+ * (browsers can't set arbitrary request headers on `new WebSocket`).
+ *
+ * The token is excluded from any URL the SDK logs — `formatSdkError`
+ * never includes it. Operators should still treat the URL as
+ * sensitive.
+ */
+const buildUrl = (config: SessionConfig): string => {
+  if (config.auth === undefined) return config.wsUrl;
+  const sep = config.wsUrl.includes('?') ? '&' : '?';
+  return `${config.wsUrl}${sep}token=${encodeURIComponent(config.auth)}`;
+};
+
+const scheduleTimeout = (
+  ms: number,
+  cb: () => void,
+): (() => void) => {
+  const handle = setTimeout(cb, ms);
+  return () => clearTimeout(handle);
+};
+
+const buildInferenceVerbs = (
+  sessionId: SessionId,
+  transport: Transport,
+  pending: Map<MessageId, (r: Result<unknown, SdkError>) => void>,
+): SessionInference => {
+  const call = async <TOutput extends ZodTypeAny>(
+    input: InferenceCallInput<TOutput>,
+  ): Promise<Result<InferenceCallSuccess<TOutput>, SdkError>> => {
+    const serialised = buildInferenceRequest(input);
+    let resolveFn!: (r: Result<unknown, SdkError>) => void;
+    const promise = new Promise<Result<unknown, SdkError>>((res) => {
+      resolveFn = res;
+    });
+    const sent = transport.send('emit', {
+      sessionId,
+      eventType: `${INFERENCE_EVENT_PREFIX}${input.callKind}`,
+      data: serialised,
+    });
+    pending.set(sent.id, resolveFn);
+    // Until chunk B8a wires the runtime, the call never resolves
+    // organically. Emit a runtime_not_wired error after a tick so
+    // the surface is observable without flapping.
+    setTimeout(() => {
+      const cb = pending.get(sent.id);
+      if (cb === undefined) return;
+      pending.delete(sent.id);
+      transport.confirmSend(sent.id);
+      cb({ ok: false, error: { kind: 'runtime_not_wired' } });
+    }, 0);
+    const result = await promise;
+    return result as Result<InferenceCallSuccess<TOutput>, SdkError>;
+  };
+  return {
+    call,
+    host: (input) => call({ ...input, callKind: 'host_open_phase' }),
+    judge: (input) => call({ ...input, callKind: 'judge_submissions' }),
+    classify: (input) => call({ ...input, callKind: 'classify' }),
+  };
+};
+
+const buildVoiceVerbs = (
+  sessionId: SessionId,
+  transport: Transport,
+  pending: Map<MessageId, (r: Result<unknown, SdkError>) => void>,
+): SessionVoice => ({
+  speak: async (input) => {
+    let resolveFn!: (r: Result<unknown, SdkError>) => void;
+    const promise = new Promise<Result<unknown, SdkError>>((res) => {
+      resolveFn = res;
+    });
+    const sent = transport.send('emit', {
+      sessionId,
+      eventType: `${VOICE_EVENT_PREFIX}speak`,
+      data: {
+        personaId: input.personaId,
+        text: input.text,
+        options: input.options ?? {},
+        caption: input.caption === null ? null : (input.caption ?? input.text),
+      },
+    });
+    pending.set(sent.id, resolveFn);
+    setTimeout(() => {
+      const cb = pending.get(sent.id);
+      if (cb === undefined) return;
+      pending.delete(sent.id);
+      transport.confirmSend(sent.id);
+      cb({ ok: false, error: { kind: 'runtime_not_wired' } });
+    }, 0);
+    const result = await promise;
+    return result as Result<SpeakSuccess, SdkError>;
+  },
+});
+
+// Re-export for consumers that want to format SdkError directly.
+export { formatSdkError };