@doswiftly/storefront-sdk 11.2.0 → 11.3.1

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 11.3.1
+
+### Patch Changes
+
+- 9ca724e: Removes the `./schema` subpath export from `@doswiftly/storefront-sdk` — it was a duplicate of what `@doswiftly/storefront-operations` already publishes.
+
+  **Why:**
+
+  `@doswiftly/storefront-operations` is a linked package — it is always installed alongside `@doswiftly/storefront-sdk`. It exposes the GraphQL SDL as a raw `schema.graphql` file via the `./schema.graphql` subpath export, which is the format every codegen tool and IDE GraphQL plugin natively consumes. Bundling the same SDL again as an ESM string literal in `@doswiftly/storefront-sdk/schema` added ~128 KB to the npm tarball without giving consumers a meaningful capability that wasn't already there.
+
+  **Migration:**
+
+  Switch from:
+
+  ```ts
+  import { schema } from "@doswiftly/storefront-sdk/schema";
+  ```
+
+  to a direct path reference in your codegen config (or `graphql-config` for your IDE):
+
+  ```ts
+  // codegen.ts
+  const config = {
+    schema: "node_modules/@doswiftly/storefront-operations/schema.graphql",
+    // …
+  };
+  ```
+
+  The schema content is byte-for-byte identical — your codegen output does not change.
+
+  **Internal:**
+  - Removed `scripts/build-schema-export.cjs` and the matching `pnpm build` chain step.
+  - `pnpm build` is now plain `tsc` again.
+  - Removed the `dist/schema.js` + `dist/schema.d.ts` build artifacts and the `schema-export.test.ts` unit test.
+  - `pnpm run doctor` no longer checks for the schema bundle.
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
+## 11.3.0
+
+### Minor Changes
+
+- 0a2dfd8: Phase 1 of the senior-level audit ships security hardening, dead-code cleanup, and a coverage gate.
+
+  **Security:**
+  - `createSetTokenHandler`, `createClearTokenHandler`, `createWhoamiHandler` now validate the `Origin` header against the `Host` header by parsed URL host (`new URL(origin).host === host`) instead of a substring `includes()` check. The previous implementation was bypassable by empty Host (`includes('')` is always true) and by Origin URLs that embedded the trusted host in their query string. Requests without both `Origin` and `Host` headers now respond with `403`.
+
+  **Removed:**
+  - `ServerClientOptions.getHeaders` (accepted by `getStorefrontClient()` but never wired through). Inject request-scoped headers via the `middleware` option — see updated JSDoc.
+
+  **Internal:**
+  - Inconsistent `setIsRenewingToken` setter in `useAuth` is renamed to `setIsRefreshingToken` to match the exposed `isRefreshingToken` flag.
+  - Removed an unused `callbackName` field in `TurnstileManager` and a pre-cookie-era `localStorage.removeItem('cart-storage')` call in `createCartStore`.
+
+  **Infrastructure:**
+  - `package.json` now declares `sideEffects: false` so consumer bundlers can tree-shake unused exports aggressively.
+  - Adds `test:coverage` script (`vitest run --coverage`) with a baseline threshold (60% statements / 50% branches / 55% functions / 60% lines). The floor will rise as later phases cover the React providers, auth/currency/language stores, and remaining hooks.
+  - Adds 102 new unit tests across `format`, `image`, `cookies`, `auth/handlers`, and additional `errorMiddleware`/`timeoutMiddleware`/`languageMiddleware` cases — including two regression tests for the origin-validation bypass vectors.
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
+- 09c3744: Phase 2 of the SDK audit ships the developer-experience features external storefront builders have been writing by hand: pre-built React components, tagged-union mutation state, a bundled GraphQL schema export, and a focused-hook auth API.
+
+  **Pre-built React components** (from `@doswiftly/storefront-sdk/react`):
+
+  Six headless, accessibility-aware components — zero styling, framework-agnostic, no `next/image` dependency so they work in any React 18/19 environment.
+  - `<Money amount currency>` — locale-formatted price from minor units (wraps `formatPrice`).
+  - `<Image data sizes priority>` — `<img>` with thumbhash blur placeholder, lazy by default, `fetchpriority` hint.
+  - `<CartCount count label hideWhenEmpty>` — aria-live cart item count.
+  - `<AddToCartButton variantId quantity onSuccess onError>` — orchestrates `useCartManager.addItem` with loading state + sr-only error alert.
+  - `<PriceDisplay price compareAtPrice currency>` — current price + optional strikethrough sale price.
+  - `<CartTotals subtotal discount shipping tax total currency labels>` — `<dl>` breakdown that elides empty rows.
+
+  **Tagged-union status in `useCartManager`**:
+  - New `status` field on the hook return — `{ type: 'idle' | 'loading' | 'error' | 'success', operation? }` — enables exhaustive switching without juggling booleans.
+  - `isLoading` and `error` remain available as derived selectors (backward-compatible).
+  - `clearCart()` resets status to `idle`.
+
+  **Bundled GraphQL schema** (`@doswiftly/storefront-sdk/schema`):
+  - New export path ships the full GraphQL SDL (123 KB) as a string constant, regenerated from `@doswiftly/storefront-operations/schema.graphql` on each build.
+  - Wire GraphQL codegen / IDE plugins without a live backend — no extra `npm install`.
+
+  **`useAuth` split into focused hooks**:
+  - `useLogin({ onSetToken })` — login flow only, `{ login, isLoggingIn, error }`.
+  - `useLogout({ onClearToken })` — logout, always clears local store even on backend failure.
+  - `useRefreshToken({ onSetToken })` — token rotation, keeps existing customer.
+  - `useAuth(options)` is preserved as a thin facade composing the three (backward-compatible, no breaking change).
+
+  Prefer the focused hooks in new code — smaller bundles, isolated state, smaller dependency arrays.
+
+  **Docs**:
+  - README adds a 7-step Next.js 16 App Router setup, BFF route handler examples, components catalog, bundled schema usage.
+  - New `docs/storefront-developer/sdk/nextjs-setup.md` and `auth.md` with end-to-end recipes.
+
+  **Tests**: 476 → 494 unit tests (+18). New files: `components.test.tsx` (37 cases), `schema-export.test.ts` (5 cases), `use-auth.test.tsx` (13 cases). Build clean, 0-deps invariant preserved.
+
+  `@doswiftly/storefront-operations` is bumped in lockstep (no code change — required because the packages are linked and ship together).
+
 ## 11.2.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,6 @@
 # @doswiftly/storefront-sdk
 
