@sonordev/site-kit 7.0.1 → 7.0.2

package/src/signal/README.md

@@ -0,0 +1,115 @@
+# Signal — `@sonordev/site-kit/signal`
+
+Real-time A/B experiments, behavior tracking, and dynamic configuration from Signal AI. Requires `full_signal` plan.
+
+## Usage
+
+Auto-included by `SiteKitLayout` when `signal` prop is enabled:
+
+```tsx
+<SiteKitLayout signal>{children}</SiteKitLayout>
+```
+
+For standalone use:
+
+```tsx
+'use client'
+import { SignalBridge } from '@sonordev/site-kit/signal'
+
+export default function Providers({ children }) {
+  return <SignalBridge>{children}</SignalBridge>
+}
+```
+
+## A/B Experiments
+
+### Declarative
+
+```tsx
+import { SignalExperiment } from '@sonordev/site-kit/signal'
+
+<SignalExperiment
+  experimentId="hero-cta"
+  variants={{
+    control: <Button>Get Started</Button>,
+    variant_a: <Button>Start Free Trial</Button>,
+  }}
+  trackImpression
+  fallback={<Button>Default</Button>}
+/>
+```
+
+### Hook-Based
+
+```tsx
+import { useSignalExperiment } from '@sonordev/site-kit/signal'
+
+function HeroCTA() {
+  const { variant, isControl } = useSignalExperiment('hero-cta')
+  return isControl ? <Button>Get Started</Button> : <Button>Start Free Trial</Button>
+}
+```
+
+### Conversion Tracking
+
+```tsx
+import { ExperimentConversion } from '@sonordev/site-kit/signal'
+
+<ExperimentConversion experimentId="hero-cta" conversionType="click">
+  <Button>Sign Up</Button>
+</ExperimentConversion>
+```
+
+## Hooks
+
+```ts
+useSignal()                    // Full context: config, loading, trackEvent, trackOutcome
+useSignalConfig()              // Just the config object
+useSignalEvent()               // Returns trackEvent function
+useSignalOutcome()             // Returns trackOutcome function
+useSignalExperiment(id)        // Returns { assignment, variant, isControl }
+```
+
+## SignalBridge Props
+
+```ts
+interface SignalBridgeProps {
+  enabled?: boolean              // Default: true
+  realtime?: boolean             // SSE real-time updates (default: true)
+  experiments?: boolean          // Participate in A/B tests (default: true)
+  behaviorTracking?: boolean     // Scroll, clicks, time-on-page (default: true)
+  children: React.ReactNode
+}
+```
+
+## What It Does
+
+1. Fetches config from `GET /api/public/signal/config`
+2. Opens SSE stream for real-time `config_update` and `experiment_update` events
+3. Assigns experiment variants per visitor (cached)
+4. Batches behavioral events (scroll depth, click count, time-on-page) and flushes on debounce
+5. Tracks outcomes/conversions via POST
+
+## Key Types
+
+```ts
+interface ExperimentConfig {
+  id: string; name: string;
+  status: 'draft' | 'running' | 'paused' | 'completed';
+  variants: ExperimentVariant[];
+  traffic_allocation: number;    // 0-1
+  goal: string;
+  winner?: string;
+}
+
+interface ExperimentVariant {
+  key: string; name: string; weight: number; description?: string;
+}
+
+interface SignalEvent {
+  event_type: string; event_name: string; event_data?: object;
+  page_url: string; page_title: string;
+  engagement: { time_on_page: number; scroll_depth: number; click_count: number };
+  experiments: Array<{ id: string; variant: string }>;
+}
+```

package/src/sitemap/README.md

