@aranova/tracking-next 1.0.0 → 1.2.0

package/README.md

@@ -407,7 +407,54 @@ its Origin allowlist is a browser-enforced header a script forges trivially. A j
 a database row you can delete; a junk **booking** puts an event on a real person's calendar
 and emails their contacts.
 
-`bookings.create()` returns a one-time `manage_token`. Put it in your confirmation email and
+Doing your own work around a booking (validation, emails, a CRM)? Call the write client from
+your own route instead of mounting the handler:
+
+```ts
+// app/api/book/route.ts
+import { createCalendarWriteClient } from "@aranova/tracking-next/calendar-server";
+import { isCalendarError } from "@aranova/tracking-next/calendar";
+
+const calendar = createCalendarWriteClient<AranovaCalendarKey>({
+  apiKey: process.env.ARANOVA_TRACKING_SECRET_KEY!,
+  endpoint: process.env.ARANOVA_TRACKING_ENDPOINT!,
+});
+
+const booking = await calendar.create({
+  calendar_key: "bookings",
+  start_at: "2026-10-14T13:00:00-04:00", // timed: start_at + duration_minutes (or end_at)
+  duration_minutes: 60,
+  // date: "2026-10-14",               // all-day instead: a local date, no start/end/buffers
+  time_zone: "America/Toronto",
+  customer: { email, name, phone },
+  description: "<b>Arrive 1–2 PM</b>", // reaches Google exactly as sent
+  idempotency_key: submissionId,
+  metadata: body.attribution, // getBookingAttribution(), sent from the browser
+});
+```
+
+- **Forward the visit.** `getBookingAttribution()` (from `./calendar`, browser only) returns the
+  visit's `session_id`, `visitor_id`, `gclid`/`fbclid` and `utm_*`. It is what ties a booking to the
+  visitor's journey and form submission in the dashboard, and what missed-booking detection matches
+  on. It reads browser storage, so a custom route can't compute it: the browser sends it with the
+  form and the route passes it into `create({ metadata })`. `useBookingForm` merges it in for you
+  (your `metadata` keys win).
+
+- **Overlaps are per calendar.** `ARANOVA_CALENDARS[].allowOverlaps` (from the CLI) says whether a
+  calendar accepts double bookings. When it is `false`, `create()` can throw `slot_unavailable`:
+  `isCalendarError(err, "slot_unavailable")`. Other codes: `calendar_not_connected`,
+  `calendar_disconnected`, `booking_not_found`, `booking_not_cancellable`,
+  `booking_not_reschedulable`, `manage_token_invalid`, `rate_limited`, `google_error`.
+- **No server-side booking window.** Notice and how far ahead customers may book are your policy.
+- **Your email can be the calendar invite.** The customer is always an attendee of the Google
+  event. Pass `send_invites: false` so Google sends nothing, then attach an ICS (`METHOD:REQUEST`)
+  with `UID` = `booking.ical_uid` and `ORGANIZER` = `booking.organizer_email`, so the customer's
+  copy is the same event as the calendar owner's. For `booking.all_day`, use
+  `DTSTART;VALUE=DATE`. `ical_uid` is null if Google hasn't confirmed the write; send a plain
+  confirmation then.
+- **All-day bookings** are moved in Google Calendar, not through `reschedule()`.
+
+`create()` returns a one-time `manage_token`. Put it in your confirmation email and
 send it as `X-Aranova-Manage-Token` to reschedule or cancel — it authorises exactly that one
 booking, which is why a public key alone still manages nothing.