@c15t/scripts 2.0.1 → 2.2.0-canary-20260727202135

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

@@ -0,0 +1,35 @@
+/**
+ * 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 function 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 function listDataAttribute(value: string[] | string | undefined): string | undefined;

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

@@ -0,0 +1,47 @@
+/**
+ * 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 function withOptionalConsentMapping<TManifest extends {
+    consentMapping?: Record<string, string[]>;
+}>(manifest: TManifest, consentMapping: Record<string, string[]> | undefined): TManifest;

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

@@ -0,0 +1,30 @@
+import type { VendorManifest } from '../../types';
+/**
+ * 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 function buildQueuePixelInstall({ global, initArgs, trackStep, scriptPlaceholder, }: BuildQueuePixelInstallOptions): VendorManifest['install'];
+export {};

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

@@ -0,0 +1,75 @@
+/**
+ * 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 function 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 function 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 function 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 function 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 function joinUrlPath(base: string, path: string): string;

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

@@ -0,0 +1,92 @@
+import type { Script } from 'c15t';
+export interface LinkedInInsightsConversionEvent {
+    conversion_id: string | number;
+    [key: string]: unknown;
+}
+type 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 vendor: 'linkedin-insights';
+    readonly category: 'marketing';
+    readonly install: [{
+        readonly type: 'setGlobal';
+        readonly name: '_linkedin_partner_id';
+        readonly value: '{{id}}';
+        readonly ifUndefined: false;
+    }, {
+        readonly type: 'setGlobal';
+        readonly name: '_linkedin_data_partner_ids';
+        readonly value: readonly [];
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'pushToQueue';
+        readonly queue: '_linkedin_data_partner_ids';
+        readonly value: '{{id}}';
+    }, {
+        readonly type: 'defineStubFunction';
+        readonly name: 'lintrk';
+        readonly queue: {
+            readonly property: 'q';
+        };
+        readonly queueFormat: 'array';
+        readonly ifUndefined: true;
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptSrc}}';
+        readonly async: true;
+    }];
+};
+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 function linkedinInsights({ id, scriptSrc, }: LinkedInInsightsOptions): Script;
+export {};

package/dist-types/vendors/ads-and-pixels/meta-pixel.d.ts

@@ -0,0 +1,289 @@
+import type { Script } from 'c15t';
+/**
+ * Represents the `contents` array object property.
+ */
+export interface FbqContent {
+    id: string | number;
+    quantity: number;
+    [key: string]: unknown;
+}
+/**
+ * Base interface for all possible event parameters.
+ * All properties are optional here; specific event types will make them required.
+ */
+export interface FbqBaseEventParams {
+    content_category?: string;
+    content_ids?: (string | number)[];
+    content_name?: string;
+    content_type?: 'product' | 'product_group';
+    contents?: FbqContent[];
+    currency?: string;
+    delivery_category?: 'in_store' | 'curbside' | 'home_delivery';
+    num_items?: number;
+    predicted_ltv?: number;
+    search_string?: string;
+    status?: boolean;
+    value?: number;
+}
+export type FbqCustomParams = Record<string, unknown>;
+type WithCustomParams<TParams> = TParams & FbqCustomParams;
+type AddPaymentInfoParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'contents' | 'currency' | 'value'>>;
+type AddToCartParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'content_type' | 'contents' | 'currency' | 'value'>>;
+type AddToWishlistParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'contents' | 'currency' | 'value'>>;
+type CompleteRegistrationParams = WithCustomParams<Pick<FbqBaseEventParams, 'currency' | 'value' | 'status'>>;
+type InitiateCheckoutParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'contents' | 'currency' | 'num_items' | 'value'>>;
+type LeadParams = WithCustomParams<Pick<FbqBaseEventParams, 'currency' | 'value'>>;
+type PageViewParams = FbqCustomParams;
+type SearchParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'content_type' | 'contents' | 'currency' | 'search_string' | 'value'>>;
+type StartTrialParams = WithCustomParams<Pick<FbqBaseEventParams, 'currency' | 'predicted_ltv' | 'value'>>;
+type SubscribeParams = WithCustomParams<Pick<FbqBaseEventParams, 'currency' | 'predicted_ltv' | 'value'>>;
+type ViewContentParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'content_type' | 'contents' | 'currency' | 'value'>>;
+/**
+ * The 'Purchase' event has required properties.
+ * We use TypeScript's utility types to enforce this.
+ */
+type PurchaseParams = WithCustomParams<Pick<FbqBaseEventParams, 'content_ids' | 'content_type' | 'contents' | 'num_items'> & Required<Pick<FbqBaseEventParams, 'currency' | 'value'>>>;
+/**
+ * Events with no specific properties listed can accept any of the base parameters.
+ */
+type ContactParams = WithCustomParams<FbqBaseEventParams>;
+type CustomizeProductParams = WithCustomParams<FbqBaseEventParams>;
+type DonateParams = WithCustomParams<FbqBaseEventParams>;
+type FindLocationParams = WithCustomParams<FbqBaseEventParams>;
+type ScheduleParams = WithCustomParams<FbqBaseEventParams>;
+type SubmitApplicationParams = WithCustomParams<FbqBaseEventParams>;
+/**
+ * A mapping of Standard Event names to their corresponding parameter types.
+ * This is the core of our type-safety mechanism.
+ */
+export interface StandardEventParams {
+    AddPaymentInfo: AddPaymentInfoParams;
+    AddToCart: AddToCartParams;
+    AddToWishlist: AddToWishlistParams;
+    CompleteRegistration: CompleteRegistrationParams;
+    Contact: ContactParams;
+    CustomizeProduct: CustomizeProductParams;
+    Donate: DonateParams;
+    FindLocation: FindLocationParams;
+    InitiateCheckout: InitiateCheckoutParams;
+    Lead: LeadParams;
+    PageView: PageViewParams;
+    Purchase: PurchaseParams;
+    Schedule: ScheduleParams;
+    Search: SearchParams;
+    StartTrial: StartTrialParams;
+    SubmitApplication: SubmitApplicationParams;
+    Subscribe: SubscribeParams;
+    ViewContent: ViewContentParams;
+}
+export type StandardEventName = keyof StandardEventParams;
+export interface MetaPixelEventOptions {
+    /**
+     * Event ID used to deduplicate browser events against Conversions API events.
+     *
+     * @see https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events
+     */
+    eventID?: string;
+    [key: string]: unknown;
+}
+export interface MetaPixelDataProcessingOptions {
+    /**
+     * Data processing flags sent to Meta before `init`.
+     *
+     * Use `['LDU']` to enable Limited Data Use, or `[]` to explicitly disable it.
+     */
+    options: 'LDU'[] | [];
+    /**
+     * Meta country code. Use `0` to let Meta geolocate the event or `1` for USA.
+     */
+    country?: number;
+    /**
+     * Meta state code. Use `0` to let Meta geolocate the event.
+     *
+     * @example `1000` for California
+     */
+    state?: number;
+}
+declare global {
+    interface Window {
+        fbq: {
+            (command: 'dataProcessingOptions', options: MetaPixelDataProcessingOptions['options'], country?: number, state?: number): void;
+            (command: 'init', pixelId: string, options?: Record<string, unknown>): void;
+            (command: 'track', eventName: StandardEventName, params?: StandardEventParams[StandardEventName], options?: MetaPixelEventOptions): void;
+            (command: 'trackCustom', eventName: string, params?: FbqCustomParams, options?: MetaPixelEventOptions): void;
+            (command: 'trackSingle', pixelId: string, eventName: StandardEventName, params?: StandardEventParams[StandardEventName], options?: MetaPixelEventOptions): void;
+            (command: 'trackSingleCustom', pixelId: string, eventName: string, params?: FbqCustomParams, options?: MetaPixelEventOptions): void;
+            (command: 'consent', action: 'grant' | 'revoke'): void;
+            (...args: unknown[]): void;
+        };
+        _fbq: Window['fbq'];
+    }
+}
+/**
+ * Meta Pixel vendor manifest.
+ *
+ * The Meta Pixel uses structured bootstrap steps to define the standard `fbq`
+ * stub and provides a consent API via `fbq('consent', 'grant'|'revoke')`.
+ */
+export declare const metaPixelManifest: {
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+    readonly vendor: 'meta-pixel';
+    readonly category: 'marketing';
+    readonly persistAfterConsentRevoked: true;
+    readonly bootstrap: [{
+        readonly type: 'defineStubFunction';
+        readonly name: 'fbq';
+        readonly queue: {
+            readonly property: 'queue';
+        };
+        readonly dispatchProperty: 'callMethod';
+        readonly selfReferences: ["push"];
+        readonly aliases: ["_fbq"];
+        readonly properties: {
+            readonly loaded: true;
+            readonly version: '2.0';
+        };
+        readonly ifUndefined: true;
+    }];
+    readonly install: [{
+        readonly type: 'callGlobal';
+        readonly global: 'fbq';
+        readonly args: ["consent", "grant"];
+    }, {
+        readonly type: 'callGlobal';
+        readonly global: 'fbq';
+        readonly args: ["init", "{{pixelId}}"];
+    }, {
+        readonly type: 'callGlobal';
+        readonly global: 'fbq';
+        readonly args: ["track", "PageView"];
+    }, {
+        readonly type: 'loadScript';
+        readonly src: '{{scriptSrc}}';
+        readonly async: true;
+    }];
+    readonly onConsentGranted: [{
+        readonly type: 'callGlobal';
+        readonly global: 'fbq';
+        readonly args: ["consent", "grant"];
+    }];
+    readonly onConsentDenied: [{
+        readonly type: 'callGlobal';
+        readonly global: 'fbq';
+        readonly args: ["consent", "revoke"];
+    }];
+};
+export interface MetaPixelOptions {
+    /**
+     * Your Meta Pixel ID
+     * @example `123456789012345`
+     */
+    pixelId: string;
+    /** Optional payload passed as the third argument to `fbq('init', ...)`. */
+    initOptions?: Record<string, unknown>;
+    /**
+     * Queue the default `PageView` event during setup.
+     *
+     * @default true
+     */
+    trackPageView?: boolean;
+    /**
+     * Optional Meta data processing options, such as Limited Data Use.
+     *
+     * When provided, c15t queues `fbq('dataProcessingOptions', ...)` before
+     * `fbq('init', ...)`.
+     */
+    dataProcessingOptions?: MetaPixelDataProcessingOptions;
+    /** Meta Pixel loader URL. */
+    scriptSrc?: string;
+}
+/**
+ * Creates a Meta Pixel script.
+ *
+ * The manifest defines a structured `fbq` stub plus the external loader URL,
+ * avoiding raw inline vendor snippets in the manifest payload.
+ *
+ * @param options - The options for the Meta Pixel script
+ * @returns The Meta Pixel script configuration
+ *
+ * @example
+ * ```ts
+ * const metaPixelScript = metaPixel({
+ *   pixelId: '123456789012345',
+ * });
+ * ```
+ *
+ * @see {@link https://developers.facebook.com/docs/meta-pixel/get-started} Meta Pixel documentation
+ */
+export declare function metaPixel({ pixelId, initOptions, trackPageView, dataProcessingOptions, scriptSrc, }: MetaPixelOptions): Script;
+/**
+ * Tracks a Meta Pixel standard event.
+ *
+ * This is a wrapper around `fbq('track', ...)`.
+ *
+ * @template TEventName - The Meta `StandardEventName` being tracked.
+ * @param eventName - The `StandardEventName` to track.
+ * @param params - Optional `StandardEventParams[TEventName]` payload.
+ * @param eventOptions - Optional `MetaPixelEventOptions` or event ID string.
+ * @returns `void`; calls `window.fbq`.
+ *
+ * @example
+ * ```ts
+ * metaPixelEvent('Purchase', { value: 10.0, currency: 'USD' }, 'event-123');
+ * ```
+ *
+ * @see {@link https://developers.facebook.com/docs/meta-pixel/reference} Meta Pixel documentation
+ */
+export declare const metaPixelEvent: <TEventName extends StandardEventName>(eventName: TEventName, params?: StandardEventParams[TEventName], eventOptions?: MetaPixelEventOptions | string) => void;
+/**
+ * Tracks a Meta Pixel custom event with optional custom parameters.
+ *
+ * @param eventName - The custom event name to track
+ * @param params - Optional custom parameters to track
+ * @param eventOptions - Optional event options, including Conversions API eventID
+ */
+export declare const metaPixelCustomEvent: (eventName: string, params?: FbqCustomParams, eventOptions?: MetaPixelEventOptions | string) => void;
+/**
+ * Tracks a standard event for a single Meta Pixel ID.
+ *
+ * Use this when multiple Meta Pixels are initialized on the same page and the
+ * event should not fire for every initialized pixel.
+ *
+ * @template TEventName - The Meta `StandardEventName` being tracked.
+ * @param pixelId - Meta Pixel ID that should receive the event.
+ * @param eventName - The `StandardEventName` to track.
+ * @param params - Optional `StandardEventParams[TEventName]` payload.
+ * @param eventOptions - Optional `MetaPixelEventOptions` or event ID string.
+ * @returns `void`; calls `window.fbq`.
+ *
+ * @example
+ * ```ts
+ * metaPixelSingleEvent(
+ * 	'123456',
+ * 	'Purchase',
+ * 	{ value: 9.99, currency: 'USD' },
+ * 	'event-123'
+ * );
+ * ```
+ */
+export declare const metaPixelSingleEvent: <TEventName extends StandardEventName>(pixelId: string, eventName: TEventName, params?: StandardEventParams[TEventName], eventOptions?: MetaPixelEventOptions | string) => void;
+/**
+ * Tracks a custom event for a single Meta Pixel ID.
+ *
+ * Use this when multiple Meta Pixels are initialized on the same page and the
+ * custom event should not fire for every initialized pixel.
+ *
+ * @param pixelId - Meta Pixel ID that should receive the custom event.
+ * @param eventName - Custom event name to track.
+ * @param params - Optional `FbqCustomParams` payload.
+ * @param eventOptions - Optional `MetaPixelEventOptions` or event ID string.
+ * @returns `void`; calls `window.fbq`.
+ *
+ * @example
+ * ```ts
+ * metaPixelSingleCustomEvent('123456', 'MyCustomEvent', { foo: 'bar' });
+ * ```
+ */
+export declare const metaPixelSingleCustomEvent: (pixelId: string, eventName: string, params?: FbqCustomParams, eventOptions?: MetaPixelEventOptions | string) => void;
+export {};