slotlock 0.6.3 → 0.7.0

package/teams.d.ts

@@ -0,0 +1,25 @@
+import type { SlotlockSql } from './store.js';
+/** What the dashboard reads and changes of the organizations turned on (SLOTLOCK_DASHBOARD_ORGS=enabled). */
+export interface SlotlockDashboardTeams {
+    /** Of these organization ids, the ones turned on. */
+    enabled(ids: readonly string[]): Promise<ReadonlySet<string>>;
+    /** Turn Slotlock on for an organization, by an owner of it (`github:<id>`). True when it was off. */
+    enable(org: {
+        id: string;
+        login: string;
+    }, by: string): Promise<boolean>;
+    /** Turn it off: its keys stop at once, and its data stay. True when it was on. */
+    disable(id: string, by: string): Promise<boolean>;
+}
+/** The organizations turned on, through slotlock.enabled_organizations and its two writers. */
+export declare function createSlotlockDashboardTeams(sql: SlotlockSql): SlotlockDashboardTeams;
+/**
+ * Whether an organization is turned on, for `serve`'s keys with SLOTLOCK_DASHBOARD_ORGS=enabled:
+ * read through slotlock.enabled_organizations and kept for `ttlMs` (30 seconds), so turning one off
+ * stops its keys on every server within that, without a query per request.
+ */
+export declare function createSlotlockOrganizationCheck(sql: SlotlockSql, options?: {
+    ttlMs?: number;
+    now?: () => number;
+    maxEntries?: number;
+}): (orgId: string) => Promise<boolean>;

package/teams.js

@@ -0,0 +1,63 @@
+const ORGANIZATION_ID = /^[1-9]\d{0,19}$/;
+const GITHUB_LOGIN = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}$/;
+const PERSON = /^github:[1-9]\d{0,19}$/;
+function refuse(message) {
+    throw Object.assign(new Error(`Slotlock organizations: ${message}`), { code: 'invalid_organization' });
+}
+/** The organizations turned on, through slotlock.enabled_organizations and its two writers. */
+export function createSlotlockDashboardTeams(sql) {
+    return {
+        async enabled(ids) {
+            const valid = ids.filter((id) => ORGANIZATION_ID.test(id));
+            if (valid.length === 0)
+                return new Set();
+            const rows = await sql `
+        SELECT org_id FROM slotlock.enabled_organizations(${valid.join(',')}::text) AS org_id`;
+            return new Set(rows.map((row) => row.org_id));
+        },
+        async enable(org, by) {
+            if (!ORGANIZATION_ID.test(org.id) || !GITHUB_LOGIN.test(org.login) || !PERSON.test(by)) {
+                refuse('needs an organization id, its login and the person turning it on');
+            }
+            const [row] = await sql `
+        SELECT slotlock.enable_organization(${org.id}::text, ${org.login}::text, ${by}::text) AS changed`;
+            return row?.changed === true;
+        },
+        async disable(id, by) {
+            if (!ORGANIZATION_ID.test(id) || !PERSON.test(by))
+                refuse('needs an organization id and the person turning it off');
+            const [row] = await sql `
+        SELECT slotlock.disable_organization(${id}::text, ${by}::text) AS changed`;
+            return row?.changed === true;
+        },
+    };
+}
+/**
+ * Whether an organization is turned on, for `serve`'s keys with SLOTLOCK_DASHBOARD_ORGS=enabled:
+ * read through slotlock.enabled_organizations and kept for `ttlMs` (30 seconds), so turning one off
+ * stops its keys on every server within that, without a query per request.
+ */
+export function createSlotlockOrganizationCheck(sql, options = {}) {
+    const ttlMs = options.ttlMs ?? 30_000;
+    const now = options.now ?? Date.now;
+    const maxEntries = options.maxEntries ?? 10_000;
+    const known = new Map();
+    const teams = createSlotlockDashboardTeams(sql);
+    return (orgId) => {
+        if (!ORGANIZATION_ID.test(orgId))
+            return Promise.resolve(false);
+        const cached = known.get(orgId);
+        if (cached && now() - cached.at < ttlMs)
+            return cached.enabled;
+        const enabled = teams.enabled([orgId]).then((found) => found.has(orgId), (error) => {
+            // A failed read is not remembered: the next request asks again.
+            known.delete(orgId);
+            throw error;
+        });
+        known.delete(orgId);
+        known.set(orgId, { at: now(), enabled });
+        if (known.size > maxEntries)
+            known.delete(known.keys().next().value);
+        return enabled;
+    };
+}

