Announcing the New Square Node.js SDK

We’re excited to announce our new Node.js SDK is now available in General Availability! This new square package is a major update that adds TypeScript support and replaces the deprecated square_connect package. With JavaScript codebases you can now get type-based hints from your IDE or text editor and with TypeScript codebases you can get full type checking for your SDK usage.

There are a few ways to install the Square package.

Install with npm or Yarn

npm install square or yarn install square

After installing and importing a few SDK packages, you’ll be ready to instantiate a client with your Square access token.

import { Client, Environment } from 'square'

const client = new Client({
  environment: Environment.Sandbox,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

With a client instantiated, we’re ready to use the Square API. For example, we can list locations.

// Get an instance of the Square API you want call
const { locationsApi } = client

// Create wrapper async function 
const getLocations = async () => {
  // The try/catch statement needs to be called from within an asynchronous function
  try {
    // Call listLocations method to get all locations in this Square account
    let listLocationsResponse = await locationsApi.listLocations()

    // Get first location from list
    let firstLocation = listLocationsResponse.result.locations[0]

    console.log("Here is your first location: ", firstLocation)
  } catch (error) {
    console.log("There was an error in your request: ", error)
  }
}

// Invokes the async function
getLocations()

Or we can see what that looks like in TypeScript:

import {  Client,  Environment,  Location } from 'square';

const getLocations =  async () : Promise<Location[]> => {
  const { locationsApi } = new Client({
    environment: Environment.Sandbox,
    accessToken: process.env.ACCESS_TOKEN,
    timeout: 3000
  })
  const { result: { locations } } = await locationsApi.listLocations();
  return locations;
}
try {
  (async () => {
    console.log(await getLocations());
  })();
} catch (e) {
  console.error(e);
}

One of the great features in the new SDK is that the response object contains new rich information about both the request and response.

If you were previously using the square-connect Node.js package, you might be wondering how the new Node.js SDK compares. Let’s take a look! For example, let’s create the following customer along with their address (these examples are for demonstrating the differences, for full examples please head over to the GitHub page for the SDK).

First, let’s look at how we used to create a customer with the deprecated Node.js Connect SDK:

var uuidv4 = require('uuid');
var SquareConnect = require('square-connect');
var defaultClient = SquareConnect.ApiClient.instance;

// Configure OAuth2 access token for authorization: oauth2
var oauth2 = defaultClient.authentications['oauth2'];
oauth2.accessToken = 'YOUR ACCESS TOKEN';

var apiInstance = new SquareConnect.CustomersApi();

var body = SquareConnect.CreateCustomerRequest.constructFromObject({
idempotencyKey: idempotencyKey,
givenName: "Amelia",
familyName: "Earhart"
});

apiInstance.createCustomer(body).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

For comparison, let’s create the same customer with the new Square Node.js SDK:

// Create a unique key for this creation operation so you don't accidentally
// create the customer multiple times if you need to retry this operation.
// Here we use the npm package uuid
import { v4 as uuidv4 } from 'uuid'
import { Client, Environment } from 'square'

const { customersApi } = new Client({
  environment: Environment.Sandbox,
  accessToken: process.env.SQUARE_ACCESS_TOKEN,
})

let idempotencyKey = uuidv4()

const createCustomer = async () => {
  // To create a customer, you only need 1 of 5 identity values but you'll be
  // specifying two.
  let requestBody = {
    idempotencyKey: idempotencyKey, // A unique id for the request
    givenName: "Amelia",
    familyName: "Earhart"
  }

  try {
    let { result } = await customersApi.createCustomer(requestBody)
    console.log(result)
  } catch (error) {
    console.log(error)
  }
}
createCustomer()

That’s all there is to it!

As you can see, the new Node.js SDK interface is much simpler, but provides richer data. The new package also ships with a ton of usability and debugging features.

Give the new Node.js SDK a try today by installing it in your project with npm install --save square or yarn add square.

With the new Node.js SDK it’s easier than ever to use Square as a platform to run your business with Node.js. We can’t wait to see what you’ll build! If you have any questions or feedback, feel free to ask us in our forums or drop by our Slack. We’d love to hear from you.