@fonderie/geo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fonderie, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# @fonderie/geo
+
+Self-hosted **IP → location**. Resolve an IPv4/IPv6 address to a country /
+region / city / lat-lng against a Postgres table loaded from MaxMind GeoLite2
+(or Hurricane Electric) CSVs — **no external API, no key shipped**.
+
+Status: **experimental** (0.x).
+
+> Provider-abstracted via `IGeoProvider` — the default `PostgresGeoProvider` is
+> self-hosted; a consumer who prefers a hosted source (MaxMind API, ipinfo, …)
+> plugs one in behind the same interface, the way `billing` swaps payment
+> providers. You're never locked into the self-hosted map.
+
+## Why it's a brick
+
+It's a **signal source**, not a product: `@fonderie/risk` consumes it (geo /
+impossible-travel), and any Fonderie app gets a day-one "where did this request
+come from" — access-log geo, suspicious-login hints — for free. In-process,
+against your own database.
+
+## Use it
+
+```ts
+import { PostgresGeoProvider, loadMaxMindCity } from '@fonderie/geo';
+import { getMigrationsPath } from '@fonderie/geo/migrations';
+// 1. run getMigrationsPath()'s SQL with your store's migration runner
+// 2. one-time load (full snapshot; re-run to refresh):
+await loadMaxMindCity(store, {
+  locationsPath: 'GeoLite2-City-Locations-en.csv',
+  blocksV4Path:  'GeoLite2-City-Blocks-IPv4.csv',
+  blocksV6Path:  'GeoLite2-City-Blocks-IPv6.csv',
+});
+
+const geo = new PostgresGeoProvider(store);
+const loc = await geo.lookup(ip); // → { country, subdivision, city, latitude, longitude, … } | null
+```
+
+## How the lookup works
+
+Blocks are stored as native `cidr`, so one table holds IPv4 **and** IPv6. A
+lookup is a CIDR containment — `WHERE network >>= $ip::inet ORDER BY
+masklen(network) DESC LIMIT 1` — the most-specific block that contains the
+address wins. A GiST `inet_ops` index (core Postgres, no extension) makes it
+fast. Invalid input resolves to `null`, never an error.
+
+## Data
+
+The CSVs are MaxMind's (GeoLite2 City, free with an account) or a compatible
+source — you download and host them; nothing proprietary ships in this package.
+`loadMaxMindCity` truncates and reloads (the dataset is a full snapshot).
+
+Peer-depends on `@fonderie/core` + `@fonderie/store`; imports no other brick.

package/brain/outcomes.md

@@ -0,0 +1,36 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/geo — outcomes
+
+What this package does to a running app: tables its migrations create,
+rows it seeds, routes it registers. Generated from the migration SQL and
+route tables in source — trust this file instead of reading `dist/` or
+downloading tarballs.
+
+## Database tables (after all migrations)
+
+### `geo_blocks`
+
+```sql
+network                  CIDR NOT NULL
+geoname_id               BIGINT
+latitude                 DOUBLE PRECISION
+longitude                DOUBLE PRECISION
+accuracy_radius          INTEGER
+-- INDEX idx_geo_blocks_geoname (geoname_id)
+```
+
+### `geo_names`
+
+```sql
+geoname_id               BIGINT PRIMARY KEY
+continent_code           TEXT
+country_iso              TEXT
+country_name             TEXT
+subdivision_iso          TEXT
+subdivision_name         TEXT
+city_name                TEXT
+time_zone                TEXT
+```
+
+Raw SQL ships in `node_modules/@fonderie/geo/dist/migrations/sql/` — read it there if you must; never download tarballs.

package/brain/signatures.md

@@ -0,0 +1,66 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/geo — signatures
+
+## @fonderie/geo
+
+Subpath exports: `@fonderie/geo/migrations`
+
+```ts
+new PostgresGeoProvider(store: Queryable): PostgresGeoProvider
+  .name: "postgres"
+  .lookup(ip: string): Promise<GeoLocation | null>
+
+function loadMaxMindCity(store: Queryable, files: { locationsPath: string; blocksV4Path?: string; blocksV6Path?: string; }): Promise<{ names: number; blocks: number; }>
+
+function ingestNames(store: Queryable, rows: NameRow[]): Promise<number>
+
+function ingestBlocks(store: Queryable, rows: BlockRow[]): Promise<number>
+
+function parseBlocksCsv(text: string): BlockRow[]
+
+function parseLocationsCsv(text: string): NameRow[]
+
+function parseCsvLine(line: string): string[]
+
+interface BlockRow {
+    network: string;
+    geonameId: number | null;
+    latitude: number | null;
+    longitude: number | null;
+    accuracyRadius: number | null;
+}
+
+interface NameRow {
+    geonameId: number;
+    continentCode: string | null;
+    countryIso: string | null;
+    countryName: string | null;
+    subdivisionIso: string | null;
+    subdivisionName: string | null;
+    cityName: string | null;
+    timeZone: string | null;
+}
+
+interface GeoLocation {
+    country: string | null;
+    countryName: string | null;
+    subdivision: string | null;
+    subdivisionName: string | null;
+    city: string | null;
+    continent: string | null;
+    timeZone: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    accuracyRadius: number | null;
+}
+
+interface IGeoProvider {
+    name: string;
+    lookup(ip: string): Promise<GeoLocation | null>;
+}
+
+interface Queryable {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+```

package/dist/index.cjs

