reliable-node-utils 1.0.0

package/dist/index.js

@@ -0,0 +1,1013 @@
+import { faker } from '@faker-js/faker';
+
+// src/errors.ts
+var UtilsError = class extends Error {
+  name = "UtilsError";
+  constructor(message, options) {
+    super(message, options);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AbortError = class extends UtilsError {
+  name = "AbortError";
+};
+var TimeoutError = class extends UtilsError {
+  name = "TimeoutError";
+};
+var RetryExhaustedError = class extends UtilsError {
+  constructor(message, attempt, lastError, options) {
+    super(message, { ...options, cause: lastError });
+    this.attempt = attempt;
+    this.lastError = lastError;
+  }
+  name = "RetryExhaustedError";
+};
+
+// src/async/retry.ts
+var DEFAULT_OPTIONS = {
+  maxAttempts: 3,
+  baseDelayMs: 1e3,
+  maxDelayMs: 3e4,
+  jitter: true
+};
+function delay(ms, signal) {
+  if (signal?.aborted) return Promise.reject(new AbortError("Aborted"));
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      clearTimeout(id);
+      signal?.removeEventListener("abort", onAbort);
+      reject(new AbortError("Aborted"));
+    };
+    const id = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function assertValidRetryOptions(fn, options) {
+  if (typeof fn !== "function") {
+    throw new TypeError("retry: fn must be a function returning a Promise");
+  }
+  if (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1) {
+    throw new TypeError("retry: maxAttempts must be an integer >= 1");
+  }
+  if (!Number.isFinite(options.baseDelayMs) || options.baseDelayMs < 0) {
+    throw new TypeError("retry: baseDelayMs must be a finite number >= 0");
+  }
+  if (!Number.isFinite(options.maxDelayMs) || options.maxDelayMs < 0) {
+    throw new TypeError("retry: maxDelayMs must be a finite number >= 0");
+  }
+  if (options.maxDelayMs < options.baseDelayMs) {
+    throw new TypeError("retry: maxDelayMs must be >= baseDelayMs");
+  }
+  if (typeof options.jitter !== "boolean") {
+    throw new TypeError("retry: jitter must be a boolean");
+  }
+  if (options.onRetry !== void 0 && typeof options.onRetry !== "function") {
+    throw new TypeError("retry: onRetry must be a function");
+  }
+}
+function clamp(min, value, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function computeDelay(attempt, baseDelayMs, maxDelayMs, jitter) {
+  const exponential = baseDelayMs * Math.pow(2, attempt - 1);
+  const capped = clamp(baseDelayMs, exponential, maxDelayMs);
+  if (!jitter) return capped;
+  return Math.random() * capped;
+}
+async function retry(fn, options = {}) {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  assertValidRetryOptions(fn, opts);
+  const { maxAttempts, baseDelayMs, maxDelayMs, jitter, onRetry, signal } = opts;
+  let lastError;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    if (signal?.aborted) {
+      throw new AbortError("Aborted");
+    }
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt === maxAttempts) {
+        throw new RetryExhaustedError(
+          `Retry exhausted after ${maxAttempts} attempt(s)`,
+          attempt,
+          lastError
+        );
+      }
+      if (onRetry) {
+        await Promise.resolve(onRetry(attempt, err));
+      }
+      if (signal?.aborted) {
+        throw new AbortError("Aborted");
+      }
+      const waitMs = computeDelay(attempt, baseDelayMs, maxDelayMs, jitter);
+      await delay(waitMs, signal);
+    }
+  }
+  throw new RetryExhaustedError(
+    `Retry exhausted after ${maxAttempts} attempt(s)`,
+    maxAttempts,
+    lastError
+  );
+}
+
+// src/async/withTimeout.ts
+async function withTimeout(promiseOrFn, ms, options = {}) {
+  const { signal } = options;
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw new TypeError("withTimeout: ms must be a finite number >= 0");
+  }
+  if (signal?.aborted) {
+    throw new AbortError("Aborted");
+  }
+  const promise = typeof promiseOrFn === "function" ? promiseOrFn() : promiseOrFn;
+  let timeoutId;
+  const timeoutPromise = new Promise((_, reject2) => {
+    timeoutId = setTimeout(() => {
+      reject2(new TimeoutError(`Operation timed out after ${ms}ms`));
+    }, ms);
+  });
+  const abortHandler = () => {
+    if (timeoutId !== void 0) clearTimeout(timeoutId);
+    reject(new AbortError("Aborted"));
+  };
+  let reject;
+  const abortPromise = new Promise((_, rej) => {
+    reject = rej;
+  });
+  signal?.addEventListener("abort", abortHandler, { once: true });
+  try {
+    const result = await Promise.race([promise, timeoutPromise, abortPromise]);
+    if (timeoutId !== void 0) clearTimeout(timeoutId);
+    signal?.removeEventListener("abort", abortHandler);
+    return result;
+  } catch (err) {
+    if (timeoutId !== void 0) clearTimeout(timeoutId);
+    signal?.removeEventListener("abort", abortHandler);
+    throw err;
+  }
+}
+
+// src/async/pLimit.ts
+function pLimit(concurrency) {
+  if (typeof concurrency !== "number" || concurrency < 1 || !Number.isFinite(concurrency)) {
+    throw new TypeError("pLimit: concurrency must be a finite number >= 1");
+  }
+  let active = 0;
+  const queue = [];
+  const run = async (fn, ...args) => {
+    const wait = () => new Promise((resolve) => {
+      queue.push(resolve);
+    });
+    const next = () => {
+      active--;
+      const resolve = queue.shift();
+      if (resolve) resolve();
+    };
+    if (active >= concurrency) {
+      await wait();
+    }
+    active++;
+    try {
+      return await fn(...args);
+    } finally {
+      next();
+    }
+  };
+  return run;
+}
+
+// src/fn/memoize.ts
+function memoize(fn, options = {}) {
+  const {
+    ttlMs,
+    maxSize,
+    keyFn = (...args) => JSON.stringify(args)
+  } = options;
+  const cache = /* @__PURE__ */ new Map();
+  const accessOrder = [];
+  function trimToMaxSize() {
+    if (maxSize === void 0 || accessOrder.length <= maxSize) return;
+    while (accessOrder.length > maxSize) {
+      const key = accessOrder.shift();
+      if (key !== void 0) cache.delete(key);
+    }
+  }
+  function getFresh(key) {
+    const entry = cache.get(key);
+    if (!entry) return { hit: false };
+    if (entry.expiresAt !== void 0 && Date.now() > entry.expiresAt) {
+      cache.delete(key);
+      const i = accessOrder.indexOf(key);
+      if (i !== -1) accessOrder.splice(i, 1);
+      return { hit: false };
+    }
+    if (maxSize !== void 0) {
+      const i = accessOrder.indexOf(key);
+      if (i !== -1) accessOrder.splice(i, 1);
+      accessOrder.push(key);
+    }
+    return { hit: true, value: entry.value };
+  }
+  const wrapped = function(...args) {
+    const key = keyFn(...args);
+    const cached = getFresh(key);
+    if (cached.hit) return cached.value;
+    const value = fn.apply(this, args);
+    const expiresAt = ttlMs !== void 0 ? Date.now() + ttlMs : void 0;
+    if (maxSize !== void 0) {
+      const existingIndex = accessOrder.indexOf(key);
+      if (existingIndex !== -1) accessOrder.splice(existingIndex, 1);
+    }
+    cache.set(key, { value, expiresAt });
+    if (maxSize !== void 0) {
+      accessOrder.push(key);
+      trimToMaxSize();
+    }
+    return value;
+  };
+  return wrapped;
+}
+
+// src/guards/index.ts
+function isDefined(value) {
+  return value !== null && value !== void 0;
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+
+// src/object/deepMerge.ts
+var BLOCKED_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function deepMerge(a, b) {
+  const result = { ...a };
+  for (const key of Object.keys(b)) {
+    const keyStr = String(key);
+    if (BLOCKED_KEYS.has(keyStr)) continue;
+    const bVal = b[key];
+    if (bVal === void 0) continue;
+    const aVal = result[key];
+    if (isPlainObject(aVal) && isPlainObject(bVal) && !Array.isArray(aVal) && !Array.isArray(bVal)) {
+      result[keyStr] = deepMerge(
+        aVal,
+        bVal
+      );
+    } else {
+      result[keyStr] = bVal;
+    }
+  }
+  return result;
+}
+
+// src/string/index.ts
+function replaceTemplateValues(template, replacements) {
+  let result = template;
+  for (const [key, value] of Object.entries(replacements)) {
+    result = result.split(`{${key}}`).join(`"${String(value)}"`);
+  }
+  return result;
+}
+function splitString(input, delimiter) {
+  return input.split(delimiter);
+}
+function parseBooleanString(input) {
+  if (input === void 0 || input === null || input.trim() === "") {
+    throw new Error("No input provided.");
+  }
+  const normalized = input.trim().toLowerCase();
+  if (normalized === "true") return true;
+  if (normalized === "false") return false;
+  throw new Error(`Cannot convert string "${input}" to boolean.`);
+}
+function isNullOrEmptyString(value) {
+  return value === null || value === void 0 || value.trim() === "";
+}
+function snakeToPascalCase(input) {
+  return input.toLowerCase().replace(/_([a-z])/g, (_match, char) => char.toUpperCase()).replace(/^\w/, (char) => char.toUpperCase());
+}
+var convertToCamelCase = snakeToPascalCase;
+var formatStringValue = replaceTemplateValues;
+
+// src/random/index.ts
+var ALPHANUMERIC = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+var ALPHABETIC = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+function assertPositiveLength(length, fnName) {
+  if (!Number.isInteger(length) || length <= 0) {
+    throw new Error(`${fnName}: length must be a positive integer.`);
+  }
+}
+function randomIndex(length, rng) {
+  return Math.floor(rng() * length);
+}
+function generateRandomAlphanumericString(length, options = {}) {
+  assertPositiveLength(length, "generateRandomAlphanumericString");
+  const rng = options.rng ?? Math.random;
+  let out = "";
+  for (let i = 0; i < length; i++) {
+    out += ALPHANUMERIC.charAt(randomIndex(ALPHANUMERIC.length, rng));
+  }
+  return options.uppercase ?? true ? out.toUpperCase() : out;
+}
+function generateRandomNDigitNumber(length, options = {}) {
+  assertPositiveLength(length, "generateRandomNDigitNumber");
+  if (length > 15) {
+    throw new Error(
+      "generateRandomNDigitNumber: length must be <= 15 for safe integers."
+    );
+  }
+  const rng = options.rng ?? Math.random;
+  const min = Math.pow(10, length - 1);
+  const max = Math.pow(10, length) - 1;
+  return Math.floor(rng() * (max - min + 1)) + min;
+}
+function generateRandomAlphabeticString(length, options = {}) {
+  assertPositiveLength(length, "generateRandomAlphabeticString");
+  const rng = options.rng ?? Math.random;
+  let out = "";
+  for (let i = 0; i < length; i++) {
+    out += ALPHABETIC.charAt(randomIndex(ALPHABETIC.length, rng));
+  }
+  return out;
+}
+var getAlphaNumericString = generateRandomAlphanumericString;
+var generateRandomNumber = generateRandomNDigitNumber;
+var generateRandomString = generateRandomAlphabeticString;
+
+// src/json/index.ts
+function updateAllKeysValues(target, updates) {
+  for (const [key, value] of Object.entries(target)) {
+    if (updates[key] !== void 0) {
+      target[key] = updates[key];
+      continue;
+    }
+    if (isPlainObject(value)) {
+      updateAllKeysValues(value, updates);
+      continue;
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (isPlainObject(item)) {
+          updateAllKeysValues(item, updates);
+        }
+      }
+    }
+  }
+}
+function updateJsonValues(jsonText, updates) {
+  const parsed = JSON.parse(jsonText);
+  if (!isPlainObject(parsed) && !Array.isArray(parsed)) {
+    throw new Error("updateJsonValues: root must be a JSON object or array.");
+  }
+  if (isPlainObject(parsed)) {
+    updateAllKeysValues(parsed, updates);
+  } else {
+    for (const item of parsed) {
+      if (isPlainObject(item)) {
+        updateAllKeysValues(item, updates);
+      }
+    }
+  }
+  return JSON.stringify(parsed, null, 2);
+}
+var updateJsonData = updateJsonValues;
+
+// src/date/index.ts
+function pad2(value) {
+  return String(value).padStart(2, "0");
+}
+function formatDate(date, pattern) {
+  return pattern.replaceAll("yyyy", String(date.getFullYear())).replaceAll("MM", pad2(date.getMonth() + 1)).replaceAll("dd", pad2(date.getDate())).replaceAll("HH", pad2(date.getHours())).replaceAll("mm", pad2(date.getMinutes())).replaceAll("ss", pad2(date.getSeconds()));
+}
+function getRelativeDate(token, format = "yyyy-MM-dd", now = /* @__PURE__ */ new Date()) {
+  const outputFormat = isNullOrEmptyString(format) ? "yyyy-MM-dd" : format;
+  const date = new Date(now.getTime());
+  switch (token) {
+    case "Year":
+      date.setFullYear(date.getFullYear() - 1);
+      break;
+    case "Yesterday":
+      date.setDate(date.getDate() - 1);
+      break;
+  }
+  return formatDate(date, outputFormat);
+}
+var getDate = getRelativeDate;
+
+// src/collections/index.ts
+function renameMapKey(data, oldKey, newKey) {
+  if (!data.has(oldKey)) return false;
+  let value = data.get(oldKey) ?? "";
+  value = value.replace(/^"(.*)"$/, "$1");
+  data.delete(oldKey);
+  data.set(newKey, value);
+  return true;
+}
+var updateKey = renameMapKey;
+
+// src/identity/uniqueStore.ts
+var InMemoryUniqueValueStore = class {
+  values = /* @__PURE__ */ new Set();
+  has(value) {
+    return this.values.has(value);
+  }
+  add(value) {
+    this.values.add(value);
+  }
+};
+var scopedStores = /* @__PURE__ */ new Map();
+function getScopedInMemoryStore(scope) {
+  const existing = scopedStores.get(scope);
+  if (existing) return existing;
+  const created = new InMemoryUniqueValueStore();
+  scopedStores.set(scope, created);
+  return created;
+}
+function clearScopedInMemoryStores() {
+  scopedStores.clear();
+}
+
+// src/identity/namesData.ts
+var COMMON_FIRST_NAMES = [
+  "James",
+  "Mary",
+  "John",
+  "Patricia",
+  "Robert",
+  "Jennifer",
+  "Michael",
+  "Linda",
+  "William",
+  "Elizabeth",
+  "David",
+  "Barbara",
+  "Richard",
+  "Susan",
+  "Joseph",
+  "Jessica",
+  "Thomas",
+  "Sarah",
+  "Charles",
+  "Karen",
+  "Christopher",
+  "Nancy",
+  "Daniel",
+  "Lisa",
+  "Matthew",
+  "Betty",
+  "Anthony",
+  "Margaret",
+  "Mark",
+  "Sandra",
+  "Donald",
+  "Ashley",
+  "Steven",
+  "Kimberly",
+  "Andrew",
+  "Emily",
+  "Paul",
+  "Donna",
+  "Joshua",
+  "Michelle",
+  "Kenneth",
+  "Dorothy",
+  "Kevin",
+  "Carol",
+  "Brian",
+  "Amanda",
+  "George",
+  "Melissa",
+  "Timothy",
+  "Deborah"
+];
+var COMMON_LAST_NAMES = [
+  "Smith",
+  "Johnson",
+  "Williams",
+  "Brown",
+  "Jones",
+  "Garcia",
+  "Miller",
+  "Davis",
+  "Rodriguez",
+  "Martinez",
+  "Hernandez",
+  "Lopez",
+  "Gonzalez",
+  "Wilson",
+  "Anderson",
+  "Thomas",
+  "Taylor",
+  "Moore",
+  "Jackson",
+  "Martin",
+  "Lee",
+  "Perez",
+  "Thompson",
+  "White",
+  "Harris",
+  "Sanchez",
+  "Clark",
+  "Ramirez",
+  "Lewis",
+  "Robinson",
+  "Walker",
+  "Young",
+  "Allen",
+  "King",
+  "Wright",
+  "Scott",
+  "Torres",
+  "Nguyen",
+  "Hill",
+  "Flores",
+  "Green",
+  "Adams",
+  "Nelson",
+  "Baker",
+  "Hall",
+  "Rivera",
+  "Campbell",
+  "Mitchell",
+  "Carter",
+  "Roberts"
+];
+
+// src/identity/providers.ts
+function pick(items, rng) {
+  const idx = Math.floor(rng() * items.length);
+  return items[Math.max(0, Math.min(items.length - 1, idx))];
+}
+var StaticDatasetNameProvider = class {
+  firstName(options = {}) {
+    const rng = options.rng ?? Math.random;
+    return pick(COMMON_FIRST_NAMES, rng);
+  }
+  lastName(options = {}) {
+    const rng = options.rng ?? Math.random;
+    return pick(COMMON_LAST_NAMES, rng);
+  }
+};
+var FakerNameProvider = class {
+  faker;
+  constructor(options = {}) {
+    this.faker = options.faker ?? faker;
+  }
+  firstName() {
+    return this.faker.person.firstName();
+  }
+  lastName() {
+    return this.faker.person.lastName();
+  }
+};
+var DEFAULT_NAME_PROVIDER = new StaticDatasetNameProvider();
+
+// src/identity/nameGenerator.ts
+function defaultNormalize(value) {
+  return value.trim().toLowerCase();
+}
+async function generateUnique(producer, options) {
+  const maxAttempts = options.maxAttempts ?? 1e3;
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new TypeError("unique name generation: maxAttempts must be an integer >= 1");
+  }
+  const normalize = options.normalize ?? defaultNormalize;
+  const store = options.store ?? getScopedInMemoryStore(options.scope ?? "default");
+  for (let i = 0; i < maxAttempts; i++) {
+    const candidate = producer();
+    const key = normalize(candidate);
+    if (!await store.has(key)) {
+      await store.add(key);
+      return candidate;
+    }
+  }
+  throw new Error(
+    `Unable to generate a unique value after ${maxAttempts} attempts. Use a larger name pool, custom normalize, or custom store.`
+  );
+}
+function generateFirstName(options = {}) {
+  const provider = options.provider ?? DEFAULT_NAME_PROVIDER;
+  return provider.firstName({ rng: options.rng });
+}
+function generateLastName(options = {}) {
+  const provider = options.provider ?? DEFAULT_NAME_PROVIDER;
+  return provider.lastName({ rng: options.rng });
+}
+function generateFullName(options = {}) {
+  return `${generateFirstName(options)} ${generateLastName(options)}`;
+}
+function generateUniqueFirstName(options = {}) {
+  return generateUnique(() => generateFirstName(options), options);
+}
+function generateUniqueLastName(options = {}) {
+  return generateUnique(() => generateLastName(options), options);
+}
+function generateUniqueFullName(options = {}) {
+  return generateUnique(() => generateFullName(options), options);
+}
+
+// src/address/errors.ts
+var AddressProviderError = class extends UtilsError {
+  name = "AddressProviderError";
+};
+var AddressVerificationError = class extends UtilsError {
+  name = "AddressVerificationError";
+};
+var ProviderNotFoundError = class extends UtilsError {
+  name = "ProviderNotFoundError";
+};
+
+// src/address/service.ts
+function pickProvider(providers, country, requireUspsForUS) {
+  if (country === "US" && requireUspsForUS) {
+    const usps = providers.find(
+      (provider2) => provider2.supportsCountry("US") && provider2.name === "USPS"
+    );
+    if (!usps) {
+      throw new ProviderNotFoundError(
+        "US lookup requires USPS provider, but none was configured"
+      );
+    }
+    return usps;
+  }
+  const provider = providers.find((p) => p.supportsCountry(country));
+  if (!provider) {
+    throw new ProviderNotFoundError(
+      `No address provider configured for country ${country}`
+    );
+  }
+  return provider;
+}
+async function getValidAddressByPostalCode(options) {
+  const provider = pickProvider(
+    options.providers,
+    options.country,
+    options.requireUspsForUS ?? true
+  );
+  return await provider.lookupPostalCode({
+    country: options.country,
+    postalCode: options.postalCode,
+    signal: options.signal
+  });
+}
+async function verifyAddress(options) {
+  const provider = pickProvider(
+    options.providers,
+    options.address.country,
+    options.requireUspsForUS ?? true
+  );
+  return await provider.verifyAddress(options.address);
+}
+
+// src/address/providers/providerUtils.ts
+function assertProviderSupportsCountry(args) {
+  if (!args.supportsCountry(args.country)) {
+    throw new AddressProviderError(
+      `${args.providerName} provider does not support country ${args.country}`
+    );
+  }
+}
+function normalizeComparable(value) {
+  return value.trim().toUpperCase().replace(/\s+/g, " ");
+}
+function normalizePostalComparable(value) {
+  return value.replace(/\s+/g, "").toUpperCase();
+}
+async function fetchJsonOrThrow(url, options) {
+  const res = await fetch(url, { method: "GET", signal: options.signal });
+  if (!res.ok) {
+    throw new AddressProviderError(
+      `${options.errorPrefix} failed with status ${res.status}`
+    );
+  }
+  return await res.json();
+}
+async function fetchTextOrThrow(url, options) {
+  const res = await fetch(url, { method: "GET", signal: options.signal });
+  if (!res.ok) {
+    throw new AddressProviderError(
+      `${options.errorPrefix} failed with status ${res.status}`
+    );
+  }
+  return await res.text();
+}
+
+// src/address/providers/uspsProvider.ts
+function escapeXml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function getTagValue(xml, tag) {
+  const match = new RegExp(`<${tag}>([^<]*)</${tag}>`, "i").exec(xml);
+  return match?.[1]?.trim();
+}
+function normalizeUsZip(value) {
+  const digits = value.replace(/\D/g, "").slice(0, 5);
+  if (digits.length !== 5) {
+    throw new TypeError("USPS provider: postalCode must contain at least 5 digits");
+  }
+  return digits;
+}
+var UspsAddressProvider = class {
+  name = "USPS";
+  endpoint;
+  userId;
+  constructor(options) {
+    if (!isNonEmptyString(options.userId)) {
+      throw new TypeError("USPS provider: userId is required");
+    }
+    this.userId = options.userId;
+    this.endpoint = options.endpoint ?? "https://secure.shippingapis.com/ShippingAPI.dll";
+  }
+  supportsCountry(country) {
+    return country === "US";
+  }
+  async lookupPostalCode(request) {
+    assertProviderSupportsCountry({
+      providerName: this.name,
+      country: request.country,
+      supportsCountry: this.supportsCountry.bind(this)
+    });
+    const zip5 = normalizeUsZip(request.postalCode);
+    const xml = `<CityStateLookupRequest USERID="${escapeXml(this.userId)}"><ZipCode ID="0"><Zip5>${zip5}</Zip5></ZipCode></CityStateLookupRequest>`;
+    const responseXml = await this.callApi("CityStateLookup", xml, request.signal);
+    const errorDescription = getTagValue(responseXml, "Description");
+    if (errorDescription) {
+      throw new AddressProviderError(`USPS CityStateLookup failed: ${errorDescription}`);
+    }
+    const city = getTagValue(responseXml, "City");
+    const state = getTagValue(responseXml, "State");
+    const canonicalZip = getTagValue(responseXml, "Zip5") ?? zip5;
+    if (!city || !state) {
+      throw new AddressProviderError("USPS CityStateLookup returned incomplete response");
+    }
+    return {
+      country: "US",
+      postalCode: canonicalZip,
+      city,
+      stateProvince: state,
+      source: this.name,
+      uspsVerified: true
+    };
+  }
+  async verifyAddress(request) {
+    assertProviderSupportsCountry({
+      providerName: this.name,
+      country: request.country,
+      supportsCountry: this.supportsCountry.bind(this)
+    });
+    if (!isNonEmptyString(request.addressLine1)) {
+      throw new TypeError("USPS provider: addressLine1 is required for verification");
+    }
+    const zip5 = normalizeUsZip(request.postalCode);
+    const xml = `<AddressValidateRequest USERID="${escapeXml(this.userId)}"><Address ID="0"><FirmName></FirmName><Address1>${escapeXml(request.addressLine2 ?? "")}</Address1><Address2>${escapeXml(request.addressLine1)}</Address2><City>${escapeXml(request.city ?? "")}</City><State>${escapeXml(request.stateProvince ?? "")}</State><Zip5>${zip5}</Zip5><Zip4></Zip4></Address></AddressValidateRequest>`;
+    const responseXml = await this.callApi("Verify", xml, request.signal);
+    const errorDescription = getTagValue(responseXml, "Description");
+    if (errorDescription) {
+      throw new AddressVerificationError(`USPS Verify failed: ${errorDescription}`);
+    }
+    const line1 = getTagValue(responseXml, "Address2");
+    const line2 = getTagValue(responseXml, "Address1");
+    const city = getTagValue(responseXml, "City");
+    const state = getTagValue(responseXml, "State");
+    const canonicalZip = getTagValue(responseXml, "Zip5");
+    const zip4 = getTagValue(responseXml, "Zip4");
+    if (!line1 || !city || !state || !canonicalZip) {
+      throw new AddressVerificationError("USPS Verify returned incomplete response");
+    }
+    return {
+      country: "US",
+      postalCode: zip4 ? `${canonicalZip}-${zip4}` : canonicalZip,
+      city,
+      stateProvince: state,
+      addressLine1: line1,
+      addressLine2: line2 || void 0,
+      source: this.name,
+      uspsVerified: true
+    };
+  }
+  async callApi(api, xml, signal) {
+    const url = `${this.endpoint}?API=${encodeURIComponent(api)}&XML=${encodeURIComponent(xml)}`;
+    return await fetchTextOrThrow(url, {
+      signal,
+      errorPrefix: "USPS request"
+    });
+  }
+};
+
+// src/address/providers/zippopotamProvider.ts
+function canonicalCountryCode(value) {
+  return value.toLowerCase();
+}
+function normalizePostalCode(value) {
+  const cleaned = value.trim().toUpperCase();
+  if (!cleaned) throw new TypeError("postalCode is required");
+  return cleaned;
+}
+var ZippopotamAddressProvider = class {
+  name = "Zippopotam";
+  endpoint;
+  constructor(options = {}) {
+    this.endpoint = options.endpoint ?? "https://api.zippopotam.us";
+  }
+  supportsCountry(country) {
+    return country === "US" || country === "CA";
+  }
+  async lookupPostalCode(request) {
+    const postalCode = normalizePostalCode(request.postalCode);
+    assertProviderSupportsCountry({
+      providerName: this.name,
+      country: request.country,
+      supportsCountry: this.supportsCountry.bind(this)
+    });
+    const country = canonicalCountryCode(request.country);
+    const url = `${this.endpoint}/${country}/${encodeURIComponent(postalCode)}`;
+    const payload = await fetchJsonOrThrow(url, {
+      signal: request.signal,
+      errorPrefix: `Zippopotam lookup for ${request.country} ${postalCode}`
+    });
+    const first = payload.places?.[0];
+    if (!first) {
+      throw new AddressProviderError("Zippopotam lookup returned no places");
+    }
+    return {
+      country: request.country,
+      postalCode: payload["post code"],
+      city: first["place name"],
+      stateProvince: first["state abbreviation"] || first.state,
+      source: this.name,
+      uspsVerified: false
+    };
+  }
+  async verifyAddress(request) {
+    const lookedUp = await this.lookupPostalCode(request);
+    if (request.city && normalizeComparable(request.city) !== normalizeComparable(lookedUp.city)) {
+      throw new AddressVerificationError(
+        `City mismatch for postal code ${request.postalCode}: expected ${lookedUp.city}`
+      );
+    }
+    if (request.stateProvince && normalizeComparable(request.stateProvince) !== normalizeComparable(lookedUp.stateProvince)) {
+      throw new AddressVerificationError(
+        `State/Province mismatch for postal code ${request.postalCode}: expected ${lookedUp.stateProvince}`
+      );
+    }
+    return {
+      ...lookedUp,
+      addressLine1: request.addressLine1,
+      addressLine2: request.addressLine2
+    };
+  }
+};
+
+// src/address/providers/canadaPostProvider.ts
+function normalizeCanadianPostalCode(value) {
+  const cleaned = value.replace(/\s+/g, "").toUpperCase();
+  if (!/^[A-Z]\d[A-Z]\d[A-Z]\d$/.test(cleaned)) {
+    throw new TypeError(
+      "CanadaPost provider: postalCode must be a valid Canadian postal code (A1A1A1)"
+    );
+  }
+  return `${cleaned.slice(0, 3)} ${cleaned.slice(3)}`;
+}
+var CanadaPostAddressProvider = class {
+  name = "CanadaPost";
+  key;
+  findEndpoint;
+  retrieveEndpoint;
+  constructor(options) {
+    if (!isNonEmptyString(options.key)) {
+      throw new TypeError("CanadaPost provider: key is required");
+    }
+    this.key = options.key;
+    this.findEndpoint = options.findEndpoint ?? "https://ws1.postescanada-canadapost.ca/AddressComplete/Interactive/Find/v2.10/json3.ws";
+    this.retrieveEndpoint = options.retrieveEndpoint ?? "https://ws1.postescanada-canadapost.ca/AddressComplete/Interactive/Retrieve/v2.11/json3.ws";
+  }
+  supportsCountry(country) {
+    return country === "CA";
+  }
+  async lookupPostalCode(request) {
+    assertProviderSupportsCountry({
+      providerName: this.name,
+      country: request.country,
+      supportsCountry: this.supportsCountry.bind(this)
+    });
+    const postalCode = normalizeCanadianPostalCode(request.postalCode);
+    const retrieved = await this.findAndRetrieve({
+      searchTerm: postalCode,
+      signal: request.signal
+    });
+    if (!retrieved.city || !retrieved.provinceCode || !retrieved.postalCode) {
+      throw new AddressProviderError("CanadaPost lookup returned incomplete response");
+    }
+    return {
+      country: "CA",
+      postalCode: normalizeCanadianPostalCode(retrieved.postalCode),
+      city: retrieved.city,
+      stateProvince: retrieved.provinceCode,
+      source: this.name,
+      uspsVerified: false
+    };
+  }
+  async verifyAddress(request) {
+    assertProviderSupportsCountry({
+      providerName: this.name,
+      country: request.country,
+      supportsCountry: this.supportsCountry.bind(this)
+    });
+    if (!isNonEmptyString(request.addressLine1)) {
+      throw new TypeError(
+        "CanadaPost provider: addressLine1 is required for verification"
+      );
+    }
+    const searchPostal = normalizeCanadianPostalCode(request.postalCode);
+    const searchTerm = [request.addressLine1, request.city, searchPostal].filter(isNonEmptyString).join(" ");
+    const retrieved = await this.findAndRetrieve({
+      searchTerm,
+      signal: request.signal
+    });
+    if (!retrieved.line1 || !retrieved.city || !retrieved.provinceCode || !retrieved.postalCode) {
+      throw new AddressVerificationError(
+        "CanadaPost verify returned incomplete response"
+      );
+    }
+    if (normalizePostalComparable(retrieved.postalCode) !== normalizePostalComparable(searchPostal)) {
+      throw new AddressVerificationError(
+        `Postal code mismatch: expected ${searchPostal}, got ${retrieved.postalCode}`
+      );
+    }
+    if (request.city && normalizeComparable(request.city) !== normalizeComparable(retrieved.city)) {
+      throw new AddressVerificationError(
+        `City mismatch: expected ${request.city}, got ${retrieved.city}`
+      );
+    }
+    if (request.stateProvince && normalizeComparable(request.stateProvince) !== normalizeComparable(retrieved.provinceCode)) {
+      throw new AddressVerificationError(
+        `Province mismatch: expected ${request.stateProvince}, got ${retrieved.provinceCode}`
+      );
+    }
+    return {
+      country: "CA",
+      postalCode: normalizeCanadianPostalCode(retrieved.postalCode),
+      city: retrieved.city,
+      stateProvince: retrieved.provinceCode,
+      addressLine1: retrieved.line1,
+      addressLine2: retrieved.line2,
+      source: this.name,
+      uspsVerified: false
+    };
+  }
+  async findAndRetrieve(args) {
+    const findPayload = await this.callFind(args.searchTerm, args.signal);
+    const firstId = findPayload.Items?.find((item) => isNonEmptyString(item.Id))?.Id;
+    if (!firstId) {
+      throw new AddressProviderError("CanadaPost find returned no candidate addresses");
+    }
+    const retrieved = await this.callRetrieve(firstId, args.signal);
+    const first = retrieved.Items?.[0];
+    if (!first) {
+      throw new AddressProviderError("CanadaPost retrieve returned no addresses");
+    }
+    return {
+      line1: first.Line1,
+      line2: first.Line2,
+      city: first.City,
+      provinceCode: first.ProvinceCode,
+      postalCode: first.PostalCode
+    };
+  }
+  async callFind(searchTerm, signal) {
+    const params = new URLSearchParams({
+      Key: this.key,
+      SearchTerm: searchTerm,
+      Country: "CAN",
+      Limit: "5"
+    });
+    const url = `${this.findEndpoint}?${params.toString()}`;
+    return await fetchJsonOrThrow(url, {
+      signal,
+      errorPrefix: "CanadaPost find"
+    });
+  }
+  async callRetrieve(id, signal) {
+    const params = new URLSearchParams({
+      Key: this.key,
+      Id: id,
+      Country: "CAN"
+    });
+    const url = `${this.retrieveEndpoint}?${params.toString()}`;
+    return await fetchJsonOrThrow(url, {
+      signal,
+      errorPrefix: "CanadaPost retrieve"
+    });
+  }
+};
+
+export { AbortError, AddressProviderError, AddressVerificationError, CanadaPostAddressProvider, DEFAULT_NAME_PROVIDER, FakerNameProvider, InMemoryUniqueValueStore, ProviderNotFoundError, RetryExhaustedError, StaticDatasetNameProvider, TimeoutError, UspsAddressProvider, ZippopotamAddressProvider, clearScopedInMemoryStores, convertToCamelCase, deepMerge, formatStringValue, generateFirstName, generateFullName, generateLastName, generateRandomAlphabeticString, generateRandomAlphanumericString, generateRandomNDigitNumber, generateRandomNumber, generateRandomString, generateUniqueFirstName, generateUniqueFullName, generateUniqueLastName, getAlphaNumericString, getDate, getRelativeDate, getScopedInMemoryStore, getValidAddressByPostalCode, isDefined, isNonEmptyString, isNullOrEmptyString, isPlainObject, memoize, pLimit, parseBooleanString, renameMapKey, replaceTemplateValues, retry, snakeToPascalCase, splitString, updateJsonData, updateJsonValues, updateKey, verifyAddress, withTimeout };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map