@fork-api/chat-sdk 0.1.132 → 0.1.134

package/dist/index.d.cts

@@ -87,7 +87,6 @@ type ForkChatTargetInput = {
 };
 type ForkChatPanelOptions = ForkChatTargetInput;
 type ForkChatInterfaceProps = ForkChatTargetInput & {
-    examplePrompts?: string[];
     /**
      * When true, render the panel flat inside its container instead of as a
      * fixed-position side drawer. Suppresses the body-margin push and the
@@ -163,6 +162,10 @@ interface PreviewSessionPayload {
     };
     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;
@@ -182,9 +185,8 @@ declare function ForkChatInterface(props: ForkChatInterfaceProps): react_jsx_run
 interface ForkBoundaryUIProps {
     boundaryId: string;
     title?: string;
-    examplePrompts?: string[];
 }
-declare function ForkBoundaryUI({ boundaryId, title, examplePrompts }: ForkBoundaryUIProps): react_jsx_runtime.JSX.Element;
+declare function ForkBoundaryUI({ boundaryId, title }: ForkBoundaryUIProps): react_jsx_runtime.JSX.Element;
 
 declare function forkable<TProps extends object>(definition: ForkBoundaryDefinition<TProps>): {
     (props: TProps): react_jsx_runtime.JSX.Element;
@@ -197,9 +199,8 @@ interface ForkUIProps {
     slotId: string;
     title?: string;
     slotLabel?: string;
-    examplePrompts?: string[];
 }
-declare function ForkUI({ slotId, title, slotLabel, examplePrompts }: ForkUIProps): react_jsx_runtime.JSX.Element;
+declare function ForkUI({ slotId, title, slotLabel }: ForkUIProps): react_jsx_runtime.JSX.Element;
 
 declare function ForkButton({ onClick }: {
     onClick?: () => void;
@@ -214,7 +215,6 @@ interface ForkPanelProps {
     targetId?: string;
     targetLabel?: string;
     historyMode?: "slot" | "boundary" | "none";
-    examplePrompts?: string[];
     onSubmit: (prompt: string, targetId: string, containerId?: string | null) => void;
     onUndo?: (targetId: string) => Promise<any>;
     onClose: () => void;
@@ -231,7 +231,7 @@ interface ForkPanelProps {
      */
     embedded?: boolean;
 }
-declare function ForkPanel({ state, fork, events, error, slotId, targetId, targetLabel, historyMode, examplePrompts, onSubmit, onUndo, onClose, baseUrl, apiKey, userId, userHash, appId, embedded, }: ForkPanelProps): react_jsx_runtime.JSX.Element;
+declare function ForkPanel({ state, fork, events, error, slotId, targetId, targetLabel, historyMode, onSubmit, onUndo, onClose, baseUrl, apiKey, userId, userHash, appId, embedded, }: ForkPanelProps): react_jsx_runtime.JSX.Element;
 
 declare function useFork(): {
     state: ForkState;
@@ -307,4 +307,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, type PreviewSessionPayload, forkable, registerForkShared, useBoundaryFork, useFork, useForkChatPanel, usePreviewSession };
+/**
+ * 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

@@ -87,7 +87,6 @@ type ForkChatTargetInput = {
 };
 type ForkChatPanelOptions = ForkChatTargetInput;
 type ForkChatInterfaceProps = ForkChatTargetInput & {
-    examplePrompts?: string[];
     /**
      * When true, render the panel flat inside its container instead of as a
      * fixed-position side drawer. Suppresses the body-margin push and the
@@ -163,6 +162,10 @@ interface PreviewSessionPayload {
     };
     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;
@@ -182,9 +185,8 @@ declare function ForkChatInterface(props: ForkChatInterfaceProps): react_jsx_run
 interface ForkBoundaryUIProps {
     boundaryId: string;
     title?: string;
-    examplePrompts?: string[];
 }
-declare function ForkBoundaryUI({ boundaryId, title, examplePrompts }: ForkBoundaryUIProps): react_jsx_runtime.JSX.Element;
+declare function ForkBoundaryUI({ boundaryId, title }: ForkBoundaryUIProps): react_jsx_runtime.JSX.Element;
 
 declare function forkable<TProps extends object>(definition: ForkBoundaryDefinition<TProps>): {
     (props: TProps): react_jsx_runtime.JSX.Element;
@@ -197,9 +199,8 @@ interface ForkUIProps {
     slotId: string;
     title?: string;
     slotLabel?: string;
-    examplePrompts?: string[];
 }
-declare function ForkUI({ slotId, title, slotLabel, examplePrompts }: ForkUIProps): react_jsx_runtime.JSX.Element;
+declare function ForkUI({ slotId, title, slotLabel }: ForkUIProps): react_jsx_runtime.JSX.Element;
 
 declare function ForkButton({ onClick }: {
     onClick?: () => void;
@@ -214,7 +215,6 @@ interface ForkPanelProps {
     targetId?: string;
     targetLabel?: string;
     historyMode?: "slot" | "boundary" | "none";
-    examplePrompts?: string[];
     onSubmit: (prompt: string, targetId: string, containerId?: string | null) => void;
     onUndo?: (targetId: string) => Promise<any>;
     onClose: () => void;
@@ -231,7 +231,7 @@ interface ForkPanelProps {
      */
     embedded?: boolean;
 }
-declare function ForkPanel({ state, fork, events, error, slotId, targetId, targetLabel, historyMode, examplePrompts, onSubmit, onUndo, onClose, baseUrl, apiKey, userId, userHash, appId, embedded, }: ForkPanelProps): react_jsx_runtime.JSX.Element;
+declare function ForkPanel({ state, fork, events, error, slotId, targetId, targetLabel, historyMode, onSubmit, onUndo, onClose, baseUrl, apiKey, userId, userHash, appId, embedded, }: ForkPanelProps): react_jsx_runtime.JSX.Element;
 
 declare function useFork(): {
     state: ForkState;
@@ -307,4 +307,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, type PreviewSessionPayload, forkable, registerForkShared, useBoundaryFork, useFork, useForkChatPanel, usePreviewSession };
+/**
+ * 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 };