slotlock 0.2.0 → 0.5.0

package/dashboard.d.ts

@@ -1,9 +1,14 @@
 import type { SlotlockApiKeyStore } from './api-keys.js';
-import type { SlotlockSql, SlotlockStore } from './store.js';
-import type { SlotlockResource, WeeklyAvailabilityRule } from './types.js';
+import { type SlotlockBookingRules } from './booking-rules.js';
+import { type CreateWebhookEndpointResult, type SlotlockChange, type SlotlockWebhookEndpoint } from './event-feed.js';
+import type { SlotlockSql, SlotlockStore, SlotlockWaitlistEntry } from './store.js';
+import type { Interval, SlotlockAgendaEntry, SlotlockResource, WeeklyAvailabilityRule } from './types.js';
 /** Resources one dashboard tenant may hold. */
 export declare const SLOTLOCK_DASHBOARD_MAX_RESOURCES = 100;
-/** A tenant's calendar resources, as the dashboard lists and adds them. */
+/**
+ * A tenant's calendar resources, as the dashboard lists and adds them. Each write takes, last, the
+ * person who made it (`github:<user id>`) as `actor`, to record on the event feed.
+ */
 export interface SlotlockDashboardResources {
     list(tenantRef: string): Promise<SlotlockResource[]>;
     /**
@@ -11,7 +16,7 @@ export interface SlotlockDashboardResources {
      * (an error with `code: 'resource_limit_reached'`) once the tenant has
      * SLOTLOCK_DASHBOARD_MAX_RESOURCES, however many adds race, on however many servers.
      */
-    add(tenantRef: string, externalRef: string, timezone: string): Promise<SlotlockResource>;
+    add(tenantRef: string, externalRef: string, timezone: string, actor?: string): Promise<SlotlockResource>;
     /**
      * Set the bookable hours of one of the tenant's resources (`{ id }`) or of all of them; `null`
      * hands them back to the server's and `[]` closes. Returns how many resources changed: 0 for an
@@ -19,7 +24,32 @@ export interface SlotlockDashboardResources {
      */
     setHours(tenantRef: string, target: {
         id: string;
-    } | 'all', rules: WeeklyAvailabilityRule[] | null): Promise<number>;
+    } | 'all', rules: WeeklyAvailabilityRule[] | null, actor?: string): Promise<number>;
+    /** What occupies the tenant's resources in `window`, by start: the overview's agenda. */
+    agenda?(tenantRef: string, window: Interval, limit: number): Promise<SlotlockAgendaEntry[]>;
+    /** The tenant's latest changes, newest first: the overview's activity. */
+    recentChanges?(tenantRef: string, limit: number): Promise<SlotlockChange[]>;
+    /**
+     * Set the booking rules of one of the tenant's resources (null clears them): the resource, or
+     * null when it is not the tenant's. Invalid rules throw with `code: 'invalid_booking_rules'`.
+     */
+    setRules?(tenantRef: string, id: string, rules: SlotlockBookingRules | null, actor?: string): Promise<SlotlockResource | null>;
+    /** Put one of the tenant's resources in a pool, or none: as setRules; `code: 'invalid_pool'`. */
+    setPool?(tenantRef: string, id: string, pool: string | null, actor?: string): Promise<SlotlockResource | null>;
+    /** The tenant's waitlist, oldest first, and leaving it (false when the entry is not the tenant's). */
+    waitlist?: {
+        list(tenantRef: string, limit: number): Promise<SlotlockWaitlistEntry[]>;
+        leave(tenantRef: string, id: string, actor?: string): Promise<boolean>;
+    };
+    /** The tenant's webhook endpoints, as the event feed keeps them. */
+    webhooks?: {
+        list(tenantRef: string): Promise<SlotlockWebhookEndpoint[]>;
+        create(tenantRef: string, url: string, eventTypes: readonly string[] | undefined, actor?: string): Promise<CreateWebhookEndpointResult>;
+        remove(tenantRef: string, id: string, actor?: string): Promise<boolean>;
+        enable(tenantRef: string, id: string, actor?: string): Promise<SlotlockWebhookEndpoint | null | {
+            code: 'changes_pruned';
+        }>;
+    };
 }
 /**
  * What the dashboard records so a sign-in callback works once, a sent form runs once and a
@@ -47,6 +77,8 @@ export interface SlotlockDashboardState {
 export interface SlotlockDashboardOptions {
     /** Where people reach the server; the dashboard lives at `<publicUrl>/dashboard`. */
     publicUrl: string;
