@zinn-digital/sdk 0.1.1396 → 0.1.1399

package/dist/generated/schema.d.ts

@@ -16135,6 +16135,52 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/ads/client-approval-links": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The client approval links the caller made (za-104).
+         * @description Gated on `ads.manage`, over every org the caller holds it in (an agency holds it on its clients through the reseller tree); narrowed by `?org_id=`. Newest first, at most 200. Never carries a token.
+         */
+        get: operations["listAdsClientApprovalLinks"];
+        put?: never;
+        /**
+         * Make an approval link for a client org (za-104).
+         * @description Gated on `ads.manage` on `org_id` (the CLIENT org); another org answers `404`. `days` 1-30 (default 14, else `badDays`); `label` is the agency's own note (plain text, else `badText`). The `201` carries `url` once — only the token's SHA-256 is stored. Audit action `ads.client_approval_link_created` on the client org.
+         */
+        post: operations["createAdsClientApprovalLink"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/ads/client-approval-links/{link_id}/revoke": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                link_id: string;
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Stop a client approval link working, now (za-104).
+         * @description Gated on `ads.manage` on the link's client org (else `404`). Twice is once. Audit action `ads.client_approval_link_revoked`.
+         */
+        post: operations["revokeAdsClientApprovalLink"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/ads/connect/amazon": {
         parameters: {
             query?: never;
@@ -18740,6 +18786,78 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/ads/connections/{connection_id}/prospecting": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connection_id: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * The Prospecting template's choices - business types, starter negatives, budget (za-158).
+         * @description Gated on `ads.view`. On the caller's own connection. The intents (category, problem, paid-competitor alternative, brand), the match types every keyword starts on (EXACT and PHRASE), each business type with its starter negatives and whether it is paid by default, the Recommended daily budget (five whole units of the account currency, also the floor) and how many prospecting templates wait for approval (docs/1006 §93). Read from stored rows, never a network call in the request.
+         */
+        get: operations["getAdsProspecting"];
+        put?: never;
+        /**
+         * Start building a Prospecting campaign preview from intent groups (za-158).
+         * @description Gated on `ads.manage`. Validates the template and its gates from stored rows, then STARTS the preview workflow and answers 202 with its `preview_id`; the account read (collision replay), the ONE batched translation and the ONE batched AI-writer request run in that workflow, never in the request. Poll `getAdsProspectingPreview`. The same input the same day is the same preview (a running or built one is not started again). The preview is one new Search campaign: a `category` group, a `problem` group, one `<Rival> alternative` group per PAID competitor (a free host is skipped, `notPaidCompetitor`; all are skipped without the competitor switch and plan, `competitorsOff`) and a `brand` group, every keyword on EXACT and PHRASE. The business type's starter negatives, plus the free-seeker class when `paid` is true; every negative passes the collision replay over the account's keywords and searches and the template's own keywords, and one that would block any of them is `dropped` with its reasons. Each group's ad names its topic and must reach GOOD (`waiting`, `adBelowGood` otherwise); the whole request passes the ad-quality gate (`status: refused`, `refused`). Refusals: `prospectingInvalid` (with the field), `killed`, `notInGoodStanding`, `needsReconnect`, `prospectingUnavailable`.
+         */
+        post: operations["buildAdsProspecting"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/ads/connections/{connection_id}/prospecting/{preview_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connection_id: string;
+                preview_id: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * One Prospecting preview - building, ready with the plan, failed or expired (za-158).
+         * @description Gated on `ads.view`. On the caller's own connection. `building` while the workflow runs, `ready` with the plan, `failed` with the refusal (`error.code`, as for `buildAdsProspecting`), `expired` once the run is no longer kept or finished more than a day ago (its account read is stale: build it again).
+         */
+        get: operations["getAdsProspectingPreview"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/ads/connections/{connection_id}/prospecting/{preview_id}/propose": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connection_id: string;
+                preview_id: string;
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Queue a ready Prospecting preview as ONE approve-first change (za-158).
+         * @description Gated on `ads.manage`. Fast: nothing is rebuilt. The gates (kill switch, good standing, campaign changes on) and the ad-quality gate run again on the preview's stored request, then it is queued as ONE pending change (`listAdsChanges`; audit action `ads.prospecting_propose`); proposing the same preview twice is the same pending change, and once that change is approved or applied it is that change again (never a second campaign). Nothing is sent to Google here: the metered gate runs when a person approves it. Refusals: `prospectingInvalid` (field `preview_id`: not ready), `killed`, `notInGoodStanding`, `needsReconnect`, `prospectingUnavailable`.
+         */
+        post: operations["proposeAdsProspecting"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/ads/connections/{connection_id}/quality-score": {
         parameters: {
             query?: never;
@@ -40416,6 +40534,52 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/public/ads-approvals/{token}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token: string;
+            };
+            cookie?: never;
+        };
+        /**
+         * The agency client approval portal — what waits on the client's accounts. Unauthenticated.
+         * @description ⛔ **No authentication.** The reader is the agency's client and has no account; the token is the whole authorisation and reaches the pending changes of ONE client org (never a sibling's, the agency's own, or an applied change). Unknown, revoked and expired tokens all answer the same `404`. Throttled per client address.
+         */
+        get: operations["viewAdsClientApprovalPortal"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/public/ads-approvals/{token}/changes/{change_id}/{action}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                action: "approve" | "reject";
+                change_id: string;
+                token: string;
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * The agency's client approves or rejects one pending change. Unauthenticated.
+         * @description Token-authorised like the page. `name` is required (1-80 characters, plain text, else `badName`); `reason` up to 500 (else `badReason`) and required to reject (`reasonRequired`). Runs the same decision as `decideAdsChange`: `approve` starts the send (202) and the kill switch, the spend ceilings and the account's good standing can still refuse it; `reject` answers 200. A change that is not pending on the link's org answers `404`. Audit action `ads.change_<action>` on the client org with `metadata.via = client_portal`, the link, the name and the reason.
+         */
+        post: operations["decideAdsChangeOnClientPortal"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/public/ads/call-numbers/{pool_key}": {
         parameters: {
             query?: {
@@ -62321,6 +62485,8 @@ export interface components {
             decided_at: string | null;
             /** @description Who approved or declined it (`autopilot` when the audit made it by itself; a person who applied the audit's one-click suggestion is named here although `proposed_by` stays `autopilot`, WALK239): who stored it (`user:<id>`, `autopilot`, `mcp:<id>`, `apikey:<id>`, …) — except a member of our staff, who reads `support` and never their id (VERIFY-ADSACTOR: an impersonated write is recorded as the staff member); a reseller's sign-in into this account (`apikey:<reseller key>` or the reseller's own `user:<id>`) reads the reseller's display name — `support` when that actor's sign-ins reach the clients of more than one parent, or its org is gone (ACTORS7, VERIFY-ACTORS7). */
             decided_by: string;
+            /** @description za-104: the reason given with the decision. An agency's client must give one to reject on the approval portal; `decided_by` then reads `client-portal:<link id>:<the name they typed>`. Empty otherwise. */
+            decision_reason?: string;
             /** @description Why the change was not sent, its CODE leading (`ceiling`, `killed`, `paused`, `disconnected`, `standing: …`, `needsReconnect`, `adBelowGood`, `xWritesOff`, za-70 `collides` — the collision simulator found what `summary.collision` names — or `collisionUnread` — the account could not be read for the replay — and za-10 `convertingSearch: …` — a negative keyword that would block a search with a conversion in the last 30 days, refused at the send even when a person approved it; SERVEWATCH `strategyStarves` — a bid-strategy switch whose ceiling or bids cannot win most of the campaign's searches against Google's own top-of-page estimates, refused whoever asked, its figures in `summary.serving_check`; UNDOSTRAT, on an APPLIED change whose Undo puts a bid strategy back: `killed` · `paused` · `standing` · `strategyStarves` followed by `: undo refused` — the restore passes the kill switch, good standing and the same simulation — and `undoReadBackDiffers: <campaigns>`, the strategy Google read back after the Undo is not `summary.bidding_before`, so the change stays applied and its Undo can be sent again); otherwise the network's own sentence. Empty when nothing went wrong. */
             error: string;
             /** Format: uuid */
@@ -62401,6 +62567,76 @@ export interface components {
                 message: string;
             };
         };
+        /** @description za-104 (docs/1006 §112): one expiring link that lets an agency's client approve or reject the changes waiting on THEIR org's ad accounts, under the agency's brand. */
+        AdsClientApprovalLink: {
+            /** Format: date-time */
+            created_at: string;
+            created_by: string;
+            decisions: number;
+            /** Format: date-time */
+            expires_at: string;
+            /** Format: uuid */
+            id: string;
+            label: string;
+            /** Format: date-time */
+            last_used_at: string | null;
+            live: boolean;
+            /**
+             * Format: uuid
+             * @description The CLIENT org the link reaches.
+             */
+            org_id: string;
+            /** Format: date-time */
+            revoked_at: string | null;
+            /**
+             * Format: uri
+             * @description Only in the `201` that made the link — the token is never stored and cannot be shown again. On the agency's own panel address once that address is live.
+             */
+            url?: string;
+        };
+        AdsClientPortal: {
+            /** @description The brand the client org renders under — the agency's, when it has one. */
+            brand: {
+                is_white_label: boolean;
+                logo_url: string;
+                name: string;
+                primary_colour: string;
+                support_url: string;
+            };
+            /** @description What this link decided in the last 30 days. */
+            decided: components["schemas"]["AdsClientPortalChange"][];
+            /** Format: date-time */
+            expires_at: string;
+            pending: components["schemas"]["AdsClientPortalChange"][];
+        };
+        /** @description What the agency's client sees of one change — no vendor path, no actor ids. */
+        AdsClientPortalChange: {
+            account_name: string;
+            action_class: string;
+            /**
+             * Format: int64
+             * @description The daily budget increase asked for, minor units of `currency`.
+             */
+            budget_delta_minor: number | null;
+            /** @description ISO 4217 code of the ad account. */
+            currency: string;
+            /** Format: date-time */
+            decided_at: string | null;
+            /** @description The name the client typed; empty while pending. */
+            decided_by_name: string;
+            decision_reason: string;
+            /** @description Only on a refused or failed change. */
+            error: string;
+            /** Format: uuid */
+            id: string;
+            /** Format: date-time */
+            proposed_at: string;
+            /** @enum {string} */
+            status: "pending" | "approved" | "applied" | "rejected" | "refused" | "failed" | "undone";
+            summary: {
+                [key: string]: unknown;
+            };
+        };
         AdsCompetitorGroup: {
             /** @description The proposed group, `<Rival> alternative`. */
             ad_group: string;
@@ -64236,6 +64472,100 @@ export interface components {
             /** @description true = the provider reports its own fee (Paddle, Freemius); the estimate is not used. */
             readonly reports_fee?: boolean;
         };
+        AdsProspectingInfoEnvelope: {
+            data: {
+                business_type: string;
+                business_types: {
+                    paid_by_default: boolean;
+                    starter_negatives: string[];
+                    value: string;
+                }[];
+                currency: string;
+                intents: ("category" | "problem" | "alternative" | "brand")[];
+                matches: ("EXACT" | "PHRASE")[];
+                pending: number;
+                recommended_budget_minor: number;
+            };
+        };
+        AdsProspectingPlan: {
+            business_type: string;
+            campaign: {
+                country: string;
+                currency: string;
+                daily_budget_minor: number;
+                final_url: string;
+                language: string;
+                name: string;
+                recommended_budget_minor: number;
+            };
+            change_id: string | null;
+            free_seeker: boolean;
+            groups: {
+                descriptions?: string[];
+                headlines?: string[];
+                /** @enum {string} */
+                intent: "category" | "problem" | "alternative" | "brand";
+                keywords: {
+                    /** @enum {string} */
+                    match: "EXACT" | "PHRASE";
+                    text: string;
+                }[];
+                name: string;
+                reason: string;
+                rival?: string;
+                /** @enum {string} */
+                status: "ready" | "waiting" | "skipped";
+            }[];
+            negatives: {
+                /** @enum {string} */
+                class: "starter" | "free_seeker";
+                /** @enum {string} */
+                match: "EXACT" | "PHRASE";
+                reasons: string[];
+                /** @enum {string} */
+                status: "kept" | "dropped";
+                text: string;
+            }[];
+            paid: boolean;
+            refused: {
+                [key: string]: unknown;
+            } | null;
+            /** @enum {string} */
+            status: "preview" | "proposed" | "refused" | "nothingReady" | "rejectedBefore";
+        };
+        AdsProspectingPreviewEnvelope: {
+            data: {
+                error: {
+                    code: string;
+                    field: string;
+                } | null;
+                plan: components["schemas"]["AdsProspectingPlan"] | null;
+                preview_id: string;
+                /** @enum {string} */
+                status: "building" | "ready" | "failed" | "expired";
+            };
+        };
+        AdsProspectingRequest: {
+            brand: string;
+            brand_terms?: string[];
+            /** @enum {string} */
+            business_type?: "free_trial" | "freemium" | "lead_gen" | "ecommerce" | "local" | "b2b";
+            category: string[];
+            competitors?: string[];
+            /** @description ISO 3166-1 alpha-2. */
+            country: string;
+            /** @description Minor units of the account currency; null = Recommended (five whole units, also the floor). */
+            daily_budget_minor?: number | null;
+            descriptions?: string[];
+            /** Format: uri */
+            final_url: string;
+            headlines?: string[];
+            /** @default en */
+            language: string;
+            /** @description null = the business type's default (freemium is not paid). */
+            paid?: boolean | null;
+            problems?: string[];
+        };
         AdsQsDiagnosis: {
             ad_group: string;
             /** @description BELOW_AVERAGE, AVERAGE, ABOVE_AVERAGE or empty. */
@@ -134863,6 +135193,91 @@ export interface operations {
             429: components["responses"]["TooManyRequests"];
         };
     };
+    listAdsClientApprovalLinks: {
+        parameters: {
+            query?: {
+                org_id?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The links. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["AdsClientApprovalLink"][];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    createAdsClientApprovalLink: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @default 14 */
+                    days?: number;
+                    label?: string;
+                    /** Format: uuid */
+                    org_id: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Made; copy `url` now. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsClientApprovalLink"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    revokeAdsClientApprovalLink: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                link_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Revoked. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsClientApprovalLink"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            404: components["responses"]["NotFound"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     startAdsConnectAmazon: {
         parameters: {
             query?: never;
@@ -139843,6 +140258,119 @@ export interface operations {
             429: components["responses"]["TooManyRequests"];
         };
     };
+    getAdsProspecting: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connection_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The template's choices. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsProspectingInfoEnvelope"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    buildAdsProspecting: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connection_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["AdsProspectingRequest"];
+            };
+        };
+        responses: {
+            /** @description The preview is being built; poll it by `preview_id`. */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsProspectingPreviewEnvelope"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    getAdsProspectingPreview: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connection_id: string;
+                preview_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The preview. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsProspectingPreviewEnvelope"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    proposeAdsProspecting: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                connection_id: string;
+                preview_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The plan with `status` `proposed` and its `change_id`, or `refused`. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsProspectingPreviewEnvelope"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     getAdsQualityScore: {
         parameters: {
             query?: never;
@@ -175859,6 +176387,73 @@ export interface operations {
             409: components["responses"]["Conflict"];
         };
     };
+    viewAdsClientApprovalPortal: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                token: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The brand, the pending changes and what this link decided. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsClientPortal"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    decideAdsChangeOnClientPortal: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                action: "approve" | "reject";
+                change_id: string;
+                token: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    name: string;
+                    reason?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description Rejected. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsClientPortalChange"];
+                };
+            };
+            /** @description Approved; the send started. */
+            202: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsClientPortalChange"];
+                };
+            };
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     getAdsCallPoolNumber: {
         parameters: {
             query?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zinn-digital/sdk",
-  "version": "0.1.1396",
+  "version": "0.1.1399",
   "description": "Typed TypeScript client for the Zinn Digital Platform API, generated from its OpenAPI spec.",
   "license": "MIT",
   "author": "Neil Lock \u2014 CEO, Zinn Digital\u00ae Ltd <office@zinndigital.com>",