@doswiftly/storefront-sdk 13.1.0 → 15.1.0

package/CHANGELOG.md

@@ -1,5 +1,241 @@
 # Changelog
 
+## 15.1.0
+
+### Minor Changes
+
+- 94c2603: Storefront SDK now covers the full checkout flow end-to-end through typed methods — no more dropping to raw GraphQL for shipping discovery, payment listing, guest order lookup, cart attributes, or saved-address pickers.
+
+  **New `CartClient` methods**
+  - `getAvailableShippingMethods(cartId, address)` — cart-aware shipping discovery. Resolves with `null` when the cart does not exist or has expired (symmetric with `get(cartId)`), otherwise with `AvailableShippingMethodsPayload`: `methods[]` (each carrying `deliveryType` — `HOME`, `PICKUP_POINT`, `LOCKER` — so the storefront picks the pickup / locker UI without inferring from the method name), `freeShippingProgress` (best progress across methods, for the picker banner), and `userErrors[]` populated for business conditions like `DIGITAL_ONLY_NO_SHIPPING` (cart with no shippable lines) or `NO_SHIPPING_METHODS` (unsupported address). Branch on `result.userErrors[0].code`; the `message` is localized per the request's `Accept-Language`.
+  - `getAvailablePaymentMethods()` — shop-level list of active payment methods. Returns `AvailablePaymentMethods`: `methods[]` (sorted by merchant position) and `defaultMethod` (merchant-flagged pre-selection). Prefer `result.defaultMethod ?? result.methods.find(m => m.isDefault)` — the merchant may override the default independently of per-method flags.
+  - `getOrderByToken(token, email?)` — guest order lookup by opaque access token (returned in `complete().order.accessToken`). Optional `email` adds defense in depth; mismatch returns the same `null` shape as an invalid token. Rate-limited server-side (5 req / min per IP + shop).
+  - `updateAttributes(cartId, attributes)` — replace-all of the cart's custom `{ key, value }` pairs (delivery instructions, gift-wrap flags, B2B PO numbers). Pass an empty array to clear.
+
+  **New `AuthClient` method**
+  - `getAddresses()` — saved address book of the authenticated customer (shipping + billing). Resolves with the address list when authenticated, with `null` when no auth context reached the server (symmetric with `getCustomer()`). Each entry carries B2B fields (`taxId`, `vatNumber`) and the `isDefault` flag, so the same list serves both shipping and billing pickers.
+
+  **Schema additions (operations package)**
+  - `MailingAddress` now exposes `taxId`, `vatNumber`, and `pickupPoint`. The new `PickupPoint` type (`provider`, `pointId`, `name?`, `address?`) is returned on shipping addresses delivered to a parcel locker / collection point.
+  - `AvailableShippingMethod` gains the declarative `deliveryType` enum.
+  - `CartAppliedGiftCard` now exposes `id` — the stable handle to pass to `cartRemoveGiftCard` (no need to keep the raw gift card code on the client).
+  - New `CustomerAddresses` query — `customer.addresses(first: 50)` connection returning the address book, normalized to a node list by the SDK wrapper.
+
+  **SDK fragment changes**
+
+  The SDK's `MailingAddress` fragment now selects `taxId`, `vatNumber`, and `pickupPoint`. Existing types that include a mailing address (`Cart.shippingAddress`, `Cart.billingAddress`, `Order.shippingAddress`, `Customer.defaultAddress`) get these fields automatically. The `AvailableShippingMethod` fragment selects `deliveryType`. The `CartAppliedGiftCard` fragment selects `id`.
+
+  **New React hook — server-driven checkout**
+  - `useCart(cartId, options?)` — sister of `useCartManager`, bound to an explicit `cartId` instead of the `cart-id` cookie. Use it for SSR-rendered checkout, deep-link order recovery, and admin "view this cart" UIs where the cart id is known up front and the cookie is irrelevant. Returns the loaded cart plus the same mutation surface as the cookie-based hook (`addItems`, `updateItems`, `removeItems`, `updateBuyerIdentity`, `setShippingAddress`, `updateDiscountCodes`, `updateNote`, `updateAttributes` — each resolves with `{ cart, warnings }` so low-stock and partial-availability hints flow through), reactive `isLoading` / `error` / `operation` state, and a `refetch()` callback. `autoFetch: false` + `initialCart` lets you skip the hydration round-trip when the server already resolved the cart.
+
+  **Field-level descriptions visible in your IDE**
+
+  Hovering on any cart / order / customer / payment / shipping field in your editor now shows a precise English description of what the field carries — when to use it, what its values mean, what is null vs zero, which enum values are relevant. The descriptions were rewritten across every type selected by the SDK so the storefront-developer audience does not need to look anywhere else for the contract. Codegen is configured (`preResolveTypes: false`) to propagate those descriptions through every generated fragment / query type, so the same hover works on the typed shape your codegen produces.
+
+  These additions are backward-compatible — existing calls keep their current signatures and return the same fields (plus the new ones). The mailing-address fragment expansion is purely additive.
+
+## 15.0.0
+
+### Major Changes
+
+- a11f9e4: GraphQL types are now generated from the storefront schema instead of being hand-written. Every exported cart, order, customer, and payment type is derived directly from the schema, so they can no longer drift out of sync with the API.
+
+  **Breaking** — the previous hand-written types were inaccurate, and correcting them changes some shapes:
+  - `Customer.orderCount` is now `string` (was `number`).
+  - `CartLineEdge` and `CartLineConnection.edges` were removed — the cart query never returned edges.
+  - Fields previously typed as `string` are now precise string-literal union types: `Order.status`, `Order.paymentStatus`, `Order.fulfillmentStatus`, `PaymentSession.status`, `CartLine.productType`, `Money.currencyCode`, `CartWarning.code`, and the `AttributeSelection` mode fields. Reading these values still works; assigning arbitrary strings into them no longer compiles.
+
+  **Fixed** — types that were missing fields or had the wrong nullability:
+  - `Order` now includes `accessToken`.
+  - `Cart` and `CartLine` now include `requiresShipping`.
+  - `Customer.displayName`, `Customer.emailMarketing`, and `Customer.totalSpent` are now correctly non-nullable.
+  - The duplicated `MailingAddress` definition is collapsed into one.
+
+  **New** — the schema enum types used by the public types are now exported: `CurrencyCode`, `CountryCode`, `LanguageCode`, `ProductTypeEnum`, `WeightUnit`, `CartWarningCode`, `StorefrontOrderStatus`, `OrderPaymentStatus`, `OrderFulfillmentStatus`, `EmailMarketingState`, `MarketingOptInLevel`, and the attribute enums.
+
+  These are type-only changes — no runtime behaviour changed.
+
+## 14.0.0
+
+### Major Changes
+
+- 1fda2ab: **BREAKING**: URL identifier unification (`slug` → `handle`) + type renames for naming consistency.
+
+  ### What changed
+
+  URL-friendly identifiers across the storefront GraphQL API now consistently use `handle` (previously a mix of `slug` and `handle`). Canonical product brand entity renamed from `BrandSummary` to `Brand`. Shop branding type `Brand` renamed to `ShopBrand` to free the `Brand` name for the product entity.
+
+  ### Field renames (GraphQL response)
+
+  | Type                         | Old    | New      |
+  | ---------------------------- | ------ | -------- |
+  | `Category`                   | `slug` | `handle` |
+  | `BlogPost`                   | `slug` | `handle` |
+  | `BlogCategory`               | `slug` | `handle` |
+  | `BlogTag`                    | `slug` | `handle` |
+  | `LoyaltyReward`              | `slug` | `handle` |
+  | `BrandFilter` (input)        | `slug` | `handle` |
+  | `BrandFilterValue`           | `slug` | `handle` |
+  | `ProductAttributeDefinition` | `slug` | `handle` |
+  | `CategoryFilterOption`       | `slug` | `handle` |
+
+  ### Type renames
+  - `BrandSummary` → `Brand` (canonical product brand entity, e.g. Funko, Nike). Update `__typename` checks and fragment spreads.
+  - `Brand` (shop branding) → `ShopBrand` (tenant-scoped shop metadata: logo, slogan, colors).
+
+  ### Query args renamed
+
+  ```graphql
+  # Old
+  query { category(slug: "figurki") { id name } }
+  query { blogPost(slug: "post-handle") { title } }
+  query BlogPosts($categorySlug: String, $tagSlug: String) {
+    blogPosts(categorySlug: $categorySlug, tagSlug: $tagSlug) { ... }
+  }
+
+  # New
+  query { category(handle: "figurki") { id name } }
+  query { blogPost(handle: "post-handle") { title } }
+  query BlogPosts($categoryHandle: String, $tagHandle: String) {
+    blogPosts(categoryHandle: $categoryHandle, tagHandle: $tagHandle) { ... }
+  }
+  ```
+
+  ### Brand filter input
+
+  ```graphql
+  # Old
+  products(filters: [{ brand: { slug: "funko" } }]) { ... }
+
+  # New
+  products(filters: [{ brand: { handle: "funko" } }]) { ... }
+  ```
+
+  ### MenuItem resource union
+
+  ```graphql
+  # Old
+  fragment MenuItem on MenuItem {
+    resource {
+      __typename
+      ... on Category {
+        id
+        slug
+        name
+      }
+      ... on BrandSummary {
+        id
+        slug
+        name
+        logo
+      }
+    }
+  }
+
+  # New
+  fragment MenuItem on MenuItem {
+    resource {
+      __typename
+      ... on Category {
+        id
+        handle
+        name
+      }
+      ... on Brand {
+        id
+        handle
+        name
+        logo
+      }
+    }
+  }
+  ```
+
+  ### Migration steps
+  1. Update to `@doswiftly/storefront-operations@^14.0.0` + `@doswiftly/storefront-sdk@^14.0.0`.
+  2. Run your codegen — TypeScript will surface every call site that needs update.
+  3. Find/replace in storefront code:
+     - `.slug` → `.handle` on response fields listed above.
+     - `__typename === 'BrandSummary'` → `__typename === 'Brand'`.
+     - `{ brand: { slug } }` filter input → `{ brand: { handle } }`.
+     - `categorySlug`/`tagSlug` query args → `categoryHandle`/`tagHandle`.
+  4. Update GraphQL fragments selecting renamed fields.
+  5. Re-run codegen, fix any remaining TypeScript errors.
+
+  ### Why
+
+  A single naming convention (`handle`) across all URL identifiers removes ambiguity and matches common e-commerce GraphQL convention. The `BrandSummary` suffix was misleading — no full `Brand` ObjectType existed, so the suffix suggested a missing parent type. Shop branding `Brand` blocked the cleaner name for the product entity.
+
+  Full migration guide with code examples: <https://docs.doswiftly.pl/storefront-developer/migration-14.0>
+
+  Naming conventions reference: <https://docs.doswiftly.pl/storefront-developer/api/naming-conventions>
+
+### Minor Changes
+
+- 507d487: Storefront GraphQL: nowy `attributeOptionsSearch(input)` query — paginated + searchable lista opcji atrybutu (Relay Connection).
+
+  Use case: storefront UI z dużymi filtrami atrybutów (np. 800+ licencji, materiałów, rozmiarów, kolorów) — dropdown z autocomplete i paginacją bez zassania całej listy. `productFilters.attributes[].filterValues[]` zostaje jako quick browse facets (top N), `attributeOptionsSearch` służy do drill-into specific filter card z searchem.
+
+  Dla **marek/producentów** preferuj dedykowane API `productFilters.brands[]` (Brand jest pełnoprawną encją z logo i productCount) — `attributeOptionsSearch(handle: "marka")` jest legacy fallback dla katalogów bez kanonicznej Brand entity.
+
+  **Input** (`AttributeOptionsSearchInput`):
+  - `handle: String!` — slug atrybutu (np. `"marka"`)
+  - `contextInput: AvailableFiltersInput` — produktowy kontekst (kategoria/kolekcja/search/currentFilters) z exclude-self semantyką
+  - `first: Int` (1–100, default 50)
+  - `after: String` — opaque cursor
+  - `search: String` — case-insensitive ILIKE (max 100 znaków)
+  - `sort: AttributeOptionsSearchSort` — `COUNT_DESC` (default, most popular first) lub `LABEL_ASC` (alfabetycznie z polskim collation)
+
+  **Output** (`AttributeFilterValueConnection`): `edges { cursor node }`, `nodes` (shortcut), `pageInfo`, `totalCount`. Wspiera atrybuty `SELECT`/`CHECKBOX`/`RADIO`/`COLOR` (z bazy `attribute_options`) oraz `TEXT`/`TEXTAREA` (z aggregated unique values).
+
+  **Migration**: brak breaking changes — `productFilters` zachowuje obecny shape. Jeśli budujesz "Pokaż wszystkie marki" UI, przenoś logikę na nowy query żeby uniknąć over-fetching.
+
+- 6f8d873: `CartWarningCode` enum gains a fourth value, `SHIPPING_METHOD_AUTO_CLEARED`.
+
+  Cart line mutations (`cartAddLines`, `cartUpdateLines`, `cartRemoveLines`) now reconcile the selected shipping method against cart contents on every call. When a mutation leaves the cart with no items that require physical delivery (digital-only or empty) but a shipping method is still set, the method is cleared automatically and the mutation response surfaces a `CartWarning { code: "SHIPPING_METHOD_AUTO_CLEARED", target: "selectedShippingMethod", message: "…" }`.
+
+  This closes the gap where a mixed cart that lost its last physical line via the storefront UI would persist a stale shipping method and fail later at checkout submit with `FORBIDDEN_SHIPPING_METHOD`. There is no escape hatch needed on the storefront — the mutation accepts non-null `shippingMethodId` only, so the backend takes responsibility for the transition.
+
+  **Storefront impact**: none required. Reads of `cart.selectedShippingMethod` already returned `null` once cleared. Apps that already consume the `warnings[]` array (Apps that follow the standard `userErrors[]` + `warnings[]` payload shape) will surface the auto-clear toast for free. Apps that ignore `warnings[]` continue to work — the mutation still succeeds and the cart is left in a consistent state.
+
+  **Locale**: `message` is translated server-side (`Accept-Language`) — for example, `pl` returns "Wybrana metoda wysyłki została usunięta, ponieważ koszyk nie wymaga już dostawy.", `en` returns "The selected shipping method was removed because the cart no longer requires delivery."
+
+  The warning fires only on the line mutation that triggers the transition, never on subsequent reads or unrelated mutations. Decrementing a physical line quantity from `3` to `1`, removing one physical line while another remains, or adding digital lines to a mixed cart all leave the shipping method untouched.
+
+- 1fda2ab: Storefront navigation menus: typed `resource` field eksponowany w `MenuItem` fragment + nowy typ linku `BRAND`.
+
+  **Co nowego**:
+  - `MenuItem.resource: MenuItemResource` — typed union (`Category` / `Collection` / `ShopPage` / `Product` / `BrandSummary`) wystawiony w `MenuItem` fragment na wszystkich 3 poziomach zagnieżdżenia. Każdy member zwraca `slug` (Category/Product/BrandSummary) lub `handle` (Collection/ShopPage) gotowy do budowy własnego URL.
+  - `MenuItemType.BRAND` — nowy typ linku menu dla marek producentów. `BrandSummary` w `resource` union (`id`, `name`, `slug`, `logo`).
+  - `MenuItem.url` dla `BRAND` resolve'uje się serwerowo jako `/brands/<slug>` — spójnie z istniejącą konwencją `/categories|/collections|/pages|/products/<slug>`.
+
+  **Dwa sposoby renderingu link target**:
+  1. **Standard route convention** — użyj `item.url` jak dotąd. Działa jeśli storefront ma routy `/categories/[slug]`, `/collections/[handle]`, `/pages/[handle]`, `/products/[handle]`, `/brands/[slug]`.
+  2. **Custom routing** (Next.js single-segment, Remix, itd.) — odczytaj `item.resource.__typename` + per-type `slug`/`handle`:
+
+  ```ts
+  function buildHref(item: MenuItem): string {
+    if (!item.resource) return item.url ?? "#";
+    switch (item.resource.__typename) {
+      case "Category":
+        return `/${item.resource.slug}`;
+      case "Collection":
+        return `/${item.resource.handle}`;
+      case "ShopPage":
+        return `/${item.resource.handle}`;
+      case "Product":
+        return `/p/${item.resource.handle}`;
+      case "BrandSummary":
+        return `/marka/${item.resource.slug}`;
+    }
+    return item.url ?? "#";
+  }
+  ```
+
+  **Performance**: wszystkie resource lookupy są batchowane per request — zero N+1 nawet w głębokich menu.
+
+  **Migration**: brak breaking changes. Kod używający tylko `item.url` działa bez zmian. `resource` jest opt-in dopóki nie zaczniesz go selekcjonować w custom fragmencie.
+
 ## 13.1.0
 
 ### Minor Changes

