@grantex/sdk 0.6.0 → 0.7.0

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"}

package/dist/caps/redis.js

@@ -0,0 +1,173 @@
+/**
+ * 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 { CapExceededError, WINDOW_MS, tenantHash } from './meter.js';
+// grantex caps redis script v1 begin
+export const RESERVE_SCRIPT = `
+local now
+if ARGV[1] ~= '' then
+  now = tonumber(ARGV[1])
+else
+  local t = redis.call('TIME')
+  now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+end
+local rid = ARGV[2]
+local n = tonumber(ARGV[3])
+local case_ttl = tonumber(ARGV[4])
+for i = 1, n do
+  local a = 4 + (i - 1) * 3
+  local limit = tonumber(ARGV[a + 1])
+  local window = tonumber(ARGV[a + 2])
+  local units = tonumber(ARGV[a + 3])
+  local zkey = KEYS[(i - 1) * 2 + 1]
+  local skey = KEYS[(i - 1) * 2 + 2]
+  local sum = tonumber(redis.call('GET', skey) or '0')
+  if window > 0 then
+    local expired = redis.call('ZRANGEBYSCORE', zkey, '-inf', now - window)
+    if #expired > 0 then
+      for _, member in ipairs(expired) do
+        sum = sum - tonumber(string.match(member, ':(%d+)$'))
+      end
+      if sum < 0 then sum = 0 end
+      redis.call('ZREMRANGEBYSCORE', zkey, '-inf', now - window)
+      redis.call('SET', skey, sum, 'KEEPTTL')
+    end
+  end
+  if sum + units > limit then
+    return {0, i, sum}
+  end
+end
+for i = 1, n do
+  local a = 4 + (i - 1) * 3
+  local window = tonumber(ARGV[a + 2])
+  local units = tonumber(ARGV[a + 3])
+  local zkey = KEYS[(i - 1) * 2 + 1]
+  local skey = KEYS[(i - 1) * 2 + 2]
+  redis.call('ZADD', zkey, now, rid .. ':' .. units)
+  redis.call('INCRBY', skey, units)
+  local ttl = case_ttl
+  if window > 0 then ttl = window + 60000 end
+  if ttl > 0 then
+    redis.call('PEXPIRE', zkey, ttl)
+    redis.call('PEXPIRE', skey, ttl)
+  end
+end
+return {1, 0, 0}
+`;
+export const REFUND_SCRIPT = `
+local rid = ARGV[1]
+local n = tonumber(ARGV[2])
+for i = 1, n do
+  local units = ARGV[2 + i]
+  local zkey = KEYS[(i - 1) * 2 + 1]
+  local skey = KEYS[(i - 1) * 2 + 2]
+  if redis.call('ZREM', zkey, rid .. ':' .. units) == 1 then
+    local left = redis.call('DECRBY', skey, tonumber(units))
+    if left < 0 then redis.call('SET', skey, 0, 'KEEPTTL') end
+  end
+end
+return 1
+`;
+export const USAGE_SCRIPT = `
+local now
+if ARGV[1] ~= '' then
+  now = tonumber(ARGV[1])
+else
+  local t = redis.call('TIME')
+  now = tonumber(t[1]) * 1000 + math.floor(tonumber(t[2]) / 1000)
+end
+local window = tonumber(ARGV[2])
+local sum = tonumber(redis.call('GET', KEYS[2]) or '0')
+if window > 0 then
+  for _, member in ipairs(redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', now - window)) do
+    sum = sum - tonumber(string.match(member, ':(%d+)$'))
+  end
+end
+if sum < 0 then sum = 0 end
+return sum
+`;
+/** Adapter for an ioredis client (`client.eval(script, numKeys, ...keysAndArgs)`). */
+export function ioredisRunner(client) {
+    return {
+        evalScript: (script, keys, args) => client.eval(script, keys.length, ...keys, ...args),
+    };
+}
+async function keysFor(tenantId, limit) {
+    const base = `grantex:caps:{${await tenantHash(tenantId)}}:${limit.key}`;
+    return [`${base}:z`, `${base}:s`];
+}
+function toInt(value) {
+    const n = typeof value === 'number' ? value : typeof value === 'string' ? Number(value) : Number.NaN;
+    if (!Number.isInteger(n))
+        throw new Error('unexpected caps script result');
+    return n;
+}
+export class RedisCapsBackend {
+    #redis;
+    #caseTtlMs;
+    /**
+     * `caseTtlSeconds` optionally expires per-case counters; by default they never
+     * expire, because an expired per-case counter would reset the cap.
+     */
+    constructor(redis, options = {}) {
+        const ttl = options.caseTtlSeconds;
+        if (ttl !== undefined && (!Number.isInteger(ttl) || ttl <= 0)) {
+            throw new Error('caseTtlSeconds must be a positive integer');
+        }
+        this.#redis = redis;
+        this.#caseTtlMs = ttl === undefined ? 0 : ttl * 1000;
+    }
+    async reserve(tenantId, reservationId, limits, nowMs) {
+        const keys = [];
+        const args = [nowMs === undefined ? '' : String(nowMs), reservationId, limits.length, this.#caseTtlMs];
+        for (const limit of limits) {
+            keys.push(...(await keysFor(tenantId, limit)));
+            args.push(limit.limit, WINDOW_MS[limit.window], limit.units);
+        }
+        const result = await this.#redis.evalScript(RESERVE_SCRIPT, keys, args);
+        if (!Array.isArray(result) || result.length !== 3)
+            throw new Error('unexpected caps script result');
+        const [ok, index, used] = result.map(toInt);
+        if (ok === 1)
+            return;
+        const limit = limits[index - 1];
+        if (limit === undefined)
+            throw new Error('unexpected caps script result');
+        throw new CapExceededError({
+            limit: limit.limit, window: limit.window, used, requested: limit.units, scope: limit.scope, kind: limit.kind,
+        });
+    }
+    async refund(tenantId, reservationId, limits) {
+        const keys = [];
+        const args = [reservationId, limits.length];
+        for (const limit of limits) {
+            keys.push(...(await keysFor(tenantId, limit)));
+            args.push(limit.units);
+        }
+        await this.#redis.evalScript(REFUND_SCRIPT, keys, args);
+    }
+    async usage(tenantId, limit, nowMs) {
+        const result = await this.#redis.evalScript(USAGE_SCRIPT, await keysFor(tenantId, limit), [
+            nowMs === undefined ? '' : String(nowMs),
+            WINDOW_MS[limit.window],
+        ]);
+        return toInt(result);
+    }
+}
+//# sourceMappingURL=redis.js.map

