@getlatedev/node 0.2.1331 → 0.2.1333

package/dist/index.d.mts

@@ -3838,6 +3838,10 @@ type AdTracking = {
         key: string;
         value: string;
     }>;
+    /**
+     * POST /v1/ads/create on Meta and Google only. Every ad created there carries `zrn=<platform ad id>` on its landing URL so orders and events tied to the landing URL map back to the ad. Meta: `{ key: zrn, value: '{{ad.id}}' }` is appended after your `urlTags`, which are sent unchanged; a `zrn` key you send yourself is kept. Skipped for lead forms, call ads, `existingCreativeId` and app promotion. Google (Display and Search): the ad's `final_url_suffix` becomes the suffix it would inherit (ad group, campaign or account) plus `&zrn={creative}`, so your account and campaign UTMs still apply; if that suffix cannot be read or Google rejects it, the ad is created untagged. Existing ads are never changed. Set `false` to create the ad with no Zernio tag.
+     */
+    zernioTag?: boolean;
 };
 /**
  * Ad set (or ad group/line item depending on platform) with rolled-up metrics and child ads
@@ -47562,9 +47566,13 @@ type ListTikTokSmartPlusReviewsResponse = ({
      */
     pendingSmartPlusAdIds?: Array<(string)>;
     /**
-     * Seconds to wait before reading this page again, set only while `incomplete` is true and review reads are paused. Null when complete (stale items included), or when the page is incomplete without a quota pause (read it again right away).
+     * Seconds until Zernio calls TikTok's review endpoint for this advertiser and connection again (the stored pause with its jitter), set exactly when `refreshState` is `paused` or `refused`, stale items with nothing pending included. Always the same value as the `Retry-After` header, which is sent exactly when this is not null. Client rule: present, wait that long before reading the page again; null with stale or pending ads, a retry is not blocked (read again now or on your `maxAgeSeconds` schedule; with `refreshState: error` check `reviewError` first).
      */
     retryAfterSeconds?: (number) | null;
+    /**
+     * Whether this request could refresh the due (stale or pending) Smart+ ads of the page. `refused`: TikTok refused a review call of this request over quota (40002 `OVER_QPS_LIMIT` or 40100) and Zernio paused. `paused`: no call was sent for the due ads because a pause from an earlier refusal, or the spacing of at least 60 seconds after a success, is still running. Both carry `retryAfterSeconds`. `error`: TikTok refused the batch for another reason (both halves the same way), the page is served from stored reviews and `reviewError` holds TikTok's error; `retryAfterSeconds` is null because retrying soon repeats the refusal. `ok`: nothing blocks a retry (every due ad was read, none was due, or the split cap left some for the next read, which can come right away).
+     */
+    refreshState?: 'ok' | 'paused' | 'refused' | 'error';
 });
 type ListTikTokSmartPlusReviewsError = (ErrorResponse | unknown);
 type ListAdsInstagramAccountsData = {

package/dist/index.d.ts

@@ -3838,6 +3838,10 @@ type AdTracking = {
         key: string;
         value: string;
     }>;
+    /**
+     * POST /v1/ads/create on Meta and Google only. Every ad created there carries `zrn=<platform ad id>` on its landing URL so orders and events tied to the landing URL map back to the ad. Meta: `{ key: zrn, value: '{{ad.id}}' }` is appended after your `urlTags`, which are sent unchanged; a `zrn` key you send yourself is kept. Skipped for lead forms, call ads, `existingCreativeId` and app promotion. Google (Display and Search): the ad's `final_url_suffix` becomes the suffix it would inherit (ad group, campaign or account) plus `&zrn={creative}`, so your account and campaign UTMs still apply; if that suffix cannot be read or Google rejects it, the ad is created untagged. Existing ads are never changed. Set `false` to create the ad with no Zernio tag.
+     */
+    zernioTag?: boolean;
 };
 /**
  * Ad set (or ad group/line item depending on platform) with rolled-up metrics and child ads
@@ -47562,9 +47566,13 @@ type ListTikTokSmartPlusReviewsResponse = ({
      */
     pendingSmartPlusAdIds?: Array<(string)>;
     /**
-     * Seconds to wait before reading this page again, set only while `incomplete` is true and review reads are paused. Null when complete (stale items included), or when the page is incomplete without a quota pause (read it again right away).
+     * Seconds until Zernio calls TikTok's review endpoint for this advertiser and connection again (the stored pause with its jitter), set exactly when `refreshState` is `paused` or `refused`, stale items with nothing pending included. Always the same value as the `Retry-After` header, which is sent exactly when this is not null. Client rule: present, wait that long before reading the page again; null with stale or pending ads, a retry is not blocked (read again now or on your `maxAgeSeconds` schedule; with `refreshState: error` check `reviewError` first).
      */
     retryAfterSeconds?: (number) | null;
