@doswiftly/storefront-operations 6.0.0 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,271 @@
 # Changelog
 
+## 7.0.0
+
+### Major Changes
+
+- 227629d: # Storefront GraphQL Operations 7.0 — Breaking changes + nowe rozszerzenia API
+
+  Major bump wprowadza zmiany breaking w schemie storefront GraphQL plus 3 znaczące nowe funkcjonalności: per-address tax info dla B2B, generic Meta Properties (extensible custom fields), oraz strukturalne userErrors[] z typed codes dla wszystkich mutacji.
+
+  ## Breaking changes
+
+  ### 1. `Product.category` (free-text) → `Product.categories` + `Product.primaryCategory` (structured)
+
+  Wcześniej `Product.category: String` zwracał free-text label — tekst nie był powiązany z entity Category. Klienci nie mogli pobrać slug/name kategorii ani zbudować breadcrumb. Po 7.0:
+
+  ```graphql
+  # PRZED (6.x):
+  product { category }  # → "Pop Vinyl" (free-text string, brak slug/parent)
+
+  # PO (7.0):
+  product {
+    categories { id slug name parent { slug } }   # M2M lista (junction table)
+    primaryCategory { slug name }                 # categories[0] dla breadcrumb
+  }
+  ```
+
+  **Migration**:
+  - Klient renderujący breadcrumb po category name: zamień `product.category` na `product.primaryCategory.name`.
+  - Klient filtrujący kategorie z `Product.category` jako string: użyj `product.categories[]` array.
+  - Filter `productCategory` w `ProductFilter` usunięty — używaj `category: { id }` (junction lookup, działało wcześniej).
+
+  ### 2. `categories` query — `CategoryTree` → `CategoryConnection` (Relay)
+
+  Wcześniej `categories` zwracał outlier shape `{ roots, totalCount }` vs reszta schemy używała Relay Connection. Klienci próbujący `categories { nodes }` dostawali GraphQL error. Po 7.0:
+
+  ```graphql
+  # PRZED (6.x):
+  categories(first: 20, rootsOnly: true) {
+    roots { id name children { id name } }
+    totalCount
+  }
+
+  # PO (7.0):
+  categories(first: 20, rootsOnly: true) {
+    nodes { id name children { id name } }
+    edges { cursor node { id } }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+    totalCount
+  }
+  ```
+
+  **Migration**:
+  - Zamień `categories.roots` na `categories.nodes`.
+  - Tree shape rebuild po stronie klienta — używaj `Category.parent` / `Category.children` field resolvers (DataLoader N+1 safe). Filtr `rootsOnly: true` zwraca tylko top-level (parent IS NULL).
+  - Pełen Relay args: `first/after/last/before` zamiast tylko `first/after`.
+
+  ### 3. `Customer.defaultAddress` — czytelny stan (poprzednio zawsze null)
+
+  Wcześniej `Customer.defaultAddress` zwracał `null` mimo że adres miał `isDefault: true` w `addresses`. Niespójność łamała storefront breadcrumb i powodowała duplikaty w formularzu dostawy. Po 7.0 zwraca poprawnie wartość — single source of truth z `addresses[].isDefaultShipping` flag.
+
+  **Migration**: brak — klient po prostu zacznie dostawać poprawne wartości.
+
+  ### 4. Apollo response — bez `extensions.stacktrace` w produkcji
+
+  Wcześniej w środowisku produkcyjnym GraphQL response zawierał stacktrace z absolutnymi ścieżkami systemu plików backendu. Po 7.0 production response strippuje wszystko poza `code`, `message`, `locations`, `path` + banner `extensions.environment`. Stacktrace dostępny **tylko** w dev/staging dla DX.
+
+  **Migration**: brak — klient produkcyjny nie powinien był polegać na stacktrace.
+
+  ### 5. Validation errors → `userErrors[]` z typed codes (tech debt resolution)
+
+  Wcześniej walidacja DTO leciała jako `body.errors[].extensions.code = "INTERNAL_SERVER_ERROR"` envelope (wyglądało jak crash). Po 7.0 mutations zwracają strukturalne `userErrors[]` z explicit codes per validation rule:
+
+  ```graphql
+  # Invalid NIP, password too short, malformed email — wszystkie zwracają payload
+  mutation {
+    customerUpdate(customer: { taxId: "1234567890" }) {
+      customer {
+        id
+      }
+      userErrors {
+        field
+        code
+        message
+      }
+      # → [{ field: ["taxId"], code: "INVALID_TAX_ID_CHECKSUM", message: "..." }]
+    }
+  }
+  ```
+
+  **Typed codes** dla 25 walidatorów: `INVALID_TAX_ID_CHECKSUM`, `INVALID_VAT_NUMBER`, `INVALID_REGON`, `INVALID_EMAIL_FORMAT`, `INVALID_FORMAT`, `INVALID_PHONE_FORMAT`, `INVALID_UUID`, `INVALID_URL`, `INVALID_DATE`, `INVALID_ENUM_VALUE`, `INVALID_TYPE`, `INVALID_COUNTRY_CODE`, `INVALID_POSTAL_CODE`, `TOO_SHORT`, `TOO_LONG`, `TOO_MANY`, `TOO_FEW`, `OUT_OF_RANGE`, `REQUIRED`, `INVALID_NESTED`, `VALIDATION_ERROR`, etc.
+
+  **Migration**: klient widzący poprzednio `body.errors[].extensions.code = "INTERNAL_SERVER_ERROR"` — sprawdź `data.<mutation>.userErrors[]` zamiast envelope.
+
+  ## New features
+
+  ### 6. `MailingAddress.taxId` + `vatNumber` — per-address B2B tax info
+
+  Adres ma teraz opcjonalne `taxId` (polski NIP, 10 cyfr z checksumą) + `vatNumber` (VAT UE, np. PL5260250274). Use case: B2B z różnymi danymi firmowymi per adres dostawy/billing (faktura na firmę matkę, dostawa na oddział z osobnym NIP-em).
+
+  ```graphql
+  mutation {
+    customerAddAddress(
+      address: {
+        streetLine1: "ul. Marszałkowska 100"
+        city: "Warszawa"
+        postalCode: "00-001"
+        country: PL
+        company: "GameGoods Sp. z o.o."
+        taxId: "5260250274"
+        vatNumber: "PL5260250274"
+      }
+    ) {
+      address {
+        taxId
+        vatNumber
+      }
+      userErrors {
+        code
+      }
+    }
+  }
+  ```
+
+  Walidacja format/checksum aktywna — invalid NIP zwraca `userErrors` z `INVALID_TAX_ID_CHECKSUM`.
+
+  ### 7. Meta Properties — extensible custom fields per encji
+
+  Generic mechanizm rozszerzania encji (Customer/Product/ProductVariant/Order) o storefront-specific dane bez wymogu zmian schematu po stronie platformy. Per-customer birthday, per-product warranty_years, per-order gift_message — wszystko jako typed key-value entries w polymorphic table.
+
+  ```graphql
+  # Customer self-edit (Bearer token klienta)
+  mutation {
+    customerMetaPropertiesSet(
+      properties: [
+        {
+          namespace: "storefront"
+          key: "birthday"
+          value: "1990-05-15"
+          type: DATE
+        }
+        {
+          namespace: "storefront"
+          key: "favorite_color"
+          value: "#FF6600"
+          type: COLOR
+        }
+      ]
+    ) {
+      metaProperties {
+        id
+        namespace
+        key
+        value
+        type
+      }
+      userErrors {
+        code
+        message
+      }
+    }
+  }
+
+  # Read na każdej encji
+  query {
+    customer {
+      metaProperty(namespace: "storefront", key: "birthday") {
+        value
+      }
+    }
+    product(id: "...") {
+      metaProperties(first: 10, namespace: "warranty") {
+        nodes {
+          key
+          value
+        }
+      }
+    }
+  }
+  ```
+
+  10 typed values: `STRING/TEXT/INTEGER/DECIMAL/BOOLEAN/JSON/DATE/DATE_TIME/URL/COLOR`. Visibility flag `isPrivate` (storefront API filtruje `isPrivate=true` na public encjach jak Product/ProductVariant). Reserved namespace prefix `doswiftly:` dla platform fields.
+
+  **Faza 1 MVP scope**: Customer self-edit only (`customerMetaPropertiesSet` / `customerMetaPropertyDelete` z auth Bearer token klienta). Cross-resource writes (Product/Order/Variant) wymagają Admin layer (Faza 2).
+
+  ### 8. NIP/REGON sanity guard — odrzucone all-zeros / repeated-digit patterns
+
+  Walidator NIP wcześniej akceptował `'0000000000'` (suma kontrolna 0=0). Po 7.0 odrzucamy wszystkie repeated-digit patterns (`'0000000000'`, `'1111111111'`, ..., `'9999999999'`) — to oczywiste fake test data / NULL placeholders, żaden urząd ich nie wystawia. Analogicznie REGON 9-digit i 14-digit.
+
+  ### 9. Empty string clear-value semantyka (wszystkie nullable input fields)
+
+  Customer kasujący wartość w UI inputie (np. `<input value="" />`) wysyła `phone: ""` zamiast `null`. Po 7.0 backend traktuje empty string jako "wyczyść pole" (DB → null) — natywne form library behavior, klient nie wymaga specjalnej logiki rozróżniającej `null` vs `""`.
+
+  Pokrycie: wszystkie nullable string/enum fields w `CustomerCreateInput`, `CustomerUpdateInput`, `MailingAddressInput`.
+
+  ## Notes
+  - 7.0 jest cumulative — kumulacja zmian z 6.x patches (B2B fields w `customerUpdate`, marketing consent flow) + breaking changes opisane wyżej.
+  - Wszystkie zmiany pokryte test coverage — backend integration tests gwarantują regression-free contract.
+
+## 6.1.0
+
+### Minor Changes
+
+- fbc6a94: Rozszerzono `CustomerUpdateInput` w GraphQL Storefront API o pełen kontrakt B2B — storefront developer może teraz zaktualizować dane firmowe klienta (nazwa firmy, NIP, VAT UE, REGON) oraz typ klienta (osoba fizyczna / firma) bezpośrednio przez mutację `customerUpdate`. Wcześniej te pola były dostępne wyłącznie z poziomu panelu administratora.
+
+  **Nowe pola Input**:
+  - `customerType: CustomerType` — `INDIVIDUAL` (B2C) lub `COMPANY` (B2B). Opcjonalne — gdy pominięte, backend dokona inteligentnej inferencji (patrz „Strict hybrid" niżej).
+  - `companyName: String` — nazwa firmy (wymagana dla `COMPANY`).
+  - `taxId: String` — polski NIP (10 cyfr z sumą kontrolną).
+  - `vatNumber: String` — numer VAT UE (np. `PL5260250274`, `DE123456789`).
+  - `regon: String` — polski REGON (9 lub 14 cyfr z sumą kontrolną).
+
+  **Nowe pola czytelne na typie `Customer`** (dostępne automatycznie przez fragment `Customer`):
+  - `customerType`, `companyName`, `taxId`, `vatNumber`, `regon`.
+
+  **Strict hybrid — kontrakt aktualizacji typu klienta**:
+  1. Jeśli `customerType` jest w payloadzie, wygrywa explicit (nawet jeśli inne pola sugerowałyby co innego).
+  2. Jeśli `customerType` jest pominięty, backend dokonuje implicit upgrade `INDIVIDUAL → COMPANY` tylko gdy podano niepuste pole firmowe. Implicit downgrade nigdy się nie zdarza — wymaga jawnego `customerType: INDIVIDUAL`.
+  3. Każde efektywne `COMPANY` (jawne lub przez inferencję) wymaga niepustej `companyName` — w przeciwnym razie mutacja zwraca `userErrors` z kodem `CUSTOMER_UPDATE_FAILED`.
+  4. `undefined` w payloadzie = brak zmiany pola; `null` = świadome czyszczenie wartości.
+
+  **Walidacja format**: NIP, VAT UE i REGON walidowane przez wspólny dekorator (regex + algorytm sumy kontrolnej). Niepoprawny format → błąd walidacji input'u GraphQL.
+
+  **Concurrency safety**: `customerUpdate` używa optimistic locking — równoczesne aktualizacje tego samego klienta (np. profil w wielu zakładkach) zwracają `userErrors` z message o konflikcie wersji zamiast cichego nadpisania.
+
+  **Use cases dla storefront-developera**:
+  - Strona „moje dane" w sklepie — pełen formularz B2C/B2B z radio pickerem typu klienta.
+  - Checkout pre-fill — możliwość uzupełnienia danych do faktury bez wchodzenia do panelu sklepu.
+  - Rejestracja firm / sole-trader scenarios — implicit upgrade gdy klient wpisze NIP w polu opcjonalnym.
+
+  **Test coverage**: 8 service-level scenariuszy (każda z 4 reguł strict hybrid + concurrency conflict + audit trail + EventEmitter) + 3 GraphQL surface scenariusze (full B2B payload, error mapping, format validation).
+
+- c91b700: Rozszerzono storefront GraphQL API o pełną obsługę zgód marketingowych — storefront-developer może teraz zbudować checkbox marketingu przy rejestracji, toggle preferencji w panelu klienta, oraz widget „zapisz się do newslettera" w stopce sklepu. Wszystkie 3 use case'y działają end-to-end (z double opt-in dla anonimowego widget'u i audit trail dla zgodności z RODO).
+
+  **Nowe pola Input (signup)** — `CustomerCreateInput`:
+  - `acceptsMarketing: Boolean` — checkbox marketingu przy `customerSignup`. `true` → state SUBSCRIBED bezpośrednio (signup = adres potwierdzony). `false`/`null` → bez zmian (NOT_SUBSCRIBED).
+  - `marketingOptInLevel: MarketingOptInLevel` (`SINGLE_OPT_IN | CONFIRMED_OPT_IN | UNKNOWN`) — opcjonalny override. Ustaw `CONFIRMED_OPT_IN` aby wymusić double opt-in (state PENDING + automatyczny email z linkiem potwierdzającym).
+
+  **Nowe pole Input (panel klienta)** — `CustomerUpdateInput`:
+  - `acceptsMarketing: Boolean` — toggle dla zalogowanego klienta. `true` → SUBSCRIBED, `false` → UNSUBSCRIBED. Działa tylko z access tokenem (auth-required mutation).
+
+  **Nowe mutacje (newsletter widget — guest, bez auth)**:
+  - `customerSubscribeToMarketing(input: { email, marketingOptInLevel? }): SubscribeToMarketingPayload` — anonimowy opt-in. Backend zawsze stosuje double opt-in (state PENDING → email z linkiem → klik → SUBSCRIBED) niezależnie od `marketingOptInLevel` w input — bez tego ktoś mógłby zapisywać cudze adresy.
+  - `customerUnsubscribeFromMarketing(input: { email }): UnsubscribeFromMarketingPayload` — anonimowy opt-out, idempotent.
+
+  **Payloady — `accepted: Boolean!` semantyka (anti-enumeration)**: obie mutacje guest zwracają `accepted: true` niezależnie od stanu emaila (registered / nieistniejący / już SUBSCRIBED). Storefront-developer dostaje deterministyczny shape response — atakujący nie może przez to API enumerate'ować adresów ani odróżnić invalid email format od valid (orzeczenie: też swallowed jako `accepted: true`). Stan końcowy zawsze widoczny przez `Customer.emailMarketing` (gdy klient autoryzowany).
+
+  **Mutacje C są throttlowane per IP** (limit 10/min) i pod botprotection guardem — storefront powinien zintegrować odpowiedni captcha provider. Email-bombing przez wpisywanie cudzego adresu w widget'cie blokowany dodatkowo na poziomie backendu (max 1 email potwierdzenia na adres na dobę).
+
+  **Strict-hybrid kontrakt update'u**:
+  - Brak pola w Input = no-op dla tego pola (zachowanie back-compat dla istniejących storefrontów bez nowych pól).
+  - `acceptsMarketing: null` na auth'd customer = explicit no-change (nie unsubscribe — do unsubscribe użyj `false`).
+
+  **Double opt-in dla widget'u — co dzieje się po kliknięciu „Zapisz"**:
+  1. Mutation `customerSubscribeToMarketing` → backend zapisuje stan PENDING + uruchamia wysłanie maila potwierdzającego.
+  2. Email idzie z domeny sklepu (per-shop branding — `From: "Sklep <noreply@shop-domain>"`) z CTA buttonem prowadzącym pod URL potwierdzający (token JWT 24h).
+  3. Klient klika link → backend transitionuje stan z PENDING na SUBSCRIBED.
+  4. Po SUBSCRIBED storefront może wysyłać maile marketingowe (gate consent jest egzekwowane przez backend pre-send).
+
+  **Read surface — `Customer.emailMarketing: EmailMarketingState!`** (pole już istniejące, dla auth'd customer): storefront odczytuje `NOT_SUBSCRIBED | PENDING | SUBSCRIBED | UNSUBSCRIBED | INVALID | REDACTED` aby zdecydować jak renderować checkbox/toggle w UI (np. PENDING = pokaż „sprawdź email", SUBSCRIBED = checkbox zaznaczony).
+
+  **Use cases**:
+  - Strona `/auth/register` — checkbox „Chcę otrzymywać newsletter" zapisany razem z signupem.
+  - Strona `/account/preferences` — toggle marketing on/off dla zalogowanego klienta.
+  - Stopka layoutu sklepu — input email + button „Zapisz się" → mutation guest subscribe → automatyczny email z linkiem potwierdzającym.
+
+  **Suppression list awareness**: jeśli adres trafił wcześniej na suppression list (hard bounce / complaint feedback), kolejna subskrypcja zwraca `accepted: true` ale email potwierdzający nie wychodzi. Klient pozostanie w stanie PENDING — admin sklepu musi ręcznie odblokować adres przez panel administracyjny.
+
 ## 6.0.0
 
 ### Major Changes

package/README.md

@@ -96,7 +96,7 @@ export function ProductList() {
 | `Collection`        | Collection with its products             |
 | `Collections`       | All collections                          |
 | `Category`          | Category with hierarchy                  |
-| `Categories`        | Category tree                            |
+| `Categories`        | Paginowana lista kategorii (Relay Connection) — drzewo budujesz po stronie klienta z `parent`/`children` |
 | `Cart`              | Cart contents by ID                      |
 | `Customer`          | Logged-in customer data                  |
 | `CustomerOrders`    | Customer order history                   |
@@ -116,23 +116,26 @@ export function ProductList() {
 
 **Authentication**
 
-- `CustomerCreate` - Register new customer
+- `CustomerSignup` - Register new customer
 - `CustomerLogin` - Login and get token
 - `CustomerLogout` - Logout
-- `CustomerTokenRenew` - Refresh auth token
+- `CustomerRefreshToken` - Refresh auth token
+- `CustomerActivate` - Activate account via email link
+- `CustomerMetaPropertiesSet` - Set custom key-value entries on the logged-in customer
+- `CustomerMetaPropertyDelete` - Delete a custom key-value entry from the logged-in customer
 
 **Customer Profile**
 
 - `CustomerUpdate` - Update profile info
-- `CustomerAddressCreate` - Add new address
-- `CustomerAddressUpdate` - Update address
-- `CustomerAddressDelete` - Delete address
-- `CustomerDefaultAddressUpdate` - Set default address
+- `CustomerAddAddress` - Add new address
+- `CustomerUpdateAddress` - Update address
+- `CustomerRemoveAddress` - Remove address
+- `CustomerSetDefaultAddress` - Set default address
 
 **Password**
 
-- `CustomerPasswordRecover` - Request password reset email
-- `CustomerPasswordReset` - Reset password with token
+- `CustomerRequestPasswordReset` - Request password reset email
+- `CustomerResetPassword` - Reset password with token
 
 ## Schema
 

package/fragments.graphql

@@ -285,6 +285,11 @@ fragment Customer on Customer {
   isEmailVerified
   emailMarketing
   tags
+  customerType
+  companyName
+  taxId
+  vatNumber
+  regon
   defaultAddress {
     ...MailingAddress
   }

package/package.json

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

package/schema.graphql

@@ -1182,11 +1182,14 @@ type Category {
   sortOrder: Int!
 }
 
-"""Paginated category list"""
+"""Paginated category list (Relay Connection)"""
 type CategoryConnection {
-  """List of category edges"""
+  """List of category edges (cursor + node pairs)"""
   edges: [CategoryEdge!]!
 
+  """List of category nodes (shortcut without cursor)"""
+  nodes: [Category!]!
+
   """Pagination info"""
   pageInfo: PageInfo!
 
@@ -1230,15 +1233,6 @@ type CategoryFilterOption {
   slug: String!
 }
 
-"""Category tree structure"""
-type CategoryTree {
-  """Root categories"""
-  roots: [Category!]!
-
-  """Total categories count"""
-  totalCount: Int!
-}
-
 """Checkout object"""
 type Checkout {
   """Applied gift cards"""
@@ -2010,9 +2004,15 @@ type Customer implements Node {
   """Saved addresses (Relay Connection)"""
   addresses(after: String, before: String, first: Int, last: Int): MailingAddressConnection!
 
+  """Company name (populated for COMPANY type)"""
+  companyName: String
+
   """Account creation date"""
   createdAt: DateTime!
 
+  """Business type discriminator (INDIVIDUAL/COMPANY)"""
+  customerType: CustomerType!
+
   """Default address"""
   defaultAddress: MailingAddress
 
@@ -2037,6 +2037,16 @@ 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!
 
@@ -2046,14 +2056,23 @@ type Customer implements Node {
   """Phone number"""
   phone: String
 
+  """Polish business registry number — REGON"""
+  regon: String
+
   """Customer tags for segmentation (e.g. vip, wholesale, b2b)"""
   tags: [String!]!
 
+  """Polish tax ID — NIP"""
+  taxId: String
+
   """Total amount spent"""
   totalSpent: Money!
 
   """Last update date"""
   updatedAt: DateTime!
+
+  """EU VAT number"""
+  vatNumber: String
 }
 
 """Customer access token"""
@@ -2103,6 +2122,11 @@ type CustomerAddAddressPayload {
 
 """Input for customer registration"""
 input CustomerCreateInput {
+  """
+  Opt-in to email marketing checkbox. true → state SUBSCRIBED (single opt-in) unless `marketingOptInLevel: CONFIRMED_OPT_IN` is also set (then PENDING + double opt-in confirmation email). false/null → no consent change.
+  """
+  acceptsMarketing: Boolean
+
   """Email address"""
   email: String!
 
@@ -2112,6 +2136,11 @@ input CustomerCreateInput {
   """Last name"""
   lastName: String
 
+  """
+  Opt-in level. Default SINGLE_OPT_IN (signup = email proven implicitly). Set CONFIRMED_OPT_IN to force double opt-in via confirmation email.
+  """
+  marketingOptInLevel: MarketingOptInLevel
+
   """Password"""
   password: String!
 
@@ -2234,6 +2263,29 @@ type CustomerSignupPayload {
   userErrors: [UserError!]!
 }
 
+"""Input for newsletter subscribe (guest-friendly)."""
+input CustomerSubscribeToMarketingInput {
+  """Email address to subscribe to newsletter"""
+  email: String!
+
+  """
+  Opt-in level. Guest mutation always enforces CONFIRMED_OPT_IN regardless of value.
+  """
+  marketingOptInLevel: MarketingOptInLevel
+}
+
+"""Customer business type — INDIVIDUAL (B2C) or COMPANY (B2B)."""
+enum CustomerType {
+  COMPANY
+  INDIVIDUAL
+}
+
+"""Input for newsletter unsubscribe (guest-friendly)."""
+input CustomerUnsubscribeFromMarketingInput {
+  """Email address to unsubscribe"""
+  email: String!
+}
+
 """Result of address update"""
 type CustomerUpdateAddressPayload {
   """Updated address"""
@@ -2247,6 +2299,17 @@ type CustomerUpdateAddressPayload {
 
 """Input for customer update"""
 input CustomerUpdateInput {
+  """
+  Email marketing toggle. true → state SUBSCRIBED bezpośrednio (auth'd customer = email proven). false → UNSUBSCRIBED. null/undefined → no change.
+  """
+  acceptsMarketing: Boolean
+
+  """Company name (required when customerType is COMPANY)"""
+  companyName: String
+
+  """Business type discriminator (INDIVIDUAL/COMPANY)"""
+  customerType: CustomerType
+
   """First name"""
   firstName: String
 
@@ -2255,6 +2318,15 @@ input CustomerUpdateInput {
 
   """Phone number"""
   phone: String
+
+  """Polish business registry number — REGON (9 or 14 digits with checksum)"""
+  regon: String
+
+  """Polish tax ID — NIP (10 digits with checksum)"""
+  taxId: String
+
+  """EU VAT number (e.g. PL1234567890)"""
+  vatNumber: String
 }
 
 """Result of customer update"""
@@ -3215,6 +3287,16 @@ type MailingAddress implements Node {
 
   """Second line of street address"""
   streetLine2: String
+
+  """
+  Per-address tax ID (Polish NIP, 10 digits z checksum). B2B use case: różne dane firmowe per adres — np. faktura na firmę matkę z NIP A, dostawa na oddział z NIP B. Distinct from `Customer.taxId` (customer-level globally).
+  """
+  taxId: String
+
+  """
+  Per-address EU VAT number (e.g. PL1234567890). B2B cross-border: różny VAT per adres dostawy. Distinct from `Customer.vatNumber` (customer-level globally).
+  """
+  vatNumber: String
 }
 
 """Paginated mailing addresses (Relay Connection)"""
@@ -3272,6 +3354,23 @@ input MailingAddressInput {
 
   """Second line of street address"""
   streetLine2: String
+
+  """
+  Per-address Polish tax ID — NIP (10 digits with checksum). B2B use case: różne dane firmowe per adres dostawy/billing.
+  """
+  taxId: String
+
+  """Per-address EU VAT number (e.g. PL1234567890). Cross-border B2B."""
+  vatNumber: String
+}
+
+"""
+Email marketing opt-in level — SINGLE_OPT_IN, CONFIRMED_OPT_IN, UNKNOWN.
+"""
+enum MarketingOptInLevel {
+  CONFIRMED_OPT_IN
+  SINGLE_OPT_IN
+  UNKNOWN
 }
 
 """Navigation menu"""
@@ -3335,6 +3434,119 @@ 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"""
@@ -3432,6 +3644,12 @@ 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!
 
@@ -3455,6 +3673,12 @@ type Mutation {
   """Register new customer"""
   customerSignup(input: CustomerCreateInput!): CustomerSignupPayload!
 
+  """Subscribe an email to the newsletter (guest-friendly, double opt-in)."""
+  customerSubscribeToMarketing(input: CustomerSubscribeToMarketingInput!): SubscribeToMarketingPayload!
+
+  """Unsubscribe an email from the newsletter (guest-friendly, idempotent)."""
+  customerUnsubscribeFromMarketing(input: CustomerUnsubscribeFromMarketingInput!): UnsubscribeFromMarketingPayload!
+
   """Update customer profile"""
   customerUpdate(customer: CustomerUpdateInput!): CustomerUpdatePayload!
 
@@ -3541,6 +3765,12 @@ type Order implements Node {
   """Line items count"""
   itemCount: Int!
 
+  """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!
 
@@ -3820,9 +4050,9 @@ type Product implements Node {
   averageRating: Float
 
   """
-  Product category (free-text classification, e.g. "Footwear", "Electronics")
+  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.
   """
-  category: String
+  categories: [Category!]!
 
   """
   Compare-at price range (Money pair). Null gdy żaden variant nie ma compareAtPrice.
@@ -3861,6 +4091,12 @@ 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.
   """
@@ -3874,6 +4110,11 @@ type Product implements Node {
   """
   priceRangeWithConversion: ConvertedPriceRange
 
+  """
+  Domyślna kategoria dla breadcrumb/nav (= categories[0] po sortOrder). Null gdy produkt nie jest w żadnej kategorii.
+  """
+  primaryCategory: Category
+
   """Similar products recommendations"""
   recommendations(first: Int = 4): ProductRecommendations
 
@@ -4060,11 +4301,6 @@ input ProductFilter {
   """Filter by variant price range"""
   price: PriceRangeFilter
 
-  """
-  Filter by product category (free-text classification, stored on Product.category). Distinct from `category: CategoryFilter` which selects by structured Category entity.
-  """
-  productCategory: String
-
   """
   Filter by product type enum (PHYSICAL/DIGITAL/SERVICE/SUBSCRIPTION/GIFT_CARD). Distinct from `productCategory` (free-text classification).
   """
@@ -4262,6 +4498,12 @@ 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!
 
@@ -4395,20 +4637,30 @@ type Query {
   """Get cart by ID"""
   cart(id: ID!): Cart
 
-  """Get category tree"""
+  """
+  Lista kategorii (Relay Connection) z opcjonalnym filtrem rootsOnly/parentId
+  """
   categories(
-    """Cursor for pagination"""
+    """Forward pagination cursor (after this element)"""
     after: String
 
-    """Number of items to fetch"""
-    first: Int! = 20
+    """Backward pagination cursor (before this element)"""
+    before: String
+
+    """Forward pagination — first N elements"""
+    first: Int
 
-    """Filter by parent category ID"""
+    """Backward pagination — last N elements"""
+    last: Int
+
+    """
+    Filter by parent category ID — używaj `null` semantically dla "roots" via `rootsOnly` flag
+    """
     parentId: ID
 
-    """Only root categories"""
+    """Tylko root categories (parentId IS NULL)"""
     rootsOnly: Boolean! = false
-  ): CategoryTree!
+  ): CategoryConnection!
 
   """Get category by ID or slug"""
   category(
@@ -5662,6 +5914,17 @@ enum StorefrontOrderStatus {
   PROCESSING
 }
 
+"""Payload for customerSubscribeToMarketing mutation"""
+type SubscribeToMarketingPayload {
+  """
+  Always true (anti-enumeration). Backend may silently skip enqueue if rate-limited or already SUBSCRIBED.
+  """
+  accepted: Boolean!
+
+  """User-facing errors"""
+  userErrors: [UserError!]!
+}
+
 """Tax line item"""
 type TaxLine {
   """Tax amount"""
@@ -5756,6 +6019,15 @@ Unsigned 64-bit integer, JSON-serialized as String (BigInt-safe). Format: "{inte
 """
 scalar UnsignedInt64
 
+"""Payload for customerUnsubscribeFromMarketing mutation"""
+type UnsubscribeFromMarketingPayload {
+  """Always true (anti-enumeration)."""
+  accepted: Boolean!
+
+  """User-facing errors"""
+  userErrors: [UserError!]!
+}
+
 """URL redirect (SEO, store migration)"""
 type UrlRedirect {
   """Source path"""