stentor-address 1.61.0

package/LICENSE.md

@@ -0,0 +1,176 @@
+                               Apache License
+                         Version 2.0, January 2004
+                      http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+        Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+        stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+        that You distribute, all copyright, patent, trademark, and
+        attribution notices from the Source form of the Work,
+        excluding those notices that do not pertain to any part of
+        the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+        distribution, then any Derivative Works that You distribute must
+        include a readable copy of the attribution notices contained
+        within such NOTICE file, excluding those notices that do not
+        pertain to any part of the Derivative Works, in at least one
+        of the following places: within a NOTICE text file distributed
+        as part of the Derivative Works; within the Source form or
+        documentation, if provided along with the Derivative Works; or,
+        within a display generated by the Derivative Works, if and
+        wherever such third-party notices normally appear. The contents
+        of the NOTICE file are for informational purposes only and
+        do not modify the License. You may add Your own attribution
+        notices within Derivative Works that You distribute, alongside
+        or as an addendum to the NOTICE text from the Work, provided
+        that such additional attribution notices cannot be construed
+        as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,5 @@
+## stentor-address
+
+A set of shared utilities for address parsing.
+
+Also includes zip to timezone functions and haversine distance calculations.

package/lib/address.d.ts

@@ -0,0 +1,53 @@
+/*! Copyright (c) 2025, XAPP AI */
+import { AddressIntentRequestSlotMap } from "stentor-models";
+import * as addresser from "addresser";
+export interface ParsedAddress extends Omit<addresser.IParsedAddress, "id" | "zipCode"> {
+    formattedAddress?: string;
+    /**
+     * Direction such as NW, SE, etc.
+     */
+    streetDirection?: string;
+    /**
+     * Zip/Postal Code
+     */
+    zipCode?: string;
+    /**
+     * Place name, typically the city or town.
+     */
+    placeName: string;
+    /**
+     * An ID for the address.
+     *
+     * @note It is not recommended to use this.
+     */
+    id?: string;
+}
+/**
+ * Attempts to parse an address from a string.
+ *
+ * @param address
+ * @returns Parsed address in ParsedAddress format
+ */
+export declare function parseAddress(address: string): ParsedAddress | undefined;
+/**
+ * Forms an address string from from the slots.
+ *
+ * @param slots
+ * @returns
+ */
+export declare function formAddressFromSlots(slots: AddressIntentRequestSlotMap): string;
+/**
+ * Attempts to parse an address from a string.
+ *
+ * @param address
+ * @returns
+ */
+export declare function parseAddressAsSlots(address: string): AddressIntentRequestSlotMap;
+/**
+ * Takes an input and attempts to parse out all the components
+ *
+ * It can be passed a partial address object and will attempt to fill in the missing components if a fullAddress is provided
+ *
+ * @param input
+ */
+export declare function getAddressComponents(input: string | Partial<ParsedAddress>): ParsedAddress;

package/lib/address.js

