# registry-augmentation

## Purpose

TypeScript module augmentation that adds the `paymentService` slot to `@suaveplan/api-plugin/service-registry`'s `ServiceRegistry` interface. Without this declaration, `ctx.getService("paymentService")` types as `never` because the base `ServiceRegistry` is empty and only consumer-declared augmentations populate it. Importing this module (which the package root barrel does for its side effect) ensures every downstream plugin that depends on `@suaveplan/api-plugin-payment` sees the typed slot.

The file also redeclares the host-side slots (`app`, `openAPIRegistry`, `logger`, `eventBus`, `clock`) so the payment plugin's `onInit` resolves them with full typing even when the consumer has not transitively pulled in `@suaveplan/api`'s own registry augmentation. TypeScript merges duplicate declarations of the same interface, so coexistence with `@suaveplan/api`'s file is safe.

## Features

- Adds `paymentService: PaymentService` to `ServiceRegistry`.
- Redeclares the 5 host slots so isolated unit-tests don't have to import `@suaveplan/api`.
- Pure type-level — zero runtime cost.

## Usage: Basic

```ts
// Side-effect import — augments the global ServiceRegistry
import "@suaveplan/api-plugin-payment/services/payment-service";

const service = ctx.getService("paymentService"); // typed PaymentService | undefined
```

## Usage: Advanced

```ts
// In a downstream plugin:
import type { PaymentService } from "@suaveplan/api-plugin-payment/services/payment-service";

declare module "@suaveplan/api-plugin/service-registry" {
    interface ServiceRegistry {
        subscriptionEngine: SubscriptionEngine;
    }
}

// Consumes both this plugin's slot and its own:
const payment = ctx.getService("paymentService");
const subs = ctx.getService("subscriptionEngine");
```

## API Reference

This module has no runtime exports — it contributes the `paymentService` slot via TypeScript module augmentation.

## Implementation Notes

The host-slot redeclaration is intentional duplication. TypeScript merges duplicate interface declarations, so having both `@suaveplan/api` and `@suaveplan/api-plugin-payment` declare `app: OpenAPIHono` is type-safe. The benefit is that the payment plugin's tests can construct a `PluginContext` directly (without booting a full `@suaveplan/api` instance) and still type-check the `ctx.getService("app")` call sites — a small ergonomic win that avoids a circular dev-dependency on the orchestrator package.