@mojaloop/sdk-scheme-adapter 24.12.0 → 24.14.0-snapshot.0

package/.yarnrc.yml

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

package/CHANGELOG.md

@@ -1,4 +1,16 @@
 # Changelog: [mojaloop/sdk-scheme-adapter](https://github.com/mojaloop/sdk-scheme-adapter)
+## [24.13.0](https://github.com/mojaloop/sdk-scheme-adapter/compare/v24.12.0...v24.13.0) (2025-10-06)
+
+
+### Features
+
+* **csi-1665:** improved logging ([#616](https://github.com/mojaloop/sdk-scheme-adapter/issues/616)) ([b8cae73](https://github.com/mojaloop/sdk-scheme-adapter/commit/b8cae734c71f5e94fef53cd0da1953042750bf54))
+
+
+### Chore
+
+* **sbom:** update sbom [skip ci] ([4cc79d0](https://github.com/mojaloop/sdk-scheme-adapter/commit/4cc79d0093732849ab25ba6d9357ce079347ab95))
+
 ## [24.12.0](https://github.com/mojaloop/sdk-scheme-adapter/compare/v24.11.0...v24.12.0) (2025-09-22)
 
 

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/_cc/learn-project.md

@@ -0,0 +1,74 @@
+You are a senior backend engineer mentoring interns/junior JS developers. Your task is to study this repository
+(it also cn be found by link: https://github.com/mojaloop/sdk-scheme-adapter)
+
+Target branch: `main`; if multiple active branches or major forks exist, compare and note differences)
+
+## Mission
+1) Understand and explain Business Logic and Architecture.
+2) Produce accurate, implementation-level notes (no hand-waving).
+3) Save all findings as Markdown files in `./_cc/docs` folder suitable for onboarding juniors.
+4) Prefer concise, example-driven explanations with TypeScript/JavaScript snippets and Mermaid diagrams.
+5) Link all new files in `CLAUDE.md` with really brief explanation what each file is about.
+
+## Critical Focus Areas (business logic, architecture, and main implementation details)
+- Inbound server (FSPIOP / ISO 20022 formats)
+- Outbound server (Mojaloop SDK Outbound Scheme Adapter API)
+- Request state management (Redis usage, keys, TTLs, state-machine/lifecycle)
+- ControlAgent (WebSocket agent) integration with PM4ML management API:
+  https://github.com/pm4ml/mojaloop-payment-manager-management-api
+- Mojaloop SDK Backend API (interactions with core connectors and DFSP backend systems)
+
+## Deliverables (Markdown in ./_cc/docs)
+Create separate files (add more if helpful):
+- High-level overview + quickstart. Who uses this service, how it fits Mojaloop hub DFSP workflows.
+- System context, containers/components, runtime topology, configs/env. Include:
+    - Sequence diagrams (PlantUML) for key flows (e.g., Payer DFSP -> Inbound -> Backend -> Outbound -> Switch -> callback).
+- Inbound Server: Purpose, routes, request/response schemas, auth/security, validation, error handling, retry/backoff, logging/tracing.
+- Outbound Server: Outbound API surface, happy-path + failure flows, idempotency, correlation IDs, callback handling.
+- Request State Management (using Redis):
+    - Keys, value shapes, expirations, pub/sub usage (if any), transactionality.
+    - State machine diagram (Mermaid) for request lifecycle (init → pending → fulfilled/errored/cancelled).
+    - Recovery logic on restarts, exactly-once/at-least-once semantics, race-condition mitigations.
+- ControlAgent design:
+    - WebSocket lifecycle, message formats, heartbeats, reconnection, auth.
+    - Interface with PM4ML management API (endpoints used, commands, examples) - https://github.com/pm4ml/mojaloop-payment-manager-management-api
+- Backend API: Mojaloop SDK Backend API spec relevant here:
+    - Endpoints, payload shapes, correlation rules, error codes.
+    - Mapping between inbound/outbound and backend calls (table).
+- Error handling patterns: Error taxonomy, standardized problem codes, logs, metrics, traces.
+- Glossary — Mojaloop terms, DFSP, transfer, quote, callback, ILP, FSPIOP, etc., with links to code.
+
+## Analysis Instructions
+- Read source code, package.json scripts, config files, OpenAPI/Swagger specs, and README(s).
+- Infer actual behavior from code over docs when they disagree; call out discrepancies.
+- Capture all external dependencies (libraries, services, ports).
+- Map end-to-end flows for: party lookup, quote, transfer, and callback handling.
+- Document correlation and idempotency strategies (HTTP headers, FSPIOP signatures/urls, state keys).
+- Note security: TLS, signing, auth between components, any PII handling, and compliance concerns.
+- For Redis, provide concrete key examples and short JS code snippets showing set/get patterns used here.
+- For each HTTP/WebSocket route: method, path, request schema, response schema, main side effects, and error paths.
+- Include small, runnable TS/JS examples that mimic real requests (curl + axios snippets).
+
+## Writing Style
+- Audience: junior JS devs. Prioritize clarity and accuracy; keep sections short with examples.
+- Use TypeScript types where feasible. Avoid framework-agnostic pseudocode when real code exists.
+- Provide “Why it’s designed this way” notes and trade-offs.
+- Link to source files by path (e.g., `src/handlers/inbound/…`).
+- Avoid speculation; if unknown, create a TODO in a “Gaps & Open Questions” section.
+
+## Output Rules
+- DO NOT execute the code; perform static analysis only.
+- Produce all files in `./_cc/docs`.
+- Use GitHub-flavored Markdown; keep line length reasonable.
+- Include a short “Onboarding in 30 minutes” section.
+- Update `CLAUDE.md` with links to new files.
+
+## Validation Checklist (include at end of each file)
+- [ ] Routes and payloads verified against code
+- [ ] Error paths documented
+- [ ] Examples compile in TS
+- [ ] Links/paths correct
+
+Begin now. If repo structure suggests different file splits, propose and proceed. 
+
+If you have any questions or hesitations, please ask immediately.