+    /**
+     * Whether this request could refresh the due (stale or pending) Smart+ ads of the page. `refused`: TikTok refused a review call of this request over quota (40002 `OVER_QPS_LIMIT` or 40100) and Zernio paused. `paused`: no call was sent for the due ads because a pause from an earlier refusal, or the spacing of at least 60 seconds after a success, is still running. Both carry `retryAfterSeconds`. `error`: TikTok refused the batch for another reason (both halves the same way), the page is served from stored reviews and `reviewError` holds TikTok's error; `retryAfterSeconds` is null because retrying soon repeats the refusal. `ok`: nothing blocks a retry (every due ad was read, none was due, or the split cap left some for the next read, which can come right away).
+     */
+    refreshState?: 'ok' | 'paused' | 'refused' | 'error';
 });
 type ListTikTokSmartPlusReviewsError = (ErrorResponse | unknown);
 type ListAdsInstagramAccountsData = {

package/dist/index.js

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@getlatedev/node",
-  version: "0.2.1331",
+  version: "0.2.1333",
   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.1331",
+  version: "0.2.1333",
   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.1331",
+  "version": "0.2.1333",
   "description": "The official Node.js library for the Zernio API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/generated/sdk.gen.ts

@@ -11778,9 +11778,10 @@ export const getAdReview = <ThrowOnError extends boolean = false>(options: Optio
  * can be up to 10 minutes old; an older one is read again. Read reviews when you need
  * them instead of sweeping every ad on a loop. When TikTok answers over quota, Zernio returns 429
  * and answers 429 for that advertiser and connection without calling TikTok for about 60 seconds, then
- * 120, 240, 480 and up to 960 while TikTok keeps refusing, and after an overage each successful call holds
- * the next one for one step less (480, 240, 120, then 60 seconds) until a success at 60 seconds ends it, each
- * with up to 10% of random jitter, with the time left as `Retry-After`; reviews read in the last 10 minutes are still served.
+ * 120, 240, 480 and up to 960 while TikTok keeps refusing. Each successful call holds the next one for the
+ * advertiser for at least 60 seconds (TikTok often refuses review calls sent in quick succession), and after an overage for one
+ * step less than the last pause (480, 240, 120, then 60 seconds). Each pause and hold has up to 10% of random
+ * jitter, with the time left as `Retry-After`; reviews read in the last 10 minutes are still served.
  */
 export const getTikTokSmartPlusAdReview = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<GetTikTokSmartPlusAdReviewData, ThrowOnError>) => {
     return (options?.client ?? client).get<GetTikTokSmartPlusAdReviewResponse, GetTikTokSmartPlusAdReviewError, ThrowOnError>({
@@ -12306,11 +12307,11 @@ export const getTikTokSmartPlusMaterialReport = <ThrowOnError extends boolean =
  *
  * Zernio lists the advertiser's Smart+ ads with `/smart_plus/ad/get/` (deleted ones only with `includeDeleted=true`) and reads `/smart_plus/ad/review_info/` for Smart+ ads holding up to 50 creatives in total per call (TikTok refuses more; a Smart+ ad with more than 50 creatives is read alone), across ad groups, one call after another. A full refresh of N Smart+ ads with C creatives in total costs about `ceil(N / 100)` listing calls and `ceil(C / 50)` review calls on TikTok. When TikTok still refuses a call for its creative count, Zernio lowers the creative cap for that advertiser and reads the same ads again in smaller calls, never resending the refused size.
  *
- * Stale while refreshing: every review is stored for 24 hours per connection, advertiser and Smart+ ad (shared with the single-ad read), and `readAt` is always the time TikTok answered, never rewritten when served from the store. `maxAgeSeconds` (default 3600) is the freshness window: a review read within it is fresh and costs no TikTok call; an older one is still returned in `items` but is read again, and so is a Smart+ ad never read. Each request first reads every Smart+ ad of the page never read (live, then deleted with `includeDeleted=true`) and only then refreshes stale ones, oldest `readAt` first, so a quota pause cannot leave never-read ads behind stale ones, progress carries over between requests and an ad already read never goes back to pending. A stored review is replaced only by a successful read. `counts` splits the Smart+ ads on this page into `fresh`, `stale`, `pending` and `failed`, and `oldestReadAt` is the oldest `readAt` of `items`. `incomplete` is true only while some Smart+ ad of the page has never been read (`pending > 0`). Staleness is reported apart: `allFresh` is true when every item and refusal of the page is within `maxAgeSeconds` and nothing is pending. A page with stale items and nothing pending is complete (`incomplete: false`, no `Retry-After`): move on, and a later read refreshes it oldest first. On 2026-10-25 TikTok's quota allowed about 130 to 230 Smart+ ads per advertiser per hour (about 11.5 ads and 4 creatives per successful call), so a larger advertiser cannot be fully refreshed within one hour and its pages stay complete but not `allFresh`.
+ * Stale while refreshing: every review is stored for 24 hours per connection, advertiser and Smart+ ad (shared with the single-ad read), and `readAt` is always the time TikTok answered, never rewritten when served from the store. `maxAgeSeconds` (default 3600) is the freshness window: a review read within it is fresh and costs no TikTok call; an older one is still returned in `items` but is read again, and so is a Smart+ ad never read. Each request first reads every Smart+ ad of the page never read (live, then deleted with `includeDeleted=true`) and only then refreshes stale ones, oldest `readAt` first, so a quota pause cannot leave never-read ads behind stale ones, progress carries over between requests and an ad already read never goes back to pending. A stored review is replaced only by a successful read. `counts` splits the Smart+ ads on this page into `fresh`, `stale`, `pending` and `failed`, and `oldestReadAt` is the oldest `readAt` of `items`. `incomplete` is true only while some Smart+ ad of the page has never been read (`pending > 0`). Staleness is reported apart: `allFresh` is true when every item and refusal of the page is within `maxAgeSeconds` and nothing is pending. A page with stale items and nothing pending is complete (`incomplete: false`): move on, and a later read refreshes it oldest first. When Zernio could not refresh some due ads of the page because review reads are held or TikTok refused them over quota, `refreshState` is `paused` or `refused` and `retryAfterSeconds` (also in the `Retry-After` header) says when that later read can reach TikTok, even with nothing pending. On 2026-10-25 TikTok's quota allowed about 130 to 230 Smart+ ads per advertiser per hour (about 11.5 ads and 4 creatives per successful call), so a larger advertiser cannot be fully refreshed within one hour and its pages stay complete but not `allFresh`.
  *
  * The listing is stored with the time it was read (`listing.readAt`) and listed again when it is older than `maxAgeSeconds`, so it can be up to `maxAgeSeconds` old: a Smart+ ad created on TikTok appears after at most that long (one hour by default). If that relisting fails, Zernio serves the stored listing with `listing.source: fallback` and the relist error in `listing.error`, instead of failing the request; `listing.source: fresh` means the listing was read within `maxAgeSeconds`. Only when no listing was ever stored does the listing error fail the request.
  *
- * TikTok's review endpoint has a strict quota of its own (TikTok documents neither the quota nor its scope). When it is over quota (or Zernio is holding review reads for this advertiser and connection after an overage: about 60 seconds, then 120, 240, 480 and up to 960 while TikTok keeps refusing, and after each successful call one step less, 480 down to 60 seconds, until a success at 60 seconds ends it, each with up to 10% of random jitter), Zernio stops calling TikTok and answers 200 with the reviews it has: stale reviews in `items`, the Smart+ ads never read in `pendingSmartPlusAdIds` and, when any are pending, `incomplete: true` with `retryAfterSeconds` (also in the `Retry-After` header). Every Smart+ ad of the page is in `items`, `failedSmartPlusAds` or `pendingSmartPlusAdIds`. Wait `retryAfterSeconds` and read the same page again: only the stale and pending ads reach TikTok.
+ * TikTok's review endpoint has a strict quota of its own (TikTok documents neither the quota nor its scope). TikTok often refuses review calls sent in quick succession, so Zernio holds the next call for this advertiser and connection for at least 60 seconds after every success, and one page reads one batch (up to 50 creatives) per minute at most. When TikTok is over quota (or Zernio is holding review reads: 60 seconds after a success, after an overage about 60 seconds, then 120, 240, 480 and up to 960 while TikTok keeps refusing, and after each successful call one step less, 480 down to 60 seconds, each with up to 10% of random jitter), Zernio stops calling TikTok and answers 200 with the reviews it has: stale reviews in `items`, the Smart+ ads never read in `pendingSmartPlusAdIds`, `incomplete: true` when any are pending, and `refreshState` (`paused` or `refused`) with `retryAfterSeconds` (also in the `Retry-After` header) whenever due ads were left unread. Every Smart+ ad of the page is in `items`, `failedSmartPlusAds` or `pendingSmartPlusAdIds`. Wait `retryAfterSeconds` and read the same page again: only the stale and pending ads reach TikTok.
  *
  * A Smart+ ad whose review TikTok refuses on its own (for example one deleted on TikTok since the listing was read) is returned in `failedSmartPlusAds` with TikTok's error and `refusedAt`, and the rest of the page is still read. Zernio finds it by splitting the refused batch in halves, at most 16 extra TikTok calls per page; ads still unresolved after that keep their stored review, or stay in `pendingSmartPlusAdIds` when they have none, and are read first by the next request. A refusal of a single ad is stored for 24 hours and read again once it is older than `maxAgeSeconds`; when an ad has both a stored review and a stored refusal, the more recent one is returned. When both halves of a refused batch are refused with the same TikTok error (for example a permission error), Zernio stops calling TikTok for that page: when every Smart+ ad of the page has a stored review or refusal, it serves them and returns the refusal in `reviewError`; when some ad was never read, the whole request fails with that error.
  *

package/src/generated/types.gen.ts

@@ -1802,6 +1802,10 @@ export type AdTracking = {
         key: string;
         value: string;
     }>;
+    /**
+     * POST /v1/ads/create on Meta and Google only. Every ad created there carries `zrn=<platform ad id>` on its landing URL so orders and events tied to the landing URL map back to the ad. Meta: `{ key: zrn, value: '{{ad.id}}' }` is appended after your `urlTags`, which are sent unchanged; a `zrn` key you send yourself is kept. Skipped for lead forms, call ads, `existingCreativeId` and app promotion. Google (Display and Search): the ad's `final_url_suffix` becomes the suffix it would inherit (ad group, campaign or account) plus `&zrn={creative}`, so your account and campaign UTMs still apply; if that suffix cannot be read or Google rejects it, the ad is created untagged. Existing ads are never changed. Set `false` to create the ad with no Zernio tag.
+     */
+    zernioTag?: boolean;
 };
 
 /**
@@ -48284,9 +48288,13 @@ export type ListTikTokSmartPlusReviewsResponse = ({
      */
     pendingSmartPlusAdIds?: Array<(string)>;
     /**
-     * Seconds to wait before reading this page again, set only while `incomplete` is true and review reads are paused. Null when complete (stale items included), or when the page is incomplete without a quota pause (read it again right away).
+     * Seconds until Zernio calls TikTok's review endpoint for this advertiser and connection again (the stored pause with its jitter), set exactly when `refreshState` is `paused` or `refused`, stale items with nothing pending included. Always the same value as the `Retry-After` header, which is sent exactly when this is not null. Client rule: present, wait that long before reading the page again; null with stale or pending ads, a retry is not blocked (read again now or on your `maxAgeSeconds` schedule; with `refreshState: error` check `reviewError` first).
      */
     retryAfterSeconds?: (number) | null;
+    /**
+     * Whether this request could refresh the due (stale or pending) Smart+ ads of the page. `refused`: TikTok refused a review call of this request over quota (40002 `OVER_QPS_LIMIT` or 40100) and Zernio paused. `paused`: no call was sent for the due ads because a pause from an earlier refusal, or the spacing of at least 60 seconds after a success, is still running. Both carry `retryAfterSeconds`. `error`: TikTok refused the batch for another reason (both halves the same way), the page is served from stored reviews and `reviewError` holds TikTok's error; `retryAfterSeconds` is null because retrying soon repeats the refusal. `ok`: nothing blocks a retry (every due ad was read, none was due, or the split cap left some for the next read, which can come right away).
+     */
+    refreshState?: 'ok' | 'paused' | 'refused' | 'error';
 });
 
 export type ListTikTokSmartPlusReviewsError = (ErrorResponse | unknown);