node-red-contrib-ipgeolocation 1.0.0

package/nodes/ipgeo-config.html

@@ -0,0 +1,72 @@
+<!-- ============================================================
+     ipgeo-config.html
+     Configuration node editor template + help panel
+     ============================================================ -->
+
+<script type="text/javascript">
+  RED.nodes.registerType('ipgeo-config', {
+    category: 'config',
+    defaults: {
+      name: { value: 'IPGeolocation.io' }
+    },
+    credentials: {
+      apiKey: { type: 'password' }
+    },
+    label: function () {
+      return this.name || 'IPGeolocation.io';
+    },
+    oneditprepare: function () {
+      // Show a tick/cross indicator based on whether a key is already saved
+      const hasKey = this.credentials.has_apiKey;
+      $('#node-config-input-apiKey').attr(
+        'placeholder',
+        hasKey ? '●●●●●●●● (saved)' : 'Paste your API key here'
+      );
+    }
+  });
+</script>
+
+<!-- ── Edit template ── -->
+<script type="text/html" data-template-name="ipgeo-config">
+  <div class="form-row">
+    <label for="node-config-input-name">
+      <i class="fa fa-tag"></i>&nbsp;Name
+    </label>
+    <input type="text" id="node-config-input-name"
+           placeholder="e.g. My IPGeo Key" style="width:70%"/>
+  </div>
+
+  <div class="form-row">
+    <label for="node-config-input-apiKey">
+      <i class="fa fa-key"></i>&nbsp;API Key
+    </label>
+    <input type="password" id="node-config-input-apiKey"
+           style="width:70%"/>
+    <div style="margin-top:6px;font-size:0.85em;color:#888;">
+      Get your free key at
+      <a href="https://app.ipgeolocation.io/signup" target="_blank">
+        ipgeolocation.io
+      </a>.
+      The key is stored encrypted and never exported in flow JSON.
+    </div>
+  </div>
+</script>
+
+<!-- ── Help panel ── -->
+<script type="text/html" data-help-name="ipgeo-config">
+  <p>
+    Stores your <strong>IPGeolocation.io API key</strong> securely as a
+    Node-RED credential.  All IPGeo nodes share this config node so you
+    only need to enter the key once.
+  </p>
+  <h3>How to get an API key</h3>
+  <ol>
+    <li>Sign up at <a href="https://app.ipgeolocation.io/signup" target="_blank">ipgeolocation.io</a>.</li>
+    <li>Log in, open the <strong>Dashboard</strong>, and copy your API key.</li>
+    <li>Paste it into the <em>API Key</em> field above and click <strong>Add</strong>.</li>
+  </ol>
+  <p>
+    The key is stored using Node-RED's credential store and is <strong>never
+    included</strong> in exported flow JSON.
+  </p>
+</script>

package/nodes/ipgeo-config.js

@@ -0,0 +1,30 @@
+/**
+ * ipgeo-config.js
+ *
+ * Configuration node — stores the IPGeolocation.io API key as a credential.
+ * All functional nodes reference this config node so a single key change
+ * propagates everywhere instantly.
+ *
+ * The config node is intentionally minimal; it is a shared credential
+ * container with no input/output behaviour of its own.
+ */
+
+'use strict';
+
+module.exports = function (RED) {
+
+  function IPGeoConfigNode(n) {
+    RED.nodes.createNode(this, n);
+    // 'name' is stored as a plain property (safe to export in flows)
+    this.name = n.name;
+    // 'apiKey' is stored as a credential (never exported in flow JSON)
+    // Access via: this.credentials.apiKey
+  }
+
+  RED.nodes.registerType('ipgeo-config', IPGeoConfigNode, {
+    credentials: {
+      apiKey: { type: 'password' },
+    },
+  });
+
+};

package/nodes/ipgeo-lookup.html

