@tummycrypt/acuity-middleware 0.1.0

package/src/middleware/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Middleware Module - Server-only Acuity wizard automation
+ *
+ * This module provides the Effect TS-based browser middleware for
+ * puppeteering the Acuity scheduling wizard. It is a SEPARATE subpath
+ * export (`@tummycrypt/scheduling-kit/middleware`) and should NOT be
+ * imported in client-side code (it depends on Playwright).
+ *
+ * @example
+ * ```typescript
+ * import { createWizardAdapter } from '@tummycrypt/scheduling-kit/middleware';
+ * import { createSchedulingKit } from '@tummycrypt/scheduling-kit';
+ * import { createVenmoAdapter } from '@tummycrypt/scheduling-kit/payments';
+ *
+ * const scheduler = createWizardAdapter({
+ *   baseUrl: process.env.ACUITY_BASE_URL,
+ *   couponCode: process.env.ACUITY_BYPASS_COUPON,
+ * });
+ *
+ * const venmo = createVenmoAdapter({ ... });
+ * const kit = createSchedulingKit(scheduler, [venmo]);
+ *
+ * // Full booking with Venmo payment
+ * const result = await kit.completeBooking(request, 'venmo')();
+ * ```
+ */
+
+// Adapter factories
+export { createWizardAdapter, type WizardAdapterConfig } from './acuity-wizard.js';
+export { createRemoteWizardAdapter, type RemoteAdapterConfig } from './remote-adapter.js';
+
+// Browser service (for custom Layer composition)
+export {
+	BrowserService,
+	BrowserServiceLive,
+	BrowserServiceTest,
+	defaultBrowserConfig,
+	type BrowserConfig,
+	type BrowserServiceShape,
+} from './browser-service.js';
+
+// Error types and bridge
+export {
+	BrowserError,
+	SelectorError,
+	WizardStepError,
+	CouponError,
+	toSchedulingError,
+	type MiddlewareError,
+} from './errors.js';
+
+// Selector registry
+export {
+	Selectors,
+	resolveSelector,
+	resolve,
+	probeSelector,
+	probe,
+	healthCheck,
+	type SelectorKey,
+	type ResolvedSelector,
+} from './selectors.js';
+
+// Individual wizard steps (for advanced composition)
+export {
+	navigateToBooking,
+	fillFormFields,
+	bypassPayment,
+	generateCouponCode,
+	submitBooking,
+	extractConfirmation,
+	toBooking,
+	type NavigateParams,
+	type NavigateResult,
+	type FillFormParams,
+	type FillFormResult,
+	type BypassPaymentResult,
+	type SubmitResult,
+	type ConfirmationData,
+} from './steps/index.js';

package/src/middleware/remote-adapter.ts