@@ -0,0 +1,263 @@
+"use strict";
+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.parseAddress = parseAddress;
+exports.formAddressFromSlots = formAddressFromSlots;
+exports.parseAddressAsSlots = parseAddressAsSlots;
+exports.getAddressComponents = getAddressComponents;
+const stentor_utils_1 = require("stentor-utils");
+const addresser = __importStar(require("addresser"));
+/**
+ * Custom fallback parser for address strings.
+ *
+ * @param formattedAddress
+ * @returns Parsed address in the format of IParsedAddress
+ */
+function customParseAddress(formattedAddress) {
+    const parsedAddress = {
+        zipCode: "",
+        stateAbbreviation: "",
+        stateName: "",
+        placeName: "",
+        addressLine1: "",
+        streetNumber: "",
+        streetSuffix: "",
+        streetName: "",
+        id: "",
+    };
+    const parts = formattedAddress.split(",").map((part) => part.trim());
+    if (parts.length === 4) {
+        // Format: "Street, City, State/Province PostalCode, Country"
+        parsedAddress.addressLine1 = parts[0];
+        parsedAddress.placeName = parts[1];
+        const statePostal = parts[2].split(" ");
+        if (statePostal.length > 1 && /^[A-Z]\d[A-Z]\s?\d[A-Z]\d$/.test(statePostal.slice(-2).join(" "))) {
+            parsedAddress.stateAbbreviation = statePostal.slice(0, -2).join(" ");
+            parsedAddress.zipCode = statePostal.slice(-2).join(" ");
+        }
+        else {
+            parsedAddress.stateAbbreviation = statePostal.slice(0, -1).join(" ");
+            parsedAddress.zipCode = statePostal[statePostal.length - 1];
+        }
+        parsedAddress.stateName = parsedAddress.stateAbbreviation; // Fallback since the full name isn't provided
+    }
+    else if (parts.length === 3) {
+        // Format: "City, State/Province PostalCode, Country"
+        parsedAddress.placeName = parts[0];
+        const statePostal = parts[1].split(" ");
+        if (statePostal.length > 1 && /^[A-Z]\d[A-Z]\s?\d[A-Z]\d$/.test(statePostal.slice(-2).join(" "))) {
+            parsedAddress.stateAbbreviation = statePostal.slice(0, -2).join(" ");
+            parsedAddress.zipCode = statePostal.slice(-2).join(" ");
+        }
+        else {
+            parsedAddress.stateAbbreviation = statePostal.slice(0, -1).join(" ");
+            parsedAddress.zipCode = statePostal[statePostal.length - 1];
+        }
+        parsedAddress.stateName = parsedAddress.stateAbbreviation; // Fallback since the full name isn't provided
+    }
+    else {
+        console.warn("Unexpected address format:", formattedAddress);
+    }
+    parsedAddress.id = `${parsedAddress.placeName}-${parsedAddress.zipCode}-${parsedAddress.addressLine1}`
+        .replace(/\s+/g, "-")
+        .toLowerCase();
+    return parsedAddress;
+}
+/**
+ * Attempts to parse an address from a string.
+ *
+ * @param address
+ * @returns Parsed address in ParsedAddress format
+ */
+function parseAddress(address) {
+    let addressed;
+    try {
+        addressed = addresser.parseAddress(address);
+    }
+    catch (e) {
+        // Not a valid address
+        // Fallback to custom parser
+        addressed = customParseAddress(address);
+    }
+    return addressed;
+}
+/**
+ * Forms an address string from from the slots.
+ *
+ * @param slots
+ * @returns
+ */
+function formAddressFromSlots(slots) {
+    const hasCity = slots.city && slots.city.value;
+    const hasState = slots.state && slots.state.value;
+    let address = "";
+    if (slots.street_number && slots.street_number.value) {
+        address += slots.street_number.value + " ";
+    }
+    if (slots.street && slots.street.value) {
+        // make sure we aren't adding the street number twice
+        // see if street starts with street number, if it does don't add it
+        if (slots.street.value.trim().startsWith(address.trim())) {
+            // just replace it since it is a dupe
+            address = slots.street.value + " ";
+        }
+        else {
+            address += slots.street.value + " ";
+        }
+    }
+    else if (slots.street_name && slots.street_name.value) {
+        address += slots.street_name.value + " ";
+    }
+    // if we have quadrant and it isn't already in the street name
+    if (slots.quadrant &&
+        slots.quadrant.value &&
+        !address.trim().toLowerCase().endsWith(slots.quadrant.value.toLowerCase())) {
+        address += slots.quadrant.value + " ";
+    }
+    if (hasCity || hasState) {
+        address = address.trim();
+        address += ", ";
+    }
+    if (slots.city && slots.city.value) {
+        if (hasState) {
+            address += slots.city.value + ", ";
+        }
+        else {
+            address += slots.city.value + " ";
+        }
+    }
+    if (slots.state && slots.state.value) {
+        address += slots.state.value + " ";
+    }
+    if (slots.zip && slots.zip.value) {
+        address += slots.zip.value;
+    }
+    return address.trim();
+}
+/**
+ * Attempts to parse an address from a string.
+ *
+ * @param address
+ * @returns
+ */
+function parseAddressAsSlots(address) {
+    const slots = {};
+    let addressed;
+    try {
+        addressed = addresser.parseAddress(address);
+    }
+    catch (e) {
+        // not a valid address
+        console.warn(`Unable to parse address string "${address}"`);
+    }
+    if (addressed) {
+        // Pull out the zipCode
+        slots.zip = {
+            name: "zip",
+            value: addressed.zipCode,
+        };
+        slots.city = {
+            name: "city",
+            value: addressed.placeName,
+        };
+        slots.state = {
+            name: "state",
+            value: addressed.stateName,
+        };
+        slots.street_number = {
+            name: "street_number",
+            value: addressed.streetNumber,
+        };
+        slots.street = {
+            name: "street",
+            value: addressed.addressLine1,
+        };
+        slots.street_name = {
+            name: "street_name",
+            value: addressed.addressLine1.replace(addressed.streetNumber, "").trim(),
+        };
+        const fullAddress = formAddressFromSlots(slots);
+        if (fullAddress) {
+            slots.address = {
+                name: "address",
+                value: fullAddress,
+            };
+        }
+    }
+    return slots;
+}
+/**
+ * Takes an input and attempts to parse out all the components
+ *
+ * It can be passed a partial address object and will attempt to fill in the missing components if a fullAddress is provided
+ *
+ * @param input
+ */
+function getAddressComponents(input) {
+    let parsedAddress;
+    if (typeof input === "string") {
+        parsedAddress = parseAddress(input);
+    }
+    else {
+        parsedAddress = input;
+    }
+    // do some tests to make sure we have all the components
+    if (!parsedAddress.stateAbbreviation || !parsedAddress.stateName) {
+        // attempt to parse the address section and merge it in
+        const parsedFormattedAddress = parseAddress(parsedAddress.formattedAddress || parsedAddress.addressLine1);
+        // clean off the parsedFormattedAddress to remove any empty strings & values
+        const pruned = (0, stentor_utils_1.pruneEmpty)(parsedFormattedAddress);
+        parsedAddress = Object.assign(Object.assign({}, parsedAddress), pruned);
+    }
+    if (!parsedAddress.id) {
+        // id is just concatenation of the address
+        let id = "";
+        if (parsedAddress.addressLine1) {
+            id += `${parsedAddress.addressLine1},`;
+        }
+        if (parsedAddress.placeName) {
+            id += `-${parsedAddress.placeName},`;
+        }
+        if (parsedAddress.stateName) {
+            id += `-${parsedAddress.stateName}`;
+        }
+        if (parsedAddress.zipCode) {
+            id += `-${parsedAddress.zipCode}`;
+        }
+        parsedAddress.id = id.replace(/\s+/g, "-");
+    }
+    return parsedAddress;
+}
+//# sourceMappingURL=address.js.map

