@c15t/scripts 2.0.0 → 2.1.0

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/{linkedin-insights.d.ts → vendors/ads-and-pixels/linkedin-insights.d.ts}

@@ -1,7 +1,15 @@
 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: ((...args: unknown[]) => void) & {
+        lintrk: LinkedInInsightsFunction & {
             q?: unknown[][];
         };
         _linkedin_partner_id?: string;
@@ -14,9 +22,9 @@ declare global {
     }
 }
 /**
- * LinkedIn Insights vendor manifest.
+ * LinkedIn Insight Tag vendor manifest.
  *
- * Sets up the LinkedIn partner ID globals and loads the insights script
+ * Sets up the LinkedIn partner ID globals and loads the Insight Tag script
  * via structured startup steps.
  */
 export declare const linkedinInsightsManifest: {
@@ -54,18 +62,22 @@ export declare const linkedinInsightsManifest: {
 };
 export interface LinkedInInsightsOptions {
     /**
-     * Your LinkedIn Insights ID
+     * Your LinkedIn Insight Tag partner ID.
+     *
+     * LinkedIn shows this in Campaign Manager under Data -> Signals manager ->
+     * Insight Tag.
+     *
      * @example `123456789012345`
      */
     id: string;
-    /** LinkedIn Insights loader URL. */
+    /** LinkedIn Insight Tag loader URL. */
     scriptSrc?: string;
 }
 /**
- * LinkedIn Insights Script
+ * LinkedIn Insight Tag script.
  *
- * @param options - The options for the LinkedIn Insights script
- * @returns The LinkedIn Insights script configuration
+ * @param options - The options for the LinkedIn Insight Tag script.
+ * @returns The LinkedIn Insight Tag script configuration.
  *
  * @example
  * ```ts
@@ -74,6 +86,7 @@ export interface LinkedInInsightsOptions {
  * });
  * ```
  *
- * @see {@link https://business.linkedin.com/marketing-solutions/ad-libraries/insights} LinkedIn Insights documentation
+ * @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 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"];
+    }];
+    readonly kind: "c15t.vendor-manifest";
+    readonly schemaVersion: 1;
+};
+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 {};

package/dist-types/{microsoft-uet.d.ts → vendors/ads-and-pixels/microsoft-uet.d.ts}

@@ -7,12 +7,13 @@ declare global {
 /**
  * Microsoft UET vendor manifest.
  *
- * Uses structured startup steps and manages consent via the UET push API:
- * `window.uetq.push('consent', 'default'|'update', { ad_storage: 'granted'|'denied' })`
+ * Loads in consent mode and manages consent via the UET push API:
+ * `window.uetq.push('consent', 'default'|'update', consentState)`.
  */
 export declare const microsoftUetManifest: {
     readonly vendor: "microsoft-uet";
     readonly category: "marketing";
+    readonly alwaysLoad: true;
     readonly persistAfterConsentRevoked: true;
     readonly bootstrap: [{
         readonly type: "setGlobal";
@@ -20,6 +21,22 @@ export declare const microsoftUetManifest: {
         readonly value: readonly [];
         readonly ifUndefined: true;
     }];
+    readonly onBeforeLoadGranted: [{
+        readonly type: "callGlobal";
+        readonly global: "uetq";
+        readonly method: "push";
+        readonly args: ["consent", "default", {
+            readonly ad_storage: "granted";
+        }];
+    }];
+    readonly onBeforeLoadDenied: [{
+        readonly type: "callGlobal";
+        readonly global: "uetq";
+        readonly method: "push";
+        readonly args: ["consent", "default", {
+            readonly ad_storage: "denied";
+        }];
+    }];
     readonly install: [{
         readonly type: "loadScript";
         readonly src: "{{scriptSrc}}";
@@ -39,13 +56,6 @@ export declare const microsoftUetManifest: {
         readonly global: "uetq";
         readonly method: "push";
         readonly args: ["pageLoad"];
-    }, {
-        readonly type: "callGlobal";
-        readonly global: "uetq";
-        readonly method: "push";
-        readonly args: ["consent", "default", {
-            readonly ad_storage: "granted";
-        }];
     }];
     readonly onConsentGranted: [{
         readonly type: "callGlobal";
@@ -77,7 +87,8 @@ export interface MicrosoftUetOptions {
 }
 /**
  * Microsoft UET Script
- * This script is persistent after consent is revoked because it has built-in functionality to opt into and out of tracking based on consent, which allows us to not need to load the script again when consent is revoked.
+ * This script loads in consent mode and stays persistent because UET can opt
+ * into and out of tracking based on consent.
  *
  * @param options - The options for the Microsoft UET script
  * @returns The Microsoft UET script configuration