Book the first appointment slot that fits your week

import express from 'express';
import { setTimeout as sleep } from 'node:timers/promises';
import { Outcrawl } from '@outcrawl/sdk';

const oc = new Outcrawl(); // reads OUTCRAWL_API_KEY

const BOOKING_PAGE = 'https://booking.riversideclinic.example/dermatology';
const PROFILE = 'prof_8c1d2e'; // the id of a profile already signed in to the booking site
const PUBLIC_URL = 'https://yourapp.example';
const TOKEN = process.env.HOOK_TOKEN ?? ''; // long and random: it is the only credential on these paths
const NTFY = 'https://ntfy.sh/your-private-topic'; // push to your phone
const MODE = process.env.SLOT_MODE === 'hand-off' ? 'hand-off' : 'book';

// Your rules, checked in code before anything is booked.
const WITHIN_DAYS = 21;
const WEEKDAYS = [1, 2, 3, 4, 5]; // Monday to Friday
const acceptable = (slot: Slot) => {
  const at = new Date(`${slot.date}T${slot.time}:00`);
  const hour = at.getHours();
  return (
    at.getTime() > Date.now() &&
    at.getTime() < Date.now() + WITHIN_DAYS * 86_400_000 &&
    WEEKDAYS.includes(at.getDay()) &&
    (hour < 10 || hour >= 16) // before work or after it
  );
};

interface Slot { date: string; time: string; clinician: string; location: string }
interface Booking { booked: boolean; confirmation: string; date: string; time: string; clinician: string }

const slotSchema = {
  type: 'object',
  properties: {
    slots: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          date: { type: 'string', description: 'YYYY-MM-DD' },
          time: { type: 'string', description: '24-hour HH:MM' },
          clinician: { type: 'string' },
          location: { type: 'string' },
        },
        required: ['date', 'time', 'clinician', 'location'],
      },
    },
  },
  required: ['slots'],
};

const bookingSchema = {
  type: 'object',
  properties: {
    booked: { type: 'boolean' },
    confirmation: { type: 'string', description: "The confirmation number the site shows, or ''." },
    date: { type: 'string' },
    time: { type: 'string' },
    clinician: { type: 'string' },
  },
  required: ['booked', 'confirmation', 'date', 'time', 'clinician'],
};

const rules = ['Only use riversideclinic.example.', 'Never make a payment.'];

async function push(title: string, message: string, click?: string): Promise<void> {
  await fetch(NTFY, {
    method: 'POST',
    headers: { Title: title, Priority: 'urgent', ...(click ? { Click: click } : {}) },
    body: message,
  });
}

let hunting = false;
const handOffs = new Map<string, string>(); // run id to the monitor that found its slot

async function hunt(monitorId: string): Promise<void> {
  // 1. Read every open slot. Nothing is booked in this run.
  const found = await oc.agent({
    task: `Open ${BOOKING_PAGE} and list every appointment slot that can be booked now, across the next ${WITHIN_DAYS} days.`,
    schema: slotSchema,
    profile: PROFILE,
    caps: { budget: '40.00', duration: '3m' },
    rules,
  });
  const listed = found.data as { slots: Slot[] } | undefined; // shaped by slotSchema
  const slots = (listed?.slots ?? []).sort((a, b) => `${a.date}T${a.time}`.localeCompare(`${b.date}T${b.time}`));

  // 2. Your code decides, not the agent.
  const slot = slots.find(acceptable);
  if (slot === undefined) return console.log(`${slots.length} open slots, none within your rules`);
  const when = `${slot.date} at ${slot.time} with ${slot.clinician}`;

  // 3a. Book mode: a second run books exactly the slot your code approved.
  if (MODE === 'book') {
    const run = await oc.agent({
      task: `On ${BOOKING_PAGE}, book the slot on ${slot.date} at ${slot.time} with ${slot.clinician} at ${slot.location}.
Use the details already saved on the account. Book that slot and no other; if it is gone, book nothing.`,
      schema: bookingSchema,
      profile: PROFILE,
      caps: { budget: '65.00', duration: '5m' },
      rules,
    });
    const booking = run.data as Booking | undefined;
    if (booking?.booked) {
      await oc.monitors.delete(monitorId); // done hunting
      await push('Appointment booked', `${when}. Confirmation ${booking.confirmation}.`, run.replayUrl);
    } else {
      console.log(`could not book ${when}: ${run.stopReason ?? run.status}`, run.replayUrl);
    }
    return;
  }

  // 3b. Hand-off mode: the agent gets the slot in hand, and you confirm it yourself.
  const job = oc.agent({
    task: `On ${BOOKING_PAGE}, pick the slot on ${slot.date} at ${slot.time} with ${slot.clinician} at ${slot.location}
and go through the booking form with the details saved on the account. Do not press the final confirm button.`,
    profile: PROFILE,
    caps: { budget: '150.00', duration: '10m' }, // time the run waits for you is billed; these caps bound it
    rules,
  });
  const runId = await job.id();
  handOffs.set(runId, monitorId);
  for await (const record of job) {
    const step = record.value as { action?: { description?: string } } | null;
    if (record.kind === 'step' && step?.action?.description?.includes(slot.time)) {
      await job.control('take', 'me'); // holds at the agent's next step boundary
      break;
    }
  }
  let run = await job.status();
  while (run.status === 'queued' || run.status === 'running') {
    await sleep(2000);
    run = await job.status();
  }
  if (run.pause?.viewerUrl === undefined) return console.log(`run ended before the hand-off: ${run.stopReason}`);
  await push(
    `Slot held: ${when}`,
    `Tap to open the live view, press take control, and confirm. When you are done: ${PUBLIC_URL}/done/${TOKEN}/${runId}`,
    run.pause.viewerUrl,
  );
}

