Client SDK v3.2.0

The official #divisions client SDK provides a type-safe, high-performance interface for interacting with our API. Built for scale, designed for developers.

Installation

Install the SDK using your preferred package manager. The SDK supports Node.js 18+, Deno, Bun, and modern browsers.

# Install the #divisions client SDK
npm install @divisions/client-sdk
ℹ️
For browser usage, use the UMD build from our CDN or bundle with Webpack/Vite. ESM is supported natively.

Quick Start

Initialize the client and make your first API call in under 10 lines of code.

import { DivisionsClient } from '@divisions/client-sdk';

// Initialize with your API key
const client = new DivisionsClient({
  apiKey: process.env.DIVISIONS_API_KEY,
  environment: 'production'
});

// Fetch your first project
const project = await client.projects.get({
  projectId: 'proj_8x9k2m'
});

console.log(project.name); // "Acme Corp Platform"

Configuration

Customize the SDK behavior using the options object passed during initialization.

Option Type Default Description
apiKey string - Your #divisions API key (required)
environment 'sandbox' | 'production' production Target API environment
timeout number 8000 Request timeout in milliseconds
retryAttempts number 3 Automatic retry count on 429/5xx errors
basePath string /v3 Custom API base path (advanced)
fetch Function global.fetch Custom fetch implementation for testing

Core Methods

The SDK exposes a namespaced method structure for intuitive resource access.

client.projects

  • .get({ projectId }) — Retrieve project details
  • .list({ page, limit, filter }) — Paginated project listing
  • .create({ name, config, metadata }) — Create a new project
  • .update({ projectId, ...data }) — Patch project configuration
  • .delete({ projectId }) — Archive project (soft delete)

client.deployments

  • .trigger({ projectId, version, env }) — Start deployment pipeline
  • .status({ deploymentId }) — Check real-time deployment status
  • .logs({ deploymentId, tail }) — Stream deployment logs (SSE)
  • .rollback({ deploymentId, targetVersion }) — Rollback to previous version
⚠️
Rate limits apply per API key. The SDK automatically handles 429 Too Many Requests with exponential backoff. Monitor X-RateLimit-Remaining headers for advanced control.

Authentication

API keys are automatically attached to all requests via the Authorization: Bearer <key> header. For enhanced security, use short-lived tokens generated via your dashboard.

// Automatic token refresh configuration
const client = new DivisionsClient({
  apiKey: 'sk_live_...',
  onTokenExpired: async () => {
    const newToken = await fetchNewToken();
    client.setApiKey(newToken);
  }
});

Error Handling

All API errors throw a DivisionsError instance with structured metadata for programmatic handling.

try {
  await client.projects.create({ name: 'Invalid' });
} catch (err) {
  if (err instanceof DivisionsError) {
    console.log(err.code);       // "VALIDATION_ERROR"
    console.log(err.status);     // 400
    console.log(err.requestId);  // "req_9x2m8k"
    console.log(err.details);    // { field: "name", message: "..." }
  }
}

Webhooks

Listen to real-time events without polling. The SDK includes a built-in webhook verification utility.

import { verifyWebhook } from '@divisions/client-sdk/webhooks';

app.post('/webhook', async (req, res) => {
  const isValid = verifyWebhook(
    req.rawBody,
    req.headers['x-divisions-signature'],
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) return res.status(401).end();

  const event = JSON.parse(req.rawBody);
  handleEvent(event);
  res.status(200).json({ received: true });
});

TypeScript Support

Full type definitions are included out of the box. No @types package required. Intellisense works for all methods, payloads, and responses.

import type { Project, DeploymentStatus, SdkConfig } from '@divisions/client-sdk';

// Fully typed responses
const projects: Project[] = await client.projects.list();
const status: DeploymentStatus = await client.deployments.status({ id: 'dep_123' });