@goflowstate/widget-sdk 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -3,4 +3,10 @@ export type { CanvasWidgetSDK, WidgetDisplayState, WidgetEvent, SettingsAPI } fr
 export { createServiceClient } from './service';
 export type { WidgetManifestServiceBlock, WidgetManifestServiceScope, WidgetServiceClient, DbRecord, DbCollection, DbAPI, DbListOptions, } from './types';
 export type { CreateServiceClientOptions } from './service';
+export { initSession, createMockSession, readSessionLaunchParams } from './session';
+export type { SessionClient, SessionStateView, SessionMember, SessionPhase, SessionGateView, SessionFlowView, SessionPollOptions, SessionLaunchParams, MockSessionOptions, } from './session';
+export { getInitialTheme, onThemeChange, applyWidgetTheme, initWidgetTheme } from './theme';
+export type { WidgetTheme } from './theme';
+export { onArtifactIngested, INGEST_MESSAGE_TYPE } from './ingest';
+export type { IngestedArtifact } from './ingest';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACrC,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EACV,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,KAAK,EACL,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AACrC,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAChD,YAAY,EACV,0BAA0B,EAC1B,0BAA0B,EAC1B,mBAAmB,EACnB,QAAQ,EACR,YAAY,EACZ,KAAK,EACL,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAC;AACpF,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC5F,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACnE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC"}

package/dist/index.mjs

@@ -1,5 +1,5 @@
-// @goflowstate/widget-sdk v0.1.1
-// https://github.com/starteryllp/goflowstate-sdk
+// @goflowstate/widget-sdk v0.2.1
+// https://github.com/goflowstate/goflowstate-sdk
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -39,10 +39,292 @@ function createServiceClient(opts) {
   };
 }
 
