@zavudev/sdk 0.54.0 → 0.56.0

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

@@ -1,366 +1,3 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../../core/resource';
-import { APIPromise } from '../../../core/api-promise';
-import { Cursor, type CursorParams, PagePromise } from '../../../core/pagination';
-import { buildHeaders } from '../../../internal/headers';
-import { RequestOptions } from '../../../internal/request-options';
-import { path } from '../../../internal/utils/path';
-
-export class Tools extends APIResource {
-  /**
-   * 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> {
-    return this._client.post(path`/v1/senders/${senderID}/agent/tools`, { body, ...options });
-  }
-
-  /**
-   * 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> {
-    const { senderId } = params;
-    return this._client.get(path`/v1/senders/${senderId}/agent/tools/${toolID}`, options);
-  }
-
-  /**
-   * 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> {
-    const { senderId, ...body } = params;
-    return this._client.patch(path`/v1/senders/${senderId}/agent/tools/${toolID}`, { body, ...options });
-  }
-
-  /**
-   * 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> {
-    return this._client.getAPIList(path`/v1/senders/${senderID}/agent/tools`, Cursor<AgentTool>, {
-      query,
-      ...options,
-    });
-  }
-
-  /**
-   * Delete a tool.
-   *
-   * @example
-   * ```ts
-   * await client.senders.agent.tools.delete('toolId', {
-   *   senderId: 'senderId',
-   * });
-   * ```
-   */
-  delete(toolID: string, params: ToolDeleteParams, options?: RequestOptions): APIPromise<void> {
-    const { senderId } = params;
-    return this._client.delete(path`/v1/senders/${senderId}/agent/tools/${toolID}`, {
-      ...options,
-      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
-    });
-  }
-
-  /**
-   * 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> {
-    const { senderId, ...body } = params;
-    return this._client.post(path`/v1/senders/${senderId}/agent/tools/${toolID}/test`, { body, ...options });
-  }
-}
-
-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 namespace ToolParameters {
-  export interface Properties {
-    description?: string;
-
-    type?: string;
-  }
-}
-
-export interface ToolCreateResponse {
-  tool: AgentTool;
-}
-
-export interface ToolRetrieveResponse {
-  tool: AgentTool;
-}
-
-export interface ToolUpdateResponse {
-  tool: AgentTool;
-}
-
-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 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.
-   */
-  export 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 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 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 ToolTestParams as ToolTestParams,
-  };
-}
+export * from './tools/index';

package/src/resources/senders/index.ts

