Assembly.js Node SDK

The Assembly.js Node SDK provides easy to call functions written in TypeScript for interacting with the Assembly REST API. Right now this is a TypeScript only package. In the future we will have a Vanilla JS package with a corresponding @types package to go along with it.

This SDK is intended to be used on the server-side only. We do not currently offer a package for client-side development.

Installation

npm install @assembly-js/node-sdk
# or
yarn add @assembly-js/node-sdk

Setup

For Custom Apps

import { assemblyApi } from '@assembly-js/node-sdk';

const assembly = assemblyApi({ apiKey: YOUR_API_KEY_HERE });

For Marketplace Apps

If you're building a Marketplace app you should go through one additional step of fetching a query parameter that gets passed into the App URL when rendered in the dashboard: ?token=TOKEN_IS_HERE

Grab that token from the URL and pass it in to the assemblyApi configuration object.

import { assemblyApi } from '@assembly-js/node-sdk';

const assembly = assemblyApi({
  apiKey: YOUR_API_KEY_HERE,
  token: searchParams.token,
});

Migration from copilot-node-sdk

If you're migrating from copilot-node-sdk, the following changes are needed:

Package Installation

# Remove old package
npm uninstall copilot-node-sdk

# Install new package
npm install @assembly-js/node-sdk

Code Changes

// Before
import { copilotApi } from 'copilot-node-sdk';
const copilot = copilotApi({ apiKey: YOUR_API_KEY });

// After
import { assemblyApi } from '@assembly-js/node-sdk';
const assembly = assemblyApi({ apiKey: YOUR_API_KEY });

Environment Variables

| Old Variable | New Variable | Notes | | --------------- | ---------------- | ------------------------------- | | COPILOT_ENV | ASSEMBLY_ENV | Both work, new takes precedence | | COPILOT_DEBUG | ASSEMBLY_DEBUG | Both work, new takes precedence |

Backwards Compatibility

For a gradual migration, the old names are still available but deprecated:

// These still work but are deprecated
import { copilotApi, type CopilotAPI } from '@assembly-js/node-sdk';

How to develop this package internally:

1. yarn
2. yarn generate-api
3. yarn test to produce a successful response
4. yarn test:fail to product a response that fails because of a missing env variable.

For additional logging you can set the environment variable ASSEMBLY_DEBUG to any truthy value. This is useful if you'd like to see SDK logs while developing in an application's codebase.

Field Deprecations

Deprecated Fields

The following fields are deprecated and will be removed in a future version of the SDK:

companyId (deprecated in v3.15.0)

• Replacement: Use companyIds array instead
• Reason: To support multi-company functionality
• Removal: Will be removed in v4.0.0
• Affected endpoints: Client operations, App connections, Tasks

recipientId (deprecated in v3.15.0)

• Replacement: Use clientId and companyId instead
• Reason: More explicit recipient targeting
• Removal: Will be removed in v4.0.0
• Affected endpoints: Contracts, Invoices, Notifications, Subscriptions

Migration Guide

Before (deprecated):

// Creating a client with single company
await assembly.createClient({
  companyId: 'company-uuid-here',
  // ... other fields
});

// Creating an invoice with recipient ID
await assembly.createInvoice({
  recipientId: 'recipient-uuid-here',
  // ... other fields
});

After (recommended):

// Creating a client with multiple companies support
await assembly.createClient({
  companyIds: ['company-uuid-here'], // Now an array
  // ... other fields
});

// Creating an invoice with explicit client and company targeting
await assembly.createInvoice({
  clientId: 'client-uuid-here',
  companyId: 'company-uuid-here',
  // ... other fields
});

Developer Experience

When using deprecated fields, you'll see:

• IDE warnings: TypeScript will show deprecation warnings in your editor
• JSDoc annotations: Hover over deprecated fields to see migration guidance
• Continued functionality: Deprecated fields continue to work until removal