@letis009/node-red-contrib-tdn-hcp-api 2.5.0

Node-RED nodes to call HCP

npm install @letis009/node-red-contrib-tdn-hcp-api

node-red-contrib-tdn-hcp-api

Node-RED nodes for calling the HCP OpenAPI over its AK/SK signed-request gateway.

Signing, credential handling and response shaping are done for you, so a flow deals in people and fields rather than in HMAC strings.

Requirements

One runtime dependency, axios. No build step.

Install

From your Node-RED user directory, usually ~/.node-red:

npm install @letis009/node-red-contrib-tdn-hcp-api

Then restart Node-RED. The nodes appear in the palette under HCP.

Who configures what

These are backend nodes. They have no user-facing surface of their own.

• Technical staff install the package, set the credentials and wire the flow. Node configuration is reached only through the Node-RED editor, which should be behind authentication and not exposed to the site.
• End users never open a node. Everything they see and do belongs to the dashboard built on top of these flows.

Follow that split when you build on this. Do not surface a node's raw output on a dashboard without shaping it first, because a response carries internal hostnames and record detail that an end user has no reason to see.

Credentials

Credentials are read from Node-RED global context, set elsewhere in your flows. They are never stored in a node, so they cannot travel inside an exported flow file.

Set them once, keyed by site:

global.set('hcp', {
  site1: {
    ip: '192.168.1.10',
    port: 443,
    ak: process.env.HCP_SITE1_AK,
    sk: process.env.HCP_SITE1_SK,
    insecureTls: true
  },
  site2: {
    ip: '192.168.1.11',
    port: 443,
    ak: process.env.HCP_SITE2_AK,
    sk: process.env.HCP_SITE2_SK
  }
});

With a single server, a flat record works and no site name is needed anywhere:

global.set('hcp', {
  ip: '192.168.1.10',
  ak: process.env.HCP_AK,
  sk: process.env.HCP_SK
});

Read the values from environment variables, a secrets file or a credential store. Do not type them into a function node, because function node source is part of the flow and gets exported and shared with it.

Accepted aliases per record: ip / host / address, ak / appKey, sk / appSecret. Only ip, ak and sk are required. Port defaults to 443 and protocol to https.

Choosing a site

Each node resolves its site as msg.site, then the node's own Site field, then the config node's default. With exactly one site defined, leave the name blank everywhere and it resolves on its own. An unknown site name is an error that lists the sites that exist, rather than a silent fall back to another server.

The config node is optional

It exists to name a different global key or context store, and to hold fallback connection details for flows that have not been migrated yet. Each field resolves from global context first and from the config node second.

Nodes

Every node outputs the same envelope:

• msg.payload is the useful part of the response
• msg.hcp is { ok, code, msg, site, host, source }, where source records which credentials were used
• msg.statusCode is the HTTP status
• msg.request is the request that was sent, with the app key masked and the signature removed

By default a non-zero platform code raises a node error so a Catch node can handle it. Untick On error to let the message through instead. The generic call node has this off already, so existing flows behave as they did.

Custom fields by name

Reading a person adds two keys to the record, leaving the original customFieldList untouched:

person.customFields      // { scanRef: "REF001" }
person.customFieldsById  // { "1": { id: "1", name: "scanRef", value: "REF001", type: 0 } }

Writing takes names rather than the platform's numeric field IDs. The node reads the person first to map each name to its ID:

msg.personId = "960";
msg.customFields = { scanRef: "REF001" };

A name that does not exist on that person raises an error listing the names that do, rather than writing to the wrong field. A failed lookup stops the write instead of guessing. To skip the lookup, pass the list the platform expects directly as msg.payload.list.

The platform misspells the key as customFiledName in its own API. Reads accept either spelling. Writes send the misspelling, because that is the form the platform accepts.

Keeping credentials out of messages

The app key is masked and the signature removed before msg.request is attached, because messages reach debug nodes, catch handlers, logs and exported flows. Treat any captured payload as publishable and check it before pasting it into a ticket.

The optional Debug setting attaches the signed string to msg.stringToSign. It contains no secret in the default configuration, but it does include the app key if you enable the timestamp or nonce signing options. Leave it off outside of troubleshooting.

Self-signed certificates are handled per request. Earlier versions set NODE_TLS_REJECT_UNAUTHORIZED=0, which disabled certificate checking for the whole Node-RED process.

Example flows

Five ready-made flows ship with the package. In the Node-RED editor open the menu, choose Import, then Examples, then this package.

Import and deploy the credentials example first. The rest assume global.hcp is already populated, and will stop with a clear status if it is not. None of them contain a credential, and the setup flow reads every value from the environment rather than holding it.

Change the sample person ID and the field name to match your own data before running the person and custom field examples.

Tests

npm test

No network access and no dev dependencies. The suite covers the signature, credential resolution, custom field handling, credential redaction and each node's message shaping. One test reproduces the 1.0.x signing code and asserts the current output is byte-identical to it, because that is the form the deployed gateways are known to accept.

Licence

MIT