@fork-api/chat-sdk 0.1.173 → 0.1.175

package/dist/index.d.cts

@@ -15,6 +15,11 @@ interface Fork {
     summary?: string;
     /** Rough estimate in minutes for how long the agent will take. Set after the Haiku title call resolves. */
     estimateMinutes?: number;
+    /** True when this user authored the fork and hasn't seen its one-shot
+     *  reveal animation yet (server-tracked via forks.reveal_seen_at, once
+     *  ever across tabs/devices). Set client-side on live SSE completion;
+     *  DirectForkSlot plays the reveal and records it via POST /forks/reveals. */
+    revealPending?: boolean;
     createdAt: string;
     completedAt?: string;
     error?: string;
@@ -58,24 +63,32 @@ interface ForkProviderBase {
     shared?: ForkSharedRegistry;
 }
 /**
- * User identity — provide EITHER userId OR authUrl:
+ * User identity — provide EITHER userId (optionally with userHash) OR authUrl:
  *
- * - `userId`: Client-asserted, no server verification (dev/testing only).
+ * - `userId` alone: Client-asserted, no server verification (dev/testing only).
+ * - `userId` + `userHash`: Host-brokered verified identity. Your backend
+ *   computes userHash = HMAC-SHA256(sk_fork_key, userId) and your app passes
+ *   both as props. Fork never touches cookies or Web Storage for identity, so
+ *   this is the required mode for embedded/iframe contexts where third-party
+ *   cookies are blocked (e.g. app-store review environments).
  * - `authUrl`: URL on your backend that returns `{ userId, userHash }`.
  *   The SDK calls this on mount (same-origin, cookies sent automatically).
- *   Your backend computes: userHash = HMAC-SHA256(sk_fork_key, userId).
- *   This provides verified per-user fork isolation.
- *   If the verified user is also a Fork tenant operator (their email matches
- *   a fork_users row with a user_roles entry on this tenant), the SDK
- *   transparently enters admin mode and acts as their mapped end-user — set
- *   the mapping in Fork's Team Settings → End user.
+ *   Relies on the host's cookie session, so it does not work where the host
+ *   page's cookies are third-party — prefer the userHash prop mode there.
+ *
+ * In either verified mode, if the user is also a Fork tenant operator (their
+ * email matches a fork_users row with a user_roles entry on this tenant), the
+ * SDK transparently enters admin mode and acts as their mapped end-user — set
+ * the mapping in Fork's Team Settings → End user.
  */
 type ForkProviderProps = ForkProviderBase & ({
     userId: string;
+    userHash?: string;
     authUrl?: never;
 } | {
     authUrl: string;
     userId?: never;
+    userHash?: never;
 });
 interface ForkBoundaryRegistration {
     id: string;
@@ -172,50 +185,24 @@ 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;
-    };
-    operator_id: number;
-    container_id?: string | null;
-    /** Human-readable container label for preview UI. Defaults to "Fork". */
-    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;
+interface AdminContainer {
+    id: string;
+    name: string;
+    isPrimary: boolean;
+    forkCount: number;
+}
+interface AdminContext {
+    /** True when the verified caller is an operator (or a mapped end-user) on
+     *  this tenant — resolved server-side via GET /admin/containers. */
+    isAdmin: boolean;
+    /** The tenant end-user the operator acts as (their mapped End-user). */
+    actingUserId: string | null;
+    /** Container currently being viewed/authored; null before one resolves. */
+    containerId: string | null;
+    containerName: string | null;
+    /** Containers the acting end-user can access (for the panel switcher). */
+    containers: AdminContainer[];
 }
-
-declare function usePreviewSession(): PreviewSessionPayload | null;
-
 interface ForkRuntimeGlobal {
     dataFetch: (path: string, body?: unknown, method?: string) => Promise<any>;
 }
@@ -730,6 +717,8 @@ interface ManifestEntry {
     legacyBundleUrl: string | null;
     buildId: string | null;
     updatedAt: string;
+    /** Author-only, once-ever reveal-animation flag (server-tracked). */
+    revealPending?: boolean;
 }
 interface ManifestModuleEntry {
     forkId: string;
@@ -804,4 +793,4 @@ declare function clearCachedManifest(tenantId: string, appId: string, userId: st
  */
 declare function manifestDiffers(a: Manifest | null, b: Manifest | null): boolean;
 
-export { type EnsureFeatureInput, type EnsureLlmJobsInput, type Fork, type ForkActivity, type ForkActivitySummary, type ForkActivityTargetKind, type ForkBoundaryDefinition, ForkBoundaryUI, ForkButton, ForkChatInterface, type ForkChatInterfaceProps, type ForkChatPanelOptions, type ForkChatTarget, type ForkDataClient, type ForkDataClientConfig, type ForkDataSource, type ForkDataStatus, type ForkEntityRef, type ForkEvent, type ForkFeature, type ForkFeatureKind, type ForkFeatureOption, type ForkFeatureValue, type ForkLlmJob, type ForkLlmJobStatus, ForkPanel, ForkProvider, type ForkProviderProps, type ForkSharedRegistry, ForkSlot, type ForkSlotProps, type ForkState, ForkUI, type LoadManifestInput, type Manifest, type ManifestEntry, type ManifestModuleEntry, type PreviewSessionPayload, type QueryLlmJobsInput, type QueryValuesInput, type SetOptionsInput, type SetValuesInput, type UseForkFeatureValuesInput, type UseForkLlmJobsInput, clearCachedManifest, createForkDataClient, forkEntityValueKey, forkable, loadManifest, manifestDiffers, readCachedManifest, registerForkShared, useBoundaryFork, useFork, useForkChatPanel, useForkDataClient, useForkDataMutation, useForkFeatureValues, useForkLlmJobs, usePreviewSession, writeCachedManifest };
+export { type AdminContainer, type AdminContext, type EnsureFeatureInput, type EnsureLlmJobsInput, type Fork, type ForkActivity, type ForkActivitySummary, type ForkActivityTargetKind, type ForkBoundaryDefinition, ForkBoundaryUI, ForkButton, ForkChatInterface, type ForkChatInterfaceProps, type ForkChatPanelOptions, type ForkChatTarget, type ForkDataClient, type ForkDataClientConfig, type ForkDataSource, type ForkDataStatus, type ForkEntityRef, type ForkEvent, type ForkFeature, type ForkFeatureKind, type ForkFeatureOption, type ForkFeatureValue, type ForkLlmJob, type ForkLlmJobStatus, ForkPanel, ForkProvider, type ForkProviderProps, type ForkSharedRegistry, ForkSlot, type ForkSlotProps, type ForkState, ForkUI, type LoadManifestInput, type Manifest, type ManifestEntry, type ManifestModuleEntry, type QueryLlmJobsInput, type QueryValuesInput, type SetOptionsInput, type SetValuesInput, type UseForkFeatureValuesInput, type UseForkLlmJobsInput, clearCachedManifest, createForkDataClient, forkEntityValueKey, forkable, loadManifest, manifestDiffers, readCachedManifest, registerForkShared, useBoundaryFork, useFork, useForkChatPanel, useForkDataClient, useForkDataMutation, useForkFeatureValues, useForkLlmJobs, writeCachedManifest };

package/dist/index.d.ts

@@ -15,6 +15,11 @@ interface Fork {
     summary?: string;
     /** Rough estimate in minutes for how long the agent will take. Set after the Haiku title call resolves. */
     estimateMinutes?: number;
+    /** True when this user authored the fork and hasn't seen its one-shot
+     *  reveal animation yet (server-tracked via forks.reveal_seen_at, once
+     *  ever across tabs/devices). Set client-side on live SSE completion;
+     *  DirectForkSlot plays the reveal and records it via POST /forks/reveals. */
+    revealPending?: boolean;
     createdAt: string;
     completedAt?: string;
     error?: string;
@@ -58,24 +63,32 @@ interface ForkProviderBase {
     shared?: ForkSharedRegistry;
 }
 /**
- * User identity — provide EITHER userId OR authUrl:
+ * User identity — provide EITHER userId (optionally with userHash) OR authUrl:
  *
- * - `userId`: Client-asserted, no server verification (dev/testing only).
+ * - `userId` alone: Client-asserted, no server verification (dev/testing only).
+ * - `userId` + `userHash`: Host-brokered verified identity. Your backend
+ *   computes userHash = HMAC-SHA256(sk_fork_key, userId) and your app passes
+ *   both as props. Fork never touches cookies or Web Storage for identity, so
+ *   this is the required mode for embedded/iframe contexts where third-party
+ *   cookies are blocked (e.g. app-store review environments).
  * - `authUrl`: URL on your backend that returns `{ userId, userHash }`.
  *   The SDK calls this on mount (same-origin, cookies sent automatically).
- *   Your backend computes: userHash = HMAC-SHA256(sk_fork_key, userId).
- *   This provides verified per-user fork isolation.
- *   If the verified user is also a Fork tenant operator (their email matches
- *   a fork_users row with a user_roles entry on this tenant), the SDK
- *   transparently enters admin mode and acts as their mapped end-user — set
- *   the mapping in Fork's Team Settings → End user.
+ *   Relies on the host's cookie session, so it does not work where the host
+ *   page's cookies are third-party — prefer the userHash prop mode there.
+ *
+ * In either verified mode, if the user is also a Fork tenant operator (their
+ * email matches a fork_users row with a user_roles entry on this tenant), the
+ * SDK transparently enters admin mode and acts as their mapped end-user — set
+ * the mapping in Fork's Team Settings → End user.
  */
 type ForkProviderProps = ForkProviderBase & ({
     userId: string;
+    userHash?: string;
     authUrl?: never;
 } | {
     authUrl: string;
     userId?: never;
+    userHash?: never;
 });
 interface ForkBoundaryRegistration {
     id: string;
@@ -172,50 +185,24 @@ 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;
-    };
-    operator_id: number;
-    container_id?: string | null;
-    /** Human-readable container label for preview UI. Defaults to "Fork". */
-    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;
+interface AdminContainer {
+    id: string;
+    name: string;
+    isPrimary: boolean;
+    forkCount: number;
+}
+interface AdminContext {
+    /** True when the verified caller is an operator (or a mapped end-user) on
+     *  this tenant — resolved server-side via GET /admin/containers. */
+    isAdmin: boolean;
+    /** The tenant end-user the operator acts as (their mapped End-user). */
+    actingUserId: string | null;
+    /** Container currently being viewed/authored; null before one resolves. */
+    containerId: string | null;
+    containerName: string | null;
+    /** Containers the acting end-user can access (for the panel switcher). */
+    containers: AdminContainer[];
 }
-
-declare function usePreviewSession(): PreviewSessionPayload | null;
-
 interface ForkRuntimeGlobal {
     dataFetch: (path: string, body?: unknown, method?: string) => Promise<any>;
 }
@@ -730,6 +717,8 @@ interface ManifestEntry {
     legacyBundleUrl: string | null;
     buildId: string | null;
     updatedAt: string;
+    /** Author-only, once-ever reveal-animation flag (server-tracked). */
+    revealPending?: boolean;
 }
 interface ManifestModuleEntry {
     forkId: string;
@@ -804,4 +793,4 @@ declare function clearCachedManifest(tenantId: string, appId: string, userId: st
  */
 declare function manifestDiffers(a: Manifest | null, b: Manifest | null): boolean;
 
-export { type EnsureFeatureInput, type EnsureLlmJobsInput, type Fork, type ForkActivity, type ForkActivitySummary, type ForkActivityTargetKind, type ForkBoundaryDefinition, ForkBoundaryUI, ForkButton, ForkChatInterface, type ForkChatInterfaceProps, type ForkChatPanelOptions, type ForkChatTarget, type ForkDataClient, type ForkDataClientConfig, type ForkDataSource, type ForkDataStatus, type ForkEntityRef, type ForkEvent, type ForkFeature, type ForkFeatureKind, type ForkFeatureOption, type ForkFeatureValue, type ForkLlmJob, type ForkLlmJobStatus, ForkPanel, ForkProvider, type ForkProviderProps, type ForkSharedRegistry, ForkSlot, type ForkSlotProps, type ForkState, ForkUI, type LoadManifestInput, type Manifest, type ManifestEntry, type ManifestModuleEntry, type PreviewSessionPayload, type QueryLlmJobsInput, type QueryValuesInput, type SetOptionsInput, type SetValuesInput, type UseForkFeatureValuesInput, type UseForkLlmJobsInput, clearCachedManifest, createForkDataClient, forkEntityValueKey, forkable, loadManifest, manifestDiffers, readCachedManifest, registerForkShared, useBoundaryFork, useFork, useForkChatPanel, useForkDataClient, useForkDataMutation, useForkFeatureValues, useForkLlmJobs, usePreviewSession, writeCachedManifest };
+export { type AdminContainer, type AdminContext, type EnsureFeatureInput, type EnsureLlmJobsInput, type Fork, type ForkActivity, type ForkActivitySummary, type ForkActivityTargetKind, type ForkBoundaryDefinition, ForkBoundaryUI, ForkButton, ForkChatInterface, type ForkChatInterfaceProps, type ForkChatPanelOptions, type ForkChatTarget, type ForkDataClient, type ForkDataClientConfig, type ForkDataSource, type ForkDataStatus, type ForkEntityRef, type ForkEvent, type ForkFeature, type ForkFeatureKind, type ForkFeatureOption, type ForkFeatureValue, type ForkLlmJob, type ForkLlmJobStatus, ForkPanel, ForkProvider, type ForkProviderProps, type ForkSharedRegistry, ForkSlot, type ForkSlotProps, type ForkState, ForkUI, type LoadManifestInput, type Manifest, type ManifestEntry, type ManifestModuleEntry, type QueryLlmJobsInput, type QueryValuesInput, type SetOptionsInput, type SetValuesInput, type UseForkFeatureValuesInput, type UseForkLlmJobsInput, clearCachedManifest, createForkDataClient, forkEntityValueKey, forkable, loadManifest, manifestDiffers, readCachedManifest, registerForkShared, useBoundaryFork, useFork, useForkChatPanel, useForkDataClient, useForkDataMutation, useForkFeatureValues, useForkLlmJobs, writeCachedManifest };