@zavudev/sdk 0.7.0 → 0.8.0

package/src/resources/broadcasts/broadcasts.ts

@@ -0,0 +1,519 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+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 { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Broadcasts extends APIResource {
+  contacts: ContactsAPI.Contacts = new ContactsAPI.Contacts(this._client);
+
+  /**
+   * 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.',
+   * });
+   * ```
+   */
+  create(body: BroadcastCreateParams, options?: RequestOptions): APIPromise<BroadcastCreateResponse> {
+    return this._client.post('/v1/broadcasts', { body, ...options });
+  }
+
+  /**
+   * Get broadcast
+   *
+   * @example
+   * ```ts
+   * const broadcast = await client.broadcasts.retrieve(
+   *   'broadcastId',
+   * );
+   * ```
+   */
+  retrieve(broadcastID: string, options?: RequestOptions): APIPromise<BroadcastRetrieveResponse> {
+    return this._client.get(path`/v1/broadcasts/${broadcastID}`, options);
+  }
+
+  /**
+   * Update a broadcast in draft status.
+   *
+   * @example
+   * ```ts
+   * const broadcast = await client.broadcasts.update(
+   *   'broadcastId',
+   * );
+   * ```
+   */
+  update(
+    broadcastID: string,
+    body: BroadcastUpdateParams,
+    options?: RequestOptions,
+  ): APIPromise<BroadcastUpdateResponse> {
+    return this._client.patch(path`/v1/broadcasts/${broadcastID}`, { body, ...options });
+  }
+
+  /**
+   * List broadcasts for this project.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const broadcast of client.broadcasts.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: BroadcastListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<BroadcastsCursor, Broadcast> {
+    return this._client.getAPIList('/v1/broadcasts', Cursor<Broadcast>, { query, ...options });
+  }
+
+  /**
+   * Delete a broadcast in draft status.
+   *
+   * @example
+   * ```ts
+   * await client.broadcasts.delete('broadcastId');
+   * ```
+   */
+  delete(broadcastID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v1/broadcasts/${broadcastID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+
+  /**
+   * 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',
+   * );
+   * ```
+   */
+  cancel(broadcastID: string, options?: RequestOptions): APIPromise<BroadcastCancelResponse> {
+    return this._client.post(path`/v1/broadcasts/${broadcastID}/cancel`, options);
+  }
+
+  /**
+   * Get real-time progress of a broadcast including delivery counts and estimated
+   * completion time.
+   *
+   * @example
+   * ```ts
+   * const broadcastProgress = await client.broadcasts.progress(
+   *   'broadcastId',
+   * );
+   * ```
+   */
+  progress(broadcastID: string, options?: RequestOptions): APIPromise<BroadcastProgress> {
+    return this._client.get(path`/v1/broadcasts/${broadcastID}/progress`, options);
+  }
+
+  /**
+   * Start sending the broadcast immediately or schedule for later. Reserves the
+   * estimated cost from your balance.
+   *
+   * @example
+   * ```ts
+   * const response = await client.broadcasts.send(
+   *   'broadcastId',
+   * );
+   * ```
+   */
+  send(
+    broadcastID: string,
+    body: BroadcastSendParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<BroadcastSendResponse> {
+    return this._client.post(path`/v1/broadcasts/${broadcastID}/send`, { body, ...options });
+  }
+}
+
+export type BroadcastsCursor = Cursor<Broadcast>;
+
+export type BroadcastContactsCursor = Cursor<BroadcastContact>;
+
+export interface Broadcast {
+  id: string;
+
+  /**
+   * Broadcast delivery channel.
+   */
+  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 };
+
+  pendingCount?: number;
+
+  /**
+   * Amount reserved from balance in USD.
+   */
+  reservedAmount?: number | null;
+
+  scheduledAt?: string;
+
+  senderId?: string;
+
+  sendingCount?: number;
+
+  startedAt?: string;
+
+  text?: string;
+
+  updatedAt?: string;
+}
+
+/**
+ * Broadcast delivery channel.
+ */
+export type BroadcastChannel = 'sms' | 'whatsapp' | '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;
+
+  errorCode?: string;
+
+  errorMessage?: string;
+
+  /**
+   * Associated message ID after processing.
+   */
+  messageId?: string;
+
+  processedAt?: string;
+
+  templateVariables?: { [key: string]: string };
+}
+
+/**
+ * Status of a contact within a broadcast.
+ */
+export type BroadcastContactStatus = 'pending' | 'queued' | 'sending' | 'delivered' | 'failed' | 'skipped';
+
+/**
+ * Content for non-text broadcast message types.
+ */
+export interface BroadcastContent {
+  /**
+   * Filename for documents.
+   */
+  filename?: string;
+
+  /**
+   * Media ID if already uploaded.
+   */
+  mediaId?: string;
+
+  /**
+   * URL of the media file.
+   */
+  mediaUrl?: string;
+
+  /**
+   * MIME type of the media.
+   */
+  mimeType?: string;
+
+  /**
+   * Template ID for template messages.
+   */
+  templateId?: string;
+
+  /**
+   * Default template variables (can be overridden per contact).
+   */
+  templateVariables?: { [key: string]: string };
+}
+
+/**
+ * Type of message for broadcast.
+ */
+export type BroadcastMessageType = 'text' | 'image' | 'video' | 'audio' | 'document' | 'template';
+
+export interface BroadcastProgress {
+  broadcastId: string;
+
+  /**
+   * Successfully delivered.
+   */
+  delivered: number;
+
+  /**
+   * 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'
+  | '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 BroadcastSendResponse {
+  broadcast: Broadcast;
+}
+
+export interface BroadcastCreateParams {
+  /**
+   * Broadcast delivery channel.
+   */
+  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 BroadcastSendParams {
+  /**
+   * Schedule for future delivery. Omit to send immediately.
+   */
+  scheduledAt?: string;
+}
+
+Broadcasts.Contacts = Contacts;
+
+export declare namespace Broadcasts {
+  export {
+    type Broadcast as Broadcast,
+    type BroadcastChannel as BroadcastChannel,
+    type BroadcastContact as BroadcastContact,
+    type BroadcastContactStatus as BroadcastContactStatus,
+    type BroadcastContent as BroadcastContent,
+    type BroadcastMessageType as BroadcastMessageType,
+    type BroadcastProgress as BroadcastProgress,
+    type BroadcastStatus as BroadcastStatus,
+    type BroadcastCreateResponse as BroadcastCreateResponse,
+    type BroadcastRetrieveResponse as BroadcastRetrieveResponse,
+    type BroadcastUpdateResponse as BroadcastUpdateResponse,
+    type BroadcastCancelResponse as BroadcastCancelResponse,
+    type BroadcastSendResponse as BroadcastSendResponse,
+    type BroadcastsCursor as BroadcastsCursor,
+    type BroadcastCreateParams as BroadcastCreateParams,
+    type BroadcastUpdateParams as BroadcastUpdateParams,
+    type BroadcastListParams as BroadcastListParams,
+    type BroadcastSendParams as BroadcastSendParams,
+  };
+
+  export {
+    Contacts as Contacts,
+    type ContactAddResponse as ContactAddResponse,
+    type ContactListParams as ContactListParams,
+    type ContactAddParams as ContactAddParams,
+    type ContactRemoveParams as ContactRemoveParams,
+  };
+}

package/src/resources/broadcasts/contacts.ts

@@ -0,0 +1,160 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as BroadcastsAPI from './broadcasts';
+import { BroadcastContactsCursor } from './broadcasts';
+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 Contacts extends APIResource {
+  /**
+   * List contacts in a broadcast with optional status filter.
+   *
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const broadcastContact of client.broadcasts.contacts.list(
+   *   'broadcastId',
+   * )) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    broadcastID: string,
+    query: ContactListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<BroadcastContactsCursor, BroadcastsAPI.BroadcastContact> {
+    return this._client.getAPIList(
+      path`/v1/broadcasts/${broadcastID}/contacts`,
+      Cursor<BroadcastsAPI.BroadcastContact>,
+      { query, ...options },
+    );
+  }
+
+  /**
+   * Add contacts to a broadcast in batch. Maximum 1000 contacts per request.
+   *
+   * @example
+   * ```ts
+   * const response = await client.broadcasts.contacts.add(
+   *   'broadcastId',
+   *   {
+   *     contacts: [
+   *       {
+   *         recipient: '+14155551234',
+   *         templateVariables: {
+   *           name: 'John',
+   *           order_id: 'ORD-001',
+   *         },
+   *       },
+   *       {
+   *         recipient: '+14155555678',
+   *         templateVariables: {
+   *           name: 'Jane',
+   *           order_id: 'ORD-002',
+   *         },
+   *       },
+   *     ],
+   *   },
+   * );
+   * ```
+   */
+  add(broadcastID: string, body: ContactAddParams, options?: RequestOptions): APIPromise<ContactAddResponse> {
+    return this._client.post(path`/v1/broadcasts/${broadcastID}/contacts`, { body, ...options });
+  }
+
+  /**
+   * Remove a contact from a broadcast in draft status.
+   *
+   * @example
+   * ```ts
+   * await client.broadcasts.contacts.remove('contactId', {
+   *   broadcastId: 'broadcastId',
+   * });
+   * ```
+   */
+  remove(contactID: string, params: ContactRemoveParams, options?: RequestOptions): APIPromise<void> {
+    const { broadcastId } = params;
+    return this._client.delete(path`/v1/broadcasts/${broadcastId}/contacts/${contactID}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface ContactAddResponse {
+  /**
+   * Number of contacts successfully added.
+   */
+  added: number;
+
+  /**
+   * Number of duplicate contacts skipped.
+   */
+  duplicates: number;
+
+  /**
+   * Number of invalid contacts rejected.
+   */
+  invalid: number;
+
+  /**
+   * Details about invalid contacts.
+   */
+  errors?: Array<ContactAddResponse.Error>;
+}
+
+export namespace ContactAddResponse {
+  export interface Error {
+    reason?: string;
+
+    recipient?: string;
+  }
+}
+
+export interface ContactListParams extends CursorParams {
+  /**
+   * Status of a contact within a broadcast.
+   */
+  status?: BroadcastsAPI.BroadcastContactStatus;
+}
+
+export interface ContactAddParams {
+  /**
+   * List of contacts to add (max 1000 per request).
+   */
+  contacts: Array<ContactAddParams.Contact>;
+}
+
+export namespace ContactAddParams {
+  export interface Contact {
+    /**
+     * Phone number (E.164) or email address.
+     */
+    recipient: string;
+
+    /**
+     * Per-contact template variables to personalize the message.
+     */
+    templateVariables?: { [key: string]: string };
+  }
+}
+
+export interface ContactRemoveParams {
+  broadcastId: string;
+}
+
+export declare namespace Contacts {
+  export {
+    type ContactAddResponse as ContactAddResponse,
+    type ContactListParams as ContactListParams,
+    type ContactAddParams as ContactAddParams,
+    type ContactRemoveParams as ContactRemoveParams,
+  };
+}
+
+export { type BroadcastContactsCursor };

package/src/resources/broadcasts/index.ts

@@ -0,0 +1,31 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Broadcasts,
+  type Broadcast,
+  type BroadcastChannel,
+  type BroadcastContact,
+  type BroadcastContactStatus,
+  type BroadcastContent,
+  type BroadcastMessageType,
+  type BroadcastProgress,
+  type BroadcastStatus,
+  type BroadcastCreateResponse,
+  type BroadcastRetrieveResponse,
+  type BroadcastUpdateResponse,
+  type BroadcastCancelResponse,
+  type BroadcastSendResponse,
+  type BroadcastCreateParams,
+  type BroadcastUpdateParams,
+  type BroadcastListParams,
+  type BroadcastSendParams,
+  type BroadcastContactsCursor,
+  type BroadcastsCursor,
+} from './broadcasts';
+export {
+  Contacts,
+  type ContactAddResponse,
+  type ContactListParams,
+  type ContactAddParams,
+  type ContactRemoveParams,
+} from './contacts';

package/src/resources/broadcasts.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './broadcasts/index';