@fencyai/react 0.1.215 → 0.1.216

package/dist/types/PendingApproval.d.ts

@@ -0,0 +1,89 @@
+import { ReactNode } from 'react';
+/**
+ * One manual action awaiting the user's answer.
+ *
+ * Flat rather than nested under a turn, but carrying `turnId`, so an app can box same-turn cards
+ * together and add its own "approve all" that fans out into one `approve()` per card. Nothing groups
+ * requests on the wire, because only the app author knows whether three approvals are three
+ * decisions or one.
+ *
+ * @public
+ */
+export interface PendingApproval {
+    actionCallId: string;
+    /** The agent task that offered it. */
+    turnId: string;
+    name: string;
+    input: unknown;
+    /**
+     * The card's line, recomputed from the local declaration — no approval message travels on the
+     * wire, so a redeployed string applies to an old request.
+     */
+    approvalMessage: string;
+    /**
+     * Optional React body from the local `approvalContent` declaration. Takes precedence over
+     * `approvalMessage` in the stock card. Also local-only — nothing travels on the wire.
+     */
+    approvalContent?: ReactNode;
+    /**
+     * False until the requesting turn's Completed progress event. ExploreProduct persists via
+     * POST /agent/complete immediately before publishing Completed, so enabling on that event means
+     * manualActionApprovalRequests are already on the server.
+     */
+    answerable: boolean;
+    /** True between the click and the result being recorded. */
+    inFlight: boolean;
+    /**
+     * Which button the user clicked, once the answer has been recorded successfully.
+     * Null while still awaiting an answer. Session-local — not rebuilt from fetchPendingApprovals.
+     */
+    decision: null | 'approved' | 'cancelled';
+    /** Bound closure — cannot answer the wrong call. */
+    approve: () => Promise<void>;
+    /** Bound closure. Posts `REJECTED`, and needs its own session like any other answer. */
+    cancel: () => Promise<void>;
+    /**
+     * Submit a whole turn: APPROVED for the given call ids, REJECTED for the rest on this turn.
+     * Kickoff runs once after the batch, not per row.
+     */
+    submitTurn: (approvedCallIds: string[]) => Promise<void>;
+}
+/**
+ * Returns manual actions still awaiting an answer, for rebuilding cards on mount.
+ *
+ * Your backend has everything it needs in one call: `GET /v1/agent-tasks?conversationId=` returns
+ * each turn's `successResponse.manualActionApprovalRequests` alongside its `manualActionResults`, and the offered
+ * ids with no recorded result are exactly the pending ones. Excluding recorded results is what makes
+ * a second device show the right thing after the first one answered.
+ *
+ * @public
+ */
+export type PendingApprovalRestore = {
+    actionCallId: string;
+    turnId: string;
+    name: string;
+    input: unknown;
+};
+export type UnusedApproval = {
+    name: string;
+    input: unknown;
+};
+export type FetchPendingApprovals = () => Promise<PendingApprovalRestore[] | {
+    pending: PendingApprovalRestore[];
+    unusedApprovals?: UnusedApproval[];
+}>;
+/**
+ * Returns a client token for a **SubmitManualActionResult** session, scoped to one action call.
+ *
+ * @remarks
+ * Your backend should call `POST /v1/sessions` with
+ * `{ submitManualActionResult: { agentTaskId, actionCallId } }` and return `{ clientToken }`.
+ * Because the session names the action, this is also where per-action authorization belongs — your
+ * backend can see exactly what is being answered before it hands the page a token.
+ *
+ * @public
+ */
+export type FetchSubmitManualActionResultClientToken = (agentTaskId: string, actionCallId: string) => Promise<{
+    clientToken: string;
+}>;
+//# sourceMappingURL=PendingApproval.d.ts.map

package/dist/types/PendingApproval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PendingApproval.d.ts","sourceRoot":"","sources":["../../src/types/PendingApproval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC5B,YAAY,EAAE,MAAM,CAAA;IACpB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAA;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,CAAA;IAC3B;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAA;IACnB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,QAAQ,EAAE,IAAI,GAAG,UAAU,GAAG,WAAW,CAAA;IACzC,oDAAoD;IACpD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,wFAAwF;IACxF,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3B;;;OAGG;IACH,UAAU,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3D;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACjC,YAAY,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,CAC3C,sBAAsB,EAAE,GACxB;IACI,OAAO,EAAE,sBAAsB,EAAE,CAAA;IACjC,eAAe,CAAC,EAAE,cAAc,EAAE,CAAA;CACrC,CACN,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wCAAwC,GAAG,CACnD,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,KACnB,OAAO,CAAC;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA"}

