@webaround/openai-ads 0.1.0

package/dist/pixel.js

@@ -0,0 +1,305 @@
+import { OpenAIAdsError } from './errors.js';
+import { assertUsableEventId } from './eventId.js';
+import { CUSTOM_EVENT_NAME_PATTERN, DATA_SHAPES, PIXEL_SUPPORTED, SDK_URL, isEventName } from './spec.js';
+/**
+ * A typed, consent-aware wrapper over OpenAI's official browser SDK.
+ *
+ * It does NOT reimplement the transport. The official SDK is a script on
+ * OpenAI's CDN plus a global command queue, and this wrapper loads that script
+ * and speaks to that queue. Everything the SDK owns - batching, timestamps,
+ * `source_url`, capturing `oppref` into the `__oppref` cookie - is left to it.
+ *
+ * Nothing here throws at the caller. A measurement failure must never break a
+ * checkout or a form submission, so errors go to `onError`.
+ */
+class OpenAIAdsPixel {
+    constructor() {
+        this.pixelIds = new Set();
+        this.debug = false;
+        this.consentGranted = true;
+        this.scriptInjected = false;
+        this.onError = () => { };
+    }
+    /**
+     * Configure error reporting. Optional; call before `init` to catch setup
+     * problems.
+     */
+    configure(options) {
+        if (options.onError !== undefined) {
+            this.onError = options.onError;
+        }
+    }
+    /**
+     * Record the visitor's consent decision.
+     *
+     * Must be called before `init` to take effect on the SDK, per its
+     * documentation. When consent is denied this wrapper also stops emitting
+     * events of its own accord - silently, because a refused consent is a normal
+     * outcome and not an error.
+     */
+    consent(granted) {
+        this.consentGranted = granted;
+        // Recorded before init so the SDK sees the decision first, as documented.
+        this.safely(() => {
+            // The queue is created without injecting the script, so a denial can be
+            // recorded on a page that never loads the SDK, and a grant is replayed
+            // ahead of init once the script arrives.
+            this.ensureQueue();
+            this.queue()('consent', granted);
+        });
+    }
+    /**
+     * Load the SDK and initialize a Pixel ID.
+     *
+     * Safe to call more than once, which is required rather than merely tolerated:
+     * the documented way to attach identity once a visitor becomes known is to
+     * call init again with `user`. Re-initializing the same Pixel ID with no new
+     * user data is skipped, which is the guard against the common mistake of
+     * initializing in both a root layout and a page.
+     *
+     * On a page with several pixels, call this once per Pixel ID.
+     */
+    init(config = {}) {
+        this.safely(() => {
+            if (config.debug !== undefined) {
+                this.debug = config.debug;
+            }
+            const pixelId = config.pixelId?.trim();
+            if (pixelId === undefined || pixelId === '') {
+                if (this.pixelIds.size === 0) {
+                    throw new OpenAIAdsError('init requires a pixelId on the first call.');
+                }
+            }
+            if (!this.consentGranted) {
+                // Do not load a measurement SDK the visitor has refused.
+                this.warn('Consent is denied; the Pixel SDK was not loaded.');
+                return;
+            }
+            this.load();
+            if (pixelId !== undefined && pixelId !== '' && this.pixelIds.has(pixelId) && config.user === undefined) {
+                this.warn(`Pixel "${pixelId}" is already initialized and no new user data was supplied; ` +
+                    'skipping. Initializing twice usually means a layout and a page both call init.');
+                return;
+            }
+            const payload = {};
+            if (pixelId !== undefined && pixelId !== '') {
+                payload['pixelId'] = pixelId;
+                this.pixelIds.add(pixelId);
+            }
+            if (this.debug) {
+                payload['debug'] = true;
+            }
+            if (config.user !== undefined) {
+                payload['user'] = config.user;
+            }
+            this.queue()('init', payload);
+        });
+    }
+    /**
+     * Emit a standard event at a confirmed conversion boundary.
+     *
+     * Fire after the action has succeeded - after payment is confirmed, after the
+     * lead is accepted - never on a button click, unless the click genuinely is
+     * the conversion.
+     */
+    track(name, data, options = {}) {
+        this.safely(() => {
+            this.emit(name, data, options);
+        });
+    }
+    /**
+     * Emit a custom event.
+     *
+     * Use only where no standard event describes the action. The same name must be
+     * used on the Conversions API side or the two will not deduplicate.
+     */
+    trackCustom(customEventName, data, options = {}) {
+        this.safely(() => {
+            this.emit('custom', data, { ...options, customEventName });
+        });
+    }
+    /** Pixel IDs initialized so far. Exposed for diagnostics and tests. */
+    initializedPixelIds() {
+        return [...this.pixelIds];
+    }
+    /** Test seam. Not part of the public API. */
+    reset() {
+        this.pixelIds.clear();
+        this.debug = false;
+        this.consentGranted = true;
+        this.scriptInjected = false;
+        this.onError = () => { };
+    }
+    /**
+     * `name` is a string rather than an EventName on purpose.
+     *
+     * TypeScript proves the caller passed a valid one; JavaScript proves nothing,
+     * and this package is published for both. The check below is what a plain-JS
+     * caller gets instead of a compile error.
+     */
+    emit(name, data, options) {
+        if (!isEventName(name)) {
+            throw new OpenAIAdsError(`"${name}" is not a supported event name.`);
+        }
+        if (!PIXEL_SUPPORTED[name]) {
+            throw new OpenAIAdsError(`"${name}" is a Conversions API event and cannot be sent from the browser. ` +
+                'Send it server-side.');
+        }
+        if (this.pixelIds.size === 0) {
+            throw new OpenAIAdsError(`init must be called before tracking "${name}".`);
+        }
+        if (!this.consentGranted) {
+            // Silent by design: a refused consent is an expected outcome.
+            return;
+        }
+        const customEventName = this.validateCustomEventName(name, options.customEventName);
+        const payload = this.buildData(name, data);
+        const sdkOptions = this.buildOptions(options, customEventName);
+        const target = options.pixelId?.trim();
+        if (target !== undefined && target !== '') {
+            if (!this.pixelIds.has(target)) {
+                throw new OpenAIAdsError(`Pixel "${target}" has not been initialized.`);
+            }
+            this.queue()('measureSingle', target, name, payload, sdkOptions);
+            return;
+        }
+        if (this.pixelIds.size > 1) {
+            // `measure` goes to every pixel initialized at the time of the call. That
+            // is the SDK's documented behaviour and is preserved here, but on a
+            // multi-pixel page it is usually not what the caller meant.
+            this.warn(`This event was broadcast to ${this.pixelIds.size} initialized pixels. ` +
+                'Pass options.pixelId to send it to one.');
+        }
+        this.queue()('measure', name, payload, sdkOptions);
+    }
+    buildData(name, data) {
+        const shape = DATA_SHAPES[name];
+        const merged = { ...data, type: shape };
+        if (merged.amount !== undefined) {
+            if (!Number.isInteger(merged.amount)) {
+                const suggestion = Math.round(merged.amount * 100);
+                throw new OpenAIAdsError(`amount must be an integer in the currency's minor unit; got ${merged.amount}. ` +
+                    `Did you mean ${suggestion}?`);
+            }
+            if (merged.currency === undefined) {
+                throw new OpenAIAdsError('currency is required when amount is present.');
+            }
+        }
+        if (merged.currency !== undefined && !/^[A-Za-z]{3}$/.test(merged.currency)) {
+            throw new OpenAIAdsError(`currency must be an ISO 4217 alpha-3 code such as "EUR"; got "${merged.currency}".`);
+        }
+        if (merged.currency !== undefined) {
+            merged.currency = merged.currency.toUpperCase();
+        }
+        return merged;
+    }
+    buildOptions(options, customEventName) {
+        const sdkOptions = {};
+        if (options.eventId !== undefined) {
+            sdkOptions['event_id'] = assertUsableEventId(options.eventId);
+        }
+        if (customEventName !== undefined) {
+            sdkOptions['custom_event_name'] = customEventName;
+        }
+        if (options.optOut !== undefined) {
+            sdkOptions['opt_out'] = options.optOut;
+        }
+        return sdkOptions;
+    }
+    validateCustomEventName(name, customEventName) {
+        if (name !== 'custom') {
+            if (customEventName !== undefined) {
+                throw new OpenAIAdsError(`customEventName is only valid for the "custom" event; "${name}" is a standard event.`);
+            }
+            return undefined;
+        }
+        if (customEventName === undefined || customEventName === '') {
+            throw new OpenAIAdsError('customEventName is required for a custom event.');
+        }
+        if (!CUSTOM_EVENT_NAME_PATTERN.test(customEventName)) {
+            throw new OpenAIAdsError('customEventName must be 1-64 characters of letters, digits, underscores or dashes, ' +
+                `starting and ending with a letter or digit; got "${customEventName}".`);
+        }
+        if (isEventName(customEventName)) {
+            throw new OpenAIAdsError(`customEventName must not reuse the standard event name "${customEventName}".`);
+        }
+        return customEventName;
+    }
+    /**
+     * Create the global command queue.
+     *
+     * This is the first half of the documented loader snippet: define the queue
+     * synchronously so commands issued before the script arrives are replayed in
+     * order. Kept separate from injecting the script so that `consent(false)` can
+     * be recorded on a page where the SDK is never loaded at all.
+     */
+    ensureQueue() {
+        if (globalThis.oaiq !== undefined) {
+            return;
+        }
+        const queue = function (...args) {
+            queue.q?.push(args);
+        };
+        queue.q = [];
+        globalThis.oaiq = queue;
+    }
+    /** The second half of the loader snippet: fetch the official SDK, once. */
+    load() {
+        if (typeof document === 'undefined') {
+            throw new OpenAIAdsError('The Pixel requires a browser document; it cannot run server-side.');
+        }
+        this.ensureQueue();
+        if (this.scriptInjected) {
+            return;
+        }
+        this.scriptInjected = true;
+        const script = document.createElement('script');
+        script.async = true;
+        script.src = SDK_URL;
+        script.addEventListener('error', () => {
+            this.onError(new OpenAIAdsError('The OpenAI Ads Pixel SDK failed to load; events were not delivered.'));
+        });
+        const first = document.getElementsByTagName('script')[0];
+        if (first?.parentNode) {
+            first.parentNode.insertBefore(script, first);
+        }
+        else {
+            (document.head ?? document.documentElement).appendChild(script);
+        }
+    }
+    queue() {
+        const queue = globalThis.oaiq;
+        if (queue === undefined) {
+            throw new OpenAIAdsError('The Pixel SDK is not loaded; call init first.');
+        }
+        return queue;
+    }
+    /**
+     * The reason nothing here throws at the caller.
+     *
+     * A measurement mistake on a checkout page must not take the checkout with it,
+     * so failures are reported and swallowed. Supply `onError` to route them into
+     * your own logging.
+     */
+    safely(operation) {
+        try {
+            operation();
+        }
+        catch (error) {
+            const wrapped = error instanceof Error ? error : new OpenAIAdsError('Unknown failure', { cause: error });
+            this.onError(wrapped);
+            if (this.debug) {
+                console.warn('[openai-ads]', wrapped.message);
+            }
+        }
+    }
+    warn(message) {
+        if (this.debug) {
+            console.warn('[openai-ads]', message);
+        }
+    }
+}
+export { OpenAIAdsPixel };
+/** The shared instance. A page has one Pixel SDK, so it has one of these. */
+export const OpenAIAds = new OpenAIAdsPixel();
+//# sourceMappingURL=pixel.js.map

