@ziprack/sdk 0.1.0

package/dist/activity/index.d.ts

@@ -0,0 +1,37 @@
+import type { Link } from '../core/link';
+import type { AckResult, JsonObject, LaunchActivity } from '../core/types';
+export interface StatementInput {
+    verb: string;
+    activity: {
+        id: string;
+        type?: string;
+    };
+    result?: JsonObject;
+    context?: JsonObject;
+    occurred_at?: string;
+}
+export interface AnswerOptions {
+    type?: string;
+    context?: JsonObject;
+}
+/**
+ * activity@1 — append-only statements. Answers are statements, not state.
+ */
+export declare class ActivityApi {
+    private readonly link;
+    constructor(link: Link);
+    /** The manifest's declared activities for this version. */
+    activities(): LaunchActivity[];
+    activity(id: string): LaunchActivity | null;
+    statement(input: StatementInput): Promise<AckResult<{
+        id: string;
+    }>>;
+    /** `answered` statement with the value in result.response — the only field reporting reads. */
+    answer(activityId: string, response: unknown, options?: AnswerOptions): Promise<AckResult<{
+        id: string;
+    }>>;
+    /** `progressed` statement with activity.type = 'step'. */
+    progress(stepId: string, context?: JsonObject): Promise<AckResult<{
+        id: string;
+    }>>;
+}

package/dist/ai/index.d.ts

@@ -0,0 +1,41 @@
+import type { Link } from '../core/link';
+import type { AckResult, JsonObject } from '../core/types';
+export interface Usage {
+    input_tokens: number;
+    output_tokens: number;
+}
+export interface ChatReply {
+    message_id: string;
+    text: string;
+    usage: Usage;
+}
+export declare class Chat {
+    private readonly link;
+    readonly promptId: string;
+    constructor(link: Link, promptId: string);
+    /**
+     * Send a participant message. onDelta receives text as it streams; the
+     * resolved result carries the full text.
+     */
+    send(message: string, onDelta?: (delta: string, soFar: string) => void): Promise<AckResult<ChatReply>>;
+    reset(): Promise<AckResult>;
+}
+/**
+ * ai@1 — declared prompt templates. The applet supplies variables, never
+ * instructions; model, prompt and budget are Rack-owned.
+ */
+export declare class AiApi {
+    private readonly link;
+    constructor(link: Link);
+    prompts(): Array<{
+        id: string;
+        mode: 'analysis' | 'chat';
+    }>;
+    /** Analysis prompt: structured JSON conforming to the declared output_schema. */
+    ask<T extends object = JsonObject>(promptId: string, vars?: JsonObject): Promise<AckResult<{
+        output: T;
+        usage: Usage;
+    }>>;
+    /** Chat prompt: conversation history is held by the Rack. */
+    chat(promptId: string): Chat;
+}

package/dist/attempt/index.d.ts