package/lib/address.js.map

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

package/lib/haversine.d.ts

@@ -0,0 +1,30 @@
+/*! Copyright (c) 2025, XAPP AI */
+/**
+ * Calculate the Haversine distance between two points on the Earth.
+ * @param one The first point with latitude and longitude.
+ * @param two The second point with latitude and longitude.
+ * @returns The distance between the two points in kilometers.
+ */
+export declare function haversineDistanceKm(one: {
+    lat: number;
+    lon: number;
+}, two: {
+    lat: number;
+    lon: number;
+}): number;
+/**
+ * Calculate the Haversine distance between two points on the Earth in miles.
+ *
+ * Calls first haversineDistanceKm and uses a conversion rate of 1 km = 0.621371 miles.
+ *
+ * @param one The first point with latitude and longitude.
+ * @param two The second point with latitude and longitude.
+ * @returns The distance between the two points in miles.
+ */
+export declare function haversineDistanceMiles(one: {
+    lat: number;
+    lon: number;
+}, two: {
+    lat: number;
+    lon: number;
+}): number;

package/lib/haversine.js

@@ -0,0 +1,36 @@
+"use strict";
+/*! Copyright (c) 2025, XAPP AI */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.haversineDistanceKm = haversineDistanceKm;
+exports.haversineDistanceMiles = haversineDistanceMiles;
+/**
+ * Calculate the Haversine distance between two points on the Earth.
+ * @param one The first point with latitude and longitude.
+ * @param two The second point with latitude and longitude.
+ * @returns The distance between the two points in kilometers.
+ */
+function haversineDistanceKm(one, two) {
+    const { lat: lat1, lon: lon1 } = one;
+    const { lat: lat2, lon: lon2 } = two;
+    const R = 6371; // Radius of Earth in km
+    const toRad = (x) => (x * Math.PI) / 180;
+    const dLat = toRad(lat2 - lat1);
+    const dLon = toRad(lon2 - lon1);
+    const a = Math.pow(Math.sin(dLat / 2), 2) + Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.pow(Math.sin(dLon / 2), 2);
+    const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+    return R * c;
+}
+/**
+ * Calculate the Haversine distance between two points on the Earth in miles.
+ *
+ * Calls first haversineDistanceKm and uses a conversion rate of 1 km = 0.621371 miles.
+ *
+ * @param one The first point with latitude and longitude.
+ * @param two The second point with latitude and longitude.
+ * @returns The distance between the two points in miles.
+ */
+function haversineDistanceMiles(one, two) {
+    const km = haversineDistanceKm(one, two);
+    return km * 0.621371; // convert km to miles
+}
+//# sourceMappingURL=haversine.js.map

