@grantex/sdk 0.5.1 → 0.7.0

package/dist/caps/meter.js

@@ -0,0 +1,200 @@
+/**
+ * Caps meter: atomic reservation of call caps and cost-unit budgets.
+ * Mirrors the Python SDK's `grantex.caps`; both address the same counters.
+ */
+export const CAP_ERROR_CODE = 'E1008';
+export const CAPS_MODES = ['off', 'warn', 'enforce'];
+/** Rolling window length per window name; `per_case` has no time window. */
+export const WINDOW_MS = {
+    per_hour: 3_600_000,
+    per_day: 86_400_000,
+    per_case: 0,
+};
+export const MAX_COUNT = 2147483647;
+const TENANT_MAX = 256;
+const RESERVATION_RE = /^[A-Za-z0-9_-]{8,64}$/;
+/** A reservation would exceed a cap. `code` is `E1008`. */
+export class CapExceededError extends Error {
+    code = CAP_ERROR_CODE;
+    reason = 'cap_exceeded';
+    limit;
+    window;
+    used;
+    requested;
+    scope;
+    kind;
+    constructor(args) {
+        const noun = args.kind === 'calls' ? 'call' : 'cost unit';
+        super(`${CAP_ERROR_CODE} cap_exceeded: ${args.scope} ${args.window} ${noun} cap of ${args.limit} reached (${args.used} used, ${args.requested} requested)`);
+        this.name = 'CapExceededError';
+        this.limit = args.limit;
+        this.window = args.window;
+        this.used = args.used;
+        this.requested = args.requested;
+        this.scope = args.scope;
+        this.kind = args.kind;
+    }
+}
+/** The caps backend could not answer. Callers must treat the call as denied. */
+export class MeterUnavailableError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'MeterUnavailableError';
+    }
+}
+/** Limits or arguments are invalid. `subReason` names why. */
+export class CapsConfigurationError extends Error {
+    subReason;
+    constructor(message, subReason = 'invalid_limits') {
+        super(message);
+        this.name = 'CapsConfigurationError';
+        this.subReason = subReason;
+    }
+}
+const encoder = new TextEncoder();
+async function sha256Hex(input) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', encoder.encode(input));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** Storage key for a counter; identical to the Python SDK's `CapLimit.key()`. */
+export function counterKey(window, counter) {
+    return sha256Hex(`grantex-caps:v1\0${window}\0${counter}`);
+}
+/** Fixed-length tenant component for storage keys. */
+export async function tenantHash(tenantId) {
+    return (await sha256Hex(`grantex-caps-tenant:v1\0${tenantId}`)).slice(0, 32);
+}
+function checkCount(value, what) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > MAX_COUNT) {
+        throw new CapsConfigurationError(`${what} must be an integer between 0 and ${MAX_COUNT}`);
+    }
+    return value;
+}
+/** Validate a reservation's arguments and apply defaults. */
+export async function resolveLimits(tenantId, limits) {
+    if (typeof tenantId !== 'string' || tenantId.length === 0 || tenantId.length > TENANT_MAX) {
+        throw new CapsConfigurationError('tenantId must be a non-empty string of at most 256 characters');
+    }
+    const resolved = [];
+    const seen = new Set();
+    for (const limit of limits) {
+        if (typeof limit !== 'object' || limit === null)
+            throw new CapsConfigurationError('limits must be objects');
+        if (!Object.prototype.hasOwnProperty.call(WINDOW_MS, limit.window)) {
+            throw new CapsConfigurationError(`unknown cap window ${JSON.stringify(limit.window)}`);
+        }
+        if (typeof limit.counter !== 'string' || limit.counter.length === 0) {
+            throw new CapsConfigurationError('a cap counter must be a non-empty string');
+        }
+        checkCount(limit.limit, 'a cap limit');
+        const units = checkCount(limit.units ?? 1, 'reserved units');
+        const key = await counterKey(limit.window, limit.counter);
+        if (seen.has(key))
+            throw new CapsConfigurationError(`counter ${JSON.stringify(limit.counter)} appears twice in one reservation`);
+        seen.add(key);
+        resolved.push({
+            counter: limit.counter,
+            limit: limit.limit,
+            window: limit.window,
+            units,
+            scope: limit.scope ?? 'manifest',
+            kind: limit.kind ?? 'calls',
+            key,
+        });
+    }
+    return resolved;
+}
+function randomId() {
+    const bytes = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(bytes);
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+function unavailable(err) {
+    const name = err instanceof Error ? err.name : typeof err;
+    return new MeterUnavailableError(`caps backend unavailable: ${name}`, { cause: err });
+}
+/**
+ * Reserve call caps and cost-unit budgets before the call that incurs cost.
+ *
+ * `reserve()` checks every limit and records the call atomically, so
+ * concurrent callers can never exceed a cap. A failed call is **not** refunded
+ * by default: a timeout or error does not prove the provider did no work. Call
+ * `refundUnsent()` only when the provider call is known not to have been sent.
+ * Any backend failure throws `MeterUnavailableError`; callers must deny.
+ */
+export class CapsMeter {
+    #backend;
+    #clock;
+    constructor(backend, options = {}) {
+        this.#backend = backend;
+        this.#clock = options.clock;
+    }
+    #now() {
+        return this.#clock === undefined ? undefined : Math.trunc(this.#clock());
+    }
+    async reserve(tenantId, limits) {
+        const applied = (await resolveLimits(tenantId, limits)).filter((l) => l.units > 0);
+        for (const limit of applied) {
+            if (limit.limit === 0) {
+                // A cap of zero disables the tool, whatever the backend holds.
+                throw new CapExceededError({
+                    limit: 0, window: limit.window, used: 0, requested: limit.units, scope: limit.scope, kind: limit.kind,
+                });
+            }
+            if (limit.units > limit.limit) {
+                // This call alone exceeds the cap; report what the counter holds.
+                let used;
+                try {
+                    used = await this.#backend.usage(tenantId, limit, this.#now());
+                }
+                catch (err) {
+                    throw unavailable(err);
+                }
+                throw new CapExceededError({
+                    limit: limit.limit, window: limit.window, used, requested: limit.units, scope: limit.scope, kind: limit.kind,
+                });
+            }
+        }
+        const reservation = { reservationId: randomId(), tenantId, limits: applied };
+        if (applied.length === 0)
+            return reservation;
+        try {
+            await this.#backend.reserve(tenantId, reservation.reservationId, applied, this.#now());
+        }
+        catch (err) {
+            if (err instanceof CapExceededError)
+                throw err;
+            throw unavailable(err);
+        }
+        return reservation;
+    }
+    /** Release a reservation whose provider call was proven not sent. */
+    async refundUnsent(reservation) {
+        if (!RESERVATION_RE.test(reservation.reservationId))
+            throw new CapsConfigurationError('invalid reservation id');
+        if (reservation.limits.length === 0)
+            return;
+        try {
+            await this.#backend.refund(reservation.tenantId, reservation.reservationId, reservation.limits, this.#now());
+        }
+        catch (err) {
+            throw unavailable(err);
+        }
+    }
+    /** Current usage of each counter, for display (consent page, case view). */
+    async usage(tenantId, limits) {
+        const resolved = await resolveLimits(tenantId, limits);
+        try {
+            const out = [];
+            for (const limit of resolved) {
+                const used = await this.#backend.usage(tenantId, limit, this.#now());
+                out.push({ limit, used, remaining: Math.max(limit.limit - used, 0) });
+            }
+            return out;
+        }
+        catch (err) {
+            throw unavailable(err);
+        }
+    }
+}
+//# sourceMappingURL=meter.js.map

