@doswiftly/storefront-sdk 21.0.1 → 22.1.0

package/dist/core/index.d.ts

@@ -41,6 +41,7 @@ export { authMiddleware } from './middleware/auth';
 export { cartSecretMiddleware, serverCartSecretMiddleware, CART_SECRET_HEADER, } from './middleware/cart-secret';
 export { currencyMiddleware } from './middleware/currency';
 export { languageMiddleware } from './middleware/language';
+export { forwardedIpMiddleware, forwardedIpSignedMessage, FORWARDED_IP_HEADER, FORWARDED_IP_TS_HEADER, FORWARDED_IP_SIG_HEADER, type ForwardedIpMiddlewareOptions, } from './middleware/forwarded-ip';
 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';
@@ -67,6 +68,7 @@ export { AUTH_COOKIE_NAME, AUTH_COOKIE_DEFAULTS, type AuthCookieConfig, REFRESH_
 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, parseCartCookieValue, formatCartCookieValue, type CartCredentials, } from './cart/cookie-config';
+export { REFERRAL_COOKIE_NAME, REFERRAL_COOKIE_MAX_AGE, REFERRAL_CODE_MAX_LENGTH, REFERRAL_CODE_PATTERN, extractReferralCodeFromUrl, } from './referral/cookie-config';
 export { matchesRoute, type RouteProtectionConfig } from './auth/routes';
 export { createSetTokenHandler, createClearTokenHandler, createWhoamiHandler, originAllowlistValidator, trustedForwardedHostValidator, } from './auth/handlers';
 export type { OriginValidator, OriginValidatorContext } from './auth/handlers';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}

package/dist/core/index.js

@@ -43,6 +43,7 @@ export { authMiddleware } from './middleware/auth';
 export { cartSecretMiddleware, serverCartSecretMiddleware, CART_SECRET_HEADER, } from './middleware/cart-secret';
 export { currencyMiddleware } from './middleware/currency';
 export { languageMiddleware } from './middleware/language';
+export { forwardedIpMiddleware, forwardedIpSignedMessage, FORWARDED_IP_HEADER, FORWARDED_IP_TS_HEADER, FORWARDED_IP_SIG_HEADER, } from './middleware/forwarded-ip';
 export { botProtectionMiddleware, BOT_PROTECTION_HEADER, } from './middleware/bot-protection';
 export { retryMiddleware } from './middleware/retry';
 export { timeoutMiddleware } from './middleware/timeout';
@@ -84,6 +85,8 @@ export { LANGUAGE_COOKIE_NAME, LANGUAGE_COOKIE_MAX_AGE, LANGUAGE_HEADER_NAME } f
 export { CURRENCY_COOKIE_NAME, CURRENCY_COOKIE_MAX_AGE, CURRENCY_HEADER_NAME } from './currency/cookie-config';
 // Cart cookie config + composite value parser/formatter (`<cartId>.<secret>`)
 export { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE, parseCartCookieValue, formatCartCookieValue, } from './cart/cookie-config';
+// Referral cookie config + URL extractor (loyalty referral program capture)
+export { REFERRAL_COOKIE_NAME, REFERRAL_COOKIE_MAX_AGE, REFERRAL_CODE_MAX_LENGTH, REFERRAL_CODE_PATTERN, extractReferralCodeFromUrl, } from './referral/cookie-config';
 // Auth route matching
 export { matchesRoute } from './auth/routes';
 // Auth cookie handlers (API route factories)

