node-red-contrib-ipgeolocation 1.0.0

package/index.js

@@ -0,0 +1,22 @@
+/**
+ * node-red-contrib-ipgeolocation
+ * Entry point — registers all nodes with the Node-RED runtime.
+ *
+ * Note: Node-RED loads nodes from the `node-red.nodes` map in package.json,
+ * so this file is primarily a convenience for `require()`-ing the package
+ * directly (e.g. in tests). It must stay in sync with package.json.
+ */
+'use strict';
+
+module.exports = function (RED) {
+  require('./nodes/ipgeo-config')(RED);
+  require('./nodes/ipgeo-lookup')(RED);
+  require('./nodes/ipgeo-bulk')(RED);
+  require('./nodes/ipgeo-security')(RED);
+  require('./nodes/ipgeo-bulk-security')(RED);
+  require('./nodes/ipgeo-abuse')(RED);
+  require('./nodes/ipgeo-asn')(RED);
+  require('./nodes/ipgeo-timezone')(RED);
+  require('./nodes/ipgeo-astronomy')(RED);
+  require('./nodes/ipgeo-useragent')(RED);
+};

package/nodes/ipgeo-abuse.html

@@ -0,0 +1,203 @@
+<!-- ============================================================
+     ipgeo-abuse.html
+     Single-IP abuse contact lookup node — editor template + help
+     ============================================================ -->
+
+     <script type="text/javascript">
+        (function () {
+          'use strict';
+        
+          RED.nodes.registerType('ipgeo-abuse', {
+            category:    'IPGeolocation',
+            color:       '#c2554f',
+            icon:        'font-awesome/fa-envelope',
+            paletteLabel:'ipgeo abuse',
+        
+            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 abuse';
+            },
+        
+            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-abuse">
+          <!-- 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 abuse" style="width:70%"/>
+          </div>
+        
+          <!-- Config node (shared with ipgeo-lookup / ipgeo-security) -->
+          <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. Leave empty to auto-detect the caller's IP. You
+              can also point this 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. abuse.emails,abuse.phone_numbers" 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. abuse.address" 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-abuse">
+          <p>
+            Looks up abuse-reporting contact details for a single IPv4 or IPv6
+            address via <strong>IPGeolocation.io v3 Abuse Contact API</strong>:
+            responsible organization, abuse-handling role, contact emails, phone
+            numbers, and registered address.
+          </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, abuse }</code> where <code>abuse</code> contains
+                  <code>route</code>, <code>country</code>, <code>name</code>,
+                  <code>organization</code>, <code>kind</code>
+                  (<code>group</code> | <code>individual</code>),
+                  <code>address</code>, <code>emails</code> (array),
+                  and <code>phone_numbers</code> (array).
+                </dd>
+                <dt class="optional">ipgeo_credits <span class="property-type">number</span></dt>
+                <dd>Credits consumed by this request (flat 1 credit per lookup).</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>Every successful lookup costs a flat <strong>1 credit</strong>.</li>
+            <li>
+              <em>Fields</em> restricts the response to named fields
+              (e.g. <code>abuse.emails</code>).
+            </li>
+            <li>
+              <em>Excludes</em> removes fields from the <code>abuse</code> object
+              (e.g. <code>abuse.address</code>). The top-level <code>ip</code>
+              field cannot be excluded.
+            </li>
+            <li>Any field may legitimately come back empty if the registry has no data for it.</li>
+            <li>
+              Bogon/private 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-abuse-contact-api.html" target="_blank">
+                IP Abuse Contact API documentation
+              </a>
+            </li>
+          </ul>
+        </script>

package/nodes/ipgeo-abuse.js

@@ -0,0 +1,148 @@
+/**
+ * ipgeo-abuse.js
+ *
+ * Node-RED node: "ipgeo abuse"
+ *
+ * Performs a single-IP abuse contact lookup via the IPGeolocation.io
+ * /v3/abuse endpoint (GET).
+ *
+ * Features
+ * ─────────
+ *  • IPv4 or IPv6 input, or empty (caller IP auto-detect)
+ *  • `fields` and `excludes` for bandwidth optimisation (dot-notation,
+ *    e.g. abuse.emails / abuse.phone_numbers)
+ *  • 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 1 credit/lookup)
+ *  • Full retry + exponential backoff via shared api-client
+ *
+ * Shares the same `ipgeo-config` config node (API key) as ipgeo-lookup
+ * and ipgeo-security.
+ */
+
+'use strict';
+
+const { request, IPGeoError } = require('./lib/api-client');
+const {
+  setStatus,
+  resolveValue,
+  setOutputProperty,
+  handleNodeError,
+  buildCommonParams,
+} = require('./lib/node-helpers');
+
+module.exports = function (RED) {
+
+  function IPGeoAbuseNode(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
+        ip = (node.ipValue || '').trim();
+      }
+
+      ip = String(ip).trim();
+
+      // ── Build query parameters ────────────────────────────────────────
+      // Abuse endpoint has no `lang` or `include` params — just
+      // apiKey / ip / fields / excludes. Like /ipgeo and /security, an
+      // omitted ip auto-detects the caller's IP.
+      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:   '/abuse',
+          params,
+        });
+
+        // ── Success ────────────────────────────────────────────────────
+        setStatus(node, 'OK', data.abuse?.organization || data.abuse?.name || 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-abuse', IPGeoAbuseNode);
+
+};

package/nodes/ipgeo-asn.html

@@ -0,0 +1,297 @@
+<!-- ============================================================
+     ipgeo-asn.html
+     ASN lookup node (by IP or by ASN number) — editor template + help
+     ============================================================ -->
+
+<script type="text/javascript">
+    (function () {
+        'use strict';
+
+        // ── Include module list ────────────────────────────────────────────────────
+        const INCLUDE_MODULES = [
+            { id: 'inc-peers', val: 'peers', label: 'peers' },
+            { id: 'inc-downstreams', val: 'downstreams', label: 'downstreams' },
+            { id: 'inc-upstreams', val: 'upstreams', label: 'upstreams' },
+            { id: 'inc-routes', val: 'routes', label: 'routes' },
+            { id: 'inc-whois', val: 'whois_response', label: 'whois_response' },
+        ];
+
+        RED.nodes.registerType('ipgeo-asn', {
+            category: 'IPGeolocation',
+            color: '#7aa874',
+            icon: 'font-awesome/fa-sitemap',
+            paletteLabel: 'ipgeo asn',
+
+            defaults: {
+                name: { value: '' },
+                server: { value: '', type: 'ipgeo-config', required: true },
+                queryType: { value: 'auto' },
+                ipType: { value: 'str' },
+                ipValue: { value: '' },
+                asnType: { value: 'str' },
+                asnValue: { value: '' },
+                include: { 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 asn';
+            },
+
+            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'],
+                });
+
+                // ── ASN input — typed input widget ─────────────────────────────────
+                $('#node-input-asnValue').typedInput({
+                    default: 'str',
+                    typeField: '#node-input-asnType',
+                    types: ['msg', 'flow', 'global', 'str'],
+                });
+
+                // ── Query type — show/hide the relevant row ─────────────────────────
+                function toggleQueryRows() {
+                    const qt = $('#node-input-queryType').val();
+                    $('#ipgeo-asn-ip-row').toggle(qt === 'ip');
+                    $('#ipgeo-asn-asn-row').toggle(qt === 'asn');
+                }
+                $('#node-input-queryType').on('change', toggleQueryRows);
+                toggleQueryRows();
+
+                // ── 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-asn-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'],
+                });
+
+                // ── 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-asn">
+          <!-- 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 asn" style="width:70%" />
+</div>
+
+<!-- Config node (shared with other ipgeo-* nodes) -->
+<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 />
+
+<!-- Query mode -->
+<div class="form-row">
+    <label for="node-input-queryType"><i class="fa fa-search"></i>&nbsp;Lookup by</label>
+    <select id="node-input-queryType" style="width:70%">
+        <option value="auto">Auto-detect (caller's IP)</option>
+        <option value="ip">IP address</option>
+        <option value="asn">ASN number</option>
+    </select>
+</div>
+
+<!-- IP row (shown when queryType === 'ip') -->
+<div class="form-row" id="ipgeo-asn-ip-row">
+    <label for="node-input-ipValue" style="margin-left:20px"><i class="fa fa-globe"></i>&nbsp;IP Address</label>
+    <input type="text" id="node-input-ipValue" placeholder="e.g. 49.12.0.0 or msg.ip" style="width:60%" />
+    <input type="hidden" id="node-input-ipType" />
+</div>
+
+<!-- ASN row (shown when queryType === 'asn') -->
+<div class="form-row" id="ipgeo-asn-asn-row">
+    <label for="node-input-asnValue" style="margin-left:20px"><i class="fa fa-hashtag"></i>&nbsp;ASN</label>
+    <input type="text" id="node-input-asnValue" placeholder="e.g. 24940 or AS24940" style="width:60%" />
+    <input type="hidden" id="node-input-asnType" />
+</div>
+
+<hr />
+
+<!-- Include modules (checkboxes) -->
+<div class="form-row">
+    <label><i class="fa fa-plus-square"></i>&nbsp;Include</label>
+    <div id="ipgeo-asn-include-container" style="display:inline-block;width:70%;vertical-align:top;line-height:2em">
+    </div>
+</div>
+<!-- Hidden field intentionally omitted — include is built/read entirely
+               via the checkboxes above in oneditprepare/oneditsave. -->
+
+<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. asn.organization,asn.country" 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. asn.date_allocated,asn.allocation_status"
+        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-asn">
+          <p>
+            Looks up Autonomous System Number (ASN) details — organization, country,
+            type, allocation date, RIR, and (optionally) peers, upstreams,
+            downstreams, routes, and raw WHOIS text — via
+            <strong>IPGeolocation.io v3 ASN 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>"peers,routes"</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>
+                  <code>{ asn, ip? }</code> — <code>ip</code> is present only when
+                  looking up by IP address or auto-detected caller IP; it is
+                  omitted when looking up directly by ASN number.
+                  <code>asn</code> contains <code>as_number</code>,
+                  <code>organization</code>, <code>country</code>,
+                  <code>asn_name</code>, <code>type</code>, <code>domain</code>,
+                  <code>date_allocated</code>, <code>rir</code>,
+                  <code>allocation_status</code>, <code>num_of_ipv4_routes</code>,
+                  <code>num_of_ipv6_routes</code>, and (when included)
+                  <code>peers</code>, <code>downstreams</code>,
+                  <code>upstreams</code>, <code>routes</code>,
+                  <code>whois_response</code>.
+                </dd>
+                <dt class="optional">ipgeo_credits <span class="property-type">number</span></dt>
+                <dd>Credits consumed by this request (flat 1 credit per lookup).</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>
+              <em>Lookup by</em> chooses which single parameter is sent:
+              <strong>Auto-detect</strong> sends neither <code>ip</code> nor
+              <code>asn</code> and the API resolves the caller's IP;
+              <strong>IP address</strong> sends <code>ip</code>;
+              <strong>ASN number</strong> sends <code>asn</code> (the
+              <code>AS</code> prefix, if typed, is stripped automatically).
+            </li>
+            <li>
+              Use <em>Include</em> checkboxes to add <code>peers</code>,
+              <code>downstreams</code>, <code>upstreams</code>, <code>routes</code>,
+              and/or <code>whois_response</code> to the response. None of these
+              add extra credit cost — the lookup is always flat-rate.
+            </li>
+            <li>
+              <em>Fields</em> restricts the response to named fields
+              (e.g. <code>asn.organization,asn.country</code>). If both
+              <em>Include</em> and <em>Fields</em> are set, only <em>Include</em>
+              is applied by the API.
+            </li>
+            <li>
+              <em>Excludes</em> removes fields from the response
+              (e.g. <code>asn.date_allocated,asn.allocation_status</code>). The
+              top-level <code>ip</code> field cannot be excluded.
+            </li>
+            <li>Every successful lookup costs a flat <strong>1 credit</strong>.</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/asn-api.html" target="_blank">
+                ASN API documentation
+              </a>
+            </li>
+          </ul>
+        </script>