node-red-contrib-ipgeolocation 1.0.0

package/nodes/ipgeo-timezone.js

@@ -0,0 +1,154 @@
+/**
+ * ipgeo-timezone.js
+ *
+ * Node-RED node: "ipgeo timezone"
+ *
+ * Timezone lookup via /v3/timezone supporting all input modes:
+ *   tz      — IANA timezone name  (e.g. "America/New_York")
+ *   ip      — IPv4 or IPv6 address
+ *   location— Free-text address   (e.g. "New York, USA")
+ *   coords  — Latitude + Longitude
+ *   iata    — IATA airport code   (e.g. "JFK")
+ *   icao    — ICAO airport code   (e.g. "KJFK")
+ *   unlocode— UN/LOCODE           (e.g. "USNYC")
+ *
+ * Each input mode is selectable in the editor. The dynamic input
+ * value can be sourced from the node config (static) or msg properties.
+ */
+
+'use strict';
+
+const { request, IPGeoError } = require('./lib/api-client');
+const {
+  setStatus,
+  resolveValue,
+  setOutputProperty,
+  handleNodeError,
+} = require('./lib/node-helpers');
+
+// Mapping from editor lookup-mode to API query parameter name
+const MODE_PARAM = {
+  tz:       'tz',
+  ip:       'ip',
+  location: 'location',
+  coords:   null,          // lat + lng are separate params
+  iata:     'iata',
+  icao:     'icao',
+  unlocode: 'location',    // UN/LO code is passed as 'location'
+};
+
+module.exports = function (RED) {
+
+  function IPGeoTimezoneNode(config) {
+    RED.nodes.createNode(this, config);
+
+    const configNode = RED.nodes.getNode(config.server);
+
+    this.name        = config.name;
+    this.mode        = config.mode        || 'tz';    // lookup mode
+    this.inputType   = config.inputType   || 'str';   // msg | str | flow | global
+    this.inputValue  = config.inputValue  || '';
+    this.latType     = config.latType     || 'str';
+    this.latValue    = config.latValue    || '';
+    this.lngType     = config.lngType     || 'str';
+    this.lngValue    = config.lngValue    || '';
+    this.outputProp  = config.outputProp  || 'payload';
+    this.outputType  = config.outputType  || 'msg';
+    this.twoOutputs  = config.twoOutputs  !== false;
+
+    const node = this;
+
+    if (!configNode) {
+      setStatus(node, 'NO_KEY');
+    } else {
+      setStatus(node, 'IDLE');
+    }
+
+    node.on('input', async function (msg, send, done) {
+      send = send || function () { node.send.apply(node, arguments); };
+
+      const apiKey = configNode && configNode.credentials
+        ? configNode.credentials.apiKey : null;
+
+      if (!apiKey) {
+        setStatus(node, 'NO_KEY');
+        const err = new IPGeoError('No API key configured', 'NO_API_KEY');
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      // ── Build query params ─────────────────────────────────────────────
+      const params = { apiKey };
+      const mode   = node.mode;
+
+      try {
+        if (mode === 'coords') {
+          // Latitude & Longitude — two separate resolved values
+          const lat = resolveValue(RED, node, msg,
+            { value: node.latValue, type: node.latType });
+          const lng = resolveValue(RED, node, msg,
+            { value: node.lngValue, type: node.lngType });
+
+          if (lat === undefined || lat === null || lat === '') {
+            throw new IPGeoError('Latitude is required for coords mode', 'INVALID_INPUT');
+          }
+          if (lng === undefined || lng === null || lng === '') {
+            throw new IPGeoError('Longitude is required for coords mode', 'INVALID_INPUT');
+          }
+
+          params.lat = lat;
+          params.long = lng;
+
+        } else {
+          // Single-value modes
+          const paramKey = MODE_PARAM[mode];
+          if (!paramKey) {
+            throw new IPGeoError(`Unknown lookup mode: ${mode}`, 'INVALID_MODE');
+          }
+
+          const inputVal = resolveValue(RED, node, msg,
+            { value: node.inputValue, type: node.inputType });
+
+          if (!inputVal && inputVal !== 0) {
+            throw new IPGeoError(`Input value is empty for mode "${mode}"`, 'INVALID_INPUT');
+          }
+
+          params[paramKey] = String(inputVal).trim();
+        }
+      } catch (err) {
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      setStatus(node, 'WORKING');
+
+      try {
+        const { data, credits } = await request({
+          method: 'GET',
+          path:   '/timezone',
+          params,
+        });
+
+        const tzName = (data.time_zone && data.time_zone.name) || 'ok';
+        setStatus(node, 'OK', tzName);
+
+        setOutputProperty(RED, node, msg,
+          { value: node.outputProp, type: node.outputType }, data);
+
+        if (credits !== null) msg.ipgeo_credits = credits;
+        delete msg.error;
+
+        send(node.twoOutputs ? [msg, null] : msg);
+        if (done) done();
+
+      } catch (err) {
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+      }
+    });
+
+    node.on('close', () => setStatus(node, 'IDLE'));
+  }
+
+  RED.nodes.registerType('ipgeo-timezone', IPGeoTimezoneNode);
+
+};

package/nodes/ipgeo-useragent.html

@@ -0,0 +1,133 @@
+<!-- ============================================================
+     ipgeo-useragent.html
+     User-Agent parser node
+     ============================================================ -->
+
+<script type="text/javascript">
+(function () {
+  'use strict';
+
+  RED.nodes.registerType('ipgeo-useragent', {
+    category:    'IPGeolocation',
+    color:       '#5da0d0',
+    icon:        'font-awesome/fa-desktop',
+    paletteLabel:'ipgeo user-agent',
+
+    defaults: {
+      name:       { value: '' },
+      server:     { value: '', type: 'ipgeo-config', required: true },
+      uaType:     { value: 'msg' },
+      uaValue:    { value: 'req.headers.user-agent' },
+      outputProp: { value: 'payload' },
+      outputType: { value: 'msg' },
+      twoOutputs: { value: true },
+    },
+
+    inputs:  1,
+    outputs: 2,
+    outputLabels: function (idx) { return idx === 0 ? 'success' : 'error'; },
+
+    label: function () { return this.name || 'ipgeo user-agent'; },
+
+    oneditprepare: function () {
+      const node = this;
+
+      $('#node-input-uaValue').typedInput({
+        default:   'msg',
+        typeField: '#node-input-uaType',
+        types:     ['msg', 'flow', 'global', 'str'],
+      });
+
+      $('#node-input-outputProp').typedInput({
+        default:   'msg',
+        typeField: '#node-input-outputType',
+        types:     ['msg', 'flow', 'global'],
+      });
+
+      $('#node-input-twoOutputs').prop('checked', node.twoOutputs !== false);
+    },
+
+    oneditsave: function () {
+      this.twoOutputs = $('#node-input-twoOutputs').prop('checked');
+    },
+  });
+}());
+</script>
+
+<!-- ── Edit template ── -->
+<script type="text/html" data-template-name="ipgeo-useragent">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i>&nbsp;Name</label>
+    <input type="text" id="node-input-name" placeholder="ipgeo user-agent" style="width:70%"/>
+  </div>
+  <div class="form-row">
+    <label for="node-input-server"><i class="fa fa-key"></i>&nbsp;API Config</label>
+    <input type="text" id="node-input-server" style="width:70%"/>
+  </div>
+  <hr/>
+  <div class="form-row">
+    <label for="node-input-uaValue"><i class="fa fa-desktop"></i>&nbsp;User-Agent</label>
+    <input type="text" id="node-input-uaValue" style="width:70%"/>
+    <input type="hidden" id="node-input-uaType"/>
+    <div style="margin-top:4px;font-size:0.82em;color:#888;">
+      Point to the message property that holds the UA string, or enter a
+      static string directly. Default: <code>msg.req.headers.user-agent</code>
+      (works with the built-in HTTP In node).
+    </div>
+  </div>
+  <hr/>
+  <div class="form-row">
+    <label for="node-input-outputProp"><i class="fa fa-sign-out"></i>&nbsp;Output to</label>
+    <input type="text" id="node-input-outputProp" style="width:70%"/>
+    <input type="hidden" id="node-input-outputType"/>
+  </div>
+  <div class="form-row">
+    <label><i class="fa fa-random"></i>&nbsp;Outputs</label>
+    <input type="checkbox" id="node-input-twoOutputs" style="width:auto;margin-right:6px"/>
+    <label for="node-input-twoOutputs" style="display:inline;font-weight:normal">
+      Use second output for errors
+    </label>
+  </div>
+</script>
+
+<!-- ── Help panel ── -->
+<script type="text/html" data-help-name="ipgeo-useragent">
+  <p>
+    Parses a User-Agent string using the
+    <strong>IPGeolocation.io User-Agent API</strong> to identify the browser,
+    device type, OS, and rendering engine.
+  </p>
+
+  <h3>Input</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">any</span></dt>
+    <dd>Passed through. The User-Agent string is read from a separate property.</dd>
+  </dl>
+
+  <h3>Output</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">object</span></dt>
+    <dd>
+      <code>{ user_agent_string, name, type, version, version_major,
+      device: { name, type, brand, cpu },
+      engine: { name, type, version },
+      operating_system: { name, type, version, build } }</code>
+    </dd>
+  </dl>
+
+  <h3>Tip</h3>
+  <p>
+    Connect to Node-RED's built-in <strong>HTTP In</strong> node and set the
+    UA source to <code>msg.req.headers.user-agent</code> to automatically
+    parse visitor browser details.
+  </p>
+
+  <h3>References</h3>
+  <ul>
+    <li>
+      <a href="https://ipgeolocation.io/documentation/user-agent-api.html" target="_blank">
+        User-Agent API documentation
+      </a>
+    </li>
+  </ul>
+</script>

package/nodes/ipgeo-useragent.js

@@ -0,0 +1,110 @@
+/**
+ * ipgeo-useragent.js
+ *
+ * Node-RED node: "ipgeo user-agent"
+ *
+ * Parses a User-Agent string via the IPGeolocation.io /v3/user-agent endpoint.
+ *
+ * Input
+ * ─────
+ *  User-Agent string can be sourced from:
+ *    • Static string in the node config
+ *    • A msg property (e.g. msg.req.headers['user-agent'])
+ *    • An incoming HTTP request forwarded through Node-RED's HTTP-in node
+ *
+ * Output
+ * ──────
+ *  msg.payload  (or configured output property) — parsed UA object with:
+ *    { user_agent_string, name, type, version, device, engine, operating_system }
+ */
+
+'use strict';
+
+const { request, IPGeoError } = require('./lib/api-client');
+const {
+  setStatus,
+  resolveValue,
+  setOutputProperty,
+  handleNodeError,
+} = require('./lib/node-helpers');
+
+module.exports = function (RED) {
+
+  function IPGeoUserAgentNode(config) {
+    RED.nodes.createNode(this, config);
+
+    const configNode = RED.nodes.getNode(config.server);
+
+    this.name        = config.name;
+    this.uaType      = config.uaType     || 'msg';   // msg | str | flow | global
+    this.uaValue     = config.uaValue    || 'req.headers.user-agent';
+    this.outputProp  = config.outputProp || 'payload';
+    this.outputType  = config.outputType || 'msg';
+    this.twoOutputs  = config.twoOutputs !== false;
+
+    const node = this;
+
+    if (!configNode) {
+      setStatus(node, 'NO_KEY');
+    } else {
+      setStatus(node, 'IDLE');
+    }
+
+    node.on('input', async function (msg, send, done) {
+      send = send || function () { node.send.apply(node, arguments); };
+
+      const apiKey = configNode && configNode.credentials
+        ? configNode.credentials.apiKey : null;
+
+      if (!apiKey) {
+        setStatus(node, 'NO_KEY');
+        const err = new IPGeoError('No API key configured', 'NO_API_KEY');
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      // ── Resolve UA string ─────────────────────────────────────────────
+      const ua = resolveValue(RED, node, msg,
+        { value: node.uaValue, type: node.uaType });
+
+      if (!ua || String(ua).trim() === '') {
+        const err = new IPGeoError(
+          'User-Agent string is empty or not found at the configured path',
+          'INVALID_INPUT'
+        );
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      setStatus(node, 'WORKING');
+
+      try {
+        const { data, credits } = await request({
+          method:  'GET',
+          path:    '/user-agent',
+          params:  { apiKey },
+          headers: { 'User-Agent': String(ua).trim() },
+        });
+
+        setStatus(node, 'OK', data.name || 'parsed');
+
+        setOutputProperty(RED, node, msg,
+          { value: node.outputProp, type: node.outputType }, data);
+
+        if (credits !== null) msg.ipgeo_credits = credits;
+        delete msg.error;
+
+        send(node.twoOutputs ? [msg, null] : msg);
+        if (done) done();
+
+      } catch (err) {
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+      }
+    });
+
+    node.on('close', () => setStatus(node, 'IDLE'));
+  }
+
+  RED.nodes.registerType('ipgeo-useragent', IPGeoUserAgentNode);
+
+};

package/nodes/lib/api-client.js

@@ -0,0 +1,210 @@
+/**
+ * lib/api-client.js
+ *
+ * Shared Axios-based HTTP client for the IPGeolocation.io v3 API.
+ *
+ * Responsibilities
+ * ─────────────────
+ *  • Single Axios instance with base URL and sensible timeouts
+ *  • Exponential-backoff retry for transient errors (5xx, ECONNRESET, ETIMEDOUT)
+ *  • Structured error objects that every node can map to Node-RED status/done(err)
+ *  • Rate-limit awareness (HTTP 429 → honour Retry-After header when present)
+ *  • Credit-charge extraction from response headers
+ */
+
+'use strict';
+
+const axios = require('axios');
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const BASE_URL       = 'https://api.ipgeolocation.io/v3';
+const DEFAULT_TIMEOUT = 10_000;   // 10 s
+const MAX_RETRIES     = 3;
+const RETRY_DELAY_MS  = 500;      // base delay; doubles each attempt
+
+// HTTP status codes that are safe to retry (server-side transient faults)
+const RETRYABLE_STATUS = new Set([429, 500, 502, 503, 504]);
+
+// ─── Error Classes ───────────────────────────────────────────────────────────
+
+class IPGeoError extends Error {
+  /**
+   * @param {string}  message   Human-readable description
+   * @param {string}  code      Machine-readable code (e.g. 'AUTH_FAILED')
+   * @param {number}  [status]  HTTP status code, if applicable
+   * @param {object}  [body]    Raw API response body, if available
+   */
+  constructor(message, code, status, body) {
+    super(message);
+    this.name   = 'IPGeoError';
+    this.code   = code;
+    this.status = status || null;
+    this.body   = body  || null;
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Sleep for `ms` milliseconds (used in retry logic).
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Map an Axios error to a typed IPGeoError with a user-friendly message.
+ *
+ * @param {import('axios').AxiosError} err
+ * @returns {IPGeoError}
+ */
+function mapAxiosError(err) {
+  if (err.response) {
+    const { status, data } = err.response;
+    const apiMsg = (data && (data.message || data.error)) || '';
+
+    switch (status) {
+      case 400: return new IPGeoError(
+        `Bad request: ${apiMsg || 'Invalid parameters'}`, 'BAD_REQUEST', 400, data);
+      case 401: return new IPGeoError(
+        `Authentication failed: ${apiMsg || 'Invalid or missing API key'}`, 'AUTH_FAILED', 401, data);
+      case 403: return new IPGeoError(
+        `Forbidden: ${apiMsg || 'Access denied (check plan limits or IP whitelist)'}`, 'FORBIDDEN', 403, data);
+      case 404: return new IPGeoError(
+        `Resource not found: ${apiMsg || 'Endpoint does not exist'}`, 'NOT_FOUND', 404, data);
+      case 422: return new IPGeoError(
+        `Unprocessable entity: ${apiMsg || 'Validation error'}`, 'VALIDATION', 422, data);
+      case 423: return new IPGeoError(
+        `API key locked: ${apiMsg || 'Quota exceeded or account suspended'}`, 'LOCKED', 423, data);
+      case 429: return new IPGeoError(
+        `Rate limit exceeded: ${apiMsg || 'Too many requests'}`, 'RATE_LIMITED', 429, data);
+      case 500: return new IPGeoError(
+        `API server error (500): ${apiMsg || 'Internal server error'}`, 'SERVER_ERROR', 500, data);
+      default:  return new IPGeoError(
+        `HTTP ${status}: ${apiMsg || err.message}`, 'HTTP_ERROR', status, data);
+    }
+  }
+
+  if (err.request) {
+    // Request was sent but no response received
+    const code = err.code || '';
+    if (code === 'ETIMEDOUT' || code === 'ECONNABORTED') {
+      return new IPGeoError(
+        `Request timed out after ${DEFAULT_TIMEOUT / 1000}s`, 'TIMEOUT');
+    }
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') {
+      return new IPGeoError(
+        'DNS resolution failed — check network connectivity', 'NETWORK_ERROR');
+    }
+    return new IPGeoError(`No response received: ${err.message}`, 'NO_RESPONSE');
+  }
+
+  // Something went wrong building the request
+  return new IPGeoError(`Request setup error: ${err.message}`, 'REQUEST_ERROR');
+}
+
+// ─── Core Request Function ───────────────────────────────────────────────────
+
+/**
+ * Perform an HTTP GET or POST with automatic retries.
+ *
+ * @param {object} options
+ * @param {'GET'|'POST'} options.method
+ * @param {string}  options.path         Relative path, e.g. '/ipgeo'
+ * @param {object}  [options.params]     URL query parameters
+ * @param {object}  [options.data]       JSON body (POST only)
+ * @param {object}  [options.headers]    Additional HTTP headers
+ * @param {number}  [options.timeout]    Override default timeout (ms)
+ * @param {number}  [options.maxRetries] Override default retry count
+ * @returns {Promise<{ data: any, credits: number|null }>}
+ */
+async function request(options) {
+  const {
+    method      = 'GET',
+    path,
+    params      = {},
+    data        = undefined,
+    headers     = {},
+    timeout     = DEFAULT_TIMEOUT,
+    maxRetries  = MAX_RETRIES,
+  } = options;
+
+  const url = `${BASE_URL}${path}`;
+  let attempt = 0;
+
+  while (attempt <= maxRetries) {
+    try {
+      const response = await axios({
+        method,
+        url,
+        params,
+        data,
+        headers: {
+          'Accept':       'application/json',
+          'Content-Type': 'application/json',
+          'User-Agent':   'node-red-contrib-ipgeolocation-io/1.0.0',
+          ...headers,
+        },
+        timeout,
+        validateStatus: null, // We handle all status codes ourselves
+      });
+
+      // Successful response (2xx)
+      if (response.status >= 200 && response.status < 300) {
+        const credits = response.headers['x-credits-charged']
+          ? Number(response.headers['x-credits-charged'])
+          : null;
+        return { data: response.data, credits };
+      }
+
+      // Handle retryable server-side errors
+      if (RETRYABLE_STATUS.has(response.status) && attempt < maxRetries) {
+        let delay = RETRY_DELAY_MS * Math.pow(2, attempt);
+
+        // Honour Retry-After header for 429 responses
+        if (response.status === 429) {
+          const retryAfter = response.headers['retry-after'];
+          if (retryAfter) {
+            delay = Math.max(delay, Number(retryAfter) * 1000);
+          }
+        }
+
+        attempt++;
+        await sleep(delay);
+        continue;
+      }
+
+      // Non-retryable error — map and throw
+      const fakeAxiosError = { response };
+      throw mapAxiosError(fakeAxiosError);
+
+    } catch (err) {
+      // Axios network-level errors (ETIMEDOUT, ECONNRESET, etc.)
+      if (err instanceof IPGeoError) throw err; // already mapped, re-throw
+
+      const ipGeoErr = mapAxiosError(err);
+
+      // Retry on network-level transient faults
+      const isTransient =
+        ipGeoErr.code === 'TIMEOUT'       ||
+        ipGeoErr.code === 'NO_RESPONSE'   ||
+        ipGeoErr.code === 'NETWORK_ERROR';
+
+      if (isTransient && attempt < maxRetries) {
+        attempt++;
+        await sleep(RETRY_DELAY_MS * Math.pow(2, attempt));
+        continue;
+      }
+
+      throw ipGeoErr;
+    }
+  }
+
+  // Should never reach here, but just in case
+  throw new IPGeoError('Max retries exceeded', 'MAX_RETRIES');
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+module.exports = { request, IPGeoError, BASE_URL };