slotlock 0.6.2 → 0.7.0

package/engine.d.ts

@@ -4,22 +4,19 @@ export declare function mergeIntervals(intervals: Interval[]): Interval[];
 /** Free sub-intervals of `window` once `busy` is carved out (busy need not be sorted/merged). */
 export declare function subtractBusy(window: Interval, busy: Interval[]): Interval[];
 /**
- * Earliest `[s, s + durationMs)` that fits entirely inside one of `windows` without touching
- * `busy`. Returns null when nothing fits (no windows, saturated, duration too long, or a
- * non-positive duration — a zero-width slot is never a useful answer).
+ * Earliest `[s, s + durationMs)` inside one of `windows` without touching `busy`, or null when
+ * nothing fits (including a non-positive duration).
  *
- * Adjacency is NOT a booking boundary: touching windows merge (half-open point-set semantics,
- * RFC 7953 set-union), so a slot may legitimately span the seam of two abutting rules. "Distinct
- * shifts, no straddling" is unexpressible via touching windows — model it as a gap or a future
- * constraint layer.
+ * Touching windows merge (RFC 7953 set-union), so a slot may span the seam of two abutting rules;
+ * "no straddling" must be modelled as a gap.
  */
 export declare function findNextAvailable(params: {
     busy: Interval[];
     windows: Interval[];
     durationMs: number;
     /**
-     * Optional: the first allowed start at or after a candidate (a booking rule's step, say). It
-     * must not move a start backwards.
+     * The first allowed start at or after a candidate (a booking rule's step); must not move a start
+     * backwards.
      */
     align?: (start: Date) => Date;
 }): Interval | null;

package/engine.js

