@doswiftly/storefront-operations 12.0.0 → 13.0.0

package/AGENTS.md

@@ -27,7 +27,7 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 12.0.0
+- **Schema version**: 13.0.0
 - **Queries**: 49
 - **Mutations**: 40
 - **Fragments**: 100

package/CHANGELOG.md

@@ -1,5 +1,181 @@
 # Changelog
 
+## 13.0.0
+
+### Major Changes
+
+- 783ce01: Faceted aggregation accuracy + DX naming consolidation w `productFilters` API. Plus boolean facet count dla "availableForSale" + payload cleanup w Cart query.
+
+  ## BREAKING — `AvailableFilters.matchCount` removed → `totalCount`
+
+  Pole `matchCount` zostało usunięte. Użyj `totalCount` — semantyka identyczna (produkty w current context PRZED zaaplikowaniem faceted filters), nazwa zaligned z `ProductConnection.totalCount` (Relay Connection spec).
+
+  **Migration** (1:1 rename):
+
+  ```graphql
+  # PRZED
+  query Listing {
+    productFilters {
+      matchCount # ❌ removed
+      activeCount
+    }
+  }
+
+  # PO
+  query Listing {
+    productFilters {
+      totalCount # ✅ same semantics, Relay-aligned
+      activeCount
+    }
+  }
+  ```
+
+  ## BREAKING — `ProductFilter.available: true` semantics
+
+  Filter teraz includuje untracked produkty (gift cards, digital, made-to-order — wszystko z `trackQuantity = false`). Semantyka zgodna z `Product.isAvailable` resolver — single source of truth dla "co jest sellable".
+
+  **Pre-fix**: `available: true` zwracał tylko produkty z fizycznym stockiem (`available > 0`), wykluczał untracked. Storefront widział "Dostępne (3)" w sidebar (computed via `isAvailable`), po kliku dostawał 2 produkty (SQL filter różny).
+
+  **Post-fix**: oba źródła zwracają to samo.
+
+  Jeśli polegałeś na exclusion untracked przez `available: true` (np. żeby ukryć gift cards) — użyj `ProductFilter.type` lub osobnej logiki klienckiej.
+
+  ## NEW — `AvailableFilters.availableCount: Int!`
+
+  Nowy boolean facet count — liczba produktów spełniających `Product.isAvailable` w current context. Storefront UI renderuje "Dostępne (N)" w sidebar facet panel.
+
+  Exclude-self: gdy `AvailableFiltersInput.available` jest provided w `currentFilters`, `availableCount` IGNORUJE ten filter (pokazuje "ile produktów ten facet odsłoni gdy włączysz") — inne facets aplikują go normalnie.
+
+  ## NEW — `AvailableFiltersInput.available: Boolean`
+
+  Storefront może passować obecny `available` filter context do `productFilters` query — wymagane dla exclude-self semantyki. Pomiń (null/undefined) gdy filtr "Dostępne" nie jest aktywny w UI.
+
+  ## IMPROVEMENT — Faceted count accuracy (`productCount` mismatch eliminated)
+
+  Per-attribute / per-brand / per-category `productCount` teraz używa exclude-self aggregation pattern. Facet count MATCHUJE `products(filters).totalCount` gdy storefront aplikuje facet jako filter.
+
+  **Pre-fix**: `productFilters({categoryId, available: true}).attributes[producent].filterValues[Funko].productCount = 4` (ignoring `available`), `products({categoryId, available: true, attributes: [Funko]}).totalCount = 3` (3 sellable + 1 OOS Funko). Storefront pokazywał "Funko (4)", user dostawał 3 — utracone zaufanie do countów.
+
+  **Post-fix**: oba zwracają 3. Facet ignoruje WYŁĄCZNIE swój wymiar w `currentFilters`, aplikuje pozostałe + `available` + context (categoryId/collectionId/searchQuery).
+
+  ## IMPROVEMENT — Cart query payload size
+
+  `Cart.lines` query w SDK używał obu form (`edges + nodes`) z których konsumowane były wyłącznie `nodes`. Backend serializował `CartLine` fragment 2× per request. Usunięcie duplikatu — redukcja payload typowo 5-20KB per cart request (proportional do liczby pozycji).
+
+  Brak API change widzialnej dla consumer — SDK używa `cart.lines.nodes` jak wcześniej. Internal SDK improvement.
+
+  ## Example: end-to-end facet sidebar query (post-rename)
+
+  ```graphql
+  query ProductListing($input: AvailableFiltersInput) {
+    productFilters(input: $input) {
+      totalCount # ile produktów w current context (przed faceted filters)
+      availableCount # ile sellable (boolean facet, exclude-self)
+      activeCount # input.currentFilters.length
+      attributes {
+        handle
+        filterValues {
+          value
+          productCount
+        } # per-value facet count (exclude-self per attrDef)
+      }
+      brands {
+        slug
+        name
+        productCount
+      } # per-brand facet count
+      categories {
+        slug
+        name
+        productCount
+      } # per-category facet count
+      priceRange {
+        min {
+          amount
+          currencyCode
+        }
+        max {
+          amount
+          currencyCode
+        }
+      }
+    }
+
+    products(
+      filters: [
+        { available: true }
+        { attributes: [{ attributeId: "producent", values: ["Funko"] }] }
+      ]
+    ) {
+      totalCount
+      nodes {
+        id
+        title
+        isAvailable
+      }
+    }
+  }
+  ```
+
+  Gdy storefront aplikuje "Dostępne + Producent=Funko" jako filter w UI:
+
+  ```graphql
+  variables: {
+    input: {
+      available: true,
+      currentFilters: [{ attributeId: "producent", values: ["Funko"] }]
+    }
+  }
+  ```
+
+  - `availableCount` = liczba sellable Funko w context (ignoring `input.available`, applying `producent: Funko`)
+  - `attributes[producent].filterValues[Funko].productCount` = liczba sellable produktów (ignoring `producent`, applying `available: true`) = `products(filters).totalCount`
+
+### Minor Changes
+
+- e64cfc5: Brand entity available in Storefront API: filter products by canonical brand + read brand details per product.
+
+  **What's new in Storefront API**
+  - **`Product.brand: BrandSummary`** — every product now exposes its canonical brand (when assigned). Returns `{ id, name, slug, logo }` or `null` if the product has no brand. Resolved via DataLoader so listing 50 products incurs at most 1 brand query (no N+1).
+  - **`ProductFilter.brand: BrandFilter`** — new filter input accepting either `{ id: "uuid" }` or `{ slug: "funko" }`. Multiple `brand` entries in `filters[]` use OR semantics. Combine with other filters (price, tags, attributes) using AND across different field names.
+  - **`AvailableFilters.brands: [BrandFilterValue!]!`** — `productFilters` query now returns aggregated brands present in the current product set, each with `productCount`. Build a brand facet (checkbox list or dropdown with logo) directly from this response. Only active brands with at least one product in context are included.
+
+  **Example: brand facet + filter on a listing page**
+
+  ```graphql
+  query Listing {
+    productFilters {
+      brands {
+        id
+        name
+        slug
+        logo
+        productCount
+      }
+    }
+    products(filters: [{ brand: { slug: "funko" } }]) {
+      totalCount
+      nodes {
+        id
+        title
+        brand {
+          name
+          slug
+          logo
+        }
+      }
+    }
+  }
+  ```
+
+  **Migration**
+  - Existing `Product.vendor: String` (legacy free-text) remains supported. New brand-based filtering uses `ProductFilter.brand` instead of `productVendor`.
+  - No breaking changes. All new fields are nullable / optional — queries written before this release continue to work.
+
+  **SDK**
+
+  Regenerated types include `BrandSummary`, `BrandFilter`, `BrandFilterValue`, and `Product.brand`. Import them from `@doswiftly/storefront-operations` schema types.
+
 ## 12.0.0
 
 ### Major Changes

