@asksable/site-connector 0.3.2 → 0.4.0

package/README.md

@@ -9,6 +9,7 @@ Use this package in public website repos that should:
 - read business/site profile data from Sable
 - submit contact forms into Sable
 - render the shared booking widget against Sable public booking APIs
+- send web analytics into the separate `Sable Websites` PostHog project
 
 ## Setup
 
@@ -17,7 +18,7 @@ Wrap the site in `SableSiteProvider`:
 ```tsx
 import { SableSiteProvider } from '@asksable/site-connector'
 
-<SableSiteProvider
+;<SableSiteProvider
   config={{
     apiUrl: import.meta.env.VITE_SABLE_PUBLIC_API_URL,
     siteSlug: import.meta.env.VITE_SABLE_SITE_SLUG,
@@ -27,10 +28,48 @@ import { SableSiteProvider } from '@asksable/site-connector'
 </SableSiteProvider>
 ```
 
+## Website analytics
+
+`SableSiteProvider` initializes PostHog automatically when the public
+`/public/site-profile` response includes an enabled analytics config. This is
+the preferred path because Sable can rotate the `Sable Websites` project token
+centrally from Convex env vars without editing every customer website.
+
+If a standalone host needs to override the server-provided config, pass:
+
+```tsx
+<SableSiteProvider
+  config={{
+    apiUrl,
+    siteSlug,
+    analytics: {
+      captureEnabled: true,
+      posthogToken: import.meta.env.VITE_SABLE_WEBSITES_POSTHOG_TOKEN,
+      posthogHost: 'https://us.i.posthog.com',
+      environment: import.meta.env.MODE,
+    },
+  }}
+>
+  <App />
+</SableSiteProvider>
+```
+
+The connector captures `$pageview` events with `sable_site_slug` and related
+site properties, plus booking-widget conversion events:
+
+- `sable_booking_widget_viewed`
+- `sable_booking_service_selected`
+- `sable_booking_created`
+- `sable_booking_payment_started`
+- `sable_booking_rescheduled`
+
 Then consume the profile or render the shared booking widget:
 
 ```tsx
-import { BookingWidgetPanel, useSableSiteProfile } from '@asksable/site-connector'
+import {
+  BookingWidgetPanel,
+  useSableSiteProfile,
+} from '@asksable/site-connector'
 ```
 
 ## Exports
@@ -75,11 +114,11 @@ Supported locales: `'en'` (default), `'es'`. Adding a locale requires a package
 
 ### Three usage modes
 
-| Site type | Pattern |
-| --- | --- |
-| **Single-language site (English only)** | Omit `language` entirely or pass `'en'`. Widget defaults to English. |
-| **Single-language site (Spanish only)** | Pass `language: 'es'` once at provider mount. |
-| **Multi-language site with a toggle** | Pass a reactive value that updates when the toggle changes. The provider re-renders, the widget re-renders with the new locale. |
+| Site type                               | Pattern                                                                                                                         |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| **Single-language site (English only)** | Omit `language` entirely or pass `'en'`. Widget defaults to English.                                                            |
+| **Single-language site (Spanish only)** | Pass `language: 'es'` once at provider mount.                                                                                   |
+| **Multi-language site with a toggle**   | Pass a reactive value that updates when the toggle changes. The provider re-renders, the widget re-renders with the new locale. |
 
 ### Multi-language example
 

package/dist/analytics.d.ts

@@ -0,0 +1,18 @@
+import type { Properties } from 'posthog-js';
+import type { PublicSiteProfile, SableSiteAnalyticsConfig } from './types.js';
+type SiteAnalyticsContext = {
+    siteSlug: string;
+    siteId?: string;
+    siteName?: string;
+    businessName?: string;
+    environment?: string;
+};
+export declare function initializeSableSiteAnalytics({ config, siteProfile, context, }: {
+    config: SableSiteAnalyticsConfig | undefined;
+    siteProfile: PublicSiteProfile | null;
+    context: SiteAnalyticsContext;
+}): Promise<boolean>;
+export declare function captureSableSitePageview(context: SiteAnalyticsContext): void;
+export declare function captureSableSiteEvent(event: string, properties: Properties | undefined, context: SiteAnalyticsContext): void;
+export {};
+//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA0B,UAAU,EAAE,MAAM,YAAY,CAAA;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAS7E,KAAK,oBAAoB,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAwCD,wBAAsB,4BAA4B,CAAC,EACjD,MAAM,EACN,WAAW,EACX,OAAO,GACR,EAAE;IACD,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAA;IAC5C,WAAW,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACrC,OAAO,EAAE,oBAAoB,CAAA;CAC9B,oBAmDA;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,oBAAoB,QAGrE;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,UAAU,GAAG,SAAS,EAClC,OAAO,EAAE,oBAAoB,QAO9B"}

package/dist/analytics.js