if (process.argv[2] === 'watch') {
  const monitor = await oc.monitors.create({
    url: BOOKING_PAGE,
    label: 'slots-dermatology',
    schedule: '*/10 * * * *', // every 10 minutes
    profile: PROFILE, // see the page the way you see it when signed in
    notify: { webhook: `${PUBLIC_URL}/hooks/slots/${TOKEN}` },
  });
  console.log('watching', monitor.id);
} else {
  const app = express();
  app.use(express.json({ limit: '2mb' }));

  app.post(`/hooks/slots/${TOKEN}`, (req, res) => {
    res.sendStatus(202); // answer at once: a monitor delivers each change once and never retries
    const { monitorId, diff } = req.body as { monitorId: string; diff?: string };
    const added = diff === undefined || /^\+(?!\+\+)/m.test(diff); // a diff that only removes lines is a slot going, not coming
    if (!added || hunting) return;
    hunting = true;
    hunt(monitorId)
      .catch((err) => console.error('hunt failed', err))
      .finally(() => (hunting = false));
  });

  // The link in the push: you have confirmed, so end the run, stop paying for it, and stop hunting.
  app.get(`/done/${TOKEN}/:runId`, async (req, res) => {
    await oc.agent.cancel(req.params.runId);
    const monitorId = handOffs.get(req.params.runId);
    if (monitorId !== undefined) await oc.monitors.delete(monitorId);
    res.send('Run ended.');
  });

  app.listen(3000, () => console.log(`listening on :3000 in ${MODE} mode`));
}

import asyncio
import os
import re
from datetime import datetime, timedelta

import httpx
from fastapi import BackgroundTasks, FastAPI, Request
from outcrawl import Outcrawl

oc = Outcrawl()  # one client for the life of the server; reads OUTCRAWL_API_KEY
app = FastAPI()

BOOKING_PAGE = "https://booking.riversideclinic.example/dermatology"
PROFILE = "prof_8c1d2e"  # the id of a profile already signed in to the booking site
PUBLIC_URL = "https://yourapp.example"
TOKEN = os.environ.get("HOOK_TOKEN", "")  # long and random: it is the only credential on these paths
NTFY = "https://ntfy.sh/your-private-topic"  # push to your phone
MODE = "hand-off" if os.environ.get("SLOT_MODE") == "hand-off" else "book"
RULES = ["Only use riversideclinic.example.", "Never make a payment."]

# Your rules, checked in code before anything is booked.
WITHIN_DAYS = 21
WEEKDAYS = {0, 1, 2, 3, 4}  # Monday to Friday


def acceptable(slot: dict) -> bool:
    at = datetime.fromisoformat(f"{slot['date']}T{slot['time']}")
    return (
        datetime.now() < at < datetime.now() + timedelta(days=WITHIN_DAYS)
        and at.weekday() in WEEKDAYS
        and (at.hour < 10 or at.hour >= 16)  # before work or after it
    )


SLOT_SCHEMA = {
    "type": "object",
    "properties": {
        "slots": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "date": {"type": "string", "description": "YYYY-MM-DD"},
                    "time": {"type": "string", "description": "24-hour HH:MM"},
                    "clinician": {"type": "string"},
                    "location": {"type": "string"},
                },
                "required": ["date", "time", "clinician", "location"],
            },
        }
    },
    "required": ["slots"],
}

BOOKING_SCHEMA = {
    "type": "object",
    "properties": {
        "booked": {"type": "boolean"},
        "confirmation": {"type": "string", "description": "The confirmation number the site shows, or ''."},
        "date": {"type": "string"},
        "time": {"type": "string"},
        "clinician": {"type": "string"},
    },
    "required": ["booked", "confirmation", "date", "time", "clinician"],
}


async def push(title: str, message: str, click: str | None = None) -> None:
    headers = {"Title": title, "Priority": "urgent", **({"Click": click} if click else {})}
    async with httpx.AsyncClient() as http:
        await http.post(NTFY, headers=headers, content=message)


