@doswiftly/storefront-sdk 15.1.0 → 16.0.0

package/CHANGELOG.md

@@ -1,5 +1,244 @@
 # Changelog
 
+## 16.0.0
+
+### Major Changes
+
+- ca67b92: **BREAKING** — the formatting utilities switch from a hardcoded 13-currency map to runtime-driven `Intl.NumberFormat` resolution. Every ISO 4217 currency known to the runtime is now supported, with the locale-correct symbol and separators.
+
+  **API changes**
+  - `formatDate(date, locale)` — `locale` is now a required argument. The previous hardcoded `'en-US'` default is gone.
+  - `formatDateTime(date, locale)` — `locale` required.
+  - `formatNumber(num, locale)` — `locale` required.
+  - `formatPrice(price, locale?)` — `locale` is now optional. When omitted, the runtime default (`Intl.NumberFormat().resolvedOptions().locale`) is used. The previous `CURRENCY_LOCALES`-keyed auto-selection is gone.
+  - `formatAmount(amount, currencyCode, locale?)` — third argument added (optional).
+  - `formatPriceRange(min, max, locale?)` — third argument added (optional).
+  - `getCurrencySymbol(code, locale?)` — second argument added (optional). The symbol is derived from `Intl.NumberFormat.formatToParts()`; output depends on the locale (`getCurrencySymbol('PLN', 'pl-PL') === 'zł'`, `getCurrencySymbol('PLN', 'en-US') === 'PLN'`).
+
+  **Removed exports**
+  - `CURRENCY_SYMBOLS` — the 13-entry map is gone. Use `getCurrencySymbol(code, locale)` instead, or read the symbol from `Intl.NumberFormat.formatToParts()` directly.
+  - `CURRENCY_LOCALES` — the locale-to-currency map is gone. Pick the locale from the storefront's i18n context (or read `shop.localeToCurrencyMap` from the API for per-shop overrides) and pass it to `formatPrice` / `formatAmount`.
+
+  **Why**
+  - The hardcoded 13-currency map covered ~7% of the ISO 4217 currencies the API now ships in `CurrencyCode` (~180 entries). Every currency outside that list silently fell back to `en-US` formatting — a Brazilian (BRL) or Indian (INR) storefront had to either write its own formatter or accept US-style output.
+  - Locale↔currency is a **per-shop** decision (`shop.localeToCurrencyMap` in the schema is explicitly marked SSOT). A globally-hardcoded map in the SDK is the wrong place for that knowledge — it makes Polish customers of a multi-locale shop unable to see PLN in `'en-PL'` even when the merchant configured it.
+  - Money precision: `formatPrice` and `formatAmount` no longer apply `parseFloat` to `Money.amount`. Decimal strings are forwarded to `Intl.NumberFormat.format()` verbatim, preserving precision across locales and unusual subunit currencies (JPY/KRW zero-decimal, BHD/JOD/KWD three-decimal, ISK rounding).
+
+  **Migration**
+
+  ```ts
+  // Before
+  import {
+    formatDate,
+    formatPrice,
+    CURRENCY_LOCALES,
+    CURRENCY_SYMBOLS,
+  } from "@doswiftly/storefront-sdk";
+
+  formatDate(order.createdAt); // hardcoded "Dec 9, 2025"
+  formatPrice({ amount: "12.50", currencyCode: "PLN" }); // auto-picked pl-PL → "12,50 zł"
+  CURRENCY_LOCALES.PLN; // "pl-PL"
+  CURRENCY_SYMBOLS.PLN; // "zł"
+
+  // After (Client Components)
+  import { useLocale } from "next-intl";
+  import {
+    formatDate,
+    formatPrice,
+    getCurrencySymbol,
+  } from "@doswiftly/storefront-sdk";
+
+  const locale = useLocale(); // e.g. "pl-PL"
+  formatDate(order.createdAt, locale);
+  formatPrice({ amount: "12.50", currencyCode: "PLN" }, locale);
+  getCurrencySymbol("PLN", locale); // "zł"
+
+  // After (Server Components / Route Handlers)
+  import { getLocale } from "next-intl/server";
+  const locale = await getLocale();
+  formatDate(order.createdAt, locale);
+  ```
+
+  For per-shop locale↔currency overrides, read `shop.localeToCurrencyMap` from the Storefront API and resolve the locale yourself before calling `formatPrice` / `formatAmount`.
+
+  **New: Context-driven format hooks**
+
+  `@doswiftly/storefront-sdk/react` now ships convenience hooks that pull the active language from `useLanguageStore` (inside `<StorefrontProvider>`) and return a memoised, locale-bound formatter. Use them when you don't want to pass `locale` to every call:
+
+  ```ts
+  import {
+    useFormatPrice,
+    useFormatAmount,
+    useFormatPriceRange,
+    useFormatDate,
+    useFormatDateTime,
+    useFormatNumber,
+    useGetCurrencySymbol,
+  } from '@doswiftly/storefront-sdk/react';
+
+  function Cart() {
+    const formatPrice = useFormatPrice();
+    return <span>{formatPrice(item.price)}</span>;
+  }
+
+  function OrderRow() {
+    const formatDate = useFormatDate();
+    return <span>{formatDate(order.processedAt)}</span>;
+  }
+  ```
+
+  Each hook accepts an optional last `localeOverride` argument that wins over the store value — useful for a "show in US format" toggle on a single element:
+
+  ```ts
+  const formatPrice = useFormatPrice();
+  return <span>{formatPrice(item.price, 'en-US')}</span>;
+  ```
+
+  Resolution per call: `localeOverride` → `useLanguageStore().language` → runtime default.
+
+  Use the vanilla `formatPrice` / `formatDate` / etc. from `@doswiftly/storefront-sdk` (no hook) with an explicit `locale` for server components, e-mail templates, or any code path outside a provider.
+
+  `formatPercentage` is unchanged.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — no operations changes.
+
+### Minor Changes
+
+- 885c011: Re-export checkout types from the public API. `CartClient` methods added in 15.1.0 (`getAvailablePaymentMethods`, `getAvailableShippingMethods`) returned typed payloads, but the named types were not part of the public surface — component props and function signatures touching these payloads required `Awaited<ReturnType<...>>` workarounds. This change closes that gap.
+
+  **Newly exported types:**
+  - `PaymentMethod`, `AvailablePaymentMethods` — shape returned by `CartClient.getAvailablePaymentMethods()`
+  - `AvailableShippingMethod`, `AvailableShippingMethodsPayload`, `FreeShippingProgress`, `DeliveryEstimate`, `ShippingCarrier`, `DeliveryType` — shape returned by `CartClient.getAvailableShippingMethods()`
+  - `PickupPoint`, `PickupPointInput` — locker / pickup-point delivery (surfaced via `MailingAddress.pickupPoint` and `CartAddressInput.pickupPoint`)
+  - `CartAttributeInput` — input shape for `CartClient.updateAttributes()`
+  - `ShippingAddressInput` — input shape for the `availableShippingMethods` standalone query
+
+  **Example:**
+
+  ```ts
+  import type {
+    AvailableShippingMethodsPayload,
+    AvailableShippingMethod,
+    DeliveryType,
+  } from "@doswiftly/storefront-sdk";
+
+  function isPickup(method: AvailableShippingMethod): boolean {
+    return method.deliveryType === "PICKUP_POINT";
+  }
+  ```
+
+  No runtime changes — types already existed internally; this change only adds them to the published surface.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — no operations changes.
+
+- fd3d199: Expose `cart.cost.totalDiscount` and `cart.cost.totalShipping` through the `CartCost` fragment.
+
+  The schema already exposed `CartCost.totalDiscount: Money!` (aggregate of every entry in `cart.discountAllocations`) and `CartCost.totalShipping: Money` (cost of the currently selected shipping method, `null` until one is selected), but the shared `CartCost` fragment did not select them — so they were not part of the typed `Cart.cost` returned by `CartClient`. Storefronts wanting to render a single "Discounts: -X" row or a shipping summary had to either sum `discountAllocations` client-side (precision-sensitive across currencies) or query the schema directly and bypass the typed surface.
+
+  After this release, both fields are part of `Cart.cost` returned by every `CartClient` operation — `get`, `create`, `addItems`, `updateItems`, `removeItems`, `setShippingAddress`, `setBillingAddress`, `selectShippingMethod`, `selectPaymentMethod`, `updateBuyerIdentity`, `updateDiscountCodes`, `updateNote`, `updateAttributes`, `applyGiftCard`, `removeGiftCard`, `updateGiftCardRecipient`.
+
+  **Example:**
+
+  ```ts
+  const cart = await cartClient.get(cartId);
+
+  const summary = {
+    subtotal: cart.cost.subtotal,
+    discount: cart.cost.totalDiscount, // Money — defaults to amount 0
+    shipping: cart.cost.totalShipping, // Money | null — null until selectShippingMethod()
+    tax: cart.cost.totalTax,
+    total: cart.cost.total, // grand total — use directly on checkout summary
+  };
+  ```
+
+  `totalDiscount` is required (defaults to amount 0 when no discount applies). `totalShipping` is nullable — `null` means no shipping method has been selected yet, an amount of 0 means a free-shipping method was selected.
+
+  Additive — existing consumers keep every field they had before, no breaking change.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity (fragment update).
+
+- 51091df: Expose `Cart.status` and `Cart.completedOrder` so storefronts can detect a completed (or expired / abandoned) cart on read, without having to attempt a mutation first and react to its `userErrors[].code`.
+
+  **New fields**
+  - `Cart.status: CartStatus!` — lifecycle status (`ACTIVE`, `ABANDONED`, `CONVERTED`, `RECOVERED`, `EXPIRED`). Only `ACTIVE` carts accept mutations; any other status rejects subsequent mutations with `CartErrorCode.ALREADY_COMPLETED`.
+  - `Cart.completedOrder: Order` — the order this cart converted into. Populated only when `status === CONVERTED`; null on every other status.
+
+  **Why**
+
+  When a buyer returned to the checkout page after completing their order (SSR re-render, deep link, "back" button after redirect), the SDK could only ask `cart(id)` for the cart and got the full pre-completion state back — every form value still there, the "Pay" button still active. The first mutation then failed with `ALREADY_COMPLETED`, after the buyer had already filled out fields. With `status` exposed, the storefront detects the terminal state on initial render and redirects to the order confirmation directly — using the `accessToken` on `completedOrder` for guest tracking, no extra `orderByToken` round-trip.
+
+  **Example**
+
+  ```ts
+  const cart = await cartClient.get(cartId);
+  if (!cart) {
+    // Cart not found — guide the buyer to create a new one
+    return redirect("/cart");
+  }
+  if (cart.status !== "ACTIVE") {
+    if (cart.completedOrder) {
+      // Render the order confirmation page off the data you already have
+      return redirect(`/order/${cart.completedOrder.accessToken}`);
+    }
+    // Abandoned / expired — start a fresh cart
+    return redirect("/cart/new");
+  }
+  // Render the checkout form normally
+  ```
+
+  Additive — every existing query that selects the shared `Cart` fragment now sees the two new fields automatically. No breaking change.
+
+  `@doswiftly/storefront-operations` bumped to keep linked parity — schema sync delivers the new fields and the `CartStatus` enum.
+
+### Patch Changes
+
+- 7ce8ac4: Clarify how `apiUrl` and `shopSlug` are configured.
+
+  `createStorefrontClient` and `<StorefrontProvider>` take `apiUrl` and `shopSlug` as **explicit `config`** — the SDK does not read environment variables, sniff hostnames, or inspect request headers. The storefront supplies the values; the SDK uses them verbatim.
+
+  Scaffolded storefronts ship a config helper (`lib/graphql/config.ts`) that resolves the two values from these sources, in order:
+  1. `doswiftly.config.ts` (preferred — committed file generated at `doswiftly init`)
+  2. `NEXT_PUBLIC_API_URL` + `NEXT_PUBLIC_SHOP_SLUG` (fallback, used for local development)
+  3. `http://localhost:8000` + `demo-shop` (defaults — smoke test only)
+
+  Scratch-built storefronts can skip the helper and pass values into `config={}` directly.
+
+  **What's new**
+  - `@doswiftly/storefront-sdk` README: new `## Configuration` section between `## Installation` and `## Quick Start`. Documents the explicit-config requirement, the three-source resolver shipped with scaffolded storefronts, and when env-var wiring actually matters.
+  - `@doswiftly/storefront-operations` `AGENTS.md`: new `### Configuration sources` convention inside `## Critical conventions — DO NOT hallucinate`. AI assistants now prefer `doswiftly.config.ts` and only fall back to the canonical env-var names.
+
+  Documentation only — no code change.
+
+- f4efab9: Add `ShopConfigFields` fragment + `query ShopConfig` for `<StorefrontProvider>` setup.
+
+  `<StorefrontProvider shopData={...}>` from `@doswiftly/storefront-sdk/react` expects a `ShopConfig` payload with a specific shape: currency setup (including `localeToCurrencyMap`), language setup, and bot protection. Until now the storefront had to hand-write the field selection, and it was easy to miss `localeToCurrencyMap` (used internally by the SDK for browser-locale-based currency detection) or to add an extra field that didn't match the `ShopConfig` interface.
+
+  **New**
+  - `fragment ShopConfigFields on Shop` — minimal selection that matches the `ShopConfig` interface 1:1.
+  - `query ShopConfig { shop { ...ShopConfigFields } }` — ready-to-use query for the provider.
+
+  **Example**
+
+  ```ts
+  const SHOP_CONFIG_QUERY = /* GraphQL */ `
+    query ShopConfig {
+      shop {
+        ...ShopConfigFields
+      }
+    }
+  `;
+
+  // In a Server Component:
+  const { data } = await execute(SHOP_CONFIG_QUERY);
+  return <StorefrontProvider shopData={data.shop}>{children}</StorefrontProvider>;
+  ```
+
+  Use the larger `Shop` fragment + `query Shop` when you also need branding / contact / business hours for your UI; use `ShopConfig` when you only need to bootstrap the provider.
+
+  Additive — no breaking change.
+
+  `@doswiftly/storefront-sdk` bumped to keep linked parity — no code change.
+
 ## 15.1.0
 
 ### Minor Changes

