# n8n-node-netsuite

A comprehensive n8n node for NetSuite integration, providing full access to NetSuite's SuiteTalk REST API with OAuth 2.0 M2M authentication.

**npm package**: `@brokenrubik/n8n-nodes-ns`

## Features

### Secure Authentication

- OAuth 2.0 Machine-to-Machine (M2M) authentication
- JWT token-based authentication with PS256 algorithm
- Automatic token caching and refresh (with 1-minute safety margin)
- Certificate-based security

### Operations (9 total)

- **List Records**: Retrieve multiple records with pagination support
- **Get Record**: Fetch individual records by ID (with optional sub-resource expansion)
- **Get Metadata**: Fetch record type metadata in JSON, OpenAPI 3.0, or JSON Schema formats
- **Insert Record**: Create new records (supports `replace` for sublist handling)
- **Update Record**: Modify existing records (supports `replace` and `replaceSelectedFields`)
- **Remove Record**: Delete records
- **Execute SuiteQL**: Run SQL-like queries with automatic offset-based pagination
- **Call RESTlet**: Call custom RESTlet scripts deployed in NetSuite
- **Raw API Request**: Direct access to any NetSuite REST endpoint

### Reliability

- **Automatic Retry**: Exponential backoff for rate limit (429) and temporary errors (502, 503, 504)
- **Configurable Retries**: Default 5 retries, configurable 0-10 via node options
- **Backoff Strategy**: Starts at 1s, doubles each attempt, max 60s, with ±10% jitter
- **Network Error Recovery**: Retries on ECONNRESET, ETIMEDOUT, and connection errors
- **500 errors are NOT retried** (per NetSuite docs, these require contacting support)

### Developer-Friendly

- **Modular Architecture**: Each operation is a separate module
- **Structured Logging**: Workflow-aware logging with `NetSuiteLogger` (workflow ID, node ID, execution ID)
- **Comprehensive Error Handling**: NetSuite-specific error parsing with `o:errorDetails` extraction
- **TypeScript Support**: Full type safety and IntelliSense
- **Custom Record Support**: Use any custom record type via script ID

## Prerequisites

### System Requirements

- Node.js >= 20.15 and npm
- n8n installed globally: `npm install n8n -g`

### NetSuite Requirements

- NetSuite account with REST API access
- OAuth 2.0 Application configured in NetSuite
- Certificate and private key for M2M authentication
- Appropriate permissions for the operations you want to perform

## Installation

### From npm

```bash
npm install @brokenrubik/n8n-nodes-ns
```

### For Development

```bash
# Clone the repository
git clone https://github.com/BrokenRubik/n8n-netsuite-node
cd n8n-netsuite-node

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link

# Restart n8n to load the new node: https://docs.n8n.io/integrations/creating-nodes/test/run-node-locally/
```

## Setup Instructions

### Step 1: Create NetSuite Integration Record

1. **Navigate to Integration Setup**:
   - Log into your NetSuite account
   - Go to **Setup > Integration > Manage Integrations > New**

2. **Configure Integration**:
   - Enter a **Name** for your integration (e.g., "n8n NetSuite Integration")
   - Set **State** to "Enabled"
   - Under **Client Credentials (M2M)**, check **"Client Credentials (Machine To Machine) Grant"**
   - Leave all other checkboxes unchecked
   - Click **Save**

3. **Copy Integration Client ID**:
   - **Important**: After saving, immediately copy the **Integration Client ID**
   - This ID will disappear if you close the tab or navigate away
   - Store it securely as you'll need it for the n8n credentials

### Step 2: Generate Certificate and Private Key

1. **Create Certificate Pair**:
   - Open a terminal/command prompt
   - Generate a private key and certificate using OpenSSL:

   ```bash
   openssl req -x509 -newkey rsa:3072 -keyout n8n_key.pem -out n8n_cert.pem -days 365 -nodes
   ```

