slotlock 0.6.3 → 0.7.0

package/slotlock.manifest.json

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

package/store.d.ts

@@ -1,8 +1,11 @@
+import { type SlotlockResourceKind, type SlotlockResourceProfileInput, type SlotlockLocation, type SlotlockPoolOrder, type SlotlockResourceGroup, type SlotlockResourceScope } from './resource-profile.js';
+import { type SlotlockUsageRow } from './usage.js';
 import { type SlotlockChangeOrigin, 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, CalendarEventContent, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, SlotlockBookingRuleDefaults, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockAgendaEntry, SlotlockHold, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
+import type { AcquireHoldResult, CalendarCoverageCommand, CalendarCoverageResult, CalendarEventContent, CalendarEventRetentionResult, BookingRetentionResult, SlotlockTenantErasure, SlotlockBookingRuleDefaults, CalendarFreeBusy, CalendarHorizonRollCursor, CalendarHorizonRollResult, CancelCalendarEventResult, CancelExternalReservationResult, ConfirmHoldResult, CreateReservationResult, DeleteResourceResult, ExternalReservationCommand, ExternalReservationResult, Interval, SlotlockCalendarEvent, SlotlockAgendaEntry, SlotlockHold, SlotlockBookingDescription, SlotlockApproval, SlotlockApprovalPolicy, SlotlockReservation, SlotlockResource, PutCalendarEventCommand, PutCalendarEventResult, ReleaseHoldResult, WeeklyAvailabilityRule } from './types.js';
+import { type PutApprovalPolicyParams } from './approvals.js';
 export { SLOTLOCK_CALENDAR_HORIZON_DAYS };
 /**
  * Longest one-off event (ten years and some leap days); a recurring series is bounded by its
@@ -137,6 +140,13 @@ export interface SlotlockStore extends SlotlockEventFeed {
         origin?: SlotlockChangeOrigin;
         /** The id (a UUID) of the API key making these changes, recorded with each. */
         keyId?: string;
+        /**
+         * A key limited to part of its tenant (RFC 0003 G6): the transaction reaches only the
+         * resources at these locations (each with every location in it) or in these groups, as they
+         * are when it starts, by the database's resource_scope_v1 policies, on every table keyed by
+         * resource, for reads and writes. A resource outside it is not found.
+         */
+        resourceScope?: SlotlockResourceScope;
     }): Promise<T>;
     /**
      * INVARIANT (erasure completeness): a tenant integration must use a stable, erasable business
@@ -159,7 +169,103 @@ export interface SlotlockStore extends SlotlockEventFeed {
          * refused (`resource_visibility_conflict`).
          */
         visibility?: SlotlockResource['visibility'];
+        /**
+         * Its profile (resource-profile.ts): name, description, kind, capacity, labels and attributes,
+         * each optional. Creating an existing reference again sets the fields given and keeps the rest.
+         * Refused (`invalid_resource_profile`) outside its bounds, or for a resource with no tenant.
+         */
+        profile?: SlotlockResourceProfileInput;
+        /**
+         * The reference of the location it is at (`location_not_found` when the tenant has none such).
+         * Without a `timezone`, a new resource takes the nearest time zone its location, or one above
+         * it, has, else UTC.
+         */
+        location?: string;
     }): Promise<SlotlockResource>;
