slotlock 0.3.0 → 0.5.1

package/booking-rules.js

@@ -0,0 +1,149 @@
+import { expandRules } from './rules.js';
+import { zonedOffsetMinutes } from './timezone.js';
+const MINUTE_MS = 60_000;
+const DAY_MINUTES = 24 * 60;
+/** Each numeric rule's least and greatest value. */
+export const SLOTLOCK_BOOKING_RULE_LIMITS = Object.freeze({
+    minNoticeMinutes: [0, 525_600],
+    maxAdvanceDays: [1, 3_660],
+    slotStepMinutes: [1, DAY_MINUTES],
+    turnaroundMinutes: [0, DAY_MINUTES],
+    checkInMinutes: [1, DAY_MINUTES],
+});
+const LIMITS = SLOTLOCK_BOOKING_RULE_LIMITS;
+/** Booking rules from untrusted input, or a TypeError naming the field that is wrong. */
+export function parseBookingRules(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('Slotlock booking rules must be an object');
+    }
+    const input = value;
+    const rules = {};
+    for (const key of Object.keys(input)) {
+        if (!(key in LIMITS) && key !== 'enforceHours' && key !== 'requireCertain') {
+            throw new TypeError(`Slotlock booking rules have no ${key}`);
+        }
+    }
+    for (const [key, [min, max]] of Object.entries(LIMITS)) {
+        const field = input[key];
+        if (field === undefined)
+            continue;
+        if (typeof field !== 'number' || !Number.isSafeInteger(field) || field < min || field > max) {
+            throw new TypeError(`Slotlock booking rule ${key} must be a whole ${min}-${max}`);
+        }
+        rules[key] = field;
+    }
+    if (input.enforceHours !== undefined) {
+        if (typeof input.enforceHours !== 'boolean') {
+            throw new TypeError('Slotlock booking rule enforceHours must be true or false');
+        }
+        rules.enforceHours = input.enforceHours;
+    }
+    if (input.requireCertain !== undefined) {
+        if (typeof input.requireCertain !== 'boolean') {
+            throw new TypeError('Slotlock booking rule requireCertain must be true or false');
+        }
+        rules.requireCertain = input.requireCertain;
+    }
+    return rules;
+}
+/** The trailing buffer a booking made under the rules keeps: the larger of its own and the rule's. */
+export function bookingBufferAfterMs(rules, ownMs = 0) {
+    return Math.max(ownMs, (rules?.turnaroundMinutes ?? 0) * MINUTE_MS);
+}
+/** Minutes past local midnight in `timezone`, with the fraction. */
+function localMinutes(instant, timezone) {
+    const local = instant.getTime() + zonedOffsetMinutes(instant, timezone) * MINUTE_MS;
+    return (((local / MINUTE_MS) % DAY_MINUTES) + DAY_MINUTES) % DAY_MINUTES;
+}
+function onStep(instant, stepMinutes, timezone) {
+    const minutes = localMinutes(instant, timezone);
+    return Number.isInteger(minutes) && minutes % stepMinutes === 0;
+}
+/**
+ * The first instant at or after `from` that starts on a step in `timezone`. A step that does not
+ * divide the day starts again at local midnight. Across a clock change it moves forward until the
+ * local time is on a step.
+ */
+export function nextStepStart(from, stepMinutes, timezone) {
+    let candidate = from;
+    for (let attempt = 0; attempt < 4; attempt++) {
+        if (onStep(candidate, stepMinutes, timezone))
+            return candidate;
+        const minutes = localMinutes(candidate, timezone);
+        const next = Math.min(Math.ceil(minutes / stepMinutes + 1e-9) * stepMinutes, DAY_MINUTES);
+        const ahead = Math.max(next - minutes, 1 / 60_000);
+        candidate = new Date(Math.ceil(candidate.getTime() + ahead * MINUTE_MS));
+    }
+    return candidate;
+}
+/**
+ * The rule a booking of `interval` made at `now` breaks, or null. `hours` are the resource's
+ * bookable hours (its own, or the default), read only when the rules enforce them.
+ */
+export function bookingRuleBroken(params) {
+    const { rules, interval, now } = params;
+    if (!rules)
+        return null;
+    const start = interval.start.getTime();
+    if (rules.minNoticeMinutes !== undefined && start < now.getTime() + rules.minNoticeMinutes * MINUTE_MS) {
+        return 'min_notice';
+    }
+    if (rules.maxAdvanceDays !== undefined &&
+        start > now.getTime() + rules.maxAdvanceDays * DAY_MINUTES * MINUTE_MS) {
+        return 'max_advance';
+    }
+    if (rules.slotStepMinutes !== undefined && !onStep(interval.start, rules.slotStepMinutes, params.timezone)) {
+        return 'slot_step';
+    }
+    if (rules.enforceHours === true) {
+        const open = expandRules([...params.hours], interval, params.timezone);
+        let covered = interval.start.getTime();
+        for (const window of open.sort((a, b) => a.start.getTime() - b.start.getTime())) {
+            if (window.start.getTime() > covered)
+                break;
+            covered = Math.max(covered, window.end.getTime());
+            if (covered >= interval.end.getTime())
+                break;
+        }
+        if (covered < interval.end.getTime())
+            return 'outside_hours';
+    }
+    return null;
+}
+/**
+ * How a search honours the rules: the part of `window` a booking made at `now` may start in, the
+ * trailing buffer each slot keeps, and how a candidate start moves to a step. `null` when no start
+ * in the window is allowed.
+ */
+export function bookingSearch(params) {
+    const { rules, window, now } = params;
+    let start = window.start.getTime();
+    let end = window.end.getTime();
+    if (rules?.minNoticeMinutes !== undefined) {
+        start = Math.max(start, now.getTime() + rules.minNoticeMinutes * MINUTE_MS);
+    }
+    const bufferAfterMs = bookingBufferAfterMs(rules, params.bufferAfterMs ?? 0);
+    const step = rules?.slotStepMinutes;
+    const searched = { start: new Date(start), end: new Date(end) };
+    if (rules?.maxAdvanceDays !== undefined) {
+        // The latest allowed start bounds where a slot may start; it may still end after it.
+        const latestStart = now.getTime() + rules.maxAdvanceDays * DAY_MINUTES * MINUTE_MS;
+        if (latestStart < start || end <= start)
+            return null;
+        const align = step === undefined ? undefined : (from) => nextStepStart(from, step, params.timezone);
+        return {
+            window: searched,
+            bufferAfterMs,
+            align: (from) => {
+                const aligned = align ? align(from) : from;
+                // Past the latest start, no slot: move it beyond the window so it cannot fit.
+                return aligned.getTime() > latestStart ? new Date(end + 1) : aligned;
+            },
+        };
+    }
+    if (end <= start)
+        return null;
+    return step === undefined
+        ? { window: searched, bufferAfterMs }
+        : { window: searched, bufferAfterMs, align: (from) => nextStepStart(from, step, params.timezone) };
+}