package/README.md

@@ -247,7 +247,7 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `ProductFilters` | Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, or `searchQuery`. For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, per-category counts, `activeCount` (length of `currentFilters` input), and `matchCount` (total products in the context). Use to render filter sidebars on listing/search pages. |
+| `ProductFilters` | Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, `searchQuery`, optional `available` (boolean for the availability facet), and optional `currentFilters` (array of attribute filters currently applied by the UI). For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, `brands`, per-category counts, `activeCount` (length of `currentFilters`), `totalCount` (products in context — Relay-aligned), and `availableCount` (boolean facet count for `availableForSale`). All per-facet counts use exclude-self aggregation: a facet's count IGNORES its own currently-applied filter and APPLIES other filters — so the count reflects "products if this facet were toggled" rather than "products currently visible". Untracked inventory (gift cards, digital, made-to-order) is always counted as available. Use to render filter sidebars on listing/search pages. |
 
 #### Loyalty Program
 
@@ -554,7 +554,7 @@ full executable body of each operation.
 | `AttributeDefinition` | `AttributeDefinition` | Filterable attribute exposed on the storefront — name, type (SELECT / CHECKBOX / SLIDER / etc.), filterability flags, display order, and either discrete `filterValues[]` or numeric `rangeBounds`. Spread inside `availableFilters.attributes[]`. |
 | `PriceRangeFilter` | `PriceRange` | Min / max price range across products in the current listing context. Use to bound the price slider. |
 | `CategoryFilterOption` | `CategoryFilterOption` | One category option in the categories filter — id, name, slug, count of products in this category within the current listing context, level + parentId for tree rendering. |
