# `@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)