SmartyStreets JavaScript SDK Utilities

Common errors

• TypeError: Cannot read properties of undefined (reading 'result')

  cause The utility functions (e.g., `isValid`, `isAmbiguous`) expect a `lookup` object that has successfully been processed by the SmartyStreets SDK and contains a `result` property, which might be `undefined` if the API call failed or the lookup itself was malformed.
  fix Ensure that the `lookup` object passed to the utility functions is valid and populated from a successful API response. Add error handling for the `client.send()` promise to catch failures before attempting to use the utilities.

• ReferenceError: require is not defined

  cause This error occurs when attempting to use CommonJS `require()` syntax in an environment configured for ES Modules (ESM), such as a modern Node.js project with `"type": "module"` in `package.json` or in a browser context without a transpiler.
  fix Switch to ES Module `import` syntax. For example, change `const utils = require("smartystreets-javascript-sdk-utils");` to `import * as utils from "smartystreets-javascript-sdk-utils";` or `import { isValid } from "smartystreets-javascript-sdk-utils";`.

Warnings

• gotcha The SmartyStreets JavaScript SDK Utils package is provided 'AS IS' and 'as a gift.' This means that while enhancement requests may be considered, there is no guarantee of official support, bug fixes, or new features. Users should be aware of this limited maintenance model.
  Fix: Plan for potential self-maintenance or be prepared for the library's functionality to remain static.
• gotcha This utility library is specifically designed to work with lookup objects returned by the `smartystreets-javascript-sdk`. Passing objects from other sources or incorrectly structured lookup objects will lead to undefined behavior or incorrect results.
  Fix: Always ensure the input to utility functions like `isValid()` is a `US Street Lookup` object that has been processed by the `smartystreets-javascript-sdk`.

Install

• npm install smartystreets-javascript-sdk-utils npm
• yarn add smartystreets-javascript-sdk-utils yarn
• pnpm add smartystreets-javascript-sdk-utils pnpm

Imports

• utils
  wrong:

  const utils = require('smartystreets-javascript-sdk-utils');

  correct:

  import * as utils from 'smartystreets-javascript-sdk-utils';

  The README example uses CommonJS `require`, but for modern Node.js and browser environments, ESM `import * as utils` is preferred for named exports.
• isValid
  wrong:

  import isValid from 'smartystreets-javascript-sdk-utils';

  correct:

  import { isValid } from 'smartystreets-javascript-sdk-utils';

  Functions like `isValid`, `isInvalid`, etc., are named exports from the utility package. The `utils` object contains these as properties if imported as `* as utils`.
• isAmbiguous
  wrong:

  const { isAmbiguous } = require('smartystreets-javascript-sdk-utils');

  correct:

  import { isAmbiguous } from 'smartystreets-javascript-sdk-utils';

  Direct destructuring from CommonJS `require` is common, but named imports are the modern standard for modularity.

Quickstart

This example demonstrates how to integrate `smartystreets-javascript-sdk-utils` with the main SmartyStreets SDK to perform address validation and then analyze the response using the utility functions like `isValid`, `isInvalid`, `isAmbiguous`, and `isMissingSecondary`. It covers authentication setup, creating a lookup, sending it via the client, and then interpreting the results programmatically using the utility library.

import * as SmartySDK from 'smartystreets-javascript-sdk';
import * as SmartyUtils from 'smartystreets-javascript-sdk-utils';

const SmartyCore = SmartySDK.core;
const Lookup = SmartySDK.usStreet.Lookup;

// Use environment variables for credentials
const authId = process.env.SMARTY_AUTH_ID ?? 'YOUR_SMARTY_AUTH_ID';
const authToken = process.env.SMARTY_AUTH_TOKEN ?? 'YOUR_SMARTY_AUTH_TOKEN';

if (authId === 'YOUR_SMARTY_AUTH_ID' || authToken === 'YOUR_SMARTY_AUTH_TOKEN') {
  console.warn('Please set SMARTY_AUTH_ID and SMARTY_AUTH_TOKEN environment variables or replace placeholders.');
}

let clientBuilder = new SmartyCore.ClientBuilder(new SmartyCore.StaticCredentials(authId, authToken));
let client = clientBuilder.buildUsStreetApiClient();

let lookup1 = new Lookup();
lookup1.street = "1600 Pennsylvania Ave NW";
lookup1.city = "Washington";
lookup1.state = "DC";

client.send(lookup1)
    .then(handleSuccess)
    .catch(handleError);

function handleSuccess(response) {
    response.lookups.map(lookup => console.log('Result for ' + lookup.inputString + ':', lookup.result));

    // Demonstrate utility functions for the first lookup in the response
    if (response.lookups.length > 0) {
        const firstLookupResult = response.lookups[0];
        console.log(`Is '${firstLookupResult.inputString}' valid (mail deliverable)?`, SmartyUtils.isValid(firstLookupResult));
        console.log(`Is '${firstLookupResult.inputString}' invalid (not mail deliverable)?`, SmartyUtils.isInvalid(firstLookupResult));
        console.log(`Is '${firstLookupResult.inputString}' ambiguous (multiple candidates)?`, SmartyUtils.isAmbiguous(firstLookupResult));
        console.log(`Is '${firstLookupResult.inputString}' missing a secondary address?`, SmartyUtils.isMissingSecondary(firstLookupResult));
    }
}

function handleError(error) {
    console.error("Error sending lookup:", error);
}