@doswiftly/storefront-operations 19.0.0 → 19.1.0

package/AGENTS.md

@@ -27,7 +27,7 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 19.0.0
+- **Schema version**: 19.1.0
 - **Queries**: 52
 - **Mutations**: 41
 - **Fragments**: 104

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 19.1.0
+
+### Minor Changes
+
+- 868894e: Add remote debug shipping for both GraphQL **and** cookie-lifecycle events, so you can trace a real shopper session end-to-end instead of reproducing it with DevTools open.
+
+  **Why**: the most useful checkout signal is often "when was the `cart-id` / currency / language cookie set or cleared?" (e.g. `cart-id` cleared by `complete()`), but debug output previously covered only GraphQL request/response. Now both flow through one channel keyed by a single `sessionId`, so one filter in your logs gives the full interleaved timeline.
+
+  **Additive (backward-compatible)** — everything is opt-in and off by default:
+  1. `DebugOptions.remote?: boolean | RemoteDebugOptions | RemoteDebugSink` — ship debug events to a backend ingest endpoint. Pass a pre-built transport (a `RemoteDebugSink`) to share **one** channel/`sessionId` across the client and the cookie stores.
+  2. New `createRemoteDebugTransport(...)` factory (+ `RemoteDebugTransport` / `RemoteDebugSink` / `RemoteDebugOptions` types).
+  3. Cookie stores emit a new `DebugEvent` with `phase: 'cookie'` (`{ name, action: 'set' | 'clear', value?, maxAge? }`) when wired with a sink:
+     - `createBrowserCartCookieStore({ onDebug })` — `cart-id` (when you own the cookie store).
+     - `useCartManager({ cookieDebug })` / `<CartManagerProvider cookieDebug={...}>` — `cart-id` when the cart manager owns the cookie store.
+     - `createCurrencyStore({ onDebug })` / `createLanguageStore(initial, { onDebug })` — currency / language.
+     - `<StorefrontProvider cookieDebug={...}>` forwards the sink to the currency + language stores.
+  4. `DebugOptions`, `DebugEvent`, `RemoteDebugOptions`, `RemoteDebugSink` are exported for typing.
+
+  **Usage example** (one shared channel across GraphQL + cookies):
+
+  ```ts
+  import {
+    createStorefrontClient,
+    createRemoteDebugTransport,
+    createBrowserCartCookieStore,
+  } from "@doswiftly/storefront-sdk";
+
+  const debugOn = process.env.NEXT_PUBLIC_SDK_DEBUG_REMOTE === "true";
+  const transport = debugOn
+    ? createRemoteDebugTransport({
+        endpoint: `${apiUrl}/storefront/debug-logs`,
+        shopSlug,
+        fetch: globalThis.fetch,
+      })
+    : null;
+
+  const client = createStorefrontClient({
+    apiUrl,
+    shopSlug,
+    debug: transport
+      ? { userErrors: true, response: true, timing: true, remote: transport }
+      : false,
+  });
+
+  // cart-id set/clear on the same channel:
+  const cartCookieStore = createBrowserCartCookieStore(
+    transport ? { onDebug: (e) => transport.capture(e) } : undefined,
+  );
+
+  // currency + language via the provider:
+  // <StorefrontProvider cookieDebug={transport ? (e) => transport.capture(e) : undefined} … />
+  ```
+
+  Behaviour:
+  - **Batched** (default 10 events / 5s); `keepalive` is used on page-hide/unload flushes so trailing events survive a navigation or payment-gateway redirect.
+  - **Fire-and-forget**: a failed send is swallowed — telemetry can never break the request that produced it.
+  - Cookies are **not** sent (`credentials: 'omit'`); the shop is identified by the `X-Shop-Slug` header.
+  - **Redaction**: the SDK masks `Authorization` / `customerAccessToken` in _headers_. It does **not** redact request `variables` or response bodies — the backend ingest endpoint masks emails + credential-named fields. Enable `response` / `headers` only for operations whose payload you're comfortable sending to your backend.
+  - Default endpoint is `${apiUrl}/storefront/debug-logs`; override via `RemoteDebugOptions.endpoint`.
+
+  **Migration checklist for existing storefronts**:
+  - [ ] No action required — all of the above is opt-in and defaults to off.
+  - [ ] To adopt: build one transport (gated behind an env flag), pass it to `createStorefrontClient`, the cart cookie store, and `<StorefrontProvider cookieDebug>`, then confirm requests to `/storefront/debug-logs`.
+
 ## 19.0.0
 
 ### Major Changes

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **19.0.0**
+> Schema version: **19.1.0**
 > 52 queries · 41 mutations · 104 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "19.0.0",
+  "schemaVersion": "19.1.0",
   "queries": [
     {
       "name": "Shop",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "19.0.0",
+  "version": "19.1.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {