@doswiftly/storefront-operations 20.1.0 → 21.0.0

package/AGENTS.md

@@ -27,10 +27,10 @@ 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**: 20.1.0
+- **Schema version**: 21.0.0
 - **Queries**: 52
 - **Mutations**: 44
-- **Fragments**: 104
+- **Fragments**: 105
 <!-- AUTOGEN:STATS:END -->
 
 ## Loading order

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 21.0.0
+
+### Major Changes
+
+- a539021: Product attribute fields renamed and split by purpose (breaking)
+
+  `Product.attributes` now returns the product's **stored custom-field values** — merchant-managed metadata such as manufacturer, licence or material — as `[EntityAttributeField!]!`. Only values marked visible are returned; pass the optional `namespace` argument to fetch a single group.
+
+  The configurator field **definitions** that previously lived under `Product.attributes` have moved to **`Product.configuratorFields(filter: { filledBy: ... })`**, returning `[ConfiguratorField!]!`.
+
+  Renames:
+  - Type `ProductAttributeDefinition` → `ConfiguratorField`, with field renames `fillingMode` → `filledBy`, `billingMode` → `pricingMode`, `isRequired` → `required`, `displayOrder` → `sortOrder`.
+  - Type `ProductAttributeOption` → `ConfiguratorOption`.
+  - Input `ProductAttributeFilterInput` → `ConfiguratorFieldFilterInput` (its `fillingMode` argument → `filledBy`).
+
+  Removed from the public contract: `Product.attributeSetId`; the internal `scopeProductId` and `taxClassId` on configurator fields; and the raw `linkedVariantId` on a configurator option (read `linkedVariant.id` instead).
+
+  Migration: rename `attributes(filter: { fillingMode })` selections to `configuratorFields(filter: { filledBy })` and spread `...ConfiguratorField`; use the new `attributes` field (optional `namespace`) to read product metadata values.
+
+## 20.2.0
+
+### Minor Changes
+
+- 17fedcf: Addresses now carry a structured building / flat number alongside the free-form street line.
+
+  **Why**: Polish addresses — and carriers like InPost as well as VAT invoicing — need the building number as a discrete field rather than mixed into a single street line (e.g. `"ul. Piękna 5/3"` must split into building `5`, flat `3`). The `MailingAddress` type and the cart / mailing address inputs now expose `buildingNumber` and `flatNumber` so storefronts can collect and display them precisely.
+
+  **Additive (backward-compatible)**:
+  1. `MailingAddress` (read) gains `buildingNumber` and `flatNumber` — populated on cart, order and saved customer addresses; `null` when only the free-form line was provided.
+  2. The address inputs (`CartAddressInput`, `MailingAddressInput`) accept optional `buildingNumber` and `flatNumber`. For a Polish street delivery without a pickup point the building number is now required server-side — omitting it returns a `BUILDING_NUMBER_REQUIRED` user error instead of silently guessing it from the street text.
+
+  **Usage example**:
+
+  ```ts
+  await cartSetShippingAddress({
+    cartId,
+    address: {
+      streetLine1: "ul. Piękna 5/3",
+      buildingNumber: "5",
+      flatNumber: "3",
+      city: "Warszawa",
+      postalCode: "00-001",
+      country: "PL",
+    },
+  });
+
+  // reading it back
+  const { buildingNumber, flatNumber } = order.shippingAddress;
+  ```
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Add a `buildingNumber` (and optional `flatNumber`) field to your address forms.
+  - [ ] For Polish street addresses, send `buildingNumber`, or handle the `BUILDING_NUMBER_REQUIRED` user error returned by the cart address mutations.
+  - [ ] Optionally render `buildingNumber` / `flatNumber` when displaying saved or order addresses.
+
 ## 20.1.0
 
 ### Minor Changes

package/README.md

@@ -170,7 +170,7 @@ full executable body of each operation.
 | Operation | Description |
 | --- | --- |
 | `Product` | Fetches a single product by `id` or `handle` (URL-friendly identifier). Pass either — whichever is provided wins; if both are missing, returns null. Returns null if the product is not storefront-accessible (must be `ACTIVE` status with `PUBLIC` or `BUNDLE_ONLY` visibility). |
