@doswiftly/storefront-operations 6.1.0 → 7.0.0

package/CHANGELOG.md

@@ -1,5 +1,202 @@
 # 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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "6.1.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"""
@@ -2043,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!
 
@@ -3283,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)"""
@@ -3340,6 +3354,14 @@ 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
 }
 
 """
@@ -3412,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"""
@@ -3509,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!
 
@@ -3624,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!
 
@@ -3903,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.
@@ -3944,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.
   """
@@ -3957,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
 
@@ -4143,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).
   """
@@ -4345,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!
 
@@ -4478,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(