@@ -0,0 +1,300 @@
+<!-- ============================================================
+     ipgeo-lookup.html
+     Single-IP geolocation lookup node — editor template + help
+     ============================================================ -->
+
+<script type="text/javascript">
+(function () {
+  'use strict';
+
+  // ── Helper: populate a select from an options array ────────────────────────
+  function populateSelect(selectId, options, currentVal) {
+    const $sel = $(selectId).empty();
+    options.forEach(function (opt) {
+      $sel.append($('<option>').val(opt.value).text(opt.label));
+    });
+    if (currentVal !== undefined) $sel.val(currentVal);
+  }
+
+  // ── Include module list ────────────────────────────────────────────────────
+  const INCLUDE_MODULES = [
+    { id: 'inc-security',   val: 'security',             label: 'security  (+2 credits)'   },
+    { id: 'inc-abuse',      val: 'abuse',                label: 'abuse  (+1 credit)'        },
+    { id: 'inc-user_agent', val: 'user_agent',           label: 'user_agent'                },
+    { id: 'inc-geo_acc',    val: 'geo_accuracy',         label: 'geo_accuracy'              },
+    { id: 'inc-dma',        val: 'dma_code',             label: 'dma_code (US only)'        },
+    { id: 'inc-host',       val: 'hostname',             label: 'hostname (DB lookup)'      },
+    { id: 'inc-livehost',   val: 'liveHostname',         label: 'liveHostname (DNS lookup)' },
+    { id: 'inc-fallback',   val: 'hostnameFallbackLive', label: 'hostnameFallbackLive'      },
+  ];
+
+  RED.nodes.registerType('ipgeo-lookup', {
+    category:    'IPGeolocation',
+    color:       '#5da0d0',
+    icon:        'font-awesome/fa-map-marker',
+    paletteLabel:'ipgeo lookup',
+
+    defaults: {
+      name:       { value: '' },
+      server:     { value: '', type: 'ipgeo-config', required: true },
+      ipType:     { value: 'str' },
+      ipValue:    { value: '' },
+      include:    { value: '' },
+      fields:     { value: '' },
+      excludes:   { value: '' },
+      lang:       { value: 'en' },
+      outputProp: { value: 'payload' },
+      outputType: { value: 'msg' },
+      uaHeader:   { value: false },
+      uaProp:     { value: 'req.headers.user-agent' },
+      twoOutputs: { value: true },
+    },
+
+    inputs:  1,
+    outputs: 2,   // [success, error]
+
+    outputLabels: function (idx) {
+      return idx === 0 ? 'success' : 'error';
+    },
+
+    label: function () {
+      return this.name || 'ipgeo lookup';
+    },
+
+    labelStyle: function () {
+      return this.name ? 'node_label_italic' : '';
+    },
+
+    oneditprepare: function () {
+      const node = this;
+
+      // ── IP input — typed input widget ──────────────────────────────────
+      $('#node-input-ipValue').typedInput({
+        default:   'str',
+        typeField: '#node-input-ipType',
+        types:     ['msg', 'flow', 'global', 'str'],
+      });
+
+      // ── Include checkboxes — encode/decode comma list ──────────────────
+      const incList = (node.include || '').split(',').map(s => s.trim()).filter(Boolean);
+      INCLUDE_MODULES.forEach(function (mod) {
+        const $cb = $('<input type="checkbox" style="margin-right:6px">')
+          .prop('id', mod.id)
+          .prop('checked', incList.includes(mod.val))
+          .data('val', mod.val);
+        const $label = $('<label>').attr('for', mod.id).text(mod.label)
+          .css({ display: 'inline', fontWeight: 'normal', marginRight: '12px' });
+        $('#ipgeo-include-container').append($('<div>').css('display','inline-block').append($cb).append($label));
+      });
+
+      // ── Output property typed input ────────────────────────────────────
+      $('#node-input-outputProp').typedInput({
+        default:   'msg',
+        typeField: '#node-input-outputType',
+        types:     ['msg', 'flow', 'global'],
+      });
+
+      // ── UA header toggle ───────────────────────────────────────────────
+      function toggleUARow() {
+        if ($('#node-input-uaHeader').prop('checked')) {
+          $('#ipgeo-ua-row').show();
+        } else {
+          $('#ipgeo-ua-row').hide();
+        }
+      }
+      $('#node-input-uaHeader').prop('checked', node.uaHeader).on('change', toggleUARow);
+      toggleUARow();
+
+      // ── Two outputs checkbox ───────────────────────────────────────────
+      $('#node-input-twoOutputs').prop('checked', node.twoOutputs !== false);
+    },
+
+    oneditsave: function () {
+      // Collect include checkboxes back into a comma-separated string
+      const chosen = [];
+      INCLUDE_MODULES.forEach(function (mod) {
+        if ($('#' + mod.id).prop('checked')) chosen.push(mod.val);
+      });
+      this.include    = chosen.join(',');
+      this.twoOutputs = $('#node-input-twoOutputs').prop('checked');
+    },
+  });
+}());
+</script>
+
+<!-- ── Edit template ── -->
+<script type="text/html" data-template-name="ipgeo-lookup">
+  <!-- Name -->
+  <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 lookup" style="width:70%"/>
+  </div>
+
+  <!-- Config node -->
+  <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%"/>
+    <input type="hidden" id="node-input-ipType"/>
+  </div>
+
+  <hr/>
+
+  <!-- IP address input -->
+  <div class="form-row">
+    <label for="node-input-ipValue"><i class="fa fa-globe"></i>&nbsp;IP / Domain</label>
+    <input type="text" id="node-input-ipValue" placeholder="Leave empty to detect caller IP" style="width:70%"/>
+    <div style="margin-top:4px;font-size:0.82em;color:#888;">
+      IPv4, IPv6, or domain name. Leave empty to auto-detect the caller's IP.
+      You can also point to a msg property (e.g. <code>msg.ip</code>).
+    </div>
+  </div>
+
+  <hr/>
+
+  <!-- Include modules (checkboxes) -->
+  <div class="form-row">
+    <label><i class="fa fa-plus-square"></i>&nbsp;Include</label>
+    <div id="ipgeo-include-container" style="display:inline-block;width:70%;vertical-align:top;line-height:2em"></div>
+  </div>
+  <hr/>
+
+  <!-- Fields & Excludes -->
+  <div class="form-row">
+    <label for="node-input-fields"><i class="fa fa-filter"></i>&nbsp;Fields</label>
+    <input type="text" id="node-input-fields" placeholder="e.g. location,asn.organization (comma-separated)" style="width:70%"/>
+  </div>
+  <div class="form-row">
+    <label for="node-input-excludes"><i class="fa fa-minus-square"></i>&nbsp;Excludes</label>
+    <input type="text" id="node-input-excludes" placeholder="e.g. currency,location.continent_code" style="width:70%"/>
+  </div>
+
+  <!-- Language -->
+  <div class="form-row">
+    <label for="node-input-lang"><i class="fa fa-language"></i>&nbsp;Language</label>
+    <select id="node-input-lang" style="width:70%">
+      <option value="en">English (en)</option>
+      <option value="de">German (de)</option>
+      <option value="ru">Russian (ru)</option>
+      <option value="ja">Japanese (ja)</option>
+      <option value="fr">French (fr)</option>
+      <option value="cn">Chinese Simplified (cn)</option>
+      <option value="es">Spanish (es)</option>
+      <option value="cs">Czech (cs)</option>
+      <option value="it">Italian (it)</option>
+      <option value="ko">Korean (ko)</option>
+      <option value="fa">Persian (fa)</option>
+      <option value="pt">Portuguese (pt)</option>
+    </select>
+  </div>
+
+  <hr/>
+
+  <!-- Forward UA header -->
+  <div class="form-row">
+    <label><i class="fa fa-desktop"></i>&nbsp;User-Agent</label>
+    <input type="checkbox" id="node-input-uaHeader" style="width:auto;margin-right:6px"/>
+    <label for="node-input-uaHeader" style="display:inline;font-weight:normal">
+      Forward User-Agent header from msg property
+    </label>
+  </div>
+  <div class="form-row" id="ipgeo-ua-row" style="display:none">
+    <label for="node-input-uaProp" style="margin-left:20px">msg path</label>
+    <input type="text" id="node-input-uaProp" placeholder="req.headers.user-agent" style="width:60%"/>
+  </div>
+
+  <hr/>
+
+  <!-- Output property -->
+  <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>
+
+  <!-- Two outputs toggle -->
+  <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 (instead of throwing to Catch node)
+    </label>
+  </div>
+</script>
+
+<!-- ── Help panel ── -->
+<script type="text/html" data-help-name="ipgeo-lookup">
+  <p>
+    Looks up geolocation, network, ASN, timezone, currency, security, and
+    abuse information for a single IPv4/IPv6 address or domain via
+    <strong>IPGeolocation.io v3 API</strong>.
+  </p>
+
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">any</span></dt>
+    <dd>Passed through unchanged.</dd>
+    <dt class="optional">ipgeo_include <span class="property-type">string</span></dt>
+    <dd>
+      Override the node's <em>Include</em> setting per-message.
+      Comma-separated list, e.g. <code>"security,abuse"</code>.
+    </dd>
+  </dl>
+
+  <h3>Outputs</h3>
+  <ol class="node-ports">
+    <li>
+      <strong>Success</strong>
+      <dl class="message-properties">
+        <dt>payload <span class="property-type">object</span></dt>
+        <dd>
+          Full IPGeolocation.io response. Top-level keys include
+          <code>ip</code>, <code>location</code>, <code>asn</code>,
+          <code>time_zone</code>, <code>currency</code>, <code>company</code>,
+          <code>network</code>, and optionally <code>security</code>,
+          <code>abuse</code>, <code>user_agent</code>, <code>hostname</code>.
+        </dd>
+        <dt class="optional">ipgeo_credits <span class="property-type">number</span></dt>
+        <dd>Credits consumed by this request (from <code>X-Credits-Charged</code> header).</dd>
+      </dl>
+    </li>
+    <li>
+      <strong>Error</strong> (when <em>Use second output</em> is checked)
+      <dl class="message-properties">
+        <dt>error <span class="property-type">object</span></dt>
+        <dd>
+          <code>{ code, message, status, body }</code> — structured error object.
+          Error codes include <code>AUTH_FAILED</code>, <code>RATE_LIMITED</code>,
+          <code>TIMEOUT</code>, <code>BAD_REQUEST</code>, etc.
+        </dd>
+      </dl>
+    </li>
+  </ol>
+
+  <h3>Details</h3>
+  <ul>
+    <li>Leave <em>IP / Domain</em> empty to look up the caller's IP address.</li>
+    <li>
+      Use <em>Include</em> checkboxes to add optional data modules.
+      <code>security</code> costs an extra 2 credits;
+      <code>abuse</code> costs an extra 1 credit.
+    </li>
+    <li>
+      <em>Fields</em> restricts the response to named fields
+      (e.g. <code>location.city,asn.organization</code>).
+    </li>
+    <li>
+      <em>Excludes</em> removes fields or whole objects
+      (e.g. <code>currency,location.continent_code</code>).
+    </li>
+    <li>Failed requests are retried up to 3 times with exponential back-off.</li>
+  </ul>
+
+  <h3>References</h3>
+  <ul>
+    <li>
+      <a href="https://ipgeolocation.io/documentation/ip-location-api.html" target="_blank">
+        IP Geolocation API documentation
+      </a>
+    </li>
+  </ul>
+</script>

