CDR SDK

This repo was forked from the published code on Github here.git pull

Using the CDR SDK

This SDK is intended for developers implementing CDR-compliant APIs in NodeJS/ExpressJS applications. It reduces the complexity and repetition involved in coding compliant APIs by providing ready-to-use middleware that handles common requirements such as error checking, header validation, and endpoint verification.

This code is offered as an npm package available in the NPM registry. You can easily install this package in your project using npm. For more information, refer to the Quick Start section below.

Explore the key middleware functions provided by the JS Holder SDK in the Middleware Functions section below.

Quick Start

To integrate the SDK into your NodeJS/ExpressJS application, ensure npm is installed on your system and run the following command:

npm install @xpsolutions/cdr-sdk

Import the necessary middleware functions and configure them as needed:

import { cdrHeaderValidator, cdrResourceValidator, cdrScopeValidator, cdrEndpointValidator } from '@xpsolutions/cdr-sdk';

// Example configuration
const dsbOptions = {
    // configuration details here
};

app.use(cdrHeaderValidator(dsbOptions));

The middleware functions cdrEndpointValidator, cdrHeaderValidator, cdrTokenValidator, and cdrJwtScopes can optionally accept a configuration object (CdrConfig) that specifies each endpoint the application implements, defined by the request type (GET/POST/DELETE) and path as outlined in the CDS. If the config parameter is not provided, the middleware defaults to using predefined endpoints (DefaultEnergyEndpoints, DefaultBankingEndpoints, and DefaultCommonEndpoints) specified in this repository.

const implementedEndpoints = [
    {
        "requestType":
        "GET",
        "requestPath": "/banking/payments/scheduled",
        "minSupportedVersion": 1,
        "maxSupportedVersion": 1
    },
    {
        "requestType": "GET",
        "requestPath": "/banking/accounts/{accountId}/balance",
        "minSupportedVersion": 1,
        "maxSupportedVersion": 1
    }
]

const config: CdrConfig = {
    endpoints: implementedEndpoints
}

app.use(cdrHeaderValidator(config))

The middleware functions cdrResourceValidator and cdrScopeValidator mandate an implementation of IUserInterface as a parameter, requiring access to scopes from the access token generated by the Identity and Access Management System (IdAM), which requires passing an implementation of IUserService by the consumer application.

Middleware Functions

Below is a detailed overview of the key middleware functions provided by the JS Holder SDK:

cdrHeaderValidator

Validates request headers and constructs CDR-compliant error responses as necessary.

| Scenario | Description | | --- | --- | | No x-v header is provided in the request | - Http status code 400- An ErrorList is returned with Header/Missing. | | Invalid x-v header is provided with the request, eg alpha character | - Http status code 400- An ErrorList is returned with Header/Invalid. | | Invalid x-min-v header is provided with the request | Http status code 400- An ErrorList is returned with Header/Invalid. | | A requested version is not supported | - Http status code 406- An ErrorList is returned with Header/UnsupportedVersion. | | No x-fapi-interaction-id in the request | An x-fapi-interaction-id header is set in the response header | | Request has x-fapi-interaction-id header | The x-fapi-interaction-id from the request is returned with the response header | | Invalid x-fapi-interaction-id header is provided with the request | - Http status code 400- An ErrorList is returned with Header/Invalid. |

cdrEndpointValidator

Checks if the request URL corresponds to a CDR endpoint and constructs CDR-compliant error responses as necessary.

| Scenario | Description | | --- | --- | | Endpoint not implemented | - Http status code 404- An ErrorList is returned with Resource/NotImplemented. | | Endpoint not is not a CDR endpoint | - Http status code 404- An ErrorList is returned with Resource/NotFound. |

cdrScopeValidator

Performs scope validation against the API endpoint requirements using the scopes available in the access token.

| Scenario | Description | | --- | --- | | Invalid scope in access token | - Http status code 403- An ErrorList is returned with Authorisation/InvalidScope |

Alternative Scope Validation: The combination of cdrJwtScopes and cdrTokenValidator functions can be used to validate scopes, and therefore performs a function similar to the cdrScopeValidator. It does however make assumptions on the Identity Provider implementation. Nevertheless, depending on the precise data holder implementation this may be more suitable than the IUsserInterface.

cdrResourceValidator

Ensures that the resource-specific identifiers like account IDs have proper consent for access within API calls.

| Scenario | Description | | --- | --- | | Access to the resource url has not been consented to | Http status code 404 |

cdrTokenValidator

Handles some basic authorisation checks and constructs CDR-compliant error responses as necessary.

