@kasuvia/sdk 0.0.8 → 0.0.9

package/src/utils/checkout.ts

@@ -1,12 +1,24 @@
 import { buildFullName } from "./customer";
 import type { CheckoutCustomer, DeliveryAddress, Order, ShippingLocation } from "../types";
+import { ProductTypeEnum, type ProductType, type CartItem } from "../types/store";
 
 export function buildDeliveryAddress(customer: CheckoutCustomer, location: ShippingLocation): DeliveryAddress {
+    if (!customer.first_name || !customer.last_name || !customer.phone) {
+        throw new Error("Customer first_name, last_name, and phone are required for delivery address");
+    }
+    if (!location.street || !location.city || !location.state || !location.country) {
+        throw new Error("Location street, city, state, and country are required for delivery address");
+    }
     return {
         first_name: customer.first_name,
         last_name: customer.last_name,
         phone: customer.phone,
-        ...location,
+        street: location.street,
+        city: location.city,
+        state: location.state,
+        lga: location.lga,
+        country: location.country,
+        postal: location.postal,
     };
 }
 
@@ -20,20 +32,24 @@ export function enrichCompletedOrder(
         customer: CheckoutCustomer;
         location?: ShippingLocation;
         bespokeBrief?: string;
-        productType?: "physical" | "digital" | "bespoke" | null;
+        productType?: ProductType | null;
     },
 ): Order {
     const customerName = getCheckoutCustomerName(options.customer);
 
     return {
         ...order,
+        customer_name: order.customer_name || customerName,
+        customer_email: order.customer_email || options.customer.email,
         customerName: order.customerName || customerName,
         customerEmail: order.customerEmail || options.customer.email,
         shippingAddress:
             order.shippingAddress ??
-            (options.productType === "physical" && options.location
+            (options.productType === ProductTypeEnum.PHYSICAL && options.location
                 ? buildDeliveryAddress(options.customer, options.location)
                 : undefined),
+        bespoke_brief: order.bespoke_brief ?? options.bespokeBrief,
         bespokeBrief: order.bespokeBrief ?? options.bespokeBrief,
     };
 }
+

package/src/utils/cookieConsent.ts

@@ -0,0 +1,34 @@
+/**
+ * Cookie Consent Utilities
+ *
+ * Cookie consent state — read/written to localStorage only (per-browser, never
+ * sent to any server). "accepted" | "rejected" | null (no choice made yet).
+ *
+ * localStorage is intentionally used here: this is a GDPR/NDPR UI preference
+ * flag, not business data. It is never sent to the backend. The banner simply
+ * reappears on the next visit if localStorage is unavailable (private browsing).
+ */
+
+export type CookieConsentValue = "accepted" | "rejected" | null;
+
+const STORAGE_KEY = "kasuvia_cookie_consent";
+export const COOKIE_CONSENT_CHANGED_EVENT = "kasuvia:cookie-consent-changed";
+
+export function getCookieConsent(): CookieConsentValue {
+  try {
+    const value = window.localStorage.getItem(STORAGE_KEY);
+    return value === "accepted" || value === "rejected" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+export function setCookieConsent(value: "accepted" | "rejected"): void {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, value);
+    window.dispatchEvent(new Event(COOKIE_CONSENT_CHANGED_EVENT));
+  } catch {
+    // localStorage unavailable (private browsing, blocked site data) — the banner
+    // will just reappear next visit rather than crash; nothing else depends on this.
+  }
+}

package/src/utils/format.ts

@@ -0,0 +1,408 @@
+/**
+ * format.ts
+ * Comprehensive number formatting utility with multiple format styles.
+ * Migrated from kasuvia-storefront to kasuvia-sdk for shared use.
+ */
+
+export type FormatStyle =
+    | "compact"        // 1000000 → "1M"
+    | "compact-lower"  // 1000000 → "1m"
+    | "compact-full"   // 1000000 → "1 Million"
+    | "compact-full-lower" // 1000000 → "1 million"
+    | "currency"       // 1000000 → "$1,000,000.00"
+    | "currency-compact" // 1000000 → "$1M"
+    | "decimal"        // 1000000 → "1,000,000"
+    | "decimal-dot"    // 1000000 → "1.000.000"  (European style)
+    | "decimal-space"  // 1000000 → "1 000 000"  (French/SI style)
+    | "plain"          // 1000000 → "1000000"
+    | "scientific"     // 1000000 → "1.00e+6"
+    | "ordinal"        // 1 → "1st", 2 → "2nd", etc.
+    | "percent"        // 0.75 → "75%"
+    | "bytes"          // 1048576 → "1.00 MB"
+    | "roman";         // 14 → "XIV"
+
+export interface FormatOptions {
+    style?: FormatStyle;
+    /** Number of decimal places (where applicable). Default: auto */
+    decimals?: number;
+    /** Currency symbol for "currency" styles. Default: "$" */
+    currencySymbol?: string;
+    /** Locale for Intl-based formatting. Default: "en-US" */
+    locale?: string;
+    /** If true, always show + sign for positive numbers */
+    showSign?: boolean;
+}
+
+// ─── Thresholds ───────────────────────────────────────────────────────────────
+
+const COMPACT_THRESHOLDS = [
+    { value: 1e12, suffixUpper: "T", suffixLower: "t", full: "Trillion" },
+    { value: 1e9, suffixUpper: "B", suffixLower: "b", full: "Billion" },
+    { value: 1e6, suffixUpper: "M", suffixLower: "m", full: "Million" },
+    { value: 1e3, suffixUpper: "K", suffixLower: "k", full: "Thousand" },
+] as const;
+
+const BYTE_THRESHOLDS = [
+    { value: 1024 ** 5, label: "PB" },
+    { value: 1024 ** 4, label: "TB" },
+    { value: 1024 ** 3, label: "GB" },
+    { value: 1024 ** 2, label: "MB" },
+    { value: 1024 ** 1, label: "KB" },
+] as const;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function trimDecimals(value: number, decimals?: number): string {
+    if (decimals !== undefined) return value.toFixed(decimals);
+    // Auto: trim unnecessary trailing zeros
+    const fixed = value.toFixed(10);
+    return parseFloat(fixed).toString();
+}
+
+function autoDecimals(value: number, defaultDecimals: number, decimals?: number): string {
+    return (decimals !== undefined ? value.toFixed(decimals) : value.toFixed(defaultDecimals))
+        .replace(/\.?0+$/, "");
+}
+
+function applySign(str: string, num: number, showSign?: boolean): string {
+    if (showSign && num > 0) return `+${str}`;
+    return str;
+}
+
+// ─── Ordinal ──────────────────────────────────────────────────────────────────
+
+function toOrdinal(n: number): string {
+    const abs = Math.abs(Math.round(n));
+    const mod100 = abs % 100;
+    const mod10 = abs % 10;
+    if (mod100 >= 11 && mod100 <= 13) return `${abs}th`;
+    if (mod10 === 1) return `${abs}st`;
+    if (mod10 === 2) return `${abs}nd`;
+    if (mod10 === 3) return `${abs}rd`;
+    return `${abs}th`;
+}
+
+// ─── Roman Numerals ───────────────────────────────────────────────────────────
+
+function toRoman(n: number): string {
+    if (n <= 0 || n > 3999 || !Number.isInteger(n)) {
+        throw new RangeError("Roman numerals only support integers between 1 and 3999.");
+    }
+    const vals = [1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1];
+    const syms = ["M", "CM", "D", "CD", "C", "XC", "L", "XL", "X", "IX", "V", "IV", "I"];
+    let result = "";
+    let remaining = n;
+    for (let i = 0; i < vals.length; i++) {
+        while (remaining >= vals[i]) {
+            result += syms[i];
+            remaining -= vals[i];
+        }
+    }
+    return result;
+}
+
+// ─── Compact ─────────────────────────────────────────────────────────────────
+
+function formatCompact(
+    n: number,
+    suffixKey: "suffixUpper" | "suffixLower" | "full",
+    lowerFull: boolean,
+    decimals?: number,
+): string {
+    const abs = Math.abs(n);
+    for (const tier of COMPACT_THRESHOLDS) {
+        if (abs >= tier.value) {
+            const divided = n / tier.value;
+            const suffix = suffixKey === "full"
+                ? (lowerFull ? tier.full.toLowerCase() : tier.full)
+                : tier[suffixKey];
+            const spacer = suffixKey === "full" ? " " : "";
+            return `${autoDecimals(divided, 2, decimals)}${spacer}${suffix}`;
+        }
+    }
+    return trimDecimals(n, decimals ?? 0);
+}
+
+// ─── Decimal ─────────────────────────────────────────────────────────────────
+
+function formatDecimal(n: number, separator: string, decimalChar = ".", decimals?: number): string {
+    const fixed = decimals !== undefined ? Math.abs(n).toFixed(decimals) : Math.abs(n).toFixed(0);
+    const [intPart, decPart] = fixed.split(".");
+    const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, separator);
+    const sign = n < 0 ? "-" : "";
+    return decPart !== undefined ? `${sign}${grouped}${decimalChar}${decPart}` : `${sign}${grouped}`;
+}
+
+// ─── Bytes ────────────────────────────────────────────────────────────────────
+
+function formatBytes(n: number, decimals = 2): string {
+    if (n === 0) return "0 B";
+    const abs = Math.abs(n);
+    for (const tier of BYTE_THRESHOLDS) {
+        if (abs >= tier.value) {
+            return `${(n / tier.value).toFixed(decimals)} ${tier.label}`;
+        }
+    }
+    return `${n.toFixed(0)} B`;
+}
+
+// ─── Main Export ──────────────────────────────────────────────────────────────
+
+/**
+ * Format a number in a variety of styles.
+ *
+ * @example
+ * formatNumber(1_000_000)                          // "1M"
+ * formatNumber(1_000_000, { style: "compact-lower" }) // "1m"
+ * formatNumber(1_000_000, { style: "compact-full" })  // "1 Million"
+ * formatNumber(1_000_000, { style: "currency" })      // "$1,000,000.00"
+ * formatNumber(1_000_000, { style: "decimal" })       // "1,000,000"
+ * formatNumber(1_234_567.89, { style: "decimal-dot" }) // "1.234.567"
+ * formatNumber(0.754, { style: "percent" })           // "75.4%"
+ * formatNumber(1_048_576, { style: "bytes" })         // "1.00 MB"
+ * formatNumber(14, { style: "roman" })                // "XIV"
+ */
+export function formatNumber(value: number, options: FormatOptions = {}): string {
+    const {
+        style = "compact",
+        decimals,
+        currencySymbol = "$",
+        locale = "en-US",
+        showSign,
+    } = options;
+
+    if (!isFinite(value)) return String(value); // Handle Infinity / NaN
+
+    let result: string;
+
+    switch (style) {
+        case "compact":
+            result = formatCompact(value, "suffixUpper", false, decimals);
+            break;
+
+        case "compact-lower":
+            result = formatCompact(value, "suffixLower", false, decimals);
+            break;
+
+        case "compact-full":
+            result = formatCompact(value, "full", false, decimals);
+            break;
+
+        case "compact-full-lower":
+            result = formatCompact(value, "full", true, decimals);
+            break;
+
+        case "currency": {
+            const d = decimals ?? 2;
+            const formatted = formatDecimal(value, ",", ".", d);
+            result = `${currencySymbol}${formatted}`;
+            break;
+        }
+
+        case "currency-compact": {
+            const compact = formatCompact(Math.abs(value), "suffixUpper", false, decimals);
+            const sign = value < 0 ? "-" : "";
+            result = `${sign}${currencySymbol}${compact}`;
+            break;
+        }
+
+        case "decimal":
+            result = formatDecimal(value, ",", ".", decimals);
+            break;
+
+        case "decimal-dot":
+            result = formatDecimal(value, ".", ",", decimals);
+            break;
+
+        case "decimal-space":
+            result = formatDecimal(value, "\u00A0", ".", decimals); // non-breaking space
+            break;
+
+        case "plain":
+            result = decimals !== undefined ? value.toFixed(decimals) : String(value);
+            break;
+
+        case "scientific": {
+            const d = decimals ?? 2;
+            result = value.toExponential(d);
+            break;
+        }
+
+        case "ordinal":
+            return toOrdinal(value); // sign not applicable
+
+        case "percent": {
+            const d = decimals ?? 1;
+            result = `${(value * 100).toFixed(d).replace(/\.?0+$/, "")}%`;
+            break;
+        }
+
+        case "bytes":
+            result = formatBytes(value, decimals);
+            break;
+
+        case "roman":
+            return toRoman(Math.round(value)); // sign not applicable
+
+        default:
+            result = String(value);
+    }
+
+    return applySign(result, value, showSign);
+}
+
+// ─── Convenience wrappers ─────────────────────────────────────────────────────
+
+/** 1000000 → "1M" */
+export const compact = (n: number, decimals?: number) =>
+    formatNumber(n, { style: "compact", decimals });
+
+/** 1000000 → "1m" */
+export const compactLower = (n: number, decimals?: number) =>
+    formatNumber(n, { style: "compact-lower", decimals });
+
+/** 1000000 → "1 Million" */
+export const compactFull = (n: number, decimals?: number) =>
+    formatNumber(n, { style: "compact-full", decimals });
+
+/** 1000000 → "$1,000,000.00" */
+export const currencyFormat = (n: number, symbol = "$", decimals = 2) =>
+    formatNumber(n, { style: "currency", currencySymbol: symbol, decimals });
+
+/** 1000000 → "$1M" */
+export const currencyCompact = (n: number, symbol = "$") =>
+    formatNumber(n, { style: "currency-compact", currencySymbol: symbol });
+
+/** 1000000 → "1,000,000" */
+export const decimal = (n: number, decimals?: number) =>
+    formatNumber(n, { style: "decimal", decimals });
+
+/** 0.75 → "75%" */
+export const percent = (n: number, decimals?: number) =>
+    formatNumber(n, { style: "percent", decimals });
+
+/** 1048576 → "1.00 MB" */
+export const bytes = (n: number, decimals?: number) =>
+    formatNumber(n, { style: "bytes", decimals });
+
+/** 14 → "XIV" */
+export const roman = (n: number) => formatNumber(n, { style: "roman" });
+
+/** 1 → "1st", 2 → "2nd" */
+export const ordinal = (n: number) => formatNumber(n, { style: "ordinal" });
+
+// ─── Currency Formatting (Multi-Currency Support) ─────────────────────────────
+
+/**
+ * NOTE: Currency and language data should be fetched from KASUVIA_PAYMENT backend API
+ * using the useSupportedLanguages hook. Do not hardcode currency values here.
+ * Use the formatPrice, getCurrencySymbol, and formatCompactPrice functions with
+ * currency/locale parameters from the API response.
+ */
+
+/**
+ * Format a bare "HH:mm" / "HH:mm:ss" time string (no date component) as a
+ * human-readable 12-hour time, e.g. "14:30:00" -> "2:30 PM".
+ *
+ * Owner-flagged cleanup (2026-09-20): call sites needing this used to build
+ * a `new Date(\`1970-01-01T${time}\`)` just to borrow Date's own formatting
+ * — a hardcoded, arbitrary epoch date standing in for a value that was
+ * never actually a date. Pure string/number parsing instead — no Date
+ * object, no dependency on the JS engine's date-string parsing behavior for
+ * a value with no real date component at all.
+ */
+export function formatTimeString(time: string): string {
+    const [hoursStr, minutesStr] = time.split(":");
+    const hours = parseInt(hoursStr, 10);
+    if (isNaN(hours) || minutesStr === undefined) return time;
+    const period = hours >= 12 ? "PM" : "AM";
+    const displayHours = hours % 12 || 12;
+    return `${displayHours}:${minutesStr} ${period}`;
+}
+
+/**
+ * Format a price amount with currency symbol and proper decimal places.
+ * Uses Intl.NumberFormat for accurate currency formatting.
+ *
+ * REAL BUG FIXED (2026-09-20): a missing/omitted `currency` used to
+ * silently default to "USD" — displaying a real price with a fabricated,
+ * likely WRONG currency (most Kasuvia businesses price in NGN or another
+ * non-USD currency) instead of flagging that the caller never passed the
+ * real one. Confirmed this is the actual reachable `formatPrice` (exported
+ * via utils/index.ts + src/index.ts) that ~26 call sites across
+ * kasuvia-storefront call — most of them WITHOUT a currency argument at
+ * all, meaning every one of those was silently mislabeling real prices as
+ * USD. Prefer `useAppContext().formatPrice` in storefront components — it
+ * reads the actual business currency from real config; this stateless
+ * function should only be used where a real currency is already in hand.
+ *
+ * @param amount - The amount to format (null/undefined returns '')
+ * @param currency - ISO 4217 currency code (e.g., USD, NGN, EUR). Required —
+ *   there is no default; a missing value returns an explicit "N/A" marker
+ *   rather than guessing.
+ * @param locale - Locale string for formatting (default: en-US)
+ * @returns Formatted currency string
+ */
+export function formatPrice(
+    amount: number | null | undefined,
+    currency: string | null | undefined,
+    locale: string = "en-US",
+): string {
+    if (amount == null || isNaN(amount)) return "";
+    if (!currency) return `N/A ${amount.toLocaleString()}`;
+    const code = currency.toUpperCase();
+    try {
+        return new Intl.NumberFormat(locale, {
+            style: "currency",
+            currency: code,
+            minimumFractionDigits: 0,
+            maximumFractionDigits: 2,
+        }).format(amount);
+    } catch {
+        return `${code} ${amount.toLocaleString()}`;
+    }
+}
+
+/**
+ * Get the currency symbol for a given currency code.
+ *
+ * REAL BUG FIXED (2026-09-20): a missing `currency` used to silently
+ * default to "USD" (same class of bug as formatPrice above) — required now,
+ * no default.
+ *
+ * @param currency - ISO 4217 currency code
+ * @param locale - Locale string (default: en-US)
+ * @returns Currency symbol (e.g., $, ₦, €)
+ */
+export function getCurrencySymbol(currency: string, locale: string = "en-US"): string {
+    const formatter = new Intl.NumberFormat(locale, {
+        style: "currency",
+        currency: currency,
+    });
+    const parts = formatter.formatToParts(0);
+    const symbolPart = parts.find(part => part.type === "currency");
+    return symbolPart?.value || currency;
+}
+
+/**
+ * Format a price in compact notation (e.g., $1M, ₦250K).
+ *
+ * REAL BUG FIXED (2026-09-20): a missing `currency` used to silently
+ * default to "USD" (same class of bug as formatPrice above) — required now,
+ * no default; a missing value returns an explicit "N/A" marker.
+ *
+ * @param amount - The amount to format
+ * @param currency - ISO 4217 currency code (e.g., USD, NGN, EUR)
+ * @param locale - Locale string for formatting (default: en-US)
+ * @returns Formatted compact currency string
+ */
+export function formatCompactPrice(
+    amount: number,
+    currency: string | null | undefined,
+    locale: string = "en-US",
+): string {
+    if (!currency) return `N/A ${formatNumber(amount, { style: "compact", decimals: 0 })}`;
+    const symbol = getCurrencySymbol(currency, locale);
+    const compactStr = formatNumber(amount, { style: "compact", decimals: 0 });
+    return `${symbol}${compactStr}`;
+}

