slotlock 0.6.3 → 0.7.0

package/resource-profile.d.ts

@@ -0,0 +1,135 @@
+/** What a resource is, as a hint for filtering and display; `other` when not said. */
+export declare const SLOTLOCK_RESOURCE_KINDS: readonly ["person", "room", "desk", "space", "vehicle", "machine", "equipment", "service", "other"];
+export type SlotlockResourceKind = (typeof SLOTLOCK_RESOURCE_KINDS)[number];
+/** The profile's bounds, which the database also holds (ddl.ts). */
+export declare const SLOTLOCK_RESOURCE_PROFILE_LIMITS: Readonly<{
+    /** Characters in a name. */
+    name: 200;
+    /** Characters in a description. */
+    description: 2000;
+    /** The most people or seats a resource is said to hold. */
+    capacity: 100000;
+    /** Labels on one resource. */
+    labels: 20;
+    /** Keys in its attributes. */
+    attributes: 50;
+    /** Characters in an attribute's key. */
+    attributeKey: 64;
+    /** Characters in an attribute's text value. */
+    attributeValue: 1000;
+    /** Bytes of its attributes as compact JSON. */
+    attributeBytes: 4096;
+}>;
+/** A label: lower case letters, digits, `.`, `_` and `-`, starting with a letter or digit, 1-64. */
+export declare const SLOTLOCK_RESOURCE_LABEL: RegExp;
+/** What an integrator keeps on a resource and wants back: text, numbers and true or false. */
+export type SlotlockResourceAttributes = Record<string, string | number | boolean>;
+/**
+ * A resource's profile as it is set: a field left out is kept as it is. `null` clears a name, a
+ * description or a capacity; `labels: []` and `attributes: {}` clear those, and `kind: 'other'`
+ * says nothing about what it is.
+ */
+export interface SlotlockResourceProfileInput {
+    name?: string | null;
+    description?: string | null;
+    kind?: SlotlockResourceKind;
+    capacity?: number | null;
+    labels?: readonly string[];
+    attributes?: Readonly<SlotlockResourceAttributes>;
+}
+/** A profile input that passed its checks: names trimmed, labels sorted without repeats. */
+export interface SlotlockResourceProfileChange {
+    name?: string | null;
+    description?: string | null;
+    kind?: SlotlockResourceKind;
+    capacity?: number | null;
+    labels?: string[];
+    attributes?: SlotlockResourceAttributes;
+}
+/** The profile fields, as the feed and the API name them. */
+export declare const SLOTLOCK_RESOURCE_PROFILE_FIELDS: readonly ["name", "description", "kind", "capacity", "labels", "attributes"];
+/**
+ * Check a profile change and put it in the form it is stored in: refused with
+ * `invalid_resource_profile`, naming the field, when a field is outside its bounds.
+ */
+export declare function parseSlotlockResourceProfile(input: SlotlockResourceProfileInput): SlotlockResourceProfileChange;
+/** Whether a resource's labels include every one of `wanted`. */
+export declare function slotlockResourceHasLabels(labels: readonly string[] | undefined, wanted: readonly string[]): boolean;
+/** Locations a tenant may have. */
+export declare const SLOTLOCK_MAX_LOCATIONS = 1000;
+/** Levels a location tree may have: a region, a site, a building, a floor, a zone. */
+export declare const SLOTLOCK_MAX_LOCATION_DEPTH = 5;
+/** Groups a tenant may have. */
+export declare const SLOTLOCK_MAX_RESOURCE_GROUPS = 500;
+/** Groups one resource may be in. */
+export declare const SLOTLOCK_MAX_GROUPS_PER_RESOURCE = 20;
+/** A location's or a group's reference, as a pool's: 1-100 of a-z, 0-9, `.`, `_` and `-`. */
+export declare const SLOTLOCK_GROUPING_REF: RegExp;
+/** A place a tenant's resources are at. */
+export interface SlotlockLocation {
+    ref: string;
+    name: string;
+    /** The location it is in; null at the top. */
+    parentRef: string | null;
+    /** The time zone a resource created here without its own takes; null to take its parent's. */
+    timezone: string | null;
+    /** How many resources are at it (not counting those below it). */
+    resources: number;
+}
+/** A set of a tenant's resources. */
+export interface SlotlockResourceGroup {
+    ref: string;
+    name: string;
+    description: string | null;
+    /** How many resources are in it. */
+    members: number;
+}
+/** Check a location as it is to be stored: refused with `invalid_location`, naming the field. */
+export declare function parseSlotlockLocation(input: {
+    ref: string;
+    name?: string;
+    parentRef?: string | null;
+    timezone?: string | null;
+}): {
+    ref: string;
+    name?: string;
+    parentRef?: string | null;
+    timezone?: string | null;
+};
+/** Check a group as it is to be stored: refused with `invalid_group`, naming the field. */
+export declare function parseSlotlockResourceGroup(input: {
+    ref: string;
+    name: string;
+    description?: string | null;
+}): {
+    ref: string;
+    name: string;
+    description: string | null;
+};
+/** Check a location or group reference given to find one: refused as its own kind's. */
+export declare function slotlockGroupingRef(code: 'invalid_location' | 'invalid_group', value: unknown): string;
+/**
+ * The order a pool booking tries a pool's members in (RFC 0003 G7): `stable`, by id (the default);
+ * `least_booked`, fewest bookings made on each in the last 30 days first, to share them out;
+ * `round_robin`, from the member after the one booked last.
+ */
+export declare const SLOTLOCK_POOL_ORDERS: readonly ["stable", "least_booked", "round_robin"];
+/** Pools a tenant may set an order for (`pool_order_limit_reached` for one more). */
+export declare const SLOTLOCK_MAX_POOL_SETTINGS = 1000;
+/** The parts a composite resource may have (RFC 0003 G8): a hall of its rooms, a court of its halves. */
+export declare const SLOTLOCK_MAX_COMPOSITE_PARTS = 50;
+/**
+ * How far a partner's count of a day may differ from Slotlock's before it is a mismatch, in percent
+ * (RFC 0003 P5: a difference above 0.5% opens an incident on our side).
+ */
+export declare const SLOTLOCK_RECONCILE_TOLERANCE_PERCENT = 0.5;
+export type SlotlockPoolOrder = (typeof SLOTLOCK_POOL_ORDERS)[number];
+/** Locations, and groups, a key limited to part of its tenant may name (RFC 0003 G6), each. */
+export declare const SLOTLOCK_MAX_KEY_SCOPE_REFS = 20;
+/** A key limited to part of its tenant (RFC 0003 G6): the locations and groups it reaches. */
+export interface SlotlockResourceScope {
+    locations: readonly string[];
+    groups: readonly string[];
+}
+/** Whether `value` is a resource scope: location and group references, at least one, each list bounded. */
+export declare function isSlotlockResourceScope(value: unknown): value is SlotlockResourceScope;