package/README.md

@@ -24,6 +24,34 @@ Layered runtime SDK for DoSwiftly Commerce storefronts. Framework-agnostic core
 pnpm add @doswiftly/storefront-sdk
 ```
 
+## Configuration
+
+`createStorefrontClient` and `<StorefrontProvider>` take `apiUrl` and `shopSlug` as **explicit `config`** — the SDK does not read environment variables, sniff hostnames, or inspect request headers. The storefront supplies the values; the SDK uses them verbatim.
+
+Scaffolded storefronts (`doswiftly init`) ship a `graphqlConfig` helper (`lib/graphql/config.ts`) that resolves both values from three sources in order:
+
+| Source | When | What it gives you |
+| --- | --- | --- |
+| **`doswiftly.config.ts`** (preferred) | `doswiftly init` storefronts | A committed config file with both values. No env wiring needed in normal use. |
+| `NEXT_PUBLIC_API_URL` + `NEXT_PUBLIC_SHOP_SLUG` (fallback) | Local development; storefronts scaffolded outside `doswiftly init` | Standard Next.js public env vars. `doswiftly dev` rewrites `NEXT_PUBLIC_API_URL` to a local CORS proxy at runtime so client-side calls don't hit production CORS headers. |
+| `http://localhost:8000` + `demo-shop` (defaults) | Empty smoke test | Last-resort placeholders so the project boots before any config is written. |
+
+If you go the env-var route, use **exactly these names** — `doswiftly dev` keys off them when overriding. Inventing `API_URL`, `STOREFRONT_URL`, or `TENANT_SLUG` means the dev proxy starts, but your storefront still calls the production API directly and you only learn about it on the first client-side mutation (build and SSR pass silently).
+
+```ts
+// app/layout.tsx — Next.js App Router, template-generated wiring
+import { graphqlConfig } from '@/lib/graphql/config';
+
+<StorefrontProvider
+  config={{ apiUrl: graphqlConfig.apiUrl, shopSlug: graphqlConfig.shopSlug }}
+  shopData={shopData}
+>
+  {children}
+</StorefrontProvider>
+```
+
+Scratch-built storefronts can read `process.env.NEXT_PUBLIC_*` directly and pass the values into `config={}` — the resolution helper is a convenience, not a requirement.
+
 ## Quick Start
 
 ### Core (framework-agnostic)

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