@@ -11,6 +11,7 @@ export {
   type AgentCreateParams,
   type AgentUpdateParams,
   type AgentExecutionsCursor,
+  type AgentsCursor,
 } from './agent/index';
 export {
   Senders,
@@ -30,6 +31,7 @@ export {
   type SenderUploadProfilePictureParams,
   type SendersCursor,
 } from './senders';
+export { Telegram, type TelegramConnectResponse, type TelegramConnectParams } from './telegram';
 export {
   WhatsappSync,
   type WhatsAppSyncContacts,

package/src/resources/senders/senders.ts

@@ -1,6 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIResource } from '../../core/resource';
+import * as TelegramAPI from './telegram';
+import { Telegram, TelegramConnectParams, TelegramConnectResponse } from './telegram';
 import * as WhatsappSyncAPI from './whatsapp-sync';
 import {
   WhatsAppSyncContacts,
@@ -32,6 +34,7 @@ import { path } from '../../internal/utils/path';
 export class Senders extends APIResource {
   agent: AgentAPI.AgentResource = new AgentAPI.AgentResource(this._client);
   whatsappSync: WhatsappSyncAPI.WhatsappSync = new WhatsappSyncAPI.WhatsappSync(this._client);
+  telegram: TelegramAPI.Telegram = new TelegramAPI.Telegram(this._client);
 
   /**
    * Create sender
@@ -358,7 +361,12 @@ export interface SenderWebhook {
  *   receive time in Unix milliseconds (the moment the channel received the message
  *   from the contact — WhatsApp, Telegram, Instagram, Messenger; `null` for SMS
  *   and email). Compare it against the top-level `timestamp` (when Zavu dispatched
- *   the webhook) to detect and ignore delayed deliveries.
+ *   the webhook) to detect and ignore delayed deliveries. When the conversation
+ *   was opened from a Click-to-WhatsApp ad or post, `data.referral` carries the ad
+ *   attribution — including `ctwaClid`, the identifier Meta's Conversions API
+ *   needs to credit a conversion back to that ad. WhatsApp only, and only on the
+ *   first message of the thread: it is absent from every later message, so persist
+ *   it when it arrives.
  * - `message.unsupported`: Received a message type that is not supported
  *
  * **Broadcast events:**
@@ -736,6 +744,7 @@ export interface SenderUploadProfilePictureParams {
 
 Senders.AgentResource = AgentResource;
 Senders.WhatsappSync = WhatsappSync;
+Senders.Telegram = Telegram;
 
 export declare namespace Senders {
   export {
@@ -777,4 +786,10 @@ export declare namespace Senders {
     type WhatsappSyncStartContactsSyncResponse as WhatsappSyncStartContactsSyncResponse,
     type WhatsappSyncStartHistorySyncResponse as WhatsappSyncStartHistorySyncResponse,
   };
+
+  export {
+    Telegram as Telegram,
+    type TelegramConnectResponse as TelegramConnectResponse,
+    type TelegramConnectParams as TelegramConnectParams,
+  };
 }

package/src/resources/senders/telegram.ts

@@ -0,0 +1,73 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Telegram extends APIResource {
+  /**
+   * Connect a Telegram bot to a sender. Provide the bot token from @BotFather; Zavu
+   * validates it, registers the webhook, and routes the sender's Telegram messages
+   * through it.
+   *
+   * @example
+   * ```ts
+   * const response = await client.senders.telegram.connect(
+   *   'senderId',
+   *   { botToken: 'botToken' },
+   * );
+   * ```
+   */
+  connect(
+    senderID: string,
+    body: TelegramConnectParams,
+    options?: RequestOptions,
+  ): APIPromise<TelegramConnectResponse> {
+    return this._client.post(path`/v1/senders/${senderID}/telegram`, { body, ...options });
+  }
+
+  /**
+   * Disconnect Telegram from a sender and remove the webhook.
+   *
+   * @example
+   * ```ts
+   * await client.senders.telegram.disconnect('senderId');
+   * ```
+   */
+  disconnect(senderID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/senders/${senderID}/telegram`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface TelegramConnectResponse {
+  telegram: TelegramConnectResponse.Telegram;
+}
+
+export namespace TelegramConnectResponse {
+  export interface Telegram {
+    connected: boolean;
+
+    botId?: string;
+
+    botUsername?: string;
+  }
+}
+
+export interface TelegramConnectParams {
+  /**
+   * Bot token from @BotFather.
+   */
+  botToken: string;
+}
+
+export declare namespace Telegram {
+  export {
+    type TelegramConnectResponse as TelegramConnectResponse,
+    type TelegramConnectParams as TelegramConnectParams,
+  };
+}

package/src/resources/templates.ts

@@ -90,6 +90,41 @@ export class Templates extends APIResource {
   submit(templateID: string, body: TemplateSubmitParams, options?: RequestOptions): APIPromise<Template> {
     return this._client.post(path`/v1/templates/${templateID}/submit`, { body, ...options });
   }
+
+  /**
+   * Reconcile this project's templates against WhatsApp. Two things happen per
+   * connected WhatsApp Business Account: templates that exist on Meta but not in
+   * Zavu are imported (or linked to an existing template with the same name), and
+   * the approval status of the templates Zavu already knows about is refreshed from
+   * Meta.
+   *
+   * This is what to call when a template was created outside Zavu — in Meta Business
+   * Manager, or by another tool — or when a `template.status_changed` webhook was
+   * missed and a template is stuck in `pending`. Status changes normally arrive by
+   * webhook; this endpoint is the recovery path and the only path for a template
+   * Zavu never created.
+   *
+   * Templates that Meta reports as rejected or disabled are not imported; they are
+   * counted in `skipped`. Existing local templates are matched first by Meta
+   * template ID, then by name.
+   *
+   * By default every sender in the project with a WhatsApp Business Account is
+   * synced. Pass `senderId` to sync only that sender's account. The call is
+   * synchronous — it waits for Meta and returns what changed — so it can take a few
+   * seconds per account. A failure on one account does not fail the request: it is
+   * reported in `errors` and the remaining accounts are still synced.
+   *
+   * @example
+   * ```ts
+   * const response = await client.templates.sync();
+   * ```
+   */
+  sync(
+    body: TemplateSyncParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<TemplateSyncResponse> {
+    return this._client.post('/v1/templates/sync', { body, ...options });
+  }
 }
 
 export type TemplatesCursor = Cursor<Template>;
@@ -241,6 +276,41 @@ export namespace Template {
  */
 export type WhatsappCategory = 'UTILITY' | 'MARKETING' | 'AUTHENTICATION';
 
+export interface TemplateSyncResponse {
+  /**
+   * WhatsApp Business Accounts reconciled in this call.
+   */
+  accountsSynced: number;
+
+  /**
+   * Problems hit while syncing. Non-empty with a 200 means part of the sync did not
+   * complete — the rest still did.
+   */
+  errors: Array<string>;
+
+  /**
+   * Templates that existed on Meta and were created in Zavu by this call.
+   */
+  imported: number;
+
+  /**
+   * Existing Zavu templates that were matched to a Meta template by name and bound
+   * to its Meta ID.
+   */
+  linked: number;
+
+  /**
+   * Meta templates left alone: already linked to a Zavu template, or
+   * rejected/disabled on Meta.
+   */
+  skipped: number;
+
+  /**
+   * Templates whose approval status changed to match Meta.
+   */
+  updated: number;
+}
+
 export interface TemplateCreateParams {
   /**
    * Default template body. Used when no channel-specific body is set.
@@ -367,13 +437,23 @@ export interface TemplateSubmitParams {
   category?: WhatsappCategory;
 }
 
+export interface TemplateSyncParams {
+  /**
+   * Sync only the WhatsApp Business Account attached to this sender. If omitted,
+   * every WhatsApp sender in the project is synced.
+   */
+  senderId?: string;
+}
+
 export declare namespace Templates {
   export {
     type Template as Template,
     type WhatsappCategory as WhatsappCategory,
+    type TemplateSyncResponse as TemplateSyncResponse,
     type TemplatesCursor as TemplatesCursor,
     type TemplateCreateParams as TemplateCreateParams,
     type TemplateListParams as TemplateListParams,
     type TemplateSubmitParams as TemplateSubmitParams,
+    type TemplateSyncParams as TemplateSyncParams,
   };
 }

package/src/resources/urls.ts

@@ -7,6 +7,26 @@ import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 export class URLs extends APIResource {
+  /**
+   * Request manual review of a rejected URL. Only URLs in 'rejected' status can be
+   * escalated; the status then moves to 'escalated'.
+   *
+   * @example
+   * ```ts
+   * const response = await client.urls.escalate('urlId', {
+   *   reason:
+   *     'This is our official landing page and was rejected in error.',
+   * });
+   * ```
+   */
+  escalate(
+    urlID: string,
+    body: URLEscalateParams,
+    options?: RequestOptions,
+  ): APIPromise<URLEscalateResponse> {
+    return this._client.post(path`/v1/urls/${urlID}/escalate`, { body, ...options });
+  }
+
   /**
    * List URLs that have been verified for this project.
    *
@@ -91,6 +111,12 @@ export interface VerifiedURL {
   updatedAt?: string;
 }
 
+export interface URLEscalateResponse {
+  message: string;
+
+  url: VerifiedURL;
+}
+
 export interface URLRetrieveDetailsResponse {
   url: VerifiedURL;
 }
@@ -99,6 +125,13 @@ export interface URLSubmitForVerificationResponse {
   url: VerifiedURL;
 }
 
+export interface URLEscalateParams {
+  /**
+   * Why the URL should be reviewed manually.
+   */
+  reason: string;
+}
+
 export interface URLListVerifiedParams extends CursorParams {
   /**
    * Filter by verification status.
@@ -116,9 +149,11 @@ export interface URLSubmitForVerificationParams {
 export declare namespace URLs {
   export {
     type VerifiedURL as VerifiedURL,
+    type URLEscalateResponse as URLEscalateResponse,
     type URLRetrieveDetailsResponse as URLRetrieveDetailsResponse,
     type URLSubmitForVerificationResponse as URLSubmitForVerificationResponse,
     type VerifiedURLsCursor as VerifiedURLsCursor,
+    type URLEscalateParams as URLEscalateParams,
     type URLListVerifiedParams as URLListVerifiedParams,
     type URLSubmitForVerificationParams as URLSubmitForVerificationParams,
   };

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.54.0'; // x-release-please-version
+export const VERSION = '0.56.0'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.54.0";
+export declare const VERSION = "0.56.0";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.54.0";
+export declare const VERSION = "0.56.0";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.54.0'; // x-release-please-version
+exports.VERSION = '0.56.0'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.54.0'; // x-release-please-version
+export const VERSION = '0.56.0'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map