@tummycrypt/acuity-middleware 0.1.0

package/flake.nix

@@ -0,0 +1,32 @@
+{
+  description = "Acuity middleware dev shell";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    flake-utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem (system:
+      let
+        pkgs = nixpkgs.legacyPackages.${system};
+      in
+      {
+        devShells.default = pkgs.mkShell {
+          buildInputs = with pkgs; [
+            nodejs_22
+            nodePackages.pnpm
+            playwright-driver.browsers
+          ];
+
+          shellHook = ''
+            export PLAYWRIGHT_BROWSERS_PATH="${pkgs.playwright-driver.browsers}"
+            export PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+            echo "acuity-middleware dev shell"
+            echo "  node $(node --version)"
+            echo "  pnpm $(pnpm --version)"
+          '';
+        };
+      }
+    );
+}

package/modal-app.py

@@ -0,0 +1,82 @@
+"""
+Modal Labs deployment for the scheduling middleware server.
+
+Runs the Node.js middleware server with Playwright + Chromium
+inside a Modal container with GPU-free compute.
+
+Usage:
+    modal deploy modal-app.py              # Deploy to Modal
+    modal serve modal-app.py               # Local dev with hot reload
+    modal run modal-app.py                 # One-shot test run
+
+Environment variables (set in Modal dashboard or .env):
+    AUTH_TOKEN           - Required Bearer token for all endpoints
+    ACUITY_BASE_URL      - Acuity scheduling URL
+    ACUITY_BYPASS_COUPON - 100% gift certificate code
+    PLAYWRIGHT_HEADLESS  - Browser headless mode (default: true)
+    PLAYWRIGHT_TIMEOUT   - Page timeout in ms (default: 30000)
+"""
+
+import modal
+
+app = modal.App("scheduling-middleware")
+
+# Base image: Playwright's official image with Chromium pre-installed
+image = (
+    modal.Image.from_registry(
+        "mcr.microsoft.com/playwright:v1.58.2-noble",
+        add_python="3.12",
+    )
+    .run_commands(
+        # Remove Node 24 from Playwright image, install Node 22 LTS
+        "apt-get remove -y nodejs || true",
+        "rm -f /usr/local/bin/node /usr/local/bin/npm /usr/local/bin/npx",
+        "curl -fsSL https://deb.nodesource.com/setup_22.x | bash -",
+        "apt-get install -y nodejs",
+        "node --version",
+        "corepack enable && corepack prepare pnpm@9.15.9 --activate",
+        "apt-get clean && rm -rf /var/lib/apt/lists/*",
+    )
+    .add_local_file("package.json", "/app/package.json", copy=True)
+    .add_local_dir("src", "/app/src", copy=True)
+    .add_local_file("tsconfig.json", "/app/tsconfig.json", copy=True)
+    .run_commands(
+        # Install all deps then compile TS → JS with esbuild (bundler handles fp-ts resolution)
+        "cd /app && pnpm install --no-frozen-lockfile",
+        "cd /app && pnpm add esbuild",
+        # Bundle middleware server to a single JS file with all deps inlined
+        "cd /app && npx esbuild src/middleware/server.ts"
+        " --bundle --platform=node --format=esm --outfile=dist/server.mjs"
+        " --external:playwright-core --external:playwright"
+        " --external:@playwright/test",
+        "ls -la /app/dist/server.mjs",
+    )
+)
+
+
+@app.function(
+    image=image,
+    # No GPU needed - browser automation only
+    cpu=2.0,
+    memory=2048,
+    # Keep warm for low latency (1 container always ready)
+    min_containers=1,
+    # 5 minute timeout (wizard can take up to 60s per booking)
+    timeout=300,
+    secrets=[modal.Secret.from_name("scheduling-middleware-secrets")],
+)
+@modal.concurrent(max_inputs=1)
+@modal.web_server(port=3001, startup_timeout=30)
+def server():
+    import subprocess
+
+    subprocess.Popen(
+        ["node", "dist/server.mjs"],
+        cwd="/app",
+        env={
+            **__import__("os").environ,
+            "NODE_ENV": "production",
+            "PORT": "3001",
+            "PLAYWRIGHT_HEADLESS": "true",
+        },
+    )

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tummycrypt/acuity-middleware",
+  "version": "0.1.0",
+  "description": "Playwright-based Acuity booking middleware server",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jesssullivan/acuity-middleware.git"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/middleware/server.js",
+    "dev": "tsx src/middleware/server.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "playwright-core": "^1.58.1",
+    "effect": "^3.19.14",
+    "fp-ts": "^2.16.9"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.0",
+    "tsx": "^4.0.0",
+    "vitest": "^4.0.0",
+    "@types/node": "^22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/adapters/acuity-scraper.ts

