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

package/dist-types/types.d.ts

@@ -1,314 +1,2 @@
-import type { AllConsentNames, HasCondition } from '@c15t/core';
-export declare const VENDOR_MANIFEST_KIND = "c15t.vendor-manifest";
-export declare const VENDOR_MANIFEST_SCHEMA_VERSION = 1;
-export declare const vendorManifestContract: {
-    readonly kind: "c15t.vendor-manifest";
-    readonly schemaVersion: 1;
-};
-export declare const RUNTIME_VALUE_KIND = "c15t.runtime-value";
-export interface RuntimeValue {
-    kind: typeof RUNTIME_VALUE_KIND;
-    value: 'date' | 'timestamp';
-}
-export declare const runtimeDateValue: {
-    readonly kind: "c15t.runtime-value";
-    readonly value: 'date';
-};
-export declare const runtimeTimestampValue: {
-    readonly kind: "c15t.runtime-value";
-    readonly value: 'timestamp';
-};
-export interface ManifestContract {
-    kind: typeof VENDOR_MANIFEST_KIND;
-    schemaVersion: typeof VENDOR_MANIFEST_SCHEMA_VERSION;
-}
-type ManifestInterpolationToken = `{{${string}}}`;
-export type ManifestCategoryCondition = HasCondition<AllConsentNames | ManifestInterpolationToken>;
-export interface LoadScriptStep {
-    type: 'loadScript';
-    src: string;
-    async?: boolean;
-    defer?: boolean;
-    attributes?: Record<string, string>;
-}
-export interface SetGlobalStep {
-    type: 'setGlobal';
-    /** Global variable name (e.g. 'dataLayer') */
-    name: string;
-    /** Value to assign. Arrays and objects are recursively cloned on execution. */
-    value: unknown;
-    /**
-     * Only set the global if it's not already defined.
-     * Mirrors the common `window.x = window.x || value` pattern.
-     * @default true
-     */
-    ifUndefined?: boolean;
-}
-export interface DefineQueueFunctionStep {
-    type: 'defineQueueFunction';
-    /** Global function name (e.g. 'gtag') */
-    name: string;
-    /** Global array name that receives queued calls (e.g. 'dataLayer') */
-    queue: string;
-    /**
-     * Only define the function if it is not already present.
-     * @default true
-     */
-    ifUndefined?: boolean;
-    /**
-     * Whether queued calls should store the `arguments` object or a copied array.
-     * @default 'arguments'
-     */
-    pushStyle?: 'arguments' | 'array';
-}
-export interface DefineStubFunctionStep {
-    type: 'defineStubFunction';
-    /** Global function name (e.g. 'fbq', 'twq', 'lintrk') */
-    name: string;
-    /**
-     * Queue storage location:
-     * - `global` pushes into another global array (e.g. `dataLayer`)
-     * - `property` pushes into a property on the stub function itself (e.g. `fbq.queue`)
-     */
-    queue: {
-        global: string;
-        property?: never;
-    } | {
-        global?: never;
-        property: string;
-    };
-    /**
-     * If present, calls `stub[dispatchProperty](...args)` when available instead of queueing.
-     * Mirrors vendor APIs like Meta Pixel's `callMethod`.
-     */
-    dispatchProperty?: string;
-    /**
-     * How queued values should be stored.
-     * - `'arguments'` => push the `arguments` object
-     * - `'array'` => push a copied array of arguments
-     */
-    queueFormat?: 'arguments' | 'array';
-    /** Additional globals that should reference the same stub */
-    aliases?: string[];
-    /** Properties on the stub that should reference the stub itself (e.g. `push`) */
-    selfReferences?: string[];
-    /** Additional scalar/object properties assigned to the stub */
-    properties?: Record<string, unknown>;
-    /** Only define the stub if not already present. */
-    ifUndefined?: boolean;
-}
-export interface CallGlobalStep {
-    type: 'callGlobal';
-    /** Global object name (e.g. 'posthog', 'fbq') */
-    global: string;
-    /** Method to call on the global. If omitted, the global itself is called as a function. */
-    method?: string;
-    /** Arguments to pass */
-    args?: unknown[];
-}
-export interface PushToQueueStep {
-    type: 'pushToQueue';
-    /** Global array name that receives queued values (e.g. 'dataLayer') */
-    queue: string;
-    /** Value to push onto the queue */
-    value: unknown;
-}
-export interface SetGlobalPathStep {
-    type: 'setGlobalPath';
-    /** Path segments under window (e.g. ['databuddy', 'options', 'disabled']) */
-    path: string[];
-    /** Value to assign at the target path */
-    value: unknown;
-    /** Only assign while the root global is still a snippet queue array. */
-    ifGlobalIsQueue?: boolean;
-}
-export interface DefineQueueMethodsStep {
-    type: 'defineQueueMethods';
-    /** Global array/object name that owns the queue methods */
-    target: string;
-    /** Method names to attach */
-    methods: string[];
-    /** Optional queue location. Defaults to the target itself. */
-    queue?: {
-        global: string;
-        property?: never;
-    } | {
-        global?: never;
-        property: string;
-    };
-    /**
-     * Format used for each queued method call.
-     *
-     * - `tuple` pushes `[methodName, ...args]`, matching classic array queues.
-     * - `methodCall` pushes `{ name, args, resolve }` and returns a `Promise`,
-     *   matching SDK loaders that replay named calls and resolve the original
-     *   pre-load promise after the real method runs.
-     * - `wrappedMethodCall` queues like `methodCall` but returns
-     *   `{ promise }`, matching Amplitude's snippet contract where queued
-     *   proxy calls expose the pending promise on a `promise` property.
-     * - `voidMethodCall` queues like `methodCall` but returns nothing,
-     *   matching snippet methods the vendor treats as synchronous.
-     * - `callback` pushes `{ name, fn }`, where `fn` replays the captured call
-     *   against the current global target, matching loaders that own a
-     *   ready-callback queue.
-     *
-     * @default 'tuple'
-     */
-    queueFormat?: 'tuple' | 'methodCall' | 'wrappedMethodCall' | 'voidMethodCall' | 'callback';
-}
-export interface DefineQueueClassStep {
-    type: 'defineQueueClass';
-    /** Global object that receives the queued helper class. */
-    target: string;
-    /** Constructor property name to define on the target object. */
-    name: string;
-    /**
-     * Instance property that stores queued helper method calls.
-     *
-     * @default '_q'
-     */
-    queueProperty?: string;
-    /** Helper instance method names to attach to the constructor prototype. */
-    methods: string[];
-}
-export type GlobalMethodBehavior = {
-    name: string;
-    behavior: 'noop';
-} | {
-    name: string;
-    behavior: 'return';
-    value: unknown;
-};
-export interface DefineGlobalMethodsStep {
-    type: 'defineGlobalMethods';
-    /** Global object name to receive the methods */
-    target: string;
-    methods: GlobalMethodBehavior[];
-    /** Only define methods while the target is still a snippet queue array. */
-    ifGlobalIsQueue?: boolean;
-}
-export interface ConstructGlobalStep {
-    type: 'constructGlobal';
-    /** Global constructor name (e.g. `UET`) */
-    constructor: string;
-    /** Global name to assign the constructed instance to */
-    assignTo: string;
-    /** Constructor args */
-    args?: unknown[];
-    /**
-     * Copies the current `window[assignTo]` value into the first constructor arg object
-     * under this property before constructing.
-     */
-    copyAssignedValueToArgProperty?: string;
-}
-export type ManifestStep = LoadScriptStep | SetGlobalStep | DefineQueueFunctionStep | DefineStubFunctionStep | CallGlobalStep | PushToQueueStep | SetGlobalPathStep | DefineQueueMethodsStep | DefineQueueClassStep | DefineGlobalMethodsStep | ConstructGlobalStep;
-/**
- * Consent signal type determines how consent state is communicated to the vendor.
- *
- * - `'gtag'` — Google Consent Mode pattern: calls `gtag('consent', 'default'|'update', state)`
- * - `'rudderstack'` — RudderStack consent-management pattern: calls
- *   `rudderanalytics.consent({ consentManagement: { enabled, provider: 'custom',
- *   allowedConsentIds, deniedConsentIds } })` with the mapping's consent IDs
- *   partitioned by the current c15t consent state
- */
-export type ConsentSignalType = 'gtag' | 'rudderstack';
-/**
- * A declarative definition of a vendor integration.
- *
- * Manifests are the source definition that the scripts engine compiles into a
- * serializable resolved manifest and then converts into a runtime `Script`.
- */
-export interface VendorManifest extends ManifestContract {
-    /** Manifest contract identifier. */
-    kind: typeof VENDOR_MANIFEST_KIND;
-    /** Manifest schema version. */
-    schemaVersion: typeof VENDOR_MANIFEST_SCHEMA_VERSION;
-    /** Unique vendor identifier (used as Script.id) */
-    vendor: string;
-    /** Consent category or condition required to load this vendor */
-    category: ManifestCategoryCondition;
-    /** Load regardless of consent state (vendor manages its own consent internally) */
-    alwaysLoad?: boolean | string;
-    /** Keep script in DOM after consent revocation (vendor has a consent API) */
-    persistAfterConsentRevoked?: boolean | string;
-    /**
-     * Steps that must execute before default consent signaling.
-     *
-     * This is primarily used for integrations such as Google tags where a stub
-     * global must exist before calling the vendor's consent API.
-     */
-    bootstrap?: ManifestStep[];
-    /**
-     * Steps to execute when installing the vendor.
-     *
-     * The resolver extracts the script source from these steps:
-     * - If a `loadScript` step exists, its `src` becomes `Script.src`
-     * - All non-`loadScript` steps run as part of `onBeforeLoad`
-     */
-    install: ManifestStep[];
-    /** Steps to execute after the main script loads */
-    afterLoad?: ManifestStep[];
-    /** Steps to execute before load when the vendor has consent */
-    onBeforeLoadGranted?: ManifestStep[];
-    /** Steps to execute before load when the vendor does not have consent */
-    onBeforeLoadDenied?: ManifestStep[];
-    /** Steps to execute after load when the vendor has consent */
-    onLoadGranted?: ManifestStep[];
-    /** Steps to execute after load when the vendor does not have consent */
-    onLoadDenied?: ManifestStep[];
-    /** Steps to run on any consent state change */
-    onConsentChange?: ManifestStep[];
-    /** Steps to run when this vendor's category consent is granted */
-    onConsentGranted?: ManifestStep[];
-    /** Steps to run when this vendor's category consent is denied */
-    onConsentDenied?: ManifestStep[];
-    /**
-     * Maps c15t consent categories to vendor-specific consent type names.
-     *
-     * Used with `consentSignal` to translate c15t consent state into
-     * the vendor's consent API format.
-     *
-     * @example
-     * ```ts
-     * // Google Consent Mode v2 mapping
-     * consentMapping: {
-     *   marketing: ['ad_storage', 'ad_user_data', 'ad_personalization'],
-     *   measurement: ['analytics_storage'],
-     *   functionality: ['functionality_storage'],
-     *   necessary: ['security_storage'],
-     *   experience: ['personalization_storage'],
-     * }
-     * ```
-     */
-    consentMapping?: Record<string, string[]>;
-    /** How to signal consent state to the vendor */
-    consentSignal?: ConsentSignalType;
-    /** Target global for consent signaling (defaults based on signal type) */
-    consentSignalTarget?: string;
-}
-/**
- * Internal transport-ready manifest shape produced by the compile phase.
- *
- * Contains only serializable data and no runtime callbacks.
- */
-export interface ResolvedManifest extends ManifestContract {
-    vendor: string;
-    category: HasCondition<AllConsentNames>;
-    alwaysLoad?: boolean;
-    persistAfterConsentRevoked?: boolean;
-    bootstrapSteps: ManifestStep[];
-    setupSteps: ManifestStep[];
-    loadScript?: LoadScriptStep;
-    afterLoadSteps: ManifestStep[];
-    onBeforeLoadGrantedSteps: ManifestStep[];
-    onBeforeLoadDeniedSteps: ManifestStep[];
-    onLoadGrantedSteps: ManifestStep[];
-    onLoadDeniedSteps: ManifestStep[];
-    onConsentChangeSteps: ManifestStep[];
-    onConsentGrantedSteps: ManifestStep[];
-    onConsentDeniedSteps: ManifestStep[];
-    consentMapping?: Record<string, string[]>;
-    consentSignal?: ConsentSignalType;
-    consentSignalTarget?: string;
-}
-export {};
+/** @deprecated Use @c15t/integrations/types. Compatibility ends in v4. */
+export * from '@c15t/integrations/types';

