@substrat-run/engine-booking 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,308 @@
+import { z } from 'zod';
+import { type Money } from '@substrat-run/contracts';
+import { type ModuleRegistration, type OperationContext } from '@substrat-run/kernel';
+export declare const PERM: {
+    create: string & z.core.$brand<"PermissionKey">;
+    read: string & z.core.$brand<"PermissionKey">;
+    hold: string & z.core.$brand<"PermissionKey">;
+    confirm: string & z.core.$brand<"PermissionKey">;
+    cancel: string & z.core.$brand<"PermissionKey">;
+    move: string & z.core.$brand<"PermissionKey">;
+    complete: string & z.core.$brand<"PermissionKey">;
+    manageResources: string & z.core.$brand<"PermissionKey">;
+};
+export declare const bookingManifest: {
+    id: string & z.core.$brand<"ModuleId">;
+    version: string;
+    kernelContract: string;
+    permissions: {
+        key: string & z.core.$brand<"PermissionKey">;
+        description: string;
+    }[];
+    events: {
+        emits: {
+            type: string;
+            schemaVersion: number;
+        }[];
+        consumes: {
+            type: string;
+            schemaVersion: number;
+        }[];
+    };
+    migrations: {
+        journalDir: string;
+        compatibleFrom: string;
+    };
+    attachmentTargets: {
+        entityType: string;
+        readPermission: string & z.core.$brand<"PermissionKey">;
+    }[];
+    entitlementKey: string;
+    entityRelations?: {
+        entityType: string;
+        parentType: string;
+    }[] | undefined;
+    guards?: {
+        before: string;
+        predicate: string;
+        config: Record<string, unknown>;
+    }[] | undefined;
+    withdraws?: string[] | undefined;
+    api?: string | undefined;
+    searchables?: {
+        entityType: string;
+        fields: string[];
+    }[] | undefined;
+    ui?: {
+        routes?: {
+            path: string;
+            screen: string;
+            permission: string & z.core.$brand<"PermissionKey">;
+        }[] | undefined;
+        nav?: {
+            label: string;
+            to: string;
+            permission: string & z.core.$brand<"PermissionKey">;
+            icon?: string | undefined;
+        }[] | undefined;
+        entityViews?: {
+            entityType: string;
+            view: string;
+        }[] | undefined;
+        widgets?: {
+            slot: string;
+            component: string;
+            permission: string & z.core.$brand<"PermissionKey">;
+        }[] | undefined;
+        settingsPanels?: {
+            label: string;
+            component: string;
+            permission: string & z.core.$brand<"PermissionKey">;
+        }[] | undefined;
+    } | undefined;
+};
+export declare const bookingMigrations: {
+    version: string;
+    sql: string;
+}[];
+/** The typed rejection a vertical surfaces as "that slot was just taken". */
+export declare class SlotUnavailable extends Error {
+    readonly resourceId: string;
+    readonly startsAt: string;
+    readonly endsAt: string;
+    readonly code = "SLOT_UNAVAILABLE";
+    constructor(resourceId: string, startsAt: string, endsAt: string);
+}
+export declare const reservationState: z.ZodEnum<{
+    held: "held";
+    confirmed: "confirmed";
+    in_service: "in_service";
+    completed: "completed";
+    expired: "expired";
+    cancelled: "cancelled";
+    no_show: "no_show";
+}>;
+export type ReservationState = z.infer<typeof reservationState>;
+export declare const createResourceInput: z.ZodObject<{
+    kind: z.ZodString;
+    name: z.ZodString;
+    capacity: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CreateResourceInput = z.infer<typeof createResourceInput>;
+export declare const holdReservationInput: z.ZodObject<{
+    resourceId: z.ZodString;
+    startsAt: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    endsAt: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    expiresAt: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    quantity: z.ZodOptional<z.ZodNumber>;
+    fillTarget: z.ZodOptional<z.ZodNumber>;
+    note: z.ZodOptional<z.ZodString>;
+    now: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type HoldReservationInput = z.infer<typeof holdReservationInput>;
+export declare const joinReservationInput: z.ZodObject<{
+    reservationId: z.ZodString;
+    partyRef: z.core.$ZodBranded<z.ZodString, "DataSubjectId", "out">;
+    share: z.ZodOptional<z.ZodObject<{
+        amount: z.core.$ZodBranded<z.ZodString, "MoneyAmount", "out">;
+        currency: z.core.$ZodBranded<z.ZodString, "CurrencyCode", "out">;
+    }, z.core.$strip>>;
+    now: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type JoinReservationInput = z.infer<typeof joinReservationInput>;
+export declare const moveReservationInput: z.ZodObject<{
+    reservationId: z.ZodString;
+    resourceId: z.ZodOptional<z.ZodString>;
+    startsAt: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    endsAt: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    now: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MoveReservationInput = z.infer<typeof moveReservationInput>;
+export interface Resource {
+    id: string;
+    kind: string;
+    name: string;
+    capacity: number;
+    active: boolean;
+    createdAt: string;
+}
+export interface Participant {
+    id: string;
+    partyRef: string;
+    share: Money | null;
+    joinedAt: string;
+    leftAt: string | null;
+}
+export interface Reservation {
+    id: string;
+    resourceId: string;
+    startsAt: string;
+    endsAt: string;
+    /** The state as stored. A `held` row keeps saying `held` until someone sweeps it. */
+    state: ReservationState;
+    /**
+     * What the row actually means *now* — `expired` once a hold's deadline has passed,
+     * whether or not anyone has swept it.
+     *
+     * Expiry is lazy, so `state` alone would render a dead hold as a live one: the
+     * console calendar would show a HELD cell counting down past 0:00 forever. Read
+     * paths render this; the transition guards use the stored `state`.
+     */
+    effectiveState: ReservationState;
+    quantity: number;
+    expiresAt: string | null;
+    fillTarget: number | null;
+    note: string | null;
+    createdBy: string;
+    createdAt: string;
+}
+export interface FreeInterval {
+    startsAt: string;
+    endsAt: string;
+    available: number;
+}
+/** The one definition of "a hold past its deadline is expired". */
+export declare function effectiveStateOf(state: ReservationState, expiresAt: string | null, now: string): ReservationState;
+export declare function createResource(ctx: OperationContext, rawInput: CreateResourceInput): Resource;
+export declare function setResourceActive(ctx: OperationContext, input: {
+    resourceId: string;
+    active: boolean;
+}): Resource;
+export declare function listResources(ctx: OperationContext, kind?: string): Resource[];
+/**
+ * Place a tentative hold. Throws {@link SlotUnavailable} if the interval would
+ * overallocate the resource.
+ *
+ * A hold is never permanent — `expiresAt` is mandatory. The same mechanism serves
+ * a payment hold and an open match awaiting players (`fillTarget`).
+ */
+export declare function holdReservation(ctx: OperationContext, rawInput: HoldReservationInput): Reservation;
+/**
+ * held → confirmed. Re-runs the allocation check excluding this reservation,
+ * because the hold may have expired and the slot been taken in the meantime.
+ */
+export declare function confirmReservation(ctx: OperationContext, input: {
+    reservationId: string;
+    now?: string;
+}): Reservation;
+/**
+ * Expire a hold whose deadline has passed. Idempotent-ish: only `held` rows move.
+ * Because expiry is lazy, calling this is optional for correctness — it exists so
+ * a vertical can surface the transition (and its event) to a UI.
+ */
+export declare function expireReservation(ctx: OperationContext, input: {
+    reservationId: string;
+    now?: string;
+}): Reservation;
+/**
+ * Add a participant. When the reservation is `held` and reaching `fillTarget`,
+ * this auto-confirms — the open-match mechanic, built out of the payment hold.
+ */
+export declare function joinReservation(ctx: OperationContext, rawInput: JoinReservationInput): {
+    participant: Participant;
+    reservation: Reservation;
+};
+/** Soft-leave: the row is never deleted, so the record of who was in stays intact. */
+/**
+ * Open an existing reservation to others, or change how many places are on offer.
+ *
+ * `fillTarget` is engine state — it drives the auto-confirm in `joinReservation`
+ * — so a booking cannot be opened up by a vertical keeping its own counter
+ * beside it and hoping the two agree. Additive: reservations made without a
+ * target are unaffected, and a target below the people already on it is refused
+ * rather than silently stranding someone.
+ *
+ * Passing `null` closes it again — a private booking with no places on offer.
+ */
+export declare function openReservation(ctx: OperationContext, input: {
+    reservationId: string;
+    fillTarget: number | null;
+    now?: string;
+}): Reservation;
+export declare function leaveReservation(ctx: OperationContext, input: {
+    reservationId: string;
+    participantId: string;
+    now?: string;
+}): Reservation;
+export declare function cancelReservation(ctx: OperationContext, input: {
+    reservationId: string;
+    reason?: string;
+}): Reservation;
+/**
+ * Reschedule to another slot and/or resource, keeping the reservation's identity
+ * and its participants.
+ *
+ * Deliberately **not** a general `updateReservation`. Engines model named
+ * transitions rather than field patches (cf. `engine-workorder`), participants are
+ * an append-only log with per-subject events rather than a patchable field (D-C),
+ * and `booking.moved` carrying from/to is worth far more to a consumer than a
+ * generic diff — event payloads freeze once shipped.
+ *
+ * This is not cancel-then-rebook: that would lose the identity, the roster, and
+ * any payment already attached.
+ */
+export declare function moveReservation(ctx: OperationContext, rawInput: MoveReservationInput): Reservation;
+export declare function startReservation(ctx: OperationContext, input: {
+    reservationId: string;
+}): Reservation;
+/**
+ * The terminal success transition. The payload is deliberately **fat** — resource,
+ * interval and the full participant list — so an invoicing consumer can raise split
+ * charges and an out-of-kernel consumer can build cross-club history, neither
+ * needing a cross-module read.
+ */
+export declare function completeReservation(ctx: OperationContext, input: {
+    reservationId: string;
+}): Reservation;
+export declare function markNoShow(ctx: OperationContext, input: {
+    reservationId: string;
+}): Reservation;
+export declare function getReservation(ctx: OperationContext, reservationId: string, now?: string): {
+    reservation: Reservation;
+    participants: Participant[];
+};
+export declare function listReservations(ctx: OperationContext, input: {
+    resourceId?: string;
+    from?: string;
+    to?: string;
+    now?: string;
+}): Reservation[];
+/**
+ * Free capacity over `[from, to)`, as merged intervals.
+ *
+ * Returns raw gaps between reservations — it knows nothing of opening hours and
+ * will happily report 03:00 as free. Intersecting with the venue's bookable
+ * window is the **vertical's** job (docs/design/engine-booking.md §4.1).
+ *
+ * Implemented as a sweep over interval boundaries rather than a simple gap walk,
+ * because capacity may exceed 1 (fungible pools), where "free" is a number and not
+ * a boolean.
+ */
+export declare function availability(ctx: OperationContext, input: {
+    resourceId: string;
+    from: string;
+    to: string;
+    now?: string;
+}): FreeInterval[];
+export declare const bookingModule: ModuleRegistration;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}