first commit

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

@@ -0,0 +1,44 @@
+# `registry-augmentation.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This file is a type-only `declare module "@suaveplan/api-plugin/service-registry"` block. It adds two slots to the shared `ServiceRegistry` interface so downstream plugins can resolve `ctx.getService("exportProviders")` and `ctx.getService("exportJobs")` with full typing — `Map<string, DataProvider>` and `Map<string, ExportJob>` respectively. The file produces no emitted runtime code; the only side effect is the type augmentation, which is why `src/index.ts` imports it for its side effects (so consumers using the package barrel pick up the slot types automatically).
+
+## Features
+
+- Adds `exportProviders: Map<string, DataProvider>` to `ServiceRegistry`.
+- Adds `exportJobs: Map<string, ExportJob>` to `ServiceRegistry`.
+- No runtime cost — the file emits no JavaScript.
+
+## Usage: Basic
+
+```ts
+import "@suaveplan/api-plugin-export"; // pulls the augmentation through the barrel
+// Now ctx.getService("exportProviders") is typed Map<string, DataProvider> | undefined
+```
+
+## Usage: Advanced
+
+```ts
+import "@suaveplan/api-plugin-export/services/registry-augmentation";
+
+// In a downstream plugin's onInit:
+const providers = ctx.getService("exportProviders");
+if (!providers) throw new Error("export plugin not initialised");
+providers.set("orders", myOrderProvider);
+```
+
+## API Reference
+
+| Symbol | Kind | Notes |
+|---|---|---|
+| `ServiceRegistry.exportProviders` | augmentation | `Map<string, DataProvider>`. |
+| `ServiceRegistry.exportJobs` | augmentation | `Map<string, ExportJob>`. |
+
+## Implementation Notes
+
+The augmentation pattern is identical to `@suaveplan/api-plugin-database`'s `registry-augmentation.ts` — both files exist purely to add slots to the shared registry interface defined by `@suaveplan/api-plugin/service-registry`. Without this file, every call site would have to cast the `getService("exportProviders")` return value, defeating the type safety that the `ServiceRegistry` interface was designed to provide. The two slots cover the two distinct concerns the plugin owns: the *registry* of data providers (writable by every consumer that wants to expose a resource for export) and the *store* of jobs (mutated by the route layer, observable by anyone tracking export progress). Exposing both is a deliberate departure from upstream, which exposed them via `ctx.registerService(...)` at runtime but never declared the corresponding types.