@@ -0,0 +1,543 @@
+/**
+ * Acuity Scraper Adapter
+ * Extracts scheduling data from public Acuity pages without API access
+ *
+ * Uses Playwright for reliable browser automation and handles:
+ * - Service (appointment type) extraction
+ * - Availability dates
+ * - Time slots
+ * - Provider information
+ */
+
+import type { Browser, Page } from 'playwright-core';
+
+const getChromium = async (): Promise<typeof import('playwright-core').chromium> => {
+  try {
+    const pw = await import('playwright-core');
+    return pw.chromium;
+  } catch {
+    throw new Error(
+      'playwright-core is required for the scraper adapter. Install with: pnpm add playwright-core'
+    );
+  }
+};
+import * as E from 'fp-ts/Either';
+import * as TE from 'fp-ts/TaskEither';
+import { pipe } from 'fp-ts/function';
+import type { Service, Provider, TimeSlot, AcuityError, InfrastructureError } from '../core/types.js';
+import { Errors } from '../core/types.js';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface ScraperConfig {
+  /** Base URL for the Acuity scheduling page */
+  baseUrl: string;
+  /** Browser launch options */
+  headless?: boolean;
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** User agent string */
+  userAgent?: string;
+  /** Path to Chromium executable (for Lambda/serverless) */
+  executablePath?: string;
+  /** Additional browser launch args */
+  launchArgs?: string[];
+}
+
+export interface ScrapedService {
+  id: string;
+  name: string;
+  description: string;
+  duration: number;
+  price: number;
+  category?: string;
+  href: string;
+}
+
+export interface ScrapedAvailability {
+  dates: string[];
+  serviceId: string;
+  providerId?: string;
+}
+
+export interface ScrapedTimeSlot {
+  time: string;
+  datetime: string;
+  available: boolean;
+}
+
+// =============================================================================
+// SCRAPER CLASS
+// =============================================================================
+
+export class AcuityScraper {
+  private config: ScraperConfig & { headless: boolean; timeout: number; userAgent: string };
+  private browser: Browser | null = null;
+
+  constructor(config: ScraperConfig) {
+    this.config = {
+      headless: true,
+      timeout: 30000,
+      userAgent:
+        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+      ...config,
+    };
+  }
+
+  /**
+   * Initialize browser instance
+   */
+  async init(): Promise<void> {
+    if (!this.browser) {
+      const chromium = await getChromium();
+      this.browser = await chromium.launch({
+        headless: this.config.headless,
+        executablePath: this.config.executablePath,
+        args: this.config.launchArgs,
+      });
+    }
+  }
+
+  /**
+   * Close browser instance
+   */
+  async close(): Promise<void> {
+    if (this.browser) {
+      await this.browser.close();
+      this.browser = null;
+    }
+  }
+
+  /**
+   * Create a new page with standard configuration
+   */
+  private async createPage(): Promise<Page> {
+    if (!this.browser) {
+      await this.init();
+    }
+    const page = await this.browser!.newPage({
+      userAgent: this.config.userAgent,
+    });
+    page.setDefaultTimeout(this.config.timeout);
+    return page;
+  }
+
+  /**
+   * Extract all services (appointment types) from the scheduling page
+   */
+  async scrapeServices(): Promise<E.Either<AcuityError | InfrastructureError, ScrapedService[]>> {
+    let page: Page | null = null;
+
+    try {
+      page = await this.createPage();
+      await page.goto(this.config.baseUrl, { waitUntil: 'networkidle' });
+
+      // Wait for appointment types to load
+      await page.waitForSelector('.select-item, .appointment-type-item, [data-testid="appointment-type"]', {
+        timeout: 10000,
+      }).catch(() => {
+        // Some Acuity pages use different selectors
+      });
+
+      // Try multiple selector patterns for robustness
+      const services = await page.evaluate(() => {
+        const results: ScrapedService[] = [];
+
+        // Pattern 1: Standard select-item layout
+        const selectItems = document.querySelectorAll('.select-item');
+        selectItems.forEach((item) => {
+          const link = item.querySelector('a');
+          const nameEl = item.querySelector('.appointment-type-name, .type-name, h3');
+          const descEl = item.querySelector('.type-description, .description, p');
+          const durationEl = item.querySelector('.duration, .time-duration');
+          const priceEl = item.querySelector('.price, .cost');
+
+          if (nameEl && link) {
+            // Extract appointment type ID from href
+            const href = link.getAttribute('href') || '';
+            const idMatch = href.match(/appointmentType=(\d+)/);
+            const id = idMatch ? idMatch[1] : `generated-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+            // Parse duration (e.g., "60 minutes" -> 60)
+            const durationText = durationEl?.textContent?.trim() || '';
+            const durationMatch = durationText.match(/(\d+)/);
+            const duration = durationMatch ? parseInt(durationMatch[1], 10) : 60;
+
+            // Parse price (e.g., "$150.00" -> 15000 cents)
+            const priceText = priceEl?.textContent?.trim() || '';
+            const priceMatch = priceText.match(/\$?([\d,.]+)/);
+            const price = priceMatch ? Math.round(parseFloat(priceMatch[1].replace(',', '')) * 100) : 0;
+
+            results.push({
+              id,
+              name: nameEl.textContent?.trim() || 'Unknown Service',
+              description: descEl?.textContent?.trim() || '',
+              duration,
+              price,
+              category: undefined,
+              href,
+            });
+          }
+        });
+
+        // Pattern 2: Category-based layout
+        if (results.length === 0) {
+          const categories = document.querySelectorAll('.category-group, .appointment-category');
+          categories.forEach((category) => {
+            const categoryName = category.querySelector('.category-name, h2')?.textContent?.trim();
+            const items = category.querySelectorAll('.appointment-type, .type-item');
+
+            items.forEach((item) => {
+              const link = item.querySelector('a');
+              const nameEl = item.querySelector('.name, .title');
+              const descEl = item.querySelector('.description');
+              const durationEl = item.querySelector('.duration');
+              const priceEl = item.querySelector('.price');
+
+              if (nameEl) {
+                const href = link?.getAttribute('href') || '';
+                const idMatch = href.match(/appointmentType=(\d+)/);
+                const id = idMatch ? idMatch[1] : `generated-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+
+                const durationText = durationEl?.textContent?.trim() || '';
+                const durationMatch = durationText.match(/(\d+)/);
+                const duration = durationMatch ? parseInt(durationMatch[1], 10) : 60;
+
+                const priceText = priceEl?.textContent?.trim() || '';
+                const priceMatch = priceText.match(/\$?([\d,.]+)/);
+                const price = priceMatch ? Math.round(parseFloat(priceMatch[1].replace(',', '')) * 100) : 0;
+
+                results.push({
+                  id,
+                  name: nameEl.textContent?.trim() || 'Unknown Service',
+                  description: descEl?.textContent?.trim() || '',
+                  duration,
+                  price,
+                  category: categoryName,
+                  href,
+                });
+              }
+            });
+          });
+        }
+
+        return results;
+      });
+
+      await page.close();
+      return E.right(services);
+    } catch (error) {
+      if (page) await page.close().catch(() => {});
+
+      if (error instanceof Error) {
+        if (error.message.includes('net::') || error.message.includes('timeout')) {
+          return E.left(
+            Errors.infrastructure('NETWORK', `Failed to load Acuity page: ${error.message}`, error)
+          );
+        }
+        return E.left(
+          Errors.acuity('SCRAPE_FAILED', `Failed to scrape services: ${error.message}`)
+        );
+      }
+
+      return E.left(
+        Errors.acuity('SCRAPE_FAILED', 'Unknown error during scraping')
+      );
+    }
+  }
+
+  /**
+   * Extract available dates for a specific service
+   */
+  async scrapeAvailableDates(
+    serviceId: string,
+    month?: string
+  ): Promise<E.Either<AcuityError | InfrastructureError, string[]>> {
+    let page: Page | null = null;
+
+    try {
+      page = await this.createPage();
+
+      // Navigate to service-specific page
+      const url = new URL(this.config.baseUrl);
+      url.searchParams.set('appointmentType', serviceId);
+      if (month) {
+        // Format: YYYY-MM
+        url.searchParams.set('month', month);
+      }
+
+      await page.goto(url.toString(), { waitUntil: 'networkidle' });
+
+      // Wait for calendar to load
+      await page.waitForSelector('.scheduleday, .calendar-day, [data-date]', {
+        timeout: 10000,
+      }).catch(() => {});
+
+      const dates = await page.evaluate(() => {
+        const results: string[] = [];
+
+        // Pattern 1: scheduleday with activeday class
+        const activeDays = document.querySelectorAll('.scheduleday.activeday, .calendar-day.available');
+        activeDays.forEach((day) => {
+          const date = day.getAttribute('data-date');
+          if (date) {
+            results.push(date);
+          }
+        });
+
+        // Pattern 2: data-available attribute
+        if (results.length === 0) {
+          const availableDays = document.querySelectorAll('[data-available="true"], [data-has-slots="true"]');
+          availableDays.forEach((day) => {
+            const date = day.getAttribute('data-date');
+            if (date) {
+              results.push(date);
+            }
+          });
+        }
+
+        return results;
+      });
+
+      await page.close();
+      return E.right(dates);
+    } catch (error) {
+      if (page) await page.close().catch(() => {});
+
+      if (error instanceof Error) {
+        return E.left(
+          Errors.acuity('SCRAPE_FAILED', `Failed to scrape available dates: ${error.message}`)
+        );
+      }
+
+      return E.left(
+        Errors.acuity('SCRAPE_FAILED', 'Unknown error during date scraping')
+      );
+    }
+  }
+
+  /**
+   * Extract available time slots for a specific date
+   */
+  async scrapeTimeSlots(
+    serviceId: string,
+    date: string
+  ): Promise<E.Either<AcuityError | InfrastructureError, ScrapedTimeSlot[]>> {
+    let page: Page | null = null;
+
+    try {
+      page = await this.createPage();
+
+      // Navigate to service page
+      const url = new URL(this.config.baseUrl);
+      url.searchParams.set('appointmentType', serviceId);
+
+      await page.goto(url.toString(), { waitUntil: 'networkidle' });
+
+      // Wait for calendar and click the date
+      await page.waitForSelector('.scheduleday, .calendar-day', { timeout: 10000 }).catch(() => {});
+
+      // Click the specific date
+      const dateSelector = `[data-date="${date}"], .scheduleday[data-date="${date}"]`;
+      await page.click(dateSelector).catch(() => {
+        // Date might not be clickable or use different mechanism
+      });
+
+      // Wait for time slots to load
+      await page.waitForSelector('.time-selection, .time-slot, [data-time]', {
+        timeout: 10000,
+      }).catch(() => {});
+
+      const slots = await page.evaluate(() => {
+        const results: ScrapedTimeSlot[] = [];
+
+        // Pattern 1: time-selection buttons
+        const timeButtons = document.querySelectorAll('.time-selection button, .time-slot');
+        timeButtons.forEach((btn) => {
+          const timeText = btn.textContent?.trim() || '';
+          const datetime = btn.getAttribute('data-time') || btn.getAttribute('data-datetime') || '';
+          const isDisabled = btn.hasAttribute('disabled') || btn.classList.contains('disabled');
+
+          if (timeText || datetime) {
+            results.push({
+              time: timeText,
+              datetime,
+              available: !isDisabled,
+            });
+          }
+        });
+
+        // Pattern 2: list items with time data
+        if (results.length === 0) {
+          const timeItems = document.querySelectorAll('[data-time], .available-time');
+          timeItems.forEach((item) => {
+            const timeText = item.textContent?.trim() || '';
+            const datetime = item.getAttribute('data-time') || '';
+
+            results.push({
+              time: timeText,
+              datetime,
+              available: true,
+            });
+          });
+        }
+
+        return results;
+      });
+
+      await page.close();
+      return E.right(slots);
+    } catch (error) {
+      if (page) await page.close().catch(() => {});
+
+      if (error instanceof Error) {
+        return E.left(
+          Errors.acuity('SCRAPE_FAILED', `Failed to scrape time slots: ${error.message}`)
+        );
+      }
+
+      return E.left(
+        Errors.acuity('SCRAPE_FAILED', 'Unknown error during time slot scraping')
+      );
+    }
+  }
+}
+
+// =============================================================================
+// TASK EITHER WRAPPERS
+// =============================================================================
+
+/**
+ * Create a scraper instance with TaskEither wrapper
+ */
+export const createScraperAdapter = (config: ScraperConfig) => {
+  const scraper = new AcuityScraper(config);
+
+  return {
+    /**
+     * Get all services
+     */
+    getServices: (): TE.TaskEither<AcuityError | InfrastructureError, Service[]> =>
+      pipe(
+        TE.tryCatch(
+          () => scraper.scrapeServices(),
+          (error) =>
+            Errors.acuity('SCRAPE_FAILED', error instanceof Error ? error.message : 'Unknown error')
+        ),
+        TE.flatMap((result) => TE.fromEither(result)),
+        TE.map((scraped) =>
+          scraped.map(
+            (s): Service => ({
+              id: s.id,
+              name: s.name,
+              description: s.description,
+              duration: s.duration,
+              price: s.price,
+              currency: 'USD',
+              category: s.category,
+              active: true,
+            })
+          )
+        )
+      ),
+
+    /**
+     * Get available dates for a service
+     */
+    getAvailableDates: (
+      serviceId: string,
+      month?: string
+    ): TE.TaskEither<AcuityError | InfrastructureError, string[]> =>
+      pipe(
+        TE.tryCatch(
+          () => scraper.scrapeAvailableDates(serviceId, month),
+          (error) =>
+            Errors.acuity('SCRAPE_FAILED', error instanceof Error ? error.message : 'Unknown error')
+        ),
+        TE.flatMap((result) => TE.fromEither(result))
+      ),
+
+    /**
+     * Get available time slots for a date
+     */
+    getTimeSlots: (
+      serviceId: string,
+      date: string
+    ): TE.TaskEither<AcuityError | InfrastructureError, TimeSlot[]> =>
+      pipe(
+        TE.tryCatch(
+          () => scraper.scrapeTimeSlots(serviceId, date),
+          (error) =>
+            Errors.acuity('SCRAPE_FAILED', error instanceof Error ? error.message : 'Unknown error')
+        ),
+        TE.flatMap((result) => TE.fromEither(result)),
+        TE.map((slots) =>
+          slots
+            .filter((s) => s.available)
+            .map(
+              (s): TimeSlot => ({
+                datetime: s.datetime || `${date}T${s.time}`,
+                available: s.available,
+              })
+            )
+        )
+      ),
+
+    /**
+     * Initialize browser
+     */
+    init: () => scraper.init(),
+
+    /**
+     * Close browser
+     */
+    close: () => scraper.close(),
+
+    /**
+     * Get the underlying scraper instance
+     */
+    getScraper: () => scraper,
+  };
+};
+
+// =============================================================================
+// CONVENIENCE FUNCTIONS
+// =============================================================================
+
+/**
+ * One-shot scrape of all services (opens and closes browser)
+ */
+export const scrapeServicesOnce = async (
+  baseUrl: string
+): Promise<E.Either<AcuityError | InfrastructureError, Service[]>> => {
+  const adapter = createScraperAdapter({ baseUrl });
+
+  try {
+    await adapter.init();
+    const result = await adapter.getServices()();
+    return result;
+  } finally {
+    await adapter.close();
+  }
+};
+
+/**
+ * One-shot scrape of availability (opens and closes browser)
+ */
+export const scrapeAvailabilityOnce = async (
+  baseUrl: string,
+  serviceId: string,
+  date: string
+): Promise<E.Either<AcuityError | InfrastructureError, TimeSlot[]>> => {
+  const adapter = createScraperAdapter({ baseUrl });
+
+  try {
+    await adapter.init();
+    const result = await adapter.getTimeSlots(serviceId, date)();
+    return result;
+  } finally {
+    await adapter.close();
+  }
+};