Rename reservations to advisory soft holds (#94)

Author: Jesssullivan

BUILD.bazel

@@ -149,7 +149,7 @@ npm_package(
     ],
     package = "@tummycrypt/scheduling-kit",
     tags = ["manual"],
-    version = "0.7.8",
+    version = "0.8.0",
     visibility = ["//visibility:public"],
 )
 

MODULE.bazel

@@ -22,7 +22,7 @@ Subpackage targets (finer-grained caching):
 
 module(
     name = "tummycrypt_scheduling_kit",
-    version = "0.7.8",
+    version = "0.8.0",
     compatibility_level = 1,
 )
 

docs/generated/package-surface.md

@@ -11,7 +11,7 @@ Generated from `package.json` and the current `src/` tree.
 | Field | Value |
 | --- | --- |
 | Package | `@tummycrypt/scheduling-kit` |
-| Version | `0.7.8` |
+| Version | `0.8.0` |
 | Description | Backend-agnostic scheduling components with alternative payment support |
 | Node range | `>=20 <25` |
 | Repository | https://github.com/Jesssullivan/scheduling-kit.git |

docs/generated/release-metadata.md

@@ -11,9 +11,9 @@ Generated from `package.json`, `MODULE.bazel`, `BUILD.bazel`,
 
 | Surface | Value |
 | --- | --- |
-| package.json version | `0.7.8` |
-| MODULE.bazel version | `0.7.8` |
-| BUILD.bazel npm_package version | `0.7.8` |
+| package.json version | `0.8.0` |
+| MODULE.bazel version | `0.8.0` |
+| BUILD.bazel npm_package version | `0.8.0` |
 | BUILD.bazel package name | `@tummycrypt/scheduling-kit` |
 | .bazelversion | `8.1.1` |
 | pnpm packageManager | `pnpm@9.15.9` |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tummycrypt/scheduling-kit",
-  "version": "0.7.8",
+  "version": "0.8.0",
   "description": "Backend-agnostic scheduling components with alternative payment support",
   "type": "module",
   "packageManager": "pnpm@9.15.9",

src/adapters/__tests__/homegrown-adapter.test.ts

