nucleus-core-ts 0.9.709 → 0.9.710

package/dist/src/ElysiaPlugin/routes/authorization/index.d.ts

@@ -10,6 +10,12 @@ export interface AuthorizationRoutesConfig {
     discovery: EndpointDiscoveryConfig & {
         token?: string;
     };
+    /**
+     * Reads integer usage counters (missing → 0) for the quota endpoint. Wired to
+     * RedisManager.readCounters when Redis is configured; when absent, `/authorization/quotas`
+     * still returns effective LIMITS but omits live usage.
+     */
+    readCounters?: (keys: string[]) => Promise<number[]>;
 }
 /**
  * Endpoint-discovery admin + manifest routes.

package/dist/src/Managers/Redis/index.d.ts

@@ -27,6 +27,12 @@ export declare class RedisManager {
     update<T>(key: string, value: T, preserveTtl?: boolean): Promise<RedisResult<'OK'>>;
     remove(key: string): Promise<RedisResult<number>>;
     exists(key: string): Promise<RedisResult<boolean>>;
+    /**
+     * Read a batch of integer counter keys (missing / non-numeric → 0). Works in both
+     * direct and Dapr modes via the state-store abstraction. Used by the quota evaluator to
+     * gate usage; the counters themselves are maintained (INCR'd) by the spender.
+     */
+    readCounters(keys: string[]): Promise<number[]>;
     /**
      * Returns the underlying ioredis client when running in direct mode.
      * Returns null in Dapr mode — raw Redis commands (INFO, KEYS, …) are not

package/dist/src/Services/Authorization/Quota/evaluate.d.ts

@@ -0,0 +1,15 @@
+import type { CounterReader, QuotaAggregate, QuotaContext, QuotaEvaluation, QuotaPolicy } from './types';
+/** Parse+validate a raw `claims.policy` jsonb value into a QuotaPolicy, or null if it isn't one. */
+export declare function parseQuotaPolicy(raw: unknown): QuotaPolicy | null;
+/**
+ * Combine the per-role limits a user holds for one quota claim into a single effective limit.
+ * `max` (default) = tier model (best role wins); `min` = strictest; `sum` = additive.
+ * Non-numeric scopes are ignored. Returns null when no numeric limit is present.
+ */
+export declare function aggregateLimit(scopes: readonly string[], mode: QuotaAggregate): number | null;
+/**
+ * Read the current usage for a quota policy and compare it to the effective limit. Pure:
+ * the counter reader is injected. Enforcement decision is the caller's — for a spend of
+ * cost C, a HARD cap allows it iff `current + C <= limit` (lte) / `< limit` (lt).
+ */
+export declare function evaluateQuota(policy: QuotaPolicy, ctx: QuotaContext, limit: number, read: CounterReader): Promise<QuotaEvaluation>;

package/dist/src/Services/Authorization/Quota/index.d.ts

@@ -0,0 +1,4 @@
+export { aggregateLimit, evaluateQuota, parseQuotaPolicy } from './evaluate';
+export { type ResolvedQuota, resolveUserQuotas } from './resolve';
+export type { CounterReader, QuotaAggregate, QuotaContext, QuotaEvaluation, QuotaOp, QuotaPolicy, QuotaWindow, } from './types';
+export { bucketDatesForWindow, buildQuotaKeys } from './windows';

package/dist/src/Services/Authorization/Quota/quota.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/Services/Authorization/Quota/resolve.d.ts

@@ -0,0 +1,16 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { QuotaPolicy } from './types';
+export interface ResolvedQuota {
+    action: string;
+    policy: QuotaPolicy;
+    /** effective limit after aggregating the per-role scopes for this claim */
+    limit: number;
+}
+/**
+ * Resolve a user's effective quota limits. For every QUOTA claim (`claims.policy.kind==='quota'`)
+ * granted through any of the user's roles, aggregate the per-role limits — each carried in that
+ * assignment's `role_claims.scope` — using the policy's `aggregate` rule (default `max`, the tier
+ * model). Active rows only. Reads whole small authz tables and filters in-memory, mirroring the
+ * existing manifest resolver (no dynamic-column WHERE).
+ */
+export declare function resolveUserQuotas(db: NodePgDatabase, schemaTables: Record<string, unknown>, userId: string): Promise<ResolvedQuota[]>;

