@thebookingkit/server 0.1.2 → 0.1.5

package/src/__tests__/api.test.ts

@@ -1,354 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import {
-  createErrorResponse,
-  createSuccessResponse,
-  createPaginatedResponse,
-  generateApiKey,
-  hashApiKey,
-  verifyApiKey,
-  hasScope,
-  isKeyExpired,
-  checkRateLimit,
-  encodeCursor,
-  decodeCursor,
-  validateSlotQueryParams,
-  parseSortParam,
-  API_ERROR_CODES,
-  type ApiKeyScope,
-} from "../api.js";
-
-// Set the required env var for API key hashing in tests
-process.env.THEBOOKINGKIT_API_KEY_SECRET = "test-secret-for-unit-tests-only";
-
-// ---------------------------------------------------------------------------
-// Response Helpers
-// ---------------------------------------------------------------------------
-
-describe("createErrorResponse", () => {
-  it("creates a standard error envelope", () => {
-    const response = createErrorResponse("NOT_FOUND", "Booking not found");
-    expect(response).toEqual({
-      error: { code: "NOT_FOUND", message: "Booking not found" },
-    });
-  });
-
-  it("includes details when provided", () => {
-    const response = createErrorResponse(
-      "VALIDATION_ERROR",
-      "Invalid input",
-      { field: "email" },
-    );
-    expect(response.error.details).toEqual({ field: "email" });
-  });
-
-  it("omits details when not provided", () => {
-    const response = createErrorResponse("UNAUTHORIZED", "Invalid key");
-    expect(response.error.details).toBeUndefined();
-  });
-});
-
-describe("createSuccessResponse", () => {
-  it("wraps data in a success envelope", () => {
-    const response = createSuccessResponse({ id: "bk-1" });
-    expect(response).toEqual({ data: { id: "bk-1" } });
-  });
-
-  it("includes meta when provided", () => {
-    const response = createSuccessResponse([], {
-      nextCursor: "abc",
-      hasMore: true,
-    });
-    expect(response.meta?.nextCursor).toBe("abc");
-  });
-});
-
-describe("createPaginatedResponse", () => {
-  it("creates paginated response with cursor", () => {
-    const response = createPaginatedResponse(["a", "b"], "cursor123", 10);
-    expect(response.data).toEqual(["a", "b"]);
-    expect(response.meta.nextCursor).toBe("cursor123");
-    expect(response.meta.hasMore).toBe(true);
-    expect(response.meta.total).toBe(10);
-  });
-
-  it("marks hasMore false when nextCursor is null", () => {
-    const response = createPaginatedResponse(["a"], null);
-    expect(response.meta.hasMore).toBe(false);
-    expect(response.meta.nextCursor).toBeNull();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// API Key Management
-// ---------------------------------------------------------------------------
-
-describe("generateApiKey", () => {
-  it("generates a key with the given prefix", () => {
-    const { key } = generateApiKey("sk_live_");
-    expect(key).toMatch(/^sk_live_[0-9a-f]{64}$/);
-  });
-
-  it("generates a display prefix", () => {
-    const { prefix } = generateApiKey("sk_live_");
-    expect(prefix).toContain("...");
-  });
-
-  it("generates a 64-char hex hash", () => {
-    const { hash } = generateApiKey();
-    expect(hash).toMatch(/^[0-9a-f]{64}$/);
-  });
-
-  it("generates unique keys each time", () => {
-    const { key: k1 } = generateApiKey();
-    const { key: k2 } = generateApiKey();
-    expect(k1).not.toBe(k2);
-  });
-});
-
-describe("hashApiKey", () => {
-  it("throws when THEBOOKINGKIT_API_KEY_SECRET is missing", () => {
-    const original = process.env.THEBOOKINGKIT_API_KEY_SECRET;
-    delete process.env.THEBOOKINGKIT_API_KEY_SECRET;
-    try {
-      expect(() => hashApiKey("sk_live_test")).toThrow(
-        "THEBOOKINGKIT_API_KEY_SECRET environment variable is required",
-      );
-    } finally {
-      process.env.THEBOOKINGKIT_API_KEY_SECRET = original;
-    }
-  });
-
-  it("accepts an explicit secret parameter", () => {
-    const hash = hashApiKey("sk_live_test", "my-explicit-secret");
-    expect(hash).toMatch(/^[0-9a-f]{64}$/);
-  });
-});
-
-describe("verifyApiKey", () => {
-  it("returns true for correct key", () => {
-    const { key, hash } = generateApiKey();
-    expect(verifyApiKey(key, hash)).toBe(true);
-  });
-
-  it("returns false for tampered key", () => {
-    const { hash } = generateApiKey();
-    expect(verifyApiKey("sk_live_wrong", hash)).toBe(false);
-  });
-
-  it("returns false for wrong hash", () => {
-    const { key } = generateApiKey();
-    const { hash: otherHash } = generateApiKey();
-    expect(verifyApiKey(key, otherHash)).toBe(false);
-  });
-});
-
-describe("hasScope", () => {
-  it("returns true when scope is present", () => {
-    const scopes: ApiKeyScope[] = ["read:bookings", "write:bookings"];
-    expect(hasScope(scopes, "read:bookings")).toBe(true);
-  });
-
-  it("returns false when scope is absent", () => {
-    const scopes: ApiKeyScope[] = ["read:bookings"];
-    expect(hasScope(scopes, "write:bookings")).toBe(false);
-  });
-
-  it("admin scope grants all permissions", () => {
-    const scopes: ApiKeyScope[] = ["admin"];
-    expect(hasScope(scopes, "read:bookings")).toBe(true);
-    expect(hasScope(scopes, "write:event-types")).toBe(true);
-    expect(hasScope(scopes, "write:webhooks")).toBe(true);
-  });
-});
-
-describe("isKeyExpired", () => {
-  it("returns false for no expiry", () => {
-    expect(isKeyExpired(undefined)).toBe(false);
-    expect(isKeyExpired(null)).toBe(false);
-  });
-
-  it("returns true for past expiry", () => {
-    expect(isKeyExpired(new Date(Date.now() - 1000))).toBe(true);
-  });
-
-  it("returns false for future expiry", () => {
-    expect(isKeyExpired(new Date(Date.now() + 86400000))).toBe(false);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Rate Limiting
-// ---------------------------------------------------------------------------
-
-describe("checkRateLimit", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-    vi.setSystemTime(new Date("2026-03-15T14:00:00.000Z"));
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("allows first request", () => {
-    const { result } = checkRateLimit(null, 120);
-    expect(result.allowed).toBe(true);
-    expect(result.remaining).toBe(119);
-    expect(result.limit).toBe(120);
-  });
-
-  it("tracks requests within a window", () => {
-    const { newState } = checkRateLimit(null, 120);
-    const { result } = checkRateLimit(newState, 120);
-    expect(result.allowed).toBe(true);
-    expect(result.remaining).toBe(118);
-  });
-
-  it("blocks requests when limit exceeded", () => {
-    let state = checkRateLimit(null, 2).newState;
-    state = checkRateLimit(state, 2).newState;
-    const { result } = checkRateLimit(state, 2);
-    expect(result.allowed).toBe(false);
-    expect(result.remaining).toBe(0);
-  });
-
-  it("resets counter in new window", () => {
-    let state = checkRateLimit(null, 2).newState;
-    state = checkRateLimit(state, 2).newState;
-    // Advance to next minute
-    vi.advanceTimersByTime(60 * 1000);
-    const { result } = checkRateLimit(state, 2);
-    expect(result.allowed).toBe(true);
-    expect(result.remaining).toBe(1);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Cursor Pagination
-// ---------------------------------------------------------------------------
-
-describe("encodeCursor / decodeCursor", () => {
-  it("round-trips cursor data", () => {
-    const data = { id: "bk-1", createdAt: "2026-03-15T14:00:00Z" };
-    const cursor = encodeCursor(data);
-    const decoded = decodeCursor(cursor);
-    expect(decoded).toEqual(data);
-  });
-
-  it("returns null for invalid cursor", () => {
-    expect(decodeCursor("not-valid-base64!!!")).toBeNull();
-  });
-
-  it("returns null for non-JSON cursor", () => {
-    const cursor = Buffer.from("not json").toString("base64url");
-    expect(decodeCursor(cursor)).toBeNull();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// validateSlotQueryParams
-// ---------------------------------------------------------------------------
-
-describe("validateSlotQueryParams", () => {
-  const validParams = {
-    providerId: "prov-1",
-    start: "2026-03-15",
-    end: "2026-04-15",
-    timezone: "America/New_York",
-  };
-
-  it("accepts valid params", () => {
-    const result = validateSlotQueryParams(validParams);
-    expect(result.valid).toBe(true);
-    expect(result.errors).toHaveLength(0);
-  });
-
-  it("accepts teamId instead of providerId", () => {
-    const result = validateSlotQueryParams({
-      teamId: "team-1",
-      start: "2026-03-15",
-      end: "2026-04-15",
-    });
-    expect(result.valid).toBe(true);
-  });
-
-  it("rejects missing providerId and teamId", () => {
-    const result = validateSlotQueryParams({
-      start: "2026-03-15",
-      end: "2026-04-15",
-    });
-    expect(result.valid).toBe(false);
-    expect(result.errors[0].field).toBe("providerId");
-  });
-
-  it("rejects missing start date", () => {
-    const result = validateSlotQueryParams({
-      providerId: "p1",
-      end: "2026-04-15",
-    });
-    expect(result.valid).toBe(false);
-    expect(result.errors.some((e) => e.field === "start")).toBe(true);
-  });
-
-  it("rejects invalid start date", () => {
-    const result = validateSlotQueryParams({
-      providerId: "p1",
-      start: "not-a-date",
-      end: "2026-04-15",
-    });
-    expect(result.valid).toBe(false);
-  });
-
-  it("rejects end before start", () => {
-    const result = validateSlotQueryParams({
-      providerId: "p1",
-      start: "2026-04-15",
-      end: "2026-03-15",
-    });
-    expect(result.valid).toBe(false);
-    expect(result.errors.some((e) => e.message.includes("after start"))).toBe(
-      true,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// parseSortParam
-// ---------------------------------------------------------------------------
-
-describe("parseSortParam", () => {
-  const allowedFields = ["createdAt", "startsAt", "status"];
-
-  it("parses ascending sort", () => {
-    const result = parseSortParam("startsAt", allowedFields);
-    expect(result).toEqual({ field: "startsAt", direction: "asc" });
-  });
-
-  it("parses descending sort with leading minus", () => {
-    const result = parseSortParam("-createdAt", allowedFields);
-    expect(result).toEqual({ field: "createdAt", direction: "desc" });
-  });
-
-  it("returns null for invalid field", () => {
-    expect(parseSortParam("unknownField", allowedFields)).toBeNull();
-  });
-
-  it("returns null for undefined input", () => {
-    expect(parseSortParam(undefined, allowedFields)).toBeNull();
-  });
-});
-
-// ---------------------------------------------------------------------------
-// API_ERROR_CODES
-// ---------------------------------------------------------------------------
-
-describe("API_ERROR_CODES", () => {
-  it("exports all standard error codes", () => {
-    expect(API_ERROR_CODES.NOT_FOUND).toBe("NOT_FOUND");
-    expect(API_ERROR_CODES.UNAUTHORIZED).toBe("UNAUTHORIZED");
-    expect(API_ERROR_CODES.FORBIDDEN).toBe("FORBIDDEN");
-    expect(API_ERROR_CODES.VALIDATION_ERROR).toBe("VALIDATION_ERROR");
-    expect(API_ERROR_CODES.RATE_LIMITED).toBe("RATE_LIMITED");
-    expect(API_ERROR_CODES.CONFLICT).toBe("CONFLICT");
-  });
-});

package/src/__tests__/auth.test.ts

@@ -1,111 +0,0 @@
-import { describe, it, expect, vi } from "vitest";
-import {
-  withAuth,
-  assertProviderOwnership,
-  assertCustomerAccess,
-  UnauthorizedError,
-  ForbiddenError,
-  type AuthAdapter,
-  type AuthUser,
-} from "../index.js";
-
-function mockAdapter(user: AuthUser | null): AuthAdapter {
-  return {
-    getCurrentUser: vi.fn().mockResolvedValue(user),
-    getSession: vi.fn().mockResolvedValue(user ? { user, expires: new Date() } : null),
-    verifyToken: vi.fn().mockResolvedValue(user),
-  };
-}
-
-function mockRequest(headers: Record<string, string> = {}): Request {
-  return new Request("http://localhost/api/test", {
-    headers: new Headers(headers),
-  });
-}
-
-describe("withAuth", () => {
-  it("injects user and calls handler on valid session", async () => {
-    const user: AuthUser = { id: "user1", email: "test@test.com" };
-    const adapter = mockAdapter(user);
-    const handler = vi.fn().mockResolvedValue(Response.json({ ok: true }));
-
-    const wrapped = withAuth(adapter, handler);
-    const response = await wrapped(mockRequest());
-
-    expect(response.status).toBe(200);
-    expect(handler).toHaveBeenCalledTimes(1);
-    const calledReq = handler.mock.calls[0][0];
-    expect(calledReq.user).toEqual(user);
-  });
-
-  it("returns 401 when no user is authenticated", async () => {
-    const adapter = mockAdapter(null);
-    // verifyToken also returns null
-    adapter.verifyToken = vi.fn().mockResolvedValue(null);
-    const handler = vi.fn();
-
-    const wrapped = withAuth(adapter, handler);
-    const response = await wrapped(mockRequest());
-
-    expect(response.status).toBe(401);
-    expect(handler).not.toHaveBeenCalled();
-  });
-
-  it("falls back to Bearer token when session returns null", async () => {
-    const user: AuthUser = { id: "user2", email: "api@test.com" };
-    const adapter = mockAdapter(null);
-    adapter.getCurrentUser = vi.fn().mockResolvedValue(null);
-    adapter.verifyToken = vi.fn().mockResolvedValue(user);
-
-    const handler = vi.fn().mockResolvedValue(Response.json({ ok: true }));
-    const wrapped = withAuth(adapter, handler);
-    const response = await wrapped(
-      mockRequest({ Authorization: "Bearer test-token-123" }),
-    );
-
-    expect(response.status).toBe(200);
-    expect(adapter.verifyToken).toHaveBeenCalledWith("test-token-123");
-  });
-
-  it("returns 403 when role does not match", async () => {
-    const user: AuthUser = {
-      id: "user3",
-      email: "member@test.com",
-      role: "customer",
-    };
-    const adapter = mockAdapter(user);
-    const handler = vi.fn();
-
-    const wrapped = withAuth(adapter, handler, { requiredRole: "admin" });
-    const response = await wrapped(mockRequest());
-
-    expect(response.status).toBe(403);
-    expect(handler).not.toHaveBeenCalled();
-  });
-});
-
-describe("assertProviderOwnership", () => {
-  it("does not throw when user IDs match", () => {
-    expect(() => assertProviderOwnership("user1", "user1")).not.toThrow();
-  });
-
-  it("throws ForbiddenError when user IDs do not match", () => {
-    expect(() => assertProviderOwnership("user1", "user2")).toThrow(
-      ForbiddenError,
-    );
-  });
-});
-
-describe("assertCustomerAccess", () => {
-  it("does not throw when emails match", () => {
-    expect(() =>
-      assertCustomerAccess("a@test.com", "a@test.com"),
-    ).not.toThrow();
-  });
-
-  it("throws ForbiddenError when emails do not match", () => {
-    expect(() =>
-      assertCustomerAccess("a@test.com", "b@test.com"),
-    ).toThrow(ForbiddenError);
-  });
-});

package/src/__tests__/concurrent-booking.test.ts

@@ -1,170 +0,0 @@
-import { describe, it, expect } from "vitest";
-import {
-  withSerializableRetry,
-  BookingConflictError,
-  SerializationRetryExhaustedError,
-} from "../index.js";
-
-/**
- * Concurrent booking simulation tests.
- *
- * These tests simulate the load test from E01-S04:
- * "50 concurrent booking attempts for the same slot yields exactly 1 confirmed
- *  booking, 0 unhandled serialization errors, and all other callers receive
- *  a clear conflict response within 2 seconds."
- *
- * Since we can't connect to a real Postgres in unit tests, we simulate the
- * database behavior with an in-memory "slot lock" that mimics the EXCLUDE
- * constraint (SQLSTATE 23P01) and serialization failures (SQLSTATE 40001).
- */
-
-/** Simulates a Postgres error with a SQLSTATE code */
-class PgError extends Error {
-  code: string;
-  constructor(message: string, code: string) {
-    super(message);
-    this.name = "PgError";
-    this.code = code;
-  }
-}
-
-describe("Concurrent Booking Simulation (E01-S04 Load Test)", () => {
-  it("50 concurrent attempts for the same slot: exactly 1 success, rest get conflict", async () => {
-    // Simulate a database slot that can only be booked once.
-    // The first successful INSERT wins; subsequent attempts get exclusion_violation.
-    let slotBooked = false;
-    let serializationFailureCount = 0;
-    const maxSimulatedSerializationFailures = 5; // simulate some contention
-
-    const attemptBooking = async (attemptId: number): Promise<string> => {
-      return withSerializableRetry(
-        async () => {
-          // Simulate random serialization failures under contention
-          if (
-            !slotBooked &&
-            serializationFailureCount < maxSimulatedSerializationFailures &&
-            Math.random() < 0.3
-          ) {
-            serializationFailureCount++;
-            throw new PgError("serialization failure", "40001");
-          }
-
-          // Simulate the EXCLUDE constraint check
-          if (slotBooked) {
-            throw new PgError(
-              "conflicting key value violates exclusion constraint",
-              "23P01",
-            );
-          }
-
-          // Race: first writer wins
-          slotBooked = true;
-          return `booking-${attemptId}`;
-        },
-        { maxRetries: 3, baseDelayMs: 10 },
-      );
-    };
-
-    const CONCURRENCY = 50;
-    const results = await Promise.allSettled(
-      Array.from({ length: CONCURRENCY }, (_, i) => attemptBooking(i)),
-    );
-
-    const successes = results.filter((r) => r.status === "fulfilled");
-    const failures = results.filter((r) => r.status === "rejected");
-
-    // Exactly 1 booking should succeed
-    expect(successes.length).toBe(1);
-
-    // All failures should be BookingConflictError (not unhandled errors)
-    for (const failure of failures) {
-      if (failure.status === "rejected") {
-        expect(failure.reason).toBeInstanceOf(BookingConflictError);
-      }
-    }
-
-    // Zero unhandled serialization errors
-    const serializationErrors = failures.filter(
-      (f) =>
-        f.status === "rejected" &&
-        f.reason instanceof SerializationRetryExhaustedError,
-    );
-    expect(serializationErrors.length).toBe(0);
-  });
-
-  it("completes all 50 attempts within 2 seconds", async () => {
-    let slotBooked = false;
-
-    const attemptBooking = async (attemptId: number): Promise<string> => {
-      return withSerializableRetry(
-        async () => {
-          if (slotBooked) {
-            throw new PgError(
-              "conflicting key value violates exclusion constraint",
-              "23P01",
-            );
-          }
-          slotBooked = true;
-          return `booking-${attemptId}`;
-        },
-        { maxRetries: 3, baseDelayMs: 10 },
-      );
-    };
-
-    const start = Date.now();
-
-    await Promise.allSettled(
-      Array.from({ length: 50 }, (_, i) => attemptBooking(i)),
-    );
-
-    const elapsed = Date.now() - start;
-    expect(elapsed).toBeLessThan(2000);
-  });
-
-  it("serialization failures are retried and can succeed on a different slot", async () => {
-    let attempt = 0;
-
-    const result = await withSerializableRetry(
-      async () => {
-        attempt++;
-        if (attempt <= 2) {
-          throw new PgError("serialization failure", "40001");
-        }
-        return "booking-success";
-      },
-      { maxRetries: 3, baseDelayMs: 10 },
-    );
-
-    expect(result).toBe("booking-success");
-    expect(attempt).toBe(3);
-  });
-
-  it("retries are exhausted after maxRetries serialization failures", async () => {
-    const fn = () =>
-      withSerializableRetry(
-        async () => {
-          throw new PgError("serialization failure", "40001");
-        },
-        { maxRetries: 3, baseDelayMs: 10 },
-      );
-
-    await expect(fn()).rejects.toThrow(SerializationRetryExhaustedError);
-  });
-
-  it("exclusion violation (slot taken) is never retried", async () => {
-    let callCount = 0;
-
-    const fn = () =>
-      withSerializableRetry(
-        async () => {
-          callCount++;
-          throw new PgError("exclusion constraint", "23P01");
-        },
-        { maxRetries: 3, baseDelayMs: 10 },
-      );
-
-    await expect(fn()).rejects.toThrow(BookingConflictError);
-    // Should NOT have retried — only 1 call
-    expect(callCount).toBe(1);
-  });
-});