# 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

```bash
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

```typescript
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.

```typescript
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

```bash
# Remove old package
npm uninstall copilot-node-sdk

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

### Code Changes

```typescript
// 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:

```typescript
// 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):**

```typescript
// 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):**

```typescript
// 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