slotlock 0.6.3 → 0.7.0

package/dashboard.d.ts

@@ -1,19 +1,28 @@
-import type { SlotlockApiKeyStore } from './api-keys.js';
-import { type SlotlockAgentCalendarBackend, type SlotlockAgentOperation, type SlotlockAgentOperationDispatchOptions, type SlotlockAgentPrincipal } from './agent-server.js';
+import type { SlotlockDashboardTeams } from './teams.js';
+import { type SlotlockApiKeyStore } from './api-keys.js';
+import { type SlotlockAgentCalendarBackend, type SlotlockAgentOperation, type SlotlockAgentOperationDispatchOptions, type SlotlockAgentPrincipal, type SlotlockAgentUsage } from './agent-server.js';
 import { type SlotlockAssistantStore } from './assistant.js';
 import { type SlotlockRate } from './config.js';
 import { type SlotlockBookingRules } from './booking-rules.js';
+import { type SlotlockTenantPlan } from './plans.js';
+import { type SlotlockLocation, type SlotlockResourceGroup, type SlotlockResourceProfileInput } from './resource-profile.js';
+import { type SlotlockUsageRow } from './usage.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, SlotlockBookingRuleDefaults, WeeklyAvailabilityRule } from './types.js';
+import { type SlotlockSandboxScenario } from './sandbox.js';
+import type { Interval, SlotlockAgendaEntry, SlotlockApproval, SlotlockResource, SlotlockBookingRuleDefaults, WeeklyAvailabilityRule } from './types.js';
 /** Resources one dashboard tenant may hold. */
-export declare const SLOTLOCK_DASHBOARD_MAX_RESOURCES = 100;
+export declare const SLOTLOCK_DASHBOARD_MAX_RESOURCES = 500;
 /**
  * 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[]>;
+    /** How many resources the tenant has, archived ones included, as a resource limit counts them. */
+    count?(tenantRef: string): Promise<number>;
+    /** The tenant's metered usage from `from` to `to`, UTC days inclusive (usage.ts). */
+    usage?(tenantRef: string, from: string, to: string): Promise<SlotlockUsageRow[]>;
     /**
      * Create the resource, or re-zone the tenant's resource with that reference. Refuse a new one
      * (an error with `code: 'resource_limit_reached'`) once the tenant has
@@ -39,8 +48,84 @@ export interface SlotlockDashboardResources {
     setRules?(tenantRef: string, id: string, rules: SlotlockBookingRules | null, actor?: string): Promise<SlotlockResource | null>;
     /** The tenant's default booking rules and its pools', which a resource's own rules overlay. */
     ruleDefaults?(tenantRef: string): Promise<SlotlockBookingRuleDefaults>;
