@c15t/scripts 3.0.0-alpha.2 → 3.0.0-alpha.3

package/package.json

@@ -1,41 +1,8 @@
 {
 	"name": "@c15t/scripts",
-	"version": "3.0.0-alpha.2",
-	"description": "Consent-aware script integrations for Google Tag Manager, Google Consent Mode v2, GA4, Google Ads, Meta Pixel, and more.",
-	"keywords": [
-		"adobe-analytics",
-		"amplitude",
-		"analytics-consent",
-		"c15t",
-		"ccpa",
-		"clearbit",
-		"cmp",
-		"consent",
-		"consent-mode",
-		"consent-mode-v2",
-		"ga4",
-		"gdpr",
-		"google-ads",
-		"google-tag",
-		"google-tag-manager",
-		"gtm",
-		"heap",
-		"hightouch",
-		"lgpd",
-		"linkedin-insights",
-		"logrocket",
-		"meta-pixel",
-		"microsoft-uet",
-		"pinterest-tag",
-		"pirsch",
-		"posthog",
-		"privacy",
-		"rudderstack",
-		"script-loader",
-		"tiktok-pixel",
-		"x-pixel"
-	],
-	"homepage": "https://c15t.com/docs/frameworks/javascript/script-loader",
+	"version": "3.0.0-alpha.3",
+	"description": "Deprecated v3 compatibility package for @c15t/integrations. Migrate before v4.",
+	"homepage": "https://c15t.com/docs/upgrade-v3#rename-the-integrations-dependency",
 	"bugs": {
 		"url": "https://github.com/c15t/c15t/issues"
 	},
@@ -49,249 +16,35 @@
 		"dist",
 		"dist-types",
 		"AGENTS.md",
+		"SKILL.md",
 		"docs"
 	],
 	"type": "module",
 	"sideEffects": false,
 	"exports": {
-		"./adobe-analytics": {
-			"types": "./dist-types/vendors/analytics/adobe-analytics.d.ts",
-			"import": "./dist/vendors/analytics/adobe-analytics.js",
-			"default": "./dist/vendors/analytics/adobe-analytics.js"
-		},
-		"./ahrefs-analytics": {
-			"types": "./dist-types/vendors/analytics/ahrefs-analytics.d.ts",
-			"import": "./dist/vendors/analytics/ahrefs-analytics.js",
-			"default": "./dist/vendors/analytics/ahrefs-analytics.js"
-		},
-		"./amplitude": {
-			"types": "./dist-types/vendors/analytics/amplitude.d.ts",
-			"import": "./dist/vendors/analytics/amplitude.js",
-			"default": "./dist/vendors/analytics/amplitude.js"
-		},
-		"./cloudflare-web-analytics": {
-			"types": "./dist-types/vendors/analytics/cloudflare-web-analytics.d.ts",
-			"import": "./dist/vendors/analytics/cloudflare-web-analytics.js",
-			"default": "./dist/vendors/analytics/cloudflare-web-analytics.js"
-		},
-		"./clearbit": {
-			"types": "./dist-types/vendors/analytics/clearbit.d.ts",
-			"import": "./dist/vendors/analytics/clearbit.js",
-			"default": "./dist/vendors/analytics/clearbit.js"
-		},
-		"./microsoft-clarity": {
-			"types": "./dist-types/vendors/analytics/microsoft-clarity.d.ts",
-			"import": "./dist/vendors/analytics/microsoft-clarity.js",
-			"default": "./dist/vendors/analytics/microsoft-clarity.js"
-		},
-		"./databuddy": {
-			"types": "./dist-types/vendors/analytics/databuddy.d.ts",
-			"import": "./dist/vendors/analytics/databuddy.js",
-			"default": "./dist/vendors/analytics/databuddy.js"
-		},
-		"./fathom-analytics": {
-			"types": "./dist-types/vendors/analytics/fathom-analytics.d.ts",
-			"import": "./dist/vendors/analytics/fathom-analytics.js",
-			"default": "./dist/vendors/analytics/fathom-analytics.js"
-		},
-		"./heap": {
-			"types": "./dist-types/vendors/analytics/heap.d.ts",
-			"import": "./dist/vendors/analytics/heap.js",
-			"default": "./dist/vendors/analytics/heap.js"
-		},
-		"./hotjar": {
-			"types": "./dist-types/vendors/analytics/hotjar.d.ts",
-			"import": "./dist/vendors/analytics/hotjar.js",
-			"default": "./dist/vendors/analytics/hotjar.js"
-		},
-		"./hightouch": {
-			"types": "./dist-types/vendors/analytics/hightouch.d.ts",
-			"import": "./dist/vendors/analytics/hightouch.js",
-			"default": "./dist/vendors/analytics/hightouch.js"
-		},
-		"./rudderstack": {
-			"types": "./dist-types/vendors/analytics/rudderstack.d.ts",
-			"import": "./dist/vendors/analytics/rudderstack.js",
-			"default": "./dist/vendors/analytics/rudderstack.js"
-		},
-		"./logrocket": {
-			"types": "./dist-types/vendors/analytics/logrocket.d.ts",
-			"import": "./dist/vendors/analytics/logrocket.js",
-			"default": "./dist/vendors/analytics/logrocket.js"
-		},
-		"./google-tag": {
-			"types": "./dist-types/vendors/analytics/google-tag.d.ts",
-			"import": "./dist/vendors/analytics/google-tag.js",
-			"default": "./dist/vendors/analytics/google-tag.js"
-		},
-		"./matomo-analytics": {
-			"types": "./dist-types/vendors/analytics/matomo-analytics.d.ts",
-			"import": "./dist/vendors/analytics/matomo-analytics.js",
-			"default": "./dist/vendors/analytics/matomo-analytics.js"
-		},
-		"./mixpanel-analytics": {
-			"types": "./dist-types/vendors/analytics/mixpanel-analytics.d.ts",
-			"import": "./dist/vendors/analytics/mixpanel-analytics.js",
-			"default": "./dist/vendors/analytics/mixpanel-analytics.js"
-		},
-		"./one-dollar-stats": {
-			"types": "./dist-types/vendors/analytics/one-dollar-stats.d.ts",
-			"import": "./dist/vendors/analytics/one-dollar-stats.js",
-			"default": "./dist/vendors/analytics/one-dollar-stats.js"
-		},
-		"./pirsch": {
-			"types": "./dist-types/vendors/analytics/pirsch.d.ts",
-			"import": "./dist/vendors/analytics/pirsch.js",
-			"default": "./dist/vendors/analytics/pirsch.js"
-		},
-		"./plausible-analytics": {
-			"types": "./dist-types/vendors/analytics/plausible-analytics.d.ts",
-			"import": "./dist/vendors/analytics/plausible-analytics.js",
-			"default": "./dist/vendors/analytics/plausible-analytics.js"
-		},
-		"./posthog": {
-			"types": "./dist-types/vendors/analytics/posthog.d.ts",
-			"import": "./dist/vendors/analytics/posthog.js",
-			"default": "./dist/vendors/analytics/posthog.js"
-		},
-		"./promptwatch": {
-			"types": "./dist-types/vendors/analytics/promptwatch.d.ts",
-			"import": "./dist/vendors/analytics/promptwatch.js",
-			"default": "./dist/vendors/analytics/promptwatch.js"
-		},
-		"./segment": {
-			"types": "./dist-types/vendors/analytics/segment.d.ts",
-			"import": "./dist/vendors/analytics/segment.js",
-			"default": "./dist/vendors/analytics/segment.js"
-		},
-		"./rybbit-analytics": {
-			"types": "./dist-types/vendors/analytics/rybbit-analytics.d.ts",
-			"import": "./dist/vendors/analytics/rybbit-analytics.js",
-			"default": "./dist/vendors/analytics/rybbit-analytics.js"
-		},
-		"./umami-analytics": {
-			"types": "./dist-types/vendors/analytics/umami-analytics.d.ts",
-			"import": "./dist/vendors/analytics/umami-analytics.js",
-			"default": "./dist/vendors/analytics/umami-analytics.js"
-		},
-		"./vercel-analytics": {
-			"types": "./dist-types/vendors/analytics/vercel-analytics.d.ts",
-			"import": "./dist/vendors/analytics/vercel-analytics.js",
-			"default": "./dist/vendors/analytics/vercel-analytics.js"
-		},
-		"./crisp": {
-			"types": "./dist-types/vendors/functional/crisp.d.ts",
-			"import": "./dist/vendors/functional/crisp.js",
-			"default": "./dist/vendors/functional/crisp.js"
-		},
-		"./front-chat": {
-			"types": "./dist-types/vendors/functional/front-chat.d.ts",
-			"import": "./dist/vendors/functional/front-chat.js",
-			"default": "./dist/vendors/functional/front-chat.js"
-		},
-		"./intercom": {
-			"types": "./dist-types/vendors/functional/intercom.d.ts",
-			"import": "./dist/vendors/functional/intercom.js",
-			"default": "./dist/vendors/functional/intercom.js"
-		},
-		"./cloudflare-zaraz": {
-			"types": "./dist-types/vendors/tag-managers/cloudflare-zaraz.d.ts",
-			"import": "./dist/vendors/tag-managers/cloudflare-zaraz.js",
-			"default": "./dist/vendors/tag-managers/cloudflare-zaraz.js"
-		},
-		"./google-tag-manager": {
-			"types": "./dist-types/vendors/tag-managers/google-tag-manager.d.ts",
-			"import": "./dist/vendors/tag-managers/google-tag-manager.js",
-			"default": "./dist/vendors/tag-managers/google-tag-manager.js"
-		},
-		"./linkedin-insights": {
-			"types": "./dist-types/vendors/ads-and-pixels/linkedin-insights.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/linkedin-insights.js",
-			"default": "./dist/vendors/ads-and-pixels/linkedin-insights.js"
-		},
-		"./meta-pixel": {
-			"types": "./dist-types/vendors/ads-and-pixels/meta-pixel.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/meta-pixel.js",
-			"default": "./dist/vendors/ads-and-pixels/meta-pixel.js"
-		},
-		"./openai-pixel": {
-			"types": "./dist-types/vendors/ads-and-pixels/openai-pixel.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/openai-pixel.js",
-			"default": "./dist/vendors/ads-and-pixels/openai-pixel.js"
-		},
-		"./pinterest-tag": {
-			"types": "./dist-types/vendors/ads-and-pixels/pinterest-tag.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/pinterest-tag.js",
-			"default": "./dist/vendors/ads-and-pixels/pinterest-tag.js"
-		},
-		"./reddit-pixel": {
-			"types": "./dist-types/vendors/ads-and-pixels/reddit-pixel.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/reddit-pixel.js",
-			"default": "./dist/vendors/ads-and-pixels/reddit-pixel.js"
-		},
-		"./microsoft-uet": {
-			"types": "./dist-types/vendors/ads-and-pixels/microsoft-uet.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/microsoft-uet.js",
-			"default": "./dist/vendors/ads-and-pixels/microsoft-uet.js"
-		},
-		"./snapchat-pixel": {
-			"types": "./dist-types/vendors/ads-and-pixels/snapchat-pixel.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/snapchat-pixel.js",
-			"default": "./dist/vendors/ads-and-pixels/snapchat-pixel.js"
-		},
-		"./tiktok-pixel": {
-			"types": "./dist-types/vendors/ads-and-pixels/tiktok-pixel.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/tiktok-pixel.js",
-			"default": "./dist/vendors/ads-and-pixels/tiktok-pixel.js"
-		},
-		"./x-pixel": {
-			"types": "./dist-types/vendors/ads-and-pixels/x-pixel.d.ts",
-			"import": "./dist/vendors/ads-and-pixels/x-pixel.js",
-			"default": "./dist/vendors/ads-and-pixels/x-pixel.js"
-		},
-		"./registry": {
-			"types": "./dist-types/registry.d.ts",
-			"import": "./dist/registry.js",
-			"default": "./dist/registry.js"
-		},
 		"./*": {
 			"types": "./dist-types/*.d.ts",
 			"import": "./dist/*.js",
 			"default": "./dist/*.js"
-		},
-		"./events": {
-			"types": "./dist-types/events.d.ts",
-			"import": "./dist/events.js",
-			"default": "./dist/events.js"
 		}
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"scripts": {
-		"build": "rslib build && bun ../../scripts/normalize-dist-types.mjs",
+		"build": "bun build-compat.ts",
 		"build:docs": "bun ../../scripts/generate-package-docs.ts @c15t/scripts",
-		"check-types": "tsc --noEmit && tsc -p live-vendors --noEmit",
-		"dev": "sh -c 'rslib build --no-dts --no-clean && rslib build --watch --no-dts --no-clean'",
+		"check-types": "tsc --noEmit",
 		"fmt": "bun oxfmt .",
-		"lint": "bun oxlint ./src ./live-vendors",
+		"lint": "bun oxlint build-compat.ts __tests__",
 		"prepack": "bun run build:docs",
-		"test": "vitest run",
-		"test:live-vendors": "bun --tsconfig-override live-vendors/tsconfig.json live-vendors/runner.ts",
-		"test:watch": "vitest"
+		"test": "vitest run"
 	},
 	"dependencies": {
-		"@c15t/core": "3.0.0-alpha.3"
+		"@c15t/integrations": "3.0.0-alpha.3"
 	},
 	"devDependencies": {
 		"@c15t/typescript-config": "0.0.1",
-		"@c15t/vitest-config": "1.0.0",
-		"playwright": "1.58.2",
 		"typescript": "7.0.2"
-	},
-	"browserslist": [
-		">0.2%",
-		"not dead",
-		"not op_mini all"
-	]
+	}
 }

