@webaround/openai-ads 0.1.0

package/dist/userData.js

@@ -0,0 +1,172 @@
+import { OpenAIAdsError } from './errors.js';
+/**
+ * Identity normalization and hashing in the browser.
+ *
+ * These rules must produce byte-identical digests to the PHP core, because a
+ * Pixel event and its Conversions API twin describe the same person. Both
+ * implementations are pinned by
+ * `packages/spec/fixtures/normalization.cases.json`, and both test suites read
+ * that file.
+ *
+ * Raw values never leave this module: `hashUser()` returns digests, and nothing
+ * here writes a raw identifier to the DOM, to storage, or to the console.
+ */
+/** ASCII punctuation. Non-ASCII characters are preserved, as the spec requires. */
+const ASCII_PUNCTUATION = /[!-/:-@[-`{-~]/g;
+/** Mirrors `normalizations.city_region.max_length` in packages/spec/user.json. */
+const CITY_REGION_MAX_LENGTH = 128;
+/** Mirrors `normalizations.postal_code.max_length` in packages/spec/user.json. */
+const POSTAL_CODE_MAX_LENGTH = 32;
+export function normalizeEmail(value) {
+    return value.trim().toLowerCase();
+}
+/**
+ * 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 function normalizePhone(value) {
+    return value
+        .trim()
+        .replace(/[\s().-]/g, '')
+        .replace(/^\+/, '')
+        .replace(/^0+/, '');
+}
+/**
+ * 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 function normalizeCountry(value) {
+    const trimmed = value.trim();
+    return /^[A-Za-z]{2}$/.test(trimmed) ? trimmed.toUpperCase() : 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 function normalizeCityOrRegion(value) {
+    return value.trim().toLowerCase().slice(0, CITY_REGION_MAX_LENGTH);
+}
+/**
+ * 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 function normalizePostalCode(value) {
+    return value
+        .trim()
+        .replace(/[^A-Za-z0-9 -]/g, '')
+        .slice(0, POSTAL_CODE_MAX_LENGTH)
+        .trim();
+}
+export function normalizeExternalId(value) {
+    // Case is preserved deliberately.
+    return value.trim();
+}
+/**
+ * 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 function normalizeName(value) {
+    return value.trim().toLowerCase().replace(/\s+/gu, '').replace(ASCII_PUNCTUATION, '');
+}
+/**
+ * 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 async function sha256Hex(value) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined) {
+        throw new OpenAIAdsError('Web Crypto is unavailable, so identity cannot be hashed in the browser. ' +
+            'This usually means the page is not served over HTTPS. Raw values are never sent.');
+    }
+    const digest = await subtle.digest('SHA-256', new TextEncoder().encode(value));
+    return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * 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 async function hashUser(raw) {
+    const user = {};
+    const hashed = [
+        ['email_sha256', raw.email, normalizeEmail],
+        ['phone_number_sha256', raw.phone, normalizePhone],
+        ['external_id_sha256', raw.externalId, normalizeExternalId],
+        ['first_name_sha256', raw.firstName, normalizeName],
+        ['last_name_sha256', raw.lastName, normalizeName],
+    ];
+    for (const [key, value, normalize] of hashed) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const normalized = normalize(value);
+        if (normalized === '') {
+            continue;
+        }
+        if (key === 'phone_number_sha256') {
+            // Both messages deliberately omit the number itself.
+            if (!/^[0-9]*$/.test(normalized)) {
+                throw new OpenAIAdsError('phone must contain only digits once whitespace, parentheses, periods, hyphens, ' +
+                    'a leading plus and leading zeroes are removed. An extension or a letter is not ' +
+                    'stripped, because stripping it would silently hash a different number.');
+            }
+            if (normalized.length < 8 || normalized.length > 15) {
+                throw new OpenAIAdsError(`phone must contain between 8 and 15 digits after normalization; got ${normalized.length}.`);
+            }
+        }
+        user[key] = await sha256Hex(normalized);
+    }
+    // Geographic values are sent unhashed but NOT unnormalized: the API documents
+    // a rule for each and drops a value that does not satisfy it, silently.
+    if (raw.country !== undefined && raw.country.trim() !== '') {
+        const country = normalizeCountry(raw.country);
+        if (country === undefined) {
+            throw new OpenAIAdsError(`country must be a two-letter ISO 3166-1 alpha-2 code such as "US"; got "${raw.country.trim()}".`);
+        }
+        user.country = country;
+    }
+    const geographic = [
+        ['city', raw.city, normalizeCityOrRegion],
+        ['region', raw.region, normalizeCityOrRegion],
+        ['postal_code', raw.postalCode, normalizePostalCode],
+    ];
+    for (const [key, value, normalize] of geographic) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        const normalized = normalize(value);
+        if (normalized !== '') {
+            user[key] = normalized;
+        }
+    }
+    return user;
+}
+//# sourceMappingURL=userData.js.map

package/dist/userData.js.map

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

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@webaround/openai-ads",
+  "version": "0.1.0",
+  "description": "OpenAI Ads Measurement Pixel for the browser: a typed, consent-aware wrapper over the official oaiq SDK, with Pixel/Conversions API deduplication.",
+  "keywords": [
+    "openai",
+    "openai-ads",
+    "pixel",
+    "oaiq",
+    "conversions-api",
+    "measurement",
+    "analytics"
+  ],
+  "homepage": "https://github.com/webaroundlabs/openai-ads-toolkit",
+  "bugs": "https://github.com/webaroundlabs/openai-ads-toolkit/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/webaroundlabs/openai-ads-toolkit.git",
+    "directory": "packages/js"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "npm run lint && npm run typecheck && npm test"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.5",
+    "@types/node": "^22.20.2",
+    "eslint": "^9.39.5",
+    "jsdom": "^25.0.1",
+    "typescript": "^5.6.3",
+    "typescript-eslint": "^8.70.0",
+    "vitest": "^5.0.0"
+  }
+}