Initial Commit

packages/communication/messaging/imessage-adapter/src/error-codes/error-codes.md

@@ -0,0 +1,87 @@
+# `IMESSAGE_*` error registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the stable, fully-qualified error-code registry for
+`@suaveplan/imessage-adapter`. Every error class in this module
+inherits from `@suaveplan/error`'s `SuaveplanError` base and carries
+one of the ten `IMESSAGE.*` codes returned by `defineCodes("IMESSAGE",
+[...])`. Consumers downstream — loggers, problem+json renderers, retry
+wrappers, OTel attribute writers — map on the code, never on the
+message or class identity, so the codes are part of the public API.
+
+## Features
+
+- Ten production codes, each thrown from at least one real call site:
+  `DB_OPEN_FAILED`, `DB_QUERY_FAILED`, `WATCHER_NOT_RUNNING`,
+  `WATCHER_ALREADY_RUNNING`, `ADAPTER_NOT_INITIALIZED`,
+  `INVALID_CONFIG`, `POLL_ABORTED`, `POLL_FAILED`,
+  `ATTACHMENT_PARSE_FAILED`, `APPLE_DATE_PARSE_FAILED`.
+- One typed error class per code, all extending the abstract
+  `IMessageError` so consumers can pattern-match via `instanceof
+  IMessageError` for a single catch site.
+- `IMessageInvalidConfigError` accepts a `issues` payload that is
+  merged into `context` so callers can recover the Zod issue array
+  from problem+json bodies.
+- Frozen `IMESSAGE_CODES` record keeps the literal-typed union
+  reachable through the public surface.
+
+## Usage: Basic
+
+```ts
+import {
+    IMessageAdapterNotInitializedError,
+} from "@suaveplan/imessage-adapter";
+
+throw new IMessageAdapterNotInitializedError();
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    IMessageError,
+    IMessageInvalidConfigError,
+    IMESSAGE_CODES,
+} from "@suaveplan/imessage-adapter";
+
+try {
+    parseWatcherConfig(input);
+} catch (err) {
+    if (err instanceof IMessageInvalidConfigError) {
+        console.error(err.code, err.context["issues"]);
+    } else if (err instanceof IMessageError) {
+        switch (err.code) {
+            case IMESSAGE_CODES.WATCHER_ALREADY_RUNNING:
+            case IMESSAGE_CODES.WATCHER_NOT_RUNNING:
+                // recoverable
+                break;
+            default:
+                throw err;
+        }
+    } else {
+        throw err;
+    }
+}
+```
+
+## API Reference
+
+- `const IMESSAGE_CODES`: frozen record `{ DB_OPEN_FAILED:
+  "IMESSAGE.DB_OPEN_FAILED", ... }`.
+- `type IMessageErrorCode`: union of every fully-qualified code.
+- `abstract class IMessageError extends SuaveplanError<IMessageErrorCode>`.
+- One concrete class per code, each accepting `{ cause?, context?,
+  traceId?, message? }`.
+
+## Implementation Notes
+
+The module side-effect-imports nothing; the registry is purely
+declarative. The package barrel (`src/index.ts`) side-effect-imports
+`./error-codes/index.js` so subpath consumers also observe the
+registration. Messages default to i18n keys (`imessage.errors.*`) so
+callers can supply their own resolver if they wish.