package/dist/types/UseAgentTasks.d.ts

@@ -1,8 +1,15 @@
 import { CreateAgentTaskParams, CreateAgentTaskResponse } from '@fencyai/js';
 import { AgentTask } from './AgentTask';
+import { PendingApproval } from './PendingApproval';
 import { FetchAgentTaskFileDownloadClientToken, FetchCreateAgentTaskClientToken } from './UseAgentTasksProps';
 export interface UseAgentTasks {
     agentTasks: AgentTask[];
+    /**
+     * Manual actions awaiting an answer, across every turn this hook knows about.
+     *
+     * Added alongside `agentTasks` rather than replacing it — renaming would break every consumer.
+     */
+    pendingApprovals: PendingApproval[];
     createAgentTask: (params: CreateAgentTaskParams, options?: {
         loadingText?: string;
         /** Called as soon as the task is registered locally (after stream is created). Useful for parallel runs. */

package/dist/types/UseAgentTasks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UseAgentTasks.d.ts","sourceRoot":"","sources":["../../src/types/UseAgentTasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,KAAK,EACR,qCAAqC,EACrC,+BAA+B,EAClC,MAAM,sBAAsB,CAAA;AAE7B,MAAM,WAAW,aAAa;IAC1B,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,eAAe,EAAE,CACb,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,4GAA4G;QAC5G,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;QAC5C;;;;;;WAMG;QACH,+BAA+B,CAAC,EAAE,+BAA+B,CAAA;QACjE;;;;;;WAMG;QACH,qCAAqC,CAAC,EAAE,qCAAqC,CAAA;KAChF,KACA,OAAO,CAAC,uBAAuB,CAAC,CAAA;IACrC,MAAM,CAAC,EAAE,SAAS,CAAA;CACrB"}
+{"version":3,"file":"UseAgentTasks.d.ts","sourceRoot":"","sources":["../../src/types/UseAgentTasks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACxD,OAAO,KAAK,EACR,qCAAqC,EACrC,+BAA+B,EAClC,MAAM,sBAAsB,CAAA;AAE7B,MAAM,WAAW,aAAa;IAC1B,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB;;;;OAIG;IACH,gBAAgB,EAAE,eAAe,EAAE,CAAA;IACnC,eAAe,EAAE,CACb,MAAM,EAAE,qBAAqB,EAC7B,OAAO,CAAC,EAAE;QACN,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,4GAA4G;QAC5G,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;QAC5C;;;;;;WAMG;QACH,+BAA+B,CAAC,EAAE,+BAA+B,CAAA;QACjE;;;;;;WAMG;QACH,qCAAqC,CAAC,EAAE,qCAAqC,CAAA;KAChF,KACA,OAAO,CAAC,uBAAuB,CAAC,CAAA;IACrC,MAAM,CAAC,EAAE,SAAS,CAAA;CACrB"}

package/dist/types/UseAgentTasksProps.d.ts

@@ -1,5 +1,7 @@
-import { AgentTaskProgressItemUpdated, StreamNotFound, StreamTimeout } from '@fencyai/js';
+import { AgentTaskProgressItemUpdated, StreamNotFound, StreamTimeout, ActionMap, ComponentMap } from '@fencyai/js';
 import { StreamError } from './StreamError';
+import { AgentTask } from './AgentTask';
+import { FetchPendingApprovals, FetchSubmitManualActionResultClientToken } from './PendingApproval';
 /**
  * Returns a short-lived client token used to authorize the create-agent-task request to the Fency API.
  *
@@ -35,6 +37,42 @@ export interface UseAgentTasksProps {
      * created by this hook.
      */
     fetchAgentTaskFileDownloadClientToken?: FetchAgentTaskFileDownloadClientToken;
+    /**
+     * Actions this app exposes, for ExploreProduct tasks.
+     *
+     * On the hook rather than per call because they describe the app rather than the request. Their
+     * handlers run in this browser; only the declarations travel.
+     */
+    actions?: ActionMap;
+    /**
+     * Render-only components this app exposes, for ExploreProduct tasks.
+     *
+     * On the hook rather than per call because they describe the app rather than the request.
+     * `render` stays in this browser; only the declarations travel.
+     */
+    components?: ComponentMap;
+    /**
+     * A snapshot of the app, evaluated per turn so it is never stale. Also what `refreshContext`
+     * re-reads mid-turn, after an action has changed something.
+     */
+    context?: () => Record<string, unknown>;
+    /** Required to answer approval cards. */
+    fetchSubmitManualActionResultClientToken?: FetchSubmitManualActionResultClientToken;
+    /** Rebuilds cards on mount, after a reload or on a second device. */
+    fetchPendingApprovals?: FetchPendingApprovals;
+    /**
+     * Called when a manual action result could not be delivered even after retrying. A person is
+     * standing right there, so surfacing beats swallowing.
+     */
+    onManualActionResultFailed?: (failure: {
+        actionCallId: string;
+        message: string;
+    }) => void;
+    /**
+     * Called when a follow-up ExploreProduct task is registered after the user approved at least
+     * one manual action. Use this to append a turn and show the same busy state as Send.
+     */
+    onFollowUpTaskRegistered?: (task: AgentTask) => void;
     onAgentTaskProgressItemUpdated?: (streamData: AgentTaskProgressItemUpdated) => void;
     onAgentTaskCompleted?: (streamId: string) => void;
     onStreamError?: (event: StreamError) => void;

package/dist/types/UseAgentTasksProps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UseAgentTasksProps.d.ts","sourceRoot":"","sources":["../../src/types/UseAgentTasksProps.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,4BAA4B,EAC5B,cAAc,EACd,aAAa,EAChB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,+BAA+B,GAAG,MAAM,OAAO,CAAC;IACxD,WAAW,EAAE,MAAM,CAAA;CACtB,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,qCAAqC,GAAG,CAChD,eAAe,EAAE,MAAM,KACtB,OAAO,CAAC;IACT,WAAW,EAAE,MAAM,CAAA;CACtB,CAAC,CAAA;AAEF,MAAM,WAAW,kBAAkB;IAC/B;;;;;;OAMG;IACH,+BAA+B,CAAC,EAAE,+BAA+B,CAAA;IACjE;;;OAGG;IACH,qCAAqC,CAAC,EAAE,qCAAqC,CAAA;IAC7E,8BAA8B,CAAC,EAAE,CAC7B,UAAU,EAAE,4BAA4B,KACvC,IAAI,CAAA;IACT,oBAAoB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACjD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IAC5C,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IAClD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;CACnD"}
+{"version":3,"file":"UseAgentTasksProps.d.ts","sourceRoot":"","sources":["../../src/types/UseAgentTasksProps.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,4BAA4B,EAC5B,cAAc,EACd,aAAa,EAChB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,KAAK,EACR,qBAAqB,EACrB,wCAAwC,EAC3C,MAAM,mBAAmB,CAAA;AAE1B;;;;;GAKG;AACH,MAAM,MAAM,+BAA+B,GAAG,MAAM,OAAO,CAAC;IACxD,WAAW,EAAE,MAAM,CAAA;CACtB,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,qCAAqC,GAAG,CAChD,eAAe,EAAE,MAAM,KACtB,OAAO,CAAC;IACT,WAAW,EAAE,MAAM,CAAA;CACtB,CAAC,CAAA;AAEF,MAAM,WAAW,kBAAkB;IAC/B;;;;;;OAMG;IACH,+BAA+B,CAAC,EAAE,+BAA+B,CAAA;IACjE;;;OAGG;IACH,qCAAqC,CAAC,EAAE,qCAAqC,CAAA;IAC7E;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,YAAY,CAAA;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC,yCAAyC;IACzC,wCAAwC,CAAC,EAAE,wCAAwC,CAAA;IACnF,qEAAqE;IACrE,qBAAqB,CAAC,EAAE,qBAAqB,CAAA;IAC7C;;;OAGG;IACH,0BAA0B,CAAC,EAAE,CAAC,OAAO,EAAE;QACnC,YAAY,EAAE,MAAM,CAAA;QACpB,OAAO,EAAE,MAAM,CAAA;KAClB,KAAK,IAAI,CAAA;IACV;;;OAGG;IACH,wBAAwB,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;IACpD,8BAA8B,CAAC,EAAE,CAC7B,UAAU,EAAE,4BAA4B,KACvC,IAAI,CAAA;IACT,oBAAoB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;IACjD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAA;IAC5C,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAA;IAClD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;CACnD"}

package/dist/types/UseStream.d.ts

@@ -1,7 +1,12 @@
 import { Stream } from '@fencyai/js';
 import { CreateStreamResponse } from './CreateStreamResponse';
 export interface UseStream {
-    createStream: () => Promise<CreateStreamResponse>;
+    /**
+     * @param maxAge - How old a cached stream may be and still be reused, in ms. Pass `0` to force a
+     * fresh stream. A blocking task type must do so: a task started on a 290 s-old stream loses SSE
+     * partway through, and from then on every action call times out as "browser gone".
+     */
+    createStream: (maxAge?: number) => Promise<CreateStreamResponse>;
     stream: Stream | null;
 }
 //# sourceMappingURL=UseStream.d.ts.map

package/dist/types/UseStream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UseStream.d.ts","sourceRoot":"","sources":["../../src/types/UseStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAE7D,MAAM,WAAW,SAAS;IACtB,YAAY,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAA;IACjD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB"}
+{"version":3,"file":"UseStream.d.ts","sourceRoot":"","sources":["../../src/types/UseStream.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAE7D,MAAM,WAAW,SAAS;IACtB;;;;OAIG;IACH,YAAY,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAA;IAChE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB"}

package/dist/types/index.d.ts

@@ -9,4 +9,5 @@ export * from './UseAgentTasks';
 export * from './UseAgentTasksProps';
 export * from './UseStream';
 export * from './UseStreamProps';
+export type { PendingApproval, PendingApprovalRestore, UnusedApproval, FetchPendingApprovals, FetchSubmitManualActionResultClientToken, } from './PendingApproval';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACjF,cAAc,wBAAwB,CAAA;AACtC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,sBAAsB,CAAA;AACpC,YAAY,EACR,aAAa,EACb,cAAc,EACd,4BAA4B,EAC5B,UAAU,GACb,MAAM,aAAa,CAAA;AACpB,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAC5C,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AACjF,cAAc,wBAAwB,CAAA;AACtC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,sBAAsB,CAAA;AACpC,YAAY,EACR,aAAa,EACb,cAAc,EACd,4BAA4B,EAC5B,UAAU,GACb,MAAM,aAAa,CAAA;AACpB,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,sBAAsB,CAAA;AACpC,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,YAAY,EACR,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,qBAAqB,EACrB,wCAAwC,GAC3C,MAAM,mBAAmB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fencyai/react",
-  "version": "0.1.215",
+  "version": "0.1.216",
   "description": "React components and hooks for the Fency AI platform",
   "author": "staklau <steinaageklaussen@gmail.com>",
   "homepage": "",
@@ -35,7 +35,7 @@
     "docs": "npx -y serve etc/docs"
   },
   "devDependencies": {
-    "@fencyai/js": "^0.1.215",
+    "@fencyai/js": "^0.1.216",
     "@microsoft/api-documenter": "^7.30.0",
     "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",
@@ -52,12 +52,12 @@
     "vite-plugin-lib-inject-css": "^2.1.1"
   },
   "peerDependencies": {
-    "@fencyai/js": "^0.1.215",
+    "@fencyai/js": "^0.1.216",
     "motion": "^11.15.0 || ^12.0.0",
     "react": ">=16.8.0",
     "react-markdown": "^10.1.0",
     "react-syntax-highlighter": "^16.1.0",
     "remark-gfm": "^4.0.1"
   },
-  "gitHead": "daf05c5debfed8a4ad24f8c9693f2f43da070e6c"
+  "gitHead": "b0ace4cc53103af7f7a4e16c6718d9b9d48b2c73"
 }