package/dist-types/__tests__/helpers.d.ts

@@ -1,141 +0,0 @@
-import type { ConsentState, Script, ScriptCallbackInfo } from '@c15t/core';
-import type { BuiltInScriptIntegrationKey } from '../registry.js';
-/**
- * Typed view of `globalThis` used by script helper tests.
- *
- * Additional string-keyed properties model browser and vendor globals created
- * during setup and individual test cases.
- */
-export type TestGlobal = typeof globalThis & Record<string, unknown>;
-/**
- * Snapshot of the script fields asserted by helper tests.
- */
-export interface HelperScriptSnapshot {
-    /** Unique script identifier generated by the helper under test. */
-    id: string;
-    /** Consent category associated with the script integration. */
-    category: unknown;
-    /** Whether the script should load even before optional consent is granted. */
-    alwaysLoad?: boolean;
-    /** Whether the script stays loaded after consent for its category is revoked. */
-    persistAfterConsentRevoked?: boolean;
-    /** Remote script URL emitted by the helper, when applicable. */
-    src?: string;
-}
-/**
- * Expected integration metadata and script attributes for a helper assertion.
- */
-export interface ExpectedScriptSnapshot {
-    /** Expected `alwaysLoad` flag from the generated helper script. */
-    alwaysLoad: boolean | undefined;
-    /** Expected consent-revocation persistence flag from the generated script. */
-    persistAfterConsentRevoked: boolean | undefined;
-    /** Expected remote script URL from the generated helper script. */
-    src: string | undefined;
-}
-/**
- * Consent state with only required storage enabled.
- *
- * `necessary` keeps essential storage on, `functionality` covers site
- * preferences, `measurement` controls analytics, `marketing` controls
- * advertising-related storage, and `experience` controls personalization.
- */
-export declare const deniedConsentState: ConsentState;
-/**
- * Consent state with required and measurement storage enabled.
- *
- * `necessary` keeps essential storage on, `functionality` covers site
- * preferences, `measurement` controls analytics, `marketing` controls
- * advertising-related storage, and `experience` controls personalization.
- */
-export declare const grantedMeasurementConsentState: ConsentState;
-/**
- * Required callback fields for creating a script lifecycle payload in tests.
- */
-export type CallbackInfoOverrides = Partial<ScriptCallbackInfo> & Pick<ScriptCallbackInfo, 'id'>;
-/**
- * Creates a fully typed callback payload for script lifecycle tests.
- *
- * Defaults model a denied-consent callback for the same DOM element ID as the
- * script ID, while allowing individual tests to override the relevant fields.
- */
-export declare const createCallbackInfo: (overrides: CallbackInfoOverrides) => ScriptCallbackInfo;
-export type LifecycleCallbackOverrides = Partial<Omit<ScriptCallbackInfo, 'id'>>;
-export declare const runOnBeforeLoad: (script: Pick<Script, 'id' | 'onBeforeLoad'>, overrides?: LifecycleCallbackOverrides) => void;
-/**
- * Returns a mutable test-friendly reference to the global object.
- *
- * @returns The current global object cast to `TestGlobal`.
- *
- * @example
- * ```ts
- * const globalRef = getTestGlobal();
- * globalRef.dataLayer = [];
- * ```
- */
-export declare const getTestGlobal: () => TestGlobal;
-/**
- * Registers browser-like setup and teardown hooks for script helper tests.
- *
- * Before each test, this installs mocked `window` and `document` globals.
- * After each test, it unstubs globals and removes vendor-specific globals left
- * behind by script execution.
- *
- * @returns Nothing.
- *
- * @example
- * ```ts
- * describe('googleTagManager', () => {
- * 	setupScriptHelperTest();
- * });
- * ```
- */
-export declare const setupScriptHelperTest: () => void;
-/**
- * Asserts that a helper-generated script matches registry metadata and
- * expected script fields.
- *
- * @param key - Built-in integration key used to find the registry entry.
- * @param script - Snapshot of the helper-generated script under test.
- * @param expected - Expected script metadata and output for the assertion.
- * @returns Nothing.
- *
- * @remarks
- * If `key` does not match any built-in integration, the assertion fails before
- * the non-null access is used.
- *
- * @example
- * ```ts
- * expectScriptMatchesIntegration(
- * 	'googleTagManager',
- * 	googleTagManager({ id: 'GTM-123' }),
- * 	{
- * 		alwaysLoad: true,
- * 		persistAfterConsentRevoked: undefined,
- * 		src: 'https://www.googletagmanager.com/gtm.js?id=GTM-123',
- * 	}
- * );
- * ```
- */
-export declare const expectScriptMatchesIntegration: (key: BuiltInScriptIntegrationKey, script: HelperScriptSnapshot, expected: ExpectedScriptSnapshot) => void;
-/**
- * Converts an array-like value into a plain array.
- *
- * @param value - Array-like input such as `arguments`, a `NodeList`, or a
- * vendor queue entry.
- * @returns A new array containing the indexed values from `value`.
- *
- * @remarks
- * Passing `null` or `undefined` throws because `slice` requires an object-like
- * value.
- *
- * @example
- * ```ts
- * function collectArgs(...args: unknown[]) {
- * 	return toArgumentsArray(args);
- * }
- * ```
- */
-export declare const toArgumentsArray: (value: unknown) => unknown[];
-export declare const expectGoogleConsentDefault: (entry: unknown) => void;
-export declare const expectStubCommandQueue: (stub: unknown, queueKey: string, commands: unknown[][]) => void;

