@zinn-digital/sdk 0.1.1427 → 0.1.1430

package/dist/generated/schema.d.ts

@@ -15989,6 +15989,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/ads/analytics/impact": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * How Zinn® Ads helped - money saved, fraud blocked, refunds won, conversions recovered, changes and before vs after (za-281).
+         * @description Over the same filters as the other analytics reads: wasted spend blocked (search terms and keywords the audit found spending with no conversion, then blocked or paused, with the measured cost and clicks before the block), invalid clicks excluded by the click shield (their measured cost), credits the network granted for invalid activity, conversions Zinn® Ads uploaded that the network's own tag had missed, the changes Zinn® Ads made by kind (changes the customer made, in the dashboard or with their own API key, are not counted) with how many can still be undone, the self-check verdicts of the changes scored in the period, and ROAS over the 90 days before the first account was connected and since. `money_saved_micros` is waste blocked plus, per account and currency, the larger of fraud blocked and refunds won (a credit refunds the same invalid clicks the exclusions measured, so that money is counted once), all measured. `hours_saved` is a MODEL (changes times the stated minutes per change), flagged `modelled: true`. Each list is the latest 20 items with the full `count` beside it; a waste item carries the change that blocked it and whether it can still be undone. Network and account filters apply to every section. The campaign filter narrows waste blocked, fraud blocked (account-level exclusions stay), the self-check verdicts and before vs after; refunds won, conversions recovered and changes made are account-wide and ignore it. Country and product/site filters apply to before vs after only. A fraud item's Undo is offered only where the server accepts it: Google has named it, no removal is under way, and it was applied inside the 30-day undo window. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Stored rows only, never a network call. Money is integer micros of the reporting `currency` at the current stored rate (`fx`).
+         */
+        get: operations["getAdsAnalyticsImpact"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/ads/analytics/summary": {
         parameters: {
             query?: never;
@@ -20477,7 +20497,7 @@ export interface paths {
         put?: never;
         /**
          * Undo one click-shield exclusion (one click).
-         * @description Gated on `ads.manage` (IPROTATE, za-59). The person's click approves the removal of that one exclusion at Google (sent by the apply workflow, through the metered driver) and the exclusion is never proposed again for its campaign. Refused (422) when it is not at Google (`notApplied`), Google has not confirmed it yet (`notYetAtGoogle`) or a removal is already on its way (`alreadyRemoving`). The daily e-mail's Undo link for one exclusion runs this same path through `actOnAdsEmailLink`. A Microsoft website exclusion is removed from the campaign's list the same way; a Meta `listed` one only leaves the Zinn-held block list (nothing is sent to Meta) and is never listed again.
+         * @description Gated on `ads.manage` (IPROTATE, za-59). The person's click approves the removal of that one exclusion at Google (sent by the apply workflow, through the metered driver) and the exclusion is never proposed again for its campaign. Refused (422) when it is not at Google (`notApplied`), Google has not confirmed it yet (`notYetAtGoogle`), a removal is already on its way (`alreadyRemoving`) or it was applied more than 30 days ago (`refusal.adsconnect.undoExpired`, the same undo window as every Zinn® Ads change). The daily e-mail's Undo link for one exclusion runs this same path through `actOnAdsEmailLink`. A Microsoft website exclusion is removed from the campaign's list the same way; a Meta `listed` one only leaves the Zinn-held block list (nothing is sent to Meta) and is never listed again.
          */
         post: operations["undoAdsShieldExclusion"];
         delete?: never;
@@ -62479,6 +62499,117 @@ export interface components {
             rate: string;
             to: string;
         };
+        AdsAnalyticsImpact: components["schemas"]["AdsAnalyticsFrame"] & {
+            before_after: {
+                after: components["schemas"]["AdsAnalyticsImpactPeriod"];
+                before: components["schemas"]["AdsAnalyticsImpactPeriod"];
+                /** Format: date */
+                started_on: string | null;
+            };
+            changes: {
+                by_kind: {
+                    count: number;
+                    kind: string;
+                    undoable: number;
+                }[];
+                total: number;
+                undoable: number;
+            };
+            effect: {
+                better: number;
+                /** Format: int64 */
+                conversions_gained_milli: number;
+                no_data: number;
+                same: number;
+                worse: number;
+            };
+            fraud: {
+                /** Format: int64 */
+                clicks: number;
+                /** Format: int64 */
+                cost_micros: number;
+                count: number;
+                items: {
+                    /** Format: date-time */
+                    blocked_at: string | null;
+                    can_undo: boolean;
+                    clicks: number;
+                    /** Format: uuid */
+                    connection_id: string;
+                    /** Format: int64 */
+                    cost_micros: number;
+                    /** Format: uuid */
+                    id: string;
+                    kind: string;
+                    label: string;
+                }[];
+            };
+            hours_saved: {
+                default_minutes: number;
+                minutes: number;
+                minutes_per_change: {
+                    [key: string]: number;
+                };
+                /** @description Always true - an estimate from the stated minutes per change */
+                modelled: boolean;
+            };
+            /**
+             * Format: int64
+             * @description Waste blocked plus fraud blocked plus refunds won (measured).
+             */
+            money_saved_micros: number;
+            recovered: {
+                conversions: number;
+                /** Format: int64 */
+                value_micros: number;
+            };
+            refunds: {
+                count: number;
+                /** Format: int64 */
+                credited_micros: number;
+                items: {
+                    /** Format: uuid */
+                    connection_id: string;
+                    /** Format: int64 */
+                    credited_micros: number;
+                    /** Format: uuid */
+                    id: string;
+                    /** Format: date */
+                    month: string | null;
+                }[];
+            };
+            waste: {
+                /** Format: int64 */
+                clicks: number;
+                /** Format: int64 */
+                cost_micros: number;
+                count: number;
+                items: {
+                    /** Format: date-time */
+                    blocked_at: string | null;
+                    campaign: string;
+                    can_undo: boolean;
+                    /** Format: uuid */
+                    change_id: string | null;
+                    clicks: number;
+                    /** Format: uuid */
+                    connection_id: string;
+                    /** Format: int64 */
+                    cost_micros: number;
+                    /** Format: uuid */
+                    id: string;
+                    /** @enum {string} */
+                    kind: "waste_term" | "poor_keyword";
+                    text: string;
+                }[];
+            };
+        };
+        AdsAnalyticsImpactPeriod: (components["schemas"]["AdsAnalyticsFigures"] & {
+            /** Format: date */
+            first_day: string;
+            /** Format: date */
+            last_day: string;
+        }) | null;
         AdsAnalyticsPoint: components["schemas"]["AdsAnalyticsFigures"] & {
             /** Format: date */
             bucket: string;
@@ -119352,7 +119483,7 @@ export interface operations {
             query?: {
                 /** @description `true` restricts to still-open purchases past their due date. A completed job past its deadline is not overdue -- it was delivered. */
                 overdue?: "true";
-                /** @description `open` (default: awaiting_staff + fulfilling), `all`, or one exact status. `fulfilling` is in the default set on purpose: an automated extra stuck mid-workflow is also work nobody is doing. */
+                /** @description `open` (default: awaiting_staff + fulfilling), `all`, or one exact status. `fulfilling` is in the default set on purpose: an automated extra stuck mid-workflow is also work nobody is doing. An AI Move's $0 purchase is left out of `open` while the AI is running it and shown once it escalates (needs staff, taken over, or past its SLA). */
                 status?: string;
             };
             header?: never;
@@ -136348,6 +136479,54 @@ export interface operations {
             429: components["responses"]["TooManyRequests"];
         };
     };
+    getAdsAnalyticsImpact: {
+        parameters: {
+            query?: {
+                /** @description Comma-separated `<connection_id>:<campaign_id>` tokens. */
+                campaign?: components["parameters"]["AdsAnalyticsCampaign"];
+                compare?: components["parameters"]["AdsAnalyticsCompare"];
+                /** @description Comma-separated ad-account connection ids. */
+                connection?: components["parameters"]["AdsAnalyticsConnection"];
+                /** @description Comma-separated ISO 3166-1 alpha-2 codes. Reads the country-level figures. */
+                country?: components["parameters"]["AdsAnalyticsCountry"];
+                /** @description Reporting currency (ISO 4217). Default the one currency in play, else the organisation's. */
+                currency?: components["parameters"]["AdsAnalyticsCurrency"];
+                from?: components["parameters"]["AdsAnalyticsFrom"];
+                /** @description Bucket size. Default day up to 92 days, week up to 366, month beyond. */
+                grain?: components["parameters"]["AdsAnalyticsGrain"];
+                /** @description Comma-separated networks (google, microsoft, meta, linkedin, tiktok, x, pinterest, amazon). */
+                network?: components["parameters"]["AdsAnalyticsNetwork"];
+                /** @description Comma-separated product/site ids (za-290), or `unassigned`. */
+                offering?: components["parameters"]["AdsAnalyticsOffering"];
+                org_id?: string;
+                /** @description The period. `custom` takes `from` and `to`. */
+                range?: components["parameters"]["AdsAnalyticsRange"];
+                to?: components["parameters"]["AdsAnalyticsTo"];
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The figures. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["AdsAnalyticsImpact"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     getAdsAnalyticsSummary: {
         parameters: {
             query?: {

package/package.json

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