node-red-contrib-ipgeolocation 1.0.0

package/nodes/ipgeo-bulk-security.html

@@ -0,0 +1,166 @@
+<!-- ============================================================
+     ipgeo-bulk-security.html
+     Bulk IP security / threat lookup node
+     ============================================================ -->
+
+<script type="text/javascript">
+    (function () {
+        'use strict';
+
+        RED.nodes.registerType('ipgeo-bulk-security', {
+            category: 'IPGeolocation',
+            color: '#d9534f',
+            icon: 'font-awesome/fa-shield',
+            paletteLabel: 'ipgeo bulk security',
+
+            defaults: {
+                name: { value: '' },
+                server: { value: '', type: 'ipgeo-config', required: true },
+                fields: { value: '' },
+                excludes: { value: '' },
+                outputProp: { value: 'payload' },
+                outputType: { value: 'msg' },
+                twoOutputs: { value: true },
+            },
+
+            inputs: 1,
+            outputs: 2,
+
+            outputLabels: function (idx) {
+                return idx === 0 ? 'success (array)' : 'error';
+            },
+
+            label: function () {
+                return this.name || 'ipgeo bulk security';
+            },
+
+            oneditprepare: function () {
+                const node = this;
+
+                $('#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-bulk-security">
+          <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 bulk security" 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-fields"><i class="fa fa-filter"></i>&nbsp;Fields</label>
+            <input type="text" id="node-input-fields"
+                   placeholder="e.g. security.is_vpn,security.threat_score" style="width:70%"/>
+            <div style="margin-top:4px;font-size:0.82em;color:#888;">
+              Dot-notation, comma-separated. Returns only the listed fields from the
+              <code>security</code> object.
+            </div>
+          </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. security.proxy_last_seen,security.vpn_last_seen" style="width:70%"/>
+            <div style="margin-top:4px;font-size:0.82em;color:#888;">
+              Dot-notation, comma-separated. Returns the full <code>security</code>
+              object except the listed fields. <code>ip</code> is always included
+              and cannot be excluded.
+            </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-bulk-security">
+          <p>
+            Performs a <strong>bulk IP security / threat lookup</strong> for up to
+            <strong>50,000</strong> IPv4/IPv6 addresses in a single HTTP POST request,
+            via the <code>/v3/security-bulk</code> endpoint.
+          </p>
+          <p>
+            For each IP, the response reports a threat score plus VPN, proxy,
+            residential proxy, Tor, relay, bot, spam, known-attacker and
+            cloud-provider signals.
+          </p>
+        
+          <h3>Input</h3>
+          <dl class="message-properties">
+            <dt>payload <span class="property-type">array | string</span></dt>
+            <dd>
+              An array of IPv4/IPv6 address strings, e.g.
+              <code>["2.56.188.34","2.56.188.35"]</code>. A comma-separated string is
+              also accepted and will be auto-split.
+              <strong>Domain names are not supported</strong> by the Security API.
+            </dd>
+          </dl>
+        
+          <h3>Output</h3>
+          <dl class="message-properties">
+            <dt>payload <span class="property-type">array</span></dt>
+            <dd>
+              Array of result objects in the same order as the input. Each entry is
+              either <code>{ ip, security: {...} }</code> for a valid IP, or
+              <code>{ message: "..." }</code> for a bogon, private, or malformed
+              entry — these do not fail the request.
+            </dd>
+            <dt class="optional">ipgeo_credits <span class="property-type">number</span></dt>
+            <dd>
+              Total credits consumed. Each valid IP costs 2 credits; bogon, private,
+              and malformed entries are not charged.
+            </dd>
+            <dt class="optional">ipgeo_invalid_count <span class="property-type">number</span></dt>
+            <dd>
+              Number of entries that came back as <code>{ message }</code> instead
+              of a security result. Only present when at least one entry was
+              invalid.
+            </dd>
+            <dt class="optional">ipgeo_invalid_messages <span class="property-type">array</span></dt>
+            <dd>
+              The <code>message</code> text for each invalid entry. Only present
+              when at least one entry was invalid.
+            </dd>
+          </dl>
+        
+          <h3>Notes</h3>
+          <ul>
+            <li>Only <code>fields</code> and <code>excludes</code> options are supported — there is no <code>include</code> or language option for the Security API.</li>
+            <li>Requires an API key on the configured server; bulk requests cannot be authenticated via Request Origin (CORS-only) setups.</li>
+          </ul>
+        
+          <h3>References</h3>
+          <ul>
+            <li>
+              <a href="https://ipgeolocation.io/documentation/ip-security-api.html#bulk-ip-security-lookup-endpoint" target="_blank">
+                Bulk IP Security Lookup documentation
+              </a>
+            </li>
+          </ul>
+        </script>

package/nodes/ipgeo-bulk-security.js

@@ -0,0 +1,177 @@
+/**
+ * ipgeo-bulk-security.js
+ *
+ * Node-RED node: "ipgeo bulk security"
+ *
+ * Performs bulk IP security / threat lookups via the IPGeolocation.io
+ * /v3/security-bulk endpoint (POST).
+ *
+ * Input
+ * ─────
+ *  msg.payload  — Array of IPv4/IPv6 address strings  (required)
+ *               OR a comma-separated string which is auto-split
+ *               (domain names are NOT supported by the Security API)
+ *
+ * Configuration
+ * ─────────────
+ *  • fields / excludes options (dot-notation, e.g. "security.threat_score")
+ *  • No "include" or "lang" options — the Security API does not support them
+ *  • Max 50,000 IPs per request (per API limits)
+ *  • Each result corresponds to one IP in the input array, in order.
+ *    Invalid/bogon/private/malformed IPs return { message: '...' } objects
+ *    instead of failing the whole request (per API spec).
+ *
+ * Output
+ * ──────
+ *  msg.payload            — Array of security result objects
+ *  msg.ipgeo_credits      — Credits consumed (2 per valid IP; from response header)
+ *  msg.ipgeo_invalid_count    — Number of entries that came back as { message }
+ *                               instead of a security result (only set if > 0,
+ *                               mirroring the API's X-Successful-Record header
+ *                               which is likewise only sent when invalid IPs
+ *                               are present)
+ *  msg.ipgeo_invalid_messages — Array of the invalid entries' messages
+ *                               (only set if ipgeo_invalid_count > 0)
+ */
+
+'use strict';
+
+const { request, IPGeoError } = require('./lib/api-client');
+const {
+  setStatus,
+  setOutputProperty,
+  handleNodeError,
+  buildCommonParams,
+} = require('./lib/node-helpers');
+
+const MAX_IPS = 50_000;
+
+module.exports = function (RED) {
+
+  function IPGeoBulkSecurityNode(config) {
+    RED.nodes.createNode(this, config);
+
+    const configNode = RED.nodes.getNode(config.server);
+
+    this.name       = config.name;
+    this.fields     = config.fields    || '';
+    this.excludes   = config.excludes  || '';
+    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); };
+
+      // ── API key ──────────────────────────────────────────────────────────
+      // Note: per the API docs, the bulk security endpoint requires an
+      // apiKey and cannot be authenticated via Request Origin (CORS) —
+      // unlike the single-IP /security endpoint.
+      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;
+      }
+
+      // ── Extract IP list from msg.payload ─────────────────────────────────
+      let ips = msg.payload;
+
+      // Support comma-separated string
+      if (typeof ips === 'string') {
+        ips = ips.split(',').map(s => s.trim()).filter(Boolean);
+      }
+
+      if (!Array.isArray(ips) || ips.length === 0) {
+        const err = new IPGeoError(
+          'msg.payload must be a non-empty array of IPv4/IPv6 addresses or a comma-separated string',
+          'INVALID_INPUT'
+        );
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      if (ips.length > MAX_IPS) {
+        const err = new IPGeoError(
+          `Bulk security lookup limit is ${MAX_IPS} IPs per request; received ${ips.length}`,
+          'TOO_MANY_IPS'
+        );
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      // ── Build params ──────────────────────────────────────────────────────
+      // The security-bulk endpoint only supports `fields` and `excludes`
+      // (plus `output`, which we don't expose since the response is always
+      // parsed as JSON). There is no `include` and no `lang` here.
+      const params = buildCommonParams(apiKey, {
+        fields:   node.fields,
+        excludes: node.excludes,
+      });
+
+      setStatus(node, 'WORKING');
+
+      try {
+        const { data, credits } = await request({
+          method: 'POST',
+          path:   '/security-bulk',
+          params,
+          data:   { ips },
+          // Bulk requests can be large — give them extra time
+          timeout: 30_000,
+        });
+
+        // Each entry is either { ip, security: {...} } for a valid IP, or
+        // { message: '...' } for a bogon/private/malformed entry. Count the
+        // latter so the user gets the same signal the API otherwise conveys
+        // via the (conditionally-present) X-Successful-Record header.
+        const invalidEntries = Array.isArray(data)
+          ? data.filter((entry) => entry && typeof entry === 'object' && !('security' in entry))
+          : [];
+
+        const validCount = Array.isArray(data) ? data.length - invalidEntries.length : ips.length;
+
+        setStatus(node, 'OK', invalidEntries.length > 0
+          ? `${validCount}/${ips.length} valid`
+          : `${ips.length} IPs`);
+
+        setOutputProperty(RED, node, msg,
+          { value: node.outputProp, type: node.outputType }, data);
+
+        if (credits !== null) msg.ipgeo_credits = credits;
+
+        if (invalidEntries.length > 0) {
+          msg.ipgeo_invalid_count = invalidEntries.length;
+          msg.ipgeo_invalid_messages = invalidEntries.map((entry) => entry.message);
+        } else {
+          delete msg.ipgeo_invalid_count;
+          delete msg.ipgeo_invalid_messages;
+        }
+
+        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-bulk-security', IPGeoBulkSecurityNode);
+
+};

package/nodes/ipgeo-bulk.html

@@ -0,0 +1,158 @@
+<!-- ============================================================
+     ipgeo-bulk.html
+     Bulk IP geolocation lookup node
+     ============================================================ -->
+
+<script type="text/javascript">
+(function () {
+  'use strict';
+
+  RED.nodes.registerType('ipgeo-bulk', {
+    category:    'IPGeolocation',
+    color:       '#5da0d0',
+    icon:        'font-awesome/fa-list',
+    paletteLabel:'ipgeo bulk',
+
+    defaults: {
+      name:       { value: '' },
+      server:     { value: '', type: 'ipgeo-config', required: true },
+      include:    { value: '' },
+      fields:     { value: '' },
+      excludes:   { value: '' },
+      lang:       { value: 'en' },
+      outputProp: { value: 'payload' },
+      outputType: { value: 'msg' },
+      twoOutputs: { value: true },
+    },
+
+    inputs:  1,
+    outputs: 2,
+
+    outputLabels: function (idx) {
+      return idx === 0 ? 'success (array)' : 'error';
+    },
+
+    label: function () {
+      return this.name || 'ipgeo bulk';
+    },
+
+    oneditprepare: function () {
+      const node = this;
+
+      $('#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-bulk">
+  <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 bulk" 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-include"><i class="fa fa-plus-square"></i>&nbsp;Include</label>
+    <input type="text" id="node-input-include"
+           placeholder="e.g. security,abuse  (comma-separated)" style="width:70%"/>
+    <div style="margin-top:4px;font-size:0.82em;color:#888;">
+      security (+2 credits each), abuse (+1), user_agent, geo_accuracy, dma_code,
+      hostname, liveHostname, hostnameFallbackLive
+    </div>
+  </div>
+  <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.city,currency" 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,time_zone" style="width:70%"/>
+  </div>
+  <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/>
+  <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-bulk">
+  <p>
+    Performs a <strong>bulk geolocation lookup</strong> for up to <strong>50,000</strong>
+    IPv4/IPv6 addresses or domain names in a single HTTP POST request.
+  </p>
+
+  <h3>Input</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">array | string</span></dt>
+    <dd>
+      An array of IP/domain strings, e.g. <code>["1.2.3.4","2.3.4.5"]</code>.
+      A comma-separated string is also accepted and will be auto-split.
+    </dd>
+    <dt class="optional">ipgeo_include <span class="property-type">string</span></dt>
+    <dd>Per-message override for the <em>Include</em> setting.</dd>
+  </dl>
+
+  <h3>Output</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">array</span></dt>
+    <dd>
+      Array of result objects in the same order as the input.
+      Invalid/private IPs return <code>{ message: "..." }</code>
+      instead of geolocation data.
+    </dd>
+    <dt class="optional">ipgeo_credits <span class="property-type">number</span></dt>
+    <dd>Total credits consumed.</dd>
+  </dl>
+
+  <h3>References</h3>
+  <ul>
+    <li>
+      <a href="https://ipgeolocation.io/documentation/ip-location-api.html" target="_blank">
+        Bulk IP Lookup documentation
+      </a>
+    </li>
+  </ul>
+</script>

package/nodes/ipgeo-bulk.js

@@ -0,0 +1,146 @@
+/**
+ * ipgeo-bulk.js
+ *
+ * Node-RED node: "ipgeo bulk"
+ *
+ * Performs bulk geolocation lookups via the IPGeolocation.io
+ * /v3/ipgeo-bulk endpoint (POST).
+ *
+ * Input
+ * ─────
+ *  msg.payload  — Array of IP strings / domains  (required)
+ *               OR a comma-separated string which is auto-split
+ *
+ * Configuration
+ * ─────────────
+ *  • Same include/fields/excludes/lang options as the single lookup node
+ *  • Max 50,000 IPs per request (per API limits)
+ *  • Each result corresponds to one IP in the input array
+ *    (invalid IPs return { message: '...' } objects per API spec)
+ *
+ * Output
+ * ──────
+ *  msg.payload  — Array of geolocation result objects
+ *  msg.ipgeo_credits  — Credits consumed (from response header)
+ */
+
+'use strict';
+
+const { request, IPGeoError } = require('./lib/api-client');
+const {
+  setStatus,
+  setOutputProperty,
+  handleNodeError,
+  buildCommonParams,
+} = require('./lib/node-helpers');
+
+const MAX_IPS = 50_000;
+
+module.exports = function (RED) {
+
+  function IPGeoBulkNode(config) {
+    RED.nodes.createNode(this, config);
+
+    const configNode = RED.nodes.getNode(config.server);
+
+    this.name       = config.name;
+    this.include    = config.include   || '';
+    this.fields     = config.fields    || '';
+    this.excludes   = config.excludes  || '';
+    this.lang       = config.lang      || 'en';
+    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); };
+
+      // ── API key ──────────────────────────────────────────────────────────
+      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;
+      }
+
+      // ── Extract IP list from msg.payload ─────────────────────────────────
+      let ips = msg.payload;
+
+      // Support comma-separated string
+      if (typeof ips === 'string') {
+        ips = ips.split(',').map(s => s.trim()).filter(Boolean);
+      }
+
+      if (!Array.isArray(ips) || ips.length === 0) {
+        const err = new IPGeoError(
+          'msg.payload must be a non-empty array of IP addresses or a comma-separated string',
+          'INVALID_INPUT'
+        );
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      if (ips.length > MAX_IPS) {
+        const err = new IPGeoError(
+          `Bulk lookup limit is ${MAX_IPS} IPs per request; received ${ips.length}`,
+          'TOO_MANY_IPS'
+        );
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      // ── Build params ──────────────────────────────────────────────────────
+      const params = buildCommonParams(apiKey, {
+        lang:     node.lang,
+        fields:   node.fields,
+        excludes: node.excludes,
+      });
+
+      const includeList = (msg.ipgeo_include || node.include || '').trim();
+      if (includeList) params.include = includeList;
+
+      setStatus(node, 'WORKING');
+
+      try {
+        const { data, credits } = await request({
+          method: 'POST',
+          path:   '/ipgeo-bulk',
+          params,
+          data:   { ips },
+          // Bulk requests can be large — give them extra time
+          timeout: 30_000,
+        });
+
+        setStatus(node, 'OK', `${ips.length} IPs`);
+
+        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-bulk', IPGeoBulkNode);
+
+};