@zavudev/sdk 0.56.0 → 0.58.0

package/src/resources/broadcasts/broadcasts.ts

@@ -1,34 +1,30 @@
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+// Generated by zavu-codegen from apps/docs/openapi.json. Do not edit: run `bun run codegen`.
 
 import { APIResource } from '../../core/resource';
-import * as ContactsAPI from './contacts';
-import {
-  ContactAddParams,
-  ContactAddResponse,
-  ContactListParams,
-  ContactRemoveParams,
-  Contacts,
-} from './contacts';
 import { APIPromise } from '../../core/api-promise';
-import { Cursor, type CursorParams, PagePromise } from '../../core/pagination';
+import { Cursor, PagePromise } from '../../core/pagination';
 import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
+import type * as T from '../../types';
+import * as ContactsAPI from './contacts';
+import {
+  Contacts,
+  type ContactAddResponse,
+  type ContactListParams,
+  type ContactAddParams,
+  type ContactRemoveParams,
+} from './contacts';
 
 export class Broadcasts extends APIResource {
   contacts: ContactsAPI.Contacts = new ContactsAPI.Contacts(this._client);
 
   /**
+   * Create broadcast
+   *
    * Create a new broadcast campaign. Add contacts after creation, then send.
    *
-   * @example
-   * ```ts
-   * const broadcast = await client.broadcasts.create({
-   *   channel: 'sms',
-   *   name: 'Black Friday Sale',
-   *   text: 'Hi {{name}}, check out our Black Friday deals! Use code FRIDAY20 for 20% off.',
-   * });
-   * ```
+   * `POST /v1/broadcasts`
    */
   create(body: BroadcastCreateParams, options?: RequestOptions): APIPromise<BroadcastCreateResponse> {
     return this._client.post('/v1/broadcasts', { body, ...options });
@@ -37,26 +33,18 @@ export class Broadcasts extends APIResource {
   /**
    * Get broadcast
    *
-   * @example
-   * ```ts
-   * const broadcast = await client.broadcasts.retrieve(
-   *   'broadcastId',
-   * );
-   * ```
+   * `GET /v1/broadcasts/{broadcastId}`
    */
   retrieve(broadcastID: string, options?: RequestOptions): APIPromise<BroadcastRetrieveResponse> {
     return this._client.get(path`/v1/broadcasts/${broadcastID}`, options);
   }
 
   /**
+   * Update broadcast
+   *
    * Update a broadcast in draft status.
    *
-   * @example
-   * ```ts
-   * const broadcast = await client.broadcasts.update(
-   *   'broadcastId',
-   * );
-   * ```
+   * `PATCH /v1/broadcasts/{broadcastId}`
    */
   update(
     broadcastID: string,
@@ -67,15 +55,11 @@ export class Broadcasts extends APIResource {
   }
 
   /**
+   * List broadcasts
+   *
    * List broadcasts for this project.
    *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const broadcast of client.broadcasts.list()) {
-   *   // ...
-   * }
-   * ```
+   * `GET /v1/broadcasts`
    */
   list(
     query: BroadcastListParams | null | undefined = {},
@@ -85,12 +69,11 @@ export class Broadcasts extends APIResource {
   }
 
   /**
+   * Delete broadcast
+   *
    * Delete a broadcast in draft status.
    *
-   * @example
-   * ```ts
-   * await client.broadcasts.delete('broadcastId');
-   * ```
+   * `DELETE /v1/broadcasts/{broadcastId}`
    */
   delete(broadcastID: string, options?: RequestOptions): APIPromise<void> {
     return this._client.delete(path`/v1/broadcasts/${broadcastID}`, {
@@ -100,61 +83,53 @@ export class Broadcasts extends APIResource {
   }
 
   /**
+   * Cancel broadcast
+   *
    * Cancel a broadcast. Pending contacts will be skipped, but already queued
    * messages may still be delivered.
    *
-   * @example
-   * ```ts
-   * const response = await client.broadcasts.cancel(
-   *   'broadcastId',
-   * );
-   * ```
+   * A broadcast can be cancelled from `draft`, `pending_review`,
+   * `pending_admin_review`, `approved`, `rejected`, `escalated`, `scheduled` and
+   * `sending`. Any balance reserved for it is released. A review still running when
+   * it is cancelled cannot bring it back.
+   *
+   * `POST /v1/broadcasts/{broadcastId}/cancel`
    */
   cancel(broadcastID: string, options?: RequestOptions): APIPromise<BroadcastCancelResponse> {
     return this._client.post(path`/v1/broadcasts/${broadcastID}/cancel`, options);
   }
 
   /**
+   * Escalate to manual review
+   *
    * Request manual review by the Zavu team for a rejected broadcast. Use this after
    * automated review rejection if you believe the content is legitimate.
    *
-   * @example
-   * ```ts
-   * const response = await client.broadcasts.escalateReview(
-   *   'broadcastId',
-   * );
-   * ```
+   * `POST /v1/broadcasts/{broadcastId}/escalate`
    */
   escalateReview(broadcastID: string, options?: RequestOptions): APIPromise<BroadcastEscalateReviewResponse> {
     return this._client.post(path`/v1/broadcasts/${broadcastID}/escalate`, options);
   }
 
   /**
+   * Get broadcast progress
+   *
    * Get real-time progress of a broadcast including delivery counts and estimated
    * completion time.
    *
-   * @example
-   * ```ts
-   * const broadcastProgress = await client.broadcasts.progress(
-   *   'broadcastId',
-   * );
-   * ```
+   * `GET /v1/broadcasts/{broadcastId}/progress`
    */
   progress(broadcastID: string, options?: RequestOptions): APIPromise<BroadcastProgress> {
     return this._client.get(path`/v1/broadcasts/${broadcastID}/progress`, options);
   }
 
   /**
+   * Reschedule broadcast
+   *
    * Update the scheduled time for a broadcast. The broadcast must be in scheduled
    * status.
    *
-   * @example
-   * ```ts
-   * const response = await client.broadcasts.reschedule(
-   *   'broadcastId',
-   *   { scheduledAt: '2024-01-15T14:00:00Z' },
-   * );
-   * ```
+   * `PATCH /v1/broadcasts/{broadcastId}/schedule`
    */
   reschedule(
     broadcastID: string,
@@ -165,51 +140,58 @@ export class Broadcasts extends APIResource {
   }
 
   /**
+   * Retry broadcast review
+   *
    * Resubmit a rejected broadcast for AI review after editing content. Maximum 3
    * review attempts allowed per broadcast.
    *
-   * @example
-   * ```ts
-   * const response = await client.broadcasts.retryReview(
-   *   'broadcastId',
-   * );
-   * ```
+   * `POST /v1/broadcasts/{broadcastId}/retry-review`
    */
   retryReview(broadcastID: string, options?: RequestOptions): APIPromise<BroadcastRetryReviewResponse> {
     return this._client.post(path`/v1/broadcasts/${broadcastID}/retry-review`, options);
   }
 
   /**
+   * Send broadcast
+   *
    * Start sending the broadcast immediately or schedule for later.
    *
-   * **Verification is required to send, except on WhatsApp.** On every channel other
-   * than `whatsapp`, the team must have completed both identity verification (KYC)
-   * and business verification (KYB); passing one is not enough. A `whatsapp`
-   * broadcast requires neither: it can only be built on a template, and Meta vets
-   * the business and the content when it approves that template, so an unapproved
-   * template is refused instead. `smart` is not exempt — it can route a contact to
-   * SMS or email. Drafts can be created, edited and kept without any check. Every
-   * send path — dashboard, API and CLI alike — enforces the same rule, returning
-   * `403` with code `kyc_required` or `kyb_required` for whichever is outstanding.
+   * **Sending a broadcast needs no account verification.** Identity and business
+   * verification raise daily ceilings; neither is a permission to broadcast, on any
+   * channel. What stands in front of a broadcast is the content review below, and it
+   * applies to every send path — dashboard, API and CLI. Drafts can be created,
+   * edited and kept freely.
+   *
+   * **Email broadcasts need a paid plan.** On Free, sending or scheduling a
+   * broadcast on the `email` channel is refused with `402` and code
+   * `paid_plan_required`; drafts can still be created and edited. A `smart`
+   * broadcast is not refused: its email recipients fail individually with
+   * `errorCode` `PAID_PLAN_REQUIRED` and the others are sent. Teams created before
+   * August 1, 2026 keep their earlier terms.
+   *
+   * **Daily ceilings apply per recipient.** Each message a broadcast sends counts
+   * against the channel's daily ceiling (see `POST /v1/messages`). Once the ceiling
+   * is reached, the remaining recipients are marked `failed` with `errorCode`
+   * `DAILY_LIMIT_EXCEEDED`; they are not retried the next day.
    *
    * **Review depends on the channel, and cannot be bypassed.** A draft is submitted
    * to automated content review here; it does not go straight out. A WhatsApp
    * broadcast built on a Meta-approved template skips review (Meta already vetted
-   * the content) and begins sending. An email broadcast sends as soon as the
-   * automated review passes. Every other channel moves to `pending_admin_review` and
-   * waits for a person. If the review rejects it, use PATCH to edit the content then
-   * call POST /retry-review.
+   * the content) and begins sending. An email broadcast sends as soon as the review
+   * passes it, unless the review asks for a person. Every other channel moves to
+   * `pending_admin_review` and waits for a person. A broadcast the review refuses
+   * lands on `rejected`: use PATCH to edit the content then call POST /retry-review,
+   * or escalate it for a manual review.
+   *
+   * A broadcast is read once, on its own text, rather than per recipient. While an
+   * account's sending is suspended its recipients fail individually with `errorCode`
+   * `SENDING_SUSPENDED`; see `POST /v1/messages`.
    *
    * Calling this on a broadcast that is already `approved` or `scheduled` sends or
    * reschedules it directly, since it has already been reviewed. Reserves the
    * estimated cost from your balance.
    *
-   * @example
-   * ```ts
-   * const response = await client.broadcasts.send(
-   *   'broadcastId',
-   * );
-   * ```
+   * `POST /v1/broadcasts/{broadcastId}/send`
    */
   send(
     broadcastID: string,
@@ -220,426 +202,54 @@ export class Broadcasts extends APIResource {
   }
 }
 
-export type BroadcastsCursor = Cursor<Broadcast>;
-
-export type BroadcastContactsCursor = Cursor<BroadcastContact>;
-
-export interface Broadcast {
-  id: string;
-
-  /**
-   * Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.
-   */
-  channel: BroadcastChannel;
-
-  createdAt: string;
-
-  /**
-   * Type of message for broadcast.
-   */
-  messageType: BroadcastMessageType;
-
-  name: string;
-
-  /**
-   * Current status of the broadcast.
-   */
-  status: BroadcastStatus;
-
-  /**
-   * Total number of contacts in the broadcast.
-   */
-  totalContacts: number;
-
-  /**
-   * Actual cost so far in USD.
-   */
-  actualCost?: number | null;
-
-  completedAt?: string;
-
-  /**
-   * Content for non-text broadcast message types.
-   */
-  content?: BroadcastContent;
-
-  deliveredCount?: number;
-
-  emailSubject?: string;
-
-  /**
-   * Estimated total cost in USD.
-   */
-  estimatedCost?: number | null;
-
-  failedCount?: number;
-
-  metadata?: { [key: string]: string };
+export type BroadcastsCursor = Cursor<T.Broadcast>;
 
-  pendingCount?: number;
-
-  /**
-   * Amount reserved from balance in USD.
-   */
-  reservedAmount?: number | null;
-
-  /**
-   * Number of review attempts (max 3).
-   */
-  reviewAttempts?: number | null;
-
-  /**
-   * AI content review result.
-   */
-  reviewResult?: Broadcast.ReviewResult | null;
-
-  scheduledAt?: string;
-
-  senderId?: string;
-
-  sendingCount?: number;
-
-  startedAt?: string;
-
-  text?: string;
-
-  updatedAt?: string;
-}
+export type BroadcastContactsCursor = Cursor<T.BroadcastContact>;
 
+export type Broadcast = T.Broadcast;
 export namespace Broadcast {
-  /**
-   * AI content review result.
-   */
-  export interface ReviewResult {
-    /**
-     * Policy categories violated, if any.
-     */
-    categories?: Array<string>;
-
-    /**
-     * Problematic text fragments, if any.
-     */
-    flaggedContent?: Array<string> | null;
-
-    /**
-     * Explanation of the review decision.
-     */
-    reasoning?: string;
-
-    reviewedAt?: string;
-
-    /**
-     * Content safety score from 0.0 to 1.0, where 1.0 is completely safe.
-     */
-    score?: number;
-  }
+  export type ReviewResult = T.BroadcastReviewResult;
 }
 
-/**
- * Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.
- */
-export type BroadcastChannel = 'smart' | 'sms' | 'sms_oneway' | 'whatsapp' | 'telegram' | 'email';
-
-export interface BroadcastContact {
-  id: string;
-
-  createdAt: string;
-
-  recipient: string;
-
-  recipientType: 'phone' | 'email';
-
-  /**
-   * Status of a contact within a broadcast.
-   */
-  status: BroadcastContactStatus;
-
-  cost?: number | null;
+export type BroadcastChannel = T.BroadcastChannel;
 
-  errorCode?: string;
+export type BroadcastContact = T.BroadcastContact;
 
-  errorMessage?: string;
+export type BroadcastContactStatus = T.BroadcastContactStatus;
 
-  /**
-   * Associated message ID after processing.
-   */
-  messageId?: string;
+export type BroadcastContent = T.BroadcastContent;
 
-  processedAt?: string;
+export type BroadcastMessageType = T.BroadcastMessageType;
 
-  templateButtonVariables?: { [key: string]: string };
+export type BroadcastProgress = T.BroadcastProgress;
 
-  templateHeaderVariables?: { [key: string]: string };
+export type BroadcastStatus = T.BroadcastStatus;
 
-  templateVariables?: { [key: string]: string };
-}
+export type BroadcastCreateResponse = T.BroadcastResponse;
 
-/**
- * Status of a contact within a broadcast.
- */
-export type BroadcastContactStatus = 'pending' | 'queued' | 'sending' | 'delivered' | 'failed' | 'skipped';
+export type BroadcastRetrieveResponse = T.BroadcastResponse;
 
-/**
- * Content for non-text broadcast message types.
- */
-export interface BroadcastContent {
-  /**
-   * Filename for documents.
-   */
-  filename?: string;
+export type BroadcastUpdateResponse = T.BroadcastResponse;
 
-  /**
-   * Media ID if already uploaded.
-   */
-  mediaId?: string;
-
-  /**
-   * URL of the media file.
-   */
-  mediaUrl?: string;
+export type BroadcastCancelResponse = T.BroadcastResponse;
 
-  /**
-   * MIME type of the media.
-   */
-  mimeType?: string;
+export type BroadcastEscalateReviewResponse = T.BroadcastResponse;
 
-  /**
-   * Default button variables for dynamic URL/OTP buttons. Keys are the button index
-   * (0, 1, 2). Per-contact values override these.
-   */
-  templateButtonVariables?: { [key: string]: string };
+export type BroadcastRescheduleResponse = T.BroadcastResponse;
 
-  /**
-   * Default value for a text-header variable, keyed by `1` (can be overridden per
-   * contact). If omitted, Zavu resolves the header from `templateVariables` by the
-   * header placeholder's name.
-   */
-  templateHeaderVariables?: { [key: string]: string };
+export type BroadcastRetryReviewResponse = T.BroadcastResponse;
 
-  /**
-   * Template ID for template messages.
-   */
-  templateId?: string;
+export type BroadcastSendResponse = T.BroadcastResponse;
 
-  /**
-   * Default body variables (can be overridden per contact). Key them to match the
-   * template body: by position (`1`, `2`, ...) for positional templates, or by name
-   * (e.g. `customer_name`) for named templates. Zavu detects the template's format
-   * and sends the correct payload to Meta. Do not mix positional and named keys.
-   */
-  templateVariables?: { [key: string]: string };
-}
+export type BroadcastCreateParams = T.BroadcastsCreateParams;
 
-/**
- * Type of message for broadcast.
- */
-export type BroadcastMessageType = 'text' | 'image' | 'video' | 'audio' | 'document' | 'template';
+export type BroadcastUpdateParams = T.BroadcastsUpdateParams;
 
-export interface BroadcastProgress {
-  broadcastId: string;
+export type BroadcastListParams = T.BroadcastsListParams;
 
-  /**
-   * Successfully delivered.
-   */
-  delivered: number;
+export type BroadcastRescheduleParams = T.BroadcastsRescheduleParams;
 
-  /**
-   * Failed to deliver.
-   */
-  failed: number;
-
-  /**
-   * Not yet queued for sending.
-   */
-  pending: number;
-
-  /**
-   * Percentage complete (0-100).
-   */
-  percentComplete: number;
-
-  /**
-   * Currently being sent.
-   */
-  sending: number;
-
-  /**
-   * Skipped (broadcast cancelled).
-   */
-  skipped: number;
-
-  /**
-   * Current status of the broadcast.
-   */
-  status: BroadcastStatus;
-
-  /**
-   * Total contacts in broadcast.
-   */
-  total: number;
-
-  /**
-   * Actual cost so far in USD.
-   */
-  actualCost?: number | null;
-
-  estimatedCompletionAt?: string;
-
-  /**
-   * Estimated total cost in USD.
-   */
-  estimatedCost?: number | null;
-
-  /**
-   * Amount reserved from balance in USD.
-   */
-  reservedAmount?: number | null;
-
-  startedAt?: string;
-}
-
-/**
- * Current status of the broadcast.
- */
-export type BroadcastStatus =
-  | 'draft'
-  | 'pending_review'
-  | 'approved'
-  | 'rejected'
-  | 'escalated'
-  | 'rejected_final'
-  | 'scheduled'
-  | 'sending'
-  | 'paused'
-  | 'completed'
-  | 'cancelled'
-  | 'failed';
-
-export interface BroadcastCreateResponse {
-  broadcast: Broadcast;
-}
-
-export interface BroadcastRetrieveResponse {
-  broadcast: Broadcast;
-}
-
-export interface BroadcastUpdateResponse {
-  broadcast: Broadcast;
-}
-
-export interface BroadcastCancelResponse {
-  broadcast: Broadcast;
-}
-
-export interface BroadcastEscalateReviewResponse {
-  broadcast: Broadcast;
-}
-
-export interface BroadcastRescheduleResponse {
-  broadcast: Broadcast;
-}
-
-export interface BroadcastRetryReviewResponse {
-  broadcast: Broadcast;
-}
-
-export interface BroadcastSendResponse {
-  broadcast: Broadcast;
-}
-
-export interface BroadcastCreateParams {
-  /**
-   * Broadcast delivery channel. Use 'smart' for per-contact intelligent routing.
-   */
-  channel: BroadcastChannel;
-
-  /**
-   * Name of the broadcast campaign.
-   */
-  name: string;
-
-  /**
-   * Content for non-text broadcast message types.
-   */
-  content?: BroadcastContent;
-
-  /**
-   * HTML body for email broadcasts.
-   */
-  emailHtmlBody?: string;
-
-  /**
-   * Email subject line. Required for email broadcasts.
-   */
-  emailSubject?: string;
-
-  /**
-   * Idempotency key to prevent duplicate broadcasts.
-   */
-  idempotencyKey?: string;
-
-  /**
-   * Type of message for broadcast.
-   */
-  messageType?: BroadcastMessageType;
-
-  metadata?: { [key: string]: string };
-
-  /**
-   * Schedule the broadcast for future delivery.
-   */
-  scheduledAt?: string;
-
-  /**
-   * Sender profile ID. Uses default sender if omitted.
-   */
-  senderId?: string;
-
-  /**
-   * Text content or caption. Supports template variables: {{name}}, {{1}}, etc.
-   */
-  text?: string;
-}
-
-export interface BroadcastUpdateParams {
-  /**
-   * Content for non-text broadcast message types.
-   */
-  content?: BroadcastContent;
-
-  emailHtmlBody?: string;
-
-  emailSubject?: string;
-
-  metadata?: { [key: string]: string };
-
-  name?: string;
-
-  text?: string;
-}
-
-export interface BroadcastListParams extends CursorParams {
-  /**
-   * Current status of the broadcast.
-   */
-  status?: BroadcastStatus;
-}
-
-export interface BroadcastRescheduleParams {
-  /**
-   * New scheduled time for the broadcast.
-   */
-  scheduledAt: string;
-}
-
-export interface BroadcastSendParams {
-  /**
-   * Schedule for future delivery. Omit to send immediately.
-   */
-  scheduledAt?: string;
-}
-
-Broadcasts.Contacts = Contacts;
+export type BroadcastSendParams = T.BroadcastsSendParams;
 
 export declare namespace Broadcasts {
   export {
@@ -665,9 +275,6 @@ export declare namespace Broadcasts {
     type BroadcastListParams as BroadcastListParams,
     type BroadcastRescheduleParams as BroadcastRescheduleParams,
     type BroadcastSendParams as BroadcastSendParams,
-  };
-
-  export {
     Contacts as Contacts,
     type ContactAddResponse as ContactAddResponse,
     type ContactListParams as ContactListParams,