Skip to content

README.md

Latest commit

 

History

History
203 lines (142 loc) · 7.22 KB

README.md

File metadata and controls

203 lines (142 loc) · 7.22 KB

SMARTY DISCLAIMER: Subject to the terms of the associated license agreement, this software is freely available for your use. This software is FREE, AS IN PUPPIES, and is a gift. Enjoy your new responsibility. This means that while we may consider enhancement requests, we may or may not choose to entertain requests at our sole and absolute discretion.

Smarty JavaScript SDK

The official JavaScript/TypeScript SDK for accessing Smarty address validation APIs. Works in both Node.js and browser environments.

npm license

Installation

npm install smartystreets-javascript-sdk

Quick Start: US Street Address Validation

import SmartySDK from "smartystreets-javascript-sdk";

const credentials = new SmartySDK.core.StaticCredentials(
  process.env.SMARTY_AUTH_ID,
  process.env.SMARTY_AUTH_TOKEN,
);
const client = new SmartySDK.core.ClientBuilder(credentials).buildUsStreetApiClient();

const lookup = new SmartySDK.usStreet.Lookup();
lookup.street = "1600 Amphitheatre Parkway";
lookup.city = "Mountain View";
lookup.state = "CA";

const response = await client.send(lookup);
console.log(response.lookups[0].result);

Quick Start: US Autocomplete Pro

const client = new SmartySDK.core.ClientBuilder(credentials).buildUsAutocompleteProClient();

const lookup = new SmartySDK.usAutocompletePro.Lookup("4770 Lincoln");
lookup.maxResults = 10;
lookup.preferStates = ["IL"];

const response = await client.send(lookup);
console.log(response.result); // Array of address suggestions

Supported APIs

API Module Build Method Example
US Street usStreet buildUsStreetApiClient() example
US Zipcode usZipcode buildUsZipcodeClient() example
US Autocomplete Pro usAutocompletePro buildUsAutocompleteProClient() example
US Extract usExtract buildUsExtractClient() example
US Enrichment usEnrichment buildUsEnrichmentClient() example
US Reverse Geocoding usReverseGeo buildUsReverseGeoClient() example
International Street internationalStreet buildInternationalStreetClient() example
International Autocomplete internationalAddressAutocomplete buildInternationalAddressAutocompleteClient() example
International Postal Code internationalPostalCode buildInternationalPostalCodeClient() example

Authentication

Three credential types are available:

  • StaticCredentials(authId, authToken) — Server-side authentication using auth-id and auth-token.
  • SharedCredentials(key) — Client-side (browser) authentication using an embedded key. Does not support batch (POST) requests.
  • BasicAuthCredentials(authId, authToken) — HTTP Basic Auth.

Browser Usage

The SDK works in modern browsers out of the box — it uses the native fetch API for transport.

Credentials

Use SharedCredentials with an embedded key registered to your website's host:

const credentials = new SmartySDK.core.SharedCredentials("YOUR_EMBEDDED_KEY");
const client = new SmartySDK.core.ClientBuilder(credentials).buildUsStreetApiClient();

Note that SharedCredentials does not support batch (POST) requests — send one lookup at a time.

Features not available in the browser

  • withProxy() is Node-only. It relies on undici's ProxyAgent, which uses Node internals. Browsers route requests through the user's network configuration, so a proxy option wouldn't apply anyway.
  • Batch requests require StaticCredentials or BasicAuthCredentials, which should not be used in the browser (they'd expose your auth-token to end users).

Bundler configuration

undici is an optionalDependencies entry and is only imported dynamically when withProxy() is called. Some bundlers still statically analyze the dynamic import("undici") call and emit a warning or try to resolve it. If that happens, tell your bundler to ignore or externalize undici:

webpack

// webpack.config.js
module.exports = {
  resolve: {
    fallback: { undici: false },
  },
};

Vite / Rollup

// vite.config.js
export default {
  build: {
    rollupOptions: {
      external: ["undici"],
    },
  },
};

esbuild

esbuild app.js --bundle --external:undici

Common Patterns

Batch Requests

Send up to 100 lookups in a single request (not available with SharedCredentials):

const batch = new SmartySDK.core.Batch();
batch.add(lookup1);
batch.add(lookup2);

const response = await client.send(batch);

Error Handling

All API errors extend SmartyError:

import { SmartyError } from "smartystreets-javascript-sdk";

try {
  const response = await client.send(lookup);
} catch (err) {
  if (err instanceof SmartyError) {
    console.error("API error:", err.message);
  }
}

Retry and Timeout

const client = new SmartySDK.core.ClientBuilder(credentials)
  .withMaxRetries(10)
  .withMaxTimeout(30000)
  .buildUsStreetApiClient();

Proxy

const client = new SmartySDK.core.ClientBuilder(credentials)
  .withProxy("proxy.example.com", 8080, "https")
  .buildUsStreetApiClient();

Custom Headers

const client = new SmartySDK.core.ClientBuilder(credentials)
  .withCustomHeaders({ "X-Custom-Header": "value" })
  .buildUsStreetApiClient();

TypeScript

The SDK is written in TypeScript and ships with full type declarations — no @types/ package needed. All types are available as named exports:

import SmartySDK, { type MatchStrategy, type SmartyError } from "smartystreets-javascript-sdk";

const lookup = new SmartySDK.usStreet.Lookup();
lookup.street = "1600 Amphitheatre Parkway";
lookup.match = "enhanced" satisfies MatchStrategy;

JavaScript users benefit too — editors like VS Code automatically pick up the bundled type declarations, providing autocompletion and hover docs with no configuration.

See UPGRADING.md for details on migrating from the previous JavaScript-only release.

Documentation

Full API documentation is available at smarty.com/docs/sdk/javascript.

License

Apache 2.0