@doswiftly/storefront-operations 6.1.0 → 7.1.0

package/AGENTS.md

@@ -0,0 +1,183 @@
+# @doswiftly/storefront-operations — AI Agent Guide
+
+> Pre-built GraphQL operations and schema for the **DoSwiftly Storefront API**.
+> Use this when building e-commerce storefronts that consume DoSwiftly platform.
+
+This file is the entry point for AI coding agents (Cursor, Claude Code, GitHub
+Copilot, Codex, Aider, etc.). It uses **progressive disclosure** — read the
+sections you need, then fetch deeper references on demand.
+
+## Intended use — this is a reference catalog, not a runtime library
+
+This package is installed as a `devDependency` and ships only `.graphql` source
+files plus Markdown / JSON / text reference documents. There is no JavaScript
+to import — nothing here ends up in the storefront's runtime bundle.
+
+**Your job when generating code**: read the catalog (this file + `llms-full.txt`
++ `queries.graphql` / `mutations.graphql` in the same directory), then write
+operations directly into the consumer's `src/graphql/` directory (or wherever
+their codegen `documents:` glob points). The consumer's storefront codegen will
+produce `TypedDocumentNode`s from your written operations.
+
+Do **not** suggest importing operations from `@doswiftly/storefront-operations`
+in runtime code — the package has no such exports. Do **not** assume the
+consumer's `codegen.ts` references this package's `.graphql` files as
+`documents:` (that's an advanced, discouraged pattern — see the package README
+"Advanced" section). The default expectation is: schema lives here, operations
+live in the consumer's repo.
+
+<!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
+- **Schema version**: 7.1.0
+- **Queries**: 48
+- **Mutations**: 44
+- **Fragments**: 108
+<!-- AUTOGEN:STATS:END -->
+
+## Loading order
+
+When you need to build a storefront feature, load resources in this order:
+
+1. **`schema.graphql`** — full GraphQL schema. Authoritative source for types,
+   fields, enums, input types, and directives. Read this first when you need
+   to know what's available.
+2. **`AGENTS.md`** (this file) — critical conventions and anti-hallucination
+   notes. Read once per session.
+3. **`llms-full.txt`** — full operation reference with descriptions, typed
+   variables, and ready-to-execute GraphQL bodies. Search this file when you
+   need to know which named operation to use for a task.
+4. **`operations.json`** — same operations as structured JSON, useful when
+   you're calling tools programmatically (MCP servers, codegen).
+5. **`queries.graphql`, `mutations.graphql`, `fragments.graphql`** — raw
+   `.graphql` source. Use these directly with `@graphql-codegen/cli` or any
+   GraphQL client tooling.
+
+## Critical conventions — DO NOT hallucinate
+
+These are conventions where LLMs **frequently hallucinate from training data**.
+Verify against this list before generating queries.
+
+### Cart mutation names
+
+The DoSwiftly API uses `cart<Verb><Object>` naming. **Do not** generate
+`cart<Object><Verb>` aliases — they do not exist in this API.
+
+| ✅ Use                          | ❌ Do NOT use (hallucination)        |
+| ------------------------------- | ------------------------------------ |
+| `cartCreate`                    | (same)                               |
+| `cartAddLines`                  | `cartLinesAdd`                       |
+| `cartUpdateLines`               | `cartLinesUpdate`                    |
+| `cartRemoveLines`               | `cartLinesRemove`                    |
+| `cartApplyDiscountCodes`        | `cartDiscountCodesUpdate`            |
+| `cartUpdateBuyerIdentity`       | `cartBuyerIdentityUpdate`            |
+| `cartUpdateNote`                | `cartNoteUpdate`                     |
+| `cartUpdateAttributes`          | `cartAttributesUpdate`               |
+
+### `userErrors[]` is the global error envelope
+
+Every mutation returns a `userErrors: [UserError!]!` field. The shape is:
+
+```graphql
+type UserError {
+  message: String!
+  code: String       # NOT a typed enum at the global level
+  field: [String!]
+}
+```
+
+**Always check `userErrors` BEFORE consuming the happy-path payload**:
+
+```graphql
+mutation {
+  cartAddLines(id: $id, lines: $lines) {
+    cart { id }
+    userErrors { code field message }   # ← check this first
+  }
+}
+```
+
+`userErrors[].code` is `String`, not an enum — handle it as a string. The
+codes are listed in `llms-full.txt` and `operations.json` per-mutation.
+
+**Domain-specific typed enums** exist for warnings (not for errors):
+`CartWarningCode`, `DiscountErrorCode`, `GiftCardErrorCode`. These are used
+in dedicated `warnings[]` fields on cart/discount/gift-card payloads — they
+are **separate** from the generic `userErrors[]`.
+
+### Authentication — pick ONE, never both
+
+Two auth modes are supported:
+
+- **Browser storefronts**: rely on the `customerAccessToken` httpOnly cookie
+  (set by the SDK after `customerLogin` mutation). The cookie is sent
+  automatically — no header needed.
+- **Server-to-server / mobile**: send `Authorization: Bearer <token>` header,
+  where `<token>` is the `accessToken` field returned by `customerLogin`.
+
+**Never send both.** Do **not** invent `X-Customer-Token`, `X-Auth-Token`, or
+similar — they are ignored.
+
+### `@inContext` directive
+
+Pass storefront context (country, language, B2B buyer) via the `@inContext`
+directive on operations:
+
+```graphql
+query Products @inContext(country: PL, language: pl, preferredLocationId: "...") {
+  products(first: 12) { ... }
+}
+```
+
+Available args: `country`, `language`, `preferredLocationId`,
+`buyer { customerAccessToken, companyLocationId }`. The `buyer` arg is for
+**B2B server-to-server** flows only — browser storefronts use cookie auth and
+should not send `buyer.customerAccessToken` in the directive.
+
+### `Money.amount` is a string, not a number
+
+Money values use `Money { amount: String!, currencyCode: CurrencyCode! }`.
+The `amount` is a **string** to preserve decimal precision. Never `parseFloat`
+totals — use string-aware money math (e.g., `Decimal.js`) or pass the string
+verbatim to display.
+
+### Pagination is Relay-style on every list
+
+Every list query (products, collections, orders, etc.) uses Relay Connection
+shape: `edges { cursor, node { ... } }`, `nodes { ... }`, `pageInfo { ... }`,
+`totalCount`. Variables: `first`, `after`, `last`, `before`, `sortKey`,
+`reverse`. The `cursor` is opaque — pass it back as `after` for the next page.
+
+The `query` argument (when present) is a **text-search filter**, not a
+GraphQL operation. Don't confuse with operation name.
+
+### `product(id, handle)` — both optional, one required
+
+The `product` query accepts EITHER `id: ID` OR `handle: String`. Pass exactly
+one. Do **not** invent `slug`, `productHandle`, `productId`, or `productSlug`
+arg names.
+
+### Customer order — singular, not plural
+
+To fetch customer orders:
+
+- `query Customer { customer { orders { ... } } }` — list of orders.
+- `query CustomerOrder($orderId: ID!) { ... }` — single order by ID.
+
+**Hallucinations to avoid**: `OrderById`, `Order(id)`, `CustomerOrders` (plural),
+`CustomerAddresses` (use `CustomerProfile` for profile data),
+`CustomerMetaPropertiesSet`/`CustomerMetaPropertyDelete` — these do not exist.
+
+### Mutations are NOT auto-retried
+
+`@doswiftly/storefront-sdk` retries **queries** on transient network errors
+but does **NOT** retry mutations (that's a deliberate platform contract — at-most-once
+semantics). Idempotency is the caller's responsibility. If you need retries
+on a mutation, wrap with your own backoff logic and check `userErrors` to
+decide whether to retry.
+
+## When in doubt
+
+- **Schema question** ("what fields are on `X`?") → grep `schema.graphql`
+- **Operation question** ("which mutation does Y?") → grep `llms-full.txt` for the verb in `**Description**:` lines
+- **Programmatic enumeration** → load `operations.json`
+
+For codegen setup and runtime transport, see `README.md` and [`@doswiftly/storefront-sdk`](https://www.npmjs.com/package/@doswiftly/storefront-sdk).

package/CHANGELOG.md

@@ -1,5 +1,235 @@
 # Changelog
 
+## 7.1.0
+
+### Minor Changes
+
+- 0399ef8: Auto-generated, drift-proof docs and AI-agent context shipped inside the package.
+
+  The package now ships three new files alongside the `.graphql` sources, all
+  generated automatically and kept in sync with the schema:
+  - **`AGENTS.md`** — entry point for AI coding agents (Cursor, Claude Code,
+    GitHub Copilot, Codex, Aider, Gemini CLI, …). Critical conventions and
+    anti-hallucination notes — load this once per session.
+  - **`llms-full.txt`** — full operation reference: descriptions, typed variables,
+    ready-to-execute GraphQL bodies, fragment cross-references.
+  - **`operations.json`** — same operations as structured JSON for MCP servers
+    and programmatic tools.
+
+  The `Available Operations` section in `README.md` is now also auto-generated,
+  so it can never drift from the actual schema again.
+
+  **Anti-hallucination conventions** documented in `AGENTS.md`:
+  - Cart mutations are `cartAddLines` / `cartUpdateLines` / `cartRemoveLines`
+    (NOT the `cart<Object><Verb>` aliases — they do not exist in this API).
+  - `userErrors[].code` is a `String`, not an enum. Domain-typed enums exist
+    separately for warnings (`CartWarningCode`, `DiscountErrorCode`, etc.).
+  - Authentication uses **either** the `customerAccessToken` cookie **or** the
+    `Authorization: Bearer` header — never both.
+  - `Money.amount` is a string (decimal precision), not a number.
+
+  No code changes for existing consumers — `schema.graphql`, `queries.graphql`,
+  `mutations.graphql`, and `fragments.graphql` are unchanged in surface (only
+  non-functional `#` description comments were added in the operation files).
+  Codegen continues to produce identical typed documents.
+
+## 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