package/dist-types/umami-analytics.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Use @c15t/integrations/umami-analytics. Compatibility ends in v4. */
+export * from '@c15t/integrations/umami-analytics';

package/dist-types/vendors/_shared/attributes.d.ts

@@ -1,35 +1,2 @@
-/**
- * Converts an optional boolean into a string suitable for a script `data-*`
- * attribute.
- *
- * @param value - Optional boolean value from a vendor option.
- * @returns `'true'` or `'false'` when a boolean is provided, otherwise
- * `undefined` so the manifest compiler can omit the attribute.
- *
- * @example
- * ```ts
- * booleanDataAttribute(true); // 'true'
- * booleanDataAttribute(false); // 'false'
- * booleanDataAttribute(undefined); // undefined
- * ```
- */
-export declare const booleanDataAttribute: (value: boolean | undefined) => string | undefined;
-/**
- * Converts a string or string list into a script `data-*` attribute value.
- *
- * Arrays are JSON-serialized so values containing commas can be round-tripped
- * with `JSON.parse` by consumers that read the attribute.
- *
- * @param value - Optional string value or string list from a vendor option.
- * @returns The original string, a JSON-serialized array, or `undefined` so the
- * manifest compiler can omit the attribute.
- *
- * @example
- * ```ts
- * listDataAttribute('example.com'); // 'example.com'
- * listDataAttribute(['a.com', 'b.com']); // '["a.com","b.com"]'
- * listDataAttribute([]); // undefined
- * listDataAttribute(undefined); // undefined
- * ```
- */
-export declare const listDataAttribute: (value: string[] | string | undefined) => string | undefined;
+/** @deprecated Use @c15t/integrations/vendors/_shared/attributes. Compatibility ends in v4. */
+export * from '@c15t/integrations/vendors/_shared/attributes';

