README

ADR Service Client

JavaScript client for the Nu Skin ADR Service web API

ADR Service Client

Installing

Using npm:

$ npm install @nuskin/adr-client

Using Yarn:

$ yarn add @nuskin/adr-client

Initializing the Client

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

baseURL - The Nu Skin Payment Service web API base URL. Currently, this is the base URL of Nu Skin's legacy web services.
clientID - The Nu Skin web API client ID.
clientSecret - The Nu Skin web API client secret.
country - Country code of the market that requests will be made for.
language - Language code of the market that requests will be made for.
userID - ID of the user that requests will be made for.
userToken - Auth token (eid) of the user that requests will be made for.

Example:

import { ADRClient } from "@nuskin/adr-client";

const client = new ADRClient({
  baseURL: "https://www.nuskin.com",
  clientID: "0123...aeae",
  clientSecret: "8888...aa00",
  country: "US",
  language: "en",
  userID: "US1234567",
  userToken: "aBCd....3Au0"
});

Using the Client

Retrieving User's ADR Status Information

Call .getUserStatus() to retrieve the user's ADR status information in the current market.

Retrieving User's Subscription List

Call .getSubscriptions() to retrieve a list of the user's subscriptions in the current market.

Retrieving a Subscription's Full Details

Call .getSubscription(id) to retrieve the full details of a single subscription.

id is the subscription's order ID.

Creating a New Subscription

Call .createSubscription(subscription, [options]) to create a new subscription.

subscription is the subscription to create.

Additional options for the request can be given in the options argument:

{
  // If true, subscription order creation will be simulated but not committed.
  simulate: false,

  // If true, the first shipment of the subscription order will be processed 
  // immediately rather than on the subscription's requested processing date.
  shipImmediate: false
}

The method returns a promise that resolves to the newly created subscription's details.

Updating a Subscription

Call .updateSubscription(subscription) to perform updates of an existing subscription order.

The method returns a promise that resolves to the updated subscription's details.

Deleting a Subscription

Call .deleteSubscription(id) to delete an existing subscription order.

id is the subscription's order ID.

Handling Errors

Promises returned by the ADR Service Client may reject with either a plain Error instance or with a ADRServiceError instance.

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

class ADRServiceError 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 ADRServiceError instance are intended to provide useful information to the user. The following is an example of how this might be handled:

import { ADRClient, ADRServiceError } from "@nuskin/adr-client";

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

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

Data Types

ADR Request

Object representing a request to update a subscription (ADR) order record.

interface ADRRequest {
  // ADR order information
  SalesOrder: SalesOrder;

  // Next requested processing date, as Unix timestamp in milliseconds
  DeliveryDate?: number;

  // Requested order frequency
  OrderFrequency?: number;

  // Numeric code of requested contract length
  ContractLength?: number;

  // Version timestamp of ADR record
  timestamp: number;

  // List of scan cards to add, update, or remove on this ADR
  Scan?: ScanCard[];
}

ADR Detail

Object representing the details of a subscription (ADR) order record.

interface ADRDetail {
  // ADR order information
  SalesOrderDetail: SalesOrderDetail;

  // Name of party the ADR is shipped to
  ShipToName?: string;

  // Flag indicating whether ADR is currently editable
  Editable?: boolean;

  // ADR creation date, as Unix timestamp in milliseconds
  CreateDate?: number;

  // ADR end date, as Unix timestamp in milliseconds
  EndDate?: number;

  // Next scheduled processing date, as Unix timestamp in milliseconds
  NextDeliveryDate: number;

  // Previous processing date, as Unix timestamp in milliseconds
  LastPlacedDate: number;

  // Numeric code of ADR contract length
  ContractLength?: number;

  // ADR order frequency
  OrderFrequency: number;

  //
  LastOrderStatus?: string;

  // Flag indicating whether ADR has been overridden this month
  Overridden?: boolean;

  // Flag indicating whether ADR is held for the current month
  Held?: boolean;

  // List of scan cards associated with this ADR
  Scan?: ScanCard[];

  // List of custom data fields applied to this ADR record
  Custom?: CustomField[];

  // Number of months this ADR has been active
  MonthCount: number;

  // Version timestamp of ADR record
  TimeStamp: string;
}

User ADR Status

Object representing the user's market-specific ADR status information.

interface UserADRStatus {
  // List of user's market-specific statuses
  ADRMarketStatus: {
    
    // Country code
    CountryCode: string;
    
    // Status code
    Status: string;
  }[];

  // List of user's market-specific ADR-points breakdowns
  ADRPoints: {
    
    // Country group code
    CountryGroup: string;
    
    // Country code
    CountryCode: string;
    
    // ADR points type
    Type: string;
    
    // Total ADR points
    TotalPoints: number;

    // ADR points already used
    UsedPoints: number;

    // ADR points currently available
    AvailablePoints: number;

    // ADR points pending availability
    PendingPoints: number;

    // ADR points expiring soon
    ExpiringPoints: number;

    //
    Currency: string;
  }[];

  // User's total ADR points across all markets
  TotalPoints: number;
}

Usage no npm install needed!