@classytic/arc 2.20.0 → 2.22.0

package/dist/usage/index.d.mts

@@ -0,0 +1,142 @@
+import { i as RequestScope } from "../types-DH0GupI7.mjs";
+import { n as PermissionContext, t as PermissionCheck } from "../types-Csxga7d3.mjs";
+import { FastifyPluginAsync, FastifyRequest } from "fastify";
+//#region src/usage/requireQuota.d.ts
+interface QuotaOptions {
+  /** Counter to enforce — `ai.tokens`, `export.runs`, `api.requests`, ... */
+  kind: string;
+  /**
+   * Ceiling for the current period. A number, `false` (unlimited — lets
+   * plan tables express "enterprise: false" uniformly), or a sync/async
+   * resolver receiving the permission context (plan-aware quotas).
+   */
+  limit: number | false | ((ctx: PermissionContext) => number | false | Promise<number | false>);
+  /**
+   * Actor key override. Default: the meter's own chain
+   * (org → user → client → `ip:<addr>`), so quota buckets are the same
+   * buckets usage writes and rate limits read.
+   */
+  actorOf?: (ctx: PermissionContext) => string | undefined;
+  /**
+   * Counter-store failure policy. Default `'allow'` (fail-open — see
+   * module header). `'deny'` throws the same 429 shape with
+   * `code: 'quota.unavailable'` and status 503.
+   */
+  onStoreError?: "allow" | "deny";
+  /** Memoize summary reads per (actor, kind) for this many ms. Default 0. */
+  cacheTtlMs?: number;
+}
+declare function requireQuota(options: QuotaOptions): PermissionCheck;
+//#endregion
+//#region src/usage/stores/interface.d.ts
+/**
+ * Usage store contract — period-bucketed counters per actor.
+ *
+ * CANONICAL HOME: `@classytic/repo-core/usage` (>=0.10) owns this
+ * contract for the ecosystem — kits implement it there without ever
+ * depending on arc (`@classytic/mongokit/usage`, ...). This file is a
+ * deliberate STRUCTURAL MIRROR of that shape — same trick as
+ * `ScheduleLockLike` vs repo-core's `LockAdapter` — so arc's emitted
+ * declarations carry no repo-core@>=0.10 subpath reference and the
+ * peer floor stays honest. Any conforming adapter assigns directly.
+ *
+ * The deliberately tiny surface (one increment, one read) is what makes
+ * every backend trivial: memory (dev/tests), Redis (`HINCRBY`), or any kit
+ * (Mongo `$inc` upsert) implements it in a handful of lines. Aggregation
+ * happens IN the store — arc never buffers counters in process memory
+ * beyond the built-in memory store, so multi-replica deployments stay
+ * correct as long as the store is shared.
+ *
+ * This is the HORIZONTAL usage layer (per-actor, per-period platform
+ * accounting for quotas/plans/billing). Itemized vertical records — e.g.
+ * `@classytic/arc-ai/usage`'s per-run AI token/cost tracking — keep their
+ * own richer stores and can sink into this one (`kind: 'ai.tokens'`).
+ */
+/** One counter cell: (actor, period, kind). */
+interface UsageBucket {
+  /** Who consumed — org / user / client id, or an IP-derived fallback. */
+  actor: string;
+  /** Aggregation period, `YYYY-MM` (see `usagePeriod()`). */
+  period: string;
+  /** Namespaced counter, dot-separated: `api.requests`, `ai.tokens`, `storage.bytes`. */
+  kind: string;
+}
+interface UsageStore {
+  /** Store name for diagnostics (e.g. 'memory', 'redis', 'mongo'). */
+  readonly name: string;
+  /** Add `amount` to the bucket's counter, creating it at 0 first. MUST be atomic per bucket. */
+  increment(bucket: UsageBucket, amount: number): Promise<void> | void;
+  /** Every counter for an actor in a period: `{ 'api.requests': 40231, ... }`. */
+  summary(actor: string, period: string): Promise<Record<string, number>>;
+  /** Optional cleanup hook (connections, timers). */
+  close?(): Promise<void>;
+}
+/**
+ * Canonical period key for a date — calendar month, UTC: `2026-07`.
+ * Monthly is the billing-native granularity; stores that want finer
+ * windows can shard internally without changing the contract.
+ */
+declare function usagePeriod(date?: Date): string;
+//#endregion
+//#region src/usage/stores/memory.d.ts
+declare class MemoryUsageStore implements UsageStore {
+  #private;
+  readonly name = "memory";
+  increment(bucket: UsageBucket, amount: number): void;
+  summary(actor: string, period: string): Promise<Record<string, number>>;
+  /** Test convenience — drop everything. */
+  clear(): void;
+}
+//#endregion
+//#region src/usage/usagePlugin.d.ts
+interface UsageTrackOptions {
+  /** Count every completed request as `api.requests` (default: true). */
+  requests?: boolean;
+  /** Sum `content-length` response bytes as `api.egress.bytes` (default: false). */
+  egress?: boolean;
+}
+interface UsagePluginOptions {
+  /** Master switch — `false` registers a typed no-op (config-gated environments). */
+  enabled?: boolean;
+  /** Counter backend. Default: in-memory (per-process — use a shared store in multi-replica). */
+  store?: UsageStore;
+  /** Automatic per-request accounting. Default: `{ requests: true, egress: false }`. */
+  track?: UsageTrackOptions;
+  /**
+   * Derive the actor key from a request. Default: org → user → client →
+   * `ip:<addr>` (same chain as `createTenantKeyGenerator`).
+   */
+  actorOf?: (request: FastifyRequest) => string | undefined;
+  /**
+   * Paths exempt from automatic tracking. Exact or trailing-`*` prefix.
+   * Default: `['/_health*', '/_metrics*']`.
+   */
+  ignorePaths?: string[];
+}
+/** The `fastify.usage` surface. */
+interface UsageMeter {
+  /**
+   * Add to a counter. `actor` may be a raw key or a `RequestScope`
+   * (derived via the org → user → client chain). Fire-and-forget safe:
+   * awaiting is optional, errors never throw into request flow.
+   */
+  record(actor: string | RequestScope | undefined, kind: string, amount?: number): Promise<void>;
+  /** All counters for an actor. Period defaults to the current month. */
+  summary(actor: string, period?: string): Promise<Record<string, number>>;
+  /** Canonical period key (`YYYY-MM`) for a date. */
+  period(date?: Date): string;
+  /** The actor key automatic tracking would use for this request. */
+  actorOf(request: FastifyRequest): string;
+  /** The active store (diagnostics). */
+  readonly store: UsageStore;
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    /** Per-actor usage counters — registered by `usagePlugin`. */
+    usage?: UsageMeter;
+  }
+}
+declare const usagePluginFn: FastifyPluginAsync<UsagePluginOptions>;
+declare const _default: FastifyPluginAsync<UsagePluginOptions>;
+//#endregion
+export { MemoryUsageStore, type QuotaOptions, type UsageBucket, type UsageMeter, type UsagePluginOptions, type UsageStore, type UsageTrackOptions, _default as default, requireQuota, usagePeriod, usagePluginFn as usagePlugin };