first commit

docs/commerce/contacts/api-plugin-contacts/src/context/context.md

@@ -0,0 +1,75 @@
+# context — Hono ContextVariableMap augmentation
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Module augmentation declaring four typed slots on Hono's
+`ContextVariableMap`: `contactRepository`, `groupRepository`,
+`membershipRepository`, and `eventBus`. Importing this module for its
+side effects (the package root barrel does it automatically) means
+every route handler in this plugin's `/contacts` and `/groups` trees
+reads `c.get("contactRepository")` as `SurrealContactRepository | undefined`
+without an `as` cast.
+
+The upstream port shipped ~30 `as any` casts in its route handlers to
+work around the missing augmentation. suaveplan CLAUDE.md rule 9 forbids
+static-analysis suppression; this module is the structural fix.
+
+## Features
+
+- Declares four typed slots on Hono's request context.
+- Zero runtime emit — the `declare module` block is removed by the TS
+  transformer.
+- Imported by `src/index.ts` for side effects so consumers of the
+  package see the augmentation automatically.
+
+## Usage: Basic
+
+```ts
+import "hono"; // brings in our augmentation transitively via the plugin root
+import type { Context } from "hono";
+
+function handler(c: Context) {
+    const repo = c.get("contactRepository");
+    // repo is typed as SurrealContactRepository | undefined.
+    return c.json({ ok: repo !== undefined });
+}
+```
+
+## Usage: Advanced
+
+```ts
+import type { Context } from "hono";
+import type { SurrealContactRepository } from "@suaveplan/api-plugin-contacts/repositories/contact-repository";
+
+function listContactsHandler(c: Context) {
+    const repo = c.get("contactRepository");
+    if (repo === undefined) {
+        throw new Error("contactRepository missing — plugin not mounted");
+    }
+    return repo.list({ tenantId: c.get("user")!.tenantId! });
+}
+```
+
+## API Reference
+
+- Module augmentation only — no runtime exports. The slots are:
+  - `contactRepository: SurrealContactRepository`
+  - `groupRepository: SurrealGroupRepository`
+  - `membershipRepository: SurrealMembershipRepository`
+  - `eventBus: EventBusLike`
+
+## Implementation Notes
+
+- Slots are typed as `T` (not `T | undefined`); `c.get` returns
+  `T | undefined` at the Hono type level, so accidental reads before
+  the plugin middleware runs are caught by the compiler.
+- Augmentations are global once imported — every Hono app in the
+  process sees them. This is the standard TypeScript module-merging
+  trade-off; sibling plugins in `packages/api/api-plugin-*` rely on the
+  same pattern.
+- The export `{}` line is required so TypeScript treats the file as a
+  module rather than a global script.