package/dist/caps/redis.js.map

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

package/dist/client.d.ts

@@ -21,6 +21,8 @@ import { PassportsClient } from './resources/passports.js';
 import { DpdpClient } from './resources/dpdp.js';
 import { CommerceClient } from './resources/commerce.js';
 import { ToolManifest, type EnforceOptions, type EnforceResult, type WrapToolOptions, type EnforceMiddlewareOptions } from './manifest.js';
+import { RevocationFeed, type RevocationFeedState } from './revocations/index.js';
+import { DecisionsClient } from './resources/decisions.js';
 import type { AuthorizationRequest, AuthorizeParams, GrantexClientOptions, RateLimit, RotateKeyResponse, SignupParams, SignupResponse, UpdateDeveloperSettingsParams, UpdateDeveloperSettingsResponse } from './types.js';
 export declare class Grantex {
     #private;
@@ -46,6 +48,7 @@ export declare class Grantex {
     readonly passports: PassportsClient;
     readonly dpdp: DpdpClient;
     readonly commerce: CommerceClient;
+    readonly decisions: DecisionsClient;
     get lastRateLimit(): RateLimit | undefined;
     constructor(options?: GrantexClientOptions);
     /**
@@ -101,6 +104,15 @@ export declare class Grantex {
      * if (!result.allowed) throw new Error(result.reason);
      * ```
      */
+    /**
+     * The revocation feed this client uses for `revocationCheck: 'feed'`,
+     * started on first use. Call `stopRevocationFeed()` to close it.
+     */
+    revocationFeed(): RevocationFeed;
+    /** What the revocation feed knows, and whether it is fresh enough to be trusted. */
+    revocationFeedState(): RevocationFeedState | undefined;
+    /** Stop following the revocation feed and release its connection. */
+    stopRevocationFeed(): Promise<void>;
     enforce(options: EnforceOptions): Promise<EnforceResult>;
     /**
      * Wrap a LangChain StructuredTool with automatic Grantex scope enforcement.

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAoB,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAE7J,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACpB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,6BAA6B,EAC7B,+BAA+B,EAEhC,MAAM,YAAY,CAAC;AAIpB,qBAAa,OAAO;;IAOlB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,iBAAiB,EAAE,uBAAuB,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAElC,IAAI,aAAa,IAAI,SAAS,GAAG,SAAS,CAEzC;IAED,YAAY,OAAO,GAAE,oBAAyB,EA4C7C;IAED;;;OAGG;IACH,OAAa,MAAM,CACjB,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO,GACjC,OAAO,CAAC,cAAc,CAAC,CAqBzB;IAED;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAMhE;IAED;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAEtC;IAED;;OAEG;IACH,cAAc,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAE9F;IAED;;;OAGG;IACH,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAEzC;IAED;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,IAAI,CAI7C;IAED;;;OAGG;IACG,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASzD;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAmF7D;IA8DD;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,CAAC,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;KAAE,EACxG,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,eAAe,GACvB,CAAC,CA+BH;IAED;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAkCxG;CACF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}