package/config.d.ts

@@ -20,6 +20,11 @@ export declare function readServerUrl(env: SlotlockEnv, name: string, fallback?:
  * an absolute UNTIL) is a startup error instead of silently making every resource unbookable.
  */
 export declare function readAvailability(env: SlotlockEnv): WeeklyAvailabilityRule[];
+/**
+ * A dashboard name (SLOTLOCK_DASHBOARD_NAME): 1-60 characters, none of them a control, format
+ * (bidi, zero-width) or line separator character, `<` or `>`.
+ */
+export declare const SLOTLOCK_DASHBOARD_NAME_PATTERN: RegExp;
 /** The GitHub sign-in dashboard (dashboard.ts), served at `<publicUrl>/dashboard` when configured. */
 export interface SlotlockServeDashboardConfig {
     githubClientId: string;
@@ -27,12 +32,22 @@ export interface SlotlockServeDashboardConfig {
     sessionSecret: string;
     /** GitHub user ids that may sign in, or `'*'` for every GitHub account. */
     allowedUsers: '*' | string[];
+    /** GitHub organization ids whose members share a tenant each (SLOTLOCK_DASHBOARD_ORGS). */
+    organizations?: string[];
+    /** What the deployment is called in the dashboard (SLOTLOCK_DASHBOARD_NAME). */
+    name?: string;
 }
 /**
  * The dashboard's settings, or undefined when none is set. Setting any of them means serving the
  * dashboard, so the rest are then required: a half-configured sign-in is a startup error.
  */
 export declare function readDashboardConfig(env: SlotlockEnv): SlotlockServeDashboardConfig | undefined;
+/**
+ * The GitHub organization ids of SLOTLOCK_DASHBOARD_ORGS, or undefined when unset. Read on its own as
+ * well: a server whose dashboard runs elsewhere (on Cloudflare Workers) still takes those
+ * organizations' keys, and only theirs.
+ */
+export declare function readDashboardOrganizations(env: SlotlockEnv): string[] | undefined;
 /** A token bucket: `perSecond` tokens come back each second, and it holds at most `burst`. */
 export interface SlotlockRate {
     perSecond: number;
@@ -56,9 +71,11 @@ declare const CAP_RANGES: Readonly<{
     readonly tenant_reservations: readonly [1, 10000000];
     readonly tenant_events: readonly [1, 10000000];
     readonly tenant_coverage: readonly [1, 10000000];
+    readonly holder_holds: readonly [1, 10000];
+    readonly holder_held_hours: readonly [1, 876000];
 }>;
 export type SlotlockCapName = keyof typeof CAP_RANGES;
-export declare const SLOTLOCK_CAP_NAMES: readonly ("key_lookup_queue" | "key_lookups" | "key_subscriptions" | "maintenance_runs" | "series_writes" | "subscriptions" | "tenant_coverage" | "tenant_events" | "tenant_holds" | "tenant_reservations" | "tenant_series_writes" | "tenant_subscriptions" | "tenant_transactions")[];
+export declare const SLOTLOCK_CAP_NAMES: readonly ("holder_held_hours" | "holder_holds" | "key_lookup_queue" | "key_lookups" | "key_subscriptions" | "maintenance_runs" | "series_writes" | "subscriptions" | "tenant_coverage" | "tenant_events" | "tenant_holds" | "tenant_reservations" | "tenant_series_writes" | "tenant_subscriptions" | "tenant_transactions")[];
 export interface SlotlockLimits {
     /** Each rate, or null where SLOTLOCK_LIMITS turns it off. */
     rates: Readonly<Record<SlotlockRateName, SlotlockRate | null>>;
@@ -102,6 +119,8 @@ export interface SlotlockLimits {
  *   agent or application writes it. Every write surface of the server shares them, so no admin
  *   key can grow the shared database without end; a write past one answers 409 with its
  *   `*_limit_reached` code.
+ * - `holder_holds` and `holder_held_hours`: one holder's (an agent's) live holds, how many and how
+ *   many hours they hold together (`hold_limit_reached`, `held_time_limit_reached`).
  */
 export declare const SLOTLOCK_DEFAULT_LIMITS: SlotlockLimits;
 /**

package/config.js

@@ -92,6 +92,11 @@ export function readAvailability(env) {
         };
     });
 }
+/**
+ * A dashboard name (SLOTLOCK_DASHBOARD_NAME): 1-60 characters, none of them a control, format
+ * (bidi, zero-width) or line separator character, `<` or `>`.
+ */
+export const SLOTLOCK_DASHBOARD_NAME_PATTERN = /^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}<>]{1,60}$/u;
 const DASHBOARD_VARIABLES = [
     'SLOTLOCK_GITHUB_CLIENT_ID',
     'SLOTLOCK_GITHUB_CLIENT_SECRET',
@@ -129,13 +134,34 @@ export function readDashboardConfig(env) {
     if (users === undefined || (users !== '*' && !/^[1-9]\d{0,19}(,[1-9]\d{0,19})*$/.test(users))) {
         throw new SlotlockConfigError('SLOTLOCK_DASHBOARD_USERS is required to serve the dashboard: * for every GitHub account, or a comma-separated list of GitHub user ids (gh api users/<login> --jq .id)');
     }
+    const orgs = readDashboardOrganizations(env);
+    const name = optional(env, 'SLOTLOCK_DASHBOARD_NAME')?.trim();
+    if (name !== undefined && name !== '' && !SLOTLOCK_DASHBOARD_NAME_PATTERN.test(name)) {
+        throw new SlotlockConfigError('SLOTLOCK_DASHBOARD_NAME must be 1-60 characters, without <, > or control or invisible characters');
+    }
     return {
         githubClientId,
         githubClientSecret,
         sessionSecret,
         allowedUsers: users === '*' ? '*' : [...new Set(users.split(','))],
+        ...(orgs !== undefined ? { organizations: orgs } : {}),
+        ...(name !== undefined && name !== '' ? { name } : {}),
     };
 }
+/**
+ * The GitHub organization ids of SLOTLOCK_DASHBOARD_ORGS, or undefined when unset. Read on its own as
+ * well: a server whose dashboard runs elsewhere (on Cloudflare Workers) still takes those
+ * organizations' keys, and only theirs.
+ */
+export function readDashboardOrganizations(env) {
+    const orgs = optional(env, 'SLOTLOCK_DASHBOARD_ORGS')?.replaceAll(' ', '');
+    if (orgs === undefined)
+        return undefined;
+    if (!/^[1-9]\d{0,19}(,[1-9]\d{0,19})*$/.test(orgs)) {
+        throw new SlotlockConfigError('SLOTLOCK_DASHBOARD_ORGS must be a comma-separated list of GitHub organization ids (gh api orgs/<login> --jq .id)');
+    }
+    return [...new Set(orgs.split(','))];
+}
 /** The token buckets `slotlock serve` keeps (SLOTLOCK_LIMITS), each counted per its own key. */
 export const SLOTLOCK_RATE_NAMES = Object.freeze([
     'address',
@@ -165,6 +191,8 @@ const CAP_RANGES = Object.freeze({
     tenant_reservations: [1, 10_000_000],
     tenant_events: [1, 10_000_000],
     tenant_coverage: [1, 10_000_000],
+    holder_holds: [1, 10_000],
+    holder_held_hours: [1, 876_000],
 });
 export const SLOTLOCK_CAP_NAMES = Object.freeze(Object.keys(CAP_RANGES));
 /**
@@ -205,6 +233,8 @@ export const SLOTLOCK_CAP_NAMES = Object.freeze(Object.keys(CAP_RANGES));
  *   agent or application writes it. Every write surface of the server shares them, so no admin
  *   key can grow the shared database without end; a write past one answers 409 with its
  *   `*_limit_reached` code.
+ * - `holder_holds` and `holder_held_hours`: one holder's (an agent's) live holds, how many and how
+ *   many hours they hold together (`hold_limit_reached`, `held_time_limit_reached`).
  */
 export const SLOTLOCK_DEFAULT_LIMITS = Object.freeze({
     rates: Object.freeze({
@@ -235,6 +265,9 @@ export const SLOTLOCK_DEFAULT_LIMITS = Object.freeze({
         tenant_reservations: 100_000,
         tenant_events: 100_000,
         tenant_coverage: 100_000,
+        // One agent's live holds: 20 at once (candidates for a few bookings), holding 90 days in all.
+        holder_holds: 20,
+        holder_held_hours: 2_160,
     }),
 });
 /**

package/dashboard.d.ts

@@ -1,9 +1,14 @@
 import type { SlotlockApiKeyStore } from './api-keys.js';
-import type { SlotlockSql, SlotlockStore } from './store.js';
-import type { SlotlockResource, WeeklyAvailabilityRule } from './types.js';
+import { type SlotlockBookingRules } from './booking-rules.js';
+import { type CreateWebhookEndpointResult, type SlotlockChange, type SlotlockWebhookEndpoint } from './event-feed.js';
+import type { SlotlockSql, SlotlockStore, SlotlockWaitlistEntry } from './store.js';
+import type { Interval, SlotlockAgendaEntry, SlotlockResource, WeeklyAvailabilityRule } from './types.js';
 /** Resources one dashboard tenant may hold. */
 export declare const SLOTLOCK_DASHBOARD_MAX_RESOURCES = 100;
-/** A tenant's calendar resources, as the dashboard lists and adds them. */
+/**
+ * A tenant's calendar resources, as the dashboard lists and adds them. Each write takes, last, the
+ * person who made it (`github:<user id>`) as `actor`, to record on the event feed.
+ */
 export interface SlotlockDashboardResources {
     list(tenantRef: string): Promise<SlotlockResource[]>;
     /**
@@ -11,7 +16,7 @@ export interface SlotlockDashboardResources {
      * (an error with `code: 'resource_limit_reached'`) once the tenant has
      * SLOTLOCK_DASHBOARD_MAX_RESOURCES, however many adds race, on however many servers.
      */
-    add(tenantRef: string, externalRef: string, timezone: string): Promise<SlotlockResource>;
+    add(tenantRef: string, externalRef: string, timezone: string, actor?: string): Promise<SlotlockResource>;
     /**
      * Set the bookable hours of one of the tenant's resources (`{ id }`) or of all of them; `null`
      * hands them back to the server's and `[]` closes. Returns how many resources changed: 0 for an
@@ -19,7 +24,32 @@ export interface SlotlockDashboardResources {
      */
     setHours(tenantRef: string, target: {
         id: string;
-    } | 'all', rules: WeeklyAvailabilityRule[] | null): Promise<number>;
+    } | 'all', rules: WeeklyAvailabilityRule[] | null, actor?: string): Promise<number>;
+    /** What occupies the tenant's resources in `window`, by start: the overview's agenda. */
+    agenda?(tenantRef: string, window: Interval, limit: number): Promise<SlotlockAgendaEntry[]>;
+    /** The tenant's latest changes, newest first: the overview's activity. */
+    recentChanges?(tenantRef: string, limit: number): Promise<SlotlockChange[]>;
+    /**
+     * Set the booking rules of one of the tenant's resources (null clears them): the resource, or
+     * null when it is not the tenant's. Invalid rules throw with `code: 'invalid_booking_rules'`.
+     */
+    setRules?(tenantRef: string, id: string, rules: SlotlockBookingRules | null, actor?: string): Promise<SlotlockResource | null>;
+    /** Put one of the tenant's resources in a pool, or none: as setRules; `code: 'invalid_pool'`. */
+    setPool?(tenantRef: string, id: string, pool: string | null, actor?: string): Promise<SlotlockResource | null>;
+    /** The tenant's waitlist, oldest first, and leaving it (false when the entry is not the tenant's). */
+    waitlist?: {
+        list(tenantRef: string, limit: number): Promise<SlotlockWaitlistEntry[]>;
+        leave(tenantRef: string, id: string, actor?: string): Promise<boolean>;
+    };
+    /** The tenant's webhook endpoints, as the event feed keeps them. */
+    webhooks?: {
+        list(tenantRef: string): Promise<SlotlockWebhookEndpoint[]>;
+        create(tenantRef: string, url: string, eventTypes: readonly string[] | undefined, actor?: string): Promise<CreateWebhookEndpointResult>;
+        remove(tenantRef: string, id: string, actor?: string): Promise<boolean>;
+        enable(tenantRef: string, id: string, actor?: string): Promise<SlotlockWebhookEndpoint | null | {
+            code: 'changes_pruned';
+        }>;
+    };
 }
 /**
  * What the dashboard records so a sign-in callback works once, a sent form runs once and a
@@ -47,6 +77,8 @@ export interface SlotlockDashboardState {
 export interface SlotlockDashboardOptions {
     /** Where people reach the server; the dashboard lives at `<publicUrl>/dashboard`. */
     publicUrl: string;
+    /** What the deployment is called in the dashboard: 1-60 characters. Defaults to `Slotlock`. */
+    name?: string;
     /**
      * Where agents reach the server's MCP and A2A endpoints, which the dashboard shows, when it is
      * served from another origin (on Cloudflare Workers, with the server elsewhere). Defaults to
@@ -63,11 +95,23 @@ export interface SlotlockDashboardOptions {
         authorizeUrl?: string;
         tokenUrl?: string;
         userUrl?: string;
+        membershipsUrl?: string;
     };
     /** Seals sessions and sign-in state and derives CSRF tokens: 32+ random characters. */
     sessionSecret: string;
     /** GitHub user ids (numbers, as strings) that may sign in, or `'*'` for every GitHub account. */
     allowedUsers: '*' | readonly string[];
+    /**
+     * GitHub organization ids (numbers, as strings) this dashboard serves. With them, a tenant is an
+     * organization (`github-org:<id>`), not a person: sign-in asks for `read:org`, and a person signs
+     * in to the served organizations they are an active member of, sharing each one's keys and
+     * resources with its other members: owners and members, not billing managers, from the first
+     * 100 memberships GitHub lists, up to 20 served organizations. Membership is read at each sign-in; leaving an organization
+     * ends access at the next sign-in, at most a session (12 hours) later, and removing an
+     * organization from this list signs its sessions out at once. Without it, each person is their
+     * own tenant (`github:<id>`).
+     */
+    organizations?: readonly string[];
     keys: SlotlockApiKeyStore;
     resources: SlotlockDashboardResources;
     /** Shared by every server behind this origin: see SlotlockDashboardState. */
@@ -98,6 +142,18 @@ export interface SlotlockDashboard {
  * in the database (a READ COMMITTED transaction, under a per-tenant lock).
  */
 export declare function createSlotlockDashboardResources(store: SlotlockStore): SlotlockDashboardResources;
+/**
+ * Records accepted write confirmations (`SlotlockAgentConfirmationOptions.consumeAcceptance`) in
+ * Postgres, shared by every server on the database: true the first time a confirmation's nonce is
+ * recorded, false while it stays recorded, so an accepted confirmation runs its write once on any
+ * server. Kept until the confirmation's own expiry, through the same function and table as the
+ * dashboard's records (only a SHA-256 digest of the nonce is stored); pass a client, not a
+ * transaction.
+ */
+export declare function createSlotlockAcceptanceRecords(sql: SlotlockSql): (acceptance: {
+    nonce: string;
+    expiresAt: Date;
+}) => Promise<boolean>;
 /**
  * The dashboard's records in Postgres, shared by every server on the database. Run `applySchema()`
  * and `grantApplicationRole()` first: the serving role reaches the records only through