package/src/utils/geolocation.ts

@@ -0,0 +1,134 @@
+/**
+ * Geolocation Helpers
+ *
+ * Helper functions for handling geolocation data including:
+ * - Map pin-drop coordinate handling
+ * - Plus Code input handling
+ * - Reverse geocoding integration via SDK logistics service
+ * - Applying an AddressAutocomplete suggestion onto ShippingLocation state
+ */
+
+import type { SdkConfig } from "../config";
+import { reverseGeocode, decodePlusCode } from "../services/logistics.service";
+import type { CoordinateSource, ShippingLocation } from "../types";
+import type { AddressSuggestion } from "../components/shared/AddressAutocomplete";
+import { logger } from "./logger";
+
+type AddressUpdater = (updater: ShippingLocation | ((prev: ShippingLocation) => ShippingLocation)) => void;
+
+export async function handlePinDrop(
+  coords: { latitude: number; longitude: number },
+  setAddress: AddressUpdater,
+  setIsReverseGeocoding?: (loading: boolean) => void,
+  config?: SdkConfig
+): Promise<void> {
+  setAddress((prev: ShippingLocation) => ({
+    ...prev,
+    latitude: coords.latitude,
+    longitude: coords.longitude,
+    coordinate_source: "pin_drop" as CoordinateSource,
+  }));
+
+  if (setIsReverseGeocoding) {
+    setIsReverseGeocoding(true);
+    try {
+      if (config) {
+        const data = await reverseGeocode(config, {
+          latitude: coords.latitude,
+          longitude: coords.longitude,
+        });
+
+        setAddress((prev: ShippingLocation) => ({
+          ...prev,
+          city: data.city || prev.city,
+          state: data.state || prev.state,
+          country: data.country_code || prev.country,
+        }));
+      } else {
+        logger.warn("[GeolocationHelper] SdkConfig is required to perform reverse geocoding.");
+      }
+    } catch (error) {
+      logger.error("[GeolocationHelper] Reverse geocoding failed:", error);
+    } finally {
+      setIsReverseGeocoding(false);
+    }
+  }
+}
+
+export async function handlePlusCodeChange(
+  plusCode: string,
+  setAddress: AddressUpdater,
+  config?: SdkConfig
+): Promise<void> {
+  setAddress((prev: ShippingLocation) => ({
+    ...prev,
+    plus_code: plusCode,
+  }));
+
+  if (plusCode) {
+    setAddress((prev: ShippingLocation) => ({
+      ...prev,
+      plus_code: plusCode,
+      coordinate_source: "plus_code" as CoordinateSource,
+    }));
+
+    try {
+      if (config) {
+        const data = await decodePlusCode(config, { plus_code: plusCode });
+        setAddress((prev: ShippingLocation) => ({
+          ...prev,
+          latitude: data.latitude,
+          longitude: data.longitude,
+        }));
+      } else {
+        logger.warn("[GeolocationHelper] SdkConfig is required to decode Plus Code.");
+      }
+    } catch (error) {
+      logger.error("[GeolocationHelper] Plus Code decoding failed:", error);
+    }
+  } else {
+    setAddress((prev: ShippingLocation) => ({
+      ...prev,
+      plus_code: "",
+      coordinate_source: undefined,
+    }));
+  }
+}
+
+/**
+ * Applies a picked AddressAutocomplete suggestion onto ShippingLocation
+ * state in one place, so a caller wiring the shared component doesn't have
+ * to hand-map its fields itself. Only overwrites a field the suggestion
+ * actually returned a value for - never blanks out something the customer
+ * had already filled in manually that this particular result happens to
+ * lack (e.g. a suggestion with no postal_code shouldn't erase one already
+ * typed). `coordinate_source` is set to "manual" (the closest of the
+ * backend's 3 fixed values - `pin_drop`/`plus_code`/`manual`, strictly
+ * validated server-side, see kasuvia-store-management's
+ * schemas/logistics.py) only when the suggestion actually carried real
+ * coordinates - an autocomplete pick is a distinct real source from either
+ * of the two interactive geolocation tools, and there is no 4th backend
+ * value for it.
+ */
+export function applyAddressSuggestion(
+  suggestion: AddressSuggestion,
+  setAddress: AddressUpdater
+): void {
+  setAddress((prev: ShippingLocation) => ({
+    ...prev,
+    street: suggestion.line1 || prev.street,
+    city: suggestion.city || prev.city,
+    state: suggestion.state || prev.state,
+    postal: suggestion.postal_code || prev.postal,
+    country: suggestion.country || prev.country,
+    latitude: suggestion.latitude ?? prev.latitude,
+    longitude: suggestion.longitude ?? prev.longitude,
+    coordinate_source:
+      suggestion.latitude != null && suggestion.longitude != null
+        ? ("manual" as CoordinateSource)
+        : prev.coordinate_source,
+  }));
+}
+
+
+

