@fork-api/chat-sdk 0.1.166 → 0.1.167

package/dist/index.d.cts

@@ -153,6 +153,12 @@ interface ForkSlotProps {
     children: ReactElement<unknown, ComponentType<any>>;
     /** Whitelist of API paths the forked component can fetch (iframe mode only). In direct mode, the component can call fetch() natively. */
     allowedFetches?: string[];
+    /**
+     * Stable host-entity identity for persistent Fork data and LLM features.
+     * Example:
+     * { rows: { entityType: "account", getId: "id", hashFields: ["name", "stage"] } }
+     */
+    entityBindings?: Record<string, unknown>;
     /** Optional GitHub repo in "owner/repo" format. If omitted, Fork resolves repo access from appId onboarding metadata. */
     githubRepo?: string;
     /** Callbacks the forked component can invoke on the parent app (bridged via postMessage) */
@@ -210,9 +216,17 @@ interface PreviewSessionPayload {
 
 declare function usePreviewSession(): PreviewSessionPayload | null;
 
+interface ForkRuntimeGlobal {
+    dataFetch: (path: string, body?: unknown, method?: string) => Promise<any>;
+}
+declare global {
+    interface Window {
+        __FORK_RUNTIME__?: ForkRuntimeGlobal;
+    }
+}
 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;
+declare function ForkSlot({ slotId, props, children, allowedFetches, entityBindings, githubRepo, callbacks, mode, shared, events }: ForkSlotProps): react_jsx_runtime.JSX.Element;
 
 declare function ForkChatInterface(props: ForkChatInterfaceProps): react_jsx_runtime.JSX.Element;
 
@@ -433,6 +447,255 @@ declare function useForkChatPanel(options: ForkChatPanelOptions): {
     adoptRunningFork: (forkId: string) => Promise<void>;
 };
 
+type ForkFeatureKind = "data_value" | "llm_field" | "tagging" | "briefing" | "kv_store";
+type ForkDataSource = "user" | "llm" | "system";
+type ForkDataStatus = "pending" | "complete" | "error" | "stale";
+type ForkLlmJobStatus = "queued" | "running" | "complete" | "error" | "cancelled";
+interface ForkEntityRef {
+    namespace?: string;
+    type: string;
+    id: string;
+}
+interface ForkFeature {
+    id: string;
+    tenantId: string;
+    appId: string;
+    containerId: string;
+    forkId: string | null;
+    artifactId: string | null;
+    targetKind: "slot" | "module" | null;
+    targetId: string | null;
+    key: string;
+    kind: ForkFeatureKind;
+    config: Record<string, unknown>;
+    status: "active" | "archived";
+    createdAt: string;
+    updatedAt: string;
+}
+interface ForkFeatureValue<T = unknown> {
+    id: string;
+    tenantId: string;
+    appId: string;
+    containerId: string;
+    featureId: string;
+    entity: Required<ForkEntityRef>;
+    valueKey: string;
+    value: T;
+    inputHash: string | null;
+    source: ForkDataSource;
+    llmJobId: string | null;
+    status: ForkDataStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ForkFeatureOption {
+    id: string;
+    featureId: string;
+    optionKey: string;
+    label: string;
+    color: string | null;
+    metadata: Record<string, unknown>;
+    archivedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ForkLlmJob {
+    id: string;
+    tenantId: string;
+    appId: string;
+    containerId: string;
+    forkId: string | null;
+    featureId: string;
+    entity: Required<ForkEntityRef>;
+    valueKey: string;
+    operation: string;
+    inputHash: string;
+    promptHash: string;
+    model: string;
+    status: ForkLlmJobStatus;
+    attempts: number;
+    result: unknown;
+    error: string | null;
+    promptTokens: number;
+    completionTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costUsd: number;
+    latencyMs: number | null;
+    valueId: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    updatedAt: string;
+}
+interface ForkDataClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    appId: string;
+    containerId: string;
+    userId?: string;
+    userHash?: string;
+    extraHeaders?: Record<string, string>;
+}
+interface EnsureFeatureInput {
+    key: string;
+    kind?: ForkFeatureKind;
+    config?: Record<string, unknown>;
+    forkId?: string | null;
+    artifactId?: string | null;
+    targetKind?: "slot" | "module" | null;
+    targetId?: string | null;
+}
+interface QueryValuesInput {
+    featureId?: string;
+    featureKey?: string;
+    entities?: ForkEntityRef[];
+    valueKeys?: string[];
+}
+interface SetValuesInput {
+    featureId?: string;
+    featureKey?: string;
+    kind?: ForkFeatureKind;
+    config?: Record<string, unknown>;
+    values: Array<{
+        entity: ForkEntityRef;
+        valueKey?: string;
+        value: unknown;
+        inputHash?: string | null;
+        source?: ForkDataSource;
+        status?: ForkDataStatus;
+    }>;
+}
+interface SetOptionsInput {
+    featureId?: string;
+    featureKey?: string;
+    kind?: ForkFeatureKind;
+    config?: Record<string, unknown>;
+    options: Array<{
+        optionKey: string;
+        label: string;
+        color?: string | null;
+        metadata?: Record<string, unknown>;
+        archived?: boolean;
+    }>;
+}
+interface EnsureLlmJobsInput {
+    featureId?: string;
+    featureKey?: string;
+    kind?: ForkFeatureKind;
+    config?: Record<string, unknown>;
+    forkId?: string | null;
+    targetKind?: "slot" | "module" | null;
+    targetId?: string | null;
+    operation?: string;
+    model?: string;
+    prompt?: string;
+    system?: string;
+    promptHash?: string;
+    outputFormat?: "text" | "json";
+    maxTokens?: number;
+    temperature?: number;
+    force?: boolean;
+    jobs: Array<{
+        entity: ForkEntityRef;
+        valueKey?: string;
+        input: unknown;
+        inputHash?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+interface QueryLlmJobsInput {
+    jobIds?: string[];
+    featureId?: string;
+    featureKey?: string;
+    entities?: ForkEntityRef[];
+}
+interface ForkDataClient {
+    listFeatures(): Promise<{
+        features: ForkFeature[];
+    }>;
+    ensureFeature(input: EnsureFeatureInput): Promise<{
+        feature: ForkFeature;
+    }>;
+    queryValues<T = unknown>(input: QueryValuesInput): Promise<{
+        feature: ForkFeature | null;
+        values: Array<ForkFeatureValue<T>>;
+    }>;
+    setValues(input: SetValuesInput): Promise<{
+        feature: ForkFeature;
+        values: ForkFeatureValue[];
+    }>;
+    listOptions(input: {
+        featureId?: string;
+        featureKey?: string;
+        includeArchived?: boolean;
+    }): Promise<{
+        feature: ForkFeature | null;
+        options: ForkFeatureOption[];
+    }>;
+    setOptions(input: SetOptionsInput): Promise<{
+        feature: ForkFeature;
+        options: ForkFeatureOption[];
+    }>;
+    ensureLlmJobs(input: EnsureLlmJobsInput): Promise<{
+        feature: ForkFeature;
+        jobs: ForkLlmJob[];
+        values: ForkFeatureValue[];
+    }>;
+    queryLlmJobs(input: QueryLlmJobsInput): Promise<{
+        feature: ForkFeature | null;
+        jobs: ForkLlmJob[];
+    }>;
+}
+declare function forkEntityValueKey(entity: ForkEntityRef, valueKey?: string): string;
+declare function createForkDataClient(config: ForkDataClientConfig): ForkDataClient;
+declare function useForkDataClient(containerIdOverride?: string | null): ForkDataClient | null;
+interface UseForkFeatureValuesInput extends QueryValuesInput {
+    containerId?: string | null;
+    enabled?: boolean;
+    pollMs?: number;
+}
+declare function useForkFeatureValues<T = unknown>(input: UseForkFeatureValuesInput): {
+    feature: ForkFeature | null;
+    values: ForkFeatureValue<T>[];
+    byKey: Map<string, ForkFeatureValue<T>>;
+    getValue: (entity: ForkEntityRef, valueKey?: string) => ForkFeatureValue<T> | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+declare function useForkDataMutation(containerIdOverride?: string | null): {
+    client: ForkDataClient | null;
+    ensureFeature: (input: EnsureFeatureInput) => Promise<{
+        feature: ForkFeature;
+    }>;
+    setValues: (input: SetValuesInput) => Promise<{
+        feature: ForkFeature;
+        values: ForkFeatureValue[];
+    }>;
+    setOptions: (input: SetOptionsInput) => Promise<{
+        feature: ForkFeature;
+        options: ForkFeatureOption[];
+    }>;
+};
+interface UseForkLlmJobsInput extends EnsureLlmJobsInput {
+    containerId?: string | null;
+    enabled?: boolean;
+    pollMs?: number;
+}
+declare function useForkLlmJobs<T = unknown>(input: UseForkLlmJobsInput): {
+    feature: ForkFeature | null;
+    jobs: ForkLlmJob[];
+    values: ForkFeatureValue<T>[];
+    byKey: Map<string, ForkFeatureValue<T>>;
+    getValue: (entity: ForkEntityRef, valueKey?: string) => ForkFeatureValue<T> | null;
+    loading: boolean;
+    error: Error | null;
+    ensure: () => Promise<void>;
+    refresh: () => Promise<void>;
+    running: boolean;
+};
+
 /**
  * Containers v2 — SDK-side manifest client.
  *
@@ -537,4 +800,4 @@ declare function clearCachedManifest(tenantId: string, appId: string, userId: st
  */
 declare function manifestDiffers(a: Manifest | null, b: Manifest | null): boolean;
 
-export { type Fork, type ForkActivity, type ForkActivitySummary, type ForkActivityTargetKind, 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 };
+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 };

package/dist/index.d.ts

@@ -153,6 +153,12 @@ interface ForkSlotProps {
     children: ReactElement<unknown, ComponentType<any>>;
     /** Whitelist of API paths the forked component can fetch (iframe mode only). In direct mode, the component can call fetch() natively. */
     allowedFetches?: string[];
+    /**
+     * Stable host-entity identity for persistent Fork data and LLM features.
+     * Example:
+     * { rows: { entityType: "account", getId: "id", hashFields: ["name", "stage"] } }
+     */
+    entityBindings?: Record<string, unknown>;
     /** Optional GitHub repo in "owner/repo" format. If omitted, Fork resolves repo access from appId onboarding metadata. */
     githubRepo?: string;
     /** Callbacks the forked component can invoke on the parent app (bridged via postMessage) */
@@ -210,9 +216,17 @@ interface PreviewSessionPayload {
 
 declare function usePreviewSession(): PreviewSessionPayload | null;
 
+interface ForkRuntimeGlobal {
+    dataFetch: (path: string, body?: unknown, method?: string) => Promise<any>;
+}
+declare global {
+    interface Window {
+        __FORK_RUNTIME__?: ForkRuntimeGlobal;
+    }
+}
 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;
+declare function ForkSlot({ slotId, props, children, allowedFetches, entityBindings, githubRepo, callbacks, mode, shared, events }: ForkSlotProps): react_jsx_runtime.JSX.Element;
 
 declare function ForkChatInterface(props: ForkChatInterfaceProps): react_jsx_runtime.JSX.Element;
 
@@ -433,6 +447,255 @@ declare function useForkChatPanel(options: ForkChatPanelOptions): {
     adoptRunningFork: (forkId: string) => Promise<void>;
 };
 
+type ForkFeatureKind = "data_value" | "llm_field" | "tagging" | "briefing" | "kv_store";
+type ForkDataSource = "user" | "llm" | "system";
+type ForkDataStatus = "pending" | "complete" | "error" | "stale";
+type ForkLlmJobStatus = "queued" | "running" | "complete" | "error" | "cancelled";
+interface ForkEntityRef {
+    namespace?: string;
+    type: string;
+    id: string;
+}
+interface ForkFeature {
+    id: string;
+    tenantId: string;
+    appId: string;
+    containerId: string;
+    forkId: string | null;
+    artifactId: string | null;
+    targetKind: "slot" | "module" | null;
+    targetId: string | null;
+    key: string;
+    kind: ForkFeatureKind;
+    config: Record<string, unknown>;
+    status: "active" | "archived";
+    createdAt: string;
+    updatedAt: string;
+}
+interface ForkFeatureValue<T = unknown> {
+    id: string;
+    tenantId: string;
+    appId: string;
+    containerId: string;
+    featureId: string;
+    entity: Required<ForkEntityRef>;
+    valueKey: string;
+    value: T;
+    inputHash: string | null;
+    source: ForkDataSource;
+    llmJobId: string | null;
+    status: ForkDataStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ForkFeatureOption {
+    id: string;
+    featureId: string;
+    optionKey: string;
+    label: string;
+    color: string | null;
+    metadata: Record<string, unknown>;
+    archivedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ForkLlmJob {
+    id: string;
+    tenantId: string;
+    appId: string;
+    containerId: string;
+    forkId: string | null;
+    featureId: string;
+    entity: Required<ForkEntityRef>;
+    valueKey: string;
+    operation: string;
+    inputHash: string;
+    promptHash: string;
+    model: string;
+    status: ForkLlmJobStatus;
+    attempts: number;
+    result: unknown;
+    error: string | null;
+    promptTokens: number;
+    completionTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    costUsd: number;
+    latencyMs: number | null;
+    valueId: string | null;
+    createdAt: string;
+    startedAt: string | null;
+    completedAt: string | null;
+    updatedAt: string;
+}
+interface ForkDataClientConfig {
+    baseUrl: string;
+    apiKey: string;
+    appId: string;
+    containerId: string;
+    userId?: string;
+    userHash?: string;
+    extraHeaders?: Record<string, string>;
+}
+interface EnsureFeatureInput {
+    key: string;
+    kind?: ForkFeatureKind;
+    config?: Record<string, unknown>;
+    forkId?: string | null;
+    artifactId?: string | null;
+    targetKind?: "slot" | "module" | null;
+    targetId?: string | null;
+}
+interface QueryValuesInput {
+    featureId?: string;
+    featureKey?: string;
+    entities?: ForkEntityRef[];
+    valueKeys?: string[];
+}
+interface SetValuesInput {
+    featureId?: string;
+    featureKey?: string;
+    kind?: ForkFeatureKind;
+    config?: Record<string, unknown>;
+    values: Array<{
+        entity: ForkEntityRef;
+        valueKey?: string;
+        value: unknown;
+        inputHash?: string | null;
+        source?: ForkDataSource;
+        status?: ForkDataStatus;
+    }>;
+}
+interface SetOptionsInput {
+    featureId?: string;
+    featureKey?: string;
+    kind?: ForkFeatureKind;
+    config?: Record<string, unknown>;
+    options: Array<{
+        optionKey: string;
+        label: string;
+        color?: string | null;
+        metadata?: Record<string, unknown>;
+        archived?: boolean;
+    }>;
+}
+interface EnsureLlmJobsInput {
+    featureId?: string;
+    featureKey?: string;
+    kind?: ForkFeatureKind;
+    config?: Record<string, unknown>;
+    forkId?: string | null;
+    targetKind?: "slot" | "module" | null;
+    targetId?: string | null;
+    operation?: string;
+    model?: string;
+    prompt?: string;
+    system?: string;
+    promptHash?: string;
+    outputFormat?: "text" | "json";
+    maxTokens?: number;
+    temperature?: number;
+    force?: boolean;
+    jobs: Array<{
+        entity: ForkEntityRef;
+        valueKey?: string;
+        input: unknown;
+        inputHash?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+interface QueryLlmJobsInput {
+    jobIds?: string[];
+    featureId?: string;
+    featureKey?: string;
+    entities?: ForkEntityRef[];
+}
+interface ForkDataClient {
+    listFeatures(): Promise<{
+        features: ForkFeature[];
+    }>;
+    ensureFeature(input: EnsureFeatureInput): Promise<{
+        feature: ForkFeature;
+    }>;
+    queryValues<T = unknown>(input: QueryValuesInput): Promise<{
+        feature: ForkFeature | null;
+        values: Array<ForkFeatureValue<T>>;
+    }>;
+    setValues(input: SetValuesInput): Promise<{
+        feature: ForkFeature;
+        values: ForkFeatureValue[];
+    }>;
+    listOptions(input: {
+        featureId?: string;
+        featureKey?: string;
+        includeArchived?: boolean;
+    }): Promise<{
+        feature: ForkFeature | null;
+        options: ForkFeatureOption[];
+    }>;
+    setOptions(input: SetOptionsInput): Promise<{
+        feature: ForkFeature;
+        options: ForkFeatureOption[];
+    }>;
+    ensureLlmJobs(input: EnsureLlmJobsInput): Promise<{
+        feature: ForkFeature;
+        jobs: ForkLlmJob[];
+        values: ForkFeatureValue[];
+    }>;
+    queryLlmJobs(input: QueryLlmJobsInput): Promise<{
+        feature: ForkFeature | null;
+        jobs: ForkLlmJob[];
+    }>;
+}
+declare function forkEntityValueKey(entity: ForkEntityRef, valueKey?: string): string;
+declare function createForkDataClient(config: ForkDataClientConfig): ForkDataClient;
+declare function useForkDataClient(containerIdOverride?: string | null): ForkDataClient | null;
+interface UseForkFeatureValuesInput extends QueryValuesInput {
+    containerId?: string | null;
+    enabled?: boolean;
+    pollMs?: number;
+}
+declare function useForkFeatureValues<T = unknown>(input: UseForkFeatureValuesInput): {
+    feature: ForkFeature | null;
+    values: ForkFeatureValue<T>[];
+    byKey: Map<string, ForkFeatureValue<T>>;
+    getValue: (entity: ForkEntityRef, valueKey?: string) => ForkFeatureValue<T> | null;
+    loading: boolean;
+    error: Error | null;
+    refresh: () => Promise<void>;
+};
+declare function useForkDataMutation(containerIdOverride?: string | null): {
+    client: ForkDataClient | null;
+    ensureFeature: (input: EnsureFeatureInput) => Promise<{
+        feature: ForkFeature;
+    }>;
+    setValues: (input: SetValuesInput) => Promise<{
+        feature: ForkFeature;
+        values: ForkFeatureValue[];
+    }>;
+    setOptions: (input: SetOptionsInput) => Promise<{
+        feature: ForkFeature;
+        options: ForkFeatureOption[];
+    }>;
+};
+interface UseForkLlmJobsInput extends EnsureLlmJobsInput {
+    containerId?: string | null;
+    enabled?: boolean;
+    pollMs?: number;
+}
+declare function useForkLlmJobs<T = unknown>(input: UseForkLlmJobsInput): {
+    feature: ForkFeature | null;
+    jobs: ForkLlmJob[];
+    values: ForkFeatureValue<T>[];
+    byKey: Map<string, ForkFeatureValue<T>>;
+    getValue: (entity: ForkEntityRef, valueKey?: string) => ForkFeatureValue<T> | null;
+    loading: boolean;
+    error: Error | null;
+    ensure: () => Promise<void>;
+    refresh: () => Promise<void>;
+    running: boolean;
+};
+
 /**
  * Containers v2 — SDK-side manifest client.
  *
@@ -537,4 +800,4 @@ declare function clearCachedManifest(tenantId: string, appId: string, userId: st
  */
 declare function manifestDiffers(a: Manifest | null, b: Manifest | null): boolean;
 
-export { type Fork, type ForkActivity, type ForkActivitySummary, type ForkActivityTargetKind, 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 };
+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 };