@grantex/sdk 0.5.1 → 0.7.0

package/dist/canonical.js

@@ -0,0 +1,163 @@
+/**
+ * JSON Canonicalization Scheme (RFC 8785).
+ *
+ * `canonicalize` turns a JSON value into its canonical text: object members
+ * sorted by the UTF-16 code units of their names, no insignificant
+ * whitespace, strings escaped as `JSON.stringify` escapes them and numbers in
+ * the ECMAScript `Number` format. Two values that differ only in member order,
+ * whitespace or number spelling canonicalise to the same text.
+ *
+ * The input must be I-JSON (RFC 7493). Anything without a single canonical
+ * form throws `CanonicalizationError` instead of being coerced or dropped:
+ * `NaN` and infinities; strings or member names with an unpaired surrogate;
+ * `undefined`, functions, symbols, bigints, sparse arrays and objects that
+ * are not plain objects (such as `Date` or `Map`, whose `toJSON` is not
+ * consulted); nesting deeper than `MAX_DEPTH`.
+ *
+ * The Python SDK implements the same rules in `grantex.canonical`; both are
+ * tested against the RFC 8785 test vectors and the shared fixtures in
+ * `spec/examples/canonicalization/`. Python additionally refuses integers
+ * whose digits are not the canonical form of a double (such as 2^53 + 1);
+ * a JavaScript number has already been rounded by the parser.
+ */
+/** Deepest nesting of arrays and objects accepted. */
+export const MAX_DEPTH = 64;
+/** The value has no RFC 8785 canonical form. */
+export class CanonicalizationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CanonicalizationError';
+    }
+}
+const LONE_SURROGATE = /[\uD800-\uDFFF]/u;
+/** Returns the RFC 8785 canonical JSON text of `value`. */
+export function canonicalize(value) {
+    const out = [];
+    write(value, out, 0);
+    return out.join('');
+}
+/** Returns the RFC 8785 canonical JSON of `value` as UTF-8 bytes. */
+export function canonicalizeToBytes(value) {
+    return new TextEncoder().encode(canonicalize(value));
+}
+/** Serialises a finite number as `Number.prototype.toString` does (`-0` as `0`). */
+export function serializeNumber(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new CanonicalizationError('NaN and infinite numbers have no JSON form');
+    }
+    // JSON.stringify applies Number::toString and writes -0 as 0.
+    return JSON.stringify(value);
+}
+function write(value, out, depth) {
+    if (value === null) {
+        out.push('null');
+        return;
+    }
+    switch (typeof value) {
+        case 'boolean':
+            out.push(value ? 'true' : 'false');
+            return;
+        case 'number':
+            out.push(serializeNumber(value));
+            return;
+        case 'string':
+            out.push(serializeString(value));
+            return;
+        case 'object':
+            break;
+        default:
+            throw new CanonicalizationError(`value of type ${typeof value} has no JSON form`);
+    }
+    if (depth >= MAX_DEPTH) {
+        throw new CanonicalizationError(`nesting deeper than ${MAX_DEPTH} levels`);
+    }
+    if (Array.isArray(value)) {
+        out.push('[');
+        for (let index = 0; index < value.length; index++) {
+            if (!Object.prototype.hasOwnProperty.call(value, index)) {
+                throw new CanonicalizationError('sparse arrays have no JSON form');
+            }
+            if (index > 0)
+                out.push(',');
+            write(value[index], out, depth + 1);
+        }
+        out.push(']');
+        return;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new CanonicalizationError('only plain objects have a JSON form');
+    }
+    const record = value;
+    // Array.prototype.sort without a comparator orders strings by UTF-16 code units.
+    const keys = Object.keys(record).sort();
+    out.push('{');
+    keys.forEach((key, index) => {
+        if (index > 0)
+            out.push(',');
+        out.push(serializeString(key));
+        out.push(':');
+        write(record[key], out, depth + 1);
+    });
+    out.push('}');
+}
+function serializeString(value) {
+    if (LONE_SURROGATE.test(value)) {
+        throw new CanonicalizationError('string contains an unpaired surrogate');
+    }
+    // For well-formed strings JSON.stringify escapes exactly as RFC 8785 requires:
+    // \b \t \n \f \r \" \\ as two-character escapes, other C0 controls as \u00xx.
+    return JSON.stringify(value);
+}
+/** A JSON text repeats a member name within one object. */
+export class DuplicateKeyError extends CanonicalizationError {
+    key;
+    constructor(key) {
+        super(`duplicate member name ${JSON.stringify(key)}`);
+        this.name = 'DuplicateKeyError';
+        this.key = key;
+    }
+}
+/**
+ * Parses JSON text like `JSON.parse`, but throws `DuplicateKeyError` when an
+ * object repeats a member name (after unescaping), instead of silently keeping
+ * the last value. Use it wherever the raw text of a value to canonicalise is
+ * available.
+ */
+export function parseJsonRejectingDuplicates(text) {
+    const value = JSON.parse(text);
+    const stack = [];
+    let i = 0;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '"') {
+            let j = i + 1;
+            while (j < text.length && text[j] !== '"')
+                j += text[j] === '\\' ? 2 : 1;
+            const top = stack[stack.length - 1];
+            if (top?.keys && top.expectKey) {
+                const key = JSON.parse(text.slice(i, j + 1));
+                if (top.keys.has(key))
+                    throw new DuplicateKeyError(key);
+                top.keys.add(key);
+                top.expectKey = false;
+            }
+            i = j + 1;
+            continue;
+        }
+        if (ch === '{')
+            stack.push({ keys: new Set(), expectKey: true });
+        else if (ch === '[')
+            stack.push({ keys: null, expectKey: false });
+        else if (ch === '}' || ch === ']')
+            stack.pop();
+        else if (ch === ',') {
+            const top = stack[stack.length - 1];
+            if (top?.keys)
+                top.expectKey = true;
+        }
+        i += 1;
+    }
+    return value;
+}
+//# sourceMappingURL=canonical.js.map

