@mojaloop/central-ledger 19.14.0 → 20.1.0

package/src/settlement/api/handlers/settlements.js

@@ -0,0 +1,114 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2026 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+
+ * ModusBox
+ - Deon Botha <deon.botha@modusbox.com>
+ - Georgi Georgiev <georgi.georgiev@modusbox.com>
+ - Miguel de Barros <miguel.debarros@modusbox.com>
+ - Rajiv Mothilal <rajiv.mothilal@modusbox.com>
+ - Valentin Genev <valentin.genev@modusbox.com>
+ --------------
+ ******/
+'use strict'
+
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const Settlements = require('../../domain/settlement/index')
+const Utility = require('@mojaloop/central-services-shared').Util
+const Enum = require('@mojaloop/central-services-shared').Enum
+const EventSdk = require('@mojaloop/event-sdk')
+
+/**
+ * Operations on /settlements
+ */
+module.exports = {
+  /**
+     * summary: Returns Settlement(s) as per parameter(s).
+     * description:
+     * parameters: currency, participantId, settlementWindowId, accountId, state, fromDateTime, toDateTime
+     * produces: application/json
+     * responses: 200, 400, 401, 404, 415, default
+     */
+  get: async function getSettlementsByParams (context, request, h) {
+    try {
+      const { span, headers } = request
+      const spanTags = Utility.EventFramework.getSpanTags(
+        Enum.Events.Event.Type.SETTLEMENT,
+        Enum.Events.Event.Action.GET,
+        undefined,
+        headers[Enum.Http.Headers.FSPIOP.SOURCE],
+        headers[Enum.Http.Headers.FSPIOP.DESTINATION]
+      )
+      span.setTags(spanTags)
+      await span.audit({
+        headers: request.headers,
+        params: request.params
+      }, EventSdk.AuditEventAction.start)
+
+      const Enums = await request.server.methods.enums('settlementStates')
+      const settlementResult = await Settlements.getSettlementsByParams({ query: request.query }, Enums)
+      return h.response(settlementResult)
+    } catch (err) {
+      request.server.log('error', err)
+      return ErrorHandler.Factory.reformatFSPIOPError(err)
+    }
+  },
+  /**
+     * summary: Trigger the creation of a settlement event, that does the calculation of the net settlement position per participant and marks all transfers in the affected windows as Pending settlement. Returned dataset is the net settlement report for the settlement window
+     * description:
+     * parameters: settlementEventPayload
+     * produces: application/json
+     * responses: 200, 400, 401, 404, 415, default
+     */
+
+  post: async function createSettlementEvent (context, request, h) {
+    try {
+      const { span, payload, headers } = request
+      const spanTags = Utility.EventFramework.getSpanTags(
+        Enum.Events.Event.Type.SETTLEMENT,
+        Enum.Events.Event.Action.POST,
+        payload.settlementWindows.map(id => id.id).join(''),
+        headers[Enum.Http.Headers.FSPIOP.SOURCE],
+        headers[Enum.Http.Headers.FSPIOP.DESTINATION]
+      )
+      span.setTags(spanTags)
+      await span.audit(request.payload, EventSdk.AuditEventAction.start)
+
+      const Enums = {
+        ledgerEntryTypes: await request.server.methods.enums('ledgerEntryTypes'),
+        settlementDelay: await request.server.methods.enums('settlementDelay'),
+        settlementGranularity: await request.server.methods.enums('settlementGranularity'),
+        settlementInterchange: await request.server.methods.enums('settlementInterchange'),
+        settlementStates: await request.server.methods.enums('settlementStates'),
+        settlementWindowStates: await request.server.methods.enums('settlementWindowStates'),
+        transferParticipantRoleTypes: await request.server.methods.enums('transferParticipantRoleTypes'),
+        transferStates: await request.server.methods.enums('transferStates')
+      }
+      const settlementResult = await Settlements.settlementEventTrigger(request.payload, Enums)
+      return h.response(settlementResult)
+    } catch (err) {
+      request.server.log('error', err)
+      return ErrorHandler.Factory.reformatFSPIOPError(err)
+    }
+  }
+}

