@fluid-app/exigo-connection-sdk 0.1.0

package/README.md

@@ -0,0 +1,190 @@
+# @fluid-app/exigo-connection-sdk
+
+One way for Fluid droplets and Mist apps to talk to Exigo: a REST client, a
+cached SQL pool, a credential interface and typed errors. The package owns
+connection, auth and errors only. Business queries stay in each app.
+
+## Install
+
+Public on npmjs:
+
+```bash
+pnpm add @fluid-app/exigo-connection-sdk
+# Only for apps that query the SQL replica:
+pnpm add mssql
+pnpm add -D @types/mssql
+```
+
+| Import                                 | Provides                                           | Needs `mssql` |
+| -------------------------------------- | -------------------------------------------------- | ------------- |
+| `@fluid-app/exigo-connection-sdk`      | `defineExigoCredentials`, credential types, errors | no            |
+| `@fluid-app/exigo-connection-sdk/rest` | `createExigoRestClient`, errors                    | no            |
+| `@fluid-app/exigo-connection-sdk/sql`  | `getExigoPool`, `closeExigoPool`, errors           | yes           |
+
+Runs on Node 20+: Cloud Run, and Vercel's Node runtime. Not on Edge.
+
+## 1. Credentials, once per app
+
+The package reads no environment variables and stores nothing. The app says
+where credentials come from; a missing field throws `ExigoCredentialsError`
+naming it.
+
+```ts
+// src/lib/exigo.ts — a multi-tenant droplet
+import { defineExigoCredentials } from "@fluid-app/exigo-connection-sdk";
+
+export const resolveExigoCredentials = defineExigoCredentials(
+  async (companyId: string) => {
+    const c = await prisma.credentials.findUniqueOrThrow({
+      where: { companyId },
+    });
+    return {
+      rest: {
+        baseUrl: c.exigoApiBaseUrl,
+        username: c.exigoApiUser,
+        password: c.exigoApiPassword,
+        company: c.exigoCompanyName,
+      },
+      sql: {
+        host: c.exigoDbHost,
+        database: c.exigoDbName,
+        username: c.exigoDbUsername,
+        password: c.exigoDbPassword,
+        // Required, no default: Exigo's replicas are Azure SQL, whose
+        // certificate does not match the host you connect to, so this must
+        // be true. It skips server certificate verification.
+        trustServerCertificate: true,
+      },
+    };
+  },
+);
+```
+
+A single-tenant Mist app returns its env vars from the same function instead.
+The resolver runs on every call, so cache in the app if the lookup is costly.
+
+## 2. REST
+
+```ts
+import {
+  createExigoRestClient,
+  ExigoAuthError,
+  ExigoTimeoutError,
+} from "@fluid-app/exigo-connection-sdk/rest";
+
+const { rest } = await resolveExigoCredentials(company.id);
+const exigo = createExigoRestClient(rest);
+
+try {
+  const account = await exigo.get<PointAccount>(
+    "/customers/{id}/pointaccounts/{accountId}",
+    { params: { id: customerId, accountId: pointAccountId } },
+  );
+} catch (error) {
+  if (error instanceof ExigoAuthError) {
+    /* wrong credentials: tell the admin */
+  }
+  if (error instanceof ExigoTimeoutError) {
+    /* retry, or fail the callback fast */
+  }
+  throw error;
+}
+```
+
+The client:
+
+- adds `/3.0` to the base URL, and does not double it when the stored URL
+  already has it; a base URL ending in another version, such as `/2.0`, throws
+  `ExigoCredentialsError` rather than pinning the client to it;
+- requires an `https` base URL, since every request carries the password
+  (`http` only for `localhost`, for a local stub);
+- sends Basic auth as `username@company`;
+- times out after 15 s by default (`timeoutMs` on the client or per call, at
+  most 2,147,483,647 ms, the most `setTimeout` can hold);
+- resolves to the parsed JSON, or `undefined` for an empty body;
+- throws `ExigoApiError` for a non-2xx status, and for a 200 whose body is an
+  HTML page or not JSON, rather than handing the page back as data; the
+  password and Basic token are redacted from its message and `bodySnippet`;
+- refuses a path that is an absolute URL, so the credentials only ever go to
+  the configured host, and a path that starts with an API version (`/3.0/...`),
+  since the client adds it;
+- refuses a path param that is empty, `.` or `..`, which would otherwise
+  resolve to a different endpoint than the path names.
+
+`get`, `delete` take `params`, `query`, `headers`, `timeoutMs` and `signal`;
+`post`, `put`, `patch` also take a `body`, sent as JSON.
+
+## 3. SQL
+
+```ts
+import { getExigoPool } from "@fluid-app/exigo-connection-sdk/sql";
+
+const { sql: creds } = await resolveExigoCredentials(company.id);
+const pool = await getExigoPool(creds);
+
+const { recordset } = await pool
+  .request()
+  .input("email", email)
+  .query("SELECT CustomerID FROM Customers WHERE Email = @email");
+```
+
+`getExigoPool` returns an `mssql` `ConnectionPool`, cached per host, port,
+database and username, and within that per password. Repeated calls reuse
+it, concurrent first calls share one connect, and a failed connect is not
+cached. A rotated password opens its own pool without closing the previous
+one, so requests in flight across a rotation keep working and a rollback
+connects at once; the previous pool is closed once nothing has asked for it
+in five minutes, and a database's current pool once nothing has asked for it
+in 30. Pools are small (4 connections, closed after 10 s idle) because every running instance opens its own. Pass
+`{ max, idleTimeoutMs, connectTimeoutMs, requestTimeoutMs }` as the second
+argument to change that; options apply when the pool opens.
+
+For typed parameters, import them from `mssql` itself
+(`import sql from "mssql"; request.input("id", sql.Int, id)`).
+
+Connect failures arrive as `ExigoAuthError`, `ExigoTimeoutError` or
+`ExigoConnectionError`, with messages that say what to check. Errors from the
+app's own queries are left alone; pass one through `translateExigoSqlError` to
+map a timeout or a dropped connection the same way. A query error (`RequestError`)
+comes back unchanged unless its code is a transport one (`ETIMEOUT`,
+`ECONNCLOSED`, `ESOCKET`), so a bad table name is never reported as a network
+failure.
+
+Close pools on shutdown:
+
+```ts
+import { closeAllExigoPools } from "@fluid-app/exigo-connection-sdk/sql";
+
+process.once("SIGTERM", () => void closeAllExigoPools());
+```
+
+In Next, keep `mssql` out of the bundle and off Edge:
+
+```ts
+// next.config.ts
+export default { serverExternalPackages: ["mssql"] };
+
+// every route that queries
+export const runtime = "nodejs";
+```
+
+## Errors
+
+Every error extends `ExigoError`. None of them carries a password or an
+Authorization header.
+
+| Error                   | When                                                  |
+| ----------------------- | ----------------------------------------------------- |
+| `ExigoCredentialsError` | a field is missing or invalid (`fields` names them)   |
+| `ExigoAuthError`        | REST 401/403, or a SQL login failure                  |
+| `ExigoTimeoutError`     | a REST call, SQL connect or SQL query ran too long    |
+| `ExigoConnectionError`  | DNS, refused connection, TLS, network                 |
+| `ExigoApiError`         | REST answered with an error or a body that isn't JSON |
+
+`source` is `"rest"` or `"sql"` on the auth, timeout and connection errors.
+
+## Releasing
+
+Listed in `.github/workflows/frontend-publish-rep-packages.yml`: a merge to
+`main` that changes this package publishes it to npm, bumping the patch
+version when the current one is already published.

package/dist/credentials.d.mts

@@ -0,0 +1,49 @@
+//#region src/credentials.d.ts
+interface ExigoRestCredentials {
+  /**
+  * The API host, such as `https://acme-api.exigo.com`. A trailing `/3.0` is
+  * accepted and not doubled; without one the client adds it.
+  */
+  readonly baseUrl: string;
+  readonly username: string;
+  readonly password: string;
+  /** The Exigo company name; Basic auth sends `username@company`. */
+  readonly company: string;
+}
+interface ExigoSqlCredentials {
+  readonly host: string;
+  readonly database: string;
+  readonly username: string;
+  readonly password: string;
+  /** Defaults to 1433. */
+  readonly port?: number;
+  /** Defaults to true. */
+  readonly encrypt?: boolean;
+  /**
+  * Required, with no default: whether to accept the server's certificate
+  * without verifying it. Exigo's replicas are Azure SQL, whose certificate
+  * does not match the host apps connect to, so they need `true`; that skips
+  * server identity checks, so each app makes the decision explicitly.
+  */
+  readonly trustServerCertificate: boolean;
+}
+/** What a resolver returns. An app includes the interfaces it uses. */
+interface ExigoCredentials {
+  readonly rest?: ExigoRestCredentials;
+  readonly sql?: ExigoSqlCredentials;
+}
+type ExigoCredentialResolver<Key, Credentials extends ExigoCredentials> = (key: Key) => Credentials | null | undefined | Promise<Credentials | null | undefined>;
+/** Throws `ExigoCredentialsError` naming every missing REST field. */
+declare function assertExigoRestCredentials(value: unknown): asserts value is ExigoRestCredentials;
+/** Throws `ExigoCredentialsError` naming every missing or invalid SQL field. */
+declare function assertExigoSqlCredentials(value: unknown): asserts value is ExigoSqlCredentials;
+/**
+* Wraps an app's credential lookup so every caller gets validated credentials.
+*
+* The resolver runs on every call; cache in the app if the lookup is costly.
+* Each interface the result includes is checked in full, and a result with
+* neither, or none at all, throws.
+*/
+declare function defineExigoCredentials<Key = string, Credentials extends ExigoCredentials = ExigoCredentials>(resolver: ExigoCredentialResolver<Key, Credentials>): (key: Key) => Promise<Credentials>;
+//#endregion
+export { ExigoCredentialResolver, ExigoCredentials, ExigoRestCredentials, ExigoSqlCredentials, assertExigoRestCredentials, assertExigoSqlCredentials, defineExigoCredentials };

package/dist/credentials.mjs

@@ -0,0 +1,92 @@
+import { ExigoCredentialsError } from "./errors.mjs";
+import { z } from "zod";
+//#region src/credentials.ts
+/**
+* The credential interface.
+*
+* The package never reads environment variables and stores nothing. Each app
+* supplies credentials, or a resolver that finds them: env in a single-tenant
+* Mist app, a table in a multi-tenant droplet. There is deliberately no
+* fallback — the `RAIN_*` fallback that pointed a droplet at another client's
+* Exigo came from exactly that — so a missing field throws.
+*/
+/** Present and not blank. Values from a database arrive as `null` when unset. */
+const requiredString = z.string().refine((value) => value.trim() !== "");
+const restCredentialsSchema = z.object({
+	baseUrl: requiredString,
+	username: requiredString,
+	password: requiredString,
+	company: requiredString
+});
+const sqlCredentialsSchema = z.object({
+	host: requiredString,
+	database: requiredString,
+	username: requiredString,
+	password: requiredString,
+	port: z.number().int().min(1).max(65535).optional(),
+	encrypt: z.boolean().optional(),
+	trustServerCertificate: z.boolean()
+});
+const REQUIRED_FIELDS = {
+	rest: Object.keys(restCredentialsSchema.shape),
+	sql: [
+		"host",
+		"database",
+		"username",
+		"password",
+		"trustServerCertificate"
+	]
+};
+/**
+* Validates one section and throws `ExigoCredentialsError` naming every field
+* at fault. Zod's own messages are never used: they can quote the value, and
+* these values are secrets.
+*/
+function assertSection(section, schema, value) {
+	const result = schema.safeParse(value);
+	if (result.success) return;
+	const missing = [];
+	const invalid = [];
+	const required = REQUIRED_FIELDS[section];
+	for (const issue of result.error.issues) {
+		const [field] = issue.path;
+		if (field === void 0) {
+			missing.push(...required.map((name) => `${section}.${name}`));
+			continue;
+		}
+		const name = `${section}.${String(field)}`;
+		const list = required.includes(String(field)) ? missing : invalid;
+		if (!list.includes(name)) list.push(name);
+	}
+	const label = `Exigo ${section.toUpperCase()} credentials`;
+	const parts = [missing.length > 0 ? `are missing ${missing.join(", ")}` : null, invalid.length > 0 ? `have an invalid ${invalid.join(", ")}` : null].filter((part) => part !== null);
+	const portHint = invalid.includes("sql.port") ? "; sql.port must be an integer from 1 to 65535" : "";
+	const trustHint = missing.includes("sql.trustServerCertificate") ? "; set sql.trustServerCertificate explicitly (Exigo's Azure SQL replicas need true, which skips certificate verification)" : "";
+	throw new ExigoCredentialsError(`${label} ${parts.join(" and ")}${portHint}${trustHint}.`, [...missing, ...invalid]);
+}
+/** Throws `ExigoCredentialsError` naming every missing REST field. */
+function assertExigoRestCredentials(value) {
+	assertSection("rest", restCredentialsSchema, value);
+}
+/** Throws `ExigoCredentialsError` naming every missing or invalid SQL field. */
+function assertExigoSqlCredentials(value) {
+	assertSection("sql", sqlCredentialsSchema, value);
+}
+/**
+* Wraps an app's credential lookup so every caller gets validated credentials.
+*
+* The resolver runs on every call; cache in the app if the lookup is costly.
+* Each interface the result includes is checked in full, and a result with
+* neither, or none at all, throws.
+*/
+function defineExigoCredentials(resolver) {
+	return async (key) => {
+		const credentials = await resolver(key);
+		if (!credentials || !credentials.rest && !credentials.sql) throw new ExigoCredentialsError("The Exigo credential resolver returned no REST or SQL credentials.");
+		if (credentials.rest) assertExigoRestCredentials(credentials.rest);
+		if (credentials.sql) assertExigoSqlCredentials(credentials.sql);
+		return credentials;
+	};
+}
+//#endregion
+export { assertExigoRestCredentials, assertExigoSqlCredentials, defineExigoCredentials };