@@ -93,7 +93,7 @@ export type PaymentSession = PaymentSessionFragment;
 export type DiscountValidationResult = CartValidateDiscountCodeQuery['cartValidateDiscountCode'];
 export type DiscountInfo = NonNullable<DiscountValidationResult['discount']>;
 export type DiscountValidationError = NonNullable<DiscountValidationResult['error']>;
-export type { CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput, CartAttributeInput, CartCompleteInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartSelectPaymentMethodInput, CartSelectShippingMethodInput, CartSetBillingAddressInput, CartSetShippingAddressInput, CartUpdateGiftCardRecipientInput, PaymentCreateInput, ShippingAddressInput, DeliveryType, AttributeSelectionInput as CartAttributeSelectionInput, PaymentMethodType, PaymentInitiationFlow, DiscountApplicationType, DiscountErrorCode, CurrencyCode, CountryCode, LanguageCode, ProductTypeEnum, WeightUnit, CartWarningCode, AttributeType, AttributeFillingMode, AttributeBillingMode, AttributeOptionSurchargeType, StorefrontOrderStatus, OrderPaymentStatus, OrderFulfillmentStatus, } from '../generated/operation-types';
+export type { CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAddressInput, CartAttributeInput, CartCompleteInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartSelectPaymentMethodInput, CartSelectShippingMethodInput, CartSetBillingAddressInput, CartSetShippingAddressInput, CartUpdateGiftCardRecipientInput, PaymentCreateInput, ShippingAddressInput, PickupPointInput, DeliveryType, DeliveryEstimate, ShippingCarrier, FreeShippingProgress, PickupPoint, AttributeSelectionInput as CartAttributeSelectionInput, PaymentMethodType, PaymentInitiationFlow, DiscountApplicationType, DiscountErrorCode, CurrencyCode, CountryCode, LanguageCode, ProductTypeEnum, WeightUnit, CartWarningCode, AttributeType, AttributeFillingMode, AttributeBillingMode, AttributeOptionSurchargeType, StorefrontOrderStatus, OrderPaymentStatus, OrderFulfillmentStatus, } from '../generated/operation-types';
 /**
  * Machine-readable error code surfaced when `createPayment` fails. The call
  * throws a `StorefrontError` on `userErrors` — read `.userErrors[0].code` off

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/cart/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EACV,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,aAAa,EACb,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,yBAAyB,EACzB,wBAAwB,EACxB,8BAA8B,EAC9B,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,iCAAiC,EACjC,aAAa,EACb,sBAAsB,EACtB,6BAA6B,EAC7B,+BAA+B,EAC/B,+BAA+B,EAC/B,qBAAqB,EACrB,iBAAiB,EACjB,+BAA+B,IAAI,qCAAqC,EACzE,MAAM,8BAA8B,CAAC;AAMtC,MAAM,MAAM,KAAK,GAAG,aAAa,CAAC;AAClC,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AACpD,MAAM,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AACxC,MAAM,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AACxC,MAAM,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AACpD,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB,GAAG,WAAW,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC;AACjF,MAAM,MAAM,kBAAkB,GAAG,0BAA0B,CAAC;AAC5D,MAAM,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AACxC,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;AACvD,MAAM,MAAM,iBAAiB,GAAG,yBAAyB,CAAC;AAC1D,MAAM,MAAM,gBAAgB,GAAG,wBAAwB,CAAC;AACxD,MAAM,MAAM,sBAAsB,GAAG,8BAA8B,CAAC;AACpE,MAAM,MAAM,IAAI,GAAG,YAAY,CAAC;AAChC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,mBAAmB,CAAC;AAC9C,wFAAwF;AACxF,MAAM,MAAM,kBAAkB,GAAG,0BAA0B,CAAC;AAC5D,oFAAoF;AACpF,MAAM,MAAM,mBAAmB,GAAG,2BAA2B,CAAC;AAC9D,kEAAkE;AAClE,MAAM,MAAM,yBAAyB,GAAG,iCAAiC,CAAC;AAC1E;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,qBAAqB,CAAC;AAClD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,+BAA+B,CAAC;AACtE;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,+BAA+B,CAAC;AACtE;;;;;;;;GAQG;AACH,MAAM,MAAM,+BAA+B,GAAG,qCAAqC,CAAC;AACpF;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,iBAAiB,CAAC;AAC1C;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,aAAa,CAAC;AAClC;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAMpD,gFAAgF;AAChF,MAAM,MAAM,wBAAwB,GAAG,6BAA6B,CAAC,0BAA0B,CAAC,CAAC;AACjG,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,wBAAwB,CAAC,UAAU,CAAC,CAAC,CAAC;AAC7E,MAAM,MAAM,uBAAuB,GAAG,WAAW,CAAC,wBAAwB,CAAC,OAAO,CAAC,CAAC,CAAC;AAMrF,YAAY,EACV,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,6BAA6B,EAC7B,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EAEZ,uBAAuB,IAAI,2BAA2B,EAEtD,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,eAAe,EACf,UAAU,EACV,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,8BAA8B,CAAC;AAMtC;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,oBAAoB,GACpB,mBAAmB,GACnB,iCAAiC,GACjC,oBAAoB,GACpB,mBAAmB,GACnB,gBAAgB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/cart/types.ts"],"names":[],"mappings":"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"}

package/dist/core/format.d.ts

@@ -3,90 +3,125 @@
  *
  * Pure functions for formatting prices, dates, numbers.
  * 0 runtime dependencies — works in Node.js, Edge, Deno, Bun.
+ *
+ * Locale handling:
+ * - Every formatter takes an optional `locale: string` argument. When omitted,
+ *   the runtime default (`Intl.NumberFormat().resolvedOptions().locale`) is
+ *   used — in browsers this resolves from `navigator.language`, in Node from
+ *   `LANG` / system settings.
+ * - For deterministic output (typical in a storefront with explicit i18n) the
+ *   caller should pass `locale` explicitly (`useLocale()` in Client Components,
+ *   `getLocale()` in Server Components, `next-intl`).
+ * - For per-shop locale↔currency overrides (e.g. PLN displayed in `'en-PL'`
+ *   for an English-speaking customer of a Polish shop), the storefront reads
+ *   `shop.localeToCurrencyMap` from the API and passes the chosen locale.
+ *
+ * Money precision:
+ * - `Money.amount` is a string (Decimal scalar) — values are forwarded to
+ *   `Intl.NumberFormat.format()` verbatim, without `parseFloat`. This preserves
+ *   decimal precision exactly as returned by the GraphQL API, including
+ *   currencies with non-2-digit subunits (JPY/KRW, BHD/JOD, ISK, etc.).
+ *
+ * Symbol resolution:
+ * - `getCurrencySymbol(code, locale?)` derives the symbol via
+ *   `Intl.NumberFormat.formatToParts()`. The SDK no longer ships a hardcoded
+ *   subset of currencies — every ISO 4217 currency known to the runtime is
+ *   supported, with the locale-correct symbol (`'zł'` in pl-PL, `'PLN'` in
+ *   en-US, `'€'` in de-DE, etc.).
  */