+    /**
+     * Change one of the tenant's resources' profile: the fields given, keeping the rest (`null`
+     * clears a name, description or capacity). Null for an id that is not the tenant's; refused
+     * (`invalid_resource_profile`) outside its bounds. The feed's `resource.updated` names the
+     * fields that changed (`profile_changed`), never their values.
+     */
+    updateResourceProfile(params: {
+        tenantRef: string;
+        id: string;
+        profile: SlotlockResourceProfileInput;
+        /** Move it to this location, or to none (`null`); left out, it stays (`location_not_found`). */
+        location?: string | null;
+    }): Promise<SlotlockResource | null>;
+    /**
+     * The tenant's locations, each under its parent, depth first (RFC 0003 G2), with how many
+     * resources are at each.
+     */
+    listLocations(params: {
+        tenantRef: string;
+    }): Promise<SlotlockLocation[]>;
+    /**
+     * Create the location with this reference, or change its name, and the parent and time zone
+     * given. Refused: `invalid_location` (naming the field), `location_not_found` (no such parent),
+     * `location_too_deep` (past SLOTLOCK_MAX_LOCATION_DEPTH levels), `location_cycle` (under itself),
+     * `location_limit_reached` (SLOTLOCK_MAX_LOCATIONS).
+     */
+    putLocation(params: {
+        tenantRef: string;
+        ref: string;
+        name: string;
+        parentRef?: string | null;
+        timezone?: string | null;
+    }): Promise<SlotlockLocation>;
+    /** Change a location's name, parent or time zone, as putLocation; null when it has none such. */
+    updateLocation(params: {
+        tenantRef: string;
+        ref: string;
+        name?: string;
+        parentRef?: string | null;
+        timezone?: string | null;
+    }): Promise<SlotlockLocation | null>;
+    /**
+     * Delete a location: false when it has none such; refused (`location_in_use`) while a resource is
+     * at it or a location is under it.
+     */
+    deleteLocation(params: {
+        tenantRef: string;
+        ref: string;
+    }): Promise<boolean>;
+    /** The tenant's groups (RFC 0003 G3), by reference, with how many resources are in each. */
+    listGroups(params: {
+        tenantRef: string;
+    }): Promise<SlotlockResourceGroup[]>;
+    /**
+     * Create the group with this reference, or change its name, and its description when given.
+     * Refused: `invalid_group` (naming the field), `group_limit_reached` (SLOTLOCK_MAX_RESOURCE_GROUPS).
+     */
+    putGroup(params: {
+        tenantRef: string;
+        ref: string;
+        name: string;
+        description?: string | null;
+    }): Promise<SlotlockResourceGroup>;
+    /** Delete a group, its resources left as they are: false when it has none such. */
+    deleteGroup(params: {
+        tenantRef: string;
+        ref: string;
+    }): Promise<boolean>;
+    /**
+     * Put one of the tenant's resources in a group: true when it was not in it. Refused:
+     * `group_not_found`, `resource_not_found`, `resource_group_limit_reached`
+     * (SLOTLOCK_MAX_GROUPS_PER_RESOURCE).
+     */
+    addGroupMember(params: {
+        tenantRef: string;
+        group: string;
+        resourceId: string;
+    }): Promise<boolean>;
+    /** Take a resource out of a group: true when it was in it. */
+    removeGroupMember(params: {
+        tenantRef: string;
+        group: string;
+        resourceId: string;
+    }): Promise<boolean>;
     /**
      * Resolve one tenant-owned resource without revealing another tenant's matching id. An archived
      * one is returned (with `archivedAt`); with `visibility`, only one of that visibility.
@@ -250,15 +356,55 @@ export interface SlotlockStore extends SlotlockEventFeed {
         tenantRef: string;
         pool: string;
         visibility?: 'shared';
+        /** In the pool's order (`setPoolOrder`) rather than by id. */
+        ordered?: boolean;
+        /**
+         * For a booking about to take one (with `ordered`): a round-robin pool's place is locked until
+         * the transaction ends, so bookings at once go round in turn instead of starting from one place.
+         */
+        forBooking?: boolean;
     }): Promise<SlotlockResource[]>;
-    /** The tenant's pools by name, with how many members each has that may be booked (its capacity). */
+    /**
+     * The tenant's pools by name, with how many members each has that may be booked (its capacity)
+     * and the order a pool booking tries them in.
+     */
     listPools(params: {
         tenantRef: string;
         visibility?: 'shared';
     }): Promise<{
         pool: string;
         capacity: number;
+        order: SlotlockPoolOrder;
     }[]>;