package/resource-profile.js

@@ -0,0 +1,263 @@
+// A resource's profile (RFC 0003 G1): how people and agents tell resources apart and find them,
+// whatever they are (a person, a room, a vehicle, a machine). Every field is optional, and none
+// changes how a resource is booked: `kind` is a hint for filtering and `capacity` is informational,
+// as SPEC.md requires ("no semantic rule assumes a particular industry"). Names and descriptions are
+// calendar content: the feed says which profile fields changed, never their values.
+/** What a resource is, as a hint for filtering and display; `other` when not said. */
+export const SLOTLOCK_RESOURCE_KINDS = Object.freeze([
+    'person',
+    'room',
+    'desk',
+    'space',
+    'vehicle',
+    'machine',
+    'equipment',
+    'service',
+    'other',
+]);
+/** The profile's bounds, which the database also holds (ddl.ts). */
+export const SLOTLOCK_RESOURCE_PROFILE_LIMITS = Object.freeze({
+    /** Characters in a name. */
+    name: 200,
+    /** Characters in a description. */
+    description: 2_000,
+    /** The most people or seats a resource is said to hold. */
+    capacity: 100_000,
+    /** Labels on one resource. */
+    labels: 20,
+    /** Keys in its attributes. */
+    attributes: 50,
+    /** Characters in an attribute's key. */
+    attributeKey: 64,
+    /** Characters in an attribute's text value. */
+    attributeValue: 1_000,
+    /** Bytes of its attributes as compact JSON. */
+    attributeBytes: 4_096,
+});
+/** A label: lower case letters, digits, `.`, `_` and `-`, starting with a letter or digit, 1-64. */
+export const SLOTLOCK_RESOURCE_LABEL = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/** The profile fields, as the feed and the API name them. */
+export const SLOTLOCK_RESOURCE_PROFILE_FIELDS = Object.freeze([
+    'name',
+    'description',
+    'kind',
+    'capacity',
+    'labels',
+    'attributes',
+]);
+function invalid(field, message) {
+    return Object.assign(new Error(`Slotlock resource ${field} ${message}`), {
+        code: 'invalid_resource_profile',
+        field,
+    });
+}
+// C0 and C1 control characters, which no name shows; a description may still break lines.
+const CONTROL = /[\u0000-\u001f\u007f-\u009f]/;
+const CONTROL_BUT_LINES = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/;
+/** Characters as PostgreSQL's char_length counts them: code points, not UTF-16 units. */
+const characters = (value) => [...value].length;
+function text(field, value, max, lines) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string')
+        throw invalid(field, 'must be text or null');
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        throw invalid(field, 'must not be empty: send null to clear it');
+    if (characters(trimmed) > max)
+        throw invalid(field, `must be at most ${max} characters`);
+    if ((lines ? CONTROL_BUT_LINES : CONTROL).test(trimmed)) {
+        throw invalid(field, 'must not contain control characters');
+    }
+    return trimmed;
+}
+/**
+ * Check a profile change and put it in the form it is stored in: refused with
+ * `invalid_resource_profile`, naming the field, when a field is outside its bounds.
+ */
+export function parseSlotlockResourceProfile(input) {
+    const limits = SLOTLOCK_RESOURCE_PROFILE_LIMITS;
+    const change = {};
+    if (input.name !== undefined)
+        change.name = text('name', input.name, limits.name, false);
+    if (input.description !== undefined) {
+        change.description = text('description', input.description, limits.description, true);
+    }
+    if (input.kind !== undefined) {
+        if (!SLOTLOCK_RESOURCE_KINDS.includes(input.kind)) {
+            throw invalid('kind', `must be one of ${SLOTLOCK_RESOURCE_KINDS.join(', ')}`);
+        }
+        change.kind = input.kind;
+    }
+    if (input.capacity !== undefined) {
+        if (input.capacity !== null &&
+            !(Number.isSafeInteger(input.capacity) && input.capacity >= 1 && input.capacity <= limits.capacity)) {
+            throw invalid('capacity', `must be a whole number from 1 to ${limits.capacity}, or null`);
+        }
+        change.capacity = input.capacity;
+    }
+    if (input.labels !== undefined) {
+        if (!Array.isArray(input.labels))
+            throw invalid('labels', 'must be a list');
+        const labels = [...new Set(input.labels)];
+        if (labels.length > limits.labels)
+            throw invalid('labels', `must be at most ${limits.labels}`);
+        for (const label of labels) {
+            if (typeof label !== 'string' || !SLOTLOCK_RESOURCE_LABEL.test(label)) {
+                throw invalid('labels', 'must each be 1-64 of a-z, 0-9, ".", "_" and "-", starting with a letter or digit');
+            }
+        }
+        change.labels = labels.sort();
+    }
+    if (input.attributes !== undefined) {
+        const given = input.attributes;
+        if (given === null || typeof given !== 'object' || Array.isArray(given)) {
+            throw invalid('attributes', 'must be an object');
+        }
+        const entries = Object.entries(given);
+        if (entries.length > limits.attributes) {
+            throw invalid('attributes', `must have at most ${limits.attributes} keys`);
+        }
+        const attributes = {};
+        for (const [key, value] of entries) {
+            if (key.length === 0 || characters(key) > limits.attributeKey || CONTROL.test(key)) {
+                throw invalid('attributes', `keys must be 1-${limits.attributeKey} characters without control characters`);
+            }
+            if (typeof value === 'string') {
+                if (characters(value) > limits.attributeValue) {
+                    throw invalid('attributes', `text values must be at most ${limits.attributeValue} characters`);
+                }
+            }
+            else if (typeof value === 'number') {
+                if (!Number.isFinite(value))
+                    throw invalid('attributes', 'numbers must be finite');
+            }
+            else if (typeof value !== 'boolean') {
+                throw invalid('attributes', 'values must be text, numbers, or true or false');
+            }
+            attributes[key] = value;
+        }
+        if (Buffer.byteLength(JSON.stringify(attributes), 'utf8') > limits.attributeBytes) {
+            throw invalid('attributes', `must be at most ${limits.attributeBytes} bytes as JSON`);
+        }
+        change.attributes = attributes;
+    }
+    return change;
+}
+/** Whether a resource's labels include every one of `wanted`. */
+export function slotlockResourceHasLabels(labels, wanted) {
+    return wanted.every((label) => labels?.includes(label) === true);
+}
+// Where a resource is, and the sets it is in (RFC 0003 G2, G3): a location is a place in a tree of
+// the tenant's own (one a resource), a group any set the tenant wants (many a resource). Neither
+// changes how a resource is booked; a pool does that.
+/** Locations a tenant may have. */
+export const SLOTLOCK_MAX_LOCATIONS = 1_000;
+/** Levels a location tree may have: a region, a site, a building, a floor, a zone. */
+export const SLOTLOCK_MAX_LOCATION_DEPTH = 5;
+/** Groups a tenant may have. */
+export const SLOTLOCK_MAX_RESOURCE_GROUPS = 500;
+/** Groups one resource may be in. */
+export const SLOTLOCK_MAX_GROUPS_PER_RESOURCE = 20;
+/** A location's or a group's reference, as a pool's: 1-100 of a-z, 0-9, `.`, `_` and `-`. */
+export const SLOTLOCK_GROUPING_REF = /^[a-z0-9][a-z0-9._-]{0,99}$/;
+function invalidGrouping(code, field, message) {
+    return Object.assign(new Error(`Slotlock ${code === 'invalid_location' ? 'location' : 'group'} ${field} ${message}`), {
+        code,
+        field,
+    });
+}
+function groupingRef(code, field, value) {
+    if (typeof value !== 'string' || !SLOTLOCK_GROUPING_REF.test(value)) {
+        throw invalidGrouping(code, field, 'must be 1-100 of a-z, 0-9, ".", "_" and "-", starting with a letter or digit');
+    }
+    return value;
+}
+function groupingName(code, value) {
+    try {
+        const name = text('name', value, SLOTLOCK_RESOURCE_PROFILE_LIMITS.name, false);
+        if (name === null)
+            throw invalid('name', 'must be given');
+        return name;
+    }
+    catch (error) {
+        throw invalidGrouping(code, 'name', error.message.replace(/^Slotlock resource name /, ''));
+    }
+}
+/** Check a location as it is to be stored: refused with `invalid_location`, naming the field. */
+export function parseSlotlockLocation(input) {
+    const location = {
+        ref: groupingRef('invalid_location', 'ref', input.ref),
+    };
+    if (input.name !== undefined)
+        location.name = groupingName('invalid_location', input.name);
+    if (input.parentRef !== undefined) {
+        location.parentRef = input.parentRef === null ? null : groupingRef('invalid_location', 'parent', input.parentRef);
+        if (location.parentRef === location.ref)
+            throw invalidGrouping('invalid_location', 'parent', 'must not be itself');
+    }
+    if (input.timezone !== undefined) {
+        if (input.timezone !== null) {
+            try {
+                if (typeof input.timezone !== 'string' || input.timezone.length > 100)
+                    throw new Error('no');
+                new Intl.DateTimeFormat('en-GB', { timeZone: input.timezone }).format(0);
+            }
+            catch {
+                throw invalidGrouping('invalid_location', 'timezone', 'must be an IANA time zone, or null');
+            }
+        }
+        location.timezone = input.timezone;
+    }
+    return location;
+}
+/** Check a group as it is to be stored: refused with `invalid_group`, naming the field. */
+export function parseSlotlockResourceGroup(input) {
+    let description = null;
+    if (input.description !== undefined && input.description !== null) {
+        try {
+            description = text('description', input.description, SLOTLOCK_RESOURCE_PROFILE_LIMITS.description, true);
+        }
+        catch (error) {
+            throw invalidGrouping('invalid_group', 'description', error.message.replace(/^Slotlock resource description /, ''));
+        }
+    }
+    return {
+        ref: groupingRef('invalid_group', 'ref', input.ref),
+        name: groupingName('invalid_group', input.name),
+        description,
+    };
+}
+/** Check a location or group reference given to find one: refused as its own kind's. */
+export function slotlockGroupingRef(code, value) {
+    return groupingRef(code, 'ref', value);
+}
+/**
+ * The order a pool booking tries a pool's members in (RFC 0003 G7): `stable`, by id (the default);
+ * `least_booked`, fewest bookings made on each in the last 30 days first, to share them out;
+ * `round_robin`, from the member after the one booked last.
+ */
+export const SLOTLOCK_POOL_ORDERS = Object.freeze(['stable', 'least_booked', 'round_robin']);
+/** Pools a tenant may set an order for (`pool_order_limit_reached` for one more). */
+export const SLOTLOCK_MAX_POOL_SETTINGS = 1_000;
+/** The parts a composite resource may have (RFC 0003 G8): a hall of its rooms, a court of its halves. */
+export const SLOTLOCK_MAX_COMPOSITE_PARTS = 50;
+/**
+ * How far a partner's count of a day may differ from Slotlock's before it is a mismatch, in percent
+ * (RFC 0003 P5: a difference above 0.5% opens an incident on our side).
+ */
+export const SLOTLOCK_RECONCILE_TOLERANCE_PERCENT = 0.5;
+/** Locations, and groups, a key limited to part of its tenant may name (RFC 0003 G6), each. */
+export const SLOTLOCK_MAX_KEY_SCOPE_REFS = 20;
+/** Whether `value` is a resource scope: location and group references, at least one, each list bounded. */
+export function isSlotlockResourceScope(value) {
+    const scope = value;
+    const refs = (list) => Array.isArray(list) &&
+        list.length <= SLOTLOCK_MAX_KEY_SCOPE_REFS &&
+        list.every((ref) => typeof ref === 'string' && SLOTLOCK_GROUPING_REF.test(ref));
+    return (typeof scope === 'object' &&
+        scope !== null &&
+        refs(scope.locations) &&
+        refs(scope.groups) &&
+        scope.locations.length + scope.groups.length > 0);
+}