@@ -34,14 +34,11 @@ export function subtractBusy(window, busy) {
     return free;
 }
 /**
- * Earliest `[s, s + durationMs)` that fits entirely inside one of `windows` without touching
- * `busy`. Returns null when nothing fits (no windows, saturated, duration too long, or a
- * non-positive duration — a zero-width slot is never a useful answer).
+ * Earliest `[s, s + durationMs)` inside one of `windows` without touching `busy`, or null when
+ * nothing fits (including a non-positive duration).
  *
- * Adjacency is NOT a booking boundary: touching windows merge (half-open point-set semantics,
- * RFC 7953 set-union), so a slot may legitimately span the seam of two abutting rules. "Distinct
- * shifts, no straddling" is unexpressible via touching windows — model it as a gap or a future
- * constraint layer.
+ * Touching windows merge (RFC 7953 set-union), so a slot may span the seam of two abutting rules;
+ * "no straddling" must be modelled as a gap.
  */
 export function findNextAvailable(params) {
     const { busy, windows, durationMs } = params;
@@ -49,8 +46,7 @@ export function findNextAvailable(params) {
         return null;
     const slotAt = (start) => ({ start, end: new Date(start.getTime() + durationMs) });
     const align = params.align ?? ((start) => start);
-    // One walk of the merged busy list alongside the merged windows, both by start: a busy interval
-    // ending by a window's start ends before every later one too.
+    // One walk of merged busy alongside merged windows, both by start.
     const merged = mergeIntervals(busy);
     let next = 0;
     for (const window of mergeIntervals(windows)) {

package/event-feed.d.ts

@@ -1,42 +1,36 @@
 import type { Sql, TransactionSql } from 'postgres';
 type SlotlockSql = Sql | TransactionSql;
 /** What a change can be, as the feed and a webhook's `event_types` name it. */
-export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "webhook.disabled", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
+export declare const SLOTLOCK_CHANGE_TYPES: readonly ["hold.created", "hold.updated", "hold.confirmed", "hold.released", "hold.expired", "reservation.created", "reservation.updated", "reservation.cancelled", "reservation.checked_in", "reservation.no_show", "event.created", "event.updated", "event.cancelled", "event.timezone_shifted", "event.timezone_conflict", "coverage.stale", "waitlist.offered", "waitlist.expired", "approval.requested", "approval.granted", "approval.declined", "approval.expired", "webhook.disabled", "usage.threshold_reached", "resource.created", "resource.updated", "resource.archived", "resource.restored", "resource.deleted", "coverage.recorded", "coverage.deleted", "webhook.created", "webhook.enabled", "webhook.deleted", "key.created", "key.rotated", "key.revoked"];
 export type SlotlockChangeType = (typeof SLOTLOCK_CHANGE_TYPES)[number];
 /**
- * Where a change came from, as the history and the feed record it (withTenant's `origin`): an agent
- * protocol (`mcp`, `a2a`), the REST API's agent routes (`rest`) or its application operations
- * (`application`), the dashboard, a member's dashboard assistant, maintenance, or code calling the
- * store itself (`library`). Never an address or anything else about a person.
+ * Where a change came from (withTenant's `origin`): an agent protocol (`mcp`, `a2a`), the REST
+ * API's agent routes (`rest`) or application operations (`application`), the dashboard, its
+ * assistant, maintenance, or direct store calls (`library`). Never anything about a person.
  */
 export declare const SLOTLOCK_CHANGE_ORIGINS: readonly ["mcp", "a2a", "rest", "application", "dashboard", "dashboard-assistant", "maintenance", "library"];
 export type SlotlockChangeOrigin = (typeof SLOTLOCK_CHANGE_ORIGINS)[number];
 /** Whether `value` is one of SLOTLOCK_CHANGE_ORIGINS. */
 export declare function isSlotlockChangeOrigin(value: unknown): value is SlotlockChangeOrigin;
 /**
- * The digest 0.5.3 named a coverage source by on the feed: `src_` and the first 24 hex digits of
- * sha256(tenant, newline, source). Unkeyed, so anyone who knows the tenant could confirm a guessed
- * source against it; 0.6 names a source by a random id instead (`calendar_coverage.source_id`), and
- * the upgrade uses this only to find the changes 0.5.3 wrote and rename them. `tenant` and `source`
- * are SQL expressions.
+ * The unkeyed digest 0.5.3 named a coverage source by (`src_` + 24 hex of sha256(tenant, newline,
+ * source)); anyone knowing the tenant could confirm a guess. Used only by the upgrade to find and
+ * rename those changes. `tenant` and `source` are SQL expressions.
  */
 export declare function legacyCoverageSourceDigestSql(tenant: string, source: string): string;
 /**
- * 0.5.3 worked out a source's id here: an unkeyed digest of the tenant and the source, which let
- * anyone who saw a change confirm a guessed source. Since 0.6 a source's `source_id` is random and
- * only the database knows it, so this throws (`coverage_source_id_unavailable`) rather than give a
- * digest nothing carries any more.
+ * Throws `coverage_source_id_unavailable`: since 0.6 a source's `source_id` is random and only the
+ * database knows it (0.5.3's unkeyed digest let anyone confirm a guessed source).
  *
  * @deprecated Read `sourceId` from `listCoverage` (`source_id` of `slotlock_get_coverage`). It may
  * be removed in 0.7.0.
  */
 export declare function slotlockCoverageSourceId(_tenantRef: string, _source: string): never;
 /**
- * A change's subject and data as the feed serves them. A `coverage.*` change never carries its
- * source (`source`) or the error read from it (`last_error`, which can quote it), and is named by a
- * `source_id` of this release or `src_redacted`: an earlier release wrote both, and the upgrade
- * renames those rows in batches after it commits, so a row it has not reached yet, or one an
- * earlier release's server writes during a rolling upgrade, is served redacted.
+ * A change's subject and data as the feed serves them. A `coverage.*` change never carries `source`
+ * or `last_error` (which can quote it), and is named by a current `source_id` or `src_redacted`:
+ * rows an earlier release wrote are renamed in batches after upgrade, so one not reached yet is
+ * served redacted.
  */
 export declare function slotlockServedChange(type: string, subject: string, data: Record<string, unknown>): {
     subject: string;
@@ -45,7 +39,7 @@ export declare function slotlockServedChange(type: string, subject: string, data
 /** How long the feed keeps a change, and so how far back a cursor may reach. */
 export declare const SLOTLOCK_CHANGE_RETENTION_DAYS = 30;
 /** Webhook endpoints one tenant may have. */
-export declare const SLOTLOCK_MAX_WEBHOOK_ENDPOINTS = 10;
+export declare const SLOTLOCK_MAX_WEBHOOK_ENDPOINTS = 25;
 /** After this long failing, an endpoint is disabled and the feed says so (`webhook.disabled`). */
 export declare const SLOTLOCK_WEBHOOK_FAILING_LIMIT_MS: number;
 export interface SlotlockChange {
@@ -66,11 +60,29 @@ export interface SlotlockChange {
     /** Pass as `after` to read what follows this change. */
     position: string;
 }
+/** Resources one webhook endpoint's filter may name. */
+export declare const SLOTLOCK_WEBHOOK_FILTER_RESOURCES = 100;
+/** Pools, locations or groups one webhook endpoint's filter may name, of each. */
+export declare const SLOTLOCK_WEBHOOK_FILTER_REFS = 20;
+/**
+ * Which resources' changes an endpoint receives (RFC 0003 G5): only changes about a resource that
+ * matches one of these, as it is when the change is delivered, so a change about no resource (a key,
+ * a webhook, a usage notice) is not sent. A location includes every location in it. At most
+ * SLOTLOCK_WEBHOOK_FILTER_RESOURCES ids, and SLOTLOCK_WEBHOOK_FILTER_REFS of each of the others.
+ */
+export interface SlotlockWebhookFilter {
+    resourceIds?: string[];
+    pools?: string[];
+    locations?: string[];
+    groups?: string[];
+}
 export interface SlotlockWebhookEndpoint {
     id: string;
     url: string;
     /** Null: every type. */
     eventTypes: SlotlockChangeType[] | null;
+    /** Only changes about these resources; absent, changes about any resource or none. */
+    filter?: SlotlockWebhookFilter;
     createdAt: Date;
     /** Failed attempts since the last delivery that succeeded. */
     attempts: number;
@@ -96,10 +108,11 @@ export interface SlotlockWebhookClaim {
 export type CreateWebhookEndpointResult = {
     ok: true;
     endpoint: SlotlockWebhookEndpoint;
-    secret: string;
+    secret: string; /** True when an idempotency key answered what an earlier create made. */
+    replayed?: boolean;
 } | {
     ok: false;
-    code: 'invalid_webhook_url' | 'invalid_event_types';
+    code: 'invalid_webhook_url' | 'invalid_event_types' | 'invalid_webhook_filter' | 'idempotency_conflict' | 'invalid_identity';
 } | {
     ok: false;
     code: 'webhook_limit_reached';
@@ -115,11 +128,10 @@ export type ListChangesResult = {
 };
 export interface SlotlockEventFeed {
     /**
-     * The tenant's changes after `after` (a `position`, or the oldest kept without it), oldest
-     * first, up to `limit` (1-500, default 100). Only changes of transactions that have ended are
-     * read, so a reader that follows `next` never skips one that commits late. `next` is the last
-     * change's position, or `after` when there is none yet: poll with it. A position before a change
-     * any store has pruned is `cursor_expired`: read from the start again.
+     * The tenant's changes after `after` (or from the oldest kept), oldest first, up to `limit`
+     * (1-500, default 100). Only ended transactions are read, so a reader following `next` never
+     * skips a late commit. `next` is the last position, or `after` when there is none: poll with it.
+     * A position before a pruned change is `cursor_expired`.
      */
     listChanges(params: {
         tenantRef: string;
@@ -143,6 +155,13 @@ export interface SlotlockEventFeed {
         tenantRef: string;
         url: string;
         eventTypes?: readonly string[];
+        /** Only changes about these resources (`invalid_webhook_filter` past its bounds). */
+        filter?: SlotlockWebhookFilter;
+        /**
+         * A retry identity, kept as long as the endpoint: the same key and request answer the endpoint
+         * and secret the first made (`replayed`), another request `idempotency_conflict`.
+         */
+        idempotencyKey?: string;
     }): Promise<CreateWebhookEndpointResult>;
     listWebhookEndpoints(params: {
         tenantRef: string;
@@ -165,9 +184,9 @@ export interface SlotlockEventFeed {
         code: 'changes_pruned';
     }>;
     /**
-     * Lease the tenant's endpoints that have changes due, each with its next `batch` (1-100)
-     * changes, for `leaseMs` (1,000-300,000). A lease that runs out is claimed again by any worker,
-     * so a worker that dies mid-batch costs a redelivery, never a lost change.
+     * Lease the tenant's endpoints with changes due, each with its next `batch` (1-100) changes, for
+     * `leaseMs` (1,000-300,000). An expired lease is claimed again by any worker, so a crash costs a
+     * redelivery, never a lost change.
      */
     claimWebhookDeliveries(params: {
         tenantRef: string;
@@ -193,11 +212,10 @@ export interface SlotlockEventFeed {
         };
     }): Promise<void>;
     /**
-     * History: the changes to one resource (`resourceId`: its bookings and events, and its own
-     * configuration) or one record (`subject`: a booking's reference, an event's, hold's, webhook's or
-     * API key's id), newest first, `limit` (1-100) at a time, each with who made it (`actor`, `keyId`),
-     * where from (`origin`) and, for a change of an existing record, what it was before. Pass the last one's
-     * `id` as `before` for the page after. Kept as long as the feed keeps changes.
+     * History of one resource (`resourceId`: its bookings, events and configuration) or one record
+     * (`subject`), newest first, `limit` (1-100) at a time, each with `actor`, `keyId`, `origin` and
+     * the prior state where there was one. Pass the last `id` as `before` for the next page. Kept as
+     * long as the feed.
      */
     listHistory(params: {
         tenantRef: string;