package/docs/frameworks/javascript/script-loader.md

@@ -1,100 +0,0 @@
----
-title: JavaScript script loading
-description: Attach a script loader to the consent kernel and dispose it with
-  the application.
-group: frameworks
----
-
-## Attach the loader before initialization
-
-Install `@c15t/scripts` alongside `c15t`. This browser example adds a
-marketing integration to a hosted kernel:
-
-```ts
-import { createConsentKernel, createHostedTransport } from 'c15t';
-import { createPersistence } from 'c15t/modules/persistence';
-import { createScriptLoader } from 'c15t/modules/script-loader';
-import { metaPixel } from '@c15t/scripts/meta-pixel';
-
-const kernel = createConsentKernel({
-  transport: createHostedTransport({ backendURL: 'https://your-project.inth.app' }),
-});
-const persistence = createPersistence({ kernel });
-const loader = createScriptLoader({ kernel, scripts: [metaPixel({ pixelId: '123456789012345' })] });
-await kernel.commands.init();
-
-function dispose() {
-  loader.dispose();
-  persistence.dispose();
-  kernel.dispose();
-}
-```
-
-Replace the URL and pixel ID. Call `dispose()` when your application tears down.
-The headless kernel does not render a banner; connect a policy-aware UI before
-shipping this integration. A framework provider already manages these modules,
-so do not attach a second loader to a provider-owned kernel.
-
-## Keep one owner per vendor
-
-Use stable script IDs and remove the vendor's original snippet. Ordinary scripts
-wait for effective permission. Helpers with `alwaysLoad` instead load and signal
-permission through the vendor API. Read the individual integration guide before
-assuming all helpers have the same network behavior.
-
-The loader exposes `updateScripts`, `getLoadedScriptIds` and `dispose`.
-Unloading an element cannot reverse requests or code that already ran. Test
-revocation and vendor cleanup with [verification](../../guides/verify-consent.md).
-
-## Dispose integration resources
-
-Ordinary scripts keep their mounted resource when `updateScripts` receives a
-fresh object with the same ID and unchanged element configuration. New callback
-functions alone do not reload the vendor or send a temporary denial. Changing
-the source, inline code or element attributes starts a new loading lifecycle.
-Consent conditions are reevaluated on every configuration update. Pending
-load and error events use the latest registered callbacks and consent state.
-Setting `persistAfterConsentRevoked` to `false` removes an owned retained element
-when the script no longer has consent.
-
-Custom script configurations can use `onDispose(info)` to release event
-listeners or other resources. Adding this hook opts the configuration into an
-object-owned lifecycle: replacing the object disposes its resources and starts
-again, even with the same ID. Keep these objects stable across framework
-rerenders. The loader also calls the hook when the configuration is removed or
-the loader is disposed, including configurations that never loaded.
-`info.element` contains the last loaded or retained element when available,
-even when configuration removal has already detached it.
-
-Duplicate references receive one cleanup per registration. Re-registering a
-removed object starts a new lifecycle. Updates requested from lifecycle
-callbacks run after the current pass; if several are requested, the latest
-configuration wins. Disposal stops further reconciliation. A callback feedback
-loop exceeding 100 consecutive passes disposes the loader and reports an
-`error` debug event. Avoid callbacks that keep changing consent or replacing
-their own configuration.
-
-`onBeforeLoad` prepares a loading attempt. If a callback changes consent or
-replaces configurations, the loader cancels that attempt before loading and
-reevaluates the latest state. A still-eligible script can retry preparation
-with a new element and updated consent. Make `onBeforeLoad` safe to repeat;
-use `onLoad` for initialization that requires a completed load. This also
-applies to callback-only scripts, whose `onLoad` is skipped when preparation
-invalidates the current pass.
-
-Consent revocation alone does not call `onDispose`. Use `onConsentChange` for
-vendor opt-out commands. Cleanup errors are reported through the loader's debug
-events and do not prevent other configurations from being cleaned up.
-
-## Clear stored tracking data
-
-Script gating does not remove cookies or Web Storage entries that a script
-already wrote. Configure [clear on revocation](../../integrations/clear-on-revocation.md)
-on your runtime, or attach its module to your existing kernel, to remove
-declared data when its category is denied.
-
-## Shared lifecycle controls
-
-See [shared consent controls](../../guides/shared-consent-controls.md) for external CMPs,
-preference delegation, withdrawal reloads, and application events. These controls
-use the same core runtime across frameworks.