package/src/settlement/api/openapiRouting.js

@@ -0,0 +1,87 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2026 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+
+ * ModusBox
+ - Georgi Georgiev <georgi.georgiev@modusbox.com>
+ --------------
+ ******/
+'use strict'
+
+/**
+ * Routing helpers shared by the settlement API and the settlement handlers
+ * monitoring API, both of which are served by OpenapiBackend.
+ */
+
+/**
+ * Base path the API is served under. It mirrors the `servers` url of the
+ * OpenAPI document (formerly the Swagger 2.0 `basePath`).
+ *
+ * @param {object} api OpenAPIBackend instance
+ * @returns {string} base path, e.g. '/v2'
+ */
+const getBasePath = (api) => api.definition.servers[0].url.replace(/\/$/, '')
+
+/**
+ * Request handler. The base path is stripped from the request path, as the
+ * paths of the OpenAPI document are relative to its `servers` url.
+ *
+ * @param {object} api OpenAPIBackend instance
+ * @param {object} req Request
+ * @param {object} h   Response handle
+ */
+const handleRequest = (api, req, h) => api.handleRequest(
+  {
+    method: req.method,
+    path: req.path.slice(getBasePath(api).length),
+    body: req.payload,
+    query: req.query,
+    headers: req.headers
+  }, req, h)
+
+/**
+ * Fail fast when the API definition declares an operation with no handler.
+ *
+ * `OpenapiBackend.initialise` runs openapi-backend non-strict, so an operation it has no
+ * handler for is dispatched to `notFound`. An operationId added to the definition but never
+ * wired into the handlers map would therefore answer 404 at runtime rather than failing at
+ * startup - the filesystem-based routing this replaced could not drift that way.
+ *
+ * @param {object} api Initialised OpenAPIBackend instance
+ * @throws {Error} If the definition declares an operation with no registered handler
+ */
+const assertHandlersRegistered = (api) => {
+  const unhandled = api.getOperations()
+    .filter(({ operationId }) => typeof api.handlers[operationId] !== 'function')
+    .map(({ method, path, operationId }) => `${method.toUpperCase()} ${path} (operationId: ${operationId})`)
+
+  if (unhandled.length > 0) {
+    throw new Error(`OpenAPI definition declares operations with no registered handler: ${unhandled.join(', ')}`)
+  }
+}
+
+module.exports = {
+  getBasePath,
+  handleRequest,
+  assertHandlersRegistered
+}

package/src/settlement/api/routes.js

