@fork-api/chat-sdk 0.1.131 → 0.1.133

package/dist/index.d.cts

@@ -131,6 +131,52 @@ interface ForkSlotProps {
 }
 type ForkState = "idle" | "prompting" | "running" | "complete" | "error";
 
+type PreviewTargetKind = "slot" | "module";
+
+/**
+ * Phase 4 — preview-session client state, persistence, and pub/sub.
+ *
+ * One module owns:
+ *   1. sessionStorage I/O (namespaced by apiKey so multiple tenants can
+ *      coexist on the same origin without trampling each other).
+ *   2. A tiny subscribe/notify model so React components — banner, provider
+ *      hooks, sidebar — all share one source of truth and stay in lockstep
+ *      across mount/unmount cycles.
+ *
+ * Why sessionStorage (not localStorage): a preview session is bound to a
+ * single tab. Closing the tab cancels the session; opening a second tab
+ * should NOT inherit somebody else's authoring state. sessionStorage
+ * mirrors that lifetime exactly.
+ *
+ * Why pub/sub over React context alone: the banner is mounted into a
+ * detached Shadow DOM root (separate render tree). It can't read context
+ * from the ForkProvider tree, so it subscribes to this module directly.
+ */
+
+interface PreviewSessionPayload {
+    preview_session_id: string;
+    tenant_id: string;
+    app_id: string;
+    target: {
+        kind: PreviewTargetKind;
+        id: string;
+    };
+    target_user_id: string;
+    operator_id: number;
+    container_id?: string | null;
+    /** Human-readable container label for preview UI. Older sessions may not
+     *  have this; callers should fall back to target_user_id. */
+    container_name?: string | null;
+    /** Seeded from activate(); the SDK updates it when authoring creates a
+     *  new fork. Null when the operator just landed and hasn't authored. */
+    fork_id: string | null;
+    /** ISO-8601 expiration. The banner ticks against this; once past, the
+     *  module clears storage on next access. */
+    expires_at: string;
+}
+
+declare function usePreviewSession(): PreviewSessionPayload | null;
+
 declare function ForkProvider(props: ForkProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function ForkSlot({ slotId, props, children, allowedFetches, githubRepo, callbacks, mode, shared, events }: ForkSlotProps): react_jsx_runtime.JSX.Element;
@@ -173,7 +219,7 @@ interface ForkPanelProps {
     targetLabel?: string;
     historyMode?: "slot" | "boundary" | "none";
     examplePrompts?: string[];
-    onSubmit: (prompt: string, targetId: string) => void;
+    onSubmit: (prompt: string, targetId: string, containerId?: string | null) => void;
     onUndo?: (targetId: string) => Promise<any>;
     onClose: () => void;
     baseUrl?: string;
@@ -198,7 +244,7 @@ declare function useFork(): {
     error: string | null;
     open: () => void;
     close: () => void;
-    startFork: (prompt: string, slotId?: string) => Promise<void>;
+    startFork: (prompt: string, slotId?: string, containerId?: string | null) => Promise<void>;
     undoFork: (slotId: string) => Promise<any>;
 };
 
@@ -209,7 +255,7 @@ declare function useBoundaryFork(boundaryId: string): {
     error: string | null;
     open: () => void;
     close: () => void;
-    startFork: (prompt: string) => Promise<void>;
+    startFork: (prompt: string, containerId?: string | null) => Promise<void>;
     undoFork: () => Promise<any>;
 };
 
@@ -218,13 +264,13 @@ declare function useForkChatPanel(options: ForkChatPanelOptions): {
     targetId: string;
     targetLabel: string | undefined;
     historyMode: "slot" | "boundary";
-    submit: (prompt: string, submittedTargetId?: string) => Promise<void>;
+    submit: (prompt: string, submittedTargetId?: string, containerId?: string | null) => Promise<void>;
     undo: (submittedTargetId?: string) => Promise<any>;
     buttonProps: {
         onClick: () => void;
     };
     panelProps: {
-        onSubmit: (prompt: string, submittedTargetId?: string) => Promise<void>;
+        onSubmit: (prompt: string, submittedTargetId?: string, containerId?: string | null) => Promise<void>;
         onUndo: (submittedTargetId?: string) => Promise<any>;
         onClose: () => void;
         baseUrl: string;
@@ -240,7 +286,7 @@ declare function useForkChatPanel(options: ForkChatPanelOptions): {
         events: ForkEvent[];
         error: string | null;
     } | {
-        onSubmit: (prompt: string, submittedTargetId?: string) => Promise<void>;
+        onSubmit: (prompt: string, submittedTargetId?: string, containerId?: string | null) => Promise<void>;
         onUndo: (submittedTargetId?: string) => Promise<any>;
         onClose: () => void;
         baseUrl: string;
@@ -265,4 +311,99 @@ declare function useForkChatPanel(options: ForkChatPanelOptions): {
     close: () => void;
 };
 
-export { type Fork, type ForkBoundaryDefinition, ForkBoundaryUI, ForkButton, ForkChatInterface, type ForkChatInterfaceProps, type ForkChatPanelOptions, type ForkChatTarget, type ForkEvent, ForkPanel, ForkProvider, type ForkProviderProps, type ForkSharedRegistry, ForkSlot, type ForkSlotProps, type ForkState, ForkUI, forkable, registerForkShared, useBoundaryFork, useFork, useForkChatPanel };
+/**
+ * Containers v2 — SDK-side manifest client.
+ *
+ * Resolves every slot + module fork for an end-user in a single round trip
+ * (vs. the per-slot fan-out the legacy /api/v1/forks/active path does), and
+ * provides stale-while-revalidate caching against localStorage so repeat
+ * visits paint with zero network latency.
+ *
+ * ForkProvider uses this for the normal end-user runtime path and for
+ * container-bound previews. Legacy preview sessions without a container still
+ * use the preview-aware overlay endpoints.
+ *
+ * Usage sketch:
+ *
+ *   const cached = readCachedManifest(tenantId, appId, userId);
+ *   if (cached) renderFrom(cached);     // instant first paint
+ *   loadManifest({...}).then((fresh) => {
+ *     if (etagDiffers(cached, fresh)) renderFrom(fresh);
+ *     writeCachedManifest(tenantId, appId, userId, fresh);
+ *   });
+ *
+ * See §14 of docs/containers-independent-plan.html for the budget this
+ * module is built to hit (p99 ≤ 50ms cold, ≤ 30ms warm; perceptual instant
+ * on repeat visits).
+ */
+interface ManifestEntry {
+    forkId: string;
+    /** Immutable, build-keyed URL — safe to cache forever in the browser. */
+    bundleUrl: string | null;
+    /** Pre-v2 bundle URL (mutable). Kept around so a partial-rollback SDK
+     *  can still resolve forks that don't have a build_id yet. */
+    legacyBundleUrl: string | null;
+    buildId: string | null;
+    updatedAt: string;
+}
+interface ManifestModuleEntry {
+    forkId: string;
+    /** Immutable, build-keyed module URL when available. */
+    moduleUrl: string | null;
+    /** Pre-v2 module URL from module_overrides.module_url. */
+    legacyModuleUrl: string | null;
+    /** Back-compat aliases while API and SDK versions overlap. */
+    bundleUrl?: string | null;
+    legacyBundleUrl?: string | null;
+    cssUrls: string[];
+    integrity?: string;
+    metadata?: Record<string, unknown>;
+    buildId: string | null;
+    updatedAt: string;
+}
+interface Manifest {
+    containerId: string | null;
+    slots: Record<string, ManifestEntry>;
+    modules: Record<string, ManifestModuleEntry>;
+    generatedAt: string;
+    /** Server-supplied ETag (from response header). Used to short-circuit the
+     *  background refresh when nothing's changed. */
+    etag?: string;
+}
+interface LoadManifestInput {
+    /** Base URL of the Fork API. Pass without trailing slash. */
+    baseUrl: string;
+    /** Publishable key (pk_fork_…) — passed as Bearer. */
+    apiKey: string;
+    appId: string;
+    /** Verified user id. The server requires either this or a userHash. */
+    userId: string;
+    /** Optional userHash for HMAC verification. */
+    userHash?: string;
+    /** Authorized explicit container lookup, used for container-bound previews. */
+    containerId?: string;
+    /** Additional trusted headers, e.g. preview session headers. */
+    extraHeaders?: Record<string, string>;
+    /** Previous manifest, if any — its etag is sent as If-None-Match. */
+    previous?: Manifest;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Fetch the manifest. Returns null when the server replies 304 Not Modified
+ * (caller keeps the previous manifest). Throws on network/HTTP errors.
+ */
+declare function loadManifest(input: LoadManifestInput): Promise<Manifest | null>;
+/** Read a previously-cached manifest. Returns null if absent or corrupted. */
+declare function readCachedManifest(tenantId: string, appId: string, userId: string): Manifest | null;
+/** Write a manifest to the cache. Best-effort — quota errors are swallowed. */
+declare function writeCachedManifest(tenantId: string, appId: string, userId: string, manifest: Manifest): void;
+/** Clear the cached manifest for a (tenant, app, user). */
+declare function clearCachedManifest(tenantId: string, appId: string, userId: string): void;
+/**
+ * Compare the resolved fork ids + build ids of two manifests. Returns true
+ * when anything user-visible has changed (so the caller should hot-swap).
+ */
+declare function manifestDiffers(a: Manifest | null, b: Manifest | null): boolean;
+
+export { type Fork, type ForkBoundaryDefinition, ForkBoundaryUI, ForkButton, ForkChatInterface, type ForkChatInterfaceProps, type ForkChatPanelOptions, type ForkChatTarget, type ForkEvent, ForkPanel, ForkProvider, type ForkProviderProps, type ForkSharedRegistry, ForkSlot, type ForkSlotProps, type ForkState, ForkUI, type LoadManifestInput, type Manifest, type ManifestEntry, type ManifestModuleEntry, type PreviewSessionPayload, clearCachedManifest, forkable, loadManifest, manifestDiffers, readCachedManifest, registerForkShared, useBoundaryFork, useFork, useForkChatPanel, usePreviewSession, writeCachedManifest };

package/dist/index.d.ts

@@ -131,6 +131,52 @@ interface ForkSlotProps {
 }
 type ForkState = "idle" | "prompting" | "running" | "complete" | "error";
 
+type PreviewTargetKind = "slot" | "module";
+
+/**
+ * Phase 4 — preview-session client state, persistence, and pub/sub.
+ *
+ * One module owns:
+ *   1. sessionStorage I/O (namespaced by apiKey so multiple tenants can
+ *      coexist on the same origin without trampling each other).
+ *   2. A tiny subscribe/notify model so React components — banner, provider
+ *      hooks, sidebar — all share one source of truth and stay in lockstep
+ *      across mount/unmount cycles.
+ *
+ * Why sessionStorage (not localStorage): a preview session is bound to a
+ * single tab. Closing the tab cancels the session; opening a second tab
+ * should NOT inherit somebody else's authoring state. sessionStorage
+ * mirrors that lifetime exactly.
+ *
+ * Why pub/sub over React context alone: the banner is mounted into a
+ * detached Shadow DOM root (separate render tree). It can't read context
+ * from the ForkProvider tree, so it subscribes to this module directly.
+ */
+
+interface PreviewSessionPayload {
+    preview_session_id: string;
+    tenant_id: string;
+    app_id: string;
+    target: {
+        kind: PreviewTargetKind;
+        id: string;
+    };
+    target_user_id: string;
+    operator_id: number;
+    container_id?: string | null;
+    /** Human-readable container label for preview UI. Older sessions may not
+     *  have this; callers should fall back to target_user_id. */
+    container_name?: string | null;
+    /** Seeded from activate(); the SDK updates it when authoring creates a
+     *  new fork. Null when the operator just landed and hasn't authored. */
+    fork_id: string | null;
+    /** ISO-8601 expiration. The banner ticks against this; once past, the
+     *  module clears storage on next access. */
+    expires_at: string;
+}
+
+declare function usePreviewSession(): PreviewSessionPayload | null;
+
 declare function ForkProvider(props: ForkProviderProps): react_jsx_runtime.JSX.Element;
 
 declare function ForkSlot({ slotId, props, children, allowedFetches, githubRepo, callbacks, mode, shared, events }: ForkSlotProps): react_jsx_runtime.JSX.Element;
@@ -173,7 +219,7 @@ interface ForkPanelProps {
     targetLabel?: string;
     historyMode?: "slot" | "boundary" | "none";
     examplePrompts?: string[];
-    onSubmit: (prompt: string, targetId: string) => void;
+    onSubmit: (prompt: string, targetId: string, containerId?: string | null) => void;
     onUndo?: (targetId: string) => Promise<any>;
     onClose: () => void;
     baseUrl?: string;
@@ -198,7 +244,7 @@ declare function useFork(): {
     error: string | null;
     open: () => void;
     close: () => void;
-    startFork: (prompt: string, slotId?: string) => Promise<void>;
+    startFork: (prompt: string, slotId?: string, containerId?: string | null) => Promise<void>;
     undoFork: (slotId: string) => Promise<any>;
 };
 
@@ -209,7 +255,7 @@ declare function useBoundaryFork(boundaryId: string): {
     error: string | null;
     open: () => void;
     close: () => void;
-    startFork: (prompt: string) => Promise<void>;
+    startFork: (prompt: string, containerId?: string | null) => Promise<void>;
     undoFork: () => Promise<any>;
 };
 
@@ -218,13 +264,13 @@ declare function useForkChatPanel(options: ForkChatPanelOptions): {
     targetId: string;
     targetLabel: string | undefined;
     historyMode: "slot" | "boundary";
-    submit: (prompt: string, submittedTargetId?: string) => Promise<void>;
+    submit: (prompt: string, submittedTargetId?: string, containerId?: string | null) => Promise<void>;
     undo: (submittedTargetId?: string) => Promise<any>;
     buttonProps: {
         onClick: () => void;
     };
     panelProps: {
-        onSubmit: (prompt: string, submittedTargetId?: string) => Promise<void>;
+        onSubmit: (prompt: string, submittedTargetId?: string, containerId?: string | null) => Promise<void>;
         onUndo: (submittedTargetId?: string) => Promise<any>;
         onClose: () => void;
         baseUrl: string;
@@ -240,7 +286,7 @@ declare function useForkChatPanel(options: ForkChatPanelOptions): {
         events: ForkEvent[];
         error: string | null;
     } | {
-        onSubmit: (prompt: string, submittedTargetId?: string) => Promise<void>;
+        onSubmit: (prompt: string, submittedTargetId?: string, containerId?: string | null) => Promise<void>;
         onUndo: (submittedTargetId?: string) => Promise<any>;
         onClose: () => void;
         baseUrl: string;
@@ -265,4 +311,99 @@ declare function useForkChatPanel(options: ForkChatPanelOptions): {
     close: () => void;
 };
 
-export { type Fork, type ForkBoundaryDefinition, ForkBoundaryUI, ForkButton, ForkChatInterface, type ForkChatInterfaceProps, type ForkChatPanelOptions, type ForkChatTarget, type ForkEvent, ForkPanel, ForkProvider, type ForkProviderProps, type ForkSharedRegistry, ForkSlot, type ForkSlotProps, type ForkState, ForkUI, forkable, registerForkShared, useBoundaryFork, useFork, useForkChatPanel };
+/**
+ * Containers v2 — SDK-side manifest client.
+ *
+ * Resolves every slot + module fork for an end-user in a single round trip
+ * (vs. the per-slot fan-out the legacy /api/v1/forks/active path does), and
+ * provides stale-while-revalidate caching against localStorage so repeat
+ * visits paint with zero network latency.
+ *
+ * ForkProvider uses this for the normal end-user runtime path and for
+ * container-bound previews. Legacy preview sessions without a container still
+ * use the preview-aware overlay endpoints.
+ *
+ * Usage sketch:
+ *
+ *   const cached = readCachedManifest(tenantId, appId, userId);
+ *   if (cached) renderFrom(cached);     // instant first paint
+ *   loadManifest({...}).then((fresh) => {
+ *     if (etagDiffers(cached, fresh)) renderFrom(fresh);
+ *     writeCachedManifest(tenantId, appId, userId, fresh);
+ *   });
+ *
+ * See §14 of docs/containers-independent-plan.html for the budget this
+ * module is built to hit (p99 ≤ 50ms cold, ≤ 30ms warm; perceptual instant
+ * on repeat visits).
+ */
+interface ManifestEntry {
+    forkId: string;
+    /** Immutable, build-keyed URL — safe to cache forever in the browser. */
+    bundleUrl: string | null;
+    /** Pre-v2 bundle URL (mutable). Kept around so a partial-rollback SDK
+     *  can still resolve forks that don't have a build_id yet. */
+    legacyBundleUrl: string | null;
+    buildId: string | null;
+    updatedAt: string;
+}
+interface ManifestModuleEntry {
+    forkId: string;
+    /** Immutable, build-keyed module URL when available. */
+    moduleUrl: string | null;
+    /** Pre-v2 module URL from module_overrides.module_url. */
+    legacyModuleUrl: string | null;
+    /** Back-compat aliases while API and SDK versions overlap. */
+    bundleUrl?: string | null;
+    legacyBundleUrl?: string | null;
+    cssUrls: string[];
+    integrity?: string;
+    metadata?: Record<string, unknown>;
+    buildId: string | null;
+    updatedAt: string;
+}
+interface Manifest {
+    containerId: string | null;
+    slots: Record<string, ManifestEntry>;
+    modules: Record<string, ManifestModuleEntry>;
+    generatedAt: string;
+    /** Server-supplied ETag (from response header). Used to short-circuit the
+     *  background refresh when nothing's changed. */
+    etag?: string;
+}
+interface LoadManifestInput {
+    /** Base URL of the Fork API. Pass without trailing slash. */
+    baseUrl: string;
+    /** Publishable key (pk_fork_…) — passed as Bearer. */
+    apiKey: string;
+    appId: string;
+    /** Verified user id. The server requires either this or a userHash. */
+    userId: string;
+    /** Optional userHash for HMAC verification. */
+    userHash?: string;
+    /** Authorized explicit container lookup, used for container-bound previews. */
+    containerId?: string;
+    /** Additional trusted headers, e.g. preview session headers. */
+    extraHeaders?: Record<string, string>;
+    /** Previous manifest, if any — its etag is sent as If-None-Match. */
+    previous?: Manifest;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Fetch the manifest. Returns null when the server replies 304 Not Modified
+ * (caller keeps the previous manifest). Throws on network/HTTP errors.
+ */
+declare function loadManifest(input: LoadManifestInput): Promise<Manifest | null>;
+/** Read a previously-cached manifest. Returns null if absent or corrupted. */
+declare function readCachedManifest(tenantId: string, appId: string, userId: string): Manifest | null;
+/** Write a manifest to the cache. Best-effort — quota errors are swallowed. */
+declare function writeCachedManifest(tenantId: string, appId: string, userId: string, manifest: Manifest): void;
+/** Clear the cached manifest for a (tenant, app, user). */
+declare function clearCachedManifest(tenantId: string, appId: string, userId: string): void;
+/**
+ * Compare the resolved fork ids + build ids of two manifests. Returns true
+ * when anything user-visible has changed (so the caller should hot-swap).
+ */
+declare function manifestDiffers(a: Manifest | null, b: Manifest | null): boolean;
+
+export { type Fork, type ForkBoundaryDefinition, ForkBoundaryUI, ForkButton, ForkChatInterface, type ForkChatInterfaceProps, type ForkChatPanelOptions, type ForkChatTarget, type ForkEvent, ForkPanel, ForkProvider, type ForkProviderProps, type ForkSharedRegistry, ForkSlot, type ForkSlotProps, type ForkState, ForkUI, type LoadManifestInput, type Manifest, type ManifestEntry, type ManifestModuleEntry, type PreviewSessionPayload, clearCachedManifest, forkable, loadManifest, manifestDiffers, readCachedManifest, registerForkShared, useBoundaryFork, useFork, useForkChatPanel, usePreviewSession, writeCachedManifest };