# BROWSER_CRYPTO_CODES

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

`codes.ts` defines the complete set of stable error codes used throughout `@suaveplan/crypto-browser`. Each code is a namespaced string constant produced by `defineCodes` from `@suaveplan/error`, ensuring codes are unique within the `"BROWSER_CRYPTO"` namespace and that the `BrowserCryptoCode` union type is always in sync with the registered values at compile time. All WebCrypto-related failures in this package surface under one of these codes, allowing consumers to branch deterministically without parsing message strings.

## Features

- Three codes covering the main WebCrypto failure domains: API unavailability, key generation, and general operation failures
- Generated via `defineCodes("BROWSER_CRYPTO", [...])` which prefixes each entry and freezes the resulting object
- `BrowserCryptoCode` is derived as a `typeof` union for compile-time exhaustive narrowing
- No runtime dependencies beyond `@suaveplan/error`

## Usage: Basic Example

```typescript
import { BROWSER_CRYPTO_CODES } from "@suaveplan/crypto-browser/errors/codes";
import { BrowserCryptoError } from "@suaveplan/crypto-browser/errors/browser-crypto-error";

throw new BrowserCryptoError(
  BROWSER_CRYPTO_CODES["NOT_AVAILABLE"],
  "error.crypto-browser.not-available"
);
```

## Usage: Advanced Example

```typescript
import {
  BROWSER_CRYPTO_CODES,
  type BrowserCryptoCode,
} from "@suaveplan/crypto-browser/errors/codes";
import { BrowserCryptoError } from "@suaveplan/crypto-browser/errors/browser-crypto-error";

function handleBrowserCryptoError(err: BrowserCryptoError): string {
  switch (err.code as BrowserCryptoCode) {
    case BROWSER_CRYPTO_CODES["NOT_AVAILABLE"]:
      return "WebCrypto API is not available in this environment (requires HTTPS or localhost).";
    case BROWSER_CRYPTO_CODES["KEY.GENERATION_FAILED"]:
      return "Key generation failed — the requested algorithm may not be supported by this browser.";
    case BROWSER_CRYPTO_CODES["OPERATION.FAILED"]:
      return "Cryptographic operation failed — check key type, algorithm, and input size.";
    default:
      return "Unknown browser crypto error.";
  }
}
```

## API Reference

### `BROWSER_CRYPTO_CODES`

```typescript
const BROWSER_CRYPTO_CODES: Readonly<Record<string, string>>
```

A frozen map from short code keys to their namespaced string values. All values are prefixed with `"BROWSER_CRYPTO."` by `defineCodes`.

| Key                    | Namespaced value                             | When thrown                                                       |
|------------------------|----------------------------------------------|-------------------------------------------------------------------|
| `NOT_AVAILABLE`        | `"BROWSER_CRYPTO.NOT_AVAILABLE"`             | `globalThis.crypto.subtle` is `undefined` or `null`              |
| `KEY.GENERATION_FAILED`| `"BROWSER_CRYPTO.KEY.GENERATION_FAILED"`     | `SubtleCrypto.generateKey` or `importKey` rejects                |
| `OPERATION.FAILED`     | `"BROWSER_CRYPTO.OPERATION.FAILED"`          | Any `SubtleCrypto` operation (`encrypt`, `decrypt`, `sign`, `verify`, `deriveBits`, `wrapKey`, `unwrapKey`) rejects |

### `BrowserCryptoCode`

```typescript
type BrowserCryptoCode =
  (typeof BROWSER_CRYPTO_CODES)[keyof typeof BROWSER_CRYPTO_CODES];
```

Union of all namespaced code strings. Use this type to annotate `err.code` when narrowing `BrowserCryptoError` in typed catch blocks.

## Implementation Notes

`defineCodes` returns a plain frozen object and the `BrowserCryptoCode` type collapses to a string literal union. Adding a new entry to the array automatically widens the union without requiring any manual type maintenance.

`OPERATION.FAILED` intentionally covers a broad set of `SubtleCrypto` rejections rather than splitting each operation into its own code. The distinction between, say, a failed `encrypt` and a failed `sign` is captured in the structured `context` field on the thrown `BrowserCryptoError` rather than in the code itself, which keeps the code registry small and stable across algorithm additions.