package/dist-types/vendors/_shared/google-consent.d.ts

@@ -1,47 +1,2 @@
-/**
- * Default c15t consent category mapping for Google Consent Mode v2.
- *
- * @remarks
- * Shared by direct gtag.js and Google Tag Manager integrations so both emit the
- * same Google storage consent defaults unless a caller provides an override.
- *
- * @example
- * ```ts
- * const manifest = {
- * 	consentMapping: GOOGLE_CONSENT_MODE_V2_DEFAULT_MAPPING,
- * };
- * ```
- */
-export declare const GOOGLE_CONSENT_MODE_V2_DEFAULT_MAPPING: Record<string, string[]>;
-/**
- * Applies an optional Google consent mapping override to a manifest.
- *
- * @param manifest - Vendor manifest that already contains the default consent
- * mapping.
- * @param consentMapping - Optional caller-provided mapping from c15t consent
- * categories to Google consent types.
- * @returns The original manifest when no override is provided, or a shallow
- * copy with the override mapping when one is provided.
- *
- * @example
- * ```ts
- * const customMapping: Record<string, string[]> = {
- * 	marketing: ['ad_storage'],
- * };
- * const mapped = withOptionalConsentMapping<TManifest>(
- * 	manifest,
- * 	customMapping
- * );
- * ```
- *
- * @example
- * ```ts
- * const unchanged = withOptionalConsentMapping<TManifest>(
- * 	manifest,
- * 	undefined
- * );
- * ```
- */
-export declare const withOptionalConsentMapping: <TManifest extends {
-    consentMapping?: Record<string, string[]>;
-}>(manifest: TManifest, consentMapping: Record<string, string[]> | undefined) => TManifest;
+/** @deprecated Use @c15t/integrations/vendors/_shared/google-consent. Compatibility ends in v4. */
+export * from '@c15t/integrations/vendors/_shared/google-consent';