2. **Alternative: Using NetSuite's Guide**:
   - Follow NetSuite's official certificate generation guide: [Creating Certificates for OAuth 2.0](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_162686838198.html)

### Step 3: Upload Certificate to NetSuite

1. **Navigate to Certificate Setup**:
   - Go to **Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup**

2. **Upload Certificate**:
   - Click **"New"** to create a new certificate entry
   - Enter a **Name** for the certificate (e.g., "n8n Integration Certificate")
   - Upload the **certificate file** (`n8n_cert.pem`) - not the private key
   - Click **Save**

3. **Copy Certificate ID**:
   - After saving, copy the generated **Certificate ID**
   - You'll need this for the n8n credentials

### Step 4: Set Up n8n Credentials

1. **Open n8n**:
   - Navigate to **Credentials** in n8n
   - Click **"Add Credential"**
   - Select **"NetSuite API"**

2. **Enter Credential Information**:
   - **Account ID**: Your NetSuite account ID (e.g., "1234567" or "1234567_SB1" for sandbox)
   - **Integration Client ID**: The ID copied from Step 1
   - **Certificate ID (M2M)**: The ID copied from Step 3
   - **PEM Content**: Copy and paste the entire content of your private key file (`n8n_key.pem`)

3. **PEM Content Format**:

   ```
   -----BEGIN PRIVATE KEY-----
   MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC...
   ... (your private key content) ...
   -----END PRIVATE KEY-----
   ```

### Step 5: Test the Connection

1. **Create a Test Workflow**:
   - Create a new workflow in n8n
   - Add a **NetSuite SuiteTalk** node
   - Configure it to list a simple record type (e.g., Customer)
   - Execute the workflow to verify the connection

## Usage Examples

### List Sales Orders

| Parameter | Value |
|-----------|-------|
| Operation | List Records |
| Record Type | Sales Order |
| Query | `status IS SalesOrd:F` |
| Return All | false |
| Limit | 100 |

The `Query` field maps to NetSuite's `q` filter parameter. NetSuite uses the syntax `field OPERATOR value` (e.g., `status IS SalesOrd:F`, `email IS "john@example.com"`).

### Get a Record with Sub-Resources

| Parameter | Value |
|-----------|-------|
| Operation | Get Record |
| Record Type | Sales Order |
| ID | `12345` |
| Expand Sub-Resources | true |
| Restrict Returned Fields | `item,entity` |

The `ID` field accepts internal IDs. Prefix with `eid:` to use external IDs (e.g., `eid:MY_EXT_ID`).

### Create Customer Record

| Parameter | Value |
|-----------|-------|
| Operation | Insert Record |
| Record Type | Customer |

The input data from the previous node is used as the request body:

```json
{
  "companyName": "Acme Corp",
  "email": "contact@acme.com",
  "phone": "+1-555-0123"
}
```

Returns `{ success: true, id: "<new-record-id>", location: "<api-url>", recordType: "customer" }`.

### Execute SuiteQL Query

| Parameter | Value |
|-----------|-------|
| Operation | Execute SuiteQL |
| Query | `SELECT id, companyname, email FROM customer WHERE datecreated >= '2024-01-01'` |
| Return All | true |

SuiteQL uses SQL-like syntax with NetSuite's database column names (lowercase). When `Return All` is enabled, the node automatically paginates through all results using offset-based pagination (up to 1000 rows per page).

### Get Metadata Catalog

| Parameter | Value |
|-----------|-------|
| Operation | Get Metadata |
| Metadata Format | JSON (Record Type List) |
| Record Types | `customer,salesOrder,invoice` |

Available formats:
- **JSON**: Lists available record types
- **OpenAPI 3.0 (Swagger)**: Full API specification
- **JSON Schema**: Record structure descriptions

Leave `Record Types` empty to return all (can be slow for accounts with many customizations).

### Raw API Request

| Parameter | Value |
|-----------|-------|
| Operation | Raw Request |
| HTTP Method | GET |
| Path | `services/rest/record/v1/customer/123` |
| Full Response | true |

