@google-ads/datamanager-util 0.4.0

package/dist/src/formatter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Utility for normalizing and formatting user data.
+ * @see {@link https://developers.google.com/google-ads/api/docs/conversions/upload-clicks#javascript}
+ */
+export declare class UserDataFormatter {
+    formatEmailAddress(emailAddress: string): string;
+    formatPhoneNumber(phoneNumber: string): string;
+    formatGivenName(givenName: string): string;
+    formatFamilyName(familyName: string): string;
+    formatRegionCode(regionCode: string): string;
+    formatPostalCode(postalCode: string): string;
+    private formatLocationString;
+    formatAddressLine(addressLine: string): string;
+    formatCity(city: string): string;
+    formatAdministrativeArea(administrativeArea: string): string;
+    hashString(s: string): Buffer;
+    hexEncode(bytes: Buffer): string;
+    base64Encode(bytes: Buffer): string;
+    processEmailAddress(email: string, encoding: Encoding): string;
+    processPhoneNumber(phoneNumber: string, encoding: Encoding): string;
+    processGivenName(givenName: string, encoding: Encoding): string;
+    processFamilyName(familyName: string, encoding: Encoding): string;
+    processRegionCode(regionCode: string): string;
+    processPostalCode(postalCode: string): string;
+    processAddressLine(addressLine: string, encoding: Encoding): string;
+    processCity(city: string): string;
+    processAdministrativeArea(administrativeArea: string): string;
+    private hashAndEncode;
+    private encode;
+}
+export declare enum Encoding {
+    HEX = "hex",
+    BASE64 = "base64"
+}

package/dist/src/formatter.js

@@ -0,0 +1,261 @@
+"use strict";
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Encoding = exports.UserDataFormatter = void 0;
+const crypto = __importStar(require("crypto"));
+/**
+ * Utility for normalizing and formatting user data.
+ * @see {@link https://developers.google.com/google-ads/api/docs/conversions/upload-clicks#javascript}
+ */
+class UserDataFormatter {
+    formatEmailAddress(emailAddress) {
+        if (!emailAddress) {
+            throw new Error('Email address is null or empty.');
+        }
+        const trimmedEmail = emailAddress.trim();
+        if (trimmedEmail === '') {
+            throw new Error('Email address is empty or blank.');
+        }
+        if (trimmedEmail.includes(' ')) {
+            throw new Error('Email address contains intermediate whitespace.');
+        }
+        const emailParts = trimmedEmail.toLowerCase().split('@');
+        if (emailParts.length !== 2) {
+            throw new Error('Email is not of the form user@domain');
+        }
+        let username = emailParts[0];
+        const domain = emailParts[1];
+        if (!username) {
+            throw new Error('Email address without the domain is empty');
+        }
+        if (!domain) {
+            throw new Error('Domain of email address is empty');
+        }
+        if (domain === 'gmail.com' || domain === 'googlemail.com') {
+            username = username.split('+')[0];
+            username = username.replace(/\./g, '');
+        }
+        if (!username) {
+            throw new Error('Email address without the domain name is empty after normalization');
+        }
+        return `${username}@${domain}`;
+    }
+    formatPhoneNumber(phoneNumber) {
+        if (!phoneNumber) {
+            throw new Error('Phone number is null or empty.');
+        }
+        const trimmedPhone = phoneNumber.trim();
+        if (trimmedPhone === '') {
+            throw new Error('Phone number is empty or blank.');
+        }
+        const digitsOnly = trimmedPhone.replace(/\D/g, '');
+        if (digitsOnly === '') {
+            throw new Error('Phone number contains no digits.');
+        }
+        return `+${digitsOnly}`;
+    }
+    formatGivenName(givenName) {
+        if (!givenName) {
+            throw new Error('Given name is null or empty.');
+        }
+        const trimmedGivenName = givenName.trim().toLowerCase();
+        if (trimmedGivenName === '') {
+            throw new Error('Given name is empty or blank.');
+        }
+        const withoutPrefix = trimmedGivenName
+            .replace(/^(?:mr|mrs|ms|dr)\.(?:\s|$)/, '')
+            .trim();
+        if (withoutPrefix === '') {
+            throw new Error('Given name consists solely of a prefix.');
+        }
+        return withoutPrefix;
+    }
+    formatFamilyName(familyName) {
+        if (!familyName) {
+            throw new Error('Family name is null or empty.');
+        }
+        const trimmedFamilyName = familyName.trim().toLowerCase();
+        if (trimmedFamilyName === '') {
+            throw new Error('Family name is empty or blank.');
+        }
+        let withoutSuffix = trimmedFamilyName;
+        const suffixPattern = new RegExp(String.raw `
+            (?:,\s*|\s+)
+            (?:jr\.?|sr\.?|2nd|3rd|ii|iii|iv|v|vi|cpa|dc|dds|vm|jd|md|phd)
+            \s?$
+        `.replace(/\s+/g, ''));
+        while (suffixPattern.test(withoutSuffix)) {
+            withoutSuffix = withoutSuffix.replace(suffixPattern, '');
+        }
+        if (withoutSuffix === '') {
+            throw new Error('Family name consists solely of a suffix.');
+        }
+        return withoutSuffix;
+    }
+    formatRegionCode(regionCode) {
+        if (!regionCode) {
+            throw new Error('Region code is null or empty.');
+        }
+        const trimmedRegionCode = regionCode.trim().toUpperCase();
+        if (trimmedRegionCode === '') {
+            throw new Error('Region code is empty or blank.');
+        }
+        if (trimmedRegionCode.length !== 2) {
+            throw new Error(`Region code length is ${trimmedRegionCode.length}. Length must be 2`);
+        }
+        if (!/^[A-Z]+$/.test(trimmedRegionCode)) {
+            throw new Error('Region code contains characters other than A-Z');
+        }
+        return trimmedRegionCode;
+    }
+    formatPostalCode(postalCode) {
+        if (!postalCode) {
+            throw new Error('Postal code is null or empty.');
+        }
+        const trimmedPostalCode = postalCode.trim();
+        if (trimmedPostalCode === '') {
+            throw new Error('Postal code is empty or blank.');
+        }
+        return trimmedPostalCode;
+    }
+    formatLocationString(value, label) {
+        if (!value) {
+            throw new Error(`${label} is null or empty.`);
+        }
+        let formattedValue = value.trim().toLowerCase();
+        formattedValue = formattedValue.replace(/[^\p{L}\p{N}\s]/gu, '');
+        if (!formattedValue) {
+            throw new Error(`${label} is blank or empty.`);
+        }
+        return formattedValue;
+    }
+    formatAddressLine(addressLine) {
+        return this.formatLocationString(addressLine, 'Address line');
+    }
+    formatCity(city) {
+        return this.formatLocationString(city, 'City');
+    }
+    formatAdministrativeArea(administrativeArea) {
+        return this.formatLocationString(administrativeArea, 'Administrative area');
+    }
+    hashString(s) {
+        if (s === null || s === undefined) {
+            throw new Error('String is null.');
+        }
+        if (s.trim() === '') {
+            throw new Error('String is empty or blank.');
+        }
+        return crypto.createHash('sha256').update(s).digest();
+    }
+    hexEncode(bytes) {
+        if (!bytes) {
+            throw new Error('Byte array is null.');
+        }
+        if (bytes.length === 0) {
+            throw new Error('Byte array is empty.');
+        }
+        return bytes.toString('hex');
+    }
+    base64Encode(bytes) {
+        if (!bytes) {
+            throw new Error('Byte array is null.');
+        }
+        if (bytes.length === 0) {
+            throw new Error('Byte array is empty.');
+        }
+        return bytes.toString('base64');
+    }
+    processEmailAddress(email, encoding) {
+        return this.hashAndEncode(this.formatEmailAddress(email), encoding);
+    }
+    processPhoneNumber(phoneNumber, encoding) {
+        return this.hashAndEncode(this.formatPhoneNumber(phoneNumber), encoding);
+    }
+    processGivenName(givenName, encoding) {
+        return this.hashAndEncode(this.formatGivenName(givenName), encoding);
+    }
+    processFamilyName(familyName, encoding) {
+        return this.hashAndEncode(this.formatFamilyName(familyName), encoding);
+    }
+    processRegionCode(regionCode) {
+        return this.formatRegionCode(regionCode);
+    }
+    processPostalCode(postalCode) {
+        return this.formatPostalCode(postalCode);
+    }
+    processAddressLine(addressLine, encoding) {
+        return this.hashAndEncode(this.formatAddressLine(addressLine), encoding);
+    }
+    processCity(city) {
+        return this.formatCity(city);
+    }
+    processAdministrativeArea(administrativeArea) {
+        return this.formatAdministrativeArea(administrativeArea);
+    }
+    hashAndEncode(normalizedString, encoding) {
+        const hashBytes = this.hashString(normalizedString);
+        return this.encode(hashBytes, encoding);
+    }
+    encode(bytes, encoding) {
+        if (encoding === 'hex') {
+            return this.hexEncode(bytes);
+        }
+        else if (encoding === 'base64') {
+            return this.base64Encode(bytes);
+        }
+        else {
+            throw new Error(`Invalid encoding: ${encoding}`);
+        }
+    }
+}
+exports.UserDataFormatter = UserDataFormatter;
+var Encoding;
+(function (Encoding) {
+    Encoding["HEX"] = "hex";
+    Encoding["BASE64"] = "base64";
+})(Encoding || (exports.Encoding = Encoding = {}));

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export * from './formatter';

package/dist/src/index.js

@@ -0,0 +1,30 @@
+"use strict";
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./formatter"), exports);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@google-ads/datamanager-util",
+  "version": "0.4.0",
+  "description": "A utility library for the Data Manager API for Node.js.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "license": "Apache-2.0",
+  "author": "Google LLC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "scripts": {
+    "test": "c8 mocha --timeout 600000 dist/test/*.js",
+    "lint": "gts lint",
+    "fix": "gts fix",
+    "build": "tsc",
+    "prepare": "npm run build",
+    "pretest": "npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "chai": "^4.2.0",
+    "@types/chai": "^4.3.0",
+    "@types/mocha": "^10.0.0"
+  }
+}