@poweredbysous/storefront-sdk 3.6.0 → 3.7.0

package/dist/index.d.cts

@@ -2461,6 +2461,23 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/visits/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Record one storefront visit and send it to Cerebro. */
+        post: operations["visits_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/withdrawals/confirm/": {
         parameters: {
             query?: never;
@@ -2635,6 +2652,45 @@ interface components {
             slug: string;
             position?: number;
         };
+        /**
+         * @description * `granted` - granted
+         *     * `denied` - denied
+         *     * `unknown` - unknown
+         * @enum {string}
+         */
+        AttributionConsentEnum: "granted" | "denied" | "unknown";
+        /**
+         * @description One landing: its click ids, UTMs, path and external referrer.
+         *
+         *     The key set of a touch in the storefront-attribution contract (section 1).
+         *     An explicit allowlist rather than a free dict: this is attacker-controllable
+         *     URL input landing in a JSON column, so unknown keys are dropped, blank
+         *     values are dropped and every value is bounded (a longer one, or a null
+         *     byte, makes the record invalid).
+         */
+        AttributionTouch: {
+            gclid?: string;
+            gbraid?: string;
+            wbraid?: string;
+            msclkid?: string;
+            fbclid?: string;
+            /** @description Retention send id (`?rt=`). */
+            rt?: string;
+            utm_source?: string;
+            utm_medium?: string;
+            utm_campaign?: string;
+            utm_term?: string;
+            utm_content?: string;
+            /** @description Path of this touch's landing document, no query string. */
+            landing_path?: string;
+            /** @description External host this touch landed from; never the storefront's. */
+            referrer_host?: string;
+        };
+        /**
+         * @description * `2` - 2
+         * @enum {integer}
+         */
+        AttributionVersionEnum: 2;
         AuthToken: {
             username: string;
             password: string;
@@ -3238,7 +3294,7 @@ interface components {
             order_number: string | null;
             purpose: string;
             attribution: {
-                [key: string]: string;
+                [key: string]: unknown;
             } | null;
             marketing_consent: {
                 [key: string]: unknown;
@@ -3257,27 +3313,58 @@ interface components {
             }[];
         };
         /**
-         * @description Ad-click and campaign identifiers captured by the storefront at landing.
+         * @description The attribution record: the last touch at the top level, plus the rest.
          *
-         *     Stored on the checkout and copied to the order at creation (PAT-2120) so
-         *     server-side measurement, if added later, can attribute this period. Not
-         *     read by anything yet. An explicit allowlist rather than a free dict: this
-         *     is attacker-controllable URL input landing in a JSON column, so unknown
-         *     keys are dropped and every value is bounded.
+         *     storefront-attribution contract, section 1. Shared by checkout creation
+         *     and ``POST /api/v1/visits/``, stored on the checkout and copied to
+         *     ``Order.metadata["attribution"]`` unchanged. A record without ``v`` is the
+         *     flat record written before the contract and is still accepted.
+         *
+         *     ``session_id`` and ``ga_client_id`` are the linking identifiers, so both
+         *     are dropped here unless the record's ``consent`` is ``granted``: nothing
+         *     downstream, checkout or visit, sees them without consent.
+         *
+         *     An invalid record is refused by ``POST /api/v1/visits/`` and dropped by
+         *     checkout creation, which carries on without it.
          */
         CheckoutAttribution: {
-            /** @description GA4 client id from the `_ga` cookie (`X.Y`). */
-            ga_client_id?: string;
             gclid?: string;
+            gbraid?: string;
+            wbraid?: string;
+            msclkid?: string;
             fbclid?: string;
-            gtm_debug?: string;
+            /** @description Retention send id (`?rt=`). */
+            rt?: string;
             utm_source?: string;
             utm_medium?: string;
             utm_campaign?: string;
             utm_term?: string;
             utm_content?: string;
+            /** @description Path of this touch's landing document, no query string. */
             landing_path?: string;
+            /** @description External host this touch landed from; never the storefront's. */
             referrer_host?: string;
+            /**
+             * @description Record version. Absent on records written before version 2.
+             *
+             *     * `2` - 2
+             */
+            v?: components["schemas"]["AttributionVersionEnum"];
+            /** @description The record's first landing. Required when `v` is 2. */
+            first_touch?: components["schemas"]["AttributionTouch"];
+            /** @description GA4 client id from the `_ga` cookie (`X.Y`). Dropped unless `consent` is `granted`. */
+            ga_client_id?: string;
+            /**
+             * @description Cookie banner state when the record was sent. Required when `v` is 2.
+             *
+             *     * `granted` - granted
+             *     * `denied` - denied
+             *     * `unknown` - unknown
+             */
+            consent?: components["schemas"]["AttributionConsentEnum"];
+            /** @description `analytics_session_id`. Dropped unless `consent` is `granted`. */
+            session_id?: string;
+            gtm_debug?: string;
         };
         ConfirmEdit: {
             payment_strategy: components["schemas"]["PaymentStrategyEnum"];
@@ -3313,7 +3400,7 @@ interface components {
         CreateCheckoutInput: {
             /** Format: uuid */
             cart_id: string;
-            /** @description Campaign and click identifiers seen by the storefront in this session; stamped on the checkout and the resulting order. */
+            /** @description Campaign and click identifiers seen by the storefront in this session; stamped on the checkout and the resulting order. A record that fails validation is dropped, not refused. */
             attribution?: components["schemas"]["CheckoutAttribution"];
             /**
              * Format: decimal
@@ -5361,6 +5448,10 @@ interface components {
             /** Format: decimal */
             amount: string;
         };
+        VisitInput: {
+            /** @description The attribution record, as on checkout creation. */
+            attribution: components["schemas"]["CheckoutAttribution"];
+        };
         /** @description Slim serializer for the widget delivery endpoint. */
         WidgetMessage: {
             /** Format: uuid */
@@ -17959,6 +18050,84 @@ interface operations {
             };
         };
     };
+    visits_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["VisitInput"];
+                "application/x-www-form-urlencoded": components["schemas"]["VisitInput"];
+                "multipart/form-data": components["schemas"]["VisitInput"];
+            };
+        };
+        responses: {
+            /** @description Recorded, bots included. No body. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Possible error codes include `VALIDATION_ERROR`. Use `x-error-codes` for machine-readable retryability metadata. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `UNAUTHORIZED`. Use `x-error-codes` for machine-readable retryability metadata. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `FORBIDDEN`. Use `x-error-codes` for machine-readable retryability metadata. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `NOT_FOUND`. Use `x-error-codes` for machine-readable retryability metadata. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `RATE_LIMITED`. Use `x-error-codes` for machine-readable retryability metadata. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `INTERNAL_ERROR`. Use `x-error-codes` for machine-readable retryability metadata. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+        };
+    };
     withdrawals_confirm_create: {
         parameters: {
             query?: never;

package/dist/index.d.ts

@@ -2461,6 +2461,23 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/visits/": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** @description Record one storefront visit and send it to Cerebro. */
+        post: operations["visits_create"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/withdrawals/confirm/": {
         parameters: {
             query?: never;
@@ -2635,6 +2652,45 @@ interface components {
             slug: string;
             position?: number;
         };
+        /**
+         * @description * `granted` - granted
+         *     * `denied` - denied
+         *     * `unknown` - unknown
+         * @enum {string}
+         */
+        AttributionConsentEnum: "granted" | "denied" | "unknown";
+        /**
+         * @description One landing: its click ids, UTMs, path and external referrer.
+         *
+         *     The key set of a touch in the storefront-attribution contract (section 1).
+         *     An explicit allowlist rather than a free dict: this is attacker-controllable
+         *     URL input landing in a JSON column, so unknown keys are dropped, blank
+         *     values are dropped and every value is bounded (a longer one, or a null
+         *     byte, makes the record invalid).
+         */
+        AttributionTouch: {
+            gclid?: string;
+            gbraid?: string;
+            wbraid?: string;
+            msclkid?: string;
+            fbclid?: string;
+            /** @description Retention send id (`?rt=`). */
+            rt?: string;
+            utm_source?: string;
+            utm_medium?: string;
+            utm_campaign?: string;
+            utm_term?: string;
+            utm_content?: string;
+            /** @description Path of this touch's landing document, no query string. */
+            landing_path?: string;
+            /** @description External host this touch landed from; never the storefront's. */
+            referrer_host?: string;
+        };
+        /**
+         * @description * `2` - 2
+         * @enum {integer}
+         */
+        AttributionVersionEnum: 2;
         AuthToken: {
             username: string;
             password: string;
@@ -3238,7 +3294,7 @@ interface components {
             order_number: string | null;
             purpose: string;
             attribution: {
-                [key: string]: string;
+                [key: string]: unknown;
             } | null;
             marketing_consent: {
                 [key: string]: unknown;
@@ -3257,27 +3313,58 @@ interface components {
             }[];
         };
         /**
-         * @description Ad-click and campaign identifiers captured by the storefront at landing.
+         * @description The attribution record: the last touch at the top level, plus the rest.
          *
-         *     Stored on the checkout and copied to the order at creation (PAT-2120) so
-         *     server-side measurement, if added later, can attribute this period. Not
-         *     read by anything yet. An explicit allowlist rather than a free dict: this
-         *     is attacker-controllable URL input landing in a JSON column, so unknown
-         *     keys are dropped and every value is bounded.
+         *     storefront-attribution contract, section 1. Shared by checkout creation
+         *     and ``POST /api/v1/visits/``, stored on the checkout and copied to
+         *     ``Order.metadata["attribution"]`` unchanged. A record without ``v`` is the
+         *     flat record written before the contract and is still accepted.
+         *
+         *     ``session_id`` and ``ga_client_id`` are the linking identifiers, so both
+         *     are dropped here unless the record's ``consent`` is ``granted``: nothing
+         *     downstream, checkout or visit, sees them without consent.
+         *
+         *     An invalid record is refused by ``POST /api/v1/visits/`` and dropped by
+         *     checkout creation, which carries on without it.
          */
         CheckoutAttribution: {
-            /** @description GA4 client id from the `_ga` cookie (`X.Y`). */
-            ga_client_id?: string;
             gclid?: string;
+            gbraid?: string;
+            wbraid?: string;
+            msclkid?: string;
             fbclid?: string;
-            gtm_debug?: string;
+            /** @description Retention send id (`?rt=`). */
+            rt?: string;
             utm_source?: string;
             utm_medium?: string;
             utm_campaign?: string;
             utm_term?: string;
             utm_content?: string;
+            /** @description Path of this touch's landing document, no query string. */
             landing_path?: string;
+            /** @description External host this touch landed from; never the storefront's. */
             referrer_host?: string;
+            /**
+             * @description Record version. Absent on records written before version 2.
+             *
+             *     * `2` - 2
+             */
+            v?: components["schemas"]["AttributionVersionEnum"];
+            /** @description The record's first landing. Required when `v` is 2. */
+            first_touch?: components["schemas"]["AttributionTouch"];
+            /** @description GA4 client id from the `_ga` cookie (`X.Y`). Dropped unless `consent` is `granted`. */
+            ga_client_id?: string;
+            /**
+             * @description Cookie banner state when the record was sent. Required when `v` is 2.
+             *
+             *     * `granted` - granted
+             *     * `denied` - denied
+             *     * `unknown` - unknown
+             */
+            consent?: components["schemas"]["AttributionConsentEnum"];
+            /** @description `analytics_session_id`. Dropped unless `consent` is `granted`. */
+            session_id?: string;
+            gtm_debug?: string;
         };
         ConfirmEdit: {
             payment_strategy: components["schemas"]["PaymentStrategyEnum"];
@@ -3313,7 +3400,7 @@ interface components {
         CreateCheckoutInput: {
             /** Format: uuid */
             cart_id: string;
-            /** @description Campaign and click identifiers seen by the storefront in this session; stamped on the checkout and the resulting order. */
+            /** @description Campaign and click identifiers seen by the storefront in this session; stamped on the checkout and the resulting order. A record that fails validation is dropped, not refused. */
             attribution?: components["schemas"]["CheckoutAttribution"];
             /**
              * Format: decimal
@@ -5361,6 +5448,10 @@ interface components {
             /** Format: decimal */
             amount: string;
         };
+        VisitInput: {
+            /** @description The attribution record, as on checkout creation. */
+            attribution: components["schemas"]["CheckoutAttribution"];
+        };
         /** @description Slim serializer for the widget delivery endpoint. */
         WidgetMessage: {
             /** Format: uuid */
@@ -17959,6 +18050,84 @@ interface operations {
             };
         };
     };
+    visits_create: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["VisitInput"];
+                "application/x-www-form-urlencoded": components["schemas"]["VisitInput"];
+                "multipart/form-data": components["schemas"]["VisitInput"];
+            };
+        };
+        responses: {
+            /** @description Recorded, bots included. No body. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            /** @description Possible error codes include `VALIDATION_ERROR`. Use `x-error-codes` for machine-readable retryability metadata. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `UNAUTHORIZED`. Use `x-error-codes` for machine-readable retryability metadata. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `FORBIDDEN`. Use `x-error-codes` for machine-readable retryability metadata. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `NOT_FOUND`. Use `x-error-codes` for machine-readable retryability metadata. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `RATE_LIMITED`. Use `x-error-codes` for machine-readable retryability metadata. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+            /** @description Possible error codes include `INTERNAL_ERROR`. Use `x-error-codes` for machine-readable retryability metadata. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["APIErrorEnvelope"];
+                };
+            };
+        };
+    };
     withdrawals_confirm_create: {
         parameters: {
             query?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poweredbysous/storefront-sdk",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "Type-safe TypeScript SDK for SOUS Storefront Backend",
   "license": "UNLICENSED",
   "private": false,