hunting = False
hand_offs: dict[str, str] = {}  # run id to the monitor that found its slot


async def hunt(monitor_id: str) -> None:
    # 1. Read every open slot. Nothing is booked in this run.
    found = await oc.agent(
        task=f"Open {BOOKING_PAGE} and list every appointment slot that can be booked now, across the next {WITHIN_DAYS} days.",
        schema=SLOT_SCHEMA,
        profile=PROFILE,
        caps={"budget": "40.00", "duration": "3m"},
        rules=RULES,
    )
    slots = sorted((found.get("data") or {}).get("slots", []), key=lambda s: f"{s['date']}T{s['time']}")

    # 2. Your code decides, not the agent.
    slot = next((s for s in slots if acceptable(s)), None)
    if slot is None:
        print(f"{len(slots)} open slots, none within your rules")
        return
    when = f"{slot['date']} at {slot['time']} with {slot['clinician']}"

    # 3a. Book mode: a second run books exactly the slot your code approved.
    if MODE == "book":
        run = await oc.agent(
            task=f"""On {BOOKING_PAGE}, book the slot on {slot['date']} at {slot['time']} with {slot['clinician']} at {slot['location']}.
Use the details already saved on the account. Book that slot and no other; if it is gone, book nothing.""",
            schema=BOOKING_SCHEMA,
            profile=PROFILE,
            caps={"budget": "65.00", "duration": "5m"},
            rules=RULES,
        )
        booking = run.get("data") or {}
        if booking.get("booked"):
            await oc.monitors.delete(monitor_id)  # done hunting
            await push("Appointment booked", f"{when}. Confirmation {booking['confirmation']}.", run.get("replayUrl"))
        else:
            print(f"could not book {when}: {run.get('stopReason') or run['status']}", run.get("replayUrl"))
        return

    # 3b. Hand-off mode: the agent gets the slot in hand, and you confirm it yourself.
    job = oc.agent(
        task=f"""On {BOOKING_PAGE}, pick the slot on {slot['date']} at {slot['time']} with {slot['clinician']} at {slot['location']}
and go through the booking form with the details saved on the account. Do not press the final confirm button.""",
        profile=PROFILE,
        caps={"budget": "150.00", "duration": "10m"},  # time the run waits for you is billed; these caps bound it
        rules=RULES,
    )
    run_id = await job.id()
    hand_offs[run_id] = monitor_id
    async for record in job:
        if record["kind"] != "step":
            continue
        description = ((record["value"] or {}).get("action") or {}).get("description") or ""
        if slot["time"] in description:
            await job.control("take", "me")  # holds at the agent's next step boundary
            break
    run = await job.status()
    while run["status"] in ("queued", "running"):
        await asyncio.sleep(2)
        run = await job.status()
    viewer = (run.get("pause") or {}).get("viewerUrl")
    if viewer is None:
        print(f"run ended before the hand-off: {run.get('stopReason')}")
        return
    await push(
        f"Slot held: {when}",
        f"Tap to open the live view, press take control, and confirm. When you are done: {PUBLIC_URL}/done/{TOKEN}/{run_id}",
        viewer,
    )


async def hunt_once(monitor_id: str) -> None:
    global hunting
    try:
        await hunt(monitor_id)
    finally:
        hunting = False


@app.post(f"/hooks/slots/{TOKEN}", status_code=202)
async def slots_changed(request: Request, background: BackgroundTasks) -> dict:
    # Answer at once: a monitor delivers each change once and never retries.
    global hunting
    change = await request.json()
    diff = change.get("diff")
    added = diff is None or re.search(r"^\+(?!\+\+)", diff, re.M) is not None  # only removed lines: a slot going, not coming
    if added and not hunting:
        hunting = True
        background.add_task(hunt_once, change["monitorId"])
    return {"accepted": True}


# The link in the push: you have confirmed, so end the run, stop paying for it, and stop hunting.
@app.get(f"/done/{TOKEN}/{{run_id}}")
async def done(run_id: str) -> str:
    await oc.agent.cancel(run_id)
    if run_id in hand_offs:
        await oc.monitors.delete(hand_offs.pop(run_id))
    return "Run ended."


async def watch() -> None:
    monitor = await oc.monitors.create(
        url=BOOKING_PAGE,
        label="slots-dermatology",
        schedule="*/10 * * * *",  # every 10 minutes
        profile=PROFILE,  # see the page the way you see it when signed in
        notify={"webhook": f"{PUBLIC_URL}/hooks/slots/{TOKEN}"},
    )
    print("watching", monitor["id"])
    await oc.aclose()


if __name__ == "__main__":
    asyncio.run(watch())  # python slot_hunter.py, once; then serve with: SLOT_MODE=book uvicorn slot_hunter:app --port 3000