@getlatedev/node 0.2.1438 → 0.2.1440

package/dist/index.d.mts

@@ -41313,6 +41313,10 @@ type TransferVoiceCallResponse = ({
 type TransferVoiceCallError = (ErrorResponse | unknown);
 type GetVoiceCallEstimateData = {
     query: {
+        /**
+         * Destination the call bridges to: `tel:+E164`, `sip:...` or `wss://...`. Defaults to the dialing number's configured forward. A `tel:` destination adds a second carrier leg to the quote. Encode the `+` as `%2B`.
+         */
+        forwardTo?: string;
         /**
          * The number the call would dial from, E.164. When it is verified on a Branded Calling identity and `to` is a US number, the estimate includes the per-call Branded Calling surcharge.
          */
@@ -56597,12 +56601,40 @@ type GetAdAccountHealthData = {
 type GetAdAccountHealthResponse = ({
     adAccountId?: string;
     status?: 'ok' | 'attention' | 'blocked';
+    /**
+     * False when a create or boost on this ad account would be refused; `blockers` says why.
+     */
+    ready?: boolean;
+    blockers?: Array<{
+        /**
+         * The `checks[].id` that blocks.
+         */
+        check: string;
+        /**
+         * The error code a refused create or boost returns for this reason.
+         */
+        code: string;
+        message: string;
+        /**
+         * What to do, in English.
+         */
+        hint: string;
+        fix?: {
+            label?: string;
+            url?: string;
+        };
+    }>;
     checkedAt?: string;
     checks?: Array<{
-        id: 'account_status' | 'payment' | 'spend_cap' | 'page' | 'instagram' | 'lead_terms' | 'pixel' | 'whatsapp';
+        id: 'account_status' | 'payment' | 'spend_cap' | 'page' | 'instagram' | 'lead_terms' | 'pixel' | 'whatsapp' | 'last_refusal';
         status: 'ok' | 'warning' | 'error' | 'missing' | 'unknown';
         title: string;
         message: string;
+        /**
+         * When the check is not `ok`: the error code a create refused for this reason returns.
+         */
+        code?: string;
+        hint?: string;
         fix?: {
             label?: string;
             url?: string;
@@ -57701,6 +57733,7 @@ type BoostPostData = {
          *
          * - Idempotency-Key storage and the duplicate-boost guard are bypassed.
          * - Counts toward the 30 Meta writes per ad account per 5 minutes.
+         * - Runs the account status and payment checks of GET /v1/ads/accounts/health first: an ad account that is not ready answers its blocker `code` (`ad_account_unusable`, `ad_account_payment_required`) with `details.hint` and `details.fix`, and Meta is not called.
          * - With `adSetId`, only the ad is dry-run.
          * - An Instagram video Meta refuses as a direct reference (subcode 1815279) comes back as `unverified` nodes, because the copy a real boost makes cannot be dry-run.
          *
@@ -58098,6 +58131,8 @@ type CreateStandaloneAdData = {
          *
          * **Meta**: validates the inline campaign, ad set, creative and ad with execution_options validate_only. Nothing is uploaded or created; validation bypasses Idempotency-Key storage. Success returns 200 with per-node results; a Meta rejection returns an error.
          *
+         * Before the dry run, Meta validateOnly runs the account status and payment checks of GET /v1/ads/accounts/health: an ad account that is not ready answers its blocker `code` (`ad_account_unusable`, `ad_account_payment_required`) with `details.hint` and `details.fix`, and Meta is not called.
+         *
          * - Supported: a single image or existing video.id (each also with bodies[] / headlines[] Multiple Text Options), all-image placementAssets with per-rule copy and text pools, or existingCreativeId.
          * - Return 400: dynamicCreative, translations, carouselCards, placement videos, new video uploads, creatives[], adSetId, RESERVED buying.
          * - Placement validation uses existing Instagram identities only. Existing campaign or creative nodes are marked skipped.

package/dist/index.d.ts

@@ -41313,6 +41313,10 @@ type TransferVoiceCallResponse = ({
 type TransferVoiceCallError = (ErrorResponse | unknown);
 type GetVoiceCallEstimateData = {
     query: {
+        /**
+         * Destination the call bridges to: `tel:+E164`, `sip:...` or `wss://...`. Defaults to the dialing number's configured forward. A `tel:` destination adds a second carrier leg to the quote. Encode the `+` as `%2B`.
+         */
+        forwardTo?: string;
         /**
          * The number the call would dial from, E.164. When it is verified on a Branded Calling identity and `to` is a US number, the estimate includes the per-call Branded Calling surcharge.
          */
@@ -56597,12 +56601,40 @@ type GetAdAccountHealthData = {
 type GetAdAccountHealthResponse = ({
     adAccountId?: string;
     status?: 'ok' | 'attention' | 'blocked';
+    /**
+     * False when a create or boost on this ad account would be refused; `blockers` says why.
+     */
+    ready?: boolean;
+    blockers?: Array<{
+        /**
+         * The `checks[].id` that blocks.
+         */
+        check: string;
+        /**
+         * The error code a refused create or boost returns for this reason.
+         */
+        code: string;
+        message: string;
+        /**
+         * What to do, in English.
+         */
+        hint: string;
+        fix?: {
+            label?: string;
+            url?: string;
+        };
+    }>;
     checkedAt?: string;
     checks?: Array<{
-        id: 'account_status' | 'payment' | 'spend_cap' | 'page' | 'instagram' | 'lead_terms' | 'pixel' | 'whatsapp';
+        id: 'account_status' | 'payment' | 'spend_cap' | 'page' | 'instagram' | 'lead_terms' | 'pixel' | 'whatsapp' | 'last_refusal';
         status: 'ok' | 'warning' | 'error' | 'missing' | 'unknown';
         title: string;
         message: string;
+        /**
+         * When the check is not `ok`: the error code a create refused for this reason returns.
+         */
+        code?: string;
+        hint?: string;
         fix?: {
             label?: string;
             url?: string;
@@ -57701,6 +57733,7 @@ type BoostPostData = {
          *
          * - Idempotency-Key storage and the duplicate-boost guard are bypassed.
          * - Counts toward the 30 Meta writes per ad account per 5 minutes.
+         * - Runs the account status and payment checks of GET /v1/ads/accounts/health first: an ad account that is not ready answers its blocker `code` (`ad_account_unusable`, `ad_account_payment_required`) with `details.hint` and `details.fix`, and Meta is not called.
          * - With `adSetId`, only the ad is dry-run.
          * - An Instagram video Meta refuses as a direct reference (subcode 1815279) comes back as `unverified` nodes, because the copy a real boost makes cannot be dry-run.
          *
@@ -58098,6 +58131,8 @@ type CreateStandaloneAdData = {
          *
          * **Meta**: validates the inline campaign, ad set, creative and ad with execution_options validate_only. Nothing is uploaded or created; validation bypasses Idempotency-Key storage. Success returns 200 with per-node results; a Meta rejection returns an error.
          *
+         * Before the dry run, Meta validateOnly runs the account status and payment checks of GET /v1/ads/accounts/health: an ad account that is not ready answers its blocker `code` (`ad_account_unusable`, `ad_account_payment_required`) with `details.hint` and `details.fix`, and Meta is not called.
+         *
          * - Supported: a single image or existing video.id (each also with bodies[] / headlines[] Multiple Text Options), all-image placementAssets with per-rule copy and text pools, or existingCreativeId.
          * - Return 400: dynamicCreative, translations, carouselCards, placement videos, new video uploads, creatives[], adSetId, RESERVED buying.
          * - Placement validation uses existing Instagram identities only. Existing campaign or creative nodes are marked skipped.

package/dist/index.js

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@getlatedev/node",
-  version: "0.2.1438",
+  version: "0.2.1440",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/dist/index.mjs

@@ -5,7 +5,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // package.json
 var package_default = {
   name: "@getlatedev/node",
-  version: "0.2.1438",
+  version: "0.2.1440",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getlatedev/node",
-  "version": "0.2.1438",
+  "version": "0.2.1440",
   "description": "The official Node.js library for the Zernio API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/generated/sdk.gen.ts

@@ -8100,7 +8100,7 @@ export const transferVoiceCall = <ThrowOnError extends boolean = false>(options:
  * Estimate call cost
  * Pre-call cost estimate for a PSTN call: the carrier leg plus optional recording and transcription add-ons.
  *
- * It uses the same billing formula as the post-call invoice, so the quote and the final charge can't disagree. The per-minute figure is deliberately conservative (the real cost comes from the settled carrier record after the call), so estimates trend slightly over the actual invoice.
+ * It uses the same billing formula as the post-call invoice, so the quote and the final charge can't disagree. The carrier figure follows the carrier's per-destination rate card: a call dialed from a number in the destination country uses the local mobile rate, and a `tel:` forward destination is quoted as a second carrier leg billed from the same number. The real cost comes from the settled carrier record after the call.
  *
  * Parity endpoint of `GET /v1/whatsapp/calls/estimate`, minus the Meta line. PSTN calls have no separate Meta bill, so `totalCostUSD` equals `billableCostUSD`.
  *
@@ -16040,15 +16040,34 @@ export const getAdAccountFinance = <ThrowOnError extends boolean = false>(option
  * - the Page's Lead Ads terms
  * - the newest pixel event
  * - the WhatsApp number linked to the Page
+ * - the last refusal Meta gave a create or boost for a reason only the account owner can fix (`last_refusal`, see below)
  *
  * Each check reads on its own: one this connection cannot see comes back `unknown` instead of failing the request.
  *
+ * ### Remembered refusals
+ *
+ * Meta cannot be asked about a code 31 security check up front. So `last_refusal` reports the last refusal of this kind that a create or boost met:
+ *
+ * - a code 31 security check or a temporary block, remembered for the connection (`accountId`)
+ * - a payment method, the non-discrimination policy or a disabled account, remembered for the ad account
+ *
+ * It stays until a later create succeeds, or for 7 days (1 day for a temporary block).
+ *
  * ### Reading the result
  *
- * - `status` is `blocked` when any check is `error` (ads will be refused), `attention` when one is `warning`, else `ok`.
+ * - `ready` is `false` when a create or boost would be refused. `blockers` lists why, each with the `code` a refused create returns (`ad_account_unusable`, `ad_account_payment_required`, `linked_account_required`, `meta_security_check_required`, `ad_account_policy_not_accepted`, ...), a `hint` and a `fix` link.
+ * - `status` is `blocked` when any check is `error`, `attention` when one is `warning`, else `ok`. It also counts problems that stop delivery but not a create, such as a reached spending limit, so `status` can be `blocked` while `ready` is `true`.
+ * - A check that is not `ok` carries the `code` of the create refusal it explains, when there is one: `whatsapp` (`missing`) carries `whatsapp_number_not_linked` and `lead_terms` (`missing`) carries `lead_ads_terms_not_accepted`, which only click-to-WhatsApp ads and lead ads hit.
  * - `missing` marks an optional asset that is not set up (a pixel, a WhatsApp number): only the ads that need it are affected.
+ * - An unsettled balance (`account_status` 3) is a `warning`: Meta still accepts creates on it while a payment method is set.
  * - A `fix.url` is either a Meta page or a Zernio dashboard path (starting with `/`).
  *
+ * ### validateOnly
+ *
+ * `POST /v1/ads/create` and `POST /v1/ads/boost` with `validateOnly: true` run the account status and payment checks first. A blocked account answers the same `code` with `details.hint` and `details.fix`, without a Meta dry run (Meta counts dry runs as ad writes).
+ *
+ * They read the account state cached for up to 5 minutes. This endpoint always reads it fresh and refreshes that cache.
+ *
  */
 export const getAdAccountHealth = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<GetAdAccountHealthData, ThrowOnError>) => {
     return (options?.client ?? client).get<GetAdAccountHealthResponse, GetAdAccountHealthError, ThrowOnError>({

package/src/generated/types.gen.ts

@@ -41250,6 +41250,10 @@ export type TransferVoiceCallError = (ErrorResponse | unknown);
 
 export type GetVoiceCallEstimateData = {
     query: {
+        /**
+         * Destination the call bridges to: `tel:+E164`, `sip:...` or `wss://...`. Defaults to the dialing number's configured forward. A `tel:` destination adds a second carrier leg to the quote. Encode the `+` as `%2B`.
+         */
+        forwardTo?: string;
         /**
          * The number the call would dial from, E.164. When it is verified on a Branded Calling identity and `to` is a US number, the estimate includes the per-call Branded Calling surcharge.
          */
@@ -57746,12 +57750,40 @@ export type GetAdAccountHealthData = {
 export type GetAdAccountHealthResponse = ({
     adAccountId?: string;
     status?: 'ok' | 'attention' | 'blocked';
+    /**
+     * False when a create or boost on this ad account would be refused; `blockers` says why.
+     */
+    ready?: boolean;
+    blockers?: Array<{
+        /**
+         * The `checks[].id` that blocks.
+         */
+        check: string;
+        /**
+         * The error code a refused create or boost returns for this reason.
+         */
+        code: string;
+        message: string;
+        /**
+         * What to do, in English.
+         */
+        hint: string;
+        fix?: {
+            label?: string;
+            url?: string;
+        };
+    }>;
     checkedAt?: string;
     checks?: Array<{
-        id: 'account_status' | 'payment' | 'spend_cap' | 'page' | 'instagram' | 'lead_terms' | 'pixel' | 'whatsapp';
+        id: 'account_status' | 'payment' | 'spend_cap' | 'page' | 'instagram' | 'lead_terms' | 'pixel' | 'whatsapp' | 'last_refusal';
         status: 'ok' | 'warning' | 'error' | 'missing' | 'unknown';
         title: string;
         message: string;
+        /**
+         * When the check is not `ok`: the error code a create refused for this reason returns.
+         */
+        code?: string;
+        hint?: string;
         fix?: {
             label?: string;
             url?: string;
@@ -58870,6 +58902,7 @@ export type BoostPostData = {
          *
          * - Idempotency-Key storage and the duplicate-boost guard are bypassed.
          * - Counts toward the 30 Meta writes per ad account per 5 minutes.
+         * - Runs the account status and payment checks of GET /v1/ads/accounts/health first: an ad account that is not ready answers its blocker `code` (`ad_account_unusable`, `ad_account_payment_required`) with `details.hint` and `details.fix`, and Meta is not called.
          * - With `adSetId`, only the ad is dry-run.
          * - An Instagram video Meta refuses as a direct reference (subcode 1815279) comes back as `unverified` nodes, because the copy a real boost makes cannot be dry-run.
          *
@@ -59291,6 +59324,8 @@ export type CreateStandaloneAdData = {
          *
          * **Meta**: validates the inline campaign, ad set, creative and ad with execution_options validate_only. Nothing is uploaded or created; validation bypasses Idempotency-Key storage. Success returns 200 with per-node results; a Meta rejection returns an error.
          *
+         * Before the dry run, Meta validateOnly runs the account status and payment checks of GET /v1/ads/accounts/health: an ad account that is not ready answers its blocker `code` (`ad_account_unusable`, `ad_account_payment_required`) with `details.hint` and `details.fix`, and Meta is not called.
+         *
          * - Supported: a single image or existing video.id (each also with bodies[] / headlines[] Multiple Text Options), all-image placementAssets with per-rule copy and text pools, or existingCreativeId.
          * - Return 400: dynamicCreative, translations, carouselCards, placement videos, new video uploads, creatives[], adSetId, RESERVED buying.
          * - Placement validation uses existing Instagram identities only. Existing campaign or creative nodes are marked skipped.