@grantex/sdk 0.6.0 → 0.7.0

package/dist/caps/limits.js

@@ -0,0 +1,109 @@
+/**
+ * Derive the counters a tool call is metered against. Mirrors the Python SDK's
+ * `grantex.caps._limits`.
+ *
+ * - The **manifest** (`caps` on the tool) declares tenant-wide counters per tool.
+ * - The **grant** (`caps` in its `urn:grantex:tools:v1` entry) declares counters
+ *   for that grant only: per tool (`{"verify_business": {"per_hour": 50}}`)
+ *   and a connector cost-unit budget (`{"cost_units": {"per_day": 5000}}`).
+ *
+ * Every declared cap is its own counter and all of them must hold. A call's
+ * cost is the sum of the manifest `cost_units` for the components it incurs
+ * (all declared components unless the caller names them).
+ */
+import { CapsConfigurationError, MAX_COUNT } from './meter.js';
+const WINDOWS = ['per_hour', 'per_day', 'per_case'];
+const MAX_ID = 256;
+export const CASE_REQUIRED = 'case_required';
+export const INVALID_CASE_ID = 'invalid_case_id';
+export const INVALID_COST_COMPONENT = 'invalid_cost_component';
+export const MALFORMED_GRANT_CAPS = 'malformed_grant_caps';
+/** Unambiguous counter identity; identical to the Python SDK's `counter_id`. */
+export function counterId(...parts) {
+    return JSON.stringify(parts);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function windows(raw, where) {
+    if (!isPlainObject(raw) || Object.keys(raw).length === 0) {
+        throw new CapsConfigurationError(`${where} must be a non-empty object`, MALFORMED_GRANT_CAPS);
+    }
+    const out = {};
+    for (const [window, value] of Object.entries(raw)) {
+        if (!WINDOWS.includes(window)) {
+            throw new CapsConfigurationError(`${where} has unknown window ${JSON.stringify(window)}`, MALFORMED_GRANT_CAPS);
+        }
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > MAX_COUNT) {
+            throw new CapsConfigurationError(`${where}.${window} must be an integer between 0 and ${MAX_COUNT}`, MALFORMED_GRANT_CAPS);
+        }
+        out[window] = value;
+    }
+    return out;
+}
+/** Validate a grant entry's `caps`; `cost_units` is the connector budget. */
+export function parseGrantCaps(caps) {
+    const out = new Map();
+    if (caps === undefined || caps === null)
+        return out;
+    if (!isPlainObject(caps))
+        throw new CapsConfigurationError('grant caps must be an object', MALFORMED_GRANT_CAPS);
+    for (const [name, value] of Object.entries(caps))
+        out.set(name, windows(value, `caps.${name}`));
+    return out;
+}
+/**
+ * The limits for one call of `tool`.
+ *
+ * @throws {CapsConfigurationError} with `subReason` `case_required`,
+ *   `invalid_case_id`, `invalid_cost_component` or `malformed_grant_caps`.
+ */
+export function buildCapLimits(options) {
+    const { connector, tool, spec, grantId, caseId, costComponents } = options;
+    if (caseId !== undefined && (typeof caseId !== 'string' || caseId.length === 0 || caseId.length > MAX_ID)) {
+        throw new CapsConfigurationError('caseId must be a non-empty string of at most 256 characters', INVALID_CASE_ID);
+    }
+    const declared = { ...(spec.costUnits ?? {}) };
+    const components = costComponents === undefined ? Object.keys(declared) : [...costComponents];
+    if (costComponents !== undefined
+        && (new Set(components).size !== components.length || components.some((c) => !Object.prototype.hasOwnProperty.call(declared, c)))) {
+        throw new CapsConfigurationError(`cost components ${JSON.stringify(components)} are not all declared by tool ${JSON.stringify(tool)}`, INVALID_COST_COMPONENT);
+    }
+    if (costComponents !== undefined && Object.keys(declared).length > 0 && components.length === 0) {
+        // A call to a tool that declares cost units incurs at least one of them;
+        // an empty list would skip the budget entirely.
+        throw new CapsConfigurationError(`tool ${JSON.stringify(tool)} declares cost units, so costComponents cannot be empty`, INVALID_COST_COMPONENT);
+    }
+    const cost = components.reduce((sum, c) => sum + declared[c], 0);
+    if (cost > MAX_COUNT) {
+        throw new CapsConfigurationError(`the cost of this call (${cost} units) exceeds ${MAX_COUNT}`, INVALID_COST_COMPONENT);
+    }
+    const grant = parseGrantCaps(options.grantCaps);
+    const limits = [];
+    const add = (scopeParts, caps, units, scope, kind) => {
+        for (const window of WINDOWS) {
+            const limit = caps[window];
+            if (limit === undefined)
+                continue;
+            const parts = [...scopeParts, kind, window];
+            if (window === 'per_case') {
+                if (caseId === undefined) {
+                    throw new CapsConfigurationError(`${scope} per_case cap on ${connector}.${tool} needs a caseId`, CASE_REQUIRED);
+                }
+                parts.push(caseId);
+            }
+            limits.push({ counter: counterId(...parts), limit, window, units, scope, kind });
+        }
+    };
+    if (spec.caps !== undefined) {
+        add(['manifest', connector, tool], { per_hour: spec.caps.perHour, per_day: spec.caps.perDay, per_case: spec.caps.perCase }, 1, 'manifest', 'calls');
+    }
+    const toolCaps = grant.get(tool);
+    if (toolCaps !== undefined && tool !== 'cost_units')
+        add(['grant', grantId, connector, tool], toolCaps, 1, 'grant', 'calls');
+    const budget = grant.get('cost_units');
+    if (cost > 0 && budget !== undefined)
+        add(['grant', grantId, connector], budget, cost, 'grant', 'cost_units');
+    return limits;
+}
+//# sourceMappingURL=limits.js.map