package/rest-api.d.ts

@@ -61,6 +61,8 @@ export interface SlotlockOpenApiOperation {
     description: string;
     inputSchema: JsonSchema;
     outputSchema: JsonSchema;
+    /** An operation's own scope: a tool's, or the partner API's (else the application scope). */
+    scope?: string;
 }
 /** The OpenAPI 3.1 document for the REST routes, from the operations' own schemas. */
 export declare function slotlockOpenApiDocument(args: {

package/rest-api.js

@@ -29,6 +29,12 @@ export const SLOTLOCK_REST_ROUTES = Object.freeze([
         operation: 'slotlock_release_slots',
         refusals: [409],
     },
+    {
+        method: 'POST',
+        path: '/v1/slot-holds/{hold_id}/confirm',
+        operation: 'slotlock_confirm_slot',
+        refusals: [404, 409],
+    },
     { method: 'GET', path: '/v1/events', operation: 'slotlock_list_events', refusals: [404] },
     { method: 'POST', path: '/v1/events', operation: 'slotlock_create_event', refusals: [404, 409] },
     { method: 'GET', path: '/v1/events/{event_id}', operation: 'slotlock_get_event', refusals: [404] },
@@ -44,6 +50,18 @@ export const SLOTLOCK_REST_ROUTES = Object.freeze([
         operation: 'slotlock_delete_event',
         refusals: [404, 409],
     },
+    {
+        method: 'POST',
+        path: '/v1/events/{event_id}/reschedule',
+        operation: 'slotlock_reschedule',
+        refusals: [404, 409],
+    },
+    {
+        method: 'POST',
+        path: '/v1/events/{event_id}/cancel',
+        operation: 'slotlock_cancel',
+        refusals: [404, 409],
+    },
 ]);
 /** The application operations' routes, served when the server has an application backend. */
 export const SLOTLOCK_APPLICATION_REST_ROUTES = Object.freeze(SLOTLOCK_APPLICATION_OPERATIONS.map(({ method, path, name }) => ({
@@ -65,6 +83,7 @@ const PROBLEM_TITLES = Object.freeze({
     revision_conflict: 'The revision is stale',
     confirmation_required: 'A person must confirm this write',
     rate_limited: 'Too many requests',
+    quota_exceeded: 'The monthly quota is used up',
     authentication_required: 'Authentication required',
     forbidden: 'Not allowed',
     invalid_arguments: 'The arguments are not valid',
@@ -330,8 +349,8 @@ export function slotlockOpenApiDocument(args) {
         if (!operation)
             throw new Error(`Slotlock REST route ${route.path} names no operation`);
         add(route, openApiOperation(route, operation, {
-            tag: 'Application',
-            scope: SLOTLOCK_APPLICATION_SCOPE,
+            tag: operation.scope === 'partner' ? 'Partner' : 'Application',
+            scope: operation.scope === 'partner' ? 'partner' : SLOTLOCK_APPLICATION_SCOPE,
             responses: {
                 '400': ERROR_RESPONSE,
                 '401': ERROR_RESPONSE,
@@ -378,6 +397,10 @@ export function slotlockOpenApiDocument(args) {
                         name: 'Application',
                         description: 'What the application around the agents does. Needs the admin scope; never offered to agents.',
                     },
+                    {
+                        name: 'Partner',
+                        description: "What a partner reselling Slotlock does for its own users' accounts. Needs a partner key (`slk_partner_…`), whose `partner` scope reaches nothing else.",
+                    },
                 ]
                 : []),
         ],
@@ -387,7 +410,7 @@ export function slotlockOpenApiDocument(args) {
                 bearer: {
                     type: 'http',
                     scheme: 'bearer',
-                    description: 'A Slotlock API key (`slk_…`) or the server token. `x-slotlock-scope` on each operation names the scope it needs.',
+                    description: 'A Slotlock API key (`slk_…`, or `slk_test_…` for a test environment), a partner key (`slk_partner_…`; with a `Slotlock-Account` field naming one of its accounts, where its contract allows, it acts as that account) or the server token. `x-slotlock-scope` on each operation names the scope it needs.',
                 },
             },
             schemas: {
@@ -403,6 +426,48 @@ export function slotlockOpenApiDocument(args) {
                         resource_id: { type: 'string', description: 'An overlap: the resource it refused.' },
                         start: { type: 'string', description: 'An overlap: the start it refused.' },
                         end: { type: 'string', description: 'An overlap: the end it refused.' },
+                        busy_start: {
+                            type: 'string',
+                            description: 'An overlap: when the booking in the way makes the time busy, from (buffers included).',
+                        },
+                        busy_end: { type: 'string', description: 'An overlap: until when that booking makes it busy.' },
+                        conflicting_hold_id: {
+                            type: 'string',
+                            description: 'An overlap with a hold of your own: its id, to book or release it.',
+                        },
+                        conflicting_event_id: {
+                            type: 'string',
+                            description: 'An overlap with an event of your own: its id, to move or cancel it.',
+                        },
+                        approval_id: {
+                            type: 'string',
+                            description: 'approval_pending, approval_declined or approval_expired: the approval a policy made of the booking. Retry with the same idempotency_key to learn how it was decided.',
+                        },
+                        policy_ref: { type: 'string', description: 'An approval refusal: the policy that applies.' },
+                        expires_at: {
+                            type: 'string',
+                            description: 'approval_pending or approval_required: until when a person may decide (the time is held until then).',
+                        },
+                        reason: { type: 'string', description: 'approval_declined: what the person who declined it said, if anything.' },
+                        alternatives: {
+                            type: 'array',
+                            maxItems: 3,
+                            description: 'A refusal another time can answer (overlap, pool_full, a booking rule): the earliest free times of the same length, within 7 days of the time asked for, checked as slotlock_find_available_slots checks them. Suggestions, not holds. Empty when none was found.',
+                            items: {
+                                type: 'object',
+                                required: ['resource_id', 'start', 'end'],
+                                properties: {
+                                    resource_id: { type: 'string' },
+                                    start: { type: 'string', format: 'date-time' },
+                                    end: { type: 'string', format: 'date-time' },
+                                    resource_ids: {
+                                        type: 'array',
+                                        items: { type: 'string' },
+                                        description: 'A bundle or pool booking: the resources free together then.',
+                                    },
+                                },
+                            },
+                        },
                         issues: {
                             type: 'array',
                             description: '`invalid_arguments` from argument validation: each field it refused (at most 20), by its path in the arguments, outermost first; `[]` is the arguments as a whole.',

package/sandbox.d.ts

@@ -0,0 +1,70 @@
+import { type SlotlockAgentCalendarBackend } from './agent-server.js';
+import { type SlotlockMaintenanceResult } from './maintenance.js';
+import type { SlotlockStore } from './store.js';
+export declare const SLOTLOCK_SANDBOX_SCENARIOS: readonly ["car-rental", "clinic", "desks"];
+export type SlotlockSandboxScenario = (typeof SLOTLOCK_SANDBOX_SCENARIOS)[number];
+/** Agents one race runs at most, so a race stays a test of the server and not a load on it. */
+export declare const SLOTLOCK_SANDBOX_MAX_RACERS = 200;
+/** Refused outside a test environment. */
+export declare class SlotlockSandboxError extends Error {
+    readonly code: 'sandbox_test_only' | 'sandbox_not_empty';
+    constructor(code: 'sandbox_test_only' | 'sandbox_not_empty', message: string);
+}
+export interface SlotlockSandboxSeedResult {
+    scenario: SlotlockSandboxScenario;
+    resources: number;
+    locations: number;
+    groups: number;
+    pools: number;
+    bookings: number;
+}
+/**
+ * Fill an empty test environment with a scenario, in one transaction: its locations, groups,
+ * resources (with profiles, pools and a composite where it has one), their hours and booking
+ * rules, and a few bookings tomorrow. Refused (`sandbox_not_empty`) where it has resources already:
+ * reset it first.
+ */
+export declare function seedSlotlockSandbox(store: SlotlockStore, tenantRef: string, scenario: SlotlockSandboxScenario, options?: {
+    now?: Date;
+}): Promise<SlotlockSandboxSeedResult>;
+/** Empty a test environment: what seeding made, and every booking since. Keys, webhooks and plan stay. */
+export declare function resetSlotlockSandbox(store: SlotlockStore, tenantRef: string): Promise<Record<string, number>>;
+export interface SlotlockSandboxFastForwardResult {
+    minutes: number;
+    /** Holds (a waitlist offer's and an approval's among them) and approvals that lapsed now. */
+    holds: number;
+    approvals: number;
+    /** The maintenance pass that then reaped them, as it would have. */
+    maintenance: SlotlockMaintenanceResult;
+}
+/**
+ * Move a test environment's waiting forward: what would lapse within `minutes` lapses now, then a
+ * maintenance pass reaps it as it would have (holds released, waitlist offers passed on, approvals
+ * expired). Bookings and events keep their times; no-shows and series rolls follow the real clock.
+ */
+export declare function fastForwardSlotlockSandbox(store: SlotlockStore, tenantRef: string, minutes: number): Promise<SlotlockSandboxFastForwardResult>;
+export interface SlotlockSandboxRaceResult {
+    agents: number;
+    booked: number;
+    /** Refusals by code. */
+    refused: Record<string, number>;
+    /** Refusals that came with alternatives. */
+    withAlternatives: number;
+    serverErrors: number;
+    p50Ms: number;
+    p99Ms: number;
+    maxMs: number;
+}
+/**
+ * Race `agents` agents (2-200), each its own principal, for one time on one resource of a test
+ * environment, through the same operation boundary MCP, A2A and REST use: who booked, who was
+ * refused and why, and how long each answer took.
+ */
+export declare function raceSlotlockSandbox(params: {
+    backend: SlotlockAgentCalendarBackend;
+    tenantRef: string;
+    resourceId: string;
+    start: Date;
+    end: Date;
+    agents?: number;
+}): Promise<SlotlockSandboxRaceResult>;