@zernio/node 0.2.99 → 0.2.101

package/src/generated/types.gen.ts

@@ -117,9 +117,56 @@ export type Ad = {
      */
     optimizationGoal?: (string) | null;
     /**
-     * Bid strategy (e.g. LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS). Ad set level overrides campaign level. Only present for Meta ads.
+     * Human-readable advertiser/account name (Meta `AdAccount.name`, TikTok
+     * `advertiser_name`, LinkedIn / X / Pinterest equivalents). Refreshed every
+     * sync so platform-side renames propagate within one cycle. `null` when the
+     * platform doesn't return a name or the sync hasn't run yet.
+     *
+     */
+    platformAdAccountName?: (string) | null;
+    /**
+     * Platform-reported creation timestamp (Meta `created_time`, TikTok `create_time`).
+     * Distinct from `createdAt` which reflects when Zernio first synced the doc — for
+     * sort/filter by "when the ad was actually created on the platform", read this field.
+     * `null` for legacy ads synced before this field was added; aggregations fall back
+     * to `createdAt` in that case.
+     *
+     */
+    platformCreatedAt?: (string) | null;
+    /**
+     * Ad-set bid strategy (overrides campaign level on Meta). Populated for Meta and
+     * TikTok. TikTok's native `bid_type` is normalized to the cross-platform Meta enum:
+     * `BID_TYPE_NO_BID` -> `LOWEST_COST_WITHOUT_CAP`, `BID_TYPE_CUSTOM` ->
+     * `LOWEST_COST_WITH_BID_CAP`, deep_bid_type=MIN_ROAS or roas_bid>0 ->
+     * `LOWEST_COST_WITH_MIN_ROAS`, `BID_TYPE_MAX_CONVERSION` -> `LOWEST_COST_WITHOUT_CAP`.
+     *
+     */
+    bidStrategy?: ((BidStrategy) | null);
+    /**
+     * Bid cap in WHOLE currency units of the ad account (USD: 5 = $5.00; JPY: 100 = ¥100).
+     * Populated when bidStrategy is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. `null` for
+     * auto-bid (`LOWEST_COST_WITHOUT_CAP`).
+     *
+     * - Meta source: `bid_amount` on the ad set (smallest-denomination int, decoded here).
+     * - TikTok source: priority order `bid_price` -> `conversion_bid_price` -> `deep_cpa_bid`
+     * (whichever is set on the ad group). TikTok stores all three in whole currency units.
+     *
+     * Source: facebook-business-sdk-codegen api_specs/specs/AdSet.json (`bid_amount`).
+     *
      */
-    bidStrategy?: (string) | null;
+    bidAmount?: (number) | null;
+    /**
+     * Minimum ROAS as a decimal multiplier (2.0 = 2.0x ROAS). Populated when bidStrategy
+     * is `LOWEST_COST_WITH_MIN_ROAS`.
+     *
+     * - Meta source: decoded from `bid_constraints.roas_average_floor` (Meta stores as
+     * fixed-point int × 10000; we return the decimal).
+     * - TikTok source: `roas_bid` on the ad group (already a decimal).
+     *
+     * Source: facebook-business-sdk-codegen api_specs/specs/AdCampaignBidConstraint.json.
+     *
+     */
+    roasAverageFloor?: (number) | null;
     /**
      * Meta promoted object containing conversion event details. Structure varies by objective. Only present for Meta ads.
      */
@@ -275,6 +322,10 @@ export type AdCampaign = {
     currency?: (string) | null;
     metrics?: AdMetrics;
     platformAdAccountId?: string;
+    /**
+     * Human-readable advertiser/account name from the platform. Refreshed on every sync.
+     */
+    platformAdAccountName?: (string) | null;
     accountId?: string;
     profileId?: string;
     /**
@@ -286,9 +337,17 @@ export type AdCampaign = {
      */
     optimizationGoal?: (string) | null;
     /**
-     * Campaign-level bid strategy (e.g. LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS)
+     * Campaign-level bid strategy. Ad sets inherit this unless they override.
+     */
+    bidStrategy?: ((BidStrategy) | null);
+    /**
+     * Representative bid cap from the top-spending ad set (whole currency units). Populated when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.
+     */
+    bidAmount?: (number) | null;
+    /**
+     * Representative ROAS floor from the top-spending ad set. Decimal multiplier (2.0 = 2.0x).
      */
-    bidStrategy?: (string) | null;
+    roasAverageFloor?: (number) | null;
     /**
      * Meta promoted object at campaign level (conversion event details)
      */
@@ -398,7 +457,15 @@ export type AdTreeAdSet = {
     /**
      * Bid strategy for this ad set (overrides campaign level when set)
      */
-    bidStrategy?: (string) | null;
+    bidStrategy?: ((BidStrategy) | null);
+    /**
+     * Bid cap in whole currency units. Populated when bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.
+     */
+    bidAmount?: (number) | null;
+    /**
+     * Minimum ROAS as a decimal multiplier (2.0 = 2.0x). Populated when bidStrategy is LOWEST_COST_WITH_MIN_ROAS.
+     */
+    roasAverageFloor?: (number) | null;
     /**
      * Meta promoted object for this ad set (conversion event details)
      */
@@ -477,6 +544,10 @@ export type AdTreeCampaign = {
     currency?: (string) | null;
     metrics?: AdMetrics;
     platformAdAccountId?: string;
+    /**
+     * Human-readable advertiser/account name from the platform. Refreshed on every sync.
+     */
+    platformAdAccountName?: (string) | null;
     accountId?: string;
     profileId?: string;
     /**
@@ -488,9 +559,17 @@ export type AdTreeCampaign = {
      */
     optimizationGoal?: (string) | null;
     /**
-     * Campaign-level bid strategy (e.g. LOWEST_COST_WITHOUT_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS)
+     * Campaign-level bid strategy. Ad sets inherit this unless they override.
+     */
+    bidStrategy?: ((BidStrategy) | null);
+    /**
+     * Representative bid cap for the campaign — bubbled up from the top-spending ad set's `bid_amount` (whole currency units). Populated when the ad-set bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP.
      */
-    bidStrategy?: (string) | null;
+    bidAmount?: (number) | null;
+    /**
+     * Representative ROAS floor for the campaign — bubbled up from the top-spending ad set. Decimal multiplier (2.0 = 2.0x).
+     */
+    roasAverageFloor?: (number) | null;
     /**
      * Meta promoted object at campaign level (conversion event details)
      */
@@ -659,6 +738,18 @@ export type scope = 'full' | 'profiles';
  */
 export type permission = 'read-write' | 'read';
 
+/**
+ * Meta bid strategy. Same enum applies at campaign and ad-set level; ad-set value (when set)
+ * overrides campaign-level. Cross-field rules:
+ * - `LOWEST_COST_WITHOUT_CAP` (default): auto-bid, forbids `bidAmount` and `roasAverageFloor`.
+ * - `LOWEST_COST_WITH_BID_CAP` / `COST_CAP`: require `bidAmount` (whole currency units).
+ * - `LOWEST_COST_WITH_MIN_ROAS`: requires `roasAverageFloor` (decimal multiplier, 2.0 = 2.0x).
+ * Source: facebook-business-sdk-codegen api_specs/specs/enum_types.json (`AdSet_bid_strategy`,
+ * `Campaign_bid_strategy`).
+ *
+ */
+export type BidStrategy = 'LOWEST_COST_WITHOUT_CAP' | 'LOWEST_COST_WITH_BID_CAP' | 'COST_CAP' | 'LOWEST_COST_WITH_MIN_ROAS';
+
 /**
  * Bluesky post settings. Supports text posts with up to 4 images or a single video. threadItems creates a reply chain (Bluesky thread). Images exceeding 1MB are automatically compressed. Alt text supported via mediaItem properties.
  *
@@ -674,6 +765,27 @@ export type BlueskyPlatformData = {
     }>;
 };
 
+/**
+ * TikTok Business Center entity. Returned by `GET /v1/ads/business-centers`. BCs are
+ * TikTok's agency container — one BC owns N advertisers (ad accounts). Most solo
+ * advertisers don't have one; the agency token uses BCs to roll up multi-client access.
+ *
+ */
+export type BusinessCenter = {
+    /**
+     * Business Center ID
+     */
+    bcId?: string;
+    /**
+     * Display name set by the BC owner
+     */
+    name?: string;
+    /**
+     * Number of advertisers (ad accounts) reachable under this BC for the calling token
+     */
+    advertiserCount?: number;
+};
+
 /**
  * A single conversion event to relay to the ad platform. All PII fields
  * (email, phone, names) are hashed with SHA-256 server-side using each
@@ -6026,6 +6138,9 @@ export type GetGoogleBusinessLocationDetailsData = {
         locationId?: string;
         /**
          * Comma-separated fields to return. Available: name, title, phoneNumbers, categories, storefrontAddress, websiteUri, regularHours, specialHours, serviceArea, serviceItems, profile, openInfo, metadata, moreHours.
+         * `title` and `metadata` are always included in the response so the `location` summary block can be populated, even if you omit them here.
+         * Note: `location` is a derived response field, not a Google readMask value, passing it returns 400.
+         *
          */
         readMask?: string;
     };
@@ -6036,11 +6151,11 @@ export type GetGoogleBusinessLocationDetailsResponse = ({
     accountId?: string;
     locationId?: string;
     /**
-     * Compact public-facing summary derived from `metadata`. Useful for
-     * surfacing the "leave a review" URL (e.g. behind a QR code) without
-     * parsing Google's raw `metadata` block. Populated when the readMask
-     * includes `metadata` (the default). For unverified or new locations,
-     * Google omits placeId/reviewUrl/mapsUri, so those return as null.
+     * Compact public-facing summary derived from Google's `metadata`. Useful
+     * for surfacing the "leave a review" URL (e.g. behind a QR code) without
+     * parsing the raw block. Always populated regardless of readMask.
+     * For unverified or new locations Google omits placeId/reviewUrl/mapsUri,
+     * so those return as null and `isVerified` is false.
      *
      */
     location?: {
@@ -12591,13 +12706,17 @@ export type UpdateAdCampaignStatusError = (unknown | {
 export type UpdateAdCampaignData = {
     body: {
         platform: 'facebook' | 'instagram';
-        budget: {
+        budget?: {
             /**
              * Budget amount in the ad account's currency
              */
             amount: number;
             type: 'daily' | 'lifetime';
         };
+        /**
+         * Campaign-level default. Ad sets inherit this unless they override.
+         */
+        bidStrategy?: (BidStrategy);
     };
     path: {
         /**
@@ -12611,6 +12730,7 @@ export type UpdateAdCampaignResponse = ({
     updated?: number;
     budget?: AdBudget;
     budgetLevel?: 'campaign';
+    bidStrategy?: BidStrategy;
 });
 
 export type UpdateAdCampaignError = (unknown | {
@@ -12673,7 +12793,7 @@ export type BulkUpdateAdCampaignStatusError = (unknown | {
 
 export type DuplicateAdCampaignData = {
     body: {
-        platform: 'facebook' | 'instagram';
+        platform: 'facebook' | 'instagram' | 'tiktok';
         /**
          * Copy child ad sets + ads + creatives + targeting
          */
@@ -12722,16 +12842,38 @@ export type UpdateAdSetData = {
     body: {
         platform: 'facebook' | 'instagram' | 'tiktok' | 'linkedin' | 'pinterest' | 'google' | 'twitter';
         /**
-         * Omit if only toggling status
+         * Omit if not updating budget
          */
         budget?: {
             amount?: number;
             type?: 'daily' | 'lifetime';
         };
         /**
-         * Omit if only updating budget
+         * Omit if not toggling delivery state
          */
         status?: 'active' | 'paused';
+        /**
+         * Ad-set-level bid strategy. Overrides the campaign-level default.
+         * Supported on Meta (facebook, instagram) and TikTok. On TikTok the
+         * Meta-style enum is mapped to bid_type / bid_price / deep_bid_type
+         * automatically. Other platforms (linkedin, pinterest, google, twitter)
+         * return 501 Not Implemented when bidStrategy is set.
+         *
+         */
+        bidStrategy?: (BidStrategy);
+        /**
+         * Bid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when
+         * bidStrategy is LOWEST_COST_WITH_BID_CAP or COST_CAP. Internally converted to Meta's
+         * smallest-denomination integer.
+         *
+         */
+        bidAmount?: number;
+        /**
+         * Minimum ROAS as a decimal multiplier (2.0 = 2.0x). Required when bidStrategy is
+         * LOWEST_COST_WITH_MIN_ROAS. Sent to Meta as `bid_constraints.roas_average_floor` × 10000.
+         *
+         */
+        roasAverageFloor?: number;
     };
     path: {
         /**
@@ -12747,6 +12889,9 @@ export type UpdateAdSetResponse = ({
     status?: 'active' | 'paused';
     statusUpdated?: number;
     statusSkipped?: number;
+    bidStrategy?: BidStrategy;
+    bidAmount?: (number) | null;
+    roasAverageFloor?: (number) | null;
 });
 
 export type UpdateAdSetError = (unknown | {
@@ -12851,7 +12996,8 @@ export type UpdateAdData = {
             type?: 'daily' | 'lifetime';
         };
         /**
-         * Meta-only. Targeting updates for other platforms are not supported after creation.
+         * Meta + TikTok only. Pinterest / X / LinkedIn / Google return 501.
+         *
          */
         targeting?: {
             ageMin?: number;
@@ -12869,6 +13015,28 @@ export type UpdateAdData = {
              */
             advantage_audience?: 0 | 1;
         };
+        /**
+         * Replace the ad's creative. Meta + TikTok only.
+         *
+         * - **Meta**: requires `headline`, `body`, `callToAction`, `linkUrl`, `imageUrl`. The
+         * ad's existing creative is replaced via a new `/act_X/adcreatives` upload + ad
+         * update. The old creative is retained on the ad account for historical reporting.
+         * - **TikTok**: patch-style. Pass any subset; `headline` is ignored (TikTok creatives
+         * have no headline slot). `body` becomes the in-feed `ad_text`; `linkUrl` becomes
+         * `landing_page_url`; `videoUrl` triggers a fresh upload.
+         *
+         */
+        creative?: {
+            /**
+             * Meta only
+             */
+            headline?: string;
+            body?: string;
+            callToAction?: string;
+            linkUrl?: string;
+            imageUrl?: string;
+            videoUrl?: string;
+        };
         name?: string;
     };
     path: {
@@ -12994,12 +13162,62 @@ export type GetAdCommentsError = (unknown | {
     error?: string;
 });
 
+export type ListAdsBusinessCentersData = {
+    query: {
+        /**
+         * ID of the `tiktokads` (or parent `tiktok` posting) SocialAccount
+         */
+        accountId: string;
+    };
+};
+
+export type ListAdsBusinessCentersResponse = ({
+    businessCenters?: Array<BusinessCenter>;
+});
+
+export type ListAdsBusinessCentersError = ({
+    error?: string;
+} | unknown);
+
+export type TriggerAdsInitialSyncData = {
+    body: {
+        /**
+         * ID of the ads SocialAccount to re-sync (e.g. `metaads` / `tiktokads` doc).
+         * Posting accounts (`facebook` / `tiktok`) are rejected — pass the ads-side
+         * account ID that owns the platform tokens.
+         *
+         */
+        accountId: string;
+    };
+};
+
+export type TriggerAdsInitialSyncResponse = ({
+    status?: 'queued' | 'already_queued';
+    /**
+     * Trace ID for the enqueued job. Reused on `already_queued`.
+     */
+    traceId?: (string) | null;
+    message?: string;
+});
+
+export type TriggerAdsInitialSyncError = (unknown | {
+    error?: string;
+});
+
 export type ListAdAccountsData = {
     query: {
         /**
          * Social account ID
          */
         accountId: string;
+        /**
+         * Filter response to a single platform ad account ID (e.g. `act_123` for Meta, advertiser_id for TikTok). Returns at most one item.
+         */
+        adAccountId?: string;
+        /**
+         * Clamp the returned `accounts[]` length. Useful for typeahead pickers on agency tokens with hundreds of advertisers.
+         */
+        limit?: number;
     };
 };
 
@@ -13082,9 +13300,25 @@ export type BoostPostData = {
             advantage_audience?: 0 | 1;
         };
         /**
-         * Max bid cap (Meta only)
+         * Meta bid strategy applied to the ad set. On TikTok, mapped to
+         * `bid_type` / `bid_price` / `deep_bid_type` automatically.
+         *
+         */
+        bidStrategy?: (BidStrategy);
+        /**
+         * Bid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when
+         * `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`. Backward-compat: providing
+         * `bidAmount` without `bidStrategy` is treated as `LOWEST_COST_WITH_BID_CAP`.
+         *
          */
         bidAmount?: number;
+        /**
+         * Minimum ROAS as a decimal multiplier (e.g. 2.0 = 2.0x ROAS). Required when
+         * `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`. Sent to Meta as
+         * `bid_constraints.roas_average_floor` × 10000 (Meta uses fixed-point integers).
+         *
+         */
+        roasAverageFloor?: number;
         /**
          * Meta only. Tracking specs (pixel, URL tags).
          */
@@ -13096,6 +13330,34 @@ export type BoostPostData = {
          * Meta only. Required for housing, employment, credit, or political ads.
          */
         specialAdCategories?: Array<('HOUSING' | 'EMPLOYMENT' | 'CREDIT' | 'ISSUES_ELECTIONS_POLITICS')>;
+        /**
+         * TikTok-only. Custom destination URL for the Spark Ad. Without this, TikTok
+         * Spark Ads have no clickable destination — required for traffic / conversion
+         * objectives. Maps to `landing_page_url` on the creative entry of /v2/ad/create/
+         * (TikTok SDK `AdcreateCreatives.landing_page_url`). Ignored on Meta / LinkedIn /
+         * Pinterest / X / Google (those infer the destination from the boosted post).
+         *
+         */
+        linkUrl?: string;
+        /**
+         * TikTok-only. Call-to-action button label on the Spark Ad creative (e.g.
+         * `LEARN_MORE`, `SHOP_NOW`, `DOWNLOAD_NOW`, `SIGN_UP`, `WATCH_NOW`). Maps to
+         * `call_to_action` on the creative entry of /v2/ad/create/. Pass-through —
+         * the platform validates the value. See TikTok's "Enumeration - Call-to-Action"
+         * reference for the full list.
+         *
+         */
+        callToAction?: string;
+        /**
+         * TikTok-only. Spark Code (creator's `auth_code`) authorizing cross-creator
+         * Spark Ads — the advertiser can boost a video owned by a DIFFERENT TikTok
+         * account. Without this, boosts are limited to videos owned by the same
+         * account running the ads (same-BC creators only). The creator generates the
+         * code in their TikTok app's Promote settings and shares it with the
+         * advertiser. Maps to `auth_code` on the creative entry of /v2/ad/create/.
+         *
+         */
+        sparkAuthCode?: string;
         /**
          * Name of the legal entity benefiting from the ad.
          * Required by Meta when targeting EU users (DSA Article 26).
@@ -13217,8 +13479,15 @@ export type CreateStandaloneAdData = {
         /**
          * Meta-only. When present, switches to the attach shape: adds
          * one new ad to this existing ad set without creating a new
-         * campaign. Budget, targeting, goal, and schedule are inherited
-         * from the ad set on Meta. Mutually exclusive with `creatives[]`.
+         * campaign. Budget, targeting, goal, schedule, AND bid strategy
+         * are inherited from the ad set on Meta — passing `bidStrategy`
+         * in attach mode returns 400. To change an existing ad set's
+         * bid, use `PUT /v1/ads/ad-sets/{adSetId}`. Mutually exclusive
+         * with `creatives[]`.
+         *
+         * Supported on Meta (facebook, instagram) and TikTok. On TikTok
+         * the `adSetId` is the ad group ID; the new ad inherits the
+         * ad group's bid + budget + targeting.
          *
          */
         adSetId?: string;
@@ -13272,6 +13541,23 @@ export type CreateStandaloneAdData = {
          * Meta only. Restrict the audience by gender. 'male' targets men only, 'female' targets women only, 'all' (default) targets everyone. Ignored by non-Meta platforms.
          */
         gender?: 'all' | 'male' | 'female';
+        /**
+         * Meta bid strategy applied to the ad set.
+         */
+        bidStrategy?: (BidStrategy);
+        /**
+         * Bid cap in WHOLE currency units (USD: 5 = $5.00; JPY: 100 = ¥100). Required when
+         * `bidStrategy` is `LOWEST_COST_WITH_BID_CAP` or `COST_CAP`.
+         *
+         */
+        bidAmount?: number;
+        /**
+         * Minimum ROAS as a decimal multiplier (e.g. 2.0 = 2.0x ROAS). Required when
+         * `bidStrategy` is `LOWEST_COST_WITH_MIN_ROAS`. Sent to Meta as
+         * `bid_constraints.roas_average_floor` × 10000.
+         *
+         */
+        roasAverageFloor?: number;
         /**
          * Name of the legal entity benefiting from the ad.
          * Required by Meta when targeting EU users (DSA Article 26).