package/dist/pixel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixel.js","sourceRoot":"","sources":["../src/pixel.ts"],"names":[],"mappings":"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"}

package/dist/spec.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The events OpenAI Ads documents.
+ *
+ * Mirrors `packages/spec/events.json`. `tests/spec-parity.test.ts` asserts this
+ * file and the specification agree on the catalogue, the data shapes and Pixel
+ * support, so an upstream addition turns this package red rather than letting it
+ * drift from the PHP core.
+ */
+export declare const EVENT_NAMES: readonly ["page_viewed", "contents_viewed", "items_added", "checkout_started", "order_created", "lead_created", "registration_completed", "appointment_scheduled", "subscription_created", "trial_started", "custom", "app_installed", "app_opened"];
+export type EventName = (typeof EVENT_NAMES)[number];
+export type DataShape = 'contents' | 'customer_action' | 'plan_enrollment' | 'custom';
+export declare const DATA_SHAPES: Readonly<Record<EventName, DataShape>>;
+/**
+ * Whether the browser Pixel can emit the event at all.
+ *
+ * `app_installed` and `app_opened` are Conversions API only. Attempting them
+ * here is a programming error the wrapper refuses rather than passes to the SDK,
+ * which would accept and silently discard them.
+ */
+export declare const PIXEL_SUPPORTED: Readonly<Record<EventName, boolean>>;
+/** Mirrors `patterns.custom_event_name` in the specification. */
+export declare const CUSTOM_EVENT_NAME_PATTERN: RegExp;
+/** The official SDK. Loaded from OpenAI's CDN; never bundled or vendored. */
+export declare const SDK_URL = "https://bzrcdn.openai.com/sdk/oaiq.min.js";
+export declare function isEventName(value: string): value is EventName;
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAO,MAAM,WAAW,sPAcd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,QAAQ,CAAC;AAEtF,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAc9D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAchE,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,QACuB,CAAC;AAE9D,6EAA6E;AAC7E,eAAO,MAAM,OAAO,8CAA8C,CAAC;AAEnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D"}