package/_cc/specs/story-CSI-1864.md

@@ -0,0 +1,45 @@
+
+1. Read `CLAUDE.md`
+2. Read additional _docs_ to get better context:
+   1. `[api-svc-01-overview.md](../docs/api-svc/api-svc-01-overview.md)`
+   2. `[api-svc-07-control-agent.md](../docs/api-svc/api-svc-07-control-agent.md)`
+3. Read Jira ticket CSI-1864: https://infitx-technologies.atlassian.net/jira/software/c/projects/CSI/boards/12/backlog?assignee=712020%3A5680aa00-ab49-4175-96be-384e78ebaa45&selectedIssue=CSI-1864
+   1. Analyze description, check Acceptance Criteria. If not able to access Jira, see the `Jira Details` section below
+   2. Understand the problem we want to solve in scope of the story, identify which components need to be added/modified.
+   3. Check in huge detail actual code implementation of involved components, understand how related logic works now.
+   4. Ask any clarification if needed!
+4. Create high-level implementation plan, split on tasks, suggest testing plan (with test cases for new logic)
+5. One of my junior colleague provided me detailed implementation plan for the story: `/home/eugen/projects/ML/sdk-scheme-adapter/_cc/specs/story-CSI-1864-plan.md`:
+   1. Analyze it, and give your feedback how to improve and/or optimize that plan
+   2. Compare your high-level plan with that one, come up with suggestion how to combine there two plans into one final plan
+   3. Suggestion from my side how to improve colleague's plan:
+      1. For polling, try to reuse `controlClient` which we already use for listening to `ControlAgent.EVENT.RECONFIGURE` event instead of creating new one
+      2. Pass this `controlClient` to `_startConfigPolling()` or access `this.controlClient` inside it
+   4. Suggest any changes you think needed, and ask my approval!
+   5. Store final plan in `/home/eugen/projects/ML/sdk-scheme-adapter/_cc/specs/story-CSI-1864-final-plan.md`
+6. Ask me to review your final plan, before any code changes!   
+7. Update `CLAUDE.md` and `api-svc-07-control-agent.md` with new changes details
+
+## Jira Details
+
+### Story description:
+```
+Implement Failsafe Mechanism in SDK to Poll Configuration Changes from Management API
+This problem results in transactions failing through that connection, which can be a DFSP connection, or a proxy connection to another scheme. I.e. if this occurs in a proxy, then in the current configuration all transaction will fail. There have been numerous attempts to fix the stale certificate sdk problem, yet the problem perisists. This story is about taking a new approach that will elimitate this problem.
+
+Currently, the SDK Scheme Adapter relies on notifications from the Management API to update its configuration — for example, when new participant certificates or JWS keys are updated.
+However, in some cases these notifications may not be delivered reliably (due to network issues, restarts, or transient errors), which can lead to JWS desynchronization between the SDK and the Management Service.
+
+To address this, introduce a failsafe polling mechanism within the SDK that periodically polls the Management API for configuration updates. This ensures that even if event-driven updates fail, the SDK eventually synchronizes its configuration.
+```
+
+## Acceptance Criteria:
+1. The SDK includes a background polling mechanism that periodically checks for configuration updates from the Management API.
+2. Polling frequency is configurable through an environment variable, e.g. MANAGEMENT_API_POLL_INTERVAL_MS.
+3. If no interval is configured, the failsafe polling feature is disabled (default behavior).
+4. When polling is enabled, the SDK should:
+   1. Fetch and compare the configuration with the current state.
+   2. Apply updates if changes are detected.
+   3. Log both successful updates and polling errors with clear messages.
+5. The implementation must not cause race conditions with live notifications — if both notification and polling update the config simultaneously, the state remains consistent.
+6. Unit tests added to validate:

