Initial commit: add .gitignore and README

2026-02-09 21:51:45 -08:00
commit 929fe6f6b6
240 changed files with 40977 additions and 0 deletions
--- a/docs/api/reference.md
+++ b/docs/api/reference.md
@@ -0,0 +1,276 @@
+# API Documentation
+
+## Authentication
+
+All API endpoints (except `/api/auth/login`) require authentication via JWT token in the Authorization header:
+
+```
+Authorization: Bearer <token>
+```
+
+## Endpoints
+
+### Authentication
+
+#### POST /api/auth/login
+
+Operator login.
+
+**Request Body**:
+```json
+{
+  "operatorId": "string",
+  "password": "string",
+  "terminalId": "string" (optional)
+}
+```
+
+**Response**:
+```json
+{
+  "token": "string",
+  "operator": {
+    "id": "string",
+    "operatorId": "string",
+    "name": "string",
+    "role": "MAKER" | "CHECKER" | "ADMIN"
+  }
+}
+```
+
+#### POST /api/auth/logout
+
+Operator logout.
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Response**:
+```json
+{
+  "message": "Logged out successfully"
+}
+```
+
+#### GET /api/auth/me
+
+Get current operator information.
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Response**:
+```json
+{
+  "id": "string",
+  "operatorId": "string",
+  "name": "string",
+  "role": "MAKER" | "CHECKER" | "ADMIN"
+}
+```
+
+### Payments
+
+#### POST /api/payments
+
+Initiate payment (Maker role required).
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Request Body**:
+```json
+{
+  "type": "CUSTOMER_CREDIT_TRANSFER" | "FI_TO_FI",
+  "amount": 1234.56,
+  "currency": "USD" | "EUR" | "GBP" | "JPY",
+  "senderAccount": "string",
+  "senderBIC": "string",
+  "receiverAccount": "string",
+  "receiverBIC": "string",
+  "beneficiaryName": "string",
+  "purpose": "string" (optional),
+  "remittanceInfo": "string" (optional)
+}
+```
+
+**Response**:
+```json
+{
+  "paymentId": "string",
+  "status": "PENDING_APPROVAL",
+  "message": "Payment initiated, pending approval"
+}
+```
+
+#### POST /api/payments/:id/approve
+
+Approve payment (Checker role required).
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Response**:
+```json
+{
+  "message": "Payment approved and processing",
+  "paymentId": "string"
+}
+```
+
+#### POST /api/payments/:id/reject
+
+Reject payment (Checker role required).
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Request Body**:
+```json
+{
+  "reason": "string" (optional)
+}
+```
+
+**Response**:
+```json
+{
+  "message": "Payment rejected",
+  "paymentId": "string"
+}
+```
+
+#### GET /api/payments/:id
+
+Get payment status.
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Response**:
+```json
+{
+  "paymentId": "string",
+  "status": "string",
+  "amount": 1234.56,
+  "currency": "USD",
+  "uetr": "string" | null,
+  "ackReceived": false,
+  "settlementConfirmed": false,
+  "createdAt": "2024-01-01T00:00:00Z"
+}
+```
+
+#### GET /api/payments
+
+List payments.
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Query Parameters**:
+- `limit` (optional, default: 50)
+- `offset` (optional, default: 0)
+
+**Response**:
+```json
+{
+  "payments": [
+    {
+      "id": "string",
+      "payment_id": "string",
+      "type": "string",
+      "amount": 1234.56,
+      "currency": "USD",
+      "status": "string",
+      "created_at": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "total": 10
+}
+```
+
+### Reconciliation
+
+#### GET /api/reconciliation/daily
+
+Generate daily reconciliation report (Checker role required).
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Query Parameters**:
+- `date` (optional, ISO date string, default: today)
+
+**Response**:
+```json
+{
+  "report": "string (formatted text report)",
+  "date": "2024-01-01"
+}
+```
+
+#### GET /api/reconciliation/aging
+
+Get aging items (Checker role required).
+
+**Headers**: `Authorization: Bearer <token>`
+
+**Query Parameters**:
+- `days` (optional, default: 1)
+
+**Response**:
+```json
+{
+  "items": [
+    {
+      "id": "string",
+      "payment_id": "string",
+      "amount": 1234.56,
+      "currency": "USD",
+      "status": "string",
+      "created_at": "2024-01-01T00:00:00Z",
+      "aging_reason": "string"
+    }
+  ],
+  "count": 5
+}
+```
+
+### Health Check
+
+#### GET /health
+
+Health check endpoint.
+
+**Response**:
+```json
+{
+  "status": "ok",
+  "timestamp": "2024-01-01T00:00:00Z"
+}
+```
+
+## Error Responses
+
+All endpoints may return error responses:
+
+```json
+{
+  "error": "Error message"
+}
+```
+
+Status codes:
+- `400` - Bad Request
+- `401` - Unauthorized
+- `403` - Forbidden
+- `404` - Not Found
+- `500` - Internal Server Error
+
+## Payment Status Flow
+
+1. `INITIATED` - Payment created by Maker
+2. `PENDING_APPROVAL` - Awaiting Checker approval
+3. `APPROVED` - Approved by Checker
+4. `COMPLIANCE_CHECKING` - Under compliance screening
+5. `COMPLIANCE_PASSED` - Screening passed
+6. `LEDGER_POSTED` - Funds reserved in ledger
+7. `MESSAGE_GENERATED` - ISO 20022 message created
+8. `TRANSMITTED` - Message sent via TLS
+9. `ACK_RECEIVED` - Acknowledgment received
+10. `SETTLED` - Settlement confirmed
+11. `FAILED` - Processing failed
+12. `CANCELLED` - Rejected/cancelled