NetSuite SuiteTalk M2M REST Client

A TypeScript/Node.js client for the NetSuite SuiteTalk REST API using OAuth 2.0 Machine-to-Machine (M2M) authentication with certificate-based JWT.

Features

• 🔐 OAuth 2.0 M2M authentication with certificate-based JWT (PS256)
• 🔄 Automatic token caching and refresh with manual controls
• 📦 Full TypeScript support with type definitions and generics
• 🛠️ Comprehensive CRUD operations for NetSuite records
• 📊 SuiteQL query execution
• ⚡ Built-in error handling with custom error class
• ⏱️ Configurable request timeouts
• ✅ Input validation for all parameters
• 🎯 Simple, intuitive API

Installation

npm install @brokenrubik/ns-suitetalk-m2m-rest

Prerequisites

Before using this client, you need to set up OAuth 2.0 M2M authentication in NetSuite:

1. Generate a certificate and private key
2. Create an Integration Record in NetSuite
3. Note your Account ID, Integration Client ID, and Certificate ID

Official Documentation

For detailed information about NetSuite SuiteTalk REST API and OAuth 2.0 setup, refer to these official resources:

• SuiteTalk REST Web Services Overview
• OAuth 2.0 for SuiteTalk REST Web Services
• Setting Up OAuth 2.0
• REST Web Services Record API

Usage

Basic Setup

import { NetSuiteService } from "@brokenrubik/ns-suitetalk-m2m-rest";

const netsuiteClient = new NetSuiteService({
  accountId: "YOUR_ACCOUNT_ID",
  integrationClientId: "YOUR_CLIENT_ID",
  certificateId: "YOUR_CERTIFICATE_ID",
  privateKey: `-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_HERE
-----END PRIVATE KEY-----`,
  // Optional configuration
  requestTimeout: 30000, // 30 seconds (default)
  tokenExpiryMargin: 60000, // 1 minute safety margin (default)
});

API Methods

SuiteQL Queries

Execute SuiteQL queries to retrieve data:

const result = await netsuiteClient.executeSuiteQLQuery(
  "SELECT id, companyname FROM customer WHERE email = ?",
);

List Records

Retrieve a list of records with optional filtering and pagination:

const customers = await netsuiteClient.listRecords("customer", {
  limit: 10,
  offset: 0,
  q: 'companyname CONTAINS "Acme"',
});

Get Record

Retrieve a single record by ID:

const customer = await netsuiteClient.getRecord("customer", "12345");

Create Record

Create a new record:

const newCustomer = await netsuiteClient.createRecord("customer", {
  companyname: "Acme Corporation",
  email: "[email protected]",
});

Update Record

Update an existing record:

const updated = await netsuiteClient.updateRecord("customer", "12345", {
  email: "[email protected]",
});

Delete Record

Delete a record:

await netsuiteClient.deleteRecord("customer", "12345");

Custom SuiteTalk Requests

Make custom requests to any SuiteTalk endpoint:

const response = await netsuiteClient.suitetalkRequest(
  "/services/rest/record/v1/customrecord_myrecord",
  "GET",
  null,
  { "Custom-Header": "value" },
);

Configuration

NetSuiteServiceOptions

| Property | Type | Required | Default | Description | | --------------------- | ------ | -------- | ------- | -------------------------------------------------- | | accountId | string | Yes | - | Your NetSuite account ID (e.g., "1234567") | | integrationClientId | string | Yes | - | Client ID from your Integration Record | | certificateId | string | Yes | - | Certificate ID from your Integration Record | | privateKey | string | Yes | - | Private key in PEM format | | requestTimeout | number | No | 30000 | Request timeout in milliseconds | | tokenExpiryMargin | number | No | 60000 | Token expiry safety margin in milliseconds |

Error Handling

The client uses a custom NetSuiteError class with enhanced error information:

import { NetSuiteError } from "@brokenrubik/ns-suitetalk-m2m-rest";

try {
  const record = await netsuiteClient.getRecord("customer", "12345");
} catch (error) {
  if (error instanceof NetSuiteError) {
    console.error("Error:", error.message);
    console.error("Status:", error.status);
    console.error("Details:", error.body);
  } else {
    console.error("Unexpected error:", error);
  }
}

Token Caching

Access tokens are automatically cached and refreshed when expired, with a configurable safety margin (default: 1 minute).

Token Cache Controls

// Clear the cached token (forces new token on next request)
netsuiteClient.clearTokenCache();

// Check if a valid token is cached
const hasToken = netsuiteClient.hasValidToken();

// Get token expiration timestamp
const expiration = netsuiteClient.getTokenExpiration();
if (expiration) {
  console.log("Token expires at:", new Date(expiration));
}

TypeScript Support

Full TypeScript definitions are included with support for generics:

import {
  NetSuiteService,
  NetSuiteServiceOptions,
  NetSuiteCredentials,
  NetSuiteHttpMethod,
  NetSuiteError,
  ListRecordsOptions,
  ListRecordsResponse,
  SuiteQLResponse,
} from "@brokenrubik/ns-suitetalk-m2m-rest";

// Use generics for type-safe responses
interface Customer {
  id: string;
  companyname: string;
  email: string;
}

const customer = await netsuiteClient.getRecord<Customer>("customer", "123");
// customer is typed as Customer

const customers = await netsuiteClient.listRecords<Customer>("customer");
// customers is typed as ListRecordsResponse<Customer>