+    /**
+     * Set the order a pool booking tries a pool's members in (RFC 0003 G7): `stable` (by id, the
+     * default), `least_booked` or `round_robin`: `invalid_pool` for a name that is not a pool's,
+     * `invalid_pool_order` for an order that is not one of these, `pool_order_limit_reached` past
+     * SLOTLOCK_MAX_POOL_SETTINGS pools a tenant.
+     */
+    setPoolOrder(params: {
+        tenantRef: string;
+        pool: string;
+        order: SlotlockPoolOrder;
+    }): Promise<SlotlockPoolOrder>;
+    /**
+     * Make a resource a part of another (RFC 0003 G8), or no part (`null`): a booking of the whole
+     * then conflicts with every part, two parts never with each other. Null for no such resource;
+     * `parent_not_found`, `composite_too_deep` (one level only), `composite_parts_limit`
+     * (SLOTLOCK_MAX_COMPOSITE_PARTS) and `composite_busy` (either side has a booking or live hold to
+     * come) refuse it.
+     */
+    setResourceParent(params: {
+        tenantRef: string;
+        id: string;
+        parentId: string | null;
+    }): Promise<SlotlockResource | null>;
+    /** Note the member a pool booking took, from which `round_robin` goes on. */
+    notePoolBooking(params: {
+        tenantRef: string;
+        pool: string;
+        resourceId: string;
+    }): Promise<void>;
     /** Set (or clear, with `null`) the bookable hours of every resource the tenant has; returns how many. */
     setTenantAvailability(params: {
         tenantRef: string;
@@ -273,7 +419,43 @@ export interface SlotlockStore extends SlotlockEventFeed {
         visibility?: SlotlockResource['visibility'];
         /** Archived resources too; omitted, only those in use. */
         includeArchived?: boolean;
+        /** Only resources of this kind (`other` for those that say none). */
+        kind?: SlotlockResourceKind;
+        /** Only resources with every one of these labels (at most 20). */
+        labels?: readonly string[];
+        /** Only resources at this location or a location under it. */
+        location?: string;
+        /** Only resources in this group. */
+        group?: string;
+        /** Only this pool's members. */
+        pool?: string;
     }): Promise<SlotlockResource[]>;
+    /**
+     * How many resources the tenant has, archived ones included: the count a resource limit (a hosted
+     * plan's, `maxTenantResources`) is checked against.
+     */
+    countResources(params: {
+        tenantRef: string;
+    }): Promise<number>;
+    /**
+     * Roll the tenant's committed bookings and holds up from its feed into its daily usage
+     * (usage.ts, `slotlock.roll_up_usage`), up to `limit` changes (1-100,000, default 5,000): how
+     * many it read. Fewer than `limit` means it has caught up.
+     */
+    rollUpUsage(params: {
+        tenantRef: string;
+        limit?: number;
+    }): Promise<number>;
+    /**
+     * The tenant's usage from `from` to `to`, UTC days `YYYY-MM-DD` inclusive, at most
+     * SLOTLOCK_USAGE_RETENTION_DAYS apart (usage.ts, `slotlock.tenant_usage`): empty unless the
+     * deployment meters it.
+     */
+    readUsage(params: {
+        tenantRef: string;
+        from: string;
+        to: string;
+    }): Promise<SlotlockUsageRow[]>;
     /**
      * Insert a confirmed reservation with the EXCLUDE constraint as the overlap arbiter; expected
      * outcomes (invalid window, lost race) come back structured. Expired holds overlapping the window
@@ -331,6 +513,14 @@ export interface SlotlockStore extends SlotlockEventFeed {
          * holder and no cap.
          */
         holderRef?: string;
+        /**
+         * Lower the holder's caps for this hold (an API key's own limits, RFC 0004 A5): never above
+         * `maxHoldsPerHolder` and `maxHeldHoursPerHolder`, which win where they are lower.
+         */
+        holderCaps?: {
+            maxHolds?: number;
+            maxHeldHours?: number;
+        };
         /**
          * 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.
@@ -342,6 +532,18 @@ export interface SlotlockStore extends SlotlockEventFeed {
         tenantRef: string;
         holdId: string;
     }): Promise<SlotlockHold | null>;
+    /**
+     * One holder's own hold by id, lapsed or live (`live`), so a confirm can say `hold_expired`
+     * rather than not found. Null when it is gone, booked, or another holder's.
+     */
+    getHolderHold(params: {
+        tenantRef: string;
+        holdId: string;
+        holderRef: string;
+    }): Promise<{
+        hold: SlotlockHold;
+        live: boolean;
+    } | null>;
     /** The tenant's live holds on one resource, by start then id, keyset-paginated like events. */
     listHolds(params: {
         tenantRef: string;
@@ -371,6 +573,156 @@ export interface SlotlockStore extends SlotlockEventFeed {
         tenantRef: string;
         externalRef: string;
     }): Promise<SlotlockReservation | null>;
+    /**
+     * Any booking, hold or event occurrence of the tenant's by its row id (the id a refused write's
+     * `conflictingReservationId` names): the time it occupies, buffers included, and whose it is.
+     * Null when the tenant has none, or the transaction's key may not see it.
+     */
+    describeBooking(params: {
+        tenantRef: string;
+        id: string;
+    }): Promise<SlotlockBookingDescription | null>;
+    /**
+     * The time an owner's calendar events occupy now, buffers included, one row per occupation: what
+     * an approval (RFC 0004 A4) holds for a write, read in the write's own rolled-back transaction.
+     */
+    eventOccupancy(params: {
+        tenantRef: string;
+        ownerRef: string;
+        externalRefs: readonly string[];
+    }): Promise<{
+        resourceId: string;
+        start: Date;
+        end: Date;
+        recurring: boolean;
+    }[]>;
+    /** Create or replace an approval policy; null when the tenant has its 50 already. */
+    putApprovalPolicy(params: PutApprovalPolicyParams): Promise<SlotlockApprovalPolicy | null>;
+    listApprovalPolicies(params: {
+        tenantRef: string;
+    }): Promise<SlotlockApprovalPolicy[]>;
+    deleteApprovalPolicy(params: {
+        tenantRef: string;
+        ref: string;
+    }): Promise<{
+        deleted: boolean;
+    }>;
+    /** The tenant's policies that apply to any of these resources (by id, pool, location, group, or all). */
+    approvalPoliciesFor(params: {
+        tenantRef: string;
+        resourceIds: readonly string[];
+    }): Promise<SlotlockApprovalPolicy[]>;
+    /**
+     * A write waiting for a person: its time held by holds the approval owns, until `expiresAt`, and
+     * the request kept to run as its requester when granted. A retry with the same `requestKey`
+     * answers the same approval (`replayed`), or `idempotency_conflict` for another request. With
+     * `consumeHold`, the requester's own hold of that time gives way to the approval's in the same
+     * transaction. `overlap` when the time is taken; `approval_limit_reached` past the pending caps.
+     */
+    requestApproval(params: {
+        tenantRef: string;
+        policyRef: string;
+        operation: SlotlockApproval['operation'];
+        request: Record<string, unknown>;
+        requester: Record<string, unknown>;
+        requesterRef: string;
+        requestKey: string;
+        holds: readonly {
+            resourceId: string;
+            start: Date;
+            end: Date;
+        }[];
+        start: Date;
+        end: Date;
+        expiresAt: Date;
+        consumeHold?: {
+            holdId: string;
+            holderRef: string;
+        };
+    }): Promise<{
+        ok: true;
+        approval: SlotlockApproval;
+        replayed: boolean;
+    } | {
+        ok: false;
+        code: 'overlap' | 'approval_limit_reached' | 'idempotency_conflict';
+        limit?: number;
+    }>;
+    /** The approval a request key made, or null. */
+    findApproval(params: {
+        tenantRef: string;
+        requestKey: string;
+    }): Promise<SlotlockApproval | null>;
+    getApproval(params: {
+        tenantRef: string;
+        id: string;
+    }): Promise<(SlotlockApproval & {
+        requester: Record<string, unknown>;
+    }) | null>;
+    listApprovals(params: {
+        tenantRef: string;
+        status?: SlotlockApproval['status'];
+        limit?: number;
+    }): Promise<SlotlockApproval[]>;
+    /**
+     * Lock a pending, unexpired approval and let its holds go, so its write can take their time in
+     * the same transaction; finishApprovalGrant then marks it granted.
+     */
+    beginApprovalGrant(params: {
+        tenantRef: string;
+        id: string;
+    }): Promise<{
+        ok: true;
+        approval: SlotlockApproval;
+    } | {
+        ok: false;
+        code: 'approval_not_found' | 'approval_not_pending' | 'approval_expired';
+    }>;
+    finishApprovalGrant(params: {
+        tenantRef: string;
+        id: string;
+        decidedBy: string;
+    }): Promise<SlotlockApproval>;
+    declineApproval(params: {
+        tenantRef: string;
+        id: string;
+        decidedBy: string;
+        reason?: string;
+    }): Promise<{
+        ok: true;
+        approval: SlotlockApproval;
+    } | {
+        ok: false;
+        code: 'approval_not_found' | 'approval_not_pending' | 'approval_expired';
+    }>;
+    /** Maintenance: up to `limit` pending approvals past their wait expire and free their time. */
+    expireApprovals(params: {
+        tenantRef: string;
+        limit?: number;
+    }): Promise<{
+        expired: number;
+    }>;
+    /**
+     * Empty a test environment (RFC 0004 A6): its resources, locations, groups, bookings, events,
+     * holds, waitlist, approval policies and feed; its keys, webhooks, plan and usage stay. Refused
+     * (`sandbox_test_only`) for a tenant that is not a test environment (`~test`). Rows removed, by
+     * table.
+     */
+    resetTestTenant(params: {
+        tenantRef: string;
+    }): Promise<Record<string, number>>;
+    /**
+     * In a test environment, make what would lapse within `minutes` lapse now (RFC 0004 A6): holds
+     * (a waitlist offer's and an approval's among them) and pending approvals. Maintenance then
+     * reaps them as it would have. Refused (`sandbox_test_only`) elsewhere.
+     */
+    fastForwardTestTenant(params: {
+        tenantRef: string;
+        minutes: number;
+    }): Promise<{
+        holds: number;
+        approvals: number;
+    }>;
     /**
      * The tenant's bookings on one resource whose occupied time meets `window` (at most 367 days),
      * by start then id, keyset-paginated: pass the last one's `{ start, id }` as `after`.
@@ -604,6 +956,11 @@ export interface SlotlockStore extends SlotlockEventFeed {
         end: Date;
         holderRef: string;
         offerTtlMs?: number;
+        /**
+         * A retry identity, kept as long as the entry: the same key and request answer the entry the
+         * first made (`replayed`), another request `idempotency_conflict`.
+         */
+        idempotencyKey?: string;
     }): Promise<JoinWaitlistResult>;
     /** The tenant's waitlist entries, oldest first, optionally of one resource, pool or holder. */
     listWaitlist(params: {
@@ -650,6 +1007,17 @@ export interface SlotlockStore extends SlotlockEventFeed {
     deleteAssistantSettings(params: {
         tenantRef: string;
     }): Promise<boolean>;
+    /**
+     * Replace the tenant's sealed assistant key `from` with `to`, the same key sealed under a newer
+     * secret (SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS), only while `from` is still the one stored: a key an
+     * owner saved since is never overwritten. Nothing else changes, its hint and who set it included.
+     * True when it was replaced.
+     */
+    resealAssistantKey(params: {
+        tenantRef: string;
+        from: string;
+        to: string;
+    }): Promise<boolean>;
     /** A member's live assistant conversation, or null when none is (or it expired). */
     getAssistantConversation(params: {
         tenantRef: string;
@@ -837,9 +1205,10 @@ export interface SlotlockWaitlistEntry {
 export type JoinWaitlistResult = {
     ok: true;
     entry: SlotlockWaitlistEntry;
+    replayed: boolean;
 } | {
     ok: false;
-    code: 'invalid_identity' | 'invalid_window' | 'invalid_ttl' | 'invalid_pool' | 'resource_not_found' | 'resource_archived' | 'pool_not_found' | 'waitlist_limit_reached';
+    code: 'invalid_identity' | 'invalid_window' | 'invalid_ttl' | 'invalid_pool' | 'resource_not_found' | 'resource_archived' | 'pool_not_found' | 'waitlist_limit_reached' | 'idempotency_conflict';
 };
 export type CheckInReservationResult = {
     ok: true;
@@ -954,4 +1323,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", "setResourceBookingRules", "setBookingRuleDefaults", "setResourcePool", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage", "createWebhookEndpoint", "deleteWebhookEndpoint", "enableWebhookEndpoint", "recordCoverageFailure", "deleteCoverage", "checkInReservation", "joinWaitlist", "leaveWaitlist", "putAssistantSettings", "deleteAssistantSettings", "putAssistantConversation", "settleAssistantAction", "deleteAssistantConversation"];
+export declare const SLOTLOCK_TENANT_WRITE_METHODS: readonly ["createResource", "updateResourceProfile", "putLocation", "updateLocation", "deleteLocation", "putGroup", "deleteGroup", "addGroupMember", "removeGroupMember", "archiveResource", "restoreResource", "deleteResource", "setResourceAvailability", "setResourceBookingRules", "setBookingRuleDefaults", "setResourcePool", "setResourceParent", "setPoolOrder", "notePoolBooking", "putApprovalPolicy", "deleteApprovalPolicy", "requestApproval", "beginApprovalGrant", "finishApprovalGrant", "declineApproval", "resetTestTenant", "fastForwardTestTenant", "setTenantAvailability", "createReservation", "createExternalReservation", "rescheduleExternalReservation", "cancelExternalReservation", "acquireHold", "confirmHold", "releaseHold", "putCalendarEvent", "cancelCalendarEvent", "cancelCalendarEventById", "recordCalendarCoverage", "createWebhookEndpoint", "deleteWebhookEndpoint", "enableWebhookEndpoint", "recordCoverageFailure", "deleteCoverage", "checkInReservation", "joinWaitlist", "leaveWaitlist", "putAssistantSettings", "deleteAssistantSettings", "resealAssistantKey", "putAssistantConversation", "settleAssistantAction", "deleteAssistantConversation"];