@encorekit/web-sdk 2.0.4 → 2.0.7

package/examples/ios-webview/SimpleExample.swift

@@ -1,114 +1,59 @@
 //
 //  SimpleExample.swift
-//  Encore iOS Simple Integration
+//  Encore hosted offer page, UIKit usage
 //
-//  The simplest possible integration - just open a URL in WKWebView
+//  The simplest possible integration: build a URL, open it in a WKWebView.
+//
+//  Requires `EncoreURLBuilder.swift`. The SwiftUI equivalent lives in
+//  `SimpleEncoreView.swift`.
 //
 
 import UIKit
 import WebKit
 
-class SimpleEncoreViewController: UIViewController {
-    
+final class SimpleEncoreViewController: UIViewController {
+
     private var webView: WKWebView!
-    
+
     override func viewDidLoad() {
         super.viewDidLoad()
-        
-        // 1. Create WKWebView
+
+        // 1. Create the webview.
         webView = WKWebView(frame: view.bounds)
         webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
-        webView.backgroundColor = .clear
-        webView.isOpaque = false
         view.addSubview(webView)
-        
-        // 2. Build Encore URL
-        let url = EncoreURL.build(
-            apiKey: "your_api_key_here",
-            userId: "user_123",
-            environment: "production",
-            attributes: [
-                "email": "user@example.com",
-                "subscriptionTier": "free"
-            ]
-        )!
-        
-        // 3. Load it!
-        webView.load(URLRequest(url: url))
-        
-        // That's it! The embed will auto-initialize and show offers.
-    }
-}
-
-// MARK: - SwiftUI Version
-
-import SwiftUI
 
-struct SimpleEncoreView: View {
-    var body: some View {
-        EncoreWebView(
-            apiKey: "your_api_key_here",
+        // 2. Build the URL. Only coarse targeting values belong here: the page
+        //    refuses email, phone, names and precise location, and says so.
+        guard let url = EncoreURL.build(
+            apiKey: "pk_live_your_key_here",
             userId: "user_123",
             attributes: [
-                "email": "user@example.com",
-                "subscriptionTier": "free"
-            ]
-        )
-    }
-}
+                "subscriptionTier": "free",
+                "countryCode": "US",
+            ],
+            custom: ["plan": "gold"]
+        ) else { return }
 
-struct EncoreWebView: UIViewRepresentable {
-    let apiKey: String
-    let userId: String?
-    let environment: String
-    let attributes: [String: String]?
-    
-    init(
-        apiKey: String,
-        userId: String? = nil,
-        environment: String = "production",
-        attributes: [String: String]? = nil
-    ) {
-        self.apiKey = apiKey
-        self.userId = userId
-        self.environment = environment
-        self.attributes = attributes
-    }
-    
-    func makeUIView(context: Context) -> WKWebView {
-        let webView = WKWebView()
-        webView.backgroundColor = .clear
-        webView.isOpaque = false
-        
-        if let url = EncoreURL.build(
-            apiKey: apiKey,
-            userId: userId,
-            environment: environment,
-            attributes: attributes
-        ) {
-            webView.load(URLRequest(url: url))
-        }
-        
-        return webView
-    }
-    
-    func updateUIView(_ webView: WKWebView, context: Context) {
-        // No updates needed
+        // 3. Load it. Nothing else is required: no message handler to register,
+        //    no bridge to install, no delegate to implement.
+        webView.load(URLRequest(url: url))
     }
 }
 
