@aranova/tracking-next 0.20.2 → 0.22.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

@@ -84,6 +84,13 @@ __export(blog_server_exports, {
 module.exports = __toCommonJS(blog_server_exports);
 var import_server_only = require("server-only");
 
+// ../tracking-core/src/capabilities.ts
+var CAPABILITY_DOM_ATTRIBUTE = "data-aranova-capability";
+var registered = /* @__PURE__ */ new Set();
+function registerCapability(capability) {
+  registered.add(capability);
+}
+
 // ../tracking-core/src/resources/blog/schema.ts
 var import_zod2 = require("zod");
 
@@ -422,6 +429,7 @@ function parseBlogPostContent(raw) {
 
 // ../tracking-core/src/resources/blog/client.ts
 function createBlogClient(config) {
+  registerCapability("blog_rendering");
   const base = config.cdnBaseUrl.replace(/\/+$/, "");
   const doFetch = (...args) => (config.fetchImpl ?? fetch)(...args);
   async function fetchJson(url, init) {
@@ -1984,6 +1992,7 @@ var BLOG_BASE_CSS = `/* Aranova blog post base stylesheet \u2014 authored source
 
 // ../tracking-core/src/resources/blog/view/blog-post-view.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
+var CAPABILITY_MARKER = { [CAPABILITY_DOM_ATTRIBUTE]: "blog_rendering" };
 async function BlogPostView({
   mdx,
   theme = BASE_BLOG_THEME,
@@ -2006,6 +2015,7 @@ async function BlogPostView({
         className: joinClassNames("aranova-blog-post", classNames?.article),
         "data-error": "mdx-validation-failed",
         style,
+        ...CAPABILITY_MARKER,
         children: [
           /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("style", { children: BLOG_BASE_CSS }),
           /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("p", { children: [
@@ -2032,6 +2042,7 @@ async function BlogPostView({
         className: joinClassNames("aranova-blog-post", classNames?.article),
         "data-error": "mdx-render-failed",
         style,
+        ...CAPABILITY_MARKER,
         children: [
           /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("style", { children: BLOG_BASE_CSS }),
           /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { children: "This post could not be displayed." })
@@ -2045,6 +2056,7 @@ async function BlogPostView({
       className: joinClassNames("aranova-blog-post", classNames?.article),
       "data-motion": motion,
       style,
+      ...CAPABILITY_MARKER,
       children: [
         /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("style", { children: BLOG_BASE_CSS }),
         header,