slotlock 0.8.0 → 0.10.0

package/types.d.ts

@@ -5,6 +5,13 @@ export interface Interval {
     start: Date;
     end: Date;
 }
+/** Hours a resource without its own inherits, as the database resolves them (RFC 0004 B2). */
+export interface SlotlockInheritedAvailability {
+    source: 'location' | 'tenant';
+    /** The location whose hours apply, when `source` is `location`. */
+    location?: string;
+    rules: WeeklyAvailabilityRule[];
+}
 /** A schedulable resource (vehicle, room, worker, machine, or any other reservable asset). */
 export interface SlotlockResource {
     id: string;
@@ -22,6 +29,11 @@ export interface SlotlockResource {
      * uses the default (`SLOTLOCK_AVAILABILITY`, or the backend's `availabilityRules`).
      */
     availabilityRules?: WeeklyAvailabilityRule[];
+    /**
+     * The hours it inherits when it has none of its own (RFC 0004 B2): its location's, the nearest
+     * up the chain, else its tenant's. Absent when it has its own, or inherits the server's.
+     */
+    inheritedAvailability?: SlotlockInheritedAvailability;
     /**
      * `shared` resources are listed to and booked by agents; `private` ones are invisible to agents.
      * Fixed at creation; absent means shared.
@@ -89,6 +101,11 @@ export interface SlotlockApprovalPolicy {
     /** How long a person has to decide, before the booking's start less `leadMinutes`. */
     approvalTtlMinutes: number;
     leadMinutes: number;
+    /**
+     * It also holds the tenant's own bookings through the application API (bundles and pool
+     * bookings); without it, it holds only agents' (RFC 0004 B7).
+     */
+    includeApplication: boolean;
     createdAt: Date;
     updatedAt: Date;
 }
@@ -148,6 +165,12 @@ export interface SlotlockReservation {
     /** Monotonic command revision; legacy, hold, and shadow rows start at 1. */
     revision: number;
     source: string | null;
+    /** Whom to tell about it (RFC 0004 P3), when it names someone. */
+    contactRef?: string;
+    /** Present, and false, when no one should be notified about it. */
+    notify?: false;
+    /** Minutes before its start it is reminded, latest first, when it is. */
+    reminderMinutes?: number[];
 }
 export interface ExternalReservationCommand {
     tenantRef: string;
@@ -158,6 +181,34 @@ export interface ExternalReservationCommand {
     bufferAfterMs: number;
     revision: number;
     source?: string;
+    /**
+     * An admin's reason for moving the booking past its reschedule cutoff (RFC 0004 B5), kept on the
+     * feed. Without it, a move past the cutoff is refused.
+     */
+    overrideReason?: string;
+    /**
+     * The wall time the booking starts at in its resource's zone, `YYYY-MM-DDTHH:MM[:SS]` (RFC 0004
+     * B9): it must name `start` now, and if zone rules later move it, maintenance says so or follows
+     * it (`followZoneRules`). Left out, the booking keeps its instant only.
+     */
+    localStart?: string;
+    /**
+     * Whom to tell about it (RFC 0004 P3): a contact's reference (`putContact`), never the person.
+     * Put on the feed with each of its changes; a sender looks the person up by it.
+     */
+    contactRef?: string;
+    /** False: no sender should notify anyone about it (default true). On the feed only when false. */
+    notify?: boolean;
+    /**
+     * Minutes before its start to remind whom it names (RFC 0004 P3): up to five, each 0 to a year,
+     * said on the feed once each as `reminder.due` by maintenance, and again if the booking moves.
+     */
+    reminderMinutes?: number[];
+}
+/** What a cancellation records for the integrator to charge (RFC 0004 B5). Slotlock moves no money. */
+export interface SlotlockRecordedFee {
+    amountMinor: number;
+    currency: string;
 }
 export type ExternalReservationResult = {
     ok: true;
@@ -166,6 +217,14 @@ export type ExternalReservationResult = {
 } | {
     ok: false;
     code: 'invalid_window';
+}
+/** `localStart` is not a wall time, or does not name `start` in the resource's zone. */
+ | {
+    ok: false;
+    code: 'invalid_local_start';
+} | {
+    ok: false;
+    code: 'invalid_contact_ref' | 'invalid_notify' | 'invalid_reminders';
 } | {
     ok: false;
     code: 'invalid_buffer';
@@ -227,6 +286,13 @@ export type CancelExternalReservationResult = {
     ok: true;
     cancelled: boolean;
     revision: number;
+    cancellationFee?: SlotlockRecordedFee;
+}
+/** The booking's cancel cutoff has passed (RFC 0004 B5): an admin may override with a reason. */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: 'cancel_cutoff';
 } | {
     ok: false;
     code: 'invalid_identity';
@@ -317,6 +383,21 @@ export interface SlotlockHold {
     source: string | null;
     /** The alternatives it was held with (`groupId` when acquired); absent when held alone. */
     groupId?: string;
+    /** Present when it waits for payment (RFC 0004 C3): it is confirmed only once paid. */
+    paymentRequired?: true;
+    /** The payment's reference at the integrator's processor, once paid. */
+    paymentRef?: string | null;
+    paidAt?: Date | null;
+    /** What the payment must be, when the hold names it. */
+    paymentAmount?: {
+        amountMinor: number;
+        currency: string;
+    } | null;
+    /** What was received, once paid and when the payer said. */
+    paidAmount?: {
+        amountMinor: number;
+        currency: string;
+    } | null;
 }
 /** One entry of a tenant's agenda (`listAgenda`): what occupies a resource, and from when. */
 export interface SlotlockAgendaEntry {
@@ -345,6 +426,16 @@ export type AcquireHoldResult =
 } | {
     ok: false;
     code: 'invalid_ttl';
+}
+/** `payment` without `paymentRequired`, or not an amount and an ISO 4217 currency. */
+ | {
+    ok: false;
+    code: 'invalid_payment';
+}
+/** An agent's `payment` that is not the resource's hold price, or where it sets none. */
+ | {
+    ok: false;
+    code: 'payment_price_mismatch';
 } | {
     ok: false;
     code: 'invalid_buffer';
@@ -412,6 +503,16 @@ export type ConfirmHoldResult = {
     ok: false;
     code: 'hold_expired';
 }
+/** The hold waits for payment (RFC 0004 C3) and none is recorded yet (markHoldPaid). */
+ | {
+    ok: false;
+    code: 'payment_required';
+}
+/** A calendar reported its time busy (RFC 0004 C1) after the hold was made. */
+ | {
+    ok: false;
+    code: 'overlap';
+}
 /** A cancellation of the hold's reference (its id) arrived first and retired it. */
  | {
     ok: false;
@@ -437,6 +538,77 @@ export type ReleaseHoldResult = {
     ok: true;
     released: boolean;
 };
+/**
+ * A person a booking may name to be told about it (RFC 0004 P3), by the tenant's own reference: how
+ * to reach them, and which channels they agreed to. A sender reads it; Slotlock sends nothing.
+ */
+export interface SlotlockContact {
+    ref: string;
+    name: string | null;
+    email: string | null;
+    /** E.164, for SMS. */
+    phone: string | null;
+    /** E.164, for WhatsApp. */
+    whatsapp: string | null;
+    /** Each channel the person said yes or no to; a channel left out has no answer recorded. */
+    consent: SlotlockContactConsent;
+    /** When each answer in `consent` was given (kept while it stands): the proof of it. */
+    consentAt: Partial<Record<keyof SlotlockContactConsent, Date>>;
+    /** BCP 47, for the language of what is sent. */
+    locale: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface SlotlockContactConsent {
+    email?: boolean;
+    sms?: boolean;
+    whatsapp?: boolean;
+}
+export type PutContactResult = {
+    ok: true;
+    contact: SlotlockContact;
+    created: boolean;
+} | {
+    ok: false;
+    code: 'invalid_contact_ref' | 'invalid_contact';
+} | {
+    ok: false;
+    code: 'contact_limit_reached';
+    limit: number;
+};
+/** Recording a hold's payment (RFC 0004 C3); `idempotent` when it was recorded already. */
+export type MarkHoldPaidResult = {
+    ok: true;
+    hold: SlotlockHold;
+    idempotent: boolean;
+} | {
+    ok: false;
+    code: 'invalid_identity' | 'invalid_payment_ref' | 'invalid_payment';
+}
+/** Less than the hold's payment, in another currency, or not said when the hold names one. */
+ | {
+    ok: false;
+    code: 'payment_amount_mismatch';
+} | {
+    ok: false;
+    code: 'hold_not_found' | 'hold_expired';
+}
+/** Paid, but the hold ended without a booking: the payment was never applied. */
+ | {
+    ok: false;
+    code: 'hold_ended';
+}
+/** The hold does not wait for payment. */
+ | {
+    ok: false;
+    code: 'payment_not_required';
+}
+/** It was already paid by another payment, `paymentRef`. */
+ | {
+    ok: false;
+    code: 'payment_conflict';
+    paymentRef: string;
+};
 /** RFC 5545 TRANSP projection. Transparent events remain visible but never occupy a resource. */
 export type CalendarTransparency = 'opaque' | 'transparent';
 export type CalendarEventStatus = 'confirmed' | 'tentative';
@@ -543,6 +715,11 @@ export interface PutCalendarEventCommand extends CalendarEventContent {
         holdId: string;
         holderRef: string;
     };
+    /**
+     * False: no sender should notify anyone about it (RFC 0004 P3), and its reminders are not put on
+     * the feed. Default true; as sent with each revision.
+     */
+    notify?: boolean;
 }
 export type PutCalendarEventResult = {
     ok: true;
@@ -604,6 +781,11 @@ export type PutCalendarEventResult = {
     ok: false;
     code: 'hold_expired';
 }
+/** `fromHold`'s hold waits for payment (RFC 0004 C3) and none is recorded yet. */
+ | {
+    ok: false;
+    code: 'payment_required';
+}
 /** `fromHold`'s hold is on another resource, or does not cover the event. */
  | {
     ok: false;
@@ -644,6 +826,8 @@ export type CancelCalendarEventResult = {
     externalRef: string;
     revision: number;
     idempotent: boolean;
+    /** What a late cancellation costs, recorded for the integrator to charge (RFC 0004 B5). */
+    cancellationFee?: SlotlockRecordedFee;
 } | {
     ok: false;
     code: 'invalid_identity';
@@ -664,6 +848,12 @@ export type CancelCalendarEventResult = {
     ok: false;
     code: 'revision_conflict';
     currentRevision: number;
+}
+/** The event's cancel cutoff has passed (RFC 0004 B5). */
+ | {
+    ok: false;
+    code: 'booking_rule_violated';
+    rule: 'cancel_cutoff';
 };
 /** A place in the roll's order of due masters: the last one a batch examined. */
 export interface CalendarHorizonRollCursor {
@@ -763,6 +953,30 @@ export type CalendarCoverageResult = {
     code: 'coverage_limit_reached';
     limit: number;
 };
+/**
+ * What a calendar that gives busy time but not its events says (Google freeBusy, Microsoft
+ * getSchedule; RFC 0004 C1): its coverage of the window, and the busy time in it, which replaces
+ * what the source said of that window before.
+ */
+export interface SourceBusyCommand extends CalendarCoverageCommand {
+    /** At most SLOTLOCK_SOURCE_BUSY_MAX intervals; clipped to the window and merged. */
+    busy: Interval[];
+}
+export type SourceBusyResult = {
+    ok: true;
+    revision: number;
+    /** A revision already recorded: nothing changed. */
+    idempotent: boolean;
+    /** How many intervals are kept, merged and clipped. */
+    busy: number;
+    /** Bookings the source newly reports in the way of, each put on the feed as coverage.conflict. */
+    conflicts: number;
+} | Exclude<CalendarCoverageResult, {
+    ok: true;
+}> | {
+    ok: false;
+    code: 'invalid_busy';
+};
 export interface CalendarCoverageAssessment {
     state: 'complete' | 'partial' | 'unknown';
     /** Required sources that are absent, stale, or do not fully cover the requested window. */
@@ -772,3 +986,19 @@ export interface CalendarFreeBusy {
     busy: Interval[];
     coverage: CalendarCoverageAssessment;
 }
+/**
+ * The tables a subject export lists and an erasure counts (RFC 0004 D3), in that order: what can
+ * name one person.
+ */
+export declare const SLOTLOCK_SUBJECT_TABLES: readonly ["contacts", "calendar_event_attendees", "calendar_events", "reservations", "reservation_tombstones", "reservation_conflict_archive", "calendar_event_tombstones", "calendar_event_commands", "waitlist_entries", "approvals", "outbox"];
+export type SlotlockSubjectTable = (typeof SLOTLOCK_SUBJECT_TABLES)[number];
+/**
+ * What a tenant export holds (RFC 0004 D3), in this order: each table's rows as kept, without the
+ * tenant and without secrets (a webhook's signing secret, the assistant's sealed provider key, API
+ * key digests: `api_keys` is each key's name, prefix, scopes and dates). Every other tenant table
+ * is in SLOTLOCK_TENANT_EXPORT_LEFT_OUT, with why.
+ */
+export declare const SLOTLOCK_TENANT_EXPORT_TABLES: readonly ["resources", "locations", "resource_groups", "resource_group_members", "pool_settings", "booking_rule_defaults", "availability_defaults", "availability_exceptions", "holiday_calendars", "reservations", "reservation_tombstones", "reservation_conflict_archive", "hold_payments", "calendar_events", "calendar_event_attendees", "calendar_event_reminders", "calendar_event_exceptions", "calendar_event_tombstones", "calendar_coverage", "source_busy", "waitlist_entries", "approval_policies", "approvals", "contacts", "webhook_endpoints", "assistant_settings", "api_keys", "outbox", "audit_events"];
+export type SlotlockTenantExportTable = (typeof SLOTLOCK_TENANT_EXPORT_TABLES)[number];
+/** The tenant tables an export leaves out, and why: each is derived, internal or one member's own. */
+export declare const SLOTLOCK_TENANT_EXPORT_LEFT_OUT: Readonly<Record<string, string>>;

package/types.js

@@ -1 +1,68 @@
-export {};
+/**
+ * The tables a subject export lists and an erasure counts (RFC 0004 D3), in that order: what can
+ * name one person.
+ */
+export const SLOTLOCK_SUBJECT_TABLES = Object.freeze([
+    'contacts',
+    'calendar_event_attendees',
+    'calendar_events',
+    'reservations',
+    'reservation_tombstones',
+    'reservation_conflict_archive',
+    'calendar_event_tombstones',
+    'calendar_event_commands',
+    'waitlist_entries',
+    'approvals',
+    'outbox',
+]);
+/**
+ * What a tenant export holds (RFC 0004 D3), in this order: each table's rows as kept, without the
+ * tenant and without secrets (a webhook's signing secret, the assistant's sealed provider key, API
+ * key digests: `api_keys` is each key's name, prefix, scopes and dates). Every other tenant table
+ * is in SLOTLOCK_TENANT_EXPORT_LEFT_OUT, with why.
+ */
+export const SLOTLOCK_TENANT_EXPORT_TABLES = Object.freeze([
+    'resources',
+    'locations',
+    'resource_groups',
+    'resource_group_members',
+    'pool_settings',
+    'booking_rule_defaults',
+    'availability_defaults',
+    'availability_exceptions',
+    'holiday_calendars',
+    'reservations',
+    'reservation_tombstones',
+    'reservation_conflict_archive',
+    'hold_payments',
+    'calendar_events',
+    'calendar_event_attendees',
+    'calendar_event_reminders',
+    'calendar_event_exceptions',
+    'calendar_event_tombstones',
+    'calendar_coverage',
+    'source_busy',
+    'waitlist_entries',
+    'approval_policies',
+    'approvals',
+    'contacts',
+    'webhook_endpoints',
+    'assistant_settings',
+    'api_keys',
+    'outbox',
+    'audit_events',
+]);
+/** The tenant tables an export leaves out, and why: each is derived, internal or one member's own. */
+export const SLOTLOCK_TENANT_EXPORT_LEFT_OUT = Object.freeze({
+    calendar_event_occurrences: "derived from each event's time and recurrence",
+    calendar_event_commands: 'records of retried writes',
+    hold_commands: 'records of retried writes',
+    outbox_pruned: 'where the history was last pruned to',
+    composite_claims: 'derived from bookings',
+    reminder_dispatches: 'which reminders were put on the feed',
+    reservation_reminder_dispatches: 'which reminders were put on the feed',
+    assistant_conversations: "each member's own conversations with the assistant",
+    assistant_chats: "each member's own conversations with the assistant",
+    tenant_exports: 'the exports themselves',
+    tenant_export_parts: 'the exports themselves',
+});

package/workspace-domains.d.ts

@@ -0,0 +1,146 @@
+import { type SlotlockDnsResolver, type SlotlockDomainCheck } from './domains.js';
+import type { SlotlockAuditEventInput, SlotlockSql } from './store.js';
+import { type SlotlockWorkspaceRole } from './workspace-roles.js';
+/** Why a change to a team's domains, or a request to join, was refused. */
+export type SlotlockDomainChangeRefusal = 'invalid_domain' | 'public_suffix' | 'consumer_domain' | 'not_found' | 'not_allowed' | 'already_claimed' | 'domain_taken' | 'domain_limit' | 'too_soon' | 'expired' | 'restricted' | 'no_verified_domain' | 'already_member' | 'pending' | 'request_limit' | 'member_cap' | 'role_not_allowed' | 'domain_not_verified';
+/**
+ * How the addresses a person brings were verified: by a Google Workspace account of their domain
+ * (Google's `hd` claim; the company controls it), or by a Google or GitHub account that verified the
+ * address once and never checks again. Only the first may join at once.
+ */
+export type SlotlockJoinEvidence = 'google_workspace' | 'google' | 'github';
+/** What a domain lets the people whose verified address is at it do. */
+export type SlotlockDomainJoinPolicy = 'off' | 'request' | 'auto';
+/** A team's domain as its Identity page shows it. */
+export interface SlotlockWorkspaceDomain {
+    id: string;
+    ascii: string;
+    unicode: string;
+    /** `pending` (with `expired` past its seven days), `verified`, or `lapsing` (its record has gone). */
+    status: 'pending' | 'verified' | 'lapsing';
+    expired: boolean;
+    /** The token the record must hold: public, since it is published. */
+    token: string;
+    joinPolicy: SlotlockDomainJoinPolicy;
+    createdAt: Date;
+    verifiedAt: Date | null;
+    lastCheckedAt: Date | null;
+    missingSince: Date | null;
+    errorSince: Date | null;
+    lapseAfter: Date | null;
+}
+/** A team a person may ask to join, or join, through a verified address. */
+export interface SlotlockDiscoverableWorkspace {
+    tenantRef: string;
+    handle: string;
+    name: string;
+    /** As people read it. */
+    domain: string;
+    /** As addresses are matched on it (ASCII). */
+    domainKey: string;
+    joinPolicy: 'request' | 'auto';
+    requested: boolean;
+}
+/** A request waiting on a team. */
+export interface SlotlockJoinRequest {
+    id: string;
+    person: string;
+    display: string | null;
+    email: string;
+    domain: string;
+    createdAt: Date;
+    expiresAt: Date;
+    evidence: SlotlockJoinEvidence;
+}
+/** What one claim's check did, for the audit log and the people told. */
+export interface SlotlockDomainCheckOutcome {
+    domainId: string;
+    tenantRef: string | null;
+    domain: string | null;
+    /**
+     * `verified`, `restored` (a lapsing domain's new record found), `seen` (still there), `missing`
+     * (gone once), `lapsing` (gone a day: a new token issued), `lapsed`, `absent` (a pending claim's
+     * record not there yet), `unchanged`, `error`; or a refusal: `domain_taken`, `too_soon`,
+     * `expired`, `not_found`, `not_allowed`.
+     */
+    outcome: string;
+    check: SlotlockDomainCheck | null;
+}
+export interface SlotlockWorkspaceDomains {
+    /** Claim a domain for a team (its Owner), with a new token. The domain as typed: normalised here. */
+    claim(tenantRef: string, actor: string, typed: string): Promise<{
+        id: string;
+    } | {
+        refusal: SlotlockDomainChangeRefusal;
+    }>;
+    list(tenantRef: string): Promise<SlotlockWorkspaceDomain[]>;
+    /** An Owner's "Verify now": the record looked up and the outcome applied (at most once a minute). */
+    verifyNow(tenantRef: string, actor: string, id: string, resolvers: readonly SlotlockDnsResolver[]): Promise<SlotlockDomainCheckOutcome>;
+    /**
+     * The daily check: up to `limit` claims due, each looked up and applied. `seen` is told each claim's
+     * missing_since before its check (null when its record was there at the last one).
+     */
+    checkDue(resolvers: readonly SlotlockDnsResolver[], limit?: number, seen?: (id: string, missingSince: Date | null) => void): Promise<SlotlockDomainCheckOutcome[]>;
+    release(tenantRef: string, actor: string, id: string): Promise<SlotlockDomainChangeRefusal | null>;
+    restrictInvites(tenantRef: string, actor: string, on: boolean): Promise<SlotlockDomainChangeRefusal | null>;
+    /** Whether a team's invitations are held to its verified domains. */
+    invitesRestricted(tenantRef: string): Promise<boolean>;
+    setJoinPolicy(tenantRef: string, actor: string, id: string, policy: SlotlockDomainJoinPolicy): Promise<SlotlockDomainChangeRefusal | null>;
+    /** The teams a person's verified addresses let them ask to join. */
+    discoverable(person: string, emails: readonly string[]): Promise<SlotlockDiscoverableWorkspace[]>;
+    requestToJoin(tenantRef: string, person: string, emails: readonly string[], evidence: SlotlockJoinEvidence, memberCap: number | null): Promise<{
+        outcome: 'joined' | 'requested';
+    } | {
+        refusal: SlotlockDomainChangeRefusal;
+    }>;
+    requests(tenantRef: string): Promise<SlotlockJoinRequest[]>;
+    decide(params: {
+        tenantRef: string;
+        actor: string;
+        id: string;
+        decision: 'approve' | 'decline';
+        role: SlotlockWorkspaceRole | null;
+        memberCap: number | null;
+    }): Promise<{
+        person: string | null;
+        refusal: SlotlockDomainChangeRefusal | null;
+    }>;
+    /** Members a domain let in: with the domain, and whether the team still holds it. */
+    domainMembers(tenantRef: string): Promise<Map<string, {
+        domain: string;
+        status: string;
+    }>>;
+    prune(): Promise<number>;
+}
+/**
+ * The addresses as matched: lowercase, the domain in its ASCII form, the domain claimable at all
+ * (a consumer address matches no team). At most ten.
+ */
+export declare function slotlockMatchableEmails(emails: readonly string[]): string[];
+/** Through the functions of ddl-identity.ts. */
+export declare function createSlotlockWorkspaceDomains(sql: SlotlockSql): SlotlockWorkspaceDomains;
+/** The role a request may be approved as: Viewer, Member or Developer. */
+export declare function slotlockJoinRole(value: string | null): SlotlockWorkspaceRole | null;
+/** The audit log's actions for a team's domains (its Identity group). */
+export declare const SLOTLOCK_DOMAIN_AUDIT_ACTIONS: readonly ["domain.claimed", "domain.verified", "domain.record_missing", "domain.lapsing", "domain.restored", "domain.lapsed", "domain.released", "domain.join_policy_changed", "workspace.invites_restricted", "workspace.invites_unrestricted"];
+/**
+ * The audit event a check that changed something records: which domain, and what each resolver said
+ * (public DNS data). A domain gone for the first time is recorded once (`missing` while it had been
+ * seen); repeats and checks that changed nothing are not.
+ */
+export declare function slotlockDomainCheckEvent(found: SlotlockDomainCheckOutcome, firstMissing: boolean): {
+    action: string;
+    targetType: 'domain';
+    targetRef: string;
+    metadata: Record<string, unknown>;
+} | null;
+/**
+ * The daily check, from the server's maintenance: the claims due looked up and applied, each change
+ * recorded in its team's audit log as Slotlock's. How many were checked.
+ */
+export declare function runSlotlockDomainChecks(params: {
+    domains: SlotlockWorkspaceDomains;
+    resolvers: readonly SlotlockDnsResolver[];
+    record?: (tenantRef: string, event: SlotlockAuditEventInput) => Promise<void>;
+    limit?: number;
+}): Promise<number>;