{"id":12045,"library":"smartystreets-javascript-sdk-utils","title":"SmartyStreets JavaScript SDK Utilities","description":"This library provides utility functions to perform additional analysis on responses from the SmartyStreets US Street API, specifically for lookups validated through the `smartystreets-javascript-sdk`. It offers functions like `isValid()`, `isInvalid()`, `isAmbiguous()`, and `isMissingSecondary()` to interpret the deliverability and clarity of address lookups based on USPS standards. The current stable version is 1.2.9. As per Smarty's disclaimer, this software is provided 'as is' and 'as a gift,' implying an infrequent or demand-driven release cadence and limited official support, differentiating it from commercially maintained libraries. It serves as an auxiliary package to enhance the core SmartyStreets JavaScript SDK functionality rather than a standalone solution.","status":"active","version":"1.2.9","language":"javascript","source_language":"en","source_url":"https://github.com/smartystreets/smartystreets-javascript-sdk-utils","tags":["javascript","smarty","smartystreets","address","validation","verification","verify","validate","street-address"],"install":[{"cmd":"npm install smartystreets-javascript-sdk-utils","lang":"bash","label":"npm"},{"cmd":"yarn add smartystreets-javascript-sdk-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add smartystreets-javascript-sdk-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package analyzes lookup objects generated and validated by the main SmartyStreets JavaScript SDK. It cannot function independently.","package":"smartystreets-javascript-sdk","optional":false}],"imports":[{"note":"The README example uses CommonJS `require`, but for modern Node.js and browser environments, ESM `import * as utils` is preferred for named exports.","wrong":"const utils = require('smartystreets-javascript-sdk-utils');","symbol":"utils","correct":"import * as utils from 'smartystreets-javascript-sdk-utils';"},{"note":"Functions like `isValid`, `isInvalid`, etc., are named exports from the utility package. The `utils` object contains these as properties if imported as `* as utils`.","wrong":"import isValid from 'smartystreets-javascript-sdk-utils';","symbol":"isValid","correct":"import { isValid } from 'smartystreets-javascript-sdk-utils';"},{"note":"Direct destructuring from CommonJS `require` is common, but named imports are the modern standard for modularity.","wrong":"const { isAmbiguous } = require('smartystreets-javascript-sdk-utils');","symbol":"isAmbiguous","correct":"import { isAmbiguous } from 'smartystreets-javascript-sdk-utils';"}],"quickstart":{"code":"import * as SmartySDK from 'smartystreets-javascript-sdk';\nimport * as SmartyUtils from 'smartystreets-javascript-sdk-utils';\n\nconst SmartyCore = SmartySDK.core;\nconst Lookup = SmartySDK.usStreet.Lookup;\n\n// Use environment variables for credentials\nconst authId = process.env.SMARTY_AUTH_ID ?? 'YOUR_SMARTY_AUTH_ID';\nconst authToken = process.env.SMARTY_AUTH_TOKEN ?? 'YOUR_SMARTY_AUTH_TOKEN';\n\nif (authId === 'YOUR_SMARTY_AUTH_ID' || authToken === 'YOUR_SMARTY_AUTH_TOKEN') {\n  console.warn('Please set SMARTY_AUTH_ID and SMARTY_AUTH_TOKEN environment variables or replace placeholders.');\n}\n\nlet clientBuilder = new SmartyCore.ClientBuilder(new SmartyCore.StaticCredentials(authId, authToken));\nlet client = clientBuilder.buildUsStreetApiClient();\n\nlet lookup1 = new Lookup();\nlookup1.street = \"1600 Pennsylvania Ave NW\";\nlookup1.city = \"Washington\";\nlookup1.state = \"DC\";\n\nclient.send(lookup1)\n    .then(handleSuccess)\n    .catch(handleError);\n\nfunction handleSuccess(response) {\n    response.lookups.map(lookup => console.log('Result for ' + lookup.inputString + ':', lookup.result));\n\n    // Demonstrate utility functions for the first lookup in the response\n    if (response.lookups.length > 0) {\n        const firstLookupResult = response.lookups[0];\n        console.log(`Is '${firstLookupResult.inputString}' valid (mail deliverable)?`, SmartyUtils.isValid(firstLookupResult));\n        console.log(`Is '${firstLookupResult.inputString}' invalid (not mail deliverable)?`, SmartyUtils.isInvalid(firstLookupResult));\n        console.log(`Is '${firstLookupResult.inputString}' ambiguous (multiple candidates)?`, SmartyUtils.isAmbiguous(firstLookupResult));\n        console.log(`Is '${firstLookupResult.inputString}' missing a secondary address?`, SmartyUtils.isMissingSecondary(firstLookupResult));\n    }\n}\n\nfunction handleError(error) {\n    console.error(\"Error sending lookup:\", error);\n}","lang":"javascript","description":"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."},"warnings":[{"fix":"Plan for potential self-maintenance or be prepared for the library's functionality to remain static.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'result')"},{"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\";`.","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.","error":"ReferenceError: require is not defined"}],"ecosystem":"npm"}