@zavudev/sdk 0.55.0 → 0.57.0

package/resources/senders/agent/tools/tools.d.mts

@@ -0,0 +1,338 @@
+import { APIResource } from "../../../../core/resource.mjs";
+import * as WebhookAPI from "./webhook.mjs";
+import { Webhook, WebhookRotateSecretParams } from "./webhook.mjs";
+import { APIPromise } from "../../../../core/api-promise.mjs";
+import { Cursor, type CursorParams, PagePromise } from "../../../../core/pagination.mjs";
+import { RequestOptions } from "../../../../internal/request-options.mjs";
+export declare class Tools extends APIResource {
+    webhook: WebhookAPI.Webhook;
+    /**
+     * Create a new tool for an agent. Tools allow the agent to call external webhooks.
+     *
+     * @example
+     * ```ts
+     * const tool = await client.senders.agent.tools.create(
+     *   'senderId',
+     *   {
+     *     description: 'Get the status of a customer order',
+     *     name: 'get_order_status',
+     *     parameters: {
+     *       type: 'object',
+     *       properties: {
+     *         order_id: {
+     *           type: 'string',
+     *           description: 'The order ID to look up',
+     *         },
+     *       },
+     *       required: ['order_id'],
+     *     },
+     *     webhookUrl:
+     *       'https://api.example.com/webhooks/order-status',
+     *     webhookSecret: 'whsec_...',
+     *   },
+     * );
+     * ```
+     */
+    create(senderID: string, body: ToolCreateParams, options?: RequestOptions): APIPromise<ToolCreateResponse>;
+    /**
+     * Get a specific tool.
+     *
+     * @example
+     * ```ts
+     * const tool = await client.senders.agent.tools.retrieve(
+     *   'toolId',
+     *   { senderId: 'senderId' },
+     * );
+     * ```
+     */
+    retrieve(toolID: string, params: ToolRetrieveParams, options?: RequestOptions): APIPromise<ToolRetrieveResponse>;
+    /**
+     * Update a tool.
+     *
+     * @example
+     * ```ts
+     * const tool = await client.senders.agent.tools.update(
+     *   'toolId',
+     *   { senderId: 'senderId' },
+     * );
+     * ```
+     */
+    update(toolID: string, params: ToolUpdateParams, options?: RequestOptions): APIPromise<ToolUpdateResponse>;
+    /**
+     * List tools for an agent.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const agentTool of client.senders.agent.tools.list(
+     *   'senderId',
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
+    list(senderID: string, query?: ToolListParams | null | undefined, options?: RequestOptions): PagePromise<AgentToolsCursor, AgentTool>;
+    /**
+     * Delete a tool.
+     *
+     * @example
+     * ```ts
+     * await client.senders.agent.tools.delete('toolId', {
+     *   senderId: 'senderId',
+     * });
+     * ```
+     */
+    delete(toolID: string, params: ToolDeleteParams, options?: RequestOptions): APIPromise<void>;
+    /**
+     * Recent runs of this tool triggered from the test endpoint, newest first. Covers
+     * manual tests only: a tool called by an agent during a real conversation is not
+     * recorded here.
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.senders.agent.tools.listTestRuns('toolId', {
+     *     senderId: 'senderId',
+     *   });
+     * ```
+     */
+    listTestRuns(toolID: string, params: ToolListTestRunsParams, options?: RequestOptions): APIPromise<ToolListTestRunsResponse>;
+    /**
+     * Run a tool with the parameters you supply and return what it answered.
+     *
+     * The call is synchronous: the response carries the tool's status, body, and
+     * duration, so a green result is evidence the tool ran rather than evidence it was
+     * accepted. Each run is also recorded and readable afterwards via
+     * `GET /v1/senders/{senderId}/agent/tools/{toolId}/test-runs`.
+     *
+     * A tool that answers with an error is reported as a run with `success: false` —
+     * the endpoint itself still returns 200. This fires the tool's real webhook, so a
+     * test has whatever side effects the tool has.
+     *
+     * @example
+     * ```ts
+     * const response = await client.senders.agent.tools.test(
+     *   'toolId',
+     *   {
+     *     senderId: 'senderId',
+     *     testParams: { order_id: 'ORD-12345' },
+     *   },
+     * );
+     * ```
+     */
+    test(toolID: string, params: ToolTestParams, options?: RequestOptions): APIPromise<ToolTestResponse>;
+}
+export type AgentToolsCursor = Cursor<AgentTool>;
+export interface AgentTool {
+    id: string;
+    agentId: string;
+    createdAt: string;
+    /**
+     * Description for the LLM to understand when to use this tool.
+     */
+    description: string;
+    enabled: boolean;
+    name: string;
+    parameters: ToolParameters;
+    updatedAt: string;
+    /**
+     * HTTPS URL to call when the tool is executed.
+     */
+    webhookUrl: string;
+    /**
+     * Signing secret for this tool's webhook. **Returned only when the tool is
+     * created**, never on a later read.
+     *
+     * Zavu generates one if you do not supply it, and signs every call to this tool
+     * with it: `X-Zavu-Signature: <hex>`, the HMAC-SHA256 of the request body. Verify
+     * it before trusting the call. Lost it? Rotate with
+     * `POST /v1/senders/{senderId}/agent/tools/{toolId}/webhook/secret`.
+     */
+    webhookSecret?: string;
+}
+export interface ToolParameters {
+    properties: {
+        [key: string]: ToolParameters.Properties;
+    };
+    required: Array<string>;
+    type: 'object';
+}
+export declare namespace ToolParameters {
+    interface Properties {
+        description?: string;
+        type?: string;
+    }
+}
+export interface ToolCreateResponse {
+    tool: AgentTool;
+}
+export interface ToolRetrieveResponse {
+    tool: AgentTool;
+}
+export interface ToolUpdateResponse {
+    tool: AgentTool;
+}
+export interface ToolListTestRunsResponse {
+    items: Array<ToolListTestRunsResponse.Item>;
+}
+export declare namespace ToolListTestRunsResponse {
+    /**
+     * One run of a tool triggered from the test endpoint. Recorded so a test is
+     * verifiable after the fact rather than only visible in the response.
+     */
+    interface Item {
+        id: string;
+        createdAt: string;
+        durationMs: number;
+        /**
+         * Whether the tool returned without error. A tool that answered with a non-2xx
+         * status is a failed run, not an error of this endpoint.
+         */
+        success: boolean;
+        toolId: string;
+        /**
+         * Why the run failed, when it did.
+         */
+        error?: string | null;
+        /**
+         * The parameters the tool was called with.
+         */
+        params?: {
+            [key: string]: unknown;
+        };
+        /**
+         * The tool's response body, truncated.
+         */
+        response?: string | null;
+        /**
+         * HTTP status the tool's webhook returned. Absent for tools that do not go over
+         * HTTP.
+         */
+        statusCode?: number | null;
+    }
+}
+export interface ToolTestResponse {
+    /**
+     * One run of a tool triggered from the test endpoint. Recorded so a test is
+     * verifiable after the fact rather than only visible in the response.
+     */
+    run: ToolTestResponse.Run;
+}
+export declare namespace ToolTestResponse {
+    /**
+     * One run of a tool triggered from the test endpoint. Recorded so a test is
+     * verifiable after the fact rather than only visible in the response.
+     */
+    interface Run {
+        id: string;
+        createdAt: string;
+        durationMs: number;
+        /**
+         * Whether the tool returned without error. A tool that answered with a non-2xx
+         * status is a failed run, not an error of this endpoint.
+         */
+        success: boolean;
+        toolId: string;
+        /**
+         * Why the run failed, when it did.
+         */
+        error?: string | null;
+        /**
+         * The parameters the tool was called with.
+         */
+        params?: {
+            [key: string]: unknown;
+        };
+        /**
+         * The tool's response body, truncated.
+         */
+        response?: string | null;
+        /**
+         * HTTP status the tool's webhook returned. Absent for tools that do not go over
+         * HTTP.
+         */
+        statusCode?: number | null;
+    }
+}
+export interface ToolCreateParams {
+    description: string;
+    name: string;
+    parameters: ToolParameters;
+    /**
+     * Must be HTTPS.
+     */
+    webhookUrl: string;
+    enabled?: boolean;
+    /**
+     * Signing secret for the webhook. Optional: Zavu generates one when omitted and
+     * returns it on this response only. Supply your own if you already have a secret
+     * you want reused.
+     */
+    webhookSecret?: string;
+}
+export interface ToolRetrieveParams {
+    senderId: string;
+}
+export interface ToolUpdateParams {
+    /**
+     * Path param
+     */
+    senderId: string;
+    /**
+     * Body param
+     */
+    description?: string;
+    /**
+     * Body param
+     */
+    enabled?: boolean;
+    /**
+     * Body param
+     */
+    name?: string;
+    /**
+     * Body param
+     */
+    parameters?: ToolParameters;
+    /**
+     * Body param
+     */
+    webhookSecret?: string | null;
+    /**
+     * Body param
+     */
+    webhookUrl?: string;
+}
+export interface ToolListParams extends CursorParams {
+    enabled?: boolean;
+}
+export interface ToolDeleteParams {
+    senderId: string;
+}
+export interface ToolListTestRunsParams {
+    /**
+     * Path param
+     */
+    senderId: string;
+    /**
+     * Query param
+     */
+    limit?: number;
+}
+export interface ToolTestParams {
+    /**
+     * Path param
+     */
+    senderId: string;
+    /**
+     * Body param: Parameters to pass to the tool for testing.
+     */
+    testParams: {
+        [key: string]: unknown;
+    };
+}
+export declare namespace Tools {
+    export { type AgentTool as AgentTool, type ToolParameters as ToolParameters, type ToolCreateResponse as ToolCreateResponse, type ToolRetrieveResponse as ToolRetrieveResponse, type ToolUpdateResponse as ToolUpdateResponse, type ToolListTestRunsResponse as ToolListTestRunsResponse, type ToolTestResponse as ToolTestResponse, type AgentToolsCursor as AgentToolsCursor, type ToolCreateParams as ToolCreateParams, type ToolRetrieveParams as ToolRetrieveParams, type ToolUpdateParams as ToolUpdateParams, type ToolListParams as ToolListParams, type ToolDeleteParams as ToolDeleteParams, type ToolListTestRunsParams as ToolListTestRunsParams, type ToolTestParams as ToolTestParams, };
+    export { Webhook as Webhook, type WebhookRotateSecretParams as WebhookRotateSecretParams };
+}
+//# sourceMappingURL=tools.d.mts.map