package/dist-types/vendors/_shared/install-builders.d.ts

@@ -1,30 +1,2 @@
-import type { VendorManifest } from '../../types.js';
-/**
- * Optional tracking call inserted between the vendor init call and script load.
- */
-interface QueuePixelInstallStep {
-    /** Arguments passed to the vendor queue function. */
-    args: unknown[];
-}
-/**
- * Options for building the common pixel install sequence.
- */
-export interface BuildQueuePixelInstallOptions {
-    /** Global queue function to call, for example `rdt` or `snaptr`. */
-    global: string;
-    /** Arguments for the required initialization call. */
-    initArgs: unknown[];
-    /** Optional tracking command queued immediately after initialization. */
-    trackStep?: QueuePixelInstallStep;
-    /** Manifest interpolation token used for the final loader script URL. */
-    scriptPlaceholder?: string;
-}
-/**
- * Builds the common queue-pixel install sequence used by advertising pixels.
- *
- * @param options - Queue pixel install options.
- * @returns Manifest install steps containing the required init call, an
- * optional tracking call, and an async `loadScript` step.
- */
-export declare const buildQueuePixelInstall: ({ global, initArgs, trackStep, scriptPlaceholder, }: BuildQueuePixelInstallOptions) => VendorManifest['install'];
-export {};
+/** @deprecated Use @c15t/integrations/vendors/_shared/install-builders. Compatibility ends in v4. */
+export * from '@c15t/integrations/vendors/_shared/install-builders';

