@zinn-digital/sdk 0.1.1400 → 0.1.1401

package/dist/generated/schema.d.ts

@@ -15902,6 +15902,52 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/ads/asks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The organisation's recent "Ask your ads" questions and their checked answers (za-N7).
+         * @description Gated on `ads.view`; the 20 most recent asks of the caller's organisation (narrow with `?org_id=`), newest first. Never another organisation's (docs/1006 §ASKADS).
+         */
+        get: operations["listAdsAsks"];
+        put?: never;
+        /**
+         * Ask a plain question about the organisation's own ads; the answer is checked figure by figure against cited facts (za-N7).
+         * @description Gated on `ads.view` in ONE organisation (`org_id` in the body or `X-Zinn-Org` when the caller holds several). Interactive: one Zinn® AI call in the request, no job queue. The facts are read ONLY from the organisation's own synced figures (account totals, spend per day for up to 31 recent days, campaigns ranked by spend, Google keywords and search terms that spend with no conversion, open findings, changes waiting). `status`: `answered` (every number in `answer` appears in a fact it cites — ids in `cites`, figures in `facts`), `facts_only` (the written answer failed that check and is withheld; the cited facts are the answer), `refused` (no AI credit, or the organisation is not in good standing — `error.failure` class `refused`, nothing was spent) or `failed` (the AI provider failed — `error.failure` names the class: outage with its status page, a customer key problem, or ours). Who pays is the one meter's decision: the organisation's own AI key, else its Zinn® AI credit. At most ONE `fix` is offered, built from a fact (never by the model): `pause_campaign` or `pause_keyword` for a Google campaign or keyword that spends with no conversion. `422` codes: `askQuestion` (1 to 500 characters), `askDays` (1 to 90), `askNoAccounts`, `askHourly` (60 asks per organisation per hour). `404` for a `connection_id` that is not the organisation's.
+         */
+        post: operations["createAdsAsk"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/ads/asks/{ask_id}/fix": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                ask_id: string;
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Keep the answer's one fix as a change waiting for approval (za-N7).
+         * @description Gated on `ads.manage` in the ask's organisation and written to its activity log. Keeps the fix as ONE pending change in the approval queue (`proposed_by` the person, `summary` `auto_action` `ask_pause_campaign` or `ask_pause_keyword`). Nothing reaches the ad network until a person approves it (`POST /v1/ads/changes/{change_id}/approve`), where the kill switches, ceilings and standing still decide; an applied pause keeps its 30-day Undo. Asking twice returns the same change. `422 askNoFix` when the answer offered none.
+         */
+        post: operations["proposeAdsAskFix"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/ads/autopilot-decisions": {
         parameters: {
             query?: never;
@@ -61767,6 +61813,57 @@ export interface components {
             connection_id: string;
             data: components["schemas"]["AdsAllowedTerm"][];
         };
+        /** @description One "Ask your ads" question and its checked answer (za-N7, docs/1006 §ASKADS). */
+        AdsAsk: {
+            /** @description Empty unless `answered`. Fact ids appear in square brackets after the figures they back. */
+            answer: string;
+            cites: string[];
+            /** Format: uuid */
+            connection_id: string | null;
+            /** Format: date-time */
+            created_at: string;
+            days: number;
+            error: {
+                can_buy?: boolean;
+                code?: string;
+                failure?: components["schemas"]["VendorFailure"];
+                reason?: string;
+            } | null;
+            facts: components["schemas"]["AdsAskFact"][];
+            fix: {
+                /** @enum {string} */
+                action: "pause_campaign" | "pause_keyword";
+                /**
+                 * Format: uuid
+                 * @description Set once proposed.
+                 */
+                change_id: string | null;
+                /** Format: uuid */
+                connection_id: string;
+                fact_id: string;
+            } | null;
+            /** Format: uuid */
+            id: string;
+            locale: string;
+            question: string;
+            /** @enum {string} */
+            status: "answered" | "facts_only" | "refused" | "failed";
+        };
+        /** @description One cited fact. `kind`: `account`, `day`, `campaign`, `keyword`, `search_term`, `findings`, `pending`; `figures` are the strings shown (money with its currency code, truncated to the currency's minor unit). */
+        AdsAskFact: {
+            /** Format: uuid */
+            connection_id: string;
+            figures: {
+                [key: string]: string;
+            };
+            fix?: {
+                /** @enum {string} */
+                action?: "pause_campaign" | "pause_keyword";
+            };
+            id: string;
+            /** @enum {string} */
+            kind: "account" | "day" | "campaign" | "keyword" | "search_term" | "findings" | "pending";
+        };
         /** @description A customer's own Customer Match list (docs/1006 §72). Counts only, never an identifier. */
         AdsAudience: {
             /** @description False once emptied. */
@@ -134693,6 +134790,102 @@ export interface operations {
             429: components["responses"]["TooManyRequests"];
         };
     };
+    listAdsAsks: {
+        parameters: {
+            query?: {
+                org_id?: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The recent asks. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["AdsAsk"][];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    createAdsAsk: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /**
+                     * Format: uuid
+                     * @description Narrow to one ad account.
+                     */
+                    connection_id?: string;
+                    /** @default 30 */
+                    days?: number;
+                    /** @description The answer's language, e.g. en, ar. */
+                    locale?: string;
+                    /** Format: uuid */
+                    org_id?: string;
+                    question: string;
+                };
+            };
+        };
+        responses: {
+            /** @description The ask, its status and (when answered) the checked answer. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsAsk"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    proposeAdsAskFix: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                ask_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The pending change. */
+            201: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AdsChange"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     getAdsAutopilotDecisions: {
         parameters: {
             query?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zinn-digital/sdk",
-  "version": "0.1.1400",
+  "version": "0.1.1401",
   "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>",