@zavudev/sdk 0.51.0 → 0.53.0

package/src/resources/functions/functions.ts

@@ -33,7 +33,7 @@ export class Functions extends APIResource {
    *   description:
    *     'Replies to order status questions on WhatsApp.',
    *   sourceCode:
-   *     "import { defineFunction } from '@zavu/functions';\n\nexport default defineFunction(async (event, ctx) => {\n  ctx.log('received', event.type);\n});\n",
+   *     "import { defineFunction } from '@zavudev/functions';\n\nexport default defineFunction(async (event, ctx) => {\n  ctx.log('received', event.type);\n});\n",
    * });
    * ```
    */
@@ -56,9 +56,11 @@ export class Functions extends APIResource {
   }
 
   /**
-   * Update the draft source code and/or dependency map without triggering a build.
-   * Visible in the dashboard immediately, but the live (deployed) function does not
-   * change until `POST /v1/functions/{functionId}/deploy` runs.
+   * Update an existing function. `sourceCode` / `dependencies` edit the draft
+   * without triggering a build — they go live on the next
+   * `POST /v1/functions/{functionId}/deploy`. `httpEnabled` is applied to the
+   * deployed function immediately, so turning the public endpoint on or off does not
+   * require a redeploy.
    *
    * @example
    * ```ts
@@ -213,7 +215,9 @@ export namespace FunctionCreateResponse {
     description?: string | null;
 
     /**
-     * HTTPS endpoint when httpEnabled is true.
+     * HTTPS endpoint, present only while httpEnabled is true. Null otherwise,
+     * including for a function that was previously exposed — the stored URL stops
+     * serving the moment HTTP is turned off, so it is never returned.
      */
     publicUrl?: string | null;
   }
@@ -285,7 +289,9 @@ export namespace FunctionRetrieveResponse {
     description?: string | null;
 
     /**
-     * HTTPS endpoint when httpEnabled is true.
+     * HTTPS endpoint, present only while httpEnabled is true. Null otherwise,
+     * including for a function that was previously exposed — the stored URL stops
+     * serving the moment HTTP is turned off, so it is never returned.
      */
     publicUrl?: string | null;
   }
@@ -357,7 +363,9 @@ export namespace FunctionUpdateResponse {
     description?: string | null;
 
     /**
-     * HTTPS endpoint when httpEnabled is true.
+     * HTTPS endpoint, present only while httpEnabled is true. Null otherwise,
+     * including for a function that was previously exposed — the stored URL stops
+     * serving the moment HTTP is turned off, so it is never returned.
      */
     publicUrl?: string | null;
   }
@@ -490,6 +498,12 @@ export interface FunctionCreateParams {
    */
   sourceCode?: string;
 
+  /**
+   * Per-invocation timeout in seconds. Event and cron invocations are asynchronous,
+   * so a long timeout only bounds cost; a tool called during a live conversation
+   * holds up the reply, and a function exposed over HTTP is additionally bounded by
+   * the platform's HTTP response limit.
+   */
   timeoutSec?: number;
 }
 
@@ -500,7 +514,14 @@ export interface FunctionUpdateParams {
   dependencies?: { [key: string]: string };
 
   /**
-   * New source code to publish (replaces the draft).
+   * Expose the function on its public HTTPS URL, or take it down. Applies to the
+   * already-deployed function without redeploying; the URL is returned as
+   * `publicUrl`.
+   */
+  httpEnabled?: boolean;
+
+  /**
+   * New source code for the draft (replaces it).
    */
   sourceCode?: string;
 }

package/src/resources/invitations.ts

