@c15t/nextjs 2.1.0 → 2.2.1

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

@@ -1,7 +1,8 @@
 ---
 title: Ahrefs Analytics
-description: Cookieless web analytics from Ahrefs with a prebuilt helper that wires the project key into a c15t-managed script.
-lastModified: 2026-05-10
+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.
@@ -139,86 +140,18 @@ if (consentStore.getState().has('measurement')) {
 
 ### AhrefsAnalyticsOptions
 
-|Property|Type|Description|Default|Required|
-|:--|:--|:--|:--|:--:|
-|key|string|Your Ahrefs Web Analytics project key.|-|✅ Required|
-|scriptUrl|string \|undefined|Custom loader URL.|'https\://analytics.ahrefs.com/analytics.js'|Optional|
+|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|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/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.\*