+// src/session.ts
+function readSessionLaunchParams() {
+  if (typeof window === "undefined") return null;
+  const q = new URLSearchParams(window.location.search);
+  const slug = q.get("slug") ?? q.get("tripId") ?? "";
+  if (!slug) return null;
+  const mobile = q.get("mobile");
+  return {
+    slug,
+    ticket: q.get("ticket"),
+    apiBase: (q.get("api") ?? "http://localhost:13002").replace(/\/$/, ""),
+    webBase: (q.get("web") ?? "http://localhost:14321").replace(/\/$/, ""),
+    mobileBase: mobile ? mobile.replace(/\/$/, "") : null
+  };
+}
+var SESSION_INIT_TIMEOUT_MS = 1e4;
+var DEFAULT_POLL_INTERVAL_MS = 4e3;
+function awaitInitTicket(webBase) {
+  return new Promise((resolve, reject) => {
+    if (typeof window === "undefined" || window.parent === window) {
+      reject(new Error("no parent page to receive a ticket from"));
+      return;
+    }
+    const webOrigin = new URL(webBase).origin;
+    const timer = setTimeout(() => {
+      window.removeEventListener("message", onMessage);
+      reject(new Error("timed out waiting for the session handoff"));
+    }, SESSION_INIT_TIMEOUT_MS);
+    const onMessage = (e) => {
+      if (e.origin !== webOrigin) return;
+      const data = e.data;
+      if (data?.type !== "flowstate:init" || typeof data.ticket !== "string") return;
+      clearTimeout(timer);
+      window.removeEventListener("message", onMessage);
+      resolve(data.ticket);
+    };
+    window.addEventListener("message", onMessage);
+    window.parent.postMessage({ type: "flowstate:ready" }, webOrigin);
+  });
+}
+var WIRE_PHASE = {
+  setup: "setup",
+  wishlist: "open",
+  sealed: "sealed",
+  plan: "resolved"
+};
+function toStateView(s) {
+  return {
+    slug: s.tripId,
+    phase: WIRE_PHASE[s.phase] ?? "open",
+    status: s.status,
+    setup: s.setup ?? null,
+    members: s.members,
+    sealedCount: s.sealedCount,
+    memberCount: s.memberCount,
+    allSealed: s.allSealed,
+    quorumMet: s.quorumMet ?? s.allSealed,
+    gate: s.gate ?? null,
+    flow: s.flow ?? null,
+    myContribution: s.myWishlist ?? null,
+    doc: s.plan ?? null,
+    artifactId: s.artifactId,
+    extension: s.extension ?? null
+  };
+}
+var parentOpener = (webBase) => {
+  return (url) => {
+    if (typeof window !== "undefined" && window.parent !== window) {
+      window.parent.postMessage({ type: "flowstate:navigate", url }, webBase);
+      return;
+    }
+    if (typeof window !== "undefined") window.open(url, "_blank", "noopener");
+  };
+};
+var HttpSessionClient = class {
+  constructor(params, opener) {
+    __publicField(this, "slug");
+    __publicField(this, "webBase");
+    __publicField(this, "mobileBase");
+    __publicField(this, "apiBase");
+    __publicField(this, "tokenPromise");
+    __publicField(this, "opener");
+    this.slug = params.slug;
+    this.webBase = params.webBase;
+    this.mobileBase = params.mobileBase ?? null;
+    this.apiBase = params.apiBase;
+    this.opener = opener ?? parentOpener(params.webBase);
+    this.tokenPromise = this.acquireTicket(params).then((t) => this.redeem(t));
+  }
+  async acquireTicket(params) {
+    if (params.ticket) return params.ticket;
+    return awaitInitTicket(params.webBase);
+  }
+  async redeem(ticket) {
+    const res = await fetch(`${this.apiBase}/api/auth/ticket/redeem`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ ticket })
+    });
+    if (!res.ok) throw new Error(`ticket redeem failed (${res.status})`);
+    const json = await res.json();
+    return json.data.token;
+  }
+  async call(path, init = {}) {
+    const token = await this.tokenPromise;
+    const res = await fetch(`${this.apiBase}/api/w/${this.slug}${path}`, {
+      ...init,
+      headers: {
+        authorization: `Bearer ${token}`,
+        ...init.body ? { "content-type": "application/json" } : {},
+        ...init.headers ?? {}
+      }
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new Error(body.message ?? `session service ${res.status}`);
+    }
+    const json = await res.json();
+    const data = json.data;
+    return toStateView(data.state ?? data);
+  }
+  join() {
+    return this.call("/enter", { method: "POST" });
+  }
+  state() {
+    return this.call("/state");
+  }
+  poll(onState, opts) {
+    const interval = opts?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    let stopped = false;
+    let timer = null;
+    const tick = async () => {
+      try {
+        const s = await this.state();
+        if (!stopped) onState(s);
+      } catch (err) {
+        opts?.onError?.(err);
+      }
+      if (!stopped) timer = setTimeout(tick, interval);
+    };
+    void tick();
+    return () => {
+      stopped = true;
+      if (timer) clearTimeout(timer);
+    };
+  }
+  commitSetup(setup) {
+    return this.call("/setup", { method: "POST", body: JSON.stringify({ setup }) });
+  }
+  contribute(payload) {
+    return this.call("/contribute", { method: "POST", body: JSON.stringify({ payload }) });
+  }
+  close() {
+    return this.call("/close", { method: "POST" });
+  }
+  action(verb, body) {
+    return this.call(`/${verb.replace(/^\//, "")}`, {
+      method: "POST",
+      body: JSON.stringify(body ?? {})
+    });
+  }
+  async request(verb, body) {
+    const token = await this.tokenPromise;
+    const res = await fetch(`${this.apiBase}/api/w/${this.slug}/${verb.replace(/^\//, "")}`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+      body: JSON.stringify(body ?? {})
+    });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      throw new Error(errBody.message ?? `session service ${res.status}`);
+    }
+    const json = await res.json();
+    return json.data;
+  }
+  openExternal(url) {
+    this.opener(url);
+  }
+  revealUrl(artifactId) {
+    return `${this.webBase}/a/${artifactId}`;
+  }
+};
+function createMockSession(opts = {}) {
+  const palette = ["#8b7ef8", "#f8a34d", "#4dc9a4", "#f26d8f", "#5aa9e6"];
+  const members = [
+    { userId: "mock-me", name: opts.me ?? "You", color: palette[0], sealed: false, isMe: true, isHost: true },
+    ...(opts.others ?? []).map((name, i) => ({
+      userId: `mock-${i + 1}`,
+      name,
+      color: palette[(i + 1) % palette.length],
+      sealed: false,
+      isMe: false,
+      isHost: false
+    }))
+  ];
+  let setup = opts.setup ?? null;
+  let myContribution = null;
+  let doc = null;
+  let status = "open";
+  const view = () => {
+    const sealedCount = members.filter((m) => m.sealed).length;
+    const allSealed = members.length > 0 && sealedCount >= members.length;
+    const phase = status === "closed" && doc ? "resolved" : !setup ? "setup" : allSealed ? "sealed" : "open";
+    return {
+      slug: "mock-session",
+      phase,
+      status,
+      setup,
+      members: members.map((m) => ({ ...m })),
+      sealedCount,
+      memberCount: members.length,
+      allSealed,
+      quorumMet: allSealed,
+      gate: null,
+      flow: null,
+      myContribution,
+      doc,
+      artifactId: doc ? "mock-artifact" : null,
+      extension: null
+    };
+  };
+  return {
+    slug: "mock-session",
+    webBase: "http://localhost:14321",
+    async join() {
+      return view();
+    },
+    async state() {
+      return view();
+    },
+    poll(onState, pollOpts) {
+      const interval = pollOpts?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+      const timer = setInterval(() => onState(view()), interval);
+      onState(view());
+      return () => clearInterval(timer);
+    },
+    async commitSetup(s) {
+      setup = s;
+      return view();
+    },
+    async contribute(payload) {
+      myContribution = payload;
+      const me = members.find((m) => m.isMe);
+      if (me) me.sealed = true;
+      return view();
+    },
+    async close() {
+      status = "closed";
+      doc = opts.synthesize ? opts.synthesize([myContribution]) : { mock: true };
+      return view();
+    },
+    async action() {
+      return view();
+    },
+    async request() {
+      return {};
+    },
+    openExternal(url) {
+      if (typeof window !== "undefined") window.open(url, "_blank", "noopener");
+    },
+    revealUrl(artifactId) {
+      return `http://localhost:14321/a/${artifactId}`;
+    }
+  };
+}
+function initSession() {
+  const params = readSessionLaunchParams();
+  if (!params) return null;
+  return new HttpSessionClient(params);
+}
+
 // src/sdk.ts
 var PROTOCOL = "canvas-widget-v1";
 var DEV_MODE_TOKEN = "dev-mode-skip";
 var INIT_TIMEOUT_MS = 5e3;
