slotlock 0.6.3 → 0.7.0

package/event-feed.d.ts

@@ -1,7 +1,7 @@
 import type { Sql, TransactionSql } from 'postgres';
 type SlotlockSql = Sql | TransactionSql;
 /** What a change can be, as the feed and a webhook's `event_types` name it. */
-export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "webhook.disabled", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
+export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "approval.requested", "approval.granted", "approval.declined", "approval.expired", "webhook.disabled", "usage.threshold_reached", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
 export type SlotlockChangeType = (typeof SLOTLOCK_CHANGE_TYPES)[number];
 /**
  * Where a change came from (withTenant's `origin`): an agent protocol (`mcp`, `a2a`), the REST
@@ -39,7 +39,7 @@ export declare function slotlockServedChange(type: string, subject: string, data
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export declare const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
-export declare const SLOTLOCK_MAX_WEBHOOK_ENDPOINTS = 10;
+export declare const SLOTLOCK_MAX_WEBHOOK_ENDPOINTS = 25;
 /** After this long failing, an endpoint is disabled and the feed says so (`webhook.disabled`). */
 export declare const SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS: number;
 export interface SlotlockChange {
@@ -60,11 +60,29 @@ export interface SlotlockChange {
     /** Pass as `after` to read what follows this change. */
     position: string;
 }
+/** Resources one webhook endpoint's filter may name. */
+export declare const SLOTLOCK_WEBHOOK_FILTER_RESOURCES = 100;
+/** Pools, locations or groups one webhook endpoint's filter may name, of each. */
+export declare const SLOTLOCK_WEBHOOK_FILTER_REFS = 20;
+/**
+ * Which resources' changes an endpoint receives (RFC 0003 G5): only changes about a resource that
+ * matches one of these, as it is when the change is delivered, so a change about no resource (a key,
+ * a webhook, a usage notice) is not sent. A location includes every location in it. At most
+ * SLOTLOCK_WEBHOOK_FILTER_RESOURCES ids, and SLOTLOCK_WEBHOOK_FILTER_REFS of each of the others.
+ */
+export interface SlotlockWebhookFilter {
+    resourceIds?: string[];
+    pools?: string[];
+    locations?: string[];
+    groups?: string[];
+}
 export interface SlotlockWebhookEndpoint {
     id: string;
     url: string;
     /** Null: every type. */
     eventTypes: SlotlockChangeType[] | null;
+    /** Only changes about these resources; absent, changes about any resource or none. */
+    filter?: SlotlockWebhookFilter;
     createdAt: Date;
     /** Failed attempts since the last delivery that succeeded. */
     attempts: number;
@@ -90,10 +108,11 @@ export interface SlotlockWebhookClaim {
 export type CreateWebhookEndpointResult = {
     ok: true;
     endpoint: SlotlockWebhookEndpoint;
-    secret: string;
+    secret: string; /** True when an idempotency key answered what an earlier create made. */
+    replayed?: boolean;
 } | {
     ok: false;
-    code: 'invalid_webhook_url' | 'invalid_event_types';
+    code: 'invalid_webhook_url' | 'invalid_event_types' | 'invalid_webhook_filter' | 'idempotency_conflict' | 'invalid_identity';
 } | {
     ok: false;
     code: 'webhook_limit_reached';
@@ -136,6 +155,13 @@ export interface SlotlockEventFeed {
         tenantRef: string;
         url: string;
         eventTypes?: readonly string[];
+        /** Only changes about these resources (`invalid_webhook_filter` past its bounds). */
+        filter?: SlotlockWebhookFilter;
+        /**
+         * A retry identity, kept as long as the endpoint: the same key and request answer the endpoint
+         * and secret the first made (`replayed`), another request `idempotency_conflict`.
+         */
+        idempotencyKey?: string;
     }): Promise<CreateWebhookEndpointResult>;
     listWebhookEndpoints(params: {
         tenantRef: string;

package/event-feed.js

@@ -1,7 +1,8 @@
 // The event feed: what changed for a tenant, read by position, and the webhook endpoints it is
 // delivered to. Rows are appended by triggers in the changing transaction (ddl.ts,
 // SLOTLOCK_OUTBOX_DDL); webhooks.ts signs and sends.
-import { randomBytes } from 'node:crypto';
+import { slotlockPlanReadRefusal } from './plans.js';
+import { createHash, randomBytes } from 'node:crypto';
 /** A transaction on a client, or a savepoint inside the caller's (a tenant's, say). */
 async function inTransaction(sql, callback) {
     return ('begin' in sql ? sql.begin(callback) : sql.savepoint(callback));
@@ -26,7 +27,14 @@ export const SLOTLOCK_CHANGE_TYPES = Object.freeze([
     'coverage.stale',
     'waitlist.offered',
     'waitlist.expired',
+    // A write waiting for a person (approval policies): requested, then granted, declined or expired.
+    'approval.requested',
+    'approval.granted',
+    'approval.declined',
+    'approval.expired',
     'webhook.disabled',
+    // A plan's monthly quota 80% or 100% used (quotas.ts): the metric, the share and the counts.
+    'usage.threshold_reached',
     // Configuration changes: ids and states, never a secret or a URL.
     'resource.created',
     'resource.updated',
@@ -102,9 +110,13 @@ export function slotlockServedChange(type, subject, data) {
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
-export const SLOTLOCK_MAX_WEBHOOK_ENDPOINTS = 10;
+export const SLOTLOCK_MAX_WEBHOOK_ENDPOINTS = 25;
 /** After this long failing, an endpoint is disabled and the feed says so (`webhook.disabled`). */
 export const SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS = 24 * 60 * 60 * 1_000;
+/** Resources one webhook endpoint's filter may name. */
+export const SLOTLOCK_WEBHOOK_FILTER_RESOURCES = 100;
+/** Pools, locations or groups one webhook endpoint's filter may name, of each. */
+export const SLOTLOCK_WEBHOOK_FILTER_REFS = 20;
 function encodePosition(position) {
     return Buffer.from(`2:${position.txid}:${position.id}:${position.at}`).toString('base64url');
 }
@@ -134,7 +146,7 @@ function toChange(row) {
     };
 }
 function toEndpoint(row) {
-    return {
+    const endpoint = {
         id: row.id,
         url: row.url,
         eventTypes: row.event_types,
@@ -146,9 +158,85 @@ function toEndpoint(row) {
         disabledAt: row.disabled_at,
         disabledReason: row.disabled_reason,
     };
+    const filter = {};
+    if (row.filter_resource_ids)
+        filter.resourceIds = row.filter_resource_ids;
+    if (row.filter_pools)
+        filter.pools = row.filter_pools;
+    if (row.filter_locations)
+        filter.locations = row.filter_locations;
+    if (row.filter_groups)
+        filter.groups = row.filter_groups;
+    if (Object.keys(filter).length > 0)
+        endpoint.filter = filter;
+    return endpoint;
 }
 const ENDPOINT_COLUMNS = (sql) => sql `id, url, event_types, created_at, attempts, failing_since, last_status, last_error,
-      disabled_at, disabled_reason`;
+      disabled_at, disabled_reason, filter_resource_ids::text[], filter_pools, filter_locations,
+      filter_groups`;
+/** A pool's, location's or group's reference. */
+const GROUPING_REF = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+/**
+ * A webhook filter as it is stored, each list without repeats, or null when one is out of bounds.
+ * An empty filter, or empty lists, filter nothing.
+ */
+function parseWebhookFilter(filter) {
+    const list = (values, max, valid) => {
+        if (values === undefined)
+            return null;
+        if (!Array.isArray(values))
+            return false;
+        const kept = [...new Set(values)];
+        if (kept.length === 0)
+            return null;
+        if (kept.length > max || !kept.every((value) => typeof value === 'string' && valid(value)))
+            return false;
+        return kept.sort();
+    };
+    const resourceIds = list(filter?.resourceIds, SLOTLOCK_WEBHOOK_FILTER_RESOURCES, (value) => UUID.test(value));
+    const pools = list(filter?.pools, SLOTLOCK_WEBHOOK_FILTER_REFS, (value) => GROUPING_REF.test(value));
+    const locations = list(filter?.locations, SLOTLOCK_WEBHOOK_FILTER_REFS, (value) => GROUPING_REF.test(value));
+    const groups = list(filter?.groups, SLOTLOCK_WEBHOOK_FILTER_REFS, (value) => GROUPING_REF.test(value));
+    if (resourceIds === false || pools === false || locations === false || groups === false)
+        return null;
+    return {
+        resourceIds: resourceIds?.map((id) => id.toLowerCase()) ?? null,
+        pools,
+        locations,
+        groups,
+    };
+}
+/**
+ * Whether a change (`change`, a row of slotlock.outbox) passes an endpoint's filter (`due`, a row of
+ * slotlock.webhook_endpoints): no filter, or a resource it names, or one in a pool, at a location
+ * (or a location in it) or in a group it names, as the resource is now; or a change to a resource
+ * that says it was in one (resource.created, resource.deleted, or resource.updated's `before`),
+ * so an endpoint also learns of a resource deleted, or moved out of what it follows.
+ */
+const FILTER_MATCH = `(
+  (due.filter_resource_ids IS NULL AND due.filter_pools IS NULL
+   AND due.filter_locations IS NULL AND due.filter_groups IS NULL)
+  OR change.resource_id = ANY (due.filter_resource_ids)
+  OR EXISTS (
+    SELECT 1 FROM slotlock.resources held
+     WHERE held.tenant_ref = change.tenant_ref AND held.id = change.resource_id
+       AND (held.pool_ref = ANY (due.filter_pools)
+            OR (held.location_ref IS NOT NULL
+                AND slotlock.location_path(held.tenant_ref, held.location_ref) && due.filter_locations)
+            OR EXISTS (SELECT 1 FROM slotlock.resource_group_members member
+                        WHERE member.tenant_ref = held.tenant_ref AND member.resource_id = held.id
+                          AND member.group_ref = ANY (due.filter_groups))))
+  OR (change.type LIKE 'resource.%' AND (
+       (change.data ->> 'pool') = ANY (due.filter_pools)
+    OR (change.data #>> '{before,pool}') = ANY (due.filter_pools)
+    OR EXISTS (
+         SELECT 1 FROM unnest(ARRAY[change.data ->> 'location', change.data #>> '{before,location}']) was(ref)
+          WHERE was.ref IS NOT NULL
+            AND (was.ref = ANY (due.filter_locations)
+                 OR slotlock.location_path(change.tenant_ref, was.ref) && due.filter_locations))
+    OR (jsonb_typeof(change.data -> 'groups') = 'array' AND (change.data -> 'groups') ?| due.filter_groups)
+    OR (jsonb_typeof(change.data #> '{before,groups}') = 'array'
+        AND (change.data #> '{before,groups}') ?| due.filter_groups))))`;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function isIdentity(value) {
     return typeof value === 'string' && Buffer.byteLength(value) >= 1 && Buffer.byteLength(value) <= 500;
@@ -268,25 +356,60 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
                     !types.every((type) => SLOTLOCK_CHANGE_TYPES.includes(type)))) {
                 return { ok: false, code: 'invalid_event_types' };
             }
+            const filter = parseWebhookFilter(params.filter);
+            if (filter === null)
+                return { ok: false, code: 'invalid_webhook_filter' };
+            const key = params.idempotencyKey;
+            if (key !== undefined && !isIdentity(key))
+                return { ok: false, code: 'invalid_identity' };
+            const payloadHash = key === undefined
+                ? null
+                : createHash('sha256')
+                    .update(JSON.stringify([params.url, types === null ? null : [...types].sort(), filter]))
+                    .digest('hex');
             const secret = `whsec_${randomBytes(32).toString('base64')}`;
             return inTransaction(sql, async (tx) => {
                 await tx `SELECT pg_advisory_xact_lock(hashtextextended(${`slotlock:webhooks:${params.tenantRef}`}, 0))`;
+                if (key !== undefined) {
+                    // Under the tenant's webhook lock: a retry racing its first finds what the first made.
+                    const [earlier] = await tx `
+            SELECT ${ENDPOINT_COLUMNS(tx)}, secret, payload_hash FROM slotlock.webhook_endpoints
+             WHERE tenant_ref = ${params.tenantRef} AND idempotency_key = ${key}`;
+                    if (earlier) {
+                        if (earlier.payload_hash !== payloadHash)
+                            return { ok: false, code: 'idempotency_conflict' };
+                        return { ok: true, endpoint: toEndpoint(earlier), secret: earlier.secret, replayed: true };
+                    }
+                }
                 const [count] = await tx `
-          SELECT count(*)::int AS count FROM slotlock.webhook_endpoints
-           WHERE tenant_ref = ${params.tenantRef}`;
-                if ((count?.count ?? 0) >= SLOTLOCK_MAX_WEBHOOK_ENDPOINTS) {
-                    return { ok: false, code: 'webhook_limit_reached', limit: SLOTLOCK_MAX_WEBHOOK_ENDPOINTS };
+          SELECT count(*)::int AS count,
+                 (SELECT max_webhook_endpoints FROM slotlock.tenant_plan(${params.tenantRef}::text))
+                   AS planned
+            FROM slotlock.webhook_endpoints
+           WHERE tenant_ref = ${params.tenantRef}`.catch((error) => {
+                    throw slotlockPlanReadRefusal(error);
+                });
+                // The lower of the server's limit and the tenant's plan (plans.ts), when it has one.
+                const limit = Math.min(SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, count?.planned ?? SLOTLOCK_MAX_WEBHOOK_ENDPOINTS);
+                if ((count?.count ?? 0) >= limit) {
+                    return { ok: false, code: 'webhook_limit_reached', limit };
                 }
                 // From now on: every transaction not yet ended is at or after this position.
                 const [row] = await tx `
-          INSERT INTO slotlock.webhook_endpoints (tenant_ref, url, secret, event_types, cursor_txid)
+          INSERT INTO slotlock.webhook_endpoints (
+            tenant_ref, url, secret, event_types, cursor_txid,
+            filter_resource_ids, filter_pools, filter_locations, filter_groups,
+            idempotency_key, payload_hash
+          )
           VALUES (${params.tenantRef}, ${params.url}, ${secret}, ${types}::text[],
-                  pg_snapshot_xmin(pg_current_snapshot()))
+                  pg_snapshot_xmin(pg_current_snapshot()),
+                  ${filter.resourceIds}::uuid[], ${filter.pools}::text[], ${filter.locations}::text[],
+                  ${filter.groups}::text[], ${key ?? null}, ${payloadHash})
           RETURNING ${ENDPOINT_COLUMNS(tx)}`;
                 if (!row)
                     throw new Error('slotlock: webhook endpoint insert returned no row');
                 await tx `SELECT slotlock.register_webhook_tenant(${params.tenantRef}::text)`;
-                return { ok: true, endpoint: toEndpoint(row), secret };
+                return { ok: true, endpoint: toEndpoint(row), secret, replayed: false };
             });
         },
         async listWebhookEndpoints(params) {
@@ -344,6 +467,32 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             if (!(Number.isSafeInteger(params.batch) && params.batch >= 1 && params.batch <= 100)) {
                 throw new RangeError('Slotlock webhook batch must be 1-100 changes');
             }
+            // An endpoint that takes only some changes (by type or filter) moves past the ones it does
+            // not take, up to the last change that has ended, when none before it is for the endpoint:
+            // else its cursor would stay where it was made, keeping the whole feed from being pruned and
+            // every claim reading it all again. Not one being delivered (leased), nor one waiting to try
+            // again (it has a change for it).
+            await sql `
+        UPDATE slotlock.webhook_endpoints due
+           SET cursor_txid = head.txid, cursor_id = head.id
+          FROM (SELECT change.txid, change.id FROM slotlock.outbox change
+                 WHERE change.tenant_ref = ${params.tenantRef}
+                   AND change.txid < pg_snapshot_xmin(pg_current_snapshot())
+                 ORDER BY change.txid DESC, change.id DESC
+                 LIMIT 1) head
+         WHERE due.tenant_ref = ${params.tenantRef}
+           AND due.disabled_at IS NULL
+           AND (due.lease_until IS NULL OR due.lease_until <= now())
+           AND (due.event_types IS NOT NULL OR due.filter_resource_ids IS NOT NULL OR due.filter_pools IS NOT NULL
+                OR due.filter_locations IS NOT NULL OR due.filter_groups IS NOT NULL)
+           AND (head.txid, head.id) > (due.cursor_txid, due.cursor_id)
+           AND NOT EXISTS (
+             SELECT 1 FROM slotlock.outbox change
+              WHERE change.tenant_ref = due.tenant_ref
+                AND (change.txid, change.id) > (due.cursor_txid, due.cursor_id)
+                AND (change.txid, change.id) <= (head.txid, head.id)
+                AND (due.event_types IS NULL OR change.type = ANY (due.event_types))
+                AND ${sql.unsafe(FILTER_MATCH)})`;
             const endpoints = await sql `
         UPDATE slotlock.webhook_endpoints endpoint
            SET lease_until = now() + make_interval(secs => ${params.leaseMs / 1_000}),
@@ -360,6 +509,7 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
                    AND change.txid < pg_snapshot_xmin(pg_current_snapshot())
                    AND (change.txid, change.id) > (due.cursor_txid, due.cursor_id)
                    AND (due.event_types IS NULL OR change.type = ANY (due.event_types))
+                   AND ${sql.unsafe(FILTER_MATCH)}
               )
             FOR UPDATE SKIP LOCKED
          )
@@ -368,14 +518,16 @@ export function slotlockEventFeedMethods(sql, retentionDays = SLOTLOCK_CHANGE_RE
             const claims = [];
             for (const endpoint of endpoints) {
                 const rows = await sql `
-          SELECT id::text, txid::text, type, resource_id, subject, data, occurred_at, actor, origin,
-               key_id::text
-            FROM slotlock.outbox
-           WHERE tenant_ref = ${params.tenantRef}
-             AND txid < pg_snapshot_xmin(pg_current_snapshot())
-             AND (txid, id) > (${endpoint.cursor_txid}::xid8, ${endpoint.cursor_id}::bigint)
-             AND (${endpoint.event_types}::text[] IS NULL OR type = ANY (${endpoint.event_types}::text[]))
-           ORDER BY txid, id
+          SELECT change.id::text, change.txid::text, change.type, change.resource_id, change.subject,
+                 change.data, change.occurred_at, change.actor, change.origin, change.key_id::text
+            FROM slotlock.outbox change, slotlock.webhook_endpoints due
+           WHERE due.id = ${endpoint.id}::uuid
+             AND change.tenant_ref = ${params.tenantRef}
+             AND change.txid < pg_snapshot_xmin(pg_current_snapshot())
+             AND (change.txid, change.id) > (${endpoint.cursor_txid}::xid8, ${endpoint.cursor_id}::bigint)
+             AND (${endpoint.event_types}::text[] IS NULL OR change.type = ANY (${endpoint.event_types}::text[]))
+             AND ${sql.unsafe(FILTER_MATCH)}
+           ORDER BY change.txid, change.id
            LIMIT ${params.batch}`;
                 claims.push({
                     endpoint: { id: endpoint.id, url: endpoint.url, secret: endpoint.secret, attempts: endpoint.attempts },

package/index.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" preserve="true" />
 export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
 export { type SlotlockBookingRule, type SlotlockBookingRules, type SlotlockBookingSearch, bookingRuleBroken, bookingSearch, bookingSearchBlocked, bookingSearchReach, nextStepStart, parseBookingRuleDefaults, parseBookingRules, } from './booking-rules.js';
+export { SLOTLOCK_GROUPING_REF, SLOTLOCK_MAX_GROUPS_PER_RESOURCE, SLOTLOCK_MAX_LOCATION_DEPTH, SLOTLOCK_MAX_LOCATIONS, SLOTLOCK_MAX_RESOURCE_GROUPS, SLOTLOCK_RESOURCE_KINDS, SLOTLOCK_RESOURCE_LABEL, SLOTLOCK_RESOURCE_PROFILE_FIELDS, SLOTLOCK_RESOURCE_PROFILE_LIMITS, parseSlotlockLocation, parseSlotlockResourceGroup, parseSlotlockResourceProfile, type SlotlockLocation, type SlotlockResourceGroup, type SlotlockResourceAttributes, type SlotlockResourceKind, type SlotlockResourceProfileChange, type SlotlockResourceProfileInput, } from './resource-profile.js';
 export { type CreateWebhookEndpointResult, type ListChangesResult, SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, slotlockChangeFeedHead, type SlotlockChange, type SlotlockChangeOrigin, type SlotlockChangeType, type SlotlockEventFeed, type SlotlockWebhookClaim, type SlotlockWebhookEndpoint, slotlockCoverageSourceId, } from './event-feed.js';
 export { type SlotlockCloudEvent, type SlotlockWebhookPassResult, type SlotlockWebhookResponse, type SlotlockWebhookScheduler, type SlotlockWebhookSender, createSlotlockGuardedFetch, createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
 export { type SlotlockMetrics, createSlotlockMetrics } from './metrics.js';
@@ -11,8 +12,8 @@ export { emitVAvailability, parseVAvailability, recurrenceRuleFromRRule, SLOTLOC
 export type { EmitVAvailabilityOptions, JSCalendarAlert, JSCalendarEvent, JSCalendarParticipant, JSCalendarRecurrenceRule, ParsedVAvailability, } from './interop.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
 export type { LocalDateTime, TimeZoneConverter, ZonedCalendarDate, ZonedWallTime, } from './timezone.js';
-export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
-export type { SlotlockAgentCalendarBackend, SlotlockAgentConfirmationOptions, SlotlockAgentErrorContext, SlotlockAgentInvocationContext, SlotlockAgentOperation, SlotlockAgentOperationDispatchOptions, SlotlockAgentOperationDispatchResult, SlotlockAgentPrincipal, SlotlockAgentScope, SlotlockAgentServerEvent, SlotlockAgentServerOAuthOptions, SlotlockAgentServerOptions, SlotlockAgentSubscriptionOptions, SlotlockAgentWriteOperation, SlotlockArgumentIssue, SlotlockMcpToolResult, SlotlockTraceContext, } from './agent-server.js';
+export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MAX_ALTERNATIVES, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
+export type { SlotlockAgentCalendarBackend, SlotlockAgentConfirmationOptions, SlotlockAgentErrorContext, SlotlockAgentInvocationContext, SlotlockAgentOperation, SlotlockAgentOperationDispatchOptions, SlotlockAgentOperationDispatchResult, SlotlockAgentPrincipal, SlotlockAgentScope, SlotlockAgentServerEvent, SlotlockAgentServerOAuthOptions, SlotlockAgentServerOptions, SlotlockAgentSubscriptionOptions, SlotlockAgentWriteOperation, SlotlockAlternative, SlotlockArgumentIssue, SlotlockMcpToolResult, SlotlockTraceContext, } from './agent-server.js';
 export { createSlotlockNodeServer } from './node-server.js';
 export type { SlotlockNodeListenOptions, SlotlockNodeServer, SlotlockNodeServerAddress, SlotlockNodeServerCloseResult, SlotlockNodeServerErrorPhase, SlotlockNodeServerFetchTarget, SlotlockNodeServerOptions, } from './node-server.js';
 export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
@@ -22,11 +23,21 @@ export { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlock
 export type { SlotlockApplicationBackend, SlotlockApplicationInvocationContext, SlotlockApplicationOperation, SlotlockApplicationOperationDefinition, } from './application-api.js';
 export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 export type { SlotlockMaintenanceResult, SlotlockMaintenanceScheduler, SlotlockMaintenanceSchedulerOptions, } from './maintenance.js';
-export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
+export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, isSlotlockTestTenant, slotlockLiveTenant, SLOTLOCK_TEST_API_KEY_PREFIX, SLOTLOCK_TEST_TENANT_SUFFIX, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
 export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
 export type { SlotlockDashboard, SlotlockDashboardAssistantOptions, SlotlockDashboardOptions, SlotlockDashboardResources, SlotlockDashboardState, } from './dashboard.js';
 export { createSlotlockAssistantStore, createSlotlockMemoryAssistantStore, SLOTLOCK_ASSISTANT_TOOL_USE, } from './assistant.js';
 export type { SlotlockAssistantStore } from './assistant.js';
+export { createSlotlockPartnerKeyAuthenticator, createSlotlockPartnerStore, parseSlotlockPartnerContract, slotlockPartnerTenantRef, SLOTLOCK_PARTNER_ACCOUNT, SLOTLOCK_PARTNER_ID, SLOTLOCK_PARTNER_SCOPE, } from './partners.js';
+export { createSlotlockDashboardTeams, createSlotlockOrganizationCheck } from './teams.js';
+export { reportSlotlockOverage, SLOTLOCK_DEFAULT_OVERAGE_STOP_PERCENT } from './overage.js';
+export type { SlotlockOverageReport } from './overage.js';
+export { createSlotlockOtlpExporter, readSlotlockOtlpConfig, slotlockCallSpan } from './otel.js';
+export type { SlotlockOtlpConfig, SlotlockTraceExporter } from './otel.js';
+export type { SlotlockDashboardTeams } from './teams.js';
+export { closeSlotlockPartnerMonth, priceSlotlockPartnerMonth, slotlockClientLabel, slotlockPartnerMonthChecksum, } from './partner-billing.js';
+export type { SlotlockPartnerAccountMonth, SlotlockPartnerInvoiceLine, SlotlockPartnerMonthClose, } from './partner-billing.js';
+export type { SlotlockPartnerAccount, SlotlockPartnerContract, SlotlockPartnerPlan, SlotlockPartnerPricing, SlotlockPartnerStore, } from './partners.js';
 export type { CreateSlotlockApiKeyInput, SlotlockApiKey, SlotlockApiKeyAuthenticatorOptions, SlotlockApiKeyChange, SlotlockApiKeyIdentity, SlotlockApiKeyScope, SlotlockApiKeyStore, } from './api-keys.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
 export type { ICalendarWorkerPool, ICalendarWorkerPoolOptions } from './ical-worker.js';
@@ -34,4 +45,4 @@ export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emit
 export type { ExternalCalendarChange, ExternalCalendarChangeInput, ExternalCalendarStatus, ICalendarEvent, ICalendarExpansionWindow, ICalendarFeedRead, ICalendarSeriesRefusal, ITipMethod, } from './sync.js';
 export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';
 export { assertSlotlockSchemaCurrent, calendarEventRollingHorizon, createSlotlockStore, readSlotlockSchemaVersion, SLOTLOCK_AGENT_OWNER_COMMAND_QUOTA, SLOTLOCK_AGENT_OWNER_EVENT_QUOTA, SLOTLOCK_CALENDAR_HORIZON_DAYS, SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS, SLOTLOCK_INTERNAL_EVENT_OWNER_REF, SLOTLOCK_LOCAL_RECURRENCE_COVERAGE_SOURCE, SLOTLOCK_MATERIALIZATION_WINDOW_DAYS, SLOTLOCK_MAX_EVENT_DURATION_DAYS, SLOTLOCK_TENANT_WRITE_METHODS, type SlotlockHoldTenantOptions, type SlotlockMigrationOptions, type SlotlockSql, type SlotlockStore, type SlotlockStoreOptions, type SlotlockTenantLimits, type SlotlockTenantStore, } from './store.js';
-export type { AcquireHoldResult, BookingRetentionResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockAgendaEntry, SlotlockHold, SlotlockCalendarEvent, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, SlotlockBookingRuleDefaults, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';
+export type { AcquireHoldResult, BookingRetentionResult, CalendarAttendee, CalendarAttendeeRole, CalendarCoverageAssessment, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventOccurrence, CalendarEventRetentionResult, CalendarEventStatus, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CalendarOrganizer, CalendarParticipationStatus, CalendarRecurrence, CalendarRecurrenceException, CalendarReminder, CalendarTransparency, ConfirmHoldResult, CancelCalendarEventResult, CancelExternalReservationResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockAgendaEntry, SlotlockHold, SlotlockCalendarEvent, SlotlockBookingDescription, SlotlockReservation, SlotlockResource, SlotlockTenantErasure, SlotlockBookingRuleDefaults, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, TrustedICalendarEvent, WeeklyAvailabilityRule, } from './types.js';

package/index.js

@@ -5,6 +5,7 @@
 /// <reference types="node" preserve="true" />
 export { findNextAvailable, mergeIntervals, subtractBusy } from './engine.js';
 export { bookingRuleBroken, bookingSearch, bookingSearchBlocked, bookingSearchReach, nextStepStart, parseBookingRuleDefaults, parseBookingRules, } from './booking-rules.js';
+export { SLOTLOCK_GROUPING_REF, SLOTLOCK_MAX_GROUPS_PER_RESOURCE, SLOTLOCK_MAX_LOCATION_DEPTH, SLOTLOCK_MAX_LOCATIONS, SLOTLOCK_MAX_RESOURCE_GROUPS, SLOTLOCK_RESOURCE_KINDS, SLOTLOCK_RESOURCE_LABEL, SLOTLOCK_RESOURCE_PROFILE_FIELDS, SLOTLOCK_RESOURCE_PROFILE_LIMITS, parseSlotlockLocation, parseSlotlockResourceGroup, parseSlotlockResourceProfile, } from './resource-profile.js';
 export { SLOTLOCK_CHANGE_ORIGINS, SLOTLOCK_CHANGE_RETENTION_DAYS, SLOTLOCK_CHANGE_TYPES, SLOTLOCK_MAX_WEBHOOK_ENDPOINTS, SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS, slotlockChangeFeedHead, slotlockCoverageSourceId, } from './event-feed.js';
 export { createSlotlockGuardedFetch, createSlotlockWebhookSender, deliverSlotlockWebhooks, isPrivateAddress, signSlotlockWebhook, slotlockCloudEvent, slotlockWebhookRetryDelayMs, startSlotlockWebhookDelivery, } from './webhooks.js';
 export { createSlotlockMetrics } from './metrics.js';
@@ -12,15 +13,20 @@ export { expandRules } from './rules.js';
 export { availabilityRuleProblem, parseAvailabilityRules, rulesToWeeklyHours, SLOTLOCK_MAX_AVAILABILITY_RULES, weeklyHoursToRules, } from './weekly-hours.js';
 export { emitVAvailability, parseVAvailability, recurrenceRuleFromRRule, SLOTLOCK_MAX_VAVAILABILITY_CHARACTERS, toJSCalendarEvent, } from './interop.js';
 export { createTimeZoneConverter, zonedCalendarDate, zonedDateTimeToUtc, zonedWallTime, } from './timezone.js';
-export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
+export { createSlotlockAgentServer, clientSupportsSlotlockMcpApp, invokeSlotlockAgentOperation, isSlotlockAgentOperation, slotlockAgentTools, slotlockApplicationOperations, slotlockOpenApi, slotlockCalendarResourceUri, slotlockMcpToolResult, parseSlotlockA2ATimestamp, resolveSlotlockAgentOperation, slotlockAgentOperationScope, SLOTLOCK_A2A_PROTOCOL_VERSION, SLOTLOCK_A2A_TASK_PAGE_SIZE, SLOTLOCK_A2A_WATCH_SKILL, SLOTLOCK_A2A_TASK_STATES, SLOTLOCK_AGENT_OPERATION_LEGACY_NAMES, SLOTLOCK_AGENT_SERVER_VERSION, SLOTLOCK_MAX_ALTERNATIVES, SLOTLOCK_MCP_LEGACY_PROTOCOL_VERSION, SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SLOTLOCK_MCP_RESOURCE_URI_TEMPLATE, SLOTLOCK_MCP_SUPPORTED_PROTOCOL_VERSIONS, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, SlotlockAgentOperationError, } from './agent-server.js';
 export { createSlotlockNodeServer } from './node-server.js';
 export { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, createSlotlockStoreChangeSource, projectSlotlockCalendarEvent, } from './agent-store-backend.js';
 export { SLOTLOCK_FEED_BUSY_MS, SLOTLOCK_FEED_IDLE_MS, } from './change-watch.js';
 export { SLOTLOCK_APPLICATION_OPERATIONS, SLOTLOCK_APPLICATION_SCOPE, isSlotlockApplicationOperation, } from './application-api.js';
 export { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
-export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
+export { createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, generateSlotlockApiKey, isSlotlockApiKey, isSlotlockTestTenant, slotlockLiveTenant, SLOTLOCK_TEST_API_KEY_PREFIX, SLOTLOCK_TEST_TENANT_SUFFIX, slotlockApiKeyDigest, SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_PREFIX, SLOTLOCK_API_KEY_RETAINED_LIMIT, SLOTLOCK_API_KEY_SCOPES, } from './api-keys.js';
 export { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, createSlotlockMemoryDashboardState, SLOTLOCK_DASHBOARD_MAX_RESOURCES, } from './dashboard.js';
 export { createSlotlockAssistantStore, createSlotlockMemoryAssistantStore, SLOTLOCK_ASSISTANT_TOOL_USE, } from './assistant.js';
+export { createSlotlockPartnerKeyAuthenticator, createSlotlockPartnerStore, parseSlotlockPartnerContract, slotlockPartnerTenantRef, SLOTLOCK_PARTNER_ACCOUNT, SLOTLOCK_PARTNER_ID, SLOTLOCK_PARTNER_SCOPE, } from './partners.js';
+export { createSlotlockDashboardTeams, createSlotlockOrganizationCheck } from './teams.js';
+export { reportSlotlockOverage, SLOTLOCK_DEFAULT_OVERAGE_STOP_PERCENT } from './overage.js';
+export { createSlotlockOtlpExporter, readSlotlockOtlpConfig, slotlockCallSpan } from './otel.js';
+export { closeSlotlockPartnerMonth, priceSlotlockPartnerMonth, slotlockClientLabel, slotlockPartnerMonthChecksum, } from './partner-billing.js';
 export { ICalendarWorkerBusyError, ICalendarWorkerPoolClosedError, createICalendarWorkerPool, } from './ical-worker.js';
 export { CalendarContractError, CalendarExpansionLimitError, emitICalendar, emitITipCalendar, expandCalendarEventOccurrences, normalizeCalendarEventContent, normalizeExternalCalendarChange, parseICalendarChanges, parseICalendarFeed, parseTrustedICalendarEvents, recurrenceRuleProblem, storedCalendarEventProblem, } from './sync.js';
 export { createSlotlockApplicationRoleGrantsDdl, createSlotlockTenantRlsDdl, SLOTLOCK_API_KEY_FUNCTIONS, SLOTLOCK_API_KEY_TABLES, SLOTLOCK_CORE_DDL, SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_DASHBOARD_TABLES, SLOTLOCK_DEFINER_FUNCTIONS, SLOTLOCK_DEFINER_TABLES, SLOTLOCK_OPERATOR_FUNCTIONS, SLOTLOCK_SCHEMA_FUNCTIONS, SLOTLOCK_SCHEMA_TABLES, SLOTLOCK_SCHEMA_VERSION, SLOTLOCK_TENANT_ADMIN_FUNCTIONS, SLOTLOCK_TENANT_ADMIN_TABLES, SLOTLOCK_TENANT_CONTEXT_SETTING, SLOTLOCK_TENANT_RLS_DDL, SLOTLOCK_TENANT_TABLES, } from './ddl.js';

package/maintenance.d.ts

@@ -24,6 +24,8 @@ export interface SlotlockMaintenanceResult {
     noShows: number;
     /** Waitlist entries whose window came free, each now holding it (`waitlist.offered`). */
     waitlistOffers: number;
+    /** Approvals no one decided in time, their held time freed (`approval.expired`). */
+    approvalsExpired: number;
     /** More was left than one pass does: run another. */
     capped: boolean;
     /**
@@ -41,6 +43,12 @@ export declare function maintainSlotlockTenant(store: SlotlockStore, tenantRef:
     batches?: number;
     signal?: AbortSignal;
     followZoneRules?: boolean;
+    /**
+     * Roll the tenant's committed bookings and holds up into its usage first (usage.ts), before
+     * pruning can delete feed changes it has not counted. For a deployment that meters
+     * (SLOTLOCK_USAGE=on).
+     */
+    usage?: boolean;
 }): Promise<SlotlockMaintenanceResult>;
 /**
  * Run `work` holding the tenant's maintenance lock on a connection of its own, or return
@@ -73,6 +81,8 @@ export interface SlotlockMaintenanceSchedulerOptions {
     maxTenants?: number;
     /** Batches of each task per pass (maintainSlotlockTenant). */
     batches?: number;
+    /** Roll each tenant's bookings and holds up into its usage, first (maintainSlotlockTenant `usage`). */
+    usage?: boolean;
     /** A pass that ran: counts only, never the tenant. Not awaited; what it throws is ignored. */
     onPass?: (result: SlotlockMaintenanceResult) => void;
     /**

package/maintenance.js

@@ -11,6 +11,14 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
         throw new RangeError('batches must be a whole number from 1 to 100');
     }
     const withTenant = (callback) => store.withTenant(tenantRef, callback, { origin: 'maintenance' });
+    if (options.usage) {
+        for (let batch = 0; batch < batches; batch++) {
+            options.signal?.throwIfAborted();
+            const read = await withTenant((tenant) => tenant.rollUpUsage({ tenantRef, limit: USAGE_ROLL_UP_BATCH }));
+            if (read < USAGE_ROLL_UP_BATCH)
+                break;
+        }
+    }
     const window = calendarEventRollingHorizon();
     let extended = 0;
     let conflicts = 0;
@@ -66,7 +74,9 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     pruned += await withTenant((tenant) => tenant.pruneAssistantConversations({ tenantRef }));
     const zones = await withTenant((tenant) => tenant.followZoneRules({ tenantRef, move: options.followZoneRules === true }));
     const staleSources = await withTenant((tenant) => tenant.reportStaleCoverage({ tenantRef }));
-    // No-shows first: the time they free is offered to the waitlist in the same pass.
+    // Approvals past their wait, and no-shows, first: the time they free is offered to the waitlist
+    // in the same pass.
+    const approvals = await withTenant((tenant) => tenant.expireApprovals({ tenantRef, limit: 100 }));
     const noShows = await withTenant((tenant) => tenant.releaseNoShows({ tenantRef }));
     // The whole waitlist in join order, a page per transaction, so a later free entry is offered
     // however many wait before it.
@@ -92,7 +102,8 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
         staleSources,
         noShows,
         waitlistOffers,
-        capped: rollCapped || eventsLeft || bookingsLeft || changesLeft,
+        approvalsExpired: approvals.expired,
+        capped: rollCapped || eventsLeft || bookingsLeft || changesLeft || approvals.expired === 100,
         rollPending: rollCapped && after !== null && (after.rollRetryAt ?? null) === null,
     };
 }
@@ -102,6 +113,8 @@ const WAITLIST_PAGES = Math.ceil(SLOTLOCK_MAX_WAITLIST_PER_TENANT / 50);
 const SWEEP_INTERVAL_MS = 15 * 60_000;
 /** Feed changes past the retention deleted per batch. */
 const CHANGE_PRUNE_BATCH = 1_000;
+/** Feed changes rolled up into usage per batch. */
+const USAGE_ROLL_UP_BATCH = 5_000;
 /** The advisory lock key for one tenant's maintenance (64-bit, from the tenant reference). */
 const LOCK_NAMESPACE = 'slotlock.maintenance:';
 /**
@@ -169,6 +182,7 @@ export function startSlotlockMaintenance(options) {
                 try {
                     const result = await withSlotlockMaintenanceLock(options.sql, tenantRef, () => maintainSlotlockTenant(options.store, tenantRef, {
                         ...(options.batches !== undefined ? { batches: options.batches } : {}),
+                        ...(options.usage ? { usage: true } : {}),
                         signal: controller.signal,
                     }));
                     recordPass(tenantRef, Date.now());

package/metrics.d.ts

@@ -2,6 +2,8 @@ import type { SlotlockAgentServerEvent } from './agent-server.js';
 import type { SlotlockMaintenanceResult } from './maintenance.js';
 import type { SlotlockRefusalCounts } from './rate-limit.js';
 import type { SlotlockWebhookPassResult } from './webhooks.js';
+/** A metric's labels, by name. */
+export type Labels = Readonly<Record<string, string>>;
 export interface SlotlockMetrics {
     /** Count what the agent server reports (its `onEvent`). */
     event(event: SlotlockAgentServerEvent): void;
@@ -13,8 +15,47 @@ export interface SlotlockMetrics {
     webhooks(result: SlotlockWebhookPassResult): void;
     /** Count a scrape refused for its credential. */
     refusedScrape(): void;
+    /**
+     * Count an authenticated request by the integrator its `Slotlock-Client` field names (RFC 0003
+     * P5): a name from the deployment's known list, `other` or `none` (slotlockClientLabel).
+     */
+    client(name: string): void;
     /** Everything counted so far, as a scrape answers it. */
     render(): string;
+    /** Everything counted so far, as data: for an OpenTelemetry metrics export (otel.ts). */
+    collect(): SlotlockMetricsSnapshot;
+}
+/** The counters and histograms of one server since it started (cumulative). */
+export interface SlotlockMetricsSnapshot {
+    startedAtMs: number;
+    counters: {
+        name: string;
+        help: string;
+        points: {
+            labels: Labels;
+            value: number;
+        }[];
+    }[];
+    histograms: {
+        name: string;
+        help: string;
+        /** Upper bounds, in seconds; each point's buckets count what fell at or under each one. */
+        bounds: readonly number[];
+        points: {
+            labels: Labels;
+            cumulative: number[];
+            sum: number;
+            count: number;
+        }[];
+    }[];
+    gauges: {
+        name: string;
+        help: string;
+        points: {
+            labels: Labels;
+            value: number;
+        }[];
+    }[];
 }
 /** Counters for one server process, reset when it restarts (`slotlock_start_time_seconds`). */
 export declare function createSlotlockMetrics(info: {