@@ -0,0 +1,94 @@
+const INSTANCE_NAME = 'sableWebsites';
+const DEFAULT_POSTHOG_HOST = 'https://us.i.posthog.com';
+let activeClient = null;
+let activeKey = null;
+function getBrowserPostHogInstance() {
+    if (typeof window === 'undefined')
+        return null;
+    const globalPostHog = window.posthog;
+    return globalPostHog?.[INSTANCE_NAME] ?? activeClient;
+}
+function cleanHost(value) {
+    return value?.trim().replace(/\/+$/, '') || DEFAULT_POSTHOG_HOST;
+}
+function getContextProperties(context) {
+    return {
+        sable_site_slug: context.siteSlug,
+        sable_site_id: context.siteId,
+        sable_site_name: context.siteName,
+        sable_business_name: context.businessName,
+        sable_environment: context.environment ?? 'production',
+    };
+}
+function getPageProperties(context) {
+    if (typeof window === 'undefined')
+        return getContextProperties(context);
+    return {
+        ...getContextProperties(context),
+        $current_url: window.location.href,
+        $host: window.location.host,
+        $pathname: window.location.pathname,
+        $referrer: document.referrer || undefined,
+        sable_pathname: window.location.pathname || '/',
+        sable_search: window.location.search || undefined,
+        sable_title: document.title || undefined,
+    };
+}
+export async function initializeSableSiteAnalytics({ config, siteProfile, context, }) {
+    if (typeof window === 'undefined')
+        return false;
+    const token = config?.posthogToken?.trim();
+    const captureEnabled = config?.captureEnabled === true && Boolean(token);
+    const client = getBrowserPostHogInstance();
+    if (!captureEnabled || !token) {
+        client?.opt_out_capturing();
+        activeClient = client;
+        activeKey = null;
+        return false;
+    }
+    const host = cleanHost(config.posthogHost);
+    const environment = config.environment ?? context.environment ?? 'production';
+    const key = [
+        token,
+        host,
+        environment,
+        context.siteSlug,
+        siteProfile?.site._id ?? '',
+    ].join('|');
+    const posthogModule = await import('posthog-js');
+    const posthog = posthogModule.default;
+    const options = {
+        api_host: host,
+        defaults: '2026-01-30',
+        capture_pageview: false,
+        capture_pageleave: true,
+        capture_dead_clicks: true,
+        opt_out_useragent_filter: environment === 'production',
+        person_profiles: 'never',
+        request_batching: environment === 'production',
+        persistence: 'localStorage+cookie',
+    };
+    if (activeKey === key && activeClient) {
+        activeClient.register(getContextProperties({ ...context, environment }));
+        activeClient.opt_in_capturing();
+        return true;
+    }
+    posthog.init(token, options, INSTANCE_NAME);
+    activeClient = posthog[INSTANCE_NAME] ?? posthog;
+    activeKey = key;
+    activeClient.register(getContextProperties({ ...context, environment }));
+    activeClient.opt_in_capturing();
+    return true;
+}
+export function captureSableSitePageview(context) {
+    const client = getBrowserPostHogInstance();
+    client?.capture('$pageview', getPageProperties(context));
+}
+export function captureSableSiteEvent(event, properties, context) {
+    const client = getBrowserPostHogInstance();
+    client?.capture(event, {
+        ...getPageProperties(context),
+        ...properties,
+    });
+}
+//# sourceMappingURL=analytics.js.map

package/dist/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../src/analytics.ts"],"names":[],"mappings":"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"}

package/dist/booking-widget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"booking-widget.d.ts","sourceRoot":"","sources":["../src/booking-widget.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqH,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AASzJ,OAAO,qBAAqB,CAAA;AA6C5B;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB;;qBAEiB;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB;qCACiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB;;sBAEkB;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;yCACqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;oEACgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,KAAK,kBAAkB,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,SAAS,CAAA;IACxB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAA;IAC9B,iBAAiB,CAAC,EAAE,wBAAwB,CAAA;IAC5C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC1B,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,cAAc,GAAG,iBAAiB,CAAA;IAC9E,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAKD,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,WAAW,EACX,YAAY,EACZ,IAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,mBAAyB,EACzB,eAAe,EACf,iBAAiB,GAClB,EAAE,kBAAkB,2CAkvEpB"}
+{"version":3,"file":"booking-widget.d.ts","sourceRoot":"","sources":["../src/booking-widget.tsx"],"names":[],"mappings":"AAAA,OAAO,EASL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AAcd,OAAO,qBAAqB,CAAA;AAmE5B;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB;;qBAEiB;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB;qCACiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB;;sBAEkB;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;yCACqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;oEACgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,KAAK,kBAAkB,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,SAAS,CAAA;IACxB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAA;IAC9B,iBAAiB,CAAC,EAAE,wBAAwB,CAAA;IAC5C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC1B,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,cAAc,GAAG,iBAAiB,CAAA;IAC9E,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAKD,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,WAAW,EACX,YAAY,EACZ,IAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,mBAAyB,EACzB,eAAe,EACf,iBAAiB,GAClB,EAAE,kBAAkB,2CA+tFpB"}