@doswiftly/storefront-sdk 4.0.0

package/dist/core/auth/cookie-config.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Auth Cookie Configuration — platform contract.
+ *
+ * Backend validates cookie by name `customerAccessToken`.
+ * Every storefront MUST use the same name. Security options
+ * (httpOnly, secure, sameSite) are the platform standard.
+ */
+export declare const AUTH_COOKIE_NAME = "customerAccessToken";
+export declare const AUTH_COOKIE_DEFAULTS: {
+    readonly name: "customerAccessToken";
+    readonly path: "/";
+    readonly sameSite: "lax";
+    readonly httpOnly: true;
+    readonly secure: boolean;
+    readonly maxAge: number;
+};
+export type AuthCookieConfig = typeof AUTH_COOKIE_DEFAULTS;
+//# sourceMappingURL=cookie-config.d.ts.map

package/dist/core/auth/cookie-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-config.d.ts","sourceRoot":"","sources":["../../../src/core/auth/cookie-config.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB,wBAAwB,CAAC;AAEtD,eAAO,MAAM,oBAAoB;;;;;;;CAUvB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,OAAO,oBAAoB,CAAC"}

package/dist/core/auth/cookie-config.js

@@ -0,0 +1,18 @@
+/**
+ * Auth Cookie Configuration — platform contract.
+ *
+ * Backend validates cookie by name `customerAccessToken`.
+ * Every storefront MUST use the same name. Security options
+ * (httpOnly, secure, sameSite) are the platform standard.
+ */
+export const AUTH_COOKIE_NAME = 'customerAccessToken';
+export const AUTH_COOKIE_DEFAULTS = {
+    name: AUTH_COOKIE_NAME,
+    path: '/',
+    sameSite: 'lax',
+    httpOnly: true,
+    secure: typeof window !== 'undefined'
+        ? window.location.protocol === 'https:'
+        : process.env.NODE_ENV === 'production',
+    maxAge: 60 * 60 * 24 * 30, // 30 days
+};

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

