first commit

docs/api-stack/api/api-plugin-payment/src/services/registry-augmentation.md

@@ -0,0 +1,47 @@
+# 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.