@zinn-digital/sdk 0.1.1421 → 0.1.1424

package/dist/generated/schema.d.ts

@@ -5479,6 +5479,8 @@ export interface paths {
          *
          *     **Written for every box the automation REACHED, before its outcome is judged**, so a box that fails every time still shows a recent attempt rather than looking untouched. `ok` and `failed` are both recorded; only *never attempted* leaves the fields empty, and that is the state worth seeing.
          *
+         *     A note of exactly `ok` also resolves the OPEN converge ops alerts (`box-job:fleet-apply`, `box-job:worker-converge`) whose only failing box is this one, whichever converge path raised them (s1014 CONVERGECLEAR).
+         *
          *     A hostname the engine does not know is a **404**, never a quiet 200 — the automation reporting about a box the fleet registry has never heard of is a real disagreement between the two, and swallowing it would re-create the divergence this pair exists to remove.
          *
          *     **Auth: a GitHub Actions OIDC token from `worker-converge.yml`, or a staff member with `fleet.manage`** — the converge runs on the platform's own box since 2026-10-15 and reports as the staff verification identity; a staff write is audited (`fleet.converge_result.recorded`). This writes, so it is a separate grant from the read-only freshness view (`fleet.view` is refused).
@@ -15967,6 +15969,66 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/ads/analytics/breakdown": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Zinn® Ads analytics leaderboard by network, account, campaign, country or product/site (za-280).
+         * @description Rows sorted by spend, paged with `offset` and `limit` (`total` counts every row), each with its comparison figures and a spend sparkline. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Stored rows only (the daily audit's figures), never a network call. Money is integer micros of the reporting `currency`: each account's currency is converted at the CURRENT stored rate, named in `fx`; a currency with no rate is left out of the blended figures and listed in `unconverted`. Conversions are thousandths; ROAS, CTR and conversion rate are basis points; CPA and CPC are micros; a ratio with no denominator is null (za-280).
+         */
+        get: operations["getAdsAnalyticsBreakdown"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/ads/analytics/summary": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Zinn® Ads analytics KPI tiles for a period and its comparison (za-280).
+         * @description The period and comparison-period totals with a sparkline per figure, and the totals per account currency. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Stored rows only (the daily audit's figures), never a network call. Money is integer micros of the reporting `currency`: each account's currency is converted at the CURRENT stored rate, named in `fx`; a currency with no rate is left out of the blended figures and listed in `unconverted`. Conversions are thousandths; ROAS, CTR and conversion rate are basis points; CPA and CPC are micros; a ratio with no denominator is null (za-280).
+         */
+        get: operations["getAdsAnalyticsSummary"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/ads/analytics/timeseries": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Zinn® Ads analytics trend per day, week or month (za-280).
+         * @description Every bucket of the period (zero-filled) with all figures, the comparison period bucket by bucket, and spend and value per network for the stacked network share. Gated on `ads.view` over the organisations the person can view; `org_id` narrows to that organisation and its client organisations. Stored rows only (the daily audit's figures), never a network call. Money is integer micros of the reporting `currency`: each account's currency is converted at the CURRENT stored rate, named in `fx`; a currency with no rate is left out of the blended figures and listed in `unconverted`. Conversions are thousandths; ROAS, CTR and conversion rate are basis points; CPA and CPC are micros; a ratio with no denominator is null (za-280).
+         */
+        get: operations["getAdsAnalyticsTimeseries"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/ads/asks": {
         parameters: {
             query?: never;
@@ -62306,6 +62368,113 @@ export interface components {
             connection_id: string;
             data: components["schemas"]["AdsAllowedTerm"][];
         };
+        AdsAnalyticsBreakdown: components["schemas"]["AdsAnalyticsFrame"] & {
+            /** @enum {string} */
+            by: "network" | "connection" | "campaign" | "country" | "offering";
+            limit: number;
+            offset: number;
+            rows: components["schemas"]["AdsAnalyticsRow"][];
+            total: number;
+        };
+        AdsAnalyticsFigures: {
+            /** Format: int64 */
+            clicks: number;
+            /** Format: int64 */
+            conv_rate_bp: number | null;
+            /** Format: int64 */
+            conversions_milli: number;
+            /** Format: int64 */
+            cost_micros: number;
+            /** Format: int64 */
+            cpa_micros: number | null;
+            /** Format: int64 */
+            cpc_micros: number | null;
+            /** Format: int64 */
+            ctr_bp: number | null;
+            /** Format: int64 */
+            impressions: number;
+            /** Format: int64 */
+            roas_bp: number | null;
+            /** Format: int64 */
+            value_micros: number;
+        };
+        AdsAnalyticsFrame: {
+            accounts: number;
+            /** @enum {string} */
+            compare: "previous" | "year" | "none";
+            /** Format: date */
+            compare_first_day: string | null;
+            /** Format: date */
+            compare_last_day: string | null;
+            currency: string;
+            /** Format: date */
+            first_day: string;
+            fx: components["schemas"]["AdsAnalyticsFx"][];
+            /** @enum {string} */
+            grain: "day" | "week" | "month";
+            /** Format: date */
+            last_day: string;
+            range: string;
+            /** @description Currencies left out of the blended figures for want of a stored rate; `???` stands for accounts whose currency is not known. */
+            unconverted: string[];
+        };
+        AdsAnalyticsFx: {
+            /** @description When the stored rate was fetched (ISO 8601). */
+            as_of: string;
+            from: string;
+            /** @description Major-unit multiplier */
+            rate: string;
+            to: string;
+        };
+        AdsAnalyticsPoint: components["schemas"]["AdsAnalyticsFigures"] & {
+            /** Format: date */
+            bucket: string;
+        };
+        AdsAnalyticsRow: components["schemas"]["AdsAnalyticsFigures"] & {
+            account?: string;
+            assigned?: boolean;
+            campaign_id?: string;
+            /** Format: uuid */
+            connection_id?: string;
+            country?: string;
+            currencies: string[];
+            key: string;
+            kind?: string;
+            label: string;
+            network?: string;
+            /** Format: uuid */
+            offering_id?: string | null;
+            /** Format: uuid */
+            org_id?: string;
+            previous: components["schemas"]["AdsAnalyticsFigures"] | null;
+            spark_cost_micros: number[];
+        };
+        AdsAnalyticsSeries: {
+            buckets?: string[];
+            clicks: number[];
+            conversions_milli: number[];
+            cost_micros: number[];
+            impressions: number[];
+            value_micros: number[];
+        };
+        AdsAnalyticsSummary: components["schemas"]["AdsAnalyticsFrame"] & {
+            by_currency: (components["schemas"]["AdsAnalyticsFigures"] & {
+                currency: string;
+            })[];
+            current: components["schemas"]["AdsAnalyticsFigures"];
+            previous: components["schemas"]["AdsAnalyticsFigures"] | null;
+            previous_sparklines: components["schemas"]["AdsAnalyticsSeries"] | null;
+            sparklines: components["schemas"]["AdsAnalyticsSeries"];
+        };
+        AdsAnalyticsTimeseries: components["schemas"]["AdsAnalyticsFrame"] & {
+            networks: {
+                cost_micros: number[];
+                network: string;
+                value_micros: number[];
+            }[];
+            points: components["schemas"]["AdsAnalyticsPoint"][];
+            previous: components["schemas"]["AdsAnalyticsPoint"][] | null;
+        };
         /** @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. */
@@ -110694,6 +110863,25 @@ export interface components {
          *     ⚠️ A value that is not a UUID is **ignored**, not refused — the answer is exactly what you would get with no header at all.
          */
         ActiveOrg: string;
+        /** @description Comma-separated `<connection_id>:<campaign_id>` tokens. */
+        AdsAnalyticsCampaign: string;
+        AdsAnalyticsCompare: "previous" | "year" | "none";
+        /** @description Comma-separated ad-account connection ids. */
+        AdsAnalyticsConnection: string;
+        /** @description Comma-separated ISO 3166-1 alpha-2 codes. Reads the country-level figures. */
+        AdsAnalyticsCountry: string;
+        /** @description Reporting currency (ISO 4217). Default the one currency in play, else the organisation's. */
+        AdsAnalyticsCurrency: string;
+        AdsAnalyticsFrom: string;
+        /** @description Bucket size. Default day up to 92 days, week up to 366, month beyond. */
+        AdsAnalyticsGrain: "day" | "week" | "month";
+        /** @description Comma-separated networks (google, microsoft, meta, linkedin, tiktok, x, pinterest, amazon). */
+        AdsAnalyticsNetwork: string;
+        /** @description Comma-separated product/site ids (za-290), or `unassigned`. */
+        AdsAnalyticsOffering: string;
+        /** @description The period. `custom` takes `from` and `to`. */
+        AdsAnalyticsRange: "7d" | "30d" | "90d" | "ytd" | "12m" | "custom";
+        AdsAnalyticsTo: string;
         /** @description Board card attachment ID (UUIDv7). */
         AgencyBoardAttachmentId: components["schemas"]["Uuid"];
         /** @description Board card ID (UUIDv7). */
@@ -135984,6 +136172,153 @@ export interface operations {
             429: components["responses"]["TooManyRequests"];
         };
     };
+    getAdsAnalyticsBreakdown: {
+        parameters: {
+            query?: {
+                by?: "network" | "connection" | "campaign" | "country" | "offering";
+                /** @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"];
+                limit?: number;
+                /** @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"];
+                offset?: number;
+                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"]["AdsAnalyticsBreakdown"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    getAdsAnalyticsSummary: {
+        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"]["AdsAnalyticsSummary"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    getAdsAnalyticsTimeseries: {
+        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"]["AdsAnalyticsTimeseries"];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     listAdsAsks: {
         parameters: {
             query?: {

package/package.json

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