@doswiftly/storefront-sdk 4.0.0 → 4.2.0

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

@@ -0,0 +1,14 @@
+/**
+ * Currency configuration constants — platform contract.
+ *
+ * Used by:
+ * - SDK currency store (client-side cookie read/write)
+ * - SDK currency middleware (X-Preferred-Currency header)
+ * - Server-side currency detection (SSR helpers)
+ *
+ * Single cookie for preferred currency persistence.
+ */
+export declare const CURRENCY_COOKIE_NAME = "preferred-currency";
+export declare const CURRENCY_COOKIE_MAX_AGE: number;
+export declare const CURRENCY_HEADER_NAME = "X-Preferred-Currency";
+//# sourceMappingURL=cookie-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-config.d.ts","sourceRoot":"","sources":["../../../src/core/currency/cookie-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AACzD,eAAO,MAAM,uBAAuB,QAAqB,CAAC;AAC1D,eAAO,MAAM,oBAAoB,yBAAyB,CAAC"}

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

@@ -0,0 +1,13 @@
+/**
+ * Currency configuration constants — platform contract.
+ *
+ * Used by:
+ * - SDK currency store (client-side cookie read/write)
+ * - SDK currency middleware (X-Preferred-Currency header)
+ * - Server-side currency detection (SSR helpers)
+ *
+ * Single cookie for preferred currency persistence.
+ */
+export const CURRENCY_COOKIE_NAME = 'preferred-currency';
+export const CURRENCY_COOKIE_MAX_AGE = 365 * 24 * 60 * 60; // 1 year
+export const CURRENCY_HEADER_NAME = 'X-Preferred-Currency';

package/dist/core/image.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Image utilities for DoSwiftly storefronts.
+ *
+ * Zero configuration — GraphQL API returns ready-to-use CDN URLs.
+ * The loader just appends resize query params. No keys, no env vars.
+ *
+ * @example
+ * ```typescript
+ * import { storefrontImageLoader, type ImageData } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={product.featuredImage.url} width={800} alt="..." />
+ * ```
+ */
+/**
+ * Image data from GraphQL API (matches Image type in storefront schema).
+ */
+export interface ImageData {
+    /** Image URL from GraphQL (ready-to-use CDN URL) */
+    url: string;
+    /** Alt text for accessibility + SEO */
+    altText?: string | null;
+    /** Original image width in pixels */
+    width?: number | null;
+    /** Original image height in pixels */
+    height?: number | null;
+    /** Image ID */
+    id?: string | null;
+}
+/**
+ * Next.js Image loader function signature.
+ */
+export interface ImageLoaderParams {
+    src: string;
+    width: number;
+    quality?: number;
+}
+/**
+ * Next.js image loader for DoSwiftly storefronts.
+ *
+ * Zero configuration — works out of the box with GraphQL image URLs.
+ * Appends resize query params (?width=&quality=&format=) to the URL
+ * that backend already returned via GraphQL.
+ *
+ * Width is quantized to preset breakpoints for optimal CDN cache.
+ * No HMAC, no env vars, no setup — like Shopify Hydrogen's image loader.
+ *
+ * @example
+ * ```tsx
+ * import { storefrontImageLoader } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={image.url} width={800} alt="..." />
+ * ```
+ */
+export declare function storefrontImageLoader({ src, width, quality }: ImageLoaderParams): string;
+//# sourceMappingURL=image.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/core/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,iBAAiB,GAAG,MAAM,CAKxF"}

package/dist/core/image.js