package/dist/errors.d.mts

@@ -0,0 +1,79 @@
+//#region src/errors.d.ts
+/**
+* Typed errors for everything this package does.
+*
+* Every error is an `ExigoError`, so an app can catch the package's failures
+* as one family and branch on the subclass when the remedy differs: an
+* `ExigoAuthError` is for the admin who entered the credentials, an
+* `ExigoTimeoutError` is worth retrying, an `ExigoConnectionError` usually
+* means a wrong host or an IP allowlist.
+*
+* Messages never carry a password or an Authorization header.
+*/
+/** Which of Exigo's two interfaces an error came from. */
+type ExigoSource = "rest" | "sql";
+interface ExigoErrorOptions {
+  readonly cause?: unknown;
+}
+declare class ExigoError extends Error {
+  name: string;
+  constructor(message: string, options?: ExigoErrorOptions);
+}
+/** Credentials were missing a field or held a value that cannot work. */
+declare class ExigoCredentialsError extends ExigoError {
+  name: string;
+  /** Dotted names of the fields at fault, such as `rest.password`. */
+  readonly fields: readonly string[];
+  constructor(message: string, fields?: readonly string[]);
+}
+/** Exigo refused the credentials: REST 401/403, or a SQL login failure. */
+declare class ExigoAuthError extends ExigoError {
+  name: string;
+  readonly source: ExigoSource;
+  /** The HTTP status, for REST. */
+  readonly status: number | undefined;
+  constructor(message: string, source: ExigoSource, options?: ExigoErrorOptions & {
+    readonly status?: number;
+  });
+}
+/** A REST call or a SQL connect or query ran past its timeout. */
+declare class ExigoTimeoutError extends ExigoError {
+  name: string;
+  readonly source: ExigoSource;
+  /** The limit that was exceeded, when known. */
+  readonly timeoutMs: number | undefined;
+  constructor(message: string, source: ExigoSource, options?: ExigoErrorOptions & {
+    readonly timeoutMs?: number;
+  });
+}
+/** Exigo could not be reached: DNS, refused connection, TLS, network. */
+declare class ExigoConnectionError extends ExigoError {
+  name: string;
+  readonly source: ExigoSource;
+  constructor(message: string, source: ExigoSource, options?: ExigoErrorOptions);
+}
+interface ExigoApiErrorDetails {
+  readonly status: number;
+  readonly method: string;
+  /** The request path below the API version, without the query string. */
+  readonly path: string;
+  readonly contentType: string | null;
+  /** The start of the response body, for diagnostics. */
+  readonly bodySnippet: string;
+}
+/**
+* The REST API answered, but not with a usable result: a non-2xx status other
+* than an auth refusal, or a success whose body is not JSON (Exigo serves an
+* HTML page for a wrong URL with a 200).
+*/
+declare class ExigoApiError extends ExigoError {
+  name: string;
+  readonly status: number;
+  readonly method: string;
+  readonly path: string;
+  readonly contentType: string | null;
+  readonly bodySnippet: string;
+  constructor(message: string, details: ExigoApiErrorDetails);
+}
+//#endregion
+export { ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoSource, ExigoTimeoutError };

package/dist/errors.mjs

@@ -0,0 +1,73 @@
+//#region src/errors.ts
+var ExigoError = class extends Error {
+	name = "ExigoError";
+	constructor(message, options) {
+		super(message, options?.cause === void 0 ? void 0 : options);
+	}
+};
+/** Credentials were missing a field or held a value that cannot work. */
+var ExigoCredentialsError = class extends ExigoError {
+	name = "ExigoCredentialsError";
+	/** Dotted names of the fields at fault, such as `rest.password`. */
+	fields;
+	constructor(message, fields = []) {
+		super(message);
+		this.fields = fields;
+	}
+};
+/** Exigo refused the credentials: REST 401/403, or a SQL login failure. */
+var ExigoAuthError = class extends ExigoError {
+	name = "ExigoAuthError";
+	source;
+	/** The HTTP status, for REST. */
+	status;
+	constructor(message, source, options) {
+		super(message, options);
+		this.source = source;
+		this.status = options?.status;
+	}
+};
+/** A REST call or a SQL connect or query ran past its timeout. */
+var ExigoTimeoutError = class extends ExigoError {
+	name = "ExigoTimeoutError";
+	source;
+	/** The limit that was exceeded, when known. */
+	timeoutMs;
+	constructor(message, source, options) {
+		super(message, options);
+		this.source = source;
+		this.timeoutMs = options?.timeoutMs;
+	}
+};
+/** Exigo could not be reached: DNS, refused connection, TLS, network. */
+var ExigoConnectionError = class extends ExigoError {
+	name = "ExigoConnectionError";
+	source;
+	constructor(message, source, options) {
+		super(message, options);
+		this.source = source;
+	}
+};
+/**
+* The REST API answered, but not with a usable result: a non-2xx status other
+* than an auth refusal, or a success whose body is not JSON (Exigo serves an
+* HTML page for a wrong URL with a 200).
+*/
+var ExigoApiError = class extends ExigoError {
+	name = "ExigoApiError";
+	status;
+	method;
+	path;
+	contentType;
+	bodySnippet;
+	constructor(message, details) {
+		super(message);
+		this.status = details.status;
+		this.method = details.method;
+		this.path = details.path;
+		this.contentType = details.contentType;
+		this.bodySnippet = details.bodySnippet;
+	}
+};
+//#endregion
+export { ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoTimeoutError };

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { ExigoCredentialResolver, ExigoCredentials, ExigoRestCredentials, ExigoSqlCredentials, assertExigoRestCredentials, assertExigoSqlCredentials, defineExigoCredentials } from "./credentials.mjs";
+import { ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoSource, ExigoTimeoutError } from "./errors.mjs";
+export { ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, type ExigoCredentialResolver, type ExigoCredentials, ExigoCredentialsError, ExigoError, ExigoErrorOptions, type ExigoRestCredentials, ExigoSource, type ExigoSqlCredentials, ExigoTimeoutError, assertExigoRestCredentials, assertExigoSqlCredentials, defineExigoCredentials };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoTimeoutError } from "./errors.mjs";
+import { assertExigoRestCredentials, assertExigoSqlCredentials, defineExigoCredentials } from "./credentials.mjs";
+export { ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoTimeoutError, assertExigoRestCredentials, assertExigoSqlCredentials, defineExigoCredentials };

