slotlock 0.8.0 → 0.9.0

package/self-host.js

@@ -3,7 +3,7 @@
 // supplies it the same way and nothing is read from a file or a request. A missing or weak secret
 // stops a command before it connects anywhere, and no secret is written to a log line or an error.
 // The one exception is the API key `key create` prints: that output is the key's only copy.
-import { createSlotlockWebhookSender, deliverSlotlockWebhooks, startSlotlockWebhookDelivery, } from './webhooks.js';
+import { createSlotlockGuardedFetch, createSlotlockWebhookSender, deliverSlotlockWebhooks, startSlotlockWebhookDelivery, } from './webhooks.js';
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import postgres from 'postgres';
@@ -21,6 +21,7 @@ import { createSlotlockDashboardTeams, createSlotlockOrganizationCheck } from '.
 import { SLOTLOCK_DEFAULT_OVERAGE_STOP_PERCENT, reportSlotlockOverage, slotlockMonthOf } from './overage.js';
 import { createSlotlockOtlpExporter, createSlotlockOtlpMetricsExporter, readSlotlockOtlpConfig, } from './otel.js';
 import { readFile } from 'node:fs/promises';
+import { readSlotlockHolidayCalendar } from './holiday-import.js';
 import { SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_QUOTA_FUNCTIONS, SLOTLOCK_TENANT_TABLES, SLOTLOCK_USAGE_FUNCTIONS, } from './ddl.js';
 import { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 import { createSlotlockNodeServer, } from './node-server.js';
@@ -114,7 +115,9 @@ const SERVED_OPERATIONS = new Set([
     'slotlock_get_free_busy',
     'slotlock_find_next_available',
     'slotlock_find_available_slots',
+    'slotlock_find_available_ranges',
     'slotlock_hold_slots',
+    'slotlock_hold_together',
     'slotlock_release_slots',
     'slotlock_book_together',
     'slotlock_book_pool',
@@ -929,6 +932,8 @@ export async function startSlotlockServer(config, log) {
                             maxTenantResources: SERVE_MAX_TENANT_RESOURCES,
                             // A granted approval's booking is made as an agent's would be (RFC 0004 A4).
                             agentBackend,
+                            // Holiday calendars by URL (RFC 0004 B1), never from a private address.
+                            holidayFetch: createSlotlockGuardedFetch(),
                             partners: createSlotlockPartnerStore(sql, {
                                 keys: createSlotlockApiKeyStore(sql),
                                 eraseTenant: (tenantRef) => store.eraseTenant({ tenantRef }),
@@ -975,7 +980,8 @@ export async function startSlotlockServer(config, log) {
                     : {}),
                 ...(config.dashboard.organizations === 'enabled' ? { teams: createSlotlockDashboardTeams(sql) } : {}),
                 keys: createSlotlockApiKeyStore(sql),
-                resources: createSlotlockDashboardResources(store, { agentBackend }),
+                // Holiday calendars by address (RFC 0004 B1), never from a private address.
+                resources: createSlotlockDashboardResources(store, { agentBackend, holidayFetch: createSlotlockGuardedFetch() }),
                 state: createSlotlockDashboardState(sql),
                 availability: config.availability,
                 ...(config.usage ? { usage: true } : {}),
@@ -1037,6 +1043,8 @@ export async function startSlotlockServer(config, log) {
           SELECT slotlock.maintenance_tenants(${after}::text) AS tenant`),
             intervalMs: SERVE_MAINTENANCE_INTERVAL_MS,
             ...(config.usage ? { usage: true } : {}),
+            // Holiday calendar subscriptions (RFC 0004 B1), never from a private address.
+            holidayFetch: createSlotlockGuardedFetch(),
             // Counts only, never the tenant.
             onPass: (result) => {
                 metrics?.maintenance(result);
@@ -1250,8 +1258,116 @@ function hoursLine(resource) {
         external_ref: resource.externalRef,
         timezone: resource.timezone,
         hours: resource.availabilityRules ?? null,
+        inherited: resource.inheritedAvailability ?? null,
     })}\n`;
 }
+/**
+ * `closures list|add|delete|import` (RFC 0004 B1): the tenant's closures and special days. Exit 0, 1
+ * when a name, id or file is not found or refused, as JSON lines on stdout.
+ */
+async function runClosures(config, io, subcommand, operands, given) {
+    const sql = connect(config.databaseUrl, 1);
+    const fail = (message) => {
+        io.stderr.write(`slotlock: ${message}\n`);
+        return 1;
+    };
+    try {
+        const store = createSlotlockStore(sql);
+        const tenantRef = config.tenantRef;
+        const line = (exception) => io.stdout.write(`${JSON.stringify({
+            id: exception.id,
+            location: exception.location ?? null,
+            resource_id: exception.resourceId ?? null,
+            starts_on: exception.startsOn,
+            ends_on: exception.endsOn,
+            outcome: exception.outcome,
+            hours: exception.hours ?? null,
+            label: exception.label,
+            source: exception.source,
+        })}\n`);
+        let scope = {};
+        if (given.location !== undefined)
+            scope = { location: given.location };
+        if (given.resource !== undefined) {
+            const resources = await tenantResources(store, tenantRef);
+            const named = resources.find((resource) => resource.id === given.resource) ??
+                resources.find((resource) => resource.externalRef === given.resource);
+            if (!named)
+                return fail('no resource with that reference or id in this tenant');
+            scope = { resourceId: named.id };
+        }
+        try {
+            if (subcommand === 'closures list') {
+                const exceptions = await store.withTenant(tenantRef, (tenant) => tenant.listAvailabilityExceptions({
+                    tenantRef,
+                    from: new Date(Date.now() - 86_400_000).toISOString().slice(0, 10),
+                    limit: 1_000,
+                }));
+                for (const exception of exceptions)
+                    line(exception);
+                return 0;
+            }
+            if (subcommand === 'closures delete') {
+                const deleted = await store.withTenant(tenantRef, (tenant) => tenant.deleteAvailabilityException({ tenantRef, id: operands[0] }));
+                if (!deleted)
+                    return fail('no closure with that id in this tenant');
+                io.stdout.write(`${JSON.stringify({ deleted: true })}\n`);
+                return 0;
+            }
+            if (subcommand === 'closures add') {
+                let hours;
+                if (given.open !== undefined) {
+                    const match = /^(\d{2}):(\d{2})-(\d{2}):(\d{2})$/.exec(given.open);
+                    if (!match)
+                        return fail('--open takes HH:MM-HH:MM, like 10:00-14:00');
+                    const [opens, closes] = [Number(match[1]) * 60 + Number(match[2]), Number(match[3]) * 60 + Number(match[4])];
+                    hours = [{ startMinutes: opens, durationMinutes: closes > opens ? closes - opens : closes + 1_440 - opens }];
+                }
+                const exception = await store.withTenant(tenantRef, (tenant) => tenant.createAvailabilityException({
+                    tenantRef,
+                    ...scope,
+                    startsOn: operands[0],
+                    ...(operands[1] !== undefined ? { endsOn: operands[1] } : {}),
+                    outcome: hours ? 'open' : 'closed',
+                    ...(hours ? { hours } : {}),
+                    label: given.label ?? '',
+                }));
+                line(exception);
+                return 0;
+            }
+            // closures import <file> [--label <calendar name>]
+            let text;
+            try {
+                text = await readFile(operands[0], 'utf8');
+            }
+            catch {
+                return fail('that file cannot be read');
+            }
+            const read = await readSlotlockHolidayCalendar({
+                icalendar: text,
+                ...(given.label !== undefined ? { name: given.label } : {}),
+            });
+            const result = await store.withTenant(tenantRef, (tenant) => tenant.importHolidayCalendar({ tenantRef, ...scope, name: read.name, holidays: read.holidays, span: read.span }));
+            io.stdout.write(`${JSON.stringify({ imported: result.imported, removed: result.removed, skipped: read.skipped, calendar: result.calendar.name })}\n`);
+            return 0;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'invalid_availability_exception' ||
+                code === 'invalid_holiday_calendar' ||
+                code === 'location_not_found' ||
+                code === 'resource_not_found' ||
+                code === 'availability_exceptions_limit_reached' ||
+                code === 'holiday_calendars_limit_reached') {
+                return fail(error.message);
+            }
+            throw error;
+        }
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
 /** Every resource of the tenant in use (with `includeArchived`, every one), a page at a time. */
 async function tenantResources(store, tenantRef, includeArchived = false) {
     const all = [];
@@ -1273,14 +1389,22 @@ async function tenantResources(store, tenantRef, includeArchived = false) {
  * `hours show|set|clear`: print, set or clear (`rules` null) the hours of the tenant's resource
  * named by reference or id, or of every resource. Returns false when no resource has that name.
  */
-async function runHours(config, out, target, rules) {
+async function runHours(config, out, target, rules, override = 'none') {
     const sql = connect(config.databaseUrl, 1);
     try {
         const store = createSlotlockStore(sql);
         const tenantRef = config.tenantRef;
         if (target === 'all') {
-            const updated = await store.withTenant(tenantRef, (tenant) => tenant.setTenantAvailability({ tenantRef, rules: rules ?? null }));
-            out.write(`${JSON.stringify({ updated })}\n`);
+            // The tenant's hours, which every resource without its own inherits (RFC 0004 B2).
+            const result = await store.withTenant(tenantRef, (tenant) => tenant.storeTenantAvailability({ tenantRef, rules: rules ?? null, overrideResources: override }));
+            out.write(`${JSON.stringify({ inheriting: result.inheriting, own_hours: result.ownHours })}\n`);
+            return true;
+        }
+        if (typeof target === 'object' && 'location' in target) {
+            const result = await store.withTenant(tenantRef, (tenant) => tenant.setLocationAvailability({ tenantRef, location: target.location, rules: rules ?? null }));
+            if (!result)
+                return false;
+            out.write(`${JSON.stringify({ location: target.location, inheriting: result.inheriting, own_hours: result.ownHours })}\n`);
             return true;
         }
         const resources = await tenantResources(store, tenantRef);
@@ -1298,6 +1422,8 @@ async function runHours(config, out, target, rules) {
             out.write(hoursLine(named));
             return true;
         }
+        if (!('resource' in target))
+            return false;
         const updated = await store.withTenant(tenantRef, (tenant) => tenant.setResourceAvailability({ tenantRef, id: named.id, rules }));
         if (!updated)
             return false;
@@ -1780,11 +1906,16 @@ async function maintainTenant(config, caps) {
                 noShows: 0,
                 waitlistOffers: 0,
                 approvalsExpired: 0,
+                bookingsCompleted: 0,
+                remindersDue: 0,
+                holidayCalendarsImported: 0,
                 capped: true,
                 passes: 0,
             };
+            // Holiday calendar subscriptions by URL (RFC 0004 B1), never from a private address.
+            const holidayFetch = createSlotlockGuardedFetch();
             while (sum.capped && sum.passes < MAINTAIN_MAX_PASSES) {
-                const pass = await maintainSlotlockTenant(store, config.tenantRef);
+                const pass = await maintainSlotlockTenant(store, config.tenantRef, { holidayFetch });
                 sum.passes += 1;
                 sum.extended += pass.extended;
                 sum.conflicts += pass.conflicts;
@@ -1795,6 +1926,9 @@ async function maintainTenant(config, caps) {
                 sum.noShows += pass.noShows;
                 sum.waitlistOffers += pass.waitlistOffers;
                 sum.approvalsExpired += pass.approvalsExpired;
+                sum.bookingsCompleted += pass.bookingsCompleted;
+                sum.remindersDue += pass.remindersDue;
+                sum.holidayCalendarsImported += pass.holidayCalendarsImported;
                 // A capped pass that got nowhere met only series it cannot extend. While its roll stopped
                 // before the series it had put back, the next pass meets new ones (and perhaps a healthy
                 // one); once it reached them, another pass would meet them again.
@@ -1872,11 +2006,26 @@ Commands:
   resource delete <ref>    Delete a resource and its history; refused while a booking, hold
                            or event on it has not ended
   hours show [--resource <ref>]
-                           Print each resource's bookable hours (null: the server's)
-  hours set <json> (--resource <ref> | --all)
-                           Give one resource, or every one, weekly hours of its own; [] closes
-  hours clear (--resource <ref> | --all)
-                           Hand one resource, or every one, back to the server's hours
+                           Print each resource's bookable hours: its own (null when none) and
+                           what it inherits from its location or the tenant
+  hours set <json> (--resource <ref> | --location <ref> | --all [--override | --matching])
+                           Give one resource, one location or the tenant weekly hours; a
+                           resource without its own inherits its location's, then the
+                           tenant's, then the server's; --override also clears resources'
+                           own hours, --matching only those the same as the tenant's were
+                           or as these (copies 0.8.0 made); [] closes
+  hours clear (--resource <ref> | --location <ref> | --all)
+                           Clear those hours, so they inherit from further up
+  closures list            Print the tenant's closures and special days from yesterday on
+  closures add <first-day> [<last-day>] --label <text> [--open HH:MM-HH:MM]
+               [--resource <ref> | --location <ref>]
+                           Close whole days (YYYY-MM-DD), or with --open give them those hours
+                           instead, everywhere or for one location or resource
+  closures delete <id>     Remove a closure
+  closures import <file> [--resource <ref> | --location <ref>] [--label <calendar name>]
+                           Close the days an iCalendar file of holidays names (each all-day
+                           event, for the next two years); importing the calendar again (by its
+                           name: --label, else its own) updates them and removes those it dropped
   rules set <json> --resource <ref>
                            Set what a booking on the resource must satisfy, like
                            {"minNoticeMinutes":120,"slotStepMinutes":30,"turnaroundMinutes":30,"enforceHours":true}
@@ -2096,6 +2245,7 @@ export async function runSlotlockCli(argv, io) {
     const subcommand = command === 'resource' ||
         command === 'key' ||
         command === 'hours' ||
+        command === 'closures' ||
         command === 'rules' ||
         command === 'tenant' ||
         command === 'plan' ||
@@ -2134,6 +2284,10 @@ export async function runSlotlockCli(argv, io) {
         'hours show': 1,
         'hours set': 2,
         'hours clear': 1,
+        'closures list': 1,
+        'closures add': 2,
+        'closures delete': 2,
+        'closures import': 2,
         'rules set': 2,
         'rules clear': 1,
         'partner create': 3,
@@ -2148,7 +2302,8 @@ export async function runSlotlockCli(argv, io) {
         'overage report': 1,
         'billing daily': 1,
     };
-    const expected = expectedOperands[subcommand];
+    // closures add takes a last day or not.
+    const expected = subcommand === 'closures add' && operands.length === 3 ? 3 : expectedOperands[subcommand];
     if (expected === undefined)
         return usage(`unknown command "${subcommand}"`);
     if (operands.length !== expected)
@@ -2208,10 +2363,32 @@ export async function runSlotlockCli(argv, io) {
     if (values.all && subcommand !== 'hours set' && subcommand !== 'hours clear') {
         return usage('--all applies only to hours set and hours clear');
     }
+    if (values.override && subcommand !== 'hours set')
+        return usage('--override applies only to hours set --all');
+    if (values.matching && subcommand !== 'hours set')
+        return usage('--matching applies only to hours set --all');
+    if (values.override && values.matching)
+        return usage('--override and --matching: give one');
     if (values.resource !== undefined &&
         !subcommand.startsWith('hours ') &&
-        !subcommand.startsWith('rules ')) {
-        return usage('--resource applies only to hours and rules commands');
+        !subcommand.startsWith('rules ') &&
+        !subcommand.startsWith('closures ')) {
+        return usage('--resource applies only to hours, closures and rules commands');
+    }
+    if (values.location !== undefined && !subcommand.startsWith('hours ') && !subcommand.startsWith('closures ')) {
+        return usage('--location applies only to hours and closures commands');
+    }
+    if (values.label !== undefined && subcommand !== 'closures add' && subcommand !== 'closures import') {
+        return usage('--label applies only to closures add and closures import');
+    }
+    if (values.open !== undefined && subcommand !== 'closures add') {
+        return usage('--open applies only to closures add');
+    }
+    if (subcommand.startsWith('closures ') && values.resource !== undefined && values.location !== undefined) {
+        return usage(`${subcommand} takes --resource or --location, not both`);
+    }
+    if (subcommand === 'closures add' && (operands.length < 2 || operands.length > 3 || values.label === undefined)) {
+        return usage('closures add needs <first-day> [<last-day>] --label <text>');
     }
     if (subcommand.startsWith('rules ') && values.resource === undefined) {
         return usage(`${subcommand} needs --resource <ref>`);
@@ -2228,9 +2405,13 @@ export async function runSlotlockCli(argv, io) {
         }
     }
     if ((subcommand === 'hours set' || subcommand === 'hours clear') &&
-        (values.resource === undefined) === (values.all !== true)) {
-        return usage(`${subcommand} needs --resource <ref> or --all, one of them`);
+        [values.resource !== undefined, values.location !== undefined, values.all === true].filter(Boolean).length !== 1) {
+        return usage(`${subcommand} needs --resource <ref>, --location <ref> or --all, one of them`);
     }
+    if (values.override && values.all !== true)
+        return usage('--override applies only to hours set --all');
+    if (values.matching && values.all !== true)
+        return usage('--matching applies only to hours set --all');
     let hours = null;
     if (subcommand === 'hours set') {
         let candidate;
@@ -2484,16 +2665,30 @@ export async function runSlotlockCli(argv, io) {
             case 'hours clear': {
                 const target = values.all === true
                     ? 'all'
-                    : values.resource !== undefined
-                        ? { resource: values.resource }
-                        : 'show';
-                const found = await runHours(readSlotlockDatabaseConfig(io.env), io.stdout, target, subcommand === 'hours show' ? undefined : hours);
+                    : values.location !== undefined
+                        ? { location: values.location }
+                        : values.resource !== undefined
+                            ? { resource: values.resource }
+                            : 'show';
+                const found = await runHours(readSlotlockDatabaseConfig(io.env), io.stdout, target, subcommand === 'hours show' ? undefined : hours, values.override === true ? 'all' : values.matching === true ? 'matching' : 'none');
                 if (!found) {
-                    io.stderr.write('slotlock: no resource with that reference or id in this tenant\n');
+                    io.stderr.write(values.location !== undefined
+                        ? 'slotlock: no location with that reference in this tenant\n'
+                        : 'slotlock: no resource with that reference or id in this tenant\n');
                     return 1;
                 }
                 return 0;
             }
+            case 'closures list':
+            case 'closures add':
+            case 'closures delete':
+            case 'closures import':
+                return runClosures(readSlotlockDatabaseConfig(io.env), io, subcommand, operands.slice(1), {
+                    ...(values.resource !== undefined ? { resource: values.resource } : {}),
+                    ...(values.location !== undefined ? { location: values.location } : {}),
+                    ...(values.label !== undefined ? { label: values.label } : {}),
+                    ...(values.open !== undefined ? { open: values.open } : {}),
+                });
             case 'rules set':
             case 'rules clear': {
                 const found = await runRules(readSlotlockDatabaseConfig(io.env), io.stdout, values.resource, bookingRules);
@@ -2594,7 +2789,12 @@ function parseCliArguments(argv) {
             month: { type: 'string' },
             event: { type: 'string' },
             resource: { type: 'string' },
+            location: { type: 'string' },
             all: { type: 'boolean' },
+            override: { type: 'boolean' },
+            matching: { type: 'boolean' },
+            label: { type: 'string' },
+            open: { type: 'string' },
             reason: { type: 'string' },
             confirm: { type: 'string' },
             from: { type: 'string' },

package/slotlock.manifest.json

@@ -3,7 +3,7 @@
   "schemaVersion": "1.0",
   "name": "Slotlock",
   "package": "slotlock",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Resource-first, deterministic calendar and availability engine for AI agents.",
   "intervalSemantics": {
     "boundary": "[)",