package/dist/core/middleware/forwarded-ip.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Forwarded-IP middleware — lets a SERVER-SIDE (BFF) storefront forward the real
+ * buyer IP to the backend, so per-buyer rate limiting works even though the
+ * backend's connection comes from the storefront server, not the browser.
+ *
+ * Why this exists: when a storefront renders/fetches on the server (server
+ * components, route handlers, server actions), the backend sees ONE source IP —
+ * the storefront server's — for every buyer. Per-IP limits then collapse onto
+ * that single address. This middleware carries the buyer's real IP (read from the
+ * incoming request, e.g. the `cf-connecting-ip` header) in a signed header the
+ * backend can trust.
+ *
+ * Trust model: the header is signed with HMAC-SHA256 over `${ip}.${ts}.${shopSlug}`
+ * using a shared platform secret. The backend recomputes the signature and only
+ * trusts the IP when it matches and the timestamp is fresh. Binding the shop slug
+ * stops a signature from one shop being replayed against another; the timestamp
+ * bounds replay. A spoofed header without a valid signature is ignored by the
+ * backend (it falls back to the connection IP).
+ *
+ * SERVER-ONLY: the secret must never reach the browser. Use this middleware only
+ * in server-side clients (`getStorefrontClient`), never in the browser pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { forwardedIpMiddleware } from '@doswiftly/storefront-sdk';
+ *
+ * // `buyerIp` comes from your server framework's incoming request — typically the
+ * // `cf-connecting-ip` request header. `serverSecret` is a server-only env value.
+ * getStorefrontClient({
+ *   apiUrl,
+ *   shopSlug,
+ *   middleware: [
+ *     forwardedIpMiddleware({
+ *       getBuyerIp: () => buyerIp,
+ *       getSecret: () => serverSecret,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+import type { Middleware } from '../client/types';
+/** Header carrying the buyer's real IP, forwarded by a server-side storefront. */
+export declare const FORWARDED_IP_HEADER = "x-doswiftly-buyer-ip";
+/** Header carrying the signature timestamp (unix milliseconds) — bounds replay. */
+export declare const FORWARDED_IP_TS_HEADER = "x-doswiftly-fwd-ts";
+/** Header carrying the hex HMAC-SHA256 signature over `${ip}.${ts}.${shopSlug}`. */
+export declare const FORWARDED_IP_SIG_HEADER = "x-doswiftly-fwd-sig";
+/**
+ * Canonical signed message. The backend MUST build this identically before
+ * verifying the signature. Order and separators are load-bearing.
+ */
+export declare function forwardedIpSignedMessage(ip: string, timestamp: string, shopSlug: string): string;
+/** A getter that may be sync or async (e.g. `async () => (await headers()).get('cf-connecting-ip')`). */
+type MaybeAsyncGetter = () => string | null | undefined | Promise<string | null | undefined>;
+export interface ForwardedIpMiddlewareOptions {
+    /** Real buyer IP from the incoming request (e.g. the `cf-connecting-ip` header). */
+    getBuyerIp: MaybeAsyncGetter;
+    /** Shared platform secret used to sign. Server-side only — never expose to the browser. */
+    getSecret: MaybeAsyncGetter;
+    /**
+     * OPTIONAL override for the shop slug bound into the signature. Defaults to the
+     * `X-Shop-Slug` header the client already sends — so you normally don't pass it,
+     * and the signed slug is guaranteed to match what the backend verifies. Provide
+     * only for non-standard transports that don't set that header.
+     */
+    getShopSlug?: MaybeAsyncGetter;
+    /** Clock source (unix milliseconds). Injectable for tests; defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Server-side forwarded-IP middleware. On every request it reads the buyer IP,
+ * shop slug and secret (lazy getters — a rotated secret is picked up without
+ * rebuilding the pipeline), signs `${ip}.${ts}.${shopSlug}` with HMAC-SHA256 and
+ * adds the three forwarded-IP headers. When any input is missing it adds nothing
+ * — the backend then keys the connection IP (the server-side default).
+ *
+ * The HMAC key is imported once per distinct secret value and reused across
+ * requests (re-imported only on rotation).
+ */
+export declare function forwardedIpMiddleware(options: ForwardedIpMiddlewareOptions): Middleware;
+export {};
+//# sourceMappingURL=forwarded-ip.d.ts.map

package/dist/core/middleware/forwarded-ip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwarded-ip.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/forwarded-ip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAElD,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAC1D,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,uBAAuB,CAAC;AAC3D,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,wBAAwB,CAAC;AAQ7D;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEhG;AAED,yGAAyG;AACzG,KAAK,gBAAgB,GAAG,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAE7F,MAAM,WAAW,4BAA4B;IAC3C,oFAAoF;IACpF,UAAU,EAAE,gBAAgB,CAAC;IAC7B,2FAA2F;IAC3F,SAAS,EAAE,gBAAgB,CAAC;IAC5B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAeD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,UAAU,CAiCvF"}

package/dist/core/middleware/forwarded-ip.js

@@ -0,0 +1,109 @@
+/**
+ * Forwarded-IP middleware — lets a SERVER-SIDE (BFF) storefront forward the real
+ * buyer IP to the backend, so per-buyer rate limiting works even though the
+ * backend's connection comes from the storefront server, not the browser.
+ *
+ * Why this exists: when a storefront renders/fetches on the server (server
+ * components, route handlers, server actions), the backend sees ONE source IP —
+ * the storefront server's — for every buyer. Per-IP limits then collapse onto
+ * that single address. This middleware carries the buyer's real IP (read from the
+ * incoming request, e.g. the `cf-connecting-ip` header) in a signed header the
+ * backend can trust.
+ *
+ * Trust model: the header is signed with HMAC-SHA256 over `${ip}.${ts}.${shopSlug}`
+ * using a shared platform secret. The backend recomputes the signature and only
+ * trusts the IP when it matches and the timestamp is fresh. Binding the shop slug
+ * stops a signature from one shop being replayed against another; the timestamp
+ * bounds replay. A spoofed header without a valid signature is ignored by the
+ * backend (it falls back to the connection IP).
+ *
+ * SERVER-ONLY: the secret must never reach the browser. Use this middleware only
+ * in server-side clients (`getStorefrontClient`), never in the browser pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { forwardedIpMiddleware } from '@doswiftly/storefront-sdk';
+ *
+ * // `buyerIp` comes from your server framework's incoming request — typically the
+ * // `cf-connecting-ip` request header. `serverSecret` is a server-only env value.
+ * getStorefrontClient({
+ *   apiUrl,
+ *   shopSlug,
+ *   middleware: [
+ *     forwardedIpMiddleware({
+ *       getBuyerIp: () => buyerIp,
+ *       getSecret: () => serverSecret,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+/** Header carrying the buyer's real IP, forwarded by a server-side storefront. */
+export const FORWARDED_IP_HEADER = 'x-doswiftly-buyer-ip';
+/** Header carrying the signature timestamp (unix milliseconds) — bounds replay. */
+export const FORWARDED_IP_TS_HEADER = 'x-doswiftly-fwd-ts';
+/** Header carrying the hex HMAC-SHA256 signature over `${ip}.${ts}.${shopSlug}`. */
+export const FORWARDED_IP_SIG_HEADER = 'x-doswiftly-fwd-sig';
+/**
+ * Shop routing header the client already attaches to every request (see
+ * `create-client.ts`). The signature binds to THIS slug by default, so the signed
+ * value always matches what the backend verifies from the same header.
+ */
+const SHOP_SLUG_HEADER = 'X-Shop-Slug';
+/**
+ * Canonical signed message. The backend MUST build this identically before
+ * verifying the signature. Order and separators are load-bearing.
+ */
+export function forwardedIpSignedMessage(ip, timestamp, shopSlug) {
+    return `${ip}.${timestamp}.${shopSlug}`;
+}
+async function importHmacKey(secret) {
+    return crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, [
+        'sign',
+    ]);
+}
+async function signHex(key, message) {
+    const signature = await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(message));
+    return Array.from(new Uint8Array(signature))
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+}
+/**
+ * Server-side forwarded-IP middleware. On every request it reads the buyer IP,
+ * shop slug and secret (lazy getters — a rotated secret is picked up without
+ * rebuilding the pipeline), signs `${ip}.${ts}.${shopSlug}` with HMAC-SHA256 and
+ * adds the three forwarded-IP headers. When any input is missing it adds nothing
+ * — the backend then keys the connection IP (the server-side default).
+ *
+ * The HMAC key is imported once per distinct secret value and reused across
+ * requests (re-imported only on rotation).
+ */
+export function forwardedIpMiddleware(options) {
+    const { getBuyerIp, getShopSlug, getSecret, now = () => Date.now() } = options;
+    let cachedSecret = null;
+    let cachedKey = null;
+    return async (request, next) => {
+        // Getters may be async (e.g. reading the IP from `headers()` per request);
+        // `await` resolves sync values unchanged, so sync getters keep working.
+        const ip = await getBuyerIp();
+        // Slug defaults to the routing header the client already sends — so it always
+        // matches what the backend verifies. The optional getter only overrides it.
+        const shopSlug = (await getShopSlug?.()) ?? request.headers[SHOP_SLUG_HEADER];
+        const secret = await getSecret();
+        // Forward only when everything needed for a trusted, shop-bound signature is
+        // present. Missing any piece -> send nothing (backend falls back to conn IP).
+        if (ip && shopSlug && secret) {
+            const timestamp = String(now());
+            if (cachedSecret !== secret || cachedKey === null) {
+                cachedSecret = secret;
+                cachedKey = importHmacKey(secret);
+            }
+            const key = await cachedKey;
+            const signature = await signHex(key, forwardedIpSignedMessage(ip, timestamp, shopSlug));
+            request.headers[FORWARDED_IP_HEADER] = ip;
+            request.headers[FORWARDED_IP_TS_HEADER] = timestamp;
+            request.headers[FORWARDED_IP_SIG_HEADER] = signature;
+        }
+        return next(request);
+    };
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Referral cookie configuration — platform contract.
+ *
+ * When a visitor lands on the storefront through a referral link
+ * (`https://shop.example/register?ref=REF-AB12CD34`), the code must survive
+ * navigation until the visitor actually signs up — possibly minutes or days
+ * later. The SDK persists it in a readable first-party cookie and the signup
+ * form passes it to `customerSignup(input: { referralCode })`.
+ *
+ * Used by:
+ * - `captureReferralCode` / `useReferralCapture` (client-side capture on landing)
+ * - `readReferralCodeCookie` (client + server readers at signup time)
+ */
+export declare const REFERRAL_COOKIE_NAME = "referral-code";
+/**
+ * Default cookie lifetime: 30 days.
+ *
+ * This is the "landing → signup" window only. It is intentionally NOT tied to
+ * the shop's referral validity setting (days the referred customer has to
+ * place their first order) — that window starts at signup and is validated
+ * exclusively by the backend. Coupling the two would be wrong: a shop giving
+ * referred customers 7 days to order would silently lose visitors who sign up
+ * 8 days after clicking the link. Override per call via
+ * `captureReferralCode({ maxAge })` if you need a different capture window.
+ */
+export declare const REFERRAL_COOKIE_MAX_AGE: number;
+/**
+ * Maximum accepted code length — longer values are ignored as garbage.
+ * Mirrors the `customerSignup` input contract (the API rejects longer codes).
+ */
+export declare const REFERRAL_CODE_MAX_LENGTH = 50;
+/**
+ * Accepted code shape: letters, digits and dashes (codes are case-insensitive —
+ * the API uppercases on lookup). Mirrors the platform referral-code charset;
+ * a non-conforming value is never persisted to the cookie, because the API
+ * would silently ignore it at signup anyway — storing it for 30 days would
+ * just carry dead weight (or someone's injection attempt) around. Widen this
+ * pattern only together with the `customerSignup.referralCode` API contract.
+ */
+export declare const REFERRAL_CODE_PATTERN: RegExp;
+/**
+ * Extract a referral code from a URL or a search string.
+ *
+ * Accepts a full or relative URL (`https://shop.example/register?ref=CODE`,
+ * `/register?ref=CODE`), a search string starting with `?` (`?ref=CODE`) or a
+ * `URL` instance. Returns the trimmed code, or `null` when the parameter is
+ * absent, empty, longer than {@link REFERRAL_CODE_MAX_LENGTH} or outside
+ * {@link REFERRAL_CODE_PATTERN} (such values would be ignored by the API
+ * anyway, so they are never persisted).
+ *
+ * @param input - URL, `URL` instance or `?`-prefixed search string to inspect.
+ * @param paramName - Query parameter carrying the code (default `'ref'` —
+ *   matches the share links generated by the platform).
+ */
+export declare function extractReferralCodeFromUrl(input: string | URL, paramName?: string): string | null;
+//# sourceMappingURL=cookie-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cookie-config.d.ts","sourceRoot":"","sources":["../../../src/core/referral/cookie-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,oBAAoB,kBAAkB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AAEzD;;;GAGG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAoB,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,SAAS,SAAQ,GAAG,MAAM,GAAG,IAAI,CAyBhG"}

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

@@ -0,0 +1,83 @@
+/**
+ * Referral cookie configuration — platform contract.
+ *
+ * When a visitor lands on the storefront through a referral link
+ * (`https://shop.example/register?ref=REF-AB12CD34`), the code must survive
+ * navigation until the visitor actually signs up — possibly minutes or days
+ * later. The SDK persists it in a readable first-party cookie and the signup
+ * form passes it to `customerSignup(input: { referralCode })`.
+ *
+ * Used by:
+ * - `captureReferralCode` / `useReferralCapture` (client-side capture on landing)
+ * - `readReferralCodeCookie` (client + server readers at signup time)
+ */
+export const REFERRAL_COOKIE_NAME = 'referral-code';
+/**
+ * Default cookie lifetime: 30 days.
+ *
+ * This is the "landing → signup" window only. It is intentionally NOT tied to
+ * the shop's referral validity setting (days the referred customer has to
+ * place their first order) — that window starts at signup and is validated
+ * exclusively by the backend. Coupling the two would be wrong: a shop giving
+ * referred customers 7 days to order would silently lose visitors who sign up
+ * 8 days after clicking the link. Override per call via
+ * `captureReferralCode({ maxAge })` if you need a different capture window.
+ */
+export const REFERRAL_COOKIE_MAX_AGE = 30 * 24 * 60 * 60; // 30 days
+/**
+ * Maximum accepted code length — longer values are ignored as garbage.
+ * Mirrors the `customerSignup` input contract (the API rejects longer codes).
+ */
+export const REFERRAL_CODE_MAX_LENGTH = 50;
+/**
+ * Accepted code shape: letters, digits and dashes (codes are case-insensitive —
+ * the API uppercases on lookup). Mirrors the platform referral-code charset;
+ * a non-conforming value is never persisted to the cookie, because the API
+ * would silently ignore it at signup anyway — storing it for 30 days would
+ * just carry dead weight (or someone's injection attempt) around. Widen this
+ * pattern only together with the `customerSignup.referralCode` API contract.
+ */
+export const REFERRAL_CODE_PATTERN = /^[A-Za-z0-9-]+$/;
+/**
+ * Extract a referral code from a URL or a search string.
+ *
+ * Accepts a full or relative URL (`https://shop.example/register?ref=CODE`,
+ * `/register?ref=CODE`), a search string starting with `?` (`?ref=CODE`) or a
+ * `URL` instance. Returns the trimmed code, or `null` when the parameter is
+ * absent, empty, longer than {@link REFERRAL_CODE_MAX_LENGTH} or outside
+ * {@link REFERRAL_CODE_PATTERN} (such values would be ignored by the API
+ * anyway, so they are never persisted).
+ *
+ * @param input - URL, `URL` instance or `?`-prefixed search string to inspect.
+ * @param paramName - Query parameter carrying the code (default `'ref'` —
+ *   matches the share links generated by the platform).
+ */
+export function extractReferralCodeFromUrl(input, paramName = 'ref') {
+    let params;
+    if (input instanceof URL) {
+        params = input.searchParams;
+    }
+    else {
+        const raw = input.trim();
+        if (!raw)
+            return null;
+        if (raw.startsWith('?')) {
+            // Search-string form: "?ref=CODE&utm_source=x"
+            params = new URLSearchParams(raw.slice(1));
+        }
+        else {
+            // Full or relative URL — the base argument makes relative paths
+            // ("/register?ref=CODE") parse too.
+            try {
+                params = new URL(raw, 'http://localhost').searchParams;
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    const value = params.get(paramName)?.trim() ?? '';
+    if (!value || value.length > REFERRAL_CODE_MAX_LENGTH || !REFERRAL_CODE_PATTERN.test(value))
+        return null;
+    return value;
+}

package/dist/react/hooks/use-referral-capture.d.ts

@@ -0,0 +1,9 @@
+import { type CaptureReferralCodeOptions } from '../referral';
+export interface UseReferralCaptureOptions extends Pick<CaptureReferralCodeOptions, 'paramName' | 'maxAge'> {
+}
+/**
+ * Capture the referral code from the current URL into the `referral-code`
+ * cookie and return the active code (`null` when none).
+ */
+export declare function useReferralCapture(options?: UseReferralCaptureOptions): string | null;
+//# sourceMappingURL=use-referral-capture.d.ts.map

package/dist/react/hooks/use-referral-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-referral-capture.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-referral-capture.ts"],"names":[],"mappings":"AA4BA,OAAO,EAAuB,KAAK,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEnF,MAAM,WAAW,yBACf,SAAQ,IAAI,CAAC,0BAA0B,EAAE,WAAW,GAAG,QAAQ,CAAC;CAAG;AAErE;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,yBAAyB,GAAG,MAAM,GAAG,IAAI,CAWrF"}

package/dist/react/hooks/use-referral-capture.js

@@ -0,0 +1,40 @@
+'use client';
+/**
+ * useReferralCapture — capture a referral code from the landing URL.
+ *
+ * Mount the hook once near the top of the app (layout or a dedicated client
+ * component). On mount it inspects the current URL for the referral parameter
+ * (`?ref=CODE` by default), persists it in the `referral-code` cookie and
+ * returns the active code (from the URL, or a previously stored one when the
+ * visitor navigated away from the landing URL before signing up).
+ *
+ * At signup time read the code with `readReferralCodeCookie()` (or use the
+ * value returned here), pass it as `customerSignup(input: { referralCode })`
+ * and call `clearReferralCodeCookie()` after success.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ * import { useReferralCapture } from '@doswiftly/storefront-sdk/react';
+ *
+ * export function ReferralCapture() {
+ *   useReferralCapture();
+ *   return null;
+ * }
+ * ```
+ */
+import { useEffect, useState } from 'react';
+import { captureReferralCode } from '../referral';
+/**
+ * Capture the referral code from the current URL into the `referral-code`
+ * cookie and return the active code (`null` when none).
+ */
+export function useReferralCapture(options) {
+    const [code, setCode] = useState(null);
+    const paramName = options?.paramName;
+    const maxAge = options?.maxAge;
+    useEffect(() => {
+        setCode(captureReferralCode({ paramName, maxAge }));
+    }, [paramName, maxAge]);
+    return code;
+}

package/dist/react/index.d.ts

@@ -37,6 +37,8 @@ export type { ShopConfig } from './types/shop-config';
 export { selectCurrency, selectBaseCurrency, selectSupportedCurrencies, selectIsLoaded } from './stores/currency.store';
 export { selectLanguage, selectDefaultLanguage, selectSupportedLanguages, selectLanguageIsLoaded } from './stores/language.store';
 export { getCookie, setCookie, deleteCookie, createBrowserCartCookieStore, } from './cookies';
+export { captureReferralCode, getReferralCodeCookie, clearReferralCodeCookie, type CaptureReferralCodeOptions, } from './referral';
+export { useReferralCapture, type UseReferralCaptureOptions } from './hooks/use-referral-capture';
 export { useBotProtection } from './hooks/use-bot-protection';
 export { useHydrated } from './hooks/use-hydrated';
 export { useDebouncedValue } from './hooks/use-debounced-value';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}

package/dist/react/index.js

@@ -36,8 +36,12 @@ export { useLanguageStore, useLanguageStoreApi } from './stores/store-context';
 export { selectCurrency, selectBaseCurrency, selectSupportedCurrencies, selectIsLoaded } from './stores/currency.store';
 export { selectLanguage, selectDefaultLanguage, selectSupportedLanguages, selectLanguageIsLoaded } from './stores/language.store';
 // Cookie utilities (client-side). Server-side readers (readCartIdCookie,
-// readCurrencyCookie) live in `@doswiftly/storefront-sdk/react/server`.
+// readCurrencyCookie, readReferralCodeCookie) live in
+// `@doswiftly/storefront-sdk/react/server`.
 export { getCookie, setCookie, deleteCookie, createBrowserCartCookieStore, } from './cookies';
+// Referral capture (loyalty referral program — landing-link `?ref=CODE` → cookie)
+export { captureReferralCode, getReferralCodeCookie, clearReferralCodeCookie, } from './referral';
+export { useReferralCapture } from './hooks/use-referral-capture';
 // Bot protection
 export { useBotProtection } from './hooks/use-bot-protection';
 // Generic hooks

package/dist/react/referral.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Client-side referral capture helpers.
+ *
+ * Flow: a visitor lands through a referral share link (`/register?ref=CODE`),
+ * `captureReferralCode()` persists the code in the readable `referral-code`
+ * cookie, and the signup form reads it back with `getReferralCodeCookie()`
+ * and passes it as `customerSignup(input: { referralCode })`. After a
+ * successful signup call `clearReferralCodeCookie()` so the code is not
+ * re-submitted by other browser tabs or future registrations.
+ *
+ * All helpers are SSR-safe (no-op / `null` without a `document`). For Server
+ * Components use the async `readReferralCodeCookie` from
+ * `@doswiftly/storefront-sdk/react/server` instead — the client helper is
+ * deliberately named differently (`get…`, synchronous) so the two cannot be
+ * confused in auto-imports.
+ */
+export interface CaptureReferralCodeOptions {
+    /**
+     * URL (or search string) to inspect. Defaults to the current
+     * `window.location.href`.
+     */
+    url?: string | URL;
+    /** Query parameter carrying the code. Default `'ref'`. */
+    paramName?: string;
+    /**
+     * Cookie lifetime in seconds. Default {@link REFERRAL_COOKIE_MAX_AGE}
+     * (30 days) — the "landing → signup" window, independent of the shop's
+     * referral validity setting (see the constant's docs).
+     */
+    maxAge?: number;
+}
+/**
+ * Capture a referral code from the current URL (or an explicit one) into the
+ * `referral-code` cookie.
+ *
+ * Returns the captured code, or the previously stored one when the URL carries
+ * no code (so a visitor who navigated away from the landing URL still counts),
+ * or `null` when there is nothing to capture. A code present in the URL always
+ * wins over a previously stored one — the most recent referral link decides.
+ */
+export declare function captureReferralCode(options?: CaptureReferralCodeOptions): string | null;
+/**
+ * Read the stored referral code (client-side, synchronous). Returns `null`
+ * when absent or outside a browser environment. Server Components use the
+ * async `readReferralCodeCookie` from `@doswiftly/storefront-sdk/react/server`.
+ */
+export declare function getReferralCodeCookie(): string | null;
+/**
+ * Remove the stored referral code. Call after a successful signup so the code
+ * is not re-submitted by future registrations from the same browser.
+ */
+export declare function clearReferralCodeCookie(): void;
+//# sourceMappingURL=referral.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"referral.d.ts","sourceRoot":"","sources":["../../src/react/referral.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AASH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IACnB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,MAAM,GAAG,IAAI,CAU3F;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,GAAG,IAAI,CAErD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/react/referral.js

@@ -0,0 +1,51 @@
+/**
+ * Client-side referral capture helpers.
+ *
+ * Flow: a visitor lands through a referral share link (`/register?ref=CODE`),
+ * `captureReferralCode()` persists the code in the readable `referral-code`
+ * cookie, and the signup form reads it back with `getReferralCodeCookie()`
+ * and passes it as `customerSignup(input: { referralCode })`. After a
+ * successful signup call `clearReferralCodeCookie()` so the code is not
+ * re-submitted by other browser tabs or future registrations.
+ *
+ * All helpers are SSR-safe (no-op / `null` without a `document`). For Server
+ * Components use the async `readReferralCodeCookie` from
+ * `@doswiftly/storefront-sdk/react/server` instead — the client helper is
+ * deliberately named differently (`get…`, synchronous) so the two cannot be
+ * confused in auto-imports.
+ */
+import { REFERRAL_COOKIE_NAME, REFERRAL_COOKIE_MAX_AGE, extractReferralCodeFromUrl, } from '../core/referral/cookie-config';
+import { getCookie, setCookie, deleteCookie } from './cookies';
+/**
+ * Capture a referral code from the current URL (or an explicit one) into the
+ * `referral-code` cookie.
+ *
+ * Returns the captured code, or the previously stored one when the URL carries
+ * no code (so a visitor who navigated away from the landing URL still counts),
+ * or `null` when there is nothing to capture. A code present in the URL always
+ * wins over a previously stored one — the most recent referral link decides.
+ */
+export function captureReferralCode(options = {}) {
+    const url = options.url ?? (typeof window !== 'undefined' ? window.location.href : null);
+    const fromUrl = url ? extractReferralCodeFromUrl(url, options.paramName) : null;
+    if (fromUrl) {
+        setCookie(REFERRAL_COOKIE_NAME, fromUrl, { maxAge: options.maxAge ?? REFERRAL_COOKIE_MAX_AGE });
+        return fromUrl;
+    }
+    return getReferralCodeCookie();
+}
+/**
+ * Read the stored referral code (client-side, synchronous). Returns `null`
+ * when absent or outside a browser environment. Server Components use the
+ * async `readReferralCodeCookie` from `@doswiftly/storefront-sdk/react/server`.
+ */
+export function getReferralCodeCookie() {
+    return getCookie(REFERRAL_COOKIE_NAME);
+}
+/**
+ * Remove the stored referral code. Call after a successful signup so the code
+ * is not re-submitted by future registrations from the same browser.
+ */
+export function clearReferralCodeCookie() {
+    deleteCookie(REFERRAL_COOKIE_NAME);
+}

package/dist/react/server/cookie-readers.d.ts

@@ -46,4 +46,11 @@ export declare function readCartIdCookie(): Promise<string | null>;
 export declare function readCartCredentials(): Promise<CartCredentials | null>;
 /** Read the first-party `preferred-currency` cookie (server-first, client fallback). */
 export declare function readCurrencyCookie(): Promise<string | null>;
+/**
+ * Read the first-party `referral-code` cookie (server-first, client fallback) —
+ * the referral code captured when the visitor landed through a referral share
+ * link. Useful for SSR-rendered signup forms that pre-fill the code field;
+ * pass it as `customerSignup(input: { referralCode })`.
+ */
+export declare function readReferralCodeCookie(): Promise<string | null>;
 //# sourceMappingURL=cookie-readers.d.ts.map

package/dist/react/server/cookie-readers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookie-readers.d.ts","sourceRoot":"","sources":["../../../src/react/server/cookie-readers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AAqBvC,6EAA6E;AAC7E,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAE3E;AAED,wFAAwF;AACxF,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEjE"}
+{"version":3,"file":"cookie-readers.d.ts","sourceRoot":"","sources":["../../../src/react/server/cookie-readers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AAsBvC,6EAA6E;AAC7E,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAE/D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAE3E;AAED,wFAAwF;AACxF,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEjE;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAErE"}