@apostra/sdk 0.40.0 → 0.41.0

package/dist/cli-login.js

@@ -65,27 +65,39 @@ function parseEntry(value) {
     if (!isRecord(value))
         return undefined;
     const text = ['issuer', 'resource', 'clientId', 'accessToken', 'refreshToken'];
+    const expiresAt = typeof value.expiresAt === 'string' &&
+        !Number.isNaN(Date.parse(value.expiresAt))
+        ? new Date(value.expiresAt).toISOString()
+        : undefined;
     if (!text.every((k) => typeof value[k] === 'string' && value[k]) ||
-        typeof value.expiresAt !== 'string' ||
-        Number.isNaN(Date.parse(value.expiresAt)) ||
+        !expiresAt ||
         typeof value.accountId !== 'string' ||
         !Array.isArray(value.scopes) ||
         !value.scopes.every((s) => typeof s === 'string'))
         return undefined;
-    return value;
+    // Credential stores round-trip text. Canonicalise at their boundary so a
+    // value with sub-millisecond precision cannot oscillate between clients.
+    return { ...value, expiresAt };
 }
-function readFileLogins() {
+function readFileStore() {
     const { fs } = node();
     try {
         const file = JSON.parse(fs.readFileSync(credentialsPath(), 'utf8'));
-        return isRecord(file) && isRecord(file.logins) ? file.logins : {};
+        if (!isRecord(file) || !isRecord(file.logins))
+            return { logins: {}, authoritative: new Set() };
+        return {
+            logins: file.logins,
+            authoritative: new Set(Array.isArray(file.authoritativeFileLogins)
+                ? file.authoritativeFileLogins.filter((resource) => typeof resource === 'string')
+                : []),
+        };
     }
     catch {
-        return {};
+        return { logins: {}, authoritative: new Set() };
     }
 }
 /** Atomic (temp file + rename), directory 0700, file 0600. */
-function writeFileLogins(logins) {
+function writeFileLogins(logins, authoritative = new Set()) {
     const { fs, path } = node();
     const file = credentialsPath();
     const dir = path.dirname(file);
@@ -98,7 +110,17 @@ function writeFileLogins(logins) {
     const temp = `${file}.${proc().pid}.${Math.random().toString(36).slice(2)}.tmp`;
     const fd = fs.openSync(temp, 'wx', 0o600);
     try {
-        fs.writeSync(fd, `${JSON.stringify({ version: 1, logins }, null, 2)}\n`);
+        fs.writeSync(fd, `${JSON.stringify({
+            version: 1,
+            logins,
+            ...(authoritative.size > 0
+                ? {
+                    authoritativeFileLogins: [...authoritative]
+                        .filter((resource) => resource in logins)
+                        .sort(),
+                }
+                : {}),
+        }, null, 2)}\n`);
     }
     finally {
         fs.closeSync(fd);
@@ -176,7 +198,8 @@ function warnFileFallback() {
  */
 function migrateFileLogins(lockHeld = false) {
     const { fs, path } = node();
-    const fileLogins = readFileLogins();
+    const fileStore = readFileStore();
+    const fileLogins = fileStore.logins;
     const entries = Object.entries(fileLogins).flatMap(([resource, value]) => {
         const entry = parseEntry(value);
         return entry ? [[resource, entry]] : [];
@@ -202,17 +225,30 @@ function migrateFileLogins(lockHeld = false) {
         }
     }
     try {
+        const remaining = { ...fileLogins };
+        const remainingAuthoritative = new Set(fileStore.authoritative);
         for (const [resource, entry] of entries) {
             // A keyring value is authoritative: preserving it avoids overwriting a
             // token another process has already refreshed during an interrupted
-            // earlier migration.
+            // earlier migration, unless the protected fallback marks a replacement
+            // as authoritative after a failed secure-store rotation.
             const stored = readSecureLogin(resource);
-            if (stored.entry)
+            if (!fileStore.authoritative.has(resource) && stored.entry) {
+                delete remaining[resource];
+                remainingAuthoritative.delete(resource);
                 continue;
-            if (!stored.available || !writeSecureLogin(resource, entry))
+            }
+            if (!stored.available || !writeSecureLogin(resource, entry)) {
+                // Retain only entries that still need migration. Otherwise a
+                // successfully migrated authoritative login could shadow its next
+                // secure-store refresh while another login remains in the file.
+                writeFileLogins(remaining, remainingAuthoritative);
                 return false;
+            }
+            delete remaining[resource];
+            remainingAuthoritative.delete(resource);
         }
-        fs.rmSync(credentialsPath(), { force: true });
+        writeFileLogins(remaining, remainingAuthoritative);
         return true;
     }
     finally {
@@ -229,17 +265,24 @@ function migrateFileLogins(lockHeld = false) {
 }
 export function readCliLogin(baseUrl) {
     const resource = normalizeBaseUrl(baseUrl);
+    const fileStore = readFileStore();
+    const fileEntry = parseEntry(fileStore.logins[resource]);
+    // A refresh token can rotate before a credential store reports an update
+    // failure. This marker makes its 0600 fallback authoritative over the now
+    // invalid secure-store value until a later read can migrate it safely.
+    if (fileStore.authoritative.has(resource) && fileEntry)
+        return fileEntry;
     const secure = readSecureLogin(resource);
     if (secure.entry)
         return secure.entry;
-    const fileLogins = readFileLogins();
+    const fileLogins = fileStore.logins;
     if (Object.keys(fileLogins).length === 0)
         return undefined;
     if (migrateFileLogins())
         return readSecureLogin(resource).entry;
     if (!secure.available)
         warnFileFallback();
-    return parseEntry(fileLogins[resource]);
+    return fileEntry;
 }
 /** Like `readCliLogin`, but never throws: for the SDK's default credential chain. */
 export function storedCliLogin(baseUrl) {
@@ -360,13 +403,24 @@ export async function withCliLoginLock(fn) {
 /** Save a login. Call inside `withCliLoginLock`. */
 export function writeCliLogin(baseUrl, entry) {
     const resource = normalizeBaseUrl(baseUrl);
+    const normalised = parseEntry(entry);
+    if (!normalised)
+        throw new TypeError('Apostra login is invalid');
     // Callers hold the cross-process lock, so the legacy file cannot overwrite
     // a rotated credential while it is being migrated.
     migrateFileLogins(true);
-    if (writeSecureLogin(resource, entry))
+    const existing = readSecureLogin(resource);
+    if (writeSecureLogin(resource, normalised))
         return;
     warnFileFallback();
-    writeFileLogins({ ...readFileLogins(), [resource]: entry });
+    const fileStore = readFileStore();
+    // A refresh token may rotate while the OS credential store disappears. Its
+    // next read could reveal the older credential, so the protected fallback is
+    // authoritative both when we saw an old entry and when availability is
+    // unknown.
+    if (!existing.available || existing.entry)
+        fileStore.authoritative.add(resource);
+    writeFileLogins({ ...fileStore.logins, [resource]: normalised }, fileStore.authoritative);
 }
 async function send(fetcher, url, init = {}) {
     return fetcher(url, {
@@ -530,8 +584,10 @@ export async function logoutCliLogin(baseUrl, { fetch: f = globalThis.fetch } =
         // A prior fallback login can still be present even when the credential
         // store has no entry (or is available again). Remove it unconditionally:
         // otherwise its refresh token could be migrated back after logout.
-        const { [key]: _removed, ...rest } = readFileLogins();
-        writeFileLogins(rest);
+        const fileStore = readFileStore();
+        const { [key]: _removed, ...rest } = fileStore.logins;
+        fileStore.authoritative.delete(key);
+        writeFileLogins(rest, fileStore.authoritative);
         return { found: true, revoked };
     });
 }

package/dist/generated/client.d.ts

@@ -49,9 +49,6 @@ export type LogEventError = Wire.LogEventErrors[keyof Wire.LogEventErrors];
 export type OpenAdvertisersPageInput = Wire.OpenAdvertisersPageData['body'];
 export type OpenAdvertisersPageResult = Wire.OpenAdvertisersPageResponses[200]['data'];
 export type OpenAdvertisersPageError = Wire.OpenAdvertisersPageErrors[keyof Wire.OpenAdvertisersPageErrors];
-export type OpenAgentCertificationPageInput = Wire.OpenAgentCertificationPageData['body'];
-export type OpenAgentCertificationPageResult = Wire.OpenAgentCertificationPageResponses[200]['data'];
-export type OpenAgentCertificationPageError = Wire.OpenAgentCertificationPageErrors[keyof Wire.OpenAgentCertificationPageErrors];
 export type OpenAgentPageInput = Wire.OpenAgentPageData['body'];
 export type OpenAgentPageResult = Wire.OpenAgentPageResponses[200]['data'];
 export type OpenAgentPageError = Wire.OpenAgentPageErrors[keyof Wire.OpenAgentPageErrors];
@@ -287,10 +284,6 @@ export interface OperationTypes {
         input: OpenAdvertisersPageInput;
         result: OpenAdvertisersPageResult;
     };
-    "open_agent_certification_page": {
-        input: OpenAgentCertificationPageInput;
-        result: OpenAgentCertificationPageResult;
-    };
     "open_agent_page": {
         input: OpenAgentPageInput;
         result: OpenAgentPageResult;
@@ -623,13 +616,13 @@ export declare class Apostra extends Transport {
     /** Show a seller what reporting we received for one buyer media buy, whether each receipt was accepted, and the current computed daily totals. Opens the Media Buy Timeline Glance. Returns the data together with response headers and request ID. */
     getSellerReportingReceiptsWithResponse(input: GetSellerReportingReceiptsInput, options?: RequestOptions): Promise<ResponseDetails<GetSellerReportingReceiptsResult>>;
     /**
-     * Current account, state, blockers, exact fixes, and reachable accounts. For seller demand, use it to tell whether readiness stops requests before source calls; read before diagnosing source health, empty responses, or demand. A Developer account adds each agent's stage, blocker, and next call.
+     * Current account, state, blockers, exact fixes, accounts to pick from. For seller demand, tells if readiness stops requests before source calls; read before diagnosing source health, empty responses, or demand. A Developer account adds each agent's stage, blocker, next call.
      *
      * @example
      * await client.getStatus(input)
      */
     getStatus(input?: GetStatusInput, options?: RequestOptions): Promise<GetStatusResult>;
-    /** Current account, state, blockers, exact fixes, and reachable accounts. For seller demand, use it to tell whether readiness stops requests before source calls; read before diagnosing source health, empty responses, or demand. A Developer account adds each agent's stage, blocker, and next call. Returns the data together with response headers and request ID. */
+    /** Current account, state, blockers, exact fixes, accounts to pick from. For seller demand, tells if readiness stops requests before source calls; read before diagnosing source health, empty responses, or demand. A Developer account adds each agent's stage, blocker, next call. Returns the data together with response headers and request ID. */
     getStatusWithResponse(input?: GetStatusInput, options?: RequestOptions): Promise<ResponseDetails<GetStatusResult>>;
     /**
      * Send up to 10,000 AdCP conversion events (log_event) to an event source the advertiser registered with save_event_source. Events must also pass the v2 rules: no raw email or phone in user_match, each event_type + event_id once per call. One invalid event refuses the whole call.
@@ -649,15 +642,6 @@ export declare class Apostra extends Transport {
     openAdvertisersPage(input: OpenAdvertisersPageInput, options?: RequestOptions): Promise<OpenAdvertisersPageResult>;
     /** Open the Advertisers Page: every advertiser with its campaign and draft counts and one next action each. Use it for "show my advertisers" or "where do I start"; the Page self-fetches. To add or set up an advertiser, pass intent: "add". For a text answer use search(kind: "advertiser"). Returns the data together with response headers and request ID. */
     openAdvertisersPageWithResponse(input: OpenAdvertisersPageInput, options?: RequestOptions): Promise<ResponseDetails<OpenAdvertisersPageResult>>;
-    /**
-     * Open one agent’s Test & certify Page: live certification per use case, recent test runs, AdCP 4.0 readiness and capability declarations. Read-only.
-     *
-     * @example
-     * await client.openAgentCertificationPage(input)
-     */
-    openAgentCertificationPage(input: OpenAgentCertificationPageInput, options?: RequestOptions): Promise<OpenAgentCertificationPageResult>;
-    /** Open one agent’s Test & certify Page: live certification per use case, recent test runs, AdCP 4.0 readiness and capability declarations. Read-only. Returns the data together with response headers and request ID. */
-    openAgentCertificationPageWithResponse(input: OpenAgentCertificationPageInput, options?: RequestOptions): Promise<ResponseDetails<OpenAgentCertificationPageResult>>;
     /**
      * Open one agent owned by this Developer account.
      *
@@ -740,13 +724,13 @@ export declare class Apostra extends Transport {
     /** Open the buyer Creative Engines Page. Optionally focus an engine, connection, or its secure setup control; the buyer starts setup in the Page, and this does not authorize a provider or start generation. Returns the data together with response headers and request ID. */
     openCreativeEnginesPageWithResponse(input: OpenCreativeEnginesPageInput, options?: RequestOptions): Promise<ResponseDetails<OpenCreativeEnginesPageResult>>;
     /**
-     * Open Creative Library. Use search for a plain object answer. Composer needs campaignId; assembly needs no Creative Engine. To save a draft, use exactly one format: a canonical format such as image, hosted video, or hosted audio, or a seller format.
+     * Open Creative Library. Use search for a plain object answer. The composer can start from an advertiser or a campaign and does not need a Creative Engine. To save a draft, use exactly one format: a canonical format such as image, hosted video, or hosted audio, or a seller format.
      *
      * @example
      * await client.openCreativeLibrary(input, { idempotencyKey: 'stable-key' })
      */
     openCreativeLibrary(input: OpenCreativeLibraryInput, options: WriteRequestOptions): Promise<OpenCreativeLibraryResult>;
-    /** Open Creative Library. Use search for a plain object answer. Composer needs campaignId; assembly needs no Creative Engine. To save a draft, use exactly one format: a canonical format such as image, hosted video, or hosted audio, or a seller format. Returns the data together with response headers and request ID. */
+    /** Open Creative Library. Use search for a plain object answer. The composer can start from an advertiser or a campaign and does not need a Creative Engine. To save a draft, use exactly one format: a canonical format such as image, hosted video, or hosted audio, or a seller format. Returns the data together with response headers and request ID. */
     openCreativeLibraryWithResponse(input: OpenCreativeLibraryInput, options: WriteRequestOptions): Promise<ResponseDetails<OpenCreativeLibraryResult>>;
     /**
      * Open the Developer home for this Developer account: its agents, their stages and what to do next.
@@ -812,13 +796,13 @@ export declare class Apostra extends Transport {
     /** Show a saved Creative Session’s variants (find via search/get kind creative_session). Not for generating new variants. Returns the data together with response headers and request ID. */
     openVariantGalleryWithResponse(input: OpenVariantGalleryInput, options?: RequestOptions): Promise<ResponseDetails<OpenVariantGalleryResult>>;
     /**
-     * Rechecks one external sales-agent source with no-spend get_products and, if it publishes one, a catalog refresh. Returns each check, findings still open, evidence IDs and readiness; no source configuration or media buy.
+     * Rechecks one external sales-agent source with no-spend get_products and, if it publishes one, a catalog refresh. Returns each check, findings still open, evidence IDs and readiness; no source configuration or media buy. scope accounts re-lists the source's accounts instead.
      *
      * @example
      * await client.refreshInventorySourceHealth(input, { idempotencyKey: 'stable-key' })
      */
     refreshInventorySourceHealth(input: RefreshInventorySourceHealthInput, options: WriteRequestOptions): Promise<RefreshInventorySourceHealthResult>;
-    /** Rechecks one external sales-agent source with no-spend get_products and, if it publishes one, a catalog refresh. Returns each check, findings still open, evidence IDs and readiness; no source configuration or media buy. Returns the data together with response headers and request ID. */
+    /** Rechecks one external sales-agent source with no-spend get_products and, if it publishes one, a catalog refresh. Returns each check, findings still open, evidence IDs and readiness; no source configuration or media buy. scope accounts re-lists the source's accounts instead. Returns the data together with response headers and request ID. */
     refreshInventorySourceHealthWithResponse(input: RefreshInventorySourceHealthInput, options: WriteRequestOptions): Promise<ResponseDetails<RefreshInventorySourceHealthResult>>;
     /**
      * Request a Buyer child under the selected Organization. Nothing is created until an Organization administrator approves it on our site; the result is approval_required with a link to show the person. Repeat with the same idempotencyKey and name for the outcome.
@@ -911,13 +895,13 @@ export declare class Apostra extends Transport {
     /** Confirm a Sales Agent product mode, register a Sales or Creative Agent, or update an owned Agent: rename it or allow certification buys. To connect from a URL, send agentUrl with dryRun: true, show what was read, then send it without dryRun. A connected agent is not yet verified as theirs. Returns the data together with response headers and request ID. */
     saveAgentWithResponse(input: SaveAgentInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveAgentResult>>;
     /**
-     * File or update a typed ask in the Apostra Support workflow; returns askId. Supply is buyer inventory. Call immediately with type support when a person explicitly asks for a human; do not diagnose first.
+     * File or update a typed ask in the Apostra Support workflow; returns askId. kind create files a new ask; kind update sends only id and requester. Supply is buyer inventory. Call immediately with type support when a person explicitly asks for a human; do not diagnose first.
      *
      * @example
      * await client.saveAsk(input, { idempotencyKey: 'stable-key' })
      */
     saveAsk(input: SaveAskInput, options: WriteRequestOptions): Promise<SaveAskResult>;
-    /** File or update a typed ask in the Apostra Support workflow; returns askId. Supply is buyer inventory. Call immediately with type support when a person explicitly asks for a human; do not diagnose first. Returns the data together with response headers and request ID. */
+    /** File or update a typed ask in the Apostra Support workflow; returns askId. kind create files a new ask; kind update sends only id and requester. Supply is buyer inventory. Call immediately with type support when a person explicitly asks for a human; do not diagnose first. Returns the data together with response headers and request ID. */
     saveAskWithResponse(input: SaveAskInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveAskResult>>;
     /**
      * Sync first-party CRM audiences for a buyer advertiser. Each audiences[] item may add, remove, or delete members. Returns an operationId; use get(kind: audience, advertiserId: "...") to read match status after it settles.
@@ -992,22 +976,22 @@ export declare class Apostra extends Transport {
     /** Manage seller or creative-engine authorization, accounts and advertiser mappings. Seller-only: reporting, selection, billing, policy, activation. Returns the data together with response headers and request ID. */
     saveConnectionWithResponse(input: SaveConnectionInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveConnectionResult>>;
     /**
-     * Declare publisher domains this Seller sells and its claimed properties. `domains` replaces the complete set; `add`, `remove`, `declareProperties`, and `removeProperties` change named items only. Read authorization; never assume it.
+     * Declare publisher domains this Seller sells and its claimed properties. `domains` replaces the complete set; `add`, `remove`, `declareProperties`, `removeProperties`, and `refresh` act on named items only. Read authorization; never assume it.
      *
      * @example
      * await client.saveCoverage(input, { idempotencyKey: 'stable-key' })
      */
     saveCoverage(input: SaveCoverageInput, options: WriteRequestOptions): Promise<SaveCoverageResult>;
-    /** Declare publisher domains this Seller sells and its claimed properties. `domains` replaces the complete set; `add`, `remove`, `declareProperties`, and `removeProperties` change named items only. Read authorization; never assume it. Returns the data together with response headers and request ID. */
+    /** Declare publisher domains this Seller sells and its claimed properties. `domains` replaces the complete set; `add`, `remove`, `declareProperties`, `removeProperties`, and `refresh` act on named items only. Read authorization; never assume it. Returns the data together with response headers and request ID. */
     saveCoverageWithResponse(input: SaveCoverageInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveCoverageResult>>;
     /**
-     * advertiserId/campaignId:name,message;assets/landing_page_url/social/sourceAssetRef/sourceAssets;Supplied content/assets only;generate new media (radio spots):save_creative_session;exactly one format selector:formatKind/formatParams,creativeFormatId/formatOptionRef;libraryRole:Buyer Account only.
+     * Save content you supply: advertiserId/campaignId, name, message, assets (landing_page_url, social, sourceAssetRef/sourceAssets). New media like radio spots: use save_creative_session. One format selector: formatKind+formatParams or creativeFormatId+formatOptionRef. libraryRole: Buyer Account only.
      *
      * @example
      * await client.saveCreative(input, { idempotencyKey: 'stable-key' })
      */
     saveCreative(input: SaveCreativeInput, options: WriteRequestOptions): Promise<SaveCreativeResult>;
-    /** advertiserId/campaignId:name,message;assets/landing_page_url/social/sourceAssetRef/sourceAssets;Supplied content/assets only;generate new media (radio spots):save_creative_session;exactly one format selector:formatKind/formatParams,creativeFormatId/formatOptionRef;libraryRole:Buyer Account only. Returns the data together with response headers and request ID. */
+    /** Save content you supply: advertiserId/campaignId, name, message, assets (landing_page_url, social, sourceAssetRef/sourceAssets). New media like radio spots: use save_creative_session. One format selector: formatKind+formatParams or creativeFormatId+formatOptionRef. libraryRole: Buyer Account only. Returns the data together with response headers and request ID. */
     saveCreativeWithResponse(input: SaveCreativeInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveCreativeResult>>;
     /**
      * Manage collections. Create with one owner and name: campaignId or advertiserId. Only advertiser mutations of an existing collection need expectedUpdatedAt; campaign writes and creates do not. isArchived archives or restores advertiser collections.
@@ -1055,13 +1039,13 @@ export declare class Apostra extends Transport {
     /** Create, change, archive, or restore up to 50 advertiser conversion event sources (pixels, server feeds). Each entry is keyed by eventSourceId and succeeds or fails alone. Setup is not proof events flow: check health with get, then use eventSourceId in an optimization goal. Returns the data together with response headers and request ID. */
     saveEventSourceWithResponse(input: SaveEventSourceInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveEventSourceResult>>;
     /**
-     * Create or update where a seller's inventory comes from. Pass `id` to change a source or omit it to add one. Pass only `agentId` or `adServer` to open the form that connects an agent or an ad server. Credentials are never passed here; a source that needs one returns the page that collects it.
+     * Create or update where a seller's inventory comes from. Pass `id` to change a source or omit it to add one. Add a sales agent with only `agentId`, never its address, or an ad server with only `adServer`; each opens a form. Credentials are never passed here; a source that needs one returns its form.
      *
      * @example
      * await client.saveInventorySource(input, { idempotencyKey: 'stable-key' })
      */
     saveInventorySource(input: SaveInventorySourceInput, options: WriteRequestOptions): Promise<SaveInventorySourceResult>;
-    /** Create or update where a seller's inventory comes from. Pass `id` to change a source or omit it to add one. Pass only `agentId` or `adServer` to open the form that connects an agent or an ad server. Credentials are never passed here; a source that needs one returns the page that collects it. Returns the data together with response headers and request ID. */
+    /** Create or update where a seller's inventory comes from. Pass `id` to change a source or omit it to add one. Add a sales agent with only `agentId`, never its address, or an ad server with only `adServer`; each opens a form. Credentials are never passed here; a source that needs one returns its form. Returns the data together with response headers and request ID. */
     saveInventorySourceWithResponse(input: SaveInventorySourceInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveInventorySourceResult>>;
     /**
      * Manage seller lessons in a seller account; send the accountId of that account. propose requires lesson; approve and retire require lessonId; preview requires lessonId and brief. Preserve seller words from a private Session note and ask if kind or scope is unclear.
@@ -1091,13 +1075,13 @@ export declare class Apostra extends Transport {
     /** Create or update seller Materials. Seller beta: preview, delete, Undo deletion, or Include again for one imported Library document. Delete archives it, excludes its source until Include again, and purges it after 30 days. https://docs.apostra.com/v3/delete-from-apostra Returns the data together with response headers and request ID. */
     saveMaterialWithResponse(input: SaveMaterialInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveMaterialResult>>;
     /**
-     * Create DRAFT buy; no spend until confirmed. Meta: shared campaign=seller_optimized; ad sets=fixed; ask if unclear. Shared: omit buy/product budgets. Pause/resume: mediaBuyId + isPaused. Proposal: flight + total budget; omit products. channelGroupId: required if grouped; invalid ungrouped/updates.
+     * Create DRAFT buy; no spend until confirmed. Meta: shared campaign=seller_optimized; ad sets=fixed; ask if unclear. Shared: omit product budgets. Pause/resume: mediaBuyId + isPaused. Proposal: flight + total budget; omit products. channelGroupId: required if grouped; invalid ungrouped/updates.
      *
      * @example
      * await client.saveMediaBuy(input, { idempotencyKey: 'stable-key' })
      */
     saveMediaBuy(input: SaveMediaBuyInput, options: WriteRequestOptions): Promise<SaveMediaBuyResult>;
-    /** Create DRAFT buy; no spend until confirmed. Meta: shared campaign=seller_optimized; ad sets=fixed; ask if unclear. Shared: omit buy/product budgets. Pause/resume: mediaBuyId + isPaused. Proposal: flight + total budget; omit products. channelGroupId: required if grouped; invalid ungrouped/updates. Returns the data together with response headers and request ID. */
+    /** Create DRAFT buy; no spend until confirmed. Meta: shared campaign=seller_optimized; ad sets=fixed; ask if unclear. Shared: omit product budgets. Pause/resume: mediaBuyId + isPaused. Proposal: flight + total budget; omit products. channelGroupId: required if grouped; invalid ungrouped/updates. Returns the data together with response headers and request ID. */
     saveMediaBuyWithResponse(input: SaveMediaBuyInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveMediaBuyResult>>;
     /**
      * Deprecated compatibility tool ("listing" is the modern term). It writes only the legacy businessProfile and does not update the canonical buyer-visible listing. New clients must read with `get({ kind: "seller", include: ["listing"] })` and write with `save_seller`.
@@ -1154,13 +1138,13 @@ export declare class Apostra extends Transport {
     /** Change one RFP turn: release it, request or cancel a proposal file, append feedback, or record its outcome. One of these per call; revise, endorse and attach a response with save_rfp. Returns the data together with response headers and request ID. */
     saveRfpTurnWithResponse(input: SaveRfpTurnInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveRfpTurnResult>>;
     /**
-     * Save Seller identity, capabilities, Apostra listing, buyer-visible listing (mediaKit is a deprecated alias), Distribution's OpenAI challenge token, an admission, or the intake hold. Scope3 eligibility and Market Maker entitlements are read-only here. Read Distribution with get(kind:"distribution").
+     * Save Seller identity, capabilities, buyer-visible listing (mediaKit is a deprecated alias), Distribution's OpenAI challenge token, an admission, the intake hold, or the demo's expiry and sample sources. Scope3 eligibility and Market Maker entitlements are read-only here. Read Distribution with get.
      *
      * @example
      * await client.saveSeller(input, { idempotencyKey: 'stable-key' })
      */
     saveSeller(input: SaveSellerInput, options: WriteRequestOptions): Promise<SaveSellerResult>;
-    /** Save Seller identity, capabilities, Apostra listing, buyer-visible listing (mediaKit is a deprecated alias), Distribution's OpenAI challenge token, an admission, or the intake hold. Scope3 eligibility and Market Maker entitlements are read-only here. Read Distribution with get(kind:"distribution"). Returns the data together with response headers and request ID. */
+    /** Save Seller identity, capabilities, buyer-visible listing (mediaKit is a deprecated alias), Distribution's OpenAI challenge token, an admission, the intake hold, or the demo's expiry and sample sources. Scope3 eligibility and Market Maker entitlements are read-only here. Read Distribution with get. Returns the data together with response headers and request ID. */
     saveSellerWithResponse(input: SaveSellerInput, options: WriteRequestOptions): Promise<ResponseDetails<SaveSellerResult>>;
     /**
      * Create, replace, or archive a signal. Managed writes need a complete draft; read before updates. Without sourceId, writes the seller catalog.

package/dist/generated/client.js

@@ -82,13 +82,13 @@ export class Apostra extends Transport {
     /** Show a seller what reporting we received for one buyer media buy, whether each receipt was accepted, and the current computed daily totals. Opens the Media Buy Timeline Glance. Returns the data together with response headers and request ID. */
     getSellerReportingReceiptsWithResponse(input, options) { return this.requestDetailed("get_seller_reporting_receipts", input, options); }
     /**
-     * Current account, state, blockers, exact fixes, and reachable accounts. For seller demand, use it to tell whether readiness stops requests before source calls; read before diagnosing source health, empty responses, or demand. A Developer account adds each agent's stage, blocker, and next call.
+     * Current account, state, blockers, exact fixes, accounts to pick from. For seller demand, tells if readiness stops requests before source calls; read before diagnosing source health, empty responses, or demand. A Developer account adds each agent's stage, blocker, next call.
      *
      * @example
      * await client.getStatus(input)
      */
     getStatus(input = {}, options) { return this.request("get_status", input, options); }
-    /** Current account, state, blockers, exact fixes, and reachable accounts. For seller demand, use it to tell whether readiness stops requests before source calls; read before diagnosing source health, empty responses, or demand. A Developer account adds each agent's stage, blocker, and next call. Returns the data together with response headers and request ID. */
+    /** Current account, state, blockers, exact fixes, accounts to pick from. For seller demand, tells if readiness stops requests before source calls; read before diagnosing source health, empty responses, or demand. A Developer account adds each agent's stage, blocker, next call. Returns the data together with response headers and request ID. */
     getStatusWithResponse(input = {}, options) { return this.requestDetailed("get_status", input, options); }
     /**
      * Send up to 10,000 AdCP conversion events (log_event) to an event source the advertiser registered with save_event_source. Events must also pass the v2 rules: no raw email or phone in user_match, each event_type + event_id once per call. One invalid event refuses the whole call.
@@ -108,15 +108,6 @@ export class Apostra extends Transport {
     openAdvertisersPage(input, options) { return this.request("open_advertisers_page", input, options); }
     /** Open the Advertisers Page: every advertiser with its campaign and draft counts and one next action each. Use it for "show my advertisers" or "where do I start"; the Page self-fetches. To add or set up an advertiser, pass intent: "add". For a text answer use search(kind: "advertiser"). Returns the data together with response headers and request ID. */
     openAdvertisersPageWithResponse(input, options) { return this.requestDetailed("open_advertisers_page", input, options); }
-    /**
-     * Open one agent’s Test & certify Page: live certification per use case, recent test runs, AdCP 4.0 readiness and capability declarations. Read-only.
-     *
-     * @example
-     * await client.openAgentCertificationPage(input)
-     */
-    openAgentCertificationPage(input, options) { return this.request("open_agent_certification_page", input, options); }
-    /** Open one agent’s Test & certify Page: live certification per use case, recent test runs, AdCP 4.0 readiness and capability declarations. Read-only. Returns the data together with response headers and request ID. */
-    openAgentCertificationPageWithResponse(input, options) { return this.requestDetailed("open_agent_certification_page", input, options); }
     /**
      * Open one agent owned by this Developer account.
      *
@@ -199,13 +190,13 @@ export class Apostra extends Transport {
     /** Open the buyer Creative Engines Page. Optionally focus an engine, connection, or its secure setup control; the buyer starts setup in the Page, and this does not authorize a provider or start generation. Returns the data together with response headers and request ID. */
     openCreativeEnginesPageWithResponse(input, options) { return this.requestDetailed("open_creative_engines_page", input, options); }
     /**
-     * Open Creative Library. Use search for a plain object answer. Composer needs campaignId; assembly needs no Creative Engine. To save a draft, use exactly one format: a canonical format such as image, hosted video, or hosted audio, or a seller format.
+     * Open Creative Library. Use search for a plain object answer. The composer can start from an advertiser or a campaign and does not need a Creative Engine. To save a draft, use exactly one format: a canonical format such as image, hosted video, or hosted audio, or a seller format.
      *
      * @example
      * await client.openCreativeLibrary(input, { idempotencyKey: 'stable-key' })
      */
     openCreativeLibrary(input, options) { return this.request("open_creative_library", input, options); }
-    /** Open Creative Library. Use search for a plain object answer. Composer needs campaignId; assembly needs no Creative Engine. To save a draft, use exactly one format: a canonical format such as image, hosted video, or hosted audio, or a seller format. Returns the data together with response headers and request ID. */
+    /** Open Creative Library. Use search for a plain object answer. The composer can start from an advertiser or a campaign and does not need a Creative Engine. To save a draft, use exactly one format: a canonical format such as image, hosted video, or hosted audio, or a seller format. Returns the data together with response headers and request ID. */
     openCreativeLibraryWithResponse(input, options) { return this.requestDetailed("open_creative_library", input, options); }
     /**
      * Open the Developer home for this Developer account: its agents, their stages and what to do next.
@@ -271,13 +262,13 @@ export class Apostra extends Transport {
     /** Show a saved Creative Session’s variants (find via search/get kind creative_session). Not for generating new variants. Returns the data together with response headers and request ID. */
     openVariantGalleryWithResponse(input, options) { return this.requestDetailed("open_variant_gallery", input, options); }
     /**
-     * Rechecks one external sales-agent source with no-spend get_products and, if it publishes one, a catalog refresh. Returns each check, findings still open, evidence IDs and readiness; no source configuration or media buy.
+     * Rechecks one external sales-agent source with no-spend get_products and, if it publishes one, a catalog refresh. Returns each check, findings still open, evidence IDs and readiness; no source configuration or media buy. scope accounts re-lists the source's accounts instead.
      *
      * @example
      * await client.refreshInventorySourceHealth(input, { idempotencyKey: 'stable-key' })
      */
     refreshInventorySourceHealth(input, options) { return this.request("refresh_inventory_source_health", input, options); }
-    /** Rechecks one external sales-agent source with no-spend get_products and, if it publishes one, a catalog refresh. Returns each check, findings still open, evidence IDs and readiness; no source configuration or media buy. Returns the data together with response headers and request ID. */
+    /** Rechecks one external sales-agent source with no-spend get_products and, if it publishes one, a catalog refresh. Returns each check, findings still open, evidence IDs and readiness; no source configuration or media buy. scope accounts re-lists the source's accounts instead. Returns the data together with response headers and request ID. */
     refreshInventorySourceHealthWithResponse(input, options) { return this.requestDetailed("refresh_inventory_source_health", input, options); }
     /**
      * Request a Buyer child under the selected Organization. Nothing is created until an Organization administrator approves it on our site; the result is approval_required with a link to show the person. Repeat with the same idempotencyKey and name for the outcome.
@@ -370,13 +361,13 @@ export class Apostra extends Transport {
     /** Confirm a Sales Agent product mode, register a Sales or Creative Agent, or update an owned Agent: rename it or allow certification buys. To connect from a URL, send agentUrl with dryRun: true, show what was read, then send it without dryRun. A connected agent is not yet verified as theirs. Returns the data together with response headers and request ID. */
     saveAgentWithResponse(input, options) { return this.requestDetailed("save_agent", input, options); }
     /**
-     * File or update a typed ask in the Apostra Support workflow; returns askId. Supply is buyer inventory. Call immediately with type support when a person explicitly asks for a human; do not diagnose first.
+     * File or update a typed ask in the Apostra Support workflow; returns askId. kind create files a new ask; kind update sends only id and requester. Supply is buyer inventory. Call immediately with type support when a person explicitly asks for a human; do not diagnose first.
      *
      * @example
      * await client.saveAsk(input, { idempotencyKey: 'stable-key' })
      */
     saveAsk(input, options) { return this.request("save_ask", input, options); }
-    /** File or update a typed ask in the Apostra Support workflow; returns askId. Supply is buyer inventory. Call immediately with type support when a person explicitly asks for a human; do not diagnose first. Returns the data together with response headers and request ID. */
+    /** File or update a typed ask in the Apostra Support workflow; returns askId. kind create files a new ask; kind update sends only id and requester. Supply is buyer inventory. Call immediately with type support when a person explicitly asks for a human; do not diagnose first. Returns the data together with response headers and request ID. */
     saveAskWithResponse(input, options) { return this.requestDetailed("save_ask", input, options); }
     /**
      * Sync first-party CRM audiences for a buyer advertiser. Each audiences[] item may add, remove, or delete members. Returns an operationId; use get(kind: audience, advertiserId: "...") to read match status after it settles.
@@ -451,22 +442,22 @@ export class Apostra extends Transport {
     /** Manage seller or creative-engine authorization, accounts and advertiser mappings. Seller-only: reporting, selection, billing, policy, activation. Returns the data together with response headers and request ID. */
     saveConnectionWithResponse(input, options) { return this.requestDetailed("save_connection", input, options); }
     /**
-     * Declare publisher domains this Seller sells and its claimed properties. `domains` replaces the complete set; `add`, `remove`, `declareProperties`, and `removeProperties` change named items only. Read authorization; never assume it.
+     * Declare publisher domains this Seller sells and its claimed properties. `domains` replaces the complete set; `add`, `remove`, `declareProperties`, `removeProperties`, and `refresh` act on named items only. Read authorization; never assume it.
      *
      * @example
      * await client.saveCoverage(input, { idempotencyKey: 'stable-key' })
      */
     saveCoverage(input, options) { return this.request("save_coverage", input, options); }
-    /** Declare publisher domains this Seller sells and its claimed properties. `domains` replaces the complete set; `add`, `remove`, `declareProperties`, and `removeProperties` change named items only. Read authorization; never assume it. Returns the data together with response headers and request ID. */
+    /** Declare publisher domains this Seller sells and its claimed properties. `domains` replaces the complete set; `add`, `remove`, `declareProperties`, `removeProperties`, and `refresh` act on named items only. Read authorization; never assume it. Returns the data together with response headers and request ID. */
     saveCoverageWithResponse(input, options) { return this.requestDetailed("save_coverage", input, options); }
     /**
-     * advertiserId/campaignId:name,message;assets/landing_page_url/social/sourceAssetRef/sourceAssets;Supplied content/assets only;generate new media (radio spots):save_creative_session;exactly one format selector:formatKind/formatParams,creativeFormatId/formatOptionRef;libraryRole:Buyer Account only.
+     * Save content you supply: advertiserId/campaignId, name, message, assets (landing_page_url, social, sourceAssetRef/sourceAssets). New media like radio spots: use save_creative_session. One format selector: formatKind+formatParams or creativeFormatId+formatOptionRef. libraryRole: Buyer Account only.
      *
      * @example
      * await client.saveCreative(input, { idempotencyKey: 'stable-key' })
      */
     saveCreative(input, options) { return this.request("save_creative", input, options); }
-    /** advertiserId/campaignId:name,message;assets/landing_page_url/social/sourceAssetRef/sourceAssets;Supplied content/assets only;generate new media (radio spots):save_creative_session;exactly one format selector:formatKind/formatParams,creativeFormatId/formatOptionRef;libraryRole:Buyer Account only. Returns the data together with response headers and request ID. */
+    /** Save content you supply: advertiserId/campaignId, name, message, assets (landing_page_url, social, sourceAssetRef/sourceAssets). New media like radio spots: use save_creative_session. One format selector: formatKind+formatParams or creativeFormatId+formatOptionRef. libraryRole: Buyer Account only. Returns the data together with response headers and request ID. */
     saveCreativeWithResponse(input, options) { return this.requestDetailed("save_creative", input, options); }
     /**
      * Manage collections. Create with one owner and name: campaignId or advertiserId. Only advertiser mutations of an existing collection need expectedUpdatedAt; campaign writes and creates do not. isArchived archives or restores advertiser collections.
@@ -514,13 +505,13 @@ export class Apostra extends Transport {
     /** Create, change, archive, or restore up to 50 advertiser conversion event sources (pixels, server feeds). Each entry is keyed by eventSourceId and succeeds or fails alone. Setup is not proof events flow: check health with get, then use eventSourceId in an optimization goal. Returns the data together with response headers and request ID. */
     saveEventSourceWithResponse(input, options) { return this.requestDetailed("save_event_source", input, options); }
     /**
-     * Create or update where a seller's inventory comes from. Pass `id` to change a source or omit it to add one. Pass only `agentId` or `adServer` to open the form that connects an agent or an ad server. Credentials are never passed here; a source that needs one returns the page that collects it.
+     * Create or update where a seller's inventory comes from. Pass `id` to change a source or omit it to add one. Add a sales agent with only `agentId`, never its address, or an ad server with only `adServer`; each opens a form. Credentials are never passed here; a source that needs one returns its form.
      *
      * @example
      * await client.saveInventorySource(input, { idempotencyKey: 'stable-key' })
      */
     saveInventorySource(input, options) { return this.request("save_inventory_source", input, options); }
-    /** Create or update where a seller's inventory comes from. Pass `id` to change a source or omit it to add one. Pass only `agentId` or `adServer` to open the form that connects an agent or an ad server. Credentials are never passed here; a source that needs one returns the page that collects it. Returns the data together with response headers and request ID. */
+    /** Create or update where a seller's inventory comes from. Pass `id` to change a source or omit it to add one. Add a sales agent with only `agentId`, never its address, or an ad server with only `adServer`; each opens a form. Credentials are never passed here; a source that needs one returns its form. Returns the data together with response headers and request ID. */
     saveInventorySourceWithResponse(input, options) { return this.requestDetailed("save_inventory_source", input, options); }
     /**
      * Manage seller lessons in a seller account; send the accountId of that account. propose requires lesson; approve and retire require lessonId; preview requires lessonId and brief. Preserve seller words from a private Session note and ask if kind or scope is unclear.
@@ -550,13 +541,13 @@ export class Apostra extends Transport {
     /** Create or update seller Materials. Seller beta: preview, delete, Undo deletion, or Include again for one imported Library document. Delete archives it, excludes its source until Include again, and purges it after 30 days. https://docs.apostra.com/v3/delete-from-apostra Returns the data together with response headers and request ID. */
     saveMaterialWithResponse(input, options) { return this.requestDetailed("save_material", input, options); }
     /**
-     * Create DRAFT buy; no spend until confirmed. Meta: shared campaign=seller_optimized; ad sets=fixed; ask if unclear. Shared: omit buy/product budgets. Pause/resume: mediaBuyId + isPaused. Proposal: flight + total budget; omit products. channelGroupId: required if grouped; invalid ungrouped/updates.
+     * Create DRAFT buy; no spend until confirmed. Meta: shared campaign=seller_optimized; ad sets=fixed; ask if unclear. Shared: omit product budgets. Pause/resume: mediaBuyId + isPaused. Proposal: flight + total budget; omit products. channelGroupId: required if grouped; invalid ungrouped/updates.
      *
      * @example
      * await client.saveMediaBuy(input, { idempotencyKey: 'stable-key' })
      */
     saveMediaBuy(input, options) { return this.request("save_media_buy", input, options); }
-    /** Create DRAFT buy; no spend until confirmed. Meta: shared campaign=seller_optimized; ad sets=fixed; ask if unclear. Shared: omit buy/product budgets. Pause/resume: mediaBuyId + isPaused. Proposal: flight + total budget; omit products. channelGroupId: required if grouped; invalid ungrouped/updates. Returns the data together with response headers and request ID. */
+    /** Create DRAFT buy; no spend until confirmed. Meta: shared campaign=seller_optimized; ad sets=fixed; ask if unclear. Shared: omit product budgets. Pause/resume: mediaBuyId + isPaused. Proposal: flight + total budget; omit products. channelGroupId: required if grouped; invalid ungrouped/updates. Returns the data together with response headers and request ID. */
     saveMediaBuyWithResponse(input, options) { return this.requestDetailed("save_media_buy", input, options); }
     /**
      * Deprecated compatibility tool ("listing" is the modern term). It writes only the legacy businessProfile and does not update the canonical buyer-visible listing. New clients must read with `get({ kind: "seller", include: ["listing"] })` and write with `save_seller`.
@@ -613,13 +604,13 @@ export class Apostra extends Transport {
     /** Change one RFP turn: release it, request or cancel a proposal file, append feedback, or record its outcome. One of these per call; revise, endorse and attach a response with save_rfp. Returns the data together with response headers and request ID. */
     saveRfpTurnWithResponse(input, options) { return this.requestDetailed("save_rfp_turn", input, options); }
     /**
-     * Save Seller identity, capabilities, Apostra listing, buyer-visible listing (mediaKit is a deprecated alias), Distribution's OpenAI challenge token, an admission, or the intake hold. Scope3 eligibility and Market Maker entitlements are read-only here. Read Distribution with get(kind:"distribution").
+     * Save Seller identity, capabilities, buyer-visible listing (mediaKit is a deprecated alias), Distribution's OpenAI challenge token, an admission, the intake hold, or the demo's expiry and sample sources. Scope3 eligibility and Market Maker entitlements are read-only here. Read Distribution with get.
      *
      * @example
      * await client.saveSeller(input, { idempotencyKey: 'stable-key' })
      */
     saveSeller(input, options) { return this.request("save_seller", input, options); }
-    /** Save Seller identity, capabilities, Apostra listing, buyer-visible listing (mediaKit is a deprecated alias), Distribution's OpenAI challenge token, an admission, or the intake hold. Scope3 eligibility and Market Maker entitlements are read-only here. Read Distribution with get(kind:"distribution"). Returns the data together with response headers and request ID. */
+    /** Save Seller identity, capabilities, buyer-visible listing (mediaKit is a deprecated alias), Distribution's OpenAI challenge token, an admission, the intake hold, or the demo's expiry and sample sources. Scope3 eligibility and Market Maker entitlements are read-only here. Read Distribution with get. Returns the data together with response headers and request ID. */
     saveSellerWithResponse(input, options) { return this.requestDetailed("save_seller", input, options); }
     /**
      * Create, replace, or archive a signal. Managed writes need a complete draft; read before updates. Without sourceId, writes the seller catalog.