@@ -0,0 +1,246 @@
+/**
+ * Remote Wizard Adapter
+ *
+ * SchedulingAdapter implementation backed by HTTP calls to a remote
+ * middleware server running Playwright + Chromium (e.g., Modal Labs,
+ * Fly.io, or any Docker host).
+ *
+ * This adapter is the client-side counterpart to `middleware/server.ts`.
+ * It serializes requests, sends them over HTTP, and deserializes
+ * responses back into fp-ts TaskEither types.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createRemoteWizardAdapter({
+ *   baseUrl: process.env.MODAL_MIDDLEWARE_URL,
+ *   authToken: process.env.MODAL_AUTH_TOKEN,
+ * });
+ * const kit = createSchedulingKit(adapter, [venmoAdapter]);
+ * ```
+ */
+
+import * as TE from 'fp-ts/TaskEither';
+import { pipe } from 'fp-ts/function';
+import type { SchedulingAdapter } from '../adapters/types.js';
+import type {
+	Booking,
+	BookingRequest,
+	Service,
+	Provider,
+	TimeSlot,
+	AvailableDate,
+	SlotReservation,
+	ClientInfo,
+	SchedulingError,
+	SchedulingResult,
+} from '../core/types.js';
+import { Errors } from '../core/types.js';
+
+// =============================================================================
+// CONFIGURATION
+// =============================================================================
+
+export interface RemoteAdapterConfig {
+	/** Base URL of the middleware server (e.g., https://scheduling-middleware--org.modal.run) */
+	readonly baseUrl: string;
+	/** Auth token for the middleware server */
+	readonly authToken?: string;
+	/** Request timeout in ms (default: 60000 - wizard flow can take 30s+) */
+	readonly timeout?: number;
+	/** Coupon code for payment bypass */
+	readonly couponCode?: string;
+}
+
+// =============================================================================
+// HTTP HELPERS
+// =============================================================================
+
+interface RemoteResponse<T> {
+	readonly success: boolean;
+	readonly data?: T;
+	readonly error?: {
+		readonly tag: string;
+		readonly code: string;
+		readonly message: string;
+	};
+}
+
+const makeRequest = <T>(
+	config: RemoteAdapterConfig,
+	path: string,
+	method: 'GET' | 'POST',
+	body?: unknown,
+): SchedulingResult<T> =>
+	TE.tryCatch(
+		async () => {
+			const url = `${config.baseUrl}${path}`;
+			const headers: Record<string, string> = {
+				'Content-Type': 'application/json',
+			};
+			if (config.authToken) {
+				headers['Authorization'] = `Bearer ${config.authToken}`;
+			}
+
+			const response = await fetch(url, {
+				method,
+				headers,
+				body: body ? JSON.stringify(body) : undefined,
+				signal: AbortSignal.timeout(config.timeout ?? 60000),
+			});
+
+			if (!response.ok) {
+				const errorBody = await response.json().catch(() => ({})) as RemoteResponse<never>;
+				throw Object.assign(new Error(errorBody.error?.message ?? `HTTP ${response.status}`), {
+					tag: errorBody.error?.tag ?? 'InfrastructureError',
+					code: errorBody.error?.code ?? 'NETWORK',
+				});
+			}
+
+			const json = (await response.json()) as RemoteResponse<T>;
+
+			if (!json.success && json.error) {
+				throw Object.assign(new Error(json.error.message), {
+					tag: json.error.tag,
+					code: json.error.code,
+				});
+			}
+
+			return json.data as T;
+		},
+		(e): SchedulingError => {
+			if (e instanceof Error && 'tag' in e) {
+				const tagged = e as Error & { tag: string; code: string };
+				return mapRemoteError(tagged.tag, tagged.code, tagged.message);
+			}
+			if (e instanceof DOMException && e.name === 'TimeoutError') {
+				return Errors.infrastructure('TIMEOUT', 'Middleware server request timed out');
+			}
+			return Errors.infrastructure(
+				'NETWORK',
+				`Middleware server error: ${e instanceof Error ? e.message : String(e)}`,
+			);
+		},
+	);
+
+const mapRemoteError = (tag: string, code: string, message: string): SchedulingError => {
+	switch (tag) {
+		case 'AcuityError':
+			return Errors.acuity(code, message);
+		case 'PaymentError':
+			return Errors.payment(code, message, 'remote');
+		case 'ValidationError':
+			return Errors.validation(code, message);
+		case 'ReservationError':
+			return Errors.reservation(code as 'SLOT_TAKEN' | 'BLOCK_FAILED' | 'TIMEOUT', message);
+		case 'InfrastructureError':
+		default:
+			return Errors.infrastructure(
+				(code as 'NETWORK' | 'TIMEOUT' | 'REDIS' | 'UNKNOWN') ?? 'UNKNOWN',
+				message,
+			);
+	}
+};
+
+// =============================================================================
+// ADAPTER FACTORY
+// =============================================================================
+
+/**
+ * Create a SchedulingAdapter that proxies all operations to a remote
+ * middleware server via HTTP. The remote server runs Playwright + Chromium
+ * and executes the actual wizard automation.
+ */
+export const createRemoteWizardAdapter = (config: RemoteAdapterConfig): SchedulingAdapter => ({
+	name: 'acuity-wizard-remote',
+
+	// ---------------------------------------------------------------------------
+	// Read operations - proxied to remote scraper
+	// ---------------------------------------------------------------------------
+
+	getServices: () =>
+		makeRequest<Service[]>(config, '/services', 'GET'),
+
+	getService: (serviceId) =>
+		makeRequest<Service>(config, `/services/${encodeURIComponent(serviceId)}`, 'GET'),
+
+	getProviders: () =>
+		TE.right([{
+			id: '1',
+			name: 'Default Provider',
+			email: 'provider@example.com',
+			description: 'Primary provider',
+			timezone: 'America/New_York',
+		}]),
+
+	getProvider: () =>
+		TE.right({
+			id: '1',
+			name: 'Default Provider',
+			email: 'provider@example.com',
+			description: 'Primary provider',
+			timezone: 'America/New_York',
+		}),
+
+	getProvidersForService: () =>
+		TE.right([{
+			id: '1',
+			name: 'Default Provider',
+			email: 'provider@example.com',
+			description: 'Primary provider',
+			timezone: 'America/New_York',
+		}]),
+
+	getAvailableDates: (params) =>
+		makeRequest<AvailableDate[]>(config, '/availability/dates', 'POST', params),
+
+	getAvailableSlots: (params) =>
+		makeRequest<TimeSlot[]>(config, '/availability/slots', 'POST', params),
+
+	checkSlotAvailability: (params) =>
+		makeRequest<boolean>(config, '/availability/check', 'POST', params),
+
+	// ---------------------------------------------------------------------------
+	// Reservation - not supported (pipeline has graceful fallback)
+	// ---------------------------------------------------------------------------
+
+	createReservation: () =>
+		TE.left(Errors.reservation('BLOCK_FAILED', 'Reservations not supported by remote wizard adapter')),
+
+	releaseReservation: () => TE.right(undefined),
+
+	// ---------------------------------------------------------------------------
+	// Write operations - proxied to remote wizard
+	// ---------------------------------------------------------------------------
+
+	createBooking: (request) =>
+		makeRequest<Booking>(config, '/booking/create', 'POST', {
+			request,
+			couponCode: config.couponCode,
+		}),
+
+	createBookingWithPaymentRef: (request, paymentRef, paymentProcessor) =>
+		makeRequest<Booking>(config, '/booking/create-with-payment', 'POST', {
+			request,
+			paymentRef,
+			paymentProcessor,
+			couponCode: config.couponCode,
+		}),
+
+	getBooking: () =>
+		TE.left(Errors.acuity('NOT_IMPLEMENTED', 'Get booking not yet supported via wizard')),
+
+	cancelBooking: () =>
+		TE.left(Errors.acuity('NOT_IMPLEMENTED', 'Cancel not yet supported via wizard')),
+
+	rescheduleBooking: () =>
+		TE.left(Errors.acuity('NOT_IMPLEMENTED', 'Reschedule not yet supported via wizard')),
+
+	// ---------------------------------------------------------------------------
+	// Client - pass-through
+	// ---------------------------------------------------------------------------
+
+	findOrCreateClient: (client) =>
+		TE.right({ id: `local-${client.email}`, isNew: true }),
+
+	getClientByEmail: () => TE.right(null),
+});

