@hammr/normalizer 1.0.0

package/dist/index.cjs

@@ -0,0 +1,332 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Normalizer: () => Normalizer,
+  isSha256: () => isSha256,
+  sha256: () => sha256
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hash.ts
+async function sha256(input) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hashHex;
+}
+function isSha256(value) {
+  return /^[a-f0-9]{64}$/.test(value);
+}
+
+// src/Normalizer.ts
+var Normalizer = class {
+  constructor(options = {}) {
+    this.options = {
+      defaultCountryCode: options.defaultCountryCode ?? "1",
+      hashAddressFields: options.hashAddressFields ?? false
+    };
+  }
+  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   * NORMALIZATION METHODS
+   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /**
+   * Normalize email: lowercase, trim whitespace
+   * Returns null if invalid format
+   */
+  normalizeEmail(email) {
+    if (!email || typeof email !== "string") return null;
+    const normalized = email.toLowerCase().trim();
+    if (!normalized.includes("@") || normalized.length < 5) return null;
+    return normalized;
+  }
+  /**
+   * Normalize phone to E.164 format (+15551234567)
+   * Returns null if invalid
+   */
+  normalizePhone(phone, countryCode) {
+    if (!phone || typeof phone !== "string") return null;
+    const code = countryCode ?? this.options.defaultCountryCode;
+    let digits = phone.replace(/[^\d+]/g, "");
+    if (digits.startsWith("+")) digits = digits.slice(1);
+    if (digits.length < 10) return null;
+    if (digits.length === 10) digits = code + digits;
+    return "+" + digits;
+  }
+  /**
+   * Normalize name: lowercase, trim, remove extra spaces
+   * Returns null if empty
+   */
+  normalizeName(name) {
+    if (!name || typeof name !== "string") return null;
+    const normalized = name.toLowerCase().trim().replace(/\s+/g, " ");
+    if (normalized.length === 0) return null;
+    return normalized;
+  }
+  /**
+   * Normalize gender: single lowercase char (m/f)
+   * Accepts: m, male, f, female
+   * Returns null if invalid
+   */
+  normalizeGender(gender) {
+    if (!gender || typeof gender !== "string") return null;
+    const g = gender.toLowerCase().trim();
+    if (g === "m" || g === "male") return "m";
+    if (g === "f" || g === "female") return "f";
+    return null;
+  }
+  /**
+   * Normalize date of birth: YYYYMMDD format
+   * Accepts formats: YYYY-MM-DD, YYYY/MM/DD, YYYY.MM.DD, YYYYMMDD
+   * Returns null if invalid
+   */
+  normalizeDateOfBirth(dob) {
+    if (!dob || typeof dob !== "string") return null;
+    const cleaned = dob.replace(/[-\/\.]/g, "");
+    if (!/^\d{8}$/.test(cleaned)) return null;
+    return cleaned;
+  }
+  /**
+   * Normalize city: lowercase, trim
+   */
+  normalizeCity(city) {
+    if (!city || typeof city !== "string") return null;
+    const normalized = city.toLowerCase().trim();
+    if (normalized.length === 0) return null;
+    return normalized;
+  }
+  /**
+   * Normalize state/region: lowercase, trim
+   */
+  normalizeState(state) {
+    if (!state || typeof state !== "string") return null;
+    const normalized = state.toLowerCase().trim();
+    if (normalized.length === 0) return null;
+    return normalized;
+  }
+  /**
+   * Normalize zip/postal code: lowercase, no spaces
+   */
+  normalizeZipCode(zip) {
+    if (!zip || typeof zip !== "string") return null;
+    const normalized = zip.toLowerCase().trim().replace(/\s+/g, "");
+    if (normalized.length === 0) return null;
+    return normalized;
+  }
+  /**
+   * Normalize country: 2-letter code, lowercase
+   * Returns null if not exactly 2 characters
+   */
+  normalizeCountry(country) {
+    if (!country || typeof country !== "string") return null;
+    const normalized = country.toLowerCase().trim();
+    if (normalized.length !== 2) return null;
+    return normalized;
+  }
+  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   * HASH METHODS
+   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /**
+   * Hash email (normalize then hash)
+   */
+  async hashEmail(email) {
+    const normalized = this.normalizeEmail(email);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash phone (normalize then hash)
+   */
+  async hashPhone(phone, countryCode) {
+    const normalized = this.normalizePhone(phone, countryCode);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash name (normalize then hash)
+   */
+  async hashName(name) {
+    const normalized = this.normalizeName(name);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash gender (normalize then hash)
+   */
+  async hashGender(gender) {
+    const normalized = this.normalizeGender(gender);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash date of birth (normalize then hash)
+   */
+  async hashDateOfBirth(dob) {
+    const normalized = this.normalizeDateOfBirth(dob);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash city (normalize then hash)
+   */
+  async hashCity(city) {
+    const normalized = this.normalizeCity(city);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash state (normalize then hash)
+   */
+  async hashState(state) {
+    const normalized = this.normalizeState(state);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash zip code (normalize then hash)
+   */
+  async hashZipCode(zip) {
+    const normalized = this.normalizeZipCode(zip);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash country (normalize then hash)
+   */
+  async hashCountry(country) {
+    const normalized = this.normalizeCountry(country);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash external ID (trim only, no other normalization)
+   */
+  async hashExternalId(externalId) {
+    if (!externalId || typeof externalId !== "string") return null;
+    return sha256(externalId.trim());
+  }
+  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   * BATCH NORMALIZATION
+   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /**
+   * Normalize and hash all user data
+   * 
+   * Raw PII in, hashed data out.
+   * 
+   * @param raw - Raw user data (unhashed PII)
+   * @returns Normalized and hashed user data
+   * 
+   * @example
+   * ```typescript
+   * const normalizer = new Normalizer();
+   * const normalized = await normalizer.normalize({
+   *   email: 'JOHN@EXAMPLE.COM',
+   *   phone: '555-123-4567',
+   *   first_name: 'John',
+   *   last_name: 'Doe',
+   *   city: 'San Francisco',
+   *   state: 'CA',
+   *   country: 'US',
+   * });
+   * 
+   * // Result:
+   * // {
+   * //   email: '5e884898...', (hashed)
+   * //   phone: 'a1b2c3d4...', (hashed)
+   * //   first_name: 'e5f6g7h8...', (hashed)
+   * //   last_name: 'i9j0k1l2...', (hashed)
+   * //   city: 'san francisco', (normalized, not hashed by default)
+   * //   state: 'ca', (normalized, not hashed by default)
+   * //   country: 'us', (normalized, not hashed by default)
+   * // }
+   * ```
+   */
+  async normalize(raw) {
+    const result = {};
+    if (raw.email) {
+      const h = await this.hashEmail(raw.email);
+      if (h) result.email = h;
+    }
+    if (raw.phone) {
+      const h = await this.hashPhone(raw.phone);
+      if (h) result.phone = h;
+    }
+    if (raw.first_name) {
+      const h = await this.hashName(raw.first_name);
+      if (h) result.first_name = h;
+    }
+    if (raw.last_name) {
+      const h = await this.hashName(raw.last_name);
+      if (h) result.last_name = h;
+    }
+    if (raw.gender) {
+      const h = await this.hashGender(raw.gender);
+      if (h) result.gender = h;
+    }
+    if (raw.date_of_birth) {
+      const h = await this.hashDateOfBirth(raw.date_of_birth);
+      if (h) result.date_of_birth = h;
+    }
+    if (raw.external_id) {
+      const h = await this.hashExternalId(raw.external_id);
+      if (h) result.external_id = h;
+    }
+    if (raw.city) {
+      if (this.options.hashAddressFields) {
+        const h = await this.hashCity(raw.city);
+        if (h) result.city = h;
+      } else {
+        result.city = raw.city;
+      }
+    }
+    if (raw.state) {
+      if (this.options.hashAddressFields) {
+        const h = await this.hashState(raw.state);
+        if (h) result.state = h;
+      } else {
+        result.state = raw.state;
+      }
+    }
+    if (raw.zip_code) {
+      if (this.options.hashAddressFields) {
+        const h = await this.hashZipCode(raw.zip_code);
+        if (h) result.zip_code = h;
+      } else {
+        result.zip_code = raw.zip_code;
+      }
+    }
+    if (raw.country) {
+      if (this.options.hashAddressFields) {
+        const h = await this.hashCountry(raw.country);
+        if (h) result.country = h;
+      } else {
+        result.country = raw.country;
+      }
+    }
+    if (raw.ip_address) result.ip_address = raw.ip_address;
+    if (raw.user_agent) result.user_agent = raw.user_agent;
+    if (raw.subscription_id) result.subscription_id = raw.subscription_id;
+    if (raw.lead_id) result.lead_id = raw.lead_id;
+    if (raw.anonymous_id) result.anonymous_id = raw.anonymous_id;
+    if (raw.traits) result.traits = raw.traits;
+    return result;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Normalizer,
+  isSha256,
+  sha256
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/hash.ts","../src/Normalizer.ts"],"sourcesContent":["/**\n * @sygnl/normalizer\n * \n * PII normalization and SHA256 hashing for Meta CAPI and ad platforms.\n * \n * @example\n * ```typescript\n * import { Normalizer } from '@sygnl/normalizer';\n * \n * const normalizer = new Normalizer();\n * \n * // Normalize and hash user data\n * const normalized = await normalizer.normalize({\n *   email: 'JOHN@EXAMPLE.COM',\n *   phone: '555-123-4567',\n *   first_name: 'John',\n *   last_name: 'Doe',\n * });\n * \n * // Or use individual methods\n * const emailHash = await normalizer.hashEmail('john@example.com');\n * const phoneHash = await normalizer.hashPhone('555-123-4567');\n * ```\n */\n\nexport { Normalizer } from './Normalizer';\nexport { sha256, isSha256 } from './hash';\nexport type {\n  Sha256Hash,\n  RawUserData,\n  NormalizedUserData,\n  NormalizerOptions,\n} from './types';\n","/**\n * SHA256 Hashing Utilities\n * \n * Uses Web Crypto API (available in modern browsers and Node.js 18+)\n * Works in both browser and Cloudflare Workers environments.\n * \n * All PII MUST be normalized before hashing to ensure consistent results.\n */\n\nimport type { Sha256Hash } from './types';\n\n/**\n * SHA256 hash a string using Web Crypto API\n * \n * Returns 64 lowercase hex characters.\n * Works in both browser and Node.js 18+ (Web Crypto API).\n * \n * @param input - String to hash (should be normalized first)\n * @returns Promise resolving to 64-character lowercase hex string\n * \n * @example\n * ```typescript\n * const hash = await sha256('hello@example.com');\n * // Returns: \"5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8\"\n * ```\n */\nexport async function sha256(input: string): Promise<Sha256Hash> {\n  const encoder = new TextEncoder();\n  const data = encoder.encode(input);\n  const hashBuffer = await crypto.subtle.digest('SHA-256', data);\n  const hashArray = Array.from(new Uint8Array(hashBuffer));\n  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');\n  return hashHex as Sha256Hash;\n}\n\n/**\n * Validate that a string is a valid SHA256 hash\n * \n * Checks for 64 lowercase hexadecimal characters.\n * \n * @param value - String to validate\n * @returns true if valid SHA256 hash format\n * \n * @example\n * ```typescript\n * isSha256('abc123');  // false\n * isSha256('5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8');  // true\n * ```\n */\nexport function isSha256(value: string): value is Sha256Hash {\n  return /^[a-f0-9]{64}$/.test(value);\n}\n","/**\n * Normalizer Class\n * \n * Normalizes and hashes PII fields for ad platform APIs (Meta CAPI, Google Ads, etc.)\n * \n * Normalization rules ensure consistent hashing:\n * - Email: lowercase, trim\n * - Phone: E.164 format (+15551234567)\n * - Name: lowercase, trim, single spaces\n * - Gender: single char (m/f)\n * - Date of Birth: YYYYMMDD format\n * - Address: lowercase, trim, format-specific rules\n * \n * Meta CAPI Hashing Requirements:\n * - HASH: email, phone, first_name, last_name, gender, date_of_birth, city, state, zip_code, country, external_id\n * - DO NOT HASH: ip_address, user_agent, fbc, fbp, subscription_id, lead_id\n */\n\nimport type { NormalizerOptions, RawUserData, NormalizedUserData, Sha256Hash } from './types';\nimport { sha256 } from './hash';\n\nexport class Normalizer {\n  private options: Required<NormalizerOptions>;\n\n  constructor(options: NormalizerOptions = {}) {\n    this.options = {\n      defaultCountryCode: options.defaultCountryCode ?? '1',\n      hashAddressFields: options.hashAddressFields ?? false,\n    };\n  }\n\n  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   * NORMALIZATION METHODS\n   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */\n\n  /**\n   * Normalize email: lowercase, trim whitespace\n   * Returns null if invalid format\n   */\n  normalizeEmail(email: string): string | null {\n    if (!email || typeof email !== 'string') return null;\n    const normalized = email.toLowerCase().trim();\n    if (!normalized.includes('@') || normalized.length < 5) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize phone to E.164 format (+15551234567)\n   * Returns null if invalid\n   */\n  normalizePhone(phone: string, countryCode?: string): string | null {\n    if (!phone || typeof phone !== 'string') return null;\n    const code = countryCode ?? this.options.defaultCountryCode;\n    let digits = phone.replace(/[^\\d+]/g, '');\n    if (digits.startsWith('+')) digits = digits.slice(1);\n    if (digits.length < 10) return null;\n    if (digits.length === 10) digits = code + digits;\n    return '+' + digits;\n  }\n\n  /**\n   * Normalize name: lowercase, trim, remove extra spaces\n   * Returns null if empty\n   */\n  normalizeName(name: string): string | null {\n    if (!name || typeof name !== 'string') return null;\n    const normalized = name.toLowerCase().trim().replace(/\\s+/g, ' ');\n    if (normalized.length === 0) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize gender: single lowercase char (m/f)\n   * Accepts: m, male, f, female\n   * Returns null if invalid\n   */\n  normalizeGender(gender: string): string | null {\n    if (!gender || typeof gender !== 'string') return null;\n    const g = gender.toLowerCase().trim();\n    if (g === 'm' || g === 'male') return 'm';\n    if (g === 'f' || g === 'female') return 'f';\n    return null;\n  }\n\n  /**\n   * Normalize date of birth: YYYYMMDD format\n   * Accepts formats: YYYY-MM-DD, YYYY/MM/DD, YYYY.MM.DD, YYYYMMDD\n   * Returns null if invalid\n   */\n  normalizeDateOfBirth(dob: string): string | null {\n    if (!dob || typeof dob !== 'string') return null;\n    const cleaned = dob.replace(/[-\\/\\.]/g, '');\n    if (!/^\\d{8}$/.test(cleaned)) return null;\n    return cleaned;\n  }\n\n  /**\n   * Normalize city: lowercase, trim\n   */\n  normalizeCity(city: string): string | null {\n    if (!city || typeof city !== 'string') return null;\n    const normalized = city.toLowerCase().trim();\n    if (normalized.length === 0) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize state/region: lowercase, trim\n   */\n  normalizeState(state: string): string | null {\n    if (!state || typeof state !== 'string') return null;\n    const normalized = state.toLowerCase().trim();\n    if (normalized.length === 0) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize zip/postal code: lowercase, no spaces\n   */\n  normalizeZipCode(zip: string): string | null {\n    if (!zip || typeof zip !== 'string') return null;\n    const normalized = zip.toLowerCase().trim().replace(/\\s+/g, '');\n    if (normalized.length === 0) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize country: 2-letter code, lowercase\n   * Returns null if not exactly 2 characters\n   */\n  normalizeCountry(country: string): string | null {\n    if (!country || typeof country !== 'string') return null;\n    const normalized = country.toLowerCase().trim();\n    if (normalized.length !== 2) return null;\n    return normalized;\n  }\n\n  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   * HASH METHODS\n   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */\n\n  /**\n   * Hash email (normalize then hash)\n   */\n  async hashEmail(email: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeEmail(email);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash phone (normalize then hash)\n   */\n  async hashPhone(phone: string, countryCode?: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizePhone(phone, countryCode);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash name (normalize then hash)\n   */\n  async hashName(name: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeName(name);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash gender (normalize then hash)\n   */\n  async hashGender(gender: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeGender(gender);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash date of birth (normalize then hash)\n   */\n  async hashDateOfBirth(dob: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeDateOfBirth(dob);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash city (normalize then hash)\n   */\n  async hashCity(city: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeCity(city);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash state (normalize then hash)\n   */\n  async hashState(state: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeState(state);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash zip code (normalize then hash)\n   */\n  async hashZipCode(zip: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeZipCode(zip);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash country (normalize then hash)\n   */\n  async hashCountry(country: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeCountry(country);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash external ID (trim only, no other normalization)\n   */\n  async hashExternalId(externalId: string): Promise<Sha256Hash | null> {\n    if (!externalId || typeof externalId !== 'string') return null;\n    return sha256(externalId.trim());\n  }\n\n  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   * BATCH NORMALIZATION\n   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */\n\n  /**\n   * Normalize and hash all user data\n   * \n   * Raw PII in, hashed data out.\n   * \n   * @param raw - Raw user data (unhashed PII)\n   * @returns Normalized and hashed user data\n   * \n   * @example\n   * ```typescript\n   * const normalizer = new Normalizer();\n   * const normalized = await normalizer.normalize({\n   *   email: 'JOHN@EXAMPLE.COM',\n   *   phone: '555-123-4567',\n   *   first_name: 'John',\n   *   last_name: 'Doe',\n   *   city: 'San Francisco',\n   *   state: 'CA',\n   *   country: 'US',\n   * });\n   * \n   * // Result:\n   * // {\n   * //   email: '5e884898...', (hashed)\n   * //   phone: 'a1b2c3d4...', (hashed)\n   * //   first_name: 'e5f6g7h8...', (hashed)\n   * //   last_name: 'i9j0k1l2...', (hashed)\n   * //   city: 'san francisco', (normalized, not hashed by default)\n   * //   state: 'ca', (normalized, not hashed by default)\n   * //   country: 'us', (normalized, not hashed by default)\n   * // }\n   * ```\n   */\n  async normalize(raw: RawUserData): Promise<NormalizedUserData> {\n    const result: NormalizedUserData = {};\n\n    // Hash contact PII\n    if (raw.email) {\n      const h = await this.hashEmail(raw.email);\n      if (h) result.email = h;\n    }\n    if (raw.phone) {\n      const h = await this.hashPhone(raw.phone);\n      if (h) result.phone = h;\n    }\n    if (raw.first_name) {\n      const h = await this.hashName(raw.first_name);\n      if (h) result.first_name = h;\n    }\n    if (raw.last_name) {\n      const h = await this.hashName(raw.last_name);\n      if (h) result.last_name = h;\n    }\n    if (raw.gender) {\n      const h = await this.hashGender(raw.gender);\n      if (h) result.gender = h;\n    }\n    if (raw.date_of_birth) {\n      const h = await this.hashDateOfBirth(raw.date_of_birth);\n      if (h) result.date_of_birth = h;\n    }\n    if (raw.external_id) {\n      const h = await this.hashExternalId(raw.external_id);\n      if (h) result.external_id = h;\n    }\n\n    // Address fields - hash only if configured to do so\n    if (raw.city) {\n      if (this.options.hashAddressFields) {\n        const h = await this.hashCity(raw.city);\n        if (h) result.city = h as unknown as string;\n      } else {\n        result.city = raw.city;\n      }\n    }\n    if (raw.state) {\n      if (this.options.hashAddressFields) {\n        const h = await this.hashState(raw.state);\n        if (h) result.state = h as unknown as string;\n      } else {\n        result.state = raw.state;\n      }\n    }\n    if (raw.zip_code) {\n      if (this.options.hashAddressFields) {\n        const h = await this.hashZipCode(raw.zip_code);\n        if (h) result.zip_code = h as unknown as string;\n      } else {\n        result.zip_code = raw.zip_code;\n      }\n    }\n    if (raw.country) {\n      if (this.options.hashAddressFields) {\n        const h = await this.hashCountry(raw.country);\n        if (h) result.country = h as unknown as string;\n      } else {\n        result.country = raw.country;\n      }\n    }\n\n    // Pass through unhashed fields\n    if (raw.ip_address) result.ip_address = raw.ip_address;\n    if (raw.user_agent) result.user_agent = raw.user_agent;\n    if (raw.subscription_id) result.subscription_id = raw.subscription_id;\n    if (raw.lead_id) result.lead_id = raw.lead_id;\n    if (raw.anonymous_id) result.anonymous_id = raw.anonymous_id;\n    if (raw.traits) result.traits = raw.traits;\n\n    return result;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,263 @@
+/**
+ * Type definitions for PII normalization and hashing
+ */
+/**
+ * SHA256 hash: 64 lowercase hex characters
+ */
+type Sha256Hash = string & {
+    __brand: 'Sha256Hash';
+};
+/**
+ * Raw user data (before normalization/hashing)
+ *
+ * Fields to HASH (according to Meta CAPI requirements):
+ * - email, phone, first_name, last_name, gender, date_of_birth
+ * - city, state, zip_code, country, external_id
+ *
+ * Fields to NOT hash (pass through as-is):
+ * - ip_address, user_agent, fbc, fbp, subscription_id, lead_id, anonymous_id
+ */
+interface RawUserData {
+    email?: string;
+    phone?: string;
+    first_name?: string;
+    last_name?: string;
+    gender?: string;
+    date_of_birth?: string;
+    external_id?: string;
+    city?: string;
+    state?: string;
+    zip_code?: string;
+    country?: string;
+    ip_address?: string;
+    user_agent?: string;
+    subscription_id?: string;
+    lead_id?: string;
+    anonymous_id?: string;
+    traits?: Record<string, unknown>;
+}
+/**
+ * Normalized user data (after hashing)
+ *
+ * All PII fields are hashed with SHA256.
+ * Tracking IDs and non-PII fields pass through unchanged.
+ */
+interface NormalizedUserData {
+    email?: Sha256Hash;
+    phone?: Sha256Hash;
+    first_name?: Sha256Hash;
+    last_name?: Sha256Hash;
+    gender?: Sha256Hash;
+    date_of_birth?: Sha256Hash;
+    external_id?: Sha256Hash;
+    city?: string;
+    state?: string;
+    zip_code?: string;
+    country?: string;
+    ip_address?: string;
+    user_agent?: string;
+    subscription_id?: string;
+    lead_id?: string;
+    anonymous_id?: string;
+    traits?: Record<string, unknown>;
+}
+/**
+ * Options for the Normalizer
+ */
+interface NormalizerOptions {
+    /**
+     * Default country code for phone normalization (e.g., '1' for USA)
+     * @default '1'
+     */
+    defaultCountryCode?: string;
+    /**
+     * Whether to hash address fields (city, state, zip, country)
+     * Some platforms require raw values, others require hashed
+     * @default false
+     */
+    hashAddressFields?: boolean;
+}
+
+/**
+ * Normalizer Class
+ *
+ * Normalizes and hashes PII fields for ad platform APIs (Meta CAPI, Google Ads, etc.)
+ *
+ * Normalization rules ensure consistent hashing:
+ * - Email: lowercase, trim
+ * - Phone: E.164 format (+15551234567)
+ * - Name: lowercase, trim, single spaces
+ * - Gender: single char (m/f)
+ * - Date of Birth: YYYYMMDD format
+ * - Address: lowercase, trim, format-specific rules
+ *
+ * Meta CAPI Hashing Requirements:
+ * - HASH: email, phone, first_name, last_name, gender, date_of_birth, city, state, zip_code, country, external_id
+ * - DO NOT HASH: ip_address, user_agent, fbc, fbp, subscription_id, lead_id
+ */
+
+declare class Normalizer {
+    private options;
+    constructor(options?: NormalizerOptions);
+    /**
+     * Normalize email: lowercase, trim whitespace
+     * Returns null if invalid format
+     */
+    normalizeEmail(email: string): string | null;
+    /**
+     * Normalize phone to E.164 format (+15551234567)
+     * Returns null if invalid
+     */
+    normalizePhone(phone: string, countryCode?: string): string | null;
+    /**
+     * Normalize name: lowercase, trim, remove extra spaces
+     * Returns null if empty
+     */
+    normalizeName(name: string): string | null;
+    /**
+     * Normalize gender: single lowercase char (m/f)
+     * Accepts: m, male, f, female
+     * Returns null if invalid
+     */
+    normalizeGender(gender: string): string | null;
+    /**
+     * Normalize date of birth: YYYYMMDD format
+     * Accepts formats: YYYY-MM-DD, YYYY/MM/DD, YYYY.MM.DD, YYYYMMDD
+     * Returns null if invalid
+     */
+    normalizeDateOfBirth(dob: string): string | null;
+    /**
+     * Normalize city: lowercase, trim
+     */
+    normalizeCity(city: string): string | null;
+    /**
+     * Normalize state/region: lowercase, trim
+     */
+    normalizeState(state: string): string | null;
+    /**
+     * Normalize zip/postal code: lowercase, no spaces
+     */
+    normalizeZipCode(zip: string): string | null;
+    /**
+     * Normalize country: 2-letter code, lowercase
+     * Returns null if not exactly 2 characters
+     */
+    normalizeCountry(country: string): string | null;
+    /**
+     * Hash email (normalize then hash)
+     */
+    hashEmail(email: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash phone (normalize then hash)
+     */
+    hashPhone(phone: string, countryCode?: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash name (normalize then hash)
+     */
+    hashName(name: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash gender (normalize then hash)
+     */
+    hashGender(gender: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash date of birth (normalize then hash)
+     */
+    hashDateOfBirth(dob: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash city (normalize then hash)
+     */
+    hashCity(city: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash state (normalize then hash)
+     */
+    hashState(state: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash zip code (normalize then hash)
+     */
+    hashZipCode(zip: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash country (normalize then hash)
+     */
+    hashCountry(country: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash external ID (trim only, no other normalization)
+     */
+    hashExternalId(externalId: string): Promise<Sha256Hash | null>;
+    /**
+     * Normalize and hash all user data
+     *
+     * Raw PII in, hashed data out.
+     *
+     * @param raw - Raw user data (unhashed PII)
+     * @returns Normalized and hashed user data
+     *
+     * @example
+     * ```typescript
+     * const normalizer = new Normalizer();
+     * const normalized = await normalizer.normalize({
+     *   email: 'JOHN@EXAMPLE.COM',
+     *   phone: '555-123-4567',
+     *   first_name: 'John',
+     *   last_name: 'Doe',
+     *   city: 'San Francisco',
+     *   state: 'CA',
+     *   country: 'US',
+     * });
+     *
+     * // Result:
+     * // {
+     * //   email: '5e884898...', (hashed)
+     * //   phone: 'a1b2c3d4...', (hashed)
+     * //   first_name: 'e5f6g7h8...', (hashed)
+     * //   last_name: 'i9j0k1l2...', (hashed)
+     * //   city: 'san francisco', (normalized, not hashed by default)
+     * //   state: 'ca', (normalized, not hashed by default)
+     * //   country: 'us', (normalized, not hashed by default)
+     * // }
+     * ```
+     */
+    normalize(raw: RawUserData): Promise<NormalizedUserData>;
+}
+
+/**
+ * SHA256 Hashing Utilities
+ *
+ * Uses Web Crypto API (available in modern browsers and Node.js 18+)
+ * Works in both browser and Cloudflare Workers environments.
+ *
+ * All PII MUST be normalized before hashing to ensure consistent results.
+ */
+
+/**
+ * SHA256 hash a string using Web Crypto API
+ *
+ * Returns 64 lowercase hex characters.
+ * Works in both browser and Node.js 18+ (Web Crypto API).
+ *
+ * @param input - String to hash (should be normalized first)
+ * @returns Promise resolving to 64-character lowercase hex string
+ *
+ * @example
+ * ```typescript
+ * const hash = await sha256('hello@example.com');
+ * // Returns: "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
+ * ```
+ */
+declare function sha256(input: string): Promise<Sha256Hash>;
+/**
+ * Validate that a string is a valid SHA256 hash
+ *
+ * Checks for 64 lowercase hexadecimal characters.
+ *
+ * @param value - String to validate
+ * @returns true if valid SHA256 hash format
+ *
+ * @example
+ * ```typescript
+ * isSha256('abc123');  // false
+ * isSha256('5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8');  // true
+ * ```
+ */
+declare function isSha256(value: string): value is Sha256Hash;
+
+export { type NormalizedUserData, Normalizer, type NormalizerOptions, type RawUserData, type Sha256Hash, isSha256, sha256 };

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Type definitions for PII normalization and hashing
+ */
+/**
+ * SHA256 hash: 64 lowercase hex characters
+ */
+type Sha256Hash = string & {
+    __brand: 'Sha256Hash';
+};
+/**
+ * Raw user data (before normalization/hashing)
+ *
+ * Fields to HASH (according to Meta CAPI requirements):
+ * - email, phone, first_name, last_name, gender, date_of_birth
+ * - city, state, zip_code, country, external_id
+ *
+ * Fields to NOT hash (pass through as-is):
+ * - ip_address, user_agent, fbc, fbp, subscription_id, lead_id, anonymous_id
+ */
+interface RawUserData {
+    email?: string;
+    phone?: string;
+    first_name?: string;
+    last_name?: string;
+    gender?: string;
+    date_of_birth?: string;
+    external_id?: string;
+    city?: string;
+    state?: string;
+    zip_code?: string;
+    country?: string;
+    ip_address?: string;
+    user_agent?: string;
+    subscription_id?: string;
+    lead_id?: string;
+    anonymous_id?: string;
+    traits?: Record<string, unknown>;
+}
+/**
+ * Normalized user data (after hashing)
+ *
+ * All PII fields are hashed with SHA256.
+ * Tracking IDs and non-PII fields pass through unchanged.
+ */
+interface NormalizedUserData {
+    email?: Sha256Hash;
+    phone?: Sha256Hash;
+    first_name?: Sha256Hash;
+    last_name?: Sha256Hash;
+    gender?: Sha256Hash;
+    date_of_birth?: Sha256Hash;
+    external_id?: Sha256Hash;
+    city?: string;
+    state?: string;
+    zip_code?: string;
+    country?: string;
+    ip_address?: string;
+    user_agent?: string;
+    subscription_id?: string;
+    lead_id?: string;
+    anonymous_id?: string;
+    traits?: Record<string, unknown>;
+}
+/**
+ * Options for the Normalizer
+ */
+interface NormalizerOptions {
+    /**
+     * Default country code for phone normalization (e.g., '1' for USA)
+     * @default '1'
+     */
+    defaultCountryCode?: string;
+    /**
+     * Whether to hash address fields (city, state, zip, country)
+     * Some platforms require raw values, others require hashed
+     * @default false
+     */
+    hashAddressFields?: boolean;
+}
+
+/**
+ * Normalizer Class
+ *
+ * Normalizes and hashes PII fields for ad platform APIs (Meta CAPI, Google Ads, etc.)
+ *
+ * Normalization rules ensure consistent hashing:
+ * - Email: lowercase, trim
+ * - Phone: E.164 format (+15551234567)
+ * - Name: lowercase, trim, single spaces
+ * - Gender: single char (m/f)
+ * - Date of Birth: YYYYMMDD format
+ * - Address: lowercase, trim, format-specific rules
+ *
+ * Meta CAPI Hashing Requirements:
+ * - HASH: email, phone, first_name, last_name, gender, date_of_birth, city, state, zip_code, country, external_id
+ * - DO NOT HASH: ip_address, user_agent, fbc, fbp, subscription_id, lead_id
+ */
+
+declare class Normalizer {
+    private options;
+    constructor(options?: NormalizerOptions);
+    /**
+     * Normalize email: lowercase, trim whitespace
+     * Returns null if invalid format
+     */
+    normalizeEmail(email: string): string | null;
+    /**
+     * Normalize phone to E.164 format (+15551234567)
+     * Returns null if invalid
+     */
+    normalizePhone(phone: string, countryCode?: string): string | null;
+    /**
+     * Normalize name: lowercase, trim, remove extra spaces
+     * Returns null if empty
+     */
+    normalizeName(name: string): string | null;
+    /**
+     * Normalize gender: single lowercase char (m/f)
+     * Accepts: m, male, f, female
+     * Returns null if invalid
+     */
+    normalizeGender(gender: string): string | null;
+    /**
+     * Normalize date of birth: YYYYMMDD format
+     * Accepts formats: YYYY-MM-DD, YYYY/MM/DD, YYYY.MM.DD, YYYYMMDD
+     * Returns null if invalid
+     */
+    normalizeDateOfBirth(dob: string): string | null;
+    /**
+     * Normalize city: lowercase, trim
+     */
+    normalizeCity(city: string): string | null;
+    /**
+     * Normalize state/region: lowercase, trim
+     */
+    normalizeState(state: string): string | null;
+    /**
+     * Normalize zip/postal code: lowercase, no spaces
+     */
+    normalizeZipCode(zip: string): string | null;
+    /**
+     * Normalize country: 2-letter code, lowercase
+     * Returns null if not exactly 2 characters
+     */
+    normalizeCountry(country: string): string | null;
+    /**
+     * Hash email (normalize then hash)
+     */
+    hashEmail(email: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash phone (normalize then hash)
+     */
+    hashPhone(phone: string, countryCode?: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash name (normalize then hash)
+     */
+    hashName(name: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash gender (normalize then hash)
+     */
+    hashGender(gender: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash date of birth (normalize then hash)
+     */
+    hashDateOfBirth(dob: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash city (normalize then hash)
+     */
+    hashCity(city: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash state (normalize then hash)
+     */
+    hashState(state: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash zip code (normalize then hash)
+     */
+    hashZipCode(zip: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash country (normalize then hash)
+     */
+    hashCountry(country: string): Promise<Sha256Hash | null>;
+    /**
+     * Hash external ID (trim only, no other normalization)
+     */
+    hashExternalId(externalId: string): Promise<Sha256Hash | null>;
+    /**
+     * Normalize and hash all user data
+     *
+     * Raw PII in, hashed data out.
+     *
+     * @param raw - Raw user data (unhashed PII)
+     * @returns Normalized and hashed user data
+     *
+     * @example
+     * ```typescript
+     * const normalizer = new Normalizer();
+     * const normalized = await normalizer.normalize({
+     *   email: 'JOHN@EXAMPLE.COM',
+     *   phone: '555-123-4567',
+     *   first_name: 'John',
+     *   last_name: 'Doe',
+     *   city: 'San Francisco',
+     *   state: 'CA',
+     *   country: 'US',
+     * });
+     *
+     * // Result:
+     * // {
+     * //   email: '5e884898...', (hashed)
+     * //   phone: 'a1b2c3d4...', (hashed)
+     * //   first_name: 'e5f6g7h8...', (hashed)
+     * //   last_name: 'i9j0k1l2...', (hashed)
+     * //   city: 'san francisco', (normalized, not hashed by default)
+     * //   state: 'ca', (normalized, not hashed by default)
+     * //   country: 'us', (normalized, not hashed by default)
+     * // }
+     * ```
+     */
+    normalize(raw: RawUserData): Promise<NormalizedUserData>;
+}
+
+/**
+ * SHA256 Hashing Utilities
+ *
+ * Uses Web Crypto API (available in modern browsers and Node.js 18+)
+ * Works in both browser and Cloudflare Workers environments.
+ *
+ * All PII MUST be normalized before hashing to ensure consistent results.
+ */
+
+/**
+ * SHA256 hash a string using Web Crypto API
+ *
+ * Returns 64 lowercase hex characters.
+ * Works in both browser and Node.js 18+ (Web Crypto API).
+ *
+ * @param input - String to hash (should be normalized first)
+ * @returns Promise resolving to 64-character lowercase hex string
+ *
+ * @example
+ * ```typescript
+ * const hash = await sha256('hello@example.com');
+ * // Returns: "5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"
+ * ```
+ */
+declare function sha256(input: string): Promise<Sha256Hash>;
+/**
+ * Validate that a string is a valid SHA256 hash
+ *
+ * Checks for 64 lowercase hexadecimal characters.
+ *
+ * @param value - String to validate
+ * @returns true if valid SHA256 hash format
+ *
+ * @example
+ * ```typescript
+ * isSha256('abc123');  // false
+ * isSha256('5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8');  // true
+ * ```
+ */
+declare function isSha256(value: string): value is Sha256Hash;
+
+export { type NormalizedUserData, Normalizer, type NormalizerOptions, type RawUserData, type Sha256Hash, isSha256, sha256 };

package/dist/index.js

@@ -0,0 +1,303 @@
+// src/hash.ts
+async function sha256(input) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(input);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+  return hashHex;
+}
+function isSha256(value) {
+  return /^[a-f0-9]{64}$/.test(value);
+}
+
+// src/Normalizer.ts
+var Normalizer = class {
+  constructor(options = {}) {
+    this.options = {
+      defaultCountryCode: options.defaultCountryCode ?? "1",
+      hashAddressFields: options.hashAddressFields ?? false
+    };
+  }
+  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   * NORMALIZATION METHODS
+   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /**
+   * Normalize email: lowercase, trim whitespace
+   * Returns null if invalid format
+   */
+  normalizeEmail(email) {
+    if (!email || typeof email !== "string") return null;
+    const normalized = email.toLowerCase().trim();
+    if (!normalized.includes("@") || normalized.length < 5) return null;
+    return normalized;
+  }
+  /**
+   * Normalize phone to E.164 format (+15551234567)
+   * Returns null if invalid
+   */
+  normalizePhone(phone, countryCode) {
+    if (!phone || typeof phone !== "string") return null;
+    const code = countryCode ?? this.options.defaultCountryCode;
+    let digits = phone.replace(/[^\d+]/g, "");
+    if (digits.startsWith("+")) digits = digits.slice(1);
+    if (digits.length < 10) return null;
+    if (digits.length === 10) digits = code + digits;
+    return "+" + digits;
+  }
+  /**
+   * Normalize name: lowercase, trim, remove extra spaces
+   * Returns null if empty
+   */
+  normalizeName(name) {
+    if (!name || typeof name !== "string") return null;
+    const normalized = name.toLowerCase().trim().replace(/\s+/g, " ");
+    if (normalized.length === 0) return null;
+    return normalized;
+  }
+  /**
+   * Normalize gender: single lowercase char (m/f)
+   * Accepts: m, male, f, female
+   * Returns null if invalid
+   */
+  normalizeGender(gender) {
+    if (!gender || typeof gender !== "string") return null;
+    const g = gender.toLowerCase().trim();
+    if (g === "m" || g === "male") return "m";
+    if (g === "f" || g === "female") return "f";
+    return null;
+  }
+  /**
+   * Normalize date of birth: YYYYMMDD format
+   * Accepts formats: YYYY-MM-DD, YYYY/MM/DD, YYYY.MM.DD, YYYYMMDD
+   * Returns null if invalid
+   */
+  normalizeDateOfBirth(dob) {
+    if (!dob || typeof dob !== "string") return null;
+    const cleaned = dob.replace(/[-\/\.]/g, "");
+    if (!/^\d{8}$/.test(cleaned)) return null;
+    return cleaned;
+  }
+  /**
+   * Normalize city: lowercase, trim
+   */
+  normalizeCity(city) {
+    if (!city || typeof city !== "string") return null;
+    const normalized = city.toLowerCase().trim();
+    if (normalized.length === 0) return null;
+    return normalized;
+  }
+  /**
+   * Normalize state/region: lowercase, trim
+   */
+  normalizeState(state) {
+    if (!state || typeof state !== "string") return null;
+    const normalized = state.toLowerCase().trim();
+    if (normalized.length === 0) return null;
+    return normalized;
+  }
+  /**
+   * Normalize zip/postal code: lowercase, no spaces
+   */
+  normalizeZipCode(zip) {
+    if (!zip || typeof zip !== "string") return null;
+    const normalized = zip.toLowerCase().trim().replace(/\s+/g, "");
+    if (normalized.length === 0) return null;
+    return normalized;
+  }
+  /**
+   * Normalize country: 2-letter code, lowercase
+   * Returns null if not exactly 2 characters
+   */
+  normalizeCountry(country) {
+    if (!country || typeof country !== "string") return null;
+    const normalized = country.toLowerCase().trim();
+    if (normalized.length !== 2) return null;
+    return normalized;
+  }
+  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   * HASH METHODS
+   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /**
+   * Hash email (normalize then hash)
+   */
+  async hashEmail(email) {
+    const normalized = this.normalizeEmail(email);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash phone (normalize then hash)
+   */
+  async hashPhone(phone, countryCode) {
+    const normalized = this.normalizePhone(phone, countryCode);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash name (normalize then hash)
+   */
+  async hashName(name) {
+    const normalized = this.normalizeName(name);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash gender (normalize then hash)
+   */
+  async hashGender(gender) {
+    const normalized = this.normalizeGender(gender);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash date of birth (normalize then hash)
+   */
+  async hashDateOfBirth(dob) {
+    const normalized = this.normalizeDateOfBirth(dob);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash city (normalize then hash)
+   */
+  async hashCity(city) {
+    const normalized = this.normalizeCity(city);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash state (normalize then hash)
+   */
+  async hashState(state) {
+    const normalized = this.normalizeState(state);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash zip code (normalize then hash)
+   */
+  async hashZipCode(zip) {
+    const normalized = this.normalizeZipCode(zip);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash country (normalize then hash)
+   */
+  async hashCountry(country) {
+    const normalized = this.normalizeCountry(country);
+    return normalized ? sha256(normalized) : null;
+  }
+  /**
+   * Hash external ID (trim only, no other normalization)
+   */
+  async hashExternalId(externalId) {
+    if (!externalId || typeof externalId !== "string") return null;
+    return sha256(externalId.trim());
+  }
+  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   * BATCH NORMALIZATION
+   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */
+  /**
+   * Normalize and hash all user data
+   * 
+   * Raw PII in, hashed data out.
+   * 
+   * @param raw - Raw user data (unhashed PII)
+   * @returns Normalized and hashed user data
+   * 
+   * @example
+   * ```typescript
+   * const normalizer = new Normalizer();
+   * const normalized = await normalizer.normalize({
+   *   email: 'JOHN@EXAMPLE.COM',
+   *   phone: '555-123-4567',
+   *   first_name: 'John',
+   *   last_name: 'Doe',
+   *   city: 'San Francisco',
+   *   state: 'CA',
+   *   country: 'US',
+   * });
+   * 
+   * // Result:
+   * // {
+   * //   email: '5e884898...', (hashed)
+   * //   phone: 'a1b2c3d4...', (hashed)
+   * //   first_name: 'e5f6g7h8...', (hashed)
+   * //   last_name: 'i9j0k1l2...', (hashed)
+   * //   city: 'san francisco', (normalized, not hashed by default)
+   * //   state: 'ca', (normalized, not hashed by default)
+   * //   country: 'us', (normalized, not hashed by default)
+   * // }
+   * ```
+   */
+  async normalize(raw) {
+    const result = {};
+    if (raw.email) {
+      const h = await this.hashEmail(raw.email);
+      if (h) result.email = h;
+    }
+    if (raw.phone) {
+      const h = await this.hashPhone(raw.phone);
+      if (h) result.phone = h;
+    }
+    if (raw.first_name) {
+      const h = await this.hashName(raw.first_name);
+      if (h) result.first_name = h;
+    }
+    if (raw.last_name) {
+      const h = await this.hashName(raw.last_name);
+      if (h) result.last_name = h;
+    }
+    if (raw.gender) {
+      const h = await this.hashGender(raw.gender);
+      if (h) result.gender = h;
+    }
+    if (raw.date_of_birth) {
+      const h = await this.hashDateOfBirth(raw.date_of_birth);
+      if (h) result.date_of_birth = h;
+    }
+    if (raw.external_id) {
+      const h = await this.hashExternalId(raw.external_id);
+      if (h) result.external_id = h;
+    }
+    if (raw.city) {
+      if (this.options.hashAddressFields) {
+        const h = await this.hashCity(raw.city);
+        if (h) result.city = h;
+      } else {
+        result.city = raw.city;
+      }
+    }
+    if (raw.state) {
+      if (this.options.hashAddressFields) {
+        const h = await this.hashState(raw.state);
+        if (h) result.state = h;
+      } else {
+        result.state = raw.state;
+      }
+    }
+    if (raw.zip_code) {
+      if (this.options.hashAddressFields) {
+        const h = await this.hashZipCode(raw.zip_code);
+        if (h) result.zip_code = h;
+      } else {
+        result.zip_code = raw.zip_code;
+      }
+    }
+    if (raw.country) {
+      if (this.options.hashAddressFields) {
+        const h = await this.hashCountry(raw.country);
+        if (h) result.country = h;
+      } else {
+        result.country = raw.country;
+      }
+    }
+    if (raw.ip_address) result.ip_address = raw.ip_address;
+    if (raw.user_agent) result.user_agent = raw.user_agent;
+    if (raw.subscription_id) result.subscription_id = raw.subscription_id;
+    if (raw.lead_id) result.lead_id = raw.lead_id;
+    if (raw.anonymous_id) result.anonymous_id = raw.anonymous_id;
+    if (raw.traits) result.traits = raw.traits;
+    return result;
+  }
+};
+export {
+  Normalizer,
+  isSha256,
+  sha256
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hash.ts","../src/Normalizer.ts"],"sourcesContent":["/**\n * SHA256 Hashing Utilities\n * \n * Uses Web Crypto API (available in modern browsers and Node.js 18+)\n * Works in both browser and Cloudflare Workers environments.\n * \n * All PII MUST be normalized before hashing to ensure consistent results.\n */\n\nimport type { Sha256Hash } from './types';\n\n/**\n * SHA256 hash a string using Web Crypto API\n * \n * Returns 64 lowercase hex characters.\n * Works in both browser and Node.js 18+ (Web Crypto API).\n * \n * @param input - String to hash (should be normalized first)\n * @returns Promise resolving to 64-character lowercase hex string\n * \n * @example\n * ```typescript\n * const hash = await sha256('hello@example.com');\n * // Returns: \"5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8\"\n * ```\n */\nexport async function sha256(input: string): Promise<Sha256Hash> {\n  const encoder = new TextEncoder();\n  const data = encoder.encode(input);\n  const hashBuffer = await crypto.subtle.digest('SHA-256', data);\n  const hashArray = Array.from(new Uint8Array(hashBuffer));\n  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');\n  return hashHex as Sha256Hash;\n}\n\n/**\n * Validate that a string is a valid SHA256 hash\n * \n * Checks for 64 lowercase hexadecimal characters.\n * \n * @param value - String to validate\n * @returns true if valid SHA256 hash format\n * \n * @example\n * ```typescript\n * isSha256('abc123');  // false\n * isSha256('5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8');  // true\n * ```\n */\nexport function isSha256(value: string): value is Sha256Hash {\n  return /^[a-f0-9]{64}$/.test(value);\n}\n","/**\n * Normalizer Class\n * \n * Normalizes and hashes PII fields for ad platform APIs (Meta CAPI, Google Ads, etc.)\n * \n * Normalization rules ensure consistent hashing:\n * - Email: lowercase, trim\n * - Phone: E.164 format (+15551234567)\n * - Name: lowercase, trim, single spaces\n * - Gender: single char (m/f)\n * - Date of Birth: YYYYMMDD format\n * - Address: lowercase, trim, format-specific rules\n * \n * Meta CAPI Hashing Requirements:\n * - HASH: email, phone, first_name, last_name, gender, date_of_birth, city, state, zip_code, country, external_id\n * - DO NOT HASH: ip_address, user_agent, fbc, fbp, subscription_id, lead_id\n */\n\nimport type { NormalizerOptions, RawUserData, NormalizedUserData, Sha256Hash } from './types';\nimport { sha256 } from './hash';\n\nexport class Normalizer {\n  private options: Required<NormalizerOptions>;\n\n  constructor(options: NormalizerOptions = {}) {\n    this.options = {\n      defaultCountryCode: options.defaultCountryCode ?? '1',\n      hashAddressFields: options.hashAddressFields ?? false,\n    };\n  }\n\n  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   * NORMALIZATION METHODS\n   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */\n\n  /**\n   * Normalize email: lowercase, trim whitespace\n   * Returns null if invalid format\n   */\n  normalizeEmail(email: string): string | null {\n    if (!email || typeof email !== 'string') return null;\n    const normalized = email.toLowerCase().trim();\n    if (!normalized.includes('@') || normalized.length < 5) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize phone to E.164 format (+15551234567)\n   * Returns null if invalid\n   */\n  normalizePhone(phone: string, countryCode?: string): string | null {\n    if (!phone || typeof phone !== 'string') return null;\n    const code = countryCode ?? this.options.defaultCountryCode;\n    let digits = phone.replace(/[^\\d+]/g, '');\n    if (digits.startsWith('+')) digits = digits.slice(1);\n    if (digits.length < 10) return null;\n    if (digits.length === 10) digits = code + digits;\n    return '+' + digits;\n  }\n\n  /**\n   * Normalize name: lowercase, trim, remove extra spaces\n   * Returns null if empty\n   */\n  normalizeName(name: string): string | null {\n    if (!name || typeof name !== 'string') return null;\n    const normalized = name.toLowerCase().trim().replace(/\\s+/g, ' ');\n    if (normalized.length === 0) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize gender: single lowercase char (m/f)\n   * Accepts: m, male, f, female\n   * Returns null if invalid\n   */\n  normalizeGender(gender: string): string | null {\n    if (!gender || typeof gender !== 'string') return null;\n    const g = gender.toLowerCase().trim();\n    if (g === 'm' || g === 'male') return 'm';\n    if (g === 'f' || g === 'female') return 'f';\n    return null;\n  }\n\n  /**\n   * Normalize date of birth: YYYYMMDD format\n   * Accepts formats: YYYY-MM-DD, YYYY/MM/DD, YYYY.MM.DD, YYYYMMDD\n   * Returns null if invalid\n   */\n  normalizeDateOfBirth(dob: string): string | null {\n    if (!dob || typeof dob !== 'string') return null;\n    const cleaned = dob.replace(/[-\\/\\.]/g, '');\n    if (!/^\\d{8}$/.test(cleaned)) return null;\n    return cleaned;\n  }\n\n  /**\n   * Normalize city: lowercase, trim\n   */\n  normalizeCity(city: string): string | null {\n    if (!city || typeof city !== 'string') return null;\n    const normalized = city.toLowerCase().trim();\n    if (normalized.length === 0) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize state/region: lowercase, trim\n   */\n  normalizeState(state: string): string | null {\n    if (!state || typeof state !== 'string') return null;\n    const normalized = state.toLowerCase().trim();\n    if (normalized.length === 0) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize zip/postal code: lowercase, no spaces\n   */\n  normalizeZipCode(zip: string): string | null {\n    if (!zip || typeof zip !== 'string') return null;\n    const normalized = zip.toLowerCase().trim().replace(/\\s+/g, '');\n    if (normalized.length === 0) return null;\n    return normalized;\n  }\n\n  /**\n   * Normalize country: 2-letter code, lowercase\n   * Returns null if not exactly 2 characters\n   */\n  normalizeCountry(country: string): string | null {\n    if (!country || typeof country !== 'string') return null;\n    const normalized = country.toLowerCase().trim();\n    if (normalized.length !== 2) return null;\n    return normalized;\n  }\n\n  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   * HASH METHODS\n   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */\n\n  /**\n   * Hash email (normalize then hash)\n   */\n  async hashEmail(email: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeEmail(email);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash phone (normalize then hash)\n   */\n  async hashPhone(phone: string, countryCode?: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizePhone(phone, countryCode);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash name (normalize then hash)\n   */\n  async hashName(name: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeName(name);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash gender (normalize then hash)\n   */\n  async hashGender(gender: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeGender(gender);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash date of birth (normalize then hash)\n   */\n  async hashDateOfBirth(dob: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeDateOfBirth(dob);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash city (normalize then hash)\n   */\n  async hashCity(city: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeCity(city);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash state (normalize then hash)\n   */\n  async hashState(state: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeState(state);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash zip code (normalize then hash)\n   */\n  async hashZipCode(zip: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeZipCode(zip);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash country (normalize then hash)\n   */\n  async hashCountry(country: string): Promise<Sha256Hash | null> {\n    const normalized = this.normalizeCountry(country);\n    return normalized ? sha256(normalized) : null;\n  }\n\n  /**\n   * Hash external ID (trim only, no other normalization)\n   */\n  async hashExternalId(externalId: string): Promise<Sha256Hash | null> {\n    if (!externalId || typeof externalId !== 'string') return null;\n    return sha256(externalId.trim());\n  }\n\n  /* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n   * BATCH NORMALIZATION\n   * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */\n\n  /**\n   * Normalize and hash all user data\n   * \n   * Raw PII in, hashed data out.\n   * \n   * @param raw - Raw user data (unhashed PII)\n   * @returns Normalized and hashed user data\n   * \n   * @example\n   * ```typescript\n   * const normalizer = new Normalizer();\n   * const normalized = await normalizer.normalize({\n   *   email: 'JOHN@EXAMPLE.COM',\n   *   phone: '555-123-4567',\n   *   first_name: 'John',\n   *   last_name: 'Doe',\n   *   city: 'San Francisco',\n   *   state: 'CA',\n   *   country: 'US',\n   * });\n   * \n   * // Result:\n   * // {\n   * //   email: '5e884898...', (hashed)\n   * //   phone: 'a1b2c3d4...', (hashed)\n   * //   first_name: 'e5f6g7h8...', (hashed)\n   * //   last_name: 'i9j0k1l2...', (hashed)\n   * //   city: 'san francisco', (normalized, not hashed by default)\n   * //   state: 'ca', (normalized, not hashed by default)\n   * //   country: 'us', (normalized, not hashed by default)\n   * // }\n   * ```\n   */\n  async normalize(raw: RawUserData): Promise<NormalizedUserData> {\n    const result: NormalizedUserData = {};\n\n    // Hash contact PII\n    if (raw.email) {\n      const h = await this.hashEmail(raw.email);\n      if (h) result.email = h;\n    }\n    if (raw.phone) {\n      const h = await this.hashPhone(raw.phone);\n      if (h) result.phone = h;\n    }\n    if (raw.first_name) {\n      const h = await this.hashName(raw.first_name);\n      if (h) result.first_name = h;\n    }\n    if (raw.last_name) {\n      const h = await this.hashName(raw.last_name);\n      if (h) result.last_name = h;\n    }\n    if (raw.gender) {\n      const h = await this.hashGender(raw.gender);\n      if (h) result.gender = h;\n    }\n    if (raw.date_of_birth) {\n      const h = await this.hashDateOfBirth(raw.date_of_birth);\n      if (h) result.date_of_birth = h;\n    }\n    if (raw.external_id) {\n      const h = await this.hashExternalId(raw.external_id);\n      if (h) result.external_id = h;\n    }\n\n    // Address fields - hash only if configured to do so\n    if (raw.city) {\n      if (this.options.hashAddressFields) {\n        const h = await this.hashCity(raw.city);\n        if (h) result.city = h as unknown as string;\n      } else {\n        result.city = raw.city;\n      }\n    }\n    if (raw.state) {\n      if (this.options.hashAddressFields) {\n        const h = await this.hashState(raw.state);\n        if (h) result.state = h as unknown as string;\n      } else {\n        result.state = raw.state;\n      }\n    }\n    if (raw.zip_code) {\n      if (this.options.hashAddressFields) {\n        const h = await this.hashZipCode(raw.zip_code);\n        if (h) result.zip_code = h as unknown as string;\n      } else {\n        result.zip_code = raw.zip_code;\n      }\n    }\n    if (raw.country) {\n      if (this.options.hashAddressFields) {\n        const h = await this.hashCountry(raw.country);\n        if (h) result.country = h as unknown as string;\n      } else {\n        result.country = raw.country;\n      }\n    }\n\n    // Pass through unhashed fields\n    if (raw.ip_address) result.ip_address = raw.ip_address;\n    if (raw.user_agent) result.user_agent = raw.user_agent;\n    if (raw.subscription_id) result.subscription_id = raw.subscription_id;\n    if (raw.lead_id) result.lead_id = raw.lead_id;\n    if (raw.anonymous_id) result.anonymous_id = raw.anonymous_id;\n    if (raw.traits) result.traits = raw.traits;\n\n    return result;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hammr/normalizer",
+  "version": "1.0.0",
+  "description": "PII normalization and SHA256 hashing for Meta CAPI and ad platforms",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "normalization",
+    "pii",
+    "hashing",
+    "sha256",
+    "meta",
+    "capi",
+    "privacy",
+    "email",
+    "phone",
+    "e164",
+    "hmac-sha256"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.0.4",
+    "@vitest/coverage-v8": "^1.0.4"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Edge Foundry, Inc.",
+  "license": "Apache-2.0"
+}