@mojaloop/sdk-scheme-adapter 24.13.0 → 24.14.0-snapshot.1

package/.yarnrc.yml

@@ -4,4 +4,4 @@ enableGlobalCache: false
 
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-4.10.2.cjs
+yarnPath: .yarn/releases/yarn-4.10.3.cjs

package/CLAUDE.md

@@ -0,0 +1,186 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is the Mojaloop SDK Scheme Adapter - a monorepo that provides an adapter interface between Mojaloop API compliant switches and DFSP backend platforms.
+The project consists of multiple modules organized using Nx workspace.
+
+## Quick Reference (Start Here)
+
+| Task | Command | Prerequisites |
+|------|---------|---------------|
+| Run all tests | `yarn test` | - |
+| Run integration tests | `yarn test:integration` | Docker running, `yarn wait-4-docker` |
+| Run specific module test | `yarn workspace @mojaloop/sdk-scheme-adapter-api-svc run test:unit` | - |
+| Build everything | `yarn build` | Node 22.15.1 (`nvm use`) |
+| Start services | `yarn start` | Docker running, modules built |
+| Update OpenAPI | `yarn build:openapi && yarn validate:api` | - |
+| Debug main service | `yarn workspace @mojaloop/sdk-scheme-adapter-api-svc run start:debug` | Port 9229 available |
+
+
+**Critical File Locations:**
+- Models: `modules/api-svc/src/lib/model/`
+- Handlers: `modules/api-svc/src/{Inbound,Outbound}Server/handlers.js`
+- Config: `modules/*/src/config/default.json`
+- OpenAPI templates: `modules/*/src/*_template.yaml` (edit these, not `api.yaml`)
+
+## Architecture
+This service can be referenced as `Mojaloop Connector`, `ML Connector` or `Scheme Adapter`.
+
+### Core Modules
+
+- **api-svc**: Main service module (JavaScript/Node.js) handling inbound/outbound HTTP APIs and core business logic
+- **outbound-command-event-handler**: TypeScript module handling outbound command events using domain-driven design
+- **outbound-domain-event-handler**: TypeScript module processing domain events for outbound operations
+- **private-shared-lib**: Shared TypeScript library containing domain entities, events, and infrastructure code
+
+### Key Components
+
+- **Event-Driven Architecture**: Uses Kafka for event streaming between modules
+- **State Machines**: JavaScript State Machine library for managing transfer states
+- **Cache Layer**: Redis for distributed caching and session management
+- **Models**: Domain models for transfers, quotes, parties, bulk operations
+- **Event Handlers**: FSPIOP and Backend event handling for Mojaloop protocol compliance
+- **ControlAgent**: WebSocket client for PM4ML Management API with optional failsafe polling
+
+## Code Structure Patterns
+
+### API Service (modules/api-svc)
+- **Handlers**: Route handlers in `src/InboundServer/handlers.js` and `src/OutboundServer/handlers.js`
+- **Models**: Business logic in `src/lib/model/` with models like:
+  - `TransfersModel.js` - Transfer operations
+  - `QuotesModel.js` - Quote handling
+  - `AccountsModel.js` - Account management
+  - `InboundTransfersModel.js` - Inbound transfer processing
+  - `OutboundTransfersModel.js` - Outbound transfer processing
+  - `OutboundBulkQuotesModel.js` - Bulk quote operations
+  - `OutboundBulkTransfersModel.js` - Bulk transfer operations
+- **State Machines**: Use `PersistentStateMachine` for managing complex state transitions
+- **Middleware**: Validation and error handling middleware in `middlewares.js`
+- **OpenAPI Templates**: API definitions in `api_template.yaml` files, compiled to `api.yaml`
+
+### Event Handlers (TypeScript modules)
+- **Domain Layer**: Aggregates and entities in `src/domain/`
+- **Application Layer**: Event handlers in `src/application/handlers/`
+- **Infrastructure**: Kafka producers/consumers in shared lib
+- **API Server**: Express-based APIs with OpenAPI specs
+- **Build Process**: TypeScript compilation + file copying (YAML files)
+
+### Testing Patterns
+- **Unit tests**: `test/unit/` directories using Jest
+- **Integration tests**: `test/integration/` requiring Docker services
+- **Functional tests**: Separate test suites in `test/func_bulk/` and `test/func_iso20022/`
+- **Mocks**: Test mocks in `test/__mocks__/`
+- **Setup**: Test setup files like `test/unit/setup.js`
+- **Configuration**: Jest config in individual `jest.config.js` files
+
+## Development Commands
+Check **[development-commands.md](./_cc/docs/development-commands.md)** file to get details about some useful commands to
+build and setup the project, start the services, run tests, linting, deps and audit checks, etc.
+
+## Key Libraries & Dependencies
+
+- **@mojaloop/sdk-standard-components**: Core Mojaloop SDK components
+- **@mojaloop/central-services-***: Mojaloop platform services
+- **@mojaloop/api-snippets**: API specification components
+- **javascript-state-machine**: State management for transfers
+- **redis**: Distributed caching (v5.x)
+- **express/koa**: HTTP servers (Express for newer modules, Koa for some services)
+- **ajv**: JSON schema validation
+- **convict**: Configuration management in TypeScript modules
+- **openapi-backend**: OpenAPI request validation and routing
+- **Package Manager**: Yarn 4.10.2 (Berry)
+
+## Docker Environment
+
+See [development-commands.md](./_cc/docs/development-commands.md#docker-operations) for Docker commands.
+
+**Services:** redis (6379), kafka (9092), ml-testing-toolkit (4040/5050), mojaloop-testing-toolkit-ui (6060)
+**Debug profile adds:** redisinsight (9001), kafka-debug-ui (9080)
+**Main service ports:** 4000-4004, 9229 (debugger)
+
+## Development Patterns & Notes
+
+### Module Architecture
+- **api-svc**: JavaScript-based, legacy module with core functionality
+- **Shared lib**: Private workspace package for cross-module code
+
+### Event Sourcing
+Commands → `outbound-command-event-handler` → Domain events → `outbound-domain-event-handler`
+**Kafka topics:** `topic-sdk-outbound-command-events`, `topic-sdk-outbound-domain-events`
+
+### State Management
+**Redis:** State machine persistence, distributed cache, cross-module communication, bulk transaction tracking
+**Pattern:** `PersistentStateMachine` class for complex state transitions
+
+### OpenAPI Workflow
+1. Edit `*_template.yaml` files (not generated `api.yaml`)
+2. Run `yarn build:openapi` to compile templates
+3. Validate with `yarn validate:api`
+4. Uses `@redocly/openapi-cli` for bundling
+
+### Testing Workflow
+1. **Unit tests**: Run locally without dependencies
+2. **Integration tests**: Require Docker services (Redis, Kafka)
+3. **Functional tests**: Full end-to-end scenarios with TTK
+4. Use `yarn wait-4-docker` to ensure services are ready
+
+## Common Development Tasks
+
+See [development-commands.md](./_cc/docs/development-commands.md) for all commands and [common-workflows.md](./_cc/docs/common-workflows.md) for step-by-step guides.
+
+## For AI Assistants (Memory Management Hints)
+
+**Always Re-read Before:**
+- Modifying OpenAPI specs → Review OpenAPI Workflow section first
+- Running integration tests → Verify Docker prerequisites and Testing Workflow
+- Making state machine changes → Review api-svc-06-state-management.md
+- Debugging test failures → Check development-commands.md for troubleshooting
+
+**Cache (Low Change Frequency):**
+- Architecture: 3 TypeScript modules (command-handler, domain-handler, shared-lib) + api-svc (JavaScript)
+- Event flow: Command events → outbound-command-event-handler → Domain events → outbound-domain-event-handler
+- Redis patterns: State machines, distributed cache, pub/sub, bulk transaction tracking
+- Kafka topics: `topic-sdk-outbound-command-events`, `topic-sdk-outbound-domain-events`
+- Package manager: Yarn 4.10.2 (Berry)
+- Node version: 22.15.1
+
+**Key Patterns to Remember:**
+- Edit `*_template.yaml` files, NEVER edit generated `api.yaml` files
+- State machines use `PersistentStateMachine` class backed by Redis
+- Integration tests require Docker services - use `yarn wait-4-docker`
+- Use workspace syntax: `yarn workspace @mojaloop/sdk-scheme-adapter-<module> run <command>`
+- Nx caching enabled for builds/tests - use `--skip-nx-cache` to bypass
+
+**When Uncertain:**
+- Ask user ANY clarifying questions
+- Check Quick Reference section at top of this file
+- Consult api-svc-01-overview.md for 30-minute onboarding
+- Use development-commands.md for command reference
+- See common-workflows.md for step-by-step task guides
+
+## Documentation
+
+### API-SVC Module Documentation
+
+Comprehensive documentation for the `api-svc` module (core service handling inbound/outbound APIs):
+
+
+| Document | Description |
+|----------|-------------|
+| **[api-svc-01-overview.md](./_cc/docs/api-svc/api-svc-01-overview.md)** | Overview, quick start guide, 30-minute onboarding with core concepts and transfer flows |
+| **[api-svc-02-architecture.md](./_cc/docs/api-svc/api-svc-02-architecture.md)** | System architecture, component design, configuration system, startup sequence |
+| **[api-svc-03-inbound-server.md](./_cc/docs/api-svc/api-svc-03-inbound-server.md)** | Inbound server handling async FSPIOP callbacks from Mojaloop switch |
+| **[api-svc-04-outbound-server.md](./_cc/docs/api-svc/api-svc-04-outbound-server.md)** | Outbound server providing synchronous REST API for DFSP backends |
+| **[api-svc-05-models.md](./_cc/docs/api-svc/api-svc-05-models.md)** | Business logic models orchestrating party lookups, quotes, transfers, bulk operations |
+| **[api-svc-06-state-management.md](./_cc/docs/api-svc/api-svc-06-state-management.md)** | Redis-backed state machines, pub/sub patterns, key patterns, recovery behavior |
+| **[api-svc-07-control-agent.md](./_cc/docs/api-svc/api-svc-07-control-agent.md)** | WebSocket client for PM4ML Management API dynamic configuration |
+| **[api-svc-08-error-handling.md](./_cc/docs/api-svc/api-svc-08-error-handling.md)** | Error taxonomy, Mojaloop error codes, handling patterns, logging strategies |
+| **[api-svc-09-core-dependencies.md](./_cc/docs/api-svc/api-svc-09-core-dependencies.md)** | Core dependencies including @mojaloop/sdk-standard-components, JWS, ILP, OIDC |
+| **[api-svc-10-service-lifecycle.md](./_cc/docs/api-svc/api-svc-10-service-lifecycle.md)** | Service startup/shutdown sequences, component bootstrap order, configuration sources, hot reload |
+| **[api-svc-11-event-handlers.md](./_cc/docs/api-svc/api-svc-11-event-handlers.md)** | Kafka event handlers for domain/command events integration with TypeScript modules |
+| **[api-svc-12-testing.md](./_cc/docs/api-svc/api-svc-12-testing.md)** | Testing strategy covering unit, integration, and functional tests |
+| **[api-svc-13-deployment.md](./_cc/docs/api-svc/api-svc-13-deployment.md)** | Kubernetes deployment with Helm charts, production configuration, monitoring |
+| **[api-svc-14-examples.md](./_cc/docs/api-svc/api-svc-14-examples.md)** | Practical examples: outbound/inbound transfers, error handling, bulk operations, auto-accept |

package/modules/api-svc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojaloop/sdk-scheme-adapter-api-svc",
-  "version": "21.0.0-snapshot.70",
+  "version": "21.0.0-snapshot.72",
   "description": "An adapter for connecting to Mojaloop API enabled switches.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -68,7 +68,7 @@
     "@mojaloop/central-services-error-handling": "13.1.3",
     "@mojaloop/central-services-logger": "11.10.1",
     "@mojaloop/central-services-metrics": "12.8.0",
-    "@mojaloop/central-services-shared": "18.34.0",
+    "@mojaloop/central-services-shared": "18.34.1",
     "@mojaloop/event-sdk": "14.8.0",
     "@mojaloop/logging-bc-client-lib": "0.5.8",
     "@mojaloop/ml-schema-transformer-lib": "2.7.8",

package/modules/api-svc/src/ControlAgent/index.js

@@ -40,12 +40,15 @@
 // the current configuration to
 
 const ws = require('ws');
+const _ = require('lodash');
 const jsonPatch = require('fast-json-patch');
+const safeStringify = require('fast-safe-stringify');
 const { generateSlug } = require('random-word-slugs');
-const _ = require('lodash');
 
 const FORCE_WS_CLOSE_TIMEOUT_MS = 5000;
 
+const cloneJson = (obj) => JSON.parse(safeStringify(obj));
+
 /**************************************************************************
  * The message protocol messages, verbs, and errors
  *************************************************************************/
@@ -77,7 +80,7 @@ const EVENT = {
 /**************************************************************************
  * Private convenience functions
  *************************************************************************/
-const serialise = JSON.stringify;
+const serialise = safeStringify;
 const deserialise = (msg) => {
     //reviver function
     return JSON.parse(msg.toString(), (k, v) => {
@@ -145,7 +148,7 @@ class Client extends ws {
      */
     constructor({ address = 'localhost', port, logger, appConfig }) {
         super(`ws://${address}:${port}`);
-        this._logger = logger.push({ component: 'ControlClient' });
+        this._logger = logger.push({ component: 'ControlClientWs' });
         this._appConfig = appConfig;
     }
 
@@ -173,28 +176,30 @@ class Client extends ws {
     async receive() {
         return new Promise((resolve) => this.once('message', (data) => {
             const msg = deserialise(data);
-            this._logger.isDebugEnabled && this._logger.push({ msg }).debug('Received');
+            this._logger.push({ msg }).debug('Received and deserialized ws message:');
             resolve(msg);
         }));
     }
 
     // Close connection
     async stop() {
-        this._logger.isDebugEnabled && this._logger.debug('Control client shutting down...');
+        this._logger.verbose('Control client shutting down...');
         return new Promise((resolve) => {
             let timer = setTimeout(() => {
-                this._logger.isInfoEnabled && this._logger.info('Control client forced to close');
+                this._logger.warn(`Control client forced to close after ${FORCE_WS_CLOSE_TIMEOUT_MS}ms`);
+                this.terminate();
                 timer = null;
                 resolve(false);
             }, FORCE_WS_CLOSE_TIMEOUT_MS);
 
             this.once('close', () => {
-                this._logger.isInfoEnabled && this._logger.info('Control client is closed');
+                this._logger.info('Control client is closed');
                 if (timer) clearTimeout(timer);
+                this.removeAllListeners();
                 resolve(true);
             });
             this.once('error', (error) => {
-                this._logger.isWarnEnabled && this._logger.push({ error }).warn('Control client failed to close');
+                this._logger.warn('Control client failed to close:', error);
                 if (timer) clearTimeout(timer);
                 resolve(false);
             });
@@ -203,6 +208,23 @@ class Client extends ws {
         });
     }
 
+    /**
+     * Call the Connector Manager in Management API to get the updated config
+     */
+    async getUpdatedConfig() { // clarify naming - why config is updated?
+        this._logger.info(`Getting updated config from Management API at ${this.url}...`);
+        const wsSendResponse = await this.send(build.CONFIGURATION.READ());
+        this._logger.debug('wsSendResponse: ', { wsSendResponse });
+
+        const wsReceivedData = (await this.receive())?.data;
+        this._logger.debug('wsReceivedData: ', { wsReceivedData });
+
+        if (!wsReceivedData) this._logger.warn('no updatedConfigFromMgmtAPI');
+        else this._logger.info('updatedConfigFromMgmtAPI keys:', { updatedConfigFromMgmtAPIKeys: Object.keys(wsReceivedData) });
+
+        return wsReceivedData;
+    }
+
     // Handle incoming message from the server.
     _handle(data) {
         // TODO: json-schema validation of received message- should be pretty straight-forward
@@ -211,7 +233,7 @@ class Client extends ws {
         try {
             msg = deserialise(data);
         } catch {
-            this._logger.isErrorEnabled && this._logger.push({ data }).console.error();('Couldn\'t parse received message');
+            this._logger.warn('failed to parse received message: ', { data });
             this.send(build.ERROR.NOTIFY.JSON_PARSE_ERROR());
         }
         this._logger.isDebugEnabled && this._logger.push({ msg }).debug('Handling received message');
@@ -219,14 +241,14 @@ class Client extends ws {
             case MESSAGE.CONFIGURATION:
                 switch (msg.verb) {
                     case VERB.NOTIFY: {
-                        const dup = JSON.parse(JSON.stringify(this._appConfig)); // fast-json-patch explicitly mutates
+                        const dup = cloneJson(this._appConfig); // fast-json-patch explicitly mutates
                         _.merge(dup, msg.data);
                         this._logger.isDebugEnabled && this._logger.push({ oldConf: this._appConfig, newConf: dup }).debug(`Emitting new agent configuration [${VERB.NOTIFY}]`);
                         this.emit(EVENT.RECONFIGURE, dup);
                         break;
                     }
                     case VERB.PATCH: {
-                        const dup = JSON.parse(JSON.stringify(this._appConfig)); // fast-json-patch explicitly mutates
+                        const dup = cloneJson(this._appConfig); // fast-json-patch explicitly mutates
                         jsonPatch.applyPatch(dup, msg.data);
                         this._logger.isDebugEnabled && this._logger.push({ oldConf: this._appConfig, newConf: dup }).debug(`Emitting new agent configuration [${VERB.PATCH}]`);
                         this.emit(EVENT.RECONFIGURE, dup);
@@ -255,9 +277,18 @@ class Client extends ws {
     }
 }
 
+const createConnectedControlAgentWs = async (conf, log) => {
+    return await Client.Create({
+        address: conf.control.mgmtAPIWsUrl,
+        port: conf.control.mgmtAPIWsPort,
+        appConfig: conf,
+        logger: log,
+    });
+};
 
 
 module.exports = {
+    createConnectedControlAgentWs,
     Client,
     build,
     MESSAGE,

package/modules/api-svc/src/OutboundServer/handlers.js

@@ -53,7 +53,7 @@ const { ReturnCodes } = Enum.Http;
  * Error handling logic shared by outbound API handlers
  */
 const handleError = (method, err, ctx, stateField) => {
-    ctx.state.logger.push({ err, stateField }).error(`Error handling ${method}`);
+    ctx.state.logger.push({ stateField }).error(`Error handling ${method}: `, err);
     ctx.response.status = err.httpStatusCode || ReturnCodes.INTERNALSERVERERRROR.CODE;
     ctx.response.body = {
         message: err.message || 'Unspecified error',

package/modules/api-svc/src/config.js

@@ -88,6 +88,7 @@ module.exports = {
         mgmtAPIWsUrl: env.get('MGMT_API_WS_URL').default('127.0.0.1').asString(),
         mgmtAPIWsPort: env.get('MGMT_API_WS_PORT').default('4005').asPortNumber(),
         mgmtAPILatencyAssumption: env.get('MGMT_API_LATENCY_ASSUMPTION').default('2000').asIntPositive(),
+        mgmtAPIPollIntervalMs: env.get('MANAGEMENT_API_POLL_INTERVAL_MS').asIntPositive(), // undefined if not set (feature disabled)
     },
     idGenerator: env.get('ID_GENERATOR').default('{"type":"ulid"}').asJsonObject(),
     logLevel: env.get('LOG_LEVEL').default('info').asEnum(LOG_LEVELS),