first commit

docs/security-stack/security/security-codes/src/errors/security-codes-error.md

@@ -0,0 +1,79 @@
+# security-codes-error
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides the package-local error class and stable error-code registry for `@suaveplan/security-codes`. Because this package is a leaf with no `@suaveplan/error` dependency, it defines its own lightweight `SecurityCodesError` base class rather than extending `SuaveplanError`. The stable `SECURITY_CODES_CODES` constant object gives callers a programmatic handle for each failure mode without relying on fragile string matching against error messages.
+
+## Features
+
+- `SECURITY_CODES_CODES` constant object with three stable error codes: `DETECTION_FAILED`, `INVALID_PATTERN`, `SANITIZATION_FAILED`.
+- `SecurityCodesCode` union type derived from the constant so callers can reference code values without importing a string literal.
+- `SecurityCodesError` extends `Error` with an additional `readonly code: string` property for programmatic handling.
+- `name` is set to `"SecurityCodesError"` so that `instanceof` checks and serialisation can distinguish this class from generic `Error` objects.
+
+## Usage: Basic Example
+
+```ts
+import { SecurityCodesError, SECURITY_CODES_CODES } from '@suaveplan/security-codes/errors/security-codes-error';
+
+try {
+  // some operation
+} catch (err) {
+  if (err instanceof SecurityCodesError) {
+    console.error(err.code, err.message);
+  }
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { SecurityCodesError, SECURITY_CODES_CODES, SecurityCodesCode } from '@suaveplan/security-codes/errors/security-codes-error';
+
+function handleCode(code: SecurityCodesCode): void {
+  switch (code) {
+    case SECURITY_CODES_CODES.DETECTION_FAILED:
+      // retry with simpler input
+      break;
+    case SECURITY_CODES_CODES.INVALID_PATTERN:
+      // remove the offending detector from the registry
+      break;
+    case SECURITY_CODES_CODES.SANITIZATION_FAILED:
+      // fall back to full-redact strategy
+      break;
+  }
+}
+```
+
+## API Reference
+
+### `SECURITY_CODES_CODES`
+
+| Key | Value |
+|---|---|
+| `DETECTION_FAILED` | `"SECURITY_CODES.DETECTION_FAILED"` |
+| `INVALID_PATTERN` | `"SECURITY_CODES.INVALID_PATTERN"` |
+| `SANITIZATION_FAILED` | `"SECURITY_CODES.SANITIZATION_FAILED"` |
+
+### `SecurityCodesCode`
+
+`"SECURITY_CODES.DETECTION_FAILED" | "SECURITY_CODES.INVALID_PATTERN" | "SECURITY_CODES.SANITIZATION_FAILED"`
+
+### `SecurityCodesError`
+
+Extends `Error`.
+
+| Member | Type | Description |
+|---|---|---|
+| `code` | `string` | Stable error code from `SECURITY_CODES_CODES` |
+| `message` | `string` | Human-readable description |
+| `name` | `"SecurityCodesError"` | Fixed for `instanceof` / serialisation |
+
+**Constructor:** `new SecurityCodesError(message: string, code: string)`
+
+## Implementation Notes
+
+The package deliberately avoids depending on `@suaveplan/error` to keep `@suaveplan/security-codes` a true leaf package suitable for use in constrained environments. The error-code namespace prefix `SECURITY_CODES.` mirrors the convention used by `@suaveplan/error` consumers so that if the package ever graduates to a full `SuaveplanError` descendant the codes remain backward-compatible.