@@ -0,0 +1,127 @@
+# Sitemap — `@sonordev/site-kit/sitemap`
+
+Auto-generates `sitemap.xml` from your Next.js app directory structure. Discovers pages, resolves dynamic routes, syncs to Sonor, and optionally writes build-time `llms.txt`.
+
+## Usage
+
+```ts
+// app/sitemap.ts
+import { createSitemap } from '@sonordev/site-kit/sitemap'
+
+export default createSitemap({
+  baseUrl: 'https://example.com',
+})
+```
+
+## Config
+
+```ts
+interface SitemapConfig {
+  baseUrl?: string                          // Resolved from Sonor API if not set
+  trailingSlash?: boolean                   // Default: next.config's trailingSlash (see below)
+  exclude?: string[]                        // Glob patterns: ['/admin/*', '/api/*']
+  defaultPriority?: number                  // Default: 0.5
+  defaultChangeFrequency?: 'weekly' | 'monthly' | 'yearly' | 'never'
+
+  // Dynamic route resolution
+  dynamicRoutes?: Record<string, string[]>  // Manual: { '[slug]': ['seo', 'analytics'] }
+  resolveGenerateStaticParams?: boolean     // Auto-import generateStaticParams (default: true)
+
+  // Priority overrides by path pattern
+  priorities?: Record<string, number>       // { '/services/*': 0.8, '/article/*': 0.6 }
+
+  // Additional paths not in app directory
+  additionalPaths?: () => Promise<{ path: string; priority?: number }[]>
+
+  // Sonor sync
+  apiUrl?: string                           // Sonor API URL
+  apiKey?: string                           // Sonor API key
+  disableSync?: boolean                     // Skip Sonor sync (default: false)
+  awaitMetaOptimization?: boolean           // Wait for Signal meta optimization
+
+  // GEO / llms.txt integration
+  optimizedLLMsTxt?: boolean                // Write AI-optimized llms.txt at build (default: true)
+  optimizedLLMsFullTxt?: boolean            // Also write llms-full.txt
+  includeLlmsTxtInSitemap?: boolean         // Add /llms.txt to sitemap (default: false; leave it off)
+  includeLlmsFullTxtInSitemap?: boolean     // Add /llms-full.txt (default: false; leave it off)
+
+  // Intelligent priority (requires Signal)
+  intelligentPriority?: boolean             // Use visibility scores + depth heuristics
+
+  // Local data for llms.txt fallback
+  getLocalData?: () => Promise<LLMsDataResponse | null>
+  llmsPublicSummaryOnly?: boolean
+}
+```
+
+## How Page Discovery Works
+
+1. Scans `app/` directory recursively for `page.tsx`/`page.jsx` files
+2. Detects dynamic segments (`[slug]`, `[...catchAll]`) and resolves them via:
+   - `dynamicRoutes` config (highest priority)
+   - Auto-import of `generateStaticParams()` from the page file (5s timeout)
+3. Fetches portfolio paths via `getPortfolioPaths()` if portfolio module is used
+4. Deduplicates and filters exclusion patterns
+5. Infers `pageType` for each page (homepage, service, article, faq, etc.)
+
+## Trailing Slashes
+
+Every `<loc>` is the URL the site actually serves. With `trailingSlash: true` in
+next.config, Next 308-redirects `/about` to `/about/`, so createSitemap emits
+`/about/`. The exceptions follow Next's own redirects: `/` itself, file-like
+paths (a `.` in the last segment, like `/llms.txt` or `/feed.xml`) and
+`/.well-known/*`.
+
+You don't need to set anything. The option defaults to the site's next.config
+value, which Next inlines into the bundle. Set `trailingSlash` only if the kit
+is loaded outside Next's bundler (`serverExternalPackages`).
+
+Only the emitted URL changes. Dedupe, `exclude`, `priorities` and the Sonor
+sync all use the unslashed path, which is how `seo_pages` stores it. The
+build-time llms.txt links follow the same setting. `npx sonor-setup doctor`
+warns (`sitemap.trailing-slash`) when a built sitemap's URLs don't match
+next.config.
+
+## Portfolio Paths
+
+```ts
+import { getPortfolioPaths } from '@sonordev/site-kit/sitemap'
+
+createSitemap({
+  additionalPaths: () => getPortfolioPaths({ basePath: '/work', priority: 0.7 }),
+})
+```
+
+## Sonor Sync
+
+During `next build` only (not ISR), the sitemap entries are POSTed to Sonor via `POST /api/public/seo/register-sitemap` with `full-replace` mode. This keeps `seo_pages` in sync with the actual site structure.
+
+## Build-Time llms.txt
+
+When `optimizedLLMsTxt` is true (default), the sitemap build also writes `public/llms.txt` (and optionally `public/llms-full.txt`) using `writeLLMsTxtToPublic()`. This is served as a static file by the llms route handler.
+
+If the Sonor API is unreachable at build time and local data can't produce real content, the write is **skipped** (with a warning) rather than replaced with an "Information not available." stub — any existing `public/llms.txt` / `public/llms-full.txt` from a previous successful build keeps serving.
+
+### It often won't fit in the route — write it from your postbuild
+
+Sonor generates llms.txt with an LLM call that can take a minute, and Next
+gives a prerendered route 60s before it retries and fails the build. So the
+in-route write gets only what's left of a 50s share of that budget: it refreshes
+the file when Sonor is quick, and otherwise leaves the existing file serving
+(the warning says so). It never fails the build.
+
+For a refresh on every build, move the write to your postbuild, where nothing
+imposes a ceiling and the sync it reads has already run:
+
+```jsonc
+// package.json
+"scripts": { "postbuild": "sonor-register-sitemap --write-llms" }
+```
+
+```ts
+// app/sitemap.ts — one writer owns the file
+export default createSitemap({ baseUrl, optimizedLLMsTxt: false })
+```
+
+Add `--write-llms-full` for `public/llms-full.txt`. The flag works even when the
+CLI skips its own sync because a sitemap route owns it.

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';