api-transfer-joesph/README.md

# 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