@nspot/geo-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NSpot Games
+
+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,190 @@
+# @nspot/geo-engine
+
+Region membership for your own PostGIS tables, as a library. `@nspot/geo-engine` installs
+the `geo` schema into any Postgres 14+ database with PostGIS, registers any table that has a
+row id and a geometry (or a lng/lat pair) so it gets a maintained region-membership cache,
+installs portable "region pack" JSON documents (countries + regions you can move between
+databases), and gives you typed query helpers plus a `geo-engine` CLI for all of the above.
+It has no dependency on the rest of this monorepo — `@geo/shared` and `@geo/db` in this repo
+are themselves built on top of it.
+
+## Install
+
+```bash
+npm i @nspot/geo-engine pg
+```
+
+The package is ESM-only (`import`, no `require`) and needs Node 20 or newer.
+
+`pg` is a peer-ish runtime dependency: every function here takes a `pg.Pool` or
+`pg.PoolClient` as its first argument (typed as `Queryable`) and you own the connection.
+
+## Quick start
+
+**1. Apply the schema.**
+
+```ts
+import pg from "pg";
+import { migrate } from "@nspot/geo-engine";
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+await migrate(pool);
+```
+
+**2. Register one of your own tables.**
+
+```ts
+import { registerSource } from "@nspot/geo-engine";
+
+await registerSource(pool, {
+  name: "hotels",
+  table: "public.hotels",
+  idColumn: "id",
+  geometry: { lng: "lng", lat: "lat" },
+});
+```
+
+This installs a row trigger that keeps `hotels` rows matched against every region as rows
+or regions change, and computes the initial memberships.
+
+**3. Install a region pack.**
+
+```ts
+import { installPack } from "@nspot/geo-engine";
+
+await installPack(pool, "https://example.com/packs/romania-1.0.0.json");
+```
+
+`installPack` also accepts a file path or an already-parsed pack object.
+
+**4. Filter your own query by region.**
+
+```ts
+import { inRegions } from "@nspot/geo-engine";
+
+const frag = inRegions(
+  "hotels",
+  { regions: ["transilvania"], exclude: ["sibiu"] },
+  { column: "h.id", idType: "int", offset: 1 }, // $1 is already used below
+);
+
+const { rows } = await pool.query(
+  `SELECT h.* FROM hotels h WHERE h.price < $1 AND ${frag.text}`,
+  [100, ...frag.values],
+);
+```
+
+`offset` shifts the fragment's own placeholders (`$2`-`$5` here) past any you already used
+in the surrounding statement; `frag.values` must be appended in the same order.
+
+**5. Look up the regions covering one row.**
+
+```ts
+import { regionsOf } from "@nspot/geo-engine";
+
+const regions = await regionsOf(pool, "hotels", 42);
+```
+
+`query.ts` also exports `notInRegions` (rows in none of the listed regions, including rows
+in no region at all), `ids` (external ids matching a filter, without writing SQL yourself)
+and `regionsAt(db, lng, lat)` (regions covering a point).
+
+`notInRegions` builds a SQL `NOT IN`, which is null-propagating: if the `column` you give it
+can be NULL — a LEFT JOINed id, for example — the predicate is NULL rather than true for
+that row and the row does not come back. Add an explicit `OR <column> IS NULL` when you want
+those rows too.
+
+**Trust model for `FragmentOptions.column`.** `column` (and `idType`) are interpolated into
+the fragment's SQL verbatim: they are raw SQL authored by you, not values. Never build them
+from request input — use a literal, or pick from a fixed list in your own code. Only
+`source`, the region slugs and the exclusions travel as bound parameters. `idType` is
+additionally checked against a plain-identifier pattern and rejected with
+`GeoEngineError("invalid_input", …)` when it is anything else.
+
+## CLI
+
+The package ships a `geo-engine` bin (run it with `npx geo-engine …`, `pnpm dlx geo-engine …`,
+or from a workspace with `pnpm exec geo-engine …`):
+
+```
+usage: geo-engine <command> [options]
+
+  check                                   list objects in public that would block a fresh install
+  migrate                                 apply pending migrations
+  register --name N --table [S.]T --id C (--geometry G | --lng X --lat Y)
+  unregister --name N
+  rebuild [--source N]                    recompute memberships (one source or all)
+  pack install <url|file>
+  pack list
+  pack uninstall <slug>
+
+Connection: DATABASE_URL or --url.
+```
+
+Every command reads `DATABASE_URL` from the environment, or takes an explicit `--url`.
+
+## Errors
+
+Every failure raised by this package is a `GeoEngineError` (`instanceof Error`) — with no
+exceptions: validation done before the database is reached raises one too. Each carries a
+stable `code`, plus the raw Postgres `sqlState` and `detail` when the failure came from the
+database, and `cause` when it wraps something else (a zod `ZodError`, a fetch failure, an
+`fs` error):
+
+| code             | when                                                                              |
+| ---------------- | ---------------------------------------------------------------------------------- |
+| `invalid_input`  | Postgres rejected a value (`22023`) — e.g. a malformed geometry or invalid enum value |
+| `invalid_input`  | `idType` is not a plain SQL type name (`inRegions` / `notInRegions`), raised before any SQL is built |
+| `invalid_input`  | `filter.regions` is empty in `inRegions` / `ids`, raised before the database is touched |
+| `invalid_input`  | `installPack` could not download, read or JSON-parse the pack (`cause` is the underlying error) |
+| `invalid_input`  | the pack document failed validation — `Invalid pack document: <path>: <issue>; …`, `cause` is the `ZodError` |
+| `invalid_input`  | `migrate` found a database whose schema is newer than the one this package ships   |
+| `unknown_source` | the request named a source that isn't registered                                  |
+| `conflict`       | a unique-key violation (`23505`) — e.g. registering a name or pack slug that already exists |
+| `invalid_source` | the registered table or column doesn't exist (`42P01` / `42703`)                  |
+| `database`       | any other Postgres error                                                          |
+
+`installPack` aborts an `http(s)` download after 30 seconds; pass `{ timeoutMs }` to change
+that.
+
+## Prerequisites and reserved names
+
+PostgreSQL 14+ with PostGIS installed (any schema — Supabase's `extensions`, for example).
+While `migrate` applies the migrations, the connecting role's `search_path` must include the
+PostGIS schema; after that, every `geo` function pins its own `search_path`, so only
+`geom_expr` fragments you pass to `registerSource` need to qualify any non-PostGIS functions
+they call. A fresh install also refuses to run if certain names already exist in `public`
+(`findReservedPublicObjects(db)` checks this ahead of time). See "Installing into your own
+database" in the
+[repo README](https://github.com/NSpot-Games/geo-engine#installing-into-your-own-database)
+for the full explanation, the exact reserved names, and the refusal message.
+
+## The `geom_expr` trust model
+
+The geometry expression you pass to `registerSource` (a raw geometry column name, or the
+lng/lat pair used to build one) is stored in `geo.sources` and evaluated later, inside the
+membership triggers and `rebuildMemberships`, with the privileges of whichever role is
+writing rows or editing regions at that moment. Registering a source is as powerful as
+writing a trigger by hand — only let database administrators call `registerSource` /
+`unregisterSource` (the underlying `geo.register_source` / `geo.unregister_source` are not
+executable by PUBLIC).
+
+## Releasing
+
+`pnpm sdk:rehearsal` (from the repo root) packs the SDK and installs it into a throwaway
+project against a scratch database; run it before every release.
+
+To cut a release: bump `version` in `packages/sdk-node/package.json`, run
+`pnpm sdk:rehearsal` and confirm it passes, commit the version bump, tag the commit
+`sdk-node-v<version>` (e.g. `sdk-node-v0.1.0`), and push the tag. Pushing a tag matching
+`sdk-node-v*` runs `.github/workflows/publish-sdk.yml`, which checks the tag against
+`package.json`'s version, builds the package, runs the full SDK test suite against a
+PostGIS service container, and publishes to npm with provenance.
+
+One-time setup, before the first release: create the `@nspot` organisation on npm,
+generate an automation token scoped to it, and add that token as the repository secret
+`NPM_TOKEN`. Without the secret the workflow is not inert: pushing a matching tag still
+runs it, and it goes all the way through the checks, build and tests before failing at
+the publish step. Add the secret before pushing the first tag.
+
+A Python SDK does not exist yet.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import pg from "pg";
+import { GeoEngineError, findReservedPublicObjects, installPack, listPacks, migrate, rebuildMemberships, registerSource, uninstallPack, unregisterSource, } from "./index.js";
+const USAGE = `usage: geo-engine <command> [options]
+
+  check                                   list objects in public that would block a fresh install
+  migrate                                 apply pending migrations
+  register --name N --table [S.]T --id C (--geometry G | --lng X --lat Y)
+  unregister --name N
+  rebuild [--source N]                    recompute memberships (one source or all)
+  pack install <url|file>
+  pack list
+  pack uninstall <slug>
+
+Connection: DATABASE_URL or --url.`;
+class UsageError extends Error {
+}
+function usageError(message) {
+    throw new UsageError(message ? `${message}\n\n${USAGE}` : USAGE);
+}
+function need(v, flag) {
+    if (!v)
+        usageError(`missing --${flag}`);
+    return v;
+}
+function parseCliArgs() {
+    try {
+        return parseArgs({
+            allowPositionals: true,
+            options: {
+                url: { type: "string" },
+                name: { type: "string" },
+                table: { type: "string" },
+                id: { type: "string" },
+                geometry: { type: "string" },
+                lng: { type: "string" },
+                lat: { type: "string" },
+                source: { type: "string" },
+            },
+        });
+    }
+    catch (err) {
+        usageError(err instanceof Error ? err.message : String(err));
+    }
+}
+async function run() {
+    const { positionals, values } = parseCliArgs();
+    const command = positionals[0];
+    const known = ["check", "migrate", "register", "unregister", "rebuild", "pack"];
+    if (!command || !known.includes(command))
+        usageError(command ? `unknown command: ${command}` : undefined);
+    const url = values.url ?? process.env.DATABASE_URL;
+    if (!url)
+        usageError("missing --url (or set DATABASE_URL)");
+    const pool = new pg.Pool({ connectionString: url });
+    try {
+        if (command === "check") {
+            const conflicts = await findReservedPublicObjects(pool);
+            if (conflicts.length === 0)
+                console.log("no reserved objects in public");
+            else {
+                console.log(conflicts.join(", "));
+                process.exitCode = 1;
+            }
+        }
+        else if (command === "migrate") {
+            await migrate(pool, { log: (m) => console.log(m.replace(/^applied migration /, "applied ")) });
+            console.log("migrations up to date");
+        }
+        else if (command === "register") {
+            const name = need(values.name, "name");
+            const table = need(values.table, "table");
+            const id = need(values.id, "id");
+            if (values.geometry && (values.lng || values.lat))
+                usageError("provide either --geometry or --lng/--lat, not both");
+            if (!values.geometry && !(values.lng && values.lat))
+                usageError("provide --geometry, or both --lng and --lat");
+            const geometry = values.geometry ?? { lng: values.lng, lat: values.lat };
+            const s = await registerSource(pool, { name, table, idColumn: id, geometry });
+            console.log(`registered ${s.name} (${s.table_schema}.${s.table_name}, id ${s.id_column} ${s.id_type})`);
+        }
+        else if (command === "unregister") {
+            const name = need(values.name, "name");
+            await unregisterSource(pool, name);
+            console.log(`unregistered ${name}`);
+        }
+        else if (command === "rebuild") {
+            const n = await rebuildMemberships(pool, values.source);
+            console.log(`rebuilt ${n} memberships`);
+        }
+        else if (command === "pack") {
+            const sub = positionals[1];
+            if (sub === "install") {
+                const source = positionals[2] ?? usageError("usage: geo-engine pack install <url|file>");
+                const r = await installPack(pool, source);
+                console.log(`installed ${r.pack}@${r.version}: ${r.regions} regions, ${r.countries} countries, ${r.memberships} memberships`);
+            }
+            else if (sub === "list") {
+                const packs = await listPacks(pool);
+                if (packs.length === 0)
+                    console.log("no packs installed");
+                else
+                    for (const p of packs)
+                        console.log(`${p.slug}  ${p.version}  ${p.region_count} regions  ${p.installed_at}`);
+            }
+            else if (sub === "uninstall") {
+                const slug = positionals[2] ?? usageError("usage: geo-engine pack uninstall <slug>");
+                const n = await uninstallPack(pool, slug);
+                console.log(`removed ${n} regions of ${slug}`);
+            }
+            else {
+                usageError(sub ? `unknown pack subcommand: ${sub}` : "usage: geo-engine pack <install|list|uninstall>");
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError)
+            throw err;
+        const message = err instanceof GeoEngineError || err instanceof Error ? err.message : String(err);
+        console.error(message);
+        process.exitCode = 1;
+    }
+    finally {
+        await pool.end();
+    }
+}
+run().catch((err) => {
+    if (err instanceof UsageError) {
+        console.error(err.message);
+        process.exitCode = 2;
+    }
+    else {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+});

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+import type { Queryable } from "./migrate.js";
+export type GeoEngineErrorCode = "invalid_input" | "unknown_source" | "conflict" | "invalid_source" | "database";
+/** Every failure raised by this package. `sqlState` is the Postgres error code when there was one. */
+export declare class GeoEngineError extends Error {
+    name: string;
+    readonly code: GeoEngineErrorCode;
+    readonly sqlState?: string;
+    readonly detail?: string;
+    constructor(code: GeoEngineErrorCode, message: string, opts?: {
+        sqlState?: string;
+        detail?: string;
+        cause?: unknown;
+    });
+}
+export declare function wrapPgError(err: unknown): GeoEngineError;
+/** Run one parameterised statement and return its rows, translating failures. */
+export declare function run<T>(db: Queryable, text: string, values?: unknown[]): Promise<T[]>;

package/dist/errors.js

@@ -0,0 +1,41 @@
+/** Every failure raised by this package. `sqlState` is the Postgres error code when there was one. */
+export class GeoEngineError extends Error {
+    name = "GeoEngineError";
+    code;
+    sqlState;
+    detail;
+    constructor(code, message, opts = {}) {
+        super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
+        this.code = code;
+        this.sqlState = opts.sqlState;
+        this.detail = opts.detail;
+    }
+}
+const BY_STATE = {
+    "22023": "invalid_input",
+    "23505": "conflict",
+    "42P01": "invalid_source",
+    "42703": "invalid_source",
+};
+export function wrapPgError(err) {
+    if (err instanceof GeoEngineError)
+        return err;
+    const e = err;
+    const sqlState = typeof e?.code === "string" ? e.code : undefined;
+    const message = typeof e?.message === "string" ? e.message : String(err);
+    const detail = typeof e?.detail === "string" ? e.detail : undefined;
+    let code = (sqlState && BY_STATE[sqlState]) || "database";
+    if (code === "invalid_input" && /^Unknown source/.test(message))
+        code = "unknown_source";
+    return new GeoEngineError(code, message, { sqlState, detail, cause: err });
+}
+/** Run one parameterised statement and return its rows, translating failures. */
+export async function run(db, text, values = []) {
+    try {
+        const { rows } = await db.query(text, values);
+        return rows;
+    }
+    catch (err) {
+        throw wrapPgError(err);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./paths.js";
+export * from "./migrate.js";
+export * from "./sources.js";
+export * from "./packs.js";
+export * from "./errors.js";
+export * from "./query.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./paths.js";
+export * from "./migrate.js";
+export * from "./sources.js";
+export * from "./packs.js";
+export * from "./errors.js";
+export * from "./query.js";

package/dist/migrate.d.ts

@@ -0,0 +1,14 @@
+import pg from "pg";
+export type { Pool, PoolClient } from "pg";
+export type Queryable = pg.Pool | pg.PoolClient;
+export interface MigrateOptions {
+    log?: (msg: string) => void;
+    /** Directory of *.sql migration files; defaults to the files shipped with this package. */
+    sqlDir?: string;
+}
+/** Objects in `public` whose names a fresh geo-engine install would take over. */
+export declare function findReservedPublicObjects(db: Queryable): Promise<string[]>;
+/** Apply pending migrations in filename order. Returns the file names applied by this call. */
+export declare function migrate(db: Queryable, opts?: MigrateOptions): Promise<string[]>;
+/** Highest applied migration number, 0 before the first install. */
+export declare function schemaVersion(db: Queryable): Promise<number>;

package/dist/migrate.js

@@ -0,0 +1,128 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { GeoEngineError, run, wrapPgError } from "./errors.js";
+import { SQL_DIR } from "./paths.js";
+/**
+ * Names 001/002 create in `public` and 003 then moves into `geo` (or drops).
+ * A host database that already owns any of them would have its own objects
+ * hijacked or dropped by a fresh install, so we refuse to start.
+ * `schema_migrations` is deliberately absent: that one is ours. The demo
+ * table (`locations` and friends) is no longer part of this core set: it is
+ * applied separately by @geo/db from packages/db/sql-demo.
+ */
+const RESERVED_PUBLIC_TYPES = ["region_type"];
+const RESERVED_PUBLIC_TABLES = ["countries", "regions"];
+const RESERVED_PUBLIC_FUNCTIONS = [
+    "geom_from_geojson_area",
+    "set_updated_at",
+    "upsert_country",
+    "upsert_region",
+    "derive_country_geom",
+    "regions_at_point",
+];
+/** Migration number encoded in a file name (`006_search_path.sql` → 6); 0 when absent. */
+function migrationNumber(name) {
+    const n = Number.parseInt(name.split("_", 1)[0], 10);
+    return Number.isFinite(n) ? n : 0;
+}
+/** Objects in `public` whose names a fresh geo-engine install would take over. */
+export async function findReservedPublicObjects(db) {
+    const rows = await run(db, `SELECT t.typname AS name
+       FROM pg_type t JOIN pg_namespace n ON n.oid = t.typnamespace
+      WHERE n.nspname = 'public' AND t.typname = ANY($1::text[])
+     UNION
+     SELECT c.relname
+       FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = 'public' AND c.relname = ANY($2::text[])
+     UNION
+     SELECT p.proname
+       FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace
+      WHERE n.nspname = 'public' AND p.proname = ANY($3::text[])
+     ORDER BY 1`, [RESERVED_PUBLIC_TYPES, RESERVED_PUBLIC_TABLES, RESERVED_PUBLIC_FUNCTIONS]);
+    return rows.map((r) => r.name);
+}
+/** Apply pending migrations in filename order. Returns the file names applied by this call. */
+export async function migrate(db, opts = {}) {
+    const log = opts.log ?? (() => { });
+    const sqlDir = opts.sqlDir ?? SQL_DIR;
+    const applied = [];
+    // One connection for the whole run: BEGIN / set_config / body / COMMIT must not be
+    // scattered over different connections of a pool.
+    //
+    // `db instanceof pg.Pool` would be wrong here: a host application can easily end up with
+    // a second copy of `pg` in its tree (a different version resolved for another dependency,
+    // a bundled build, a pool subclass from a wrapper library), and a Pool created from that
+    // copy is not `instanceof` *this* module's `pg.Pool` — it would be mistaken for a
+    // PoolClient and `client.release()` would be missing. Duck-type on the one member that
+    // actually differs: a `PoolClient` has `release`, a `Pool` does not. A bare `pg.Client`
+    // is not a `Queryable` and is not supported here: pass a Pool or a checked-out PoolClient.
+    const isClient = typeof db.release === "function";
+    const client = isClient ? db : await db.connect();
+    try {
+        await client.query("CREATE SCHEMA IF NOT EXISTS geo");
+        // databases migrated before the geo schema existed keep their history in public
+        await client.query(`
+      DO $$ BEGIN
+        IF to_regclass('public.schema_migrations') IS NOT NULL AND to_regclass('geo.schema_migrations') IS NULL THEN
+          ALTER TABLE public.schema_migrations SET SCHEMA geo;
+        END IF;
+      END $$`);
+        await client.query(`
+      CREATE TABLE IF NOT EXISTS geo.schema_migrations (
+        name text PRIMARY KEY,
+        applied_at timestamptz NOT NULL DEFAULT now()
+      )`);
+        const files = (await readdir(sqlDir)).filter((f) => f.endsWith(".sql")).sort();
+        const { rows } = await client.query("SELECT name FROM geo.schema_migrations");
+        const alreadyApplied = new Set(rows.map((r) => r.name));
+        // A database migrated by a newer @nspot/geo-engine may contain objects this copy does
+        // not know about; applying our (older) files on top would be at best a no-op and at
+        // worst a downgrade, so refuse rather than guess.
+        const dbMax = [...alreadyApplied].reduce((max, name) => Math.max(max, migrationNumber(name)), 0);
+        const sdkMax = files.reduce((max, name) => Math.max(max, migrationNumber(name)), 0);
+        if (dbMax > sdkMax) {
+            throw new GeoEngineError("invalid_input", `Database schema version ${dbMax} is newer than this package's ${sdkMax}; upgrade @nspot/geo-engine`);
+        }
+        if (alreadyApplied.size === 0) {
+            const conflicts = await findReservedPublicObjects(client);
+            if (conflicts.length > 0) {
+                throw new GeoEngineError("invalid_input", `Refusing to install: these objects already exist in schema public and would be taken over by the geo-engine migrations: ${conflicts.join(", ")}. Rename or drop them, or install geo-engine into a separate database.`);
+            }
+        }
+        for (const file of files) {
+            if (alreadyApplied.has(file))
+                continue;
+            const sql = await readFile(path.join(sqlDir, file), "utf8");
+            await client.query("BEGIN");
+            try {
+                // unqualified DDL in 001/002 must land in public even when the role's name matches
+                // a schema (the dev role is `geo`); keep the rest of the path so PostGIS resolves
+                // wherever the host installed it
+                await client.query("SELECT set_config('search_path', 'public, ' || current_setting('search_path'), true)");
+                await client.query(sql);
+                await client.query("INSERT INTO geo.schema_migrations (name) VALUES ($1)", [file]);
+                await client.query("COMMIT");
+                applied.push(file);
+                log(`applied migration ${file}`);
+            }
+            catch (err) {
+                await client.query("ROLLBACK");
+                throw err;
+            }
+        }
+    }
+    catch (err) {
+        // every failure leaving this package is a GeoEngineError
+        throw wrapPgError(err);
+    }
+    finally {
+        if (!isClient)
+            client.release();
+    }
+    return applied;
+}
+/** Highest applied migration number, 0 before the first install. */
+export async function schemaVersion(db) {
+    const rows = await run(db, "SELECT coalesce(max(split_part(name, '_', 1)::int), 0)::int AS v FROM geo.schema_migrations");
+    return rows[0].v;
+}

package/dist/packs.d.ts

@@ -0,0 +1,14 @@
+import type { Queryable } from "./migrate.js";
+import { type InstallPackResult, type Pack, type PackInfo } from "./types.js";
+export interface InstallPackOptions {
+    /** Override for tests; defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** Abort an http(s) pack download after this many milliseconds; defaults to 30000. */
+    timeoutMs?: number;
+}
+export declare function exportPack(db: Queryable, slug: string, version: string): Promise<Pack>;
+/** Install a pack given as a parsed document, a file path, or an http(s) URL. */
+export declare function installPack(db: Queryable, source: Pack | string, opts?: InstallPackOptions): Promise<InstallPackResult>;
+/** Removes the pack's regions and the pack row; returns how many regions were removed. */
+export declare function uninstallPack(db: Queryable, slug: string): Promise<number>;
+export declare function listPacks(db: Queryable): Promise<PackInfo[]>;

package/dist/packs.js

@@ -0,0 +1,73 @@
+import { readFile } from "node:fs/promises";
+import { GeoEngineError, run } from "./errors.js";
+import { packSchema } from "./types.js";
+const DEFAULT_TIMEOUT_MS = 30_000;
+export async function exportPack(db, slug, version) {
+    const rows = await run(db, "SELECT geo.export_pack($1, $2) AS pack", [slug, version]);
+    return rows[0].pack;
+}
+/** Install a pack given as a parsed document, a file path, or an http(s) URL. */
+export async function installPack(db, source, opts = {}) {
+    const raw = typeof source === "string" ? await loadPack(source, opts) : source;
+    const doc = parsePack(raw);
+    const rows = await run(db, "SELECT geo.install_pack($1::jsonb) AS r", [JSON.stringify(doc)]);
+    return rows[0].r;
+}
+/** Validate a pack document, reporting every zod issue as one `invalid_input` message. */
+function parsePack(raw) {
+    const result = packSchema.safeParse(raw);
+    if (result.success)
+        return result.data;
+    const issues = result.error.issues
+        .map((i) => `${i.path.join(".") || "document"}: ${i.message}`)
+        .join("; ");
+    throw new GeoEngineError("invalid_input", `Invalid pack document: ${issues}`, { cause: result.error });
+}
+async function loadPack(source, opts) {
+    if (/^https?:\/\//i.test(source)) {
+        const fetchImpl = opts.fetch ?? fetch;
+        let res;
+        try {
+            res = await fetchImpl(source, { signal: AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) });
+        }
+        catch (cause) {
+            throw new GeoEngineError("invalid_input", `Failed to download pack from ${source}: ${messageOf(cause)}`, { cause });
+        }
+        if (!res.ok) {
+            throw new GeoEngineError("invalid_input", `Failed to download pack from ${source}: HTTP ${res.status}`);
+        }
+        try {
+            return await res.json();
+        }
+        catch (cause) {
+            throw new GeoEngineError("invalid_input", `Pack at ${source} is not valid JSON: ${messageOf(cause)}`, { cause });
+        }
+    }
+    let text;
+    try {
+        text = await readFile(source, "utf8");
+    }
+    catch (cause) {
+        throw new GeoEngineError("invalid_input", `Failed to read pack file ${source}: ${messageOf(cause)}`, { cause });
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch (cause) {
+        throw new GeoEngineError("invalid_input", `Pack file ${source} is not valid JSON: ${messageOf(cause)}`, { cause });
+    }
+}
+const messageOf = (err) => (err instanceof Error ? err.message : String(err));
+/** Removes the pack's regions and the pack row; returns how many regions were removed. */
+export async function uninstallPack(db, slug) {
+    const rows = await run(db, "SELECT geo.uninstall_pack($1) AS n", [slug]);
+    return rows[0].n;
+}
+export async function listPacks(db) {
+    const rows = await run(db, `
+    SELECT p.id, p.slug, p.version, p.schema_version, p.installed_at,
+           (SELECT count(*) FROM geo.regions r WHERE r.pack_id = p.id)::int AS region_count
+    FROM geo.packs p ORDER BY p.slug`);
+    // pg hands back a Date for timestamptz; PackInfo.installed_at is an ISO string
+    return rows.map((row) => ({ ...row, installed_at: new Date(row.installed_at).toISOString() }));
+}

package/dist/paths.d.ts

@@ -0,0 +1,4 @@
+/** Package root: works both from src/ (tsx) and dist/ (compiled). */
+export declare const PACKAGE_ROOT: string;
+/** The migration files shipped with this package (a copy of packages/db/sql). */
+export declare const SQL_DIR: string;