slotlock 0.9.0 → 0.10.0

package/store.d.ts

@@ -1,10 +1,12 @@
 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 SlotlockWorkspaceRole } from './workspace-roles.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, SLOTLOCK_SOURCE_BUSY_MAX } from './rules.js';
 import type { AcquireHoldResult, MarkHoldPaidResult, PutContactResult, SlotlockContact, SlotlockContactConsent, CalendarCoverageCommand, CalendarCoverageResult, SourceBusyCommand, SourceBusyResult, 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 SlotlockSubjectTable, type SlotlockTenantExportTable } from './types.js';
 import { type SlotlockAvailabilityDefaults, type SlotlockAvailabilityDefaultsResult, type SlotlockAvailabilityExceptionInput, type SlotlockOverrideResources, type SlotlockHolidayCalendar, type SlotlockHolidayImport } from './availability-store.js';
 import type { SlotlockAvailabilityException, SlotlockRankedException } from './hours.js';
 import type { SlotlockHoliday } from './holidays.js';
@@ -518,7 +520,10 @@ export interface SlotlockStore extends SlotlockEventFeed {
     }): Promise<{
         closures: number;
     } | null>;
-    /** Subscriptions due to be imported again, the longest waiting first. */
+    /**
+     * Subscriptions due to be imported again, each put off a day before it is read (maintenance):
+     * importing it sets its next import, so one a pass never finishes is not tried again at once.
+     */
     dueHolidayCalendars(params: {
         tenantRef: string;
         limit: number;
@@ -674,12 +679,19 @@ export interface SlotlockStore extends SlotlockEventFeed {
             amountMinor: number;
             currency: string;
         };
+        /**
+         * An agent's hold (RFC 0004 C3): its price is the resource's `holdPrice` booking rule, never its
+         * own. On a resource with one, it waits for that payment whatever it asks (and lives at most
+         * SLOTLOCK_PAYMENT_HOLD_MAX_TTL_MS); a `payment` other than that price is refused
+         * (`payment_price_mismatch`), as is any `payment` where the resource sets none.
+         */
+        priceFromRules?: boolean;
     }): Promise<AcquireHoldResult>;
     /**
      * Record that a hold waiting for payment is paid (RFC 0004 C3), by the payment's reference at the
      * integrator's processor: the integrator says so, or an adapter that verified it. Once paid it
      * may be confirmed. The same reference again answers the same hold, whatever became of it since
-     * (confirmed, booked, expired: the payment is kept apart); another is `payment_conflict`. The feed says so (`hold.paid`). A hold that does not wait for payment is
+     * (confirmed or booked from: the payment is kept apart), unless the hold ended without a booking (`hold_ended`: never applied, so refunded); another is `payment_conflict`, naming the one recorded. The feed says so (`hold.paid`). A hold that does not wait for payment is
      * `payment_not_required`; an expired one `hold_expired`; one confirmed, released or unknown
      * `hold_not_found`.
      */
@@ -731,6 +743,98 @@ export interface SlotlockStore extends SlotlockEventFeed {
         deleted: boolean;
         bookings: number;
     }>;