@@ -0,0 +1,176 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2026 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+
+ * ModusBox
+ - Georgi Georgiev <georgi.georgiev@modusbox.com>
+ --------------
+ ******/
+'use strict'
+
+const OpenapiBackend = require('@mojaloop/central-services-shared').Util.OpenapiBackend
+const Path = require('path')
+const Handlers = require('./handlers')
+const { getBasePath, handleRequest, assertHandlersRegistered } = require('./openapiRouting')
+
+/**
+ * Core API Routes
+ *
+ * @param {object} api OpenAPIBackend instance
+ */
+const APIRoutes = (api) => {
+  const basePath = getBasePath(api)
+  return [
+    {
+      method: 'GET',
+      path: `${basePath}/health`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'getHealth',
+        tags: ['api', 'getHealth'],
+        description: 'GET health'
+      }
+    },
+    {
+      method: 'GET',
+      path: `${basePath}/settlementWindows/{id}`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'getSettlementWindowById',
+        tags: ['api', 'getSettlementWindowById', 'sampled'],
+        description: 'GET settlement window by id'
+      }
+    },
+    {
+      method: 'POST',
+      path: `${basePath}/settlementWindows/{id}`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'closeSettlementWindow',
+        tags: ['api', 'closeSettlementWindow', 'sampled'],
+        description: 'POST close settlement window by id'
+      }
+    },
+    {
+      method: 'GET',
+      path: `${basePath}/settlementWindows`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'getSettlementWindowsByParams',
+        tags: ['api', 'getSettlementWindowsByParams', 'sampled'],
+        description: 'GET settlement windows by params'
+      }
+    },
+    {
+      method: 'GET',
+      path: `${basePath}/settlements`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'getSettlementsByParams',
+        tags: ['api', 'getSettlementsByParams', 'sampled'],
+        description: 'GET settlements by params'
+      }
+    },
+    {
+      method: 'POST',
+      path: `${basePath}/settlements`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'createSettlement',
+        tags: ['api', 'createSettlement', 'sampled'],
+        description: 'POST trigger settlement event'
+      }
+    },
+    {
+      method: 'GET',
+      path: `${basePath}/settlements/{id}`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'getSettlementById',
+        tags: ['api', 'getSettlementById', 'sampled'],
+        description: 'GET settlement by id'
+      }
+    },
+    {
+      method: 'PUT',
+      path: `${basePath}/settlements/{id}`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'updateSettlementById',
+        tags: ['api', 'updateSettlementById', 'sampled'],
+        description: 'PUT update settlement by id'
+      }
+    },
+    {
+      method: 'GET',
+      path: `${basePath}/settlements/{sid}/participants/{pid}`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'getSettlementBySettlementParticipant',
+        tags: ['api', 'getSettlementBySettlementParticipant', 'sampled'],
+        description: 'GET settlement by settlement and participant'
+      }
+    },
+    {
+      method: 'PUT',
+      path: `${basePath}/settlements/{sid}/participants/{pid}`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'updateSettlementBySettlementParticipant',
+        tags: ['api', 'updateSettlementBySettlementParticipant', 'sampled'],
+        description: 'PUT update settlement by settlement and participant'
+      }
+    },
+    {
+      method: 'GET',
+      path: `${basePath}/settlements/{sid}/participants/{pid}/accounts/{aid}`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'getSettlementBySettlementParticipantAccount',
+        tags: ['api', 'getSettlementBySettlementParticipantAccount', 'sampled'],
+        description: 'GET settlement by settlement, participant and account'
+      }
+    },
+    {
+      method: 'PUT',
+      path: `${basePath}/settlements/{sid}/participants/{pid}/accounts/{aid}`,
+      handler: (req, h) => handleRequest(api, req, h),
+      config: {
+        id: 'updateSettlementBySettlementParticipantAccount',
+        tags: ['api', 'updateSettlementBySettlementParticipantAccount', 'sampled'],
+        description: 'PUT update settlement by settlement, participant and account'
+      }
+    }
+  ]
+}
+
+module.exports = {
+  plugin: {
+    name: 'settlement api routes',
+    register: async function (server) {
+      const api = await OpenapiBackend.initialise(Path.resolve(process.cwd(), 'src/settlement/interface/swagger.json'), Handlers)
+      assertHandlersRegistered(api)
+      server.route(APIRoutes(api))
+    }
+  }
+}

package/src/settlement/domain/rules/index.js

@@ -0,0 +1,46 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ - Name Surname <name.surname@mojaloop.io>
+
+ * ModusBox
+ - Shashikant Hirugade <shashikant.hirugade@modusbox.com>
+ --------------
+ ******/
+
+const ErrorHandler = require('@mojaloop/central-services-error-handling')
+const TransferSettlementModel = require('../../models/transferSettlement')
+const { logger } = require('../../shared/logger')
+
+module.exports = {
+  insertLedgerEntries: async function insertLedgerEntries (ledgerEntries, transferEventId, trx) {
+    logger.debug(`rules::insertLedgerEntries - ledgerEntries=${JSON.stringify(ledgerEntries)}`)
+
+    try {
+      await TransferSettlementModel.insertLedgerEntries(ledgerEntries, transferEventId, trx)
+      return true
+    } catch (err) {
+      logger.error(err)
+      throw ErrorHandler.Factory.reformatFSPIOPError(err)
+    }
+  }
+}