@zernio/node 0.2.990 → 0.2.992

package/src/generated/sdk.gen.ts

@@ -9226,6 +9226,18 @@ export const removeAdKeyword = <ThrowOnError extends boolean = false>(options: O
  * Google campaign budgets include amountMicros, explicitlyShared, resourceName and
  * deliveryMethod after the next successful sync. This endpoint does not fetch Google live.
  *
+ * **Status freshness.** `status`, `configuredStatus`, `platformStatus`, `platformAdSetStatus`
+ * and `platformCampaignStatus` are the values Zernio last stored. Background sync refreshes
+ * them, typically within 15 to 60 minutes (Google up to about 3 hours), and ended or
+ * long-paused objects may be refreshed less often. Zernio's own status writes re-read the
+ * switches they change. A change made in the platform's own ads manager therefore shows up
+ * here only after the next sync. Controllers that act on a switch should pass `live=true`,
+ * which reads the switches from the platform now, stores them, and returns `statusReadAt`
+ * (null when the read failed and the stored values were returned).
+ * With `live=true` (which needs `limit` of 20 or less) each returned campaign's own switch
+ * (`platformCampaignStatus`) is read live. Live reads cover TikTok, Meta, Google and OpenAI.
+ * The rolled-up `status` is not re-derived by a live read.
+ *
  */
 export const listAdCampaigns = <ThrowOnError extends boolean = false>(options?: OptionsLegacyParser<ListAdCampaignsData, ThrowOnError>) => {
     return (options?.client ?? client).get<ListAdCampaignsResponse, ListAdCampaignsError, ThrowOnError>({
@@ -9262,12 +9274,26 @@ export const createAdCampaign = <ThrowOnError extends boolean = false>(options:
 /**
  * Pause or resume a campaign
  * Writes the campaign's own on/off switch, then lets the platform cascade delivery to its ad sets and ads.
- * Makes one platform API call, not one per ad.
+ *
+ * **What the write touches (current semantics, per platform).** TikTok: the campaign, every
+ * ad group and every ad under it that is not in a terminal status (rejected, completed,
+ * cancelled), on pause and on resume alike, so a resume also switches those ad groups and ads
+ * on. LinkedIn: the campaign group plus the campaigns and creatives of its non-terminal ads.
+ * Google: `paused` writes the campaign alone; `active` also switches on the ad groups and ads
+ * Zernio tracks under it (see below). Pinterest: the campaign plus one tracked ad and its ad
+ * group. X: the campaign plus one tracked line item. Meta and ChatGPT (OpenAI): the campaign
+ * switch only.
+ *
+ * **Counts and readback.** Before the write, each ad's own switch is read live from the
+ * platform (up to 20 ads; beyond that the stored switch is used), and `updated` / `skipped`
+ * are computed against that live state. After the write each ad's own switch and delivery
+ * status are read again and stored, and the campaign switch is re-read and stored, so an
+ * immediate GET returns what the platform now reports.
  *
  * The switch is always written, whatever delivery status the ads underneath report: an ad still in review
  * does not block resuming its campaign. The echoed `status` is the confirmation that it landed.
  *
- * `updated` / `skipped` describe only the ads whose own stored status CHANGED alongside it, so
+ * `updated` / `skipped` describe only the ads whose own status changed alongside it, so
  * `updated: 0` is a normal successful response, not a no-op. Ads are skipped when they are in a terminal
  * status (rejected, completed, cancelled), already in the target state, or switched on but not yet
  * delivering. The last group keeps its `pending_review` / `error` status until the platform reports what
@@ -9495,7 +9521,9 @@ export const replaceCampaignNegativeKeywords = <ThrowOnError extends boolean = f
  * Pause or resume many campaigns
  * Process up to 50 campaigns in one call. Each campaign is updated
  * concurrently and the response contains a per-campaign result so a
- * single bad row does not fail the whole batch.
+ * single bad row does not fail the whole batch. Each campaign is written,
+ * counted and re-read exactly as PUT /v1/ads/campaigns/{campaignId}/status
+ * describes, including which child ad sets and ads each platform writes.
  *
  */
 export const bulkUpdateAdCampaignStatus = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<BulkUpdateAdCampaignStatusData, ThrowOnError>) => {
@@ -9628,6 +9656,19 @@ export const updateCampaignTargeting = <ThrowOnError extends boolean = false>(op
  * Google only) is visible here even though it is invisible in the tree
  * until an ad joins it via `adSetId` on POST /v1/ads/create. Returns at most 500
  * rows, newest first.
+ *
+ * **Status freshness.** `status`, `configuredStatus`, `platformStatus`, `platformAdSetStatus`
+ * and `platformCampaignStatus` are the values Zernio last stored. Background sync refreshes
+ * them, typically within 15 to 60 minutes (Google up to about 3 hours), and ended or
+ * long-paused objects may be refreshed less often. Zernio's own status writes re-read the
+ * switches they change. A change made in the platform's own ads manager therefore shows up
+ * here only after the next sync. Controllers that act on a switch should pass `live=true`,
+ * which reads the switches from the platform now, stores them, and returns `statusReadAt`
+ * (null when the read failed and the stored values were returned).
+ * With `live=true` (which needs a `campaignId` or `adSetId` filter) each listed ad set's own
+ * switch (`platformAdSetStatus`) is read live, for the first 20 rows; later rows keep their
+ * synced value with `statusReadAt: null`. Live reads cover TikTok, Meta, Google and OpenAI.
+ * The rolled-up `status` is not re-derived by a live read.
  */
 export const listAdSets = <ThrowOnError extends boolean = false>(options?: OptionsLegacyParser<ListAdSetsData, ThrowOnError>) => {
     return (options?.client ?? client).get<ListAdSetsResponse, ListAdSetsError, ThrowOnError>({
@@ -9752,6 +9793,11 @@ export const getAdSetDetails = <ThrowOnError extends boolean = false>(options: O
  * CBO, the response is 409 with code BUDGET_LEVEL_MISMATCH. Route to
  * PUT /v1/ads/campaigns/{campaignId} instead.
  *
+ * `status` behaves exactly as PUT /v1/ads/ad-sets/{adSetId}/status
+ * describes, including which child ads each platform writes with the ad
+ * set and how `statusUpdated` / `statusSkipped` are counted against the
+ * ads' live switches.
+ *
  */
 export const updateAdSet = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<UpdateAdSetData, ThrowOnError>) => {
     return (options?.client ?? client).put<UpdateAdSetResponse, UpdateAdSetError, ThrowOnError>({
@@ -9791,13 +9837,26 @@ export const deleteAdSet = <ThrowOnError extends boolean = false>(options: Optio
  * status, LinkedIn campaign, Pinterest ad group, X line item, OpenAI ad
  * group), whatever delivery status its ads report: an ad still in review
  * or paused by its campaign does not block it. The echoed `status` is the
- * confirmation that it landed. On TikTok, Pinterest and OpenAI the ads
- * whose own switch is not yet in the target state are flipped with it.
- *
- * `updated` / `skipped` describe only the ads whose own stored status
- * CHANGED alongside the switch, so `updated: 0` is a normal successful
- * response. See `skippedReasons` for which of the three cases applies
- * (terminal, already in the target state, or switched on but not yet
+ * confirmation that it landed.
+ *
+ * **What the write touches (current semantics, per platform).** On TikTok the ad group AND
+ * every ad under it that is not in a terminal status (rejected, completed, cancelled) are
+ * written to the target state, on pause and on resume alike, so a resume also switches those
+ * ads on. Pinterest and ChatGPT (OpenAI) do the same with their ads. On Meta, Google, LinkedIn
+ * (campaign) and X (line item) only the ad set's own switch is written and each ad keeps its
+ * own switch.
+ *
+ * **Counts and readback.** Before the write, each ad's own switch is read live from the
+ * platform (up to 20 ads; beyond that the stored switch is used), and `updated` / `skipped`
+ * are computed against that live state, not against a stored switch a change in the
+ * platform's UI may have left stale. After the write each ad's own switch and delivery
+ * status are read again and stored, and the ad set switch is re-read and stored, so an
+ * immediate GET returns what the platform now reports.
+ *
+ * `updated` / `skipped` describe only the ads whose own status changed
+ * alongside the switch, so `updated: 0` is a normal successful response.
+ * See `skippedReasons` for which of the three cases applies (terminal,
+ * own switch already in the target state, or switched on but not yet
  * delivering).
  *
  * A campaign created paused needs its campaign resumed as well: pair this
@@ -9884,6 +9943,18 @@ export const getAdsTimeline = <ThrowOnError extends boolean = false>(options: Op
  * `creative.creativeFeatures` holds the stored requested settings, which do not confirm
  * platform application.
  *
+ * **Status freshness.** `status`, `configuredStatus`, `platformStatus`, `platformAdSetStatus`
+ * and `platformCampaignStatus` are the values Zernio last stored. Background sync refreshes
+ * them, typically within 15 to 60 minutes (Google up to about 3 hours), and ended or
+ * long-paused objects may be refreshed less often. Zernio's own status writes re-read the
+ * switches they change. A change made in the platform's own ads manager therefore shows up
+ * here only after the next sync. Controllers that act on a switch should pass `live=true`,
+ * which reads the switches from the platform now, stores them, and returns `statusReadAt`
+ * (null when the read failed and the stored values were returned).
+ * With `live=true` the ad's own switch (`configuredStatus`), its delivery status (`status`,
+ * `platformStatus`) and its ad set and campaign switches (`platformAdSetStatus`,
+ * `platformCampaignStatus`) are read live.
+ *
  */
 export const getAd = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<GetAdData, ThrowOnError>) => {
     return (options?.client ?? client).get<GetAdResponse, GetAdError, ThrowOnError>({

package/src/generated/types.gen.ts

@@ -502,6 +502,10 @@ export type AdCampaign = {
      * Raw platform-level campaign status (Meta `effective_status`; ChatGPT (OpenAI): the campaign's own switch, active / paused / archived; TikTok: the campaign's own switch `operation_status`, ENABLE / DISABLE).
      */
     platformCampaignStatus?: (string) | null;
+    /**
+     * Only on GET /v1/ads/campaigns with `live=true`. When `platformCampaignStatus` was read from the platform; null when this campaign could not be read live.
+     */
+    statusReadAt?: (string) | null;
     /**
      * Platform-reported campaign issues (Meta `issues_info[]`).
      */
@@ -1141,11 +1145,11 @@ export type AdPromotedObject = {
      */
     customConversionId?: string;
     /**
-     * Optional catalog ID. If supplied with productSetId, the set must belong to this catalog. A catalog ID cannot replace productSetId.
+     * Optional catalog ID. If supplied with productSetId, the set must belong to this catalog (checked by Zernio when the Meta login carries catalog_management, by Meta otherwise). A catalog ID cannot replace productSetId.
      */
     productCatalogId?: string;
     /**
-     * Meta product SET ID from GET /v1/ads/catalogs/{catalogId}/product-sets. Zernio checks that the token can read the set and its product_catalog before creation. A catalog ID or inaccessible set returns a precise 400 naming promotedObject.productSetId. A mismatch with productCatalogId names promotedObject.productCatalogId.
+     * Meta product SET ID, for example from GET /v1/ads/catalogs/{catalogId}/product-sets. Creating catalog ads needs only ads_management on the Meta login, not catalog_management. Zernio checks before creation that the set is visible to the token, and a set it cannot see returns a 400 naming promotedObject.productSetId (a catalog ID is caught the same way when the login carries catalog_management, and rejected by Meta otherwise). When the login can also read the set's catalog (catalog_management), a mismatch with productCatalogId returns a 400 naming promotedObject.productCatalogId; otherwise Meta judges the catalog match. With validateOnly and a new campaign, Meta cannot dry-run the set inside the ad set, so the adSet result carries a reason; pass existingCampaignId to dry-run it in full.
      */
     productSetId?: string;
     /**
@@ -7717,6 +7721,11 @@ export type ParameterCatalogTokenAccountId = string;
  */
 export type ParameterIdempotencyKeyHeader = string;
 
+/**
+ * Read the on/off switches live from the platform instead of returning the synced values. The fresh values are stored (so later reads return them too) and the response carries `statusReadAt`, the time of the read. At most 20 platform objects are read per request. Where a read fails (credentials, platform error, no reader on that platform), the stored values come back with `statusReadAt: null`. See "Status freshness" in the operation description.
+ */
+export type ParameterLiveStatusRead = boolean;
+
 /**
  * Page number (1-based)
  */
@@ -37960,6 +37969,10 @@ export type ListAdCampaignsData = {
          */
         includeEmpty?: boolean;
         limit?: number;
+        /**
+         * Read the on/off switches live from the platform instead of returning the synced values. The fresh values are stored (so later reads return them too) and the response carries `statusReadAt`, the time of the read. At most 20 platform objects are read per request. Where a read fails (credentials, platform error, no reader on that platform), the stored values come back with `statusReadAt: null`. See "Status freshness" in the operation description.
+         */
+        live?: boolean;
         /**
          * Return only campaigns whose spend between `fromDate` and `toDate` reaches this amount, in each campaign's OWN currency (the `currency` field on the campaign). Implies `hasDelivery`; `minSpend=0` applies no filter. Mirrors the same filter on /v1/ads/tree.
          */
@@ -38798,10 +38811,18 @@ export type ListAdSetsData = {
          * Account ID
          */
         accountId?: string;
+        /**
+         * Platform ad set ID
+         */
+        adSetId?: string;
         /**
          * Platform campaign ID
          */
         campaignId?: string;
+        /**
+         * Read the on/off switches live from the platform instead of returning the synced values. The fresh values are stored (so later reads return them too) and the response carries `statusReadAt`, the time of the read. At most 20 platform objects are read per request. Where a read fails (credentials, platform error, no reader on that platform), the stored values come back with `statusReadAt: null`. See "Status freshness" in the operation description.
+         */
+        live?: boolean;
         platform?: 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter' | 'openai';
     };
 };
@@ -38880,6 +38901,10 @@ export type ListAdSetsResponse = ({
         } | null;
         isExternal?: (boolean) | null;
         platformCreatedAt?: (string) | null;
+        /**
+         * Only with `live=true`. When `platformAdSetStatus` was read from the platform; null when this row was not read live.
+         */
+        statusReadAt?: (string) | null;
     }>;
 });
 
@@ -39419,6 +39444,12 @@ export type GetAdData = {
          */
         adId: string;
     };
+    query?: {
+        /**
+         * Read the on/off switches live from the platform instead of returning the synced values. The fresh values are stored (so later reads return them too) and the response carries `statusReadAt`, the time of the read. At most 20 platform objects are read per request. Where a read fails (credentials, platform error, no reader on that platform), the stored values come back with `statusReadAt: null`. See "Status freshness" in the operation description.
+         */
+        live?: boolean;
+    };
 };
 
 export type GetAdResponse = ({
@@ -39431,6 +39462,10 @@ export type GetAdResponse = ({
      * Whether Google RSA details use the last successful cached response.
      */
     stale?: boolean;
+    /**
+     * Only with `live=true`. When the switches were read from the platform; null when the live read failed and the stored values were returned.
+     */
+    statusReadAt?: (string) | null;
 });
 
 export type GetAdError = (ErrorResponse | {