@zavudev/sdk 0.55.0 → 0.57.0

package/src/resources/index.ts

@@ -10,6 +10,24 @@ export {
   type AddressListParams,
   type AddressesCursor,
 } from './addresses';
+export {
+  AgentTemplates,
+  type AgentTemplateRetrieveResponse,
+  type AgentTemplateListResponse,
+} from './agent-templates';
+export {
+  Agents,
+  type AgentCreateResponse,
+  type AgentRetrieveResponse,
+  type AgentUpdateResponse,
+  type AgentListVoicesResponse,
+  type AgentTestResponse,
+  type AgentCreateParams,
+  type AgentUpdateParams,
+  type AgentListParams,
+  type AgentListVoicesParams,
+  type AgentTestParams,
+} from './agents/agents';
 export { Balance, type BalanceRetrieveResponse } from './balance';
 export {
   Broadcasts,
@@ -37,6 +55,16 @@ export {
   type BroadcastContactsCursor,
   type BroadcastsCursor,
 } from './broadcasts/broadcasts';
+export {
+  Calls,
+  type CallCreateResponse,
+  type CallRetrieveResponse,
+  type CallListResponse,
+  type CallHangupResponse,
+  type CallCreateParams,
+  type CallListParams,
+  type CallListResponsesCursor,
+} from './calls';
 export {
   Contacts,
   type Contact,
@@ -47,6 +75,23 @@ export {
   type ContactMergeParams,
   type ContactsCursor,
 } from './contacts/contacts';
+export {
+  Conversations,
+  type ConversationRetrieveResponse,
+  type ConversationListResponse,
+  type ConversationMarkAsReadResponse,
+  type ConversationListParams,
+  type ConversationListMessagesParams,
+  type ConversationListResponsesCursor,
+} from './conversations';
+export {
+  EmailDomains,
+  type EmailDomainCreateResponse,
+  type EmailDomainRetrieveResponse,
+  type EmailDomainListResponse,
+  type EmailDomainVerifyResponse,
+  type EmailDomainCreateParams,
+} from './email-domains';
 export {
   Functions,
   type FunctionCreateResponse,
@@ -55,16 +100,23 @@ export {
   type FunctionDeleteResponse,
   type FunctionDeployResponse,
   type FunctionGetDeploymentResponse,
+  type FunctionListDeploymentsResponse,
+  type FunctionListEventTypesResponse,
+  type FunctionRollbackDeploymentResponse,
   type FunctionTailLogsResponse,
   type FunctionCreateParams,
   type FunctionUpdateParams,
   type FunctionDeployParams,
+  type FunctionListDeploymentsParams,
+  type FunctionRollbackDeploymentParams,
   type FunctionTailLogsParams,
 } from './functions/functions';
 export {
   Introspect,
   type LineType,
+  type IntrospectValidateEmailResponse,
   type IntrospectValidatePhoneResponse,
+  type IntrospectValidateEmailParams,
   type IntrospectValidatePhoneParams,
 } from './introspect';
 export {
@@ -86,6 +138,7 @@ export {
   type MessageResponse,
   type MessageStatus,
   type MessageType,
+  type MessageListAttachmentsResponse,
   type MessageShowTypingResponse,
   type MessageListParams,
   type MessageReactParams,
@@ -164,16 +217,20 @@ export {
   Templates,
   type Template,
   type WhatsappCategory,
+  type TemplateSyncResponse,
   type TemplateCreateParams,
   type TemplateListParams,
   type TemplateSubmitParams,
+  type TemplateSyncParams,
   type TemplatesCursor,
 } from './templates';
 export {
   URLs,
   type VerifiedURL,
+  type URLEscalateResponse,
   type URLRetrieveDetailsResponse,
   type URLSubmitForVerificationResponse,
+  type URLEscalateParams,
   type URLListVerifiedParams,
   type URLSubmitForVerificationParams,
   type VerifiedURLsCursor,

package/src/resources/introspect.ts

@@ -6,6 +6,32 @@ import { APIPromise } from '../core/api-promise';
 import { RequestOptions } from '../internal/request-options';
 
 export class Introspect extends APIResource {
+  /**
+   * Heuristic email validation to run before sending: catches invalid syntax, dead
+   * domains (no MX/A records), disposable inboxes, role-based addresses (info@,
+   * contacto@, sales@), and addresses already on your project's suppression list.
+   * Use it to clean a list before a broadcast and keep your bounce rate low.
+   *
+   * No mailbox-level (SMTP) probe is performed, so a `deliverable` verdict is not a
+   * delivery guarantee — it means no negative signal was found. Treat `risky`
+   * addresses with care and drop `undeliverable` ones.
+   *
+   * Accepts a single `email` or an `emails` batch (max 100 per request).
+   *
+   * @example
+   * ```ts
+   * const response = await client.introspect.validateEmail({
+   *   email: 'maria@example.com',
+   * });
+   * ```
+   */
+  validateEmail(
+    body: IntrospectValidateEmailParams,
+    options?: RequestOptions,
+  ): APIPromise<IntrospectValidateEmailResponse> {
+    return this._client.post('/v1/introspect/email', { body, ...options });
+  }
+
   /**
    * Validate a phone number and check if a WhatsApp conversation window is open.
    *
@@ -29,6 +55,71 @@ export class Introspect extends APIResource {
  */
 export type LineType = 'mobile' | 'landline' | 'voip' | 'toll_free' | 'unknown';
 
+export interface IntrospectValidateEmailResponse {
+  /**
+   * One result per submitted address, in the same order.
+   */
+  results: Array<IntrospectValidateEmailResponse.Result>;
+
+  summary: IntrospectValidateEmailResponse.Summary;
+}
+
+export namespace IntrospectValidateEmailResponse {
+  export interface Result {
+    /**
+     * Domain part of the address. Null when the syntax is invalid.
+     */
+    domain: string | null;
+
+    /**
+     * The address exactly as submitted.
+     */
+    email: string;
+
+    /**
+     * Lowercased, trimmed form of the address. Null when the syntax is invalid.
+     */
+    normalized: string | null;
+
+    /**
+     * Signals behind the verdict. Empty for a clean `deliverable` address.
+     */
+    reasons: Array<
+      | 'invalid_syntax'
+      | 'domain_not_found'
+      | 'domain_no_mx'
+      | 'disposable_domain'
+      | 'role_address'
+      | 'suppressed_hard_bounce'
+      | 'suppressed_soft_bounce'
+      | 'suppressed_complaint'
+      | 'suppressed_manual'
+      | 'suppressed_unsubscribe'
+    >;
+
+    /**
+     * Validation verdict.
+     *
+     * - `deliverable`: nothing suggests the address will bounce.
+     * - `risky`: sendable, but a signal predicts elevated bounce/complaint odds (role
+     *   address, disposable domain, MX-less domain, prior soft bounce).
+     * - `undeliverable`: will bounce or is blocked (invalid syntax, dead domain, or
+     *   the address is on your suppression list after a hard bounce/complaint).
+     */
+    verdict: 'deliverable' | 'risky' | 'undeliverable';
+  }
+
+  export interface Summary {
+    deliverable: number;
+
+    risky: number;
+
+    total: number;
+
+    undeliverable: number;
+  }
+}
+
 export interface IntrospectValidatePhoneResponse {
   countryCode: string;
 
@@ -74,6 +165,18 @@ export namespace IntrospectValidatePhoneResponse {
   }
 }
 
+export interface IntrospectValidateEmailParams {
+  /**
+   * Single email address to validate.
+   */
+  email?: string;
+
+  /**
+   * Batch of email addresses to validate (max 100).
+   */
+  emails?: Array<string>;
+}
+
 export interface IntrospectValidatePhoneParams {
   phoneNumber: string;
 }
@@ -81,7 +184,9 @@ export interface IntrospectValidatePhoneParams {
 export declare namespace Introspect {
   export {
     type LineType as LineType,
+    type IntrospectValidateEmailResponse as IntrospectValidateEmailResponse,
     type IntrospectValidatePhoneResponse as IntrospectValidatePhoneResponse,
+    type IntrospectValidateEmailParams as IntrospectValidateEmailParams,
     type IntrospectValidatePhoneParams as IntrospectValidatePhoneParams,
   };
 }

package/src/resources/messages.ts

@@ -40,6 +40,25 @@ export class Messages extends APIResource {
     return this._client.getAPIList('/v1/messages', Cursor<Message>, { query, ...options });
   }
 
+  /**
+   * List the stored file attachments for an email message and get a short-lived
+   * signed `downloadUrl` for each. Works for both inbound emails (received via
+   * `message.inbound`) and outbound emails you sent with attachments. Messages
+   * without stored attachments (including SMS, WhatsApp, and other channels) return
+   * an empty list. Each `downloadUrl` is generated fresh per request and expires —
+   * fetch the file promptly and do not cache the URL.
+   *
+   * @example
+   * ```ts
+   * const response = await client.messages.listAttachments(
+   *   'messageId',
+   * );
+   * ```
+   */
+  listAttachments(messageID: string, options?: RequestOptions): APIPromise<MessageListAttachmentsResponse> {
+    return this._client.get(path`/v1/messages/${messageID}/attachments`, options);
+  }
+
   /**
    * Send an emoji reaction to an existing WhatsApp message. Reactions are only
    * supported for WhatsApp messages.
@@ -96,6 +115,36 @@ export class Messages extends APIResource {
    *   100/day. Teams on earlier plans keep their original email quotas instead
    * - SMS and voice are billed per message from your balance on every plan
    *
+   * **Account verification and daily limits:**
+   *
+   * - A brand-new account can send on every channel immediately, but `sms`,
+   *   `sms_oneway` and `voice` reach only the phone numbers the project has
+   *   verified. Sending elsewhere returns `403` with code
+   *   `destination_not_verified`; `details.verifiedNumbers` lists the numbers that
+   *   are reachable. A number is verified from the dashboard's Sandbox screen:
+   *   generate a code and send the pre-filled WhatsApp message from that phone to
+   *   Zavu's sandbox number. One verification covers WhatsApp, SMS and calls, up to
+   *   5 numbers per project. To send to any destination, do any one of these: verify
+   *   your identity, add a payment method, settle a deposit, or subscribe to a paid
+   *   plan. Business verification (KYB) is never required to send
+   * - Daily ceilings apply per channel group and rise with verification. An account
+   *   that has verified nothing: 25/day across `sms` + `sms_oneway`, 5/day for
+   *   `voice`, 100/day across WhatsApp, Telegram, Instagram and Messenger combined.
+   *   Past that floor: 200/day for SMS, or 10,000/day once identity or business
+   *   verification is approved (or a higher limit agreed for your account); 50/day
+   *   voice and 250/day conversational on Free. **Paid plans have no voice or
+   *   conversational daily ceiling.** Over a ceiling, sends return `429` with code
+   *   `daily_limit_exceeded` and `details.limit`; the count resets at 00:00 UTC
+   * - The daily ceiling never reduces the monthly allowance: 100/day on the
+   *   conversational group still reaches the 2,000 monthly A2P messages Free
+   *   includes
+   * - Email needs no account verification here: a sender with a verified domain
+   *   sends from day one, within the plan quota (100/day and 3,000/month on Free).
+   *   Over the daily quota it returns `429` with code `daily_limit_exceeded`. Email
+   *   broadcasts are the exception: they need the account past the unverified level,
+   *   see `POST /v1/broadcasts/{broadcastId}/send`
+   * - Full reference: https://docs.zavu.dev/concepts/sending-limits
+   *
    * **Email recipient pre-flight:** Email messages are validated automatically
    * before dispatch. Sends that would be a guaranteed hard bounce are failed instead
    * of sent, protecting your bounce rate: the message transitions to `failed`
@@ -183,6 +232,12 @@ export interface Message {
 
   createdAt: string;
 
+  /**
+   * Who sent the message. Needed to render a thread: `status` cannot tell the two
+   * apart, because an inbound message is also stored as `delivered`.
+   */
+  direction: 'inbound' | 'outbound';
+
   /**
    * Type of message. Non-text types are supported by WhatsApp and Telegram (varies
    * by type).
@@ -596,6 +651,52 @@ export type MessageType =
   | 'reaction'
   | 'template';
 
+export interface MessageListAttachmentsResponse {
+  items: Array<MessageListAttachmentsResponse.Item>;
+}
+
+export namespace MessageListAttachmentsResponse {
+  /**
+   * A stored file attachment for an email message (inbound or outbound).
+   */
+  export interface Item {
+    id: string;
+
+    /**
+     * Content-ID for inline attachments (referenced in the HTML body as
+     * `cid:<contentId>`). Null for regular attachments.
+     */
+    contentId: string | null;
+
+    createdAt: string;
+
+    /**
+     * Short-lived signed URL to download the attachment bytes. Freshly generated on
+     * each request and expires; do not cache it. Null if the stored file is no longer
+     * available.
+     */
+    downloadUrl: string | null;
+
+    filename: string;
+
+    /**
+     * Whether the attachment is inline (embedded in the HTML body) rather than a
+     * regular attachment.
+     */
+    isInline: boolean;
+
+    /**
+     * MIME type of the attachment.
+     */
+    mimeType: string;
+
+    /**
+     * Size of the attachment in bytes.
+     */
+    size: number;
+  }
+}
+
 export interface MessageShowTypingResponse {
   success: boolean;
 }
@@ -760,6 +861,7 @@ export declare namespace Messages {
     type MessageResponse as MessageResponse,
     type MessageStatus as MessageStatus,
     type MessageType as MessageType,
+    type MessageListAttachmentsResponse as MessageListAttachmentsResponse,
     type MessageShowTypingResponse as MessageShowTypingResponse,
     type MessagesCursor as MessagesCursor,
     type MessageListParams as MessageListParams,

package/src/resources/number-10dlc/brands.ts

@@ -115,11 +115,16 @@ export class Brands extends APIResource {
 
   /**
    * Submit a draft brand to The Campaign Registry (TCR) for vetting. The brand must
-   * be in draft status. TCR's one-time $4 brand registration fee is charged from
-   * your balance at submission (passed through at cost) and refunded if the carrier
-   * rejects the registration. A team that already paid this fee through the
-   * compliance flow is not charged again. Campaign registration is billed separately
-   * when a campaign is submitted.
+   * be in draft status, and the team must have an approved Business Verification
+   * (KYB) — carriers register a brand against a vetted legal entity, so submitting
+   * without one returns `403` with code `kyb_required`.
+   *
+   * TCR's one-time $4 brand registration fee is charged from your balance at
+   * submission (passed through at cost) and refunded if the carrier rejects the
+   * registration. The fee is per BRAND: a team registering a second legal entity
+   * pays it again. A brand already paid for through the compliance flow is not
+   * charged twice. Campaign registration is billed separately when a campaign is
+   * submitted.
    *
    * @example
    * ```ts

package/src/resources/number-10dlc/campaigns/campaigns.ts

@@ -116,13 +116,14 @@ export class Campaigns extends APIResource {
   }
 
   /**
-   * Submit a draft campaign for carrier review. The campaign must be in draft status
-   * and its brand must be verified. TCR's one-time registration fee is charged from
-   * your balance at submission ($15 for standard use cases, $2 for LOW_VOLUME),
-   * passed through at cost and refunded if the carrier rejects it. Once approved,
-   * the campaign's monthly TCR fee ($10 standard, $2 LOW_VOLUME) is charged from
-   * your balance while the campaign is active — see registrationCostCents and
-   * monthlyFeeCents on the campaign object.
+   * The team must have an approved Business Verification (KYB): submitting without
+   * one returns `403` with code `kyb_required`. Submit a draft campaign for carrier
+   * review. The campaign must be in draft status and its brand must be verified.
+   * TCR's one-time registration fee is charged from your balance at submission ($15
+   * for standard use cases, $2 for LOW_VOLUME), passed through at cost and refunded
+   * if the carrier rejects it. Once approved, the campaign's monthly TCR fee ($10
+   * standard, $2 LOW_VOLUME) is charged from your balance while the campaign is
+   * active — see registrationCostCents and monthlyFeeCents on the campaign object.
    *
    * @example
    * ```ts

package/src/resources/phone-numbers.ts

@@ -229,7 +229,12 @@ export interface PhoneNumberPricing {
 
 export type PhoneNumberStatus = 'active' | 'suspended' | 'pending';
 
-export type PhoneNumberType = 'local' | 'national' | 'tollFree';
+/**
+ * Type of phone number. `mobile` is stocked in countries where no geographic
+ * (`local`) or non-geographic (`national`) inventory exists, and in several
+ * markets it is the only type that can receive SMS.
+ */
+export type PhoneNumberType = 'local' | 'national' | 'tollFree' | 'mobile';
 
 /**
  * A group of requirements for a specific country/phone type combination.

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

@@ -26,23 +26,6 @@ import {
   FlowUpdateResponse,
   Flows,
 } from './flows';
-import * as ToolsAPI from './tools';
-import {
-  AgentTool,
-  AgentToolsCursor,
-  ToolCreateParams,
-  ToolCreateResponse,
-  ToolDeleteParams,
-  ToolListParams,
-  ToolParameters,
-  ToolRetrieveParams,
-  ToolRetrieveResponse,
-  ToolTestParams,
-  ToolTestResponse,
-  ToolUpdateParams,
-  ToolUpdateResponse,
-  Tools,
-} from './tools';
 import * as KnowledgeBasesAPI from './knowledge-bases/knowledge-bases';
 import {
   AgentDocument,
@@ -58,6 +41,25 @@ import {
   KnowledgeBaseUpdateResponse,
   KnowledgeBases,
 } from './knowledge-bases/knowledge-bases';
+import * as ToolsAPI from './tools/tools';
+import {
+  AgentTool,
+  AgentToolsCursor,
+  ToolCreateParams,
+  ToolCreateResponse,
+  ToolDeleteParams,
+  ToolListParams,
+  ToolListTestRunsParams,
+  ToolListTestRunsResponse,
+  ToolParameters,
+  ToolRetrieveParams,
+  ToolRetrieveResponse,
+  ToolTestParams,
+  ToolTestResponse,
+  ToolUpdateParams,
+  ToolUpdateResponse,
+  Tools,
+} from './tools/tools';
 import { APIPromise } from '../../../core/api-promise';
 import { Cursor } from '../../../core/pagination';
 import { buildHeaders } from '../../../internal/headers';
@@ -158,6 +160,8 @@ export class AgentResource extends APIResource {
 
 export type AgentExecutionsCursor = Cursor<AgentExecution>;
 
+export type AgentsCursor = Cursor<Agent>;
+
 /**
  * AI Agent configuration for a sender.
  */
@@ -771,6 +775,7 @@ export declare namespace AgentResource {
     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,
@@ -778,6 +783,7 @@ export declare namespace AgentResource {
     type ToolUpdateParams as ToolUpdateParams,
     type ToolListParams as ToolListParams,
     type ToolDeleteParams as ToolDeleteParams,
+    type ToolListTestRunsParams as ToolListTestRunsParams,
     type ToolTestParams as ToolTestParams,
   };
 

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

@@ -11,6 +11,7 @@ export {
   type AgentCreateParams,
   type AgentUpdateParams,
   type AgentExecutionsCursor,
+  type AgentsCursor,
 } from './agent';
 export {
   Executions,
@@ -57,12 +58,14 @@ export {
   type ToolCreateResponse,
   type ToolRetrieveResponse,
   type ToolUpdateResponse,
+  type ToolListTestRunsResponse,
   type ToolTestResponse,
   type ToolCreateParams,
   type ToolRetrieveParams,
   type ToolUpdateParams,
   type ToolListParams,
   type ToolDeleteParams,
+  type ToolListTestRunsParams,
   type ToolTestParams,
   type AgentToolsCursor,
-} from './tools';
+} from './tools/index';

package/src/resources/senders/agent/knowledge-bases/documents.ts

@@ -85,12 +85,69 @@ export class Documents extends APIResource {
       { ...options, headers: buildHeaders([{ Accept: '*/*' }, options?.headers]) },
     );
   }
+
+  /**
+   * Get a single document from a knowledge base.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.senders.agent.knowledgeBases.documents.retrieveDocument(
+   *     'docId',
+   *     { senderId: 'senderId', kbId: 'kbId' },
+   *   );
+   * ```
+   */
+  retrieveDocument(
+    docID: string,
+    params: DocumentRetrieveDocumentParams,
+    options?: RequestOptions,
+  ): APIPromise<DocumentRetrieveDocumentResponse> {
+    const { senderId, kbId } = params;
+    return this._client.get(
+      path`/v1/senders/${senderId}/agent/knowledge-bases/${kbId}/documents/${docID}`,
+      options,
+    );
+  }
+
+  /**
+   * Update a document's title or content. Updating content reprocesses the document
+   * for RAG.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.senders.agent.knowledgeBases.documents.updateDocument(
+   *     'docId',
+   *     { senderId: 'senderId', kbId: 'kbId' },
+   *   );
+   * ```
+   */
+  updateDocument(
+    docID: string,
+    params: DocumentUpdateDocumentParams,
+    options?: RequestOptions,
+  ): APIPromise<DocumentUpdateDocumentResponse> {
+    const { senderId, kbId, ...body } = params;
+    return this._client.patch(
+      path`/v1/senders/${senderId}/agent/knowledge-bases/${kbId}/documents/${docID}`,
+      { body, ...options },
+    );
+  }
 }
 
 export interface DocumentCreateResponse {
   document: KnowledgeBasesAPI.AgentDocument;
 }
 
+export interface DocumentRetrieveDocumentResponse {
+  document: KnowledgeBasesAPI.AgentDocument;
+}
+
+export interface DocumentUpdateDocumentResponse {
+  document: KnowledgeBasesAPI.AgentDocument;
+}
+
 export interface DocumentCreateParams {
   /**
    * Path param
@@ -121,12 +178,44 @@ export interface DocumentDeleteParams {
   kbId: string;
 }
 
+export interface DocumentRetrieveDocumentParams {
+  senderId: string;
+
+  kbId: string;
+}
+
+export interface DocumentUpdateDocumentParams {
+  /**
+   * Path param
+   */
+  senderId: string;
+
+  /**
+   * Path param
+   */
+  kbId: string;
+
+  /**
+   * Body param
+   */
+  content?: string;
+
+  /**
+   * Body param
+   */
+  title?: string;
+}
+
 export declare namespace Documents {
   export {
     type DocumentCreateResponse as DocumentCreateResponse,
+    type DocumentRetrieveDocumentResponse as DocumentRetrieveDocumentResponse,
+    type DocumentUpdateDocumentResponse as DocumentUpdateDocumentResponse,
     type DocumentCreateParams as DocumentCreateParams,
     type DocumentListParams as DocumentListParams,
     type DocumentDeleteParams as DocumentDeleteParams,
+    type DocumentRetrieveDocumentParams as DocumentRetrieveDocumentParams,
+    type DocumentUpdateDocumentParams as DocumentUpdateDocumentParams,
   };
 }
 

package/src/resources/senders/agent/knowledge-bases/index.ts

@@ -3,9 +3,13 @@
 export {
   Documents,
   type DocumentCreateResponse,
+  type DocumentRetrieveDocumentResponse,
+  type DocumentUpdateDocumentResponse,
   type DocumentCreateParams,
   type DocumentListParams,
   type DocumentDeleteParams,
+  type DocumentRetrieveDocumentParams,
+  type DocumentUpdateDocumentParams,
 } from './documents';
 export {
   KnowledgeBases,