@@ -0,0 +1,27 @@
+import type { Link } from '../core/link';
+import type { AckResult, AttemptStatus, JsonObject, LaunchAttempt } from '../core/types';
+/**
+ * attempt@1 — lifecycle, resume state, completion. Declaring it also pins
+ * every participant to the version they started on.
+ */
+export declare class AttemptApi {
+    private readonly link;
+    private local;
+    constructor(link: Link);
+    /** The attempt as launched, with local updates applied. */
+    current(): LaunchAttempt | null;
+    get status(): AttemptStatus | null;
+    get id(): number | null;
+    /** Resume state exactly as last saved. */
+    state<T extends object = JsonObject>(): T | null;
+    segment(): Record<string, string> | null;
+    /** Save resume state (max 64 KB). Send after every transition; the shell coalesces bursts. */
+    setState(state: JsonObject): Promise<AckResult>;
+    /** Set segment dimensions (max 20 keys, string values). */
+    setSegment(segment: Record<string, string>): Promise<AckResult>;
+    /** Mark the attempt completed. Idempotent. */
+    complete(summary?: JsonObject): Promise<AckResult<{
+        status: AttemptStatus;
+        completed_at: string | null;
+    }>>;
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,14 @@
+import type { Link } from '../core/link';
+import type { LaunchUser } from '../core/types';
+/**
+ * auth@1 — who the participant is and the profile attributes the Rack chose to
+ * release. Attributes the manifest requested but the Rack withheld are simply
+ * absent; degrade gracefully.
+ */
+export declare class AuthApi {
+    private readonly link;
+    constructor(link: Link);
+    user(): LaunchUser | null;
+    /** A released profile attribute, or the fallback when withheld. */
+    attribute<T = unknown>(key: string, fallback?: T | null): T | null;
+}

package/dist/broadcast/index.d.ts

@@ -0,0 +1,81 @@
+import type { Link } from '../core/link';
+import type { AckResult, JsonObject, LaunchRoom, RackEvent, RoomMember, RoomRole, RoomStatus } from '../core/types';
+export declare const ROOM_CHANNEL = "$room";
+export type RoomEventName = 'presence' | 'state' | 'role' | 'status';
+export interface RoomEvents {
+    presence: {
+        members: RoomMember[];
+    };
+    state: {
+        key: string;
+        value: unknown;
+        version: number;
+    };
+    role: {
+        role: RoomRole;
+        participant_id: number;
+    };
+    status: {
+        status: RoomStatus;
+    };
+}
+export declare class Channel {
+    private readonly link;
+    readonly name: string;
+    private readonly listeners;
+    private unsubscribe;
+    constructor(link: Link, name: string);
+    /** @internal */
+    attach(): void;
+    /** Listen for an event on this channel ('*' for all). Returns an unsubscribe function. */
+    listen<T = unknown>(event: string, callback: (payload: T, from: RackEvent['from']) => void): () => void;
+    /** Publish to everyone in the room. Facilitator-only events are enforced by the Rack. */
+    publish(event: string, payload?: unknown): Promise<AckResult>;
+    leave(): Promise<AckResult>;
+}
+/**
+ * broadcast@1 — rooms, presence, facilitator control and shared state. The
+ * Rack holds the WebSocket; the applet only ever sees postMessage.
+ */
+export declare class BroadcastApi {
+    private readonly link;
+    private readonly channels;
+    private readonly roomListeners;
+    private localRole;
+    private localMembers;
+    private localState;
+    private detach;
+    constructor(link: Link);
+    get room(): LaunchRoom | null;
+    get role(): RoomRole | null;
+    get isFacilitator(): boolean;
+    members(): RoomMember[];
+    /** Join a named channel within the room (default "main"). */
+    join(channel?: string): Promise<Channel>;
+    /** Who is in the room, by role. */
+    presence(): Promise<AckResult<{
+        members: RoomMember[];
+    }>>;
+    readonly state: {
+        /** Server-arbitrated shared state. */
+        get: (keys?: string[]) => Promise<AckResult<{
+            state: JsonObject;
+        }>>;
+        /** Last write wins at the key; the Rack stamps the version. */
+        set: (key: string, value: unknown) => Promise<AckResult<{
+            version: number;
+        }>>;
+        /** Locally known state (launch snapshot plus pushed updates). */
+        snapshot: () => JsonObject;
+    };
+    /** Claim the facilitator role (opt_in rooms). */
+    claim(): Promise<AckResult<{
+        role: RoomRole;
+    }>>;
+    /** Hand the facilitator role to another member. */
+    transfer(participantId: number): Promise<AckResult>;
+    /** Room-level events: presence, state, role, status. */
+    on<K extends RoomEventName>(event: K, callback: (payload: RoomEvents[K]) => void): () => void;
+    private launch;
+    private ensureRoomListener;
+}

package/dist/core/bridge.d.ts

@@ -0,0 +1,39 @@
+import type { AckResult, JsonObject, LaunchData, RackEvent, SendOptions, Transport } from './types';
+export interface BridgeOptions {
+    ackTimeoutMs: number;
+    /** Window-like object to post to. Defaults to window.parent. */
+    target?: Pick<Window, 'postMessage'>;
+    /** Whether a MessageEvent came from the host. Defaults to event.source === window.parent. */
+    isHost?: (source: MessageEventSource | null) => boolean;
+    /** Where to listen for messages. Defaults to window. */
+    listenOn?: Pick<Window, 'addEventListener' | 'removeEventListener'>;
+}
+/**
+ * postMessage transport used inside the Rack's iframe.
+ *
+ * Only messages whose source is the parent window are honoured; the applet
+ * never inspects event.origin because its own origin is opaque by design.
+ */
+export declare class HostBridge implements Transport {
+    private readonly options;
+    readonly kind: "host";
+    private readonly pending;
+    private readonly eventListeners;
+    private launchResolvers;
+    private launchData;
+    private readonly target;
+    private readonly isHost;
+    private readonly listenOn;
+    private readonly listener;
+    constructor(options: BridgeOptions);
+    announceReady(): void;
+    waitForLaunch(timeoutMs: number): Promise<LaunchData | null>;
+    send<T = JsonObject>(type: string, payload: unknown, options?: SendOptions): Promise<AckResult<T>>;
+    fire(type: string, payload?: unknown): void;
+    onEvent(listener: (event: RackEvent) => void): () => void;
+    dispose(): void;
+    private expire;
+    private post;
+    private onMessage;
+    private onAck;
+}

package/dist/core/link.d.ts

@@ -0,0 +1,14 @@
+import type { AckResult, JsonObject, LaunchData, RackEvent, SendOptions } from './types';
+/**
+ * What a capability module needs from the client: send/fire, the launch data,
+ * event subscription and the declared-capability check.
+ */
+export interface Link {
+    send<T = JsonObject>(type: string, payload: unknown, options?: SendOptions): Promise<AckResult<T>>;
+    fire(type: string, payload?: unknown): void;
+    launch(): LaunchData | null;
+    declares(capability: string): boolean;
+    onEvent(listener: (event: RackEvent) => void): () => void;
+    mode(): 'host' | 'mock' | 'pending';
+}
+export declare function notDeclared<T = JsonObject>(capability: string): AckResult<T>;

package/dist/core/mock/MockRack.d.ts

@@ -0,0 +1,141 @@
+import type { AckResult, JsonObject, LaunchData, RackEvent, RoomMember, RoomRole } from '../types';
+import type { RecordRow } from '../../db';
+import type { StoredFile } from '../../storage';
+import type { Store } from './store';
+export interface MockManifest {
+    schema?: string;
+    slug: string;
+    name: string;
+    version: string;
+    requires?: {
+        capabilities?: string[];
+        profile?: string[];
+    };
+    media?: Array<{
+        id: string;
+        provider: string;
+        key: string;
+    }>;
+    activities?: Array<{
+        id: string;
+        type: string;
+        label: string;
+        scale?: unknown;
+        segment?: string | null;
+        sequence?: number;
+    }>;
+    collections?: Array<{
+        name: string;
+        scope: string;
+        schema?: JsonObject;
+    }>;
+    uploads?: Array<{
+        name: string;
+        scope: string;
+        mime?: string[];
+        max_bytes?: number;
+    }>;
+    prompts?: Array<{
+        id: string;
+        mode: 'analysis' | 'chat';
+        output_schema?: JsonObject;
+    }>;
+    broadcast?: {
+        facilitator_events?: string[];
+        channels?: string[];
+        mock_mode?: 'first_in' | 'opt_in';
+    };
+    [key: string]: unknown;
+}
+export type AiMockHandler = (vars: JsonObject, mode: 'analysis' | 'chat', message?: string) => unknown | Promise<unknown>;
+export interface MockRackOptions {
+    /** Whether undeclared capabilities are refused, as a real Rack would. Default true when a manifest is present. */
+    strict?: boolean;
+    log?: (type: string, payload: unknown) => void;
+    participantId?: number;
+    participantName?: string;
+    /** Force the mock room role instead of deriving it from the assignment mode. */
+    role?: RoomRole;
+}
+export type MockOutcome = AckResult | {
+    stream: AsyncIterable<JsonObject>;
+    final: () => JsonObject;
+};
+/**
+ * An in-memory Rack that services every capability so an applet can be built
+ * and QA'd standalone. Shared by the browser mock transport (localStorage) and
+ * the testing FakeHost (memory).
+ */
+export declare class MockRack {
+    readonly manifest: MockManifest | null;
+    private readonly store;
+    private readonly options;
+    readonly participantId: number;
+    readonly participantName: string;
+    readonly statements: Array<JsonObject & {
+        id: string;
+    }>;
+    readonly events: RackEvent[];
+    private readonly aiHandlers;
+    private readonly chatHistory;
+    private readonly blobs;
+    private readonly eventListeners;
+    private readonly roomMembers;
+    private roomState;
+    private role;
+    private readonly joinedAt;
+    private channel;
+    private heartbeat;
+    constructor(manifest: MockManifest | null, store: Store, options?: MockRackOptions);
+    get slug(): string;
+    private key;
+    declares(capability: string): boolean;
+    onEvent(listener: (event: RackEvent) => void): () => void;
+    pushEvent(event: RackEvent): void;
+    launchData(nameHint?: string): LaunchData;
+    mockAi(promptId: string, handler: AiMockHandler): void;
+    dispose(): void;
+    handle(type: string, payload: JsonObject): Promise<MockOutcome>;
+    attempt(): NonNullable<LaunchData['attempt']>;
+    private saveAttempt;
+    private attemptState;
+    private attemptSegment;
+    private attemptComplete;
+    /** Clear a completed mock attempt so the experience can be run again. */
+    resetAttempt(): void;
+    private statement;
+    private collectionKey;
+    records(collection: string): RecordRow[];
+    private saveRecords;
+    private collectionDeclared;
+    private dbCreate;
+    private dbGet;
+    private dbUpdate;
+    private dbDelete;
+    private filter;
+    private dbList;
+    private dbCount;
+    files(): StoredFile[];
+    private storagePut;
+    private storageUrl;
+    private storageList;
+    private storageDelete;
+    private prompt;
+    private aiAsk;
+    private aiChat;
+    private member;
+    members(): RoomMember[];
+    private stateSnapshot;
+    private send;
+    private joinRoom;
+    /** An earlier facilitator wins; a later optimistic one steps down. */
+    private reconcileFacilitator;
+    private onRoomMessage;
+    private setRole;
+    private publish;
+    private stateSet;
+    private claim;
+    private transfer;
+}
+/** A plausible object for an analysis prompt's output_schema, so UIs render in mock mode. */
+export declare function stubFromSchema(schema: JsonObject | undefined, vars: JsonObject): unknown;

package/dist/core/mock/MockTransport.d.ts

@@ -0,0 +1,14 @@
+import type { AckResult, JsonObject, RackEvent, SendOptions, Transport } from '../types';
+import type { MockRack } from './MockRack';
+/**
+ * Transport that fulfils every message locally through a MockRack.
+ */
+export declare class MockTransport implements Transport {
+    readonly rack: MockRack;
+    readonly kind: "mock";
+    constructor(rack: MockRack);
+    send<T = JsonObject>(type: string, payload: unknown, options?: SendOptions): Promise<AckResult<T>>;
+    fire(type: string, payload?: unknown): void;
+    onEvent(listener: (event: RackEvent) => void): () => void;
+    dispose(): void;
+}

package/dist/core/mock/store.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Key/value persistence for the mock Rack. localStorage in the browser so a
+ * standalone session survives a refresh; memory in tests.
+ */
+export interface Store {
+    get<T>(key: string): T | null;
+    set(key: string, value: unknown): void;
+    remove(key: string): void;
+    keys(prefix: string): string[];
+}
+export declare class MemoryStore implements Store {
+    private readonly data;
+    get<T>(key: string): T | null;
+    set(key: string, value: unknown): void;
+    remove(key: string): void;
+    keys(prefix: string): string[];
+}
+export declare class LocalStore implements Store {
+    get<T>(key: string): T | null;
+    set(key: string, value: unknown): void;
+    remove(key: string): void;
+    keys(prefix: string): string[];
+}

package/dist/core/protocol.d.ts

@@ -0,0 +1,15 @@
+export declare const PROTOCOL_NAMESPACE: "ziprack";
+export declare const PROTOCOL_VERSION: 1;
+export declare const FORMAT: "ziprack/1";
+export interface Envelope<T = unknown> {
+    ns: typeof PROTOCOL_NAMESPACE;
+    v: typeof PROTOCOL_VERSION;
+    type: string;
+    requestId?: string;
+    payload?: T;
+}
+export declare function newRequestId(): string;
+export declare function createEnvelope<T>(type: string, payload?: T, requestId?: string): Envelope<T>;
+export declare function isEnvelope(data: unknown): data is Envelope;
+/** Capability id from a message type ("db:create" -> "db"). */
+export declare function capabilityOf(type: string): string;

package/dist/core/rack.d.ts

@@ -0,0 +1,68 @@
+import { ActivityApi } from '../activity';
+import { AiApi } from '../ai';
+import { AttemptApi } from '../attempt';
+import { AuthApi } from '../auth';
+import { BroadcastApi } from '../broadcast';
+import { DbApi } from '../db';
+import { MediaApi } from '../media';
+import { StorageApi } from '../storage';
+import { MockRack, type AiMockHandler } from './mock/MockRack';
+import type { AckResult, InitOptions, JsonObject, LaunchData, LaunchListener, RackEvent, SendOptions } from './types';
+/**
+ * The SDK entry point. One instance per applet; `Rack` is the default singleton.
+ *
+ * Every capability is a message the Rack services. The applet asks; the Rack
+ * decides, enforces and persists. Nothing here ever throws on a Rack error:
+ * calls resolve to { ok: false, error }.
+ */
+export declare class RackClient {
+    readonly auth: AuthApi;
+    readonly attempt: AttemptApi;
+    readonly activity: ActivityApi;
+    readonly db: DbApi;
+    readonly storage: StorageApi;
+    readonly ai: AiApi;
+    readonly broadcast: BroadcastApi;
+    readonly media: MediaApi;
+    /** Dev-only hooks that only take effect in mock mode. */
+    readonly mock: {
+        /** Answer an ai prompt yourself instead of the schema stub. */
+        ai: (promptId: string, handler: AiMockHandler) => void;
+        /** Clear a completed mock attempt so the experience can be replayed. */
+        resetAttempt: () => void;
+        /** The MockRack when running standalone, else null. */
+        rack: () => MockRack | null;
+    };
+    private transport;
+    private initPromise;
+    private launchData;
+    private readonly queue;
+    private readonly launchListeners;
+    private readonly eventListeners;
+    private pendingAiMocks;
+    constructor();
+    /**
+     * Handshake with the Rack. Resolves with launch data once the Rack answers,
+     * or with mock launch data when running standalone. Safe to call repeatedly.
+     */
+    init(options?: InitOptions): Promise<LaunchData>;
+    get launched(): boolean;
+    get mode(): 'host' | 'mock' | 'pending';
+    getLaunchData(): LaunchData | null;
+    /** Whether the manifest declared a capability (any version). */
+    declares(capability: string): boolean;
+    on(event: 'launch', listener: LaunchListener): () => void;
+    on(event: 'event', listener: (event: RackEvent) => void): () => void;
+    /** Ask the Rack to leave the applet. Needs no capability. */
+    eject(): void;
+    /** Low-level: send any message and await its ack. Capability calls go through the typed APIs. */
+    send<T = JsonObject>(type: string, payload: unknown, options?: SendOptions): Promise<AckResult<T>>;
+    fire(type: string, payload?: unknown): void;
+    /** Tear down (tests). */
+    dispose(): void;
+    private performInit;
+    private activateMock;
+    private activate;
+    private flushQueue;
+    private mockRack;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,155 @@
+export type JsonObject = Record<string, unknown>;
+export type AckErrorCode = 'timeout' | 'disposed' | 'persist_failed' | 'undeclared_capability' | 'unknown_type' | 'validation' | 'forbidden' | 'completed' | 'quota_exceeded' | 'budget_exceeded' | 'not_found' | 'conflict';
+/** Every SDK call resolves to one of these and never throws. */
+export interface AckResult<T = JsonObject> {
+    ok: boolean;
+    data?: T;
+    error?: AckErrorCode | string;
+    message?: string;
+    details?: JsonObject;
+}
+export interface AckPayload extends AckResult {
+    requestId: string;
+    partial?: boolean;
+    done?: boolean;
+    [key: string]: unknown;
+}
+export interface LaunchActor {
+    id: number;
+    name: string;
+}
+export interface LaunchApplet {
+    slug: string;
+    name: string;
+    version: string;
+}
+export interface MediaEmbed {
+    provider: 'vimeo' | 'youtube' | string;
+    embedUrl: string;
+    meta: {
+        title?: string;
+        thumbnail_url?: string;
+        duration?: number;
+        width?: number;
+        height?: number;
+    } | null;
+}
+export type AttemptStatus = 'in_progress' | 'completed';
+export interface LaunchAttempt {
+    id: number;
+    status: AttemptStatus;
+    state: JsonObject | null;
+    segment: Record<string, string> | null;
+}
+export interface LaunchActivity {
+    id: string;
+    type: string;
+    label: string;
+    scale?: unknown;
+    segment?: string | null;
+    sequence?: number;
+}
+export interface LaunchUser {
+    id: number;
+    display_name: string;
+    [attribute: string]: unknown;
+}
+export type RoomStatus = 'open' | 'locked' | 'closed';
+export type RoomRole = 'participant' | 'facilitator';
+export interface RoomMember {
+    id: number;
+    name: string;
+    role: RoomRole;
+    present: boolean;
+}
+export interface LaunchRoom {
+    id: number;
+    code: string;
+    name: string;
+    status: RoomStatus;
+    mode: 'opt_in' | 'first_in' | 'roster';
+}
+export interface LaunchBroadcast {
+    room: LaunchRoom;
+    role: RoomRole;
+    members: RoomMember[];
+    state: JsonObject;
+    channels: string[];
+}
+export interface LaunchData {
+    schema: 'ziprack/1';
+    actor: LaunchActor;
+    applet: LaunchApplet;
+    capabilities: string[];
+    media: Record<string, MediaEmbed>;
+    auth?: {
+        user: LaunchUser;
+    };
+    attempt?: LaunchAttempt;
+    activity?: {
+        activities: LaunchActivity[];
+    };
+    db?: {
+        collections: Array<{
+            name: string;
+            scope: string;
+        }>;
+    };
+    storage?: {
+        uploads: Array<{
+            name: string;
+            scope: string;
+            mime: string[];
+            max_bytes: number;
+        }>;
+    };
+    ai?: {
+        prompts: Array<{
+            id: string;
+            mode: 'analysis' | 'chat';
+        }>;
+    };
+    broadcast?: LaunchBroadcast;
+    [capability: string]: unknown;
+}
+export interface RackEvent<T = unknown> {
+    event: string;
+    payload: T;
+    channel?: string;
+    from?: {
+        participant_id: number;
+        role?: RoomRole;
+    } | null;
+}
+export interface SendOptions {
+    /** Receives each partial chunk of a streamed ack. */
+    onPartial?: (chunk: JsonObject) => void;
+    /** Override the ack timeout for this call (streamed calls reset it per chunk). */
+    timeoutMs?: number;
+}
+/**
+ * Transport abstraction shared by the real host bridge, the standalone mock
+ * and the testing FakeHost.
+ */
+export interface Transport {
+    readonly kind: 'host' | 'mock';
+    send<T = JsonObject>(type: string, payload: unknown, options?: SendOptions): Promise<AckResult<T>>;
+    fire(type: string, payload?: unknown): void;
+    onEvent(listener: (event: RackEvent) => void): () => void;
+    dispose(): void;
+}
+export interface InitOptions {
+    /** Labels the mock session and locates ./manifest.json when running standalone. */
+    slug?: string;
+    /** Milliseconds to wait for rack:launch before falling back to mock mode. */
+    launchTimeoutMs?: number;
+    /** Milliseconds to wait for each rack:ack. */
+    ackTimeoutMs?: number;
+    /** Where the mock loads the manifest from. Default "./manifest.json". */
+    manifestUrl?: string;
+    /** Inject a transport (tests). Skips the host handshake and mock detection. */
+    transport?: Transport;
+    /** Launch data to use with an injected transport. */
+    launch?: LaunchData;
+}
+export type LaunchListener = (data: LaunchData) => void;