+    /** What the deployment is called in the dashboard: 1-60 characters. Defaults to `Slotlock`. */
+    name?: string;
     /**
      * Where agents reach the server's MCP and A2A endpoints, which the dashboard shows, when it is
      * served from another origin (on Cloudflare Workers, with the server elsewhere). Defaults to
@@ -63,11 +95,23 @@ export interface SlotlockDashboardOptions {
         authorizeUrl?: string;
         tokenUrl?: string;
         userUrl?: string;
+        membershipsUrl?: string;
     };
     /** Seals sessions and sign-in state and derives CSRF tokens: 32+ random characters. */
     sessionSecret: string;
     /** GitHub user ids (numbers, as strings) that may sign in, or `'*'` for every GitHub account. */
     allowedUsers: '*' | readonly string[];
+    /**
+     * GitHub organization ids (numbers, as strings) this dashboard serves. With them, a tenant is an
+     * organization (`github-org:<id>`), not a person: sign-in asks for `read:org`, and a person signs
+     * in to the served organizations they are an active member of, sharing each one's keys and
+     * resources with its other members: owners and members, not billing managers, from the first
+     * 100 memberships GitHub lists, up to 20 served organizations. Membership is read at each sign-in; leaving an organization
+     * ends access at the next sign-in, at most a session (12 hours) later, and removing an
+     * organization from this list signs its sessions out at once. Without it, each person is their
+     * own tenant (`github:<id>`).
+     */
+    organizations?: readonly string[];
     keys: SlotlockApiKeyStore;
     resources: SlotlockDashboardResources;
     /** Shared by every server behind this origin: see SlotlockDashboardState. */
@@ -76,6 +120,12 @@ export interface SlotlockDashboardOptions {
     availability?: readonly WeeklyAvailabilityRule[];
     fetch?: typeof fetch;
     now?: () => number;
+    /**
+     * The address a request came from, as the server counts its clients (the socket's, or a trusted
+     * proxy's field such as CF-Connecting-IP), so one client's sign-ins in flight are capped below
+     * every client's. Without it, or when it returns undefined, only the cap on every client applies.
+     */
+    clientAddress?: (request: Request) => string | undefined;
     /**
      * Called with whatever a request handler throws; the person sees a generic error page. Not
      * awaited; what it throws, or its promise rejects with, is ignored.
@@ -92,6 +142,18 @@ export interface SlotlockDashboard {
  * in the database (a READ COMMITTED transaction, under a per-tenant lock).
  */
 export declare function createSlotlockDashboardResources(store: SlotlockStore): SlotlockDashboardResources;
+/**
+ * Records accepted write confirmations (`SlotlockAgentConfirmationOptions.consumeAcceptance`) in
+ * Postgres, shared by every server on the database: true the first time a confirmation's nonce is
+ * recorded, false while it stays recorded, so an accepted confirmation runs its write once on any
+ * server. Kept until the confirmation's own expiry, through the same function and table as the
+ * dashboard's records (only a SHA-256 digest of the nonce is stored); pass a client, not a
+ * transaction.
+ */
+export declare function createSlotlockAcceptanceRecords(sql: SlotlockSql): (acceptance: {
+    nonce: string;
+    expiresAt: Date;
+}) => Promise<boolean>;
 /**
  * The dashboard's records in Postgres, shared by every server on the database. Run `applySchema()`
  * and `grantApplicationRole()` first: the serving role reaches the records only through