package/dist/rest.d.mts

@@ -0,0 +1,65 @@
+import { ExigoRestCredentials } from "./credentials.mjs";
+import { ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoSource, ExigoTimeoutError } from "./errors.mjs";
+
+//#region src/rest.d.ts
+declare const EXIGO_API_VERSION = "3.0";
+declare const DEFAULT_EXIGO_TIMEOUT_MS = 15e3;
+type ExigoHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type ExigoQueryValue = string | number | boolean;
+interface ExigoRequestOptions {
+  /** Values for `{name}` placeholders in the path, URL-encoded. */
+  readonly params?: Readonly<Record<string, string | number>>;
+  /** Query string values; `null` and `undefined` are left out. */
+  readonly query?: Readonly<Record<string, ExigoQueryValue | readonly ExigoQueryValue[] | null | undefined>>;
+  /** Sent as JSON. */
+  readonly body?: unknown;
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Overrides the client's timeout for this call. */
+  readonly timeoutMs?: number;
+  /** Aborting it rejects with the signal's reason, not an Exigo error. */
+  readonly signal?: AbortSignal;
+}
+type ExigoMethodOptions = Omit<ExigoRequestOptions, "body">;
+type ExigoBodyMethodOptions = ExigoRequestOptions;
+interface ExigoRestClientOptions {
+  /** Per-request timeout. Defaults to {@link DEFAULT_EXIGO_TIMEOUT_MS}. */
+  readonly timeoutMs?: number;
+  /** For tests and instrumentation. Defaults to the global `fetch`. */
+  readonly fetch?: typeof fetch;
+}
+interface ExigoRestClient {
+  /** The normalized base URL, including the API version. */
+  readonly baseUrl: string;
+  /**
+  * Resolves to the parsed JSON body, or `undefined` for an empty one. The
+  * type parameter is an assertion about Exigo's response, not a check.
+  */
+  request<T = unknown>(method: ExigoHttpMethod, path: string, options?: ExigoRequestOptions): Promise<T>;
+  get<T = unknown>(path: string, options?: ExigoMethodOptions): Promise<T>;
+  post<T = unknown>(path: string, options?: ExigoBodyMethodOptions): Promise<T>;
+  put<T = unknown>(path: string, options?: ExigoBodyMethodOptions): Promise<T>;
+  patch<T = unknown>(path: string, options?: ExigoBodyMethodOptions): Promise<T>;
+  delete<T = unknown>(path: string, options?: ExigoMethodOptions): Promise<T>;
+}
+/**
+* `https://acme-api.exigo.com`, `…/3.0` and `…/3.0/` all become
+* `https://acme-api.exigo.com/3.0`. A base URL ending in any other version
+* segment is refused rather than kept, so no stored URL can pin a client to
+* an API version it was not written for. Query strings and fragments are
+* dropped.
+*
+* Requires HTTPS, since every request carries the password in its
+* Authorization header; plain HTTP is accepted only for a loopback host, such
+* as a local stub.
+*/
+declare function normalizeExigoBaseUrl(baseUrl: string): string;
+/**
+* Creates a client for one set of REST credentials.
+*
+* Accepts `undefined` so a resolver's optional `rest` section can be passed
+* straight in: missing credentials throw `ExigoCredentialsError` here rather
+* than failing later as an unauthenticated request.
+*/
+declare function createExigoRestClient(credentials: ExigoRestCredentials | null | undefined, options?: ExigoRestClientOptions): ExigoRestClient;
+//#endregion
+export { DEFAULT_EXIGO_TIMEOUT_MS, EXIGO_API_VERSION, ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoBodyMethodOptions, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoHttpMethod, ExigoMethodOptions, ExigoQueryValue, ExigoRequestOptions, ExigoRestClient, ExigoRestClientOptions, type ExigoRestCredentials, ExigoSource, ExigoTimeoutError, createExigoRestClient, normalizeExigoBaseUrl };

package/dist/rest.mjs