@@ -0,0 +1,48 @@
+/**
+ * Image utilities for DoSwiftly storefronts.
+ *
+ * Zero configuration — GraphQL API returns ready-to-use CDN URLs.
+ * The loader just appends resize query params. No keys, no env vars.
+ *
+ * @example
+ * ```typescript
+ * import { storefrontImageLoader, type ImageData } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={product.featuredImage.url} width={800} alt="..." />
+ * ```
+ */
+/**
+ * Preset widths for CDN cache optimization.
+ * Loader quantizes requested width to the nearest preset — limits cache variants.
+ */
+const PRESET_WIDTHS = [150, 320, 640, 750, 828, 1080, 1200, 1600, 1920, 2048];
+function nearestPresetWidth(requested) {
+    for (const w of PRESET_WIDTHS) {
+        if (w >= requested)
+            return w;
+    }
+    return PRESET_WIDTHS[PRESET_WIDTHS.length - 1];
+}
+/**
+ * Next.js image loader for DoSwiftly storefronts.
+ *
+ * Zero configuration — works out of the box with GraphQL image URLs.
+ * Appends resize query params (?width=&quality=&format=) to the URL
+ * that backend already returned via GraphQL.
+ *
+ * Width is quantized to preset breakpoints for optimal CDN cache.
+ * No HMAC, no env vars, no setup — like Shopify Hydrogen's image loader.
+ *
+ * @example
+ * ```tsx
+ * import { storefrontImageLoader } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={image.url} width={800} alt="..." />
+ * ```
+ */
+export function storefrontImageLoader({ src, width, quality }) {
+    const w = nearestPresetWidth(width);
+    const q = quality || 85;
+    const separator = src.includes('?') ? '&' : '?';
+    return `${src}${separator}width=${w}&quality=${q}&format=webp`;
+}

package/dist/core/index.d.ts

@@ -37,9 +37,13 @@ export { createStorefrontClient } from './client/create-client';
 export type { StorefrontClient, StorefrontClientConfig, Middleware, ExecuteFn, GraphQLRequest, GraphQLResponse, GraphQLErrorInfo, UserError, CacheStrategy, CacheOptions, TypedDocumentString, } from './client/types';
 export { authMiddleware } from './middleware/auth';
 export { currencyMiddleware } from './middleware/currency';
+export { languageMiddleware } from './middleware/language';
+export { botProtectionMiddleware, BOT_PROTECTION_HEADER, type BotProtectionTokenProvider, type BotProtectionConfig, type BotProtectionProviderConfig, type BotProtectionMiddlewareOptions, type FailStrategy, } from './middleware/bot-protection';
 export { retryMiddleware, type RetryOptions } from './middleware/retry';
 export { timeoutMiddleware, type TimeoutOptions } from './middleware/timeout';
 export { errorMiddleware } from './middleware/errors';
+export { createBotProtectionManager } from './bot-protection/create-manager';
+export { FallbackBotProtectionManager } from './bot-protection/fallback-manager';
 export { StorefrontError, ErrorCodes, type StorefrontErrorOptions } from './errors';
 export { cacheNone, cacheShort, cacheLong, cachePrivate, cacheCustom, generateCacheControlHeader, type CacheOverrides, } from './cache';
 export { CartClient } from './cart/cart-client';
@@ -51,9 +55,13 @@ export { sanitizeHtml } from './helpers/sanitize-html';
 export { normalizeConnection, type Connection, type ConnectionEdge, type ConnectionPageInfo, type NormalizedConnection, } from './helpers/normalize-connection';
 export { formatPrice, formatPriceRange, formatAmount, formatDate, formatDateTime, formatNumber, formatPercentage, getCurrencySymbol, CURRENCY_SYMBOLS, CURRENCY_LOCALES, type PriceMoney, } from './format';
 export { AUTH_COOKIE_NAME, AUTH_COOKIE_DEFAULTS, type AuthCookieConfig, } from './auth/cookie-config';
