@mft/moneyhub-api-client 6.98.0 → 6.100.1

package/readme.md

@@ -26,6 +26,9 @@ This is an Node.JS client for the [Moneyhub API](https://docs.moneyhubenterprise
 - Get a tax return for a subset of transactions
 - Get the regular transactions on an account
 - Get beneficiaries
+- Create reseller check requests and get consent history
+- Standard financial statements
+- Legacy bank connections listing
 - CAAS (Categorisation as a Service) API for advanced transaction enrichment and categorisation
 
 Currently this library supports `client_secret_basic`, `client_secret_jwt` and `private_key_jwt` authentication.
@@ -64,7 +67,7 @@ const {Moneyhub} = require("@mft/moneyhub-api-client")
 
 ## Publishing (maintainers)
 
-Official releases are published to npm by **GitHub Actions** when a [GitHub Release](https://github.com/moneyhub/moneyhub-api-client/releases) is published (see `.github/workflows/publish.yml`). Do not rely on publishing from a developer machine.
+Official releases are published to npm by **GitHub Actions** when a [GitHub Release](https://github.com/moneyhub/moneyhub-api-client/releases) is published (see `.github/workflows/publish.yml`). The publish workflow runs lint and build on GitHub-hosted runners. Live integration tests are not part of publish; they run in the private synced repository (allowlisted IPs / secrets). Do not rely on publishing from a developer machine.
 
 The `prepublishOnly` lifecycle script runs **`scripts/assert-github-actions-publish.js`** before the build. It exits with an error unless `GITHUB_ACTIONS` is set (as it is in GitHub Actions), so a normal local `npm publish` is blocked. That reduces accidental publishes; it is **not** a security boundary on its own—npm access control and trusted publishing still matter.
 
@@ -74,9 +77,10 @@ To bypass the check in a **documented emergency** only, you can run `npm publish
 
 To use this API client you will need:
 
+- Node.js >= 18.0.0
 - A `client_id`, `client_secret` and `redirect_uri` of a registered API client
 - The url of the Moneyhub identity service for the environment you are connecting to (https://identity.moneyhub.co.uk)
-- The url for the API gateway for the environment that you are connecting to (https://api.moneyhub.co.uk/v2.0)
+- The url for the API gateway for the environment that you are connecting to (https://api.moneyhub.co.uk/v3)
 
 ## To install
 
@@ -257,6 +261,8 @@ The `expirationDateTime` and `transactionFromDateTime` options can be set accord
 
 Set `enableAsync` to true if you wish to make an AIS connection that won't wait for accounts and transactions to be fetched.
 
+Set `accVerification` to true to add the `mh:account_verification` claim. This is independent of `enableAsync`.
+
 **Note:** all methods generate an authorise URL using the Pushed Authorisation Request (PAR) method, see [here](https://docs.moneyhubenterprise.com/docs/pushed-authorisation-requests-par) for more details.
 
 #### `getAuthorizeUrl`
@@ -280,6 +286,7 @@ const url = await moneyhub.getAuthorizeUrl({
   expirationDateTime: "2022-09-01T00:00:00.000Z", // optional
   transactionFromDateTime: "2020-09-01T00:00:00.000Z", // optional,
   enableAsync: false, // optional
+  accVerification: false, // optional - adds mh:account_verification independently of enableAsync
 });
 
 // Default claims if none are provided
@@ -399,24 +406,6 @@ const defaultClaims = {
 
 #### `getRefreshAuthorizeUrlForCreatedUser`
 
-#### `getAuthorizeUrlLegacy`
-
-This method returns an authorize url for your API client using the legacy method (where a request object is generated and passed in as the `request` query parameter). You can redirect a user to this url, after which they will be redirected back to your `redirect_uri`. It has the same method signature as `getAuthorizeUrl`
-
-```javascript
-const url = await moneyhub.getAuthorizeUrlLegacy({
-  scope: "openid bank-id-scope other-data-scopes",
-  state: " your state value", // optional
-  nonce: "your nonce value", //optional
-  claims: claimsObject, // optional
-  permissions: ["ReadBeneficiariesDetail"], // optional - set of extra permissions to set for auth URL
-  permissionsAction: "replace" // optional - replace default consent permissions. Defaults to "add"
-  expirationDateTime: "2022-09-01T00:00:00.000Z", // optional
-  transactionFromDateTime: "2020-09-01T00:00:00.000Z", // optional,
-  enableAsync: false, // optional
-});
-```
-
 This is a helper function that returns an authorize url for a specific user to refresh an existing connection. This function uses the scope `openid refresh`. (Only relevant for legacy connections)
 
 ```javascript
@@ -444,6 +433,24 @@ const defaultClaims = {
 };
 ```
 
+#### `getAuthorizeUrlLegacy`
+
+This method returns an authorize url for your API client using the legacy method (where a request object is generated and passed in as the `request` query parameter). You can redirect a user to this url, after which they will be redirected back to your `redirect_uri`. It has the same method signature as `getAuthorizeUrl`
+
+```javascript
+const url = await moneyhub.getAuthorizeUrlLegacy({
+  scope: "openid bank-id-scope other-data-scopes",
+  state: " your state value", // optional
+  nonce: "your nonce value", //optional
+  claims: claimsObject, // optional
+  permissions: ["ReadBeneficiariesDetail"], // optional - set of extra permissions to set for auth URL
+  permissionsAction: "replace" // optional - replace default consent permissions. Defaults to "add"
+  expirationDateTime: "2022-09-01T00:00:00.000Z", // optional
+  transactionFromDateTime: "2020-09-01T00:00:00.000Z", // optional,
+  enableAsync: false, // optional
+});
+```
+
 #### `exchangeCodeForTokensLegacy`
 
 This is a legacy method to get tokens for a user.
@@ -850,7 +857,7 @@ Similar to getAccounts method, however this method does not return `transactionD
 
 ```javascript
 const queryParams = { limit: 10, offset: 5 , showTransacionData: false, showPerformanceScore: true};
-const accounts = await moneyhub.getAccounts({
+const accounts = await moneyhub.getAccountsList({
   userId: "userId",
   params: queryParams,
 }, options);
@@ -862,7 +869,7 @@ Similar to getAccountsWithDetails method, however this method does not return `t
 
 ```javascript
 const queryParams = { limit: 10, offset: 5 };
-const accounts = await moneyhub.getAccountsWithDetails({
+const accounts = await moneyhub.getAccountsListWithDetails({
   userId: "userId",
   params: queryParams,
 }, options);
@@ -1004,6 +1011,28 @@ const statements = await moneyhub.getAccountStatementsWithDetail({
 }, options);
 ```
 
+#### `getStandardFinancialStatements`
+
+List standard financial statement reports for a user (Money Advice Service schema metadata). Uses the scope `standard_financial_statement:read`.
+
+```javascript
+const statements = await moneyhub.getStandardFinancialStatements({
+  userId: "userId",
+  params: {limit: 10, offset: 0},
+}, options);
+```
+
+#### `getStandardFinancialStatement`
+
+Get a single standard financial statement report by id. Uses the scope `standard_financial_statement:read`.
+
+```javascript
+const statement = await moneyhub.getStandardFinancialStatement({
+  userId: "userId",
+  reportId: "reportId",
+}, options);
+```
+
 #### `createAccount`
 
 Create a manual account for a user. This function uses the scopes `accounts:read accounts:write:all`
@@ -1353,11 +1382,9 @@ const accounts = await moneyhub.getOsipAccounts({
 Get an account for a user. This function uses the scope `osip:read`.
 
 ```javascript
-const queryParams = { limit: 10, offset: 5 };
-const accounts = await moneyhub.getOsipAccounts({
+const account = await moneyhub.getOsipAccount({
   userId: "userId",
   accountId: "accountId",
-  params: queryParams,
 });
 ```
 
@@ -1367,7 +1394,7 @@ Get account holdings for an account. This function uses the scope `osip:read`.
 
 ```javascript
 const queryParams = { limit: 10, offset: 5 };
-const accounts = await moneyhub.getOsipAccounts({
+const holdings = await moneyhub.getOsipAccountHoldings({
   userId: "userId",
   accountId: "accountId",
   params: queryParams,
@@ -1380,7 +1407,7 @@ Get account transactions. This function uses the scope `osip:read`.
 
 ```javascript
 const queryParams = { limit: 10, offset: 5 };
-const accounts = await moneyhub.getOsipAccounts({
+const transactions = await moneyhub.getOsipAccountTransactions({
   userId: "userId",
   accountId: "accountId",
   params: queryParams,
@@ -1728,6 +1755,18 @@ const payees = await moneyhub.getPayees({
 });
 ```
 
+#### `getPayee`
+
+Get a single registered payee by id. This function uses the scope `payee:read`.
+
+```javascript
+const payee = await moneyhub.getPayee({
+  id: "payee-id",
+});
+```
+
+Example script: `node examples/payments/get-payee.js -i payee-id`.
+
 #### `getPayments`
 
 This method returns a list of initiated payments. This function uses the scope `payment:read`
@@ -1995,7 +2034,7 @@ const recurringPayment = await moneyhub.getRecurringPayment({
 This method creates a payment using the recurring payment consent. This function uses the scope `recurring_payment:create`
 
 ```javascript
-const recurringPayments = await moneyhub.getRecurringPayments({
+const recurringPayment = await moneyhub.makeRecurringPayment({
   recurringPaymentId: "Id of the recurring payment consent",
   payment: {
     payeeId: "payee-id", // optional
@@ -2016,6 +2055,22 @@ const revokedRecurringPayment = await moneyhub.revokeRecurringPayment({
 });
 ```
 
+#### `confirmFundsForRecurringPayment`
+
+Confirm that funds are available for a payment under an existing recurring payment consent. This function uses the scope `recurring_payment:funds_confirmation`.
+
+```javascript
+const fundsConfirmation = await moneyhub.confirmFundsForRecurringPayment({
+  recurringPaymentId: "Id of the recurring payment consent",
+  fundsConfirmation: {
+    amount: "10.00",
+    currency: "GBP",
+  },
+});
+```
+
+Example script: `node examples/recurring-payments/confirm-funds.js -i recurring-payment-id -a 10.00`.
+
 #### `getRegularTransactions`
 
 Get all the regular transactions for a user, there is an option to pass an account ID as a parameter as a filter. This function uses the scope `accounts:read`, `transactions:read:all` and `regular_transactions:read`
@@ -2221,6 +2276,20 @@ const resellerCheck = await moneyhub.createResellerCheckRequest({
 }, options);
 ```
 
+#### `getConsentHistory`
+
+Get consent history for the API client, optionally filtered by user. This function uses the scope `consent_history:read`.
+
+```javascript
+const consentHistory = await moneyhub.getConsentHistory({
+  limit: 10, // optional
+  offset: 0, // optional
+  userId: "user-id", // optional
+});
+```
+
+Example script: `node examples/consent-history/get-history.js -u user-id`.
+
 ### CAAS API
 
 The CAAS (Categorisation as a Service) API provides advanced transaction enrichment, categorisation, and management capabilities. All CAAS endpoints use dedicated scopes prefixed with `caas:`.
@@ -2252,9 +2321,11 @@ const result = await moneyhub.caasEnrichTransactions({
 }, options);
 ```
 
+Example script: `node examples/caas/transactions/enrich-transactions.js` (uses a built-in example transaction).
+
 #### `caasGetTransactions`
 
-Get transactions from the CAAS API with optional filtering by user and limit. This function uses the scope `caas:transactions:read`.
+Get transactions from the CAAS API with optional filtering by user and limit. This function uses the scopes `caas:transactions:read caas:transaction_splits:read`. The `splits` array is included for any split transaction when the client is registered for the `caas:transaction_splits:read` scope.
 
 ```javascript
 const result = await moneyhub.caasGetTransactions({
@@ -2264,6 +2335,8 @@ const result = await moneyhub.caasGetTransactions({
 }, options);
 ```
 
+Example script: `node examples/caas/transactions/get-transactions.js -a accountId -u userId -l 50`.
+
 #### `caasGetEnhancedTransaction`
 
 Retrieves Google Places–backed enhanced location and merchant data for a single CAAS transaction. Uses scope `caas:enhanced_transactions:read`. This is a premium endpoint and incurs a cost per request. Responses must not be cached or persisted when the data is sourced from Google (see API documentation).
@@ -2280,18 +2353,23 @@ const result = await moneyhub.caasGetEnhancedTransaction({
 
 The response follows the usual API envelope: the enhanced transaction is `result.data` (optional `links` / `meta` may also be present).
 
+Example script: `node examples/caas/transactions/get-enhanced-transaction.js -a accountId -t transactionId -i search_pro`.
+
 #### `caasPatchTransaction`
 
-Update a transaction category via the CAAS endpoint. This function uses the scope `caas:transactions:write` and returns the updated transaction data under `data`.
+Update a transaction's user-defined category via the CAAS endpoint. This function uses the scope `caas:transactions:write` and returns the updated transaction data under `data`. The optional `recategorisationType` query parameter (`single` or `future`, defaulting to `single`) controls whether the change applies to this transaction only or to all future matching transactions.
 
 ```javascript
 const result = await moneyhub.caasPatchTransaction({
   accountId: "accountId",
   transactionId: "transactionId",
-  l2CategoryId: "21",
+  userCategoryId: "21",
+  recategorisationType: "single",
 }, options);
 ```
 
+Example script: `node examples/caas/transactions/patch-transaction.js -a accountId -t transactionId -c 21 -r single`.
+
 #### `caasDeleteTransaction`
 
 Delete a transaction via the CAAS endpoint. This function uses the scope `caas:transactions:delete`.
@@ -2303,6 +2381,8 @@ await moneyhub.caasDeleteTransaction({
 }, options);
 ```
 
+Example script: `node examples/caas/transactions/delete-transaction.js -a accountId -t transactionId`.
+
 #### `caasPutTransactionSplits`
 
 Create or replace all splits for a transaction. Requires between 2 and 10 splits; split amounts must sum to the parent transaction `amount`. Uses scope `caas:transaction_splits:write`. Returns the upserted splits under `data`.
@@ -2318,7 +2398,7 @@ const result = await moneyhub.caasPutTransactionSplits({
 }, options);
 ```
 
-Example script: `npm run ts-node -- examples/caas/put-transaction-splits.js -a accTestQA123 -t testQA123 -d '[{"amount":4,"userCategoryId":"2d6078a1-06db-4c9c-b559-f36cec9e4fc1","description":"Food"},{"amount":6,"userCategoryId":"22","description":"Gift"}]'` (split amounts must sum to the parent transaction amount).
+Example script: `npm run ts-node -- examples/caas/transactions/put-transaction-splits.js -a accTestQA123 -t testQA123 -d '[{"amount":4,"userCategoryId":"2d6078a1-06db-4c9c-b559-f36cec9e4fc1","description":"Food"},{"amount":6,"userCategoryId":"22","description":"Gift"}]'` (split amounts must sum to the parent transaction amount).
 
 #### `caasDeleteTransactionSplits`
 
@@ -2331,7 +2411,7 @@ const status = await moneyhub.caasDeleteTransactionSplits({
 }, options);
 ```
 
-Example script: `node examples/caas/delete-transaction-splits.js -a accountId -t transactionId`.
+Example script: `node examples/caas/transactions/delete-transaction-splits.js -a accountId -t transactionId`.
 
 #### `caasGetCategories`
 
@@ -2341,6 +2421,8 @@ Get all available CAAS categories. This function uses the scope `caas:categories
 const result = await moneyhub.caasGetCategories(options);
 ```
 
+Example script: `node examples/caas/categories/get-categories.js`.
+
 #### `caasGetCategoryGroups`
 
 Get all available CAAS category groups. This function uses the scope `caas:categories:read`.
@@ -2349,6 +2431,46 @@ Get all available CAAS category groups. This function uses the scope `caas:categ
 const result = await moneyhub.caasGetCategoryGroups(options);
 ```
 
+Example script: `node examples/caas/categories/get-category-groups.js`.
+
+#### `caasGetCustomCategories`
+
+Get all custom categories created by a user. This function uses the scope `caas:categories:read` and returns the custom categories under `data`.
+
+```javascript
+const result = await moneyhub.caasGetCustomCategories({
+  userId: "userId",
+}, options);
+```
+
+Example script: `node examples/caas/custom-categories/get-custom-categories.js -u userId`.
+
+#### `caasCreateCustomCategory`
+
+Create a custom category for a user. This function uses the scope `caas:categories:write` and returns the created custom category under `data`. The returned `customCategoryId` can be used as the `userCategoryId` when updating a transaction via `caasPatchTransaction`. Returns a 409 if a custom category with the same name already exists for the user.
+
+```javascript
+const result = await moneyhub.caasCreateCustomCategory({
+  userId: "userId",
+  customCategoryName: "Coffee",
+}, options);
+```
+
+Example script: `node examples/caas/custom-categories/create-custom-category.js -u userId -n "Coffee"`.
+
+#### `caasDeleteCustomCategory`
+
+Delete a custom category for a user. This function uses the scope `caas:categories:delete`. `categoryId` must be a valid UUID. Resolves with the HTTP status code (`204` on success).
+
+```javascript
+await moneyhub.caasDeleteCustomCategory({
+  userId: "userId",
+  categoryId: "categoryId",
+}, options);
+```
+
+Example script: `node examples/caas/custom-categories/delete-custom-category.js -u userId -c categoryId`.
+
 #### `caasGetCounterparties`
 
 Get counterparties with optional pagination. This function uses the scope `caas:transactions:read`.
@@ -2360,6 +2482,8 @@ const result = await moneyhub.caasGetCounterparties({
 }, options);
 ```
 
+Example script: `node examples/caas/counterparties/get-counterparties.js -l 50 -o 0`.
+
 #### `caasGetGeotags`
 
 Get geotag information for specific geotag IDs. This function uses the scope `caas:transactions:read`.
@@ -2370,6 +2494,8 @@ const result = await moneyhub.caasGetGeotags({
 }, options);
 ```
 
+Example script: `node examples/caas/geotags/get-geotags.js -g geotag-id-1 -g geotag-id-2`.
+
 #### `caasGetRegularTransactions`
 
 Get regular transaction series for an account from the CaaS API. This function uses the scope `caas:regular_transactions:read`.
@@ -2380,6 +2506,8 @@ const result = await moneyhub.caasGetRegularTransactions({
 }, options);
 ```
 
+Example script: `node examples/caas/transactions/get-regular-transactions.js -a accountId`.
+
 #### `caasDeleteAccount`
 
 Delete an account via the CAAS endpoint. This function uses the scope `caas:users:delete`.
@@ -2390,6 +2518,8 @@ await moneyhub.caasDeleteAccount({
 }, options);
 ```
 
+Example script: `node examples/caas/accounts/delete-account.js -a accountId`.
+
 #### `caasDeleteUser`
 
 Delete a user via the CAAS endpoint. This function uses the scope `caas:users:delete`.
@@ -2400,6 +2530,8 @@ await moneyhub.caasDeleteUser({
 }, options);
 ```
 
+Example script: `node examples/caas/users/delete-user.js -u userId`.
+
 ### Financial Connections
 
 #### `listConnections`
@@ -2418,6 +2550,14 @@ This method will resolve with a list of all the API connections that a user can
 const availableConnections = await moneyhub.listAPIConnections();
 ```
 
+#### `listLegacyConnections`
+
+This method will resolve with a list of legacy connections from Identity (`.well-known/legacy-connections`).
+
+```javascript
+const availableConnections = await moneyhub.listLegacyConnections();
+```
+
 #### `listTestConnections`
 
 This method will resolve with a list of all the Test connections that a user can connect to.

package/scripts/assert-github-actions-publish.js

@@ -1,10 +1,20 @@
 #!/usr/bin/env node
 // prepublishOnly guard; emergency bypass: npm publish --ignore-scripts
+const allowedRepo = "moneyhub/moneyhub-api-client";
+
 if (process.env.GITHUB_ACTIONS !== "true") {
   console.error(
     "Publishing this package is restricted to GitHub Actions. " +
-      "Create a GitHub Release to trigger the publish workflow. " +
+      "Create a GitHub Release on moneyhub/moneyhub-api-client to trigger the publish workflow. " +
       "For a documented emergency bypass, use npm publish --ignore-scripts."
   );
   process.exit(1);
 }
+
+if (process.env.GITHUB_REPOSITORY !== allowedRepo) {
+  console.error(
+    `Publishing this package is restricted to ${allowedRepo}. ` +
+      `Current repository: ${process.env.GITHUB_REPOSITORY || "(unset)"}.`
+  );
+  process.exit(1);
+}

package/scripts/check-secrets.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+const {execFileSync} = require("child_process")
+
+const git = args => execFileSync("git", args, {encoding: "utf8"})
+
+const blockedPaths = [
+  "examples/config.js",
+]
+
+const secretPatterns = [
+  {
+    name: "PEM private key",
+    regex: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/,
+  },
+  {
+    name: "JWK private component (\"d\")",
+    regex: /"d"\s*:\s*"[A-Za-z0-9_-]{20,}"/,
+  },
+  {
+    name: "Real client_secret value",
+    regex: /client_secret"?\s*[:=]\s*"(?!your client secret")[^"]{8,}"/,
+  },
+]
+
+const getStagedFiles = () => {
+  const output = git(["diff", "--cached", "--name-only", "--diff-filter=ACM", "--no-renames"])
+  return output.split("\n").map(line => line.trim()).filter(Boolean)
+}
+
+const getStagedContent = file => git(["show", `:${file}`])
+
+const scanFile = file => {
+  const findings = []
+  if (blockedPaths.includes(file)) {
+    findings.push(`${file}: file is blocked from being committed (use examples/config.example.js as a template and keep secrets in the git-ignored examples/config.js)`)
+    return findings
+  }
+  let content
+  try {
+    content = getStagedContent(file)
+  } catch (err) {
+    findings.push(`${file}: unable to read staged content, cannot verify it is secret-free (${err.message})`)
+    return findings
+  }
+  secretPatterns.forEach(({name, regex}) => {
+    if (regex.test(content)) {
+      findings.push(`${file}: matched "${name}"`)
+    }
+  })
+  return findings
+}
+
+const main = () => {
+  const files = getStagedFiles()
+  const findings = files.flatMap(scanFile)
+  if (findings.length === 0) {
+    process.exit(0)
+  }
+  console.error("\nCommit blocked: potential secrets detected in staged changes\n")
+  findings.forEach(finding => console.error(`  - ${finding}`))
+  console.error("\nRemove the secrets, unstage the file, and commit again.")
+  console.error("If this is a false positive, review the staged content before bypassing.\n")
+  process.exit(1)
+}
+
+main()

package/.idea/codeStyles/Project.xml

@@ -1,21 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <code_scheme name="Project" version="173">
-    <JSCodeStyleSettings version="0">
-      <option name="USE_SEMICOLON_AFTER_STATEMENT" value="false" />
-      <option name="FORCE_SEMICOLON_STYLE" value="true" />
-      <option name="SPACE_BEFORE_FUNCTION_LEFT_PARENTH" value="false" />
-      <option name="FORCE_QUOTE_STYlE" value="true" />
-    </JSCodeStyleSettings>
-    <codeStyleSettings language="JavaScript">
-      <option name="BLOCK_COMMENT_ADD_SPACE" value="true" />
-      <option name="KEEP_BLANK_LINES_IN_CODE" value="3" />
-      <option name="INDENT_CASE_FROM_SWITCH" value="false" />
-      <option name="ALIGN_MULTILINE_PARAMETERS" value="false" />
-      <option name="ALIGN_MULTILINE_FOR" value="false" />
-      <indentOptions>
-        <option name="INDENT_SIZE" value="2" />
-        <option name="CONTINUATION_INDENT_SIZE" value="2" />
-      </indentOptions>
-    </codeStyleSettings>
-  </code_scheme>
-</component>

package/.idea/codeStyles/codeStyleConfig.xml

@@ -1,5 +0,0 @@
-<component name="ProjectCodeStyleConfiguration">
-  <state>
-    <option name="USE_PER_PROJECT_SETTINGS" value="true" />
-  </state>
-</component>