@doswiftly/storefront-operations 20.2.0 → 21.0.1

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.2.0
+- **Schema version**: 21.0.1
 - **Queries**: 52
 - **Mutations**: 44
-- **Fragments**: 104
+- **Fragments**: 105
 <!-- AUTOGEN:STATS:END -->
 
 ## Loading order

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 21.0.1
+
+### Patch Changes
+
+- 65c7f72: Fixed: cart, order, and customer address reads now include `buildingNumber` and `flatNumber`. The previous release added both fields to the schema and inputs (you could send them), but the SDK's `MailingAddress` selection did not request them back — they always came back missing on `cart.shippingAddress` / `cart.billingAddress`, order addresses, the saved address book (`getAddresses()`), and `customer.defaultAddress`. The generated types now carry both fields as well.
+
+  Documentation: rewrote the SDK README to match the current API.
+
+  The README (shown on npm and GitHub) previously described setup patterns from older releases. It now documents the current surface:
+  - **Quick start** based on `createStorefrontAuthRoute` (one route file mounting `login` / `refresh` / `logout` / `whoami`), `getInitialAuth()` server seeding, and `<StorefrontProvider>` with automatic session refresh.
+  - **Cart** chapter covering the capability model (composite `cart-id` cookie carrying the cart access secret, `cartSecretMiddleware`), the full `useCartManager` checkout lifecycle (per-operation recovery table, tagged-union `status`, lifecycle callbacks, `initialCartId`), `<CartManagerProvider>` / `useCartManagerContext()`, completion + payment session creation, discovery queries, `merge` / `downgradeOnLogout` / `recoveryRedeem`, and the framework-agnostic recovery runner.
+  - **Authentication** chapter documenting the session cookie set, proactive + reactive refresh, the BFF sign-in flow, `AuthClient` methods (including `refreshSession()` and `getAddresses()`), and reverse-proxy origin validators.
+  - Reference sections for the middleware pipeline order, debug logging (including the remote debug transport), runtime schema enums, cookie contract constants, format hooks, pre-built components (including payment instrument tiles), and server-side helpers (`readCartCredentials`, `serverCartSecretMiddleware`).
+  - A **Deprecated** section listing the legacy cart store (`createCartStore` / `CartProvider` / `useCartStore`), `AuthClient.refreshToken()` / `useRefreshToken`, and `ShopCurrencyData` with their replacements.
+
+  Also cleaned up developer-facing JSDoc across the package (clients, middleware, stores, hooks, pre-built components): comments and IDE hover text are now plain technical English, and the `getBrowserDataForPayment` example no longer suggests passing browser data to `createPayment` (its input is `{ orderId, returnUrl?, cancelUrl? }`). No runtime changes.
+
+  `@doswiftly/storefront-operations` is version-synced; no code changes.
+
+## 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

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
 }
@@ -1632,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
@@ -1646,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
@@ -1656,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.2.0**
-> 52 queries · 44 mutations · 104 fragments
+> Schema version: **21.0.1**
+> 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
 }
@@ -5080,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
@@ -5099,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
@@ -5118,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.2.0",
+  "schemaVersion": "21.0.1",
   "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"
     },
     {
@@ -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.2.0",
+  "version": "21.0.1",
   "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
@@ -2167,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
@@ -3455,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)."""
@@ -5273,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
@@ -5307,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!
 
@@ -5433,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"""