# 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.