npm - @c15t/nextjs - Versions diffs - 2.1.0 → 2.2.1 - Mend

@c15t/nextjs 2.1.0 → 2.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (162) hide show

package/AGENTS.md +155 -0
package/README.md +31 -15
package/client/components/integrations.js +3 -0
package/dist/components/integrations/index.cjs +1 -0
package/dist/components/integrations/index.js +1 -0
package/dist/headless.cjs +1 -1
package/dist/index.cjs +1 -1
package/dist/libs/browser-initial-data.cjs +1 -1
package/dist/libs/initial-data.cjs +1 -1
package/dist/styles.tw3.css +1 -1
package/dist/version.cjs +1 -1
package/dist/version.js +1 -1
package/dist-types/components/integrations/index.d.ts +1 -0
package/dist-types/libs/browser-initial-data.d.ts +1 -1
package/dist-types/version.d.ts +1 -1
package/docs/README.md +155 -73
package/docs/{building-headless-components.md → frameworks/next/building-headless-components.md} +3 -1
package/docs/{callbacks.md → frameworks/next/callbacks.md} +3 -1
package/docs/{components → frameworks/next/components}/consent-banner.md +10 -21
package/docs/{components → frameworks/next/components}/consent-dialog-link.md +8 -5
package/docs/frameworks/next/components/consent-dialog-trigger.md +202 -0
package/docs/{components → frameworks/next/components}/consent-dialog.md +7 -15
package/docs/frameworks/next/components/consent-manager-provider.md +327 -0
package/docs/{components → frameworks/next/components}/consent-widget.md +8 -6
package/docs/{components → frameworks/next/components}/dev-tools.md +9 -6
package/docs/{components → frameworks/next/components}/frame.md +8 -9
package/docs/{concepts → frameworks/next/concepts}/client-modes.md +4 -2
package/docs/{concepts → frameworks/next/concepts}/consent-categories.md +1 -0
package/docs/{concepts → frameworks/next/concepts}/consent-models.md +1 -0
package/docs/{concepts → frameworks/next/concepts}/cookie-management.md +3 -3
package/docs/{concepts → frameworks/next/concepts}/glossary.md +1 -0
package/docs/{concepts → frameworks/next/concepts}/initialization-flow.md +1 -0
package/docs/{concepts → frameworks/next/concepts}/policy-packs.md +1 -0
package/docs/{headless.md → frameworks/next/headless.md} +3 -1
package/docs/{hooks → frameworks/next/hooks}/use-color-scheme.md +1 -0
package/docs/{hooks → frameworks/next/hooks}/use-consent-manager/checking-consent.md +3 -1
package/docs/{hooks → frameworks/next/hooks}/use-consent-manager/location-info.md +3 -1
package/docs/frameworks/next/hooks/use-consent-manager/overview.md +185 -0
package/docs/{hooks → frameworks/next/hooks}/use-consent-manager/setting-consent.md +3 -1
package/docs/{hooks → frameworks/next/hooks}/use-draggable.md +3 -1
package/docs/{hooks → frameworks/next/hooks}/use-focus-trap.md +1 -0
package/docs/{hooks → frameworks/next/hooks}/use-reduced-motion.md +3 -1
package/docs/{hooks → frameworks/next/hooks}/use-ssr-status.md +6 -5
package/docs/{hooks → frameworks/next/hooks}/use-text-direction.md +1 -0
package/docs/frameworks/next/hooks/use-translations.md +55 -0
package/docs/{iab → frameworks/next/iab}/consent-banner.md +9 -12
package/docs/{iab → frameworks/next/iab}/consent-dialog.md +9 -14
package/docs/{iab → frameworks/next/iab}/overview.md +4 -2
package/docs/{iab → frameworks/next/iab}/use-gvl-data.md +3 -2
package/docs/{iframe-blocking.md → frameworks/next/iframe-blocking.md} +8 -9
package/docs/{internationalization.md → frameworks/next/internationalization.md} +13 -3
package/docs/{network-blocker.md → frameworks/next/network-blocker.md} +13 -51
package/docs/{optimization.md → frameworks/next/optimization.md} +5 -4
package/docs/{policy-packs.md → frameworks/next/policy-packs.md} +3 -1
package/docs/{quickstart.md → frameworks/next/quickstart.md} +26 -42
package/docs/{script-loader.md → frameworks/next/script-loader.md} +72 -90
package/docs/{server-side.md → frameworks/next/server-side.md} +12 -15
package/docs/{styling → frameworks/next/styling}/classnames.md +3 -1
package/docs/{styling → frameworks/next/styling}/color-scheme.md +3 -1
package/docs/frameworks/next/styling/css-variables.md +53 -0
package/docs/frameworks/next/styling/overview.md +299 -0
package/docs/frameworks/next/styling/slots.md +94 -0
package/docs/{styling → frameworks/next/styling}/tailwind.md +3 -1
package/docs/frameworks/next/styling/tokens.md +156 -0
package/docs/{troubleshooting.md → frameworks/next/troubleshooting.md} +3 -1
package/docs/integrations/adobe-analytics.md +160 -0
package/docs/integrations/ahrefs-analytics.md +15 -82
package/docs/integrations/amplitude.md +230 -0
package/docs/integrations/building-integrations.md +15 -181
package/docs/integrations/clearbit.md +130 -0
package/docs/integrations/cloudflare-web-analytics.md +15 -83
package/docs/integrations/crisp.md +13 -87
package/docs/integrations/databuddy.md +16 -85
package/docs/integrations/fathom-analytics.md +15 -86
package/docs/integrations/google-maps.md +263 -0
package/docs/integrations/google-tag-manager.md +18 -86
package/docs/integrations/google-tag.md +15 -84
package/docs/integrations/heap.md +219 -0
package/docs/integrations/hightouch.md +199 -0
package/docs/integrations/hotjar.md +15 -83
package/docs/integrations/intercom.md +13 -83
package/docs/integrations/linkedin-insights.md +15 -82
package/docs/integrations/logrocket.md +175 -0
package/docs/integrations/matomo-analytics.md +13 -88
package/docs/integrations/meta-pixel.md +33 -316
package/docs/integrations/microsoft-clarity.md +15 -83
package/docs/integrations/microsoft-uet.md +16 -83
package/docs/integrations/mixpanel-analytics.md +15 -83
package/docs/integrations/overview.md +55 -6
package/docs/integrations/pirsch.md +142 -0
package/docs/integrations/plausible-analytics.md +14 -97
package/docs/integrations/posthog.md +26 -98
package/docs/integrations/promptwatch.md +16 -82
package/docs/integrations/reddit-pixel.md +27 -122
package/docs/integrations/rudderstack.md +271 -0
package/docs/integrations/rybbit-analytics.md +15 -94
package/docs/integrations/segment.md +15 -82
package/docs/integrations/snapchat-pixel.md +21 -102
package/docs/integrations/tiktok-pixel.md +13 -81
package/docs/integrations/umami-analytics.md +16 -88
package/docs/integrations/vercel-analytics.md +13 -85
package/docs/integrations/x-pixel.md +27 -102
package/docs/integrations/youtube.md +193 -0
package/docs/shared/concepts/client-modes.md +103 -0
package/docs/shared/concepts/consent-categories.md +41 -0
package/docs/shared/concepts/consent-models.md +72 -0
package/docs/shared/concepts/cookie-management.md +88 -0
package/docs/shared/concepts/glossary.md +24 -0
package/docs/shared/concepts/initialization-flow.md +105 -0
package/docs/shared/concepts/policy-packs.md +225 -0
package/docs/shared/react/components/consent-banner.md +242 -0
package/docs/shared/react/components/consent-dialog-link.md +45 -0
package/docs/shared/react/components/consent-dialog-trigger.md +185 -0
package/docs/shared/react/components/consent-dialog.md +119 -0
package/docs/shared/react/components/consent-manager-provider.md +225 -0
package/docs/shared/react/components/consent-widget.md +121 -0
package/docs/shared/react/components/dev-tools.md +81 -0
package/docs/shared/react/components/frame.md +52 -0
package/docs/shared/react/guides/building-headless-components.md +110 -0
package/docs/shared/react/guides/callbacks.md +89 -0
package/docs/shared/react/guides/headless.md +31 -0
package/docs/shared/react/guides/iframe-blocking.md +65 -0
package/docs/shared/react/guides/internationalization.md +123 -0
package/docs/shared/react/guides/network-blocker.md +72 -0
package/docs/shared/react/guides/optimization.md +44 -0
package/docs/shared/react/guides/policy-packs.md +173 -0
package/docs/shared/react/guides/script-loader.md +311 -0
package/docs/shared/react/hooks/use-color-scheme.md +31 -0
package/docs/shared/react/hooks/use-consent-manager/checking-consent.md +95 -0
package/docs/shared/react/hooks/use-consent-manager/location-info.md +96 -0
package/docs/shared/react/hooks/use-consent-manager/overview.md +74 -0
package/docs/shared/react/hooks/use-consent-manager/setting-consent.md +93 -0
package/docs/shared/react/hooks/use-draggable.md +30 -0
package/docs/shared/react/hooks/use-focus-trap.md +20 -0
package/docs/shared/react/hooks/use-reduced-motion.md +33 -0
package/docs/shared/react/hooks/use-ssr-status.md +16 -0
package/docs/shared/react/hooks/use-text-direction.md +38 -0
package/docs/shared/react/hooks/use-translations.md +15 -0
package/docs/shared/react/iab/consent-banner.md +60 -0
package/docs/shared/react/iab/consent-dialog.md +76 -0
package/docs/shared/react/iab/overview.md +80 -0
package/docs/shared/react/iab/use-gvl-data.md +21 -0
package/docs/shared/react/styling/classnames.md +93 -0
package/docs/shared/react/styling/color-scheme.md +35 -0
package/docs/shared/react/styling/css-variables.md +53 -0
package/docs/shared/react/styling/overview.md +261 -0
package/docs/shared/react/styling/slots.md +93 -0
package/docs/shared/react/styling/stylesheet-entrypoint.md +8 -0
package/docs/shared/react/styling/tailwind.md +88 -0
package/docs/shared/react/styling/tokens.md +155 -0
package/docs/shared/troubleshooting.md +82 -0
package/package.json +19 -10
package/readme.json +14 -8
package/docs/ai-agents.md +0 -111
package/docs/components/consent-dialog-trigger.md +0 -103
package/docs/components/consent-manager-provider.md +0 -425
package/docs/hooks/use-consent-manager/overview.md +0 -420
package/docs/hooks/use-translations.md +0 -118
package/docs/styling/css-variables.md +0 -92
package/docs/styling/overview.md +0 -457
package/docs/styling/slots.md +0 -128
package/docs/styling/tokens.md +0 -216

package/docs/integrations/google-tag.md CHANGED Viewed

@@ -1,8 +1,9 @@
 ---
 title: GA4 + Google Ads (gtag.js)
-description: Send data to Google Analytics 4 and Google Ads with automatic Consent Mode v2 support.
-lastModified: 2026-02-10
+description: Send data to Google Analytics 4 and Google Ads with automatic
+  Consent Mode v2 support.
 icon: google-analytics
+group: integrations
 ---
 Google Tag (`gtag.js`) is Google's unified tracking script for sending data to Google Analytics 4 (GA4), Google Ads, and Floodlight. It measures user behavior, tracks conversions, and powers Google's advertising ecosystem.
@@ -116,88 +117,18 @@ You do not need to wrap `gtag(...)` calls in a `useConsentManager().has(...)` ch
 ### GtagOptions
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|Your gtag id|-|✅ Required|
-|category|AllConsentNames|The consent category to use for the gtag script. This is typically marketing (Ads & Floodlight) or measurement (Analytics)|-|✅ Required|
-|consentMapping|Record\<string, string\[]> \|undefined|Custom mapping from c15t consent categories to Google Consent Mode v2 types. Overrides the default mapping when provided.|\`\`\`ts \{ necessary: \['security\_storage'], functionality: \['functionality\_storage'], measurement: \['analytics\_storage'], marketing: \['ad\_storage', 'ad\_user\_data', 'ad\_personalization'], experience: \['personalization\_storage'], } \`\`\`|Optional|
-|script|Script \|undefined|Deprecated script-level overrides preserved for backwards compatibility. Prefer manifest-backed options instead of this generic override bag.|-|Optional|
+|Property|Value|
+|:--|:--|
+|Type Name|\`GtagOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/google-tag.ts\`|
+\*ExtractedTypeTable: Could not extract "GtagOptions" from "./packages/scripts/src/vendors/analytics/google-tag.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
 ### Script
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|Unique identifier for the script|-|✅ Required|
-|src|string \|undefined|URL of the script to load|-|Optional|
-|textContent|string \|undefined|Inline JavaScript code to execute|-|Optional|
-|category|HasCondition\<AllConsentNames>|Consent category or condition required to load this script|-|✅ Required|
-|callbackOnly|boolean \|undefined|Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed.|false|Optional|
-|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|false|Optional|
-|alwaysLoad|boolean \|undefined|Whether the script should always load regardless of consent state. This is useful for scripts like Google Tag Manager or PostHog that manage their own consent state internally. The script will load immediately and never be unloaded based on consent changes. Note: When using this option, you are responsible for ensuring the script itself respects user consent preferences through its own consent management.|false|Optional|
-|fetchPriority|"high" \|"low" \|"auto" \|undefined|Priority hint for browser resource loading|-|Optional|
-|attributes|Record\<string, string> \|undefined|Additional attributes to add to the script element|-|Optional|
-|async|boolean \|undefined|Whether to use async loading|-|Optional|
-|defer|boolean \|undefined|Whether to defer script loading|-|Optional|
-|nonce|string \|undefined|Content Security Policy nonce|-|Optional|
-|anonymizeId|boolean \|undefined|Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockers|true|Optional|
-|target|"head" \|"body" \|undefined|Where to inject the script element in the DOM. Options: \`'head'\`: Scripts are appended to \`\<head>\` (default); \`'body'\`: Scripts are appended to \`\<body>\`|'head'|Optional|
-|onBeforeLoad|Object \|undefined|Callback executed before the script is loaded|-|Optional|
-|onLoad|Object \|undefined|Callback executed when the script loads successfully|-|Optional|
-|onError|Object \|undefined|Callback executed if the script fails to load|-|Optional|
-|onConsentChange|Object \|undefined|Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.|-|Optional|
-|vendorId|string \|number \|undefined|IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over \`category\` when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.|-|Optional|
-|iabPurposes|number\[] \|undefined|IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.|-|Optional|
-|iabLegIntPurposes|number\[] \|undefined|IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.|-|Optional|
-|iabSpecialFeatures|number\[] \|undefined|IAB TCF special feature IDs this script requires. Options: 1: Use precise geolocation data; 2: Actively scan device characteristics for identification|-|Optional|
-#### `onBeforeLoad`
-Callback executed before the script is loaded
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-#### `onLoad`
-Callback executed when the script loads successfully
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-#### `onError`
-Callback executed if the script fails to load
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-#### `onConsentChange`
-Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
+|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/heap.md ADDED Viewed

@@ -0,0 +1,219 @@
+---
+title: Heap
+description: Load Heap with c15t and gate autocapture product analytics behind
+  measurement consent.
+group: integrations
+icon: heap
+---
+[Heap](https://www.heap.io/) provides product analytics with automatic interaction capture, identity APIs, event properties, and pageview tracking. The `heap()` helper creates Heap's current heap.js v5 callback queue, records your environment ID and optional client configuration, and loads Heap only when `measurement` consent is available.
+## Integrate with c15t
+**React**
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { heap } from '@c15t/scripts/heap';
+const scripts = [
+  heap({
+    envId: 'YOUR_APP_ID',
+    clientConfig: {
+      disableTextCapture: 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 { heap } from '@c15t/scripts/heap';
+const scripts = [
+  heap({
+    envId: 'YOUR_APP_ID',
+    clientConfig: {
+      disableTextCapture: 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 { heap } from '@c15t/scripts/heap';
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    heap({
+      envId: 'YOUR_APP_ID',
+      clientConfig: {
+        disableTextCapture: true,
+      },
+    }),
+  ],
+});
+```
+## How c15t loads it
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted
+* **On revocation:** unloaded - c15t removes the script element it created. `window.heap` and `window.heapReadyCb` remain until the next page load (c15t reloads the page on revocation by default), and Heap has no documented browser opt-out API — treat the load gate as the consent boundary.
+The helper maps Heap's current web installation snippet into the manifest engine:
+```ts
+heap({
+  envId: 'YOUR_APP_ID',
+  clientConfig: {
+    disableTextCapture: true,
+  },
+});
+```
+It creates `window.heapReadyCb` and `window.heap`, records:
+```ts
+window.heap.envId = 'YOUR_APP_ID';
+window.heap.appid = 'YOUR_APP_ID';
+window.heap.clientConfig = {
+  disableTextCapture: true,
+  shouldFetchServerConfig: false,
+};
+```
+and loads:
+```txt
+https://cdn.us.heap-api.com/config/YOUR_APP_ID/heap_config.js
+```
+Heap's config script then chain-loads the versioned heap.js runtime for that environment. The official snippet stores queued calls as `{ name, fn }` records in `window.heapReadyCb`; c15t reproduces that callback queue instead of using tuple queues such as `['track', ...args]`.
+`envId` is required and must be a non-empty string after trimming. Heap app IDs are commonly numeric strings, but Heap's public install docs describe the value as your app ID, so c15t does not enforce a numeric-only format.
+## Configure heap.js
+Pass `clientConfig` as the second Heap load argument. Values must be JSON-serializable: plain objects, arrays, strings, finite numbers, booleans, and `null`.
+```ts
+import { heap } from '@c15t/scripts/heap';
+heap({
+  envId: 'YOUR_APP_ID',
+  clientConfig: {
+    disableTextCapture: true,
+    disableSessionReplay: true,
+    metadataStorage: 'localstorage',
+  },
+});
+```
+c15t always adds `shouldFetchServerConfig: false`, matching Heap's current installation snippet. Do not pass functions, Dates, Maps, Sets, class instances, symbols, `undefined`, `NaN`, or infinite numbers in `clientConfig`.
+To proxy or self-host the config loader, pass a custom URL:
+```ts
+heap({
+  envId: 'YOUR_APP_ID',
+  scriptUrl: 'https://analytics.example.com/heap_config.js',
+});
+```
+## Consent behavior
+c15t blocks Heap from loading until `measurement` consent is granted and unloads it on revocation. Heap autocaptures interactions when heap.js runs, and its web installation docs do not document a consent-mode-style runtime opt-out API that c15t can call to make an already-loaded SDK inert after consent is withdrawn.
+That makes the consent gate on load the consent boundary: no Heap config loader, heap.js runtime, cookies, localStorage, automatic page tracking, or interaction capture should start before the user grants `measurement` consent. See the [RudderStack consent notes](/docs/integrations/rudderstack#consent-behavior) for the broader reasoning behind blocking SDK load when a vendor API cannot guarantee denied-by-default collection semantics.
+## Tracking events in your app
+c15t gates Heap from loading until `measurement` consent is granted. Your application code that calls Heap's runtime API (`window.heap.track`, `identify`, etc.) is **not** automatically gated - `window.heap` does not exist until the script is loaded, so unguarded calls before consent throw.
+Guard event calls by checking consent state. From React:
+```tsx
+import { useCallback } from 'react';
+import { useConsentManager } from '@c15t/react';
+function SignupExample() {
+  const { has } = useConsentManager();
+  const trackSignup = useCallback(() => {
+    if (has('measurement')) {
+      window.heap?.track('Signup Completed', { plan: 'pro' });
+    }
+  }, [has]);
+}
+```
+From plain JavaScript:
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+const { consentStore } = getOrCreateConsentRuntime();
+if (consentStore.getState().has('measurement')) {
+  window.heap?.track('Signup Completed', { plan: 'pro' });
+}
+```
+## Types
+### HeapOptions
+|Property|Value|
+|:--|:--|
+|Type Name|\`HeapOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/heap.ts\`|
+\*ExtractedTypeTable: Could not extract "HeapOptions" from "./packages/scripts/src/vendors/analytics/heap.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/hightouch.md ADDED Viewed

@@ -0,0 +1,199 @@
+---
+title: Hightouch
+description: Load Hightouch Events with c15t and gate the browser SDK behind
+  measurement consent.
+group: integrations
+icon: hightouch
+---
+[Hightouch Events](https://hightouch.com/docs/events/overview) collects customer behavior from websites and sends it into Hightouch for warehouse-backed analytics, activation, and real-time workflows. The `hightouch()` helper creates Hightouch's `window.htevents` queue, records the write key and optional API host for the standalone loader, optionally queues the initial `page()` call, and loads the browser SDK when `measurement` consent is available.
+## Integrate with c15t
+**React**
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { hightouch } from '@c15t/scripts/hightouch';
+const scripts = [
+  hightouch({
+    writeKey: 'WRITE_KEY',
+    apiHost: 'us-east-1.hightouch-events.com',
+  }),
+];
+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 { hightouch } from '@c15t/scripts/hightouch';
+const scripts = [
+  hightouch({
+    writeKey: 'WRITE_KEY',
+    apiHost: 'us-east-1.hightouch-events.com',
+  }),
+];
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+**JavaScript**
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { hightouch } from '@c15t/scripts/hightouch';
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    hightouch({
+      writeKey: 'WRITE_KEY',
+      apiHost: 'us-east-1.hightouch-events.com',
+    }),
+  ],
+});
+```
+## How c15t loads it
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted
+* **On revocation:** unloaded - c15t removes the script element it created. The `window.htevents` runtime object is left in place until the next page load (c15t reloads the page on revocation by default), so treat the load gate as the consent boundary.
+The helper maps Hightouch's browser snippet into the manifest engine:
+```ts
+hightouch({
+  writeKey: 'WRITE_KEY',
+  apiHost: 'us-east-1.hightouch-events.com',
+});
+```
+It creates `window.htevents`, defines the official queue methods, queues:
+```ts
+window.htevents.load('WRITE_KEY', {
+  apiHost: 'us-east-1.hightouch-events.com',
+});
+window.htevents.page();
+```
+and loads:
+```txt
+https://cdn.hightouch-events.com/browser/release/v1-latest/events.min.js
+```
+`writeKey` is required and must be a non-empty string after trimming. `apiHost` is optional; Hightouch's SDK defaults to `us-east-1.hightouch-events.com`, so pass it only when your Event Source uses another region or a first-party tracking host.
+## Configure page tracking
+By default the helper queues `htevents.page()` before the vendor bundle loads. If you want to handle page views yourself, set `trackPageView` to `false`.
+```ts
+import { hightouch } from '@c15t/scripts/hightouch';
+hightouch({
+  writeKey: 'WRITE_KEY',
+  trackPageView: false,
+});
+```
+To proxy or self-host the loader, pass a custom URL:
+```ts
+hightouch({
+  writeKey: 'WRITE_KEY',
+  scriptUrl: 'https://analytics.example.com/events.min.js',
+});
+```
+## Consent behavior
+c15t blocks the Hightouch SDK from loading until `measurement` consent is granted and unloads it on revocation. Hightouch does not expose a browser API that prevents collection while loaded — the SDK writes identifiers and delivers events to Hightouch as soon as it runs — so gating the load is the only default that reliably honors missing or denied consent. See the [RudderStack consent notes](/docs/integrations/rudderstack#consent-behavior) for the full reasoning behind this model versus vendor consent-API mapping (as used for Google Tag Manager).
+## Tracking events in your app
+c15t gates the Hightouch browser SDK from loading until `measurement` consent is granted. Your application code that calls Hightouch's runtime API (`window.htevents.track`, `identify`, etc.) is **not** automatically gated - `window.htevents` does not exist until c15t initializes the integration, so unguarded calls made before that (or while consent is denied) throw. Once the integration is initialized with consent, early calls queue normally until the SDK finishes loading.
+Guard event calls by checking consent state. From React:
+```tsx
+import { useCallback } from 'react';
+import { useConsentManager } from '@c15t/react';
+function SignupExample() {
+  const { has } = useConsentManager();
+  const trackSignup = useCallback(() => {
+    if (has('measurement')) {
+      window.htevents?.track('Signup Completed', { plan: 'pro' });
+    }
+  }, [has]);
+}
+```
+From plain JavaScript:
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+const { consentStore } = getOrCreateConsentRuntime();
+if (consentStore.getState().has('measurement')) {
+  window.htevents?.track('Signup Completed', { plan: 'pro' });
+}
+```
+## Types
+### HightouchOptions
+|Property|Value|
+|:--|:--|
+|Type Name|\`HightouchOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/hightouch.ts\`|
+\*ExtractedTypeTable: Could not extract "HightouchOptions" from "./packages/scripts/src/vendors/analytics/hightouch.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/hotjar.md CHANGED Viewed

@@ -1,7 +1,8 @@
 ---
 title: Hotjar
-description: Product analytics and behavior insights with a prebuilt helper that seeds Hotjar globals before loading the vendor bundle.
-lastModified: 2026-05-10
+description: Product analytics and behavior insights with a prebuilt helper that
+  seeds Hotjar globals before loading the vendor bundle.
+group: integrations
 icon: hotjar
 ---
 Hotjar helps you understand behavior with heatmaps, session recordings, and feedback tools. The `hotjar()` helper sets up Hotjar's `_hjSettings` global and `hj` queue stub, then loads the vendor script once `measurement` consent is granted.
@@ -125,87 +126,18 @@ if (consentStore.getState().has('measurement')) {
 ### HotjarOptions
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|siteId|string \|number|Your Hotjar site ID.|-|✅ Required|
-|version|number \|undefined|Hotjar script version.|6|Optional|
-|scriptUrl|string \|undefined|Hotjar loader URL.|-|Optional|
+|Property|Value|
+|:--|:--|
+|Type Name|\`HotjarOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/hotjar.ts\`|
+\*ExtractedTypeTable: Could not extract "HotjarOptions" from "./packages/scripts/src/vendors/analytics/hotjar.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
 ### Script
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|Unique identifier for the script|-|✅ Required|
-|src|string \|undefined|URL of the script to load|-|Optional|
-|textContent|string \|undefined|Inline JavaScript code to execute|-|Optional|
-|category|HasCondition\<AllConsentNames>|Consent category or condition required to load this script|-|✅ Required|
-|callbackOnly|boolean \|undefined|Whether this is a callback-only script that doesn't need to load an external resource. When true, no script tag will be added to the DOM, only callbacks will be executed.|false|Optional|
-|persistAfterConsentRevoked|boolean \|undefined|Whether the script should persist after consent is revoked.|false|Optional|
-|alwaysLoad|boolean \|undefined|Whether the script should always load regardless of consent state. This is useful for scripts like Google Tag Manager or PostHog that manage their own consent state internally. The script will load immediately and never be unloaded based on consent changes. Note: When using this option, you are responsible for ensuring the script itself respects user consent preferences through its own consent management.|false|Optional|
-|fetchPriority|"high" \|"low" \|"auto" \|undefined|Priority hint for browser resource loading|-|Optional|
-|attributes|Record\<string, string> \|undefined|Additional attributes to add to the script element|-|Optional|
-|async|boolean \|undefined|Whether to use async loading|-|Optional|
-|defer|boolean \|undefined|Whether to defer script loading|-|Optional|
-|nonce|string \|undefined|Content Security Policy nonce|-|Optional|
-|anonymizeId|boolean \|undefined|Whether to use an anonymized ID for the script element, this helps ensure the script is not blocked by ad blockers|true|Optional|
-|target|"head" \|"body" \|undefined|Where to inject the script element in the DOM. Options: \`'head'\`: Scripts are appended to \`\<head>\` (default); \`'body'\`: Scripts are appended to \`\<body>\`|'head'|Optional|
-|onBeforeLoad|Object \|undefined|Callback executed before the script is loaded|-|Optional|
-|onLoad|Object \|undefined|Callback executed when the script loads successfully|-|Optional|
-|onError|Object \|undefined|Callback executed if the script fails to load|-|Optional|
-|onConsentChange|Object \|undefined|Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.|-|Optional|
-|vendorId|string \|number \|undefined|IAB TCF vendor ID - links script to a registered vendor. When in IAB mode, the script will only load if this vendor has consent. Takes precedence over \`category\` when in IAB mode. Use custom vendor IDs (string or number) to gate non-IAB vendors too.|-|Optional|
-|iabPurposes|number\[] \|undefined|IAB TCF purpose IDs this script requires consent for. When in IAB mode and no vendorId is set, the script will only load if ALL specified purposes have consent.|-|Optional|
-|iabLegIntPurposes|number\[] \|undefined|IAB TCF legitimate interest purpose IDs. These purposes can operate under legitimate interest instead of consent. The script loads if all iabPurposes have consent OR all iabLegIntPurposes have legitimate interest established.|-|Optional|
-|iabSpecialFeatures|number\[] \|undefined|IAB TCF special feature IDs this script requires. Options: 1: Use precise geolocation data; 2: Actively scan device characteristics for identification|-|Optional|
-#### `onBeforeLoad`
-Callback executed before the script is loaded
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-#### `onLoad`
-Callback executed when the script loads successfully
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-#### `onError`
-Callback executed if the script fails to load
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
-#### `onConsentChange`
-Callback executed whenever the consent store is changed. This callback only applies to scripts already loaded.
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|id|string|The original script ID|-|✅ Required|
-|elementId|string|The actual DOM element ID used (anonymized if enabled)|-|✅ Required|
-|hasConsent|boolean|Has consent|-|✅ Required|
-|consents|ConsentState|The current consent state|-|✅ Required|
-|element|HTMLScriptElement \|undefined|The script element (for load/error callbacks) Will be undefined for callback-only scripts|-|Optional|
-|error|Error \|undefined|Error information (for error callbacks)|-|Optional|
+|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.\*