Note that the functionality here requires access to the scopes contained from access token generated by the IdAM (Identity and Access Management System). For a common scenario where the access token is being issued as a JWT, the cdrJwtScopes middleware can be utilised to extend the Request object accordingly.

| Scenario | Description | | --- | --- | | No authorisation header present in Request | Http status code 401 | | Authorisation header is present, invalid scope in access token | - Http status code 403- An ErrorList is returned with Authorisation/InvalidScope |

cdrJwtScopes

Extends the Request object and make the scopes contained in the access token accessible from the Request object.

This can be used for any IdAM which returns the access token as an JWT and the scopes property is either an array of strings or a space separated string. The middleware will expect a configuration object.

| Scenario | Description | | --- | --- | | The access token from the IdAM is a JWT and scopes are an array of strings | The request object will be extended | | The access token from the IdAM is a JWT and scopes are a space separated string | The request object will be extended |

Utility Functions

buildErrorMessage

This function will return a ReponseErrorListV2. It will use the standard error codes as published by the Data Standards Body (eg urn:au-cds:error:cds-banking: Authorisation/InvalidBankingAccount) depending on the errorMessageId being passed in

| Parameter | Description | | --- | --- | | errorMessageId | an identifier as per DsbStandardError defintions | | errorDetail | which will be the details property on the returned error object | | errorList (optional) | an existing error list. The error object wil be appendd to that list | | metaData (optional) | options metadata object |

Example:

let msg = buildErrorMessage(DsbStandardError.INVALID_BANK_ACCOUNT, "123456");

// returns this as msg
    "errors": [
        {
            "code": "urn:au-cds:error:cds-banking:Authorisation/InvalidBankingAccount",
            "title": "Invalid Banking Account",
            "detail": "123456"
        }
    ]

getLinksPaginated

| Parameter | Description | | --- | --- | | req | The request object | | totalRecords | The total number of records in the dataset |

Example: if the req object has a url https://api.xpsol.com.au/cds-au/v1/energy/plans?category=ALL&page=4&page-size=2

getLinksPaginated(req, 1000)

will return

{
    self: "https://api.xpsol.com.au/cds-au/v1/energy/plans?category=ALL&page=4&page-size=2",
    next: "https://api.xpsol.com.au/cds-au/v1/energy/plans?category=ALL&page=5&page-size=2",
    prev: "https://api.xpsol.com.au/cds-au/v1/energy/plans?category=ALL&page=3&page-size=2",
    first: "https://api.xpsol.com.au/cds-au/v1/energy/plans?category=ALL&page=1&page-size=2",
    last: "https://api.xpsol.com.au/cds-au/v1/energy/plans?category=ALL&page=500&page-size=2"
}

getMetaPaginated

Will return a MetaPaginated object | Parameter | Description | | --- | --- | | totalRecords | The total number of records in the dataset | | query (optional) | The query property from the Request object |

Example:

getMetaPaginated(1000)

This use the default page-size=25 since no query parameters are passes in. Therefore, this will return

{
    totalRecords: 1000,
    totalPages: 40
}

paginateData

This will return a subset of data depending on the page-size and page properties from the Request query object

| Parameter | Description | | --- | --- | | data | an array of data objects. | | query | typycally this will be the query property from the Request object |

Example:

let data: any = [
            {
                "amount": "4439.65",
                "description": "payment transaction at Durgan and Sons using card ending with ***(...6407) for XAU 365.41 in account ***06028839",
            },
            {

                "accountId": "d339f6db-cd8d-413f-95e4-ec9e8e9d806f",
                "amount": "318.99",
                "description": "payment transaction at Gleason - Fadel using card ending with ***(...6904) for SYP 219.10 in 
            },
            {
                "extendedData": {
                    "service": "X2P1.01",
                    "payer": "Angelica Beatty"
                },
            },
            {
                "amount": "4013.89",
                "description": "payment transaction at Watson, Braun and Bartell using card ending with ***(...6802) for GEL 281.13 in account ***74872985",
                "isDetailAvailable": true,
            },
            {
                "executionDateTime": "2024-01-20T12:49:36.782Z",
                "apcaNumber": "572618"
            },
]

and a query object

let query: any = {
   "page-size": "2",
   "page" : "2"
}

then paginateData(data, query) returns

    [
            {
                "extendedData": {
                    "service": "X2P1.01",
                    "payer": "Angelica Beatty"
                },
            },
            {
                "amount": "4013.89",
                "description": "payment transaction at Watson, Braun and Bartell using card ending with ***(...6802) for GEL 281.13 in account ***74872985",
                "isDetailAvailable": true,
            }
    ]

.

Licensing Information

This repository contains code from a project originally created by Consumer Data Standards Australia, which is licensed under the MIT License. All code in this repository remains under its original license.