@doswiftly/storefront-sdk 21.0.1 → 22.0.0

package/dist/core/index.d.ts

@@ -67,6 +67,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

@@ -84,6 +84,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/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"}

package/dist/react/server/cookie-readers.js

@@ -24,6 +24,7 @@
  */
 import { CART_COOKIE_NAME, parseCartCookieValue, } from '../../core/cart/cookie-config';
 import { CURRENCY_COOKIE_NAME } from '../../core/currency/cookie-config';
+import { REFERRAL_COOKIE_NAME } from '../../core/referral/cookie-config';
 import { getCookie } from '../cookies';
 /**
  * Read a cookie server-first: the request cookies via `next/headers` in a Server
@@ -71,3 +72,12 @@ export async function readCartCredentials() {
 export async function readCurrencyCookie() {
     return readCookieIsomorphic(CURRENCY_COOKIE_NAME);
 }
+/**
+ * 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 async function readReferralCodeCookie() {
+    return readCookieIsomorphic(REFERRAL_COOKIE_NAME);
+}

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

@@ -1,7 +1,7 @@
 export { getStorefrontClient, type ServerClientOptions } from './get-storefront-client';
 export { createStorefrontAuthRoute, type StorefrontAuthRouteOptions, type StorefrontAuthRouteHandlers, } from './create-storefront-auth-route';
 export { getInitialAuth, type InitialAuth } from './get-initial-auth';
-export { readCartIdCookie, readCartCredentials, readCurrencyCookie } from './cookie-readers';
+export { readCartIdCookie, readCartCredentials, readCurrencyCookie, readReferralCodeCookie } from './cookie-readers';
 export { serverCartSecretMiddleware } from '../../core/middleware/cart-secret';
 export { trustedForwardedHostValidator, originAllowlistValidator, type OriginValidator, type OriginValidatorContext, } from '../../core/auth/handlers';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGxF,OAAO,EACL,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,GACjC,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAI7F,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAG/E,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGxF,OAAO,EACL,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,2BAA2B,GACjC,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAIrH,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AAG/E,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,EACxB,KAAK,eAAe,EACpB,KAAK,sBAAsB,GAC5B,MAAM,0BAA0B,CAAC"}

package/dist/react/server/index.js

@@ -3,8 +3,8 @@ export { getStorefrontClient } from './get-storefront-client';
 export { createStorefrontAuthRoute, } from './create-storefront-auth-route';
 // Server-only cold-start auth seed from the first-party cookies.
 export { getInitialAuth } from './get-initial-auth';
-// Server-first readers for the readable first-party cookies (cart-id, currency).
-export { readCartIdCookie, readCartCredentials, readCurrencyCookie } from './cookie-readers';
+// Server-first readers for the readable first-party cookies (cart-id, currency, referral).
+export { readCartIdCookie, readCartCredentials, readCurrencyCookie, readReferralCodeCookie } from './cookie-readers';
 // Server cart-secret middleware — prepend to `getStorefrontClient({ middleware })`
 // with `await readCartCredentials()` so SSR / edge cart reads carry the secret.
 export { serverCartSecretMiddleware } from '../../core/middleware/cart-secret';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "21.0.1",
+  "version": "22.0.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "sideEffects": false,