@@ -0,0 +1,231 @@
+import { ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoTimeoutError } from "./errors.mjs";
+import { assertExigoRestCredentials } from "./credentials.mjs";
+//#region src/rest.ts
+/**
+* `@fluid-app/exigo-connection-sdk/rest`: one way to call Exigo's REST API.
+*
+* The client owns what every droplet used to rebuild: the `/3.0` version
+* segment (a URL without it answered 200 with no data, #846), Basic auth as
+* `username@company`, a default timeout, and reading Exigo's responses without
+* mistaking its HTML error pages for data (#751). Endpoints and payloads stay
+* in each app.
+*
+* Uses the global `fetch`, so it runs on Node 20+ (Cloud Run, Vercel's Node
+* runtime) without Node-only APIs.
+*/
+const EXIGO_API_VERSION = "3.0";
+const DEFAULT_EXIGO_TIMEOUT_MS = 15e3;
+const BODY_SNIPPET_LENGTH = 500;
+const VERSION_SEGMENT = /^\d+\.\d+$/;
+const LOOPBACK_HOSTS = new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
+/**
+* `https://acme-api.exigo.com`, `…/3.0` and `…/3.0/` all become
+* `https://acme-api.exigo.com/3.0`. A base URL ending in any other version
+* segment is refused rather than kept, so no stored URL can pin a client to
+* an API version it was not written for. Query strings and fragments are
+* dropped.
+*
+* Requires HTTPS, since every request carries the password in its
+* Authorization header; plain HTTP is accepted only for a loopback host, such
+* as a local stub.
+*/
+function normalizeExigoBaseUrl(baseUrl) {
+	let url;
+	try {
+		url = new URL(baseUrl.trim());
+	} catch {
+		throw new ExigoCredentialsError("Exigo rest.baseUrl is not a valid URL.", ["rest.baseUrl"]);
+	}
+	const loopbackHttp = url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+	if (url.protocol !== "https:" && !loopbackHttp) throw new ExigoCredentialsError("Exigo rest.baseUrl must be an https URL; requests carry the password.", ["rest.baseUrl"]);
+	if (url.username || url.password) throw new ExigoCredentialsError("Exigo rest.baseUrl must not carry credentials; pass username and password instead.", ["rest.baseUrl"]);
+	const segments = url.pathname.split("/").filter(Boolean);
+	const last = segments.at(-1);
+	if (last !== void 0 && VERSION_SEGMENT.test(last)) {
+		if (last !== "3.0") throw new ExigoCredentialsError(`Exigo rest.baseUrl ends in /${last}; this client speaks the 3.0 API. Store the host alone or with /3.0.`, ["rest.baseUrl"]);
+	} else segments.push("3.0");
+	return `${url.origin}/${segments.join("/")}`;
+}
+/** Latin-1-safe Base64 of UTF-8 text, without Node's Buffer. */
+function base64(text) {
+	let binary = "";
+	for (const byte of new TextEncoder().encode(text)) binary += String.fromCharCode(byte);
+	return btoa(binary);
+}
+function authorizationHeader(credentials) {
+	const suffix = `@${credentials.company}`;
+	return `Basic ${base64(`${credentials.username.endsWith(suffix) ? credentials.username : `${credentials.username}${suffix}`}:${credentials.password}`)}`;
+}
+const ABSOLUTE_URL = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i;
+const LEADING_VERSION_SEGMENT = /^\/?\d+\.\d+(?:\/|$)/;
+function expandPath(path, params) {
+	if (ABSOLUTE_URL.test(path)) throw new TypeError(`Exigo request path must be relative to the base URL, got "${path}".`);
+	if (LEADING_VERSION_SEGMENT.test(path)) throw new TypeError(`Exigo request path must not start with an API version; the client adds /3.0. Got "${path}".`);
+	const expanded = path.replace(/\{([^}]+)\}/g, (_, name) => {
+		const value = params?.[name];
+		if (value === void 0) throw new TypeError(`Missing path parameter "${name}" for ${path}.`);
+		const text = String(value);
+		if (text === "" || text === "." || text === "..") throw new TypeError(`Path parameter "${name}" is empty or a dot segment for ${path}.`);
+		return encodeURIComponent(text);
+	});
+	return expanded.startsWith("/") ? expanded : `/${expanded}`;
+}
+function appendQuery(url, query) {
+	for (const [key, value] of Object.entries(query ?? {})) {
+		if (value === null || value === void 0) continue;
+		const values = Array.isArray(value) ? value : [value];
+		for (const item of values) url.searchParams.append(key, String(item));
+	}
+}
+const REDACTED = "[redacted]";
+/**
+* The start of a response body for diagnostics, with the credentials taken
+* out first: an Exigo error body can echo the request, and the snippet ends up
+* in the error's message and in whatever logs it.
+*/
+function redact(text, secrets) {
+	let redacted = text;
+	for (const secret of secrets) if (secret.length > 0) redacted = redacted.split(secret).join(REDACTED);
+	return redacted;
+}
+function snippet(text, secrets) {
+	const collapsed = redact(text, secrets).replace(/\s+/g, " ").trim();
+	return collapsed.length > BODY_SNIPPET_LENGTH ? `${collapsed.slice(0, BODY_SNIPPET_LENGTH)}…` : collapsed;
+}
+function looksLikeHtml(contentType, text) {
+	return /\btext\/html\b/i.test(contentType ?? "") || /^\s*<(?:!doctype\s+html|html)[\s>]/i.test(text);
+}
+function parseJson(text) {
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(text)
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+/** Exigo's error bodies vary by endpoint; take the first message they carry. */
+function errorMessageFrom(body) {
+	if (body === null || typeof body !== "object") return null;
+	const record = body;
+	for (const key of [
+		"message",
+		"Message",
+		"error_description",
+		"error",
+		"title"
+	]) {
+		const value = record[key];
+		if (typeof value === "string" && value.trim() !== "") return value.trim();
+	}
+	return null;
+}
+function describeNetworkFailure(error) {
+	const cause = error instanceof Error && error.cause instanceof Error ? error.cause : error;
+	const code = cause !== null && typeof cause === "object" ? cause.code : void 0;
+	const message = cause instanceof Error ? cause.message : String(cause);
+	return typeof code === "string" && !message.includes(code) ? `${code}: ${message}` : message;
+}
+const MAX_TIMEOUT_MS = 2147483647;
+function validTimeout(timeoutMs) {
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_TIMEOUT_MS) throw new TypeError(`Exigo timeoutMs must be a positive number up to ${MAX_TIMEOUT_MS}, got ${timeoutMs}.`);
+	return timeoutMs;
+}
+/**
+* Creates a client for one set of REST credentials.
+*
+* Accepts `undefined` so a resolver's optional `rest` section can be passed
+* straight in: missing credentials throw `ExigoCredentialsError` here rather
+* than failing later as an unauthenticated request.
+*/
+function createExigoRestClient(credentials, options = {}) {
+	if (!credentials) throw new ExigoCredentialsError("No Exigo REST credentials were provided.", ["rest"]);
+	assertExigoRestCredentials(credentials);
+	const baseUrl = normalizeExigoBaseUrl(credentials.baseUrl);
+	const host = new URL(baseUrl).host;
+	const authorization = authorizationHeader(credentials);
+	const secrets = [credentials.password, authorization.replace(/^Basic /, "")];
+	const defaultTimeout = validTimeout(options.timeoutMs ?? 15e3);
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+	async function request(method, path, requestOptions = {}) {
+		const relative = expandPath(path, requestOptions.params);
+		const url = new URL(`${baseUrl}${relative}`);
+		appendQuery(url, requestOptions.query);
+		const timeoutMs = validTimeout(requestOptions.timeoutMs ?? defaultTimeout);
+		const headers = new Headers(requestOptions.headers);
+		if (!headers.has("Accept")) headers.set("Accept", "application/json");
+		headers.set("Authorization", authorization);
+		let body;
+		if (requestOptions.body !== void 0) {
+			headers.set("Content-Type", "application/json");
+			body = JSON.stringify(requestOptions.body);
+		}
+		const callerSignal = requestOptions.signal;
+		callerSignal?.throwIfAborted();
+		const controller = new AbortController();
+		let timedOut = false;
+		const timer = setTimeout(() => {
+			timedOut = true;
+			controller.abort();
+		}, timeoutMs);
+		const onCallerAbort = () => controller.abort(callerSignal?.reason);
+		callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
+		let response;
+		let text;
+		try {
+			response = await fetchImpl(url, {
+				method,
+				headers,
+				body,
+				signal: controller.signal
+			});
+			text = await response.text();
+		} catch (error) {
+			if (timedOut) throw new ExigoTimeoutError(`Exigo ${method} ${relative} did not answer within ${timeoutMs} ms.`, "rest", {
+				cause: error,
+				timeoutMs
+			});
+			if (callerSignal?.aborted) throw callerSignal.reason;
+			throw new ExigoConnectionError(`Could not reach Exigo at ${host}: ${describeNetworkFailure(error)}`, "rest", { cause: error });
+		} finally {
+			clearTimeout(timer);
+			callerSignal?.removeEventListener("abort", onCallerAbort);
+		}
+		const contentType = response.headers.get("content-type");
+		const details = {
+			status: response.status,
+			method,
+			path: url.pathname.slice(new URL(baseUrl).pathname.length) || "/",
+			contentType,
+			bodySnippet: snippet(text, secrets)
+		};
+		const html = looksLikeHtml(contentType, text);
+		const parsed = html || text.trim() === "" ? null : parseJson(text);
+		if (response.status === 401 || response.status === 403) throw new ExigoAuthError(`Exigo rejected the API credentials (HTTP ${response.status}). Check the username, password and company name.`, "rest", { status: response.status });
+		if (!response.ok) {
+			const exigoMessage = parsed?.ok ? errorMessageFrom(parsed.value) : null;
+			const reason = exigoMessage ? `: ${redact(exigoMessage, secrets)}` : html ? " with an HTML error page instead of JSON" : "";
+			throw new ExigoApiError(`Exigo ${method} ${details.path} failed with HTTP ${response.status}${reason}.`, details);
+		}
+		if (html) throw new ExigoApiError(`Exigo ${method} ${details.path} answered HTTP ${response.status} with an HTML page, not JSON. The base URL is probably not Exigo's API host.`, details);
+		if (parsed === null) return void 0;
+		if (!parsed.ok) throw new ExigoApiError(`Exigo ${method} ${details.path} answered HTTP ${response.status} with a body that is not JSON.`, details);
+		return parsed.value;
+	}
+	return {
+		baseUrl,
+		request,
+		get: (path, requestOptions) => request("GET", path, requestOptions),
+		post: (path, requestOptions) => request("POST", path, requestOptions),
+		put: (path, requestOptions) => request("PUT", path, requestOptions),
+		patch: (path, requestOptions) => request("PATCH", path, requestOptions),
+		delete: (path, requestOptions) => request("DELETE", path, requestOptions)
+	};
+}
+//#endregion
+export { DEFAULT_EXIGO_TIMEOUT_MS, EXIGO_API_VERSION, ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoTimeoutError, createExigoRestClient, normalizeExigoBaseUrl };