@@ -308,8 +308,8 @@ describe("HomegrownAdapter", () => {
         "getAvailableDates",
         "getAvailableSlots",
         "checkSlotAvailability",
-        "createReservation",
-        "releaseReservation",
+        "softHoldSlot",
+        "releaseSoftHold",
         "createBooking",
         "createBookingWithPaymentRef",
         "getBooking",
@@ -530,13 +530,13 @@ describe("HomegrownAdapter", () => {
   // Reservations
   // -------------------------------------------------------------------------
 
-  describe("createReservation", () => {
-    it("inserts a reservation and returns SlotReservation", async () => {
+  describe("softHoldSlot", () => {
+    it("inserts an advisory soft hold and returns SlotSoftHold", async () => {
       const mockDb = createMockDb({ insert: [RESERVATION_ROW] });
       const adapter = createAdapter({ getDb: async () => mockDb });
 
       const result = await Effect.runPromise(
-        adapter.createReservation({
+        adapter.softHoldSlot({
           serviceId: "svc-uuid-1",
           providerId: "prac-uuid-1",
           datetime: "2026-04-20T14:00:00.000Z",
@@ -561,7 +561,7 @@ describe("HomegrownAdapter", () => {
       // The adapter calculates expiresAt internally — we just verify the
       // insert goes through and returns the DB row
       const result = await Effect.runPromise(
-        adapter.createReservation({
+        adapter.softHoldSlot({
           serviceId: "svc-uuid-1",
           datetime: "2026-04-20T14:00:00.000Z",
           duration: 60,
@@ -572,14 +572,14 @@ describe("HomegrownAdapter", () => {
     });
   });
 
-  describe("releaseReservation", () => {
-    it("sets releasedAt on the reservation", async () => {
+  describe("releaseSoftHold", () => {
+    it("sets releasedAt on the soft hold", async () => {
       const mockDb = createMockDb();
       const adapter = createAdapter({ getDb: async () => mockDb });
 
-      // releaseReservation returns void — just ensure no throw
+      // releaseSoftHold returns void — just ensure no throw
       await expect(
-        Effect.runPromise(adapter.releaseReservation("res-uuid-1")),
+        Effect.runPromise(adapter.releaseSoftHold("res-uuid-1")),
       ).resolves.toBeUndefined();
 
       expect(mockDb.update).toHaveBeenCalled();

src/adapters/acuity.ts

@@ -12,7 +12,7 @@ import type {
   AvailableDate,
   Booking,
   BookingRequest,
-  SlotReservation,
+  SlotSoftHold,
   ClientInfo,
 } from '../core/types.js';
 import { Errors } from '../core/types.js';
@@ -297,10 +297,10 @@ export const createAcuityAdapter = (config: AcuityAdapterConfig): SchedulingAdap
       );
     },
 
-    // Reservations (via Acuity blocks)
-    createReservation: ({ providerId, datetime, duration, notes }) => {
+    // Advisory soft holds (via Acuity blocks)
+    softHoldSlot: ({ providerId, datetime, duration, notes }) => {
       if (!providerId) {
-        return Effect.fail(Errors.reservation('BLOCK_FAILED', 'Provider ID required for reservation'));
+        return Effect.fail(Errors.reservation('BLOCK_FAILED', 'Provider ID required for soft hold'));
       }
 
       const startTime = new Date(datetime);
@@ -312,25 +312,25 @@ export const createAcuityAdapter = (config: AcuityAdapterConfig): SchedulingAdap
             calendarID: parseInt(providerId, 10),
             start: startTime.toISOString(),
             end: endTime.toISOString(),
-            notes: notes ?? 'Payment pending - slot reserved',
+            notes: notes ?? 'Payment pending - advisory soft hold',
           }),
           (block) => ({
             id: String(block.id),
             datetime,
             duration,
             expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
             providerId,
-          } satisfies SlotReservation)
+          } satisfies SlotSoftHold)
         ),
         Effect.mapError((e) =>
-          Errors.reservation('BLOCK_FAILED', e._tag === 'AcuityError' ? e.message : 'Failed to create reservation')
+          Errors.reservation('BLOCK_FAILED', e._tag === 'AcuityError' ? e.message : 'Failed to create soft hold')
         )
       );
     },
 
-    releaseReservation: (reservationId) =>
+    releaseSoftHold: (softHoldId) =>
       pipe(
-        Effect.map(del<void>(`/blocks/${reservationId}`), () => undefined),
+        Effect.map(del<void>(`/blocks/${softHoldId}`), () => undefined),
         Effect.catchAll(() => Effect.succeed(undefined)) // Ignore errors when releasing
       ),
 

src/adapters/calcom.ts

@@ -14,7 +14,7 @@ import type {
 	TimeSlot,
 	Booking,
 	BookingRequest,
-	SlotReservation,
+	SlotSoftHold,
 	ClientInfo,
 } from '../core/types.js';
 import type { SchedulingResult } from '../core/types.js';
@@ -82,16 +82,16 @@ export const createCalComAdapter = (_config: CalComConfig): SchedulingAdapter =>
 			datetime: string;
 		}) => notImplemented<boolean>(),
 
-		createReservation: (_params: {
+		softHoldSlot: (_params: {
 			serviceId: string;
 			providerId?: string;
 			datetime: string;
 			duration: number;
 			expirationMinutes?: number;
 			notes?: string;
-		}) => notImplemented<SlotReservation>(),
+		}) => notImplemented<SlotSoftHold>(),
 
-		releaseReservation: (_reservationId: string) => notImplemented<void>(),
+		releaseSoftHold: (_softHoldId: string) => notImplemented<void>(),
 
 		createBooking: (_request: BookingRequest) => notImplemented<Booking>(),
 

src/adapters/homegrown.ts

@@ -18,7 +18,7 @@ import type {
   AvailableDate,
   Booking,
   BookingRequest,
-  SlotReservation,
+  SlotSoftHold,
   ClientInfo,
   SchedulingResult,
   BookingStatus,
@@ -295,8 +295,8 @@ export const createHomegrownAdapter = (
           ),
         );
 
-      // Active reservations (not expired, not released)
-      const reservationRows = await d
+      // Active soft holds (not expired, not released)
+      const softHoldRows = await d
         .select({
           datetime: slotReservations.datetime,
           duration: slotReservations.duration,
@@ -325,7 +325,7 @@ export const createHomegrownAdapter = (
           end: new Date(r.endTime),
         });
       }
-      for (const r of reservationRows) {
+      for (const r of softHoldRows) {
         const start = new Date(r.datetime);
         occupied.push({
           start,
@@ -606,9 +606,9 @@ export const createHomegrownAdapter = (
         });
       }),
 
-    // --- Reservations ---
+    // --- Advisory soft holds ---
 
-    createReservation: (params) =>
+    softHoldSlot: (params) =>
       fromAsync(async () => {
         const { slotReservations } = (await loadSchemas()).booking;
         const expirationMinutes = params.expirationMinutes ?? 10;
@@ -633,18 +633,18 @@ export const createHomegrownAdapter = (
           duration: row.duration,
           expiresAt: row.expiresAt,
           providerId: params.providerId,
-        } satisfies SlotReservation;
+        } satisfies SlotSoftHold;
       }),
 
-    releaseReservation: (reservationId: string) =>
+    releaseSoftHold: (softHoldId: string) =>
       fromAsync(async () => {
         const { slotReservations } = (await loadSchemas()).booking;
         const { eq } = await import("drizzle-orm");
         await withDb((d) =>
           d
             .update(slotReservations)
             .set({ releasedAt: new Date().toISOString() })
-            .where(eq(slotReservations.id, reservationId)),
+            .where(eq(slotReservations.id, softHoldId)),
         );
       }),
 

src/adapters/types.ts

@@ -11,7 +11,7 @@ import type {
   AvailableDate,
   Booking,
   BookingRequest,
-  SlotReservation,
+  SlotSoftHold,
   ClientInfo,
 } from '../core/types.js';
 
@@ -92,26 +92,30 @@ export interface SchedulingAdapter {
   }): SchedulingResult<boolean>;
 
   // ---------------------------------------------------------------------------
-  // Slot Reservation (Hold)
+  // Slot Soft Hold (Advisory)
   // ---------------------------------------------------------------------------
 
   /**
-   * Create a temporary hold on a time slot while payment is processing.
-   * This prevents double-booking during the checkout flow.
+   * Create an advisory temporary hold on a time slot while payment is
+   * processing. This is not a cross-backend reservation guarantee.
+   *
+   * Correctness still belongs to the backing scheduler's final booking
+   * conflict/rejection semantics, and backends should pair this with their own
+   * slot-scoped locking when they can.
    */
-  createReservation(params: {
+  softHoldSlot(params: {
     serviceId: string;
     providerId?: string;
     datetime: string;
     duration: number;
     expirationMinutes?: number;
     notes?: string;
-  }): SchedulingResult<SlotReservation>;
+  }): SchedulingResult<SlotSoftHold>;
 
   /**
-   * Release a slot reservation (after successful booking or timeout)
+   * Release a soft hold after successful booking, timeout, or abandonment.
    */
-  releaseReservation(reservationId: string): SchedulingResult<void>;
+  releaseSoftHold(softHoldId: string): SchedulingResult<void>;
 
   // ---------------------------------------------------------------------------
   // Bookings