slotlock 0.3.0 → 0.5.0

package/store.d.ts

@@ -1,6 +1,8 @@
+import { type SlotlockEventFeed } from './event-feed.js';
+import { type SlotlockBookingRules } from './booking-rules.js';
 import type { Sql, TransactionSql } from 'postgres';
 import { SLOTLOCK_CALENDAR_HORIZON_DAYS } from './rules.js';
-import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockHold, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
+import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockAgendaEntry, SlotlockHold, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
 export { SLOTLOCK_CALENDAR_HORIZON_DAYS };
 /**
  * Longest one-off event the store accepts (ten years and some leap days): long enough for any lease
@@ -16,6 +18,14 @@ export declare const SLOTLOCK_MAX_EVENT_DURATION_DAYS = 3660;
 export declare const SLOTLOCK_MATERIALIZATION_WINDOW_DAYS: number;
 /** Trusted provider/maintenance namespace used by backwards-compatible store callers. */
 export declare const SLOTLOCK_INTERNAL_EVENT_OWNER_REF = "internal";
+/** How many live holds one holder (a keyed hold's principal) may have in a tenant at once. */
+export declare const SLOTLOCK_MAX_HOLDS_PER_HOLDER = 20;
+/** Windows one holder may wait for at once (joinWaitlist). */
+export declare const SLOTLOCK_MAX_WAITLIST_PER_HOLDER = 20;
+/** Waiting entries one tenant may have. */
+export declare const SLOTLOCK_MAX_WAITLIST_PER_TENANT = 10000;
+/** How long before its start a booking may be checked in. */
+export declare const SLOTLOCK_CHECK_IN_OPENS_MINUTES = 60;
 /** Default hard ceiling for retained active + tombstoned identities per agent principal. */
 export declare const SLOTLOCK_AGENT_OWNER_EVENT_QUOTA = 1000;
 /** Hard retained command ceiling; includes reserved cancellation capacity for every identity. */
@@ -60,7 +70,28 @@ export declare function readSlotlockSchemaVersion(sql: SlotlockSql): Promise<num
  * migrated it, whose schema this release's code does not know. Both carry `installed` and `expected`.
  */
 export declare function assertSlotlockSchemaCurrent(sql: SlotlockSql): Promise<void>;
