suaveplan/packages/api/api-plugin-banking

@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

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 — 14 BANKING.* codes + BankingError.
• otel/instruments — 6 OTel instruments.
• schemas/schemas — 11 Zod schemas.
• schemas/options — plugin options schema.
• repositories/base-repository — shared CRUD scaffold + field whitelist.
• repositories/bank-repository — bank-institution surface.
• repositories/account-repository — bank-account surface + fund-movement primitives.
• service/service — BankingService coordinator with policy enforcement.
• routes/build-routes — 19 OpenAPIHono routes.
• plugin/plugin — createBankingPlugin factory + tenant decommission helper.
• services/registry-augmentation — bankingService / app / db slots.
• types/types — 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)