-| `ProductConfigurator` | Fetches a product together with its filtered attribute definitions, optimized for the configurator UI (e.g. customer-facing text fields, finishing options, scoped variants). `fillingMode: "CUSTOMER"` returns only customer-facing attributes; pass `"BOTH"` to also include attributes shared with the merchant admin. Single round-trip — saves a separate `attributes` query. |
+| `ProductConfigurator` | Fetches a product together with its configurator fields, optimized for the product-page configurator UI. filledBy CUSTOMER returns only the fields a shopper edits; pass BOTH to also include seller-prefilled fields. Single round-trip. |
 | `Products` | Paginated product list (Relay Connection, default page size 20, max 100). The `query` argument supports a structured search syntax — `tag:summer`, `vendor:foo`, `product_type:shirts`, `variants.price:>10`, plus `AND`/`OR`/`NOT` — falling back to free-text title/content search. The `filters[]` array uses multi-filter logic: same field name appears multiple times → OR; different fields → AND. Sort: `RELEVANCE`, `TITLE`, `PRICE`, `NEWEST`, `OLDEST`, `BEST_SELLING`. The response includes a `filters` block for faceted navigation (counts per filterable attribute value). |
 | `ProductSearch` | Full-text product search — `$query` is required. Functionally equivalent to `Products` with `$query` set, minus the `sortKey` argument (search defaults to relevance ranking). Use for the search results page; combine with `filters[]` for guided refinement. |
 | `SearchSuggestions` | Type-ahead suggestions for the storefront search input. Returns up to `$limit` matching products (hard cap 50) plus up to 5 styled query suggestions with `<mark>` tags around matched spans. Polish-language aware (handles morphology in suggestions). Run on each keystroke (debounce 200-300ms). The `$query` is capped at 100 characters server-side. |
@@ -638,13 +638,19 @@ full executable body of each operation.
 | --- | --- | --- |
 | `UrlRedirect` | `UrlRedirect` | Single legacy `path` → new `target` redirect entry. Use on the server / edge to issue 301 redirects for migrated routes. |
 
