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

package/modules/api-svc/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojaloop/sdk-scheme-adapter-api-svc",
-  "version": "21.0.0-snapshot.71",
+  "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",

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

@@ -147,11 +147,9 @@ 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 }) {
-        const wsUrl = `ws://${address}:${port}`;
-        super(wsUrl);
+        super(`ws://${address}:${port}`);
         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
@@ -214,7 +212,7 @@ 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}...`);
+        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 });
 

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/index.js

@@ -26,6 +26,7 @@
  ******/
 'use strict';
 
+const { hostname } = require('node:os');
 const EventEmitter = require('node:events');
 const http = require('http');
 const https = require('https');
@@ -250,7 +251,7 @@ class Server extends EventEmitter {
                 this.logger.warn('No config received from polling');
                 return;
             }
-            this.logger.info('polling config from Management API is done, restarting server...');
+            this.logger.info('polling config from mgmt-api is done, checking if SDK server restart needed...');
 
             const mergedConfig = _.merge({}, this.conf, newConfig);
             await this.restart(mergedConfig, { source: 'polling' });
@@ -326,7 +327,7 @@ class Server extends EventEmitter {
 
         // Race condition prevention
         if (this._configUpdateInProgress) {
-            this.logger.info('Restart already in progress, skipping', { source });
+            this.logger.info('restart already in progress, skipping', { source });
             return;
         }
 
@@ -592,7 +593,7 @@ async function start(config) {
         process.exit(1);
     });
 
-    logger.info('SDK server is started', { name, version });
+    logger.info('SDK server is started', { name, version, hostname: hostname() });
 }
 
 if (require.main === module) {

package/modules/api-svc/src/lib/logger.js

@@ -25,15 +25,14 @@
  --------------
  ******/
 
-const { hostname } = require('node:os');
 const { loggerFactory, LOG_LEVELS } = require('@mojaloop/sdk-standard-components').Logger;
 
 const createLogger = (conf = {}) => {
     const {
         context = {
+            context: 'SDK',
             // If we're running from a Mojaloop helm chart deployment, we'll have a SIM_NAME
             simulator: process.env['SIM_NAME'],
-            hostname: hostname(),
         },
         isJsonOutput = false,
     } = conf;

package/modules/outbound-command-event-handler/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojaloop/sdk-scheme-adapter-outbound-command-event-handler",
-  "version": "0.3.0-snapshot.66",
+  "version": "0.3.0-snapshot.67",
   "description": "Mojaloop sdk scheme adapter command event handler",
   "license": "Apache-2.0",
   "homepage": "https://github.com/mojaloop/sdk-scheme-adapter/",

package/modules/outbound-domain-event-handler/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mojaloop/sdk-scheme-adapter-outbound-domain-event-handler",
-    "version": "0.3.0-snapshot.66",
+    "version": "0.3.0-snapshot.67",
     "description": "mojaloop sdk scheme adapter outbound domain event handler",
     "license": "Apache-2.0",
     "homepage": "https://github.com/mojaloop/sdk-scheme-adapter/",

package/modules/private-shared-lib/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojaloop/sdk-scheme-adapter-private-shared-lib",
-  "version": "0.4.0-snapshot.66",
+  "version": "0.4.0-snapshot.67",
   "description": "SDK Scheme Adapter private shared library.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/mojaloop/accounts-and-balances-bc/tree/main/modules/private-types",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mojaloop/sdk-scheme-adapter",
-  "version": "24.14.0-snapshot.0",
+  "version": "24.14.0-snapshot.1",
   "description": "mojaloop sdk-scheme-adapter",
   "license": "Apache-2.0",
   "homepage": "https://github.com/mojaloop/sdk-scheme-adapter",

package/_cc/learn-project.md

@@ -1,74 +0,0 @@
-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

@@ -1,45 +0,0 @@
-
-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: