@c15t/scripts 2.1.0 → 2.2.0-canary-20260804162155

package/docs/integrations/databuddy.md

@@ -0,0 +1,205 @@
+---
+title: Databuddy
+description: Databuddy is a privacy-focused analytics platform that helps you
+  understand user behavior and track events. It supports cookieless tracking and
+  manages consent automatically through c15t's consent state synchronization.
+icon: databuddy
+group: integrations
+---
+The Databuddy script automatically respects consent preferences by toggling tracking on and off based on the user's consent state.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { databuddy } from '@c15t/scripts/databuddy';
+
+const scripts = [
+  databuddy({
+    clientId: 'your-client-id',
+    scriptUrl: 'https://cdn.databuddy.cc/databuddy.js',
+    apiUrl: 'https://basket.databuddy.cc',
+    configWhenGranted: {
+      clientId: 'your-client-id',
+      apiUrl: 'https://basket.databuddy.cc',
+      disabled: false,
+    },
+    configWhenDenied: {
+      clientId: 'your-client-id',
+      apiUrl: 'https://basket.databuddy.cc',
+      disabled: true,
+    },
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { databuddy } from '@c15t/scripts/databuddy';
+
+const scripts = [
+  databuddy({
+    clientId: 'your-client-id',
+    scriptUrl: 'https://cdn.databuddy.cc/databuddy.js',
+    apiUrl: 'https://basket.databuddy.cc',
+    configWhenGranted: {
+      clientId: 'your-client-id',
+      apiUrl: 'https://basket.databuddy.cc',
+      disabled: false,
+    },
+    configWhenDenied: {
+      clientId: 'your-client-id',
+      apiUrl: 'https://basket.databuddy.cc',
+      disabled: true,
+    },
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { databuddy } from '@c15t/scripts/databuddy';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    databuddy({
+      clientId: 'your-client-id',
+      scriptUrl: 'https://cdn.databuddy.cc/databuddy.js',
+      apiUrl: 'https://basket.databuddy.cc',
+      configWhenGranted: {
+        clientId: 'your-client-id',
+        apiUrl: 'https://basket.databuddy.cc',
+        disabled: false,
+      },
+      configWhenDenied: {
+        clientId: 'your-client-id',
+        apiUrl: 'https://basket.databuddy.cc',
+        disabled: true,
+      },
+    }),
+  ],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `measurement` (Analytics)
+* **Loads when:** [`alwaysLoad`](/docs/frameworks/react/script-loader#always-load) — runs on page start regardless of consent state
+* **On consent change:** c15t toggles `window.databuddy.options.disabled` so tracking turns on or off without removing the script
+
+## Configure the integration
+
+The Databuddy manifest expects explicit initial config objects for the granted
+and denied consent states:
+
+```ts
+databuddy({
+  clientId: 'your-client-id',
+  scriptUrl: 'https://cdn.databuddy.cc/databuddy.js',
+  apiUrl: 'https://basket.databuddy.cc', // Optional, defaults to basket.databuddy.cc, change if self-hosting
+  configWhenGranted: {
+    clientId: 'your-client-id',
+    apiUrl: 'https://basket.databuddy.cc',
+    // Tracking options
+    trackScreenViews: true,        // Automatically track page views
+    trackOutgoingLinks: true,      // Track clicks on external links
+    trackAttributes: false,        // Track data-track attributes on elements
+    trackErrors: false,            // Track JavaScript errors
+    trackPerformance: true,        // Track performance metrics
+    trackWebVitals: false,         // Track Core Web Vitals
+
+
+    // Network options
+    enableBatching: false,         // Batch events before sending
+    batchSize: 10,                 // Events per batch
+    batchTimeout: 2000,            // Batch timeout in ms
+    samplingRate: 1.0,             // Sample rate (0.0-1.0)
+    disabled: false,
+  },
+  configWhenDenied: {
+    clientId: 'your-client-id',
+    apiUrl: 'https://basket.databuddy.cc',
+    disabled: true,
+  }
+})
+```
+
+## Tracking events in your app
+
+Databuddy is `alwaysLoad: true`, so the script is in the DOM from page start regardless of consent. `window.databuddy` is therefore always defined and calls to `track`, `screenView`, or `setGlobalProperties` are safe to make at any time — when measurement consent is denied, c15t flips `window.databuddy.options.disabled = true` so the SDK becomes a no-op until consent is granted again.
+
+```ts
+window.databuddy?.track('signup');
+```
+
+You do not need to guard these calls with `useConsentManager().has('measurement')`, but doing so does no harm if you prefer the symmetry with other vendors.
+
+## Consent and privacy
+
+The Databuddy integration automatically handles consent management:
+
+1. **Before Script Load**: Sets `window.databuddyConfig.disabled` based on initial consent state
+2. **On Consent Grant**: Enables tracking by setting `window.databuddy.options.disabled = false`
+3. **On Consent Revoke**: Disables tracking by setting `window.databuddy.options.disabled = true`
+
+This ensures that no tracking occurs without user consent, keeping your analytics privacy-compliant.
+
+## Types
+
+### DatabuddyConsentOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`DatabuddyConsentOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/databuddy.ts\`|
+
+\*ExtractedTypeTable: Could not extract "DatabuddyConsentOptions" from "./packages/scripts/src/vendors/analytics/databuddy.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/integrations/fathom-analytics.md

@@ -0,0 +1,150 @@
+---
+title: Fathom Analytics
+description: Privacy-friendly cookieless analytics with a prebuilt helper that
+  maps Fathom's data attributes into a c15t-managed script.
+group: integrations
+icon: fathom-analytics
+---
+Fathom Analytics is a lightweight, cookieless analytics product configured entirely through `data-*` attributes on its loader. The `fathomAnalytics()` helper serializes your site ID and tracking options into those attributes and hands the result to c15t's script loader.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { fathomAnalytics } from '@c15t/scripts/fathom-analytics';
+
+const scripts = [fathomAnalytics({ site: 'SITE123' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: 'https://your-instance.c15t.dev',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/nextjs';
+import { fathomAnalytics } from '@c15t/scripts/fathom-analytics';
+
+const scripts = [fathomAnalytics({ site: 'SITE123' })];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { fathomAnalytics } from '@c15t/scripts/fathom-analytics';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [fathomAnalytics({ site: 'SITE123' })],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted
+* **On revocation:** unloaded — c15t removes the script element from the DOM. Fathom is cookieless, so no client-side state needs clearing.
+
+If you need to tune SPA tracking, canonical URL tracking, or Do Not Track handling:
+
+```ts
+fathomAnalytics({
+  site: 'SITE123',
+  spa: 'history',
+  canonical: true,
+  honorDnt: true,
+})
+```
+
+Each option is mapped to Fathom's published `data-*` attribute (`data-site`, `data-spa`, `data-auto`, `data-canonical`, `data-honor-dnt`) and the script uses `defer` so it matches Fathom's recommended embed pattern.
+
+## Tracking events in your app
+
+c15t gates the Fathom script from loading until `measurement` consent is granted. Your application code that calls Fathom's runtime API (`window.fathom.trackEvent`, `trackPageview`, `trackGoal`) is **not** automatically gated — `window.fathom` does not exist until the script is loaded, so unguarded calls before consent will throw errors.
+
+Guard event calls by checking consent state. From React:
+
+```tsx
+import { useConsentManager } from '@c15t/react';
+
+function useTrackSignup() {
+  const { has } = useConsentManager();
+
+  return () => {
+    if (has('measurement')) {
+      window.fathom?.trackEvent('signup');
+    }
+  };
+}
+
+function SignupButton() {
+  const trackSignup = useTrackSignup();
+
+  return <button onClick={trackSignup}>Sign up</button>;
+}
+```
+
+From plain JavaScript:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+
+const { consentStore } = getOrCreateConsentRuntime();
+
+if (consentStore.getState().has('measurement')) {
+  window.fathom?.trackEvent('signup');
+}
+```
+
+## Types
+
+### FathomAnalyticsOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`FathomAnalyticsOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/fathom-analytics.ts\`|
+
+\*ExtractedTypeTable: Could not extract "FathomAnalyticsOptions" from "./packages/scripts/src/vendors/analytics/fathom-analytics.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+
+### Script
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`Script\`|
+|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+
+\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

package/docs/integrations/google-maps.md

@@ -0,0 +1,263 @@
+---
+title: Google Maps
+description: Render Google Maps only after consent with one shared Maps
+  JavaScript API loader and independently managed map instances.
+icon: google-maps
+group: integrations
+---
+`GoogleMap` is a renderable integration for React and Next.js. It keeps the
+Google Maps JavaScript API off the page until the configured consent category is
+allowed, then loads the SDK once and creates a map for each mounted component.
+
+Unlike the helpers from `@c15t/scripts`, `GoogleMap` owns both the consent-aware
+script lifecycle and the visible map container.
+
+> ℹ️ **Info:**
+> The browser must receive a Google Maps API key, so the key is visible to site visitors. Keep it out of source control, use a key created for browser use, and restrict it by website and API in Google Cloud.
+
+## Integrate with c15t
+
+`GoogleMap` must render inside a `ConsentManagerProvider`. Complete the
+[React quickstart](/docs/frameworks/react/quickstart) or
+[Next.js quickstart](/docs/frameworks/next/quickstart) first.
+
+**React**
+
+```tsx
+import { GoogleMap } from '@c15t/react';
+
+const apiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;
+
+export function StoreMap() {
+  if (!apiKey) {
+    return <p>Google Maps is not configured.</p>;
+  }
+
+  return (
+    <GoogleMap
+      apiKey={apiKey}
+      authReferrerPolicy="origin"
+      center={{ lat: 40.7128, lng: -74.006 }}
+      consentCategory="measurement"
+      style={{ height: 400 }}
+      zoom={12}
+    />
+  );
+}
+```
+
+**Next.js**
+
+```tsx
+'use client';
+
+import { GoogleMap } from '@c15t/nextjs';
+
+const apiKey = process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY;
+
+export function StoreMap() {
+  if (!apiKey) {
+    return <p>Google Maps is not configured.</p>;
+  }
+
+  return (
+    <GoogleMap
+      apiKey={apiKey}
+      authReferrerPolicy="origin"
+      center={{ lat: 40.7128, lng: -74.006 }}
+      consentCategory="measurement"
+      style={{ height: 400 }}
+      zoom={12}
+    />
+  );
+}
+```
+
+`measurement` is a common choice for an interactive map, but the correct
+category depends on why your application uses Google Maps and the policy shown
+to your users.
+
+## How c15t loads it
+
+* **Before consent:** no Maps JavaScript API script is requested and no map
+  instance is created.
+* **After consent:** c15t registers one shared SDK loader and waits for Google's
+  callback before constructing the map.
+* **Multiple maps:** components with the same `scriptId` reuse the SDK while
+  keeping separate map instances.
+* **On revocation or unmount:** the component clears the map instance and its
+  listeners. The page-level SDK registration is retained after its first load
+  because Google supports one loader per page.
+* **Existing SDK:** if another part of the application already loaded a
+  compatible Google Maps global, the component adopts it instead of adding a
+  duplicate script.
+* **Visible states:** the blocked, loading, and error states are accessible and
+  use the active c15t translations by default.
+
+Keep one `scriptId` and one loader configuration across the page. Override the
+default `scriptId` only to coordinate with a known c15t script registration, not
+to load a second Maps SDK configuration. If two maps register conflicting
+loader options, c15t reports the conflict and tells you to align the key,
+language, region, libraries, and other loader options. A different `scriptId`
+does not make a second Google loader safe.
+
+## Configure the map
+
+Pass `center`, `zoom`, `mapId`, and `options` as you would when constructing a
+Google map:
+
+```tsx
+<GoogleMap
+  apiKey={apiKey}
+  center={{ lat: 51.5072, lng: -0.1276 }}
+  consentCategory="measurement"
+  mapId="YOUR_MAP_ID"
+  options={{
+    disableDefaultUI: true,
+    gestureHandling: 'cooperative',
+  }}
+  zoom={11}
+/>
+```
+
+Changes to `center`, `zoom`, and updateable `options` are applied to the existing
+map. Changing `mapId` recreates it because Google treats that value as
+construction-time configuration.
+
+The component has a default height of `320px`. Override `style.height` or apply
+a class with an explicit height when your layout needs another size.
+
+### Loader options
+
+The direct Maps JavaScript API loader options are available as component props:
+
+* `libraries`
+* `language`
+* `region`
+* `version`
+* `authReferrerPolicy`
+* `mapIds`
+* `channel`
+* `solutionChannel`
+* `nonce`
+
+`mapIds` preloads map ID configuration; `mapId` selects the map ID for the
+component instance.
+
+## Handle loading and errors
+
+The built-in loading and error states use `frame.loading` and `frame.error` from
+your c15t messages. The consent placeholder uses the localized consent-type
+title in both its message and button—for example, an `Analytics` title produces
+“Enable Analytics consent.”
+
+Use the fallback props when you need integration-specific content and `onError`
+for reporting:
+
+```tsx
+import { Frame, GoogleMap } from '@c15t/react';
+
+function reportMapError(error: Error) {
+  // Send the error to your observability provider.
+}
+
+<GoogleMap
+  apiKey={apiKey}
+  center={{ lat: 40.7128, lng: -74.006 }}
+  consentCategory="measurement"
+  loadingFallback={<p>Loading map…</p>}
+  errorFallback={<p>The map could not be loaded.</p>}
+  onError={reportMapError}
+  placeholder={
+    <Frame.Root>
+      <Frame.Title>Allow measurement consent to view this map.</Frame.Title>
+      <Frame.Button category="measurement" />
+    </Frame.Root>
+  }
+/>
+```
+
+`onError` covers loader failures, timeouts, map-constructor failures, and
+Google's global authentication failure callback. Authentication failures
+usually indicate an invalid key, missing billing, a disabled API, or a referrer
+that is not allowed.
+
+If you provide a custom `placeholder`, include `Frame.Button` or another way to
+reopen consent preferences or grant the required category.
+
+### Retry a failed map
+
+Increment `retryKey` to retry the same map after a loader, authentication, or
+constructor failure:
+
+```tsx
+import { GoogleMap } from '@c15t/react';
+import { useState } from 'react';
+
+function RetryableMap({ apiKey }: { apiKey: string }) {
+  const [retryKey, setRetryKey] = useState(0);
+
+  return (
+    <>
+      <GoogleMap
+        apiKey={apiKey}
+        center={{ lat: 40.7128, lng: -74.006 }}
+        retryKey={retryKey}
+      />
+
+      <button type="button" onClick={() => setRetryKey((key) => key + 1)}>
+        Retry map
+      </button>
+    </>
+  );
+}
+```
+
+Changing `retryKey` clears the failed attempt and retries with the same
+`scriptId`. A successful page-level SDK registration remains shared and is not
+loaded again.
+
+## Secure the browser key
+
+For production:
+
+1. Create a key specifically for the browser application.
+2. Apply a **Websites** application restriction for every allowed development
+   and production origin.
+3. Restrict the key to the **Maps JavaScript API** and any additional APIs used
+   by requested libraries.
+4. Keep the value in an untracked environment file and expose it through the
+   browser environment variable required by your framework.
+5. Monitor key usage and rotate the key if you see unexpected traffic.
+
+When `authReferrerPolicy="origin"` is set, configure origin-level website
+restrictions without URL paths.
+
+* [Google Maps Platform security guidance](https://developers.google.com/maps/api-security-best-practices)
+* [Maps JavaScript API loader options](https://developers.google.com/maps/documentation/javascript/load-maps-js-api)
+* [Maps Demo Key for local prototypes](https://developers.google.com/maps/documentation/javascript/demo-key)
+
+## Verify setup
+
+1. Clear saved consent and reload the page.
+2. Confirm no request to `maps.googleapis.com/maps/api/js` occurs before the
+   configured category is allowed.
+3. Grant consent and confirm the map reaches its ready state.
+4. Render two maps with the same `scriptId` and confirm only one loader script is
+   added.
+5. Revoke consent and confirm each map instance is removed.
+6. Test a rejected key or referrer and confirm `errorFallback` and `onError`
+   receive the failure.
+7. Fix the rejected configuration, change `retryKey`, and confirm the map can
+   recover without changing `scriptId`.
+
+## Types
+
+### GoogleMapProps
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`GoogleMapProps\`|
+|Source Path|\`./packages/react/src/components/integrations/google-map.tsx\`|
+
+\*ExtractedTypeTable: Could not extract "GoogleMapProps" from "./packages/react/src/components/integrations/google-map.tsx" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*