+declare global {
+    namespace Intl {
+        interface NumberFormat {
+            format(value: string): string;
+        }
+    }
+}
 export interface PriceMoney {
     amount: string;
     currencyCode: string;
 }
-/** Currency symbols mapping */
-export declare const CURRENCY_SYMBOLS: Record<string, string>;
-/** Currency locale mapping for proper formatting */
-export declare const CURRENCY_LOCALES: Record<string, string>;
 /**
- * Get currency symbol
+ * Get the currency symbol for an ISO 4217 code in the requested locale. Derived
+ * from `Intl.NumberFormat.formatToParts()` — every currency known to the
+ * runtime is supported, with the locale-correct symbol.
+ *
+ * @example
+ * getCurrencySymbol('PLN', 'pl-PL')  // => "zł"
+ * getCurrencySymbol('PLN', 'en-US')  // => "PLN" (en-US has no narrow symbol for PLN)
+ * getCurrencySymbol('EUR', 'de-DE')  // => "€"
+ * getCurrencySymbol('USD')           // depends on the runtime locale
  */
-export declare function getCurrencySymbol(code: string): string;
+export declare function getCurrencySymbol(code: string, locale?: string): string;
 /**
- * Format price with currency symbol
+ * Format a `Money` value in the requested locale. `amount` is passed to
+ * `Intl.NumberFormat` as a string — no `parseFloat`, so decimal precision is
+ * preserved exactly as returned by the GraphQL API.
  *
  * @example
- * ```typescript
- * formatPrice({ amount: "99.99", currencyCode: "USD" })
- * // => "$99.99"
- * ```
+ * formatPrice({ amount: "99.99", currencyCode: "USD" }, 'en-US')  // => "$99.99"
+ * formatPrice({ amount: "12.50", currencyCode: "PLN" }, 'pl-PL')  // => "12,50 zł"
+ * formatPrice({ amount: "115.20", currencyCode: "EUR" }, 'de-DE') // => "115,20 €"
  */