package/src/utils/graphql-url.ts

@@ -0,0 +1,47 @@
+import { GraphQLClient } from 'graphql-request'
+import type { SdkConfig } from '../config'
+
+/**
+ * REAL BUG FIXED (2026-09-21), live-reproduced in the browser console:
+ * `graphql-request`'s `GraphQLClient` constructs a `new URL(endpoint)`
+ * internally when issuing a request. Client-side SDK config deliberately
+ * uses a same-origin relative path (`/api/proxy/store`) so the real backend
+ * host is never exposed to the browser — but the native `URL` constructor
+ * throws `TypeError: Failed to construct 'URL': Invalid URL` for a relative
+ * string with no base, which is exactly what broke every client-side
+ * GraphQL call (products, collections, wishlist): `Failed to fetch
+ * products`/`Failed to fetch collections` in ProductsListing.tsx.
+ *
+ * Server-side config already uses an absolute real-backend URL, so this is
+ * a no-op there — only the browser case (a relative path, `window` defined)
+ * needs the current origin prepended.
+ */
+export function resolveGraphQLEndpoint(url: string): string {
+  if (typeof window === 'undefined') return url
+  try {
+    // Absolute already (real backend URL, e.g. in a server-rendered client bundle edge case) — leave as-is.
+    new URL(url)
+    return url
+  } catch {
+    return `${window.location.origin}${url}`
+  }
+}
+
+/**
+ * REAL DUPLICATION FIXED (2026-09-22): this exact function (same headers,
+ * same endpoint resolution) was hand-copied identically into
+ * product.service.ts, collection.service.ts, and wishlist.service.ts — the
+ * SDK's three GraphQL-backed services. One shared implementation now.
+ */
+export function createGraphQLClient(config: SdkConfig, accessToken?: string): GraphQLClient {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'Accept': 'application/json',
+    'X-Storefront-Key': config.storefrontApiKey,
+    'X-Business-ID': config.businessId,
+  }
+  if (accessToken) {
+    headers['Authorization'] = `Bearer ${accessToken}`
+  }
+  return new GraphQLClient(resolveGraphQLEndpoint(`${config.backendUrls.store}/graphql`), { headers })
+}