@doswiftly/storefront-sdk 13.1.0 → 14.0.0

package/CHANGELOG.md

@@ -1,5 +1,186 @@
 # Changelog
 
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "13.1.0",
+  "version": "14.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,