package/dist/caps/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/caps/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAiC,MAAM,YAAY,CAAC;AAE9F,MAAM,OAAO,GAAyB,CAAC,UAAU,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;AAC1E,MAAM,MAAM,GAAG,GAAG,CAAC;AAEnB,MAAM,CAAC,MAAM,aAAa,GAAG,eAAe,CAAC;AAC7C,MAAM,CAAC,MAAM,eAAe,GAAG,iBAAiB,CAAC;AACjD,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D,gFAAgF;AAChF,MAAM,UAAU,SAAS,CAAC,GAAG,KAAe;IAC1C,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,OAAO,CAAC,GAAY,EAAE,KAAa;IAC1C,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,sBAAsB,CAAC,GAAG,KAAK,6BAA6B,EAAE,oBAAoB,CAAC,CAAC;IAChG,CAAC;IACD,MAAM,GAAG,GAAuC,EAAE,CAAC;IACnD,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,IAAI,CAAE,OAA6B,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACrD,MAAM,IAAI,sBAAsB,CAAC,GAAG,KAAK,uBAAuB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,EAAE,oBAAoB,CAAC,CAAC;QAClH,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;YAC5F,MAAM,IAAI,sBAAsB,CAAC,GAAG,KAAK,IAAI,MAAM,qCAAqC,SAAS,EAAE,EAAE,oBAAoB,CAAC,CAAC;QAC7H,CAAC;QACD,GAAG,CAAC,MAAmB,CAAC,GAAG,KAAK,CAAC;IACnC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,cAAc,CAAC,IAAa;IAC1C,MAAM,GAAG,GAAG,IAAI,GAAG,EAA8C,CAAC;IAClE,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,GAAG,CAAC;IACpD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,sBAAsB,CAAC,8BAA8B,EAAE,oBAAoB,CAAC,CAAC;IACjH,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,CAAC;IAChG,OAAO,GAAG,CAAC;AACb,CAAC;AAYD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC;IAC3E,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;QAC1G,MAAM,IAAI,sBAAsB,CAAC,6DAA6D,EAAE,eAAe,CAAC,CAAC;IACnH,CAAC;IAED,MAAM,QAAQ,GAA2B,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,CAAC;IACvE,MAAM,UAAU,GAAG,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC;IAC9F,IACE,cAAc,KAAK,SAAS;WACzB,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,MAAM,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,EACjI,CAAC;QACD,MAAM,IAAI,sBAAsB,CAC9B,mBAAmB,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,iCAAiC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EACpG,sBAAsB,CACvB,CAAC;IACJ,CAAC;IACD,IAAI,cAAc,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChG,yEAAyE;QACzE,gDAAgD;QAChD,MAAM,IAAI,sBAAsB,CAC9B,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,yDAAyD,EACrF,sBAAsB,CACvB,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAI,QAAQ,CAAC,CAAC,CAAY,EAAE,CAAC,CAAC,CAAC;IAC7E,IAAI,IAAI,GAAG,SAAS,EAAE,CAAC;QACrB,MAAM,IAAI,sBAAsB,CAAC,0BAA0B,IAAI,mBAAmB,SAAS,EAAE,EAAE,sBAAsB,CAAC,CAAC;IACzH,CAAC;IAED,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,MAAM,GAAe,EAAE,CAAC;IAC9B,MAAM,GAAG,GAAG,CAAC,UAAoB,EAAE,IAAwC,EAAE,KAAa,EAAE,KAAa,EAAE,IAAY,EAAE,EAAE;QACzH,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3B,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAClC,MAAM,KAAK,GAAG,CAAC,GAAG,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAC5C,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;gBAC1B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACzB,MAAM,IAAI,sBAAsB,CAAC,GAAG,KAAK,oBAAoB,SAAS,IAAI,IAAI,iBAAiB,EAAE,aAAa,CAAC,CAAC;gBAClH,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrB,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,GAAG,CAAC,CAAC,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAwC,EAAE,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;IAC5L,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,QAAQ,KAAK,SAAS,IAAI,IAAI,KAAK,YAAY;QAAE,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7H,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACvC,IAAI,IAAI,GAAG,CAAC,IAAI,MAAM,KAAK,SAAS;QAAE,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;IAC9G,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/caps/memory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * In-process caps backend. **For tests only.**
+ *
+ * Counters live in one process's memory: they are not shared between workers,
+ * are lost on restart, and would let a multi-process deployment exceed every
+ * cap. Use the Redis or Postgres backend in any deployment.
+ */
+import { type CapsBackend, type ResolvedCapLimit } from './meter.js';
+export declare class InMemoryCapsBackend implements CapsBackend {
+    #private;
+    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=memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/caps/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAA2C,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAQ9G,qBAAa,mBAAoB,YAAW,WAAW;;IAkB/C,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,CAiBpI;IAEK,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxG;IAEK,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAEjG;CACF"}

package/dist/caps/memory.js

@@ -0,0 +1,57 @@
+/**
+ * In-process caps backend. **For tests only.**
+ *
+ * Counters live in one process's memory: they are not shared between workers,
+ * are lost on restart, and would let a multi-process deployment exceed every
+ * cap. Use the Redis or Postgres backend in any deployment.
+ */
+import { CapExceededError, WINDOW_MS, tenantHash } from './meter.js';
+export class InMemoryCapsBackend {
+    #counters = new Map();
+    async #entries(tenantId, limit, now) {
+        const id = `${await tenantHash(tenantId)}:${limit.key}`;
+        let entries = this.#counters.get(id);
+        if (entries === undefined) {
+            entries = [];
+            this.#counters.set(id, entries);
+        }
+        const window = WINDOW_MS[limit.window];
+        if (window > 0) {
+            const live = entries.filter((e) => e.at > now - window);
+            entries.splice(0, entries.length, ...live);
+        }
+        return entries;
+    }
+    async reserve(tenantId, reservationId, limits, nowMs) {
+        const now = nowMs ?? Date.now();
+        // Resolve every counter before checking, then check and record with no
+        // await in between: JavaScript runs this block without interleaving.
+        const all = [];
+        for (const limit of limits)
+            all.push(await this.#entries(tenantId, limit, now));
+        limits.forEach((limit, i) => {
+            const used = all[i].reduce((sum, e) => sum + e.units, 0);
+            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,
+                });
+            }
+        });
+        limits.forEach((limit, i) => {
+            all[i].push({ at: now, reservationId, units: limit.units });
+        });
+    }
+    async refund(tenantId, reservationId, limits) {
+        for (const limit of limits) {
+            const entries = this.#counters.get(`${await tenantHash(tenantId)}:${limit.key}`);
+            if (entries === undefined)
+                continue;
+            const kept = entries.filter((e) => e.reservationId !== reservationId);
+            entries.splice(0, entries.length, ...kept);
+        }
+    }
+    async usage(tenantId, limit, nowMs) {
+        return (await this.#entries(tenantId, limit, nowMs ?? Date.now())).reduce((sum, e) => sum + e.units, 0);
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/caps/memory.js.map

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

package/dist/caps/meter.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Caps meter: atomic reservation of call caps and cost-unit budgets.
+ * Mirrors the Python SDK's `grantex.caps`; both address the same counters.
+ */
+export declare const CAP_ERROR_CODE = "E1008";
+export type CapWindow = 'per_hour' | 'per_day' | 'per_case';
+/** `off` skips caps, `warn` allows over-cap calls and reports them, `enforce` denies them. */
+export type CapsMode = 'off' | 'warn' | 'enforce';
+export declare const CAPS_MODES: readonly CapsMode[];
+/** Rolling window length per window name; `per_case` has no time window. */
+export declare const WINDOW_MS: Readonly<Record<CapWindow, number>>;
+export declare const MAX_COUNT = 2147483647;
+/** One counter a call is metered against. */
+export interface CapLimit {
+    /** Counter identity within a tenant; per-case counters must include the case. */
+    counter: string;
+    limit: number;
+    window: CapWindow;
+    /** Units this call consumes (default 1). */
+    units?: number;
+    /** `manifest` or `grant` (default `manifest`). */
+    scope?: string;
+    /** `calls` or `cost_units` (default `calls`). */
+    kind?: string;
+}
+/** A validated limit with defaults applied. */
+export interface ResolvedCapLimit extends Required<CapLimit> {
+    /** Stable, fixed-length storage key (SHA-256 hex). */
+    key: string;
+}
+/** Units reserved for one call. Keep it to refund a call proven unsent. */
+export interface Reservation {
+    reservationId: string;
+    tenantId: string;
+    limits: readonly ResolvedCapLimit[];
+}
+export interface CounterUsage {
+    limit: ResolvedCapLimit;
+    used: number;
+    remaining: number;
+}
+/** A reservation would exceed a cap. `code` is `E1008`. */
+export declare class CapExceededError extends Error {
+    readonly code = "E1008";
+    readonly reason = "cap_exceeded";
+    readonly limit: number;
+    readonly window: CapWindow;
+    readonly used: number;
+    readonly requested: number;
+    readonly scope: string;
+    readonly kind: string;
+    constructor(args: {
+        limit: number;
+        window: CapWindow;
+        used: number;
+        requested: number;
+        scope: string;
+        kind: string;
+    });
+}
+/** The caps backend could not answer. Callers must treat the call as denied. */
+export declare class MeterUnavailableError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Limits or arguments are invalid. `subReason` names why. */
+export declare class CapsConfigurationError extends Error {
+    readonly subReason: string;
+    constructor(message: string, subReason?: string);
+}
+/** Storage for counters. Implementations must be atomic across all limits. */
+export interface CapsBackend {
+    /** Reserve every limit or none; throw `CapExceededError` naming the first limit exceeded. */
+    reserve(tenantId: string, reservationId: string, limits: readonly ResolvedCapLimit[], nowMs: number | undefined): Promise<void>;
+    /** Remove a reservation. Idempotent. */
+    refund(tenantId: string, reservationId: string, limits: readonly ResolvedCapLimit[], nowMs: number | undefined): Promise<void>;
+    /** Units currently held by the counter within its window. */
+    usage(tenantId: string, limit: ResolvedCapLimit, nowMs: number | undefined): Promise<number>;
+}
+/** Storage key for a counter; identical to the Python SDK's `CapLimit.key()`. */
+export declare function counterKey(window: CapWindow, counter: string): Promise<string>;
+/** Fixed-length tenant component for storage keys. */
+export declare function tenantHash(tenantId: string): Promise<string>;
+/** Validate a reservation's arguments and apply defaults. */
+export declare function resolveLimits(tenantId: unknown, limits: readonly CapLimit[]): Promise<ResolvedCapLimit[]>;
+/**
+ * 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 declare class CapsMeter {
+    #private;
+    constructor(backend: CapsBackend, options?: {
+        clock?: () => number;
+    });
+    reserve(tenantId: string, limits: readonly CapLimit[]): Promise<Reservation>;
+    /** Release a reservation whose provider call was proven not sent. */
+    refundUnsent(reservation: Reservation): Promise<void>;
+    /** Current usage of each counter, for display (consent page, case view). */
+    usage(tenantId: string, limits: readonly CapLimit[]): Promise<CounterUsage[]>;
+}
+//# sourceMappingURL=meter.d.ts.map

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

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

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