Initial Commit

packages/api-stack/api/api-plugin-user/src/services/registry-augmentation.md

@@ -0,0 +1,70 @@
+# services/registry-augmentation
+
+## Purpose
+
+This module is a TypeScript `declare module` augmentation. It adds the
+`userService` slot to the canonical `ServiceRegistry` interface owned
+by `@suaveplan/api-plugin/service-registry` so downstream plugins that
+import `@suaveplan/api-plugin-user` for its side effects see
+`ctx.getService("userService")` resolve to `UserService | undefined`
+without a cast.
+
+## Features
+
+- One side-effect import of this file (which the package root barrel
+  performs automatically) gives every consumer typed access to the
+  `userService` slot.
+- Mirrors the auth plugin's registry-augmentation pattern so a future
+  project-wide audit can grep every plugin's registry slot from a
+  single regex.
+- Declaration merging means the augmentation composes safely with
+  every other plugin's registry-augmentation file — the host's
+  `ServiceRegistry` is the union of all loaded plugins' slots.
+
+## Usage: Basic
+
+```ts
+import "@suaveplan/api-plugin-user/services/user-service";
+// `ctx.getService("userService")` now types as `UserService | undefined`.
+```
+
+The package root barrel already imports this file for its side
+effects — explicit import is only required when the consumer pulls
+the user-service file directly via the subpath export.
+
+## Usage: Advanced
+
+Downstream plugins that depend on the user service can resolve it
+inside their own `onInit`:
+
+```ts
+const userService = ctx.getService("userService");
+if (!userService) {
+    throw new PluginError(PLUGIN_CODES.SERVICE_NOT_AVAILABLE, "userService");
+}
+const profile = await userService.getById(principal.id);
+```
+
+## API Reference
+
+The module has no runtime exports — it is a pure type-level
+augmentation. The augmentation adds:
+
+```ts
+declare module "@suaveplan/api-plugin/service-registry" {
+    interface ServiceRegistry {
+        userService: UserService;
+    }
+}
+```
+
+## Implementation Notes
+
+- The augmentation is intentionally minimal — host-side slots
+  (`app`, `openAPIRegistry`, `migrationRunner`, `db`) are declared by
+  the auth plugin's augmentation and merged in by TypeScript.
+- The side-effect import in `src/index.ts` is what makes the
+  augmentation visible to consumers; removing it would silently
+  weaken typing.
+- This file MUST NOT carry runtime code — Vite would emit a chunk
+  with no exports otherwise.