@sonordev/site-kit 7.0.1 → 7.1.0

package/src/slots/README.md

@@ -0,0 +1,168 @@
+# Managed copy — `@sonordev/site-kit/website/slots`
+
+Let the owner edit a site's words in Sonor without a deploy, while you keep
+the markup. Wrap the copy you'd like managed; the text in your code is the
+fallback, so the page renders exactly as written until someone edits it, and
+whenever Sonor can't be reached.
+
+```tsx
+import { ManagedSlot, ManagedRichText, ManagedLink, ManagedList } from '@sonordev/site-kit/website/slots'
+
+<h1 className="hero-title">
+  <ManagedSlot id="home-hero-headline" page="/">
+    New homes in Cincinnati and Northern Kentucky
+  </ManagedSlot>
+</h1>
+```
+
+Every managed region shows up in Sonor under **Website → Content** the first
+time a page renders it. There's no schema to define.
+
+## Four kinds of copy
+
+| Component | For | The owner edits |
+|---|---|---|
+| `<ManagedSlot>` | a headline, tagline, label | plain text |
+| `<ManagedRichText>` | an intro, an about section | paragraphs, bold, italic, links, lists |
+| `<ManagedLink>` | a call to action | its label and where it goes |
+| `<ManagedList>` | services, team, FAQs, a gallery | items: title, body, link, image |
+
+### `ManagedRichText`
+
+```tsx
+<div className="prose">
+  <ManagedRichText id="about-intro" page="/about">
+    {`We've built homes here since **1998**.\n\n- Custom builds\n- Remodels`}
+  </ManagedRichText>
+</div>
+```
+
+A string child is read as the same rich-text subset the owner edits, so the
+fallback and the managed copy render alike. It renders `<p>`, `<ul>`, `<ol>`,
+`<strong>`, `<em>`, `<a>` and `<br>`, and nothing else: managed copy is
+parsed into elements, never inserted as HTML.
+
+The subset: blank-line paragraphs, single newlines as line breaks,
+`**bold**`, `*italic*`, `[a link](https://…)`, and `-` or `1.` lists.
+
+### `ManagedLink`
+
+```tsx
+<ManagedLink id="home-hero-cta" href="/contact" label="Get a free quote">
+  {({ href, label }) => <Link href={href} className="btn">{label}</Link>}
+</ManagedLink>
+```
+
+Without a render function it draws a plain `<a>` with your `className`.
+Managed links may point to `https:`, `http:`, `mailto:`, `tel:`, a `#anchor`
+or a `/path`.
+
+### `ManagedList`
+
+```tsx
+<ManagedList id="home-services" items={SERVICES}>
+  {(items) => (
+    <ul className="grid">
+      {items.map((s) => (
+        <li key={s.title}>
+          <a href={s.href}>{s.title}</a>
+          <p>{s.body}</p>
+        </li>
+      ))}
+    </ul>
+  )}
+</ManagedList>
+```
+
+Each item may have a `title`, a plain-text `body`, an `href` and an
+`image: { src, alt, width?, height? }` (https only). Up to 50 items.
+
+## Props every component takes
+
+| Prop | |
+|---|---|
+| `id` | stable, lowercase, page-scoped by convention: `home-hero-headline` |
+| `page` | the route it renders on (`"/pricing"`), a literal; Sonor ties the copy to that page's analytics |
+| `site` | the host, on a multi-site project (defaults to `NEXT_PUBLIC_SITE_URL`) |
+| `revalidate` | seconds before a cached value is checked again (default 300); with [Live updates](../revalidate/README.md) installed, edits don't wait for it |
+
+## How it stays fast and safe
+
+- **Static.** Copy resolves in the server render with a cached fetch, so a
+  page using it stays prerendered. Nothing ships to the browser.
+- **Fallback first.** No key, no network, a bad response, or content of a
+  different kind than the code now renders: the fallback shows. It never
+  breaks a build or a page.
+- **Signed.** Sonor signs every value with your project key and site-kit
+  refuses anything that doesn't verify.
+- **Live in seconds.** Publishing in Sonor calls the site's revalidation
+  route, so the change shows without waiting for the next check. It's one
+  file, shared with the rest of site-kit (see [Live updates](../revalidate/README.md)):
+
+```ts
+// app/api/seo-revalidate/route.ts
+export { POST } from '@sonordev/site-kit/revalidate'
+```
+
+  Without it, a published edit shows once the cached copy ages out (the
+  `revalidate` window, five minutes by default).
+
+## Edit on page
+
+In Sonor, Website → Content → **Edit on page** opens the live site with its
+managed copy outlined. Click any of it to edit it in a side panel. Text, rich
+text and links show the change on the page as you type, before you publish.
+Links on the page take you to its other pages, still in edit mode.
+
+The site needs nothing beyond site-kit 7.1: no login, no secret, no extra
+route. It works like this:
+
+- Sonor frames the page with `?sonor_edit=1`. For any other visitor the
+  page is unchanged; the overlay is a separate chunk that only loads when
+  Sonor frames the page.
+- The overlay finds the copy by its visible text, so your markup and CSS are
+  exactly what you wrote (no wrapper elements, no attributes).
+- The page only reports what it found and what was clicked. The edit itself
+  is saved by Sonor with the signed-in person's own account.
+- It needs Sonor's dashboard to be allowed to frame the site, which
+  `securityHeaders` does by default. A site that sets its own
+  `frame-ancestors` should use `DEFAULT_FRAME_ANCESTORS`.
+
+## Lists with photos
+
+A list item can carry an image (`{ src, alt, width, height }`). In Sonor,
+**Upload photo** on a list item stores it with the project's files and fills
+in its size, so the page can reserve the space. A gallery is a list:
+
+```tsx
+<ManagedList id="gallery" items={[]}>
+  {(items) => (
+    <ul className="gallery">
+      {items.map((item, i) =>
+        item.image ? (
+          <li key={item.image.src}>
+            <img src={item.image.src} alt={item.image.alt} width={item.image.width} height={item.image.height} loading={i < 3 ? 'eager' : 'lazy'} />
+            {item.title && <p>{item.title}</p>}
+          </li>
+        ) : null,
+      )}
+    </ul>
+  )}
+</ManagedList>
+```
+
+## Drafts and history
+
+Edits in Sonor can be saved as drafts and published when they're ready.
+Every publish is kept, so any earlier version can be restored. Signal can
+propose copy too; proposals wait for approval in Sonor unless the project
+lets it publish on its own.
+
+## Using it without a component
+
+```ts
+import { getSlot } from '@sonordev/site-kit/website/slots'
+
+const slot = await getSlot('home-services', { type: 'list' })
+// slot?.value → { items: [...] }, or null (render your fallback)
+```

package/src/sync/README.md

@@ -0,0 +1,115 @@
+# Sync (Booking) — `@sonordev/site-kit/sync`
+
+Embeddable booking/scheduling widget — like Calendly, built into Sonor. Appointments, consultations, classes.
+
+## Usage
+
+```tsx
+'use client'
+import { BookingWidget } from '@sonordev/site-kit/sync'
+
+export default function BookPage() {
+  return (
+    <BookingWidget
+      onBookingComplete={(result) => {
+        console.log('Booked:', result.booking.confirmationCode)
+      }}
+    />
+  )
+}
+```
+
+## Props
+
+```ts
+interface BookingWidgetProps {
+  orgSlug?: string                    // Organization slug (for public mode)
+  apiKey?: string                     // API key (auto-resolved from env)
+  apiUrl?: string                     // Default: https://api.sonor.io
+  bookingTypeSlug?: string            // Show specific type only
+  timezone?: string                   // Guest timezone (auto-detected)
+  className?: string
+  daysToShow?: number                 // Days of availability to display
+  onBookingComplete?: (result: BookingResult) => void
+  onError?: (error: Error) => void
+  hideTypeSelector?: boolean          // Hide type selector for single-type embed
+
+  styles?: {                          // Custom theme
+    primaryColor?: string
+    borderRadius?: string
+    fontFamily?: string
+    backgroundColor?: string
+    textPrimary?: string
+    borderColor?: string
+  }
+}
+```
+
+## UI Flow
+
+1. **Type selector:** choose a booking type, unless a specific `bookingTypeSlug` is provided.
+2. **Meeting format:** when the booking type enables meeting options, choose virtual, office, or a visit to the guest's location. Travel meetings validate the address before showing availability.
+3. **Calendar and times:** choose an available time and reserve it while completing contact details.
+4. **Guest info:** name, email, phone, and notes. Travel meetings require a phone number.
+5. **Result:** a confirmed booking shows calendar links when Sonor sends the guest's invitation. When the host's Google Calendar sends it, the widget says who the invite is coming from instead (see [Calendar invitations](#calendar-invitations)). Meetings that require review show a pending request without calendar links.
+
+Changing a meeting format restores the selected format, address, and access notes. Guests can return to the service selector when it's available. Contact details survive changes to the format or reserved time.
+
+Expired meeting details and time reservations show a recovery action. Guests can recheck their meeting details or choose another time without re-entering their contact information. An active hold remains usable if its prepared meeting token expires, until the hold's own deadline.
+
+Navigation is disabled while a reservation or booking request is running. Stale responses cannot reopen a previous step, and holds created after the widget is removed are released.
+
+## API Functions
+
+```ts
+import {
+  fetchBookingTypes, fetchBookingTypeDetails,
+  fetchAvailability, fetchAvailableDates,
+  createSlotHold, releaseSlotHold, createBooking,
+  prepareMeeting,
+  detectTimezone, formatTime, formatDate, formatDuration,
+} from '@sonordev/site-kit/sync'
+```
+
+## Types
+
+```ts
+interface BookingType {
+  slug: string; name: string; description?: string;
+  duration_minutes: number; color?: string;
+  location_type: 'virtual' | 'phone' | 'in_person' | 'custom';
+  price_cents?: number; currency?: string; is_active: boolean;
+}
+
+interface BookingResult {
+  success: boolean
+  booking: {
+    id: string; confirmationCode: string; scheduledAt: string;
+    durationMinutes: number; hostName?: string; timezone: string;
+  }
+  cancelUrl: string; rescheduleUrl: string;
+  invitation?: 'google' | 'sonor'   // who sends the guest's calendar invite
+  calendarLinks: { google: string; outlook: string; ics: string }
+}
+```
+
+## Calendar invitations
+
+Each booking gives the guest one calendar invitation, and `invitation` says who sends it:
+
+- **`'google'`**: the host has Google Calendar connected, so Google invites the guest to the host's event. Sonor's emails don't attach a second invite, and the success screen says who the invite is coming from instead of showing calendar links. The Google and Outlook links build a separate event with no tie to that invitation, so a guest who clicked one would have two entries for the same meeting.
+- **`'sonor'`**: there's no Google event for the booking, usually because the host hasn't connected a calendar. Sonor's confirmation email carries the invite, and the success screen shows the calendar links.
+
+APIs older than the field don't send it; treat a missing `invitation` like `'sonor'`. `calendarLinks` is still sent for every booking so older widgets keep working. If you build your own success screen with `createBooking`, check `invitation` before you render `calendarLinks`.
+
+## Features
+
+- Automatic timezone detection
+- Slot hold with expiry (prevents double-booking)
+- Business hours support
+- Multiple hosts per booking type
+- Custom meeting URL / location
+
+## Booking regression checks
+
+Run `pnpm exec vitest run src/sync/booking-flow.test.ts` for expiry and server-error recovery checks. Start `pnpm exec vite --host 127.0.0.1 --port 5189`, then run `node test/meeting-flow/run.mjs` and `node test/meeting-flow/regression.mjs` for the real widget flows. The browser harness intercepts requests to a reserved test domain, so it creates no live bookings.

package/dist/SitemapSync-7WKY4HXI.js

@@ -1,8 +0,0 @@
-export { SitemapSync } from './chunk-WATH55UY.js';
-import './chunk-YVKRYQRG.js';
-import './chunk-43OCZ3JA.js';
-import './chunk-EKBEOXTH.js';
-import './chunk-EGOD74PP.js';
-import './chunk-3KUUH2YP.js';
-import './chunk-QGHSMJKW.js';
-import './chunk-PKBMQBKP.js';

package/dist/chunk-SS636UDN.js

@@ -1,35 +0,0 @@
-import { createHmac, timingSafeEqual } from 'crypto';
-
-// src/contracts/slots.ts
-var SLOTS_CONTRACT_VERSION = 1;
-var SLOT_CONTENT_TYPES = ["text"];
-var SLOT_CONTENT_MAX_LENGTH = 1e4;
-var SLOT_ID_PATTERN = /^[a-z0-9][a-z0-9-_.:]{0,127}$/;
-function isValidSlotId(id) {
-  return SLOT_ID_PATTERN.test(id);
-}
-function slotSigningPayload(content) {
-  return `sonor-slot.v${SLOTS_CONTRACT_VERSION}
-${content.slot_id}
-${content.type}
-${content.content}`;
-}
-function signSlotContent(content, apiKey) {
-  return createHmac("sha256", apiKey).update(slotSigningPayload(content), "utf8").digest("hex");
-}
-function verifySlotContent(content, apiKey) {
-  if (!content || typeof content !== "object") return false;
-  const c = content;
-  if (typeof c.slot_id !== "string" || !isValidSlotId(c.slot_id) || typeof c.content !== "string" || c.content.length === 0 || c.content.length > SLOT_CONTENT_MAX_LENGTH || typeof c.signature !== "string" || !SLOT_CONTENT_TYPES.includes(c.type)) {
-    return false;
-  }
-  const expected = signSlotContent(
-    { slot_id: c.slot_id, type: c.type, content: c.content },
-    apiKey
-  );
-  const a = Buffer.from(expected, "utf8");
-  const b = Buffer.from(c.signature, "utf8");
-  return a.length === b.length && timingSafeEqual(a, b);
-}
-
-export { SLOTS_CONTRACT_VERSION, SLOT_CONTENT_MAX_LENGTH, SLOT_CONTENT_TYPES, SLOT_ID_PATTERN, isValidSlotId, signSlotContent, slotSigningPayload, verifySlotContent };