-| `AvailableFilters` | `AvailableFilters` | Full result of the `productFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars. |
+| `AvailableFilters` | `AvailableFilters` | Full result of the `productFilters($input)` query — attribute filters, price range, category filters, brands, count of currently active filters, total products in context (Relay-aligned `totalCount`), and boolean facet count for `availableForSale` (`availableCount`). Spread on listing pages to render filter sidebars. Per-facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`, `availableCount`) use exclude-self aggregation: when a dimension is in `input.currentFilters` / `input.available`, its own facet count IGNORES that filter (shows "how many products would appear if this facet were toggled"), while OTHER dimensions APPLY their filters. This matches industry convention for accurate facet UX. |
 
 #### Loyalty Program
 

package/fragments.graphql

@@ -1012,7 +1012,7 @@ fragment CategoryFilterOption on CategoryFilterOption {
   parentId
 }
 
-# Full result of the `productFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars.
+# Full result of the `productFilters($input)` query — attribute filters, price range, category filters, brands, count of currently active filters, total products in context (Relay-aligned `totalCount`), and boolean facet count for `availableForSale` (`availableCount`). Spread on listing pages to render filter sidebars. Per-facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`, `availableCount`) use exclude-self aggregation: when a dimension is in `input.currentFilters` / `input.available`, its own facet count IGNORES that filter (shows "how many products would appear if this facet were toggled"), while OTHER dimensions APPLY their filters. This matches industry convention for accurate facet UX.
 fragment AvailableFilters on AvailableFilters {
   attributes {
     ...AttributeDefinition
@@ -1024,7 +1024,8 @@ fragment AvailableFilters on AvailableFilters {
     ...CategoryFilterOption
   }
   activeCount
-  matchCount
+  totalCount
+  availableCount
 }
 
 # ============================================

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **12.0.0**
+> Schema version: **13.0.0**
 > 49 queries · 40 mutations · 100 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
@@ -705,7 +705,7 @@ query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShipp
 
 **Section**: Attribute Filters
 
-**Description**: Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, or `searchQuery`. For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, per-category counts, `activeCount` (length of `currentFilters` input), and `matchCount` (total products in the context). Use to render filter sidebars on listing/search pages.
+**Description**: Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, `searchQuery`, optional `available` (boolean for the availability facet), and optional `currentFilters` (array of attribute filters currently applied by the UI). For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, `brands`, per-category counts, `activeCount` (length of `currentFilters`), `totalCount` (products in context — Relay-aligned), and `availableCount` (boolean facet count for `availableForSale`). All per-facet counts use exclude-self aggregation: a facet's count IGNORES its own currently-applied filter and APPLIES other filters — so the count reflects "products if this facet were toggled" rather than "products currently visible". Untracked inventory (gift cards, digital, made-to-order) is always counted as available. Use to render filter sidebars on listing/search pages.
 
 **Variables**:
 - `$input`: `AvailableFiltersInput`
@@ -3887,7 +3887,7 @@ fragment CategoryFilterOption on CategoryFilterOption {
 
 **Section**: Attribute Filters
 
-**Description**: Full result of the `productFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars.
+**Description**: Full result of the `productFilters($input)` query — attribute filters, price range, category filters, brands, count of currently active filters, total products in context (Relay-aligned `totalCount`), and boolean facet count for `availableForSale` (`availableCount`). Spread on listing pages to render filter sidebars. Per-facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`, `availableCount`) use exclude-self aggregation: when a dimension is in `input.currentFilters` / `input.available`, its own facet count IGNORES that filter (shows "how many products would appear if this facet were toggled"), while OTHER dimensions APPLY their filters. This matches industry convention for accurate facet UX.
 
 **Uses fragments**: `AttributeDefinition`, `CategoryFilterOption`, `PriceRangeFilter`
 
@@ -3904,7 +3904,8 @@ fragment AvailableFilters on AvailableFilters {
     ...CategoryFilterOption
   }
   activeCount
-  matchCount
+  totalCount
+  availableCount
 }
 ```
 

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "12.0.0",
+  "schemaVersion": "13.0.0",
   "queries": [
     {
       "name": "Shop",
@@ -528,7 +528,7 @@
       "name": "ProductFilters",
       "kind": "query",
       "section": "Attribute Filters",
-      "description": "Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, or `searchQuery`. For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, per-category counts, `activeCount` (length of `currentFilters` input), and `matchCount` (total products in the context). Use to render filter sidebars on listing/search pages.",
+      "description": "Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, `searchQuery`, optional `available` (boolean for the availability facet), and optional `currentFilters` (array of attribute filters currently applied by the UI). For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, `brands`, per-category counts, `activeCount` (length of `currentFilters`), `totalCount` (products in context — Relay-aligned), and `availableCount` (boolean facet count for `availableForSale`). All per-facet counts use exclude-self aggregation: a facet's count IGNORES its own currently-applied filter and APPLIES other filters — so the count reflects \"products if this facet were toggled\" rather than \"products currently visible\". Untracked inventory (gift cards, digital, made-to-order) is always counted as available. Use to render filter sidebars on listing/search pages.",
       "variables": [
         {
           "name": "input",
@@ -2557,14 +2557,14 @@
       "name": "AvailableFilters",
       "kind": "fragment",
       "section": "Attribute Filters",
-      "description": "Full result of the `productFilters($input)` query — attribute filters, price range, category filters, count of currently active filters, total products matching the context. Spread on listing pages to render filter sidebars.",
+      "description": "Full result of the `productFilters($input)` query — attribute filters, price range, category filters, brands, count of currently active filters, total products in context (Relay-aligned `totalCount`), and boolean facet count for `availableForSale` (`availableCount`). Spread on listing pages to render filter sidebars. Per-facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`, `availableCount`) use exclude-self aggregation: when a dimension is in `input.currentFilters` / `input.available`, its own facet count IGNORES that filter (shows \"how many products would appear if this facet were toggled\"), while OTHER dimensions APPLY their filters. This matches industry convention for accurate facet UX.",
       "variables": [],
       "fragmentRefs": [
         "AttributeDefinition",
         "CategoryFilterOption",
         "PriceRangeFilter"
       ],
-      "body": "fragment AvailableFilters on AvailableFilters {\n  attributes {\n    ...AttributeDefinition\n  }\n  priceRange {\n    ...PriceRangeFilter\n  }\n  categories {\n    ...CategoryFilterOption\n  }\n  activeCount\n  matchCount\n}",
+      "body": "fragment AvailableFilters on AvailableFilters {\n  attributes {\n    ...AttributeDefinition\n  }\n  priceRange {\n    ...PriceRangeFilter\n  }\n  categories {\n    ...CategoryFilterOption\n  }\n  activeCount\n  totalCount\n  availableCount\n}",
       "onType": "AvailableFilters"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "12.0.0",
+  "version": "13.0.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/queries.graphql

@@ -387,7 +387,7 @@ query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShipp
 # Attribute Filters
 # ============================================
 
-# Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, or `searchQuery`. For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, per-category counts, `activeCount` (length of `currentFilters` input), and `matchCount` (total products in the context). Use to render filter sidebars on listing/search pages.
+# Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, `searchQuery`, optional `available` (boolean for the availability facet), and optional `currentFilters` (array of attribute filters currently applied by the UI). For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, `brands`, per-category counts, `activeCount` (length of `currentFilters`), `totalCount` (products in context — Relay-aligned), and `availableCount` (boolean facet count for `availableForSale`). All per-facet counts use exclude-self aggregation: a facet's count IGNORES its own currently-applied filter and APPLIES other filters — so the count reflects "products if this facet were toggled" rather than "products currently visible". Untracked inventory (gift cards, digital, made-to-order) is always counted as available. Use to render filter sidebars on listing/search pages.
 query ProductFilters($input: AvailableFiltersInput) {
   productFilters(input: $input) {
     ...AvailableFilters

package/schema.graphql

@@ -72,6 +72,11 @@ type AttributeDefinition {
   """Attribute name (e.g., "Color", "Size")"""
   name: String!
 
+  """
+  Faza 3 Opcja A (2026-05-17): opcjonalne grupowanie atrybutu (np. "inventory", "marketing", "content"). NULL = atrybut bez grupy. Pomaga storefront-devom rozpoznać "te atrybuty są custom dane ERP" vs "te są filtrowalne cechy katalogu".
+  """
+  namespace: String
+
   """Range bounds (for NUMBER, CURRENCY)"""
   rangeBounds: AttributeRangeBounds
 
@@ -99,6 +104,11 @@ input AttributeFilterInput {
   """Minimum value (for NUMBER, CURRENCY)"""
   minValue: Float
 
+  """
+  Opcjonalny dyskryminator grupy atrybutów (np. "inventory", "marketing"). Faza 3 Opcja A (2026-05-17): konsolidacja MetaProperty-style custom fields pod AttributeDefinition — namespace pozwala filtrować "Marka z grupy XYZ" gdy multiple shopów ma `Marka` w różnych grupach.
+  """
+  namespace: String
+
   """Text search (for TEXT, TEXTAREA)"""
   textSearch: String
 
@@ -248,34 +258,51 @@ enum AttributeType {
 """Available filters for product listing"""
 type AvailableFilters {
   """
-  Number of currently active filters (renamed from activeFilterCount in Storefront 5.0)
+  Liczba currently applied filters w `currentFilters` (Storefront UI renderuje "Filtry (3)" w sidebar header).
   """
   activeCount: Int!
 
   """Filterable attributes with values"""
   attributes: [AttributeDefinition!]!
 
-  """Categories available for filtering"""
-  categories: [CategoryFilterOption!]
+  """
+  Boolean facet count: liczba produktów w current context spełniających `Product.isAvailable` (przynajmniej jeden aktywny wariant z untracked inventory LUB available>0). Exclude-self: jeśli `available: true` jest w `currentFilters`, count IGNORUJE ten filtr i pokazuje "ile produktów dostępnych w bazowym kontekście" (nie "ile teraz widać"). Spójne semantically z `attributes[].filterValues[].productCount` (per-enum-value facet) i `brands[].productCount` (per-brand facet) — wszystkie używają exclude-self per dimension. Untracked inventory (gift cards, digital, na-zamówienie) zawsze liczy się jako available.
+  """
+  availableCount: Int!
 
   """
-  Total products matching current context, before filters (renamed from totalProducts in Storefront 5.0)
+  Faza 3 (2026-05-17): canonical Brand entities z product counts w current context. Storefront UI renderuje checkbox list / dropdown z logo per brand. Klik → `filters: [{brand: {slug}}]`. Tylko brandy z >0 produktów w current product set + isActive=true.
   """
-  matchCount: Int!
+  brands: [BrandFilterValue!]
+
+  """Categories available for filtering"""
+  categories: [CategoryFilterOption!]
 
   """Price range for filtering"""
   priceRange: PriceRange
+
+  """
+  Total products w current context (categoryId/collectionId/searchQuery) PRZED zaaplikowaniem faceted filters z `currentFilters`. Spójne z `ProductConnection.totalCount` Relay Connection spec — gdy `currentFilters` jest pusty, `AvailableFilters.totalCount` === `products(filters).totalCount`. Użyj do "Wszystkie produkty (N)" w sidebar header.
+  """
+  totalCount: Int!
 }
 
 """Context for available filters query"""
 input AvailableFiltersInput {
+  """
+  Czy filtr "dostępne" jest currently zaaplikowany. Mirror `ProductFilter.available`. Backend używa do exclude-self semantyki: gdy `available: true` (lub `false`) tutaj, `AvailableFilters.availableCount` IGNORUJE ten filtr (pokazuje "ile produktów ten facet odsłoni gdy włączysz"), pozostałe facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`) APLIKUJĄ go (pokazują "ile produktów w obecnym kontekście + tym facet"). Pomiń (null/undefined) gdy storefront nie aplikuje "dostępne" filter.
+  """
+  available: Boolean
+
   """Category ID context (supports comma-separated UUIDs)"""
   categoryId: ID
 
   """Collection ID context (supports comma-separated UUIDs)"""
   collectionId: ID
 
-  """Currently applied filters (to update counts)"""
+  """
+  Currently applied attribute filters (to update facet counts). Per facet `productCount` używa exclude-self pattern: gdy attrId X jest w currentFilters, facet values X.* są liczone IGNORUJĄC X (pokazują "ile produktów dla X=Y w pozostałym kontekście"). Pozostałe attrIds są aplikowane.
+  """
   currentFilters: [AttributeFilterInput!]
 
   """Search query context"""
@@ -598,6 +625,52 @@ type BrandColors {
   secondary: BrandColorGroup
 }
 
+"""Filter products po brand (canonical entity)"""
+input BrandFilter {
+  """Brand ID — exact UUID match"""
+  id: ID
+
+  """
+  Brand slug — URL-friendly identifier. Preferowany over `id` dla storefront refetch (stable po URL share).
+  """
+  slug: String
+}
+
+"""Brand filter value z product count"""
+type BrandFilterValue {
+  """Brand ID"""
+  id: ID!
+
+  """Brand logo URL (UI rendering)"""
+  logo: String
+
+  """Brand name"""
+  name: String!
+
+  """Liczba produktów z tym brandem w current product set"""
+  productCount: Int!
+
+  """Brand slug (refetch payload — paste w ProductFilter.brand.slug)"""
+  slug: String!
+}
+
+"""
+Brand summary — minimalna projekcja dla storefront catalog + filter rendering
+"""
+type BrandSummary {
+  """Brand unique identifier"""
+  id: ID!
+
+  """Brand logo URL (CDN-served, storefront-rendered)"""
+  logo: String
+
+  """Brand display name (e.g. "Funko", "Nintendo")"""
+  name: String!
+
+  """URL-friendly slug — używane dla future /marka/[slug] landing pages"""
+  slug: String!
+}
+
 """Business hours for a day"""
 type BusinessHour {
   """Closing time (HH:MM format)"""
@@ -1904,6 +1977,9 @@ type Customer implements Node {
   """Saved addresses (Relay Connection)"""
   addresses(after: String, before: String, first: Int, last: Int): MailingAddressConnection!
 
+  """Customer custom field values (post-Opcja A unified custom fields)."""
+  attributes(namespace: String): [EntityAttributeField!]!
+
   """Company name (populated for COMPANY type)"""
   companyName: String
 
@@ -1937,16 +2013,6 @@ type Customer implements Node {
   """Last name"""
   lastName: String
 
-  """
-  Lista meta properties (Relay Connection) — opcjonalnie scoped do namespace
-  """
-  metaProperties(first: Int = 10, namespace: String): MetaPropertyConnection!
-
-  """
-  Pojedyncze meta property po (namespace, key) — dla zalogowanego klienta zwraca także private
-  """
-  metaProperty(key: String!, namespace: String!): MetaProperty
-
   """Total orders count (UnsignedInt64 — BigInt-safe)"""
   orderCount: UnsignedInt64!
 
@@ -2347,6 +2413,39 @@ enum EmailMarketingState {
   UNSUBSCRIBED
 }
 
+"""Attribute assignment per entity (polymorphic owner)"""
+type EntityAttributeField {
+  """AttributeDefinition ID"""
+  definitionId: ID!
+
+  """Attribute handle (URL-friendly identifier)"""
+  handle: String!
+
+  """EntityAttribute row ID"""
+  id: ID!
+
+  """
+  Per-entity visibility override (NULL = use AttributeDefinition.isVisible).
+  """
+  isVisibleOverride: Boolean
+
+  """Attribute display name"""
+  name: String!
+
+  """
+  Optional grouping namespace (e.g. "inventory", "marketing"). NULL = ungrouped.
+  """
+  namespace: String
+
+  """Attribute data type"""
+  type: AttributeType!
+
+  """
+  Value serialized as JSON string. Storefront-dev parses according to `type` (TEXT/NUMBER/BOOLEAN/JSON/etc.). Null values serialize as JSON `null`.
+  """
+  value: String!
+}
+
 """Exchange rate between currencies"""
 type ExchangeRate {
   """Source currency code"""
@@ -3269,119 +3368,6 @@ enum MenuItemType {
   SEARCH
 }
 
-"""
-Payload `customerMetaPropertiesSet` — bulk upsert własnych meta properties klienta
-"""
-type MetaPropertiesSetPayload {
-  """Upserted meta properties (puste gdy userErrors)"""
-  metaProperties: [MetaProperty!]!
-
-  """User errors (code z `MetaPropertyErrorCode` enum)"""
-  userErrors: [UserError!]!
-}
-
-"""Pojedyncze pole dodatkowe (meta property) na encji commerce"""
-type MetaProperty implements Node {
-  """Created at"""
-  createdAt: DateTime!
-
-  """Unique identifier"""
-  id: ID!
-
-  """
-  true = readable tylko przez authenticated context (admin/customer self). false (default) = readable również przez anonymous Storefront API.
-  """
-  isPrivate: Boolean!
-
-  """
-  Key w obrębie namespace (3-64 chars). Unique per (ownerType, ownerId, namespace).
-  """
-  key: String!
-
-  """
-  Namespace (3-64 chars). Zapobiega kolizji kluczy między aplikacjami. Reserved prefix: `doswiftly:` (platform).
-  """
-  namespace: String!
-
-  """Typ wartości — informuje klienta jak parse value."""
-  type: MetaPropertyValueType!
-
-  """Last updated at"""
-  updatedAt: DateTime!
-
-  """
-  Wartość — zawsze String. Klient parsuje zgodnie z polem `type` (np. INTEGER → parseInt, JSON → JSON.parse).
-  """
-  value: String!
-}
-
-"""Paginated meta property list (Relay Connection)"""
-type MetaPropertyConnection {
-  """Edges (cursor + node pairs)"""
-  edges: [MetaPropertyEdge!]!
-
-  """Nodes (shortcut bez cursor)"""
-  nodes: [MetaProperty!]!
-
-  """Page info"""
-  pageInfo: PageInfo!
-
-  """Total count (max po wszystkich pages)"""
-  totalCount: Int!
-}
-
-"""Payload `customerMetaPropertyDelete`"""
-type MetaPropertyDeletePayload {
-  """ID usuniętego meta property (null gdy userErrors)"""
-  deletedId: ID
-
-  """User errors (code z `MetaPropertyErrorCode` enum)"""
-  userErrors: [UserError!]!
-}
-
-"""Meta property edge (Relay pagination)"""
-type MetaPropertyEdge {
-  """Cursor for pagination"""
-  cursor: String!
-
-  """Meta property node"""
-  node: MetaProperty!
-}
-
-"""Input dla pojedynczego meta property w bulk set"""
-input MetaPropertyInput {
-  """Visibility — true = admin/customer-only, false = storefront-readable"""
-  isPrivate: Boolean = false
-
-  """Key (3-64 chars)"""
-  key: String!
-
-  """Namespace (3-64 chars, NOT starting with `doswiftly:`)"""
-  namespace: String!
-
-  """Typ wartości (driver walidacji backend-side)"""
-  type: MetaPropertyValueType!
-
-  """Wartość jako String (parse zgodnie z type)"""
-  value: String!
-}
-
-"""
-Typy wartości — STRING (max 255 chars), TEXT (no cap), INTEGER, DECIMAL, BOOLEAN ("true"/"false"), JSON (stringified), DATE (YYYY-MM-DD), DATE_TIME (ISO 8601), URL (http(s)://...), COLOR (#RRGGBB / #RRGGBBAA hex).
-"""
-enum MetaPropertyValueType {
-  BOOLEAN
-  COLOR
-  DATE
-  DATE_TIME
-  DECIMAL
-  INTEGER
-  JSON
-  STRING
-  TEXT
-  URL
-}
-
 """Monetary value with currency"""
 type Money {
   """Decimal money amount"""
@@ -3463,12 +3449,6 @@ type Mutation {
   """Logout customer (clears auth cookie)"""
   customerLogout: CustomerLogoutPayload!
 
-  """Bulk upsert własnych meta properties klienta (Bearer token wymagany)"""
-  customerMetaPropertiesSet(properties: [MetaPropertyInput!]!): MetaPropertiesSetPayload!
-
-  """Usuwa pojedyncze meta property klienta po (namespace, key)"""
-  customerMetaPropertyDelete(key: String!, namespace: String!): MetaPropertyDeletePayload!
-
   """Refresh access token"""
   customerRefreshToken: CustomerRefreshTokenPayload!
 
@@ -3576,6 +3556,9 @@ type Order implements Node {
   """
   accessToken: String!
 
+  """Order custom field values (post-Opcja A unified custom fields)."""
+  attributes(namespace: String): [EntityAttributeField!]!
+
   """Czy storefront może zainicjować płatność dla tego order"""
   canCreatePayment: Boolean!
 
@@ -3602,12 +3585,6 @@ type Order implements Node {
   """
   lineItems(after: String, first: Int = 10): OrderLineItemConnection!
 
-  """Lista meta properties (Relay Connection)"""
-  metaProperties(first: Int = 10, namespace: String): MetaPropertyConnection!
-
-  """Pojedyncze meta property po (namespace, key)"""
-  metaProperty(key: String!, namespace: String!): MetaProperty
-
   """Order number (human-readable)"""
   orderNumber: String!
 
@@ -4014,6 +3991,11 @@ type Product implements Node {
   """Average rating (1-5)"""
   averageRating: Float
 
+  """
+  Canonical brand entity (Faza 3, 2026-05-17). Resolved via DataLoader (N+1 safe dla list queries). Null gdy product nie ma przypisanego brand_id.
+  """
+  brand: BrandSummary
+
   """
   Wszystkie kategorie do których produkt należy (M2M przez ProductCategory junction). Posortowane po junction.sortOrder ASC. Empty list gdy produkt nie jest w żadnej kategorii.
   """
@@ -4056,12 +4038,6 @@ type Product implements Node {
   """
   isPurchasable: Boolean!
 
-  """Lista meta properties — Storefront API filtruje isPrivate=false"""
-  metaProperties(first: Int = 10, namespace: String): MetaPropertyConnection!
-
-  """Pojedyncze meta property — Storefront API filtruje isPrivate=false"""
-  metaProperty(key: String!, namespace: String!): MetaProperty
-
   """
   Per-product option definitions (Color, Size, …) with their available values. Use these to build a variant picker without aggregating `selectedOptions` manually.
   """
@@ -4109,7 +4085,9 @@ type Product implements Node {
   """Product variants (Relay Connection)"""
   variants(after: String, before: String, first: Float, last: Float): ProductVariantConnection!
 
-  """Vendor/brand name"""
+  """
+  Legacy vendor/brand name (free-text). Preferred: `brand` field (canonical Brand entity, Faza 3).
+  """
   vendor: String
 
   """Catalog visibility (Faza 1.5) — PUBLIC | HIDDEN | BUNDLE_ONLY"""
@@ -4245,13 +4223,18 @@ type ProductEdge {
 """Single product filter"""
 input ProductFilter {
   """
-  DoSwiftly: dynamic attribute filters (configurator system). Product/variant metafield filters will be added in Wave 5.
+  DoSwiftly: dynamic attribute filters (configurator + custom fields system). Optional `namespace` w AttributeFilterInput dyskryminuje per grupa atrybutów.
   """
   attributes: [AttributeFilterInput!]
 
   """Filter by availability for sale"""
   available: Boolean
 
+  """
+  Faza 3 (2026-05-17): filter by canonical Brand entity. Wybierz po `slug` (URL-stable) lub `id` (raw UUID). Multiple `brand` entries w `filters[]` array = OR semantics. Vendor (legacy free-text) wciąż wspierany via `productVendor`.
+  """
+  brand: BrandFilter
+
   """Filter by category"""
   category: CategoryFilter
 
@@ -4437,6 +4420,9 @@ enum ProductTypeEnum {
 
 """Product variant - purchasable unit"""
 type ProductVariant {
+  """Variant custom field values (post-Opcja A unified custom fields)."""
+  attributes(namespace: String): [EntityAttributeField!]!
+
   """
   Available stock (computed: stock - reserved). Null when track is disabled.
   """
@@ -4460,12 +4446,6 @@ type ProductVariant {
   """Whether variant is available for purchase"""
   isAvailable: Boolean!
 
-  """Lista meta properties — Storefront API filtruje isPrivate=false"""
-  metaProperties(first: Int = 10, namespace: String): MetaPropertyConnection!
-
-  """Pojedyncze meta property — Storefront API filtruje isPrivate=false"""
-  metaProperty(key: String!, namespace: String!): MetaProperty
-
   """Variant price (Money). Default field — industry-standard schema."""
   price: Money!