@doswiftly/storefront-sdk 22.8.1 → 22.10.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 22.10.0
+
+### Minor Changes
+
+- 3961ca4: Attach the cart access secret (`x-cart-secret`) only to cart operations.
+
+  Previously the header was sent on every request whenever a cart cookie was
+  present, which kept public catalog reads (products, search, recommendations,
+  payment methods) off the shared response cache for any visitor who had a cart.
+  The secret is now attached only to cart-scoped operations, so those public
+  reads become cacheable again — faster responses, with no change needed in your
+  code.
+
+  A new `isCartScopedOperation` helper is exported, and `cartSecretMiddleware` /
+  `serverCartSecretMiddleware` accept an optional classifier as their second
+  argument. Cart operations are recognised by a `Cart` operation-name prefix. If
+  you issue custom cart queries through the SDK, name them with a `Cart` prefix,
+  or pass your own classifier:
+  `cartSecretMiddleware(getSecret, (operationName) => ...)`.
+
+## 22.9.0
+
+### Minor Changes
+
+- 36c28ff: Add `customerNote` to the storefront `Order` type — the note a buyer left at checkout (delivery instructions, gift message, etc.). It is selected by the order fragment, so it is available on every order query, and is `null` when the buyer left no note.
+
+  ```tsx
+  // Order confirmation / detail page
+  const note = order.customerNote;
+  if (note) {
+    return <p className="order-note">{note}</p>;
+  }
+  ```
+
+- a399d36: Image loader now produces clean image URLs (no internal storage prefix) on custom domains.
+
+  **Why**: when your storefront is served from its own image domain, the built `<Image>` URLs no longer carry the `/s/{shopId}` storage prefix (`https://img.yourshop.com/_next/static/media/hero.webp?width=256` instead of `.../s/{shopId}/_next/...`). The stored object is unchanged — the platform restores the prefix toward storage — so this is purely a nicer public URL. Branding-friendly, and one fewer internal detail in the markup.
+
+  **This is automatic — no code change.** The common `createImageLoader()` setup reads the flag from the platform-injected env var, so clean URLs simply turn on when your storefront is served from a custom domain configured for them:
+
+  ```ts
+  // lib/image-loader.ts — unchanged; clean URLs turn on automatically.
+  import { createImageLoader } from "@doswiftly/storefront-sdk/next";
+  export default createImageLoader();
+  ```
+
+  **Additive (backward-compatible)**:
+  1. `ImageLoaderConfig` gains an optional `cleanUrl?: boolean` (defaults to `false`).
+  2. `createImageLoader()` reads it automatically from `NEXT_PUBLIC_ASSET_CLEAN_URL`.
+
+  When `cleanUrl` is off (the default), URLs keep the `/s/{shopId}` prefix exactly as before — existing storefronts are unaffected. The boolean is also accepted by the low-level `buildImageLoaderUrl` for non-`<Image>` usage (e.g. CSS backgrounds) or tests:
+
+  ```ts
+  import { buildImageLoaderUrl } from "@doswiftly/storefront-sdk";
+  buildImageLoaderUrl(
+    { shopId, version, cleanUrl: true, cdnBase: "https://img.yourshop.com" },
+    { src: "/hero.webp", width: 256 },
+  );
+  // → https://img.yourshop.com/public/hero.webp?width=256&v=<version>
+  ```
+
+  **Migration checklist for existing storefronts**:
+  - [ ] None required — the default behavior is unchanged. Re-deploy to pick up clean URLs once your custom domain is configured.
+
 ## 22.8.1
 
 ### Patch Changes

package/README.md