-export interface SlotlockStore {
+/**
+ * What makes a put the same request: its identity and the event it asks for. Not the window its
+ * occurrences are stored over, which for a series is the rolling horizon from the current UTC
+ * midnight: with it in the hash, a retry after midnight was refused as a different request.
+ */
+declare function putCommandHash(params: {
+    command: PutCalendarEventCommand;
+    ownerRef: string;
+    event: CalendarEventContent;
+}): string;
+/**
+ * The hash 0.3.0 and earlier stored, with the window in it, so a command stored before the upgrade
+ * still replays: always for a one-off event, whose window is its own span, and on the same UTC day
+ * for a series. Remove once no stored command can be that old (commands are pruned after 30 days).
+ */
+export declare function legacyPutCommandHash(params: Parameters<typeof putCommandHash>[0] & {
+    window: Interval;
+}): string;
+/** Members a pool booking or search considers at most, in id order. */
+export declare const SLOTLOCK_MAX_POOL_MEMBERS = 100;
+export declare function isPoolName(value: unknown): value is string;
+export interface SlotlockStore extends SlotlockEventFeed {
     /**
      * Apply the Slotlock DDL (idempotent). Owns the `slotlock` schema on the connected DB. Refuses
      * (`unsafe_slotlock_schema`, with the `reasons` found) a `slotlock` schema that a role other than the
@@ -112,6 +143,11 @@ export interface SlotlockStore {
     withTenant<T>(tenantRef: string, callback: (store: SlotlockTenantStore) => Promise<T>, options?: {
         isolation?: 'read committed';
         signal?: AbortSignal;
+        /**
+         * Who is making these changes (an API key's id, an agent's subject), 1-200 characters
+         * without control characters: the history (listHistory) records it with each change.
+         */
+        actor?: string;
     }): Promise<T>;
     /**
      * INVARIANT (erasure completeness): a tenant integration must use a stable, erasable business
@@ -181,6 +217,44 @@ export interface SlotlockStore {
         id: string;
         rules: readonly WeeklyAvailabilityRule[] | null;
     }): Promise<SlotlockResource | null>;
+    /**
+     * Set one resource's booking rules (`SlotlockBookingRules`), or clear them (`null`). They apply to
+     * bookings made from then on: holds, reservations, moves, and events written with
+     * `enforceBookingRules`. Null for an id that is not the tenant's. Refuses rules outside their
+     * bounds (`invalid_booking_rules`).
+     */
+    setResourceBookingRules(params: {
+        tenantRef: string;
+        id: string;
+        rules: SlotlockBookingRules | null;
+    }): Promise<SlotlockResource | null>;
+    /**
+     * Put one resource in a pool, or take it out (`null`): `pool` is 1-100 characters of a-z, 0-9,
+     * `.`, `_` and `-`, starting with a letter or digit (`invalid_pool` otherwise). A resource is in
+     * one pool at most. Null for an id that is not the tenant's.
+     */
+    setResourcePool(params: {
+        tenantRef: string;
+        id: string;
+        pool: string | null;
+    }): Promise<SlotlockResource | null>;
+    /**
+     * The members of one of the tenant's pools that may be booked, in the order a pool booking tries
+     * them (by id): archived ones left out, and with `visibility: 'shared'` private ones too.
+     */
+    listPoolMembers(params: {
+        tenantRef: string;
+        pool: string;
+        visibility?: 'shared';
+    }): Promise<SlotlockResource[]>;
+    /** The tenant's pools by name, with how many members each has that may be booked (its capacity). */
+    listPools(params: {
+        tenantRef: string;
+        visibility?: 'shared';
+    }): Promise<{
+        pool: string;
+        capacity: number;
+    }[]>;
     /** Set (or clear, with `null`) the bookable hours of every resource the tenant has; returns how many. */
     setTenantAvailability(params: {
         tenantRef: string;
@@ -228,7 +302,8 @@ export interface SlotlockStore {
     }): Promise<CancelExternalReservationResult>;
     /**
      * Occupy a window WITHOUT committing: the hold blocks rivals under the same EXCLUDE arbiter
-     * until `expiresAt` (DB clock — now() + ttl, never the app clock), then frees via lazy reap.
+     * until `expiresAt` (DB clock — the statement's time + ttl, never the app clock), then frees via
+     * lazy reap.
      * With `tenantRef`, only a resource of that tenant (`resource_not_found` otherwise, whatever the
      * connection's row-level security).
      */
@@ -251,6 +326,19 @@ export interface SlotlockStore {
         idempotencyKey?: string;
         /** Whose keys `idempotencyKey` is among, 1-500 UTF-8 bytes (an API key's subject, say). */
         principalRef?: string;
+        /**
+         * Who the hold belongs to, 1-500 UTF-8 bytes, inside `tenantRef` (required with it): an agent
+         * acting for one person, say. `releaseHold` and `putCalendarEvent`'s `fromHold` with a
+         * `holderRef` take only their own, and a holder may have `maxHoldsPerHolder` (20) live at once,
+         * holding at most `maxHeldHoursPerHolder` together when that is set. Without it the hold has no
+         * holder and no cap: an application holding for its customers.
+         */
+        holderRef?: string;
+        /**
+         * Holds taken as alternatives for one booking share a group (a UUID): booking one with
+         * `fromHold` releases the rest, and releasing one with a holder releases them all.
+         */
+        groupId?: string;
     }): Promise<AcquireHoldResult>;
     /** One of the tenant's live holds, or null (none, expired, confirmed, or another tenant's). */
     getHold(params: {
@@ -267,6 +355,17 @@ export interface SlotlockStore {
             id: string;
         };
     }): Promise<SlotlockHold[]>;
+    /**
+     * What occupies the tenant's resources in `window` (at most 367 days), every resource at once, by
+     * start then id: bookings, calendar events' occurrences and live holds, up to `limit` (1-1000,
+     * default 100). An agenda for people to read; listReservations, listCalendarEvents and listHolds
+     * page through each.
+     */
+    listAgenda(params: {
+        tenantRef: string;
+        window: Interval;
+        limit?: number;
+    }): Promise<SlotlockAgendaEntry[]>;
     /**
      * The tenant's booking with this reference as it now is (its current revision), or null: none,
      * cancelled, or a calendar event's occupation, which is not a booking.
@@ -302,7 +401,13 @@ export interface SlotlockStore {
      * Delete a live hold; released=false when it was already gone (expired-reaped or confirmed). With
      * `tenantRef`, only a hold on one of that tenant's resources, as for confirmHold.
      */