-export declare function formatPrice(price: PriceMoney | null | undefined): string;
+export declare function formatPrice(price: PriceMoney | null | undefined, locale?: string): string;
 /**
- * Format price range
+ * Format a price range (`min - max`). Returns a single price when `min` equals
+ * `max` by string comparison (no numeric conversion).
  *
  * @example
- * ```typescript
  * formatPriceRange(
  *   { amount: "10.00", currencyCode: "USD" },
- *   { amount: "50.00", currencyCode: "USD" }
+ *   { amount: "50.00", currencyCode: "USD" },
+ *   'en-US'
  * )
  * // => "$10.00 - $50.00"
- * ```
  */
-export declare function formatPriceRange(minPrice: PriceMoney, maxPrice: PriceMoney): string;
+export declare function formatPriceRange(minPrice: PriceMoney, maxPrice: PriceMoney, locale?: string): string;
 /**
- * Format amount with currency
+ * Format an amount with currency. Accepts a string (recommended — precision
+ * preserved) or a number. String values are forwarded to `Intl.NumberFormat`
+ * verbatim; number values pass through the standard number path.
  *
  * @example
- * ```tsx
- * const formatted = formatAmount("115.20", "EUR");
- * // => "115,20 €"
- * ```
+ * formatAmount("115.20", "EUR", 'de-DE')  // => "115,20 €"
+ * formatAmount(50, "USD", 'en-US')        // => "$50.00"
  */