package/dist/core/auth/auth-client.d.ts

@@ -16,7 +16,7 @@
  * ```
  */
 import type { StorefrontClient } from '../client/types';
-import type { AuthResult, Customer, CustomerCreateInput } from './types';
+import type { AuthResult, Customer, CustomerCreateInput, MailingAddress } from './types';
 export declare class AuthClient {
     private readonly client;
     constructor(client: StorefrontClient);
@@ -48,5 +48,17 @@ export declare class AuthClient {
      * via SDK auth middleware (`setAuthToken`).
      */
     getCustomer(): Promise<Customer | null>;
+    /**
+     * Saved address book of the authenticated customer (shipping + billing).
+     * Each entry carries B2B fields (`taxId`, `vatNumber`) and the `isDefault`
+     * flag, so the same list serves both pickers on checkout.
+     *
+     * Resolves with `null` when the request reaches the server without an auth
+     * context — symmetric with `getCustomer()` which also returns `null` for
+     * the unauthenticated case. Storefront UIs typically already gate access
+     * to address-pickers behind their own auth-state (`useAuth`), so `null`
+     * here means "no session reached the server" rather than "no addresses".
+     */
+    getAddresses(): Promise<MailingAddress[] | null>;
 }
 //# sourceMappingURL=auth-client.d.ts.map

package/dist/core/auth/auth-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../../src/core/auth/auth-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAUzE,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBjE;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAa7B;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC;IAiBzC;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB/D;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;CAO9C"}
+{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../../src/core/auth/auth-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAWzF,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,gBAAgB;IAErD;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBjE;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAa7B;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC;IAiBzC;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB/D;;;;OAIG;IACG,WAAW,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAQ7C;;;;;;;;;;OAUG;IACG,YAAY,IAAI,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC;CAMvD"}

package/dist/core/auth/auth-client.js

@@ -16,7 +16,7 @@
  * ```
  */
 import { assertNoUserErrors } from '../helpers/assert-no-user-errors';
