slotlock 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slotlock",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "license": "Apache-2.0",
@@ -21,6 +21,7 @@
     },
     "./manifest": "./slotlock.manifest.json",
     "./manifest.schema": "./slotlock-manifest.schema.json",
+    "./openapi.json": "./openapi.json",
     "./package.json": "./package.json"
   },
   "bin": {
@@ -58,7 +59,7 @@
   "dependencies": {
     "ical.js": "2.2.1",
     "rrule": "2.8.1",
-    "zod": "4.6.5"
+    "zod": "4.6.7"
   },
   "peerDependencies": {
     "postgres": "^3.4.5"

package/rate-limit.d.ts

@@ -0,0 +1,71 @@
+import { type SlotlockAgentOperation, type SlotlockAgentPrincipal } from './agent-server.js';
+import { type SlotlockApplicationOperation } from './application-api.js';
+import type { SlotlockLimits } from './config.js';
+import type { SlotlockNodeServerFetchTarget } from './node-server.js';
+export type SlotlockRefusalReason = 'auth_refused' | 'rate_limited' | 'lookup_overflow' | 'series_writes_busy' | 'maintenance_busy' | 'request_too_large';
+/** One `refusals` log line: counts since the last one, and the most refused clients as pseudonyms. */
+export interface SlotlockRefusalCounts extends Record<SlotlockRefusalReason, number> {
+    window_seconds: number;
+    /** Each client's address keyed by a per-process secret: comparable within one run, not reversible. */
+    clients: {
+        client: string;
+        refusals: number;
+    }[];
+}
+export interface SlotlockRequestLimitsOptions {
+    limits: SlotlockLimits;
+    /** A lower-case request field a trusted proxy sets to the client address (config.ts). */
+    trustedProxyHeader?: string;
+    /** The public URL's path, without a trailing slash (`''` at the origin root). */
+    basePath: string;
+    /** Paths, under the base path, of the dashboard's sign-in and its callback, when it is served. */
+    signInPaths?: readonly string[];
+    /** Resolve a request's credential: an API key lookup or the server token. Called once a request. */
+    authenticate(request: Request): Promise<SlotlockAgentPrincipal | null>;
+    onRefusals?: (counts: SlotlockRefusalCounts) => void;
+    /**
+     * Called once, with the field's name, when a request carries a field a proxy puts the client's
+     * address in while `trustedProxyHeader` is not set: every client behind that proxy is then
+     * counted as the proxy's one address.
+     */
+    onIgnoredClientField?: (field: string) => void;
+    /** Milliseconds, for tests; defaults to `performance.now`. */
+    now?: () => number;
+}
+export interface SlotlockRequestLimits {
+    /** The agent server's `authenticate`: the request's lookup from `fetch`, else a lookup now. */
+    authenticate(request: Request): Promise<SlotlockAgentPrincipal | null>;
+    /** The agent server's `consumeRateLimit`: the key, tenant and server buckets of the request. */
+    consumeRateLimit(args: {
+        principal: SlotlockAgentPrincipal;
+        operation: SlotlockAgentOperation | 'protocol';
+    }): Promise<boolean>;
+    /**
+     * For `authorize`: when the operation may expand a recurring series, or runs maintenance, take its
+     * write token and wait for a slot, holding it until the request is answered. Throws a
+     * `SlotlockAgentOperationError` when none comes: `rate_limited` (429) when the write is over its
+     * budget or the tenant's own writes fill its slots, `server_busy` (503) while the server's do.
+     */
+    admit(args: {
+        principal: SlotlockAgentPrincipal;
+        operation: SlotlockAgentOperation | SlotlockApplicationOperation;
+        input: Record<string, unknown>;
+    }): Promise<void>;
+    /** Put the limits in front of `target`: the listener's fetch target. */
+    serve(target: SlotlockNodeServerFetchTarget): SlotlockNodeServerFetchTarget;
+    /** The client address a request reaching `serve`'s target was counted as (the dashboard's). */
+    clientAddress(request: Request): string | undefined;
+    /** Log what is still counted and stop the timer. */
+    close(): void;
+}
+/** The bucket key of an address: an IPv4 address itself, an IPv6 address's /64; null if neither. */
+export declare function slotlockClientKey(value: string): string | null;
+/**
+ * The network a client key (slotlockClientKey) signs in from: an IPv6 /64's /48, any other key
+ * itself. A site is generally given a /48 or a /56 (RFC 6177) and may use each /64 in it, so a
+ * budget per /64 would let one site sign in as thousands of clients and use up a ceiling every
+ * client shares; per /48, a site counts as one, as a site behind one IPv4 address does.
+ */
+export declare function slotlockClientNetwork(key: string): string;
+/** The limits `slotlock serve` puts in front of its agent server and dashboard. */
+export declare function createSlotlockRequestLimits(options: SlotlockRequestLimitsOptions): SlotlockRequestLimits;