node-red-contrib-ipgeolocation 1.0.0

package/nodes/lib/node-helpers.js

@@ -0,0 +1,214 @@
+/**
+ * lib/node-helpers.js
+ *
+ * Utility functions shared across all IPGeolocation.io nodes.
+ *
+ * Contents
+ * ─────────
+ *  • setStatus / clearStatus  — node status shorthands
+ *  • resolveValue             — reads msg / flow / global / str values
+ *  • setOutputProperty        — writes to any msg / flow / global path
+ *  • handleNodeError          — standard error handler (status + done)
+ *  • buildCommonParams        — assembles shared query params (apiKey, lang, output, fields, excludes)
+ */
+
+'use strict';
+
+// ─── Status Helpers ──────────────────────────────────────────────────────────
+
+const STATUS = {
+  IDLE:     { fill: 'grey',   shape: 'ring',  text: '' },
+  WORKING:  { fill: 'blue',   shape: 'dot',   text: 'requesting…' },
+  OK:       { fill: 'green',  shape: 'dot',   text: 'ok' },
+  ERROR:    { fill: 'red',    shape: 'ring',  text: 'error' },
+  NO_KEY:   { fill: 'red',    shape: 'ring',  text: 'no API key' },
+  RATE_LIM: { fill: 'yellow', shape: 'ring',  text: 'rate limited' },
+};
+
+/**
+ * Set a node status using a named key from STATUS, or a raw status object.
+ * @param {object} node
+ * @param {string|object} state  Key from STATUS or raw { fill, shape, text }
+ * @param {string} [suffix]      Optional text appended to STATUS[state].text
+ */
+function setStatus(node, state, suffix) {
+  if (typeof state === 'string' && STATUS[state]) {
+    const s = { ...STATUS[state] };
+    if (suffix) s.text = suffix;
+    node.status(s);
+  } else {
+    node.status(state);
+  }
+}
+
+/** Clear a node's status indicator. */
+function clearStatus(node) {
+  node.status({});
+}
+
+// ─── Value Resolution ────────────────────────────────────────────────────────
+
+/**
+ * Resolve a typed value from the message context.
+ * Supports Node-RED's standard { value, type } descriptor types:
+ *   msg, flow, global, str, num, bool, json, env
+ *
+ * @param {object} RED   Node-RED runtime
+ * @param {object} node  The node instance (for flow/global context access)
+ * @param {object} msg   The current message
+ * @param {object} descriptor  { value: string, type: string }
+ * @returns {*} Resolved value or undefined
+ */
+function resolveValue(RED, node, msg, descriptor) {
+  if (!descriptor) return undefined;
+  const { value, type } = descriptor;
+
+  switch (type) {
+    case 'msg':
+      return RED.util.getMessageProperty(msg, value);
+
+    case 'flow':
+      return node.context().flow.get(value);
+
+    case 'global':
+      return node.context().global.get(value);
+
+    case 'str':
+      return String(value);
+
+    case 'num':
+      return Number(value);
+
+    case 'bool':
+      return value === true || value === 'true';
+
+    case 'json':
+      try { return JSON.parse(value); } catch { return undefined; }
+
+    case 'env':
+      return process.env[value];
+
+    default:
+      return value;
+  }
+}
+
+// ─── Output Property Setter ──────────────────────────────────────────────────
+
+/**
+ * Write a value to a target on msg / flow / global.
+ *
+ * @param {object} RED
+ * @param {object} node
+ * @param {object} msg
+ * @param {object} descriptor  { value: string, type: 'msg'|'flow'|'global' }
+ * @param {*}      data        Value to write
+ */
+function setOutputProperty(RED, node, msg, descriptor, data) {
+  if (!descriptor) return;
+  const { value, type } = descriptor;
+
+  switch (type) {
+    case 'msg':
+      RED.util.setMessageProperty(msg, value, data);
+      break;
+    case 'flow':
+      node.context().flow.set(value, data);
+      break;
+    case 'global':
+      node.context().global.set(value, data);
+      break;
+    default:
+      RED.util.setMessageProperty(msg, value, data);
+  }
+}
+
+// ─── Error Handler ───────────────────────────────────────────────────────────
+
+/**
+ * Standard error handler called from within input event listeners.
+ * Sets an appropriate status, logs to the Node-RED debug panel, and
+ * calls done(err) / node.error(err, msg) for Catch-node compatibility.
+ *
+ * @param {object} node
+ * @param {Error}  err
+ * @param {object} msg
+ * @param {Function} done   Node-RED 1.0+ done callback
+ * @param {Function} send   Node-RED send function (used for error port if configured)
+ * @param {boolean}  [twoOutputs] Whether the node uses a second (error) output
+ */
+function handleNodeError(node, err, msg, done, send, twoOutputs) {
+  const code = (err.code || 'ERROR').toUpperCase();
+
+  // Choose the most informative status text
+  let statusText = err.message || 'unknown error';
+  if (statusText.length > 50) statusText = statusText.substring(0, 47) + '…';
+
+  if (code === 'RATE_LIMITED') {
+    setStatus(node, 'RATE_LIM');
+  } else {
+    setStatus(node, { fill: 'red', shape: 'ring', text: statusText });
+  }
+
+  // Attach error metadata to the message for downstream nodes
+  msg.error = {
+    code:    err.code   || 'ERROR',
+    message: err.message,
+    status:  err.status || null,
+    body:    err.body   || null,
+  };
+
+  // If the node has a second output, emit error message there instead of throwing
+  if (twoOutputs && send) {
+    send([null, msg]);
+    if (done) done();
+    return;
+  }
+
+  // Standard Node-RED error handling (triggers Catch nodes)
+  if (done) {
+    done(err);
+  } else {
+    node.error(err.message, msg);
+  }
+}
+
+// ─── Common Parameter Builder ────────────────────────────────────────────────
+
+/**
+ * Build the common query parameters shared by most IPGeo API calls.
+ *
+ * @param {string} apiKey
+ * @param {object} nodeConfig  Node configuration properties
+ * @returns {object} params object ready for Axios
+ */
+function buildCommonParams(apiKey, nodeConfig) {
+  const params = { apiKey };
+
+  if (nodeConfig.lang && nodeConfig.lang !== 'en') {
+    params.lang = nodeConfig.lang;
+  }
+  if (nodeConfig.output && nodeConfig.output !== 'json') {
+    params.output = nodeConfig.output;
+  }
+  if (nodeConfig.fields && nodeConfig.fields.trim()) {
+    params.fields = nodeConfig.fields.trim();
+  }
+  if (nodeConfig.excludes && nodeConfig.excludes.trim()) {
+    params.excludes = nodeConfig.excludes.trim();
+  }
+
+  return params;
+}
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  STATUS,
+  setStatus,
+  clearStatus,
+  resolveValue,
+  setOutputProperty,
+  handleNodeError,
+  buildCommonParams,
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "node-red-contrib-ipgeolocation",
+  "version": "1.0.0",
+  "description": "Node-RED nodes for the IPGeolocation.io v3 API: IP geolocation, security and threat intelligence (VPN, proxy, and TOR detection), abuse contacts, ASN lookup, bulk IP processing, timezone, astronomy, and user-agent parsing.",
+  "keywords": [
+    "node-red",
+    "ipgeolocation",
+    "geolocation",
+    "ip-lookup",
+    "timezone",
+    "astronomy",
+    "user-agent",
+    "security",
+    "ip-intelligence"
+  ],
+  "author": {
+    "name": "IPGeolocation.io"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/IPGeolocation/node-red-contrib-ipgeolocation",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IPGeolocation/node-red-contrib-ipgeolocation.git"
+  },
+  "bugs": {
+    "url": "https://github.com/IPGeolocation/node-red-contrib-ipgeolocation/issues"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "node-red": {
+    "version": ">=2.0.0",
+    "nodes": {
+      "ipgeo-config": "nodes/ipgeo-config.js",
+      "ipgeo-lookup": "nodes/ipgeo-lookup.js",
+      "ipgeo-bulk": "nodes/ipgeo-bulk.js",
+      "ipgeo-security": "nodes/ipgeo-security.js",
+      "ipgeo-bulk-security": "nodes/ipgeo-bulk-security.js",
+      "ipgeo-abuse": "nodes/ipgeo-abuse.js",
+      "ipgeo-asn": "nodes/ipgeo-asn.js",
+      "ipgeo-timezone": "nodes/ipgeo-timezone.js",
+      "ipgeo-astronomy": "nodes/ipgeo-astronomy.js",
+      "ipgeo-useragent": "nodes/ipgeo-useragent.js"
+    }
+  },
+  "dependencies": {
+    "axios": "^1.18.0"
+  },
+  "devDependencies": {
+    "@node-red/editor-client": "^3.1.9",
+    "mocha": "^10.8.2",
+    "nock": "^13.5.6",
+    "node-red": "^3.1.15",
+    "node-red-node-test-helper": "^0.3.6",
+    "nyc": "^15.1.0",
+    "should": "^13.2.3",
+    "sinon": "^17.0.1"
+  },
+  "main": "index.js",
+  "files": [
+    "nodes/",
+    "examples/",
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "mocha",
+    "test:watch": "mocha --watch",
+    "coverage": "nyc --reporter=text --reporter=html mocha",
+    "prepublishOnly": "npm test"
+  }
+}