@procore/js-sdk NPM

Procore JS SDK

A node.js JS SDK for the Procore API.

Note: ECMAScript target is ES5.

Requirements

Node.js version 14 or 16+, not 15.
- We emphasize using the latest LTS version
A registered app on the Procore Developer Portal.
A Node.js web server (such as Express) for server authentication.

Installation

yarn add @procore/js-sdk

We recommend installing the package with yarn.

Making Requests

At the core of the package is the client object. Clients are initialized with a client_id and client_secret which can be obtained by signing up for Procore's Developer Program. The redirect_uri used for authorization must be specified on the Manage App page for the App associated with the client_id in use.

The Client object exposes #get, #post, #put, #patch, and #delete methods to you.

import * as sdk from '@procore/js-sdk';

const client = sdk.client(authorizer);

client.get(
  { base, version?, action?, params?, qs? }: EndpointConfig | string,
  {formatter?, companyId?, headers?}: RequestConfig
)

client.post(
  { base, version?, action?, params?, qs? }: EndpointConfig | string,
  payload,
  {formatter?, companyId?, headers?}: RequestConfig
)

client.put(
  { base, version?, action?, params?, qs? }: EndpointConfig | string,
  payload,
  {formatter?, companyId?, headers?}: RequestConfig
)

client.patch(
  { base, version?, action?, params?, qs? }: EndpointConfig | string,
  payload,
  {formatter?, companyId?, headers?}: RequestConfig
)

client.delete(
  { base, version?, action?, params?, qs? }: EndpointConfig | string,
  payload,
  {formatter?, companyId?, headers?}: RequestConfig
)

Request Config (RequestConfig)

RequestConfig supports 3 parameters:

formatter: Custom formatter function for response body.
companyId: Company Id used to set Procore-Company-Id header. Takes precedence over defaultCompanyId passed in ClientOptions.
headers: Custom headers passed as key/value pairs.

import * as sdk from '@procore/js-sdk';

const client = client(authorizer);

const customFormatter = async (response) => {
  if (response.body) {
    return await response.json();
  }
};

client.get(
  { base: "/projects" },
  {
    formatter: customFormatter,
    companyId: 1,
    headers: { "Acme-Customer-Header": "code" }
  }
);

Example

JS-SDK-Sample-App

Use js-sdk-sample-app as a getting started example application.

All paths are relative to https://{apiHostname}/{vapid|rest/{version}}/, the @procore/js-sdk will handle expanding them.

An API version may be specified in the version attribute to the client[method] function call, or the defaultVersion is used. The default version is v1.0 unless otherwise configured when instantiating the client (client(Authorizer, RequestInit, { defaultVersion: 'vapid' })).

A company id may be specified in the companyId attribute to the client[method] function call, or the defaultCompanyId value will be used when appending the Procore-Company-Id header to the request. (client(Authorizer, RequestInit, { defaultCompanyId: 10 })).

Example	Requested URL
`client.get({ base: '/example/{id}', params: { id: 42 } })`	`https://api.procore.com/rest/v1.0/example/42`
`client.get({ base: '/example/{id}', params: { id: 42 }, version: 'v1.1' })`	`https://api.procore.com/rest/v1.1/example/42`
`client.get({ base: '/example/{id}', params: { id: 42 }, version: 'vapid' })`	`https://api.procore.com/vapid/example/42`
`client.get({ base: '/example/{id}', params: { id: 42 }, version: 'unversioned' })`	`https://api.procore.com/example/42`

Responses

A single API response contains the response body (JSON parsed), original request, and complete response: { body, request, response }. isomorphic-fetch is the underlying http library, so both the request and response follow its specification. See fetch for more details.

import * as sdk from '@procore/js-sdk';

const client = sdk.client(authorizer);

client.get({
    base: '/projects',
    qs: { company_id: 1 }
  },
  {
    companyId: 1
  })
  .then({ body, request, response } => {
    console.log(body[0].name); // ACME Construction LLC.
    console.log(response.headers.get('Total')) // 865 (Total records for the resource)
  })
  .catch(error => {
    //Handle error
    console.log(error);
  });

import * as sdk from '@procore/js-sdk';

const client = sdk.client(authorizer);

async function getProjects() {
  const { body, request, response } = await client
    .get({
      base: '/projects',
      qs: { company_id: 1 }
    },
    {
      companyId: 1
    })
    .catch(error => {
    // Handle error
    console.log(error);
  });
  console.log(body[0].name); // ACME Construction LLC.
  console.log(response.headers.get('Total')) // 865 (Total records for the resource)
}
getProjects();

Formatting the response

By default, the SDK tries to format the body as JSON, you can control the formatting of the body by passing the formatter option as follows:

import * as sdk from '@procore/js-sdk';

const client = sdk.client(authorizer);
// Create your own formatter
function formatter(response) {
  // Your custom formatter code.
  // Response supports .text() and .json()
}

// Pass the formatter configuration
client.get({base: '/me'}, { formatter })

Multiple Procore Zones (MPZ)

All requests to the Procore API must include the Procore-Company-Id header to support Multiple Procore Zones (MPZ). See Multiple Procore Zones (MPZ) for more details. A Procore-Company-Id header will automatically be added to the request if the defaultCompanyId parameter is passed in the ClientOptions object or companyId parameter is passed in the RequestConfig object.

import * as sdk from '@procore/js-sdk';

// Pass the defaultCompanyId configuration in the ClientOptions
const client = sdk.client(authorizer, undefined, { defaultCompanyId: 10 });

client.get(
  { base: "/projects" }
);

import * as sdk from '@procore/js-sdk';

const client = sdk.client(authorizer);

// Pass the companyId configuration in the RequestConfig
client.get(
  { base: "/projects" },
  { companyId: procoreCompanyId }
);

Client Options (ClientOptions)

ClientOptions supports 3 parameters:

apiHostname: This is the hostname used for api requests. Default: https://api.procore.com
defaultVersion: Rest api version. Must in the format v\d.\d e.g. v1.0. Default: v1.0
defaultCompanyId: If companyId is not provided in RequestConfig this value will be used. Default: undefined

import * as sdk from '@procore/js-sdk';

const client = client(
  authorizer,
  undefined,
  {
    apiHostname: "https://api.procore.com",
    defaultVersion: "v1.1",
    defaultCompanyId: 10,
  }
);

client.get({ base: "/projects" });

Tests

yarn && yarn test

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/procore/js-sdk. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.