package/dist/spec.js

@@ -0,0 +1,68 @@
+/**
+ * The events OpenAI Ads documents.
+ *
+ * Mirrors `packages/spec/events.json`. `tests/spec-parity.test.ts` asserts this
+ * file and the specification agree on the catalogue, the data shapes and Pixel
+ * support, so an upstream addition turns this package red rather than letting it
+ * drift from the PHP core.
+ */
+export const EVENT_NAMES = [
+    'page_viewed',
+    'contents_viewed',
+    'items_added',
+    'checkout_started',
+    'order_created',
+    'lead_created',
+    'registration_completed',
+    'appointment_scheduled',
+    'subscription_created',
+    'trial_started',
+    'custom',
+    'app_installed',
+    'app_opened',
+];
+export const DATA_SHAPES = {
+    page_viewed: 'contents',
+    contents_viewed: 'contents',
+    items_added: 'contents',
+    checkout_started: 'contents',
+    order_created: 'contents',
+    lead_created: 'customer_action',
+    registration_completed: 'customer_action',
+    appointment_scheduled: 'customer_action',
+    subscription_created: 'plan_enrollment',
+    trial_started: 'plan_enrollment',
+    custom: 'custom',
+    app_installed: 'customer_action',
+    app_opened: 'customer_action',
+};
+/**
+ * Whether the browser Pixel can emit the event at all.
+ *
+ * `app_installed` and `app_opened` are Conversions API only. Attempting them
+ * here is a programming error the wrapper refuses rather than passes to the SDK,
+ * which would accept and silently discard them.
+ */
+export const PIXEL_SUPPORTED = {
+    page_viewed: true,
+    contents_viewed: true,
+    items_added: true,
+    checkout_started: true,
+    order_created: true,
+    lead_created: true,
+    registration_completed: true,
+    appointment_scheduled: true,
+    subscription_created: true,
+    trial_started: true,
+    custom: true,
+    app_installed: false,
+    app_opened: false,
+};
+/** Mirrors `patterns.custom_event_name` in the specification. */
+export const CUSTOM_EVENT_NAME_PATTERN = /^[A-Za-z0-9]$|^[A-Za-z0-9][A-Za-z0-9_-]{0,62}[A-Za-z0-9]$/;
+/** The official SDK. Loaded from OpenAI's CDN; never bundled or vendored. */
+export const SDK_URL = 'https://bzrcdn.openai.com/sdk/oaiq.min.js';
+export function isEventName(value) {
+    return EVENT_NAMES.includes(value);
+}
+//# sourceMappingURL=spec.js.map