package/dist/caps/meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.js","sourceRoot":"","sources":["../../src/caps/meter.ts"],"names":[],"mappings":"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"}

package/dist/caps/postgres.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Postgres caps backend: row locks serialize reservations per counter.
+ *
+ * A reservation runs in one READ COMMITTED transaction: it makes sure a row
+ * exists per counter in `grantex_cap_counters`, locks those rows in a fixed
+ * order (so concurrent reservations cannot deadlock), prunes and sums the
+ * counter's reservations in `grantex_cap_reservations`, and inserts the new
+ * reservation only if every limit holds. Time comes from the database
+ * (`clock_timestamp()`) unless a clock is injected for tests. Same tables and
+ * statements as the Python SDK's `PostgresCapsBackend`.
+ *
+ * Rows carry a SHA-256-derived hash of the tenant id, not the tenant id, in
+ * `tenant_id`: isolation comes from that hash being part of every key and
+ * query, and row-level security policies written against plain tenant ids do
+ * not match these rows.
+ *
+ * Expired rows are deleted lazily when their counter is next reserved. Run
+ * `prune()` periodically (for example hourly) to delete expired reservations,
+ * per-case reservations older than `caseTtlSeconds` if one is set, and
+ * counters with no reservations left.
+ *
+ * `pool` is a `pg` Pool, or anything with the same `connect()` / `query()` /
+ * `release()` shape. Create the tables with `CAPS_SCHEMA_SQL` through your own
+ * migration tool, or `ensureSchema()`.
+ */
+import { type CapsBackend, type ResolvedCapLimit } from './meter.js';
+export declare const CAPS_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS grantex_cap_counters (\n  tenant_id   TEXT NOT NULL,\n  counter_key TEXT NOT NULL,\n  PRIMARY KEY (tenant_id, counter_key)\n);\n\nCREATE TABLE IF NOT EXISTS grantex_cap_reservations (\n  tenant_id      TEXT NOT NULL,\n  counter_key    TEXT NOT NULL,\n  reservation_id TEXT NOT NULL,\n  units          BIGINT NOT NULL CHECK (units >= 0),\n  reserved_at    TIMESTAMPTZ NOT NULL,\n  expires_at     TIMESTAMPTZ,\n  PRIMARY KEY (tenant_id, counter_key, reservation_id),\n  FOREIGN KEY (tenant_id, counter_key)\n    REFERENCES grantex_cap_counters (tenant_id, counter_key)\n);\n\nALTER TABLE grantex_cap_reservations ADD COLUMN IF NOT EXISTS expires_at TIMESTAMPTZ;\n\nCREATE INDEX IF NOT EXISTS idx_grantex_cap_reservations_time\n  ON grantex_cap_reservations (tenant_id, counter_key, reserved_at);\n\nCREATE INDEX IF NOT EXISTS idx_grantex_cap_reservations_expiry\n  ON grantex_cap_reservations (expires_at)\n  WHERE expires_at IS NOT NULL;\n";
+export interface PgClientLike {
+    query(text: string, values?: readonly unknown[]): Promise<{
+        rows: Array<Record<string, unknown>>;
+        rowCount?: number | null;
+    }>;
+    /** `pg` destroys the connection instead of reusing it when given an error. */
+    release(err?: Error | boolean): void;
+}
+export interface PgPoolLike {
+    connect(): Promise<PgClientLike>;
+}
+export declare class PostgresCapsBackend implements CapsBackend {
+    #private;
+    /**
+     * `caseTtlSeconds` optionally lets `prune()` delete per-case reservations
+     * that old; by default they are kept, because deleting them would reset the
+     * per-case cap.
+     */
+    constructor(pool: PgPoolLike, options?: {
+        caseTtlSeconds?: number;
+    });
+    ensureSchema(): Promise<void>;
+    reserve(tenantId: string, reservationId: string, limits: readonly ResolvedCapLimit[], nowMs: number | undefined): Promise<void>;
+    refund(tenantId: string, reservationId: string, limits: readonly ResolvedCapLimit[]): Promise<void>;
+    usage(tenantId: string, limit: ResolvedCapLimit, nowMs: number | undefined): Promise<number>;
+    /**
+     * Delete expired reservations and counters left empty; returns the numbers
+     * deleted. Counters being reserved are locked and skipped, and a counter that
+     * still has reservations cannot be deleted (the foreign key refuses it,
+     * failing this run rather than losing a reservation; run it again).
+     */
+    prune(nowMs?: number): Promise<{
+        reservations: number;
+        counters: number;
+    }>;
+}
+//# sourceMappingURL=postgres.d.ts.map