-    releaseHold(holdId: string, options?: SlotlockHoldTenantOptions): Promise<ReleaseHoldResult>;
+    releaseHold(holdId: string, options?: SlotlockHoldTenantOptions & {
+        /**
+         * Only a hold this holder took (`acquireHold`'s `holderRef`), with the rest of its group:
+         * released=false for another holder's.
+         */
+        holderRef?: string;
+    }): Promise<ReleaseHoldResult>;
     /**
      * Reservations overlapping `window` for one resource, as merged-ready half-open intervals. With
      * `tenantRef`, only a resource of that tenant (`resource_not_found` otherwise, whatever the
@@ -405,7 +510,7 @@ export interface SlotlockStore {
         tenantRef: string;
         /** Rows per class per call, 1-1000. Defaults to 100. */
         limit?: number;
-        /** Replay window in whole days, 1-3650. Defaults to `SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS`. */
+        /** Replay window in whole days, 1-3650. Defaults to the store's `retentionDays`, at least 30. */
         retentionDays?: number;
     }): Promise<CalendarEventRetentionResult>;
     /**
@@ -417,13 +522,149 @@ export interface SlotlockStore {
      * tenant the tenant and its own id as reference, as the migration does. Call until `hasMore` is
      * false.
      */
+    /**
+     * Time zone rules that changed since an event was booked (a new tzdata): a future one-off event
+     * whose wall-clock time in its zone now falls at another instant. Each is reported once on the
+     * feed (`event.timezone_shifted`, with the instant it has and the one its wall time now means).
+     * With `move`, it is moved there instead (a new revision, `event.updated` naming `slotlock:tzdata`),
+     * unless that overlaps another booking: then it stays and `event.timezone_conflict` reports it,
+     * for a person or an agent to decide. Up to `limit` (1-1,000, default 100) events a call.
+     */
+    followZoneRules(params: {
+        tenantRef: string;
+        move?: boolean;
+        limit?: number;
+    }): Promise<{
+        shifted: number;
+        moved: number;
+        conflicts: number;
+    }>;
+    /**
+     * A source failed to read (a feed answered 500, a token expired): kept as its last error, at most
+     * 500 characters, beside its coverage, which stays as it was. `coverage_not_found` for a source
+     * that has never recorded coverage on the resource.
+     */
+    recordCoverageFailure(params: {
+        tenantRef: string;
+        resourceId: string;
+        source: string;
+        error: string;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        code: 'coverage_not_found' | 'invalid_identity';
+    }>;
+    /**
+     * Retire a source (a sync disconnected or replaced): its coverage of the resource is forgotten, so
+     * free/busy and the booking rule `requireCertain` stop waiting on it. False when there was none.
+     */
+    deleteCoverage(params: {
+        tenantRef: string;
+        resourceId: string;
+        source: string;
+    }): Promise<boolean>;
+    /**
+     * Each source's coverage of one resource and how healthy it is: when it was last read, its last
+     * error, and whether it is `stale` (not read for `maxAgeMs`, default a day, as free/busy judges).
+     */
+    listCoverage(params: {
+        tenantRef: string;
+        resourceId: string;
+        maxAgeMs?: number;
+    }): Promise<SlotlockCoverageHealth[]>;
+    /**
+     * Put each source that has gone stale (not read for `maxAgeMs`, default a day) on the feed once
+     * (`coverage.stale`), until it is read again. Up to `limit` (default 100); how many.
+     */
+    reportStaleCoverage(params: {
+        tenantRef: string;
+        maxAgeMs?: number;
+        limit?: number;
+    }): Promise<number>;
+    /**
+     * Claim a booking by its reference (check-in), so a resource whose booking rules ask for check-in
+     * (`checkInMinutes`) does not release it. Check-in opens `SLOTLOCK_CHECK_IN_OPENS_MINUTES` before
+     * the start (`check_in_not_open` sooner), and a move to another start clears it. Checking in again
+     * keeps the first time. Refused once the booking has ended (`reservation_ended`); a reference with
+     * no live booking is `reservation_not_found`. The feed says so (`reservation.checked_in`).
+     */
+    checkInReservation(params: {
+        tenantRef: string;
+        externalRef: string;
+    }): Promise<CheckInReservationResult>;
+    /**
+     * Release up to `limit` (default 100) bookings left unclaimed: on a resource whose booking rules
+     * ask for check-in, made since they did, not checked in `checkInMinutes` after the start, and not
+     * yet ended. Each is cancelled as `cancelExternalReservation` would (its reference retired at the
+     * next revision) and the feed says why (`reservation.no_show`). How many.
+     */
+    releaseNoShows(params: {
+        tenantRef: string;
+        limit?: number;
+    }): Promise<number>;
+    /**
+     * Wait for a window on one resource (`resourceId`) or any member of a pool (`pool`): when it comes
+     * free, `offerWaitlist` holds it for `holderRef` for `offerTtlMs` (1 minute to a day, default 15
+     * minutes), first come first offered. A holder may wait for `SLOTLOCK_MAX_WAITLIST_PER_HOLDER`
+     * windows at once and a tenant `SLOTLOCK_MAX_WAITLIST_PER_TENANT`.
+     */
+    joinWaitlist(params: {
+        tenantRef: string;
+        resourceId?: string;
+        pool?: string;
+        start: Date;
+        end: Date;
+        holderRef: string;
+        offerTtlMs?: number;
+    }): Promise<JoinWaitlistResult>;
+    /** The tenant's waitlist entries, oldest first, optionally of one resource, pool or holder. */
+    listWaitlist(params: {
+        tenantRef: string;
+        resourceId?: string;
+        pool?: string;
+        holderRef?: string;
+        limit?: number;
+    }): Promise<SlotlockWaitlistEntry[]>;
+    /**
+     * Stop waiting; with `holderRef`, only that holder's entry. A hold offered and not yet confirmed is
+     * released with it. False when there was none.
+     */
+    leaveWaitlist(params: {
+        tenantRef: string;
+        id: string;
+        holderRef?: string;
+    }): Promise<boolean>;
+    /**
+     * Offer freed time to the waitlist, in the order entries joined: each waiting entry whose window
+     * is free (on its resource, or on the first free member of its pool) gets a hold for its holder
+     * and the feed says so (`waitlist.offered`, with the hold). Entries whose window has started are
+     * expired (`waitlist.expired`); finished ones older than the change feed's retention are deleted.
+     * One tenant's offers run one at a time. One page of `limit` (1-100, default 50) entries: pass
+     * `next` back as `after` for the next, until it is null.
+     */
+    offerWaitlist(params: {
+        tenantRef: string;
+        limit?: number;
+        after?: {
+            createdAt: Date;
+            id: string;
+        };
+    }): Promise<{
+        offered: number;
+        expired: number;
+        next: {
+            createdAt: Date;
+            id: string;
+        } | null;
+    }>;
     pruneBookingRetention(params: {
         tenantRef: string;
         /** Rows per class per call, 1-1000. Defaults to 100. */
         limit?: number;
         /**
-         * How long a stray retirement is kept, in whole days, 1-3650. Defaults to
-         * `SLOTLOCK_EVENT_COMMAND_RETENTION_DAYS`.
+         * How long a stray retirement is kept, in whole days, 1-3650. Defaults to the store's
+         * `retentionDays`, at least 30.
          */
         retentionDays?: number;
     }): Promise<BookingRetentionResult>;
@@ -494,10 +735,60 @@ export interface SlotlockStore {
         coverageMaxAgeMs?: number;
     }): Promise<Interval | null>;
 }
