Initial transfer API rail: client, router, docs fetcher, tests

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -0,0 +1,115 @@
+# api-transfer-joesph
+
+ISO 20022 transfer API rail for single-point cash transfer credit messages. Connects to an external API (base URL + API key) and exposes a client and optional HTTP endpoint for core banking applications.
+
+## Configuration
+
+Environment variables (see [.env.example](.env.example)):
+
+| Variable | Description |
+|----------|-------------|
+| `TRANSFER_RAIL_BASE_URL` | External API base URL (e.g. `http://187.43.157.150`) |
+| `TRANSFER_RAIL_API_KEY` | API key (e.g. IPv6 or token from provider) |
+| `TRANSFER_RAIL_DOCS_PATH` | Optional; path to API docs (default: `/openapi.json`) |
+| `TRANSFER_RAIL_API_KEY_HEADER` | Optional; header name for API key (default: `X-API-Key`) |
+| `TRANSFER_RAIL_PORT` | Optional; port for standalone server (default: `4001`) |
+
+Do not commit `.env`. Use a secret manager in production.
+
+## Usage
+
+### Option A — As a library (in-process)
+
+In the core banking app, add this repo as a submodule (e.g. `transfer-rail/`) and depend on it:
+
+```json
+"dependencies": {
+  "api-transfer-joesph": "file:./transfer-rail"
+}
+```
+
+Then:
+
+```ts
+import { createTransferRailClient, getTransferRailConfig } from 'api-transfer-joesph';
+
+const config = getTransferRailConfig();
+const client = createTransferRailClient(config);
+
+const result = await client.sendCreditTransfer({
+  messageType: 'pacs.008',
+  sender: 'SENDERBIC',
+  receiver: 'RECEIVERBIC',
+  document: { amount: '100', currency: 'USD' },
+});
+```
+
+### Option B — As an HTTP endpoint (sidecar)
+
+Mount the router in your Express app:
+
+```ts
+import { createTransferRailRouter } from 'api-transfer-joesph/router';
+
+app.use('/api/transfer-rail', createTransferRailRouter());
+```
+
+Or run the standalone server:
+
+```bash
+npm run start
+# Listens on TRANSFER_RAIL_PORT or 4001
+```
+
+Endpoints:
+
+- `GET /api/transfer-rail/health` — health check (and optional external API reachability).
+- `POST /api/transfer-rail/iso20022/send` — body: `{ messageType, sender, receiver, document }` (aligned with asle bank API). Returns `{ success, messageId }`.
+
+### Fetching API docs from the external host
+
+```ts
+import { fetchApiDocs, getTransferRailConfig } from 'api-transfer-joesph';
+
+const config = getTransferRailConfig();
+const docs = await fetchApiDocs(config);
+if (docs.ok && typeof docs.body === 'object') {
+  console.log('OpenAPI spec:', docs.body);
+}
+```
+
+## Adding this repo as a submodule (core banking app)
+
+From the root of the core banking application repo:
+
+```bash
+git submodule add <repo-url> transfer-rail
+git add .gitmodules transfer-rail
+git commit -m "Add api-transfer-joesph as transfer-rail submodule"
+```
+
+Clone the parent repo with submodules:
+
+```bash
+git clone --recurse-submodules <parent-repo-url>
+# or after clone:
+git submodule update --init --recursive
+```
+
+Update the submodule to latest:
+
+```bash
+git submodule update --remote transfer-rail
+```
+
+## Build and test
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## License
+
+ISC