package/dist/caps/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/caps/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAA2C,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9G,eAAO,MAAM,eAAe,48BA2B3B,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAC9H,8EAA8E;IAC9E,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;CAClC;AAYD,qBAAa,mBAAoB,YAAW,WAAW;;IAIrD;;;;OAIG;IACH,YAAY,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAO,EAOtE;IAEK,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CASlC;IAiEK,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,gBAAgB,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCpI;IAEK,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAaxG;IAEK,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CASjG;IAED;;;;;OAKG;IACG,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAgB/E;CACF"}

package/dist/caps/postgres.js

@@ -0,0 +1,221 @@
+/**
+ * Postgres caps backend: row locks serialize reservations per counter.
+ *
+ * A reservation runs in one READ COMMITTED transaction: it makes sure a row
+ * exists per counter in `grantex_cap_counters`, locks those rows in a fixed
+ * order (so concurrent reservations cannot deadlock), prunes and sums the
+ * counter's reservations in `grantex_cap_reservations`, and inserts the new
+ * reservation only if every limit holds. Time comes from the database
+ * (`clock_timestamp()`) unless a clock is injected for tests. Same tables and
+ * statements as the Python SDK's `PostgresCapsBackend`.
+ *
+ * Rows carry a SHA-256-derived hash of the tenant id, not the tenant id, in
+ * `tenant_id`: isolation comes from that hash being part of every key and
+ * query, and row-level security policies written against plain tenant ids do
+ * not match these rows.
+ *
+ * Expired rows are deleted lazily when their counter is next reserved. Run
+ * `prune()` periodically (for example hourly) to delete expired reservations,
+ * per-case reservations older than `caseTtlSeconds` if one is set, and
+ * counters with no reservations left.
+ *
+ * `pool` is a `pg` Pool, or anything with the same `connect()` / `query()` /
+ * `release()` shape. Create the tables with `CAPS_SCHEMA_SQL` through your own
+ * migration tool, or `ensureSchema()`.
+ */
+import { CapExceededError, WINDOW_MS, tenantHash } from './meter.js';
+export const CAPS_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS grantex_cap_counters (
+  tenant_id   TEXT NOT NULL,
+  counter_key TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, counter_key)
+);
+
+CREATE TABLE IF NOT EXISTS grantex_cap_reservations (
+  tenant_id      TEXT NOT NULL,
+  counter_key    TEXT NOT NULL,
+  reservation_id TEXT NOT NULL,
+  units          BIGINT NOT NULL CHECK (units >= 0),
+  reserved_at    TIMESTAMPTZ NOT NULL,
+  expires_at     TIMESTAMPTZ,
+  PRIMARY KEY (tenant_id, counter_key, reservation_id),
+  FOREIGN KEY (tenant_id, counter_key)
+    REFERENCES grantex_cap_counters (tenant_id, counter_key)
+);
+
+ALTER TABLE grantex_cap_reservations ADD COLUMN IF NOT EXISTS expires_at TIMESTAMPTZ;
+
+CREATE INDEX IF NOT EXISTS idx_grantex_cap_reservations_time
+  ON grantex_cap_reservations (tenant_id, counter_key, reserved_at);
+
+CREATE INDEX IF NOT EXISTS idx_grantex_cap_reservations_expiry
+  ON grantex_cap_reservations (expires_at)
+  WHERE expires_at IS NOT NULL;
+`;
+const NOW_SQL = 'SELECT CASE WHEN $1::bigint IS NULL THEN clock_timestamp() ELSE to_timestamp($1::bigint / 1000.0) END AS now';
+const LOCK_ATTEMPTS = 3;
+function int(value) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' || typeof value === 'bigint' ? Number(value) : Number.NaN;
+    if (!Number.isSafeInteger(n))
+        throw new Error('database returned an invalid usage');
+    return n;
+}
+export class PostgresCapsBackend {
+    #pool;
+    #caseTtlSeconds;
+    /**
+     * `caseTtlSeconds` optionally lets `prune()` delete per-case reservations
+     * that old; by default they are kept, because deleting them would reset the
+     * per-case cap.
+     */
+    constructor(pool, options = {}) {
+        const ttl = options.caseTtlSeconds;
+        if (ttl !== undefined && (!Number.isInteger(ttl) || ttl <= 0)) {
+            throw new Error('caseTtlSeconds must be a positive integer');
+        }
+        this.#pool = pool;
+        this.#caseTtlSeconds = ttl;
+    }
+    async ensureSchema() {
+        const client = await this.#pool.connect();
+        try {
+            for (const statement of CAPS_SCHEMA_SQL.split(';').map((s) => s.trim()).filter(Boolean)) {
+                await client.query(statement);
+            }
+        }
+        finally {
+            client.release();
+        }
+    }
+    static async #now(client, nowMs) {
+        const { rows } = await client.query(NOW_SQL, [nowMs ?? null]);
+        const row = rows[0];
+        if (row === undefined)
+            throw new Error('database returned no time');
+        return row['now'];
+    }
+    static async #used(client, tenant, key, windowMs, now, prune) {
+        let rows;
+        if (windowMs > 0) {
+            if (prune) {
+                await client.query('DELETE FROM grantex_cap_reservations WHERE tenant_id = $1 AND counter_key = $2 ' +
+                    'AND reserved_at <= $3::timestamptz - make_interval(secs => $4::double precision)', [tenant, key, now, windowMs / 1000]);
+            }
+            ({ rows } = await client.query('SELECT COALESCE(SUM(units), 0) AS used FROM grantex_cap_reservations ' +
+                'WHERE tenant_id = $1 AND counter_key = $2 AND reserved_at > $3::timestamptz - make_interval(secs => $4::double precision)', [tenant, key, now, windowMs / 1000]));
+        }
+        else {
+            ({ rows } = await client.query('SELECT COALESCE(SUM(units), 0) AS used FROM grantex_cap_reservations WHERE tenant_id = $1 AND counter_key = $2', [tenant, key]));
+        }
+        const row = rows[0];
+        if (row === undefined)
+            throw new Error('database returned no usage');
+        return int(row['used']);
+    }
+    #expirySeconds(limit) {
+        const window = WINDOW_MS[limit.window];
+        if (window > 0)
+            return window / 1000;
+        return this.#caseTtlSeconds ?? null;
+    }
+    /** Run `work` in a READ COMMITTED transaction; a connection whose rollback fails is destroyed. */
+    async #transaction(work) {
+        const client = await this.#pool.connect();
+        let releaseError;
+        try {
+            await client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+            try {
+                const result = await work(client);
+                await client.query('COMMIT');
+                return result;
+            }
+            catch (err) {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch (rollbackError) {
+                    // The original error propagates; the connection is not reused.
+                    releaseError = rollbackError instanceof Error ? rollbackError : new Error(String(rollbackError));
+                }
+                throw err;
+            }
+        }
+        finally {
+            client.release(releaseError);
+        }
+    }
+    async reserve(tenantId, reservationId, limits, nowMs) {
+        const tenant = await tenantHash(tenantId);
+        const ordered = [...limits].sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+        await this.#transaction(async (client) => {
+            for (const limit of ordered) {
+                let locked = false;
+                for (let attempt = 0; attempt < LOCK_ATTEMPTS && !locked; attempt += 1) {
+                    await client.query('INSERT INTO grantex_cap_counters (tenant_id, counter_key) VALUES ($1, $2) ON CONFLICT DO NOTHING', [tenant, limit.key]);
+                    const { rows } = await client.query('SELECT counter_key FROM grantex_cap_counters WHERE tenant_id = $1 AND counter_key = $2 FOR UPDATE', [tenant, limit.key]);
+                    // No row: prune() removed an empty counter between the two statements.
+                    locked = rows.length === 1;
+                }
+                if (!locked)
+                    throw new Error('caps counter row could not be locked');
+            }
+            // Read the time after the locks are held, so a reservation that waited
+            // is judged against the moment it actually runs.
+            const now = await PostgresCapsBackend.#now(client, nowMs);
+            for (const limit of ordered) {
+                const used = await PostgresCapsBackend.#used(client, tenant, limit.key, WINDOW_MS[limit.window], now, true);
+                if (used + limit.units > limit.limit) {
+                    throw new CapExceededError({
+                        limit: limit.limit, window: limit.window, used, requested: limit.units, scope: limit.scope, kind: limit.kind,
+                    });
+                }
+            }
+            for (const limit of ordered) {
+                await client.query('INSERT INTO grantex_cap_reservations (tenant_id, counter_key, reservation_id, units, reserved_at, expires_at) ' +
+                    'VALUES ($1, $2, $3, $4, $5::timestamptz, $5::timestamptz + make_interval(secs => $6::double precision))', [tenant, limit.key, reservationId, limit.units, now, this.#expirySeconds(limit)]);
+            }
+        });
+    }
+    async refund(tenantId, reservationId, limits) {
+        const tenant = await tenantHash(tenantId);
+        const client = await this.#pool.connect();
+        try {
+            for (const limit of limits) {
+                await client.query('DELETE FROM grantex_cap_reservations WHERE tenant_id = $1 AND counter_key = $2 AND reservation_id = $3', [tenant, limit.key, reservationId]);
+            }
+        }
+        finally {
+            client.release();
+        }
+    }
+    async usage(tenantId, limit, nowMs) {
+        const tenant = await tenantHash(tenantId);
+        const client = await this.#pool.connect();
+        try {
+            const now = await PostgresCapsBackend.#now(client, nowMs);
+            return await PostgresCapsBackend.#used(client, tenant, limit.key, WINDOW_MS[limit.window], now, false);
+        }
+        finally {
+            client.release();
+        }
+    }
+    /**
+     * Delete expired reservations and counters left empty; returns the numbers
+     * deleted. Counters being reserved are locked and skipped, and a counter that
+     * still has reservations cannot be deleted (the foreign key refuses it,
+     * failing this run rather than losing a reservation; run it again).
+     */
+    async prune(nowMs) {
+        return this.#transaction(async (client) => {
+            const now = await PostgresCapsBackend.#now(client, nowMs);
+            const expired = await client.query('DELETE FROM grantex_cap_reservations WHERE expires_at IS NOT NULL AND expires_at <= $1::timestamptz', [now]);
+            const empty = await client.query('DELETE FROM grantex_cap_counters WHERE (tenant_id, counter_key) IN (' +
+                ' SELECT c.tenant_id, c.counter_key FROM grantex_cap_counters c' +
+                ' WHERE NOT EXISTS (SELECT 1 FROM grantex_cap_reservations r' +
+                '   WHERE r.tenant_id = c.tenant_id AND r.counter_key = c.counter_key)' +
+                ' FOR UPDATE SKIP LOCKED)');
+            return { reservations: expired.rowCount ?? 0, counters: empty.rowCount ?? 0 };
+        });
+    }
+}
+//# sourceMappingURL=postgres.js.map

package/dist/caps/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../src/caps/postgres.ts"],"names":[],"mappings":"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"}

package/dist/caps/redis.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Redis caps backend: one Lua script reserves every limit atomically.
+ *
+ * Keys are tenant-scoped and share a hash tag, `grantex:caps:{<tenant>}:...`,
+ * so one reservation touches a single Redis Cluster slot. Each counter is a
+ * sorted set of `<reservation id>:<units>` members scored by reservation time
+ * plus a running total; rolling windows drop members older than the window
+ * before checking. Time comes from the Redis server (`TIME`) unless a clock is
+ * injected for tests.
+ *
+ * Requires Redis 6.0 or later (`SET ... KEEPTTL`). Run it with
+ * `maxmemory-policy noeviction`: an evicted counter would forget reservations
+ * and let calls exceed a cap. Per-hour and per-day keys expire one window plus
+ * 60 seconds after the last reservation on the counter; per-case keys only with
+ * `caseTtlSeconds`.
+ *
+ * The scripts are byte-identical to the Python SDK's (`grantex/caps/_redis.py`);
+ * a test in each SDK checks this.
+ */
+import { type CapsBackend, type ResolvedCapLimit } from './meter.js';
+export declare const RESERVE_SCRIPT = "\nlocal now\nif ARGV[1] ~= '' then\n  now = tonumber(ARGV[1])\nelse\n  local t = redis.call('TIME')\n  now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nend\nlocal rid = ARGV[2]\nlocal n = tonumber(ARGV[3])\nlocal case_ttl = tonumber(ARGV[4])\nfor i = 1, n do\n  local a = 4 + (i - 1) * 3\n  local limit = tonumber(ARGV[a + 1])\n  local window = tonumber(ARGV[a + 2])\n  local units = tonumber(ARGV[a + 3])\n  local zkey = KEYS[(i - 1) * 2 + 1]\n  local skey = KEYS[(i - 1) * 2 + 2]\n  local sum = tonumber(redis.call('GET', skey) or '0')\n  if window > 0 then\n    local expired = redis.call('ZRANGEBYSCORE', zkey, '-inf', now - window)\n    if #expired > 0 then\n      for _, member in ipairs(expired) do\n        sum = sum - tonumber(string.match(member, ':(%d+)$'))\n      end\n      if sum < 0 then sum = 0 end\n      redis.call('ZREMRANGEBYSCORE', zkey, '-inf', now - window)\n      redis.call('SET', skey, sum, 'KEEPTTL')\n    end\n  end\n  if sum + units > limit then\n    return {0, i, sum}\n  end\nend\nfor i = 1, n do\n  local a = 4 + (i - 1) * 3\n  local window = tonumber(ARGV[a + 2])\n  local units = tonumber(ARGV[a + 3])\n  local zkey = KEYS[(i - 1) * 2 + 1]\n  local skey = KEYS[(i - 1) * 2 + 2]\n  redis.call('ZADD', zkey, now, rid .. ':' .. units)\n  redis.call('INCRBY', skey, units)\n  local ttl = case_ttl\n  if window > 0 then ttl = window + 60000 end\n  if ttl > 0 then\n    redis.call('PEXPIRE', zkey, ttl)\n    redis.call('PEXPIRE', skey, ttl)\n  end\nend\nreturn {1, 0, 0}\n";
+export declare const REFUND_SCRIPT = "\nlocal rid = ARGV[1]\nlocal n = tonumber(ARGV[2])\nfor i = 1, n do\n  local units = ARGV[2 + i]\n  local zkey = KEYS[(i - 1) * 2 + 1]\n  local skey = KEYS[(i - 1) * 2 + 2]\n  if redis.call('ZREM', zkey, rid .. ':' .. units) == 1 then\n    local left = redis.call('DECRBY', skey, tonumber(units))\n    if left < 0 then redis.call('SET', skey, 0, 'KEEPTTL') end\n  end\nend\nreturn 1\n";
+export declare const USAGE_SCRIPT = "\nlocal now\nif ARGV[1] ~= '' then\n  now = tonumber(ARGV[1])\nelse\n  local t = redis.call('TIME')\n  now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)\nend\nlocal window = tonumber(ARGV[2])\nlocal sum = tonumber(redis.call('GET', KEYS[2]) or '0')\nif window > 0 then\n  for _, member in ipairs(redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', now - window)) do\n    sum = sum - tonumber(string.match(member, ':(%d+)$'))\n  end\nend\nif sum < 0 then sum = 0 end\nreturn sum\n";
+/** Runs a Lua script. Adapt your client, for example `ioredisRunner(new Redis(url))`. */
+export interface RedisScriptRunner {
+    evalScript(script: string, keys: readonly string[], args: readonly (string | number)[]): Promise<unknown>;
+}
+/** Adapter for an ioredis client (`client.eval(script, numKeys, ...keysAndArgs)`). */
+export declare function ioredisRunner(client: {
+    eval(script: string, numKeys: number, ...keysAndArgs: (string | number)[]): Promise<unknown>;
+}): RedisScriptRunner;
+export declare class RedisCapsBackend implements CapsBackend {
+    #private;
+    /**
+     * `caseTtlSeconds` optionally expires per-case counters; by default they never
+     * expire, because an expired per-case counter would reset the cap.
+     */
+    constructor(redis: RedisScriptRunner, options?: {
+        caseTtlSeconds?: number;
+    });
+    reserve(tenantId: string, reservationId: string, limits: readonly ResolvedCapLimit[], nowMs: number | undefined): Promise<void>;
+    refund(tenantId: string, reservationId: string, limits: readonly ResolvedCapLimit[]): Promise<void>;
+    usage(tenantId: string, limit: ResolvedCapLimit, nowMs: number | undefined): Promise<number>;
+}
+//# sourceMappingURL=redis.d.ts.map

package/dist/caps/redis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis.d.ts","sourceRoot":"","sources":["../../src/caps/redis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAA2C,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9G,eAAO,MAAM,cAAc,i/CAkD1B,CAAC;AAEF,eAAO,MAAM,aAAa,qYAazB,CAAC;AAEF,eAAO,MAAM,YAAY,2eAiBxB,CAAC;AAGF,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3G;AAED,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9F,GAAG,iBAAiB,CAIpB;AAaD,qBAAa,gBAAiB,YAAW,WAAW;;IAIlD;;;OAGG;IACH,YAAY,KAAK,EAAE,iBAAiB,EAAE,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAO,EAO9E;IAEK,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,gBAAgB,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBpI;IAEK,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxG;IAEK,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAMjG;CACF"}