# Scheduling Integration

## When to use

Use this skill whenever a task requires checking booking availability, creating or managing appointments (events), or looking up/creating contacts in the Scheduling app. Typical triggers: a lead wants to book a meeting, a booking needs to be confirmed, canceled, completed, or rescheduled, or you need to list a resource's upcoming events. Do not use this skill for anything unrelated to scheduling, such as CRM (customer relationship management) records outside of contacts tied to bookings, or email delivery.

## Tools

- `http-get` — read event types, availability, events, and contacts
- `http-post` — create bookings, events, contacts, and event types
- `http-request` — update events (PATCH) and trigger status transitions
- `write-file` — stage large result sets (for example, a full event list) instead of dumping them into the conversation
- `send-message` — escalate to a human when authentication fails or an Integration is missing

## Playbook

1. Discover available booking types before offering times: `http-get` `/api/v1/event_types` to list active event types for the current resource.
2. Find open slots for the requested window: `http-get` `/api/v1/availabilities?start_date=&end_date=&event_type_id=` to get computed open time slots.
3. If you need slots formatted for a single day (for example, to read out loud or paste into a message), `http-get` `/api/v1/availabilities/formatted?date=&event_type_id=`.
4. Before finalizing a specific date/time with a contact, confirm it is still open: `http-get` `/api/v1/availabilities/check_slot?date=&time=&event_type_id=&duration=`.
5. Look up the contact by email to avoid duplicates: `http-get` `/api/v1/contacts?email=`. If none exists, create one with `http-post` `/api/v1/contacts`.
6. Create the booking using the safe, validated path — never the raw event endpoint — with `http-post` `/api/v1/bookings`. This endpoint re-validates slot availability and auto-creates or matches the contact.
7. To create an event directly without a slot-availability check (only when explicitly instructed to bypass validation), use `http-post` `/api/v1/events`.
8. To update an existing event's time, notes, or other fields, use `http-request` (PATCH) against `/api/v1/events/:id`.
9. Advance an event's status as needed: `http-request` (POST) `/api/v1/events/:id/confirm`, `/api/v1/events/:id/cancel`, or `/api/v1/events/:id/complete`.
10. To review a single event's details, `http-get` `/api/v1/events/:id`. To list events with filters (status, event_type_id, contact_id, start_date, end_date), `http-get` `/api/v1/events`.
11. If a listing or lookup returns a large result set, write it to disk with `write-file` rather than including it inline, then summarize the key rows in your response.
12. Never request, echo, or hardcode API keys, tokens, or the `X-Organization` header — authentication is injected automatically by the org's Integration row for this app.

## Failure modes

- A 401 Unauthorized response means the Integration row is missing or its credentials are invalid. Stop immediately and use `send-message` to notify a human, naming "Scheduling" as the app and stating that its Integration needs to be configured or repaired.
- A 403 Forbidden response means the caller lacks write permission for a mutating call. Stop and use `send-message` to name "Scheduling" and specify that write access (`can_write?`) is needed for the calling identity.
- If no Integration row exists for the org at all, do not attempt any call — use `send-message` right away to request that a Scheduling Integration be added, naming the required scopes (read event types/availability/events/contacts, write bookings/events/contacts).
- If `check_slot` or `availabilities` shows a slot as unavailable, do not force a booking through `/api/v1/events` — report the conflict instead of bypassing validation.

## Done when

The requested booking, event update, status transition, or contact record has been created or modified via the appropriate endpoint and confirmed by a follow-up `http-get`, or a human has been notified via `send-message` because authentication or an Integration was missing.