-#### Product Configurator (per-product attributes)
+#### Product Attributes (stored metadata values)
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `LinkedVariantSummary` | `LinkedVariantSummary` | Slim variant snapshot linked from a configurator option — when an attribute option (e.g. "256 GB" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ProductAttributeOption.linkedVariant`. |
-| `ProductAttributeOption` | `ProductAttributeOption` | One option (choice) within a configurator attribute — value, label, sort order, optional color hex, surcharge (amount + type), default flag, optional linked variant for variant-mapped options. |
-| `ProductAttributeDefinition` | `ProductAttributeDefinition` | Configurator attribute definition — name, type, fillingMode (CUSTOMER / MERCHANT / BOTH), billingMode, tax class, validation bounds, options (for choice-type attributes), required + visibility flags. Returned by `product.attributes(filter)` for the configurator UI. |
+| `AttributeValue` | `EntityAttributeField` | A stored custom-field value on a product (or variant / customer / order) - merchant-managed metadata exposed via the `attributes` field. Parse `value` (a JSON string) according to `type`. |
+
+#### Product Configurator (per-product fields)
+
+| Fragment | On Type | Description |
+| --- | --- | --- |
+| `LinkedVariantSummary` | `LinkedVariantSummary` | Slim variant snapshot linked from a configurator choice — when an option (e.g. "256 GB" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ConfiguratorOption.linkedVariant`. |
+| `ConfiguratorOption` | `ConfiguratorOption` | One selectable choice within a configurator field - value, label, sort order, optional colour, surcharge (amount + type), default flag, and the linked stocked variant for component-style choices. |
+| `ConfiguratorField` | `ConfiguratorField` | A configurator field on the product page - label, input type, who fills it (filledBy), pricing behaviour (pricingMode), validation bounds, required + visibility flags, and selectable options for choice-type fields. |
 <!-- AUTOGEN:FRAGMENTS:END -->
 
 For full operation signatures with typed variables, GraphQL bodies and

package/fragments.graphql

@@ -155,7 +155,9 @@ fragment ProductBase on Product {
   stockTotal
   type
   visibility
-  attributeSetId
+  attributes {
+    ...AttributeValue
+  }
   createdAt
   updatedAt
 }
@@ -257,6 +259,8 @@ fragment MailingAddress on MailingAddress {
   id
   streetLine1
   streetLine2
+  buildingNumber
+  flatNumber
   city
   company
   country
@@ -1630,10 +1634,26 @@ fragment UrlRedirect on UrlRedirect {
 }
 
 # ============================================
-# Product Configurator (per-product attributes)
+# Product Attributes (stored metadata values)
+# ============================================
+
+# A stored custom-field value on a product (or variant / customer / order) - merchant-managed metadata exposed via the `attributes` field. Parse `value` (a JSON string) according to `type`.
+fragment AttributeValue on EntityAttributeField {
+  id
+  definitionId
+  handle
+  name
+  namespace
+  type
+  value
+  isVisibleOverride
+}
+
+# ============================================
+# Product Configurator (per-product fields)
 # ============================================
 
-# Slim variant snapshot linked from a configurator option — when an attribute option (e.g. "256 GB" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ProductAttributeOption.linkedVariant`.
+# Slim variant snapshot linked from a configurator choice — when an option (e.g. "256 GB" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ConfiguratorOption.linkedVariant`.
 fragment LinkedVariantSummary on LinkedVariantSummary {
   id
   productId
@@ -1644,8 +1664,8 @@ fragment LinkedVariantSummary on LinkedVariantSummary {
   trackQuantity
 }
 
-# One option (choice) within a configurator attribute — value, label, sort order, optional color hex, surcharge (amount + type), default flag, optional linked variant for variant-mapped options.
-fragment ProductAttributeOption on ProductAttributeOption {
+# One selectable choice within a configurator field - value, label, sort order, optional colour, surcharge (amount + type), default flag, and the linked stocked variant for component-style choices.
+fragment ConfiguratorOption on ConfiguratorOption {
   id
   value
   label
@@ -1654,29 +1674,26 @@ fragment ProductAttributeOption on ProductAttributeOption {
   surchargeAmount
   surchargeType
   isDefault
-  linkedVariantId
   linkedVariant {
     ...LinkedVariantSummary
   }
 }
 
-# Configurator attribute definition — name, type, fillingMode (CUSTOMER / MERCHANT / BOTH), billingMode, tax class, validation bounds, options (for choice-type attributes), required + visibility flags. Returned by `product.attributes(filter)` for the configurator UI.
-fragment ProductAttributeDefinition on ProductAttributeDefinition {
+# A configurator field on the product page - label, input type, who fills it (filledBy), pricing behaviour (pricingMode), validation bounds, required + visibility flags, and selectable options for choice-type fields.
+fragment ConfiguratorField on ConfiguratorField {
   id
   name
   handle
   description
   type
-  fillingMode
-  billingMode
-  taxClassId
-  scopeProductId
-  isRequired
+  filledBy
+  pricingMode
+  required
   isVisible
-  displayOrder
+  sortOrder
   minValue
   maxValue
   options {
-    ...ProductAttributeOption
+    ...ConfiguratorOption
   }
 }

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **20.1.0**
-> 52 queries · 44 mutations · 104 fragments
+> Schema version: **21.0.0**
+> 52 queries · 44 mutations · 105 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
 regenerated on every release to match the published schema.
@@ -81,21 +81,21 @@ query Product($id: ID, $handle: String) {
 
 **Section**: Products
 
-**Description**: Fetches a product together with its filtered attribute definitions, optimized for the configurator UI (e.g. customer-facing text fields, finishing options, scoped variants). `fillingMode: "CUSTOMER"` returns only customer-facing attributes; pass `"BOTH"` to also include attributes shared with the merchant admin. Single round-trip — saves a separate `attributes` query.
+**Description**: Fetches a product together with its configurator fields, optimized for the product-page configurator UI. filledBy CUSTOMER returns only the fields a shopper edits; pass BOTH to also include seller-prefilled fields. Single round-trip.
 
 **Variables**:
 - `$handle`: `String!`
-- `$fillingMode`: `AttributeFillingMode` *(default: `CUSTOMER`)*
+- `$filledBy`: `AttributeFillingMode` *(default: `CUSTOMER`)*
 
-**Fragments used**: `ProductAttributeDefinition`, `ProductFull`
+**Fragments used**: `ConfiguratorField`, `ProductFull`
 
 **GraphQL**:
 ```graphql
-query ProductConfigurator($handle: String!, $fillingMode: AttributeFillingMode = CUSTOMER) {
+query ProductConfigurator($handle: String!, $filledBy: AttributeFillingMode = CUSTOMER) {
   product(handle: $handle) {
     ...ProductFull
-    attributes(filter: {fillingMode: $fillingMode}) {
-      ...ProductAttributeDefinition
+    configuratorFields(filter: {filledBy: $filledBy}) {
+      ...ConfiguratorField
     }
   }
 }
@@ -2788,7 +2788,7 @@ fragment ProductCard on Product {
 
 **Description**: `ProductCard` plus textual content (description, descriptionHtml), stock total, type, visibility flags, and timestamps. Use when you need full product copy but not the heavy variants/images lists. Sweet spot for blog post embeds, related-product cards with description.
 
-**Uses fragments**: `ProductCard`
+**Uses fragments**: `AttributeValue`, `ProductCard`
 
 **GraphQL**:
 ```graphql
@@ -2799,7 +2799,9 @@ fragment ProductBase on Product {
   stockTotal
   type
   visibility
-  attributeSetId
+  attributes {
+    ...AttributeValue
+  }
   createdAt
   updatedAt
 }
@@ -2937,6 +2939,8 @@ fragment MailingAddress on MailingAddress {
   id
   streetLine1
   streetLine2
+  buildingNumber
+  flatNumber
   city
   company
   country
@@ -5078,11 +5082,31 @@ fragment UrlRedirect on UrlRedirect {
 }
 ```
 
+### Fragment: `AttributeValue` on `EntityAttributeField`
+
+**Section**: Product Attributes (stored metadata values)
+
+**Description**: A stored custom-field value on a product (or variant / customer / order) - merchant-managed metadata exposed via the `attributes` field. Parse `value` (a JSON string) according to `type`.
+
+**GraphQL**:
+```graphql
+fragment AttributeValue on EntityAttributeField {
+  id
+  definitionId
+  handle
+  name
+  namespace
+  type
+  value
+  isVisibleOverride
+}
+```
+
 ### Fragment: `LinkedVariantSummary` on `LinkedVariantSummary`
 
-**Section**: Product Configurator (per-product attributes)
+**Section**: Product Configurator (per-product fields)
 
-**Description**: Slim variant snapshot linked from a configurator option — when an attribute option (e.g. "256 GB" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ProductAttributeOption.linkedVariant`.
+**Description**: Slim variant snapshot linked from a configurator choice — when an option (e.g. "256 GB" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ConfiguratorOption.linkedVariant`.
 
 **GraphQL**:
 ```graphql
@@ -5097,17 +5121,17 @@ fragment LinkedVariantSummary on LinkedVariantSummary {
 }
 ```
 
-### Fragment: `ProductAttributeOption` on `ProductAttributeOption`
+### Fragment: `ConfiguratorOption` on `ConfiguratorOption`
 
-**Section**: Product Configurator (per-product attributes)
+**Section**: Product Configurator (per-product fields)
 
-**Description**: One option (choice) within a configurator attribute — value, label, sort order, optional color hex, surcharge (amount + type), default flag, optional linked variant for variant-mapped options.
+**Description**: One selectable choice within a configurator field - value, label, sort order, optional colour, surcharge (amount + type), default flag, and the linked stocked variant for component-style choices.
 
 **Uses fragments**: `LinkedVariantSummary`
 
 **GraphQL**:
 ```graphql
-fragment ProductAttributeOption on ProductAttributeOption {
+fragment ConfiguratorOption on ConfiguratorOption {
   id
   value
   label
@@ -5116,40 +5140,37 @@ fragment ProductAttributeOption on ProductAttributeOption {
   surchargeAmount
   surchargeType
   isDefault
-  linkedVariantId
   linkedVariant {
     ...LinkedVariantSummary
   }
 }
 ```
 
-### Fragment: `ProductAttributeDefinition` on `ProductAttributeDefinition`
+### Fragment: `ConfiguratorField` on `ConfiguratorField`
 
-**Section**: Product Configurator (per-product attributes)
+**Section**: Product Configurator (per-product fields)
 
-**Description**: Configurator attribute definition — name, type, fillingMode (CUSTOMER / MERCHANT / BOTH), billingMode, tax class, validation bounds, options (for choice-type attributes), required + visibility flags. Returned by `product.attributes(filter)` for the configurator UI.
+**Description**: A configurator field on the product page - label, input type, who fills it (filledBy), pricing behaviour (pricingMode), validation bounds, required + visibility flags, and selectable options for choice-type fields.
 
-**Uses fragments**: `ProductAttributeOption`
+**Uses fragments**: `ConfiguratorOption`
 
 **GraphQL**:
 ```graphql
-fragment ProductAttributeDefinition on ProductAttributeDefinition {
+fragment ConfiguratorField on ConfiguratorField {
   id
   name
   handle
   description
   type
-  fillingMode
-  billingMode
-  taxClassId
-  scopeProductId
-  isRequired
+  filledBy
+  pricingMode
+  required
   isVisible
-  displayOrder
+  sortOrder
   minValue
   maxValue
   options {
-    ...ProductAttributeOption
+    ...ConfiguratorOption
   }
 }
 ```

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "20.1.0",
+  "schemaVersion": "21.0.0",
   "queries": [
     {
       "name": "Shop",
@@ -49,7 +49,7 @@
       "name": "ProductConfigurator",
       "kind": "query",
       "section": "Products",
-      "description": "Fetches a product together with its filtered attribute definitions, optimized for the configurator UI (e.g. customer-facing text fields, finishing options, scoped variants). `fillingMode: \"CUSTOMER\"` returns only customer-facing attributes; pass `\"BOTH\"` to also include attributes shared with the merchant admin. Single round-trip — saves a separate `attributes` query.",
+      "description": "Fetches a product together with its configurator fields, optimized for the product-page configurator UI. filledBy CUSTOMER returns only the fields a shopper edits; pass BOTH to also include seller-prefilled fields. Single round-trip.",
       "variables": [
         {
           "name": "handle",
@@ -57,16 +57,16 @@
           "defaultValue": null
         },
         {
-          "name": "fillingMode",
+          "name": "filledBy",
           "type": "AttributeFillingMode",
           "defaultValue": "CUSTOMER"
         }
       ],
       "fragmentRefs": [
-        "ProductAttributeDefinition",
+        "ConfiguratorField",
         "ProductFull"
       ],
-      "body": "query ProductConfigurator($handle: String!, $fillingMode: AttributeFillingMode = CUSTOMER) {\n  product(handle: $handle) {\n    ...ProductFull\n    attributes(filter: {fillingMode: $fillingMode}) {\n      ...ProductAttributeDefinition\n    }\n  }\n}"
+      "body": "query ProductConfigurator($handle: String!, $filledBy: AttributeFillingMode = CUSTOMER) {\n  product(handle: $handle) {\n    ...ProductFull\n    configuratorFields(filter: {filledBy: $filledBy}) {\n      ...ConfiguratorField\n    }\n  }\n}"
     },
     {
       "name": "Products",
@@ -2054,9 +2054,10 @@
       "description": "`ProductCard` plus textual content (description, descriptionHtml), stock total, type, visibility flags, and timestamps. Use when you need full product copy but not the heavy variants/images lists. Sweet spot for blog post embeds, related-product cards with description.",
       "variables": [],
       "fragmentRefs": [
+        "AttributeValue",
         "ProductCard"
       ],
-      "body": "fragment ProductBase on Product {\n  ...ProductCard\n  description\n  descriptionHtml\n  stockTotal\n  type\n  visibility\n  attributeSetId\n  createdAt\n  updatedAt\n}",
+      "body": "fragment ProductBase on Product {\n  ...ProductCard\n  description\n  descriptionHtml\n  stockTotal\n  type\n  visibility\n  attributes {\n    ...AttributeValue\n  }\n  createdAt\n  updatedAt\n}",
       "onType": "Product"
     },
     {
@@ -2117,7 +2118,7 @@
       "fragmentRefs": [
         "PickupPoint"
       ],
-      "body": "fragment MailingAddress on MailingAddress {\n  id\n  streetLine1\n  streetLine2\n  city\n  company\n  country\n  countryCode\n  firstName\n  lastName\n  name\n  phone\n  state\n  stateCode\n  postalCode\n  isDefault\n  taxId\n  vatNumber\n  regon\n  pickupPoint {\n    ...PickupPoint\n  }\n}",
+      "body": "fragment MailingAddress on MailingAddress {\n  id\n  streetLine1\n  streetLine2\n  buildingNumber\n  flatNumber\n  city\n  company\n  country\n  countryCode\n  firstName\n  lastName\n  name\n  phone\n  state\n  stateCode\n  postalCode\n  isDefault\n  taxId\n  vatNumber\n  regon\n  pickupPoint {\n    ...PickupPoint\n  }\n}",
       "onType": "MailingAddress"
     },
     {
@@ -3109,39 +3110,49 @@
       "body": "fragment UrlRedirect on UrlRedirect {\n  path\n  target\n}",
       "onType": "UrlRedirect"
     },
+    {
+      "name": "AttributeValue",
+      "kind": "fragment",
+      "section": "Product Attributes (stored metadata values)",
+      "description": "A stored custom-field value on a product (or variant / customer / order) - merchant-managed metadata exposed via the `attributes` field. Parse `value` (a JSON string) according to `type`.",
+      "variables": [],
+      "fragmentRefs": [],
+      "body": "fragment AttributeValue on EntityAttributeField {\n  id\n  definitionId\n  handle\n  name\n  namespace\n  type\n  value\n  isVisibleOverride\n}",
+      "onType": "EntityAttributeField"
+    },
     {
       "name": "LinkedVariantSummary",
       "kind": "fragment",
-      "section": "Product Configurator (per-product attributes)",
-      "description": "Slim variant snapshot linked from a configurator option — when an attribute option (e.g. \"256 GB\" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ProductAttributeOption.linkedVariant`.",
+      "section": "Product Configurator (per-product fields)",
+      "description": "Slim variant snapshot linked from a configurator choice — when an option (e.g. \"256 GB\" storage) maps to a specific variant, this fragment exposes that variant's id, title, sku, stock flags. Spread inside `ConfiguratorOption.linkedVariant`.",
       "variables": [],
       "fragmentRefs": [],
       "body": "fragment LinkedVariantSummary on LinkedVariantSummary {\n  id\n  productId\n  title\n  sku\n  availableStock\n  isAvailable\n  trackQuantity\n}",
       "onType": "LinkedVariantSummary"
     },
     {
-      "name": "ProductAttributeOption",
+      "name": "ConfiguratorOption",
       "kind": "fragment",
-      "section": "Product Configurator (per-product attributes)",
-      "description": "One option (choice) within a configurator attribute — value, label, sort order, optional color hex, surcharge (amount + type), default flag, optional linked variant for variant-mapped options.",
+      "section": "Product Configurator (per-product fields)",
+      "description": "One selectable choice within a configurator field - value, label, sort order, optional colour, surcharge (amount + type), default flag, and the linked stocked variant for component-style choices.",
       "variables": [],
       "fragmentRefs": [
         "LinkedVariantSummary"
       ],
-      "body": "fragment ProductAttributeOption on ProductAttributeOption {\n  id\n  value\n  label\n  sortOrder\n  colorHex\n  surchargeAmount\n  surchargeType\n  isDefault\n  linkedVariantId\n  linkedVariant {\n    ...LinkedVariantSummary\n  }\n}",
-      "onType": "ProductAttributeOption"
+      "body": "fragment ConfiguratorOption on ConfiguratorOption {\n  id\n  value\n  label\n  sortOrder\n  colorHex\n  surchargeAmount\n  surchargeType\n  isDefault\n  linkedVariant {\n    ...LinkedVariantSummary\n  }\n}",
+      "onType": "ConfiguratorOption"
     },
     {
-      "name": "ProductAttributeDefinition",
+      "name": "ConfiguratorField",
       "kind": "fragment",
-      "section": "Product Configurator (per-product attributes)",
-      "description": "Configurator attribute definition — name, type, fillingMode (CUSTOMER / MERCHANT / BOTH), billingMode, tax class, validation bounds, options (for choice-type attributes), required + visibility flags. Returned by `product.attributes(filter)` for the configurator UI.",
+      "section": "Product Configurator (per-product fields)",
+      "description": "A configurator field on the product page - label, input type, who fills it (filledBy), pricing behaviour (pricingMode), validation bounds, required + visibility flags, and selectable options for choice-type fields.",
       "variables": [],
       "fragmentRefs": [
-        "ProductAttributeOption"
+        "ConfiguratorOption"
       ],
-      "body": "fragment ProductAttributeDefinition on ProductAttributeDefinition {\n  id\n  name\n  handle\n  description\n  type\n  fillingMode\n  billingMode\n  taxClassId\n  scopeProductId\n  isRequired\n  isVisible\n  displayOrder\n  minValue\n  maxValue\n  options {\n    ...ProductAttributeOption\n  }\n}",
-      "onType": "ProductAttributeDefinition"
+      "body": "fragment ConfiguratorField on ConfiguratorField {\n  id\n  name\n  handle\n  description\n  type\n  filledBy\n  pricingMode\n  required\n  isVisible\n  sortOrder\n  minValue\n  maxValue\n  options {\n    ...ConfiguratorOption\n  }\n}",
+      "onType": "ConfiguratorField"
     }
   ]
 }

package/package.json

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

package/queries.graphql

@@ -32,12 +32,12 @@ query Product($id: ID, $handle: String) {
   }
 }
 
-# Fetches a product together with its filtered attribute definitions, optimized for the configurator UI (e.g. customer-facing text fields, finishing options, scoped variants). `fillingMode: "CUSTOMER"` returns only customer-facing attributes; pass `"BOTH"` to also include attributes shared with the merchant admin. Single round-trip — saves a separate `attributes` query.
-query ProductConfigurator($handle: String!, $fillingMode: AttributeFillingMode = CUSTOMER) {
+# Fetches a product together with its configurator fields, optimized for the product-page configurator UI. filledBy CUSTOMER returns only the fields a shopper edits; pass BOTH to also include seller-prefilled fields. Single round-trip.
+query ProductConfigurator($handle: String!, $filledBy: AttributeFillingMode = CUSTOMER) {
   product(handle: $handle) {
     ...ProductFull
-    attributes(filter: { fillingMode: $fillingMode }) {
-      ...ProductAttributeDefinition
+    configuratorFields(filter: { filledBy: $filledBy }) {
+      ...ConfiguratorField
     }
   }
 }

package/schema.graphql

@@ -44,7 +44,7 @@ type Attribute {
 }
 
 """
-How attribute surcharge affects pricing: BUNDLED (in unitPrice) or SEPARATE_LINE (own OrderItem)
+How an option surcharge is billed: BUNDLED (added into the product price — a single line) or SEPARATE_LINE (shown as its own order line, which may carry its own tax rate).
 """
 enum AttributeBillingMode {
   BUNDLED
@@ -89,7 +89,7 @@ type AttributeDefinition {
 }
 
 """
-Who fills the attribute value: MERCHANT (admin on product), CUSTOMER (in cart), or BOTH
+Who provides the value: MERCHANT (set by the seller — product metadata, not shown as an editable field), CUSTOMER (entered or chosen by the shopper in the configurator), or BOTH (seller sets a default the shopper can change).
 """
 enum AttributeFillingMode {
   BOTH
@@ -1049,6 +1049,11 @@ type CartAddLinesPayload {
 Mailing address used as the shipping or billing address on a cart. Carries an optional pickup point (for parcel locker / collection-point delivery) and optional B2B fields (`taxId`, `vatNumber`, `regon`).
 """
 input CartAddressInput {
+  """
+  Building / house number as a discrete field, overlaid on `streetLine1`. Required for delivery and billing addresses in Poland (`country: PL`) without a `pickupPoint` — carriers (e.g. InPost) and invoicing need the building number split out from the street name.
+  """
+  buildingNumber: String
+
   """City"""
   city: String!
 
@@ -1061,6 +1066,11 @@ input CartAddressInput {
   """First name"""
   firstName: String
 
+  """
+  Flat / apartment number as a discrete field — optional companion to `buildingNumber`.
+  """
+  flatNumber: String
+
   """Last name"""
   lastName: String
 
@@ -2157,6 +2167,106 @@ enum CompensationType {
   STORE_CREDIT
 }
 
+"""
+A single field of a product configurator — an input the shopper sees on the product page.
+"""
+type ConfiguratorField {
+  """Optional help text shown beneath the field."""
+  description: String
+
+  """
+  Who provides the value — CUSTOMER (the shopper fills it in) or BOTH (seller sets a default the shopper can change). Seller-only metadata fields are not returned here.
+  """
+  filledBy: AttributeFillingMode!
+
+  """URL-friendly key for the field."""
+  handle: String!
+
+  """Stable identifier of this field."""
+  id: ID!
+
+  """Whether this field should be shown on the storefront."""
+  isVisible: Boolean!
+
+  """Upper bound — maximum value (NUMBER) or maximum length (TEXT)."""
+  maxValue: Float
+
+  """Lower bound — minimum value (NUMBER) or minimum length (TEXT)."""
+  minValue: Float
+
+  """Field label shown to the shopper (e.g. "Finish")."""
+  name: String!
+
+  """
+  Selectable choices for SELECT / RADIO / CHECKBOX fields; empty for free-input types (TEXT, NUMBER, …).
+  """
+  options: [ConfiguratorOption!]!
+
+  """
+  If a choice adds cost, how it is billed — BUNDLED (folded into the product price) or SEPARATE_LINE (its own order line). Null when the field has no price impact.
+  """
+  pricingMode: AttributeBillingMode
+
+  """
+  Whether the shopper must provide a value before adding the product to the cart.
+  """
+  required: Boolean!
+
+  """Order in which to render this field."""
+  sortOrder: Int!
+
+  """
+  Input type — controls how to render the field (TEXT, TEXTAREA, SELECT, RADIO, CHECKBOX, NUMBER, COLOR, …).
+  """
+  type: AttributeType!
+}
+
+"""Filter for the configuratorFields query."""
+input ConfiguratorFieldFilterInput {
+  """
+  Return only fields with this filledBy value. The storefront configurator typically requests CUSTOMER + BOTH (the fields a shopper can edit).
+  """
+  filledBy: AttributeFillingMode
+}
+
+"""
+A selectable choice within a product configurator field (e.g. a size, finish or add-on).
+"""
+type ConfiguratorOption {
+  """Hex colour for swatch rendering (COLOR fields)."""
+  colorHex: String
+
+  """Stable identifier of this choice."""
+  id: ID!
+
+  """Whether this choice is pre-selected by default."""
+  isDefault: Boolean!
+
+  """Human-readable label shown to the shopper."""
+  label: String!
+
+  """
+  The stocked variant this choice maps to (used for inventory-backed components). Null when the choice maps to no variant or the variant no longer exists.
+  """
+  linkedVariant: LinkedVariantSummary
+
+  """Order in which to render this choice."""
+  sortOrder: Int!
+
+  """
+  Extra charge applied when this choice is selected. With surchargeType FIXED it is an amount in minor currency units (e.g. 500 = 5.00). With PERCENT it is thousandths of a percent (e.g. 1500 = 1.5%).
+  """
+  surchargeAmount: Int
+
+  """How to interpret surchargeAmount — FIXED (a money amount) or PERCENT."""
+  surchargeType: AttributeOptionSurchargeType
+
+  """
+  Machine value (slug-style) — use it for form state and when submitting the choice to the cart.
+  """
+  value: String!
+}
+
 """Format of stored content (HTML or MARKDOWN)"""
 enum ContentFormat {
   HTML
@@ -3445,7 +3555,7 @@ enum LanguageDirection {
 }
 
 """
-Summary of a ProductVariant linked to an AttributeOption (product configurator).
+Summary of the stocked ProductVariant a configurator option maps to (component-style choice). Exposed via `ConfiguratorOption.linkedVariant`.
 """
 type LinkedVariantSummary {
   """Available stock (stock − active reservations, always ≥ 0)."""
@@ -3836,6 +3946,11 @@ enum LoyaltyTransactionType {
 A mailing address — shipping or billing — used on a cart, on the resulting order, or saved in a customer address book. Carries optional B2B fields (`taxId`, `vatNumber`, `regon`) and an optional `pickupPoint` for parcel locker / collection-point delivery.
 """
 type MailingAddress implements Node {
+  """
+  Building / house number as a discrete field, overlaid on `streetLine1`. Populated for structured addresses (required for PL delivery / billing without a pickup point); null when only the free-form `streetLine1` was provided.
+  """
+  buildingNumber: String
+
   """City / town."""
   city: String
 
@@ -3853,6 +3968,11 @@ type MailingAddress implements Node {
   """Buyer first name."""
   firstName: String
 
+  """
+  Flat / apartment number as a discrete field — optional companion to `buildingNumber`.
+  """
+  flatNumber: String
+
   """
   Country-aware ordered address lines, ready to render line by line in UI without manual formatting. The exact line layout depends on country (e.g. PL puts postal code before city, US after state).
   """
@@ -3944,6 +4064,11 @@ type MailingAddressEdge {
 
 """Input for mailing address"""
 input MailingAddressInput {
+  """
+  Building / house number as a discrete field, overlaid on `streetLine1`. Required for saved Polish addresses (`country: PL`) — used for carrier delivery and invoicing.
+  """
+  buildingNumber: String
+
   """City"""
   city: String
 
@@ -3956,6 +4081,11 @@ input MailingAddressInput {
   """First name"""
   firstName: String
 
+  """
+  Flat / apartment number as a discrete field — optional companion to `buildingNumber`.
+  """
+  flatNumber: String
+
   """Last name"""
   lastName: String
 
@@ -5243,18 +5373,15 @@ type PricingTier {
 
 """Product - main catalog item"""
 type Product implements Node {
-  """Assigned AttributeSet ID (shared template fields)"""
-  attributeSetId: ID
-
   """
-  Customer-facing product attributes (configurator) — set definitions + per-product scoped
+  This product's stored custom-field values — merchant-managed metadata such as manufacturer, licence, material or EAN. Only fields the merchant marked visible are returned. Pass `namespace` to fetch a single group.
   """
   attributes(
     """
-    Optional filter — pass `{ fillingMode: CUSTOMER }` to return only buyer-fillable configurator fields
+    Optional group filter — return only attributes in this namespace (e.g. "specs").
     """
-    filter: ProductAttributeFilterInput
-  ): [ProductAttributeDefinition!]!
+    namespace: String
+  ): [EntityAttributeField!]!
 
   """Average rating (1-5)"""
   averageRating: Float
@@ -5277,6 +5404,16 @@ type Product implements Node {
   """Opt-in: compare-at price range with conversion transparency."""
   compareAtPriceRangeWithConversion: ConvertedPriceRange
 
+  """
+  Configurable fields shown on the product page for the shopper to fill in or choose (combines shared template fields and product-specific ones). Pass `{ filledBy: CUSTOMER }` to return only the fields a shopper can edit.
+  """
+  configuratorFields(
+    """
+    Optional filter — pass `{ filledBy: CUSTOMER }` to return only the fields a shopper can edit.
+    """
+    filter: ConfiguratorFieldFilterInput
+  ): [ConfiguratorField!]!
+
   """Creation timestamp"""
   createdAt: DateTime!
 
@@ -5403,103 +5540,6 @@ type Product implements Node {
   visibility: ProductVisibility!
 }
 
-"""Product attribute definition (configurator)"""
-type ProductAttributeDefinition {
-  """Billing mode — BUNDLED | SEPARATE_LINE; null = informational only"""
-  billingMode: AttributeBillingMode
-
-  """Customer-facing description"""
-  description: String
-
-  """Display order"""
-  displayOrder: Int!
-
-  """Filling mode — MERCHANT | CUSTOMER | BOTH"""
-  fillingMode: AttributeFillingMode!
-
-  """URL-friendly handle"""
-  handle: String!
-
-  """Definition ID"""
-  id: ID!
-
-  """Required validation flag"""
-  isRequired: Boolean!
-
-  """Visibility flag"""
-  isVisible: Boolean!
-
-  """Max value (NUMBER) / max length (TEXT)"""
-  maxValue: Float
-
-  """Min value (NUMBER) / min length (TEXT)"""
-  minValue: Float
-
-  """Field name (e.g. "Finiszer")"""
-  name: String!
-
-  """Options for SELECT/RADIO/CHECKBOX types"""
-  options: [ProductAttributeOption!]!
-
-  """
-  Per-product scope — set to product ID for unique configurator fields, null for shared (in AttributeSet)
-  """
-  scopeProductId: ID
-
-  """Tax class ID; null = inherit from variant"""
-  taxClassId: ID
-
-  """Field type — TEXT/SELECT/RADIO/CHECKBOX/etc."""
-  type: AttributeType!
-}
-
-"""Filter for product attributes query"""
-input ProductAttributeFilterInput {
-  """
-  Filter by filling mode — MERCHANT | CUSTOMER | BOTH (configurator UI uses CUSTOMER + BOTH)
-  """
-  fillingMode: AttributeFillingMode
-}
-
-"""Selectable option of a product attribute (configurator)"""
-type ProductAttributeOption {
-  """Hex color (for COLOR/SWATCH types)"""
-  colorHex: String
-
-  """Option ID"""
-  id: ID!
-
-  """Default option marker"""
-  isDefault: Boolean!
-
-  """Display label shown to customer"""
-  label: String!
-
-  """
-  Summary of the linked ProductVariant. Null when the option has no linkedVariantId or the variant was deleted.
-  """
-  linkedVariant: LinkedVariantSummary
-
-  """
-  Linked ProductVariant ID for component stock decrement (hidden-products pattern).
-  """
-  linkedVariantId: ID
-
-  """Sort order"""
-  sortOrder: Int!
-
-  """
-  Surcharge amount when selected (FIXED = minor currency units; PERCENT = thousandths of percent).
-  """
-  surchargeAmount: Int
-
-  """Surcharge type — FIXED | PERCENT."""
-  surchargeType: AttributeOptionSurchargeType
-
-  """Internal value (slug-style)"""
-  value: String!
-}
-
 """Paginated product list"""
 type ProductConnection {
   """Product edges with cursors"""