@c15t/scripts 2.1.0 → 2.2.0-canary-20260804162155

package/docs/integrations/adobe-analytics.md

@@ -0,0 +1,160 @@
+---
+title: Adobe Analytics
+description: Adobe Analytics loaded through an Adobe Experience Platform Data
+  Collection Tags embed URL.
+group: integrations
+icon: adobe-analytics
+---
+[Adobe Analytics](https://business.adobe.com/products/analytics/adobe-analytics.html) is commonly deployed through an Adobe Experience Platform Data Collection web property. Data Collection generates a property-specific Tags embed script, often hosted on `assets.adobedtm.com`, and that script can load Adobe Analytics, Web SDK, or other configured extensions and rules.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { adobeAnalytics } from '@c15t/scripts/adobe-analytics';
+
+const scripts = [
+  adobeAnalytics({
+    scriptUrl:
+      'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
+  }),
+];
+
+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 { adobeAnalytics } from '@c15t/scripts/adobe-analytics';
+
+const scripts = [
+  adobeAnalytics({
+    scriptUrl:
+      'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { adobeAnalytics } from '@c15t/scripts/adobe-analytics';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    adobeAnalytics({
+      scriptUrl:
+        'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
+    }),
+  ],
+});
+```
+
+## Find Your Embed URL
+
+Open Adobe Data Collection, choose your Tags property, then open **Environments**. Select the install action for the environment you want to deploy and copy the web property embed script URL from the generated code.
+
+Each Adobe environment has its own embed code. Use the production URL in production, and keep development or staging URLs limited to test environments. The URL is typically shaped like:
+
+```txt
+https://assets.adobedtm.com/{org}/{property}/launch-{env}.min.js
+```
+
+Self-hosted Data Collection builds are supported too. c15t only requires a full `https:` URL.
+
+## How c15t loads it
+
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted
+* **On revocation:** unloaded - c15t removes the Adobe Tags script element from the DOM.
+
+The helper blocks the Adobe Tags library until measurement consent is granted. When measurement consent is revoked, c15t unloads the script element. Adobe rules, extensions, cookies, and downstream tags that already ran may have their own state, so configure Data Collection rules and extensions to respect your consent model as well.
+
+This is the same caveat as tag managers: a Tags property can load more than Adobe Analytics. Keep non-measurement tags behind Adobe-side rule conditions, consent checks, or separate properties so they do not run from a measurement-only grant.
+
+By default, c15t also seeds the Adobe Client Data Layer queue before loading:
+
+```ts
+adobeAnalytics({
+  scriptUrl:
+    'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
+  seedAdobeDataLayer: true,
+})
+```
+
+This creates `window.adobeDataLayer = []` only when it is still undefined. Adobe's Client Data Layer extension uses `adobeDataLayer` as the default object name, and the pre-seed is harmless for properties that do not use that extension.
+
+Adobe's `_satellite` object becomes available after the Tags library loads:
+
+```ts
+if (window._satellite) {
+  // Adobe Tags runtime is available.
+}
+```
+
+Use synchronous deployment only when a legacy Tags setup requires it:
+
+```ts
+adobeAnalytics({
+  scriptUrl:
+    'https://assets.adobedtm.com/YOUR_ORG/YOUR_PROPERTY/launch-production.min.js',
+  async: false,
+})
+```
+
+## Types
+
+### AdobeAnalyticsOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`AdobeAnalyticsOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/adobe-analytics.ts\`|
+
+\*ExtractedTypeTable: Could not extract "AdobeAnalyticsOptions" from "./packages/scripts/src/vendors/analytics/adobe-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/ahrefs-analytics.md

@@ -0,0 +1,157 @@
+---
+title: Ahrefs Analytics
+description: Cookieless web analytics from Ahrefs with a prebuilt helper that
+  wires the project key into a c15t-managed script.
+group: integrations
+icon: ahrefs
+---
+Ahrefs Web Analytics is a cookieless analytics product configured with a single project key. The `ahrefsAnalytics()` helper wires that key into the `data-key` attribute that Ahrefs' loader reads at startup.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { ahrefsAnalytics } from '@c15t/scripts/ahrefs-analytics';
+
+const scripts = [
+  ahrefsAnalytics({
+    key: 'your-ahrefs-project-key',
+  }),
+];
+
+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 { ahrefsAnalytics } from '@c15t/scripts/ahrefs-analytics';
+
+const scripts = [
+  ahrefsAnalytics({
+    key: 'your-ahrefs-project-key',
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { ahrefsAnalytics } from '@c15t/scripts/ahrefs-analytics';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    ahrefsAnalytics({
+      key: 'your-ahrefs-project-key',
+    }),
+  ],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted
+* **On revocation:** unloaded — c15t removes the script element from the DOM. Ahrefs Web Analytics is cookieless, so no client-side state needs clearing.
+
+To run from a custom loader URL (for example a self-hosted proxy):
+
+```ts
+ahrefsAnalytics({
+  key: 'your-ahrefs-project-key',
+  scriptUrl: 'https://analytics.example.com/analytics.js',
+})
+```
+
+Once loaded, Ahrefs exposes its runtime API on `window.AhrefsAnalytics`. The c15t helper only models the serializable script configuration — calls to `window.AhrefsAnalytics.sendEvent(...)` happen in your application code as needed.
+
+## Tracking events in your app
+
+c15t gates the Ahrefs Analytics script from loading until `measurement` consent is granted. Your application code that calls Ahrefs' runtime API (`window.AhrefsAnalytics.sendEvent`) is **not** automatically gated — `window.AhrefsAnalytics` 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.AhrefsAnalytics?.sendEvent('signup');
+    }
+  }, [has]);
+
+  // Call trackSignup() from an event handler after signup succeeds.
+}
+```
+
+From plain JavaScript:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+
+const { consentStore } = getOrCreateConsentRuntime();
+
+if (consentStore.getState().has('measurement')) {
+  window.AhrefsAnalytics?.sendEvent('signup');
+}
+```
+
+## Types
+
+### AhrefsAnalyticsOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`AhrefsAnalyticsOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/ahrefs-analytics.ts\`|
+
+\*ExtractedTypeTable: Could not extract "AhrefsAnalyticsOptions" from "./packages/scripts/src/vendors/analytics/ahrefs-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/amplitude.md

@@ -0,0 +1,230 @@
+---
+title: Amplitude
+description: Load Amplitude Browser SDK 2 with c15t and gate product analytics
+  behind measurement consent.
+group: integrations
+icon: amplitude
+---
+[Amplitude](https://amplitude.com/) provides product analytics for tracking user behavior, funnels, retention, and feature adoption. The `amplitude()` helper creates the Browser SDK 2 snippet queue, queues `amplitude.init(apiKey, initOptions)`, and loads Amplitude only when `measurement` consent is available.
+
+## Integrate with c15t
+
+**React**
+
+```tsx
+import { type ReactNode } from 'react';
+import { ConsentManagerProvider } from '@c15t/react';
+import { amplitude } from '@c15t/scripts/amplitude';
+
+const scripts = [
+  amplitude({
+    apiKey: 'AMPLITUDE_API_KEY',
+    initOptions: {
+      autocapture: false,
+    },
+  }),
+];
+
+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 { amplitude } from '@c15t/scripts/amplitude';
+
+const scripts = [
+  amplitude({
+    apiKey: 'AMPLITUDE_API_KEY',
+    initOptions: {
+      autocapture: false,
+    },
+  }),
+];
+
+export function ConsentProvider({ children }: { children: ReactNode }) {
+  return (
+    <ConsentManagerProvider
+      options={{
+        mode: 'hosted',
+        backendURL: '/api/c15t',
+        scripts,
+      }}
+    >
+      {children}
+    </ConsentManagerProvider>
+  );
+}
+```
+
+**JavaScript**
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+import { amplitude } from '@c15t/scripts/amplitude';
+
+getOrCreateConsentRuntime({
+  mode: 'hosted',
+  backendURL: 'https://your-instance.c15t.dev',
+  scripts: [
+    amplitude({
+      apiKey: 'AMPLITUDE_API_KEY',
+      initOptions: {
+        autocapture: false,
+      },
+    }),
+  ],
+});
+```
+
+## How c15t loads it
+
+* **Category:** `measurement` (Analytics)
+* **Loads when:** measurement consent is granted
+* **On revocation:** c15t calls `amplitude.setOptOut(true)` through the lifecycle callback and unloads the script by default.
+
+The helper maps Amplitude Browser SDK 2's script-loader contract into the manifest engine:
+
+```ts
+amplitude({
+  apiKey: 'AMPLITUDE_API_KEY',
+  initOptions: {
+    autocapture: false,
+  },
+});
+```
+
+It creates `window.amplitude` with:
+
+* `invoked: true`
+* `_q: []` for queued `{ name, args, resolve }` method calls
+* `_iq: {}` for the named-instance registry expected by the SDK
+* `Identify` for queued pre-load identify operations
+* core queue methods for `init`, `track`, `identify`, `setUserId`, `setOptOut`, and `flush`
+
+Then it queues:
+
+```ts
+window.amplitude.init('AMPLITUDE_API_KEY', {
+  autocapture: false,
+});
+```
+
+and loads:
+
+```txt
+https://cdn.amplitude.com/libs/analytics-browser-2.44.4-min.js.gz
+```
+
+`apiKey` is required and must be a non-empty string after trimming.
+
+## Configure initialization
+
+Pass `initOptions` to provide Amplitude Browser SDK 2 initialization options. Values must be JSON-serializable: plain objects, arrays, strings, numbers, booleans, and `null`.
+
+```ts
+import { amplitude } from '@c15t/scripts/amplitude';
+
+amplitude({
+  apiKey: 'AMPLITUDE_API_KEY',
+  initOptions: {
+    autocapture: false,
+    fetchRemoteConfig: false,
+  },
+});
+```
+
+Do not pass functions, Dates, Maps, Sets, class instances, symbols, or other non-JSON values in `initOptions`.
+
+## Configure the loader URL
+
+Amplitude's Browser SDK 2 CDN bundle path is versioned. c15t pins a tested default version and lets you override the URL if you self-host or proxy the bundle.
+
+```ts
+amplitude({
+  apiKey: 'AMPLITUDE_API_KEY',
+  scriptUrl: 'https://analytics.example.com/analytics-browser.js',
+});
+```
+
+## Consent behavior
+
+Amplitude should not load before analytics consent. c15t gates the SDK on `measurement` consent and queues `init()` only when the script is allowed to load.
+
+After the SDK has loaded, the generated lifecycle callback maps consent changes to Amplitude's runtime opt-out API:
+
+```ts
+window.amplitude.setOptOut(false); // measurement granted
+window.amplitude.setOptOut(true); // measurement denied
+```
+
+The script still uses c15t's default unload behavior when measurement consent is revoked.
+
+## Tracking events in your app
+
+c15t gates the Amplitude browser SDK from loading until `measurement` consent is granted. Your application code that calls Amplitude's runtime API (`window.amplitude.track`, `identify`, etc.) is **not** automatically gated - `window.amplitude` 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.amplitude?.track('Signup Completed', { plan: 'pro' });
+    }
+  }, [has]);
+}
+```
+
+From plain JavaScript:
+
+```ts
+import { getOrCreateConsentRuntime } from 'c15t';
+
+const { consentStore } = getOrCreateConsentRuntime();
+
+if (consentStore.getState().has('measurement')) {
+  window.amplitude?.track('Signup Completed', { plan: 'pro' });
+}
+```
+
+## Types
+
+### AmplitudeOptions
+
+|Property|Value|
+|:--|:--|
+|Type Name|\`AmplitudeOptions\`|
+|Source Path|\`./packages/scripts/src/vendors/analytics/amplitude.ts\`|
+
+\*ExtractedTypeTable: Could not extract "AmplitudeOptions" from "./packages/scripts/src/vendors/analytics/amplitude.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.\*