@doswiftly/storefront-operations 7.0.0 → 8.0.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**: 8.0.0
+- **Queries**: 48
+- **Mutations**: 44
+- **Fragments**: 104
+<!-- 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,111 @@
 # Changelog
 
+## 8.0.0
+
+### Major Changes
+
+- 5f016e2: **BREAKING**: Operations were renamed to match the underlying GraphQL schema field names. If you used codegen against this package, regenerate your hooks and update import paths.
+
+  ### Renamed checkout mutations
+
+  | Old operation name                | New operation name                | New field call                                       |
+  | --------------------------------- | --------------------------------- | ---------------------------------------------------- |
+  | `CheckoutShippingAddressUpdate`   | `CheckoutUpdateShippingAddress`   | `checkoutUpdateShippingAddress(id, shippingAddress)` |
+  | `CheckoutBillingAddressUpdate`    | `CheckoutUpdateBillingAddress`    | `checkoutUpdateBillingAddress(id, billingAddress)`   |
+  | `CheckoutEmailUpdate`             | `CheckoutUpdateEmail`             | `checkoutUpdateEmail(id, email)`                     |
+  | `CheckoutShippingLineUpdate`      | `CheckoutSelectShippingRate`      | `checkoutSelectShippingRate(id, rateId)`             |
+  | `CheckoutDiscountCodeApply`       | `CheckoutApplyDiscountCode`       | `checkoutApplyDiscountCode(id, discountCode)`        |
+  | `CheckoutDiscountCodeRemove`      | `CheckoutRemoveDiscountCode`      | `checkoutRemoveDiscountCode(id, discountCode)`       |
+  | `CheckoutDiscountCodeValidate`    | `CheckoutValidateDiscountCode`    | `checkoutValidateDiscountCode(id, discountCode)`     |
+  | `CheckoutPaymentMethodUpdate`     | `CheckoutSelectPaymentMethod`     | `checkoutSelectPaymentMethod(id, paymentMethodId)`   |
+  | `CheckoutGiftCardApply`           | `CheckoutApplyGiftCard`           | `checkoutApplyGiftCard(id, giftCardCode)`            |
+  | `CheckoutGiftCardRemove`          | `CheckoutRemoveGiftCard`          | `checkoutRemoveGiftCard(id, giftCardCode)`           |
+  | `CheckoutGiftCardRecipientUpdate` | `CheckoutUpdateGiftCardRecipient` | `checkoutUpdateGiftCardRecipient(input)`             |
+
+  ### Argument changes in checkout mutations
+  - Variable `$checkoutId: ID!` → `$id: ID!`
+  - Argument `checkoutId:` → `id:`
+  - In `CheckoutSelectShippingRate`: variable `$shippingRateHandle: String!` → `$rateId: String!`, argument `shippingRateHandle:` → `rateId:`
+
+  Note: `CheckoutCreate` and `CheckoutComplete` were already aligned and are unchanged.
+
+  ### Renamed queries
+
+  | Old query                               | New query           | New field call                    |
+  | --------------------------------------- | ------------------- | --------------------------------- |
+  | `PredictiveSearch` (`predictiveSearch`) | `SearchSuggestions` | `searchSuggestions(query, limit)` |
+  | `AvailableFilters` (`availableFilters`) | `ProductFilters`    | `productFilters(input)`           |
+
+  `Categories` query now uses the `rootsOnly: true` argument and reads `nodes` instead of `roots`. Same data shape, standard Relay-style connection.
+
+  ### Renamed mutations (loyalty)
+
+  | Old mutation field     | New mutation field            |
+  | ---------------------- | ----------------------------- |
+  | `redeemLoyaltyReward`  | `loyaltyRedeemReward`         |
+  | `generateReferralCode` | `loyaltyGenerateReferralCode` |
+
+  Operation names (`RedeemLoyaltyReward`, `GenerateReferralCode`) are unchanged.
+
+  ### Wishlist mutations — argument alignment
+  - `wishlistAddItem(wishlistId, input)` → `wishlistAddItem(id, input)`
+  - `wishlistRemoveItem(wishlistId, itemId)` → `wishlistRemoveItem(id, itemId)`
+  - `wishlistDelete(wishlistId)` → `wishlistDelete(id)`
+
+  The `userErrors` field on every wishlist mutation result now correctly carries the `UserError` sub-selection.
+
+  ### Fragment shape changes
+  - `ProductCard` fragment now reads `categories { id, slug, name }` instead of the removed scalar `category` field. Cards that displayed a single category should now show the first item or join the list.
+  - `AvailableFilters` fragment now reads `activeCount` (was `activeFilterCount`) and `matchCount` (was `totalProducts`).
+  - Variant connections (`product.variants`) now require explicit `nodes { … }` selection — Relay-style.
+  - Loyalty payload fragments (`RedeemRewardPayload`, `GenerateReferralCodePayload`) now require the `UserError` sub-selection on `userErrors`.
+
+  ### Removed fragments
+  - `Price`, `PriceMoney`, `ProductRecommendation`, `CartRecommendation` — unused by any operation in this package. Inline equivalents are available if needed.
+
+  ### Migration
+  1. Regenerate codegen output against the new `schema.graphql` and operation files.
+  2. Update import paths to the new operation/hook names (search-and-replace based on the tables above).
+  3. In your form/UI code, rename the mutation variable `checkoutId` → `id` and update the argument key in the request payload.
+  4. In the shipping-rate flow, rename `shippingRateHandle` → `rateId`.
+  5. In `ProductCard` consumers, switch from `product.category` (string) to the first item of `product.categories` (array of `{ id, slug, name }`).
+  6. In `AvailableFilters` consumers, rename `activeFilterCount` → `activeCount` and `totalProducts` → `matchCount`.
+  7. In any `variants` selection on a product, wrap field selections in `nodes { … }`.
+  8. In `userErrors` reads on loyalty and wishlist mutations, expect the `UserError` shape (no longer a bare scalar).
+
+## 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