package/dist-types/vendors/_shared/required-id.d.ts

@@ -0,0 +1,2 @@
+/** @deprecated Use @c15t/integrations/vendors/_shared/required-id. Compatibility ends in v4. */
+export * from '@c15t/integrations/vendors/_shared/required-id';

package/dist-types/vendors/_shared/script-url.d.ts

@@ -1,75 +1,2 @@
-/**
- * Trims an optional string and treats empty or whitespace-only values as
- * missing.
- *
- * @param value - Optional string value, usually a user-provided override.
- * @returns The trimmed string when it contains non-whitespace characters,
- * otherwise `undefined`.
- *
- * @example
- * ```ts
- * trimToUndefined(', https://cdn.example.com  '); // 'https://cdn.example.com'
- * trimToUndefined('   '); // undefined
- * trimToUndefined(undefined); // undefined
- * ```
- */
-export declare const trimToUndefined: (value: string | undefined) => string | undefined;
-/**
- * Resolves a script URL from an optional override and a required fallback.
- *
- * @param override - Explicit script URL supplied by the integration caller.
- * @param fallback - Default vendor script URL.
- * @returns `override` when it is defined, otherwise `fallback`.
- *
- * @remarks
- * This helper intentionally does not trim or validate the override. Use
- * `trimToUndefined` before calling this helper when blank string overrides
- * should fall back to the vendor default.
- *
- * @example
- * ```ts
- * resolveScriptUrl(undefined, 'https://cdn.example.com/default.js');
- * // 'https://cdn.example.com/default.js'
- * ```
- *
- * @example
- * ```ts
- * resolveScriptUrl(
- * 	'https://custom.com/script.js',
- * 	'https://cdn.example.com/default.js'
- * );
- * // 'https://custom.com/script.js'
- * ```
- */
-export declare const resolveScriptUrl: (override: string | undefined, fallback: string) => string;
-/**
- * Removes leading slash characters without using a regular expression.
- *
- * This helper is used on caller-controlled URL fragments, so it intentionally
- * stays linear even for very long repeated slash input.
- */
-export declare const stripLeadingSlashes: (value: string) => string;
-/**
- * Removes trailing slash characters without using a regular expression.
- *
- * This helper is used on caller-controlled URL fragments, so it intentionally
- * stays linear even for very long repeated slash input.
- */
-export declare const stripTrailingSlashes: (value: string) => string;
-/**
- * Joins a base URL and path with exactly one slash between them.
- *
- * @param base - Base URL or origin. Trailing slashes are removed before joining.
- * @param path - Path segment. Leading slashes are removed before joining.
- * @returns A slash-joined URL string.
- *
- * @example
- * ```ts
- * joinUrlPath('https://example.com///', '///script.js');
- * // 'https://example.com/script.js'
- *
- * joinUrlPath('https://example.com', 'script.js');
- * // 'https://example.com/script.js'
- * ```
- */
-export declare const joinUrlPath: (base: string, path: string) => string;
+/** @deprecated Use @c15t/integrations/vendors/_shared/script-url. Compatibility ends in v4. */
+export * from '@c15t/integrations/vendors/_shared/script-url';