package/dist/canonical.js.map

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

package/dist/caps/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Call caps and cost-unit budgets for tool calls.
+ *
+ * `CapsMeter` reserves units against every applicable counter atomically,
+ * before the call that incurs cost. Backends: `RedisCapsBackend` (Lua script,
+ * tenant-scoped keys; preferred), `PostgresCapsBackend` (row locks and upserts,
+ * for deployments without Redis) and `InMemoryCapsBackend` (**tests only**).
+ *
+ * There is no automatic failover between backends: two stores would keep two
+ * sets of counters and concurrent calls could exceed a cap. If the configured
+ * backend is unavailable the meter throws `MeterUnavailableError` and
+ * `enforce()` denies. See docs/concepts/caps-and-metering.md.
+ */
+export { CAPS_MODES, CAP_ERROR_CODE, CapExceededError, CapsConfigurationError, CapsMeter, MAX_COUNT, MeterUnavailableError, WINDOW_MS, counterKey, resolveLimits, tenantHash, type CapLimit, type CapWindow, type CapsMode, type CapsBackend, type CounterUsage, type Reservation, type ResolvedCapLimit, } from './meter.js';
+export { InMemoryCapsBackend } from './memory.js';
+export { REFUND_SCRIPT, RESERVE_SCRIPT, USAGE_SCRIPT, RedisCapsBackend, ioredisRunner, type RedisScriptRunner, } from './redis.js';
+export { CAPS_SCHEMA_SQL, PostgresCapsBackend, type PgClientLike, type PgPoolLike } from './postgres.js';
+export { CASE_REQUIRED, INVALID_CASE_ID, INVALID_COST_COMPONENT, MALFORMED_GRANT_CAPS, buildCapLimits, counterId, parseGrantCaps, type BuildCapLimitsOptions, } from './limits.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/caps/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,qBAAqB,EACrB,SAAS,EACT,UAAU,EACV,aAAa,EACb,UAAU,EACV,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AACzG,OAAO,EACL,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,aAAa,CAAC"}

package/dist/caps/index.js

@@ -0,0 +1,19 @@
+/**
+ * Call caps and cost-unit budgets for tool calls.
+ *
+ * `CapsMeter` reserves units against every applicable counter atomically,
+ * before the call that incurs cost. Backends: `RedisCapsBackend` (Lua script,
+ * tenant-scoped keys; preferred), `PostgresCapsBackend` (row locks and upserts,
+ * for deployments without Redis) and `InMemoryCapsBackend` (**tests only**).
+ *
+ * There is no automatic failover between backends: two stores would keep two
+ * sets of counters and concurrent calls could exceed a cap. If the configured
+ * backend is unavailable the meter throws `MeterUnavailableError` and
+ * `enforce()` denies. See docs/concepts/caps-and-metering.md.
+ */
+export { CAPS_MODES, CAP_ERROR_CODE, CapExceededError, CapsConfigurationError, CapsMeter, MAX_COUNT, MeterUnavailableError, WINDOW_MS, counterKey, resolveLimits, tenantHash, } from './meter.js';
+export { InMemoryCapsBackend } from './memory.js';
+export { REFUND_SCRIPT, RESERVE_SCRIPT, USAGE_SCRIPT, RedisCapsBackend, ioredisRunner, } from './redis.js';
+export { CAPS_SCHEMA_SQL, PostgresCapsBackend } from './postgres.js';
+export { CASE_REQUIRED, INVALID_CASE_ID, INVALID_COST_COMPONENT, MALFORMED_GRANT_CAPS, buildCapLimits, counterId, parseGrantCaps, } from './limits.js';
+//# sourceMappingURL=index.js.map

