@asyncify-hq/node 0.2.1 → 0.3.0

package/README.md

@@ -50,6 +50,29 @@ your frontend — API keys never reach the browser:
 const { token } = await asyncify.subscriberToken('user-42');
 ```
 
+## Agent tools & approvals
+
+Give a managed agent a custom tool, then review the calls it wants to make:
+
+```ts
+// Register a tool — the secret is returned ONCE; store it to verify our
+// signed calls to your endpoint.
+const { secret } = await asyncify.agents.tools.create('acme-support', {
+  name: 'lookup_order',
+  description: 'Fetch an order by id',
+  parameters: { type: 'object', properties: { orderId: { type: 'string' } } },
+  endpointUrl: 'https://api.acme.com/tools/lookup-order',
+  approval: 'required',
+});
+
+// Work the human-in-the-loop queue
+const { approvals } = await asyncify.approvals.list({ status: 'pending' });
+await asyncify.approvals.decide(approvals[0].id, 'approve');
+
+// Route approval cards to a Slack channel
+await asyncify.settings.putApprovals({ slackConnectionId, slackChannelId: 'C0123' });
+```
+
 ## API surface
 
 | Method | Purpose |
@@ -60,6 +83,10 @@ const { token } = await asyncify.subscriberToken('user-42');
 | `subscribers.upsert({ subscriberId, email?, phone?, pushToken? })` | Create/update a subscriber |
 | `topics.upsert / addSubscribers / removeSubscribers / list / delete` | Manage segments |
 | `workflows.upsert / list` · `templates.upsert / get / list / delete` | Manage workflows & MJML templates |
+| `agents.create / list / get / update / rotateSecret / delete / linkToken` | Manage AI agents |
+| `agents.tools.create / list / update / delete / rotateSecret` | Per-agent custom tool registry |
+| `approvals.list / decide` | Human-in-the-loop tool-call queue |
+| `settings.getApprovals / putApprovals` | Which channels carry approval cards |
 | `subscriberToken(subscriberId, ttlSeconds?)` | Browser-safe inbox token |
 
 Errors throw `AsyncifyError` with `status` and the API's message.

package/dist/index.cjs

@@ -105,8 +105,69 @@ var AsyncifyClient = class {
     linkToken: (agentIdentifier, subscriberId) => this.request(
       "POST",
       `/v1/agents/${encodeURIComponent(agentIdentifier)}/subscribers/${encodeURIComponent(subscriberId)}/link-token`
+    ),
+    /**
+     * The per-agent custom tool registry (managed runtime dispatches these).
+     * Reads as `client.agents.tools.create('acme-support', {...})`.
+     */
+    tools: {
+      /**
+       * Register a tool. The secret is returned EXACTLY ONCE — store it; it is
+       * used to verify our signed calls to your endpoint.
+       */
+      create: (identifier, options) => this.request(
+        "POST",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools`,
+        options
+      ),
+      /** Every tool registered on this agent. */
+      list: (identifier) => this.request(
+        "GET",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools`
+      ),
+      /** Patch any subset; `status: 'disabled'` hides the tool from the model. */
+      update: (identifier, toolId, patch) => this.request(
+        "PATCH",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools/${encodeURIComponent(toolId)}`,
+        patch
+      ),
+      delete: (identifier, toolId) => this.request(
+        "DELETE",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools/${encodeURIComponent(toolId)}`
+      ),
+      /** New call secret, shown once; the old one stops working immediately. */
+      rotateSecret: (identifier, toolId) => this.request(
+        "POST",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools/${encodeURIComponent(toolId)}/rotate-secret`
+      )
+    }
+  };
+  approvals = {
+    /** Gated tool calls: `pending` (default) awaiting review, or `decided`. */
+    list: (filters = {}) => {
+      const qs = filters.status ? `?status=${filters.status}` : "";
+      return this.request("GET", `/v1/approvals${qs}`);
+    },
+    /** Approve or deny a pending call — atomic: 409 once already decided. */
+    decide: (id, decision, note) => this.request(
+      "POST",
+      `/v1/approvals/${encodeURIComponent(id)}/decision`,
+      { decision, note }
     )
   };