package/dist/sql.d.mts

@@ -0,0 +1,53 @@
+import { ExigoSqlCredentials } from "./credentials.mjs";
+import { ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoSource, ExigoTimeoutError } from "./errors.mjs";
+import { ConnectionPool, ConnectionPool as ConnectionPool$1 } from "mssql";
+
+//#region src/sql.d.ts
+declare const EXIGO_SQL_DEFAULTS: {
+  readonly port: number;
+  readonly max: number;
+  readonly idleTimeoutMs: number;
+  readonly connectTimeoutMs: number;
+  readonly requestTimeoutMs: number;
+};
+/**
+* Pool settings. They apply when the pool opens; a later call with different
+* options reuses the open pool as it is.
+*/
+interface ExigoPoolOptions {
+  readonly max?: number;
+  readonly idleTimeoutMs?: number;
+  readonly connectTimeoutMs?: number;
+  readonly requestTimeoutMs?: number;
+  /**
+  * Errors the pool raises outside a query, such as an idle connection that
+  * dropped. Defaults to a `console.warn`; the pool replaces the connection.
+  */
+  readonly onError?: (error: ExigoError | Error) => void;
+}
+/**
+* Turns an `mssql` failure into the package's typed errors where Exigo's
+* remedy is known: login, timeout, and reaching the server. Anything else,
+* such as a syntax error in a droplet's query, is returned unchanged.
+*/
+declare function translateExigoSqlError(error: unknown): unknown;
+/**
+* The open pool for these credentials, opening it on first use.
+*
+* Pools are keyed by host, port, database and username, and within that by
+* password and TLS settings. Concurrent first calls share one connect. A
+* failed connect is not cached, so the next call tries again. A rotated
+* password opens its own pool without closing the previous one, which is
+* closed once no call has used it for five minutes. A pool closed directly is
+* replaced on the next call.
+*/
+declare function getExigoPool(credentials: ExigoSqlCredentials | null | undefined, options?: ExigoPoolOptions): Promise<ConnectionPool$1>;
+/**
+* Closes and forgets every pool for this database, whatever password it was
+* opened with.
+*/
+declare function closeExigoPool(credentials: Pick<ExigoSqlCredentials, "host" | "database" | "username" | "port">): Promise<void>;
+/** Closes every pool this package opened; for shutdown hooks and tests. */
+declare function closeAllExigoPools(): Promise<void>;
+//#endregion
+export { type ConnectionPool, EXIGO_SQL_DEFAULTS, ExigoApiError, ExigoApiErrorDetails, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoErrorOptions, ExigoPoolOptions, ExigoSource, type ExigoSqlCredentials, ExigoTimeoutError, closeAllExigoPools, closeExigoPool, getExigoPool, translateExigoSqlError };

package/dist/sql.mjs