@@ -197,7 +197,7 @@ const client = createStorefrontClient({
   apiUrl: 'https://api.doswiftly.pl',
   shopSlug: 'my-shop',
   middleware: [
-    cartSecretMiddleware(() => cartSecret), // lazy getter — picks up rotation
+    cartSecretMiddleware(() => cartSecret), // lazy getter; secret rides cart ops only
     retryMiddleware({ maxRetries: 2 }),
     timeoutMiddleware({ timeout: 5000 }),
     errorMiddleware(), // ALWAYS LAST
@@ -425,17 +425,24 @@ Cart access is authorized by **possession of a secret**, not by the customer
 session. The `cart-id` cookie stores a composite value `"<cartId>.<secret>"`
 (30 days, SSR/edge-visible, not httpOnly — the cart carries no payment data).
 `CartClient.create()` and `recoveryRedeem()` reveal the secret **once**; the SDK
-persists it into the cookie for you. Every request then carries the secret in
-the `x-cart-secret` header via middleware:
+persists it into the cookie for you. **Cart operations** then carry the secret in
+the `x-cart-secret` header via middleware — public reads (product listings,
+search, recommendations, payment methods) do **not**, so they stay eligible for
+the shared cache even when the visitor has a cart:
 
 - **Browser**: `StorefrontProvider` wires `cartSecretMiddleware` automatically —
-  the secret is read lazily from the cookie on every request, so a rotated
-  secret is picked up without rebuilding the client.
+  the secret is read lazily from the cookie and attached only to cart
+  operations, so a rotated secret is picked up without rebuilding the client.
 - **Server (SSR/edge)**: prepend `serverCartSecretMiddleware(await readCartCredentials())`
   to your server client — see [Server-side](#server-side-reactserver).
 - **Custom runtimes**: `cartSecretMiddleware(() => secret)` + the
   `parseCartCookieValue` / `formatCartCookieValue` helpers.
 
+Cart operations are recognised by a `Cart` operation-name prefix
+(`isCartScopedOperation`). If you issue custom cart queries, name them with a
+`Cart` prefix, or pass your own classifier as the second argument:
+`cartSecretMiddleware(getSecret, (operationName) => ...)`.
+
 A cookie without the secret half (or a stale capability) makes the cart
 unreachable — mutations reject with `CART_NOT_FOUND` and the standard recovery
 flow recreates a fresh cart.
@@ -777,13 +784,16 @@ The loader is global and handles each `<Image src>` by category:
 | Image imported in code (`import hero from './hero.webp'`) | Routed through the CDN — the framework bundles it under `/_next/static/media/`, the loader resizes it per `srcset` (no code change needed) |
 | Other build asset (`/_next/*` JS/CSS, `/_nuxt/`, `/_astro/`, `/_app/`), absolute external URL, `data:` URI, SVG | Returned unchanged |
 
-The loader reads `NEXT_PUBLIC_SHOP_ID`, `NEXT_PUBLIC_DEPLOYMENT_COMMIT`, and
-`NEXT_PUBLIC_IMGPROXY_BASE` — all injected by the platform at build/deploy time. When
-they are absent (e.g. local `doswiftly dev`, where `public/` images are served by the
-dev server) the loader leaves local `public/` images untouched; product images, being
-absolute CDN URLs, are unaffected. `<Image quality>` is a no-op — quality is applied
-server-side (the format is still auto-negotiated AVIF/WebP). Pass explicit overrides only for non-standard setups:
-`createImageLoader({ shopId, version, cdnBase })`.
+The loader reads `NEXT_PUBLIC_SHOP_ID`, `NEXT_PUBLIC_DEPLOYMENT_COMMIT`,
+`NEXT_PUBLIC_IMGPROXY_BASE`, and `NEXT_PUBLIC_ASSET_CLEAN_URL` — all injected by the platform
+at build/deploy time. When they are absent (e.g. local `doswiftly dev`, where `public/` images
+are served by the dev server) the loader leaves local `public/` images untouched; product
+images, being absolute CDN URLs, are unaffected. `NEXT_PUBLIC_ASSET_CLEAN_URL` is set to `true`
+only when your storefront is served from a custom domain configured for clean URLs — then the
+built URLs omit the internal storage prefix (`{host}/_next/static/media/...` instead of
+`{host}/s/{shopId}/_next/...`); the stored object is unchanged. `<Image quality>` is a no-op —
+quality is applied server-side (the format is still auto-negotiated AVIF/WebP). Pass explicit
+overrides only for non-standard setups: `createImageLoader({ shopId, version, cdnBase, cleanUrl })`.
 
 For non-`<Image>` usage (CSS backgrounds, raw `<img>`), build CDN URLs yourself
 with the pure helper `buildImageLoaderUrl` from `@doswiftly/storefront-sdk`.
@@ -803,7 +813,7 @@ replay; a 401 on a mutation fires the `session-expired` signal instead.
 ```typescript
 import {
   authMiddleware,           // Authorization: Bearer <token> (lazy getter)
-  cartSecretMiddleware,     // x-cart-secret header (lazy getter)
+  cartSecretMiddleware,     // x-cart-secret header (cart operations only)
   currencyMiddleware,       // X-Preferred-Currency header
   languageMiddleware,       // X-Language header (skipped when null — intentional)
   botProtectionMiddleware,  // challenge token for protected mutations only

package/dist/core/generated/operation-types.d.ts

@@ -2439,6 +2439,8 @@ export type Order = Node & {
     cancelledAt?: Maybe<Scalars['DateTime']['output']>;
     /** When the order was confirmed (e.g. payment authorised / approved). Null until confirmation. */
     confirmedAt?: Maybe<Scalars['DateTime']['output']>;
+    /** The note the buyer left at checkout (delivery instructions, gift message, etc.). Null when no note was provided. */
+    customerNote?: Maybe<Scalars['String']['output']>;
     /** Per-code discount allocations on the order (parity with `Cart.discountAllocations`). One entry per code that reduced the price; empty when no discount applied. The sum of `amount` equals the order-level discount. */
     discountAllocations: Array<OrderDiscountAllocation>;
     /** When the order expired (e.g. pending payment timed out). Null when not expired. */
@@ -4182,7 +4184,7 @@ export type CartCompleteMutationVariables = Exact<{
 }>;
 export type CartCompleteMutation = {
     cartComplete: {
-        order?: Maybe<(Pick<Order, 'id' | 'orderNumber' | 'accessToken' | 'status' | 'paymentStatus' | 'fulfillmentStatus' | 'processedAt' | 'confirmedAt' | 'cancelledAt' | 'expiredAt' | 'itemCount' | 'canCreatePayment' | 'paymentMethodType'> & {
+        order?: Maybe<(Pick<Order, 'id' | 'orderNumber' | 'accessToken' | 'status' | 'paymentStatus' | 'fulfillmentStatus' | 'processedAt' | 'confirmedAt' | 'cancelledAt' | 'expiredAt' | 'itemCount' | 'customerNote' | 'canCreatePayment' | 'paymentMethodType'> & {
             totals: {
                 total: Pick<Money, 'amount' | 'currencyCode'>;
                 subtotal: Pick<Money, 'amount' | 'currencyCode'>;
@@ -5307,7 +5309,7 @@ export type OrderByTokenQueryVariables = Exact<{
     email?: InputMaybe<Scalars['String']['input']>;
 }>;
 export type OrderByTokenQuery = {
-    orderByToken?: Maybe<(Pick<Order, 'id' | 'orderNumber' | 'accessToken' | 'status' | 'paymentStatus' | 'fulfillmentStatus' | 'processedAt' | 'confirmedAt' | 'cancelledAt' | 'expiredAt' | 'itemCount' | 'canCreatePayment' | 'paymentMethodType'> & {
+    orderByToken?: Maybe<(Pick<Order, 'id' | 'orderNumber' | 'accessToken' | 'status' | 'paymentStatus' | 'fulfillmentStatus' | 'processedAt' | 'confirmedAt' | 'cancelledAt' | 'expiredAt' | 'itemCount' | 'customerNote' | 'canCreatePayment' | 'paymentMethodType'> & {
         totals: {
             total: Pick<Money, 'amount' | 'currencyCode'>;
             subtotal: Pick<Money, 'amount' | 'currencyCode'>;
@@ -5568,7 +5570,7 @@ export type FreeShippingProgressFragment = (Pick<FreeShippingProgress, 'qualifie
     threshold?: Maybe<Pick<Money, 'amount' | 'currencyCode'>>;
     remaining?: Maybe<Pick<Money, 'amount' | 'currencyCode'>>;
 });
-export type OrderFragment = (Pick<Order, 'id' | 'orderNumber' | 'accessToken' | 'status' | 'paymentStatus' | 'fulfillmentStatus' | 'processedAt' | 'confirmedAt' | 'cancelledAt' | 'expiredAt' | 'itemCount' | 'canCreatePayment' | 'paymentMethodType'> & {
+export type OrderFragment = (Pick<Order, 'id' | 'orderNumber' | 'accessToken' | 'status' | 'paymentStatus' | 'fulfillmentStatus' | 'processedAt' | 'confirmedAt' | 'cancelledAt' | 'expiredAt' | 'itemCount' | 'customerNote' | 'canCreatePayment' | 'paymentMethodType'> & {
     totals: {
         total: Pick<Money, 'amount' | 'currencyCode'>;
         subtotal: Pick<Money, 'amount' | 'currencyCode'>;