package/docker-compose.yml

@@ -95,7 +95,7 @@ services:
   kafka:
     networks:
       - mojaloop-net
-    image: docker.io/bitnami/kafka:3.4.0
+    image: docker.io/bitnamilegacy/kafka:3.4.0
     container_name: kafka
     ports:
       - "9092:9092"
@@ -156,7 +156,7 @@ services:
   init-kafka:
     networks:
       - mojaloop-net
-    image: docker.io/bitnami/kafka:3.4.0
+    image: docker.io/bitnamilegacy/kafka:3.4.0
     depends_on:
       kafka:
         condition: service_healthy

package/modules/api-svc/.env.example

@@ -126,7 +126,7 @@ CHECK_ILP=true
 # set to true to enable test features such as request cacheing and retrieval endpoints
 ENABLE_TEST_FEATURES=false
 
-# set to true to mock WSO2 oauth2 token endpoint
+# set to true to mock OIDC oauth2 token endpoint
 ENABLE_OAUTH_TOKEN_ENDPOINT=false
 OAUTH_TOKEN_ENDPOINT_CLIENT_KEY=test-client-key
 OAUTH_TOKEN_ENDPOINT_CLIENT_SECRET=test-client-secret
@@ -135,7 +135,7 @@ OAUTH_TOKEN_ENDPOINT_LISTEN_PORT=6000
 # WSO2 Bearer Token specific to golden-fsp instance and environment
 WSO2_BEARER_TOKEN=7718fa9b-be13-3fe7-87f0-a12cf1628168
 