@@ -0,0 +1,295 @@
+import { ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoTimeoutError } from "./errors.mjs";
+import { assertExigoSqlCredentials } from "./credentials.mjs";
+import { createHash } from "node:crypto";
+//#region src/sql.ts
+/**
+* `@fluid-app/exigo-connection-sdk/sql`: one cached connection pool per Exigo database.
+*
+* Opening a pool per query leaks connections past the request that opened
+* them (rewards-exigo's checkout path did this). Here the first call for a
+* database opens a small pool, later calls reuse it, and the app closes it
+* explicitly on shutdown. The cache lives on `globalThis`, so Next's dev
+* reloads share one pool rather than stacking new ones.
+*
+* Node runtime only. `mssql` is an optional peer dependency that is imported
+* the first time a pool opens, so an app that only imports `./rest` never
+* loads it. In Next, list `mssql` in `serverExternalPackages` and set
+* `export const runtime = "nodejs"` on routes that query.
+*/
+const EXIGO_SQL_DEFAULTS = {
+	port: 1433,
+	max: 4,
+	idleTimeoutMs: 1e4,
+	connectTimeoutMs: 12e3,
+	requestTimeoutMs: 3e4
+};
+/**
+* Each database holds one pool per credential fingerprint (password and TLS
+* settings). A rotation therefore never closes a pool another request is
+* using: requests that resolved the old password keep the old pool, new ones
+* get the new pool, and a rollback finds its pool still there. A pool that
+* is not its database's most recently used one, and that no request has asked
+* for in this long, is closed and forgotten. The sweep runs on every call and,
+* while any database holds more than one pool, on an unref'd timer, so it
+* happens even for a tenant that stops querying.
+*/
+const UNUSED_POOL_TTL_MS = 5 * 6e4;
+/**
+* A database's current pool is closed too once nothing has asked for it in
+* this long, so tenant churn does not grow the cache. It already holds no
+* connections when idle (`min: 0`); the next call reopens it.
+*/
+const IDLE_POOL_TTL_MS = 30 * 6e4;
+const CACHE_KEY = Symbol.for("@fluid-app/exigo-connection-sdk/sql-pools");
+const SWEEP_TIMER_KEY = Symbol.for("@fluid-app/exigo-connection-sdk/sql-pool-sweep");
+function cache() {
+	const holder = globalThis;
+	holder[CACHE_KEY] ??= /* @__PURE__ */ new Map();
+	return holder[CACHE_KEY];
+}
+const TRANSPORT_REQUEST_CODES = new Set([
+	"ETIMEOUT",
+	"ECONNCLOSED",
+	"ESOCKET"
+]);
+function poolKey(credentials) {
+	const port = credentials.port ?? EXIGO_SQL_DEFAULTS.port;
+	return JSON.stringify([
+		credentials.host.trim().toLowerCase(),
+		port,
+		credentials.database,
+		credentials.username
+	]);
+}
+function fingerprint(credentials) {
+	return createHash("sha256").update(JSON.stringify([
+		credentials.password,
+		credentials.encrypt ?? true,
+		credentials.trustServerCertificate
+	])).digest("hex");
+}
+function toMssqlConfig(credentials, options) {
+	return {
+		server: credentials.host.trim(),
+		port: credentials.port ?? EXIGO_SQL_DEFAULTS.port,
+		database: credentials.database,
+		user: credentials.username,
+		password: credentials.password,
+		connectionTimeout: options.connectTimeoutMs ?? EXIGO_SQL_DEFAULTS.connectTimeoutMs,
+		requestTimeout: options.requestTimeoutMs ?? EXIGO_SQL_DEFAULTS.requestTimeoutMs,
+		pool: {
+			max: options.max ?? EXIGO_SQL_DEFAULTS.max,
+			min: 0,
+			idleTimeoutMillis: options.idleTimeoutMs ?? EXIGO_SQL_DEFAULTS.idleTimeoutMs
+		},
+		options: {
+			encrypt: credentials.encrypt ?? true,
+			trustServerCertificate: credentials.trustServerCertificate,
+			enableArithAbort: true
+		}
+	};
+}
+async function loadMssql() {
+	let loaded;
+	try {
+		loaded = await import("mssql");
+	} catch (error) {
+		throw new ExigoError("@fluid-app/exigo-connection-sdk/sql needs the mssql package. Install it next to @fluid-app/exigo-connection-sdk.", { cause: error });
+	}
+	return loaded.default ?? loaded;
+}
+/**
+* mssql wraps tedious, which wraps the socket error, sometimes in an
+* AggregateError: `ECONNREFUSED` sits three levels below a top-level
+* `ESOCKET` whose message only says "Could not connect (sequence)".
+*/
+function errorChain(error) {
+	const codes = /* @__PURE__ */ new Set();
+	const messages = [];
+	const seen = /* @__PURE__ */ new Set();
+	const visit = (value, depth) => {
+		if (value === null || typeof value !== "object" || seen.has(value) || depth > 5) return;
+		seen.add(value);
+		const record = value;
+		if (typeof record.code === "string") codes.add(record.code);
+		if (typeof record.message === "string") messages.push(record.message);
+		visit(record.originalError, depth + 1);
+		visit(record.cause, depth + 1);
+		if (Array.isArray(record.errors)) for (const inner of record.errors) visit(inner, depth + 1);
+	};
+	visit(error, 0);
+	return {
+		codes,
+		text: messages.join("\n")
+	};
+}
+/**
+* Turns an `mssql` failure into the package's typed errors where Exigo's
+* remedy is known: login, timeout, and reaching the server. Anything else,
+* such as a syntax error in a droplet's query, is returned unchanged.
+*/
+function translateExigoSqlError(error) {
+	if (error instanceof ExigoError) return error;
+	const { codes, text } = errorChain(error);
+	const code = error !== null && typeof error === "object" ? error.code : void 0;
+	const name = error instanceof Error ? error.name : "";
+	const raw = error instanceof Error ? error.message : String(error);
+	const options = { cause: error };
+	const has = (...candidates) => candidates.some((candidate) => codes.has(candidate));
+	if (name === "RequestError" && !TRANSPORT_REQUEST_CODES.has(String(code))) return error;
+	if (has("ELOGIN") || /Login failed/i.test(text)) return new ExigoAuthError("Exigo's SQL Server rejected the username or password.", "sql", options);
+	if (code === "ETIMEOUT") return name === "RequestError" ? new ExigoTimeoutError(`An Exigo SQL query timed out: ${raw}`, "sql", options) : new ExigoTimeoutError("Timed out connecting to Exigo's SQL Server. This is usually an IP allowlist or a wrong host or port, not a bad password.", "sql", options);
+	if (has("ENOTFOUND", "EAI_AGAIN", "EINSTLOOKUP") || /ENOTFOUND|EAI_AGAIN|getaddrinfo/i.test(text)) return new ExigoConnectionError(`Could not resolve the Exigo SQL host: ${raw}`, "sql", options);
+	if (has("ECONNREFUSED") || /ECONNREFUSED/i.test(text)) return new ExigoConnectionError("The Exigo SQL host refused the connection. Check the port and that the server accepts remote TCP connections.", "sql", options);
+	if (/self[- ]signed|certificate/i.test(text)) return new ExigoConnectionError(`TLS failed reaching Exigo's SQL Server: ${raw}`, "sql", options);
+	if (name === "ConnectionError" || code === "ESOCKET" || code === "ECONNCLOSED") return new ExigoConnectionError(`Could not connect to Exigo's SQL Server: ${raw}`, "sql", options);
+	return error;
+}
+async function openPool(credentials, options) {
+	const pool = new (await (loadMssql())).ConnectionPool(toMssqlConfig(credentials, options));
+	const onError = options.onError ?? ((error) => console.warn(`[@fluid-app/exigo-connection-sdk] ${error.message}`));
+	pool.on("error", (error) => {
+		const translated = translateExigoSqlError(error);
+		onError(translated instanceof Error ? translated : new Error(String(translated)));
+	});
+	try {
+		return await pool.connect();
+	} catch (error) {
+		await pool.close().catch(() => void 0);
+		throw translateExigoSqlError(error);
+	}
+}
+function isUsable(pool) {
+	return pool.connected || pool.connecting;
+}
+/**
+* The open pool for these credentials, opening it on first use.
+*
+* Pools are keyed by host, port, database and username, and within that by
+* password and TLS settings. Concurrent first calls share one connect. A
+* failed connect is not cached, so the next call tries again. A rotated
+* password opens its own pool without closing the previous one, which is
+* closed once no call has used it for five minutes. A pool closed directly is
+* replaced on the next call.
+*/
+async function getExigoPool(credentials, options = {}) {
+	if (!credentials) throw new ExigoCredentialsError("No Exigo SQL credentials were provided.", ["sql"]);
+	assertExigoSqlCredentials(credentials);
+	const pools = cache();
+	const identity = poolKey(credentials);
+	const current = fingerprint(credentials);
+	const group = () => {
+		let entries = pools.get(identity);
+		if (entries === void 0) {
+			entries = /* @__PURE__ */ new Map();
+			pools.set(identity, entries);
+		}
+		return entries;
+	};
+	const own = pools.get(identity)?.get(current);
+	if (own !== void 0) own.lastUsed = Date.now();
+	sweepSupersededPools(Date.now());
+	for (;;) {
+		const entries = group();
+		const existing = entries.get(current);
+		if (existing === void 0) break;
+		existing.lastUsed = Date.now();
+		const pool = await existing.pool;
+		if (isUsable(pool)) return pool;
+		if (entries.get(current) === existing) {
+			entries.delete(current);
+			break;
+		}
+	}
+	const entry = {
+		pool: openPool(credentials, options),
+		lastUsed: Date.now()
+	};
+	const entries = group();
+	entries.set(current, entry);
+	entry.pool.catch(() => {
+		if (entries.get(current) === entry) entries.delete(current);
+	});
+	if (entries.size > 1) scheduleSweep();
+	return entry.pool;
+}
+/**
+* Closes every pool that has been superseded on its database (it is not the
+* most recently used one there) and has sat unused past the TTL. A database's
+* current pool is never closed here, however long it idles.
+*/
+function sweepSupersededPools(now) {
+	const pools = cache();
+	let pending = false;
+	for (const [identity, entries] of pools) {
+		if (entries.size > 1) {
+			let keep;
+			let newest = Number.NEGATIVE_INFINITY;
+			for (const [key, entry] of entries) if (entry.lastUsed >= newest) {
+				newest = entry.lastUsed;
+				keep = key;
+			}
+			for (const [key, entry] of entries) {
+				if (key === keep || now - entry.lastUsed < UNUSED_POOL_TTL_MS) continue;
+				entries.delete(key);
+				closeEntry(entry).catch(() => void 0);
+			}
+		}
+		for (const [key, entry] of entries) {
+			if (now - entry.lastUsed < IDLE_POOL_TTL_MS) continue;
+			entries.delete(key);
+			closeEntry(entry).catch(() => void 0);
+		}
+		if (entries.size === 0) pools.delete(identity);
+		else if (entries.size > 1) pending = true;
+	}
+	if (pending) scheduleSweep();
+}
+/** One timer at a time; unref'd so it never keeps a process alive. */
+function scheduleSweep() {
+	const holder = globalThis;
+	if (holder[SWEEP_TIMER_KEY] !== void 0) return;
+	const timer = setTimeout(() => {
+		holder[SWEEP_TIMER_KEY] = void 0;
+		sweepSupersededPools(Date.now());
+	}, UNUSED_POOL_TTL_MS);
+	timer.unref?.();
+	holder[SWEEP_TIMER_KEY] = timer;
+}
+function cancelSweep() {
+	const holder = globalThis;
+	if (holder[SWEEP_TIMER_KEY] === void 0) return;
+	clearTimeout(holder[SWEEP_TIMER_KEY]);
+	holder[SWEEP_TIMER_KEY] = void 0;
+}
+/**
+* Closes and forgets every pool for this database, whatever password it was
+* opened with.
+*/
+async function closeExigoPool(credentials) {
+	const pools = cache();
+	const identity = poolKey(credentials);
+	const entries = pools.get(identity);
+	if (entries === void 0) return;
+	pools.delete(identity);
+	await Promise.all([...entries.values()].map(closeEntry));
+}
+/** Closes every pool this package opened; for shutdown hooks and tests. */
+async function closeAllExigoPools() {
+	const pools = cache();
+	const entries = [...pools.values()].flatMap((group) => [...group.values()]);
+	pools.clear();
+	cancelSweep();
+	await Promise.all(entries.map(closeEntry));
+}
+async function closeEntry(entry) {
+	let pool;
+	try {
+		pool = await entry.pool;
+	} catch {
+		return;
+	}
+	await pool.close();
+}
+//#endregion
+export { EXIGO_SQL_DEFAULTS, ExigoApiError, ExigoAuthError, ExigoConnectionError, ExigoCredentialsError, ExigoError, ExigoTimeoutError, closeAllExigoPools, closeExigoPool, getExigoPool, translateExigoSqlError };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@fluid-app/exigo-connection-sdk",
+  "version": "0.1.0",
+  "description": "Exigo REST client, SQL pool and credential interface for Fluid droplets and Mist apps",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fluid-commerce/fluid.git",
+    "directory": "packages/platform/exigo"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./rest": {
+      "types": "./dist/rest.d.mts",
+      "default": "./dist/rest.mjs"
+    },
+    "./sql": {
+      "types": "./dist/sql.d.mts",
+      "default": "./dist/sql.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@fluid-app/typescript-config": "0.0.0",
+    "@types/mssql": "^12.3.0",
+    "@types/node": "24.10.12",
+    "mssql": "^12.7.2",
+    "tsdown": "^0.21.0",
+    "typescript": "^5",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@types/mssql": ">=9",
+    "mssql": ">=11 <13"
+  },
+  "peerDependenciesMeta": {
+    "@types/mssql": {
+      "optional": true
+    },
+    "mssql": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "oxlint --deny-warnings",
+    "lint:fix": "oxlint --fix --deny-warnings",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsgo --noEmit",
+    "check:publish-shape": "node scripts/check-publish-shape.mjs"
+  }
+}