-export declare function formatAmount(amount: string | number, currencyCode: string): string;
+export declare function formatAmount(amount: string | number, currencyCode: string, locale?: string): string;
 /**
- * Format date to locale string
+ * Format a date in the requested locale using a `MMM d, y`-style pattern
+ * (locale-specific month abbreviation and ordering).
  *
  * @example
- * ```typescript
- * formatDate(new Date())
- * // => "Dec 9, 2025"
- * ```
+ * formatDate(new Date(2025, 11, 9), 'en-US')  // => "Dec 9, 2025"
+ * formatDate(new Date(2025, 11, 9), 'pl-PL')  // => "9 gru 2025"
+ * formatDate('2025-12-09T12:00:00Z', 'de-DE') // => "9. Dez. 2025"
  */
-export declare function formatDate(date: Date | string): string;
+export declare function formatDate(date: Date | string, locale: string): string;
 /**
- * Format date with time
+ * Format a date with time in the requested locale (month-abbreviated date plus
+ * hour and minute, 12- or 24-hour depending on locale convention).
  *
  * @example
- * ```typescript
- * formatDateTime(new Date())
- * // => "Dec 9, 2025, 10:30 PM"
- * ```
+ * formatDateTime(new Date(), 'en-US')  // => "Dec 9, 2025, 10:30 PM"
+ * formatDateTime(new Date(), 'pl-PL')  // => "9 gru 2025, 22:30"
  */