+    /**
+     * Change one of the tenant's resources' profile (resource-profile.ts): the fields given, keeping
+     * the rest. As setRules; `code: 'invalid_resource_profile'`, with the `field`.
+     */
+    setProfile?(tenantRef: string, id: string, profile: SlotlockResourceProfileInput, actor?: string): Promise<SlotlockResource | null>;
+    /**
+     * Make one of the tenant's resources a part of a composite (RFC 0003 G8), or no part. A refusal
+     * carries the store's `code`: `parent_not_found`, `composite_too_deep`, `composite_parts_limit`
+     * or `composite_busy`.
+     */
+    setParent?(tenantRef: string, id: string, parentId: string | 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 locations and groups (RFC 0003 G2, G3), and where each resource is in them. A
+     * refusal carries the store's `code`: `invalid_location` or `invalid_group` (with the `field`),
+     * `location_not_found`, `location_too_deep`, `location_cycle`, `location_limit_reached`,
+     * `location_in_use`, `group_not_found`, `group_limit_reached` or `resource_group_limit_reached`.
+     */
+    grouping?: {
+        /** Each under its parent, depth first, with how many resources are at each. */
+        locations(tenantRef: string): Promise<SlotlockLocation[]>;
+        /** Create the location with this reference, or change its name, parent and time zone. */
+        putLocation(tenantRef: string, location: {
+            ref: string;
+            name: string;
+            parentRef: string | null;
+            timezone: string | null;
+        }, actor?: string): Promise<SlotlockLocation>;
+        /** False when the tenant has no such location. */
+        deleteLocation(tenantRef: string, ref: string, actor?: string): Promise<boolean>;
+        /** By reference, with how many resources are in each. */
+        groups(tenantRef: string): Promise<SlotlockResourceGroup[]>;
+        /** Create the group with this reference, or change its name and description. */
+        putGroup(tenantRef: string, group: {
+            ref: string;
+            name: string;
+            description: string | null;
+        }, actor?: string): Promise<SlotlockResourceGroup>;
+        /** Delete a group, its resources left as they are: false when the tenant has no such group. */
+        deleteGroup(tenantRef: string, ref: string, actor?: string): Promise<boolean>;
+        /**
+         * Put one of the tenant's resources at a location (or none) and in exactly these groups, in one
+         * transaction: the resource as it then is, or null when it is not the tenant's.
+         */
+        place(tenantRef: string, id: string, place: {
+            location: string | null;
+            groups: readonly string[];
+        }, actor?: string): Promise<SlotlockResource | null>;
+    };
+    /**
+     * The tenant's approvals (RFC 0004 A4), newest first, and deciding one: a grant makes the booking
+     * as the agent asked for it; a refusal says why (approval_not_pending, overlap, a booking rule).
+     */
+    approvals?: {
+        list(tenantRef: string, limit: number): Promise<SlotlockApproval[]>;
+        decide(tenantRef: string, id: string, decision: 'grant' | 'decline', actor?: string, reason?: string): Promise<{
+            ok: true;
+        } | {
+            ok: false;
+            code: string;
+        }>;
+    };
+    /**
+     * The sandbox (RFC 0004 A6), for a test environment only: fill it with a scenario, empty it, and
+     * make what would lapse within some minutes lapse now. Each refuses a live tenant.
+     */
+    sandbox?: {
+        seed(tenantRef: string, scenario: SlotlockSandboxScenario): Promise<{
+            resources: number;
+            bookings: number;
+        }>;
+        reset(tenantRef: string): Promise<void>;
+        fastForward(tenantRef: string, minutes: number): Promise<{
+            holds: number;
+            approvals: number;
+        }>;
+    };
     /** 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[]>;
@@ -91,6 +176,18 @@ export interface SlotlockDashboardState {
 export interface SlotlockDashboardAssistantOptions {
     /** Seals each tenant's API key (SLOTLOCK_ASSISTANT_SECRET): 32+ random characters. */
     secret: string;
+    /**
+     * Secrets keys may still be sealed under (SLOTLOCK_ASSISTANT_PREVIOUS_SECRETS), newest first, at
+     * most SLOTLOCK_ASSISTANT_MAX_PREVIOUS_SECRETS: a key one of them opens is used, and sealed again
+     * under `secret` in the same request, so changing the secret makes no owner enter a key again.
+     * Drop an old secret once every tenant has used the assistant since the change, or keys still
+     * sealed under it stop opening.
+     */
+    previousSecrets?: readonly string[];
+    /** Each operation the assistant runs, for usage metering (the agent server's `onUsage`). */
+    onUsage?: (usage: SlotlockAgentUsage) => void;
+    /** Each message a member sends that the assistant answers, for usage metering. Never awaited. */
+    onMessage?: (tenantRef: string) => void;
     backend: SlotlockAgentCalendarBackend;
     /**
      * As the agent server's: false refuses an operation. Every offered operation by default. It also
@@ -135,11 +232,70 @@ export interface SlotlockDashboardAssistantOptions {
     /** How long a conversation is kept after its last message: 2 hours by default. */
     conversationTtlMs?: number;
 }
+/**
+ * Hosted Slotlock's plans (plans.ts) and their billing: a Plan page with the tenant's plan and use,
+ * Upgrade (to a checkout page) and Manage (to a billing portal). Off unless set.
+ */
+export interface SlotlockDashboardBilling {
+    /** The tenant's plan (its own, or the default), or null when it has none (the server's limits apply). */
+    plan(tenantRef: string): Promise<SlotlockTenantPlan | null>;
+    /**
+     * Puts a tenant new to plans on the default plan before it adds a key, resource or webhook
+     * endpoint, while the default does not yet apply to every tenant (plans.ts).
+     */
+    enrol?(tenantRef: string): Promise<void>;
+    /** A checkout URL for the Developer plan, or the Team plan for an organization (with `teamPrices`). */
+    checkout(input: {
+        tenantRef: string;
+        interval: 'month' | 'year';
+        plan?: 'developer' | 'team';
+        customer: string | null;
+        successUrl: string;
+        cancelUrl: string;
+    }): Promise<string>;
+    /** A billing portal URL for the tenant's customer. */
+    portal(input: {
+        customer: string;
+        returnUrl: string;
+    }): Promise<string>;
+    /** The Developer plan's prices as shown, such as `$10`. */
+    prices: {
+        month: string;
+        year: string;
+    };
+    /**
+     * The Team plan's prices as shown (Teams on Cloud). With them, an organization's workspace is
+     * offered Team instead of Developer.
+     */
+    teamPrices?: {
+        month: string;
+        year: string;
+    };
+    /**
+     * Metered overage on Developer (SLOTLOCK_OVERAGE, overage.ts): its price as shown, such as `$2
+     * per 10,000 operations`, and the percent of the quota where use is refused.
+     */
+    overage?: {
+        price: string;
+        stopPercent: number;
+    };
+    /** Where a Custom (self-hosted) enquiry goes: an https or mailto URL. */
+    contact: string;
+    /** The https origins Upgrade and Manage redirect to, allowed in the policy's form-action. */
+    formOrigins: readonly string[];
+}
 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;