+/** One entry of a tenant's waitlist (joinWaitlist). */
+export interface SlotlockWaitlistEntry {
+    id: string;
+    /** The resource it waits on, or null when it waits on a pool. */
+    resourceId: string | null;
+    pool: string | null;
+    start: Date;
+    end: Date;
+    holderRef: string;
+    offerTtlMs: number;
+    /** `waiting`, `offered` (a hold was made: `holdId` on `offeredResourceId`) or `expired`. */
+    status: 'waiting' | 'offered' | 'expired';
+    holdId: string | null;
+    offeredResourceId: string | null;
+    offeredAt: Date | null;
+    createdAt: Date;
+}
+export type JoinWaitlistResult = {
+    ok: true;
+    entry: SlotlockWaitlistEntry;
+} | {
+    ok: false;
+    code: 'invalid_identity' | 'invalid_window' | 'invalid_ttl' | 'invalid_pool' | 'resource_not_found' | 'resource_archived' | 'pool_not_found' | 'waitlist_limit_reached';
+};
+export type CheckInReservationResult = {
+    ok: true;
+    reference: string;
+    checkedInAt: Date;
+} | {
+    ok: false;
+    code: 'invalid_identity' | 'reservation_not_found' | 'reservation_ended' | 'check_in_not_open';
+};
+/** One source's coverage of a resource, with its health (listCoverage). */
+export interface SlotlockCoverageHealth {
+    source: string;
+    start: Date;
+    end: Date;
+    revision: number;
+    /** When it was last read. */
+    observedAt: Date;
+    lastError: string | null;
+    lastErrorAt: Date | null;
+    /** Not read for longer than free/busy trusts: time it covers is unproven, not free. */
+    stale: boolean;
+}
 export type SlotlockTenantStore = Omit<SlotlockStore, 'applySchema' | 'applyTenantRls' | 'grantApplicationRole' | 'withTenant'>;
 export interface SlotlockStoreOptions {
     /** Namespaced PostgreSQL setting installed by applyTenantRls. Defaults to `slotlock.tenant_ref`. */
     tenantContextSetting?: string;
+    /**
+     * The bookable hours of a resource without its own, where its booking rules enforce hours
+     * (`enforceHours`). None by default: such a resource is then never bookable.
+     */
+    defaultAvailabilityRules?: readonly WeeklyAvailabilityRule[];
     /** Hard active + tombstone identity ceiling per non-internal owner. Defaults to 1,000. */
     agentOwnerEventQuota?: number;
     /** Hard retained-command ceiling per non-internal owner. Defaults to 10,000; cannot be disabled. */
@@ -525,6 +816,24 @@ export interface SlotlockStoreOptions {
      * to retry. Not set inside a caller's transaction.
      */
     tenantLockTimeoutMs?: number;
+    /**
+     * How many days history is kept, 1-3,650 (default 30): the change feed (and how far back a cursor
+     * reaches) and waitlist entries that ended; and, when longer than 30 days, retired idempotency
+     * answers, booking references and past events' commands (never shorter, so a delayed retry is still
+     * answered as the first try was). Maintenance prunes what is older. A cursor before a change any
+     * store has pruned answers `cursor_expired`, so stores set differently never skip a change.
+     */
+    retentionDays?: number;
+    /**
+     * Live holds one holder (`acquireHold`'s `holderRef`) may have at once, 1-10,000. Defaults to
+     * SLOTLOCK_MAX_HOLDS_PER_HOLDER (20).
+     */
+    maxHoldsPerHolder?: number;
+    /**
+     * Hours one holder's live holds may hold together, 1-876,000 (none by default): past it a hold is
+     * refused with `held_time_limit_reached`, however few holds it has.
+     */
+    maxHeldHoursPerHolder?: number;
 }
 /** Per-tenant row limits, each a whole number from 1 to 10,000,000 (resources: to 100,000). */
 export interface SlotlockTenantLimits {
@@ -565,4 +874,4 @@ export declare function createSlotlockStore(sql: StoreSql, options?: SlotlockSto
  * Every store method that writes for a tenant: what a suspended tenant's withTenant store refuses.
  * Maintenance (rolling series, pruning, purging) and erasure are not among them.
  */
-export declare const SLOTLOCK_TENANT_WRITE_METHODS: readonly ["createResource", "archiveResource", "restoreResource", "deleteResource", "setResourceAvailability", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage"];
+export declare const SLOTLOCK_TENANT_WRITE_METHODS: readonly ["createResource", "archiveResource", "restoreResource", "deleteResource", "setResourceAvailability", "setResourceBookingRules", "setResourcePool", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage", "createWebhookEndpoint", "deleteWebhookEndpoint", "enableWebhookEndpoint", "recordCoverageFailure", "deleteCoverage", "checkInReservation", "joinWaitlist", "leaveWaitlist"];