@@ -8,12 +8,22 @@ import { path } from '../internal/utils/path';
 
 export class Invitations extends APIResource {
   /**
-   * Create a partner invitation link for a client to connect WhatsApp. The client
-   * opens the returned `url` and completes Meta's embedded signup, linking an
-   * official WhatsApp Business Account. The resulting sender is created in your
-   * project when the client completes the flow, and the invitation transitions to
+   * Create a partner invitation link for a client to connect a Meta channel. The
+   * client opens the returned `url` and authorizes with Meta; the resulting sender
+   * is created in your project when they finish, and the invitation transitions to
    * `completed`.
    *
+   * `connectionType` picks the channel:
+   *
+   * - `whatsapp_waba` (default): Meta's embedded signup links an official WhatsApp
+   *   Business Account.
+   * - `messenger`: the client picks a Facebook Page they administer; its Messenger
+   *   inbox (including Marketplace chats) is routed to Zavu.
+   *
+   * One invitation connects one channel — create one per channel to onboard a client
+   * on several. `phoneNumberId` and `allowedPhoneCountries` apply to `whatsapp_waba`
+   * only.
+   *
    * @example
    * ```ts
    * const invitation = await client.invitations.create({
@@ -92,8 +102,13 @@ export interface Invitation {
 
   /**
    * Current status of the partner invitation.
+   *
+   * `failed` means the client started the connection and it did not finish (they
+   * cancelled Meta's dialog, denied a permission, or abandoned the tab). A failed
+   * invitation is still usable: the same link can be retried, and it moves back to
+   * `in_progress` when the client tries again.
    */
-  status: 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled';
+  status: 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled' | 'failed';
 
   updatedAt: string;
 
@@ -111,13 +126,33 @@ export interface Invitation {
   completedAt?: string | null;
 
   /**
-   * How the client connects WhatsApp: `whatsapp_waba` (official Cloud API via
-   * embedded signup).
+   * The account the client linked, populated once the invitation is `completed`.
+   * Null before that. Use it to show the partner what was connected without fetching
+   * the sender.
+   */
+  connectedAccount?: Invitation.ConnectedAccount | null;
+
+  /**
+   * Which Meta channel the client connects: `whatsapp_waba` (official WhatsApp Cloud
+   * API via embedded signup) or `messenger` (a Facebook Page's Messenger inbox,
+   * including Marketplace chats).
    */
-  connectionType?: 'whatsapp_waba';
+  connectionType?: 'whatsapp_waba' | 'messenger';
+
+  failedAt?: string | null;
 
   /**
-   * ID of a pre-assigned Zavu phone number for WhatsApp registration.
+   * Stable code for why the last attempt failed, present when `status` is `failed`.
+   * Values include `fb_cancelled` (client closed Meta's dialog), `fb_not_authorized`
+   * (permission denied), `signup_abandoned` (started but never finished),
+   * `meta_no_pages` (the client administers no Facebook Page), and `internal_error`.
+   * Treat unknown codes as a generic failure.
+   */
+  failureReason?: string | null;
+
+  /**
+   * ID of a pre-assigned Zavu phone number for WhatsApp registration. Always null
+   * for `messenger` invitations.
    */
   phoneNumberId?: string | null;
 
@@ -131,6 +166,28 @@ export interface Invitation {
   viewedAt?: string | null;
 }
 
+export namespace Invitation {
+  /**
+   * The account the client linked, populated once the invitation is `completed`.
+   * Null before that. Use it to show the partner what was connected without fetching
+   * the sender.
+   */
+  export interface ConnectedAccount {
+    /**
+     * Provider-side identifier: the WhatsApp phone number ID, or the Facebook Page ID.
+     */
+    id: string;
+
+    channel: 'whatsapp' | 'messenger';
+
+    /**
+     * Display name of the connected account: the WhatsApp verified name, or the
+     * Facebook Page name.
+     */
+    name?: string | null;
+  }
+}
+
 export interface InvitationCreateResponse {
   invitation: Invitation;
 }
@@ -145,7 +202,8 @@ export interface InvitationCancelResponse {
 
 export interface InvitationCreateParams {
   /**
-   * ISO country codes for allowed phone numbers.
+   * ISO country codes for allowed phone numbers. Only valid when `connectionType` is
+   * `whatsapp_waba` — sending it with `messenger` returns 400.
    */
   allowedPhoneCountries?: Array<string>;
 
@@ -165,10 +223,21 @@ export interface InvitationCreateParams {
   clientPhone?: string;
 
   /**
-   * How the client connects WhatsApp. `whatsapp_waba` (default) runs Meta's embedded
-   * signup to link an official WhatsApp Business Account.
+   * Which Meta channel the client connects, and how.
+   *
+   * - `whatsapp_waba` (default): Meta's embedded signup links an official WhatsApp
+   *   Business Account. Accepts `phoneNumberId` and `allowedPhoneCountries`.
+   * - `messenger`: the client authorizes with Facebook and picks a Facebook Page
+   *   they administer. The Page's Messenger inbox — including Marketplace chats — is
+   *   routed to Zavu. They must be an admin of at least one Page. A Page can only be
+   *   connected to one Zavu project at a time: if the client picks a Page that
+   *   another project already connected, the newer connection wins and the older one
+   *   is disconnected.
+   *
+   * One invitation connects one channel. To onboard a client on several channels,
+   * create one invitation per channel; each completes into its own sender.
    */
-  connectionType?: 'whatsapp_waba';
+  connectionType?: 'whatsapp_waba' | 'messenger';
 
   /**
    * Number of days until the invitation expires.
@@ -177,7 +246,9 @@ export interface InvitationCreateParams {
 
   /**
    * ID of a Zavu phone number to pre-assign for WhatsApp registration. If provided,
-   * the client will use this number instead of their own.
+   * the client will use this number instead of their own. Only valid when
+   * `connectionType` is `whatsapp_waba` — sending it with `messenger` returns 400,
+   * since a Facebook Page has no phone number.
    */
   phoneNumberId?: string;
 }
@@ -185,8 +256,13 @@ export interface InvitationCreateParams {
 export interface InvitationListParams extends CursorParams {
   /**
    * Current status of the partner invitation.
+   *
+   * `failed` means the client started the connection and it did not finish (they
+   * cancelled Meta's dialog, denied a permission, or abandoned the tab). A failed
+   * invitation is still usable: the same link can be retried, and it moves back to
+   * `in_progress` when the client tries again.
    */
-  status?: 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled';
+  status?: 'pending' | 'in_progress' | 'completed' | 'expired' | 'cancelled' | 'failed';
 }
 
 export declare namespace Invitations {

package/src/resources/messages.ts

@@ -82,10 +82,19 @@ export class Messages extends APIResource {
    * - Window opens when the user messages you first
    * - Use template messages to initiate conversations outside the window
    *
-   * **Daily limits:**
+   * **Plan allowances and email billing:**
    *
-   * - Unverified accounts: 200 messages per channel per day
-   * - Complete KYC verification to increase limits to 10,000/day
+   * - WhatsApp, Telegram, Instagram and Messenger share an allowance of 2,000
+   *   messages per month on Free. Over it, sends return 429 with code
+   *   `a2p_limit_exceeded` and upgrade details; the counter resets on the 1st of
+   *   each month. Paid plans have no message caps
+   * - Email is billed from your prepaid balance in 1,000-message blocks: $0.40 per
+   *   1,000 transactional emails, $0.80 per 1,000 marketing (broadcast) emails. A
+   *   block is charged when your monthly count crosses each 1,000 boundary, and at
+   *   zero balance email sends return 402 with code `insufficient_balance`. Free
+   *   teams start with $2 of credit and additionally cap at 3,000 emails/month and
+   *   100/day. Teams on earlier plans keep their original email quotas instead
+   * - SMS and voice are billed per message from your balance on every plan
    *
    * **Email recipient pre-flight:** Email messages are validated automatically
    * before dispatch. Sends that would be a guaranteed hard bounce are failed instead
@@ -177,6 +186,20 @@ export interface Message {
   /**
    * Type of message. Non-text types are supported by WhatsApp and Telegram (varies
    * by type).
+   *
+   * `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.
    */
   messageType: MessageType;
 
@@ -461,6 +484,20 @@ export type MessageStatus =
 /**
  * Type of message. Non-text types are supported by WhatsApp and Telegram (varies
  * by type).
+ *
+ * `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'
@@ -474,6 +511,8 @@ export type MessageType =
   | 'buttons'
   | 'list'
   | 'cta_url'
+  | 'request_contact_info'
+  | 'location_request'
   | 'reaction'
   | 'template';
 

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

@@ -115,7 +115,11 @@ export class Brands extends APIResource {
 
   /**
    * Submit a draft brand to The Campaign Registry (TCR) for vetting. The brand must
-   * be in draft status. A $35 registration fee is charged from your balance.
+   * be in draft status. TCR's one-time $4 brand registration fee is charged from
+   * your balance at submission (passed through at cost) and refunded if the carrier
+   * rejects the registration. A team that already paid this fee through the
+   * compliance flow is not charged again. Campaign registration is billed separately
+   * when a campaign is submitted.
    *
    * @example
    * ```ts

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

@@ -117,7 +117,12 @@ export class Campaigns extends APIResource {
 
   /**
    * Submit a draft campaign for carrier review. The campaign must be in draft status
-   * and its brand must be verified.
+   * and its brand must be verified. TCR's one-time registration fee is charged from
+   * your balance at submission ($15 for standard use cases, $2 for LOW_VOLUME),
+   * passed through at cost and refunded if the carrier rejects it. Once approved,
+   * the campaign's monthly TCR fee ($10 standard, $2 LOW_VOLUME) is charged from
+   * your balance while the campaign is active — see registrationCostCents and
+   * monthlyFeeCents on the campaign object.
    *
    * @example
    * ```ts

package/src/resources/phone-numbers.ts

@@ -60,8 +60,9 @@ export class PhoneNumbers extends APIResource {
   }
 
   /**
-   * Purchase an available phone number. The first US phone number is free for each
-   * team.
+   * Purchase an available phone number. Requires a paid plan: the Free plan cannot
+   * purchase phone numbers and receives `402` with code `paid_plan_required`. Paid
+   * plans include the first US number at no charge.
    *
    * @example
    * ```ts
@@ -206,7 +207,8 @@ export interface PhoneNumberCapabilities {
 
 export interface PhoneNumberPricing {
   /**
-   * Whether this number qualifies for the free first US number offer.
+   * Whether this number qualifies as the plan-included first US number on paid
+   * plans.
    */
   isFreeEligible?: boolean;
 
@@ -350,6 +352,12 @@ export interface PhoneNumberSearchAvailableParams {
    */
   countryCode: string;
 
+  /**
+   * Comma-separated capabilities the number must have: `sms`, `voice`, `mms`.
+   * Numbers missing any of them are dropped.
+   */
+  capabilities?: string;
+
   /**
    * Search for numbers containing this string.
    */