+export { LANGUAGE_COOKIE_NAME, LANGUAGE_COOKIE_MAX_AGE, LANGUAGE_HEADER_NAME } from './language/cookie-config';
+export { CURRENCY_COOKIE_NAME, CURRENCY_COOKIE_MAX_AGE, CURRENCY_HEADER_NAME } from './currency/cookie-config';
+export { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from './cart/cookie-config';
 export { matchesRoute, type RouteProtectionConfig } from './auth/routes';
 export { createSetTokenHandler, createClearTokenHandler } from './auth/handlers';
 export { createAuthTokenClient, type AuthTokenClient } from './auth/token-client';
+export { storefrontImageLoader, type ImageData, type ImageLoaderParams, } from './image';
 export { getOperationName } from './client/operation-name';
 export { hashQuery } from './client/hash';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAGhE,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,UAAU,EACV,SAAS,EACT,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,YAAY,EACZ,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGpF,OAAO,EACL,SAAS,EACT,UAAU,EACV,SAAS,EACT,YAAY,EACZ,WAAW,EACX,0BAA0B,EAC1B,KAAK,cAAc,GACpB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,YAAY,EACV,IAAI,EACJ,QAAQ,EACR,mBAAmB,EACnB,YAAY,EACZ,QAAQ,EACR,iBAAiB,EACjB,gBAAgB,EAChB,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACnB,eAAe,EACf,sBAAsB,EACtB,KAAK,GACN,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,YAAY,EACV,QAAQ,EACR,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,EACL,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACV,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,UAAU,GAChB,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,gBAAgB,GACtB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,YAAY,EAAE,KAAK,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAGzE,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAGjF,OAAO,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGlF,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}

package/dist/core/index.js

@@ -38,9 +38,14 @@ export { createStorefrontClient } from './client/create-client';
 // Middleware
 export { authMiddleware } from './middleware/auth';
 export { currencyMiddleware } from './middleware/currency';
+export { languageMiddleware } from './middleware/language';
+export { botProtectionMiddleware, BOT_PROTECTION_HEADER, } from './middleware/bot-protection';
 export { retryMiddleware } from './middleware/retry';
 export { timeoutMiddleware } from './middleware/timeout';
 export { errorMiddleware } from './middleware/errors';
+// Bot protection managers (framework-agnostic, DOM APIs)
+export { createBotProtectionManager } from './bot-protection/create-manager';
+export { FallbackBotProtectionManager } from './bot-protection/fallback-manager';
 // Errors
 export { StorefrontError, ErrorCodes } from './errors';
 // Cache strategies
@@ -57,12 +62,20 @@ export { normalizeConnection, } from './helpers/normalize-connection';
 export { formatPrice, formatPriceRange, formatAmount, formatDate, formatDateTime, formatNumber, formatPercentage, getCurrencySymbol, CURRENCY_SYMBOLS, CURRENCY_LOCALES, } from './format';
 // Auth cookie config (platform contract)
 export { AUTH_COOKIE_NAME, AUTH_COOKIE_DEFAULTS, } from './auth/cookie-config';