+function safeRandomUUID() {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  const b = new Uint8Array(16);
+  if (c && typeof c.getRandomValues === "function") c.getRandomValues(b);
+  else for (let i = 0; i < 16; i++) b[i] = Math.floor(Math.random() * 256);
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  const h = Array.from(b, (x) => x.toString(16).padStart(2, "0"));
+  return `${h[0]}${h[1]}${h[2]}${h[3]}-${h[4]}${h[5]}-${h[6]}${h[7]}-${h[8]}${h[9]}-${h[10]}${h[11]}${h[12]}${h[13]}${h[14]}${h[15]}`;
+}
 var cachedKey = null;
 async function getHmacKey(secret) {
   if (cachedKey && cachedKey.secret === secret) return cachedKey.key;
@@ -69,6 +351,7 @@ var CanvasWidgetSDKImpl = class {
     __publicField(this, "_state");
     __publicField(this, "_hmacSecret");
     __publicField(this, "_user");
+    __publicField(this, "_namespace");
     __publicField(this, "_widgetApiUrl");
     __publicField(this, "_widgetApiToken");
     __publicField(this, "_installationId");
@@ -89,6 +372,7 @@ var CanvasWidgetSDKImpl = class {
     this._state = init.state;
     this._hmacSecret = init.hmacSecret;
     this._user = init.user;
+    this._namespace = init.namespace ?? null;
     this._widgetApiUrl = init.widgetApiUrl;
     this._widgetApiToken = init.widgetApiToken ?? null;
     this._installationId = init.installationId;
@@ -114,6 +398,11 @@ var CanvasWidgetSDKImpl = class {
   get user() {
     return this._user;
   }
+  /** Namespace (office) context — id and owner-inclusive member count — or
+   *  null on a personal canvas. What the `canvas.context` permission grants. */
+  get namespace() {
+    return this._namespace;
+  }
   /** Subscribe to display state changes; returns an unsubscribe function. */
   onStateChange(cb) {
     this._stateListeners.push(cb);
@@ -238,6 +527,52 @@ var CanvasWidgetSDKImpl = class {
       }
     };
   }
+  /** Platform LLM access (widget.* aliases only). Requests ride the same
+   *  widget-gateway auth as db/storage; the platform meters every call and
+   *  attributes it to this widget's publishing org. */
+  get ai() {
+    const complete = (opts) => this.widgetApiRequest("/widget-api/ai/complete", "POST", opts);
+    const streamRequest = (opts) => this.widgetApiStream(opts);
+    return {
+      complete,
+      // Async generator over the gateway's SSE frames. Ends on [DONE] or
+      // stream end; returning early (break) cancels the fetch body, which
+      // the gateway sees as a disconnect and aborts the upstream call, so
+      // an abandoned stream stops generating and billing.
+      async *stream(opts) {
+        const response = await streamRequest(opts);
+        const reader = response.body?.getReader();
+        if (!reader) throw new Error("ai.stream: response has no body");
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+          for (; ; ) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buffer += decoder.decode(value, { stream: true });
+            const frames = buffer.split("\n\n");
+            buffer = frames.pop() ?? "";
+            for (const frame of frames) {
+              const dataLine = frame.split("\n").find((l) => l.startsWith("data:"));
+              if (!dataLine) continue;
+              const payload = dataLine.slice(5).trim();
+              if (!payload || payload === "[DONE]") continue;
+              let parsed;
+              try {
+                parsed = JSON.parse(payload);
+              } catch {
+                continue;
+              }
+              yield parsed;
+            }
+          }
+        } finally {
+          await reader.cancel().catch(() => {
+          });
+        }
+      }
+    };
+  }
   /** Widget configuration settings persisted by the canvas host. */
   get settings() {
     return {
@@ -263,6 +598,28 @@ var CanvasWidgetSDKImpl = class {
     });
   }
   // ── Private ─────────────────────────────────────────────────
+  /** Raw streaming POST against the widget gateway — same auth as
+   *  widgetApiRequest, but returns the Response for SSE consumption
+   *  instead of parsing a JSON envelope. */
+  async widgetApiStream(body) {
+    if (!this._widgetApiUrl) {
+      throw new Error("Widget API Gateway URL not available");
+    }
+    const headers = { "Content-Type": "application/json" };
+    if (this._widgetApiToken) {
+      headers["Authorization"] = `Bearer ${this._widgetApiToken}`;
+    }
+    const response = await fetch(`${this._widgetApiUrl}/widget-api/ai/stream`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    if (!response.ok) {
+      const err = await response.json().catch(() => ({}));
+      throw new Error(err.message ?? "ai.stream request failed");
+    }
+    return response;
+  }
   async widgetApiRequest(path, method, body) {
     if (!this._widgetApiUrl) {
       throw new Error("Widget API Gateway URL not available");
@@ -377,7 +734,7 @@ var CanvasWidgetSDKImpl = class {
     });
   }
   async buildMessage(type, payload) {
-    const nonce = crypto.randomUUID();
+    const nonce = safeRandomUUID();
     const timestamp = Date.now();
     let token;
     if (this._hmacSecret) {
@@ -407,6 +764,13 @@ var CanvasWidgetSDKImpl = class {
   }
 };
 var CanvasWidget = {
+  /**
+   * Initialize a group-session client for widgets hosted on the /w/[slug]
+   * session page (ticket handshake + session REST rails). Returns null when
+   * the launch context carries no session params — see `initSession` in
+   * ./session for details and `createMockSession` for standalone dev.
+   */
+  initSession,
   /**
    * Initialize the SDK and establish communication with the canvas host.
    *
@@ -436,7 +800,7 @@ var CanvasWidget = {
         type: "READY",
         widgetId: "",
         // Not yet known — host identifies us by iframe source
-        nonce: crypto.randomUUID(),
+        nonce: safeRandomUUID(),
         timestamp: Date.now(),
         token: DEV_MODE_TOKEN,
         // READY is always allowed, token doesn't matter
@@ -446,8 +810,84 @@ var CanvasWidget = {
     });
   }
 };
+
+// src/theme.ts
+var THEME_MESSAGE_TYPE = "flowstate:theme";
+var DEFAULT_THEME = "glass";
+function isWidgetTheme(value) {
+  return value === "light" || value === "dark" || value === "glass";
+}
+function getInitialTheme() {
+  if (typeof window === "undefined") return DEFAULT_THEME;
+  try {
+    const param = new URLSearchParams(window.location.search).get("theme");
+    return isWidgetTheme(param) ? param : DEFAULT_THEME;
+  } catch {
+    return DEFAULT_THEME;
+  }
+}
+function onThemeChange(cb, opts) {
+  if (typeof window === "undefined") return () => {
+  };
+  const listener = (event) => {
+    if (event.source !== window.parent) return;
+    if (opts?.allowedOrigin && event.origin !== opts.allowedOrigin) return;
+    const data = event.data;
+    if (typeof data !== "object" || data === null) return;
+    const message = data;
+    if (message.type !== THEME_MESSAGE_TYPE) return;
+    if (!isWidgetTheme(message.theme)) return;
+    cb(message.theme);
+  };
+  window.addEventListener("message", listener);
+  return () => window.removeEventListener("message", listener);
+}
+function applyWidgetTheme(theme) {
+  if (typeof document === "undefined") return;
+  if (theme === "glass") {
+    delete document.documentElement.dataset.theme;
+  } else {
+    document.documentElement.dataset.theme = theme;
+  }
+}
+function initWidgetTheme() {
+  applyWidgetTheme(getInitialTheme());
+  return onThemeChange(applyWidgetTheme);
+}
+
+// src/ingest.ts
+var INGEST_MESSAGE_TYPE = "flowstate:ingest";
+function onArtifactIngested(cb, opts) {
+  if (typeof window === "undefined") return () => {
+  };
+  const listener = (event) => {
+    if (event.source !== window.parent) return;
+    if (opts?.allowedOrigin && event.origin !== opts.allowedOrigin) return;
+    const data = event.data;
+    if (typeof data !== "object" || data === null) return;
+    const message = data;
+    if (message.type !== INGEST_MESSAGE_TYPE) return;
+    if (typeof message.artifactId !== "string" || !message.artifactId) return;
+    cb({
+      artifactId: message.artifactId,
+      kind: typeof message.kind === "string" ? message.kind : void 0,
+      payload: message.payload
+    });
+  };
+  window.addEventListener("message", listener);
+  return () => window.removeEventListener("message", listener);
+}
 export {
   CanvasWidget,
-  createServiceClient
+  INGEST_MESSAGE_TYPE,
+  applyWidgetTheme,
+  createMockSession,
+  createServiceClient,
+  getInitialTheme,
+  initSession,
+  initWidgetTheme,
+  onArtifactIngested,
+  onThemeChange,
+  readSessionLaunchParams
 };
 //# sourceMappingURL=index.mjs.map