+  settings = {
+    /** Current approval-channel config + count of linked telegram approvers. */
+    getApprovals: () => this.request(
+      "GET",
+      "/v1/settings/approvals"
+    ),
+    /**
+     * Merge-patch approval channels (an absent field is kept). An explicit
+     * `null` CLEARS a field; `slackChannelId` requires an active
+     * `slackConnectionId` (and is cleared when that connection is nulled).
+     */
+    putApprovals: (patch) => this.request("PUT", "/v1/settings/approvals", patch)
+  };
   conversations = {
     /** Conversations across your agents, newest first. */
     list: (filters = {}) => {

package/dist/index.d.cts

@@ -105,6 +105,55 @@ interface ConversationSummary {
     lastMessagePreview: string | null;
     lastMessageAt: string;
 }
+/** A custom tool in an agent's registry — the managed brain dispatches these. */
+interface AgentTool {
+    id: string;
+    name: string;
+    description: string;
+    /** JSON Schema object ({ type: 'object', ... }) describing the tool's args. */
+    parameters: Record<string, unknown>;
+    endpointUrl: string;
+    /** 'required' routes every call through the human approval queue first. */
+    approval: 'auto' | 'required';
+    timeoutMs: number;
+    status: 'active' | 'disabled';
+    createdAt: string;
+}
+interface CreateAgentToolOptions {
+    /** Lowercase `^[a-z][a-z0-9_]{0,63}$`; reserved built-in names are rejected. */
+    name: string;
+    description: string;
+    /** JSON Schema; must be an object with `type: 'object'`. */
+    parameters: Record<string, unknown>;
+    /** We POST tool calls here — must be a public URL (SSRF-checked write-time). */
+    endpointUrl: string;
+    /** 'auto' (default) runs immediately; 'required' gates on human approval. */
+    approval?: 'auto' | 'required';
+    /** Per-call timeout in ms, 1000–30000 (default 10000). */
+    timeoutMs?: number;
+}
+/** A gated tool call in the approvals queue — pending, or already decided. */
+interface ToolApproval {
+    id: string;
+    agentIdentifier: string | null;
+    toolName: string;
+    args: Record<string, unknown>;
+    conversationId: string;
+    status: 'pending' | 'approved' | 'denied' | 'expired' | 'executed' | 'failed';
+    /** Tool result, truncated to 500 chars; null until the call has executed. */
+    result: string | null;
+    note: string | null;
+    requestedAt: string;
+    decidedAt: string | null;
+    decidedBy: string | null;
+    expiresAt: string | null;
+}
+/** Which connections carry approval cards; each field null when unset. */
+interface ApprovalSettings {
+    slackConnectionId: string | null;
+    slackChannelId: string | null;
+    telegramConnectionId: string | null;
+}
 declare class AsyncifyError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
@@ -201,6 +250,65 @@ declare class AsyncifyClient {
             deepLink: string;
             expiresAt: string;
         }>;
+        /**
+         * The per-agent custom tool registry (managed runtime dispatches these).
+         * Reads as `client.agents.tools.create('acme-support', {...})`.
+         */
+        tools: {
+            /**
+             * Register a tool. The secret is returned EXACTLY ONCE — store it; it is
+             * used to verify our signed calls to your endpoint.
+             */
+            create: (identifier: string, options: CreateAgentToolOptions) => Promise<{
+                tool: AgentTool;
+                secret: string;
+            }>;
+            /** Every tool registered on this agent. */
+            list: (identifier: string) => Promise<{
+                tools: AgentTool[];
+            }>;
+            /** Patch any subset; `status: 'disabled'` hides the tool from the model. */
+            update: (identifier: string, toolId: string, patch: Partial<Omit<CreateAgentToolOptions, "name">> & {
+                status?: "active" | "disabled";
+            }) => Promise<{
+                tool: AgentTool;
+            }>;
+            delete: (identifier: string, toolId: string) => Promise<{
+                deleted: boolean;
+            }>;
+            /** New call secret, shown once; the old one stops working immediately. */
+            rotateSecret: (identifier: string, toolId: string) => Promise<{
+                secret: string;
+            }>;
+        };
+    };
+    readonly approvals: {
+        /** Gated tool calls: `pending` (default) awaiting review, or `decided`. */
+        list: (filters?: {
+            status?: "pending" | "decided";
+        }) => Promise<{
+            approvals: ToolApproval[];
+        }>;
+        /** Approve or deny a pending call — atomic: 409 once already decided. */
+        decide: (id: string, decision: "approve" | "deny", note?: string) => Promise<{
+            id: string;
+            status: string;
+        }>;
+    };
+    readonly settings: {
+        /** Current approval-channel config + count of linked telegram approvers. */
+        getApprovals: () => Promise<{
+            settings: ApprovalSettings;
+            telegramApproverCount: number;
+        }>;
+        /**
+         * Merge-patch approval channels (an absent field is kept). An explicit
+         * `null` CLEARS a field; `slackChannelId` requires an active
+         * `slackConnectionId` (and is cleared when that connection is nulled).
+         */
+        putApprovals: (patch: Partial<ApprovalSettings>) => Promise<{
+            settings: ApprovalSettings;
+        }>;
     };
     readonly conversations: {
         /** Conversations across your agents, newest first. */
@@ -298,4 +406,4 @@ declare class AsyncifyClient {
     }>;
 }
 
-export { type Agent, AsyncifyClient, type AsyncifyClientOptions, AsyncifyError, type ConversationSummary, type CreateAgentOptions, type Priority, type Recipient, type TriggerOptions, type TriggerRecipient, type TriggerResult, type WorkflowStep };
+export { type Agent, type AgentTool, type ApprovalSettings, AsyncifyClient, type AsyncifyClientOptions, AsyncifyError, type ConversationSummary, type CreateAgentOptions, type CreateAgentToolOptions, type Priority, type Recipient, type ToolApproval, type TriggerOptions, type TriggerRecipient, type TriggerResult, type WorkflowStep };

package/dist/index.d.ts

@@ -105,6 +105,55 @@ interface ConversationSummary {
     lastMessagePreview: string | null;
     lastMessageAt: string;
 }
+/** A custom tool in an agent's registry — the managed brain dispatches these. */
+interface AgentTool {
+    id: string;
+    name: string;
+    description: string;
+    /** JSON Schema object ({ type: 'object', ... }) describing the tool's args. */
+    parameters: Record<string, unknown>;
+    endpointUrl: string;
+    /** 'required' routes every call through the human approval queue first. */
+    approval: 'auto' | 'required';
+    timeoutMs: number;
+    status: 'active' | 'disabled';
+    createdAt: string;
+}
+interface CreateAgentToolOptions {
+    /** Lowercase `^[a-z][a-z0-9_]{0,63}$`; reserved built-in names are rejected. */
+    name: string;
+    description: string;
+    /** JSON Schema; must be an object with `type: 'object'`. */
+    parameters: Record<string, unknown>;
+    /** We POST tool calls here — must be a public URL (SSRF-checked write-time). */
+    endpointUrl: string;
+    /** 'auto' (default) runs immediately; 'required' gates on human approval. */
+    approval?: 'auto' | 'required';
+    /** Per-call timeout in ms, 1000–30000 (default 10000). */
+    timeoutMs?: number;
+}
+/** A gated tool call in the approvals queue — pending, or already decided. */
+interface ToolApproval {
+    id: string;
+    agentIdentifier: string | null;
+    toolName: string;
+    args: Record<string, unknown>;
+    conversationId: string;
+    status: 'pending' | 'approved' | 'denied' | 'expired' | 'executed' | 'failed';
+    /** Tool result, truncated to 500 chars; null until the call has executed. */
+    result: string | null;
+    note: string | null;
+    requestedAt: string;
+    decidedAt: string | null;
+    decidedBy: string | null;
+    expiresAt: string | null;
+}
+/** Which connections carry approval cards; each field null when unset. */
+interface ApprovalSettings {
+    slackConnectionId: string | null;
+    slackChannelId: string | null;
+    telegramConnectionId: string | null;
+}
 declare class AsyncifyError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
@@ -201,6 +250,65 @@ declare class AsyncifyClient {
             deepLink: string;
             expiresAt: string;
         }>;
+        /**
+         * The per-agent custom tool registry (managed runtime dispatches these).
+         * Reads as `client.agents.tools.create('acme-support', {...})`.
+         */
+        tools: {
+            /**
+             * Register a tool. The secret is returned EXACTLY ONCE — store it; it is
+             * used to verify our signed calls to your endpoint.
+             */
+            create: (identifier: string, options: CreateAgentToolOptions) => Promise<{
+                tool: AgentTool;
+                secret: string;
+            }>;
+            /** Every tool registered on this agent. */
+            list: (identifier: string) => Promise<{
+                tools: AgentTool[];
+            }>;
+            /** Patch any subset; `status: 'disabled'` hides the tool from the model. */
+            update: (identifier: string, toolId: string, patch: Partial<Omit<CreateAgentToolOptions, "name">> & {
+                status?: "active" | "disabled";
+            }) => Promise<{
+                tool: AgentTool;
+            }>;
+            delete: (identifier: string, toolId: string) => Promise<{
+                deleted: boolean;
+            }>;
+            /** New call secret, shown once; the old one stops working immediately. */
+            rotateSecret: (identifier: string, toolId: string) => Promise<{
+                secret: string;
+            }>;
+        };
+    };
+    readonly approvals: {
+        /** Gated tool calls: `pending` (default) awaiting review, or `decided`. */
+        list: (filters?: {
+            status?: "pending" | "decided";
+        }) => Promise<{
+            approvals: ToolApproval[];
+        }>;
+        /** Approve or deny a pending call — atomic: 409 once already decided. */
+        decide: (id: string, decision: "approve" | "deny", note?: string) => Promise<{
+            id: string;
+            status: string;
+        }>;
+    };
+    readonly settings: {
+        /** Current approval-channel config + count of linked telegram approvers. */
+        getApprovals: () => Promise<{
+            settings: ApprovalSettings;
+            telegramApproverCount: number;
+        }>;
+        /**
+         * Merge-patch approval channels (an absent field is kept). An explicit
+         * `null` CLEARS a field; `slackChannelId` requires an active
+         * `slackConnectionId` (and is cleared when that connection is nulled).
+         */
+        putApprovals: (patch: Partial<ApprovalSettings>) => Promise<{
+            settings: ApprovalSettings;
+        }>;
     };
     readonly conversations: {
         /** Conversations across your agents, newest first. */
@@ -298,4 +406,4 @@ declare class AsyncifyClient {
     }>;
 }
 