-Layered runtime SDK for DoSwiftly Commerce storefronts. Hydrogen-aligned architecture with **0 runtime dependencies** in core.
+Layered runtime SDK for DoSwiftly Commerce storefronts. Framework-agnostic core + React adapter, **0 runtime dependencies** in core.
 
 ## Architecture
 
@@ -94,10 +94,222 @@ const { currency, setCurrency } = useCurrencyStore();
 | Path | Description | Dependencies |
 |------|-------------|-------------|
 | `@doswiftly/storefront-sdk` | Core: transport, middleware, clients, errors, format, image types, sanitize, auth handlers, route matching | **0** |
-| `@doswiftly/storefront-sdk/react` | Providers, hooks, store hooks, useHydrated, useDebouncedValue, createStoreContext | react, zustand |
+| `@doswiftly/storefront-sdk/react` | Providers, hooks, pre-built UI components, Zustand stores | react, zustand |
 | `@doswiftly/storefront-sdk/react/server` | Server-side client factory | react |
 | `@doswiftly/storefront-sdk/cache` | Cache strategy functions | **0** |
 
+## Next.js 16 App Router — first add-to-cart in 15 minutes
+
+End-to-end skeleton that gets you a working cart + auth flow without writing
+the middleware pipeline by hand. Copy the files below into a fresh `app/`
+directory and you're live.
+
+**1. `app/layout.tsx`** — wrap the tree in `StorefrontProvider`:
+
+```tsx
+import { StorefrontProvider } from '@doswiftly/storefront-sdk/react';
+import { getStorefrontClient } from '@doswiftly/storefront-sdk/react/server';
+import { cookies } from 'next/headers';
+import { AUTH_COOKIE_NAME } from '@doswiftly/storefront-sdk';
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  const serverClient = getStorefrontClient({
+    apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+    shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+  });
+  // `SHOP_BASICS_QUERY` is your own operation — generated by graphql-codegen
+  // from `@doswiftly/storefront-operations/schema.graphql`. It should request
+  // `shop.currency`, `shop.supportedCurrencies`, `shop.supportedLanguages`,
+  // `shop.botProtection` — whatever StorefrontProvider needs.
+  const { shop } = await serverClient.query(SHOP_BASICS_QUERY);
+
+  // Read the httpOnly auth cookie server-side so we can hydrate the auth store
+  // without a flash of "Sign In".
+  const cookieStore = await cookies();
+  const initialIsAuthenticated = Boolean(cookieStore.get(AUTH_COOKIE_NAME)?.value);
+
+  return (
+    <html lang="pl">
+      <body>
+        <StorefrontProvider
+          config={{
+            apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+            shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+          }}
+          shopData={shop}
+          initialIsAuthenticated={initialIsAuthenticated}
+        >
+          {children}
+        </StorefrontProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+**2. `app/api/auth/set-token/route.ts`** — BFF route that sets the httpOnly
+cookie. The SDK ships factories so each file is two lines:
+
+```ts
+import { createSetTokenHandler } from '@doswiftly/storefront-sdk';
+export const POST = createSetTokenHandler();
+```
+
+**3. `app/api/auth/clear-token/route.ts`** — clears the cookie on logout:
+
+```ts
+import { createClearTokenHandler } from '@doswiftly/storefront-sdk';
+export const POST = createClearTokenHandler();
+```
+
+**4. `app/api/auth/whoami/route.ts`** — hydrates customer state from the
+httpOnly cookie after a hard refresh (`accessToken` no longer persists in
+localStorage — XSS hardening):
+
+```ts
+import { createWhoamiHandler } from '@doswiftly/storefront-sdk';
+
+export const GET = createWhoamiHandler({
+  apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+  shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+});
+```
+
+**5. Sign-in form** — uses the focused `useLogin` hook + wires the BFF
+callback:
+
+```tsx
+'use client';
+import { useLogin } from '@doswiftly/storefront-sdk/react';
+
+export function LoginForm() {
+  const { login, isLoggingIn, error } = useLogin({
+    onSetToken: async (token) => {
+      await fetch('/api/auth/set-token', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token }),
+      });
+    },
+  });
+
+  return (
+    <form onSubmit={async (e) => {
+      e.preventDefault();
+      const data = new FormData(e.currentTarget);
+      const result = await login(String(data.get('email')), String(data.get('password')));
+      if (result.success) location.href = '/account';
+    }}>
+      <input name="email" type="email" required />
+      <input name="password" type="password" required />
+      <button type="submit" disabled={isLoggingIn}>{isLoggingIn ? 'Signing in…' : 'Sign in'}</button>
+      {error && <p role="alert">{error}</p>}
+    </form>
+  );
+}
+```
+
+**6. Product card with add-to-cart** — pre-built components:
+
+```tsx
+'use client';
+import { Image, PriceDisplay, AddToCartButton } from '@doswiftly/storefront-sdk/react';
+
+export function ProductCard({ product }: { product: ProductCardFields }) {
+  return (
+    <article>
+      <Image data={product.featuredImage} sizes="(max-width: 768px) 100vw, 33vw" />
+      <h2>{product.title}</h2>
+      <PriceDisplay
+        price={product.price.amount * 100}
+        compareAtPrice={product.compareAtPrice ? product.compareAtPrice.amount * 100 : undefined}
+        currency={product.price.currencyCode}
+      />
+      <AddToCartButton variantId={product.firstVariant.id}>Add to cart</AddToCartButton>
+    </article>
+  );
+}
+```
+
+That's it. Cart recovery (stale-cart auto-replay) is automatic — wire a single
+global `onExpired` toast subscriber once in `app/layout.tsx`:
+
+```tsx
+'use client';
+import { useEffect } from 'react';
+import { useCartManager } from '@doswiftly/storefront-sdk/react';
+import { toast } from 'sonner';
+
+export function CartExpiredToast() {
+  const { onExpired } = useCartManager();
+  useEffect(() => onExpired((e) => {
+    toast.error(e.reason === 'state-dependent'
+      ? 'Twój koszyk wygasł, dodaj produkty ponownie'
+      : 'Nie udało się odzyskać koszyka, spróbuj ponownie');
+  }), [onExpired]);
+  return null;
+}
+```
+
+## Pre-built React components
+
+Headless, accessibility-aware, zero styling — pass `className` to integrate
+with your CSS approach. Available from `@doswiftly/storefront-sdk/react`:
+
+| Component | Purpose |
+|-----------|---------|
+| `<Money amount currency>` | Locale-formatted price string from minor units |
+| `<Image data sizes priority>` | `<img>` with thumbhash blur placeholder + sane defaults |
+| `<CartCount count label>` | Aria-live cart item count |
+| `<AddToCartButton variantId quantity>` | Button wired to `useCartManager.addItem` |
+| `<PriceDisplay price compareAtPrice currency>` | Price + optional strikethrough sale price |
+| `<CartTotals subtotal tax shipping discount total currency>` | Cart financial breakdown `<dl>` |
+
+```tsx
+import { Money, Image, CartCount, AddToCartButton, PriceDisplay, CartTotals } from '@doswiftly/storefront-sdk/react';
+
+<Money amount={9990} currency="PLN" />          {/* "99,90 zł" */}
+<PriceDisplay price={7990} compareAtPrice={9990} currency="PLN" />
+<CartCount count={3} label="items" />
+```
+
+## GraphQL schema for codegen
+
+The GraphQL SDL ships in the linked `@doswiftly/storefront-operations` package
+(which is installed alongside the SDK) — point your codegen / IDE plugin at it
+directly. No live backend required:
+
+```ts
+// codegen.ts — uses raw .graphql file from the operations package
+const config = {
+  schema: 'node_modules/@doswiftly/storefront-operations/schema.graphql',
+  documents: ['./app/**/*.{ts,tsx,graphql}'],
+  generates: { './generated/graphql.ts': { /* … */ } },
+};
+export default config;
+```
+
+For VS Code GraphQL extension, point `graphql-config` at the same path.
+
+## Auth: focused hooks vs the facade
+
+Prefer the per-flow hooks in new code — smaller bundles, isolated state:
+
+```tsx
+import { useLogin, useLogout, useRefreshToken } from '@doswiftly/storefront-sdk/react';
+
+const { login, isLoggingIn } = useLogin({ onSetToken });
+const { logout, isLoggingOut } = useLogout({ onClearToken });
+const { refreshToken } = useRefreshToken({ onSetToken });
+```
+
+The legacy `useAuth` facade still works (combines all three):
+
+```tsx
+import { useAuth } from '@doswiftly/storefront-sdk/react';
+const { login, logout, refreshToken, isLoading, error } = useAuth({ onSetToken, onClearToken });
+```
+
 ## Core API
 
 ### createStorefrontClient

package/dist/core/auth/handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/core/auth/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,UAAU,sBAAsB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAmCD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,sBAAsB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAgEzC;AAED,UAAU,oBAAoB;IAC5B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA6DzC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAkCjF"}
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../../src/core/auth/handlers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,UAAU,sBAAsB;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,CAAC,EAAE,sBAAsB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAgEzC;AAED,UAAU,oBAAoB;IAC5B,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,GAAE,oBAAyB,GACjC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CA6DzC;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAkCjF"}

package/dist/core/auth/handlers.js

@@ -27,15 +27,43 @@ function serializeCookie(name, value, options) {
         parts.push('HttpOnly');
     return parts.join('; ');
 }
+/**
+ * Validate the Origin header against the Host header to prevent CSRF from
+ * unrelated origins.
+ *
+ * Compares the *parsed* origin's host with the request's host header, not a
+ * substring match — `origin.includes(host)` was bypassable two ways:
+ * - `host = ""` (or missing) → `origin.includes('')` always true;
+ * - `origin = "https://attacker.example/?host=trusted"` → substring match
+ *   passes for any trusted host name.
+ *
+ * Both Origin and Host MUST be present (typical browser fetch sends Origin
+ * for cross-origin and same-origin POSTs; server-to-server callers without
+ * an Origin header should hit the GraphQL API directly, not these BFF
+ * handlers).
+ */
 function validateOrigin(request) {
     const origin = request.headers.get('origin');
     const host = request.headers.get('host');
-    if (origin && !origin.includes(host || '')) {
+    if (!origin || !host) {
+        return new Response(JSON.stringify({ error: 'Origin and Host headers are required' }), { status: 403, headers: { 'Content-Type': 'application/json' } });
+    }
+    let originHost;
+    try {
+        originHost = new URL(origin).host;
+    }
+    catch {
         return new Response(JSON.stringify({ error: 'Invalid origin' }), {
             status: 403,
             headers: { 'Content-Type': 'application/json' },
         });
     }
+    if (originHost !== host) {
+        return new Response(JSON.stringify({ error: 'Origin mismatch' }), {
+            status: 403,
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
     return null;
 }
 /**

package/dist/core/bot-protection/turnstile-manager.d.ts

@@ -6,7 +6,6 @@
  */
 import { AbstractBotProtectionManager } from './abstract-manager';
 export declare class TurnstileManager extends AbstractBotProtectionManager {
-    private callbackName;
     protected _waitForApi(): Promise<void>;
     protected _renderWidget(container: HTMLElement, action?: string): string;
     protected _executeChallenge(widgetId: string, action?: string): Promise<string | null>;

package/dist/core/bot-protection/turnstile-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turnstile-manager.d.ts","sourceRoot":"","sources":["../../../src/core/bot-protection/turnstile-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAElE,qBAAa,gBAAiB,SAAQ,4BAA4B;IAChE,OAAO,CAAC,YAAY,CAAoE;IAExF,SAAS,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtC,SAAS,CAAC,aAAa,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;IAaxE,SAAS,CAAC,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAuCtF,SAAS,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAKjD"}
+{"version":3,"file":"turnstile-manager.d.ts","sourceRoot":"","sources":["../../../src/core/bot-protection/turnstile-manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AAElE,qBAAa,gBAAiB,SAAQ,4BAA4B;IAChE,SAAS,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAqBtC,SAAS,CAAC,aAAa,CAAC,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM;IAaxE,SAAS,CAAC,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAuCtF,SAAS,CAAC,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAKjD"}

package/dist/core/bot-protection/turnstile-manager.js

@@ -7,7 +7,6 @@
 /// <reference path="./types/turnstile.d.ts" />
 import { AbstractBotProtectionManager } from './abstract-manager';
 export class TurnstileManager extends AbstractBotProtectionManager {
-    callbackName = `onloadTurnstileCallback_${Math.random().toString(36).slice(2)}`;
     _waitForApi() {
         if (typeof window !== 'undefined' && window.turnstile) {
             return Promise.resolve();

package/dist/react/components/AddToCartButton.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `<AddToCartButton>` — minimal opinionated "add to cart" trigger that wires
+ * `useCartManager().addItem` to a `<button>` with loading state and error
+ * surfacing.
+ *
+ * Headless: no styling. Renders a button that:
+ *   - disables itself while the mutation is in flight (`aria-busy`),
+ *   - exposes the last error to assistive tech via a visually-hidden alert,
+ *   - invokes `onSuccess` / `onError` callbacks for consumer-side toasts
+ *     or analytics.
+ *
+ * The component does **not** subscribe to the global `onExpired` event — that
+ * is the consumer's responsibility (typically a single global toast). On
+ * stale-cart recovery the SDK swaps the cart transparently and this button
+ * just reports success.
+ *
+ * @example
+ * ```tsx
+ * <AddToCartButton variantId={variant.id} quantity={1}>
+ *   Add to cart
+ * </AddToCartButton>
+ * ```
+ */
+import { type ButtonHTMLAttributes, type ReactNode } from 'react';
+interface CartLineAttribute {
+    key: string;
+    value: string;
+}
+type ButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type' | 'onClick' | 'aria-busy' | 'onError'>;
+export interface AddToCartButtonProps extends ButtonProps {
+    /** Product variant identifier to add. */
+    variantId: string;
+    /** Quantity (default 1). */
+    quantity?: number;
+    /** Cart line attributes (custom options, gift wrap, etc.). */
+    attributes?: CartLineAttribute[];
+    /** Button label / contents. Defaults to "Add to cart". */
+    children?: ReactNode;
+    /** Called after the mutation succeeds with the updated cart summary. */
+    onSuccess?: (result: {
+        cartId: string;
+        totalQuantity: number;
+    }) => void;
+    /** Called when the mutation throws (does not bubble through React Error Boundary). */
+    onError?: (error: Error) => void;
+}
+export declare function AddToCartButton({ variantId, quantity, attributes, children, onSuccess, onError, disabled, ...buttonProps }: AddToCartButtonProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=AddToCartButton.d.ts.map

package/dist/react/components/AddToCartButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AddToCartButton.d.ts","sourceRoot":"","sources":["../../../src/react/components/AddToCartButton.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAY,KAAK,oBAAoB,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG5E,UAAU,iBAAiB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,KAAK,WAAW,GAAG,IAAI,CACrB,oBAAoB,CAAC,iBAAiB,CAAC,EAEvC,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAC7C,CAAC;AAEF,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxE,sFAAsF;IACtF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,wBAAgB,eAAe,CAAC,EAC9B,SAAS,EACT,QAAY,EACZ,UAAU,EACV,QAAQ,EACR,SAAS,EACT,OAAO,EACP,QAAQ,EACR,GAAG,WAAW,EACf,EAAE,oBAAoB,2CAqCtB"}

package/dist/react/components/AddToCartButton.js

@@ -0,0 +1,47 @@
+/**
+ * `<AddToCartButton>` — minimal opinionated "add to cart" trigger that wires
+ * `useCartManager().addItem` to a `<button>` with loading state and error
+ * surfacing.
+ *
+ * Headless: no styling. Renders a button that:
+ *   - disables itself while the mutation is in flight (`aria-busy`),
+ *   - exposes the last error to assistive tech via a visually-hidden alert,
+ *   - invokes `onSuccess` / `onError` callbacks for consumer-side toasts
+ *     or analytics.
+ *
+ * The component does **not** subscribe to the global `onExpired` event — that
+ * is the consumer's responsibility (typically a single global toast). On
+ * stale-cart recovery the SDK swaps the cart transparently and this button
+ * just reports success.
+ *
+ * @example
+ * ```tsx
+ * <AddToCartButton variantId={variant.id} quantity={1}>
+ *   Add to cart
+ * </AddToCartButton>
+ * ```
+ */
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { useCartManager } from '../hooks/use-cart-manager';
+export function AddToCartButton({ variantId, quantity = 1, attributes, children, onSuccess, onError, disabled, ...buttonProps }) {
+    const { addItem, isLoading } = useCartManager();
+    const [localError, setLocalError] = useState(null);
+    const handleClick = async () => {
+        setLocalError(null);
+        try {
+            const result = await addItem([{ variantId, quantity, attributes }]);
+            onSuccess?.({
+                cartId: result.cart.id,
+                totalQuantity: result.cart.totalQuantity,
+            });
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error('Failed to add to cart');
+            setLocalError(error);
+            onError?.(error);
+        }
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("button", { ...buttonProps, type: "button", onClick: handleClick, disabled: disabled || isLoading, "aria-busy": isLoading || undefined, children: children ?? 'Add to cart' }), localError && (_jsx("span", { role: "alert", style: { position: 'absolute', width: 1, height: 1, overflow: 'hidden', clip: 'rect(0 0 0 0)' }, children: localError.message }))] }));
+}

package/dist/react/components/CartCount.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `<CartCount>` — render the cart item count with screen-reader-friendly
+ * semantics (`aria-live="polite"`).
+ *
+ * Receives `count` explicitly rather than reading from a store — the SDK's
+ * cart store tracks `cartId`, not line totals (which come from a GraphQL
+ * query in the consumer). This keeps the component reusable across data
+ * layers (React Query, SWR, Apollo, custom fetcher).
+ *
+ * @example
+ * ```tsx
+ * const { data } = useCartQuery(cartId);
+ * <CartCount count={data?.totalQuantity ?? 0} />
+ * ```
+ */
+export interface CartCountProps {
+    /** Number of items in the cart. */
+    count: number;
+    /** Class name for styling. */
+    className?: string;
+    /**
+     * Custom formatter (e.g. localised pluralisation).
+     * Default: stringifies the count.
+     */
+    formatter?: (count: number) => string;
+    /**
+     * Optional label rendered after the count (e.g. "items"). Use a localised
+     * string from the consumer's i18n layer rather than hardcoding.
+     */
+    label?: string;
+    /** Hide entirely when count is zero (default `false`). */
+    hideWhenEmpty?: boolean;
+}
+export declare function CartCount({ count, className, formatter, label, hideWhenEmpty, }: CartCountProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=CartCount.d.ts.map

package/dist/react/components/CartCount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartCount.d.ts","sourceRoot":"","sources":["../../../src/react/components/CartCount.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,SAAS,EACT,SAAS,EACT,KAAK,EACL,aAAqB,GACtB,EAAE,cAAc,kDAYhB"}

package/dist/react/components/CartCount.js

@@ -0,0 +1,23 @@
+/**
+ * `<CartCount>` — render the cart item count with screen-reader-friendly
+ * semantics (`aria-live="polite"`).
+ *
+ * Receives `count` explicitly rather than reading from a store — the SDK's
+ * cart store tracks `cartId`, not line totals (which come from a GraphQL
+ * query in the consumer). This keeps the component reusable across data
+ * layers (React Query, SWR, Apollo, custom fetcher).
+ *
+ * @example
+ * ```tsx
+ * const { data } = useCartQuery(cartId);
+ * <CartCount count={data?.totalQuantity ?? 0} />
+ * ```
+ */
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function CartCount({ count, className, formatter, label, hideWhenEmpty = false, }) {
+    if (hideWhenEmpty && count === 0)
+        return null;
+    const text = formatter ? formatter(count) : String(count);
+    return (_jsxs("span", { className: className, "aria-live": "polite", "aria-atomic": "true", children: [_jsx("span", { "aria-hidden": "true", children: text }), _jsxs("span", { className: "sr-only", children: [text, label ? ` ${label}` : ''] })] }));
+}

package/dist/react/components/CartTotals.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `<CartTotals>` — render a description list (`<dl>`) of cart financial
+ * breakdown rows: subtotal, optional discount / shipping / tax, total.
+ *
+ * Renders only the rows you pass. `subtotal`, `total`, and `currency` are
+ * required; everything else is optional and elided when undefined or zero
+ * (discount specifically — pass zero to hide rather than showing "-0,00").
+ *
+ * Labels are passed by the consumer (i18n is its responsibility). The
+ * component defaults to English labels so it works out of the box during
+ * prototyping.
+ *
+ * @example
+ * ```tsx
+ * <CartTotals
+ *   subtotal={cart.cost.subtotal.amount * 100}
+ *   shipping={cart.cost.shipping?.amount * 100}
+ *   tax={cart.cost.tax?.amount * 100}
+ *   total={cart.cost.total.amount * 100}
+ *   currency={cart.cost.total.currencyCode}
+ *   labels={{ subtotal: 'Suma częściowa', shipping: 'Dostawa', tax: 'Podatek', total: 'Razem' }}
+ * />
+ * ```
+ */
+import type { ReactNode } from 'react';
+export interface CartTotalsLabels {
+    subtotal?: ReactNode;
+    discount?: ReactNode;
+    shipping?: ReactNode;
+    tax?: ReactNode;
+    total?: ReactNode;
+}
+export interface CartTotalsProps {
+    /** Subtotal in minor units. */
+    subtotal: number;
+    /** Discount in minor units. Rendered as `−<amount>` when > 0. */
+    discount?: number;
+    /** Shipping in minor units. Rendered when provided (incl. 0 = free shipping). */
+    shipping?: number;
+    /** Tax in minor units. Rendered when provided. */
+    tax?: number;
+    /** Total in minor units. */
+    total: number;
+    /** ISO 4217 currency code shared by every line. */
+    currency: string;
+    /** Class applied to the wrapping `<dl>`. */
+    className?: string;
+    /** Class applied to each `<div>` row (subtotal, discount, etc.). */
+    rowClassName?: string;
+    /** Custom row labels. Defaults to English. */
+    labels?: CartTotalsLabels;
+}
+export declare function CartTotals({ subtotal, discount, shipping, tax, total, currency, className, rowClassName, labels, }: CartTotalsProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=CartTotals.d.ts.map

package/dist/react/components/CartTotals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartTotals.d.ts","sourceRoot":"","sources":["../../../src/react/components/CartTotals.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAUD,wBAAgB,UAAU,CAAC,EACzB,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,GAAG,EACH,KAAK,EACL,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,MAAM,GACP,EAAE,eAAe,2CAoCjB"}