@tummycrypt/acuity-middleware 0.1.0

package/src/adapters/types.ts

@@ -0,0 +1,193 @@
+/**
+ * Scheduling Adapter Interface
+ * Backend-agnostic contract for scheduling providers (Acuity, Cal.com, etc.)
+ */
+
+import type {
+  SchedulingResult,
+  Service,
+  Provider,
+  TimeSlot,
+  AvailableDate,
+  Booking,
+  BookingRequest,
+  SlotReservation,
+  ClientInfo,
+} from '../core/types.js';
+
+// =============================================================================
+// SCHEDULING ADAPTER INTERFACE
+// =============================================================================
+
+/**
+ * The core abstraction for scheduling backends.
+ * Implement this interface for Acuity, Cal.com, or any other provider.
+ */
+export interface SchedulingAdapter {
+  readonly name: string;
+
+  // ---------------------------------------------------------------------------
+  // Services (Appointment Types)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get all available services/appointment types
+   */
+  getServices(): SchedulingResult<Service[]>;
+
+  /**
+   * Get a specific service by ID
+   */
+  getService(serviceId: string): SchedulingResult<Service>;
+
+  // ---------------------------------------------------------------------------
+  // Providers (Calendars/Staff)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get all providers/calendars
+   */
+  getProviders(): SchedulingResult<Provider[]>;
+
+  /**
+   * Get a specific provider by ID
+   */
+  getProvider(providerId: string): SchedulingResult<Provider>;
+
+  /**
+   * Get providers available for a specific service
+   */
+  getProvidersForService(serviceId: string): SchedulingResult<Provider[]>;
+
+  // ---------------------------------------------------------------------------
+  // Availability
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get available dates for a service (and optionally a provider)
+   */
+  getAvailableDates(params: {
+    serviceId: string;
+    providerId?: string;
+    startDate: string; // YYYY-MM-DD
+    endDate: string;   // YYYY-MM-DD
+  }): SchedulingResult<AvailableDate[]>;
+
+  /**
+   * Get available time slots for a specific date
+   */
+  getAvailableSlots(params: {
+    serviceId: string;
+    providerId?: string;
+    date: string; // YYYY-MM-DD
+  }): SchedulingResult<TimeSlot[]>;
+
+  /**
+   * Check if a specific datetime is still available
+   */
+  checkSlotAvailability(params: {
+    serviceId: string;
+    providerId?: string;
+    datetime: string; // ISO 8601
+  }): SchedulingResult<boolean>;
+
+  // ---------------------------------------------------------------------------
+  // Slot Reservation (Hold)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Create a temporary hold on a time slot while payment is processing.
+   * This prevents double-booking during the checkout flow.
+   */
+  createReservation(params: {
+    serviceId: string;
+    providerId?: string;
+    datetime: string;
+    duration: number;
+    expirationMinutes?: number;
+    notes?: string;
+  }): SchedulingResult<SlotReservation>;
+
+  /**
+   * Release a slot reservation (after successful booking or timeout)
+   */
+  releaseReservation(reservationId: string): SchedulingResult<void>;
+
+  // ---------------------------------------------------------------------------
+  // Bookings
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Create a new booking/appointment
+   */
+  createBooking(request: BookingRequest): SchedulingResult<Booking>;
+
+  /**
+   * Create a booking with a payment reference stored in notes/metadata
+   * This is the key method for alt-payment integration
+   */
+  createBookingWithPaymentRef(
+    request: BookingRequest,
+    paymentRef: string,
+    paymentProcessor: string
+  ): SchedulingResult<Booking>;
+
+  /**
+   * Get a booking by ID
+   */
+  getBooking(bookingId: string): SchedulingResult<Booking>;
+
+  /**
+   * Cancel a booking
+   */
+  cancelBooking(bookingId: string, reason?: string): SchedulingResult<void>;
+
+  /**
+   * Reschedule a booking to a new datetime
+   */
+  rescheduleBooking(
+    bookingId: string,
+    newDatetime: string
+  ): SchedulingResult<Booking>;
+
+  // ---------------------------------------------------------------------------
+  // Clients
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Find or create a client
+   */
+  findOrCreateClient(client: ClientInfo): SchedulingResult<{ id: string; isNew: boolean }>;
+
+  /**
+   * Get client by email
+   */
+  getClientByEmail(email: string): SchedulingResult<ClientInfo | null>;
+}
+
+// =============================================================================
+// ADAPTER CONFIGURATION
+// =============================================================================
+
+export interface AcuityAdapterConfig {
+  readonly type: 'acuity';
+  readonly userId: string;
+  readonly apiKey: string;
+  readonly baseUrl?: string;
+}
+
+export interface CalComAdapterConfig {
+  readonly type: 'calcom';
+  readonly apiKey: string;
+  readonly baseUrl?: string;
+}
+
+export type SchedulingAdapterConfig = AcuityAdapterConfig | CalComAdapterConfig;
+
+// =============================================================================
+// ADAPTER FACTORY
+// =============================================================================
+
+export type CreateSchedulingAdapter = (
+  config: SchedulingAdapterConfig
+) => SchedulingAdapter;

