addressverify 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AETHER TECHNOLOGY LLC (AddressVerify)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# AddressVerify JavaScript / TypeScript SDK
+
+Official SDK for the [AddressVerify](https://addressverify.io) API: validate U.S. residential
+addresses, classify home types, and get estimated property values in real time.
+
+[![npm](https://img.shields.io/npm/v/addressverify.svg)](https://www.npmjs.com/package/addressverify)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+- 🏠 **Address validation**: confirm an address is a real, deliverable U.S. residence
+- 🏷️ **Home-type classification**: `SINGLE_FAMILY`, `MULTI_FAMILY`, `APARTMENT`, `CONDO`, `TOWNHOUSE`, `MANUFACTURED`, `LOT`
+- 💰 **Property values**: estimated home value, plus optional expanded property data
+- 📦 **Zero runtime dependencies**: uses native `fetch` (Node 18+)
+- 🟦 **Fully typed**: first-class TypeScript types
+
+## Installation
+
+```bash
+npm install addressverify
+```
+
+## Get an API key
+
+Create a free account at **[app.addressverify.io](https://app.addressverify.io/user/register)** and copy your API key from the dashboard. The free tier includes 50 free API calls to get started.
+
+## Quick start
+
+```ts
+import { AddressVerify } from "addressverify";
+
+const av = new AddressVerify({ apiKey: process.env.ADDRESSVERIFY_API_KEY! });
+
+// Single-line address
+const result = await av.verify("123 Main St, New York, NY 10001");
+
+console.log(result.addressValid); // true
+console.log(result.homeType);     // "SINGLE_FAMILY"
+console.log(result.homeValue);    // 273900
+```
+
+### Multi-line address
+
+```ts
+const result = await av.verify({
+  street: "20 Marie St",
+  city: "Iberia",
+  state: "MO",
+  zip: "65486",
+});
+```
+
+### Expanded property data
+
+Pass `{ expanded: true }` to receive parsed address components, property details, tax
+assessment, and listing data (available on all plans at no extra cost):
+
+```ts
+const result = await av.verify("20 Marie St, Iberia, MO 65486", { expanded: true });
+
+console.log(result.propertyInfo?.bedrooms);        // 4
+console.log(result.taxAssessment?.taxAssessedValue); // 150210
+console.log(result.listing?.listingStatus);        // "recentlySold"
+```
+
+## Response shape
+
+```jsonc
+{
+  "address": "20 Marie St, Iberia, MO 65486",
+  "addressValid": true,
+  "homeType": "SINGLE_FAMILY",
+  "homeValue": 371000,
+
+  // present only with { expanded: true }
+  "addressInfo":   { "streetAddress": "20 Marie St", "zipcode": "65486", "city": "Iberia", "state": "MO" },
+  "propertyInfo":  { "bathrooms": 2, "bedrooms": 4, "livingArea": 2072, "yearBuilt": 2001, "lotSize": "1.84 acres" },
+  "taxAssessment": { "taxAssessedValue": 150210, "taxAssessmentYear": "2024" },
+  "listing":       { "lastSoldDate": "2025-05-22", "isPreforeclosureAuction": false, "listingStatus": "recentlySold" }
+}
+```
+
+## Error handling
+
+Non-2xx responses throw an `AddressVerifyError` with the HTTP `status` and parsed `body`:
+
+```ts
+import { AddressVerify, AddressVerifyError } from "addressverify";
+
+try {
+  await av.verify("not a real address");
+} catch (err) {
+  if (err instanceof AddressVerifyError) {
+    console.error(err.status); // e.g. 422
+    console.error(err.body);   // API error payload
+  }
+}
+```
+
+| Status | Meaning |
+| ------ | ------- |
+| `400`  | Bad Request: invalid or missing parameters |
+| `401`  | Unauthorized: invalid API key |
+| `422`  | Invalid address (e.g. missing street number) |
+| `429`  | Too Many Requests: rate limit exceeded |
+
+## Configuration
+
+```ts
+new AddressVerify({
+  apiKey: "...",                          // required
+  baseUrl: "https://api.addressverify.io" // optional override
+});
+```
+
+`verify()` also accepts an `AbortSignal` for cancellation/timeouts:
+
+```ts
+await av.verify("123 Main St, New York, NY 10001", {
+  signal: AbortSignal.timeout(5000),
+});
+```
+
+## Roadmap
+
+- **Home Verify** (homeowner + person & property lookup, `…/isHomeOwner/homeOwner`): coming to the SDK. Already available on the [REST API](https://addressverify.io/docs).
+
+## Links
+
+- 🌐 Website: <https://addressverify.io>
+- 📚 API docs: <https://addressverify.io/docs>
+- 🔑 Get an API key: <https://app.addressverify.io/user/register>
+
+## License
+
+MIT © AddressVerify

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Official TypeScript/JavaScript SDK for the AddressVerify API.
+ *
+ * AddressVerify validates U.S. residential addresses, classifies home types,
+ * and returns estimated property values — with optional expanded property data.
+ *
+ * @see https://addressverify.io
+ * @see https://addressverify.io/docs
+ */
+/** Known home-type classifications. Unknown future values fall back to `string`. */
+export type HomeType = "SINGLE_FAMILY" | "MULTI_FAMILY" | "APARTMENT" | "CONDO" | "TOWNHOUSE" | "MANUFACTURED" | "LOT" | (string & {});
+/** Parsed address components (present only with `expanded: true`). */
+export interface AddressInfo {
+    streetAddress: string;
+    zipcode: string;
+    city: string;
+    state: string;
+}
+/** Physical property details (present only with `expanded: true`). */
+export interface PropertyInfo {
+    bathrooms: number;
+    bedrooms: number;
+    livingArea: number;
+    yearBuilt: number;
+    /** Lot size with unit, e.g. "5001 sqft" or "1.84 acres". */
+    lotSize: string;
+}
+/** Tax assessment data (present only with `expanded: true`). */
+export interface TaxAssessment {
+    taxAssessedValue: number;
+    taxAssessmentYear: string;
+}
+/** Listing/market data (present only with `expanded: true`). */
+export interface Listing {
+    /** Date the property was last sold (YYYY-MM-DD). */
+    lastSoldDate: string;
+    isPreforeclosureAuction: boolean;
+    /** e.g. "forSale", "recentlySold", "offMarket". */
+    listingStatus: string;
+}
+/** Response from {@link AddressVerify.verify}. Expanded fields appear only with `expanded: true`. */
+export interface VerifyResult {
+    address: string;
+    addressValid: boolean;
+    homeType: HomeType;
+    homeValue: number;
+    addressInfo?: AddressInfo;
+    propertyInfo?: PropertyInfo;
+    taxAssessment?: TaxAssessment;
+    listing?: Listing;
+}
+/** A full address on one line, e.g. "123 Main St, New York, NY 10001". */
+export type SingleLineInput = string | {
+    address: string;
+};
+/** A split address. */
+export interface MultiLineInput {
+    street: string;
+    city: string;
+    state: string;
+    zip: string;
+}
+export type VerifyInput = SingleLineInput | MultiLineInput;
+export interface AddressVerifyOptions {
+    /** Your API key (sent as the `x-api-key` header). Get one at https://app.addressverify.io/user/register */
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://api.addressverify.io */
+    baseUrl?: string;
+    /** Custom fetch implementation (defaults to the global `fetch`). */
+    fetch?: typeof fetch;
+}
+export interface VerifyRequestOptions {
+    /** Return expanded property data (addressInfo, propertyInfo, taxAssessment, listing). */
+    expanded?: boolean;
+    /** Abort signal for cancellation/timeouts. */
+    signal?: AbortSignal;
+}
+/** Thrown when the API responds with a non-2xx status. */
+export declare class AddressVerifyError extends Error {
+    /** HTTP status code (e.g. 400, 401, 422, 429). */
+    readonly status: number;
+    /** Parsed response body (JSON object when available, otherwise raw text). */
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * Client for the AddressVerify API.
+ *
+ * @example
+ * ```ts
+ * import { AddressVerify } from "addressverify";
+ *
+ * const av = new AddressVerify({ apiKey: process.env.ADDRESSVERIFY_API_KEY! });
+ *
+ * // Single-line
+ * const r = await av.verify("123 Main St, New York, NY 10001");
+ * console.log(r.addressValid, r.homeType, r.homeValue);
+ *
+ * // Multi-line + expanded property data
+ * const full = await av.verify(
+ *   { street: "20 Marie St", city: "Iberia", state: "MO", zip: "65486" },
+ *   { expanded: true },
+ * );
+ * console.log(full.propertyInfo?.bedrooms);
+ * ```
+ */
+export declare class AddressVerify {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: AddressVerifyOptions);
+    /**
+     * Verify an address.
+     *
+     * @param input Single-line string, `{ address }`, or `{ street, city, state, zip }`.
+     * @param options `{ expanded }` to request detailed property data.
+     * @throws {AddressVerifyError} on a non-2xx response.
+     */
+    verify(input: VerifyInput, options?: VerifyRequestOptions): Promise<VerifyResult>;
+}
+export default AddressVerify;

package/dist/index.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Official TypeScript/JavaScript SDK for the AddressVerify API.
+ *
+ * AddressVerify validates U.S. residential addresses, classifies home types,
+ * and returns estimated property values — with optional expanded property data.
+ *
+ * @see https://addressverify.io
+ * @see https://addressverify.io/docs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddressVerify = exports.AddressVerifyError = void 0;
+const DEFAULT_BASE_URL = "https://api.addressverify.io";
+const VERIFY_PATH = "/service/lookup/address";
+/** Thrown when the API responds with a non-2xx status. */
+class AddressVerifyError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.name = "AddressVerifyError";
+        this.status = status;
+        this.body = body;
+        Object.setPrototypeOf(this, AddressVerifyError.prototype);
+    }
+}
+exports.AddressVerifyError = AddressVerifyError;
+function isMultiLine(input) {
+    return typeof input === "object" && "street" in input;
+}
+/**
+ * Client for the AddressVerify API.
+ *
+ * @example
+ * ```ts
+ * import { AddressVerify } from "addressverify";
+ *
+ * const av = new AddressVerify({ apiKey: process.env.ADDRESSVERIFY_API_KEY! });
+ *
+ * // Single-line
+ * const r = await av.verify("123 Main St, New York, NY 10001");
+ * console.log(r.addressValid, r.homeType, r.homeValue);
+ *
+ * // Multi-line + expanded property data
+ * const full = await av.verify(
+ *   { street: "20 Marie St", city: "Iberia", state: "MO", zip: "65486" },
+ *   { expanded: true },
+ * );
+ * console.log(full.propertyInfo?.bedrooms);
+ * ```
+ */
+class AddressVerify {
+    constructor(options) {
+        if (!options || !options.apiKey) {
+            throw new Error("AddressVerify: `apiKey` is required.");
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("AddressVerify: global `fetch` is unavailable. Use Node 18+ or pass a `fetch` implementation.");
+        }
+        this.fetchImpl = fetchImpl;
+    }
+    /**
+     * Verify an address.
+     *
+     * @param input Single-line string, `{ address }`, or `{ street, city, state, zip }`.
+     * @param options `{ expanded }` to request detailed property data.
+     * @throws {AddressVerifyError} on a non-2xx response.
+     */
+    async verify(input, options = {}) {
+        const body = typeof input === "string"
+            ? { address: input }
+            : isMultiLine(input)
+                ? { street: input.street, city: input.city, state: input.state, zip: input.zip }
+                : { address: input.address };
+        const url = `${this.baseUrl}${VERIFY_PATH}${options.expanded ? "?expanded=true" : ""}`;
+        const response = await this.fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "x-api-key": this.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+            signal: options.signal,
+        });
+        const raw = await response.text();
+        let data = null;
+        if (raw) {
+            try {
+                data = JSON.parse(raw);
+            }
+            catch {
+                data = raw;
+            }
+        }
+        if (!response.ok) {
+            const detail = data && typeof data === "object" && "message" in data
+                ? String(data.message)
+                : response.statusText;
+            throw new AddressVerifyError(`AddressVerify request failed (${response.status} ${detail})`, response.status, data);
+        }
+        return data;
+    }
+}
+exports.AddressVerify = AddressVerify;
+exports.default = AddressVerify;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "addressverify",
+  "version": "0.1.0",
+  "description": "Official TypeScript/JavaScript SDK for the AddressVerify API: validate residential addresses, classify home types, and get property values.",
+  "keywords": [
+    "addressverify",
+    "address verification",
+    "address validation",
+    "usps",
+    "property data",
+    "home value",
+    "real estate api",
+    "api",
+    "sdk"
+  ],
+  "homepage": "https://addressverify.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AddressVerify-io/addressverify-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AddressVerify-io/addressverify-js/issues"
+  },
+  "license": "MIT",
+  "author": "AddressVerify (https://addressverify.io)",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}