package/timezone.js

@@ -247,6 +247,11 @@ export function canonicalTimeZoneName(timezone) {
     const invalid = () => Object.assign(new Error(`Invalid timezone: ${timezone}`), { code: 'invalid_timezone' });
     if (!name || /^[+-]/.test(name))
         throw invalid();
+    // Each name resolves the same for the process's life (its time zone data does not change under
+    // it), and building a formatter to ask is the costly part: remembered, valid names only.
+    const known = canonicalNames.get(name);
+    if (known !== undefined)
+        return known;
     let resolved;
     try {
         resolved = new Intl.DateTimeFormat('en-US', { timeZone: name }).resolvedOptions().timeZone;
@@ -256,8 +261,15 @@ export function canonicalTimeZoneName(timezone) {
     }
     if (/^[+-]/.test(resolved))
         throw invalid();
-    return resolved.toLowerCase() === name.toLowerCase() ? resolved : name;
+    const canonical = resolved.toLowerCase() === name.toLowerCase() ? resolved : name;
+    if (canonicalNames.size >= MAX_CANONICAL_NAMES)
+        canonicalNames.clear();
+    canonicalNames.set(name, canonical);
+    return canonical;
 }
+/** Names canonicalTimeZoneName resolved; a few hundred zones exist, so this rarely fills. */
+const canonicalNames = new Map();
+const MAX_CANONICAL_NAMES = 2_000;
 /**
  * The civil date and ISO weekday an instant falls on in `timezone` (the inverse of {@link
  * zonedDateTimeToUtc}): a pickup at 00:30 BST on a Friday is a Friday, whatever UTC says.

package/types.d.ts

@@ -1,4 +1,5 @@
 import type { SlotlockBookingRule, SlotlockBookingRules } from './booking-rules.js';
+import type { SlotlockResourceAttributes, SlotlockResourceKind } from './resource-profile.js';
 /** Half-open time interval `[start, end)`. */
 export interface Interval {
     start: Date;
@@ -40,6 +41,94 @@ export interface SlotlockResource {
      * (`slotlock_book_pool`).
      */
     pool?: string;
+    /**
+     * The composite it is a part of (RFC 0003 G8), and its place there: a booking of the whole
+     * conflicts with every part. Absent when it is no part.
+     */
+    parentId?: string;
+    partIndex?: number;
+    /** Its name, shown instead of `externalRef` (resource-profile.ts). Absent when it has none. */
+    name?: string;
+    /** What it is, in a sentence or a paragraph. Absent when it has none. */
+    description?: string;
+    /** What kind of thing it is, a hint for filtering that changes no booking. Absent: `other`. */
+    kind?: SlotlockResourceKind;
+    /** How many people or seats it holds, said for people to read; never enforced. Absent: not said. */
+    capacity?: number;
+    /** Labels to find it by, sorted. Absent when it has none. */
+    labels?: string[];
+    /** What the integrator keeps on it. Absent when it has none. */
+    attributes?: SlotlockResourceAttributes;
+    /** The reference of the location it is at (resource-profile.ts). Absent when not said. */
+    location?: string;
+    /** That location's name. */
+    locationName?: string;
+    /** The references of the groups it is in, sorted. Absent when it is in none. */
+    groups?: string[];
+}
+/** Which writes an approval policy covers (RFC 0004 A4); none named is every write it applies to. */
+export type SlotlockApprovalKind = 'single' | 'pool' | 'bundle' | 'move';
+/** A tenant's approval policy (RFC 0004 A4). */
+export interface SlotlockApprovalPolicy {
+    ref: string;
+    name: string;
+    /** The resources it applies to; every one when all are empty. */
+    appliesTo: {
+        resourceIds?: string[];
+        pools?: string[];
+        locations?: string[];
+        groups?: string[];
+    };
+    /** What makes a write need it; a write meets it when it meets every condition given. */
+    conditions: {
+        longerThanMinutes?: number;
+        outsideHours?: boolean;
+        kinds?: SlotlockApprovalKind[];
+    };
+    outcome: 'require_approval' | 'refuse';
+    /** How long a person has to decide, before the booking's start less `leadMinutes`. */
+    approvalTtlMinutes: number;
+    leadMinutes: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/** A write waiting for a person, or decided (RFC 0004 A4). */
+export interface SlotlockApproval {
+    id: string;
+    policyRef: string;
+    status: 'pending' | 'granted' | 'declined' | 'expired';
+    /** The agent operation it runs when granted, and its arguments. */
+    operation: 'slotlock_create_event' | 'slotlock_book_together' | 'slotlock_update_event';
+    request: Record<string, unknown>;
+    /** Who asked, as the history names an actor (the principal's subject, at most 200 characters). */
+    requestedBy: string | null;
+    /** The resources and time it holds while it waits. */
+    holdIds: string[];
+    resourceIds: string[];
+    start: Date;
+    end: Date;
+    expiresAt: Date;
+    decidedBy: string | null;
+    decidedAt: Date | null;
+    reason: string | null;
+    createdAt: Date;
+}
+/**
+ * A booking, hold or event occurrence as a refusal can name it (`describeBooking`): the time it
+ * occupies, buffers included, and whose it is, so a caller is told only what it may see.
+ */
+export interface SlotlockBookingDescription {
+    id: string;
+    resourceId: string;
+    status: 'held' | 'confirmed';
+    /** The holder of a hold, as the store was given it; null otherwise. */
+    holderRef: string | null;
+    /** The calendar event this is an occurrence of (its id and reference), and its owner; null for a booking. */
+    eventId: string | null;
+    eventRef: string | null;
+    eventOwnerRef: string | null;
+    start: Date;
+    end: Date;
 }
 /** A confirmed occupation of a resource. The DB EXCLUDE constraint is the overlap arbiter. */
 export interface SlotlockReservation {
@@ -505,11 +594,16 @@ export type PutCalendarEventResult = {
     code: 'revision_conflict';
     currentRevision: number;
 }
-/** `fromHold` names no live hold of that holder's: released, booked, expired, or another's. */
+/** `fromHold` names no hold of that holder's: released, booked, reaped, or another's. */
  | {
     ok: false;
     code: 'hold_not_found';
 }
+/** `fromHold`'s hold is the holder's, but it lapsed before it was booked. */
+ | {
+    ok: false;
+    code: 'hold_expired';
+}
 /** `fromHold`'s hold is on another resource, or does not cover the event. */
  | {
     ok: false;

package/usage.d.ts

@@ -0,0 +1,106 @@
+import type { SlotlockAgentUsage } from './agent-server.js';
+import { SLOTLOCK_RECORDED_USAGE_METRICS, SLOTLOCK_USAGE_METRICS, SLOTLOCK_USAGE_RETENTION_DAYS } from './ddl.js';
+import type { SlotlockSql } from './store.js';
+export type SlotlockUsageMetric = (typeof SLOTLOCK_USAGE_METRICS)[number];
+/** What a server counts and records itself; bookings, holds and resources the database counts. */
+export type SlotlockRecordedUsageMetric = (typeof SLOTLOCK_RECORDED_USAGE_METRICS)[number];
+export { SLOTLOCK_RECORDED_USAGE_METRICS, SLOTLOCK_USAGE_METRICS, SLOTLOCK_USAGE_RETENTION_DAYS };
+/** One counted row: a tenant's count of one metric on one UTC day, by key ('' for none) and surface. */
+export interface SlotlockUsageCount {
+    tenantRef: string;
+    /** The UTC day, `YYYY-MM-DD`. */
+    day: string;
+    metric: SlotlockRecordedUsageMetric;
+    keyId: string;
+    origin: string;
+    count: number;
+}
+export interface SlotlockUsageMeterOptions {
+    /** Records one batch once per `flushId`: true when added, false when it was added before. */
+    record(flushId: string, rows: readonly SlotlockUsageCount[]): Promise<boolean>;
+    /** How often counts are recorded, in milliseconds (default 15,000). 0: only on `flush`. */
+    intervalMs?: number;
+    now?: () => number;
+    /** A batch the database refused (kept for the next flush), or one dropped after too many. */
+    onError?: (error: unknown) => void;
+}
+export interface SlotlockUsageMeter {
+    /** Count one operation (the agent server's `onUsage`). Never throws, never waits. */
+    count(usage: SlotlockAgentUsage): void;
+    /**
+     * Count something else a server sees: webhook deliveries an endpoint accepted, messages to the
+     * assistant. Never throws, never waits; a count below 1 is ignored.
+     */
+    add(usage: {
+        tenantRef: string;
+        metric: Exclude<SlotlockRecordedUsageMetric, 'operations'>;
+        origin: string;
+        count?: number;
+        keyId?: string;
+    }): void;
+    /**
+     * Record what has been counted. A batch the database refuses is kept, with its id, and sent again
+     * first next time, so a batch whose answer was lost is never added twice.
+     */
+    flush(): Promise<void>;
+    /** Stop the timer and record what is left. */
+    close(): Promise<void>;
+    /** Rows counted and not yet recorded, held batches included. */
+    pending(): number;
+    /**
+     * What this meter has counted of a tenant's metric on `fromDay` (`YYYY-MM-DD`) or later and not
+     * yet recorded, batches held or being sent included, and how much of it it has counted since it
+     * started: quotas.ts adds them to what the database holds.
+     */
+    local(tenantRef: string, metric: SlotlockRecordedUsageMetric, fromDay: string): {
+        unrecorded: number;
+        counted: number;
+    };
+}
+/** The UTC day of an instant, `YYYY-MM-DD`. */
+export declare function slotlockUsageDay(at: number): string;
+export declare function createSlotlockUsageMeter(options: SlotlockUsageMeterOptions): SlotlockUsageMeter;
+/** `slotlock.record_usage`: one batch of counts, once per flush id. */
+export declare function recordSlotlockUsage(sql: SlotlockSql, flushId: string, rows: readonly SlotlockUsageCount[]): Promise<boolean>;
+/** One stored row of a tenant's usage. */
+export interface SlotlockUsageRow {
+    day: string;
+    metric: SlotlockUsageMetric;
+    keyId: string;
+    origin: string;
+    count: number;
+}
+/** The tenant's usage from `from` to `to`, UTC days inclusive (at most SLOTLOCK_USAGE_RETENTION_DAYS apart). */
+export declare function readSlotlockTenantUsage(sql: SlotlockSql, tenantRef: string, from: string, to: string): Promise<SlotlockUsageRow[]>;
+/**
+ * Each metric's total over some rows: every metric present, 0 when unused. Resources are a count
+ * each day, not something used up, so theirs is the latest day's.
+ */
+export declare function totalSlotlockUsage(rows: readonly SlotlockUsageRow[]): Record<SlotlockUsageMetric, number>;
+/** Operations, bookings and holds together: one line of a usage summary. */
+export type SlotlockUsageTotals = Record<SlotlockUsageMetric, number>;
+/** A tenant's usage over a range, as `GET /v1/usage` and the Plan page show it. */
+export interface SlotlockUsageSummary {
+    totals: SlotlockUsageTotals;
+    /** Each UTC day with any use, in order. */
+    days: Array<{
+        day: string;
+    } & SlotlockUsageTotals>;
+    /** Each API key with any use (`keyId` null: no key, such as the assistant), most operations first; no resources. */
+    keys: Array<{
+        keyId: string | null;
+    } & SlotlockUsageTotals>;
+    /** Each surface with any use (mcp, a2a, rest, application, dashboard-assistant, webhooks), most first; no resources. */
+    surfaces: Array<{
+        origin: string;
+    } & SlotlockUsageTotals>;
+}
+/** Totals, by day, by key and by surface, from stored rows: bounded however many rows there are. */
+export declare function summarizeSlotlockUsage(rows: readonly SlotlockUsageRow[]): SlotlockUsageSummary;
+/** The range `GET /v1/usage` reads when given none: the first of this UTC month to today. */
+export declare function slotlockUsageMonthToDate(at: number): {
+    from: string;
+    to: string;
+};
+/** Days from `from` to `to`, both `YYYY-MM-DD`: 0 for the same day, negative when `to` is earlier. */
+export declare function slotlockUsageSpanDays(from: string, to: string): number;

package/usage.js

@@ -0,0 +1,238 @@
+// Usage metering (RFC 0003 part 3): how much each tenant uses the service, by UTC day, API key and
+// surface. Operations are counted by the server that runs them (`createSlotlockUsageMeter`, fed by
+// the agent server's `onUsage`) and recorded in batches; bookings and holds are rolled up from the
+// tenant's feed by maintenance, so a write that rolled back is never counted. Counts only, never
+// arguments or results. Off unless the deployment asks for it (SLOTLOCK_USAGE=on).
+import { randomUUID } from 'node:crypto';
+import { SLOTLOCK_RECORDED_USAGE_METRICS, SLOTLOCK_USAGE_METRICS, SLOTLOCK_USAGE_RETENTION_DAYS, } from './ddl.js';
+export { SLOTLOCK_RECORDED_USAGE_METRICS, SLOTLOCK_USAGE_METRICS, SLOTLOCK_USAGE_RETENTION_DAYS };
+/** Rows one `slotlock.record_usage` call takes. */
+const MAX_BATCH_ROWS = 10_000;
+/** Batches kept for another try while the database refuses them; older ones are dropped, and said so. */
+const MAX_HELD_BATCHES = 100;
+/** PostgreSQL's invalid_parameter_value: record_usage refusing a batch it will never take. */
+const REFUSED_FOR_GOOD = '22023';
+/** Tenants whose running totals one meter keeps (`local`); past this they start again from 0. */
+const MAX_TOTALS = 100_000;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The UTC day of an instant, `YYYY-MM-DD`. */
+export function slotlockUsageDay(at) {
+    return new Date(at).toISOString().slice(0, 10);
+}
+export function createSlotlockUsageMeter(options) {
+    const now = options.now ?? Date.now;
+    let counted = new Map();
+    const held = [];
+    // Rows taken from `counted` for the flush under way, until each batch is recorded or held.
+    let sending = [];
+    // Everything counted since the meter started, by tenant and metric.
+    let totals = new Map();
+    let running = Promise.resolve();
+    const report = (error) => {
+        try {
+            options.onError?.(error);
+        }
+        catch {
+            // A reporter's failure changes nothing.
+        }
+    };
+    const dropped = (rows, why) => report(Object.assign(new Error(`Slotlock usage: ${String(rows)} counts dropped ${why}`), {
+        code: 'usage_dropped',
+    }));
+    // True when recorded, or when the database refused the batch for good (record_usage's
+    // invalid_parameter_value: a day it no longer takes, after an outage past the next day), which is
+    // then dropped rather than held in front of every batch after it. False to try again.
+    async function send(batch) {
+        try {
+            await options.record(batch.flushId, batch.rows);
+            return true;
+        }
+        catch (error) {
+            report(error);
+            if (error?.code === REFUSED_FOR_GOOD) {
+                dropped(batch.rows.length, 'that the database will not take');
+                return true;
+            }
+            return false;
+        }
+    }
+    async function flushOnce() {
+        // Batches refused before go first, under their own ids.
+        while (held.length > 0) {
+            if (!(await send(held[0])))
+                return;
+            held.shift();
+        }
+        if (counted.size === 0)
+            return;
+        const rows = [...counted.values()];
+        counted = new Map();
+        sending = rows;
+        try {
+            for (let start = 0; start < rows.length; start += MAX_BATCH_ROWS) {
+                const batch = { flushId: randomUUID(), rows: rows.slice(start, start + MAX_BATCH_ROWS) };
+                if (held.length > 0 || !(await send(batch)))
+                    held.push(batch);
+                sending = rows.slice(start + MAX_BATCH_ROWS);
+            }
+        }
+        finally {
+            sending = [];
+        }
+        while (held.length > MAX_HELD_BATCHES) {
+            const oldest = held.shift();
+            dropped(oldest?.rows.length ?? 0, `after the database refused them ${String(MAX_HELD_BATCHES)} times`);
+        }
+    }
+    const flush = () => {
+        running = running.then(flushOnce, flushOnce);
+        return running;
+    };
+    const interval = options.intervalMs ?? 15_000;
+    const timer = interval > 0 ? setInterval(() => void flush(), interval) : null;
+    timer?.unref?.();
+    function tally(tenantRef, metric, keyIdGiven, origin, count) {
+        try {
+            if (typeof tenantRef !== 'string' || tenantRef.length === 0)
+                return;
+            if (!Number.isSafeInteger(count) || count < 1)
+                return;
+            const keyId = typeof keyIdGiven === 'string' && UUID.test(keyIdGiven) ? keyIdGiven : '';
+            const day = slotlockUsageDay(now());
+            const key = `${tenantRef}\0${day}\0${metric}\0${keyId}\0${origin}`;
+            const found = counted.get(key);
+            if (found)
+                found.count += count;
+            else
+                counted.set(key, { tenantRef, day, metric, keyId, origin, count });
+            const total = `${tenantRef}\0${metric}`;
+            if (!totals.has(total) && totals.size >= MAX_TOTALS)
+                totals = new Map();
+            totals.set(total, (totals.get(total) ?? 0) + count);
+        }
+        catch {
+            // Metering never changes a call.
+        }
+    }
+    return {
+        count({ principal, origin }) {
+            tally(principal.tenantRef, 'operations', principal.keyId, origin, 1);
+        },
+        add({ tenantRef, metric, origin, count = 1, keyId }) {
+            tally(tenantRef, metric, keyId, origin, count);
+        },
+        flush,
+        async close() {
+            if (timer)
+                clearInterval(timer);
+            await flush();
+        },
+        pending() {
+            return [...counted.values()].length + held.reduce((sum, batch) => sum + batch.rows.length, 0);
+        },
+        local(tenantRef, metric, fromDay) {
+            let unrecorded = 0;
+            const add = (row) => {
+                if (row.tenantRef === tenantRef && row.metric === metric && row.day >= fromDay) {
+                    unrecorded += row.count;
+                }
+            };
+            for (const row of counted.values())
+                add(row);
+            for (const row of sending)
+                add(row);
+            for (const batch of held)
+                for (const row of batch.rows)
+                    add(row);
+            return { unrecorded, counted: totals.get(`${tenantRef}\0${metric}`) ?? 0 };
+        },
+    };
+}
+/** `slotlock.record_usage`: one batch of counts, once per flush id. */
+export async function recordSlotlockUsage(sql, flushId, rows) {
+    const payload = rows.map((row) => ({
+        tenant_ref: row.tenantRef,
+        day: row.day,
+        metric: row.metric,
+        key_id: row.keyId,
+        origin: row.origin,
+        count: row.count,
+    }));
+    const [result] = await sql `
+    SELECT slotlock.record_usage(${flushId}::uuid, ${JSON.stringify(payload)}::text::jsonb) AS added`;
+    return result?.added === true;
+}
+/** The tenant's usage from `from` to `to`, UTC days inclusive (at most SLOTLOCK_USAGE_RETENTION_DAYS apart). */
+export async function readSlotlockTenantUsage(sql, tenantRef, from, to) {
+    const rows = await sql `SELECT * FROM slotlock.tenant_usage(${tenantRef}::text, ${from}::date, ${to}::date)`;
+    return rows.map((row) => ({
+        day: typeof row.day === 'string' ? row.day.slice(0, 10) : slotlockUsageDay(row.day.getTime()),
+        metric: row.metric,
+        keyId: row.key_id,
+        origin: row.origin,
+        count: Number(row.count),
+    }));
+}
+/**
+ * Each metric's total over some rows: every metric present, 0 when unused. Resources are a count
+ * each day, not something used up, so theirs is the latest day's.
+ */
+export function totalSlotlockUsage(rows) {
+    const totals = Object.fromEntries(SLOTLOCK_USAGE_METRICS.map((metric) => [metric, 0]));
+    let resourcesDay = '';
+    for (const row of rows) {
+        if (row.metric !== 'resources')
+            totals[row.metric] += row.count;
+        else if (row.day > resourcesDay) {
+            resourcesDay = row.day;
+            totals.resources = row.count;
+        }
+        else if (row.day === resourcesDay)
+            totals.resources += row.count;
+    }
+    return totals;
+}
+/** Totals, by day, by key and by surface, from stored rows: bounded however many rows there are. */
+export function summarizeSlotlockUsage(rows) {
+    const zero = () => totalSlotlockUsage([]);
+    const days = new Map();
+    const keys = new Map();
+    const surfaces = new Map();
+    const add = (map, name, row) => {
+        const found = map.get(name) ?? zero();
+        found[row.metric] += row.count;
+        map.set(name, found);
+    };
+    for (const row of rows) {
+        add(days, row.day, row);
+        // A day's resource count belongs to no key or surface.
+        if (row.metric === 'resources')
+            continue;
+        add(keys, row.keyId, row);
+        add(surfaces, row.origin, row);
+    }
+    const byUse = (a, b) => b.operations - a.operations ||
+        b.bookings - a.bookings ||
+        b.holds - a.holds ||
+        b.webhook_deliveries - a.webhook_deliveries ||
+        b.assistant_messages - a.assistant_messages;
+    return {
+        totals: totalSlotlockUsage(rows),
+        days: [...days].sort(([a], [b]) => a.localeCompare(b)).map(([day, totals]) => ({ day, ...totals })),
+        keys: [...keys]
+            .sort(([a, x], [b, y]) => byUse(x, y) || a.localeCompare(b))
+            .map(([keyId, totals]) => ({ keyId: keyId === '' ? null : keyId, ...totals })),
+        surfaces: [...surfaces]
+            .sort(([a, x], [b, y]) => byUse(x, y) || a.localeCompare(b))
+            .map(([origin, totals]) => ({ origin, ...totals })),
+    };
+}
+/** The range `GET /v1/usage` reads when given none: the first of this UTC month to today. */
+export function slotlockUsageMonthToDate(at) {
+    const to = slotlockUsageDay(at);
+    return { from: `${to.slice(0, 8)}01`, to };
+}
+/** Days from `from` to `to`, both `YYYY-MM-DD`: 0 for the same day, negative when `to` is earlier. */
+export function slotlockUsageSpanDays(from, to) {
+    return Math.round((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`)) / 86_400_000);
+}