slotlock 0.2.0 → 0.5.0

package/types.d.ts

@@ -1,3 +1,4 @@
+import type { SlotlockBookingRule, SlotlockBookingRules } from './booking-rules.js';
 /** Half-open time interval `[start, end)`. */
 export interface Interval {
     start: Date;
@@ -21,14 +22,35 @@ export interface SlotlockResource {
      * uses the default (`SLOTLOCK_AVAILABILITY`, or the backend's `availabilityRules`).
      */
     availabilityRules?: WeeklyAvailabilityRule[];
+    /**
+     * `shared` resources are listed to agents and booked through them; `private` ones are invisible
+     * to agents and reached only by the tenant's own code. Fixed when the resource is created. The
+     * store always says which; a resource built elsewhere without it is shared.
+     */
+    visibility?: 'shared' | 'private';
+    /** When the tenant archived it: no longer listed or booked, its history kept. Absent in use. */
+    archivedAt?: Date;
+    /** What a booking on it must satisfy (`SlotlockBookingRules`). Absent when it has none. */
+    bookingRules?: SlotlockBookingRules;
+    /**
+     * The pool it belongs to: interchangeable resources sharing a name, such as a vehicle class or a
+     * room type, booked by the class (`slotlock_book_pool`). Absent when it is in none.
+     */
+    pool?: string;
 }
 /** A confirmed occupation of a resource. The DB EXCLUDE constraint is the overlap arbiter. */
 export interface SlotlockReservation {
     id: string;
     resourceId: string;
-    /** Null only for legacy, hold, and parity-shadow rows. */
+    /**
+     * Null only for live holds, rows on a resource that has no tenant (legacy), and parity-shadow rows.
+     * A booking made by confirming a hold, or by createReservation, on a tenant's resource has one.
+     */
     tenantRef: string | null;
-    /** Stable booking identity inside tenantRef; null for legacy, hold, and shadow rows. */
+    /**
+     * Stable booking identity inside tenantRef; null exactly when tenantRef is. A confirmed hold, and
+     * a createReservation booking, use their own id.
+     */
     externalRef: string | null;
     start: Date;
     end: Date;
@@ -82,6 +104,31 @@ export type ExternalReservationResult = {
 } | {
     ok: false;
     code: 'idempotency_conflict';
+}
+/** The resource is archived: it takes no new booking (cancel and release still work). */
+ | {
+    ok: false;
+    code: 'resource_archived';
+}
+/**
+ * A recurring event on the resource is not stored as far as this write reaches, and cannot be
+ * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
+ */
+ | {
+    ok: false;
+    code: 'recurrence_not_materialized';
+}
+/** The tenant's bookings and retired references are at its `reservations` limit. */
+ | {
+    ok: false;
+    code: 'reservation_limit_reached';
+    limit: number;
+}
+/** The booking breaks one of the resource's booking rules (`SlotlockResource.bookingRules`). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: SlotlockBookingRule;
 } | {
     ok: false;
     code: 'overlap';
@@ -106,6 +153,15 @@ export type CancelExternalReservationResult = {
 } | {
     ok: false;
     code: 'revision_conflict';
+}
+/**
+ * Retiring a reference no booking holds would add a row past the tenant's `reservations` limit
+ * (cancelling a booking it has never does).
+ */
+ | {
+    ok: false;
+    code: 'reservation_limit_reached';
+    limit: number;
 };
 /**
  * VAVAILABILITY-style bookable window (RFC 7953 semantics, weekly subset): a weekly-cadence RRULE
@@ -127,6 +183,36 @@ export type CreateReservationResult = {
 } | {
     ok: false;
     code: 'invalid_window';
+}
+/** No resource with that id, or (under tenant RLS or with `tenantRef`) not one of the tenant's. */
+ | {
+    ok: false;
+    code: 'resource_not_found';
+}
+/** The resource is archived: it takes no new booking (cancel and release still work). */
+ | {
+    ok: false;
+    code: 'resource_archived';
+}
+/**
+ * A recurring event on the resource is not stored as far as this write reaches, and cannot be
+ * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
+ */
+ | {
+    ok: false;
+    code: 'recurrence_not_materialized';
+}
+/** The booking's tenant is at its `reservations` limit. */
+ | {
+    ok: false;
+    code: 'reservation_limit_reached';
+    limit: number;
+}
+/** The booking breaks one of the resource's booking rules (`SlotlockResource.bookingRules`). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: SlotlockBookingRule;
 } | {
     ok: false;
     code: 'overlap';
@@ -138,18 +224,93 @@ export interface SlotlockHold {
     resourceId: string;
     start: Date;
     end: Date;
+    /** Turnaround kept busy after `end`; the booking the hold is confirmed into keeps it. */
+    bufferAfterMs: number;
     expiresAt: Date;
     source: string | null;
+    /** The alternatives it was held with (`groupId` when acquired); absent when held alone. */
+    groupId?: string;
+}
+/** One entry of a tenant's agenda (`listAgenda`): what occupies a resource, and from when. */
+export interface SlotlockAgendaEntry {
+    id: string;
+    resourceId: string;
+    start: Date;
+    end: Date;
+    /** A booking, a calendar event's occurrence, or a live hold. */
+    kind: 'booking' | 'event' | 'hold';
+    /** The booking's reference; null for an event's occurrence and a hold. */
+    reference: string | null;
+    /** The calendar event's summary; null for a booking and a hold. */
+    summary: string | null;
+    /** When the hold lapses; null for a booking and an event. */
+    expiresAt: Date | null;
+    source: string | null;
 }
-export type AcquireHoldResult = {
+export type AcquireHoldResult = 
+/** `idempotent`: a retry of a keyed hold, answered with the hold the first request made. */
+{
     ok: true;
     hold: SlotlockHold;
+    idempotent: boolean;
 } | {
     ok: false;
     code: 'invalid_window';
 } | {
     ok: false;
     code: 'invalid_ttl';
+} | {
+    ok: false;
+    code: 'invalid_buffer';
+}
+/** A tenant, principal or idempotency key that is malformed, or a key without both of the others. */
+ | {
+    ok: false;
+    code: 'invalid_identity';
+}
+/** No resource with that id, or (under tenant RLS or with `tenantRef`) not one of the tenant's. */
+ | {
+    ok: false;
+    code: 'resource_not_found';
+}
+/** The resource is archived: it takes no new booking (cancel and release still work). */
+ | {
+    ok: false;
+    code: 'resource_archived';
+}
+/** The idempotency key already made a hold with another resource, window, ttl, buffer or source. */
+ | {
+    ok: false;
+    code: 'idempotency_conflict';
+}
+/**
+ * A recurring event on the resource is not stored as far as this write reaches, and cannot be
+ * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
+ */
+ | {
+    ok: false;
+    code: 'recurrence_not_materialized';
+}
+/** The resource's tenant has as many holds as its `holds` limit, expired ones deleted. */
+ | {
+    ok: false;
+    code: 'hold_limit_reached';
+    limit: number;
+}
+/**
+ * The holder's live holds would together hold more hours than `maxHeldHoursPerHolder` allows
+ * (`limit`, in hours): one agent cannot keep a resource's month from everyone, a hold at a time.
+ */
+ | {
+    ok: false;
+    code: 'held_time_limit_reached';
+    limit: number;
+}
+/** The booking breaks one of the resource's booking rules (`SlotlockResource.bookingRules`). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: SlotlockBookingRule;
 } | {
     ok: false;
     code: 'overlap';
@@ -164,6 +325,27 @@ export type ConfirmHoldResult = {
 } | {
     ok: false;
     code: 'hold_expired';
+}
+/** A cancellation of the hold's reference (its id) arrived first and retired it. */
+ | {
+    ok: false;
+    code: 'reservation_cancelled';
+}
+/** Another booking of the tenant already uses the hold's id as its reference. */
+ | {
+    ok: false;
+    code: 'idempotency_conflict';
+}
+/** The hold's resource was archived since: it takes no new booking. */
+ | {
+    ok: false;
+    code: 'resource_archived';
+}
+/** The tenant is at its `reservations` limit: the hold stays a hold. */
+ | {
+    ok: false;
+    code: 'reservation_limit_reached';
+    limit: number;
 };
 export type ReleaseHoldResult = {
     ok: true;
@@ -241,6 +423,11 @@ export interface SlotlockCalendarEvent extends CalendarEventContent {
     updatedAt: Date;
 }
 export interface PutCalendarEventCommand extends CalendarEventContent {
+    /**
+     * The resource the writer read the event on: a revision is refused (`resource_tenant_mismatch`)
+     * when the stored event is on another, checked under the event's lock.
+     */
+    expectedResourceId?: string;
     tenantRef: string;
     /** Defaults to the trusted `internal` namespace. Agent callers must supply their owner digest. */
     ownerRef?: string;
@@ -253,6 +440,24 @@ export interface PutCalendarEventCommand extends CalendarEventContent {
     /** Mandatory for recurrence; bounded to 367 days. Defaults to the event interval otherwise. */
     materializationWindow?: Interval;
     source?: string;
+    /**
+     * Judge the event as a booking made now against the resource's booking rules (its first
+     * occurrence for notice and advance, every occurrence for step and hours), and keep the
+     * resource's turnaround after each occurrence. Off by default: an imported event is what happened
+     * elsewhere. The agent tools set it.
+     */
+    enforceBookingRules?: boolean;
+    /**
+     * Book the time a live hold keeps: the hold must be `holderRef`'s (`acquireHold`'s
+     * `principalRef`), on this resource, and cover the event, a single occurrence. In one transaction
+     * the hold and the rest of its group are released and the event takes the time, so no rival can
+     * come between. Its notice and advance were judged when it was held; step and hours are judged
+     * again.
+     */
+    fromHold?: {
+        holdId: string;
+        holderRef: string;
+    };
 }
 export type PutCalendarEventResult = {
     ok: true;
@@ -281,9 +486,20 @@ export type PutCalendarEventResult = {
     ok: false;
     code: 'owner_command_quota_exceeded';
     limit: number;
+}
+/** A new event would pass the tenant's `events` limit (revising one it has never does). */
+ | {
+    ok: false;
+    code: 'event_limit_reached';
+    limit: number;
 } | {
     ok: false;
     code: 'resource_tenant_mismatch';
+}
+/** The resource is archived: it takes no new booking (cancel and release still work). */
+ | {
+    ok: false;
+    code: 'resource_archived';
 } | {
     ok: false;
     code: 'event_cancelled';
@@ -292,11 +508,46 @@ export type PutCalendarEventResult = {
     ok: false;
     code: 'revision_conflict';
     currentRevision: number;
+}
+/** `fromHold` names no live hold of that holder's: released, booked, expired, or another's. */
+ | {
+    ok: false;
+    code: 'hold_not_found';
+}
+/** `fromHold`'s hold is on another resource, or does not cover the event. */
+ | {
+    ok: false;
+    code: 'hold_mismatch';
+}
+/**
+ * A recurring event on the resource is not stored as far as this write reaches, and cannot be
+ * extended that far (past the rolling horizon, or blocked): the time cannot be proven free.
+ */
+ | {
+    ok: false;
+    code: 'recurrence_not_materialized';
+}
+/** The booking breaks one of the resource's booking rules (`SlotlockResource.bookingRules`). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: SlotlockBookingRule;
 } | {
     ok: false;
     code: 'overlap';
     conflictingReservationId: string | null;
 };
+export type DeleteResourceResult = 
+/** `deleted`: false when the tenant has no resource with that id (deleted already, say). */
+{
+    ok: true;
+    deleted: boolean;
+}
+/** A future booking, a live hold, or a calendar event is still on it. */
+ | {
+    ok: false;
+    code: 'resource_in_use';
+};
 export type CancelCalendarEventResult = {
     ok: true;
     eventId: string;
@@ -324,8 +575,16 @@ export type CancelCalendarEventResult = {
     code: 'revision_conflict';
     currentRevision: number;
 };
-/** A place in the roll's order of due masters: the last one a batch examined. */
+/**
+ * A place in the roll's order of due masters: the last one a batch examined. The roll takes the
+ * masters it has never put back first, then those it has, longest waiting first.
+ */
 export interface CalendarHorizonRollCursor {
+    /**
+     * When the master was due to be examined again, if the roll had put it back; null (or, from a
+     * cursor of an earlier release, missing) when it had not.
+     */
+    rollRetryAt?: Date | null;
     materializedEndsAt: Date;
     eventId: string;
 }
@@ -338,11 +597,18 @@ export interface CalendarHorizonRollResult {
      * stored end and the window's: a roll never moves a series' end back.
      */
     extended: number;
-    /** Masters whose new occurrence collided; their previous coverage remains intact. */
+    /**
+     * Masters whose new occurrence collided; their previous coverage remains intact, and they wait an
+     * hour before a roll examines them again, behind every master it has not put back.
+     */
     conflicts: number;
+    /** The ids of those masters: what blocks each is a booking or hold on its new occurrences. */
+    conflictEventIds: string[];
     /**
      * Masters whose rule takes more than the expansion budget to reach the window (one that never
-     * occurs again, or almost never); their previous coverage remains intact.
+     * occurs again, or almost never), or whose roll failed for any other reason; their previous
+     * coverage remains intact, and they wait an hour
+     * before a roll examines them again, behind every master it has not put back.
      */
     refused: number;
     /** The ids of those masters, to find and fix them. */
@@ -350,9 +616,8 @@ export interface CalendarHorizonRollResult {
     /** True when more due masters remain beyond this bounded batch. */
     hasMore: boolean;
     /**
-     * Pass as `after` for the next batch of this pass, so the masters this batch left behind (in
-     * conflict or refused, which keep their place at the front of the order) are not examined again
-     * by every later batch. `null` when none remain.
+     * Pass as `after` for the next batch of this pass, so the masters this batch examined are not
+     * examined again by every later batch. `null` when none remain.
      */
     next: CalendarHorizonRollCursor | null;
 }
@@ -364,6 +629,26 @@ export interface CalendarEventRetentionResult {
     /** True when either class filled its batch, so more rows may already be eligible. */
     hasMore: boolean;
 }
+/** What erasing a tenant deleted. */
+export interface SlotlockTenantErasure {
+    /** Rows deleted, by table (every table the tenant owns rows in is named, with 0 for none). */
+    rows: Record<string, number>;
+    /** Rows deleted in all; 0 when the tenant had already been erased. */
+    total: number;
+}
+export interface BookingRetentionResult {
+    /** Holds past their expiry: they occupy nothing, and only a rival's write would reap them. */
+    expiredHoldsDeleted: number;
+    /** Keyed hold answers whose hold has expired: a retry with that key makes a new hold. */
+    holdCommandsDeleted: number;
+    /**
+     * References a cancel retired with no booking, older than the window: a create with one makes a
+     * new booking. A cancelled booking's reference stays retired.
+     */
+    tombstonesDeleted: number;
+    /** True when any class filled its batch, so more rows may already be eligible. */
+    hasMore: boolean;
+}
 export interface CalendarCoverageCommand {
     tenantRef: string;
     resourceId: string;
@@ -385,6 +670,12 @@ export type CalendarCoverageResult = {
 } | {
     ok: false;
     code: 'stale_revision' | 'revision_conflict' | 'idempotency_conflict';
+}
+/** A new source would pass the tenant's `coverage` limit (advancing one it has never does). */
+ | {
+    ok: false;
+    code: 'coverage_limit_reached';
+    limit: number;
 };
 export interface CalendarCoverageAssessment {
     state: 'complete' | 'partial' | 'unknown';

package/types.js

@@ -1,3 +1 @@
-// Slotlock core types. Every interval is half-open `[start, end)`: back-to-back reservations do not
-// conflict, matching RFC 5545 interval semantics and PostgreSQL range boundaries.
 export {};

package/webhooks.d.ts

@@ -0,0 +1,91 @@
+import type { SlotlockChange, SlotlockEventFeed } from './event-feed.js';
+/** The CloudEvents envelope a change is delivered and listed as. */
+export interface SlotlockCloudEvent {
+    specversion: '1.0';
+    id: string;
+    source: string;
+    type: string;
+    subject: string;
+    time: string;
+    datacontenttype: 'application/json';
+    data: Record<string, unknown>;
+}
+/** A change as CloudEvents 1.0 (structured mode): `type` is `io.pylota.slotlock.<change type>`. */
+export declare function slotlockCloudEvent(change: SlotlockChange): SlotlockCloudEvent;
+/**
+ * The Standard Webhooks signature of one attempt: `v1,` and the base64 HMAC-SHA256, keyed by the
+ * secret's bytes, of `id.timestamp.body`.
+ */
+export declare function signSlotlockWebhook(params: {
+    secret: string;
+    id: string;
+    timestamp: number;
+    body: string;
+}): string;
+/**
+ * When to try a failed endpoint again, by how many attempts have failed in a row: the Standard
+ * Webhooks example schedule (5 s, 5 min, 30 min, 2 h, 5 h, then 10 h), with ±10% jitter, and never
+ * sooner than the endpoint's Retry-After (capped at a day).
+ */
+export declare function slotlockWebhookRetryDelayMs(attempts: number, retryAfterMs?: number, random?: () => number): number;
+/** Whether `address` is one a webhook may not reach: loopback, private, link-local, and the like. */
+export declare function isPrivateAddress(address: string): boolean;
+export interface SlotlockWebhookResponse {
+    status: number;
+    /** From the response's Retry-After, when it gave one in seconds. */
+    retryAfterMs?: number;
+}
+export type SlotlockWebhookSender = (request: {
+    url: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<SlotlockWebhookResponse>;
+/**
+ * POST with Node's http client: no redirect is followed, the answer's body is never read beyond
+ * 64 KiB, and every address the host resolves to is checked when the socket connects, so a name
+ * that resolves to a private network (or is rebound to one) is refused unless `allowPrivateNetworks`.
+ */
+export declare function createSlotlockWebhookSender(options?: {
+    timeoutMs?: number;
+    allowPrivateNetworks?: boolean;
+}): SlotlockWebhookSender;
+export interface SlotlockWebhookPassResult {
+    /** Changes an endpoint accepted. */
+    delivered: number;
+    /** Endpoints whose next change failed, to be tried again later. */
+    failed: number;
+}
+/**
+ * One delivery pass for a tenant: claim each endpoint with changes due, send them in order until
+ * one fails, and record how far each got. A 2xx is delivered; 410 disables the endpoint; anything
+ * else, or no answer, is retried on the schedule. The send happens outside any transaction.
+ */
+export declare function deliverSlotlockWebhooks(params: {
+    feed: Pick<SlotlockEventFeed, 'claimWebhookDeliveries' | 'settleWebhookDelivery'>;
+    tenantRef: string;
+    send: SlotlockWebhookSender;
+    batch?: number;
+    leaseMs?: number;
+    /** After this long (default 30,000 ms) no further change is sent this pass; the rest wait. */
+    budgetMs?: number;
+    now?: () => number;
+}): Promise<SlotlockWebhookPassResult>;
+export interface SlotlockWebhookScheduler {
+    /** Deliver for this tenant too (a server calls it for each tenant it serves). */
+    touch(tenantRef: string): void;
+    close(): Promise<void>;
+}
+/**
+ * Delivery passes every `intervalMs` (250-60,000, default 2,000) for the tenants `tenants()` lists
+ * (the store's webhook_tenants(), say) and those touched, one tenant at a time. A pass that fails
+ * is reported and the next one runs as usual.
+ */
+export declare function startSlotlockWebhookDelivery(options: {
+    tenants: () => Promise<readonly string[]>;
+    /** Tenants delivered at once (1-64, default 8), so one slow tenant's endpoints hold up none other. */
+    concurrency?: number;
+    deliver: (tenantRef: string) => Promise<SlotlockWebhookPassResult>;
+    intervalMs?: number;
+    onPass?: (tenantRef: string, result: SlotlockWebhookPassResult) => void;
+    onError?: (error: unknown) => void;
+}): SlotlockWebhookScheduler;