node-red-contrib-ipgeolocation 1.0.0

package/nodes/ipgeo-asn.js

@@ -0,0 +1,197 @@
+/**
+ * ipgeo-asn.js
+ *
+ * Node-RED node: "ipgeo asn"
+ *
+ * Performs an ASN (Autonomous System Number) lookup via the
+ * IPGeolocation.io /v3/asn endpoint (GET).
+ *
+ * Unlike the other ipgeo-* nodes, this endpoint accepts EITHER an `ip`
+ * OR an `asn` query parameter (mutually exclusive) — or neither, in
+ * which case the API auto-detects the caller's IP and returns ASN data
+ * for it.
+ *
+ * Features
+ * ─────────
+ *  • Query mode: auto-detect caller IP | lookup by IP | lookup by ASN
+ *  • Configurable `include` modules: peers, downstreams, upstreams,
+ *    routes, whois_response  (comma-separated)
+ *  • `fields` and `excludes` for bandwidth optimisation
+ *  • IP/ASN value can be sourced from node config OR msg/flow/global property
+ *  • Two outputs: [success, error] — error output is optional
+ *  • Exposes credits consumed on msg.ipgeo_credits (flat 1 credit/lookup)
+ *  • Full retry + exponential backoff via shared api-client
+ *
+ * Shares the same `ipgeo-config` config node (API key) as the other
+ * ipgeo-* nodes.
+ */
+
+"use strict";
+
+const { request, IPGeoError } = require("./lib/api-client");
+const {
+  setStatus,
+  resolveValue,
+  setOutputProperty,
+  handleNodeError,
+  buildCommonParams,
+} = require("./lib/node-helpers");
+
+module.exports = function (RED) {
+  function IPGeoASNNode(config) {
+    RED.nodes.createNode(this, config);
+
+    // ── Config node (API key) ─────────────────────────────────────────────
+    const configNode = RED.nodes.getNode(config.server);
+
+    // ── Node configuration ────────────────────────────────────────────────
+    this.name = config.name;
+    this.queryType = config.queryType || "auto"; // 'auto' | 'ip' | 'asn'
+    this.ipType = config.ipType || "str"; // 'str' | 'msg' | 'flow' | 'global'
+    this.ipValue = config.ipValue || "";
+    this.asnType = config.asnType || "str"; // 'str' | 'msg' | 'flow' | 'global'
+    this.asnValue = config.asnValue || "";
+    this.include = config.include || ""; // comma-sep list of modules
+    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 / asn depending on the selected query mode ─────────
+      // Only one of ip/asn is ever sent. If queryType is 'auto', neither
+      // is sent and the API auto-detects the caller's IP.
+      let ip = "";
+      let asn = "";
+
+      if (node.queryType === "ip") {
+        if (
+          node.ipType === "msg" ||
+          node.ipType === "flow" ||
+          node.ipType === "global"
+        ) {
+          ip =
+            resolveValue(RED, node, msg, {
+              value: node.ipValue,
+              type: node.ipType,
+            }) || "";
+        } else {
+          ip = (node.ipValue || "").trim();
+        }
+        ip = String(ip).trim();
+      } else if (node.queryType === "asn") {
+        if (
+          node.asnType === "msg" ||
+          node.asnType === "flow" ||
+          node.asnType === "global"
+        ) {
+          asn =
+            resolveValue(RED, node, msg, {
+              value: node.asnValue,
+              type: node.asnType,
+            }) || "";
+        } else {
+          asn = (node.asnValue || "").trim();
+        }
+        // Accept "AS24940" or "24940" — API expects the bare number.
+        asn = String(asn).trim().replace(/^as/i, "").trim();
+      }
+      // 'auto' — leave both ip and asn unset; caller IP is used.
+
+      // ── Build query parameters ────────────────────────────────────────
+      // ASN endpoint has no `lang` param — apiKey / ip|asn / include /
+      // fields / excludes.
+      const params = buildCommonParams(apiKey, {
+        fields: node.fields,
+        excludes: node.excludes,
+      });
+
+      if (ip) params.ip = ip;
+      if (asn) params.asn = asn;
+
+      // Build include list (may come from node config or msg override)
+      const includeList = (msg.ipgeo_include || node.include || "").trim();
+      if (includeList) params.include = includeList;
+
+      // ── Set working status ────────────────────────────────────────────
+      setStatus(node, "WORKING");
+
+      // ── API call ──────────────────────────────────────────────────────
+      try {
+        const { data, credits } = await request({
+          method: "GET",
+          path: "/asn",
+          params,
+        });
+
+        // ── Success ────────────────────────────────────────────────────
+        setStatus(
+          node,
+          "OK",
+          data.asn?.as_number || data.asn?.organization || 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 1 credit/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-asn", IPGeoASNNode);
+};

package/nodes/ipgeo-astronomy.html

@@ -0,0 +1,242 @@
+<!-- ============================================================
+     ipgeo-astronomy.html
+     Astronomy (sun & moon) node
+     ============================================================ -->
+
+<script type="text/javascript">
+(function () {
+  'use strict';
+
+  RED.nodes.registerType('ipgeo-astronomy', {
+    category:    'IPGeolocation',
+    color:       '#5da0d0',
+    icon:        'font-awesome/fa-sun-o',
+    paletteLabel:'ipgeo astronomy',
+
+    defaults: {
+      name:           { value: '' },
+      server:         { value: '', type: 'ipgeo-config', required: true },
+      mode:           { value: 'coords' },
+      inputType:      { value: 'str' },
+      inputValue:     { value: '' },
+      latType:        { value: 'str' },
+      latValue:       { value: '' },
+      lngType:        { value: 'str' },
+      lngValue:       { value: '' },
+      dateType:       { value: 'str' },
+      dateValue:      { value: '' },
+      tzType:         { value: 'str' },
+      tzValue:        { value: '' },
+      elevationType:  { value: 'str' },
+      elevationValue: { value: '' },
+      langType:       { value: 'str' },
+      langValue:      { 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 astronomy'; },
+
+    oneditprepare: function () {
+      const node = this;
+
+      const typedOpts = { types: ['msg', 'flow', 'global', 'str'] };
+
+      $('#node-input-inputValue').typedInput({ ...typedOpts, default: 'str', typeField: '#node-input-inputType' });
+      $('#node-input-latValue').typedInput({ ...typedOpts, default: 'str', typeField: '#node-input-latType' });
+      $('#node-input-lngValue').typedInput({ ...typedOpts, default: 'str', typeField: '#node-input-lngType' });
+      $('#node-input-dateValue').typedInput({ ...typedOpts, default: 'str', typeField: '#node-input-dateType' });
+      $('#node-input-tzValue').typedInput({ ...typedOpts, default: 'str', typeField: '#node-input-tzType' });
+      $('#node-input-elevationValue').typedInput({ ...typedOpts, default: 'str', typeField: '#node-input-elevationType' });
+      $('#node-input-langValue').typedInput({ ...typedOpts, default: 'str', typeField: '#node-input-langType' });
+
+      $('#node-input-outputProp').typedInput({
+        default:   'msg',
+        typeField: '#node-input-outputType',
+        types:     ['msg', 'flow', 'global'],
+      });
+
+      $('#node-input-twoOutputs').prop('checked', node.twoOutputs !== false);
+
+      // Show only the inputs relevant to the selected mode.
+      const placeholders = {
+        location: 'e.g. New York, USA',
+        ip:       'e.g. 8.8.8.8',
+      };
+      function refreshMode() {
+        const mode = $('#node-input-mode').val();
+        $('.ipgeo-coords-row').toggle(mode === 'coords');
+        $('.ipgeo-single-row').toggle(mode === 'location' || mode === 'ip');
+        if (placeholders[mode]) {
+          $('#node-input-inputValue').attr('placeholder', placeholders[mode]);
+        }
+      }
+      $('#node-input-mode').on('change', refreshMode);
+      refreshMode();
+    },
+
+    oneditsave: function () {
+      this.twoOutputs = $('#node-input-twoOutputs').prop('checked');
+    },
+  });
+}());
+</script>
+
+<!-- ── Edit template ── -->
+<script type="text/html" data-template-name="ipgeo-astronomy">
+  <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 astronomy" 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 -->
+  <div class="form-row">
+    <label for="node-input-mode"><i class="fa fa-crosshairs"></i>&nbsp;Look up by</label>
+    <select id="node-input-mode" style="width:70%">
+      <option value="coords">Coordinates (lat &amp; long)</option>
+      <option value="location">Location / city address</option>
+      <option value="ip">IP address</option>
+      <option value="auto">Caller IP (no input)</option>
+    </select>
+  </div>
+
+  <!-- Coordinates -->
+  <div class="form-row ipgeo-coords-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 ipgeo-coords-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>
+
+  <!-- Single value (location / ip) -->
+  <div class="form-row ipgeo-single-row">
+    <label for="node-input-inputValue"><i class="fa fa-map-marker"></i>&nbsp;Value</label>
+    <input type="text" id="node-input-inputValue" style="width:70%"/>
+    <input type="hidden" id="node-input-inputType"/>
+  </div>
+
+  <hr/>
+
+  <!-- Optional date -->
+  <div class="form-row">
+    <label for="node-input-dateValue"><i class="fa fa-calendar"></i>&nbsp;Date</label>
+    <input type="text" id="node-input-dateValue" placeholder="YYYY-MM-DD (leave empty for today)" style="width:70%"/>
+    <input type="hidden" id="node-input-dateType"/>
+  </div>
+
+  <!-- Optional timezone -->
+  <div class="form-row">
+    <label for="node-input-tzValue"><i class="fa fa-clock-o"></i>&nbsp;Time zone</label>
+    <input type="text" id="node-input-tzValue" placeholder="e.g. America/New_York (optional)" style="width:70%"/>
+    <input type="hidden" id="node-input-tzType"/>
+    <div style="margin-top:4px;font-size:0.82em;color:#888;">
+      Converts all event times into this IANA time zone. Leave empty to use
+      the location's local time.
+    </div>
+  </div>
+
+  <!-- Optional elevation -->
+  <div class="form-row">
+    <label for="node-input-elevationValue"><i class="fa fa-mountain"></i>&nbsp;Elevation</label>
+    <input type="text" id="node-input-elevationValue" placeholder="metres, 0 to 10000 (optional)" style="width:70%"/>
+    <input type="hidden" id="node-input-elevationType"/>
+  </div>
+
+  <!-- Optional language -->
+  <div class="form-row">
+    <label for="node-input-langValue"><i class="fa fa-language"></i>&nbsp;Language</label>
+    <input type="text" id="node-input-langValue" placeholder="e.g. en, de, fr (optional, paid plans)" style="width:70%"/>
+    <input type="hidden" id="node-input-langType"/>
+  </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-astronomy">
+  <p>
+    Retrieves sun and moon rise/set times, twilight phases, and positional
+    data via the <strong>IPGeolocation.io Astronomy API</strong>.
+  </p>
+
+  <h3>Look up by</h3>
+  <p>The location can be derived in one of four ways:</p>
+  <ul>
+    <li><b>Coordinates</b>: latitude + longitude.</li>
+    <li><b>Location / city address</b>: e.g. <code>New York, USA</code>.</li>
+    <li><b>IP address</b>: any IPv4 or IPv6 address.</li>
+    <li><b>Caller IP</b>: send no location and let the API use the caller's IP.</li>
+  </ul>
+  <p>
+    If more than one is supplied, the API prefers coordinates, then location,
+    then IP.
+  </p>
+
+  <h3>Inputs</h3>
+  <dl class="message-properties">
+    <dt class="optional">Latitude / Longitude <span class="property-type">number | string</span></dt>
+    <dd>Decimal degrees. Required in <i>Coordinates</i> mode.</dd>
+    <dt class="optional">Value <span class="property-type">string</span></dt>
+    <dd>The address or IP. Required in <i>Location</i> or <i>IP</i> mode.</dd>
+    <dt class="optional">Date <span class="property-type">string</span></dt>
+    <dd><code>YYYY-MM-DD</code>. Defaults to today at the location.</dd>
+    <dt class="optional">Time zone <span class="property-type">string</span></dt>
+    <dd>IANA name; converts event times into this zone.</dd>
+    <dt class="optional">Elevation <span class="property-type">number | string</span></dt>
+    <dd>Metres above sea level, 0 to 10000. Defaults to 0.</dd>
+    <dt class="optional">Language <span class="property-type">string</span></dt>
+    <dd>Language for the <code>location</code> object (paid plans).</dd>
+  </dl>
+
+  <h3>Output</h3>
+  <dl class="message-properties">
+    <dt>payload <span class="property-type">object</span></dt>
+    <dd>
+      Object with a <code>location</code> block and an <code>astronomy</code>
+      block. The latter holds <code>sunrise</code>, <code>sunset</code>,
+      <code>solar_noon</code>, <code>day_length</code>, <code>sun_altitude</code>,
+      <code>sun_azimuth</code>, <code>sun_distance</code>, <code>moonrise</code>,
+      <code>moonset</code>, <code>moon_phase</code>,
+      <code>moon_illumination_percentage</code>, plus <code>morning</code> and
+      <code>evening</code> twilight phases. When looked up by IP, an
+      <code>ip</code> field is also returned.
+    </dd>
+    <dt>ipgeo_credits <span class="property-type">number</span></dt>
+    <dd>Credits charged for the request (1 per astronomy lookup).</dd>
+  </dl>
+
+  <h3>References</h3>
+  <ul>
+    <li>
+      <a href="https://ipgeolocation.io/documentation/astronomy-api.html" target="_blank">
+        Astronomy API documentation
+      </a>
+    </li>
+  </ul>
+</script>

package/nodes/ipgeo-astronomy.js

@@ -0,0 +1,195 @@
+/**
+ * ipgeo-astronomy.js
+ *
+ * Node-RED node: "ipgeo astronomy"
+ *
+ * Fetches sun & moon rise/set times and positional data via the
+ * IPGeolocation.io /v3/astronomy endpoint.
+ *
+ * Input modes (the API derives the location from one of these)
+ * ────────────────────────────────────────────────────────────
+ *  auto      — send no location parameter; the API uses the caller's IP
+ *  coords    — latitude + longitude (lat / long)
+ *  location  — a free-text address, preferably a city (location)
+ *  ip        — an IPv4 or IPv6 address (ip)
+ *
+ * Per the API: if several location parameters are present, lat/long win,
+ * then location, then ip; with none, the caller's IP is used.
+ *
+ * Optional inputs (any mode)
+ * ──────────────────────────
+ *  date       — "YYYY-MM-DD"; defaults to today at the location
+ *  time_zone  — IANA timezone name; event times are converted to it
+ *  elevation  — metres above sea level (0 to 10000); default 0
+ *  lang       — response language for the location object (paid plans)
+ *
+ * Every value can be static (node config) or sourced dynamically from
+ * msg / flow / global context.
+ */
+
+'use strict';
+
+const { request, IPGeoError } = require('./lib/api-client');
+const {
+  setStatus,
+  resolveValue,
+  setOutputProperty,
+  handleNodeError,
+} = require('./lib/node-helpers');
+
+// Editor mode -> single-value query parameter name. 'coords' is handled
+// separately because it maps to two parameters (lat + long); 'auto' sends
+// no location parameter at all.
+const MODE_PARAM = {
+  auto:     null,
+  coords:   null,
+  location: 'location',
+  ip:       'ip',
+};
+
+module.exports = function (RED) {
+
+  function IPGeoAstronomyNode(config) {
+    RED.nodes.createNode(this, config);
+
+    const configNode = RED.nodes.getNode(config.server);
+
+    this.name        = config.name;
+    this.mode        = config.mode        || 'coords'; // auto | coords | location | ip
+    this.inputType   = config.inputType   || 'str';    // for location / ip modes
+    this.inputValue  = config.inputValue  || '';
+    this.latType     = config.latType     || 'str';
+    this.latValue    = config.latValue    || '';
+    this.lngType     = config.lngType     || 'str';
+    this.lngValue    = config.lngValue    || '';
+    this.dateType    = config.dateType    || 'str';
+    this.dateValue   = config.dateValue   || '';   // empty = API default (today)
+    this.tzType      = config.tzType      || 'str';
+    this.tzValue     = config.tzValue     || '';   // empty = API determines tz
+    this.elevationType  = config.elevationType  || 'str';
+    this.elevationValue = config.elevationValue || ''; // empty = API default (0)
+    this.langType    = config.langType    || 'str';
+    this.langValue   = config.langValue   || '';   // empty = API default (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); };
+
+      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;
+      }
+
+      const params = { apiKey };
+      const mode   = node.mode;
+
+      try {
+        if (mode === 'coords') {
+          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 || String(lat).trim() === '') {
+            throw new IPGeoError('Latitude is required for coords mode', 'INVALID_INPUT');
+          }
+          if (lng === undefined || lng === null || String(lng).trim() === '') {
+            throw new IPGeoError('Longitude is required for coords mode', 'INVALID_INPUT');
+          }
+
+          params.lat  = String(lat).trim();
+          params.long = String(lng).trim();
+
+        } else if (mode === 'location' || mode === 'ip') {
+          const paramKey  = MODE_PARAM[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();
+
+        } else if (mode !== 'auto') {
+          throw new IPGeoError(`Unknown lookup mode: ${mode}`, 'INVALID_MODE');
+        }
+        // 'auto' sends no location parameter; the API falls back to the caller IP.
+      } catch (err) {
+        handleNodeError(node, err, msg, done, send, node.twoOutputs);
+        return;
+      }
+
+      // ── Optional parameters (all modes) ───────────────────────────────
+      const date = resolveValue(RED, node, msg,
+        { value: node.dateValue, type: node.dateType });
+      if (date && String(date).trim()) {
+        params.date = String(date).trim();
+      }
+
+      const tz = resolveValue(RED, node, msg,
+        { value: node.tzValue, type: node.tzType });
+      if (tz && String(tz).trim()) {
+        params.time_zone = String(tz).trim();
+      }
+
+      const elevation = resolveValue(RED, node, msg,
+        { value: node.elevationValue, type: node.elevationType });
+      if (elevation !== undefined && elevation !== null && String(elevation).trim() !== '') {
+        params.elevation = String(elevation).trim();
+      }
+
+      const lang = resolveValue(RED, node, msg,
+        { value: node.langValue, type: node.langType });
+      if (lang && String(lang).trim()) {
+        params.lang = String(lang).trim();
+      }
+
+      setStatus(node, 'WORKING');
+
+      try {
+        const { data, credits } = await request({
+          method: 'GET',
+          path:   '/astronomy',
+          params,
+        });
+
+        // The response nests the data under an `astronomy` object.
+        const sunrise = data && data.astronomy ? data.astronomy.sunrise : undefined;
+        setStatus(node, 'OK', sunrise ? `sunrise ${sunrise}` : 'ok');
+
+        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-astronomy', IPGeoAstronomyNode);
+
+};