@@ -0,0 +1,32 @@
+/**
+ * Auth cookie handlers — factory functions for API routes.
+ *
+ * 0 deps, pure Web API (Request/Response). Framework-agnostic.
+ * Creates set-token and clear-token handlers that any storefront
+ * can use as 2-line API routes.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/set-token/route.ts
+ * import { createSetTokenHandler } from '@doswiftly/storefront-sdk';
+ * export const POST = createSetTokenHandler();
+ * ```
+ */
+interface SetTokenHandlerOptions {
+    maxAge?: number;
+}
+/**
+ * Create a POST handler that sets the auth token in an httpOnly cookie.
+ *
+ * Security: origin validation, Content-Type check, CSRF (SameSite=Lax),
+ * httpOnly (XSS protection), Secure in production.
+ */
+export declare function createSetTokenHandler(overrides?: SetTokenHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * Create a POST handler that clears the auth token cookie.
+ *
+ * Security: origin validation, immediate expiration (maxAge=0).
+ */
+export declare function createClearTokenHandler(): (request: Request) => Promise<Response>;
+export {};
+//# sourceMappingURL=handlers.d.ts.map

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

@@ -0,0 +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;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAkCjF"}

package/dist/core/auth/handlers.js

@@ -0,0 +1,127 @@
+/**
+ * Auth cookie handlers — factory functions for API routes.
+ *
+ * 0 deps, pure Web API (Request/Response). Framework-agnostic.
+ * Creates set-token and clear-token handlers that any storefront
+ * can use as 2-line API routes.
+ *
+ * @example
+ * ```ts
+ * // app/api/auth/set-token/route.ts
+ * import { createSetTokenHandler } from '@doswiftly/storefront-sdk';
+ * export const POST = createSetTokenHandler();
+ * ```
+ */
+import { AUTH_COOKIE_NAME, AUTH_COOKIE_DEFAULTS } from './cookie-config';
+function serializeCookie(name, value, options) {
+    const parts = [`${name}=${value}`];
+    if (options.maxAge != null)
+        parts.push(`Max-Age=${options.maxAge}`);
+    if (options.path)
+        parts.push(`Path=${options.path}`);
+    if (options.sameSite)
+        parts.push(`SameSite=${options.sameSite}`);
+    if (options.secure)
+        parts.push('Secure');
+    if (options.httpOnly)
+        parts.push('HttpOnly');
+    return parts.join('; ');
+}
+function validateOrigin(request) {
+    const origin = request.headers.get('origin');
+    const host = request.headers.get('host');
+    if (origin && !origin.includes(host || '')) {
+        return new Response(JSON.stringify({ error: 'Invalid origin' }), {
+            status: 403,
+            headers: { 'Content-Type': 'application/json' },
+        });
+    }
+    return null;
+}
+/**
+ * Create a POST handler that sets the auth token in an httpOnly cookie.
+ *
+ * Security: origin validation, Content-Type check, CSRF (SameSite=Lax),
+ * httpOnly (XSS protection), Secure in production.
+ */
+export function createSetTokenHandler(overrides) {
+    const maxAge = overrides?.maxAge ?? AUTH_COOKIE_DEFAULTS.maxAge;
+    return async (request) => {
+        try {
+            // 1. CSRF: validate origin
+            const originError = validateOrigin(request);
+            if (originError)
+                return originError;
+            // 2. Validate Content-Type
+            const contentType = request.headers.get('content-type');
+            if (!contentType?.includes('application/json')) {
+                return new Response(JSON.stringify({ error: 'Content-Type must be application/json' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
+            }
+            // 3. Parse body
+            let body;
+            try {
+                body = await request.json();
+            }
+            catch {
+                return new Response(JSON.stringify({ error: 'Invalid JSON body' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
+            }
+            const { token } = body;
+            if (!token || typeof token !== 'string' || token.trim() === '') {
+                return new Response(JSON.stringify({ error: 'Token is required and must be a non-empty string' }), { status: 400, headers: { 'Content-Type': 'application/json' } });
+            }
+            // 4. Set httpOnly cookie
+            const cookie = serializeCookie(AUTH_COOKIE_NAME, token, {
+                maxAge,
+                path: AUTH_COOKIE_DEFAULTS.path,
+                sameSite: AUTH_COOKIE_DEFAULTS.sameSite,
+                secure: AUTH_COOKIE_DEFAULTS.secure,
+                httpOnly: AUTH_COOKIE_DEFAULTS.httpOnly,
+            });
+            return new Response(JSON.stringify({ success: true, message: 'Token set successfully' }), {
+                status: 200,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Set-Cookie': cookie,
+                },
+            });
+        }
+        catch (error) {
+            console.error('Error setting auth token:', error);
+            return new Response(JSON.stringify({ error: 'Internal server error' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
+        }
+    };
+}
+/**
+ * Create a POST handler that clears the auth token cookie.
+ *
+ * Security: origin validation, immediate expiration (maxAge=0).
+ */
+export function createClearTokenHandler() {
+    return async (request) => {
+        try {
+            // 1. CSRF: validate origin
+            const originError = validateOrigin(request);
+            if (originError)
+                return originError;
+            // 2. Clear cookie (maxAge=0)
+            const cookie = serializeCookie(AUTH_COOKIE_NAME, '', {
+                maxAge: 0,
+                path: AUTH_COOKIE_DEFAULTS.path,
+                sameSite: AUTH_COOKIE_DEFAULTS.sameSite,
+                secure: AUTH_COOKIE_DEFAULTS.secure,
+                httpOnly: AUTH_COOKIE_DEFAULTS.httpOnly,
+            });
+            return new Response(JSON.stringify({ success: true, message: 'Token cleared successfully' }), {
+                status: 200,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Set-Cookie': cookie,
+                },
+            });
+        }
+        catch (error) {
+            console.error('Error clearing auth token:', error);
+            return new Response(JSON.stringify({ error: 'Internal server error' }), { status: 500, headers: { 'Content-Type': 'application/json' } });
+        }
+    };
+}

package/dist/core/auth/routes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Route matching utility for auth redirects.
+ *
+ * Pure function — route lists stay in the template (SSOT config),
+ * but matching logic lives in the SDK (reusable across templates).
+ */
+export interface RouteProtectionConfig {
+    protectedRoutes: string[];
+    guestOnlyRoutes: string[];
+    redirects: {
+        unauthenticated: string;
+        authenticated: string;
+    };
+}
+/**
+ * Check if a pathname matches any route in the list.
+ * Supports both exact matches and prefix matches
+ * (e.g., "/account" matches "/account/orders").
+ */
+export declare function matchesRoute(pathname: string, routes: string[]): boolean;
+//# sourceMappingURL=routes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../../src/core/auth/routes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,EAAE;QACT,eAAe,EAAE,MAAM,CAAC;QACxB,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAIxE"}

package/dist/core/auth/routes.js

@@ -0,0 +1,14 @@
+/**
+ * Route matching utility for auth redirects.
+ *
+ * Pure function — route lists stay in the template (SSOT config),
+ * but matching logic lives in the SDK (reusable across templates).
+ */
+/**
+ * Check if a pathname matches any route in the list.
+ * Supports both exact matches and prefix matches
+ * (e.g., "/account" matches "/account/orders").
+ */
+export function matchesRoute(pathname, routes) {
+    return routes.some((route) => pathname === route || pathname.startsWith(`${route}/`));
+}

package/dist/core/auth/token-client.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Client-side auth token helpers — fetch-based, 0 deps.
+ *
+ * Calls API routes to set/clear the httpOnly auth cookie.
+ * Used by template hooks (use-auth.ts, use-auth-sync.ts, register-form.tsx).
+ *
+ * @example
+ * ```ts
+ * import { createAuthTokenClient } from '@doswiftly/storefront-sdk';
+ * const { setToken, clearToken } = createAuthTokenClient();
+ *
+ * await setToken(accessToken);
+ * await clearToken();
+ * ```
+ */
+export interface AuthTokenClient {
+    setToken: (token: string) => Promise<void>;
+    clearToken: () => Promise<void>;
+}
+/**
+ * Create a client for managing auth tokens via API routes.
+ *
+ * @param basePath - Base path for API routes (default: "/api/auth")
+ */
+export declare function createAuthTokenClient(basePath?: string): AuthTokenClient;
+//# sourceMappingURL=token-client.d.ts.map

package/dist/core/auth/token-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-client.d.ts","sourceRoot":"","sources":["../../../src/core/auth/token-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,SAAc,GAAG,eAAe,CAwB7E"}

package/dist/core/auth/token-client.js

@@ -0,0 +1,42 @@
+/**
+ * Client-side auth token helpers — fetch-based, 0 deps.
+ *
+ * Calls API routes to set/clear the httpOnly auth cookie.
+ * Used by template hooks (use-auth.ts, use-auth-sync.ts, register-form.tsx).
+ *
+ * @example
+ * ```ts
+ * import { createAuthTokenClient } from '@doswiftly/storefront-sdk';
+ * const { setToken, clearToken } = createAuthTokenClient();
+ *
+ * await setToken(accessToken);
+ * await clearToken();
+ * ```
+ */
+/**
+ * Create a client for managing auth tokens via API routes.
+ *
+ * @param basePath - Base path for API routes (default: "/api/auth")
+ */
+export function createAuthTokenClient(basePath = '/api/auth') {
+    return {
+        async setToken(token) {
+            const response = await fetch(`${basePath}/set-token`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ token }),
+            });
+            if (!response.ok) {
+                throw new Error('Failed to set authentication token');
+            }
+        },
+        async clearToken() {
+            const response = await fetch(`${basePath}/clear-token`, {
+                method: 'POST',
+            });
+            if (!response.ok) {
+                throw new Error('Failed to clear authentication token');
+            }
+        },
+    };
+}

package/dist/core/auth/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Auth types — manual (no codegen).
+ */
+export interface CustomerAccessToken {
+    accessToken: string;
+    expiresAt: string;
+}
+export interface Customer {
+    id: string;
+    email: string;
+    firstName: string | null;
+    lastName: string | null;
+    displayName: string | null;
+    phone: string | null;
+    emailVerified: boolean;
+    emailMarketingState: string | null;
+    defaultAddress: MailingAddress | null;
+    ordersCount: number;
+    totalSpent: {
+        amount: string;
+        currencyCode: string;
+    } | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MailingAddress {
+    id: string;
+    address1: string | null;
+    address2: string | null;
+    city: string | null;
+    company: string | null;
+    country: string | null;
+    countryCode: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    phone: string | null;
+    province: string | null;
+    provinceCode: string | null;
+    zip: string | null;
+    isDefault: boolean;
+}
+export interface AuthResult {
+    accessToken: string;
+    expiresAt: string;
+    customer?: Customer;
+}
+export interface CustomerCreateInput {
+    email: string;
+    password: string;
+    firstName?: string;
+    lastName?: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/core/auth/types.js

@@ -0,0 +1,4 @@
+/**
+ * Auth types — manual (no codegen).
+ */
+export {};

package/dist/core/cache.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Cache strategies — functions (not constants) with override support.
+ *
+ * Inspired by Shopify Hydrogen's caching strategies.
+ *
+ * @example
+ * ```typescript
+ * import { cacheLong, cacheShort } from '@doswiftly/storefront-sdk';
+ *
+ * // Default
+ * const data = await client.query(ShopQuery, {}, cacheLong());
+ *
+ * // Override with tags (Next.js revalidateTag)
+ * const data = await client.query(ProductQuery, { slug }, cacheLong({ tags: ['product', slug] }));
+ * ```
+ */
+import type { CacheStrategy, CacheOptions } from './client/types';
+export interface CacheOverrides {
+    /** Override max-age (seconds) */
+    maxAge?: number;
+    /** Override stale-while-revalidate (seconds) */
+    staleWhileRevalidate?: number;
+    /** Cache tags (for Next.js revalidateTag) */
+    tags?: string[];
+}
+/**
+ * No caching — every request hits the server.
+ * Use for: Cart, Customer data, real-time inventory.
+ */
+export declare function cacheNone(overrides?: CacheOverrides): CacheStrategy;
+/**
+ * Short cache — 1s max-age, 9s stale-while-revalidate (10s total).
+ * Use for: Product listings, collections, search results.
+ */
+export declare function cacheShort(overrides?: CacheOverrides): CacheStrategy;
+/**
+ * Long cache — 1h max-age, 23h stale-while-revalidate (24h total).
+ * Use for: Static content, shop info, rarely changing data.
+ */
+export declare function cacheLong(overrides?: CacheOverrides): CacheStrategy;
+/**
+ * Private cache — 1s max-age, no sharing between users.
+ * Use for: Personalized content, customer-specific data.
+ */
+export declare function cachePrivate(overrides?: CacheOverrides): CacheStrategy;
+/**
+ * Custom cache — full control over all options.
+ */
+export declare function cacheCustom(options: CacheOptions): CacheStrategy;
+/**
+ * Generate Cache-Control header string from cache strategy.
+ */
+export declare function generateCacheControlHeader(cache: CacheStrategy): string;
+//# sourceMappingURL=cache.d.ts.map

package/dist/core/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/core/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,aAAa,CAMnE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,aAAa,CAOpE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,aAAa,CAOnE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,cAAc,GAAG,aAAa,CAOtE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,aAAa,CAEhE;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAYvE"}

package/dist/core/cache.js

@@ -0,0 +1,82 @@
+/**
+ * Cache strategies — functions (not constants) with override support.
+ *
+ * Inspired by Shopify Hydrogen's caching strategies.
+ *
+ * @example
+ * ```typescript
+ * import { cacheLong, cacheShort } from '@doswiftly/storefront-sdk';
+ *
+ * // Default
+ * const data = await client.query(ShopQuery, {}, cacheLong());
+ *
+ * // Override with tags (Next.js revalidateTag)
+ * const data = await client.query(ProductQuery, { slug }, cacheLong({ tags: ['product', slug] }));
+ * ```
+ */
+/**
+ * No caching — every request hits the server.
+ * Use for: Cart, Customer data, real-time inventory.
+ */
+export function cacheNone(overrides) {
+    return {
+        maxAge: 0,
+        mode: 'no-store',
+        tags: overrides?.tags,
+    };
+}
+/**
+ * Short cache — 1s max-age, 9s stale-while-revalidate (10s total).
+ * Use for: Product listings, collections, search results.
+ */
+export function cacheShort(overrides) {
+    return {
+        maxAge: overrides?.maxAge ?? 1,
+        staleWhileRevalidate: overrides?.staleWhileRevalidate ?? 9,
+        mode: 'public',
+        tags: overrides?.tags,
+    };
+}
+/**
+ * Long cache — 1h max-age, 23h stale-while-revalidate (24h total).
+ * Use for: Static content, shop info, rarely changing data.
+ */
+export function cacheLong(overrides) {
+    return {
+        maxAge: overrides?.maxAge ?? 3600,
+        staleWhileRevalidate: overrides?.staleWhileRevalidate ?? 82800,
+        mode: 'public',
+        tags: overrides?.tags,
+    };
+}
+/**
+ * Private cache — 1s max-age, no sharing between users.
+ * Use for: Personalized content, customer-specific data.
+ */
+export function cachePrivate(overrides) {
+    return {
+        maxAge: overrides?.maxAge ?? 1,
+        staleWhileRevalidate: overrides?.staleWhileRevalidate ?? 9,
+        mode: 'private',
+        tags: overrides?.tags,
+    };
+}
+/**
+ * Custom cache — full control over all options.
+ */
+export function cacheCustom(options) {
+    return { ...options };
+}
+/**
+ * Generate Cache-Control header string from cache strategy.
+ */
+export function generateCacheControlHeader(cache) {
+    if (cache.mode === 'no-store') {
+        return 'no-store, no-cache, must-revalidate';
+    }
+    const parts = [cache.mode, `max-age=${cache.maxAge}`];
+    if (cache.staleWhileRevalidate !== undefined) {
+        parts.push(`stale-while-revalidate=${cache.staleWhileRevalidate}`);
+    }
+    return parts.join(', ');
+}

package/dist/core/cart/cart-client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * CartClient — plain async API for cart operations (no React, no React Query).
+ *
+ * Wraps StorefrontClient.mutate/query with typed operations.
+ * Auto-throws on userErrors via assertNoUserErrors.
+ *
+ * @example
+ * ```typescript
+ * const cartClient = new CartClient(storefrontClient);
+ *
+ * const cart = await cartClient.create();
+ * const updated = await cartClient.addItem(cart.id, [
+ *   { merchandiseId: 'variant-123', quantity: 1 }
+ * ]);
+ * ```
+ */
+import type { StorefrontClient } from '../client/types';
+import type { Cart, CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput } from './types';
+export declare class CartClient {
+    private readonly client;
+    constructor(client: StorefrontClient);
+    /**
+     * Fetch existing cart by ID.
+     * Returns null if cart doesn't exist or has expired.
+     */
+    get(cartId: string): Promise<Cart | null>;
+    /**
+     * Create a new cart, optionally with initial lines.
+     */
+    create(input?: CartCreateInput): Promise<Cart>;
+    /**
+     * Add line items to an existing cart.
+     */
+    addItems(cartId: string, lines: CartLineInput[]): Promise<Cart>;
+    /**
+     * Update line items (quantity, attributes).
+     */
+    updateItems(cartId: string, lines: CartLineUpdateInput[]): Promise<Cart>;
+    /**
+     * Remove line items by their line IDs.
+     */
+    removeItems(cartId: string, lineIds: string[]): Promise<Cart>;
+    /**
+     * Update discount codes (replaces all existing codes).
+     * Pass empty array to clear discounts.
+     */
+    updateDiscountCodes(cartId: string, discountCodes: string[]): Promise<Cart>;
+    /**
+     * Update cart note / gift message.
+     */
+    updateNote(cartId: string, note: string): Promise<Cart>;
+    /**
+     * Update buyer identity (email, phone, country, customer link).
+     */
+    updateBuyerIdentity(cartId: string, buyerIdentity: CartBuyerIdentityInput): Promise<Cart>;
+}
+//# sourceMappingURL=cart-client.d.ts.map

package/dist/core/cart/cart-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart-client.d.ts","sourceRoot":"","sources":["../../../src/core/cart/cart-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EACV,IAAI,EACJ,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,SAAS,CAAC;AA0BjB,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;;;OAGG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAQ/C;;OAEG;IACG,MAAM,CAAC,KAAK,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IASpD;;OAEG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASrE;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9E;;OAEG;IACG,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASnE;;;OAGG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASjF;;OAEG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D;;OAEG;IACG,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;CAQhG"}