+    /**
+     * The terms people accept by signing in, an https URL. The sign-in page links them beside the
+     * button; without it, the page names no terms.
+     */
+    termsUrl?: string;
+    /** The privacy notice the sign-in page links, an https URL. */
+    privacyUrl?: 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
@@ -158,9 +314,25 @@ export interface SlotlockDashboardOptions {
         userUrl?: string;
         membershipsUrl?: string;
     };
+    /**
+     * Sign-in with Google (OpenID Connect), beside GitHub, for people without a GitHub account: each
+     * is their own tenant, `google:<subject>`. Not offered with a fixed list of `organizations`,
+     * which are GitHub's. Its redirect URI is the same `<publicUrl>/dashboard/callback`.
+     */
+    google?: {
+        clientId: string;
+        clientSecret: string;
+        authorizeUrl?: string;
+        tokenUrl?: string;
+        /** Google's signing keys (JWKS); https://www.googleapis.com/oauth2/v3/certs by default. */
+        jwksUrl?: 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. */
+    /**
+     * GitHub user ids (numbers, as strings) and Google accounts (`google:<subject>`) that may sign in,
+     * or `'*'` for every account.
+     */
     allowedUsers: '*' | readonly string[];
     /**
      * GitHub organization ids (numbers, as strings) this dashboard serves. With them, a tenant is an
@@ -171,8 +343,14 @@ export interface SlotlockDashboardOptions {
      * 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>`).
+     *
+     * `'enabled'` (Teams on Cloud, with `teams`): each person signs in to their own tenant and may
+     * switch to any organization they belong to that an owner turned on, on the Teams page; turning
+     * one off ends its use at once.
      */
-    organizations?: readonly string[];
+    organizations?: readonly string[] | 'enabled';
+    /** The organizations turned on, with `organizations: 'enabled'` (teams.ts). */
+    teams?: SlotlockDashboardTeams;
     keys: SlotlockApiKeyStore;
     resources: SlotlockDashboardResources;
     /** Shared by every server behind this origin: see SlotlockDashboardState. */
@@ -181,6 +359,18 @@ export interface SlotlockDashboardOptions {
     availability?: readonly WeeklyAvailabilityRule[];
     /** The chat assistant; off unless set. */
     assistant?: SlotlockDashboardAssistantOptions;
+    /** Plans and billing (hosted Slotlock); off unless set. */
+    billing?: SlotlockDashboardBilling;
+    /**
+     * The deployment meters usage (SLOTLOCK_USAGE=on): the Plan page shows this month's, from the
+     * resources adapter's `usage`.
+     */
+    usage?: boolean;
+    /**
+     * The deployment holds tenants to their plans' monthly quotas (SLOTLOCK_QUOTAS=on): the Plan page
+     * shows this month's use against them, and warns from 80%. Needs `usage`.
+     */
+    quotas?: boolean;
     fetch?: typeof fetch;
     now?: () => number;
     /**
@@ -204,7 +394,13 @@ export interface SlotlockDashboard {
  * The dashboard's resources, in the store under each tenant's row-level security. Adds hold the cap
  * in the database (a READ COMMITTED transaction, under a per-tenant lock).
  */
-export declare function createSlotlockDashboardResources(store: SlotlockStore): SlotlockDashboardResources;
+export declare function createSlotlockDashboardResources(store: SlotlockStore, options?: {
+    /**
+     * The agent backend (`createSlotlockStoreAgentBackend`) a granted approval's booking is made
+     * through: with it, the dashboard lists approvals and decides them.
+     */
+    agentBackend?: SlotlockAgentCalendarBackend;
+}): 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