-import { CUSTOMER_LOGIN, CUSTOMER_LOGOUT, CUSTOMER_REFRESH_TOKEN, CUSTOMER_SIGNUP, CUSTOMER_QUERY, } from '../operations/auth';
+import { CUSTOMER_LOGIN, CUSTOMER_LOGOUT, CUSTOMER_REFRESH_TOKEN, CUSTOMER_SIGNUP, CUSTOMER_QUERY, CUSTOMER_ADDRESSES_QUERY, } from '../operations/auth';
 export class AuthClient {
     client;
     constructor(client) {
@@ -85,4 +85,19 @@ export class AuthClient {
         const data = await this.client.query(CUSTOMER_QUERY);
         return data.customer;
     }
+    /**
+     * Saved address book of the authenticated customer (shipping + billing).
+     * Each entry carries B2B fields (`taxId`, `vatNumber`) and the `isDefault`
+     * flag, so the same list serves both pickers on checkout.
+     *
+     * Resolves with `null` when the request reaches the server without an auth
+     * context — symmetric with `getCustomer()` which also returns `null` for
+     * the unauthenticated case. Storefront UIs typically already gate access
+     * to address-pickers behind their own auth-state (`useAuth`), so `null`
+     * here means "no session reached the server" rather than "no addresses".
+     */
+    async getAddresses() {
+        const data = await this.client.query(CUSTOMER_ADDRESSES_QUERY);
+        return data.customer?.addresses.nodes ?? null;
+    }
 }

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

@@ -1,60 +1,26 @@
 /**
- * Auth types — manual (no codegen).
+ * Auth types — derived from the generated GraphQL operation types.
+ *
+ * Output types alias the generated `*Fragment` types; the input type and enums
+ * re-export the generated schema types. SSOT chain: backend storefront-graphql
+ * schema → `core/operations/*.ts` → `src/core/generated/operation-types.ts`
+ * (regenerate with `pnpm codegen`).
+ */
+import type { CustomerFieldsFragment, CustomerAccessTokenFieldsFragment, MailingAddressFragment } from '../generated/operation-types';
+/** Authenticated customer profile. */
+export type Customer = CustomerFieldsFragment;
+/** Access token pair issued by login / signup / refresh. */
+export type CustomerAccessToken = CustomerAccessTokenFieldsFragment;
+/** Shipping/billing address shape (shared with the cart surface). */
+export type MailingAddress = MailingAddressFragment;
+export type { CustomerCreateInput, EmailMarketingState, MarketingOptInLevel, } from '../generated/operation-types';
+/**
+ * Result of a login / signup call — the SDK's composite shape pairing the
+ * issued access token with the (optional) customer profile.
  */
-export interface CustomerAccessToken {
-    accessToken: string;
-    expiresAt: string;
-}
-export interface Customer {
-    id: string;
-    email: string;
-    firstName: string | null;
-    lastName: string | null;
-    displayName: string | null;
-    phone: string | null;
-    isEmailVerified: boolean;
-    emailMarketing: string | null;
-    defaultAddress: MailingAddress | null;
-    orderCount: number;
-    totalSpent: {
-        amount: string;
-        currencyCode: string;
-    } | null;
-    createdAt: string;
-    updatedAt: string;
-}
-export interface MailingAddress {
-    id: string;
-    streetLine1: string | null;
-    streetLine2: string | null;
-    city: string | null;
-    company: string | null;
-    country: string | null;
-    countryCode: string | null;
-    firstName: string | null;
-    lastName: string | null;
-    /** Computed full name (`firstName + " " + lastName`). */
-    name: string | null;
-    phone: string | null;
-    state: string | null;
-    stateCode: string | null;
-    postalCode: string | null;
-    isDefault: boolean;
-}
 export interface AuthResult {
     accessToken: string;
     expiresAt: string;
     customer?: Customer;
 }
-export interface CustomerCreateInput {
-    email: string;
-    password: string;
-    firstName?: string;
-    lastName?: string;
-    phone?: string;
-    /** Opt-in to email marketing. `true` → SUBSCRIBED (lub PENDING gdy CONFIRMED_OPT_IN). */
-    acceptsMarketing?: boolean;
-    /** Marketing opt-in level — `'SINGLE_OPT_IN'` (default) lub `'CONFIRMED_OPT_IN'` (double opt-in via email). */
-    marketingOptInLevel?: 'SINGLE_OPT_IN' | 'CONFIRMED_OPT_IN';
-}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,cAAc,GAAG,IAAI,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,yDAAyD;IACzD,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,+GAA+G;IAC/G,mBAAmB,CAAC,EAAE,eAAe,GAAG,kBAAkB,CAAC;CAC5D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/auth/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EACV,sBAAsB,EACtB,iCAAiC,EACjC,sBAAsB,EACvB,MAAM,8BAA8B,CAAC;AAEtC,sCAAsC;AACtC,MAAM,MAAM,QAAQ,GAAG,sBAAsB,CAAC;AAE9C,4DAA4D;AAC5D,MAAM,MAAM,mBAAmB,GAAG,iCAAiC,CAAC;AAEpE,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,sBAAsB,CAAC;AAEpD,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AAEtC;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB"}

package/dist/core/auth/types.js

@@ -1,4 +1 @@
-/**
- * Auth types — manual (no codegen).
- */
 export {};

package/dist/core/cart/cart-client.d.ts

@@ -22,7 +22,7 @@
  * ```
  */
 import type { StorefrontClient } from '../client/types';
-import type { Cart, CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartSetShippingAddressInput, CartSetBillingAddressInput, CartSelectShippingMethodInput, CartSelectPaymentMethodInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartUpdateGiftCardRecipientInput, CartCompleteInput, CartWarning, Order, DiscountValidationResult, PaymentSession, PaymentCreateInput } from './types';
+import type { Cart, CartCreateInput, CartLineInput, CartLineUpdateInput, CartBuyerIdentityInput, CartAttributeInput, CartSetShippingAddressInput, CartSetBillingAddressInput, CartSelectShippingMethodInput, CartSelectPaymentMethodInput, CartApplyGiftCardInput, CartRemoveGiftCardInput, CartUpdateGiftCardRecipientInput, CartCompleteInput, CartWarning, Order, DiscountValidationResult, PaymentSession, PaymentCreateInput, AvailableShippingMethodsPayload, AvailablePaymentMethods, ShippingAddressInput } from './types';
 /**
  * Standard mutation return shape — `cart` is non-null on success (userErrors
  * cause assertNoUserErrors to throw), `warnings` may be empty.
@@ -51,6 +51,47 @@ export declare class CartClient {
      * Returns null if cart doesn't exist or has expired.
      */
     get(cartId: string): Promise<Cart | null>;
+    /**
+     * Cart-aware list of shipping methods available for the given destination.
+     * Resolves with `null` when the cart does not exist or has expired —
+     * symmetric with `CartClient.get(cartId)`. Otherwise resolves with
+     * `AvailableShippingMethodsPayload`:
+     *
+     * - `methods[]` — methods available for this cart at the destination, each
+     *   carrying `deliveryType` (`HOME` / `PICKUP_POINT` / `LOCKER`).
+     * - `freeShippingProgress` — best free-shipping progress across all
+     *   returned methods (use for a single banner above the picker).
+     * - `userErrors[]` — populated by the backend for business conditions
+     *   (e.g. `DIGITAL_ONLY_NO_SHIPPING` for a cart with no shippable lines,
+     *   `NO_SHIPPING_METHODS` for an unsupported address). Branch on
+     *   `userErrors[0].code`; the `message` is localized per the request's
+     *   `Accept-Language` header.
+     */
+    getAvailableShippingMethods(cartId: string, address: ShippingAddressInput): Promise<AvailableShippingMethodsPayload | null>;
+    /**
+     * Shop-level list of active payment methods. Returns the raw payload from
+     * the backend:
+     *
+     * - `methods[]` — sorted by the merchant's display position.
+     * - `defaultMethod` — the merchant-flagged pre-selection (may be null when
+     *   none is configured). Prefer this over scanning `methods.find(isDefault)`
+     *   — the merchant may override the default independently of per-method
+     *   flags.
+     */
+    getAvailablePaymentMethods(): Promise<AvailablePaymentMethods>;
+    /**
+     * Fetch a guest order by its opaque access token (returned in
+     * `complete().order.accessToken`). Use on the post-checkout confirmation
+     * page when the buyer is not signed in.
+     *
+     * Optional `email` is matched case-insensitively against the order's buyer
+     * email as defense in depth — on mismatch the call returns `null` with the
+     * same shape as an invalid token (attackers cannot distinguish the two).
+     *
+     * Backend rate-limits this query (5 requests / minute per IP + shop) and
+     * responses are uncached.
+     */
+    getOrderByToken(token: string, email?: string): Promise<Order | null>;
     /**
      * Create a new cart, optionally with initial lines.
      */
@@ -76,6 +117,14 @@ export declare class CartClient {
      * Update cart note / gift message.
      */
     updateNote(cartId: string, note: string): Promise<CartMutationOutcome>;
+    /**
+     * Replace the cart's custom `{ key, value }` attribute pairs — free-form
+     * metadata visible to the merchant (delivery instructions, gift-wrap flags,
+     * B2B PO numbers). Semantics is REPLACE-ALL (not merge): pass the full set
+     * each call, an empty array clears all attributes. Backend rejects oversized
+     * sets with `CART_ATTRIBUTES_LIMIT_EXCEEDED` (max 250 pairs, 255-char keys).
+     */
+    updateAttributes(cartId: string, attributes: CartAttributeInput[]): Promise<CartMutationOutcome>;
     /**
      * Update buyer identity (email, phone, country, customer link, languageCode).
      */

package/dist/core/cart/cart-client.d.ts.map

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

package/dist/core/cart/cart-client.js

@@ -22,7 +22,7 @@
  * ```
  */
 import { assertNoUserErrors } from '../helpers/assert-no-user-errors';
-import { CART_QUERY, CART_CREATE, CART_ADD_LINES, CART_UPDATE_LINES, CART_REMOVE_LINES, CART_DISCOUNT_CODES_UPDATE, CART_UPDATE_NOTE, CART_UPDATE_BUYER_IDENTITY, CART_SET_SHIPPING_ADDRESS, CART_SET_BILLING_ADDRESS, CART_SELECT_SHIPPING_METHOD, CART_SELECT_PAYMENT_METHOD, CART_APPLY_GIFT_CARD, CART_REMOVE_GIFT_CARD, CART_UPDATE_GIFT_CARD_RECIPIENT, CART_COMPLETE, CART_VALIDATE_DISCOUNT_CODE, PAYMENT_CREATE, } from '../operations/cart';
+import { CART_QUERY, ORDER_BY_TOKEN_QUERY, CART_AVAILABLE_SHIPPING_METHODS_QUERY, AVAILABLE_PAYMENT_METHODS_QUERY, CART_CREATE, CART_ADD_LINES, CART_UPDATE_LINES, CART_REMOVE_LINES, CART_DISCOUNT_CODES_UPDATE, CART_UPDATE_NOTE, CART_UPDATE_ATTRIBUTES, CART_UPDATE_BUYER_IDENTITY, CART_SET_SHIPPING_ADDRESS, CART_SET_BILLING_ADDRESS, CART_SELECT_SHIPPING_METHOD, CART_SELECT_PAYMENT_METHOD, CART_APPLY_GIFT_CARD, CART_REMOVE_GIFT_CARD, CART_UPDATE_GIFT_CARD_RECIPIENT, CART_COMPLETE, CART_VALIDATE_DISCOUNT_CODE, PAYMENT_CREATE, } from '../operations/cart';
 export class CartClient {
     client;
     constructor(client) {
@@ -36,6 +36,56 @@ export class CartClient {
         const data = await this.client.query(CART_QUERY, { id: cartId });
         return data.cart;
     }
+    /**
+     * Cart-aware list of shipping methods available for the given destination.
+     * Resolves with `null` when the cart does not exist or has expired —
+     * symmetric with `CartClient.get(cartId)`. Otherwise resolves with
+     * `AvailableShippingMethodsPayload`:
+     *
+     * - `methods[]` — methods available for this cart at the destination, each
+     *   carrying `deliveryType` (`HOME` / `PICKUP_POINT` / `LOCKER`).
+     * - `freeShippingProgress` — best free-shipping progress across all
+     *   returned methods (use for a single banner above the picker).
+     * - `userErrors[]` — populated by the backend for business conditions
+     *   (e.g. `DIGITAL_ONLY_NO_SHIPPING` for a cart with no shippable lines,
+     *   `NO_SHIPPING_METHODS` for an unsupported address). Branch on
+     *   `userErrors[0].code`; the `message` is localized per the request's
+     *   `Accept-Language` header.
+     */
+    async getAvailableShippingMethods(cartId, address) {
+        const data = await this.client.query(CART_AVAILABLE_SHIPPING_METHODS_QUERY, { cartId, address });
+        return data.cart?.availableShippingMethods ?? null;
+    }
+    /**
+     * Shop-level list of active payment methods. Returns the raw payload from
+     * the backend:
+     *
+     * - `methods[]` — sorted by the merchant's display position.
+     * - `defaultMethod` — the merchant-flagged pre-selection (may be null when
+     *   none is configured). Prefer this over scanning `methods.find(isDefault)`
+     *   — the merchant may override the default independently of per-method
+     *   flags.
+     */
+    async getAvailablePaymentMethods() {
+        const data = await this.client.query(AVAILABLE_PAYMENT_METHODS_QUERY);
+        return data.availablePaymentMethods;
+    }
+    /**
+     * Fetch a guest order by its opaque access token (returned in
+     * `complete().order.accessToken`). Use on the post-checkout confirmation
+     * page when the buyer is not signed in.
+     *
+     * Optional `email` is matched case-insensitively against the order's buyer
+     * email as defense in depth — on mismatch the call returns `null` with the
+     * same shape as an invalid token (attackers cannot distinguish the two).
+     *
+     * Backend rate-limits this query (5 requests / minute per IP + shop) and
+     * responses are uncached.
+     */
+    async getOrderByToken(token, email) {
+        const data = await this.client.query(ORDER_BY_TOKEN_QUERY, { token, email });
+        return data.orderByToken;
+    }
     /**
      * Create a new cart, optionally with initial lines.
      */
@@ -85,6 +135,18 @@ export class CartClient {
         assertNoUserErrors(data.cartUpdateNote);
         return { cart: data.cartUpdateNote.cart, warnings: data.cartUpdateNote.warnings ?? [] };
     }
+    /**
+     * Replace the cart's custom `{ key, value }` attribute pairs — free-form
+     * metadata visible to the merchant (delivery instructions, gift-wrap flags,
+     * B2B PO numbers). Semantics is REPLACE-ALL (not merge): pass the full set
+     * each call, an empty array clears all attributes. Backend rejects oversized
+     * sets with `CART_ATTRIBUTES_LIMIT_EXCEEDED` (max 250 pairs, 255-char keys).
+     */
+    async updateAttributes(cartId, attributes) {
+        const data = await this.client.mutate(CART_UPDATE_ATTRIBUTES, { id: cartId, attributes });
+        assertNoUserErrors(data.cartUpdateAttributes);
+        return { cart: data.cartUpdateAttributes.cart, warnings: data.cartUpdateAttributes.warnings ?? [] };
+    }
     /**
      * Update buyer identity (email, phone, country, customer link, languageCode).
      */