@assembly-js/node-sdk

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.

For AI coding agents

This section surfaces key resources for LLM-based tools and AI coding agents working with this SDK.

• Full API reference: https://docs.assembly.com/reference
• OpenAPI spec: https://docs.assembly.com/openapi/core-resources.json

Installation

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

Setup

Note: Since v4, assemblyApi() is async and must be called with await.

For Custom Apps

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

const assembly = await 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 = await 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 (note: assemblyApi is async since v4)
import { assemblyApi } from '@assembly-js/node-sdk';
const assembly = await 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
• Affected endpoints: Client operations, App connections, Tasks

recipientId (deprecated in v3.15.0)

• Replacement: Use clientId and companyId instead
• Reason: More explicit recipient targeting
• 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