package/dist-types/vendors/ads-and-pixels/linkedin-insights.d.ts

@@ -1,92 +1,2 @@
-import type { Script } from '@c15t/core';
-export interface LinkedInInsightsConversionEvent {
-    conversion_id: string | number;
-    [key: string]: unknown;
-}
-interface LinkedInInsightsFunction {
-    (command: 'track', event: LinkedInInsightsConversionEvent): void;
-    (command: string, ...args: unknown[]): void;
-}
-declare global {
-    interface Window {
-        lintrk: LinkedInInsightsFunction & {
-            q?: unknown[][];
-        };
-        _linkedin_partner_id?: string;
-        _linkedin_data_partner_ids?: string[];
-        ORIBILI?: {
-            _DEBUG?: {
-                disableScript?: () => void;
-            };
-        };
-    }
-}
-/**
- * LinkedIn Insight Tag vendor manifest.
- *
- * Sets up the LinkedIn partner ID globals and loads the Insight Tag script
- * via structured startup steps.
- */
-export declare const linkedinInsightsManifest: {
-    readonly kind: "c15t.vendor-manifest";
-    readonly schemaVersion: 1;
-    readonly category: 'marketing';
-    readonly install: [{
-        readonly ifUndefined: false;
-        readonly name: '_linkedin_partner_id';
-        readonly type: 'setGlobal';
-        readonly value: '{{id}}';
-    }, {
-        readonly ifUndefined: true;
-        readonly name: '_linkedin_data_partner_ids';
-        readonly type: 'setGlobal';
-        readonly value: readonly [];
-    }, {
-        readonly queue: '_linkedin_data_partner_ids';
-        readonly type: 'pushToQueue';
-        readonly value: '{{id}}';
-    }, {
-        readonly ifUndefined: true;
-        readonly name: 'lintrk';
-        readonly queue: {
-            readonly property: 'q';
-        };
-        readonly queueFormat: 'array';
-        readonly type: 'defineStubFunction';
-    }, {
-        readonly async: true;
-        readonly src: '{{scriptSrc}}';
-        readonly type: 'loadScript';
-    }];
-    readonly vendor: 'linkedin-insights';
-};
-export interface LinkedInInsightsOptions {
-    /**
-     * Your LinkedIn Insight Tag partner ID.
-     *
-     * LinkedIn shows this in Campaign Manager under Data -> Signals manager ->
-     * Insight Tag.
-     *
-     * @example `123456789012345`
-     */
-    id: string;
-    /** LinkedIn Insight Tag loader URL. */
-    scriptSrc?: string;
-}
-/**
- * LinkedIn Insight Tag script.
- *
- * @param options - The options for the LinkedIn Insight Tag script.
- * @returns The LinkedIn Insight Tag script configuration.
- *
- * @example
- * ```ts
- * const linkedinInsightsScript = linkedinInsights({
- *   id: '123456789012345',
- * });
- * ```
- *
- * @see {@link https://www.linkedin.com/help/lms/answer/a418880} Add the LinkedIn Insight Tag to your website
- */
-export declare const linkedinInsights: ({ id, scriptSrc, }: LinkedInInsightsOptions) => Script;
-export {};
+/** @deprecated Use @c15t/integrations/vendors/ads-and-pixels/linkedin-insights. Compatibility ends in v4. */
+export * from '@c15t/integrations/vendors/ads-and-pixels/linkedin-insights';