ScalePad SDK for Node.js

A TypeScript SDK for the ScalePad API with strong typing, Zod v4 validation, pagination helpers, filtering/sorting support, and rate-limit aware retries.

Features

• 🔒 Type-safe: Full TypeScript support with strong typing
• ✅ Validated: Zod v4 schema validation for API responses
• 🔄 Pagination: Built-in cursor-based pagination with async generators
• 🔍 Filtering & Sorting: Intuitive API for filtering and sorting resources
• ⚡ Rate Limiting: Automatic retry with exponential backoff and Retry-After support
• 📝 Logging: Configurable logging with secret redaction
• 🧪 Well-tested: Comprehensive test coverage
• 📦 Dual Package: ESM and CommonJS support

Installation

npm install @scalepad/sdk

Quick Start

import{ScalePadClient}from'@scalepad/sdk';constclient=newScalePadClient({apiKey: process.env.SCALEPAD_API_KEY!,logLevel: 'info',});// List clientsconstresult=awaitclient.core.v1.clients.list({pageSize: 100,});console.log(`Found ${result.total_count} clients`);

Authentication

The SDK requires a ScalePad API key. You can generate one in your ScalePad account:

1. Sign into your ScalePad account
2. Navigate to your personal API keys
3. Select New API key
4. Copy the generated API key

For more details, see the Getting Started Guide.

Usage

Initialization

import{ScalePadClient}from'@scalepad/sdk';constclient=newScalePadClient({apiKey: 'your-api-key',// Optional configurationbaseUrl: 'https://api.scalepad.com',// defaulttimeoutMs: 60000,// default: 60 secondslogLevel: 'info',// 'debug' | 'info' | 'warn' | 'error' | 'none'// Retry configurationretry: {maxRetries: 3,// defaultretryOn429: true,// defaultretryOn5xx: true,// default},});

Listing Resources

// List clientsconstclients=awaitclient.core.v1.clients.list({pageSize: 100,});// List contactsconstcontacts=awaitclient.core.v1.contacts.list();// List hardware assetsconstassets=awaitclient.core.v1.hardwareAssets.list();// Other resources:// - client.core.v1.contracts// - client.core.v1.members// - client.core.v1.saas// - client.core.v1.tickets// - client.core.v1.opportunities

Filtering

The SDK supports all ScalePad API filter operators: eq, in, lt, lte, gt, gte.

// Exact matchconstworkstations=awaitclient.core.v1.hardwareAssets.list({filters: {type: {op: 'eq',value: 'WORKSTATION'},},});// Multiple values (IN operator)constserverOrWorkstation=awaitclient.core.v1.hardwareAssets.list({filters: {type: {op: 'in',value: ['SERVER','WORKSTATION']},},});// Numeric comparisonconstlowRamAssets=awaitclient.core.v1.hardwareAssets.list({filters: {'configuration.ram_bytes': {op: 'lte',value: 8_000_000_000},},});// Multiple filters (combined with AND)constfiltered=awaitclient.core.v1.hardwareAssets.list({filters: {type: {op: 'eq',value: 'WORKSTATION'},'configuration.ram_bytes': {op: 'lte',value: 8_000_000_000},},});// Special characters (automatically quoted)constclient=awaitclient.core.v1.clients.list({filters: {name: {op: 'eq',value: 'Space Sprockets, Inc.'},},});

Sorting

// Sort by field (ascending by default)constclients=awaitclient.core.v1.clients.list({sort: ['name'],});// Sort descendingconstclients=awaitclient.core.v1.clients.list({sort: ['-num_hardware_assets'],});// Multiple sort fieldsconstclients=awaitclient.core.v1.clients.list({sort: ['num_hardware_assets','-num_contacts'],});

Pagination

The SDK provides multiple ways to work with paginated results:

Manual Pagination

letcursor: string|undefined;letallClients=[];do{constresult=awaitclient.core.v1.clients.list({pageSize: 200,
cursor,});allClients.push(...result.data);cursor=result.next_cursor??undefined;}while(cursor);

Async Generator (Pages)

// Iterate through pagesforawait(constpageofclient.core.v1.clients.paginate({pageSize: 200})){console.log(`Processing ${page.length} clients`);// Process page...}

Async Generator (Items)

// Iterate through individual itemsforawait(constclientofclient.core.v1.clients.paginateItems({pageSize: 200})){console.log(`Processing client: ${client.id}`);// Process individual client...}

Collect All

import{collectAll}from'@scalepad/sdk';// Collect all pages into a single arrayconstallClients=awaitcollectAll((cursor)=>client.core.v1.clients.list({ cursor,pageSize: 200}));

Getting a Resource by ID

constclient=awaitclient.core.v1.clients.getById('client-id');constcontact=awaitclient.core.v1.contacts.getById('contact-id');

Error Handling

import{ScalePadClient,ApiError,AuthenticationError,RateLimitError,NetworkError,TimeoutError,ResponseValidationError,}from'@scalepad/sdk';try{constresult=awaitclient.core.v1.clients.list();}catch(error){if(errorinstanceofAuthenticationError){console.error('Invalid API credentials');}elseif(errorinstanceofRateLimitError){console.error('Rate limited. Retry after:',error.retryAfter);}elseif(errorinstanceofApiError){console.error('API error:',error.statusCode,error.errors);}elseif(errorinstanceofNetworkError){console.error('Network error:',error.message);}elseif(errorinstanceofTimeoutError){console.error('Request timed out');}elseif(errorinstanceofResponseValidationError){console.error('Invalid response format:',error.issues);}}

Custom Logger

import{ScalePadClient,Logger}from'@scalepad/sdk';classCustomLoggerimplementsLogger{debug(message: string, ...args: unknown[]): void{// Your custom debug logging}info(message: string, ...args: unknown[]): void{// Your custom info logging}warn(message: string, ...args: unknown[]): void{// Your custom warn logging}error(message: string, ...args: unknown[]): void{// Your custom error logging}}constclient=newScalePadClient({apiKey: 'your-api-key',logger: newCustomLogger(),});

Available Resources

The SDK currently supports the following Core API v1 resources (read-only):

• Clients: client.core.v1.clients
• Contacts: client.core.v1.contacts
• Contracts: client.core.v1.contracts
• Hardware Assets: client.core.v1.hardwareAssets
• Members: client.core.v1.members
• SaaS: client.core.v1.saas
• Tickets: client.core.v1.tickets
• Opportunities: client.core.v1.opportunities

Each resource provides:

• list(options?) - List resources with filtering, sorting, and pagination
• getById(id) - Get a single resource by ID
• paginate(options?) - Async generator for pages
• paginateItems(options?) - Async generator for individual items

Rate Limiting

The SDK automatically handles rate limiting according to the ScalePad API rate limits:

• Default limit: 50 requests per 5 seconds
• On 429 Too Many Requests, the SDK automatically retries after the Retry-After duration
• Configurable retry behavior via the retry option

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

importtype{Client,Contact,Contract,HardwareAsset,Member,SaaS,Ticket,Opportunity,Filters,SortSpec,ListResult,PaginatedResponse,}from'@scalepad/sdk';

Development

# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test# Type check
npm run typecheck
# Lint
npm run lint

Examples

See the examples directory for complete usage examples:

• quickstart.ts - Basic usage and common patterns

API Documentation

For full API documentation, visit:

• ScalePad API Getting Started
• ScalePad API Reference
• API Versioning Policy

Requirements

• Node.js >= 18 (for native fetch support)
• TypeScript >= 5.0 (if using TypeScript)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• GitHub Issues
• ScalePad Developer Documentation