-# OAuth2 data used to obtain WSO2 bearer token
+# OAuth2 data used to obtain OIDC bearer token
 OAUTH_TOKEN_ENDPOINT=
 OAUTH_CLIENT_KEY=
 OAUTH_CLIENT_SECRET=

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.71",
   "description": "An adapter for connecting to Mojaloop API enabled switches.",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -64,21 +64,21 @@
   },
   "dependencies": {
     "@koa/cors": "5.0.0",
-    "@mojaloop/api-snippets": "18.1.1",
-    "@mojaloop/central-services-error-handling": "13.1.2",
+    "@mojaloop/api-snippets": "18.2.0",
+    "@mojaloop/central-services-error-handling": "13.1.3",
     "@mojaloop/central-services-logger": "11.10.1",
-    "@mojaloop/central-services-metrics": "12.7.1",
-    "@mojaloop/central-services-shared": "18.33.3",
-    "@mojaloop/event-sdk": "14.7.0",
+    "@mojaloop/central-services-metrics": "12.8.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",
     "@mojaloop/sdk-scheme-adapter-private-shared-lib": "workspace:^",
-    "@mojaloop/sdk-standard-components": "19.17.0",
+    "@mojaloop/sdk-standard-components": "19.18.0",
     "ajv": "8.17.1",
     "axios": "1.12.2",
     "body-parser": "2.2.0",
     "co-body": "6.2.0",
-    "dotenv": "17.2.2",
+    "dotenv": "17.2.3",
     "env-var": "7.5.0",
     "express": "4.21.2",
     "fast-json-patch": "3.1.1",
@@ -96,7 +96,7 @@
     "prom-client": "15.1.3",
     "promise-timeout": "1.3.0",
     "random-word-slugs": "0.1.7",
-    "redis": "5.8.2",
+    "redis": "5.8.3",
     "retry": "^0.13.1",
     "uuidv4": "6.2.13",
     "ws": "8.18.3"
@@ -108,7 +108,7 @@
     "@types/jest": "30.0.0",
     "@types/retry": "^0",
     "axios-mock-adapter": "2.1.0",
-    "babel-jest": "30.1.2",
+    "babel-jest": "30.2.0",
     "eslint": "9.15.0",
     "eslint-config-airbnb-base": "15.0.0",
     "eslint-plugin-import": "2.32.0",

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) => {
@@ -144,9 +147,11 @@ class Client extends ws {
      * `Client` instances outside of this class should be created via the `Create(...args)` static method.
      */
     constructor({ address = 'localhost', port, logger, appConfig }) {
-        super(`ws://${address}:${port}`);
-        this._logger = logger.push({ component: 'ControlClient' });
+        const wsUrl = `ws://${address}:${port}`;
+        super(wsUrl);
+        this._logger = logger.push({ component: 'ControlClientWs' });
         this._appConfig = appConfig;
+        this._wsUrl = wsUrl;
     }
 
     // Really only exposed so that a user can import only the client for convenience
@@ -173,28 +178,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 +210,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._wsUrl}...`);
+        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 +235,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 +243,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 +279,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/FSPIOPEventHandler/handlers/bulk-quotes-requested.js

@@ -43,7 +43,7 @@ module.exports.handleBulkQuotesRequestedDmEvt = async (
             ...options.config,
             cache: options.cache,
             logger: logger,
-            wso2: options.wso2,
+            oidc: options.oidc,
         });
 
         await model.initialize(event.request);

package/modules/api-svc/src/FSPIOPEventHandler/handlers/bulk-transfers-requested.js

@@ -43,7 +43,7 @@ module.exports.handleBulkTransfersRequestedDmEvt = async (
             ...options.config,
             cache: options.cache,
             logger: logger,
-            wso2: options.wso2,
+            oidc: options.oidc,
         });
 
         await model.initialize(event.request);

package/modules/api-svc/src/FSPIOPEventHandler/handlers/party-info-requested.js

@@ -46,7 +46,7 @@ module.exports.handlePartyInfoRequestedDmEvt = async (
             ...options.config,
             cache: options.cache,
             logger: logger,
-            wso2: options.wso2,
+            oidc: options.oidc,
         };
 
         const cacheKey = PartiesModel.generateKey(args);

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

@@ -44,11 +44,11 @@ const {
 } = require('./handlers');
 
 class FSPIOPEventHandler {
-    constructor({ config, logger, cache, wso2 }) {
+    constructor({ config, logger, cache, oidc }) {
         this._conf = config;
         this._logger = logger.push({ component: this.constructor.name });
         this._cache = cache;
-        this._wso2 = wso2;
+        this._oidc = oidc;
 
         this._loggerFromLoggingBC = new DefaultLogger(BC_CONFIG.bcName, 'fspiop-event-handler', '0.0.1', config.logLevel);
 
@@ -70,7 +70,7 @@ class FSPIOPEventHandler {
             producer: this._producer,
             consumer: this._consumer,
             cache: this._cache,
-            wso2: this._wso2,
+            oidc: this._oidc,
             config: this._conf,
         };
 

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

@@ -74,7 +74,7 @@ const createInboundTransfersModel = (ctx) => new InboundTransfersModel({
     },
     cache: ctx.state.cache,
     logger: ctx.state.logger,
-    wso2: ctx.state.wso2,
+    oidc: ctx.state.oidc,
     resourceVersions: ctx.resourceVersions,
     backendSharedAgents: ctx.state.backendSharedAgents,
     mojaloopSharedAgents: ctx.state.mojaloopSharedAgents,
@@ -1133,14 +1133,14 @@ const createPutFxTransfersHandler = (success) => async (ctx) => {
 };
 
 const handlePostPing = (ctx) => {
-    const { jwsPingValidationResult, conf, logger, wso2 } = ctx.state;
+    const { jwsPingValidationResult, conf, logger, oidc } = ctx.state;
     const { sourceFspId, body, headers } = extractBodyHeadersSourceFspId(ctx);
 
     const model = new InboundPingModel({
         ...conf,
         resourceVersions: ctx.resourceVersions,
         logger,
-        wso2,
+        oidc,
     });
     model.postPing({ jwsPingValidationResult, sourceFspId, body, headers })
         .catch(err => logger.error('error in handlePostPing:', err));