package/dist/src/Services/Authorization/Quota/types.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Generic usage-quota primitive. A quota is expressed as a CLAIM whose `policy` jsonb
+ * column carries this shape; the per-role LIMIT lives in the `role_claims.scope` of each
+ * assignment (so the same claim can be granted at different limits to different roles, and
+ * a user's effective limit is an aggregation across their roles). The counter itself is
+ * maintained by whoever does the spending (e.g. the LLM service) under the key described
+ * here — nucleus only READS it to gate. Deliberately not spend-specific: `metric` is
+ * free-form, so the same engine covers tokens, dollars, request counts, storage, etc.
+ */
+export type QuotaOp = 'lte' | 'lt';
+/** How a user's per-role limits combine when they hold the claim via multiple roles. */
+export type QuotaAggregate = 'max' | 'min' | 'sum';
+export type QuotaWindow = {
+    type: 'rolling';
+    days: number;
+} | {
+    type: 'calendar_day';
+} | {
+    type: 'total';
+};
+export interface QuotaPolicy {
+    kind: 'quota';
+    source: 'redis';
+    /** Free-form metric label, e.g. 'tokens' | 'cost_usd' | 'requests'. */
+    metric: string;
+    window: QuotaWindow;
+    /**
+     * Redis counter key template. Placeholders: `{userId}`, `{tenant}`, `{date}`.
+     * Bucketed windows (rolling / calendar_day) substitute `{date}` (yyyy-mm-dd, UTC) once
+     * per bucket. `total` uses the template as-is (must not contain `{date}`).
+     * e.g. `usage:{tenant}:{userId}:tokens:{date}` or `usage:{tenant}:{userId}:tokens:total`.
+     */
+    keyTemplate: string;
+    /** Comparison for a HARD cap. `lte`: usage may reach the limit; `lt`: must stay below. Default `lte`. */
+    op?: QuotaOp;
+    /** Multi-role limit resolution. Default `max` (tier model: the most generous role wins). */
+    aggregate?: QuotaAggregate;
+    /** Optional display unit, e.g. 'tokens' | 'usd'. */
+    unit?: string;
+}
+export interface QuotaContext {
+    userId: string;
+    tenant?: string;
+    now: Date;
+}
+export interface QuotaEvaluation {
+    metric: string;
+    window: QuotaWindow;
+    limit: number;
+    current: number;
+    /** limit − current; negative when already over. */
+    remaining: number;
+    /** true when the cap is already reached (no room for another unit under `op`). */
+    over: boolean;
+    /** the concrete counter keys that were summed (for debugging / the status endpoint). */
+    keys: string[];
+}
+/** Reads integer counter values for a set of keys (missing → 0). Injected so the evaluator stays pure. */
+export type CounterReader = (keys: string[]) => Promise<number[]>;

package/dist/src/Services/Authorization/Quota/windows.d.ts

@@ -0,0 +1,11 @@
+import type { QuotaContext, QuotaPolicy, QuotaWindow } from './types';
+/**
+ * The yyyy-mm-dd daily buckets a window spans, most-recent first, or `null` for `total`
+ * (which is a single cumulative counter with no date bucket). Rolling windows include today.
+ */
+export declare function bucketDatesForWindow(window: QuotaWindow, now: Date): string[] | null;
+/**
+ * Concrete Redis counter keys for a policy + context. Substitutes `{userId}`/`{tenant}`,
+ * then `{date}` per bucket (or none for `total`). The spender maintains these; nucleus reads them.
+ */
+export declare function buildQuotaKeys(policy: QuotaPolicy, ctx: QuotaContext): string[];

package/dist/src/Services/Authorization/SeedRunner/index.d.ts

@@ -10,6 +10,12 @@ type SeedConfig = {
         path: string;
         method: string;
         description?: string;
+        /**
+         * Optional generic policy dictionary (jsonb) — e.g. a QUOTA policy
+         * (`{ kind:'quota', metric, window, keyTemplate, ... }`). Reconciled on
+         * drift like `scope`, so editing a seeded quota claim's policy takes effect.
+         */
+        policy?: Record<string, unknown> | null;
     }>;
     roleClaimAssignments?: Array<{
         role: string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.709",
+	"version": "0.9.710",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",

package/src/system.tables.json

@@ -209,6 +209,10 @@
           "type": "varchar",
           "length": 10,
           "notNull": true
+        },
+        {
+          "name": "policy",
+          "type": "jsonb"
         }
       ],
       "indexes": [