# 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.