+// Language config
+export { LANGUAGE_COOKIE_NAME, LANGUAGE_COOKIE_MAX_AGE, LANGUAGE_HEADER_NAME } from './language/cookie-config';
+// Currency config
+export { CURRENCY_COOKIE_NAME, CURRENCY_COOKIE_MAX_AGE, CURRENCY_HEADER_NAME } from './currency/cookie-config';
+// Cart cookie config
+export { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from './cart/cookie-config';
 // Auth route matching
 export { matchesRoute } from './auth/routes';
 // Auth cookie handlers (API route factories)
 export { createSetTokenHandler, createClearTokenHandler } from './auth/handlers';
 // Auth token client (client-side fetch helpers)
 export { createAuthTokenClient } from './auth/token-client';
+// Image utilities
+export { storefrontImageLoader, } from './image';
 // Utilities
 export { getOperationName } from './client/operation-name';
 export { hashQuery } from './client/hash';

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

@@ -0,0 +1,14 @@
+/**
+ * Language configuration constants — platform contract.
+ *
+ * Used by:
+ * - SDK language store (client-side cookie read/write)
+ * - SDK language middleware (X-Lang header)
+ * - next-intl middleware `localeCookie.name` (server-side locale detection)
+ *
+ * Single cookie replaces both next-intl's NEXT_LOCALE and SDK's preferred-language.
+ */
+export declare const LANGUAGE_COOKIE_NAME = "preferred-language";
+export declare const LANGUAGE_COOKIE_MAX_AGE: number;
+export declare const LANGUAGE_HEADER_NAME = "X-Lang";
+//# sourceMappingURL=cookie-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-config.d.ts","sourceRoot":"","sources":["../../../src/core/language/cookie-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,uBAAuB,CAAC;AACzD,eAAO,MAAM,uBAAuB,QAAqB,CAAC;AAC1D,eAAO,MAAM,oBAAoB,WAAW,CAAC"}

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

@@ -0,0 +1,13 @@
+/**
+ * Language configuration constants — platform contract.
+ *
+ * Used by:
+ * - SDK language store (client-side cookie read/write)
+ * - SDK language middleware (X-Lang header)
+ * - next-intl middleware `localeCookie.name` (server-side locale detection)
+ *
+ * Single cookie replaces both next-intl's NEXT_LOCALE and SDK's preferred-language.
+ */
+export const LANGUAGE_COOKIE_NAME = 'preferred-language';
+export const LANGUAGE_COOKIE_MAX_AGE = 365 * 24 * 60 * 60; // 1 year
+export const LANGUAGE_HEADER_NAME = 'X-Lang';

package/dist/core/middleware/bot-protection.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Bot protection middleware — vendor-agnostic token injection.
+ *
+ * Intercepts protected mutations and adds a bot verification token
+ * via the X-Bot-Protection-Token header. Token acquisition is delegated
+ * to a BotProtectionTokenProvider (EU CAPTCHA, Turnstile, etc.).
+ *
+ * Fail strategy is per-operation: 'open' = continue without token,
+ * 'closed' = throw if token unavailable.
+ */
+import type { Middleware } from '../client/types';
+/** Vendor-agnostic token provider interface */
+export interface BotProtectionTokenProvider {
+    /**
+     * Get a fresh bot protection token.
+     * Handles: in-flight deduplication, timeout, singleton script loading.
+     *
+     * @param options.action - Operation name (e.g. 'CustomerCreate') for action validation
+     * @param options.timeoutMs - Timeout in ms (default: 10000)
+     * @returns Token string or null if unavailable (adblock, timeout, error)
+     */
+    execute(options?: {
+        action?: string;
+        timeoutMs?: number;
+    }): Promise<string | null>;
+    /** Cleanup widget and script resources */
+    destroy(): void;
+}
+/** Single provider config (from shop query) */
+export interface BotProtectionProviderConfig {
+    /** Provider identifier: 'eucaptcha' | 'turnstile' | 'recaptcha' | extensible */
+    provider: string;
+    /** Site key for the bot protection widget */
+    siteKey: string;
+    /** Script URL — configurable for region-specific / enterprise overrides */
+    scriptUrl: string;
+}
+/** Bot protection configuration from shop query */
+export interface BotProtectionConfig {
+    /** Primary provider */
+    primary: BotProtectionProviderConfig;
+    /** Fallback provider (runtime: if primary fails -> fallback -> fail-open) */
+    fallback?: BotProtectionProviderConfig | null;
+    /** GraphQL operation names requiring verification */
+    protectedOperations: string[];
+}
+/** Fail strategy per request */
+export type FailStrategy = 'open' | 'closed';
+export interface BotProtectionMiddlewareOptions {
+    /** Token provider instance (manager or fallback chain) */
+    tokenProvider: BotProtectionTokenProvider;
+    /** GraphQL operation names that require bot protection */
+    protectedOperations: string[];
+    /** Default fail strategy when token acquisition fails (default: 'open') */
+    defaultFailStrategy?: FailStrategy;
+    /** Override fail strategy per operation (e.g. CheckoutComplete = closed) */
+    failStrategyOverrides?: Record<string, FailStrategy>;
+}
+/** Header name for bot protection token */
+export declare const BOT_PROTECTION_HEADER = "X-Bot-Protection-Token";
+/**
+ * Creates bot protection middleware for the SDK pipeline.
+ *
+ * Only intercepts mutations whose operationName is in protectedOperations.
+ * Token is fetched fresh on every call (single-use tokens, retry-safe).
+ *
+ * Pipeline position: AFTER auth/currency, BEFORE retry/timeout/errors.
+ * Retry middleware re-executes the full chain, so each attempt gets a fresh token.
+ */
+export declare function botProtectionMiddleware(options: BotProtectionMiddlewareOptions): Middleware;
+//# sourceMappingURL=bot-protection.d.ts.map

package/dist/core/middleware/bot-protection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot-protection.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/bot-protection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAOlD,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B;IACzC;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEnF,0CAA0C;IAC1C,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD,+CAA+C;AAC/C,MAAM,WAAW,2BAA2B;IAC1C,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC,uBAAuB;IACvB,OAAO,EAAE,2BAA2B,CAAC;IACrC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAC9C,qDAAqD;IACrD,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAM7C,MAAM,WAAW,8BAA8B;IAC7C,0DAA0D;IAC1D,aAAa,EAAE,0BAA0B,CAAC;IAC1C,0DAA0D;IAC1D,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,YAAY,CAAC;IACnC,4EAA4E;IAC5E,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACtD;AAMD,2CAA2C;AAC3C,eAAO,MAAM,qBAAqB,2BAA2B,CAAC;AAM9D;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,UAAU,CA2C3F"}

package/dist/core/middleware/bot-protection.js

@@ -0,0 +1,63 @@
+/**
+ * Bot protection middleware — vendor-agnostic token injection.
+ *
+ * Intercepts protected mutations and adds a bot verification token
+ * via the X-Bot-Protection-Token header. Token acquisition is delegated
+ * to a BotProtectionTokenProvider (EU CAPTCHA, Turnstile, etc.).
+ *
+ * Fail strategy is per-operation: 'open' = continue without token,
+ * 'closed' = throw if token unavailable.
+ */
+import { StorefrontError } from '../errors';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Header name for bot protection token */
+export const BOT_PROTECTION_HEADER = 'X-Bot-Protection-Token';
+// ---------------------------------------------------------------------------
+// Middleware factory
+// ---------------------------------------------------------------------------
+/**
+ * Creates bot protection middleware for the SDK pipeline.
+ *
+ * Only intercepts mutations whose operationName is in protectedOperations.
+ * Token is fetched fresh on every call (single-use tokens, retry-safe).
+ *
+ * Pipeline position: AFTER auth/currency, BEFORE retry/timeout/errors.
+ * Retry middleware re-executes the full chain, so each attempt gets a fresh token.
+ */
+export function botProtectionMiddleware(options) {
+    const { tokenProvider, protectedOperations, defaultFailStrategy = 'open', failStrategyOverrides = {}, } = options;
+    const protectedSet = new Set(protectedOperations);
+    return async (request, next) => {
+        // Only intercept mutations
+        if (!request.isMutation)
+            return next(request);
+        // Only intercept protected operations
+        const opName = request.operationName;
+        if (!opName || !protectedSet.has(opName)) {
+            return next(request);
+        }
+        // Fetch fresh token — action param enables backend action validation
+        const token = await tokenProvider.execute({
+            action: opName,
+            timeoutMs: 10000,
+        });
+        if (token) {
+            request.headers[BOT_PROTECTION_HEADER] = token;
+        }
+        else {
+            // Fail strategy: open = continue without token, closed = throw
+            const strategy = failStrategyOverrides[opName] ?? defaultFailStrategy;
+            if (strategy === 'closed') {
+                throw new StorefrontError({
+                    code: 'BOT_PROTECTION_REQUIRED',
+                    message: 'Bot protection verification failed. Please try again.',
+                    status: 0,
+                });
+            }
+            // fail-open: continue without token — backend guard may still reject
+        }
+        return next(request);
+    };
+}

package/dist/core/middleware/currency.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/currency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAC3C,UAAU,CAQZ"}
+{"version":3,"file":"currency.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/currency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAC3C,UAAU,CAQZ"}

package/dist/core/middleware/currency.js

@@ -10,11 +10,12 @@
  * client.use(currencyMiddleware(() => currencyStore.getState().currency));
  * ```
  */
+import { CURRENCY_HEADER_NAME } from '../currency/cookie-config';
 export function currencyMiddleware(getCurrency) {
     return (request, next) => {
         const currency = getCurrency();
         if (currency) {
-            request.headers['X-Preferred-Currency'] = currency;
+            request.headers[CURRENCY_HEADER_NAME] = currency;
         }
         return next(request);
     };

package/dist/core/middleware/language.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Language middleware — adds X-Lang header.
+ *
+ * Language is resolved lazily so language switches are reflected immediately.
+ * CRITICAL: does NOT send header when language=null (store not yet initialized)
+ * — without this, backend returns default language, React Query caches it,
+ *   and after setLanguage() the cache is stale.
+ *
+ * @example
+ * ```typescript
+ * import { languageMiddleware } from '@doswiftly/storefront-sdk';
+ *
+ * client.use(languageMiddleware(() => languageStore.getState().language));
+ * ```
+ */
+import type { Middleware } from '../client/types';
+export declare function languageMiddleware(getLanguage: () => string | null | undefined): Middleware;
+//# sourceMappingURL=language.d.ts.map

package/dist/core/middleware/language.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"language.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/language.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAGlD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAC3C,UAAU,CAQZ"}

package/dist/core/middleware/language.js

@@ -0,0 +1,25 @@
+/**
+ * Language middleware — adds X-Lang header.
+ *
+ * Language is resolved lazily so language switches are reflected immediately.
+ * CRITICAL: does NOT send header when language=null (store not yet initialized)
+ * — without this, backend returns default language, React Query caches it,
+ *   and after setLanguage() the cache is stale.
+ *
+ * @example
+ * ```typescript
+ * import { languageMiddleware } from '@doswiftly/storefront-sdk';
+ *
+ * client.use(languageMiddleware(() => languageStore.getState().language));
+ * ```
+ */
+import { LANGUAGE_HEADER_NAME } from '../language/cookie-config';
+export function languageMiddleware(getLanguage) {
+    return (request, next) => {
+        const language = getLanguage();
+        if (language) {
+            request.headers[LANGUAGE_HEADER_NAME] = language;
+        }
+        return next(request);
+    };
+}

package/dist/react/bot-protection/bot-protection-context.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Bot protection React context.
+ *
+ * Provides access to the BotProtectionTokenProvider manager
+ * for the useBotProtection() escape hatch hook.
+ */
+import type { BotProtectionTokenProvider } from '../../core/middleware/bot-protection';
+export interface BotProtectionContextValue {
+    manager: BotProtectionTokenProvider | null;
+}
+export declare const BotProtectionContext: import("react").Context<BotProtectionContextValue | null>;
+//# sourceMappingURL=bot-protection-context.d.ts.map

package/dist/react/bot-protection/bot-protection-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot-protection-context.d.ts","sourceRoot":"","sources":["../../../src/react/bot-protection/bot-protection-context.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAEvF,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,0BAA0B,GAAG,IAAI,CAAC;CAC5C;AAED,eAAO,MAAM,oBAAoB,2DAAwD,CAAC"}

package/dist/react/bot-protection/bot-protection-context.js

@@ -0,0 +1,9 @@
+/**
+ * Bot protection React context.
+ *
+ * Provides access to the BotProtectionTokenProvider manager
+ * for the useBotProtection() escape hatch hook.
+ */
+'use client';
+import { createContext } from 'react';
+export const BotProtectionContext = createContext(null);

package/dist/react/bot-protection/bot-protection-widget.d.ts

@@ -0,0 +1,13 @@
+/**
+ * BotProtectionWidget — invisible React wrapper that mounts the bot protection manager.
+ *
+ * Renders a hidden div and mounts/unmounts the manager lifecycle.
+ * Triggers lazy script preload on mount.
+ */
+import type { BotProtectionTokenProvider } from '../../core/middleware/bot-protection';
+interface BotProtectionWidgetProps {
+    manager: BotProtectionTokenProvider | null;
+}
+export declare function BotProtectionWidget({ manager }: BotProtectionWidgetProps): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# sourceMappingURL=bot-protection-widget.d.ts.map

package/dist/react/bot-protection/bot-protection-widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot-protection-widget.d.ts","sourceRoot":"","sources":["../../../src/react/bot-protection/bot-protection-widget.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAGvF,UAAU,wBAAwB;IAChC,OAAO,EAAE,0BAA0B,GAAG,IAAI,CAAC;CAC5C;AAED,wBAAgB,mBAAmB,CAAC,EAAE,OAAO,EAAE,EAAE,wBAAwB,kDA4BxE"}

package/dist/react/bot-protection/bot-protection-widget.js

@@ -0,0 +1,34 @@
+/**
+ * BotProtectionWidget — invisible React wrapper that mounts the bot protection manager.
+ *
+ * Renders a hidden div and mounts/unmounts the manager lifecycle.
+ * Triggers lazy script preload on mount.
+ */
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from 'react';
+export function BotProtectionWidget({ manager }) {
+    const containerRef = useRef(null);
+    const mountedRef = useRef(false);
+    useEffect(() => {
+        if (!manager || !containerRef.current || mountedRef.current)
+            return;
+        mountedRef.current = true;
+        // Trigger lazy script preload + mount container
+        const mgr = manager;
+        if (typeof mgr.loadScript === 'function') {
+            mgr.loadScript().catch(() => {
+                // Script load failure is handled gracefully in execute()
+            });
+        }
+        if (typeof mgr.mount === 'function') {
+            mgr.mount(containerRef.current);
+        }
+        return () => {
+            mountedRef.current = false;
+        };
+    }, [manager]);
+    if (!manager)
+        return null;
+    return _jsx("div", { ref: containerRef, style: { display: 'none' }, "aria-hidden": "true" });
+}

package/dist/react/cookies.d.ts

@@ -10,11 +10,14 @@
 export declare function getCookie(name: string): string | null;
 /**
  * Set cookie (client-side only).
+ *
+ * `secure` defaults to auto-detect from `location.protocol` (true on HTTPS).
  */
 export declare function setCookie(name: string, value: string, options?: {
     maxAge?: number;
     path?: string;
     sameSite?: string;
+    secure?: boolean;
 }): void;
 /**
  * Delete cookie (client-side only).
@@ -25,4 +28,18 @@ export declare function deleteCookie(name: string, path?: string): void;
  * Falls back to document.cookie on client.
  */
 export declare function getCurrencyFromCookieAsync(): Promise<string | null>;
+/**
+ * Get cart ID from cookie (async — works with Next.js cookies()).
+ * Falls back to document.cookie on client.
+ *
+ * Use in Server Components for SSR cart badge:
+ * ```typescript
+ * const cartId = await getCartIdFromCookieAsync();
+ * if (cartId) {
+ *   const cart = await fetchCart(cartId);
+ *   // Render cart badge with real totalQuantity — no skeleton needed
+ * }
+ * ```
+ */
+export declare function getCartIdFromCookieAsync(): Promise<string | null>;
 //# sourceMappingURL=cookies.d.ts.map

package/dist/react/cookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/react/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrD;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,IAAI,CAIN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,IAAI,CAG3D;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYzE"}
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../../src/react/cookies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIrD;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACpF,IAAI,CAON;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,SAAM,GAAG,IAAI,CAG3D;AAKD;;;GAGG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYvE"}