@ziprack/sdk 0.1.0

package/dist/db/index.d.ts

@@ -0,0 +1,62 @@
+import { type Link } from '../core/link';
+import type { AckResult, JsonObject } from '../core/types';
+export type WhereOperator = '=' | '!=' | '<' | '<=' | '>' | '>=' | 'in';
+export type WhereClause = [path: string, operator: WhereOperator, value: unknown];
+export interface ListQuery {
+    /** Filters on paths declared in the collection's `indexed` list. */
+    where?: WhereClause[];
+    orderBy?: string;
+    direction?: 'asc' | 'desc';
+    /** Max 100. */
+    limit?: number;
+    cursor?: string | null;
+}
+export interface RecordRow<T extends object = JsonObject> {
+    id: string;
+    data: T;
+    owner_id: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface ListResult<T extends object = JsonObject> {
+    records: RecordRow<T>[];
+    nextCursor: string | null;
+}
+export declare class Collection<T extends object = JsonObject> {
+    private readonly link;
+    readonly name: string;
+    constructor(link: Link, name: string);
+    create(data: T): Promise<AckResult<{
+        record: RecordRow<T>;
+    }>>;
+    get(id: string): Promise<AckResult<{
+        record: RecordRow<T>;
+    }>>;
+    /** Merge by default; pass { merge: false } to replace the whole document. */
+    update(id: string, data: Partial<T>, options?: {
+        merge?: boolean;
+    }): Promise<AckResult<{
+        record: RecordRow<T>;
+    }>>;
+    delete(id: string): Promise<AckResult<{
+        id: string;
+    }>>;
+    list(query?: ListQuery): Promise<AckResult<ListResult<T>>>;
+    count(query?: Pick<ListQuery, 'where'>): Promise<AckResult<{
+        count: number;
+    }>>;
+    private send;
+}
+/**
+ * db@1 — CRUD records in collections the manifest declares, each with a JSON
+ * Schema and a scope (attempt | user | room | applet).
+ */
+export declare class DbApi {
+    private readonly link;
+    constructor(link: Link);
+    collection<T extends object = JsonObject>(name: string): Collection<T>;
+    collections(): Array<{
+        name: string;
+        scope: string;
+    }>;
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { RackClient } from './core/rack';
+export * from './core/types';
+export { PROTOCOL_NAMESPACE, PROTOCOL_VERSION, FORMAT } from './core/protocol';
+export { RackClient } from './core/rack';
+export { HostBridge } from './core/bridge';
+export type { AnswerOptions, StatementInput } from './activity';
+export type { Collection, ListQuery, ListResult, RecordRow, WhereClause, WhereOperator } from './db';
+export type { StoredFile, FileStatus } from './storage';
+export type { Chat, ChatReply, Usage } from './ai';
+export type { Channel, RoomEventName, RoomEvents } from './broadcast';
+export type { MockManifest, AiMockHandler } from './core/mock/MockRack';
+/** The singleton every applet talks through. */
+export declare const Rack: RackClient;
+/** A separate client (tests, or unusual multi-frame setups). */
+export declare function createRack(): RackClient;

package/dist/index.js

@@ -0,0 +1,517 @@
+import { n as f, c as h, i as g, a as u, M as l, b as w, L as b } from "./store-DSV5q7C7.js";
+import { F as K, P as V, d as W } from "./store-DSV5q7C7.js";
+class v {
+  constructor(t) {
+    this.link = t;
+  }
+  /** The manifest's declared activities for this version. */
+  activities() {
+    return this.link.launch()?.activity?.activities ?? [];
+  }
+  activity(t) {
+    return this.activities().find((e) => e.id === t) ?? null;
+  }
+  statement(t) {
+    return this.link.send("activity:statement", {
+      ...t,
+      occurred_at: t.occurred_at ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  /** `answered` statement with the value in result.response — the only field reporting reads. */
+  answer(t, e, s = {}) {
+    return this.statement({
+      verb: "answered",
+      activity: { id: t, type: s.type ?? this.activity(t)?.type },
+      result: { response: e },
+      context: s.context
+    });
+  }
+  /** `progressed` statement with activity.type = 'step'. */
+  progress(t, e) {
+    return this.statement({ verb: "progressed", activity: { id: t, type: "step" }, context: e });
+  }
+}
+class y {
+  constructor(t, e) {
+    this.link = t, this.promptId = e;
+  }
+  /**
+   * Send a participant message. onDelta receives text as it streams; the
+   * resolved result carries the full text.
+   */
+  async send(t, e) {
+    let s = "";
+    const n = await this.link.send("ai:chat", { prompt: this.promptId, message: t }, {
+      timeoutMs: 6e4,
+      onPartial: (i) => {
+        const a = typeof i.delta == "string" ? i.delta : "";
+        s += a, e?.(a, s);
+      }
+    });
+    return n.ok ? {
+      ok: !0,
+      data: {
+        message_id: String(n.data?.message_id ?? ""),
+        text: n.data?.text ?? s,
+        usage: n.data?.usage ?? { input_tokens: 0, output_tokens: 0 }
+      }
+    } : n;
+  }
+  reset() {
+    return this.link.send("ai:chat.reset", { prompt: this.promptId });
+  }
+}
+class M {
+  constructor(t) {
+    this.link = t;
+  }
+  prompts() {
+    return this.link.launch()?.ai?.prompts ?? [];
+  }
+  /** Analysis prompt: structured JSON conforming to the declared output_schema. */
+  ask(t, e = {}) {
+    return this.link.send("ai:ask", { prompt: t, vars: e }, { timeoutMs: 6e4 });
+  }
+  /** Chat prompt: conversation history is held by the Rack. */
+  chat(t) {
+    return new y(this.link, t);
+  }
+}
+class L {
+  constructor(t) {
+    this.link = t, this.local = {};
+  }
+  /** The attempt as launched, with local updates applied. */
+  current() {
+    const t = this.link.launch()?.attempt;
+    return t ? { ...t, ...this.local } : null;
+  }
+  get status() {
+    return this.current()?.status ?? null;
+  }
+  get id() {
+    return this.current()?.id ?? null;
+  }
+  /** Resume state exactly as last saved. */
+  state() {
+    return this.current()?.state ?? null;
+  }
+  segment() {
+    return this.current()?.segment ?? null;
+  }
+  /** Save resume state (max 64 KB). Send after every transition; the shell coalesces bursts. */
+  setState(t) {
+    return this.local.state = t, this.link.send("attempt:state", { state: t });
+  }
+  /** Set segment dimensions (max 20 keys, string values). */
+  setSegment(t) {
+    return this.local.segment = t, this.link.send("attempt:segment", { segment: t });
+  }
+  /** Mark the attempt completed. Idempotent. */
+  async complete(t) {
+    const e = await this.link.send("attempt:complete", { summary: t ?? null });
+    return e.ok && (this.local.status = "completed"), e;
+  }
+}
+class A {
+  constructor(t) {
+    this.link = t;
+  }
+  user() {
+    return this.link.launch()?.auth?.user ?? null;
+  }
+  /** A released profile attribute, or the fallback when withheld. */
+  attribute(t, e = null) {
+    const s = this.user();
+    return !s || !(t in s) ? e : s[t];
+  }
+}
+const R = "$room";
+class E {
+  constructor(t, e) {
+    this.link = t, this.name = e, this.listeners = /* @__PURE__ */ new Map(), this.unsubscribe = null;
+  }
+  /** @internal */
+  attach() {
+    this.unsubscribe ??= this.link.onEvent((t) => {
+      t.channel === this.name && (this.listeners.get(t.event)?.forEach((e) => e(t.payload, t.from)), this.listeners.get("*")?.forEach((e) => e({ event: t.event, payload: t.payload }, t.from)));
+    });
+  }
+  /** Listen for an event on this channel ('*' for all). Returns an unsubscribe function. */
+  listen(t, e) {
+    const s = this.listeners.get(t) ?? /* @__PURE__ */ new Set();
+    return s.add(e), this.listeners.set(t, s), () => {
+      s.delete(e);
+    };
+  }
+  /** Publish to everyone in the room. Facilitator-only events are enforced by the Rack. */
+  publish(t, e = {}) {
+    return this.link.send("broadcast:publish", { channel: this.name, event: t, payload: e });
+  }
+  async leave() {
+    return this.unsubscribe?.(), this.unsubscribe = null, this.listeners.clear(), this.link.send("broadcast:leave", { channel: this.name });
+  }
+}
+class S {
+  constructor(t) {
+    this.link = t, this.channels = /* @__PURE__ */ new Map(), this.roomListeners = /* @__PURE__ */ new Map(), this.localRole = null, this.localMembers = null, this.localState = null, this.detach = null, this.state = {
+      /** Server-arbitrated shared state. */
+      get: async (e) => {
+        const s = await this.link.send("broadcast:state.get", e ? { keys: e } : {});
+        return s.ok && s.data && (this.localState = { ...this.localState ?? {}, ...s.data.state }), s;
+      },
+      /** Last write wins at the key; the Rack stamps the version. */
+      set: (e, s) => (this.localState = { ...this.localState ?? this.launch()?.state ?? {}, [e]: s }, this.link.send("broadcast:state.set", { key: e, value: s })),
+      /** Locally known state (launch snapshot plus pushed updates). */
+      snapshot: () => this.localState ?? this.launch()?.state ?? {}
+    };
+  }
+  get room() {
+    return this.launch()?.room ?? null;
+  }
+  get role() {
+    return this.localRole ?? this.launch()?.role ?? null;
+  }
+  get isFacilitator() {
+    return this.role === "facilitator";
+  }
+  members() {
+    return this.localMembers ?? this.launch()?.members ?? [];
+  }
+  /** Join a named channel within the room (default "main"). */
+  async join(t = "main") {
+    this.ensureRoomListener();
+    let e = this.channels.get(t);
+    return e || (e = new E(this.link, t), this.channels.set(t, e)), e.attach(), await this.link.send("broadcast:join", { channel: t }), e;
+  }
+  /** Who is in the room, by role. */
+  async presence() {
+    const t = await this.link.send("broadcast:presence", {});
+    return t.ok && t.data && (this.localMembers = t.data.members), t;
+  }
+  /** Claim the facilitator role (opt_in rooms). */
+  claim() {
+    return this.link.send("broadcast:claim", {});
+  }
+  /** Hand the facilitator role to another member. */
+  transfer(t) {
+    return this.link.send("broadcast:transfer", { to: t });
+  }
+  /** Room-level events: presence, state, role, status. */
+  on(t, e) {
+    this.ensureRoomListener();
+    const s = this.roomListeners.get(t) ?? /* @__PURE__ */ new Set();
+    return s.add(e), this.roomListeners.set(t, s), () => {
+      s.delete(e);
+    };
+  }
+  launch() {
+    return this.link.launch()?.broadcast ?? null;
+  }
+  ensureRoomListener() {
+    this.detach ??= this.link.onEvent((t) => {
+      if (t.channel !== R)
+        return;
+      const e = t.payload;
+      t.event === "presence" && Array.isArray(e.members) && (this.localMembers = e.members), t.event === "state" && typeof e.key == "string" && (this.localState = { ...this.localState ?? this.launch()?.state ?? {}, [e.key]: e.value }), t.event === "role" && e.participant_id === this.link.launch()?.actor.id && (this.localRole = e.role), this.roomListeners.get(t.event)?.forEach((s) => s(e));
+    });
+  }
+}
+function d(r) {
+  return { ok: !1, error: "undeclared_capability", message: `The manifest does not declare the [${r}] capability.` };
+}
+class T {
+  constructor(t, e) {
+    this.link = t, this.name = e;
+  }
+  create(t) {
+    return this.send("db:create", { data: t });
+  }
+  get(t) {
+    return this.send("db:get", { id: t });
+  }
+  /** Merge by default; pass { merge: false } to replace the whole document. */
+  update(t, e, s = {}) {
+    return this.send("db:update", { id: t, data: e, merge: s.merge ?? !0 });
+  }
+  delete(t) {
+    return this.send("db:delete", { id: t });
+  }
+  list(t = {}) {
+    return this.send("db:list", t);
+  }
+  count(t = {}) {
+    return this.send("db:count", t);
+  }
+  send(t, e) {
+    return this.link.launch() && !this.link.declares("db") ? Promise.resolve(d("db")) : this.link.send(t, { collection: this.name, ...e });
+  }
+}
+class D {
+  constructor(t) {
+    this.link = t;
+  }
+  collection(t) {
+    return new T(this.link, t);
+  }
+  collections() {
+    return this.link.launch()?.db?.collections ?? [];
+  }
+}
+class _ {
+  constructor(t) {
+    this.link = t;
+  }
+  get(t) {
+    return this.link.launch()?.media?.[t] ?? null;
+  }
+  /** Player URL for an <iframe src>. Null when the id is not declared. */
+  embedUrl(t) {
+    return this.get(t)?.embedUrl ?? null;
+  }
+  all() {
+    return this.link.launch()?.media ?? {};
+  }
+}
+class O {
+  constructor(t) {
+    this.link = t;
+  }
+  uploads() {
+    return this.link.launch()?.storage?.uploads ?? [];
+  }
+  /** Upload into a declared upload slot. Resolves once stored (status may still be pending scan). */
+  put(t, e, s = {}) {
+    const n = e instanceof File ? e.name : "blob";
+    return this.link.send("storage:put", { upload: t, file: e, name: n, mime: e.type, bytes: e.size, meta: s }, { timeoutMs: 12e4 });
+  }
+  /** Short-lived URL for a clean file. Never an object key. */
+  url(t) {
+    return this.link.send("storage:url", { id: t });
+  }
+  list(t) {
+    return this.link.send("storage:list", t ? { upload: t } : {});
+  }
+  delete(t) {
+    return this.link.send("storage:delete", { id: t });
+  }
+}
+class P {
+  constructor(t) {
+    this.options = t, this.kind = "host", this.pending = /* @__PURE__ */ new Map(), this.eventListeners = /* @__PURE__ */ new Set(), this.launchResolvers = [], this.launchData = null, this.listener = (e) => this.onMessage(e), this.target = t.target ?? window.parent, this.isHost = t.isHost ?? ((e) => e === window.parent), this.listenOn = t.listenOn ?? window, this.listenOn.addEventListener("message", this.listener);
+  }
+  announceReady() {
+    this.fire("rack:ready", {});
+  }
+  waitForLaunch(t) {
+    return this.launchData ? Promise.resolve(this.launchData) : new Promise((e) => {
+      const s = setTimeout(() => {
+        this.launchResolvers = this.launchResolvers.filter((i) => i !== n), e(null);
+      }, t), n = (i) => {
+        clearTimeout(s), e(i);
+      };
+      this.launchResolvers.push(n);
+    });
+  }
+  send(t, e, s = {}) {
+    const n = f(), i = s.timeoutMs ?? this.options.ackTimeoutMs;
+    return new Promise((a) => {
+      const o = {
+        resolve: a,
+        timer: setTimeout(() => this.expire(n), i),
+        timeoutMs: i,
+        onPartial: s.onPartial
+      };
+      this.pending.set(n, o), this.post(h(t, e, n));
+    });
+  }
+  fire(t, e = {}) {
+    this.post(h(t, e));
+  }
+  onEvent(t) {
+    return this.eventListeners.add(t), () => {
+      this.eventListeners.delete(t);
+    };
+  }
+  dispose() {
+    this.listenOn.removeEventListener("message", this.listener);
+    for (const [t, e] of this.pending)
+      clearTimeout(e.timer), e.resolve({ ok: !1, error: "disposed" }), this.pending.delete(t);
+  }
+  expire(t) {
+    const e = this.pending.get(t);
+    e && (this.pending.delete(t), e.resolve({ ok: !1, error: "timeout" }));
+  }
+  post(t) {
+    this.target.postMessage(t, "*");
+  }
+  onMessage(t) {
+    if (!this.isHost(t.source) || !g(t.data))
+      return;
+    const e = t.data;
+    if (e.type === "rack:launch") {
+      this.launchData = e.payload;
+      const s = this.launchResolvers;
+      this.launchResolvers = [], s.forEach((n) => n(this.launchData));
+      return;
+    }
+    if (e.type === "rack:event") {
+      const s = e.payload;
+      this.eventListeners.forEach((n) => n(s));
+      return;
+    }
+    e.type === "rack:ack" && this.onAck(e.payload);
+  }
+  onAck(t) {
+    const e = this.pending.get(t.requestId);
+    if (!e)
+      return;
+    if (t.partial && !t.done) {
+      const { requestId: F, ok: U, partial: $, ...k } = t;
+      e.onPartial?.(k), clearTimeout(e.timer), e.timer = setTimeout(() => this.expire(t.requestId), e.timeoutMs);
+      return;
+    }
+    clearTimeout(e.timer), this.pending.delete(t.requestId);
+    const { requestId: s, ok: n, data: i, error: a, message: o, details: p, partial: C, done: j, ...c } = t;
+    e.resolve({ ok: n, data: i ?? (Object.keys(c).length ? c : void 0), error: a, message: o, details: p });
+  }
+}
+const q = 3e3, I = 5e3;
+class m {
+  constructor() {
+    this.transport = null, this.initPromise = null, this.launchData = null, this.queue = [], this.launchListeners = /* @__PURE__ */ new Set(), this.eventListeners = /* @__PURE__ */ new Set(), this.pendingAiMocks = [];
+    const t = {
+      send: (e, s, n) => this.send(e, s, n),
+      fire: (e, s) => this.fire(e, s),
+      launch: () => this.launchData,
+      declares: (e) => this.declares(e),
+      onEvent: (e) => this.on("event", e),
+      mode: () => this.mode
+    };
+    this.auth = new A(t), this.attempt = new L(t), this.activity = new v(t), this.db = new D(t), this.storage = new O(t), this.ai = new M(t), this.broadcast = new S(t), this.media = new _(t), this.mock = {
+      ai: (e, s) => {
+        const n = this.mockRack();
+        n ? n.mockAi(e, s) : this.pendingAiMocks.push([e, s]);
+      },
+      resetAttempt: () => this.mockRack()?.resetAttempt(),
+      rack: () => this.mockRack()
+    };
+  }
+  /**
+   * 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(t = {}) {
+    return this.initPromise ??= this.performInit(t), this.initPromise;
+  }
+  get launched() {
+    return this.launchData !== null;
+  }
+  get mode() {
+    return this.transport?.kind ?? "pending";
+  }
+  getLaunchData() {
+    return this.launchData;
+  }
+  /** Whether the manifest declared a capability (any version). */
+  declares(t) {
+    return (this.launchData?.capabilities ?? []).some((e) => e.split("@")[0] === t);
+  }
+  on(t, e) {
+    if (t === "launch") {
+      const n = e;
+      return this.launchListeners.add(n), this.launchData && n(this.launchData), () => {
+        this.launchListeners.delete(n);
+      };
+    }
+    const s = e;
+    return this.eventListeners.add(s), () => {
+      this.eventListeners.delete(s);
+    };
+  }
+  /** Ask the Rack to leave the applet. Needs no capability. */
+  eject() {
+    this.fire("rack:eject", {}), this.transport?.kind === "mock" && console.info("[ziprack mock] eject: the Rack would navigate away now.");
+  }
+  /** Low-level: send any message and await its ack. Capability calls go through the typed APIs. */
+  send(t, e, s) {
+    return this.launchData && !t.startsWith("rack:") && !this.declares(u(t)) ? Promise.resolve(d(u(t))) : this.transport ? this.transport.send(t, e, s) : new Promise((n) => {
+      this.queue.push({ type: t, payload: e, options: s, resolve: n });
+    });
+  }
+  fire(t, e = {}) {
+    if (this.transport) {
+      this.transport.fire(t, e);
+      return;
+    }
+    this.send(t, e);
+  }
+  /** Tear down (tests). */
+  dispose() {
+    this.transport?.dispose(), this.transport = null, this.initPromise = null, this.launchData = null;
+  }
+  async performInit(t) {
+    const e = t.ackTimeoutMs ?? I, s = t.launchTimeoutMs ?? q;
+    if (t.transport) {
+      const o = t.launch ?? (t.transport instanceof l ? t.transport.rack.launchData() : null);
+      if (!o)
+        throw new Error("init({ transport }) needs `launch` data unless the transport is a MockTransport.");
+      return this.activate(t.transport, o);
+    }
+    if (!(typeof window < "u" && window.parent !== window))
+      return this.activateMock(t, "not embedded in a Rack");
+    const i = new P({ ackTimeoutMs: e });
+    i.announceReady();
+    const a = await i.waitForLaunch(s);
+    return a ? this.activate(i, a) : (i.dispose(), this.activateMock(t, `no rack:launch within ${s}ms`));
+  }
+  async activateMock(t, e) {
+    console.info(`[ziprack] running in mock mode (${e})`);
+    const s = await x(t.manifestUrl ?? "./manifest.json", t.slug), n = new w(s, new b(), {
+      log: (i, a) => console.info(`[ziprack mock] ${i}`, a)
+    });
+    for (const [i, a] of this.pendingAiMocks)
+      n.mockAi(i, a);
+    return this.pendingAiMocks = [], this.activate(new l(n), n.launchData(t.slug));
+  }
+  activate(t, e) {
+    return this.transport = t, this.launchData = e, t.onEvent((s) => this.eventListeners.forEach((n) => n(s))), this.launchListeners.forEach((s) => s(e)), this.flushQueue(), e;
+  }
+  flushQueue() {
+    if (this.transport)
+      for (; this.queue.length > 0; ) {
+        const e = this.queue.shift();
+        this.send(e.type, e.payload, e.options).then(e.resolve);
+      }
+  }
+  mockRack() {
+    return this.transport instanceof l ? this.transport.rack : null;
+  }
+}
+async function x(r, t) {
+  if (typeof fetch != "function")
+    return null;
+  try {
+    const e = await fetch(r, { cache: "no-store" });
+    if (!e.ok)
+      throw new Error(String(e.status));
+    const s = await e.json();
+    return t && s.slug !== t && console.warn(`[ziprack mock] manifest slug [${s.slug}] does not match init({ slug: '${t}' }).`), s;
+  } catch (e) {
+    return console.warn(`[ziprack mock] could not load ${r}; mock mode will accept every capability.`, e), null;
+  }
+}
+const H = new m();
+function N() {
+  return new m();
+}
+export {
+  K as FORMAT,
+  P as HostBridge,
+  V as PROTOCOL_NAMESPACE,
+  W as PROTOCOL_VERSION,
+  H as Rack,
+  m as RackClient,
+  N as createRack
+};
+//# sourceMappingURL=index.js.map