Realforce API - TypeScript SDK

TypeScript client SDK for the Realforce API.

Version: 0.2.3

Installation

npm install @realforce-software/api-client

Authentication

The SDK authenticates with a Bearer token in the Authorization header. There are two kinds of token, depending on whether a human or a machine is calling.

Machine-to-machine (M2M) apps — recommended for integrations

If you have a Realforce app (a clientId plus an RSA private key), the SDK does the whole OAuth client_credentials + private_key_jwt flow for you — signing the assertion, calling the token endpoint, caching the short-lived rfm_ token, and refreshing it before it expires:

import { createAuthenticatedClient } from '@realforce-software/api-client/authentication';
import { readFileSync } from 'node:fs';

const client = createAuthenticatedClient('https://api.realforce.com', {
  clientId: 'your-client-id',
  tokenUrl: 'https://api.realforce.com/v1/oauth/token',
  privateKeyPem: readFileSync('app-key.pem', 'utf8'), // the PEM shown once when the app/key was created
  // optional scope-down:
  // scopes: ['agents:read'],
  // workspaceIds: ['00000000-0000-0000-0000-000000000000'],
});

const agents = await client.queryAgents(workspaceId, {});

Server-side only. This flow uses Node's built-in crypto and your RSA private key — never run it in a browser. A failed token request throws RealforceAuthenticationError (inspect .error / .errorDescription, e.g. invalid_client when the assertion or key is wrong).

Personal Access Token (PAT) — for scripts acting as a user

Generate a PAT in the Realforce dashboard and send it as a Bearer token directly:

import axios from 'axios';
import { RealforceApiClient } from '@realforce-software/api-client';

const http = axios.create({
  headers: { Authorization: 'Bearer rfp_xxxxxxxxxxxxxxxx' }
});

const client = new RealforceApiClient('https://api.realforce.com', http);

Workspace ID

Most endpoints are scoped to a workspace. The generated client surfaces this as an x_Workspace_ID parameter (string GUID) on each method — pass the workspace your token has access to on every call:

const workspaceId = '00000000-0000-0000-0000-000000000000';
const agent = await client.getAgent(agentId, workspaceId);

Quick Start

import axios from 'axios';
import { RealforceApiClient } from '@realforce-software/api-client';

const http = axios.create({
  headers: { Authorization: 'Bearer rfp_xxxxxxxxxxxxxxxx' }
});

const client = new RealforceApiClient('https://api.realforce.com', http);

const workspaceId = '...';
const agents = await client.queryAgents(workspaceId, {});

Error Handling

The SDK throws ApiException for non-2xx responses, surfacing the status code and parsed body:

try {
  const result = await client.getAgent(agentId, workspaceId);
} catch (error: any) {
  if (error.status) {
    console.error(`HTTP ${error.status}:`, error.response);
  } else if (error.request) {
    console.error('No response received:', error.request);
  } else {
    console.error('Request error:', error.message);
  }
}

Custom Axios Instance

The constructor's second argument accepts any pre-configured AxiosInstance, so you can attach interceptors, set timeouts, retry, etc.:

import axios from 'axios';
import { RealforceApiClient } from '@realforce-software/api-client';

const http = axios.create({
  timeout: 30000,
  headers: { Authorization: `Bearer ${token}` }
});

const client = new RealforceApiClient('https://api.realforce.com', http);

Requirements

• Node.js 16+ or a modern browser
• axios ^1.6.0

Support

• Please contact the Realforce support team.