@kard-financial/sdk 3.0.0 → 3.2.0

package/dist/cjs/helpers/hem.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalize an email address for Hashed Email (HEM) generation.
+ *
+ * Follows UID2/LiveRamp industry standards:
+ * - Remove all whitespace
+ * - Lowercase
+ * - Gmail/Googlemail only: remove dots from local-part, strip '+' suffix
+ * - Canonicalize googlemail.com → gmail.com
+ */
+export declare function normalizeEmail(raw: string): string;
+/**
+ * Generate a Hashed Email (HEM) from a raw email address.
+ * Returns the lowercase hex SHA-256 digest of the normalized, UTF-8-encoded email.
+ */
+export declare function generateHEM(raw: string): string;

package/dist/cjs/helpers/hem.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeEmail = normalizeEmail;
+exports.generateHEM = generateHEM;
+const crypto_1 = require("crypto");
+const GMAIL_DOMAINS = new Set(["gmail.com", "googlemail.com"]);
+/**
+ * Normalize an email address for Hashed Email (HEM) generation.
+ *
+ * Follows UID2/LiveRamp industry standards:
+ * - Remove all whitespace
+ * - Lowercase
+ * - Gmail/Googlemail only: remove dots from local-part, strip '+' suffix
+ * - Canonicalize googlemail.com → gmail.com
+ */
+function normalizeEmail(raw) {
+    const email = raw.replace(/\s/g, "").toLowerCase();
+    const atIndex = email.indexOf("@");
+    if (atIndex < 1 || atIndex !== email.lastIndexOf("@") || atIndex === email.length - 1) {
+        throw new TypeError(`Invalid email address: ${JSON.stringify(raw)}`);
+    }
+    const localPart = email.slice(0, atIndex);
+    const domain = email.slice(atIndex + 1);
+    if (GMAIL_DOMAINS.has(domain)) {
+        const base = localPart.split("+")[0].replace(/\./g, "");
+        return `${base}@gmail.com`;
+    }
+    return `${localPart}@${domain}`;
+}
+/**
+ * Generate a Hashed Email (HEM) from a raw email address.
+ * Returns the lowercase hex SHA-256 digest of the normalized, UTF-8-encoded email.
+ */
+function generateHEM(raw) {
+    return (0, crypto_1.createHash)("sha256").update(normalizeEmail(raw), "utf8").digest("hex");
+}

package/dist/esm/helpers/hem.d.mts

@@ -0,0 +1,15 @@
+/**
+ * Normalize an email address for Hashed Email (HEM) generation.
+ *
+ * Follows UID2/LiveRamp industry standards:
+ * - Remove all whitespace
+ * - Lowercase
+ * - Gmail/Googlemail only: remove dots from local-part, strip '+' suffix
+ * - Canonicalize googlemail.com → gmail.com
+ */
+export declare function normalizeEmail(raw: string): string;
+/**
+ * Generate a Hashed Email (HEM) from a raw email address.
+ * Returns the lowercase hex SHA-256 digest of the normalized, UTF-8-encoded email.
+ */
+export declare function generateHEM(raw: string): string;

package/dist/esm/helpers/hem.mjs

@@ -0,0 +1,32 @@
+import { createHash } from "crypto";
+const GMAIL_DOMAINS = new Set(["gmail.com", "googlemail.com"]);
+/**
+ * Normalize an email address for Hashed Email (HEM) generation.
+ *
+ * Follows UID2/LiveRamp industry standards:
+ * - Remove all whitespace
+ * - Lowercase
+ * - Gmail/Googlemail only: remove dots from local-part, strip '+' suffix
+ * - Canonicalize googlemail.com → gmail.com
+ */
+export function normalizeEmail(raw) {
+    const email = raw.replace(/\s/g, "").toLowerCase();
+    const atIndex = email.indexOf("@");
+    if (atIndex < 1 || atIndex !== email.lastIndexOf("@") || atIndex === email.length - 1) {
+        throw new TypeError(`Invalid email address: ${JSON.stringify(raw)}`);
+    }
+    const localPart = email.slice(0, atIndex);
+    const domain = email.slice(atIndex + 1);
+    if (GMAIL_DOMAINS.has(domain)) {
+        const base = localPart.split("+")[0].replace(/\./g, "");
+        return `${base}@gmail.com`;
+    }
+    return `${localPart}@${domain}`;
+}
+/**
+ * Generate a Hashed Email (HEM) from a raw email address.
+ * Returns the lowercase hex SHA-256 digest of the normalized, UTF-8-encoded email.
+ */
+export function generateHEM(raw) {
+    return createHash("sha256").update(normalizeEmail(raw), "utf8").digest("hex");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@kard-financial/sdk",
-    "version": "3.0.0",
+    "version": "3.2.0",
     "private": false,
     "repository": "github:KardFinancial/kard-node-sdk",
     "type": "commonjs",
@@ -20,7 +20,19 @@
             },
             "default": "./dist/cjs/index.js"
         },
-        "./package.json": "./package.json"
+        "./package.json": "./package.json",
+        "./helpers/hem": {
+            "types": "./dist/cjs/helpers/hem.d.ts",
+            "import": {
+                "types": "./dist/esm/helpers/hem.d.mts",
+                "default": "./dist/esm/helpers/hem.mjs"
+            },
+            "require": {
+                "types": "./dist/cjs/helpers/hem.d.ts",
+                "default": "./dist/cjs/helpers/hem.js"
+            },
+            "default": "./dist/cjs/helpers/hem.js"
+        }
     },
     "files": [
         "dist",

package/reference.md

@@ -1884,3 +1884,79 @@ await client.users.uploads.update("organization-123", "user-123", "upload-123",
 </dd>
 </dl>
 </details>
+
+## Custom Helper Functions
+### hem
+
+**Import:** `import { normalizeEmail, generateHEM } from "@kard-financial/sdk/helpers/hem";`
+
+<details><summary><code><a href="/src/helpers/hem.ts">normalizeEmail(raw: string): string</a></code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+Normalize an email address for Hashed Email (HEM) generation.
+Follows UID2/LiveRamp industry standards:
+- Remove all whitespace
+- Lowercase
+- Gmail/Googlemail only: remove dots from local-part, strip '+' suffix
+- Canonicalize googlemail.com → gmail.com
+
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+```typescript
+import { normalizeEmail } from "@kard-financial/sdk/helpers/hem";
+
+const result = normalizeEmail(/* raw: string */);
+```
+
+</dd>
+</dl>
+
+</dd>
+</dl>
+</details>
+
+<details><summary><code><a href="/src/helpers/hem.ts">generateHEM(raw: string): string</a></code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+Generate a Hashed Email (HEM) from a raw email address.
+Returns the lowercase hex SHA-256 digest of the normalized, UTF-8-encoded email.
+
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+```typescript
+import { generateHEM } from "@kard-financial/sdk/helpers/hem";
+
+const result = generateHEM(/* raw: string */);
+```
+
+</dd>
+</dl>
+
+</dd>
+</dl>
+</details>
+