From c3d4d5ff02a93640f5179f76bc94298b5cd1fc65 Mon Sep 17 00:00:00 2001 From: Andrei Date: Wed, 29 Jul 2026 17:14:04 +0300 Subject: [PATCH] feat: docs deep-scan: read the whole of banking (src + bins + README + MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs deep-scan: read the whole of banking (src + bins + README + docs/) and update all docs to match current behavior — README accuracy, CLI help parity, missing docs pages; PR-first, conventional commits [loop-infinity-300pr] X-Factory-Run: run_9488b934b120 X-Factory-Task: c7f19fce-748c-4d76-a9cf-ab9457d0f97f --- README.md | 37 ++++++--- docs/CLI.md | 97 ++++++++++++++++++++++ docs/MCP.md | 59 +++++++++++++ docs/README.md | 19 +++++ docs/SDK.md | 91 ++++++++++++++++++++ docs/migration/iapp-payments-to-banking.md | 6 +- docs/providers/api-inventory-2026-06-29.md | 7 +- src/cli/index.ts | 10 ++- 8 files changed, 309 insertions(+), 17 deletions(-) create mode 100644 docs/CLI.md create mode 100644 docs/MCP.md create mode 100644 docs/README.md create mode 100644 docs/SDK.md diff --git a/README.md b/README.md index 806138f..a41978e 100644 --- a/README.md +++ b/README.md @@ -2,17 +2,16 @@ Agent-safe banking control plane for infrastructure and AI agents. -`@hasna/banking` is the public OSS package for a provider-capability model, -typed SDK, `banking` CLI, and `banking-mcp` entrypoint. It is request-oriented: -agents can inspect banking state and request payment/card actions, but live -money movement must pass policy, idempotency, approval, audit, and -reconciliation gates. +`@hasna/banking` provides a provider-capability model, typed SDK, `banking` +CLI, and `banking-mcp` descriptor entrypoint. It is request-oriented: Mercury +state can be read through the explicit live-read adapter, while payment and +card commands create local intent envelopes. No provider-side mutation path is +enabled. ## Target Surfaces | Surface | Target | | --- | --- | -| Local folder | `open-banking` | | GitHub repo | `hasna/banking` | | npm package | `@hasna/banking` | | CLI | `banking` | @@ -44,7 +43,8 @@ provider conformance task. | Mercury mutations | Descriptor and request-envelope only. Payments, internal transfers, card lifecycle, webhooks, recipients, attachments, categories, customers, invoices, onboarding, and metadata writes do not execute provider side effects. | | Erste BCR PSD2 AIS/PIS | Descriptor and conformance-fixture only. Consent, SCA, account, transaction, payment, cancellation, and creditor-confirmation flows are modeled but not executed against sandbox or production. | | Erste BCR non-PSD2 extras | Unsupported. Direct card control, card-account AIS, funds confirmation, signing baskets, party verification, sensitive card data, and Mercury-style webhooks fail closed. | -| MCP tools | Local descriptors and request envelopes only. Generic card MCP helpers deny unsupported providers such as Erste BCR through policy. | +| Generic SDK reads | Return `provider_backed_pending`; use `createMercuryReadClient` or the live CLI commands for implemented Mercury reads. | +| MCP tools | Callable as local library helpers for descriptors and request envelopes. The binary lists tools but does not implement the MCP wire protocol. | ## Install @@ -52,6 +52,8 @@ provider conformance task. bun add @hasna/banking ``` +Runtime and source-development commands require Bun 1.3 or newer. + ## State and paths The package currently owns no persistent user-level state, and installation @@ -80,7 +82,10 @@ banking cards list --provider mercury --account acct_123 --live true --environme banking transactions list --provider mercury --live true --environment sandbox --limit 10 --order desc --json banking transactions list --provider mercury --account acct_123 --live true --environment sandbox --limit 10 --order desc --json banking payments request --provider mercury --account acct_123 --amount 10.00 --currency USD --to "Vendor" --recipient recipient_123 --rail ach --json +banking payments status --provider mercury --request req_123 --provider-payment mercury_123 --json banking cards request --provider mercury --account acct_123 --label "Ops" --limit-month 250.00 --currency USD --json +banking cards update --provider mercury --card card_123 --label "Travel" --json +banking cards freeze --provider mercury --card card_123 --json ``` Mercury live reads are available for accounts, balances, transactions, and @@ -104,6 +109,9 @@ For source checkouts: BANKING_MERCURY_LIVE_SMOKE=true BANKING_MERCURY_ENVIRONMENT=sandbox BANKING_MERCURY_LIVE_SMOKE_LIMIT=1 bun run smoke:mercury:live ``` +See the [CLI reference](docs/CLI.md) for the complete command, option, +credential, output, and exit-status contract. + `banking ops list`, `banking ops describe`, and `banking ops plan` expose the shared provider operation registry used to expand CLI, SDK, and MCP surfaces. The Mercury registry covers the current official API families: accounts, @@ -143,7 +151,9 @@ const banking = createBankingClient(); console.log(banking.listProviders()); ``` -The SDK exports provider capability cards and provider-agnostic primitives for: +See the [SDK reference](docs/SDK.md) for the current exported surfaces and +execution boundaries. The SDK exports provider capability cards and +provider-agnostic primitives for: - exact minor-unit money values; - request-oriented payment and card intents; @@ -165,6 +175,8 @@ See [`docs/migration/iapp-payments-to-banking.md`](docs/migration/iapp-payments- for the migration checklist from existing payment integrations to the provider-operation model. +For all current and historical pages, see the [documentation index](docs/README.md). + ## MCP ```bash @@ -172,6 +184,9 @@ banking-mcp --help banking-mcp --list-tools ``` -The MCP entrypoint exposes stable tool descriptors and local request-envelope -dispatch helpers. The full MCP protocol server lands after the store and -provider adapter nodes. +See the [MCP reference](docs/MCP.md) for every tool and dispatch input. The +MCP module exposes stable tool descriptors and local request-envelope +dispatch helpers. `banking-mcp --list-tools` prints descriptors and provider +cards as JSON. Invoking `banking-mcp` without one of the implemented flags +prints an error and exits with status 1 because the MCP protocol server is not +implemented. diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 0000000..28a2352 --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,97 @@ +# CLI reference + +The `banking` binary exposes provider descriptors, four Mercury live-read +operations, and local payment/card intent builders. It does not execute +provider-side mutations. + +```bash +banking --help +banking --version +``` + +`-h` and `-v` are aliases. Options accept either `--key value` or +`--key=value`. `--json` requests JSON output where a command can otherwise emit +plain text. + +## Provider operation registry + +| Command | Required input | Optional input | Result | +| --- | --- | --- | --- | +| `ops list` | none | `--provider`, `--safety`, `--include-unsupported true`, `--json` | Matching operation descriptors. Unsupported descriptors are omitted by default. | +| `ops describe ` | operation id | `--json` | One operation descriptor or an invalid-request error. | +| `ops plan ` | operation id, `--environment` | `--scopes `, `--env-keys `, `--json` | A non-executing environment, credential, scope, and conformance plan. | +| `providers list` | none | `--json` | All provider capability cards. | +| `providers show ` | provider id | `--json` | One provider capability card. | + +Valid providers are `mercury`, `bunq`, `revolut-business`, and `erste-bcr`. +Valid environments are `sandbox` and `production`. Valid `--safety` values are +`read`, `metadata_write`, `money_movement`, `card_lifecycle`, +`sensitive_read`, `webhook_mutation`, and `auth_flow`. + +`--scopes` and `--env-keys` are comma-separated. The singular aliases +`--scope` and `--env-key` are also accepted. Supplying environment key names to +`ops plan` marks them present for preflight; never put credential values on the +command line. + +## Live reads + +Live reads require `--live true`, `--provider mercury`, and an explicit +`--environment sandbox|production`. Without `--live true`, read commands fail +closed with exit status 2. Other providers also fail closed with status 2. + +| Command | Required input | Pagination and filters | +| --- | --- | --- | +| `accounts list` | `--provider` | `--limit 1..1000`, `--order asc|desc`, one of `--start-after` or `--end-before` | +| `balances get` | `--provider`, `--account` | none | +| `transactions list` | `--provider` | optional `--account`, `--limit 1..1000`, `--order asc|desc`, one of `--start-after`, `--end-before`, or `--start-at` | +| `cards list` | `--provider` | optional `--account`, `--limit 1..1000`, `--order asc|desc`, one of `--start-after` or `--end-before` | + +Credentials resolve in this order: the environment-specific +`MERCURY_SANDBOX_API_KEY` or `MERCURY_PRODUCTION_API_KEY`, then +`MERCURY_API_KEY`, then the optional `--secret-key `. A secret +reference is resolved by running `secrets get ` locally; it is not a +raw token argument. + +The client sends Bearer authentication to the environment-specific Mercury API +base URL. Responses are normalized and sensitive account/routing/card fields +are reduced to summaries; raw credentials are never returned. + +## Local intent envelopes + +These commands return an intent, its idempotency fingerprint, and a policy +decision. They never submit the intent to a provider. + +| Command | Required input | Optional input | +| --- | --- | --- | +| `payments quote` | `--provider`, `--account`, `--amount`, `--currency`, `--to` | `--recipient`, `--rail` | +| `payments request` | `--provider`, `--account`, `--amount`, `--currency`, `--to` | `--recipient`, `--rail` | +| `payments status` | `--provider`, `--request` | `--provider-payment` | +| `cards request` | `--provider`, `--account`, `--label` | `--limit-month` with required `--currency` | +| `cards update` | `--provider`, `--card` | `--label` | +| `cards freeze` | `--provider`, `--card` | none | +| `cards unfreeze` | `--provider`, `--card` | none | +| `cards terminate` | `--provider`, `--card` | none | + +All envelope commands accept `--actor ` (default `agent-cli`), +`--reason ` (a command-specific default), `--live true`, and +`--environment sandbox|production` (default `sandbox`). `--live true` changes +policy evaluation only; it does not enable provider submission. Payment rails +default to `ach`. Currency codes are uppercased before money parsing. + +## Admin gate + +`banking admin --help` reports the planned administrative surface. Any other +`admin` command returns `admin_approval_required`; provider verification is not +implemented. + +## Output and exit status + +| Status | Meaning | +| --- | --- | +| `0` | Help/version or a command completed successfully. A successful local envelope may still contain a denied policy decision. | +| `1` | Unknown command, missing/invalid input, invalid provider/environment, or provider/API error caught as `invalid_request`. | +| `2` | A requested read adapter is not implemented, live mode was omitted, or the provider has no live adapter. | +| `3` | An administrative command is gated. | + +Structured errors are written to stderr. Unknown commands are plain text unless +`--json` is set; validation and adapter errors are JSON objects in either mode. diff --git a/docs/MCP.md b/docs/MCP.md new file mode 100644 index 0000000..04be58e --- /dev/null +++ b/docs/MCP.md @@ -0,0 +1,59 @@ +# MCP reference + +The package contains an MCP-shaped descriptor and local dispatch module, not an +MCP protocol server. + +## Binary + +```bash +banking-mcp --help +banking-mcp --version +banking-mcp --list-tools +``` + +`-h` and `-v` are aliases. These commands exit with status 0. +`--list-tools` prints tool descriptors and provider capability cards as JSON. +Invoking the binary without an implemented flag prints an error and exits 1; +it does not start a stdio, HTTP, or SSE MCP transport. + +## Library dispatch + +The MCP module exports `listMcpTools`, `listMcpToolDescriptors`, +`listPlannedMcpTools`, and `runMcpTool`. `runMcpTool(name, input)` is a local +function call and does not perform MCP transport or schema negotiation. + +| Tool | Status | Input | +| --- | --- | --- | +| `banking_ops_list` | implemented | optional `providerId`, `includeUnsupported` | +| `banking_ops_describe` | implemented | `operationId` | +| `banking_ops_plan` | implemented | `operationId`, `environment`; optional `grantedScopes`, `envKeys` | +| `banking_providers_list` | implemented | none | +| `banking_provider_get` | implemented | `providerId` | +| `banking_accounts_list` | provider-backed pending | `providerId` | +| `banking_balance_get` | provider-backed pending | `providerId`, `accountId` | +| `banking_transactions_list` | provider-backed pending | `providerId`, `accountId` | +| `banking_cards_list` | provider-backed pending | `providerId` | +| `banking_payment_quote` | implemented locally | payment input | +| `banking_payment_request` | implemented locally | payment input | +| `banking_payment_status` | implemented locally | `providerId`, `paymentRequestId`; optional `providerPaymentId` | +| `banking_card_request` | implemented locally | `providerId`, `accountId`, `label` | +| `banking_card_update_request` | implemented locally | `providerId`, `cardId`; optional `label` | +| `banking_card_freeze_request` | implemented locally | `providerId`, `cardId` | +| `banking_card_unfreeze_request` | implemented locally | `providerId`, `cardId` | +| `banking_card_terminate_request` | implemented locally | `providerId`, `cardId` | +| `banking_admin_provider_verify_operation` | admin gated | none | + +Payment input requires `providerId`, `sourceAccountId`, `counterpartyName`, +`amount`, and `currency`; `providerRecipientId`, `rail`, `actorId`, `reason`, +`liveMode`, and `environment` are optional. The default rail is `ach`, actor is +`agent-mcp`, and environment is `sandbox`. + +Card and payment tools create local intent envelopes only. `liveMode: true` +changes policy evaluation but does not submit the intent. Generic read tools +return `provider_backed_pending` and do not use the Mercury network adapter. +The admin tool returns `admin_approval_required`. Unknown names return +`not_implemented` rather than throwing. + +`grantedScopes` and `envKeys` accept either a comma-separated string or a string +array. Provider ids and environments are validated. Missing required string +fields throw an error to the direct caller. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5d6fa85 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,19 @@ +# Documentation + +Current behavior is documented here: + +- [CLI reference](CLI.md): commands, options, credentials, output, and exit status. +- [SDK reference](SDK.md): exported surfaces, execution boundaries, workflow, and stores. +- [MCP reference](MCP.md): binary behavior, tool descriptors, dispatch inputs, and limitations. +- [State layout](STATE_LAYOUT.md): package-owned and caller-owned paths. +- [Postgres schema](schema/postgres.sql): production-store reference schema and transaction boundary. +- [Migration guide](migration/iapp-payments-to-banking.md): moving direct integrations to the provider-operation model. + +Dated research and evidence are retained separately: + +- [Provider API inventory (2026-06-29)](providers/api-inventory-2026-06-29.md) +- [0.0.2 release evidence](releases/0.0.2.md) +- [0.0.7 release evidence](releases/0.0.7.md) + +Dated pages describe what was checked or released at that time. Use the current +references above for the package's present command and API behavior. diff --git a/docs/SDK.md b/docs/SDK.md new file mode 100644 index 0000000..d7d7aa7 --- /dev/null +++ b/docs/SDK.md @@ -0,0 +1,91 @@ +# SDK reference + +The package root exports the core model, provider model and contracts, Mercury +read adapter, and Bun SQLite development store. + +```ts +import { + createBankingClient, + createMercuryReadClient, + createSqliteDevStore, + moneyFromDecimal, +} from "@hasna/banking"; +``` + +## Client boundary + +`createBankingClient()` provides provider capability lookup and local intent +envelope builders. Its generic read methods validate the provider and return a +`provider_backed_pending` result; they do not call provider APIs. + +| Method | Current result | +| --- | --- | +| `listProviders`, `getProvider` | Provider capability cards. | +| `listAccounts`, `getBalance`, `listTransactions`, `listCards` | `provider_backed_pending`; no network call. | +| `createPaymentQuote`, `createPaymentRequest`, `createPaymentStatus` | Local intent, idempotency fingerprint, and policy decision. | +| `createCardRequest`, `createCardUpdate`, `createCardLifecycle` | Local intent, idempotency fingerprint, and policy decision. Unsupported provider/card combinations are denied by policy. | + +Creating an envelope never submits it. The default policy is dry-run sandbox +mode, requires approval for provider side effects, and denies sensitive card +data. Callers can supply a `BankingPolicy` to the envelope methods. + +## Mercury live reads + +`createMercuryReadClient` is the only network-backed SDK adapter. It requires an +explicit `sandbox` or `production` environment and resolves credentials from an +`apiKey`, the matching environment variable, `MERCURY_API_KEY`, or an optional +secret reference callback/CLI. + +The adapter implements: + +- `listAccounts`; +- `getBalance`; +- `listCards`, optionally account-filtered; +- `listTransactions`, optionally account-filtered. + +List methods accept limit, order, and cursor input. Limits must be between 1 +and 1000. Only transactions accept `startAt`. Responses are normalized into +summary types; account/routing numbers and card details are not exposed as raw +provider payloads. `MercuryCredentialError` reports credential failures and +`MercuryApiError` reports sanitized transport, response, and validation errors. + +## Provider registry and contracts + +Use `listOperationDescriptors`, `getOperationDescriptor`, or +`requireOperationDescriptor` to inspect provider operations. `planProviderOperation` +combines the descriptor with environment, scope, credential-key, and provider +security preflights. A plan describes readiness; it does not execute an +operation. + +Provider contract helpers validate request shape and build provider-safe +request descriptors. Conformance exports pin the Mercury live-read allowlist +and the Erste BCR AIS/PIS fixture surface. A documented provider capability is +not proof of implemented execution: check descriptor `executionMode`, +`liveReadEnabled`, `providerSideEffectsEnabled`, and conformance fields. + +## Core workflow + +The core exports exact minor-unit money helpers, typed payment/card intents, +policy evaluation, deterministic idempotency fingerprints, maker-checker +approvals, redacted hash-chained audit events, reconciliation, and execution +workflow helpers. + +`submitExecutionRequest` reserves idempotency, saves the intent, appends audit +evidence, and returns one of the workflow states. Approved requests enqueue a +`provider.dry_run` outbox entry with `providerSideEffectsEnabled: false`; the +workflow does not perform a provider mutation. Approval execution verifies the +intent binding, payload hash, expiry, human approver, maker-checker separation, +and policy snapshot. + +## Stores + +`BankingCoreStore` is the asynchronous storage contract. `createSqliteDevStore` +implements it with `bun:sqlite`, uses `:memory:` by default, and is explicitly +`mode: "dev"`. A supplied file path is caller-owned. The store supports +idempotency reservations, intents, approvals, audit events, reconciliation, +and outbox transitions, plus a development-only `reset()`. + +Production implementations should follow the [Postgres reference +schema](schema/postgres.sql) and perform reservation, intent persistence, +approval validation, audit append, and outbox enqueue in one serializable +transaction before any future provider side effect. diff --git a/docs/migration/iapp-payments-to-banking.md b/docs/migration/iapp-payments-to-banking.md index 8de6922..208d84f 100644 --- a/docs/migration/iapp-payments-to-banking.md +++ b/docs/migration/iapp-payments-to-banking.md @@ -3,8 +3,7 @@ Date: 2026-06-29 This note is for moving existing payment or bank-integration code, including -`iapp-payments`-style flows, onto the public `hasna/banking` OSS package while -keeping the local checkout folder named `open-banking`. +`iapp-payments`-style flows, onto the public `hasna/banking` OSS package. ## Naming @@ -14,7 +13,6 @@ keeping the local checkout folder named `open-banking`. | npm package | `@hasna/banking` | | CLI binary | `banking` | | MCP binary | `banking-mcp` | -| Local folder | `open-banking` | Do not keep a separate plain-provider integration path. Provider behavior should flow through the operation registry, SDK policy primitives, CLI commands, and @@ -50,6 +48,8 @@ MCP descriptors. 6. Keep provider execution behind conformance, approval, idempotency, audit, reconciliation, and adversarial review gates. +See the [CLI reference](../CLI.md) for the complete current command contract. + ## Smoke And Verification ```bash diff --git a/docs/providers/api-inventory-2026-06-29.md b/docs/providers/api-inventory-2026-06-29.md index 7393bc1..6b35088 100644 --- a/docs/providers/api-inventory-2026-06-29.md +++ b/docs/providers/api-inventory-2026-06-29.md @@ -6,6 +6,11 @@ registry. It intentionally separates verified provider capabilities from implementation decisions so the CLI, SDK, and MCP server can grow through descriptors instead of ad hoc command branches. +This is a dated research and roadmap artifact, not the current command +reference. Commands under “Scalable CLI Architecture Requirements” are design +targets unless they also appear in the current [CLI reference](../CLI.md). Use +the [SDK](../SDK.md) and [MCP](../MCP.md) references for present behavior. + ## Sources Checked | Provider | Source | Status | @@ -223,7 +228,7 @@ advertise or implement: These are not PSD2 AIS/PIS capabilities in the public source set. -## Scalable CLI Architecture Requirements +## Historical Scalable CLI Architecture Requirements The implementation now uses a provider operation registry with typed descriptors. The descriptor drives CLI, SDK, MCP, docs, tests, and policy gates diff --git a/src/cli/index.ts b/src/cli/index.ts index 144d2e7..6592869 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -48,15 +48,21 @@ Usage: banking transactions list --provider [--account ] [--live true --environment --secret-key ] [--limit ] [--order ] [--start-after |--end-before |--start-at ] [--json] banking payments quote --provider --account --amount --currency --to [--recipient ] [--rail ] [--json] banking payments request --provider --account --amount --currency --to [--recipient ] [--rail ] [--json] - banking payments status --provider --request [--json] + banking payments status --provider --request [--provider-payment ] [--json] banking cards list --provider [--account ] [--live true --environment --secret-key ] [--limit ] [--order ] [--start-after |--end-before ] [--json] banking cards request --provider --account --label