@aranova/tracking-next 0.20.1 → 0.21.0

package/README.md

@@ -341,6 +341,81 @@ npx @aranova/tracking-cli gen          # reads ARANOVA_TRACKING_SECRET_KEY from
 See the full guide: [sales-tracking.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/sales-tracking.md)
 and the CLI reference: [cli.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/cli.md).
 
+## Calendar Bookings
+
+Take bookings on a client site against a connected Google Calendar. Unlike sales,
+reads and writes are **separate entries**, and the split is structural rather than a
+convention — the read entry exposes no write verb at all.
+
+Read availability with your **public** key, straight from the browser:
+
+```ts
+import { createCalendarReadClient, computeSlots } from "@aranova/tracking-next/calendar";
+import type { AranovaCalendarKey } from "./aranova-services"; // generated, see below
+
+const calendar = createCalendarReadClient<AranovaCalendarKey>({
+  apiKey: process.env.NEXT_PUBLIC_ARANOVA_TRACKING_API_KEY!,
+  endpoint,
+});
+
+// Busy intervals only — never the contents of anyone's events.
+// `since`/`until` are ISO instants WITH an offset; a date-only value is a 400.
+const { busy, time_zone } = await calendar.busy("consultations", { since, until });
+```
+
+**Opening hours live in your app, not in the dashboard.** The API answers only "when is
+this person busy"; `computeSlots()` is a pure, dependency-free helper that turns that plus
+your own hours into offerable slots:
+
+```ts
+const { slots, nextAvailableAt } = computeSlots({
+  busy,
+  timeZone: time_zone,
+  openingHours: { weekly: { 1: [{ start: "09:00", end: "17:00" }] } },
+  durationMinutes: 30,
+  minNoticeMinutes: 240,
+  bufferAfterMinutes: 15,
+});
+```
+
+Writes need your **secret** key, so they run only on your own server. Drop in one route
+file — `./calendar-server` carries `import "server-only"`, so a client component importing
+it fails the build instead of shipping the key to a browser:
+
+```ts
+// app/api/aranova/calendar/[...route]/route.ts
+import { createCalendarRoutes } from "@aranova/tracking-next/calendar-server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export const { POST, PATCH, DELETE } = createCalendarRoutes({
+  secretKey: process.env.ARANOVA_TRACKING_SECRET_KEY!, // never NEXT_PUBLIC_
+  endpoint: process.env.ARANOVA_TRACKING_ENDPOINT!,
+});
+```
+
+Why the split, when sales is one isomorphic client: a public key ships in a JS bundle and
+its Origin allowlist is a browser-enforced header a script forges trivially. A junk sale is
+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
+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.
+
+Headless hooks on the root entry (no booking UI ships, for the same reason no consent UI does):
+
+```tsx
+"use client";
+import { useCalendarBusy, useSlots, useBookingForm } from "@aranova/tracking-next";
+// wrap in <CalendarClientProvider value={calendar}> — the hooks need a read client
+```
+
+Generate the typed `AranovaCalendarKey` union with the CLI (`npx @aranova/tracking-cli gen`).
+
+Full guide: [calendar.md](https://github.com/AranovaIO/aranova_internal/blob/master/docs/tracking-package/calendar.md)
+
 ## On-site conversion firing
 
 Run `tracking-cli gen` once to emit `ARANOVA_TRACKING_CONFIG`, then use that
@@ -495,8 +570,12 @@ Reads are best-effort: network/parse failures degrade to `null`/empty — a blog
   attribution hooks, event types; `createSalesClient()` (isomorphic — public key writes;
   secret key reads/CRUD, `summary`, `customers.*`, `business.config`) +
   `toMinor`/`fromMinor`/`formatMoney`/`formatDateInTz`; phone
-  (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`)
+  (`parsePhone`/`toE164`/`formatPhone`/`phoneField`, `usePhoneField`, `PhoneField`); calendar
+  read surface + headless hooks (`CalendarClientProvider`, `useCalendarBusy`, `useSlots`,
+  `useBookingForm`) — booking **writes** are not here, see `/calendar-server`
 - `@aranova/tracking-next/sales`: **React-free** server-safe SDK — `createSalesClient`, money/date helpers, and all sale/customer/config types. Use this in Server Components, route handlers, and Node servers; the root entry re-exports the same symbols for back-compat.
+- `@aranova/tracking-next/calendar`: **React-free, read-only** — `createCalendarReadClient`, `computeSlots`, timezone helpers, and the booking types. Public key, browser-safe. Deliberately exposes no write verb.
+- `@aranova/tracking-next/calendar-server`: **`server-only`** — `createCalendarWriteClient` and `createCalendarRoutes()` (drop-in booking route handler). Secret key; importing this from a client component fails the build.
 - `@aranova/tracking-next/middleware`: `createTrackingMiddleware()`
 - `@aranova/tracking-next/server`: `getTrackingParamsServer()`
 - `@aranova/tracking-next/phone`: isomorphic phone utils (no React)

package/dist/blog-server.js

@@ -679,6 +679,7 @@ function buildBlogSitemapEntries(posts, opts) {
 
 // ../tracking-core/src/resources/blog/toc.ts
 var import_github_slugger = __toESM(require("github-slugger"));
+var import_remark_gfm = __toESM(require("remark-gfm"));
 var import_remark_mdx = __toESM(require("remark-mdx"));
 var import_remark_parse = __toESM(require("remark-parse"));
 var import_unified = require("unified");
@@ -707,7 +708,7 @@ function headingText(node) {
 function extractBlogHeadings(mdx) {
   let tree;
   try {
-    tree = (0, import_unified.unified)().use(import_remark_parse.default).use(import_remark_mdx.default).parse(mdx);
+    tree = (0, import_unified.unified)().use(import_remark_parse.default).use(import_remark_gfm.default).use(import_remark_mdx.default).parse(mdx);
   } catch {
     return [];
   }
@@ -740,6 +741,7 @@ function estimateReadingTime(mdx) {
 }
 
 // ../tracking-core/src/resources/blog/validate-mdx.ts
+var import_remark_gfm2 = __toESM(require("remark-gfm"));
 var import_remark_mdx2 = __toESM(require("remark-mdx"));
 var import_remark_parse2 = __toESM(require("remark-parse"));
 var import_unified2 = require("unified");
@@ -932,7 +934,7 @@ function validateBlogMdx(mdx, options) {
   }
   let tree;
   try {
-    tree = (0, import_unified2.unified)().use(import_remark_parse2.default).use(import_remark_mdx2.default).parse(mdx);
+    tree = (0, import_unified2.unified)().use(import_remark_parse2.default).use(import_remark_gfm2.default).use(import_remark_mdx2.default).parse(mdx);
   } catch (error) {
     const line = error.line;
     return {
@@ -1008,6 +1010,7 @@ function validateBlogMdx(mdx, options) {
 // ../tracking-core/src/resources/blog/view/blog-post-view.tsx
 var import_rsc = require("next-mdx-remote/rsc");
 var import_rehype_slug = __toESM(require("rehype-slug"));
+var import_remark_gfm3 = __toESM(require("remark-gfm"));
 
 // ../tracking-core/src/resources/blog/view/components.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -2019,7 +2022,7 @@ async function BlogPostView({
     const compiled = await (0, import_rsc.compileMDX)({
       source: mdx,
       components: merged,
-      options: { mdxOptions: { rehypePlugins: [import_rehype_slug.default] } }
+      options: { mdxOptions: { remarkPlugins: [import_remark_gfm3.default], rehypePlugins: [import_rehype_slug.default] } }
     });
     content = compiled.content;
   } catch {