Initial Commit

packages/api/api-plugin-banking/README.md

@@ -0,0 +1,71 @@
+# `@suaveplan/api-plugin-banking`
+
+Banking foundation plugin for `@suaveplan/api`: bank-institution +
+bank-account CRUD on SurrealDB, account-number arithmetic, fund-transfer
+primitive with overdraft policy, soft-delete + status FSM, default-bank
+bootstrap, full Hono OpenAPI route surface, `BANKING.*` error codes,
+OTel instruments, and lifecycle helpers for tenant create / delete.
+
+## Quick start
+
+```ts
+import { createBankingPlugin } from "@suaveplan/api-plugin-banking";
+
+const plugin = createBankingPlugin({
+    routePrefix: "/banking",
+    maxAccountsPerUser: 10,
+    enableTransfers: true,
+    enableOverdraft: false,
+});
+
+registry.register(plugin);
+```
+
+## Modules
+
+- [`error-codes/error-codes`](./src/error-codes/error-codes.md) — 14
+  `BANKING.*` codes + `BankingError`.
+- [`otel/instruments`](./src/otel/instruments.md) — 6 OTel instruments.
+- [`schemas/schemas`](./src/schemas/schemas.md) — 11 Zod schemas.
+- [`schemas/options`](./src/schemas/options.md) — plugin options schema.
+- [`repositories/base-repository`](./src/repositories/base-repository.md) —
+  shared CRUD scaffold + field whitelist.
+- [`repositories/bank-repository`](./src/repositories/bank-repository.md) —
+  bank-institution surface.
+- [`repositories/account-repository`](./src/repositories/account-repository.md) —
+  bank-account surface + fund-movement primitives.
+- [`service/service`](./src/service/service.md) — `BankingService`
+  coordinator with policy enforcement.
+- [`routes/build-routes`](./src/routes/build-routes.md) — 19 OpenAPIHono
+  routes.
+- [`plugin/plugin`](./src/plugin/plugin.md) — `createBankingPlugin`
+  factory + tenant decommission helper.
+- [`services/registry-augmentation`](./src/services/registry-augmentation.md) —
+  `bankingService` / `app` / `db` slots.
+- [`types/types`](./src/types/types.md) — record aliases, result
+  wrappers, lifecycle event payloads, `BankingEventMap`.
+
+## Lifecycle
+
+1. `onInit` — resolves `db` from `ServiceRegistry`, constructs
+   `BankingService`, registers it under `bankingService`, emits
+   `banking:initialized`.
+2. `onReady` — bootstraps the configured default bank, mounts the
+   route tree on `app` under `config.routePrefix`, emits
+   `banking:ready`.
+3. `onClose` — drops the cached service.
+
+## SurQL migration
+
+`surql/001-bank-and-account.surql` carries the canonical schema,
+the sort-code / account-number function library, and the
+`user_account` relation. The migration runner of
+`@suaveplan/api-plugin-database` consumes it from the configured
+`migrations.directory`.
+
+## Status
+
+- Version: 0.1.0
+- Tier: server (Bun / Node)
+- Tests: real SurrealDB testcontainer; no mocks
+- Coverage gate: 100% / 100% / 100% / 100% (istanbul)