-// MARK: - Usage Examples
+// MARK: - Presentation patterns
 
 extension SimpleEncoreViewController {
-    
-    /// Example: Show in cancellation flow
+
+    /// Present from a cancellation flow, where the churn carousel fits better
+    /// than the page's default reward sheet.
     static func showInCancellationFlow(from viewController: UIViewController) {
         let encoreVC = SimpleEncoreViewController()
         encoreVC.modalPresentationStyle = .fullScreen
         viewController.present(encoreVC, animated: true)
     }
-    
-    /// Example: Show as modal sheet
+
+    /// Present as a sheet.
     static func showAsSheet(from viewController: UIViewController) {
         let encoreVC = SimpleEncoreViewController()
         if let sheet = encoreVC.sheetPresentationController {
@@ -117,8 +62,8 @@ extension SimpleEncoreViewController {
         }
         viewController.present(encoreVC, animated: true)
     }
-    
-    /// Example: Embed in existing view
+
+    /// Embed in an existing view.
     static func embedInView(_ containerView: UIView, parentVC: UIViewController) {
         let encoreVC = SimpleEncoreViewController()
         parentVC.addChild(encoreVC)
@@ -128,4 +73,3 @@ extension SimpleEncoreViewController {
         encoreVC.didMove(toParent: parentVC)
     }
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@encorekit/web-sdk",
-  "version": "2.0.4",
+  "version": "2.0.7",
   "type": "module",
   "description": "Encore SDK for web applications - display targeted offers and manage user entitlements",
   "main": "./dist/cjs/index.cjs",
@@ -24,19 +24,15 @@
   "files": [
     "dist",
     "types",
-    "embed/dist",
-    "embed/index.html",
-    "embed/styles.css",
     "embed/README.md",
     "examples",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "npm run build:types && npm run build:bundle && npm run build:embed",
+    "build": "npm run build:types && npm run build:bundle",
     "build:types": "tsc -p tsconfig.types.json --emitDeclarationOnly",
     "build:bundle": "rollup -c",
-    "build:embed": "rollup -c --config-embed",
     "build:watch": "rollup -c -w",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -50,7 +46,6 @@
     "demo:backend": "ENV_FILE=.env.local node demo/backend.js",
     "demo:dev": "concurrently -n watch,backend,mock,frontend -c blue,magenta,yellow,green \"npm run build:watch\" \"npm run demo:backend\" \"npm run demo:mock\" \"npm run demo:frontend\"",
     "dev:example": "bash scripts/dev-example.sh",
-    "embed:serve": "http-server -p 3001 -o embed/index.html",
     "clean:examples": "bash scripts/clean-examples.sh",
     "prepublishOnly": "npm test && npm run build && npm run clean:examples",
     "pack:local": "npm run build && npm run clean:examples && npm pack",

package/types/api/APIClient.d.ts

@@ -5,6 +5,7 @@
  */
 import type { UserAttributes, Entitlement, VerificationStatus, UseCase } from '../types';
 import type { StartTransactionResponse, InitUserResponse, IdentifyUserResponse, RemoteConfigResponse, OfferModel, BackendVerificationStatus } from './models';
+import type { ErrorContext } from '../core/errorContext';
 interface RequestOptions {
     method: 'GET' | 'POST' | 'PATCH';
     headers?: Record<string, string>;
@@ -119,7 +120,8 @@ export declare class APIClient {
     reportError(params: {
         errorType: string;
         message: string;
-        context: string;
+        /** Typed so the backend's `[errorType, context]` fingerprint groups with iOS and Android. */
+        context: ErrorContext;
         severity?: 'fatal' | 'error' | 'warning' | 'info';
         stackTrace?: string;
         userId?: string;

package/types/api/APIClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"APIClient.d.ts","sourceRoot":"","sources":["../../src/api/APIClient.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"APIClient.d.ts","sourceRoot":"","sources":["../../src/api/APIClient.ts"],"names":[],"mappings":"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"}

package/types/api/errorReportLimits.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Field limits for `POST /errors`, copied from the endpoint's own Zod schema
+ * (`backend/packages/core/src/infrastructure/errors/schema.ts`).
+ *
+ * These matter because Zod rejects the WHOLE report when one field is over
+ * length. The 400 is not a truncated report, it is no report. And the failure
+ * is worst exactly where the report is most valuable: a deep stack in a
+ * minified production bundle is both the most likely to exceed 10000
+ * characters and the hardest to reproduce locally.
+ *
+ * Keep these in step with the schema. A limit that drifts too high loses
+ * reports again; one that drifts too low only costs detail.
+ */
+export declare const ERROR_REPORT_LIMITS: {
+    readonly errorType: 100;
+    readonly message: 2000;
+    readonly context: 200;
+    readonly stackTrace: 10000;
+    readonly underlyingError: 2000;
+    readonly appBundleId: 200;
+    readonly userId: 200;
+    readonly metadataValue: 500;
+};
+/** Stand-ins for the `.min(1)` fields when the value we have is empty. */
+export declare const ERROR_REPORT_FALLBACKS: {
+    readonly message: "Unknown error";
+    readonly appBundleId: "unknown";
+};
+/**
+ * Clips a field to its limit and says so.
+ *
+ * Keeps the START of the value. For a stack trace that is the frames nearest
+ * the throw, which is the diagnostic half; the tail is framework noise. The
+ * marker is what stops a reader in Sentry or Cloud Logging reading a clipped
+ * trace as a shallow one.
+ */
+export declare function bounded(value: string, limit: number): string;
+/**
+ * Bounds a field that the schema also requires to be non-empty.
+ *
+ * `message` and `appBundleId` carry `.min(1)` as well as a `.max()`, and both
+ * can legitimately arrive empty: `new Error()` has `message === ''`, and
+ * `window.location.hostname` is `''` on a `file://` page or a sandboxed iframe.
+ * An empty value fails validation exactly as an over-long one does, and loses
+ * the whole report the same way.
+ */
+export declare function boundedNonEmpty(value: string, limit: number, fallback: string): string;
+/** Bounds every value of a metadata record, dropping nothing. */
+export declare function boundedMetadata(metadata: Record<string, string>): Record<string, string>;
+//# sourceMappingURL=errorReportLimits.d.ts.map

package/types/api/errorReportLimits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorReportLimits.d.ts","sourceRoot":"","sources":["../../src/api/errorReportLimits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;CAStB,CAAC;AAIX,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB;;;CAGzB,CAAC;AAEX;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxB"}

package/types/api/generated/types.d.ts

@@ -82,6 +82,8 @@ export interface paths {
                                 priority: number | null;
                                 /** @description When true, this campaign is auto-granted to every newly created app. Independent of priority (which controls ranking order only). */
                                 defaultCatalog: boolean;
+                                /** @description When true, this is a demo offer: a fictional brand served only to pk_test_* keys so an integration can be exercised end to end without contacting a real advertiser. Surface it as such rather than presenting it as real inventory. Absent or false means ordinary inventory. */
+                                isDemo?: boolean;
                                 /**
                                  * @description Deprecated; always 'whitelist'. Retained because iOS/Android SDK decoders require the field. Access is governed solely by campaign_allowed_apps + enabled.
                                  * @enum {string}
@@ -376,6 +378,8 @@ export interface paths {
                                 priority: number | null;
                                 /** @description When true, this campaign is auto-granted to every newly created app. Independent of priority (which controls ranking order only). */
                                 defaultCatalog: boolean;
+                                /** @description When true, this is a demo offer: a fictional brand served only to pk_test_* keys so an integration can be exercised end to end without contacting a real advertiser. Surface it as such rather than presenting it as real inventory. Absent or false means ordinary inventory. */
+                                isDemo?: boolean;
                                 /**
                                  * @description Deprecated; always 'whitelist'. Retained because iOS/Android SDK decoders require the field. Access is governed solely by campaign_allowed_apps + enabled.
                                  * @enum {string}
@@ -574,7 +578,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** @description Rebrokering catalog: the full set of offers your app may serve to a given end user, to render on your own surface. Two hard, server-enforced filters always apply: entitlement (your app's opt-outs + whitelist) and geo (offers not redeemable in the end user's country are dropped — non-redeemable offers are never returned). Serve path requires `userId` (a stable end-user identifier) and geo (`countryCode`, or the end user's IP forwarded via X-Forwarded-For); missing either is a 400. Each returned creative carries a tokenized `clickUrl` — route the end user there on tap and it records an attributed transaction (bound to your app, the offer, the creative, and the userId) then 302s to the advertiser. Filter to your curated offer IDs and order CLIENT-SIDE, falling back to other returned offers so your surface is never empty (the server does not narrow to your picks). Set `includeAllRegions: true` for config-time discovery of your full addressable inventory (skips geo, needs no userId, returns no clickUrls; each offer carries targetCountries) — not for display. Authentication: publishable key (X-API-Key: pk_live_* / pk_test_*). */
+        /** @description Rebrokering catalog: the full set of offers your app may serve to a given end user, to render on your own surface. Two hard, server-enforced filters always apply: entitlement (your app's opt-outs + whitelist) and geo (offers not redeemable in the end user's country are dropped: non-redeemable offers are never returned). Serve path requires `userId` (a stable end-user identifier) and geo (`countryCode`, or the end user's IP forwarded via X-Forwarded-For); missing either is a 400. Each returned creative carries a tokenized `clickUrl`: route the end user there on tap and it records an attributed transaction (bound to your app, the offer, the creative, and the userId) then 302s to the advertiser. Filter to your curated offer IDs and order CLIENT-SIDE, falling back to other returned offers so your surface is never empty (the server does not narrow to your picks). Set `includeAllRegions: true` for config-time discovery of your full addressable inventory (skips geo, needs no userId, returns no clickUrls; each offer carries targetCountries); not for display. Authentication: publishable key (X-API-Key: pk_live_* / pk_test_*). */
         post: {
             parameters: {
                 query?: never;
@@ -591,6 +595,13 @@ export interface paths {
                         clientId?: string;
                         /** @description ISO 3166-1 alpha-2 country code of the END USER the offers will be shown to (e.g. "US", "GB"). Provides the geography signal for geo-filtering. Resolution: this value → client IP (X-Forwarded-For aware) → (rejected if neither resolves). Send it when calling server-to-server without forwarding the end user's IP; omit it when the end user (or a proxy forwarding their IP) is the caller. Ignored when includeAllRegions is true. */
                         countryCode?: string;
+                        /**
+                         * @description Optional device family of the END USER the offers will be shown to (enum; any other value is rejected with 400). Analytics dimension only (platform on the serve event); never 'api'.
+                         * @enum {string}
+                         */
+                        platform?: "android" | "ios" | "web";
+                        /** @description Optional publisher-defined label for the surface this offer is shown on (e.g. 'cancel_flow', 'home_feed', 'post_purchase'). Stamped onto the impression AND onto the click it produces, so publisher analytics can break the funnel out by placement. Normalised server-side: a blank value is treated as absent, anything longer than 64 characters is TRUNCATED rather than rejected, and the stored label NEVER carries leading or trailing whitespace — including after truncation, so ' my label ' and 'my label' are always one placement and can never show up as two rows. Case IS significant: 'Cancel_Flow' and 'cancel_flow' are different placements. Omit it and this traffic groups under '(unlabeled)' — the same bucket as an SDK integration that supplies no placement. */
+                        placementId?: string;
                         /** @description CONFIG-TIME ONLY. When true, skips geo-filtering and returns the full addressable inventory for your app (entitlement still applies), with each offer's targetCountries — use this to build your curation. Do NOT use for offers displayed to an end user; those must come from a geo-scoped request (countryCode or forwarded IP). When true, no geography signal is required and countryCode is ignored. */
                         includeAllRegions?: boolean;
                         /** @description Optional page size (1..100). OMIT to return ALL eligible offers (the default) — catalogs are small enough that you normally take the whole set and curate client-side. Provide only if you want to page (with offset). */
@@ -629,6 +640,8 @@ export interface paths {
                                 /** @description New/discounted price for the offer */
                                 newPrice: string | null;
                                 targetCountries: string[];
+                                /** @description When true, this is a demo offer: a fictional brand served only to pk_test_* keys so an integration can be exercised end to end without contacting a real advertiser. Surface it as such rather than presenting it as real inventory. Absent or false means ordinary inventory. */
+                                isDemo?: boolean;
                                 organization?: {
                                     /** Format: uuid */
                                     id: string;
@@ -724,7 +737,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** @description Select one eligible offer for a third-party messaging surface (WhatsApp, Messenger, Instagram) and return the raw offer fields — the branded short clickUrl plus context (title, description, imageUrl, advertiserName, perk) — so the integrator composes their own message. Authentication: publishable key (X-API-Key: pk_live_* / pk_test_*). Retries are NOT deduplicated server-side (no retry-stable client key on the request), so each call produces a distinct short link and analytics row. */
+        /** @description DEPRECATED (2026-08-24): kept serving for existing integrators; new integrations use /offers/feed. Select one eligible offer for a third-party messaging surface (WhatsApp, Messenger, Instagram) and return the raw offer fields, the branded short clickUrl plus context (title, description, imageUrl, advertiserName, perk), so the integrator composes their own message. Calling this endpoint is NOT itself the impression: it emits sdk_offer_requested and returns impressionUid; confirm display via POST /offers/impressions/{impressionUid}/delivered once the message is delivered. Authentication: publishable key (X-API-Key: pk_live_* / pk_test_*). Retries are NOT deduplicated server-side (no retry-stable client key on the request), so each call produces a distinct short link and analytics row. */
         post: {
             parameters: {
                 query?: never;
@@ -751,6 +764,8 @@ export interface paths {
                              */
                             platform?: "android" | "ios" | "web";
                         };
+                        /** @description Optional publisher-defined label for the surface this offer is shown on (e.g. 'cancel_flow', 'home_feed', 'post_purchase'). Stamped onto the impression AND onto the click it produces, so publisher analytics can break the funnel out by placement. Normalised server-side: a blank value is treated as absent, anything longer than 64 characters is TRUNCATED rather than rejected, and the stored label NEVER carries leading or trailing whitespace — including after truncation, so ' my label ' and 'my label' are always one placement and can never show up as two rows. Case IS significant: 'Cancel_Flow' and 'cancel_flow' are different placements. Omit it and this traffic groups under '(unlabeled)' — the same bucket as an SDK integration that supplies no placement. */
+                        placementId?: string;
                     };
                 };
             };
@@ -764,6 +779,11 @@ export interface paths {
                         "application/json": {
                             /** @enum {boolean} */
                             success: true;
+                            /**
+                             * Format: uuid
+                             * @description Handle for the served offer; POST /offers/impressions/{impressionUid}/delivered when the message is confirmed delivered to the user (that call is the impression). Absent when no offer was served.
+                             */
+                            impressionUid?: string;
                             /** @description Selected offer details — the branded short clickUrl plus context fields — for the integrator to compose and send their own message, or null when no eligible offer was found. No message is composed server-side. */
                             offer: {
                                 /**
@@ -782,6 +802,8 @@ export interface paths {
                                 imageUrl: string;
                                 /** @description Display name of the advertiser (organization) behind the offer. */
                                 advertiserName: string;
+                                /** @description When true, this is a demo offer: a fictional brand served only to pk_test_* keys so an integration can be exercised end to end without contacting a real advertiser. Surface it as such rather than presenting it as real inventory. Absent or false means ordinary inventory. */
+                                isDemo?: boolean;
                                 /** @description Campaign value proposition (e.g. "3 months of Apple Music free"), or null when the campaign has none. Surfaced explicitly so integrators can render the deal in the message they compose. */
                                 perk?: string | null;
                                 /**
@@ -846,7 +868,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** @description Return the bandit-ranked eligible offers for a user (up to `limit`, default 10) so a native / custom-UI app can render them and cycle through them client-side. Each offer carries its own impressionUid plus the branded short clickUrl and context (title, description, imageUrl, additionalImages, advertiserName, advertiserLogo, perk). Calling this endpoint is NOT itself the impression — the server emits one offer.requested per offer as the served baseline; confirm an actual impression by calling POST /offers/impressions/:impression_uid/delivered when an offer is shown. Returns offers:[] when no eligible offer was found. Authentication: publishable key (X-API-Key: pk_live_* / pk_test_*). */
+        /** @description Return the bandit-ranked eligible offers for a user (up to `limit`, default 10) so a native / custom-UI app can render them and cycle through them client-side. Each offer carries its own impressionUid plus the branded short clickUrl and context (title, description, imageUrl, additionalImages, advertiserName, advertiserLogo, perk). Calling this endpoint is NOT itself the impression: the server emits one sdk_offer_requested per offer as the requests baseline; confirm an actual impression by calling POST /offers/impressions/:impression_uid/delivered when an offer is shown. Returns offers:[] when no eligible offer was found. Authentication: publishable key (X-API-Key: pk_live_* / pk_test_*). */
         post: {
             parameters: {
                 query?: never;
@@ -878,6 +900,8 @@ export interface paths {
                          * @default 10
                          */
                         limit?: number;
+                        /** @description Optional publisher-defined label for the surface this offer is shown on (e.g. 'cancel_flow', 'home_feed', 'post_purchase'). Stamped onto the impression AND onto the click it produces, so publisher analytics can break the funnel out by placement. Normalised server-side: a blank value is treated as absent, anything longer than 64 characters is TRUNCATED rather than rejected, and the stored label NEVER carries leading or trailing whitespace — including after truncation, so ' my label ' and 'my label' are always one placement and can never show up as two rows. Case IS significant: 'Cancel_Flow' and 'cancel_flow' are different placements. Omit it and this traffic groups under '(unlabeled)' — the same bucket as an SDK integration that supplies no placement. */
+                        placementId?: string;
                     };
                 };
             };
@@ -900,6 +924,11 @@ export interface paths {
                                  * @description Branded short click URL (https://link.encorekit.com/<slug>) that 302s to the advertiser with attribution. Open it in-app to register the click; also usable as a share-to-friend link.
                                  */
                                 clickUrl: string;
+                                /**
+                                 * Format: uuid
+                                 * @description Stable identifier for the offer (campaign). Use THIS to match a completion back to the offer you displayed: the `offer_completed` webhook carries the same value as its `campaignId`. Unlike `title` (which is per-creative and localized) and `campaignName` (an editable admin label), this never changes for a given offer.
+                                 */
+                                campaignId: string;
                                 /** @description Creative headline/title for the offer. */
                                 title: string;
                                 /** @description Longer creative description, or null when the creative has none. */
@@ -914,6 +943,8 @@ export interface paths {
                                  * @default []
                                  */
                                 additionalImages: string[];
+                                /** @description When true, this is a demo offer: a fictional brand served only to pk_test_* keys so an integration can be exercised end to end without contacting a real advertiser. Surface it as such rather than presenting it as real inventory. Absent or false means ordinary inventory. */
+                                isDemo?: boolean;
                                 /** @description Display name of the advertiser (organization) behind the offer. */
                                 advertiserName: string;
                                 /**
@@ -985,7 +1016,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** @description Record that a previously selected offer (impression) was actually shown to the end user — confirming an impression. Used by both the messaging surface (/offers/message) and the multi-offer feed (/offers/feed, called once per offer as it is displayed). Emits `offer.delivered`; analytics joins to `offer.requested` by impression_uid downstream. Authentication: publishable key (X-API-Key: pk_live_* / pk_test_*). */
+        /** @description Confirms an impression: call once per offer as it is displayed, for /offers/feed, /offers/catalog and /offers/message alike; the impression id comes from the serve response or the click url. Emits sdk_offer_presented keyed on the impression id; analytics stitches it to the serve in the warehouse. Authentication: publishable key (X-API-Key: pk_live_* / pk_test_*). */
         post: {
             parameters: {
                 query?: never;
@@ -999,9 +1030,9 @@ export interface paths {
             requestBody: {
                 content: {
                     "application/json": {
-                        /** @description Unix seconds — Meta webhook `statuses[].timestamp` where status='delivered'. */
+                        /** @description Unix seconds — Meta webhook `statuses[].timestamp` where status='delivered'. Milliseconds are also accepted (any value above 1e11 is read as milliseconds), and a value that is not plausibly a real delivery is replaced by the receipt time on the analytics event; the value you send is always preserved verbatim in the event's properties. */
                         deliveredTimestamp: number;
-                        /** @description Unix seconds — Meta webhook `statuses[].timestamp` where status='read'. Optional. */
+                        /** @description Unix seconds — Meta webhook `statuses[].timestamp` where status='read'. Optional. Milliseconds are also accepted, exactly as for `deliveredTimestamp`. Unlike `deliveredTimestamp` there is no receipt-time substitution: a value that is not plausibly a real read is simply reported as null on the analytics event, since nothing depends on it. */
                         readTimestamp?: number;
                     };
                 };
@@ -2053,6 +2084,18 @@ export interface paths {
                     };
                 };
                 /** @description Default Response */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: string;
+                            details?: unknown;
+                        };
+                    };
+                };
+                /** @description Default Response */
                 500: {
                     headers: {
                         [name: string]: unknown;
@@ -2880,7 +2923,7 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** @description Simulate a conversion postback for the Paramount+ Encore Demo campaign. Unauthenticated; hard-scoped to the demo campaign at the service layer. */
+        /** @description Simulate a conversion postback for the Halcyon Stream campaign. Unauthenticated; hard-scoped to the demo campaign at the service layer. */
         post: {
             parameters: {
                 query?: never;
@@ -4468,6 +4511,8 @@ export interface components {
                 priority: number | null;
                 /** @description When true, this campaign is auto-granted to every newly created app. Independent of priority (which controls ranking order only). */
                 defaultCatalog: boolean;
+                /** @description When true, this is a demo offer: a fictional brand served only to pk_test_* keys so an integration can be exercised end to end without contacting a real advertiser. Surface it as such rather than presenting it as real inventory. Absent or false means ordinary inventory. */
+                isDemo?: boolean;
                 /**
                  * @description Deprecated; always 'whitelist'. Retained because iOS/Android SDK decoders require the field. Access is governed solely by campaign_allowed_apps + enabled.
                  * @enum {string}
@@ -4654,6 +4699,8 @@ export interface components {
             priority: number | null;
             /** @description When true, this campaign is auto-granted to every newly created app. Independent of priority (which controls ranking order only). */
             defaultCatalog: boolean;
+            /** @description When true, this is a demo offer: a fictional brand served only to pk_test_* keys so an integration can be exercised end to end without contacting a real advertiser. Surface it as such rather than presenting it as real inventory. Absent or false means ordinary inventory. */
+            isDemo?: boolean;
             /**
              * @description Deprecated; always 'whitelist'. Retained because iOS/Android SDK decoders require the field. Access is governed solely by campaign_allowed_apps + enabled.
              * @enum {string}