Developer Hub@eclips/sdk

TypeScript SDK

A typed client for the eClips Workforce REST API, with no runtime dependencies. It works in Node.js 18+ and any runtime that has fetch.

The package isn't on the public npm registry yet. Ask us for access; the API itself is included on the Growth and Enterprise plans.

Install

bash

npm install @eclips/sdk

Quickstart

Create a client with your API key and run an agent. The key tells us which organization you are.

typescript

import { EClipsClient } from '@eclips/sdk';

// Your organization comes from the API key, so there is no org id to pass.
const client = new EClipsClient({ apiKey: process.env.ECLIPS_API_KEY! });

// Start a run and poll until it finishes
const result = await client.runAndWait(
  'rfq_generator',
  'Draft an RFQ for 500 laptops, delivery to Amman within 30 days',
);

console.log(result.status);   // "completed", or "pending_triage" if a person must look
console.log(result.result);   // the agent's structured output

Batch runs

Run the same agent over up to 500 rows in one call, then poll for progress.

typescript

// Run the same agent over many rows in one call
const batch = await client.createBatch('ap_specialist', [
  { invoice_id: 'INV-1001' },
  { invoice_id: 'INV-1002' },
  { invoice_id: 'INV-1003' },
]);

// Poll for progress
const status = await client.getBatch(batch.id);
console.log(status.completed, '/', status.total);

Webhooks

Register a webhook with createWebhook(url, events); eClips POSTs a signed payload on each event. The signing secret is returned once, at creation. Verify the HMAC-SHA256 signature before you trust the body.

typescript

import { EClipsClient } from '@eclips/sdk';
import crypto from 'crypto';

const client = new EClipsClient({ apiKey: process.env.ECLIPS_API_KEY! });

// 1. Register a webhook. The signing secret is returned once, so store it.
const { secret } = await client.createWebhook(
  'https://your-app.com/webhooks/eclips',
  ['run.completed', 'run.failed', 'run.triage_required'],
);

// 2. In your webhook route, verify the HMAC-SHA256 signature before trusting
//    the body. It arrives in X-eClips-Signature as sha256=<hex>.
function verify(rawBody: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Typed errors

Each kind of failure has its own error class, so you can branch on what happened.

typescript

import {
  EClipsClient,
  AuthenticationError,
  RateLimitError,
  TimeoutError,
  NotFoundError,
} from '@eclips/sdk';

try {
  const result = await client.runAndWait('ap_specialist', task);
} catch (err) {
  if (err instanceof AuthenticationError) {
    // Invalid or missing API key
  } else if (err instanceof RateLimitError) {
    await sleep(err.retryAfter ?? 60);   // seconds
  } else if (err instanceof TimeoutError) {
    // The wait timed out but the run carries on. Poll client.getRun(err.runId).
  } else if (err instanceof NotFoundError) {
    // Run or triage item not found
  }
}

Method reference

client.run()Runs

Start a run; returns { run_id, status, agent_type }

client.runAndWait()Runs

Start a run and poll until it finishes

client.waitForRun()Runs

Poll an existing run until it finishes

client.getRun()Runs

Fetch a single run by id

client.listRuns()Runs

List runs ({ data, total, limit, offset })

client.listTriage()Triage

Items waiting for a person

client.approveTriage()Triage

Approve and continue the blocked run

client.rejectTriage()Triage

Reject an item with an optional reason

client.createWebhook()Webhooks

client.listWebhooks()Webhooks

List registered webhook endpoints

client.deleteWebhook()Webhooks

Delete a webhook by id

client.createBatch()Batch

Run an agent over many rows at once

client.getBatch()Batch

Fetch a batch with progress counts

client.listBatches()Batch

List batches for your org

client.cancelBatch()Batch

Cancel an in-flight batch

REST API reference Scaffold a project