@@ -0,0 +1,198 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  PostgresGeoProvider: () => PostgresGeoProvider,
+  ingestBlocks: () => ingestBlocks,
+  ingestNames: () => ingestNames,
+  loadMaxMindCity: () => loadMaxMindCity,
+  parseBlocksCsv: () => parseBlocksCsv,
+  parseCsvLine: () => parseCsvLine,
+  parseLocationsCsv: () => parseLocationsCsv
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/provider.ts
+var LOOKS_LIKE_IP = /^[0-9a-fA-F:.]+$/;
+var PostgresGeoProvider = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  name = "postgres";
+  async lookup(ip) {
+    const addr = (ip ?? "").trim();
+    if (!addr || addr.length > 45 || !LOOKS_LIKE_IP.test(addr)) return null;
+    try {
+      const rows = await this.store.query(
+        `SELECT n.country_iso, n.country_name, n.subdivision_iso, n.subdivision_name,
+				        n.city_name, n.continent_code, n.time_zone,
+				        b.latitude, b.longitude, b.accuracy_radius
+				 FROM geo_blocks b
+				 LEFT JOIN geo_names n ON n.geoname_id = b.geoname_id
+				 WHERE b.network >>= $1::inet
+				 ORDER BY masklen(b.network) DESC
+				 LIMIT 1`,
+        [addr]
+      );
+      const r = rows[0];
+      if (!r) return null;
+      return {
+        country: r.country_iso ?? null,
+        countryName: r.country_name ?? null,
+        subdivision: r.subdivision_iso ?? null,
+        subdivisionName: r.subdivision_name ?? null,
+        city: r.city_name ?? null,
+        continent: r.continent_code ?? null,
+        timeZone: r.time_zone ?? null,
+        latitude: r.latitude != null ? Number(r.latitude) : null,
+        longitude: r.longitude != null ? Number(r.longitude) : null,
+        accuracyRadius: r.accuracy_radius != null ? Number(r.accuracy_radius) : null
+      };
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/ingest.ts
+var import_node_fs = require("fs");
+function parseCsvLine(line) {
+  const out = [];
+  let field = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (line[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') inQuotes = true;
+    else if (c === ",") {
+      out.push(field);
+      field = "";
+    } else field += c;
+  }
+  out.push(field);
+  return out;
+}
+var num = (s) => {
+  if (s == null || s === "") return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+};
+var str = (s) => s == null || s === "" ? null : s;
+function parseBlocksCsv(text) {
+  const rows = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const c = parseCsvLine(line);
+    if (!c[0]) continue;
+    rows.push({
+      network: c[0],
+      geonameId: num(c[1]),
+      latitude: num(c[7]),
+      longitude: num(c[8]),
+      accuracyRadius: num(c[9])
+    });
+  }
+  return rows;
+}
+function parseLocationsCsv(text) {
+  const rows = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const c = parseCsvLine(line);
+    const id = num(c[0]);
+    if (id == null) continue;
+    rows.push({
+      geonameId: id,
+      continentCode: str(c[2]),
+      countryIso: str(c[4]),
+      countryName: str(c[5]),
+      subdivisionIso: str(c[6]),
+      subdivisionName: str(c[7]),
+      cityName: str(c[10]),
+      timeZone: str(c[12])
+    });
+  }
+  return rows;
+}
+var CHUNK = 500;
+async function insertChunked(store, rows, cols, sqlHead, toParams) {
+  let n = 0;
+  for (let i = 0; i < rows.length; i += CHUNK) {
+    const batch = rows.slice(i, i + CHUNK);
+    const values = batch.map((_, b) => `(${Array.from({ length: cols }, (_2, k) => `$${b * cols + k + 1}`).join(", ")})`).join(", ");
+    const params = batch.flatMap(toParams);
+    await store.query(`${sqlHead} VALUES ${values}`, params);
+    n += batch.length;
+  }
+  return n;
+}
+async function ingestNames(store, rows) {
+  return insertChunked(
+    store,
+    rows,
+    8,
+    `INSERT INTO geo_names (geoname_id, continent_code, country_iso, country_name, subdivision_iso, subdivision_name, city_name, time_zone)`,
+    (r) => [r.geonameId, r.continentCode, r.countryIso, r.countryName, r.subdivisionIso, r.subdivisionName, r.cityName, r.timeZone]
+  ).then(async (c) => {
+    return c;
+  });
+}
+async function ingestBlocks(store, rows) {
+  return insertChunked(
+    store,
+    rows,
+    5,
+    `INSERT INTO geo_blocks (network, geoname_id, latitude, longitude, accuracy_radius)`,
+    (r) => [r.network, r.geonameId, r.latitude, r.longitude, r.accuracyRadius]
+  );
+}
+async function loadMaxMindCity(store, files) {
+  await store.query("TRUNCATE geo_blocks");
+  await store.query("TRUNCATE geo_names");
+  const names = await ingestNames(store, parseLocationsCsv((0, import_node_fs.readFileSync)(files.locationsPath, "utf8")));
+  let blocks = 0;
+  for (const p of [files.blocksV4Path, files.blocksV6Path]) {
+    if (p) blocks += await ingestBlocks(store, parseBlocksCsv((0, import_node_fs.readFileSync)(p, "utf8")));
+  }
+  return { names, blocks };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PostgresGeoProvider,
+  ingestBlocks,
+  ingestNames,
+  loadMaxMindCity,
+  parseBlocksCsv,
+  parseCsvLine,
+  parseLocationsCsv
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/provider.ts","../src/ingest.ts"],"sourcesContent":["// @fonderie/geo — self-hosted IP → location.\n//\n// The default PostgresGeoProvider resolves against a table of MaxMind/HE CIDR\n// blocks (native inet/GiST — IPv4 + IPv6, no external API). IGeoProvider is the\n// swap seam for a hosted source later. A signal source for @fonderie/risk and a\n// day-one \"where is this request from\" for any Fonderie app.\n//\n// Run getMigrationsPath()'s SQL with your store's migration runner, then load\n// data with loadMaxMindCity() (or the parse*/ingest* pieces).\nexport { PostgresGeoProvider } from './provider.js';\nexport {\n\tloadMaxMindCity,\n\tingestNames,\n\tingestBlocks,\n\tparseBlocksCsv,\n\tparseLocationsCsv,\n\tparseCsvLine,\n} from './ingest.js';\nexport type { BlockRow, NameRow } from './ingest.js';\nexport type { GeoLocation, IGeoProvider, Queryable } from './types.js';\n","import type { GeoLocation, IGeoProvider, Queryable } from './types.js';\n\n// Cheap guard so obvious garbage never reaches the ::inet cast (which would\n// throw). Not a full validator — the cast is the real gate; this just avoids a\n// round-trip (and an error log) for empty / clearly-non-IP input.\nconst LOOKS_LIKE_IP = /^[0-9a-fA-F:.]+$/;\n\n/**\n * The default, self-hosted provider: resolves an IP against the geo_blocks /\n * geo_names tables loaded from MaxMind/HE CSVs. The lookup is a CIDR\n * containment — the most-specific block that contains the address wins —\n * handling IPv4 and IPv6 uniformly via Postgres's native `cidr`/`inet`.\n */\nexport class PostgresGeoProvider implements IGeoProvider {\n\treadonly name = 'postgres';\n\n\tconstructor(private readonly store: Queryable) {}\n\n\tasync lookup(ip: string): Promise<GeoLocation | null> {\n\t\tconst addr = (ip ?? '').trim();\n\t\tif (!addr || addr.length > 45 || !LOOKS_LIKE_IP.test(addr)) return null;\n\t\ttry {\n\t\t\tconst rows = await this.store.query<{\n\t\t\t\tcountry_iso: string | null;\n\t\t\t\tcountry_name: string | null;\n\t\t\t\tsubdivision_iso: string | null;\n\t\t\t\tsubdivision_name: string | null;\n\t\t\t\tcity_name: string | null;\n\t\t\t\tcontinent_code: string | null;\n\t\t\t\ttime_zone: string | null;\n\t\t\t\tlatitude: number | null;\n\t\t\t\tlongitude: number | null;\n\t\t\t\taccuracy_radius: number | null;\n\t\t\t}>(\n\t\t\t\t`SELECT n.country_iso, n.country_name, n.subdivision_iso, n.subdivision_name,\n\t\t\t\t        n.city_name, n.continent_code, n.time_zone,\n\t\t\t\t        b.latitude, b.longitude, b.accuracy_radius\n\t\t\t\t FROM geo_blocks b\n\t\t\t\t LEFT JOIN geo_names n ON n.geoname_id = b.geoname_id\n\t\t\t\t WHERE b.network >>= $1::inet\n\t\t\t\t ORDER BY masklen(b.network) DESC\n\t\t\t\t LIMIT 1`,\n\t\t\t\t[addr],\n\t\t\t);\n\t\t\tconst r = rows[0];\n\t\t\tif (!r) return null;\n\t\t\treturn {\n\t\t\t\tcountry: r.country_iso ?? null,\n\t\t\t\tcountryName: r.country_name ?? null,\n\t\t\t\tsubdivision: r.subdivision_iso ?? null,\n\t\t\t\tsubdivisionName: r.subdivision_name ?? null,\n\t\t\t\tcity: r.city_name ?? null,\n\t\t\t\tcontinent: r.continent_code ?? null,\n\t\t\t\ttimeZone: r.time_zone ?? null,\n\t\t\t\tlatitude: r.latitude != null ? Number(r.latitude) : null,\n\t\t\t\tlongitude: r.longitude != null ? Number(r.longitude) : null,\n\t\t\t\taccuracyRadius: r.accuracy_radius != null ? Number(r.accuracy_radius) : null,\n\t\t\t};\n\t\t} catch {\n\t\t\t// Invalid inet (bad cast) or a transient store error → unknown, not a throw.\n\t\t\treturn null;\n\t\t}\n\t}\n}\n","// Load MaxMind GeoLite2 City CSVs (the same files the prior arbinuity importer\n// used) into geo_blocks + geo_names. Hurricane Electric / other sources work\n// too as long as rows map to {network, geoname_id, lat, lng, accuracy} and\n// {geoname_id, country, subdivision, city}.\nimport { readFileSync } from 'node:fs';\nimport type { Queryable } from './types.js';\n\nexport interface BlockRow {\n\tnetwork: string;\n\tgeonameId: number | null;\n\tlatitude: number | null;\n\tlongitude: number | null;\n\taccuracyRadius: number | null;\n}\n\nexport interface NameRow {\n\tgeonameId: number;\n\tcontinentCode: string | null;\n\tcountryIso: string | null;\n\tcountryName: string | null;\n\tsubdivisionIso: string | null;\n\tsubdivisionName: string | null;\n\tcityName: string | null;\n\ttimeZone: string | null;\n}\n\n/** RFC4180-ish single-line parser: handles quoted fields, embedded commas, and\n * \"\" escaped quotes (MaxMind city names like \"Washington, D.C.\" need this). */\nexport function parseCsvLine(line: string): string[] {\n\tconst out: string[] = [];\n\tlet field = '';\n\tlet inQuotes = false;\n\tfor (let i = 0; i < line.length; i++) {\n\t\tconst c = line[i];\n\t\tif (inQuotes) {\n\t\t\tif (c === '\"') {\n\t\t\t\tif (line[i + 1] === '\"') { field += '\"'; i++; } else inQuotes = false;\n\t\t\t} else field += c;\n\t\t} else if (c === '\"') inQuotes = true;\n\t\telse if (c === ',') { out.push(field); field = ''; }\n\t\telse field += c;\n\t}\n\tout.push(field);\n\treturn out;\n}\n\nconst num = (s: string | undefined): number | null => {\n\tif (s == null || s === '') return null;\n\tconst n = Number(s);\n\treturn Number.isFinite(n) ? n : null;\n};\nconst str = (s: string | undefined): string | null => (s == null || s === '' ? null : s);\n\n/** Parse a GeoLite2-City-Blocks-IPv4/IPv6 CSV (header row skipped). Columns:\n * network, geoname_id, registered_country_geoname_id, represented_country_geoname_id,\n * is_anonymous_proxy, is_satellite_provider, postal_code, latitude, longitude, accuracy_radius. */\nexport function parseBlocksCsv(text: string): BlockRow[] {\n\tconst rows: BlockRow[] = [];\n\tconst lines = text.split(/\\r?\\n/);\n\tfor (let i = 1; i < lines.length; i++) {\n\t\tconst line = lines[i];\n\t\tif (!line) continue;\n\t\tconst c = parseCsvLine(line);\n\t\tif (!c[0]) continue;\n\t\trows.push({\n\t\t\tnetwork: c[0],\n\t\t\tgeonameId: num(c[1]),\n\t\t\tlatitude: num(c[7]),\n\t\t\tlongitude: num(c[8]),\n\t\t\taccuracyRadius: num(c[9]),\n\t\t});\n\t}\n\treturn rows;\n}\n\n/** Parse a GeoLite2-City-Locations-<locale> CSV (header row skipped). Columns:\n * geoname_id, locale_code, continent_code, continent_name, country_iso_code,\n * country_name, subdivision_1_iso_code, subdivision_1_name, subdivision_2_iso_code,\n * subdivision_2_name, city_name, metro_code, time_zone, is_in_european_union. */\nexport function parseLocationsCsv(text: string): NameRow[] {\n\tconst rows: NameRow[] = [];\n\tconst lines = text.split(/\\r?\\n/);\n\tfor (let i = 1; i < lines.length; i++) {\n\t\tconst line = lines[i];\n\t\tif (!line) continue;\n\t\tconst c = parseCsvLine(line);\n\t\tconst id = num(c[0]);\n\t\tif (id == null) continue;\n\t\trows.push({\n\t\t\tgeonameId: id,\n\t\t\tcontinentCode: str(c[2]),\n\t\t\tcountryIso: str(c[4]),\n\t\t\tcountryName: str(c[5]),\n\t\t\tsubdivisionIso: str(c[6]),\n\t\t\tsubdivisionName: str(c[7]),\n\t\t\tcityName: str(c[10]),\n\t\t\ttimeZone: str(c[12]),\n\t\t});\n\t}\n\treturn rows;\n}\n\nconst CHUNK = 500;\n\nasync function insertChunked<T>(\n\tstore: Queryable,\n\trows: T[],\n\tcols: number,\n\tsqlHead: string,\n\ttoParams: (r: T) => unknown[],\n): Promise<number> {\n\tlet n = 0;\n\tfor (let i = 0; i < rows.length; i += CHUNK) {\n\t\tconst batch = rows.slice(i, i + CHUNK);\n\t\tconst values = batch\n\t\t\t.map((_, b) => `(${Array.from({ length: cols }, (_, k) => `$${b * cols + k + 1}`).join(', ')})`)\n\t\t\t.join(', ');\n\t\tconst params = batch.flatMap(toParams);\n\t\tawait store.query(`${sqlHead} VALUES ${values}`, params);\n\t\tn += batch.length;\n\t}\n\treturn n;\n}\n\nexport async function ingestNames(store: Queryable, rows: NameRow[]): Promise<number> {\n\treturn insertChunked(\n\t\tstore,\n\t\trows,\n\t\t8,\n\t\t`INSERT INTO geo_names (geoname_id, continent_code, country_iso, country_name, subdivision_iso, subdivision_name, city_name, time_zone)`,\n\t\t(r) => [r.geonameId, r.continentCode, r.countryIso, r.countryName, r.subdivisionIso, r.subdivisionName, r.cityName, r.timeZone],\n\t).then(async (c) => {\n\t\t// geo_names is a PK table; a re-run would conflict. Caller truncates first\n\t\t// for a full reload; this keeps ingest itself simple and idempotent-free.\n\t\treturn c;\n\t});\n}\n\nexport async function ingestBlocks(store: Queryable, rows: BlockRow[]): Promise<number> {\n\treturn insertChunked(\n\t\tstore,\n\t\trows,\n\t\t5,\n\t\t`INSERT INTO geo_blocks (network, geoname_id, latitude, longitude, accuracy_radius)`,\n\t\t(r) => [r.network, r.geonameId, r.latitude, r.longitude, r.accuracyRadius],\n\t);\n}\n\n/** Full load from MaxMind City CSV files. Truncates first so a reload is a\n * clean replace (the dataset is a full snapshot, not a delta). */\nexport async function loadMaxMindCity(\n\tstore: Queryable,\n\tfiles: { locationsPath: string; blocksV4Path?: string; blocksV6Path?: string },\n): Promise<{ names: number; blocks: number }> {\n\tawait store.query('TRUNCATE geo_blocks');\n\tawait store.query('TRUNCATE geo_names');\n\tconst names = await ingestNames(store, parseLocationsCsv(readFileSync(files.locationsPath, 'utf8')));\n\tlet blocks = 0;\n\tfor (const p of [files.blocksV4Path, files.blocksV6Path]) {\n\t\tif (p) blocks += await ingestBlocks(store, parseBlocksCsv(readFileSync(p, 'utf8')));\n\t}\n\treturn { names, blocks };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKA,IAAM,gBAAgB;AAQf,IAAM,sBAAN,MAAkD;AAAA,EAGxD,YAA6B,OAAkB;AAAlB;AAAA,EAAmB;AAAA,EAAnB;AAAA,EAFpB,OAAO;AAAA,EAIhB,MAAM,OAAO,IAAyC;AACrD,UAAM,QAAQ,MAAM,IAAI,KAAK;AAC7B,QAAI,CAAC,QAAQ,KAAK,SAAS,MAAM,CAAC,cAAc,KAAK,IAAI,EAAG,QAAO;AACnE,QAAI;AACH,YAAM,OAAO,MAAM,KAAK,MAAM;AAAA,QAY7B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAQA,CAAC,IAAI;AAAA,MACN;AACA,YAAM,IAAI,KAAK,CAAC;AAChB,UAAI,CAAC,EAAG,QAAO;AACf,aAAO;AAAA,QACN,SAAS,EAAE,eAAe;AAAA,QAC1B,aAAa,EAAE,gBAAgB;AAAA,QAC/B,aAAa,EAAE,mBAAmB;AAAA,QAClC,iBAAiB,EAAE,oBAAoB;AAAA,QACvC,MAAM,EAAE,aAAa;AAAA,QACrB,WAAW,EAAE,kBAAkB;AAAA,QAC/B,UAAU,EAAE,aAAa;AAAA,QACzB,UAAU,EAAE,YAAY,OAAO,OAAO,EAAE,QAAQ,IAAI;AAAA,QACpD,WAAW,EAAE,aAAa,OAAO,OAAO,EAAE,SAAS,IAAI;AAAA,QACvD,gBAAgB,EAAE,mBAAmB,OAAO,OAAO,EAAE,eAAe,IAAI;AAAA,MACzE;AAAA,IACD,QAAQ;AAEP,aAAO;AAAA,IACR;AAAA,EACD;AACD;;;AC3DA,qBAA6B;AAwBtB,SAAS,aAAa,MAAwB;AACpD,QAAM,MAAgB,CAAC;AACvB,MAAI,QAAQ;AACZ,MAAI,WAAW;AACf,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACrC,UAAM,IAAI,KAAK,CAAC;AAChB,QAAI,UAAU;AACb,UAAI,MAAM,KAAK;AACd,YAAI,KAAK,IAAI,CAAC,MAAM,KAAK;AAAE,mBAAS;AAAK;AAAA,QAAK,MAAO,YAAW;AAAA,MACjE,MAAO,UAAS;AAAA,IACjB,WAAW,MAAM,IAAK,YAAW;AAAA,aACxB,MAAM,KAAK;AAAE,UAAI,KAAK,KAAK;AAAG,cAAQ;AAAA,IAAI,MAC9C,UAAS;AAAA,EACf;AACA,MAAI,KAAK,KAAK;AACd,SAAO;AACR;AAEA,IAAM,MAAM,CAAC,MAAyC;AACrD,MAAI,KAAK,QAAQ,MAAM,GAAI,QAAO;AAClC,QAAM,IAAI,OAAO,CAAC;AAClB,SAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AACjC;AACA,IAAM,MAAM,CAAC,MAA0C,KAAK,QAAQ,MAAM,KAAK,OAAO;AAK/E,SAAS,eAAe,MAA0B;AACxD,QAAM,OAAmB,CAAC;AAC1B,QAAM,QAAQ,KAAK,MAAM,OAAO;AAChC,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACtC,UAAM,OAAO,MAAM,CAAC;AACpB,QAAI,CAAC,KAAM;AACX,UAAM,IAAI,aAAa,IAAI;AAC3B,QAAI,CAAC,EAAE,CAAC,EAAG;AACX,SAAK,KAAK;AAAA,MACT,SAAS,EAAE,CAAC;AAAA,MACZ,WAAW,IAAI,EAAE,CAAC,CAAC;AAAA,MACnB,UAAU,IAAI,EAAE,CAAC,CAAC;AAAA,MAClB,WAAW,IAAI,EAAE,CAAC,CAAC;AAAA,MACnB,gBAAgB,IAAI,EAAE,CAAC,CAAC;AAAA,IACzB,CAAC;AAAA,EACF;AACA,SAAO;AACR;AAMO,SAAS,kBAAkB,MAAyB;AAC1D,QAAM,OAAkB,CAAC;AACzB,QAAM,QAAQ,KAAK,MAAM,OAAO;AAChC,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACtC,UAAM,OAAO,MAAM,CAAC;AACpB,QAAI,CAAC,KAAM;AACX,UAAM,IAAI,aAAa,IAAI;AAC3B,UAAM,KAAK,IAAI,EAAE,CAAC,CAAC;AACnB,QAAI,MAAM,KAAM;AAChB,SAAK,KAAK;AAAA,MACT,WAAW;AAAA,MACX,eAAe,IAAI,EAAE,CAAC,CAAC;AAAA,MACvB,YAAY,IAAI,EAAE,CAAC,CAAC;AAAA,MACpB,aAAa,IAAI,EAAE,CAAC,CAAC;AAAA,MACrB,gBAAgB,IAAI,EAAE,CAAC,CAAC;AAAA,MACxB,iBAAiB,IAAI,EAAE,CAAC,CAAC;AAAA,MACzB,UAAU,IAAI,EAAE,EAAE,CAAC;AAAA,MACnB,UAAU,IAAI,EAAE,EAAE,CAAC;AAAA,IACpB,CAAC;AAAA,EACF;AACA,SAAO;AACR;AAEA,IAAM,QAAQ;AAEd,eAAe,cACd,OACA,MACA,MACA,SACA,UACkB;AAClB,MAAI,IAAI;AACR,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,OAAO;AAC5C,UAAM,QAAQ,KAAK,MAAM,GAAG,IAAI,KAAK;AACrC,UAAM,SAAS,MACb,IAAI,CAAC,GAAG,MAAM,IAAI,MAAM,KAAK,EAAE,QAAQ,KAAK,GAAG,CAACA,IAAG,MAAM,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,EAAE,KAAK,IAAI,CAAC,GAAG,EAC9F,KAAK,IAAI;AACX,UAAM,SAAS,MAAM,QAAQ,QAAQ;AACrC,UAAM,MAAM,MAAM,GAAG,OAAO,WAAW,MAAM,IAAI,MAAM;AACvD,SAAK,MAAM;AAAA,EACZ;AACA,SAAO;AACR;AAEA,eAAsB,YAAY,OAAkB,MAAkC;AACrF,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,UAAU,EAAE,QAAQ;AAAA,EAC/H,EAAE,KAAK,OAAO,MAAM;AAGnB,WAAO;AAAA,EACR,CAAC;AACF;AAEA,eAAsB,aAAa,OAAkB,MAAmC;AACvF,SAAO;AAAA,IACN;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc;AAAA,EAC1E;AACD;AAIA,eAAsB,gBACrB,OACA,OAC6C;AAC7C,QAAM,MAAM,MAAM,qBAAqB;AACvC,QAAM,MAAM,MAAM,oBAAoB;AACtC,QAAM,QAAQ,MAAM,YAAY,OAAO,sBAAkB,6BAAa,MAAM,eAAe,MAAM,CAAC,CAAC;AACnG,MAAI,SAAS;AACb,aAAW,KAAK,CAAC,MAAM,cAAc,MAAM,YAAY,GAAG;AACzD,QAAI,EAAG,WAAU,MAAM,aAAa,OAAO,mBAAe,6BAAa,GAAG,MAAM,CAAC,CAAC;AAAA,EACnF;AACA,SAAO,EAAE,OAAO,OAAO;AACxB;","names":["_"]}

package/dist/index.d.cts

@@ -0,0 +1,84 @@
+/** A resolved IP location. Any field may be null — MaxMind has blocks with a
+ * country but no city, etc. */
+interface GeoLocation {
+    country: string | null;
+    countryName: string | null;
+    subdivision: string | null;
+    subdivisionName: string | null;
+    city: string | null;
+    continent: string | null;
+    timeZone: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    accuracyRadius: number | null;
+}
+/** The swap seam: the default resolves against the self-hosted Postgres table,
+ * but a consumer can plug a hosted provider (MaxMind API, ipinfo, …) behind
+ * the same interface — same pattern as IBillingProvider / IStorageProvider. */
+interface IGeoProvider {
+    name: string;
+    /** Resolve an IPv4/IPv6 address to a location, or null if unknown/invalid. */
+    lookup(ip: string): Promise<GeoLocation | null>;
+}
+/** Store adapter surface the Postgres provider needs (accepts the adapter or a
+ * transaction handle). */
+interface Queryable {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+
+/**
+ * The default, self-hosted provider: resolves an IP against the geo_blocks /
+ * geo_names tables loaded from MaxMind/HE CSVs. The lookup is a CIDR
+ * containment — the most-specific block that contains the address wins —
+ * handling IPv4 and IPv6 uniformly via Postgres's native `cidr`/`inet`.
+ */
+declare class PostgresGeoProvider implements IGeoProvider {
+    private readonly store;
+    readonly name = "postgres";
+    constructor(store: Queryable);
+    lookup(ip: string): Promise<GeoLocation | null>;
+}
+
+interface BlockRow {
+    network: string;
+    geonameId: number | null;
+    latitude: number | null;
+    longitude: number | null;
+    accuracyRadius: number | null;
+}
+interface NameRow {
+    geonameId: number;
+    continentCode: string | null;
+    countryIso: string | null;
+    countryName: string | null;
+    subdivisionIso: string | null;
+    subdivisionName: string | null;
+    cityName: string | null;
+    timeZone: string | null;
+}
+/** RFC4180-ish single-line parser: handles quoted fields, embedded commas, and
+ * "" escaped quotes (MaxMind city names like "Washington, D.C." need this). */
+declare function parseCsvLine(line: string): string[];
+/** Parse a GeoLite2-City-Blocks-IPv4/IPv6 CSV (header row skipped). Columns:
+ * network, geoname_id, registered_country_geoname_id, represented_country_geoname_id,
+ * is_anonymous_proxy, is_satellite_provider, postal_code, latitude, longitude, accuracy_radius. */
+declare function parseBlocksCsv(text: string): BlockRow[];
+/** Parse a GeoLite2-City-Locations-<locale> CSV (header row skipped). Columns:
+ * geoname_id, locale_code, continent_code, continent_name, country_iso_code,
+ * country_name, subdivision_1_iso_code, subdivision_1_name, subdivision_2_iso_code,
+ * subdivision_2_name, city_name, metro_code, time_zone, is_in_european_union. */
+declare function parseLocationsCsv(text: string): NameRow[];
+declare function ingestNames(store: Queryable, rows: NameRow[]): Promise<number>;
+declare function ingestBlocks(store: Queryable, rows: BlockRow[]): Promise<number>;
+/** Full load from MaxMind City CSV files. Truncates first so a reload is a
+ * clean replace (the dataset is a full snapshot, not a delta). */
+declare function loadMaxMindCity(store: Queryable, files: {
+    locationsPath: string;
+    blocksV4Path?: string;
+    blocksV6Path?: string;
+}): Promise<{
+    names: number;
+    blocks: number;
+}>;
+
+export { type BlockRow, type GeoLocation, type IGeoProvider, type NameRow, PostgresGeoProvider, type Queryable, ingestBlocks, ingestNames, loadMaxMindCity, parseBlocksCsv, parseCsvLine, parseLocationsCsv };

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+/** A resolved IP location. Any field may be null — MaxMind has blocks with a
+ * country but no city, etc. */
+interface GeoLocation {
+    country: string | null;
+    countryName: string | null;
+    subdivision: string | null;
+    subdivisionName: string | null;
+    city: string | null;
+    continent: string | null;
+    timeZone: string | null;
+    latitude: number | null;
+    longitude: number | null;
+    accuracyRadius: number | null;
+}
+/** The swap seam: the default resolves against the self-hosted Postgres table,
+ * but a consumer can plug a hosted provider (MaxMind API, ipinfo, …) behind
+ * the same interface — same pattern as IBillingProvider / IStorageProvider. */
+interface IGeoProvider {
+    name: string;
+    /** Resolve an IPv4/IPv6 address to a location, or null if unknown/invalid. */
+    lookup(ip: string): Promise<GeoLocation | null>;
+}
+/** Store adapter surface the Postgres provider needs (accepts the adapter or a
+ * transaction handle). */
+interface Queryable {
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+}
+
+/**
+ * The default, self-hosted provider: resolves an IP against the geo_blocks /
+ * geo_names tables loaded from MaxMind/HE CSVs. The lookup is a CIDR
+ * containment — the most-specific block that contains the address wins —
+ * handling IPv4 and IPv6 uniformly via Postgres's native `cidr`/`inet`.
+ */
+declare class PostgresGeoProvider implements IGeoProvider {
+    private readonly store;
+    readonly name = "postgres";
+    constructor(store: Queryable);
+    lookup(ip: string): Promise<GeoLocation | null>;
+}
+
+interface BlockRow {
+    network: string;
+    geonameId: number | null;
+    latitude: number | null;
+    longitude: number | null;
+    accuracyRadius: number | null;
+}
+interface NameRow {
+    geonameId: number;
+    continentCode: string | null;
+    countryIso: string | null;
+    countryName: string | null;
+    subdivisionIso: string | null;
+    subdivisionName: string | null;
+    cityName: string | null;
+    timeZone: string | null;
+}
+/** RFC4180-ish single-line parser: handles quoted fields, embedded commas, and
+ * "" escaped quotes (MaxMind city names like "Washington, D.C." need this). */
+declare function parseCsvLine(line: string): string[];
+/** Parse a GeoLite2-City-Blocks-IPv4/IPv6 CSV (header row skipped). Columns:
+ * network, geoname_id, registered_country_geoname_id, represented_country_geoname_id,
+ * is_anonymous_proxy, is_satellite_provider, postal_code, latitude, longitude, accuracy_radius. */
+declare function parseBlocksCsv(text: string): BlockRow[];
+/** Parse a GeoLite2-City-Locations-<locale> CSV (header row skipped). Columns:
+ * geoname_id, locale_code, continent_code, continent_name, country_iso_code,
+ * country_name, subdivision_1_iso_code, subdivision_1_name, subdivision_2_iso_code,
+ * subdivision_2_name, city_name, metro_code, time_zone, is_in_european_union. */
+declare function parseLocationsCsv(text: string): NameRow[];
+declare function ingestNames(store: Queryable, rows: NameRow[]): Promise<number>;
+declare function ingestBlocks(store: Queryable, rows: BlockRow[]): Promise<number>;
+/** Full load from MaxMind City CSV files. Truncates first so a reload is a
+ * clean replace (the dataset is a full snapshot, not a delta). */
+declare function loadMaxMindCity(store: Queryable, files: {
+    locationsPath: string;
+    blocksV4Path?: string;
+    blocksV6Path?: string;
+}): Promise<{
+    names: number;
+    blocks: number;
+}>;
+
+export { type BlockRow, type GeoLocation, type IGeoProvider, type NameRow, PostgresGeoProvider, type Queryable, ingestBlocks, ingestNames, loadMaxMindCity, parseBlocksCsv, parseCsvLine, parseLocationsCsv };

package/dist/index.js

@@ -0,0 +1,165 @@
+// src/provider.ts
+var LOOKS_LIKE_IP = /^[0-9a-fA-F:.]+$/;
+var PostgresGeoProvider = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  name = "postgres";
+  async lookup(ip) {
+    const addr = (ip ?? "").trim();
+    if (!addr || addr.length > 45 || !LOOKS_LIKE_IP.test(addr)) return null;
+    try {
+      const rows = await this.store.query(
+        `SELECT n.country_iso, n.country_name, n.subdivision_iso, n.subdivision_name,
+				        n.city_name, n.continent_code, n.time_zone,
+				        b.latitude, b.longitude, b.accuracy_radius
+				 FROM geo_blocks b
+				 LEFT JOIN geo_names n ON n.geoname_id = b.geoname_id
+				 WHERE b.network >>= $1::inet
+				 ORDER BY masklen(b.network) DESC
+				 LIMIT 1`,
+        [addr]
+      );
+      const r = rows[0];
+      if (!r) return null;
+      return {
+        country: r.country_iso ?? null,
+        countryName: r.country_name ?? null,
+        subdivision: r.subdivision_iso ?? null,
+        subdivisionName: r.subdivision_name ?? null,
+        city: r.city_name ?? null,
+        continent: r.continent_code ?? null,
+        timeZone: r.time_zone ?? null,
+        latitude: r.latitude != null ? Number(r.latitude) : null,
+        longitude: r.longitude != null ? Number(r.longitude) : null,
+        accuracyRadius: r.accuracy_radius != null ? Number(r.accuracy_radius) : null
+      };
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/ingest.ts
+import { readFileSync } from "fs";
+function parseCsvLine(line) {
+  const out = [];
+  let field = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (inQuotes) {
+      if (c === '"') {
+        if (line[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else inQuotes = false;
+      } else field += c;
+    } else if (c === '"') inQuotes = true;
+    else if (c === ",") {
+      out.push(field);
+      field = "";
+    } else field += c;
+  }
+  out.push(field);
+  return out;
+}
+var num = (s) => {
+  if (s == null || s === "") return null;
+  const n = Number(s);
+  return Number.isFinite(n) ? n : null;
+};
+var str = (s) => s == null || s === "" ? null : s;
+function parseBlocksCsv(text) {
+  const rows = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const c = parseCsvLine(line);
+    if (!c[0]) continue;
+    rows.push({
+      network: c[0],
+      geonameId: num(c[1]),
+      latitude: num(c[7]),
+      longitude: num(c[8]),
+      accuracyRadius: num(c[9])
+    });
+  }
+  return rows;
+}
+function parseLocationsCsv(text) {
+  const rows = [];
+  const lines = text.split(/\r?\n/);
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line) continue;
+    const c = parseCsvLine(line);
+    const id = num(c[0]);
+    if (id == null) continue;
+    rows.push({
+      geonameId: id,
+      continentCode: str(c[2]),
+      countryIso: str(c[4]),
+      countryName: str(c[5]),
+      subdivisionIso: str(c[6]),
+      subdivisionName: str(c[7]),
+      cityName: str(c[10]),
+      timeZone: str(c[12])
+    });
+  }
+  return rows;
+}
+var CHUNK = 500;
+async function insertChunked(store, rows, cols, sqlHead, toParams) {
+  let n = 0;
+  for (let i = 0; i < rows.length; i += CHUNK) {
+    const batch = rows.slice(i, i + CHUNK);
+    const values = batch.map((_, b) => `(${Array.from({ length: cols }, (_2, k) => `$${b * cols + k + 1}`).join(", ")})`).join(", ");
+    const params = batch.flatMap(toParams);
+    await store.query(`${sqlHead} VALUES ${values}`, params);
+    n += batch.length;
+  }
+  return n;
+}
+async function ingestNames(store, rows) {
+  return insertChunked(
+    store,
+    rows,
+    8,
+    `INSERT INTO geo_names (geoname_id, continent_code, country_iso, country_name, subdivision_iso, subdivision_name, city_name, time_zone)`,
+    (r) => [r.geonameId, r.continentCode, r.countryIso, r.countryName, r.subdivisionIso, r.subdivisionName, r.cityName, r.timeZone]
+  ).then(async (c) => {
+    return c;
+  });
+}
+async function ingestBlocks(store, rows) {
+  return insertChunked(
+    store,
+    rows,
+    5,
+    `INSERT INTO geo_blocks (network, geoname_id, latitude, longitude, accuracy_radius)`,
+    (r) => [r.network, r.geonameId, r.latitude, r.longitude, r.accuracyRadius]
+  );
+}
+async function loadMaxMindCity(store, files) {
+  await store.query("TRUNCATE geo_blocks");
+  await store.query("TRUNCATE geo_names");
+  const names = await ingestNames(store, parseLocationsCsv(readFileSync(files.locationsPath, "utf8")));
+  let blocks = 0;
+  for (const p of [files.blocksV4Path, files.blocksV6Path]) {
+    if (p) blocks += await ingestBlocks(store, parseBlocksCsv(readFileSync(p, "utf8")));
+  }
+  return { names, blocks };
+}
+export {
+  PostgresGeoProvider,
+  ingestBlocks,
+  ingestNames,
+  loadMaxMindCity,
+  parseBlocksCsv,
+  parseCsvLine,
+  parseLocationsCsv
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/provider.ts","../src/ingest.ts"],"sourcesContent":["import type { GeoLocation, IGeoProvider, Queryable } from './types.js';\n\n// Cheap guard so obvious garbage never reaches the ::inet cast (which would\n// throw). Not a full validator — the cast is the real gate; this just avoids a\n// round-trip (and an error log) for empty / clearly-non-IP input.\nconst LOOKS_LIKE_IP = /^[0-9a-fA-F:.]+$/;\n\n/**\n * The default, self-hosted provider: resolves an IP against the geo_blocks /\n * geo_names tables loaded from MaxMind/HE CSVs. The lookup is a CIDR\n * containment — the most-specific block that contains the address wins —\n * handling IPv4 and IPv6 uniformly via Postgres's native `cidr`/`inet`.\n */\nexport class PostgresGeoProvider implements IGeoProvider {\n\treadonly name = 'postgres';\n\n\tconstructor(private readonly store: Queryable) {}\n\n\tasync lookup(ip: string): Promise<GeoLocation | null> {\n\t\tconst addr = (ip ?? '').trim();\n\t\tif (!addr || addr.length > 45 || !LOOKS_LIKE_IP.test(addr)) return null;\n\t\ttry {\n\t\t\tconst rows = await this.store.query<{\n\t\t\t\tcountry_iso: string | null;\n\t\t\t\tcountry_name: string | null;\n\t\t\t\tsubdivision_iso: string | null;\n\t\t\t\tsubdivision_name: string | null;\n\t\t\t\tcity_name: string | null;\n\t\t\t\tcontinent_code: string | null;\n\t\t\t\ttime_zone: string | null;\n\t\t\t\tlatitude: number | null;\n\t\t\t\tlongitude: number | null;\n\t\t\t\taccuracy_radius: number | null;\n\t\t\t}>(\n\t\t\t\t`SELECT n.country_iso, n.country_name, n.subdivision_iso, n.subdivision_name,\n\t\t\t\t        n.city_name, n.continent_code, n.time_zone,\n\t\t\t\t        b.latitude, b.longitude, b.accuracy_radius\n\t\t\t\t FROM geo_blocks b\n\t\t\t\t LEFT JOIN geo_names n ON n.geoname_id = b.geoname_id\n\t\t\t\t WHERE b.network >>= $1::inet\n\t\t\t\t ORDER BY masklen(b.network) DESC\n\t\t\t\t LIMIT 1`,\n\t\t\t\t[addr],\n\t\t\t);\n\t\t\tconst r = rows[0];\n\t\t\tif (!r) return null;\n\t\t\treturn {\n\t\t\t\tcountry: r.country_iso ?? null,\n\t\t\t\tcountryName: r.country_name ?? null,\n\t\t\t\tsubdivision: r.subdivision_iso ?? null,\n\t\t\t\tsubdivisionName: r.subdivision_name ?? null,\n\t\t\t\tcity: r.city_name ?? null,\n\t\t\t\tcontinent: r.continent_code ?? null,\n\t\t\t\ttimeZone: r.time_zone ?? null,\n\t\t\t\tlatitude: r.latitude != null ? Number(r.latitude) : null,\n\t\t\t\tlongitude: r.longitude != null ? Number(r.longitude) : null,\n\t\t\t\taccuracyRadius: r.accuracy_radius != null ? Number(r.accuracy_radius) : null,\n\t\t\t};\n\t\t} catch {\n\t\t\t// Invalid inet (bad cast) or a transient store error → unknown, not a throw.\n\t\t\treturn null;\n\t\t}\n\t}\n}\n","// Load MaxMind GeoLite2 City CSVs (the same files the prior arbinuity importer\n// used) into geo_blocks + geo_names. Hurricane Electric / other sources work\n// too as long as rows map to {network, geoname_id, lat, lng, accuracy} and\n// {geoname_id, country, subdivision, city}.\nimport { readFileSync } from 'node:fs';\nimport type { Queryable } from './types.js';\n\nexport interface BlockRow {\n\tnetwork: string;\n\tgeonameId: number | null;\n\tlatitude: number | null;\n\tlongitude: number | null;\n\taccuracyRadius: number | null;\n}\n\nexport interface NameRow {\n\tgeonameId: number;\n\tcontinentCode: string | null;\n\tcountryIso: string | null;\n\tcountryName: string | null;\n\tsubdivisionIso: string | null;\n\tsubdivisionName: string | null;\n\tcityName: string | null;\n\ttimeZone: string | null;\n}\n\n/** RFC4180-ish single-line parser: handles quoted fields, embedded commas, and\n * \"\" escaped quotes (MaxMind city names like \"Washington, D.C.\" need this). */\nexport function parseCsvLine(line: string): string[] {\n\tconst out: string[] = [];\n\tlet field = '';\n\tlet inQuotes = false;\n\tfor (let i = 0; i < line.length; i++) {\n\t\tconst c = line[i];\n\t\tif (inQuotes) {\n\t\t\tif (c === '\"') {\n\t\t\t\tif (line[i + 1] === '\"') { field += '\"'; i++; } else inQuotes = false;\n\t\t\t} else field += c;\n\t\t} else if (c === '\"') inQuotes = true;\n\t\telse if (c === ',') { out.push(field); field = ''; }\n\t\telse field += c;\n\t}\n\tout.push(field);\n\treturn out;\n}\n\nconst num = (s: string | undefined): number | null => {\n\tif (s == null || s === '') return null;\n\tconst n = Number(s);\n\treturn Number.isFinite(n) ? n : null;\n};\nconst str = (s: string | undefined): string | null => (s == null || s === '' ? null : s);\n\n/** Parse a GeoLite2-City-Blocks-IPv4/IPv6 CSV (header row skipped). Columns:\n * network, geoname_id, registered_country_geoname_id, represented_country_geoname_id,\n * is_anonymous_proxy, is_satellite_provider, postal_code, latitude, longitude, accuracy_radius. */\nexport function parseBlocksCsv(text: string): BlockRow[] {\n\tconst rows: BlockRow[] = [];\n\tconst lines = text.split(/\\r?\\n/);\n\tfor (let i = 1; i < lines.length; i++) {\n\t\tconst line = lines[i];\n\t\tif (!line) continue;\n\t\tconst c = parseCsvLine(line);\n\t\tif (!c[0]) continue;\n\t\trows.push({\n\t\t\tnetwork: c[0],\n\t\t\tgeonameId: num(c[1]),\n\t\t\tlatitude: num(c[7]),\n\t\t\tlongitude: num(c[8]),\n\t\t\taccuracyRadius: num(c[9]),\n\t\t});\n\t}\n\treturn rows;\n}\n\n/** Parse a GeoLite2-City-Locations-<locale> CSV (header row skipped). Columns:\n * geoname_id, locale_code, continent_code, continent_name, country_iso_code,\n * country_name, subdivision_1_iso_code, subdivision_1_name, subdivision_2_iso_code,\n * subdivision_2_name, city_name, metro_code, time_zone, is_in_european_union. */\nexport function parseLocationsCsv(text: string): NameRow[] {\n\tconst rows: NameRow[] = [];\n\tconst lines = text.split(/\\r?\\n/);\n\tfor (let i = 1; i < lines.length; i++) {\n\t\tconst line = lines[i];\n\t\tif (!line) continue;\n\t\tconst c = parseCsvLine(line);\n\t\tconst id = num(c[0]);\n\t\tif (id == null) continue;\n\t\trows.push({\n\t\t\tgeonameId: id,\n\t\t\tcontinentCode: str(c[2]),\n\t\t\tcountryIso: str(c[4]),\n\t\t\tcountryName: str(c[5]),\n\t\t\tsubdivisionIso: str(c[6]),\n\t\t\tsubdivisionName: str(c[7]),\n\t\t\tcityName: str(c[10]),\n\t\t\ttimeZone: str(c[12]),\n\t\t});\n\t}\n\treturn rows;\n}\n\nconst CHUNK = 500;\n\nasync function insertChunked<T>(\n\tstore: Queryable,\n\trows: T[],\n\tcols: number,\n\tsqlHead: string,\n\ttoParams: (r: T) => unknown[],\n): Promise<number> {\n\tlet n = 0;\n\tfor (let i = 0; i < rows.length; i += CHUNK) {\n\t\tconst batch = rows.slice(i, i + CHUNK);\n\t\tconst values = batch\n\t\t\t.map((_, b) => `(${Array.from({ length: cols }, (_, k) => `$${b * cols + k + 1}`).join(', ')})`)\n\t\t\t.join(', ');\n\t\tconst params = batch.flatMap(toParams);\n\t\tawait store.query(`${sqlHead} VALUES ${values}`, params);\n\t\tn += batch.length;\n\t}\n\treturn n;\n}\n\nexport async function ingestNames(store: Queryable, rows: NameRow[]): Promise<number> {\n\treturn insertChunked(\n\t\tstore,\n\t\trows,\n\t\t8,\n\t\t`INSERT INTO geo_names (geoname_id, continent_code, country_iso, country_name, subdivision_iso, subdivision_name, city_name, time_zone)`,\n\t\t(r) => [r.geonameId, r.continentCode, r.countryIso, r.countryName, r.subdivisionIso, r.subdivisionName, r.cityName, r.timeZone],\n\t).then(async (c) => {\n\t\t// geo_names is a PK table; a re-run would conflict. Caller truncates first\n\t\t// for a full reload; this keeps ingest itself simple and idempotent-free.\n\t\treturn c;\n\t});\n}\n\nexport async function ingestBlocks(store: Queryable, rows: BlockRow[]): Promise<number> {\n\treturn insertChunked(\n\t\tstore,\n\t\trows,\n\t\t5,\n\t\t`INSERT INTO geo_blocks (network, geoname_id, latitude, longitude, accuracy_radius)`,\n\t\t(r) => [r.network, r.geonameId, r.latitude, r.longitude, r.accuracyRadius],\n\t);\n}\n\n/** Full load from MaxMind City CSV files. Truncates first so a reload is a\n * clean replace (the dataset is a full snapshot, not a delta). */\nexport async function loadMaxMindCity(\n\tstore: Queryable,\n\tfiles: { locationsPath: string; blocksV4Path?: string; blocksV6Path?: string },\n): Promise<{ names: number; blocks: number }> {\n\tawait store.query('TRUNCATE geo_blocks');\n\tawait store.query('TRUNCATE geo_names');\n\tconst names = await ingestNames(store, parseLocationsCsv(readFileSync(files.locationsPath, 'utf8')));\n\tlet blocks = 0;\n\tfor (const p of [files.blocksV4Path, files.blocksV6Path]) {\n\t\tif (p) blocks += await ingestBlocks(store, parseBlocksCsv(readFileSync(p, 'utf8')));\n\t}\n\treturn { names, blocks };\n}\n"],"mappings":"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","names":["_"]}

package/dist/migrations/index.d.ts

@@ -0,0 +1,3 @@
+declare const getMigrationsPath: () => string;
+
+export { getMigrationsPath };

package/dist/migrations/index.js

@@ -0,0 +1,7 @@
+// src/migrations/index.ts
+import { createMigrationsPath } from "@fonderie/store";
+var getMigrationsPath = () => createMigrationsPath(import.meta.url);
+export {
+  getMigrationsPath
+};
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/migrations/index.ts"],"sourcesContent":["import { createMigrationsPath } from '@fonderie/store';\n\nexport const getMigrationsPath = (): string => createMigrationsPath(import.meta.url);\n"],"mappings":";AAAA,SAAS,4BAA4B;AAE9B,IAAM,oBAAoB,MAAc,qBAAqB,YAAY,GAAG;","names":[]}

package/dist/migrations/sql/001_geo.sql

@@ -0,0 +1,40 @@
+-- ----------------------------------------------------------------------------
+-- 001_geo
+-- ----------------------------------------------------------------------------
+-- Self-hosted IP → location. Two tables, loaded from MaxMind GeoLite2 (or
+-- Hurricane Electric) City CSVs by the ingest command:
+--
+--   geo_blocks — one row per CIDR block (`network`), pointing at a geoname_id,
+--                with the block's own lat/lng/accuracy.
+--   geo_names  — the human-readable location for a geoname_id (country,
+--                subdivision, city), denormalized for a single-join lookup.
+--
+-- Stored as native `cidr`, so ONE table holds IPv4 AND IPv6 and the lookup is
+-- a range-contains — `WHERE network >>= $ip::inet ORDER BY masklen(network)
+-- DESC LIMIT 1` (the most-specific block wins). The GiST `inet_ops` index makes
+-- that containment fast; it ships in core Postgres (>= 9.4), no extension.
+-- ----------------------------------------------------------------------------
+
+CREATE TABLE IF NOT EXISTS geo_names (
+	geoname_id        BIGINT PRIMARY KEY,
+	continent_code    TEXT,
+	country_iso       TEXT,          -- ISO-3166-1 alpha-2
+	country_name      TEXT,
+	subdivision_iso   TEXT,          -- ISO-3166-2 (state/region), if any
+	subdivision_name  TEXT,
+	city_name         TEXT,
+	time_zone         TEXT
+);
+
+CREATE TABLE IF NOT EXISTS geo_blocks (
+	network           CIDR   NOT NULL,  -- IPv4 or IPv6 block
+	geoname_id        BIGINT,           -- FK-by-value into geo_names (nullable: MaxMind has blocks with no city)
+	latitude          DOUBLE PRECISION,
+	longitude         DOUBLE PRECISION,
+	accuracy_radius   INTEGER
+);
+
+-- Containment lookup: which block(s) contain this address? inet_ops GiST
+-- supports the >>= operator; masklen() then picks the most specific.
+CREATE INDEX IF NOT EXISTS idx_geo_blocks_network ON geo_blocks USING gist (network inet_ops);
+CREATE INDEX IF NOT EXISTS idx_geo_blocks_geoname ON geo_blocks (geoname_id);

package/package.json

@@ -0,0 +1,74 @@
+{
+	"name": "@fonderie/geo",
+	"version": "0.1.0",
+	"fonderie": { "stability": "experimental" },
+	"description": "Self-hosted IP → location. Provider-abstracted (IGeoProvider); the default resolves against a Postgres table of MaxMind/Hurricane-Electric CIDR blocks using native inet/GiST — IPv4 and IPv6, no external API, no key shipped. A signal source for @fonderie/risk and a day-one 'where did this request come from' for any Fonderie app.",
+	"keywords": [
+		"fonderiejs",
+		"geoip",
+		"geolocation",
+		"ip",
+		"maxmind",
+		"risk",
+		"saas",
+		"typescript"
+	],
+	"license": "MIT",
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		},
+		"./migrations": {
+			"types": "./dist/migrations/index.d.ts",
+			"import": "./dist/migrations/index.js"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsup && tsup --config tsup.migrations.ts",
+		"dev": "tsup --watch",
+		"typecheck": "tsc --noEmit",
+		"test": "tsx --test src/__tests__/*.test.ts",
+		"lint": "biome lint src",
+		"format": "biome format --write src",
+		"check": "biome check --write src"
+	},
+	"peerDependencies": {
+		"@fonderie/core": "^0.10.0",
+		"@fonderie/store": "^0.3.0"
+	},
+	"devDependencies": {
+		"@fonderie/core": "../core",
+		"@fonderie/store": "../store",
+		"@types/node": "^26.4.1",
+		"tsup": "^8.5.1",
+		"tsx": "^4.23.13",
+		"typescript": "^6.0.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"brain",
+		"LICENSE",
+		"README.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fonderiejs/fonderie.git",
+		"directory": "packages/geo"
+	},
+	"homepage": "https://github.com/fonderiejs/fonderie/tree/main/packages/geo#readme",
+	"bugs": {
+		"url": "https://github.com/fonderiejs/fonderie/issues"
+	}
+}