package/src/middleware/selectors.ts

@@ -0,0 +1,308 @@
+/**
+ * Acuity CSS Selector Registry
+ *
+ * Single source of truth for all CSS selectors used by the wizard middleware.
+ * Each selector has a primary pattern and fallback chain.
+ * When Acuity changes their DOM, fix this ONE file.
+ */
+
+import { Effect } from 'effect';
+import type { Page, ElementHandle } from 'playwright-core';
+import { SelectorError } from './errors.js';
+
+// =============================================================================
+// SELECTOR DEFINITIONS
+// =============================================================================
+
+/**
+ * Acuity Scheduling (2026 React SPA) CSS Selector Registry
+ *
+ * Verified against live DOM: 2026-02-25
+ * Uses Emotion CSS-in-JS (css-* hashes are UNSTABLE — prefer semantic classes)
+ *
+ * Wizard flow:
+ *   1. Service page: massageithaca.as.me → <li.select-item> list with "Book" buttons
+ *   2. Calendar page: /schedule/<hash>/appointment/<aptId>/calendar/<calId>
+ *      - react-calendar month grid + available-times-container
+ *   3. Client form: (after selecting time slot) → input fields
+ *   4. Payment/coupon: certificate input → Apply → verify $0
+ *   5. Submit → confirmation
+ *
+ * URL pattern (no query params):
+ *   /schedule/<hash>/appointment/<appointmentTypeId>/calendar/<calendarId>
+ */
+export const Selectors = {
+	// -- Service selection page --
+	// Services are <li class="select-item select-item-box"> with NO <a> links
+	// Categories use <div class="select-type"> with <div class="select-label">
+	serviceList: ['.select-item', '.select-item-box', '.appointment-type-item'],
+	serviceName: ['.appointment-type-name', '.type-name', 'h3'],
+	serviceLink: ['.select-item', '.select-item-box'],
+	// Price & duration are combined: <span>30 minutes @ $150.00</span> inside .duration-container
+	servicePrice: ['.duration-container', '.duration-container span', '.price', '.cost'],
+	serviceDuration: ['.duration-container', '.duration-container span', '.duration', '.time-duration'],
+	serviceDescription: ['.type-description', '.description', 'p.type-description'],
+	// "Book" button inside each service item
+	serviceBookButton: ['button.btn', '.select-item button.btn'],
+	// Category labels
+	serviceCategory: ['.select-label', '.select-label p', '.select-type .select-label'],
+
+	// -- Calendar page (react-calendar component) --
+	// Wrapper: .monthly-calendar-v2 > .react-calendar.monthly-calendar-react-calendar
+	calendar: ['.monthly-calendar-v2', '.react-calendar', '.monthly-calendar-react-calendar'],
+	calendarMonth: ['.react-calendar__navigation__label', '.react-calendar__navigation__label__labelText'],
+	calendarPrev: ['.react-calendar__navigation__prev-button'],
+	calendarNext: ['.react-calendar__navigation__next-button'],
+	// Day tiles are buttons: <button class="react-calendar__tile react-calendar__month-view__days__day">1</button>
+	calendarDay: [
+		'.react-calendar__tile',
+		'.react-calendar__month-view__days__day',
+		'button.react-calendar__tile',
+	],
+	// Active/selected day: react-calendar__tile--active + custom "activeday" class
+	activeDay: [
+		'.react-calendar__tile--active',
+		'.activeday',
+		'.react-calendar__tile:not(:disabled)',
+	],
+
+	// -- Time slot selection --
+	// Container: .available-times-container
+	// Slots: <button class="time-selection">10:00 AM1 spot left</button>
+	// Selected: <button class="time-selection selected-time">
+	timeSlotContainer: ['.available-times-container'],
+	timeSlot: ['button.time-selection', '.time-selection', '.time-slot', '[data-time]'],
+	timeSlotSelected: ['button.time-selection.selected-time', '.selected-time'],
+	// "Select and continue" is an <li role="menuitem"> NOT a button
+	selectAndContinue: [
+		'li[role="menuitem"]',
+		'[data-keyboard-navigable="keyboard-navigable-list-item"]',
+		'text=Select and continue',
+	],
+
+	// -- Client form --
+	// Field names use "client." prefix: client.firstName, client.lastName, etc.
+	firstNameInput: ['input[name="client.firstName"]', '#client\\.firstName', 'input[name="firstName"]'],
+	lastNameInput: ['input[name="client.lastName"]', '#client\\.lastName', 'input[name="lastName"]'],
+	emailInput: ['input[name="client.email"]', '#client\\.email', 'input[name="email"]'],
+	phoneInput: ['input[name="client.phone"]', '#client\\.phone', 'input[name="phone"]'],
+	// "Continue to Payment" button on the form page
+	continueToPayment: [
+		'button.btn:has-text("Continue to Payment")',
+		'button:has-text("Continue to Payment")',
+		'button.btn[type="submit"]',
+	],
+	// "Check Code Balance" button for entering coupon codes
+	checkCodeBalance: [
+		'button:has-text("Check Code Balance")',
+		'button.css-9zfkvr',
+	],
+	// Terms agreement checkbox (custom field)
+	termsCheckbox: [
+		'input[type="checkbox"][name*="field-13933959"]',
+		'input[id*="13933959"]',
+	],
+
+	// -- Client form intake fields --
+	// Radio buttons have NO name or id attrs; are purely React-controlled.
+	// Strategy: click <label> wrapping the radio via locator().nth().
+	// 3 yes/no question groups, each with aria-required="true".
+	radioNoLabel: ['label:has(input[type="radio"][value="no"])'],
+	radioYesLabel: ['label:has(input[type="radio"][value="yes"])'],
+	// "How did you hear" multi-checkbox (REQUIRED — at least 1 must be checked)
+	// Names: "Internet search", "google maps", "referral from Noha Acupuncture",
+	//        "referral from dentist", "referral from PT or other practitioner"
+	howDidYouHearCheckbox: [
+		'input[type="checkbox"][name="Internet search"]',
+		'label:has(input[type="checkbox"][name="Internet search"])',
+	],
+	// Medication textarea
+	medicationField: [
+		'textarea[name="fields[field-16606770]"]',
+		'#fields\\[field-16606770\\]',
+	],
+
+	// -- Payment / coupon --
+	// PAYMENT IS A SEPARATE PAGE at URL .../datetime/<ISO>/payment
+	// Verified 2026-02-26: Square-powered (NOT Stripe).
+	//
+	// "Check Code Balance" modal on client form page is INFORMATIONAL ONLY.
+	// The REAL coupon entry is on the PAYMENT page:
+	//   "Package, gift, or coupon code" expandable section
+	//
+	// Client form modal selectors (kept for reference):
+	couponField: ['#code', 'input#code', 'input[id="code"]'],
+	couponTabByCode: [
+		'button:has-text("Check by code")',
+		'button.css-1jjp8vb:has-text("Check by code")',
+	],
+	couponConfirmButton: [
+		'[role="dialog"] button:has-text("Confirm")',
+		'button.css-qgmcoe',
+		'button:has-text("Confirm")',
+	],
+	couponCloseButton: ['button:has-text("Close")', 'button.css-ve50y1'],
+	couponError: [
+		'[role="dialog"] p:has-text("weren\'t able to recognize")',
+		'[role="dialog"] p:has-text("try entering it again")',
+		'p.css-7bwtx1',
+	],
+	couponSuccess: [
+		'[role="dialog"] p:has-text("balance")',
+		'[role="dialog"] [class*="success"]',
+		'.coupon-applied',
+		'.certificate-success',
+	],
+
+	// -- Payment page (Square checkout) --
+	// URL pattern: .../datetime/<ISO>/payment
+	// "Package, gift, or coupon code" expandable section is the coupon entry point.
+	paymentCouponToggle: [
+		'button:has-text("Package, gift, or coupon code")',
+		'text=Package, gift, or coupon code',
+	],
+	// After expanding: input placeholder="Enter code" (React id unstable like :r9:)
+	// and an "Apply" button. Verified 2026-02-26.
+	paymentCouponInput: ['input[placeholder="Enter code"]', 'input[placeholder*="code" i]', 'input[name*="coupon"]'],
+	paymentCouponApply: ['button:has-text("Apply")', 'button:has-text("Redeem")'],
+	// After applying, the certificate shows with a "REMOVE" link
+	paymentCouponRemove: ['text=REMOVE', 'a:has-text("REMOVE")', 'button:has-text("REMOVE")'],
+	// Order summary on payment page
+	paymentTotal: ['.order-total', '.payment-total', '.total-amount', 'text=$0.00'],
+	paymentSubtotal: ['text=Subtotal'],
+	// Pay & Confirm button (the final submit on payment page)
+	payAndConfirm: [
+		'button:has-text("Pay & Confirm")',
+		'button:has-text("PAY & CONFIRM")',
+		'button:has-text("Confirm Appointment")',
+	],
+
+	// -- Checkout / submit (legacy — use payAndConfirm for payment page) --
+	submitButton: [
+		'button:has-text("Pay & Confirm")',
+		'button:has-text("PAY & CONFIRM")',
+		'button[type="submit"].confirm',
+		'.complete-booking',
+		'#submit-booking',
+		'button:has-text("Complete Appointment")',
+		'button:has-text("Book Now")',
+		'button:has-text("Schedule")',
+	],
+
+	// -- Confirmation page --
+	confirmationPage: ['.confirmation', '.booking-confirmed', '.thank-you', '#confirmation'],
+	confirmationId: ['.confirmation-number', '.appointment-id', '[data-confirmation]'],
+	confirmationService: ['.appointment-type', '.service-name', '.booked-service'],
+	confirmationDatetime: ['.appointment-datetime', '.booked-time', '.booking-date'],
+} as const;
+
+// =============================================================================
+// SELECTOR TYPE
+// =============================================================================
+
+export type SelectorKey = keyof typeof Selectors;
+
+export interface ResolvedSelector {
+	readonly selector: string;
+	readonly element: ElementHandle;
+}
+
+// =============================================================================
+// RESOLUTION UTILITIES
+// =============================================================================
+
+/**
+ * Try selectors in order, return the first match.
+ * Fails with SelectorError if none match.
+ */
+export const resolveSelector = (
+	page: Page,
+	candidates: readonly string[],
+	timeout = 3000,
+): Effect.Effect<ResolvedSelector, SelectorError> =>
+	Effect.gen(function* () {
+		for (const selector of candidates) {
+			const el = yield* Effect.tryPromise({
+				try: () =>
+					page.waitForSelector(selector, { timeout, state: 'attached' }).then(
+						(handle) => handle,
+						() => null,
+					),
+				catch: () => null,
+			}).pipe(Effect.orElseSucceed(() => null));
+
+			if (el) {
+				return { selector, element: el } as ResolvedSelector;
+			}
+		}
+
+		return yield* Effect.fail(
+			new SelectorError({
+				candidates,
+				message: `None of [${candidates.join(', ')}] found within ${timeout}ms`,
+			}),
+		);
+	});
+
+/**
+ * Resolve a selector from the registry by key name.
+ */
+export const resolve = (
+	page: Page,
+	key: SelectorKey,
+	timeout?: number,
+): Effect.Effect<ResolvedSelector, SelectorError> =>
+	resolveSelector(page, Selectors[key], timeout);
+
+/**
+ * Check if any selector in the candidates list exists on the page (non-blocking).
+ * Returns the matching selector string or null.
+ */
+export const probeSelector = (
+	page: Page,
+	candidates: readonly string[],
+): Effect.Effect<string | null, never> =>
+	Effect.gen(function* () {
+		for (const selector of candidates) {
+			const exists = yield* Effect.tryPromise({
+				try: () => page.$(selector).then((el) => el !== null),
+				catch: () => false,
+			}).pipe(Effect.orElseSucceed(() => false));
+
+			if (exists) return selector;
+		}
+		return null;
+	});
+
+/**
+ * Probe a selector from the registry by key name.
+ */
+export const probe = (page: Page, key: SelectorKey): Effect.Effect<string | null, never> =>
+	probeSelector(page, Selectors[key]);
+
+/**
+ * Validate that all critical selectors can be resolved on the current page.
+ * Returns a report of which selectors passed/failed.
+ */
+export const healthCheck = (
+	page: Page,
+	keys: readonly SelectorKey[],
+): Effect.Effect<
+	{ passed: SelectorKey[]; failed: SelectorKey[] },
+	never
+> =>
+	Effect.gen(function* () {
+		const passed: SelectorKey[] = [];
+		const failed: SelectorKey[] = [];
+
+		for (const key of keys) {
+			const found = yield* probe(page, key);
+			if (found) {
+				passed.push(key);
+			} else {
+				failed.push(key);
+			}
+		}
+
+		return { passed, failed };
+	});