+    /**
+     * What the tenant keeps about one person (RFC 0004 D3, an access request): the rows that name
+     * them, as kept, by table (SLOTLOCK_SUBJECT_TABLES), up to `limit` (1-10,000, default 1,000) a
+     * table. It lists what eraseSubject would delete or take them out of; an event lists its time and
+     * title, and an approval its decision, never the other people they name.
+     */
+    exportSubject(params: {
+        tenantRef: string;
+        subject: SlotlockSubject;
+        limit?: number;
+    }): Promise<SlotlockSubjectExport>;
+    /**
+     * Take one person out of the tenant's data (RFC 0004 D3, an erasure request), in one transaction.
+     * Their contacts, attendee entries and waitlist entries are deleted; their email leaves events'
+     * attendee and organizer lists and approvals' requests; their holder reference and booking
+     * reference become one `erased-` name wherever they were (bookings, holds, ended bookings, the
+     * change history, approvals), and a contact's reference leaves them. Bookings stay, as time taken.
+     * Counts, by table, the rows deleted or changed.
+     */
+    eraseSubject(params: {
+        tenantRef: string;
+        subject: SlotlockSubject;
+    }): Promise<SlotlockSubjectErasure>;
+    /**
+     * Ask for a copy of everything the tenant keeps (RFC 0004 D3): a pending export, which
+     * buildTenantExport builds. Refused while another is pending (`export_in_progress`) or when the
+     * tenant keeps SLOTLOCK_MAX_TENANT_EXPORTS already (`export_limit_reached`).
+     */
+    createTenantExport(params: {
+        tenantRef: string;
+        requestedBy?: string;
+    }): Promise<SlotlockTenantExport>;
+    /**
+     * Build a pending export: every table of SLOTLOCK_TENANT_EXPORT_TABLES read through one cursor,
+     * so in one snapshot, into parts of one table's rows. Null when it is not pending, or another is
+     * building it. Throws `export_too_large` past SLOTLOCK_TENANT_EXPORT_MAX_BYTES, writing nothing.
+     */
+    buildTenantExport(params: {
+        tenantRef: string;
+        exportId: string;
+    }): Promise<SlotlockTenantExport | null>;
+    /** Mark a pending export failed, with why (`export_too_large`, `export_failed`). */
+    failTenantExport(params: {
+        tenantRef: string;
+        exportId: string;
+        error: string;
+    }): Promise<void>;
+    /** One of the tenant's exports, or null. */
+    getTenantExport(params: {
+        tenantRef: string;
+        exportId: string;
+    }): Promise<SlotlockTenantExport | null>;
+    /** The tenant's exports, newest first. */
+    listTenantExports(params: {
+        tenantRef: string;
+    }): Promise<SlotlockTenantExport[]>;
+    /** One part (1 to its `parts`) of a ready export. */
+    getTenantExportPart(params: {
+        tenantRef: string;
+        exportId: string;
+        part: number;
+    }): Promise<SlotlockTenantExportPartResult>;
+    /** Delete one of the tenant's exports at once. False when there was none. */
+    deleteTenantExport(params: {
+        tenantRef: string;
+        exportId: string;
+    }): Promise<boolean>;
+    /**
+     * Delete the tenant's exports past their time; and name those left pending for more than two
+     * minutes (their server stopped before building them), for maintenance to build.
+     */
+    pruneTenantExports(params: {
+        tenantRef: string;
+    }): Promise<{
+        deleted: number;
+        pending: string[];
+    }>;
+    /**
+     * Read everything the tenant keeps, as an export holds it, in one snapshot, without storing it
+     * (`slotlock tenant export`): each part (one table's rows) to `onPart` as it is read.
+     */
+    streamTenantExport(params: {
+        tenantRef: string;
+        onPart: (part: {
+            table: SlotlockTenantExportTable;
+            lines: string[];
+        }) => Promise<void>;
+    }): Promise<{
+        rows: number;
+        bytes: number;
+        tables: Record<string, number>;
+    }>;
     /** One of the tenant's live holds, or null (none, expired, confirmed, or another tenant's). */
     getHold(params: {
         tenantRef: string;
@@ -843,6 +947,19 @@ export interface SlotlockStore extends SlotlockEventFeed {
             holdId: string;
             holderRef: string;
         };
+        /**
+         * The agent it holds time for, and its key's caps (RFC 0004 A5): its pending approvals' holds
+         * count against its live-hold and held-hour caps with its own holds, so asking for approval
+         * never holds more than the agent could hold itself (`hold_limit_reached`,
+         * `held_time_limit_reached`). Kept on the approval's requester as `holder_ref`.
+         */
+        holder?: {
+            ref: string;
+            caps?: {
+                maxHolds?: number;
+                maxHeldHours?: number;
+            };
+        };
     }): Promise<{
         ok: true;
         approval: SlotlockApproval;
@@ -851,6 +968,10 @@ export interface SlotlockStore extends SlotlockEventFeed {
         ok: false;
         code: 'overlap' | 'approval_limit_reached' | 'idempotency_conflict';
         limit?: number;
+    } | {
+        ok: false;
+        code: 'hold_limit_reached' | 'held_time_limit_reached';
+        limit: number;
     }>;
     /** The approval a request key made, or null. */
     findApproval(params: {
@@ -1348,6 +1469,51 @@ export interface SlotlockStore extends SlotlockEventFeed {
         memberRef: string;
         chatId: string;
     }): Promise<boolean>;
+    /**
+     * Add an event to the tenant's audit log (slotlock.audit_events). The log is append-only for the
+     * serving role: nothing here changes or removes an event. Text past its column's bound is cut.
+     */
+    recordAuditEvent(params: {
+        tenantRef: string;
+        event: SlotlockAuditEventInput;
+    }): Promise<void>;
+    /**
+     * The tenant's audit events, newest first: up to `limit` (1-200, default 50), before the event
+     * `before` names, and only those of `action` or `actorRef` when given.
+     */
+    listAuditEvents(params: {
+        tenantRef: string;
+        limit?: number;
+        before?: {
+            occurredAt: Date;
+            id: string;
+        };
+        /** After the event with this id, at its exact time (the API's cursor); none if it was pruned. */
+        beforeId?: string;
+        action?: string;
+        actorRef?: string;
+    }): Promise<SlotlockAuditEvent[]>;
+    /** The tenant's hosted plan and its standing (slotlock.tenant_plan), or null when none applies. */
+    tenantPlan(params: {
+        tenantRef: string;
+    }): Promise<{
+        plan: string;
+        status: string;
+    } | null>;
+    /** Delete the tenant's audit events older than SLOTLOCK_AUDIT_RETENTION_DAYS; how many went. */
+    pruneAuditEvents(params: {
+        tenantRef: string;
+    }): Promise<number>;
+    /**
+     * Check the tenant's audit chain from its oldest event kept (slotlock.verify_audit_chain): how many
+     * events held, and the number of the first that does not (null when every one does).
+     */
+    verifyAuditChain(params: {
+        tenantRef: string;
+    }): Promise<{
+        checked: number;
+        brokenAt: number | null;
+    }>;
     /** Delete up to `limit` (default 1,000) of the tenant's expired assistant conversations: how many. */
     pruneAssistantConversations(params: {
         tenantRef: string;
@@ -1360,6 +1526,14 @@ export interface SlotlockStore extends SlotlockEventFeed {
     sweepAssistantConversations(params?: {
         limit?: number;
     }): Promise<number>;
+    /**
+     * Delete team workspace invitations finished (accepted, revoked or expired) more than 30 days ago,
+     * with the addresses they were sent to (slotlock.prune_workspace_invitations), requests to join
+     * decided a month ago and domain claims ended three months ago (slotlock.prune_workspace_domains), and dashboard
+     * sessions ended or expired a day ago (slotlock.prune_dashboard_sessions), and erase the team
+     * workspaces whose deletion came due (slotlock.erase_deleted_teams): how many.
+     */
+    sweepDashboardRecords(): Promise<number>;
     /**
      * Offer freed time to the waitlist in join order: each waiting entry whose window is free (on its
      * resource, or the first free pool member) gets a hold for its holder (`waitlist.offered`).
@@ -1520,6 +1694,96 @@ export interface SlotlockAssistantChatRecord extends SlotlockAssistantChatSummar
     /** When it is deleted unless used again; null when it is kept until the member deletes it. */
     expiresAt: Date | null;
 }
+/** What an audit event records (slotlock.audit_events): who did what, to what, from where. */
+export interface SlotlockAuditEventInput {
+    /** `<area>.<verb>`, such as `api_key.created` or `authz.denied`. */
+    action: string;
+    actorType: 'person' | 'api_key' | 'assistant' | 'system';
+    /** `github:<id>`, `google:<subject>`, `api_key:<id>`: a reference, never a name or an email. */
+    actorRef: string;
+    /** The actor's role in the workspace when it acted. */
+    actorRole?: SlotlockWorkspaceRole | null;
+    targetType?: string;
+    targetRef?: string;
+    outcome?: 'success' | 'denied';
+    reason?: string;
+    ipAddress?: string;
+    userAgent?: string;
+    /** Before-and-after values and the like: never a secret, a token or a key. */
+    metadata?: Record<string, unknown>;
+}
+/** An audit event as the API and `slotlock audit export` give it: snake_case, nulls kept. */
+export declare function slotlockAuditEventRecord(event: SlotlockAuditEvent): Record<string, unknown>;
+/**
+ * Whom an access or erasure request is about (RFC 0004 D3): one person, by exactly one of the
+ * identifiers Slotlock keeps for them. `email` matches contacts, event attendees and organizers
+ * (ignoring case); `holder` the holder reference on holds, bookings and waitlist entries;
+ * `contact` a contact's reference; `reference` a booking's or an event's reference.
+ */
+export type SlotlockSubject = {
+    email: string;
+} | {
+    holder: string;
+} | {
+    contact: string;
+} | {
+    reference: string;
+};
+/** What the tenant keeps about one person (exportSubject). */
+export interface SlotlockSubjectExport {
+    /** Each table's rows that name them, as kept (snake_case, without the tenant). */
+    records: Record<SlotlockSubjectTable, Record<string, unknown>[]>;
+    /** True when a table had more rows than the limit: its first ones are listed. */
+    truncated: boolean;
+}
+/** What an erasure did (eraseSubject): by table, the rows deleted or taken the person out of. */
+export interface SlotlockSubjectErasure {
+    erased: Record<SlotlockSubjectTable, number>;
+}
+/** Hours a tenant export is kept once ready, or since it was asked for if it never is. */
+export declare const SLOTLOCK_TENANT_EXPORT_HOURS = 24;
+/** The most a tenant export holds: past it, the export fails (`export_too_large`). */
+export declare const SLOTLOCK_TENANT_EXPORT_MAX_BYTES: number;
+/** The most exports a tenant keeps at once. */
+export declare const SLOTLOCK_MAX_TENANT_EXPORTS = 5;
+/** A part of an export: one table's rows, at most this many, or about this many bytes. */
+export declare const SLOTLOCK_TENANT_EXPORT_PART_ROWS = 5000;
+/** A copy of everything the tenant keeps (createTenantExport), as built or being built. */
+export interface SlotlockTenantExport {
+    id: string;
+    /** `pending` until it is built, then `ready`, or `failed` (`error` says why). */
+    status: 'pending' | 'ready' | 'failed';
+    requestedBy: string | null;
+    createdAt: Date;
+    finishedAt: Date | null;
+    /** When maintenance deletes it. */
+    expiresAt: Date;
+    parts: number;
+    rows: number;
+    bytes: number;
+    /** Rows by table (SLOTLOCK_TENANT_EXPORT_TABLES), for the tables with any. */
+    tables: Record<string, number>;
+    error: string | null;
+}
+/** One part of an export: one table's rows, each a JSON object as kept (NDJSON lines). */
+export type SlotlockTenantExportPartResult = {
+    ok: true;
+    table: SlotlockTenantExportTable;
+    lines: string[];
+} | {
+    ok: false;
+    code: 'export_not_found' | 'export_not_ready' | 'export_part_not_found';
+};
+/** An audit event as the log keeps it. */
+export interface SlotlockAuditEvent extends SlotlockAuditEventInput {
+    id: string;
+    occurredAt: Date;
+    outcome: 'success' | 'denied';
+    metadata: Record<string, unknown>;
+    /** Its place in the tenant's chain, and its SHA-256 (hex) over the one before and itself. */
+    chainIndex: number | null;
+    hash: string | null;
+}
 /** One entry of a tenant's waitlist (joinWaitlist). */
 export interface SlotlockWaitlistEntry {
     id: string;
@@ -1661,6 +1925,13 @@ export interface SlotlockHoldTenantOptions {
  * waiter out of the line, rejecting with its reason. Each holder calls the release it gets once.
  */
 export declare function createTenantSlots(max: number): (tenantRef: string, signal?: AbortSignal) => Promise<() => void>;
+/**
+ * Build a pending tenant export (RFC 0004 D3) in its own tenant transaction, and mark it failed if
+ * that fails (`export_too_large`, else `export_failed`). Null when it was not pending, or another
+ * server is building it. Never throws: a server builds it after answering, and maintenance builds
+ * one left pending.
+ */
+export declare function buildSlotlockTenantExport(store: SlotlockStore, tenantRef: string, exportId: string): Promise<SlotlockTenantExport | null>;
 export declare function createSlotlockStore(sql: StoreSql, options?: SlotlockStoreOptions): SlotlockStore;
 /**
  * Every store method that writes for a tenant: what a suspended tenant's withTenant store refuses.