@doswiftly/storefront-operations 7.0.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,38 @@
 # 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