node-red-contrib-ipgeolocation 1.0.0

package/nodes/ipgeo-security.html

@@ -0,0 +1,214 @@
+<!-- ============================================================
+     ipgeo-security.html
+     Single-IP threat/security lookup node — editor template + help
+     ============================================================ -->
+
+<script type="text/javascript">
+    (function () {
+        'use strict';
+
+        RED.nodes.registerType('ipgeo-security', {
+            category: 'IPGeolocation',
+            color: '#d08a5d',
+            icon: 'font-awesome/fa-shield',
+            paletteLabel: 'ipgeo security',
+
+            defaults: {
+                name: { value: '' },
+                server: { value: '', type: 'ipgeo-config', required: true },
+                ipType: { value: 'str' },
+                ipValue: { value: '' },
+                fields: { value: '' },
+                excludes: { value: '' },
+                outputProp: { value: 'payload' },
+                outputType: { value: 'msg' },
+                twoOutputs: { value: true },
+            },
+
+            inputs: 1,
+            outputs: 2,   // [success, error]
+
+            outputLabels: function (idx) {
+                return idx === 0 ? 'success' : 'error';
+            },
+
+            label: function () {
+                return this.name || 'ipgeo security';
+            },
+
+            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'],
+                });
+
+                // ── Output property typed input ────────────────────────────────────
+                $('#node-input-outputProp').typedInput({
+                    default: 'msg',
+                    typeField: '#node-input-outputType',
+                    types: ['msg', 'flow', 'global'],
+                });
+
+                // ── Two outputs checkbox ───────────────────────────────────────────
+                $('#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-security">
+          <!-- 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 security" style="width:70%" />
+</div>
+
+<!-- Config node (shared with ipgeo-lookup) -->
+<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 Address</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 or IPv6 only — <strong>domain names are not supported</strong> by this
+        endpoint and will return an error. Leave empty to auto-detect the
+        caller's IP. You can also point to a msg/flow/global property.
+    </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. security.threat_score,security.is_vpn"
+        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. security.is_tor,security.is_cloud_provider"
+        style="width:70%" />
+</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-security">
+          <p>
+            Returns threat/risk flags for a single IPv4 or IPv6 address via
+            <strong>IPGeolocation.io v3 Security API</strong>: VPN, proxy,
+            residential proxy, Tor, relay, bot, spam, known-attacker, and
+            cloud-provider signals, with confidence scores and provider names
+            where available.
+          </p>
+        
+          <h3>Inputs</h3>
+          <dl class="message-properties">
+            <dt>payload <span class="property-type">any</span></dt>
+            <dd>Passed through unchanged.</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>
+                  <code>{ ip, security }</code> where <code>security</code> contains
+                  <code>threat_score</code>, <code>is_tor</code>, <code>is_proxy</code>,
+                  <code>proxy_provider_names</code>, <code>proxy_confidence_score</code>,
+                  <code>proxy_last_seen</code>, <code>is_residential_proxy</code>,
+                  <code>is_vpn</code>, <code>vpn_provider_names</code>,
+                  <code>vpn_confidence_score</code>, <code>vpn_last_seen</code>,
+                  <code>is_relay</code>, <code>relay_provider_name</code>,
+                  <code>is_anonymous</code>, <code>is_known_attacker</code>,
+                  <code>is_bot</code>, <code>is_spam</code>,
+                  <code>is_cloud_provider</code>, <code>cloud_provider_name</code>.
+                </dd>
+                <dt class="optional">ipgeo_credits <span class="property-type">number</span></dt>
+                <dd>Credits consumed by this request (flat 2 credits per valid IP).</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 Address</em> empty to look up the caller's IP address.</li>
+            <li>
+              <strong>Domain names are not accepted</strong> — only IPv4/IPv6
+              addresses. Passing a domain returns a 401 from the API.
+            </li>
+            <li>Every successful lookup costs a flat <strong>2 credits</strong>, regardless of fields/excludes used.</li>
+            <li>
+              <em>Fields</em> restricts the response to named fields
+              (e.g. <code>security.threat_score</code>).
+            </li>
+            <li>
+              <em>Excludes</em> removes fields from the <code>security</code> object
+              (e.g. <code>security.is_tor,security.is_cloud_provider</code>). The
+              top-level <code>ip</code> field is always present and cannot be excluded.
+            </li>
+            <li>
+              Bogon/private/malformed IPs are rejected with HTTP 423 and are not billed.
+            </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-security-api.html" target="_blank">
+                IP Security API documentation
+              </a>
+            </li>
+          </ul>
+        </script>

package/nodes/ipgeo-security.js

@@ -0,0 +1,150 @@
+/**
+ * ipgeo-security.js
+ *
+ * Node-RED node: "ipgeo security"
+ *
+ * Performs a single-IP threat/security lookup via the IPGeolocation.io
+ * /v3/security endpoint (GET).
+ *
+ * Features
+ * ─────────
+ *  • IPv4 or IPv6 input, or empty (caller IP auto-detect)
+ *    NOTE: unlike /v3/ipgeo, the security endpoint does NOT accept domain
+ *    names — passing one returns a 401 from the API.
+ *  • `fields` and `excludes` for bandwidth optimisation (dot-notation,
+ *    e.g. security.threat_score / security.is_tor)
+ *  • 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 (flat 2 credits/lookup)
+ *  • Full retry + exponential backoff via shared api-client
+ *
+ * Shares the same `ipgeo-config` config node (API key) as ipgeo-lookup.
+ */
+
+'use strict';
+
+const { request, IPGeoError } = require('./lib/api-client');
+const {
+  setStatus,
+  resolveValue,
+  setOutputProperty,
+  handleNodeError,
+  buildCommonParams,
+} = require('./lib/node-helpers');
+
+module.exports = function (RED) {
+
+  function IPGeoSecurityNode(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' | 'flow' | 'global'
+    this.ipValue     = config.ipValue     || '';          // value or msg/flow/global prop path
+    this.fields      = config.fields      || '';
+    this.excludes    = config.excludes    || '';
+    this.outputProp  = config.outputProp  || 'payload';   // output property
+    this.outputType  = config.outputType  || 'msg';
+    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/flow/global 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 ────────────────────────────────────────
+      // Security endpoint has no `lang` or `include` params — just
+      // apiKey / ip / fields / excludes.
+      const params = buildCommonParams(apiKey, {
+        fields:   node.fields,
+        excludes: node.excludes,
+      });
+
+      if (ip) params.ip = ip;
+
+      // ── Set working status ────────────────────────────────────────────
+      setStatus(node, 'WORKING');
+
+      // ── API call ──────────────────────────────────────────────────────
+      try {
+        const { data, credits } = await request({
+          method: 'GET',
+          path:   '/security',
+          params,
+        });
+
+        // ── Success ────────────────────────────────────────────────────
+        const score = data.security?.threat_score;
+        setStatus(node, 'OK',
+          score !== undefined ? `threat ${score}` : (data.ip || 'ok'));
+
+        // Write result to configured output property
+        setOutputProperty(RED, node, msg,
+          { value: node.outputProp, type: node.outputType }, data);
+
+        // Expose credits consumed (informational) — flat 2 credits/lookup
+        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-security', IPGeoSecurityNode);
+
+};

package/nodes/ipgeo-timezone.html

@@ -0,0 +1,201 @@
+<!-- ============================================================
+     ipgeo-timezone.html
+     Timezone lookup node with 7-mode editor
+     ============================================================ -->
+
+<script type="text/javascript">
+(function () {
+  'use strict';
+
+  RED.nodes.registerType('ipgeo-timezone', {
+    category:    'IPGeolocation',
+    color:       '#5da0d0',
+    icon:        'font-awesome/fa-clock-o',
+    paletteLabel:'ipgeo timezone',
+
+    defaults: {
+      name:       { value: '' },
+      server:     { value: '', type: 'ipgeo-config', required: true },
+      mode:       { value: 'tz' },
+      inputType:  { value: 'str' },
+      inputValue: { value: '' },
+      latType:    { value: 'str' },
+      latValue:   { value: '' },
+      lngType:    { value: 'str' },
+      lngValue:   { value: '' },
+      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 timezone (' + (this.mode || 'tz') + ')';
+    },
+
+    oneditprepare: function () {
+      const node = this;
+
+      // ── Mode selector — show/hide input rows ───────────────────────────
+      function updateModeRows() {
+        const mode = $('#node-input-mode').val();
+        $('#ipgeo-tz-single-row').toggle(mode !== 'coords');
+        $('#ipgeo-tz-coords-rows').toggle(mode === 'coords');
+
+        // Update placeholder text based on mode
+        const placeholders = {
+          tz:       'e.g. America/New_York',
+          ip:       'e.g. 8.8.8.8',
+          location: 'e.g. New York, USA',
+          iata:     'e.g. JFK',
+          icao:     'e.g. KJFK',
+          unlocode: 'e.g. USNYC',
+        };
+        const p = placeholders[mode] || '';
+        $('#node-input-inputValue').attr('placeholder', p);
+      }
+
+      $('#node-input-mode').val(node.mode || 'tz').on('change', updateModeRows);
+
+      // ── Single-value typed input ───────────────────────────────────────
+      $('#node-input-inputValue').typedInput({
+        default:   'str',
+        typeField: '#node-input-inputType',
+        types:     ['msg', 'flow', 'global', 'str'],
+      });
+
+      // ── Coords typed inputs ────────────────────────────────────────────
+      $('#node-input-latValue').typedInput({
+        default:   'str',
+        typeField: '#node-input-latType',
+        types:     ['msg', 'flow', 'global', 'str', 'num'],
+      });
+      $('#node-input-lngValue').typedInput({
+        default:   'str',
+        typeField: '#node-input-lngType',
+        types:     ['msg', 'flow', 'global', 'str', 'num'],
+      });
+
+      // ── Output property ────────────────────────────────────────────────
+      $('#node-input-outputProp').typedInput({
+        default:   'msg',
+        typeField: '#node-input-outputType',
+        types:     ['msg', 'flow', 'global'],
+      });
+
+      $('#node-input-twoOutputs').prop('checked', node.twoOutputs !== false);
+
+      updateModeRows();
+    },
+
+    oneditsave: function () {
+      this.twoOutputs = $('#node-input-twoOutputs').prop('checked');
+    },
+  });
+}());
+</script>
+
+<!-- ── Edit template ── -->
+<script type="text/html" data-template-name="ipgeo-timezone">
+  <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 timezone" 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/>
+
+  <!-- Lookup mode selector -->
+  <div class="form-row">
+    <label for="node-input-mode"><i class="fa fa-search"></i>&nbsp;Lookup by</label>
+    <select id="node-input-mode" style="width:70%">
+      <option value="tz">Timezone Name (tz)</option>
+      <option value="ip">IP Address (ip)</option>
+      <option value="location">Address / City (location)</option>
+      <option value="coords">Coordinates (lat + long)</option>
+      <option value="iata">IATA Airport Code</option>
+      <option value="icao">ICAO Airport Code</option>
+      <option value="unlocode">UN/LOCODE</option>
+    </select>
+  </div>
+
+  <!-- Single value row (all modes except coords) -->
+  <div id="ipgeo-tz-single-row" class="form-row">
+    <label for="node-input-inputValue"><i class="fa fa-pencil"></i>&nbsp;Value</label>
+    <input type="text" id="node-input-inputValue" style="width:70%"/>
+    <input type="hidden" id="node-input-inputType"/>
+  </div>
+
+  <!-- Coordinates rows -->
+  <div id="ipgeo-tz-coords-rows">
+    <div class="form-row">
+      <label for="node-input-latValue"><i class="fa fa-arrows-v"></i>&nbsp;Latitude</label>
+      <input type="text" id="node-input-latValue" placeholder="e.g. 40.7128" style="width:70%"/>
+      <input type="hidden" id="node-input-latType"/>
+    </div>
+    <div class="form-row">
+      <label for="node-input-lngValue"><i class="fa fa-arrows-h"></i>&nbsp;Longitude</label>
+      <input type="text" id="node-input-lngValue" placeholder="e.g. -74.0060" style="width:70%"/>
+      <input type="hidden" id="node-input-lngType"/>
+    </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-timezone">
+  <p>
+    Retrieves current date, time, and timezone information from the
+    <strong>IPGeolocation.io Timezone API</strong>.
+  </p>
+
+  <h3>Lookup Modes</h3>
+  <ul>
+    <li><strong>Timezone Name</strong> — IANA name, e.g. <code>America/New_York</code></li>
+    <li><strong>IP Address</strong> — any IPv4 or IPv6 address</li>
+    <li><strong>Address / City</strong> — free text, e.g. <code>Paris, France</code></li>
+    <li><strong>Coordinates</strong> — decimal lat &amp; long</li>
+    <li><strong>IATA</strong> — airport code, e.g. <code>LHR</code></li>
+    <li><strong>ICAO</strong> — airport code, e.g. <code>EGLL</code></li>
+    <li><strong>UN/LOCODE</strong> — e.g. <code>GBLON</code></li>
+  </ul>
+
+  <h3>Output</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">object</span></dt>
+    <dd>
+      Contains a <code>time_zone</code> object with fields:
+      <code>name</code>, <code>offset</code>, <code>date_time</code>,
+      <code>current_time</code>, <code>is_dst</code>, <code>dst_start</code>,
+      <code>dst_end</code>, and more.
+    </dd>
+  </dl>
+
+  <h3>References</h3>
+  <ul>
+    <li>
+      <a href="https://ipgeolocation.io/documentation/timezone-api.html" target="_blank">
+        Timezone API documentation
+      </a>
+    </li>
+  </ul>
+</script>