@zavudev/sdk 0.58.1 → 0.59.0

package/src/v2/types.ts

@@ -0,0 +1,2412 @@
+// Generated by zavu-codegen from apps/docs/api-reference/v2/openapi.json. Do not edit: run `bun run codegen`.
+
+// The types every resource module aliases under its public names. Not part of the
+// package's export map: import the names from `@zavudev/sdk` or its resource modules.
+
+/**
+ * A channel whose connection has an on/off switch. `sms`, `sms_oneway` and `voice`
+ * are billed per message and per phone number, are always on, and have nothing to
+ * activate.
+ */
+export type ActivatableChannel = 'whatsapp' | 'telegram' | 'instagram' | 'messenger' | 'email';
+
+/**
+ * Click-to-WhatsApp (CTWA) ad attribution: where an inbound conversation came
+ * from.
+ *
+ * WhatsApp only. Present on the **first inbound message** of a conversation opened
+ * from a Meta ad or post, and on no message after it — so store it when it
+ * arrives rather than expecting it again. Organic conversations never carry it.
+ *
+ * Field names are camelCased to match the rest of this API; Meta sends them as
+ * snake_case (`ctwa_clid`, `source_id`, ...). Fields that do not apply are
+ * omitted: a `post` source has no click id, and an image ad has no `videoUrl`.
+ */
+export interface AdReferral {
+  /** Where the click came from. */
+  sourceType?: AdReferralSourceType;
+  /** Identifier of the ad or post that produced the click. */
+  sourceId?: string;
+  /** Meta permalink to the ad or post. */
+  sourceUrl?: string;
+  /** Headline of the ad or post. */
+  headline?: string;
+  /** Body copy of the ad or post. */
+  body?: string;
+  /** Type of media on the ad, when it had any. */
+  mediaType?: AdReferralMediaType;
+  /** Image of the ad. Present when `mediaType` is `image`. */
+  imageUrl?: string;
+  /** Video of the ad. Present when `mediaType` is `video`. */
+  videoUrl?: string;
+  /** Thumbnail of the ad media. */
+  thumbnailUrl?: string;
+  /**
+   * Click-to-WhatsApp click identifier. This is the value Meta's Conversions API
+   * needs to credit a conversion back to the ad that produced the conversation.
+   * Present on `ad` sources; a `post` source has none.
+   */
+  ctwaClid?: string;
+}
+
+export type AdReferralSourceType = 'ad' | 'post';
+
+export type AdReferralMediaType = 'image' | 'video';
+
+/** An AI agent. It answers on the addresses in `channels`. */
+export interface Agent {
+  id: string;
+  name: string;
+  /** Whether the agent is active. */
+  enabled: boolean;
+  provider: AgentProvider;
+  /** Model ID (e.g., gpt-4o-mini, claude-3-5-sonnet). */
+  model: string;
+  /** System prompt for the agent. */
+  systemPrompt: string;
+  /**
+   * Number of previous messages to include as context.
+   *
+   * @defaultValue `10`
+   */
+  contextWindowMessages?: number;
+  /**
+   * Whether to include contact metadata in context.
+   *
+   * @defaultValue `true`
+   */
+  includeContactMetadata?: boolean;
+  /** Maximum tokens for LLM response. */
+  maxTokens?: number | null;
+  /** LLM temperature (0-2). */
+  temperature?: number | null;
+  /** Channels that trigger the agent. */
+  triggerOnChannels?: Array<string>;
+  /** Message types that trigger the agent. */
+  triggerOnMessageTypes?: Array<string>;
+  stats?: AgentStats;
+  createdAt: string;
+  updatedAt: string;
+  /**
+   * Voice Agent configuration. When present and enabled, the agent can answer
+   * inbound phone calls and place outbound calls with Zavu's managed voice pipeline.
+   * Requires the Voice Agents feature to be enabled for your team.
+   */
+  voice?: AgentVoiceConfig;
+  /**
+   * The (address, type) entries this agent answers on: every transport of the
+   * addresses it is connected to that its `triggerOnChannels` allows. Connect one
+   * with `POST /v2/agents/{agentId}/channels`.
+   */
+  channels: Array<AgentChannelsItem>;
+}
+
+export interface AgentStats {
+  totalInvocations?: number;
+  totalTokensUsed?: number;
+  /** Total cost in USD. */
+  totalCost?: number;
+}
+
+export interface AgentChannelsItem {
+  address: string;
+  type: ChannelType;
+  active: boolean;
+}
+
+/** Create an agent that exists on its own, disabled and connected to no channel. */
+export interface AgentCreateStandaloneRequest {
+  name: string;
+  provider: AgentProvider;
+  /**
+   * Your key for the model provider. Required for `openai`, `anthropic`, `google`
+   * and `mistral`, where a request without it is refused with `400`; not used with
+   * `zavu`. Stored encrypted and never returned.
+   */
+  apiKey?: string;
+  model: string;
+  systemPrompt: string;
+  /** @defaultValue `10` */
+  contextWindowMessages?: number;
+  /** @defaultValue `true` */
+  includeContactMetadata?: boolean;
+  /** @defaultValue `["*"]` */
+  triggerOnChannels?: Array<string>;
+  /** @defaultValue `["text"]` */
+  triggerOnMessageTypes?: Array<string>;
+  maxTokens?: number;
+  temperature?: number;
+  voice?: AgentVoiceConfig;
+}
+
+/** LLM provider for the AI agent. */
+export type AgentProvider = 'openai' | 'anthropic' | 'google' | 'mistral' | 'zavu';
+
+/**
+ * Run the agent and return what it would say. Nothing is delivered to anyone and
+ * no execution is recorded.
+ *
+ * A run is **billed like a live reply**: on an agent with the `zavu` provider it
+ * is charged to your balance at the same price per token, and refused with `402
+ * insufficient_balance` at a balance of zero. On a bring-your-own-key agent it
+ * costs your provider, not Zavu. `cost` on the response is what this run charged.
+ */
+export interface AgentTestRequest {
+  /** What to say to the agent. */
+  message: string;
+  /**
+   * Prior turns, oldest first, to exercise multi-turn behaviour without persisting a
+   * thread. Trimmed to the agent's context window.
+   */
+  history?: Array<AgentTestRequestHistoryItem>;
+  /**
+   * Set false to skip retrieval and isolate prompt behaviour from the knowledge
+   * base.
+   *
+   * @defaultValue `true`
+   */
+  useKnowledgeBase?: boolean;
+  /**
+   * Run the tools the agent calls instead of reporting the choice and stopping.
+   *
+   * Off by default because a tool handler talks to the outside world: a rehearsal
+   * that charges a card is not a rehearsal. Turn it on to exercise the loop that
+   * actually matters — the model picks a tool, the handler answers, the model
+   * replies with the result — without sending a message to anyone. What ran comes
+   * back in `executedToolCalls`.
+   *
+   * @defaultValue `false`
+   */
+  executeTools?: boolean;
+}
+
+export interface AgentTestRequestHistoryItem {
+  role: AgentTestRequestHistoryItemRole;
+  content: string;
+}
+
+export type AgentTestRequestHistoryItemRole = 'user' | 'assistant';
+
+export interface AgentTestResponse {
+  success: boolean;
+  /** What the agent would reply. */
+  text: string | null;
+  error: string | null;
+  inputTokens: number;
+  outputTokens: number;
+  latencyMs: number;
+  /**
+   * Knowledge-base chunks retrieved for this message. Zero means the answer was not
+   * grounded in your documents.
+   */
+  knowledgeChunksUsed: number;
+  /**
+   * Tools that actually ran, in order, when the request set `executeTools`. Empty on
+   * a normal dry run, where nothing is executed. An entry with `ok: false` means the
+   * agent saw an error and answered around it, which is what a customer would have
+   * received.
+   */
+  executedToolCalls?: Array<AgentTestResponseExecutedToolCallsItem>;
+  /**
+   * Things that are true of this agent but that a dry run cannot prove. Surfaced so
+   * a passing dry run is never mistaken for proof that the agent works live.
+   *
+   * - The agent being disabled.
+   * - Enabled tools that were offered to the model but not run: if the agent picks
+   *   one, the reply stops at that choice (see `plannedToolCalls`). Pass
+   *   `executeTools` to run them.
+   * - Tools that ran for real, when `executeTools` was set, and any that failed.
+   * - An agent whose sender has none of the channels it triggers on, which answers
+   *   every dry run and no real message.
+   * - Contact metadata that exists on a real conversation but not here, and memory
+   *   tools (`remember`, `recall`, `save_record`), which have no contact to write
+   *   about on a test run.
+   */
+  warnings: Array<string>;
+  /**
+   * USD charged to your balance for this run, rounded to 6 decimals. 0 on a
+   * bring-your-own-key agent. When the balance covers only part of a run, that part
+   * is charged and the next run is refused with `402`.
+   */
+  cost: number;
+  /**
+   * Tools the model chose to call, with the arguments it chose, on a run without
+   * `executeTools`. Nothing was executed: the reply stops at the choice. Empty when
+   * it answered without reaching for a tool, and on a run that executed tools (see
+   * `executedToolCalls`).
+   */
+  plannedToolCalls: Array<AgentTestResponsePlannedToolCallsItem>;
+}
+
+export interface AgentTestResponseExecutedToolCallsItem {
+  name: string;
+  ok: boolean;
+  error?: string | null;
+}
+
+export interface AgentTestResponsePlannedToolCallsItem {
+  name: string;
+  /** The arguments as a JSON string. */
+  arguments: string;
+}
+
+export interface AgentUpdateRequest {
+  name?: string;
+  enabled?: boolean;
+  provider?: AgentProvider;
+  model?: string;
+  systemPrompt?: string;
+  apiKey?: string;
+  contextWindowMessages?: number;
+  includeContactMetadata?: boolean;
+  maxTokens?: number | null;
+  temperature?: number | null;
+  triggerOnChannels?: Array<string>;
+  triggerOnMessageTypes?: Array<string>;
+  /**
+   * Voice Agent configuration. Patch this object to enable voice, change the
+   * greeting, or adjust call limits. Requires the Voice Agents feature to be enabled
+   * for your team.
+   */
+  voice?: AgentVoiceConfig;
+}
+
+/**
+ * Voice Agent configuration on an AI agent. Controls how the agent behaves on
+ * inbound and outbound phone calls through Zavu's managed voice pipeline (speech
+ * recognition, the agent's LLM, and speech synthesis, with real-time interruption
+ * handling). Requires the Voice Agents feature to be enabled for your team.
+ */
+export interface AgentVoiceConfig {
+  /**
+   * Whether the agent handles voice calls. When false, the voice agent does not
+   * answer calls and outbound calls are rejected.
+   */
+  enabled: boolean;
+  /**
+   * Opening line the agent speaks when the call connects. If omitted, the agent
+   * waits for the caller to speak first.
+   */
+  greeting?: string;
+  /**
+   * Greeting per language, keyed by language code. Used when the caller's language
+   * differs from the one `greeting` is written in.
+   */
+  greetings?: { [key: string]: string };
+  /**
+   * BCP-47 language code used for both speech recognition and speech synthesis (e.g.
+   * `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
+   */
+  language?: string;
+  /**
+   * Model that runs the conversation, co-located in the voice network for lowest
+   * latency. Independent of the model used for text messaging. Derived from the
+   * agent's text model when omitted.
+   */
+  model?: string;
+  /** Speech-recognition provider. Uses the default when omitted. */
+  sttProvider?: string;
+  /** Speech-recognition model. Uses the default when omitted. */
+  sttModel?: string;
+  /** Speech-synthesis provider. Uses the default when omitted. */
+  ttsProvider?: string;
+  /**
+   * Identifier of the synthesized voice that speaks. Choose from the voices
+   * available in the dashboard. Uses a neutral default when omitted.
+   */
+  ttsVoiceId?: string;
+  /**
+   * Speech rate. 1.0 is natural. Only honoured by voices that support rate control;
+   * ignored by the others.
+   *
+   * @defaultValue `1.0`
+   */
+  voiceSpeed?: number;
+  /**
+   * Whether the caller can interrupt the agent while it is speaking (barge-in). When
+   * true, the agent stops talking as soon as the caller starts.
+   *
+   * @defaultValue `true`
+   */
+  interruptible?: boolean;
+  /**
+   * Hard limit on call length in minutes. The call ends automatically when reached.
+   *
+   * @defaultValue `15`
+   */
+  maxCallDurationMinutes?: number;
+  /**
+   * How long the agent waits during silence before ending the call.
+   *
+   * @defaultValue `30`
+   */
+  maxIdleSeconds?: number;
+  /** Whether the call audio is recorded. */
+  recordCalls?: boolean;
+  /**
+   * What the agent does when an answering machine or voicemail is detected on an
+   * outbound call.
+   *
+   * @defaultValue `"hangup"`
+   */
+  voicemailAction?: AgentVoiceConfigVoicemailAction;
+  /**
+   * Message spoken when `voicemailAction` is `leave_message`. Falls back to
+   * `greeting` when omitted.
+   */
+  voicemailMessage?: string;
+  /**
+   * E.164 phone number the agent can transfer the call to. When set, the agent is
+   * given a transfer tool it can use to hand the call to a human.
+   */
+  transferPhoneNumber?: string;
+}
+
+export type AgentVoiceConfigVoicemailAction = 'hangup' | 'leave_message';
+
+export interface AvailablePhoneNumber {
+  phoneNumber: string;
+  friendlyName?: string;
+  locality?: string;
+  region?: string;
+  capabilities: PhoneNumberCapabilities;
+  pricing: PhoneNumberPricing;
+}
+
+/**
+ * A campaign. The same object as a /v1 broadcast: its `id` works on
+ * `/v1/broadcasts/{broadcastId}`.
+ */
+export interface Broadcast {
+  id: string;
+  name: string;
+  status: BroadcastStatus;
+  channel: BroadcastChannel;
+  messageType: BroadcastMessageType;
+  text?: string;
+  content?: BroadcastContent;
+  emailSubject?: string;
+  /** Total number of contacts in the broadcast. */
+  totalContacts: number;
+  pendingCount?: number;
+  sendingCount?: number;
+  /**
+   * Recipients whose message the provider accepted, without a confirmed delivery
+   * yet. Channels that never report delivery keep their recipients here.
+   */
+  sentCount?: number;
+  /** Recipients with confirmed delivery to the device. */
+  deliveredCount?: number;
+  failedCount?: number;
+  /** Estimated total cost in USD. */
+  estimatedCost?: number | null;
+  /** Amount reserved from balance in USD. */
+  reservedAmount?: number | null;
+  /** Actual cost so far in USD. */
+  actualCost?: number | null;
+  scheduledAt?: string;
+  startedAt?: string;
+  completedAt?: string;
+  metadata?: { [key: string]: string };
+  createdAt: string;
+  updatedAt?: string;
+  /** AI content review result. */
+  reviewResult?: BroadcastReviewResult | null;
+  /** Number of review attempts (max 3). */
+  reviewAttempts?: number | null;
+  /**
+   * The address the campaign is sent from, for its `channel` (the sender's first
+   * address when `channel` is `smart`).
+   */
+  from?: string | null;
+}
+
+export interface BroadcastReviewResult {
+  /** Content safety score from 0.0 to 1.0, where 1.0 is completely safe. */
+  score?: number;
+  /** Policy categories violated, if any. */
+  categories?: Array<string>;
+  /** Explanation of the review decision. */
+  reasoning?: string;
+  reviewedAt?: string;
+  /** Problematic text fragments, if any. */
+  flaggedContent?: Array<string> | null;
+}
+
+/** Broadcast delivery channel. Use 'smart' for per-contact intelligent routing. */
+export type BroadcastChannel = 'smart' | 'sms' | 'sms_oneway' | 'whatsapp' | 'telegram' | 'email';
+
+export interface BroadcastContactInput {
+  /**
+   * Phone number (E.164) or email address. On a `telegram` broadcast, the numeric
+   * chat ID of someone who has already written to your bot (`838360395`, or
+   * `telegram:838360395`); a phone number is rejected there, because a bot cannot
+   * start a chat.
+   */
+  recipient: string;
+  /**
+   * Per-contact body variables. 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 };
+  /**
+   * Per-contact button variables for dynamic URL/OTP buttons. Keys are the button
+   * index (0, 1, 2).
+   */
+  templateButtonVariables?: { [key: string]: string };
+  /**
+   * Per-contact value for a text-header variable, keyed by `1`. If omitted, Zavu
+   * resolves the header from `templateVariables` by the header placeholder's name.
+   */
+  templateHeaderVariables?: { [key: string]: string };
+}
+
+export interface BroadcastContactsAddRequest {
+  /** List of contacts to add (max 1000 per request). */
+  contacts: Array<BroadcastContactInput>;
+}
+
+export interface BroadcastContactsAddResponse {
+  /** 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<BroadcastContactsAddResponseErrorsItem>;
+}
+
+export interface BroadcastContactsAddResponseErrorsItem {
+  recipient?: string;
+  /**
+   * Why it was not added, in words that are true of this recipient and this
+   * campaign.
+   */
+  reason?: string;
+  /**
+   * Set for `unreachable_by_channel` and `ten_dlc_required`. Absent on other
+   * reasons.
+   */
+  code?: BroadcastContactsAddResponseErrorsItemCode;
+}
+
+export type BroadcastContactsAddResponseErrorsItemCode = 'unreachable_by_channel' | 'ten_dlc_required';
+
+/** Content for non-text broadcast message types. */
+export interface BroadcastContent {
+  /** URL of the media file. */
+  mediaUrl?: string;
+  /** Media ID if already uploaded. */
+  mediaId?: string;
+  /** MIME type of the media. */
+  mimeType?: string;
+  /** Filename for documents. */
+  filename?: string;
+  /** Template ID for template messages. */
+  templateId?: string;
+  /**
+   * 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 };
+  /**
+   * 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 };
+  /**
+   * 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 };
+}
+
+/** A campaign is a /v1 broadcast. Create it, add recipients, then send. */
+export interface BroadcastCreateRequest {
+  /** Name of the broadcast campaign. */
+  name: string;
+  channel: BroadcastChannel;
+  /** @defaultValue `"text"` */
+  messageType?: BroadcastMessageType;
+  /** Text content or caption. Supports template variables: {{name}}, {{1}}, etc. */
+  text?: string;
+  content?: BroadcastContent;
+  /** Email subject line. Required for email broadcasts. */
+  emailSubject?: string;
+  /** HTML body for email broadcasts. */
+  emailHtmlBody?: string;
+  /** Schedule the broadcast for future delivery. */
+  scheduledAt?: string;
+  metadata?: { [key: string]: string };
+  /** Idempotency key to prevent duplicate broadcasts. */
+  idempotencyKey?: string;
+  /**
+   * The address that sends the campaign (`GET /v2/channels`). The project default
+   * when omitted. Resolved like `from` on `POST /v2/messages`, with the campaign's
+   * `channel` as the transport (none for `smart`).
+   */
+  from?: string;
+}
+
+/** Type of message for broadcast. */
+export type BroadcastMessageType = 'text' | 'image' | 'video' | 'audio' | 'document' | 'template';
+
+export interface BroadcastProgress {
+  status: BroadcastStatus;
+  /** Total contacts in broadcast. */
+  total: number;
+  /** Not yet queued for sending. */
+  pending: number;
+  /** Currently being sent. */
+  sending: number;
+  /** Accepted by the provider, delivery not confirmed yet. */
+  sent?: number;
+  /** Confirmed delivered to the device. */
+  delivered: number;
+  /** Failed to deliver. */
+  failed: number;
+  /** Skipped (broadcast cancelled). */
+  skipped: number;
+  /** Percentage complete (0-100). */
+  percentComplete: number;
+  /** Estimated total cost in USD. */
+  estimatedCost?: number | null;
+  /** Amount reserved from balance in USD. */
+  reservedAmount?: number | null;
+  /** Actual cost so far in USD. */
+  actualCost?: number | null;
+  startedAt?: string;
+  estimatedCompletionAt?: string;
+  campaignId: string;
+}
+
+export interface BroadcastSendRequest {
+  /** Schedule for future delivery. Omit to send immediately. */
+  scheduledAt?: string;
+}
+
+/**
+ * Current status of the campaign. `pending_review`: in the automated content
+ * review. `pending_admin_review`: the automated review passed and it waits for a
+ * person, which is where every channel but a WhatsApp campaign on an approved
+ * template goes. `rejected`: the review refused it; edit it and send again, or
+ * escalate. `scheduled` and `sending` follow approval.
+ */
+export type BroadcastStatus =
+  | 'draft'
+  | 'pending_review'
+  | 'pending_admin_review'
+  | 'approved'
+  | 'rejected'
+  | 'escalated'
+  | 'rejected_final'
+  | 'scheduled'
+  | 'sending'
+  | 'paused'
+  | 'completed'
+  | 'cancelled'
+  | 'failed';
+
+/** A transport a message travels on. */
+export type ChannelType =
+  | 'sms'
+  | 'sms_oneway'
+  | 'whatsapp'
+  | 'telegram'
+  | 'email'
+  | 'instagram'
+  | 'messenger'
+  | 'voice';
+
+/**
+ * `auto`, or a transport. `auto` applies the fixed order described on `POST
+ * /v2/messages`.
+ */
+export type ChannelTypeRequest =
+  | 'auto'
+  | 'sms'
+  | 'sms_oneway'
+  | 'whatsapp'
+  | 'telegram'
+  | 'email'
+  | 'instagram'
+  | 'messenger'
+  | 'voice';
+
+export interface Contact {
+  id: string;
+  /** Display name for the contact. */
+  displayName?: string;
+  /** DEPRECATED: Use primaryPhone instead. Primary phone number in E.164 format. */
+  phoneNumber?: string;
+  /** Primary phone number in E.164 format. */
+  primaryPhone?: string;
+  /** Primary email address. */
+  primaryEmail?: string;
+  countryCode?: string;
+  /** Contact's WhatsApp profile name. Only available for WhatsApp contacts. */
+  profileName?: string | null;
+  /** List of available messaging channels for this contact. */
+  availableChannels: Array<string>;
+  /** Preferred channel for this contact. */
+  defaultChannel?: ContactDefaultChannel;
+  /** Whether this contact has been verified. */
+  verified: boolean;
+  /** All communication channels for this contact. */
+  channels?: Array<ContactChannel>;
+  metadata: { [key: string]: string };
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export type ContactDefaultChannel =
+  | 'sms'
+  | 'whatsapp'
+  | 'telegram'
+  | 'email'
+  | 'instagram'
+  | 'messenger'
+  | 'voice';
+
+/** A communication channel for a contact. */
+export interface ContactChannel {
+  id: string;
+  /** Channel type. */
+  channel: ContactChannelChannel;
+  /** Channel identifier (phone number or email address). */
+  identifier: string;
+  /** ISO country code for phone numbers. */
+  countryCode?: string;
+  /** Optional label for the channel. */
+  label?: string;
+  /** Whether this is the primary channel for its type. */
+  isPrimary: boolean;
+  /** Whether this channel has been verified. */
+  verified: boolean;
+  /** Delivery metrics for this channel. */
+  metrics?: ContactChannelMetrics;
+  /** Last time a message was received on this channel. */
+  lastInboundAt?: string;
+  metadata?: { [key: string]: string };
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export type ContactChannelChannel =
+  | 'sms'
+  | 'whatsapp'
+  | 'email'
+  | 'telegram'
+  | 'instagram'
+  | 'messenger'
+  | 'voice';
+
+export interface ContactChannelMetrics {
+  successCount?: number;
+  failureCount?: number;
+  totalAttempts?: number;
+  avgDeliveryTimeMs?: number;
+  lastSuccessAt?: string;
+}
+
+/** Input for creating a contact channel. */
+export interface ContactChannelInput {
+  /** Channel type. */
+  channel: ContactChannelInputChannel;
+  /** Channel identifier (phone number in E.164 format or email address). */
+  identifier: string;
+  /** ISO country code for phone numbers. */
+  countryCode?: string;
+  /** Optional label for the channel. */
+  label?: string;
+  /**
+   * Whether this should be the primary channel for its type.
+   *
+   * @defaultValue `false`
+   */
+  isPrimary?: boolean;
+}
+
+export type ContactChannelInputChannel =
+  | 'sms'
+  | 'whatsapp'
+  | 'email'
+  | 'telegram'
+  | 'instagram'
+  | 'messenger'
+  | 'voice';
+
+/** Request body to create a contact with channels. */
+export interface ContactCreateRequest {
+  /** Display name for the contact. */
+  displayName?: string;
+  /** Communication channels for the contact. */
+  channels: Array<ContactChannelInput>;
+  /** Arbitrary metadata to associate with the contact. */
+  metadata?: { [key: string]: string };
+}
+
+export interface ContactUpdateRequest {
+  /**
+   * Human-readable name for this contact. Set to null to clear it and fall back to
+   * the contact's identifier. Contacts created automatically from an inbound message
+   * have no display name until you set one.
+   */
+  displayName?: string | null;
+  /** Preferred channel for this contact. Set to null to clear. */
+  defaultChannel?: ContactUpdateRequestDefaultChannel | null;
+  metadata?: { [key: string]: string };
+}
+
+export type ContactUpdateRequestDefaultChannel =
+  | 'sms'
+  | 'whatsapp'
+  | 'telegram'
+  | 'email'
+  | 'instagram'
+  | 'messenger'
+  | 'voice';
+
+/**
+ * An inbox thread with one contact. A conversation groups every message exchanged
+ * with that contact across channels, so a contact who writes on WhatsApp and later
+ * by email stays in one thread.
+ */
+export interface Conversation {
+  id: string;
+  /**
+   * ID of the contact this thread belongs to. Absent on group threads and on threads
+   * whose contact has not been resolved yet.
+   */
+  contactId?: string;
+  /**
+   * The key this thread is filed under: a phone number in E.164, a WhatsApp
+   * business-scoped user ID (BSUID), or a numeric chat ID
+   * (Telegram/Instagram/Messenger). It is not always a phone number, so do not parse
+   * it as one.
+   */
+  contactIdentifier: string;
+  /** Email address of the thread, when the contact was reached by email. */
+  email?: string;
+  /** Every channel this thread has carried messages on. */
+  channels: Array<string>;
+  /**
+   * Denormalized preview of the most recent message, so a thread list needs no extra
+   * fetch.
+   */
+  lastMessage: ConversationLastMessage;
+  messageCount: number;
+  /**
+   * Inbound messages not yet marked read. Reset with POST
+   * /v2/conversations/{conversationId}/read.
+   */
+  unreadCount: number;
+  /** WhatsApp identity, present when the contact adopted a username. */
+  whatsapp?: ConversationWhatsapp;
+  createdAt: string;
+  updatedAt: string;
+  /**
+   * The address this thread was last handled from, on the transport of its last
+   * message. Pass the conversation's `id` as `conversationId` on `POST /v2/messages`
+   * to reply from it. A thread opened by an API send before /v2 recorded no sender;
+   * its `from` is read off its messages. `?from=` on the list matches threads by the
+   * recorded sender only, which messages sent through /v2 record.
+   */
+  from?: string | null;
+}
+
+export interface ConversationLastMessage {
+  id: string;
+  /** Text or caption. Empty when the last message carried no text (e.g. media). */
+  text: string;
+  channel: ChannelType;
+  direction: ConversationLastMessageDirection;
+  at: string;
+}
+
+export type ConversationLastMessageDirection = 'inbound' | 'outbound';
+
+export interface ConversationWhatsapp {
+  /** Business-scoped user ID. Can be used as `to` when sending. */
+  bsuid?: string;
+  username?: string;
+}
+
+/** Email attachment. Provide either `content` (base64) or `path` (URL), not both. */
+export interface EmailAttachmentInput {
+  /** Name of the attached file. */
+  filename: string;
+  /** Content of the attached file as a Base64-encoded string. */
+  content?: string;
+  /** URL where the attachment file is hosted. The server will fetch the file. */
+  path?: string;
+  /** MIME type of the attachment. If not set, will be derived from the filename. */
+  content_type?: string;
+  /**
+   * Content ID for inline images. Reference in HTML as `<img
+   * src="cid:your_content_id">`.
+   */
+  content_id?: string;
+}
+
+/**
+ * Every v2 error has this shape at the root. There is no `{error: {...}}` wrapper
+ * anywhere in v2. A missing resource is `404 not_found` with the message
+ * `<Resource> not found`; an address the project does not have is `404 not_found`,
+ * `None of this project's channels has the address <address>.`, with the address
+ * in `details` under the name the request used (`from` or `address`). A `message`
+ * is written for the caller and never carries a stack trace or a source path. A
+ * body that is not JSON is `400 invalid_json`, with `details.errors` (`path: []`,
+ * the parse error in `message`).
+ */
+export interface ErrorBody {
+  code: string;
+  message: string;
+  /**
+   * Machine-readable context. Keys that mean the same thing everywhere:
+   * - `errors`: present on every `400 invalid_request` for an invalid body or query
+   *   parameter, `[{path, message, ...}]`, `path` naming the field (`["to"]`,
+   *   `["contacts", 2, "recipient"]`, `["limit"]`).
+   * - `recommendation`: one sentence saying what to do next.
+   * - `dashboardUrl`: the dashboard screen that fixes it.
+   * - `connect`: on `409 no_channel`, the channels this project can connect to reach
+   *   the recipient, each `{type, request, note, available, dashboardUrl?}`;
+   *   `request` is the exact call (`POST /v2/channels` with its body, or `POST
+   *   /v2/numbers`), or null for a channel connected from the dashboard (WhatsApp,
+   *   Instagram, Messenger). `available: false` says why in `note` (one-way SMS
+   *   closed until business verification is approved).
+   * - `address` / `from`: the address the error is about, under the name the request
+   *   used for it.
+   */
+  details?: ErrorDetails;
+}
+
+export interface ErrorDetails {
+  errors?: Array<ErrorDetailsErrorsItem>;
+  [key: string]: unknown;
+}
+
+export interface ErrorDetailsErrorsItem {
+  path: Array<ErrorDetailsErrorsItemPathItem>;
+  message: string;
+  code?: string;
+  [key: string]: unknown;
+}
+
+export type ErrorDetailsErrorsItemPathItem = string | number;
+
+export interface Message {
+  id: string;
+  to: string;
+  /**
+   * Where the message came from: for an outbound message, your address (as `GET
+   * /v2/channels` lists it for `channel`, except WhatsApp, where it is the sender's
+   * own number field); for an inbound one, the contact.
+   */
+  from?: string;
+  channel: ChannelType;
+  /**
+   * 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: MessageDirection;
+  messageType: MessageType;
+  status: MessageStatus;
+  /** Text content or caption. */
+  text?: string;
+  content?: MessageContent;
+  /**
+   * ID of the conversation (inbox thread) this message belongs to. Use it to build a
+   * direct dashboard link:
+   * `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. Omitted only
+   * on legacy messages created before conversation threading.
+   */
+  conversationId?: string;
+  /** Message ID from the delivery provider. */
+  providerMessageId?: string;
+  /**
+   * Why a failed message failed, as a Zavu code: `RISK_REJECTED`,
+   * `DAILY_LIMIT_EXCEEDED`, `TEN_DLC_REQUIRED`, `SMS_NOT_DELIVERED`,
+   * `WHATSAPP_WINDOW_CLOSED`... A delivery provider's own code is translated where
+   * its meaning is known and kept in `errorDetails.providerCode`; one with no known
+   * meaning is `SMS_DELIVERY_FAILED`, `WHATSAPP_REJECTED`, `VOICE_DELIVERY_FAILED`,
+   * `EMAIL_DELIVERY_FAILED` or `DELIVERY_FAILED`. (/v1 returns the provider's raw
+   * code here.)
+   */
+  errorCode?: string | null;
+  errorMessage?: string | null;
+  /**
+   * Zavu's own per-message platform charge, in USD (6 decimals). Messaging is billed
+   * against the plan's allowance, so it is often 0.
+   */
+  cost?: number | null;
+  /**
+   * What delivering the message cost Zavu (carrier cost), in USD. Filled in when the
+   * delivery report brings it, so null until then.
+   */
+  costProvider?: number | null;
+  /**
+   * `cost` + `costProvider`. For SMS this is BEFORE Zavu's markup, so it is not what
+   * your balance was charged: read `charged` for that. For voice it includes the
+   * markup.
+   */
+  costTotal?: number | null;
+  metadata?: { [key: string]: string };
+  createdAt: string;
+  updatedAt?: string;
+  /**
+   * Transports tried before the current `channel`, oldest first, when an automatic
+   * fallback moved the message (WhatsApp to SMS). Empty when no fallback happened.
+   * Fallback runs after the send returned, so this can change after `POST
+   * /v2/messages` answered.
+   */
+  attemptedChannels?: Array<ChannelType>;
+  /**
+   * `held` while the message waits for risk review (it stays `queued`), `released`
+   * once a reviewer let it go, null when it was never held.
+   */
+  riskHold?: MessageRiskHold | null;
+  /** Present when `errorCode` translates a delivery provider's code. */
+  errorDetails?: MessageErrorDetails | null;
+  /**
+   * What this message has taken from your prepaid balance, in USD. SMS and one-way
+   * SMS only: charged per segment when the message is accepted
+   * (`routing.estimatedCost`), raised if the delivery report brings a higher real
+   * cost, and refunded (0) when the message fails AND the carrier charged nothing. A
+   * failed SMS the carrier did charge for (it attempted delivery) stays charged.
+   * Null on other channels, which are not billed per message here.
+   */
+  charged?: number | null;
+}
+
+export type MessageDirection = 'inbound' | 'outbound';
+
+export type MessageRiskHold = 'held' | 'released';
+
+export interface MessageErrorDetails {
+  /** The provider's own code, unchanged. */
+  providerCode?: string;
+}
+
+/** Content for non-text message types (WhatsApp and Telegram). */
+export interface MessageContent {
+  /** URL of the media file (for image, video, audio, document, sticker). */
+  mediaUrl?: string;
+  /** WhatsApp media ID if already uploaded. */
+  mediaId?: string;
+  /** MIME type of the media. */
+  mimeType?: string;
+  /** Filename for documents. */
+  filename?: string;
+  /** Latitude for location messages. */
+  latitude?: number;
+  /** Longitude for location messages. */
+  longitude?: number;
+  /** Name of the location. */
+  locationName?: string;
+  /** Address of the location. */
+  locationAddress?: string;
+  /** Contact cards for contact messages. */
+  contacts?: Array<MessageContentContactsItem>;
+  /** Interactive buttons (max 3). */
+  buttons?: Array<MessageContentButtonsItem>;
+  /** Button text for list messages. */
+  listButton?: string;
+  /** Sections for list messages. */
+  sections?: Array<MessageContentSectionsItem>;
+  /** Button label for cta_url messages. */
+  ctaDisplayText?: string;
+  /**
+   * Destination URL opened in the device's default browser when the button is
+   * tapped. Used with messageType=cta_url. WhatsApp requires HTTPS in production.
+   */
+  ctaUrl?: string;
+  /** Optional header type for cta_url messages. */
+  ctaHeaderType?: MessageContentCtaHeaderType;
+  /** Header text when ctaHeaderType is 'text'. */
+  ctaHeaderText?: string;
+  /**
+   * Public HTTPS URL of the header media when ctaHeaderType is 'image', 'video', or
+   * 'document'. WhatsApp fetches this URL — it must be publicly reachable and
+   * return the declared content type.
+   */
+  ctaHeaderMediaUrl?: string;
+  /** Optional footer text for cta_url messages. */
+  footerText?: string;
+  /** Emoji for reaction messages. */
+  emoji?: string;
+  /** Message ID to react to. */
+  reactToMessageId?: string;
+  /**
+   * Zavu message ID of the quoted message this message replies to. Present on
+   * inbound messages that quote an earlier message. Omitted when the quoted message
+   * is not found in Zavu (e.g. an old or unknown message) — use
+   * replyToProviderMessageId in that case.
+   */
+  replyToMessageId?: string;
+  /**
+   * Provider message ID (WhatsApp WAMID) of the quoted message. Present whenever an
+   * inbound message is a reply, even if the quoted message is not stored in Zavu.
+   */
+  replyToProviderMessageId?: string;
+  /** Sender of the quoted message (phone number in E.164 format). */
+  replyToFrom?: string;
+  /**
+   * Truncated snippet of the quoted message's text, for display. Empty when the
+   * quoted message has no text (e.g. media).
+   */
+  replyToText?: string;
+  /** Type of the quoted message (text, image, video, etc.). */
+  replyToMessageType?: string;
+  /** Template ID for template messages. */
+  templateId?: string;
+  /**
+   * Variables for body placeholders. 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. Named keys also resolve a named text-header
+   * variable. Do not mix positional and named keys in the same request.
+   */
+  templateVariables?: { [key: string]: string };
+  /**
+   * Variables for dynamic button placeholders (URL buttons and OTP buttons). Keys
+   * are the button index (0, 1, 2) in the template's `buttons` array — not the
+   * placeholder name. Values substitute the `{{1}}` placeholder inside that button's
+   * URL.
+   *
+   * **WhatsApp constraints:**
+   * - URL buttons only accept `{{1}}` — positional, numeric, no whitespace, no
+   *   name. Named placeholders like `{{token}}` are stored as literal URL text by
+   *   Meta and cannot be substituted.
+   * - At most one placeholder per URL button.
+   * - A template may have at most three buttons.
+   * - Static URL buttons (no placeholder) and `quick_reply` buttons are not included
+   *   here.
+   */
+  templateButtonVariables?: { [key: string]: string };
+  /**
+   * Value for a text-header variable, keyed by `1` (WhatsApp text headers allow at
+   * most one variable). Optional override. If omitted, Zavu resolves the header from
+   * `templateVariables` using the header placeholder's name (e.g. `novios`). Static
+   * text headers need no value.
+   */
+  templateHeaderVariables?: { [key: string]: string };
+  referral?: AdReferral;
+}
+
+export interface MessageContentContactsItem {
+  name?: string;
+  phones?: Array<string>;
+}
+
+export interface MessageContentButtonsItem {
+  id: string;
+  title: string;
+}
+
+export interface MessageContentSectionsItem {
+  title: string;
+  rows: Array<MessageContentSectionsItemRowsItem>;
+}
+
+export interface MessageContentSectionsItemRowsItem {
+  id: string;
+  title: string;
+  description?: string;
+}
+
+export type MessageContentCtaHeaderType = 'text' | 'image' | 'video' | 'document';
+
+export type MessageStatus =
+  | 'queued'
+  | 'sending'
+  | 'sent'
+  | 'delivered'
+  | 'read'
+  | 'failed'
+  | 'received'
+  | 'pending_url_verification';
+
+/**
+ * Type of message. Every type except `text` and `template` is sent on WhatsApp
+ * only: the send routes them there whatever `channel` says, and in v2 an explicit
+ * `channel` other than `whatsapp` is refused with `400` naming `messageType` and
+ * `channel`.
+ *
+ * `location_request` asks the recipient to share their location and is
+ * WhatsApp-only. It takes no `content` object — the prompt goes in `text` (max
+ * 1024 characters) and the button label is fixed by WhatsApp. The recipient's
+ * answer arrives as an inbound `location` message whose `content.replyToMessageId`
+ * is the ID of the request.
+ *
+ * `request_contact_info` asks the recipient to share their phone number and is
+ * WhatsApp-only. Like `location_request` it takes no `content` object — the
+ * prompt goes in `text` (max 1024 characters) and WhatsApp renders a fixed **Share
+ * Contact Info** button. The answer arrives as an inbound `contact` message. Use
+ * it to recover the phone number of a contact who adopted a WhatsApp username and
+ * is only known by their business-scoped user ID (BSUID); when they share it, Zavu
+ * automatically links the phone number to that contact.
+ */
+export type MessageType =
+  | 'text'
+  | 'image'
+  | 'video'
+  | 'audio'
+  | 'document'
+  | 'sticker'
+  | 'location'
+  | 'contact'
+  | 'buttons'
+  | 'list'
+  | 'cta_url'
+  | 'request_contact_info'
+  | 'location_request'
+  | 'reaction'
+  | 'template';
+
+export interface OwnedPhoneNumber {
+  id: string;
+  phoneNumber: string;
+  /** Optional custom name for the phone number. */
+  name?: string;
+  capabilities: Array<string>;
+  status: PhoneNumberStatus;
+  pricing: OwnedPhoneNumberPricing;
+  /**
+   * Regulatory review state. Numbers that need no review are `approved` immediately.
+   * A number bought with regulatory information is owned and billed from purchase
+   * and starts `pending_review`; it cannot send messages or place calls until this
+   * is `approved`, and its `channels` entry can be absent until then. The state is
+   * re-checked every 6 hours.
+   */
+  regulatoryStatus: OwnedPhoneNumberRegulatoryStatus;
+  nextRenewalDate?: string;
+  createdAt: string;
+  updatedAt?: string;
+}
+
+export type OwnedPhoneNumberRegulatoryStatus = 'approved' | 'pending_review' | 'rejected';
+
+export interface OwnedPhoneNumberPricing {
+  /** Monthly price in USD. */
+  monthlyPrice?: number;
+  /** One-time purchase cost in cents. */
+  upfrontCost?: number;
+  /** Monthly cost in cents. */
+  monthlyCost?: number;
+  /** Whether this is a free number. */
+  isFreeNumber?: boolean;
+}
+
+export interface PhoneNumberCapabilities {
+  sms?: boolean;
+  voice?: boolean;
+  mms?: boolean;
+}
+
+export interface PhoneNumberPricing {
+  /** Monthly price in USD. */
+  monthlyPrice?: number;
+  /** One-time purchase price in USD. */
+  upfrontPrice?: number;
+  /**
+   * Whether this number qualifies as the plan-included number: a US or Canadian
+   * number (a +1 number) costing $20 a month or less. The benefit is one per
+   * account: it is never offered again once claimed, not even after the number is
+   * released.
+   */
+  isFreeEligible?: boolean;
+}
+
+export interface PhoneNumberPurchaseRequest {
+  /** Phone number in E.164 format. */
+  phoneNumber: string;
+  /** Optional custom name for the phone number. */
+  name?: string;
+  /**
+   * Type the number was found under in `GET /v2/numbers/available`. Used to look the
+   * number up and to keep regulatory information for reuse. Required when
+   * `regulatoryRequirements` is sent. `toll_free` is accepted as an alias of
+   * `tollFree`. A number not listed under this type is refused with `400
+   * number_unavailable` saying so.
+   */
+  type?: PhoneNumberType;
+  /**
+   * Regulatory information, for numbers whose requirements list is not empty. Get
+   * the list with `GET /v1/phone-numbers/requirements?phoneNumber=...` and send one
+   * entry per requirement id, except `action` requirements, which take no value.
+   * Every required id must be present, once, and no unknown id may be sent;
+   * otherwise the purchase is refused with `400 invalid_request` before anything is
+   * charged.
+   *
+   * The information is kept for your project under the number's country and `type`.
+   * A later purchase there may omit this field if what is kept still covers that
+   * number's requirements. Omit it for numbers without requirements.
+   */
+  regulatoryRequirements?: Array<PhoneNumberPurchaseRequestRegulatoryRequirementsItem>;
+}
+
+export interface PhoneNumberPurchaseRequestRegulatoryRequirementsItem {
+  /**
+   * A `requirementTypes[].id` from `GET /v1/phone-numbers/requirements`. Each id may
+   * appear only once.
+   */
+  requirementType: string;
+  /**
+   * Depends on the requirement's `type`: the text itself for `textual`; for
+   * `address`, the `id` of an address created in this project with `POST
+   * /v1/addresses`; for `document`, the `id` of a document created with `POST
+   * /v1/documents`. An address or document from another project, or one rejected in
+   * review, is refused.
+   */
+  fieldValue: string;
+}
+
+/**
+ * Billing state of an owned number, separate from `regulatoryStatus`. `pending` is
+ * legacy and is not written to numbers today.
+ */
+export type PhoneNumberStatus = 'active' | 'suspended' | 'pending' | 'releasing' | 'released';
+
+/**
+ * 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';
+
+/**
+ * The one webhook for everything in the project. Stored apart from the /v1 project
+ * webhook (`/v1/invitations/webhook`); neither API reads or writes the other's.
+ */
+export interface ProjectWebhookV2 {
+  url: string;
+  /**
+   * Any event in `WebhookEvent`, including `message.*`, `conversation.new` and
+   * `call.*`.
+   */
+  events: Array<WebhookEvent>;
+  active: boolean;
+  signatureVersion: WebhookSignatureVersion;
+  /**
+   * Returned only by `PUT /v2/webhook` when it creates the webhook, and by `POST
+   * /v2/webhook/secret`.
+   */
+  secret?: string;
+}
+
+export interface ProjectWebhookV2Put {
+  /** HTTPS only. */
+  url: string;
+  /**
+   * Any event in `WebhookEvent`. An unknown value is refused with `400` and
+   * `details.allowed`.
+   */
+  events: Array<WebhookEvent>;
+  /** @defaultValue `true` */
+  active?: boolean;
+  signatureVersion?: WebhookSignatureVersion;
+  /**
+   * Switch off the /v1 sender webhooks of this project in the same call, so each
+   * event arrives once. They are only switched off (`webhookActive: false` on /v1);
+   * URL, events and secret stay, so /v1 can turn one back on. Off by default: the
+   * /v2 webhook is added next to them and both receive every event until you decide.
+   * `senderWebhooks` on the response lists what is still on.
+   *
+   * @defaultValue `false`
+   */
+  disableSenderWebhooks?: boolean;
+}
+
+/**
+ * What the engine decided at send time. Reports only decisions the engine makes;
+ * it does not rank channels by price or by WhatsApp window state.
+ */
+export interface Routing {
+  channel: ChannelType;
+  /**
+   * The address the message leaves from, as `GET /v2/channels` lists it for
+   * `channel`. With a test-mode key, the WhatsApp sandbox number.
+   */
+  from: string;
+  /**
+   * Why this transport was chosen. Closed list:
+   * - `explicit`: `channel` was given.
+   * - `auto_order`: `channel` omitted or `auto`; the first ACTIVE transport of the
+   *   sender in a fixed order (for a phone number: WhatsApp, then SMS, then one-way
+   *   SMS). A connected transport that is switched off is skipped, not chosen and
+   *   then refused. It does not compare price and does not check the WhatsApp
+   *   24-hour window; a closed window fails later as `message.failed`.
+   * - `conversation`: the sender came from `conversationId` (the sender, not the
+   *   transport; the transport is then chosen as for `auto_order` unless `channel`
+   *   is given).
+   * - `recipient_type`: `to` is an email address, so email.
+   * - `message_type`: `messageType` is WhatsApp-only (media, interactive,
+   *   template...), so WhatsApp.
+   * - `sandbox`: test-mode key, which always uses the WhatsApp sandbox.
+   * An automatic fallback is never a send-time reason: it happens later, see
+   * `Message.attemptedChannels`.
+   */
+  reason: RoutingReason;
+  /**
+   * USD this call took from the balance when it was accepted (rounded to 6
+   * decimals). An estimate: for SMS the delivery report can raise it to the real
+   * cost, and `message.charged` shows where it ended up. Present for `sms` and
+   * `sms_oneway`. Null otherwise — WhatsApp is billed by Meta, email in
+   * 1,000-message blocks, voice per minute — and also null while a message waits
+   * for URL verification, which is charged when it is released. Null means "not
+   * known at send time", not "free".
+   */
+  estimatedCost: number | null;
+}
+
+export type RoutingReason =
+  | 'explicit'
+  | 'auto_order'
+  | 'conversation'
+  | 'recipient_type'
+  | 'message_type'
+  | 'sandbox';
+
+/**
+ * Request body to send a message. No `Zavu-Sender` header: where it leaves from
+ * comes from `conversationId`, then `from`, then the project default. `to` is
+ * required, except with `conversationId`, where it defaults to whoever the
+ * conversation is with.
+ */
+export interface SendMessageRequest {
+  /**
+   * Recipient phone number in E.164 format, email address, WhatsApp business-scoped
+   * user ID (BSUID, e.g. `US.13491208655302741918`), or numeric chat ID (for
+   * Telegram/Instagram/Messenger). A phone number written with spaces, dashes, dots
+   * or parentheses after its `+` (`+56 9 1234 5678`) is read as the E.164 number;
+   * bare digits are not (see `400` on this operation). A BSUID is routed to WhatsApp
+   * and sent via the `recipient` field; use it to message a contact who adopted a
+   * username and whose phone number is hidden.
+   *
+   * Required unless `conversationId` is given. With `conversationId` it may be
+   * omitted (it is the conversation's contact: its email for `channel: "email"`,
+   * else the identifier it is filed under); if given it must be one of that
+   * conversation's identifiers (its key, email or BSUID, in any formatting), else
+   * `400` naming `to` and `conversationId`.
+   */
+  to?: string;
+  channel?: ChannelTypeRequest;
+  /**
+   * Type of message. Defaults to 'text'.
+   *
+   * @defaultValue `"text"`
+   */
+  messageType?: MessageType;
+  /** Text body for text messages or caption for media messages. */
+  text?: string;
+  /** Additional content for non-text message types. */
+  content?: MessageContent;
+  /**
+   * Email subject line. Required when channel is 'email' or recipient is an email
+   * address.
+   */
+  subject?: string;
+  /**
+   * HTML body for email messages. If provided, email will be sent as multipart with
+   * both text and HTML.
+   */
+  htmlBody?: string;
+  /** Reply-To email address for email messages. */
+  replyTo?: string;
+  /** Optional idempotency key to avoid duplicate sends. */
+  idempotencyKey?: string;
+  /** Arbitrary metadata to associate with the message. */
+  metadata?: { [key: string]: string };
+  /**
+   * Whether to enable automatic fallback to SMS if WhatsApp fails. Defaults to true.
+   *
+   * @defaultValue `true`
+   */
+  fallbackEnabled?: boolean;
+  /**
+   * Language code for voice text-to-speech (e.g., 'en-US', 'es-ES', 'pt-BR'). If
+   * omitted, language is auto-detected from recipient's country code.
+   */
+  voiceLanguage?: string;
+  /**
+   * Email attachments. Only supported when channel is 'email'. Maximum 40MB total
+   * size.
+   */
+  attachments?: Array<EmailAttachmentInput>;
+  /**
+   * Which of your addresses sends (see `GET /v2/channels`): an E.164 number in any
+   * common formatting, an email address, `@botname`, `@username`, a Page id.
+   * Resolved inside your project only. Omitted: the project default, the same one
+   * /v1 uses when no `Zavu-Sender` header is sent. Ignored when `conversationId` is
+   * set, and with a test-mode key, which always sends from the WhatsApp sandbox.
+   *
+   * An address that no entry has returns `404 not_found`. An address two of your
+   * senders share (a number whose WhatsApp was connected on one sender and SMS on
+   * another) resolves when `channel` names the transport; otherwise it returns `409
+   * ambiguous_from` with `details.candidates[{address, type, v1SenderId}]`, and in
+   * that case, and only then, `from` also accepts one of those `v1SenderId` values.
+   */
+  from?: string;
+  /**
+   * Reply inside an existing conversation: the message leaves from the sender that
+   * last handled it (`from` on the Conversation), and goes to whoever the
+   * conversation is with, so `to` may be omitted. A `to` that is not the
+   * conversation's contact is refused with `400` (`details.errors` on `to` and
+   * `conversationId`, `details.conversationTo`) instead of silently opening another
+   * conversation. Takes precedence over `from`. When `channel` is omitted,
+   * `routing.reason` is then `conversation`. A conversation of another project
+   * returns `404`; one with no sender recorded returns `409 no_channel`. The 202's
+   * `message.conversationId` is set whenever the conversation the message is filed
+   * in already exists; it is absent only for a recipient's first message, whose
+   * conversation is created after the response. A reply to a conversation that an
+   * inbound email opened reaches the right person but is filed in a separate
+   * conversation keyed by the email address.
+   */
+  conversationId?: string;
+}
+
+export interface SendMessageResponse {
+  message: Message;
+  routing: Routing;
+}
+
+export interface Template {
+  id: string;
+  /** Template name. For WhatsApp, must match the approved template name in Meta. */
+  name: string;
+  /** Language code. */
+  language: string;
+  /**
+   * Default template body with variables: positional ({{1}}, {{2}}) or named
+   * ({{customer_name}}, {{contact.first_name}}). Templates created in Zavu are
+   * submitted to Meta as positional; templates imported from a WhatsApp Business
+   * Account keep their original format (named or positional). Used when no
+   * channel-specific body is set.
+   */
+  body: string;
+  /** Channel-specific body for SMS messages. Falls back to `body` if not set. */
+  smsBody?: string;
+  /** Channel-specific body for Telegram messages. Falls back to `body` if not set. */
+  telegramBody?: string;
+  /** Channel-specific body for Instagram messages. Falls back to `body` if not set. */
+  instagramBody?: string;
+  /**
+   * The category the template is billed under. For a template linked to WhatsApp
+   * this is the category **Meta currently assigns**, not the one it was submitted
+   * with: Meta can recategorize a template at approval or at any point afterwards,
+   * and that changes what the message costs.
+   *
+   * A recategorization reaches this field through the `template.status_changed`
+   * webhook, which carries `data.category`, and through `POST /v1/templates/sync`,
+   * which reconciles it against Meta. Read one of those rather than assuming the
+   * category you sent is the one in force.
+   *
+   * For a template that was never submitted to WhatsApp, this is the category stored
+   * locally, defaulting to `UTILITY`.
+   */
+  category: WhatsAppCategory;
+  /** @defaultValue `"draft"` */
+  status?: TemplateStatus;
+  /** List of variable names for documentation. */
+  variables?: Array<string>;
+  /** Type of header (text, image, video, document). */
+  headerType?: string;
+  /** Header content (text or media URL). */
+  headerContent?: string;
+  /** Footer text for the template. */
+  footer?: string;
+  /** Template buttons. */
+  buttons?: Array<TemplateButtonsItem>;
+  /** Add 'Do not share this code' disclaimer. Only for AUTHENTICATION templates. */
+  addSecurityRecommendation?: boolean;
+  /** Code expiration time in minutes. Only for AUTHENTICATION templates. */
+  codeExpirationMinutes?: number;
+  /** WhatsApp-specific template information. */
+  whatsapp?: TemplateWhatsapp;
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+export type TemplateStatus = 'draft' | 'pending' | 'approved' | 'rejected';
+
+export interface TemplateButtonsItem {
+  type?: TemplateButtonsItemType;
+  text?: string;
+  url?: string;
+  /**
+   * Sample value used to substitute `{{1}}` in the URL when submitting the template
+   * to Meta for review. Only present for dynamic URL buttons.
+   */
+  example?: string;
+  phoneNumber?: string;
+  /** OTP button type. Required when type is 'otp'. */
+  otpType?: TemplateButtonsItemOtpType;
+  /** Android package name. Required for ONE_TAP buttons. */
+  packageName?: string;
+  /** Android app signature hash. Required for ONE_TAP buttons. */
+  signatureHash?: string;
+}
+
+export type TemplateButtonsItemType = 'quick_reply' | 'url' | 'phone' | 'otp' | 'request_contact_info';
+
+export type TemplateButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
+
+export interface TemplateWhatsapp {
+  /** WhatsApp template name. */
+  templateName?: string;
+  /** WhatsApp Business Account namespace. */
+  namespace?: string;
+  /** WhatsApp approval status. */
+  status?: string;
+}
+
+export interface TemplateCreateRequest {
+  name: string;
+  /** @defaultValue `"en"` */
+  language: string;
+  /** Default template body. Used when no channel-specific body is set. */
+  body: string;
+  /** Channel-specific body for SMS. Falls back to `body` if not set. */
+  smsBody?: string;
+  /** Channel-specific body for Telegram. Falls back to `body` if not set. */
+  telegramBody?: string;
+  /** Channel-specific body for Instagram. Falls back to `body` if not set. */
+  instagramBody?: string;
+  whatsappCategory?: WhatsAppCategory;
+  /** Type of header for the template. */
+  headerType?: TemplateCreateRequestHeaderType;
+  /** Header content (text string or media URL). */
+  headerContent?: string;
+  /** Footer text for the template. */
+  footer?: string;
+  variables?: Array<string>;
+  /** Template buttons (max 3). */
+  buttons?: Array<TemplateCreateRequestButtonsItem>;
+  /** Add 'Do not share this code' disclaimer. Only for AUTHENTICATION templates. */
+  addSecurityRecommendation?: boolean;
+  /** Code expiration time in minutes. Only for AUTHENTICATION templates. */
+  codeExpirationMinutes?: number;
+}
+
+export type TemplateCreateRequestHeaderType = 'text' | 'image' | 'video' | 'document';
+
+export interface TemplateCreateRequestButtonsItem {
+  /**
+   * `request_contact_info` renders a fixed **Share Contact Info** button that asks
+   * the recipient to share their phone number — useful when a contact adopted a
+   * WhatsApp username and you only know their BSUID. It takes no other fields.
+   */
+  type: TemplateCreateRequestButtonsItemType;
+  /**
+   * Button label. Required for every type except `request_contact_info`, whose label
+   * is fixed by WhatsApp.
+   */
+  text?: string;
+  /**
+   * Button destination. Use `{{1}}` exactly once for a dynamic URL (e.g.
+   * `https://example.com/orders/{{1}}`); WhatsApp only accepts the strict `{{1}}`
+   * form. Static URLs must not contain any `{{...}}` placeholder.
+   */
+  url?: string;
+  /**
+   * Sample value Meta uses to review templates with a dynamic URL button.
+   * Substituted into `{{1}}` of the URL when the template is submitted to Meta. Only
+   * meaningful when `url` contains `{{1}}`; ignored for static URLs.
+   */
+  example?: string;
+  phoneNumber?: string;
+  /**
+   * Required when type is 'otp'. COPY_CODE shows copy button, ONE_TAP enables
+   * Android autofill.
+   */
+  otpType?: TemplateCreateRequestButtonsItemOtpType;
+  /** Android package name. Required for ONE_TAP buttons. */
+  packageName?: string;
+  /** Android app signature hash. Required for ONE_TAP buttons. */
+  signatureHash?: string;
+}
+
+export type TemplateCreateRequestButtonsItemType =
+  | 'quick_reply'
+  | 'url'
+  | 'phone'
+  | 'otp'
+  | 'request_contact_info';
+
+export type TemplateCreateRequestButtonsItemOtpType = 'COPY_CODE' | 'ONE_TAP';
+
+export interface TemplateSubmitRequest {
+  /**
+   * The WhatsApp number whose Business Account receives the template: an address
+   * with a `whatsapp` entry in `GET /v2/channels`.
+   */
+  from: string;
+  category?: WhatsAppCategory;
+}
+
+/**
+ * Type of event that triggers the webhook.
+ *
+ * **Message lifecycle events:**
+ * - `message.queued`: Message created and queued for sending. `data.status` =
+ *   `queued`
+ * - `message.sent`: Message accepted by the provider. `data.status` = `sent`
+ * - `message.delivered`: Message delivered to recipient. `data.status` =
+ *   `delivered`
+ * - `message.read`: Message was read by the recipient (WhatsApp only).
+ *   `data.status` = `read`
+ * - `message.failed`: Message failed to send. `data.status` = `failed`
+ *
+ * **Inbound events:**
+ * - `message.inbound`: New message received from a contact. `data.conversationId`,
+ *   the inbox thread id (deep-link with
+ *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), is sent on
+ *   **email** messages only, and is `null` there on the first message of a
+ *   brand-new thread. On every other channel it is absent: read it from `GET
+ *   /v2/messages/{messageId}`, which always has it, or from `conversation.new` for
+ *   a new contact. Reactions are delivered as `message.inbound` with
+ *   `messageType='reaction'`. When the contact replied to (quoted) an earlier
+ *   message, `data.content` carries the reply context: `replyToMessageId`,
+ *   `replyToProviderMessageId`, `replyToFrom`, `replyToText`, and
+ *   `replyToMessageType`. `data.providerTimestamp` is the provider's original
+ *   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. 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:**
+ * - `broadcast.status_changed`: Broadcast status changed (pending_review,
+ *   approved, rejected, sending, completed, cancelled)
+ *
+ * **Other events:**
+ * - `conversation.new`: New conversation started with a contact. `data` carries
+ *   `conversationId` (the inbox thread id — deep-link with
+ *   `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`), the
+ *   `phoneNumber` or `email` key, `channel`, `firstMessageId`, `firstMessageText`,
+ *   and `profileName`.
+ * - `template.status_changed`: WhatsApp template approval status changed. `data`
+ *   carries `templateId`, `name`, `previousStatus`, `currentStatus`,
+ *   `rejectionReason`, and `category` — the category Meta currently bills the
+ *   template under. Meta can recategorize a template (typically `UTILITY` to
+ *   `MARKETING`) at approval or long afterwards, which changes what each message
+ *   costs; `category` is how that reaches you. A recategorization with no status
+ *   change is delivered as this same event, so compare `category` against what you
+ *   hold rather than only reacting to `currentStatus`.
+ *
+ * **Partner events:**
+ * - `invitation.status_changed`: A partner invitation's stored status changed: to
+ *   `in_progress`, `completed`, `failed`, `cancelled`, or back to `pending` when
+ *   it is resent from the dashboard. A change to the same status sends nothing,
+ *   and expiry is not a stored change, so no event is sent when an invitation
+ *   expires. Delivered to the project that created the invitation; a parent
+ *   project does not receive its sub-accounts' events. `data` carries
+ *   `invitationId`, `clientName`, `clientEmail`, `connectionType` (`whatsapp_waba`
+ *   or `messenger`), `previousStatus`, and `currentStatus`. On `completed` it also
+ *   carries `connectedAccount` (`channel`, `id`, `name`), the WhatsApp number or
+ *   Facebook Page that was linked, and, for WhatsApp, `wabaAccountId`. On `failed`
+ *   it carries `failureReason`; the invitation link stays usable, so a client can
+ *   retry it.
+ *
+ * **Voice Agent events:**
+ * For every voice event, `data` carries `callId`, `direction`, `from`, `to`,
+ * `status`, `durationSeconds`, `endReason`, and `transcriptAvailable`. The
+ * terminal events (`call.completed`, `call.failed`) additionally carry `cost` —
+ * what the call was billed, in USD, combining telephony and the managed voice
+ * pipeline — and `currency`. They are dispatched after the call is charged, so
+ * `cost` is populated rather than zero; telephony can still be settling on an
+ * outbound call, in which case `GET /v1/calls/{callId}` holds the reconciled
+ * figure.
+ * - `call.initiated`: An outbound call was created and is dialing, or an inbound
+ *   call was received. `data.status` = `ringing`
+ * - `call.answered`: The call was answered and the voice agent is connected.
+ *   `data.status` = `in_progress`
+ * - `call.completed`: The call ended after a conversation. `data.status` =
+ *   `completed`; `durationSeconds` and `endReason` describe how it ended, and
+ *   `transcriptAvailable` indicates whether a transcript can be fetched.
+ * - `call.failed`: The call could not be completed (busy, no answer, canceled, or
+ *   an error). `data.status` is the terminal status and `endReason` explains the
+ *   cause.
+ *
+ * **Custom domain events:**
+ * - `domain.verified`: A custom email domain passed verification (DKIM, and
+ *   SPF/DMARC/MAIL FROM if enhanced records are enabled)
+ * - `domain.failed`: A custom email domain failed verification or is partially
+ *   verified
+ */
+export type WebhookEvent =
+  | 'message.queued'
+  | 'message.sent'
+  | 'message.delivered'
+  | 'message.read'
+  | 'message.failed'
+  | 'message.inbound'
+  | 'message.unsupported'
+  | 'broadcast.status_changed'
+  | 'conversation.new'
+  | 'template.status_changed'
+  | 'invitation.status_changed'
+  | 'call.initiated'
+  | 'call.answered'
+  | 'call.completed'
+  | 'call.failed'
+  | 'domain.verified'
+  | 'domain.failed';
+
+/**
+ * Data payload for message webhook events (queued, sent, delivered, failed,
+ * inbound).
+ */
+export interface WebhookMessageData {
+  /** ID of the message. */
+  messageId: string;
+  /**
+   * Recipient phone number or email. On `message.inbound` this is your own number
+   * (the message's destination).
+   */
+  to: string;
+  /**
+   * Sender of the message. Present on `message.inbound`: the contact who sent the
+   * message.
+   */
+  from?: string;
+  channel: ChannelType;
+  status: MessageStatus;
+  /** Type of the message. Present on `message.inbound`. */
+  messageType?: MessageType;
+  /**
+   * ID of the conversation (inbox thread) this message belongs to. Sent on
+   * `message.inbound` for **email** messages only; on SMS, WhatsApp, Telegram,
+   * Instagram and Messenger it is absent. Use it to deep-link to the dashboard
+   * inbox: `https://dashboard.zavu.dev/{locale}/inbox?conv={conversationId}`. On
+   * email it is `null` on the first message of a brand-new thread. In every case,
+   * fetch it via `GET /v2/messages/{messageId}`, whose `conversationId` is always
+   * populated, or take it from the `conversation.new` event for a new contact.
+   */
+  conversationId?: string | null;
+  /**
+   * Text body or media caption. Present on `message.inbound` when the message has
+   * text.
+   */
+  text?: string;
+  /** Error code if the message failed. */
+  errorCode?: string | null;
+  /** Error message if the message failed. */
+  errorMessage?: string | null;
+  /**
+   * The provider's original receive time in Unix milliseconds (when the channel
+   * received the message from the contact). Present on `message.inbound` for
+   * channels that report it (WhatsApp, Telegram, Instagram, Messenger); null for SMS
+   * and email.
+   */
+  providerTimestamp?: number | null;
+  /**
+   * Click-to-WhatsApp ad attribution. Present on `message.inbound` only when this is
+   * the first message of a conversation opened from a Meta ad or post — absent on
+   * every later message in that same thread, and on organic conversations. Read
+   * `referral.ctwaClid` here to attribute the conversation, and persist it on your
+   * side: this webhook is the only delivery. `GET /v2/messages/{messageId}` also
+   * returns it, under `content.referral`.
+   */
+  referral?: AdReferral;
+}
+
+/**
+ * What a `POST` to your /v2 webhook carries. Signed like every Zavu webhook
+ * (`X-Zavu-Signature`, with the webhook's `signatureVersion`); the event name is
+ * also in the `X-Zavu-Event` header. No sender id appears anywhere in it.
+ */
+export interface WebhookPayloadV2 {
+  /**
+   * Unique event identifier. Different from the id of the same event delivered to a
+   * /v1 webhook.
+   */
+  id: string;
+  event: WebhookEvent;
+  /** Unix milliseconds when the event was created. */
+  timestamp: number;
+  projectId: string;
+  /**
+   * Where the event's message or call came from. Outbound message events: your
+   * address. `message.inbound`, `message.unsupported`, `conversation.new`: the
+   * contact. `call.*`: the caller. Project-level events (`invitation.*`, `domain.*`,
+   * `broadcast.*`) are not about one address: read `data`. On those, `from`, `to`
+   * and `type` can be null, or name an address of the channel group the event was
+   * recorded on.
+   */
+  from: string | null;
+  /**
+   * The other end: the recipient of an outbound message, your address for an inbound
+   * one, the callee of a call.
+   */
+  to: string | null;
+  /** The transport, as in `GET /v2/channels`. Null when the event names none. */
+  type: ChannelType | null;
+  /** The same event data /v1 sends (see `WebhookEvent`), without `senderId`. */
+  data: { [key: string]: unknown };
+}
+
+/**
+ * Which `X-Zavu-Signature` scheme this receiver is sent. The header is `t=<unix
+ * seconds>` followed by the signatures.
+ *
+ * - `v1`: `v1=HMAC_SHA256(secret, body)`.
+ * - `v2`: `v2=HMAC_SHA256(secret, "{t}.{body}")`. The current scheme, and the
+ *   default for a new /v2 webhook. It signs the timestamp together with the body.
+ * - `v1+v2`: both signatures, sharing one `t`. The migration setting: a receiver
+ *   reading either one works.
+ *
+ * Moving straight between `v1` and `v2`, in either direction, returns `400`. Set
+ * `v1+v2` first. See
+ * https://docs.zavu.dev/guides/receiving-messages/signature-migration
+ */
+export type WebhookSignatureVersion = 'v1' | 'v1+v2' | 'v2';
+
+/** WhatsApp template category. */
+export type WhatsAppCategory = 'UTILITY' | 'MARKETING' | 'AUTHENTICATION';
+
+/** One place the project can send from, on one transport. */
+export interface ChannelEntry {
+  /**
+   * The address the recipient sees: an E.164 number (`sms`, `voice`, `whatsapp`), an
+   * email address (lowercase), `@botname` (`telegram`), `@username` (`instagram`),
+   * the Facebook Page id (`messenger`), or the literal `sms_oneway` (one-way SMS
+   * goes out from shared system numbers, and messages on it store this same literal
+   * as `from`).
+   */
+  address: string;
+  type: ChannelType;
+  /**
+   * It can send right now. A connected transport that is switched off is listed with
+   * `active: false`; turn it on with `POST /v2/channels/{address}/{type}/activate`.
+   * `sms`, `sms_oneway` and `voice` have no switch and are always active.
+   */
+  active: boolean;
+  /**
+   * Read-only. The /v1 sender behind this entry, usable as the `Zavu-Sender` header
+   * on /v1. Entries with the same `v1SenderId` are one channel group. On /v2 it is
+   * accepted as `from` only when two entries of different groups share an address
+   * (see `409 ambiguous_from`).
+   */
+  v1SenderId: string;
+}
+
+/**
+ * A /v1 sender webhook that is still on. Each one also receives the events it is
+ * subscribed to, as a separate delivery.
+ */
+export interface SenderWebhookV1 {
+  /** The sender's first address; null for a sender with no connected transport. */
+  address: string | null;
+  url: string;
+  /** Read-only; the sender to change on /v1. */
+  v1SenderId: string;
+}
+
+/**
+ * What to connect. Only channels that need no purchase and no third-party signup
+ * are connected here: one-way SMS, an email address at a verified domain, a
+ * Telegram bot. Two-way SMS and voice come with a number (`POST /v2/numbers`);
+ * WhatsApp, Instagram and Messenger connect through Meta, from Accounts in the
+ * dashboard. Any of those types here is a `400` saying so.
+ */
+export type ChannelConnectRequest =
+  | ChannelConnectRequestSmsOneway
+  | ChannelConnectRequestEmail
+  | ChannelConnectRequestTelegram;
+
+export interface EmailDomain {
+  id: string;
+  domain: string;
+  /** Overall verification status. */
+  status: string;
+  dkimStatus: string;
+  /**
+   * DNS records to publish. Present when fetching a single domain or after adding
+   * one.
+   */
+  dnsRecords?: Array<EmailDomainDnsRecord>;
+  /**
+   * Present with `dnsRecords`. False when the DKIM records could not be generated:
+   * such a domain cannot verify whatever DNS you publish, and `setupError` says what
+   * to do.
+   */
+  verifiable?: boolean;
+  /**
+   * Present when `verifiable` is false. `recommendation` is the same everywhere this
+   * domain is refused (`POST .../verify`, `POST /v2/channels`): remove the domain
+   * and add it again, which sets it up from scratch; contact support if the new one
+   * has no `dkim` record either. It never says to retry verify or to publish the
+   * other records.
+   */
+  setupError?: EmailDomainSetupError;
+}
+
+export interface EmailDomainSetupError {
+  code?: 'dkim_records_unavailable';
+  message?: string;
+  recommendation?: string;
+}
+
+export interface EmailDomainDnsRecord {
+  /** DNS record type. */
+  type: string;
+  /** Record host/name to create. */
+  name: string;
+  /** Record value. */
+  value: string;
+  /** Priority (MX records only). */
+  priority?: number;
+  /** What the record is for. */
+  purpose: EmailDomainDnsRecordPurpose;
+  /**
+   * Whether the record is required to verify + send (DKIM) or recommended for
+   * deliverability.
+   */
+  required: boolean;
+}
+
+export type EmailDomainDnsRecordPurpose = 'dkim' | 'spf' | 'dmarc' | 'mail_from';
+
+/**
+ * A Zavu Function: TypeScript that runs in Zavu Cloud, either reacting to events,
+ * serving HTTP, or holding the agents its code declares.
+ */
+export interface ZavuFunction {
+  id: string;
+  slug: string;
+  name: string;
+  description?: string | null;
+  runtime: string;
+  status: FunctionStatus;
+  /**
+   * True only while a version is live and not paused (`status: active`). A draft, a
+   * failed first deploy, a deploy in progress or a pause are all `false`.
+   */
+  enabled: boolean;
+  timeoutSec: number;
+  memoryMb: FunctionMemoryMb;
+  /**
+   * arm64 is the default and the cheaper one; x86_64 bills each invocation at 1.25x
+   * units. Applied on the next deploy.
+   */
+  architecture: FunctionArchitecture;
+  httpEnabled: boolean;
+  /** Null while `httpEnabled` is false: the URL does not serve then. */
+  publicUrl?: string | null;
+  activeDeploymentId?: string | null;
+  createdAt: string;
+  updatedAt: string;
+  /**
+   * The customer paused it. A deploy, a git push or a rollback does not resume it.
+   * Pausing stops event triggers; the HTTP endpoint has its own switch,
+   * `httpEnabled`, and the tools of the agents it declares keep answering.
+   */
+  paused: boolean;
+}
+
+export type FunctionStatus = 'draft' | 'deploying' | 'active' | 'failed' | 'disabled';
+
+export type FunctionMemoryMb = 128 | 256 | 512 | 1024;
+
+export type FunctionArchitecture = 'arm64' | 'x86_64';
+
+/**
+ * Configuration only, applied in one transaction: if any part is refused, nothing
+ * changes. Code, dependencies and deploys are on /v1 (`PATCH
+ * /v1/functions/{functionId}` and `POST /v1/functions/{functionId}/deploy`). Send
+ * at least one field. Every invalid field is reported in `details.errors`.
+ */
+export interface FunctionUpdateRequest {
+  name?: string;
+  /** null clears it. */
+  description?: string | null;
+  /** Applied on the next deploy. */
+  timeoutSec?: number;
+  /** Applied on the next deploy. */
+  memoryMb?: FunctionUpdateRequestMemoryMb;
+  architecture?: FunctionUpdateRequestArchitecture;
+  /**
+   * false pauses the function, true resumes it. Refused with 409
+   * `function_not_ready` while it is a draft, deploying, or its first deploy failed.
+   */
+  enabled?: boolean;
+  /**
+   * Switch the public endpoint on or off. Applies to the deployed function without a
+   * redeploy.
+   */
+  httpEnabled?: boolean;
+}
+
+export type FunctionUpdateRequestMemoryMb = 128 | 256 | 512 | 1024;
+
+export type FunctionUpdateRequestArchitecture = 'arm64' | 'x86_64';
+
+/**
+ * One-way SMS from shared system numbers. No number or credential; recipients
+ * cannot reply. Sends within the SMS daily ceiling. Sending to a US or Canadian
+ * (+1) number needs an approved 10DLC campaign first, and is refused with `403
+ * ten_dlc_required` until then. Refused with `403 kyb_required` only on an account
+ * that must verify its business before using one-way SMS.
+ */
+export interface ChannelConnectRequestSmsOneway {
+  type: 'sms_oneway';
+}
+
+/**
+ * An address at an email domain of this project that is verified (`GET
+ * /v2/email-domains`).
+ */
+export interface ChannelConnectRequestEmail {
+  type: 'email';
+  address: string;
+  /** Display name in the recipient's inbox. */
+  fromName?: string;
+}
+
+/** A Telegram bot. Its address is `@botname`. */
+export interface ChannelConnectRequestTelegram {
+  type: 'telegram';
+  /** Bot token from @BotFather. */
+  botToken: string;
+}
+
+export type ListMessagesV2Status = 'queued' | 'sending' | 'sent' | 'delivered' | 'failed' | 'received';
+
+export interface ListMessagesV2Response {
+  items: Array<Message>;
+  nextCursor?: string | null;
+}
+
+export interface GetMessageV2Response {
+  message: Message;
+}
+
+export interface ListConversationsV2Response {
+  items: Array<Conversation>;
+  nextCursor?: string | null;
+}
+
+export interface GetConversationV2Response {
+  conversation: Conversation;
+}
+
+export interface ListConversationMessagesV2Response {
+  items: Array<Message>;
+  nextCursor?: string | null;
+}
+
+export interface MarkConversationReadV2Response {
+  conversation: Conversation;
+}
+
+export interface ListContactsV2Response {
+  items: Array<Contact>;
+  nextCursor?: string | null;
+}
+
+export interface ListChannelsV2Response {
+  items: Array<ChannelEntry>;
+  nextCursor?: string | null;
+}
+
+export interface ConnectChannelV2Response {
+  items: Array<ChannelEntry>;
+}
+
+export interface ListTemplatesV2Response {
+  items: Array<Template>;
+  nextCursor?: string | null;
+}
+
+export interface ListCampaignsV2Response {
+  items: Array<Broadcast>;
+  nextCursor: string | null;
+}
+
+export interface CreateCampaignV2Response {
+  campaign: Broadcast;
+}
+
+export interface GetCampaignV2Response {
+  campaign: Broadcast;
+}
+
+export interface SendCampaignV2Response {
+  campaign: Broadcast;
+}
+
+export interface GetWebhookV2Response {
+  webhook: ProjectWebhookV2 | null;
+  senderWebhooks: Array<SenderWebhookV1>;
+}
+
+export interface PutWebhookV2Response {
+  webhook: ProjectWebhookV2;
+  senderWebhooks: Array<SenderWebhookV1>;
+  /** How many /v1 sender webhooks this call switched off. */
+  disabledSenderWebhooks: number;
+}
+
+export interface RotateWebhookSecretV2Response {
+  secret: string;
+}
+
+export interface ListAgentsV2Response {
+  items: Array<Agent>;
+  nextCursor?: string | null;
+}
+
+export interface CreateAgentV2Response {
+  agent: Agent;
+}
+
+export interface GetAgentV2Response {
+  agent: Agent;
+}
+
+export interface UpdateAgentV2Response {
+  agent: Agent;
+}
+
+export interface GetChannelV2Response {
+  items: Array<ChannelEntry>;
+}
+
+export interface ActivateChannelV2Response {
+  address: string;
+  type: ActivatableChannel;
+  /** Every entry of the address after the change. */
+  channels: Array<ChannelEntry>;
+  activated: boolean;
+  chargedCents: number;
+  monthlyCents: number;
+}
+
+export interface DeactivateChannelV2Response {
+  address: string;
+  type: ActivatableChannel;
+  /** Every entry of the address after the change. */
+  channels: Array<ChannelEntry>;
+  deactivated: boolean;
+}
+
+export interface SearchNumbersV2Response {
+  items: Array<AvailablePhoneNumber>;
+}
+
+export interface PurchaseNumberV2Response {
+  number: OwnedPhoneNumber;
+  /** The entries of the new number (`sms`, once routed). */
+  channels: Array<ChannelEntry>;
+  /**
+   * Present only when the purchase succeeded and turning SMS on did not.
+   * `details.recommendation` says how to retry.
+   */
+  setupError?: ErrorBody;
+}
+
+export interface ConnectAgentChannelV2Body {
+  address: string;
+  type: ChannelType;
+}
+
+export interface ConnectAgentChannelV2Response {
+  agent: Agent;
+}
+
+export interface ListEmailDomainsV2Response {
+  items: Array<EmailDomain>;
+}
+
+export interface AddEmailDomainV2Body {
+  domain: string;
+}
+
+export interface AddEmailDomainV2Response {
+  domain: EmailDomain;
+}
+
+export interface GetEmailDomainV2Response {
+  domain: EmailDomain;
+}
+
+export interface VerifyEmailDomainV2Response {
+  domain: EmailDomain;
+}
+
+export interface CancelCampaignV2Response {
+  campaign: Broadcast;
+}
+
+export interface ListFunctionsV2Response {
+  items: Array<ZavuFunction>;
+  nextCursor: string | null;
+}
+
+export interface GetFunctionV2Response {
+  function: ZavuFunction;
+}
+
+export interface UpdateFunctionV2Response {
+  function: ZavuFunction;
+}
+
+/** Params for `messages.send`. */
+export interface MessagesSendParams extends SendMessageRequest {}
+
+/** Params for `messages.list`. */
+export interface MessagesListParams {
+  status?: ListMessagesV2Status;
+  to?: string;
+  channel?: ChannelType;
+  /** @defaultValue `50` */
+  limit?: number;
+  /** Opaque `nextCursor` from the previous page. */
+  cursor?: string;
+}
+
+/** Params for `conversations.list`. */
+export interface ConversationsListParams {
+  /** Only threads that have carried this transport. */
+  channel?: ChannelType;
+  /**
+   * Keep only threads last handled from this address. Resolved like `from` on `POST
+   * /v2/messages`, narrowed by `channel` when given.
+   */
+  from?: string;
+  /** Identity search (number, email, username). Never message bodies. */
+  search?: string;
+  /** @defaultValue `50` */
+  limit?: number;
+  /** Opaque `nextCursor` from the previous page. */
+  cursor?: string;
+}
+
+/** Params for `conversations.listMessages`. */
+export interface ConversationsListMessagesParams {
+  /** @defaultValue `50` */
+  limit?: number;
+  /** Opaque `nextCursor` from the previous page. */
+  cursor?: string;
+}
+
+/** Params for `contacts.list`. */
+export interface ContactsListParams {
+  search?: string;
+  tag?: Array<string>;
+  /** @defaultValue `50` */
+  limit?: number;
+  /** Opaque `nextCursor` from the previous page. */
+  cursor?: string;
+}
+
+/** Params for `contacts.create`. */
+export interface ContactsCreateParams extends ContactCreateRequest {}
+
+/** Params for `contacts.update`. */
+export interface ContactsUpdateParams extends ContactUpdateRequest {}
+
+/** Params for `channels.list`. */
+export interface ChannelsListParams {
+  /** @defaultValue `50` */
+  limit?: number;
+  /** Opaque `nextCursor` from the previous page. */
+  cursor?: string;
+}
+
+/** Params for `channels.connect`. */
+export type ChannelsConnectParams = ChannelConnectRequest;
+
+/** Params for `templates.list`. */
+export interface TemplatesListParams {
+  /** @defaultValue `50` */
+  limit?: number;
+  /** Opaque `nextCursor` from the previous page. */
+  cursor?: string;
+}
+
+/** Params for `templates.create`. */
+export interface TemplatesCreateParams extends TemplateCreateRequest {}
+
+/** Params for `templates.submit`. */
+export interface TemplatesSubmitParams extends TemplateSubmitRequest {}
+
+/** Params for `campaigns.list`. */
+export interface CampaignsListParams {
+  status?: BroadcastStatus;
+  /** @defaultValue `50` */
+  limit?: number;
+  /** Opaque, from a previous `nextCursor`. */
+  cursor?: string;
+}
+
+/** Params for `campaigns.create`. */
+export interface CampaignsCreateParams extends BroadcastCreateRequest {}
+
+/** Params for `campaigns.send`. */
+export interface CampaignsSendParams extends BroadcastSendRequest {}
+
+/** Params for `campaigns.recipients.add`. */
+export interface CampaignsRecipientsAddParams extends BroadcastContactsAddRequest {}
+
+/** Params for `webhook.set`. */
+export interface WebhookSetParams extends ProjectWebhookV2Put {}
+
+/** Params for `agents.list`. */
+export interface AgentsListParams {
+  /** @defaultValue `50` */
+  limit?: number;
+  /** Opaque `nextCursor` from the previous page. */
+  cursor?: string;
+}
+
+/** Params for `agents.create`. */
+export interface AgentsCreateParams extends AgentCreateStandaloneRequest {}
+
+/** Params for `agents.update`. */
+export interface AgentsUpdateParams extends AgentUpdateRequest {}
+
+/** Params for `agents.test`. */
+export interface AgentsTestParams extends AgentTestRequest {}
+
+/** Params for `agents.channels.connect`. */
+export interface AgentsChannelsConnectParams extends ConnectAgentChannelV2Body {}
+
+/** Params for `numbers.searchAvailable`. */
+export interface NumbersSearchAvailableParams {
+  countryCode: string;
+  type?: PhoneNumberType;
+  contains?: string;
+  capabilities?: string;
+  /** @defaultValue `10` */
+  limit?: number;
+}
+
+/** Params for `numbers.purchase`. */
+export interface NumbersPurchaseParams extends PhoneNumberPurchaseRequest {}
+
+/** Params for `emailDomains.create`. */
+export interface EmailDomainsCreateParams extends AddEmailDomainV2Body {}
+
+/** Params for `functions.list`. */
+export interface FunctionsListParams {
+  /** @defaultValue `50` */
+  limit?: number;
+  cursor?: string;
+}
+
+/** Params for `functions.update`. */
+export interface FunctionsUpdateParams extends FunctionUpdateRequest {}