package/resources/senders/agent/tools/tools.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.mts","sourceRoot":"","sources":["../../../../src/resources/senders/agent/tools/tools.ts"],"names":[],"mappings":"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"}

package/resources/senders/agent/tools/tools.d.ts

@@ -0,0 +1,338 @@
+import { APIResource } from "../../../../core/resource.js";
+import * as WebhookAPI from "./webhook.js";
+import { Webhook, WebhookRotateSecretParams } from "./webhook.js";
+import { APIPromise } from "../../../../core/api-promise.js";
+import { Cursor, type CursorParams, PagePromise } from "../../../../core/pagination.js";
+import { RequestOptions } from "../../../../internal/request-options.js";
+export declare class Tools extends APIResource {
+    webhook: WebhookAPI.Webhook;
+    /**
+     * Create a new tool for an agent. Tools allow the agent to call external webhooks.
+     *
+     * @example
+     * ```ts
+     * const tool = await client.senders.agent.tools.create(
+     *   'senderId',
+     *   {
+     *     description: 'Get the status of a customer order',
+     *     name: 'get_order_status',
+     *     parameters: {
+     *       type: 'object',
+     *       properties: {
+     *         order_id: {
+     *           type: 'string',
+     *           description: 'The order ID to look up',
+     *         },
+     *       },
+     *       required: ['order_id'],
+     *     },
+     *     webhookUrl:
+     *       'https://api.example.com/webhooks/order-status',
+     *     webhookSecret: 'whsec_...',
+     *   },
+     * );
+     * ```
+     */
+    create(senderID: string, body: ToolCreateParams, options?: RequestOptions): APIPromise<ToolCreateResponse>;
+    /**
+     * Get a specific tool.
+     *
+     * @example
+     * ```ts
+     * const tool = await client.senders.agent.tools.retrieve(
+     *   'toolId',
+     *   { senderId: 'senderId' },
+     * );
+     * ```
+     */
+    retrieve(toolID: string, params: ToolRetrieveParams, options?: RequestOptions): APIPromise<ToolRetrieveResponse>;
+    /**
+     * Update a tool.
+     *
+     * @example
+     * ```ts
+     * const tool = await client.senders.agent.tools.update(
+     *   'toolId',
+     *   { senderId: 'senderId' },
+     * );
+     * ```
+     */
+    update(toolID: string, params: ToolUpdateParams, options?: RequestOptions): APIPromise<ToolUpdateResponse>;
+    /**
+     * List tools for an agent.
+     *
+     * @example
+     * ```ts
+     * // Automatically fetches more pages as needed.
+     * for await (const agentTool of client.senders.agent.tools.list(
+     *   'senderId',
+     * )) {
+     *   // ...
+     * }
+     * ```
+     */
+    list(senderID: string, query?: ToolListParams | null | undefined, options?: RequestOptions): PagePromise<AgentToolsCursor, AgentTool>;
+    /**
+     * Delete a tool.
+     *
+     * @example
+     * ```ts
+     * await client.senders.agent.tools.delete('toolId', {
+     *   senderId: 'senderId',
+     * });
+     * ```
+     */
+    delete(toolID: string, params: ToolDeleteParams, options?: RequestOptions): APIPromise<void>;
+    /**
+     * Recent runs of this tool triggered from the test endpoint, newest first. Covers
+     * manual tests only: a tool called by an agent during a real conversation is not
+     * recorded here.
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.senders.agent.tools.listTestRuns('toolId', {
+     *     senderId: 'senderId',
+     *   });
+     * ```
+     */
+    listTestRuns(toolID: string, params: ToolListTestRunsParams, options?: RequestOptions): APIPromise<ToolListTestRunsResponse>;
+    /**
+     * Run a tool with the parameters you supply and return what it answered.
+     *
+     * The call is synchronous: the response carries the tool's status, body, and
+     * duration, so a green result is evidence the tool ran rather than evidence it was
+     * accepted. Each run is also recorded and readable afterwards via
+     * `GET /v1/senders/{senderId}/agent/tools/{toolId}/test-runs`.
+     *
+     * A tool that answers with an error is reported as a run with `success: false` —
+     * the endpoint itself still returns 200. This fires the tool's real webhook, so a
+     * test has whatever side effects the tool has.
+     *
+     * @example
+     * ```ts
+     * const response = await client.senders.agent.tools.test(
+     *   'toolId',
+     *   {
+     *     senderId: 'senderId',
+     *     testParams: { order_id: 'ORD-12345' },
+     *   },
+     * );
+     * ```
+     */
+    test(toolID: string, params: ToolTestParams, options?: RequestOptions): APIPromise<ToolTestResponse>;
+}
+export type AgentToolsCursor = Cursor<AgentTool>;
+export interface AgentTool {
+    id: string;
+    agentId: string;
+    createdAt: string;
+    /**
+     * Description for the LLM to understand when to use this tool.
+     */
+    description: string;
+    enabled: boolean;
+    name: string;
+    parameters: ToolParameters;
+    updatedAt: string;
+    /**
+     * HTTPS URL to call when the tool is executed.
+     */
+    webhookUrl: string;
+    /**
+     * Signing secret for this tool's webhook. **Returned only when the tool is
+     * created**, never on a later read.
+     *
+     * Zavu generates one if you do not supply it, and signs every call to this tool
+     * with it: `X-Zavu-Signature: <hex>`, the HMAC-SHA256 of the request body. Verify
+     * it before trusting the call. Lost it? Rotate with
+     * `POST /v1/senders/{senderId}/agent/tools/{toolId}/webhook/secret`.
+     */
+    webhookSecret?: string;
+}
+export interface ToolParameters {
+    properties: {
+        [key: string]: ToolParameters.Properties;
+    };
+    required: Array<string>;
+    type: 'object';
+}
+export declare namespace ToolParameters {
+    interface Properties {
+        description?: string;
+        type?: string;
+    }
+}
+export interface ToolCreateResponse {
+    tool: AgentTool;
+}
+export interface ToolRetrieveResponse {
+    tool: AgentTool;
+}
+export interface ToolUpdateResponse {
+    tool: AgentTool;
+}
+export interface ToolListTestRunsResponse {
+    items: Array<ToolListTestRunsResponse.Item>;
+}
+export declare namespace ToolListTestRunsResponse {
+    /**
+     * One run of a tool triggered from the test endpoint. Recorded so a test is
+     * verifiable after the fact rather than only visible in the response.
+     */
+    interface Item {
+        id: string;
+        createdAt: string;
+        durationMs: number;
+        /**
+         * Whether the tool returned without error. A tool that answered with a non-2xx
+         * status is a failed run, not an error of this endpoint.
+         */
+        success: boolean;
+        toolId: string;
+        /**
+         * Why the run failed, when it did.
+         */
+        error?: string | null;
+        /**
+         * The parameters the tool was called with.
+         */
+        params?: {
+            [key: string]: unknown;
+        };
+        /**
+         * The tool's response body, truncated.
+         */
+        response?: string | null;
+        /**
+         * HTTP status the tool's webhook returned. Absent for tools that do not go over
+         * HTTP.
+         */
+        statusCode?: number | null;
+    }
+}
+export interface ToolTestResponse {
+    /**
+     * One run of a tool triggered from the test endpoint. Recorded so a test is
+     * verifiable after the fact rather than only visible in the response.
+     */
+    run: ToolTestResponse.Run;
+}
+export declare namespace ToolTestResponse {
+    /**
+     * One run of a tool triggered from the test endpoint. Recorded so a test is
+     * verifiable after the fact rather than only visible in the response.
+     */
+    interface Run {
+        id: string;
+        createdAt: string;
+        durationMs: number;
+        /**
+         * Whether the tool returned without error. A tool that answered with a non-2xx
+         * status is a failed run, not an error of this endpoint.
+         */
+        success: boolean;
+        toolId: string;
+        /**
+         * Why the run failed, when it did.
+         */
+        error?: string | null;
+        /**
+         * The parameters the tool was called with.
+         */
+        params?: {
+            [key: string]: unknown;
+        };
+        /**
+         * The tool's response body, truncated.
+         */
+        response?: string | null;
+        /**
+         * HTTP status the tool's webhook returned. Absent for tools that do not go over
+         * HTTP.
+         */
+        statusCode?: number | null;
+    }
+}
+export interface ToolCreateParams {
+    description: string;
+    name: string;
+    parameters: ToolParameters;
+    /**
+     * Must be HTTPS.
+     */
+    webhookUrl: string;
+    enabled?: boolean;
+    /**
+     * Signing secret for the webhook. Optional: Zavu generates one when omitted and
+     * returns it on this response only. Supply your own if you already have a secret
+     * you want reused.
+     */
+    webhookSecret?: string;
+}
+export interface ToolRetrieveParams {
+    senderId: string;
+}
+export interface ToolUpdateParams {
+    /**
+     * Path param
+     */
+    senderId: string;
+    /**
+     * Body param
+     */
+    description?: string;
+    /**
+     * Body param
+     */
+    enabled?: boolean;
+    /**
+     * Body param
+     */
+    name?: string;
+    /**
+     * Body param
+     */
+    parameters?: ToolParameters;
+    /**
+     * Body param
+     */
+    webhookSecret?: string | null;
+    /**
+     * Body param
+     */
+    webhookUrl?: string;
+}
+export interface ToolListParams extends CursorParams {
+    enabled?: boolean;
+}
+export interface ToolDeleteParams {
+    senderId: string;
+}
+export interface ToolListTestRunsParams {
+    /**
+     * Path param
+     */
+    senderId: string;
+    /**
+     * Query param
+     */
+    limit?: number;
+}
+export interface ToolTestParams {
+    /**
+     * Path param
+     */
+    senderId: string;
+    /**
+     * Body param: Parameters to pass to the tool for testing.
+     */
+    testParams: {
+        [key: string]: unknown;
+    };
+}
+export declare namespace Tools {
+    export { type AgentTool as AgentTool, type ToolParameters as ToolParameters, type ToolCreateResponse as ToolCreateResponse, type ToolRetrieveResponse as ToolRetrieveResponse, type ToolUpdateResponse as ToolUpdateResponse, type ToolListTestRunsResponse as ToolListTestRunsResponse, type ToolTestResponse as ToolTestResponse, type AgentToolsCursor as AgentToolsCursor, type ToolCreateParams as ToolCreateParams, type ToolRetrieveParams as ToolRetrieveParams, type ToolUpdateParams as ToolUpdateParams, type ToolListParams as ToolListParams, type ToolDeleteParams as ToolDeleteParams, type ToolListTestRunsParams as ToolListTestRunsParams, type ToolTestParams as ToolTestParams, };
+    export { Webhook as Webhook, type WebhookRotateSecretParams as WebhookRotateSecretParams };
+}
+//# sourceMappingURL=tools.d.ts.map

package/resources/senders/agent/tools/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../../src/resources/senders/agent/tools/tools.ts"],"names":[],"mappings":"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"}