Initial Commit

packages/api-stack/api/api-graphql-apollo/src/error-codes/error-codes.md

@@ -0,0 +1,86 @@
+# `error-codes` — `GRAPHQL_APOLLO.*` registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`error-codes` defines the stable `GRAPHQL_APOLLO.*` namespace plus the
+`GraphqlApolloError` class consumed by every other module in the
+`@suaveplan/api-graphql-apollo` package. It sits in the same shape as the
+sibling `@suaveplan/api-graphql` registry so callers can write a single
+`instanceof SuaveplanError` discriminator and narrow further on
+`error.code`.
+
+The registry covers ten codes — request-document parse and validation
+failures, depth and complexity guard rejections, schema-build failures
+inside Apollo, the missing-transport case for subscriptions, request
+timeouts, introspection-denied responses, persisted-query lookup misses,
+and the resolver-attach catch-all. Every code is thrown by a production
+path; the conformance harness enforces that empirically.
+
+## Features
+
+- Frozen `defineCodes("GRAPHQL_APOLLO", […])` registry — no untyped string
+  ever escapes the package.
+- `GraphqlApolloError` exposes the code via both the inherited `error.code`
+  and a narrowed `graphqlApolloCode` field; either narrows downstream code
+  to the union of ten possible values.
+- Constructor preserves `cause` and `context` per the `SuaveplanError`
+  contract — wrappers can attach the raw `cause: Error` for crash dumps.
+- The class sets `this.name = "GraphqlApolloError"` so logs surface the
+  concrete subclass.
+
+## Usage: Basic
+
+```ts
+import {
+    GRAPHQL_APOLLO_CODES,
+    GraphqlApolloError,
+} from "@suaveplan/api-graphql-apollo/error-codes";
+
+throw new GraphqlApolloError(
+    GRAPHQL_APOLLO_CODES.PARSE_FAILED,
+    "request document failed to parse"
+);
+```
+
+## Usage: Advanced
+
+Attach a cause and a context payload that the OTel span recorder will
+attach as event attributes:
+
+```ts
+import { GraphqlApolloError } from "@suaveplan/api-graphql-apollo/error-codes";
+
+try {
+    JSON.parse(maybeJson);
+} catch (cause) {
+    throw new GraphqlApolloError(
+        "GRAPHQL_APOLLO.PARSE_FAILED",
+        "persisted-query manifest is not valid JSON",
+        { cause: cause as Error, context: { path: "./pq.json" } }
+    );
+}
+```
+
+## API Reference
+
+- `GRAPHQL_APOLLO_CODES` — frozen object mapping each short name to its
+  fully-qualified code string.
+- `GraphqlApolloErrorCode` — union of every code value resolved through
+  `GRAPHQL_APOLLO_CODES`.
+- `class GraphqlApolloError extends SuaveplanError<GraphqlApolloErrorCode>`.
+  - `constructor(code, message, options?)`
+  - `graphqlApolloCode` — convenience accessor pre-narrowed to the
+    `GraphqlApolloErrorCode` union.
+
+## Implementation Notes
+
+The codes intentionally mirror the design-doc §10.5 list. Adding a new
+code requires (a) appending it to the `defineCodes` array, (b) wiring at
+least one production throw site, and (c) extending the conformance
+checklist. The `name` field is set so structured logs see
+`GraphqlApolloError` rather than the generic `SuaveplanError`. The class
+extends the abstract `SuaveplanError` directly — no intermediate base.