package/dist/caps/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/caps/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,sBAAsB,EACtB,SAAS,EACT,SAAS,EACT,qBAAqB,EACrB,SAAS,EACT,UAAU,EACV,aAAa,EACb,UAAU,GAQX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,aAAa,EACb,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,aAAa,GAEd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAsC,MAAM,eAAe,CAAC;AACzG,OAAO,EACL,aAAa,EACb,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,EACd,SAAS,EACT,cAAc,GAEf,MAAM,aAAa,CAAC"}

package/dist/caps/limits.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 type { ToolSpec } from '../manifest.js';
+import { type CapLimit, type CapWindow } from './meter.js';
+export declare const CASE_REQUIRED = "case_required";
+export declare const INVALID_CASE_ID = "invalid_case_id";
+export declare const INVALID_COST_COMPONENT = "invalid_cost_component";
+export declare const MALFORMED_GRANT_CAPS = "malformed_grant_caps";
+/** Unambiguous counter identity; identical to the Python SDK's `counter_id`. */
+export declare function counterId(...parts: string[]): string;
+/** Validate a grant entry's `caps`; `cost_units` is the connector budget. */
+export declare function parseGrantCaps(caps: unknown): Map<string, Partial<Record<CapWindow, number>>>;
+export interface BuildCapLimitsOptions {
+    connector: string;
+    tool: string;
+    spec: ToolSpec;
+    grantId: string;
+    grantCaps?: unknown;
+    caseId?: string;
+    costComponents?: readonly string[];
+}
+/**
+ * The limits for one call of `tool`.
+ *
+ * @throws {CapsConfigurationError} with `subReason` `case_required`,
+ *   `invalid_case_id`, `invalid_cost_component` or `malformed_grant_caps`.
+ */
+export declare function buildCapLimits(options: BuildCapLimitsOptions): CapLimit[];
+//# sourceMappingURL=limits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/caps/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAqC,KAAK,QAAQ,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAK9F,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAC7C,eAAO,MAAM,eAAe,oBAAoB,CAAC;AACjD,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAC/D,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,gFAAgF;AAChF,wBAAgB,SAAS,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAEpD;AAuBD,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,CAM7F;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,QAAQ,EAAE,CAuDzE"}

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

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":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,UAAU,EAA2C,MAAM,YAAY,CAAC;AAQ9G,MAAM,OAAO,mBAAmB;IACrB,SAAS,GAAG,IAAI,GAAG,EAAmB,CAAC;IAEhD,KAAK,CAAC,QAAQ,CAAC,QAAgB,EAAE,KAAuB,EAAE,GAAW;QACnE,MAAM,EAAE,GAAG,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC;QACxD,IAAI,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,GAAG,MAAM,CAAC,CAAC;YACxD,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,aAAqB,EAAE,MAAmC,EAAE,KAAyB;QACnH,MAAM,GAAG,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QAChC,uEAAuE;QACvE,qEAAqE;QACrE,MAAM,GAAG,GAAc,EAAE,CAAC;QAC1B,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QAChF,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YAC1B,MAAM,IAAI,GAAI,GAAG,CAAC,CAAC,CAAa,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACtE,IAAI,IAAI,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC;gBACrC,MAAM,IAAI,gBAAgB,CAAC;oBACzB,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI;iBAC7G,CAAC,CAAC;YACL,CAAC;QACH,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;YACzB,GAAG,CAAC,CAAC,CAAa,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3E,CAAC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAAgB,EAAE,aAAqB,EAAE,MAAmC;QACvF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;YACjF,IAAI,OAAO,KAAK,SAAS;gBAAE,SAAS;YACpC,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,aAAa,CAAC,CAAC;YACtE,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,QAAgB,EAAE,KAAuB,EAAE,KAAyB;QAC9E,OAAO,CAAC,MAAM,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IAC1G,CAAC;CACF"}

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