-export declare function formatDateTime(date: Date | string): string;
+export declare function formatDateTime(date: Date | string, locale: string): string;
 /**
- * Format number with thousands separator
+ * Format a number with the locale-appropriate thousands separator and decimal
+ * mark.
  *
  * @example
- * ```typescript
- * formatNumber(1234567)
- * // => "1,234,567"
- * ```
+ * formatNumber(1234567, 'en-US')  // => "1,234,567"
+ * formatNumber(1234567, 'pl-PL')  // => "1 234 567" (NBSP separator)
+ * formatNumber(1234.5, 'de-DE')   // => "1.234,5"
  */
-export declare function formatNumber(num: number): string;
+export declare function formatNumber(num: number, locale: string): string;
 /**
- * Format percentage
+ * Format a 0-1 ratio as an integer percentage. Locale-independent — uses
+ * `Math.round` and a literal `%` suffix.
  *
  * @example
- * ```typescript
- * formatPercentage(0.15)
- * // => "15%"
- * ```
+ * formatPercentage(0.15)  // => "15%"
+ * formatPercentage(0.125) // => "13%" (Math.round half-up)
  */
 export declare function formatPercentage(value: number): string;
 //# sourceMappingURL=format.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/core/format.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD,+BAA+B;AAC/B,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAcnD,CAAC;AAEF,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAcnD,CAAC;AA+CF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAaxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,UAAU,GACnB,MAAM,CAMR;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,YAAY,EAAE,MAAM,GACnB,MAAM,CAUR;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAQtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAU1D;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/core/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAOH,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,IAAI,CAAC;QACb,UAAU,YAAY;YACpB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;SAC/B;KACF;CACF;AAMD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AA+DD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAYvE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CASzF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,UAAU,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAMR;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAaR;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQtE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAU1E;AAMD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD"}