@nuskin/shipping-address-client

Shipping Address Service Client

JavaScript client for the Nu Skin Shipping Address Service web API

• Shipping Address Service Client
  • Installing
  • Initializing the Client
  • Using the Client
    • Requesting saved addresses
    • Saving a new address
    • Updating a saved address
    • Deleting a saved address
    • Getting market shipping date restrictions
    • Finding address data matching a postal code
  • Handling Errors

Installing

Using npm:

$ npm install @nuskin/shipping-address-client

Using Yarn:

$ yarn add @nuskin/shipping-address-client

Initializing the Client

Initialize a new instance of the client by providing the following parameters to the constructor:

• awsBaseURL - The Nu Skin AWS cloud API's base URL.
• legacyBaseURL - The Nu Skin legacy web API's base URL.
• clientID - The web API client ID.
• clientSecret - The web API client secret.
• country - The country that requests are made for.
• language - The language that requests are made for.
• userID - The ID of the user that requests are made for.
• userToken - The auth token (eid) of the user that requests are made for.

Example:

import { ShippingAddressClient } from "@nuskin/shipping-address-client";

const client = new ShippingAddressClient({
  awsBaseURL: "https://api.cloud.nuskin.com",
  legacyBaseURL: "https://www.nuskin.com",
  clientID: "0123...aeae",
  clientSecret: "8888...aa00",
  country: "US",
  language: "en",
  userID: "ZZ9999999",
  userToken: "ey5G...3Agw"
});

Using the Client

Requesting saved addresses

Call client.getShippingAddresses(country) to retrieve the user's saved shipping addresses.

The argument country is optional: omit if requesting shipping addresses for the country provided to the constructor, provide country if requesting shipping addresses for the user that are in a different country.

Example 1, requesting shipping addresses in current country:

client.getShippingAddresses().then(addresses => {
  console.log(addresses[0]);
  /*
  {
    beShippingAddressId: 123456789,
    shippingAddressName: "Sherlock Holmes",
    shippingAddress1: "221B Baker St",
    shippingAddress2: null,
    shippingCity: "Marylebone",
    shippingCounty: "London",
    shippingState: null,
    shippingPostalCode: "NW1 6XE",
    shippingCountry: "GB",
    shippingPhone: "01234567890",
    shippingMobilePhone: null,
    shippingInstructions: null,
    shippingAlias: "987654321098",
    addressType: "home",
    shippingEmail: null,
    defaultShipping: false
  }
  */
});

Example 2, requesting shipping addresses in another country:

client.getShippingAddresses("ZZ").then(addresses => {
  ...
});

Saving a new address

Call client.createShippingAddress(address) to save a new shipping address to the user's profile.

NOTE: when creating a new shipping address, DO NOT provide a beShippingAddressId field. That field is assigned by the server upon creation of the address, and is included in the saved address object returned by this function.

Example:

client
  .createShippingAddress({
    shippingAddressName: "Sherlock Holmes",
    shippingAddress1: "221B Baker St",
    shippingCity: "Marylebone",
    shippingCounty: "London",
    shippingPostalCode: "NW1 6XE",
    shippingCountry: "GB",
    shippingPhone: "01234567890",
    addressType: "home",
    defaultShipping: false
  })
  .then(address => {
    console.log(address);
    /*
    {
      beShippingAddressId: 123456789,
      shippingAddressName: "Sherlock Holmes",
      shippingAddress1: "221B Baker St",
      shippingAddress2: null,
      shippingCity: "Marylebone",
      shippingCounty: "London",
      shippingState: null,
      shippingPostalCode: "NW1 6XE",
      shippingCountry: "GB",
      shippingPhone: "01234567890",
      shippingMobilePhone: null,
      shippingInstructions: null,
      shippingAlias: "987654321098",
      addressType: "home",
      shippingEmail: null,
      defaultShipping: false
    }
    */
  });

Updating a saved address