package/lib/haversine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"haversine.js","sourceRoot":"","sources":["../src/haversine.ts"],"names":[],"mappings":";AAAA,kCAAkC;;AAQlC,kDAWC;AAWD,wDAGC;AA/BD;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,GAAiC,EAAE,GAAiC;IACtG,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC;IACrC,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC;IAErC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,wBAAwB;IACxC,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC;IACzD,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAChC,MAAM,CAAC,GAAG,SAAA,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,EAAI,CAAC,CAAA,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,SAAA,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,EAAI,CAAC,CAAA,CAAC;IAC5G,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACzD,OAAO,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,sBAAsB,CAAC,GAAiC,EAAE,GAAiC;IACzG,MAAM,EAAE,GAAG,mBAAmB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,OAAO,EAAE,GAAG,QAAQ,CAAC,CAAC,sBAAsB;AAC9C,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+/*! Copyright (c) 2025, XAPP AI */
+export * from "./address";
+export * from "./haversine";
+export * from "./zipToTZ";

package/lib/index.js

@@ -0,0 +1,21 @@
+"use strict";
+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 });
+/*! Copyright (c) 2025, XAPP AI */
+__exportStar(require("./address"), exports);
+__exportStar(require("./haversine"), exports);
+__exportStar(require("./zipToTZ"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,kCAAkC;AAClC,4CAA0B;AAC1B,8CAA4B;AAC5B,4CAA0B"}

package/lib/zipToTZ.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Converts a ZIP code that is in the 5-digit format to a timezone string, such as "America/New_York".
+ *
+ * @param zip
+ * @throws Error if the ZIP code is not in the correct format or if the timezone is not found.
+ * @returns
+ */
+export declare function zipToTz(zip: string): string;

package/lib/zipToTZ.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zipToTz = zipToTz;
+/*! Copyright (c) 2025, XAPP AI */
+const zipToTZData_1 = require("./zipToTZData"); // adjust path as needed
+/**
+ * Converts a ZIP code that is in the 5-digit format to a timezone string, such as "America/New_York".
+ *
+ * @param zip
+ * @throws Error if the ZIP code is not in the correct format or if the timezone is not found.
+ * @returns
+ */
+function zipToTz(zip) {
+    const cleanZip = zip.replace(/\s/g, "");
+    if (!/^\d{5}$/.test(cleanZip)) {
+        console.warn(`Invalid ZIP code format: ${zip}`);
+    }
+    return zipToTZData_1.zipToTimezone[cleanZip];
+}
+//# sourceMappingURL=zipToTZ.js.map

package/lib/zipToTZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zipToTZ.js","sourceRoot":"","sources":["../src/zipToTZ.ts"],"names":[],"mappings":";;AAUA,0BAQC;AAlBD,kCAAkC;AAClC,+CAA8C,CAAC,wBAAwB;AAEvE;;;;;;GAMG;AACH,SAAgB,OAAO,CAAC,GAAW;IACjC,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAExC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,4BAA4B,GAAG,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,2BAAa,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/lib/zipToTZData.d.ts

@@ -0,0 +1,2 @@
+/*! Copyright (c) 2025, XAPP AI */
+export declare const zipToTimezone: Record<string, string>;