The `Path` is appended to `https://<account>.suitetalk.api.netsuite.com/`. You can also paste a full URL and the node will extract the path automatically. For methods other than GET/HEAD/OPTIONS, input data from the previous node is sent as the request body.

### Call a RESTlet

| Parameter | Value |
|-----------|-------|
| Operation | Call RESTlet |
| HTTP Method | POST |
| Script ID | `customscript_my_restlet` |
| Deploy ID | `1` |

The input data from the previous node is sent as the request body for POST/PUT/PATCH/DELETE methods. You can also add query parameters via the "Query Parameters" collection. For GET requests, no body is sent.

### Using Custom Records

| Parameter | Value |
|-----------|-------|
| Operation | List Records |
| Record Type | Custom Record |
| Custom Record Script ID | `customrecord_my_record` |
| Return All | true |

Select **Custom Record** as the Record Type, then enter the script ID (usually starts with `customrecord`).

## Architecture

### Modular Design

- **Main Node** (`NetSuite.node.ts`): Orchestrates 9 operations via switch statement (~155 lines)
- **Service Layer** (`NetSuite.service.ts`): OAuth 2.0 M2M auth, token caching, retry-wrapped HTTP requests
- **Operation Modules** (`operations/`): One file per operation, consistent `INetSuiteOperationOptions` interface
- **Type System** (`types/`): Auth, request, response, operation, and logger types
- **Utilities** (`utils/`): Response handler, helpers, retry handler, structured logger

### Error Handling

- Follows NetSuite's official error format (`o:errorDetails` array)
- Extracts error codes, paths, and details from responses
- Provides specific guidance per HTTP status code
- Supports graceful degradation with "Continue on Fail"

### SuiteQL Pagination

SuiteQL uses **offset-based pagination** (not response link-based). Each page requests up to 1000 rows. The loop advances the offset by the number of items returned and stops when fewer items than requested come back. This avoids infinite loops caused by unreliable `hasMore`/`nextUrl` fields in SuiteQL POST responses.

## Development

### Project Structure

```
nodes/NetSuite/
  types/              # TypeScript type definitions
  utils/              # Response handler, logger, retry handler, helpers
  operations/         # 9 operation modules (one per operation)
  NetSuite.node.ts    # Main node class (orchestrator)
  NetSuite.service.ts # Service layer (auth + API communication)
  NetSuite.node.options.ts # Node UI configuration
credentials/
  NetSuiteApi.credentials.ts # n8n credential definition
```

### Common Commands

| Command | Description |
|---------|-------------|
| `npm run build` | Build the project (compiles TypeScript and copies icons) |
| `npm run dev` | Watch mode for development |
| `npm run lint` | Run ESLint |
| `npm run lintfix` | Auto-fix lint errors |
| `npm run format` | Format code with Prettier |

### Adding New Operations

1. Create operation file in `operations/` directory
2. Export function from `operations/index.ts`
3. Add case to switch statement in `NetSuite.node.ts`
4. Add UI configuration to `NetSuite.node.options.ts`

## Troubleshooting

### Debug Logging

- **Legacy debug output**: `NODE_DEBUG=n8n-nodes-netsuite` (uses Node.js `util.debuglog`)
- **Structured logger**: `NetSuiteLogger` outputs structured messages via `console.*` at all levels (debug, info, warn, audit, error) with workflow context automatically included

### Common Issues

- **401 Unauthorized**: Check that your Integration Client ID, Certificate ID, and PEM content are correct. Ensure the certificate hasn't expired.
- **403 Forbidden**: Verify the role assigned to the integration has permissions for the record type and operation.
- **429 Too Many Requests**: The node retries automatically with exponential backoff. If persistent, reduce concurrency or increase retry count.
- **500 Internal Server Error**: Not retried. Check NetSuite's audit trail or contact NetSuite support.

## License

MIT