Call client.updateShippingAddress(address) to update an existing saved shipping address.

Example:

client
  .updateShippingAddress({
    beShippingAddressId: 999999999,
    shippingAddressName: "Lex Luthor",
    shippingAddress1: "4458  Gregory Lane",
    shippingCity: "Louisville",
    shippingState: "KY",
    shippingPostalCode: "40202",
    shippingCountry: "US",
    shippingPhone: "502-555-7777",
    shippingMobilePhone: "502-555-9999",
    shippingAlias: "999988887777",
    addressType: "home",
    defaultShipping: true
  })
  .then(address => {
    console.log(address);
    /*
    {
      beShippingAddressId: 999999999,
      shippingAddressName: "Lex Luthor",
      shippingAddress1: "4458  Gregory Lane",
      shippingAddress2: null,
      shippingCity: "Louisville",
      shippingCounty: null,
      shippingState: "KY",
      shippingPostalCode: "40202",
      shippingCountry: "US",
      shippingPhone: "502-555-7777",
      shippingMobilePhone: "502-555-9999",
      shippingInstructions: null,
      shippingAlias: "999988887777",
      addressType: "home",
      shippingEmail: null,
      defaultShipping: true
    }
    */
  });

Deleting a saved address

Call client.deleteShippingAddress(ID) to delete an existing saved shipping address. The ID argument provided to this function is the beShippingAddressId field of the saved address.

Example:

const ID = 999999999; // beShippingAddressId of the saved shipping address

client.deleteShippingAddress(ID).then(succeeded => {
  console.log(succeeded); // true
});

Getting market shipping date restrictions

Markets have limits on the days of the month during which they can process and ship subscription orders. Call client.getShippingDays(country) to retrieve the subscription shipping date restrictions for the market in the given country.

If country is omitted, data is requested for the country that was provided to the constructor.

Example:

client.getShippingDays("GB").then(data => {
  console.log(data);
  /*
  {
    blackoutDays: [ 26, 27, 28, 29, 30, 31 ],
    defaultShipDay: 16,
    blackoutPeriod: 1
  }
  */
});

Finding address data matching a postal code

Some markets provide address autocompletion by looking up the city, county, and state corresponding to a given postal code.

Call client.findCitiesByPostalCode(code, country) to find address data matching the given postal code in the given country. If country is omitted, address data will be requested for the country provided to the constructor.

Example:

client.findCitiesByPostalCode("53300", "MY").then(matches => {
  console.log(matches[0]);
  /*
  {
    postalcode: "53300",
    region: "WP",
    regionDesc: null,
    district: null,
    districtDesc: "MALAYSIA",
    city: "KUALA LUMPUR",
    street: null,
    building: null,
    timeDesignationAllowed: "false"
  }
  */
});

Handling Errors

Promises returned by the Shipping Address Service Client may reject with either a plain Error instance or with a ShippingAddressServiceError instance.

The ShippingAddressServiceError class represents errors caused by the web API rejecting a request. The class takes the following form:

// Payment Service Error
class ShippingAddressServiceError extends Error {
  // HTTP status code returned by the web API
  status: number;

  // List of messages returned by the web API
  messages: Array<{
    // Message level: "iNFO", "WARN", "ERROR"
    level: string;

    // Error code
    code: string;

    // Server exception type
    type: string;

    // Localized message text for display to the user
    message: string;

    // Technical message text for debugging
    technicalMessage: string;
  }>;
}

The list of messages included in a ShippingAddressServiceError instance are intended to provide useful information to the user. The following is an example of how this might be handled:

import { ShippingAddressClient, ShippingAddressServiceError } from "@nuskin/payment-client";

const client = new ShippingAddressClient({...});

client.createShippingAddress(address)
.then(...)
.catch(e => {
  if (e instanceof ShippingAddressServiceError) {
    e.messages.forEach(msg => {
      // display error message text to the user
    })
  } else {
    // handle other types of error
  }
})