-export { type Agent, AsyncifyClient, type AsyncifyClientOptions, AsyncifyError, type ConversationSummary, type CreateAgentOptions, type Priority, type Recipient, type TriggerOptions, type TriggerRecipient, type TriggerResult, type WorkflowStep };
+export { type Agent, type AgentTool, type ApprovalSettings, AsyncifyClient, type AsyncifyClientOptions, AsyncifyError, type ConversationSummary, type CreateAgentOptions, type CreateAgentToolOptions, type Priority, type Recipient, type ToolApproval, type TriggerOptions, type TriggerRecipient, type TriggerResult, type WorkflowStep };

package/dist/index.js

@@ -80,8 +80,69 @@ var AsyncifyClient = class {
     linkToken: (agentIdentifier, subscriberId) => this.request(
       "POST",
       `/v1/agents/${encodeURIComponent(agentIdentifier)}/subscribers/${encodeURIComponent(subscriberId)}/link-token`
+    ),
+    /**
+     * The per-agent custom tool registry (managed runtime dispatches these).
+     * Reads as `client.agents.tools.create('acme-support', {...})`.
+     */
+    tools: {
+      /**
+       * Register a tool. The secret is returned EXACTLY ONCE — store it; it is
+       * used to verify our signed calls to your endpoint.
+       */
+      create: (identifier, options) => this.request(
+        "POST",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools`,
+        options
+      ),
+      /** Every tool registered on this agent. */
+      list: (identifier) => this.request(
+        "GET",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools`
+      ),
+      /** Patch any subset; `status: 'disabled'` hides the tool from the model. */
+      update: (identifier, toolId, patch) => this.request(
+        "PATCH",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools/${encodeURIComponent(toolId)}`,
+        patch
+      ),
+      delete: (identifier, toolId) => this.request(
+        "DELETE",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools/${encodeURIComponent(toolId)}`
+      ),
+      /** New call secret, shown once; the old one stops working immediately. */
+      rotateSecret: (identifier, toolId) => this.request(
+        "POST",
+        `/v1/agents/${encodeURIComponent(identifier)}/tools/${encodeURIComponent(toolId)}/rotate-secret`
+      )
+    }
+  };
+  approvals = {
+    /** Gated tool calls: `pending` (default) awaiting review, or `decided`. */
+    list: (filters = {}) => {
+      const qs = filters.status ? `?status=${filters.status}` : "";
+      return this.request("GET", `/v1/approvals${qs}`);
+    },
+    /** Approve or deny a pending call — atomic: 409 once already decided. */
+    decide: (id, decision, note) => this.request(
+      "POST",
+      `/v1/approvals/${encodeURIComponent(id)}/decision`,
+      { decision, note }
     )
   };
+  settings = {
+    /** Current approval-channel config + count of linked telegram approvers. */
+    getApprovals: () => this.request(
+      "GET",
+      "/v1/settings/approvals"
+    ),
+    /**
+     * Merge-patch approval channels (an absent field is kept). An explicit
+     * `null` CLEARS a field; `slackChannelId` requires an active
+     * `slackConnectionId` (and is cleared when that connection is nulled).
+     */
+    putApprovals: (patch) => this.request("PUT", "/v1/settings/approvals", patch)
+  };
   conversations = {
     /** Conversations across your agents, newest first. */
     list: (filters = {}) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asyncify-hq/node",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Server-side SDK for Asyncify — multi-channel notification infrastructure (email, SMS, push, in-app)",
   "keywords": [
     "notifications",