package/nodes/ipgeo-lookup.js

@@ -0,0 +1,165 @@
+/**
+ * ipgeo-lookup.js
+ *
+ * Node-RED node: "ipgeo lookup"
+ *
+ * Performs a single-IP geolocation lookup via the IPGeolocation.io
+ * /v3/ipgeo endpoint (GET).
+ *
+ * Features
+ * ─────────
+ *  • IPv4, IPv6, domain, or empty (caller IP auto-detect)
+ *  • Configurable `include` modules: security, abuse, hostname, user_agent,
+ *    geo_accuracy, dma_code  (comma-separated)
+ *  • `fields` and `excludes` for bandwidth optimisation
+ *  • Response language selection (12 languages)
+ *  • Optional custom User-Agent header forwarding
+ *  • Hostname lookup variants: hostname | liveHostname | hostnameFallbackLive
+ *  • IP can be sourced from node config OR msg property (dynamic)
+ *  • Two outputs: [success, error] — error output is optional
+ *  • Exposes credits consumed on msg.ipgeo_credits
+ *  • Full retry + exponential backoff via shared api-client
+ */
+
+'use strict';
+
+const { request, IPGeoError } = require('./lib/api-client');
+const {
+  setStatus,
+  resolveValue,
+  setOutputProperty,
+  handleNodeError,
+  buildCommonParams,
+} = require('./lib/node-helpers');
+
+module.exports = function (RED) {
+
+  function IPGeoLookupNode(config) {
+    RED.nodes.createNode(this, config);
+
+    // ── Config node (API key) ─────────────────────────────────────────────
+    const configNode = RED.nodes.getNode(config.server);
+
+    // ── Node configuration ────────────────────────────────────────────────
+    this.name        = config.name;
+    this.ipType      = config.ipType      || 'str';      // 'str' | 'msg'
+    this.ipValue     = config.ipValue     || '';          // value or msg prop path
+    this.include     = config.include     || '';          // comma-sep list of modules
+    this.fields      = config.fields      || '';
+    this.excludes    = config.excludes    || '';
+    this.lang        = config.lang        || 'en';
+    this.outputProp  = config.outputProp  || 'payload';   // output property
+    this.outputType  = config.outputType  || 'msg';
+    this.uaHeader    = config.uaHeader    || false;       // forward UA from msg
+    this.uaProp      = config.uaProp      || 'req.headers.user-agent';
+    this.twoOutputs  = config.twoOutputs  !== false;      // default true
+
+    const node = this;
+
+    // ── Pre-flight: warn if no config node ───────────────────────────────
+    if (!configNode) {
+      setStatus(node, 'NO_KEY');
+      node.warn('No IPGeolocation.io config node selected — configure an API key first.');
+    } else {
+      setStatus(node, 'IDLE');
+    }
+
+    // ── Input handler ─────────────────────────────────────────────────────
+    node.on('input', async function (msg, send, done) {
+      // Node-RED 0.x compat
+      send = send || function () { node.send.apply(node, arguments); };
+
+      // ── Validate API key availability ─────────────────────────────────
+      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 IP from msg or static config ──────────────────────────
+      let ip = '';
+      if (node.ipType === 'msg') {
+        ip = resolveValue(RED, node, msg,
+          { value: node.ipValue, type: 'msg' }) || '';
+      } else if (node.ipType === 'flow') {
+        ip = resolveValue(RED, node, msg,
+          { value: node.ipValue, type: 'flow' }) || '';
+      } else if (node.ipType === 'global') {
+        ip = resolveValue(RED, node, msg,
+          { value: node.ipValue, type: 'global' }) || '';
+      } else {
+        // 'str' — static value from node config; can be empty for caller-IP
+        ip = (node.ipValue || '').trim();
+      }
+
+      ip = String(ip).trim();
+
+      // ── Build query parameters ────────────────────────────────────────
+      const params = buildCommonParams(apiKey, {
+        lang:     node.lang,
+        fields:   node.fields,
+        excludes: node.excludes,
+      });
+
+      if (ip) params.ip = ip;
+
+      // Build include list (may come from node config or msg override)
+      const includeList = (msg.ipgeo_include || node.include || '').trim();
+      if (includeList) params.include = includeList;
+
+      // ── Optional User-Agent header forwarding ─────────────────────────
+      const extraHeaders = {};
+      if (node.uaHeader) {
+        const ua = resolveValue(RED, node, msg,
+          { value: node.uaProp, type: 'msg' });
+        if (ua) extraHeaders['User-Agent'] = ua;
+      }
+
+      // ── Set working status ────────────────────────────────────────────
+      setStatus(node, 'WORKING');
+
+      // ── API call ──────────────────────────────────────────────────────
+      try {
+        const { data, credits } = await request({
+          method:  'GET',
+          path:    '/ipgeo',
+          params,
+          headers: extraHeaders,
+        });
+
+        // ── Success ────────────────────────────────────────────────────
+        setStatus(node, 'OK',
+          `${data.location?.city || data.ip || 'ok'}`);
+
+        // Write result to configured output property
+        setOutputProperty(RED, node, msg,
+          { value: node.outputProp, type: node.outputType }, data);
+
+        // Expose credits consumed (informational)
+        if (credits !== null) msg.ipgeo_credits = credits;
+
+        // Clear error property if previously set
+        delete msg.error;
+
+        send(node.twoOutputs ? [msg, null] : msg);
+        if (done) done();
+
+      } catch (err) {
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+      }
+    });
+
+    // ── Clean up on node removal/redeploy ─────────────────────────────────
+    node.on('close', function () {
+      setStatus(node, 'IDLE');
+    });
+  }
+
+  RED.nodes.registerType('ipgeo-lookup', IPGeoLookupNode);
+
+};