first commit

docs/commerce/contacts/audience-rules/src/error-codes/error-codes.md

@@ -0,0 +1,93 @@
+# error-codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`error-codes.ts` defines the stable, namespaced error-code registry for the
+`@suaveplan/audience-rules` package, alongside the discriminated
+`AudienceRulesError` class that every failure path raises. It exists so that
+consumers can dispatch on a stable string (`"AUDIENCE_RULES.SEGMENT_NOT_FOUND"`)
+rather than parsing error messages, and so that diagnostic context
+(`segmentId` / `tenantId`) survives transport across logger sinks, OTel span
+events, and structured-output channels without polluting the base
+`SuaveplanError` `context` map.
+
+## Features
+
+- `AUDIENCE_RULES_CODES` registry built via `defineCodes("AUDIENCE_RULES", [...])`
+  with four stable codes: `INVALID_INPUT`, `SEGMENT_NOT_FOUND`,
+  `UNKNOWN_OPERATOR`, `PROVIDER_FAILED`.
+- `AudienceRulesErrorCode` union type narrowing every legal `code` value.
+- `AudienceRulesError extends SuaveplanError<AudienceRulesErrorCode>` carrying
+  optional `segmentId` and `tenantId` discriminants.
+- `AudienceRulesErrorOptions` extending `SuaveplanErrorOptions` with the two
+  discriminant fields.
+- Compatible with the `@suaveplan/error` cause-chain traversal, redaction, and
+  OTel span-event adapter without further wiring.
+
+## Usage: Basic Example
+
+```ts
+import {
+    AUDIENCE_RULES_CODES,
+    AudienceRulesError,
+} from "@suaveplan/audience-rules";
+
+throw new AudienceRulesError(
+    AUDIENCE_RULES_CODES.SEGMENT_NOT_FOUND,
+    "segment 'seg_42' does not exist",
+    { segmentId: "seg_42", tenantId: "tenant-1" }
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    AudienceRulesError,
+    AUDIENCE_RULES_CODES,
+} from "@suaveplan/audience-rules";
+
+function handleRefresh(error: unknown) {
+    if (
+        error instanceof AudienceRulesError &&
+        error.code === AUDIENCE_RULES_CODES.PROVIDER_FAILED
+    ) {
+        // narrow tenantId for diagnostics, then re-throw with extra context
+        throw new AudienceRulesError(
+            AUDIENCE_RULES_CODES.PROVIDER_FAILED,
+            "contact provider failed during scheduled refresh",
+            { tenantId: error.tenantId, cause: error }
+        );
+    }
+    throw error;
+}
+```
+
+## API Reference
+
+- `AUDIENCE_RULES_CODES` — frozen record mapping every short name to its
+  namespaced string (e.g. `INVALID_INPUT → "AUDIENCE_RULES.INVALID_INPUT"`).
+- `type AudienceRulesErrorCode` — union of every namespaced string value.
+- `interface AudienceRulesErrorOptions extends SuaveplanErrorOptions` — accepts
+  `segmentId?: string`, `tenantId?: string`, plus every option from the base
+  `SuaveplanErrorOptions` (e.g. `cause`, `context`).
+- `class AudienceRulesError extends SuaveplanError<AudienceRulesErrorCode>` —
+  constructor `(code, message, options?)`; exposes `segmentId?: string` and
+  `tenantId?: string` as readonly own-properties.
+
+## Implementation Notes
+
+- The registry is intentionally small at v0.1.0. Adding a code requires bumping
+  the package and updating the OpenSpec delta; deleting a code is a breaking
+  change. See `AGENTS.md §2c` — codes are never removed just because a
+  call site has not been wired yet.
+- `segmentId` / `tenantId` are assigned only when the constructor option is
+  non-`undefined`, so the runtime shape stays compact for logger redaction
+  passes that walk own-property keys.
+- `defineCodes` from `@suaveplan/error` guarantees the namespaced prefix at
+  type-time, so a typo in the literal (`"AUDIENCE_RULE.X"`) is a compile error,
+  not a silent registry shift.