Getting Started

The @nodestash/sdk is a type-safe TypeScript client for the nodestash API. Zero runtime dependencies, built-in retry logic, and auto-pagination.

Installation

npm install @nodestash/sdk

pnpm add @nodestash/sdk

yarn add @nodestash/sdk

Requirements:

Node.js >= 18.0.0
TypeScript >= 5.0 (recommended)

Initialize the Client

import { NodeStash } from '@nodestash/sdk'

const client = new NodeStash({
  apiKey: process.env.NODESTASH_API_KEY!,
})

Configuration Options

Option	Type	Default	Description
`apiKey`	`string`	—	Required. Your API key (`nds_live_...` or `nds_test_...`)
`baseUrl`	`string`	`https://api.nodestash.io/v1`	API base URL
`timeout`	`number`	`30000`	Request timeout in milliseconds
`maxRetries`	`number`	`3`	Max retry attempts for failed requests

const client = new NodeStash({
  apiKey: 'nds_live_...',
  baseUrl: 'https://api.nodestash.io/v1', // default
  timeout: 60_000,   // 60 seconds
  maxRetries: 5,     // more retries for bulk operations
})

Make Your First Request

// Create a contact
const contact = await client.contacts.create({
  email: 'jane@acme.com',
  first_name: 'Jane',
  last_name: 'Doe',
})

console.log(contact.id)    // ct_5hJ3kM9pQrVwXyZaB2cD4
console.log(contact.email) // jane@acme.com

Available Resources

The client exposes these resources:

client.contacts             // Contacts CRUD + list
client.companies            // Companies CRUD + list
client.deals                // Deals CRUD + list
client.pipelines            // Pipelines CRUD + list
client.pipelines.stages     // Pipeline Stages (nested)
client.activities           // Activities CRUD + list
client.customFields.definitions  // Custom Field Definitions
client.customFields.values       // Custom Field Values
client.apiKeys              // API Key management

Each resource follows the same pattern:

// Create
const item = await client.contacts.create({ ... })

// Get by ID
const item = await client.contacts.get('ct_abc123')

// List with filters
const { data, pagination } = await client.contacts.list({ limit: 25 })

// Update
const updated = await client.contacts.update('ct_abc123', { ... })

// Delete
await client.contacts.delete('ct_abc123')

// Auto-paginate
for await (const item of client.contacts.listAll()) {
  // ...
}

Request Tracking

Every response sets a request ID you can use for debugging:

const contact = await client.contacts.get('ct_abc123')
console.log(client.lastRequestId) // "req_abc123def456ghi789jkl012"

Include this ID when contacting support.

Next Steps

Resources

Detailed reference for every resource and method.

Error Handling

Handle errors with typed error classes.

Pagination

Navigate results with cursors and async iterators.

API Reference

Full endpoint documentation.