package/src/core/types.ts

@@ -0,0 +1,325 @@
+/**
+ * Core types for scheduling-kit
+ * Backend-agnostic scheduling with fp-ts monadic composition
+ */
+
+import type { TaskEither } from 'fp-ts/TaskEither';
+import type { ReaderTaskEither } from 'fp-ts/ReaderTaskEither';
+
+// =============================================================================
+// ERROR TYPES (Discriminated Union)
+// =============================================================================
+
+export interface AcuityError {
+  readonly _tag: 'AcuityError';
+  readonly code: string;
+  readonly message: string;
+  readonly statusCode?: number;
+  readonly endpoint?: string;
+}
+
+export interface CalComError {
+  readonly _tag: 'CalComError';
+  readonly code: string;
+  readonly message: string;
+  readonly statusCode?: number;
+}
+
+export interface PaymentError {
+  readonly _tag: 'PaymentError';
+  readonly code: string;
+  readonly message: string;
+  readonly processor: string;
+  readonly transactionId?: string;
+  readonly recoverable: boolean;
+}
+
+export interface ValidationError {
+  readonly _tag: 'ValidationError';
+  readonly field: string;
+  readonly message: string;
+  readonly value?: unknown;
+}
+
+export interface ReservationError {
+  readonly _tag: 'ReservationError';
+  readonly code: 'SLOT_TAKEN' | 'BLOCK_FAILED' | 'TIMEOUT';
+  readonly message: string;
+  readonly datetime?: string;
+}
+
+export interface IdempotencyError {
+  readonly _tag: 'IdempotencyError';
+  readonly key: string;
+  readonly existingResult?: unknown;
+}
+
+export interface InfrastructureError {
+  readonly _tag: 'InfrastructureError';
+  readonly code: 'NETWORK' | 'TIMEOUT' | 'REDIS' | 'UNKNOWN';
+  readonly message: string;
+  readonly cause?: Error;
+}
+
+export type SchedulingError =
+  | AcuityError
+  | CalComError
+  | PaymentError
+  | ValidationError
+  | ReservationError
+  | IdempotencyError
+  | InfrastructureError;
+
+// =============================================================================
+// ERROR CONSTRUCTORS
+// =============================================================================
+
+export const Errors = {
+  acuity: (code: string, message: string, statusCode?: number, endpoint?: string): AcuityError => ({
+    _tag: 'AcuityError',
+    code,
+    message,
+    statusCode,
+    endpoint,
+  }),
+
+  calcom: (code: string, message: string, statusCode?: number): CalComError => ({
+    _tag: 'CalComError',
+    code,
+    message,
+    statusCode,
+  }),
+
+  payment: (
+    code: string,
+    message: string,
+    processor: string,
+    recoverable = false,
+    transactionId?: string
+  ): PaymentError => ({
+    _tag: 'PaymentError',
+    code,
+    message,
+    processor,
+    recoverable,
+    transactionId,
+  }),
+
+  validation: (field: string, message: string, value?: unknown): ValidationError => ({
+    _tag: 'ValidationError',
+    field,
+    message,
+    value,
+  }),
+
+  reservation: (
+    code: 'SLOT_TAKEN' | 'BLOCK_FAILED' | 'TIMEOUT',
+    message: string,
+    datetime?: string
+  ): ReservationError => ({
+    _tag: 'ReservationError',
+    code,
+    message,
+    datetime,
+  }),
+
+  idempotency: (key: string, existingResult?: unknown): IdempotencyError => ({
+    _tag: 'IdempotencyError',
+    key,
+    existingResult,
+  }),
+
+  infrastructure: (
+    code: 'NETWORK' | 'TIMEOUT' | 'REDIS' | 'UNKNOWN',
+    message: string,
+    cause?: Error
+  ): InfrastructureError => ({
+    _tag: 'InfrastructureError',
+    code,
+    message,
+    cause,
+  }),
+} as const;
+
+// =============================================================================
+// MONADIC TYPES
+// =============================================================================
+
+/**
+ * The core result type - TaskEither for async operations with typed errors
+ */
+export type SchedulingResult<A> = TaskEither<SchedulingError, A>;
+
+/**
+ * Reader variant for dependency injection
+ */
+export type SchedulingReader<Env, A> = ReaderTaskEither<Env, SchedulingError, A>;
+
+// =============================================================================
+// DOMAIN TYPES
+// =============================================================================
+
+export interface Service {
+  readonly id: string;
+  readonly name: string;
+  readonly description?: string;
+  readonly duration: number; // minutes
+  readonly price: number; // cents
+  readonly currency: string;
+  readonly category?: string;
+  readonly color?: string;
+  readonly active: boolean;
+}
+
+export interface Provider {
+  readonly id: string;
+  readonly name: string;
+  readonly email?: string;
+  readonly description?: string;
+  readonly image?: string;
+  readonly timezone: string;
+}
+
+export interface TimeSlot {
+  readonly datetime: string; // ISO 8601
+  readonly available: boolean;
+  readonly providerId?: string;
+}
+
+export interface AvailableDate {
+  readonly date: string; // YYYY-MM-DD
+  readonly slots: number;
+}
+
+export interface ClientInfo {
+  readonly firstName: string;
+  readonly lastName: string;
+  readonly email: string;
+  readonly phone?: string;
+  readonly notes?: string;
+  readonly customFields?: Record<string, string>;
+}
+
+export interface BookingRequest {
+  readonly serviceId: string;
+  readonly providerId?: string;
+  readonly datetime: string;
+  readonly client: ClientInfo;
+  readonly paymentMethod?: string;
+  readonly idempotencyKey: string;
+}
+
+export interface Booking {
+  readonly id: string;
+  readonly serviceId: string;
+  readonly serviceName: string;
+  readonly providerId?: string;
+  readonly providerName?: string;
+  readonly datetime: string;
+  readonly endTime: string;
+  readonly duration: number;
+  readonly price: number;
+  readonly currency: string;
+  readonly client: ClientInfo;
+  readonly status: BookingStatus;
+  readonly confirmationCode?: string;
+  readonly paymentStatus: PaymentStatus;
+  readonly paymentRef?: string;
+  readonly createdAt: string;
+}
+
+export type BookingStatus = 'confirmed' | 'pending' | 'cancelled' | 'completed' | 'no-show';
+export type PaymentStatus = 'pending' | 'paid' | 'refunded' | 'failed';
+
+export interface SlotReservation {
+  readonly id: string;
+  readonly datetime: string;
+  readonly duration: number;
+  readonly expiresAt: string;
+  readonly providerId?: string;
+}
+
+// =============================================================================
+// PAYMENT TYPES
+// =============================================================================
+
+export interface PaymentIntent {
+  readonly id: string;
+  readonly amount: number; // cents
+  readonly currency: string;
+  readonly status: 'pending' | 'processing' | 'completed' | 'failed' | 'cancelled';
+  readonly processor: string;
+  readonly processorTransactionId?: string;
+  readonly metadata?: Record<string, unknown>;
+  readonly createdAt: string;
+  readonly expiresAt?: string;
+}
+
+export interface PaymentResult {
+  readonly success: boolean;
+  readonly transactionId: string;
+  readonly processor: string;
+  readonly amount: number;
+  readonly currency: string;
+  readonly timestamp: string;
+  readonly receiptUrl?: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface RefundResult {
+  readonly success: boolean;
+  readonly refundId: string;
+  readonly originalTransactionId: string;
+  readonly amount: number;
+  readonly currency: string;
+  readonly timestamp: string;
+}
+
+// =============================================================================
+// CHECKOUT STATE TYPES
+// =============================================================================
+
+export type CheckoutStep =
+  | 'service'
+  | 'provider'
+  | 'datetime'
+  | 'details'
+  | 'payment'
+  | 'confirm'
+  | 'complete'
+  | 'error';
+
+export interface CheckoutState {
+  readonly step: CheckoutStep;
+  readonly service?: Service;
+  readonly provider?: Provider;
+  readonly datetime?: string;
+  readonly client?: ClientInfo;
+  readonly paymentIntent?: PaymentIntent;
+  readonly paymentResult?: PaymentResult;
+  readonly booking?: Booking;
+  readonly reservation?: SlotReservation;
+  readonly error?: SchedulingError;
+}
+
+// =============================================================================
+// CONFIGURATION TYPES
+// =============================================================================
+
+export interface SchedulingConfig {
+  readonly timezone: string;
+  readonly currency: string;
+  readonly locale: string;
+  readonly minAdvanceHours: number;
+  readonly maxAdvanceDays: number;
+  readonly slotReservationMinutes: number;
+}
+
+export const DEFAULT_CONFIG: SchedulingConfig = {
+  timezone: 'America/New_York',
+  currency: 'USD',
+  locale: 'en-US',
+  minAdvanceHours: 2,
+  maxAdvanceDays: 60,
+  slotReservationMinutes: 15,
+};

package/src/index.ts

@@ -0,0 +1,75 @@
+/**
+ * @tummycrypt/acuity-middleware
+ *
+ * Playwright-based Acuity booking middleware server.
+ * Proxies booking operations through browser automation.
+ */
+
+// Core types
+export type {
+	Service,
+	Provider,
+	TimeSlot,
+	AvailableDate,
+	Booking,
+	BookingRequest,
+	ClientInfo,
+	SchedulingError,
+	SchedulingResult,
+	BookingStatus,
+	PaymentStatus,
+} from './core/types.js';
+export { Errors } from './core/types.js';
+
+// Adapter interface
+export type { SchedulingAdapter } from './adapters/types.js';
+
+// Middleware exports
+export {
+	createWizardAdapter,
+	type WizardAdapterConfig,
+} from './middleware/acuity-wizard.js';
+
+export {
+	createRemoteWizardAdapter,
+	type RemoteAdapterConfig,
+} from './middleware/remote-adapter.js';
+
+export {
+	BrowserService,
+	BrowserServiceLive,
+	BrowserServiceTest,
+	defaultBrowserConfig,
+	type BrowserConfig,
+	type BrowserServiceShape,
+} from './middleware/browser-service.js';
+
+export {
+	BrowserError,
+	SelectorError,
+	WizardStepError,
+	CouponError,
+	toSchedulingError,
+	type MiddlewareError,
+} from './middleware/errors.js';
+
+export {
+	Selectors,
+	resolveSelector,
+	resolve,
+	probeSelector,
+	probe,
+	healthCheck,
+	type SelectorKey,
+	type ResolvedSelector,
+} from './middleware/selectors.js';
+
+// Scraper
+export {
+	createScraperAdapter,
+	AcuityScraper,
+	type ScraperConfig,
+} from './adapters/acuity-scraper.js';
+
+// Server
+export { server } from './middleware/server.js';