package/dist/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../src/spec.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,aAAa;IACb,iBAAiB;IACjB,aAAa;IACb,kBAAkB;IAClB,eAAe;IACf,cAAc;IACd,wBAAwB;IACxB,uBAAuB;IACvB,sBAAsB;IACtB,eAAe;IACf,QAAQ;IACR,eAAe;IACf,YAAY;CACJ,CAAC;AAMX,MAAM,CAAC,MAAM,WAAW,GAA2C;IACjE,WAAW,EAAE,UAAU;IACvB,eAAe,EAAE,UAAU;IAC3B,WAAW,EAAE,UAAU;IACvB,gBAAgB,EAAE,UAAU;IAC5B,aAAa,EAAE,UAAU;IACzB,YAAY,EAAE,iBAAiB;IAC/B,sBAAsB,EAAE,iBAAiB;IACzC,qBAAqB,EAAE,iBAAiB;IACxC,oBAAoB,EAAE,iBAAiB;IACvC,aAAa,EAAE,iBAAiB;IAChC,MAAM,EAAE,QAAQ;IAChB,aAAa,EAAE,iBAAiB;IAChC,UAAU,EAAE,iBAAiB;CAC9B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAyC;IACnE,WAAW,EAAE,IAAI;IACjB,eAAe,EAAE,IAAI;IACrB,WAAW,EAAE,IAAI;IACjB,gBAAgB,EAAE,IAAI;IACtB,aAAa,EAAE,IAAI;IACnB,YAAY,EAAE,IAAI;IAClB,sBAAsB,EAAE,IAAI;IAC5B,qBAAqB,EAAE,IAAI;IAC3B,oBAAoB,EAAE,IAAI;IAC1B,aAAa,EAAE,IAAI;IACnB,MAAM,EAAE,IAAI;IACZ,aAAa,EAAE,KAAK;IACpB,UAAU,EAAE,KAAK;CAClB,CAAC;AAEF,iEAAiE;AACjE,MAAM,CAAC,MAAM,yBAAyB,GACpC,2DAA2D,CAAC;AAE9D,6EAA6E;AAC7E,MAAM,CAAC,MAAM,OAAO,GAAG,2CAA2C,CAAC;AAEnE,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAQ,WAAiC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+import type { EventName } from './spec.js';
+/** An item inside a `contents` array. */
+export interface Content {
+    id?: string;
+    name?: string;
+    content_type?: string;
+    quantity?: number;
+    amount?: number;
+    currency?: string;
+}
+interface BaseData {
+    /** Integer, in the currency's minor unit. 1299, never 12.99. */
+    amount?: number;
+    /** ISO 4217 alpha-3. Required whenever `amount` is present. */
+    currency?: string;
+}
+export interface ContentsData extends BaseData {
+    type: 'contents';
+    contents?: Content[];
+}
+export interface CustomerActionData extends BaseData {
+    type: 'customer_action';
+}
+export interface PlanEnrollmentData extends BaseData {
+    type: 'plan_enrollment';
+    plan_id?: string;
+    contents?: Content[];
+}
+export interface CustomData extends BaseData {
+    type: 'custom';
+    plan_id?: string;
+    contents?: Content[];
+    [key: string]: unknown;
+}
+export type EventData = ContentsData | CustomerActionData | PlanEnrollmentData | CustomData;
+/** Maps an event name to the only data shape it accepts. */
+export type DataFor<N extends EventName> = Extract<EventData, {
+    type: DataShapeOf<N>;
+}>;
+type DataShapeOf<N extends EventName> = N extends 'page_viewed' | 'contents_viewed' | 'items_added' | 'checkout_started' | 'order_created' ? 'contents' : N extends 'lead_created' | 'registration_completed' | 'appointment_scheduled' ? 'customer_action' : N extends 'subscription_created' | 'trial_started' ? 'plan_enrollment' : 'custom';
+/**
+ * Identity for the Pixel: singular keys, scalar values.
+ *
+ * The Conversions API wants the same digests under plural keys with array
+ * values. Producing this shape is `hashUser()`'s job; do not hand-build it from
+ * a Conversions API payload.
+ */
+export interface PixelUser {
+    email_sha256?: string;
+    phone_number_sha256?: string;
+    external_id_sha256?: string;
+    first_name_sha256?: string;
+    last_name_sha256?: string;
+    country?: string;
+    city?: string;
+    region?: string;
+    postal_code?: string;
+}
+/** Raw identity, normalized and hashed in the browser by `hashUser()`. */
+export interface RawUser {
+    email?: string;
+    phone?: string;
+    externalId?: string;
+    firstName?: string;
+    lastName?: string;
+    country?: string;
+    city?: string;
+    region?: string;
+    postalCode?: string;
+}
+export interface InitConfig {
+    /** Required on the first call. Subsequent calls may omit it on a single-pixel page. */
+    pixelId?: string;
+    /** Turns on the SDK's own debug output and this wrapper's warnings. */
+    debug?: boolean;
+    /** Already-hashed identity. Use `hashUser()` to produce it. */
+    user?: PixelUser;
+}
+export interface TrackOptions {
+    /**
+     * Ties this browser event to its server-side twin. Both sides must use the
+     * same Pixel ID, event name and id, or the conversion is counted twice.
+     */
+    eventId?: string;
+    /** Required when the event is `custom`. */
+    customEventName?: string;
+    /** Excludes the event from personalization. NOT a consent gate. */
+    optOut?: boolean;
+    /**
+     * Send to one Pixel ID instead of every initialized one.
+     *
+     * Without this the SDK broadcasts to every pixel initialized at the time of
+     * the call, which double-counts on a page running more than one pixel.
+     */
+    pixelId?: string;
+}
+export interface ToolkitOptions {
+    /**
+     * Called instead of throwing. Measurement must never break the page, so every
+     * failure - a validation mistake included - is routed here.
+     *
+     * Defaults to a `console.warn` when `debug` is on, and to silence otherwise.
+     */
+    onError?: (error: Error) => void;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/userData.d.ts

@@ -0,0 +1,68 @@
+import type { PixelUser, RawUser } from './types.js';
+export declare function normalizeEmail(value: string): string;
+/**
+ * Remove the four documented separators, then a leading '+', then leading
+ * zeroes - and nothing else.
+ *
+ * Upstream documents '8-15 digits after removing a leading +, leading zeroes,
+ * whitespace, parentheses, periods, and hyphens'. Removing every non-digit
+ * instead looks equivalent and is not: '+1 (555) 123-4567 ext. 89' would become
+ * '1555123456789', which passes a length check and hashes to nobody. Whatever
+ * is left over is returned as-is so the caller can refuse it.
+ *
+ * Dialling plans are still not parsed: '+00 44 (0)20 7946 0958' becomes
+ * '4402079460958'.
+ */
+export declare function normalizePhone(value: string): string;
+/**
+ * ISO 3166-1 alpha-2, uppercased.
+ *
+ * Returns undefined for anything that is not two ASCII letters. A country name
+ * rather than a code is dropped by the API without an error, so sending one
+ * would look like matching data and be nothing of the sort.
+ */
+export declare function normalizeCountry(value: string): string | undefined;
+/**
+ * Trim, lowercase, cap at 128 characters - what the API does on receipt.
+ *
+ * Applied here too so the string sent is the string stored, and so the Pixel
+ * and the Conversions API carry the same one for the same person.
+ */
+export declare function normalizeCityOrRegion(value: string): string;
+/**
+ * Reduce to letters, digits, spaces and hyphens, cap at 32 characters.
+ *
+ * Disallowed characters are removed rather than refused - a stray period is a
+ * formatting artefact. Case is deliberately not folded: upstream states a
+ * lowercase rule for cities and regions and states none here.
+ */
+export declare function normalizePostalCode(value: string): string;
+export declare function normalizeExternalId(value: string): string;
+/**
+ * Lowercase, then strip whitespace and ASCII punctuation.
+ *
+ * `toLowerCase()` is Unicode-aware, which is what the PHP side gets from
+ * `mb_strtolower`. A byte-wise lowercase there would leave a diacritic
+ * untouched and produce a digest that never matches this one.
+ */
+export declare function normalizeName(value: string): string;
+/**
+ * SHA-256 as lowercase hexadecimal.
+ *
+ * Web Crypto is asynchronous and only available in a secure context, so this is
+ * async and fails loudly on plain HTTP rather than degrading to a weaker hash or
+ * - far worse - sending the raw value.
+ */
+export declare function sha256Hex(value: string): Promise<string>;
+/**
+ * Normalize and hash raw identity into the Pixel's shape.
+ *
+ * Pass the result to `init({ user })` when the person becomes known - after a
+ * login, a checkout, a lead submission. Geographic values are sent unhashed, as
+ * documented.
+ *
+ * Values that normalize away to nothing are dropped rather than hashed: the
+ * digest of an empty string is a valid-looking value that matches nobody.
+ */
+export declare function hashUser(raw: RawUser): Promise<PixelUser>;
+//# sourceMappingURL=userData.d.ts.map

package/dist/userData.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"userData.d.ts","sourceRoot":"","sources":["../src/userData.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAwBrD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIlE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMzD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAa9D;AAED;;;;;;;;;GASG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CA2E/D"}