eClips Tech
eClipsTech
Developer Hub@eclips/sdk

TypeScript SDK

A fully typed, zero-dependency client for the eClips REST API. Works in Node.js 18+ and any modern runtime with fetch.

Install

bash
npm install @eclips/sdk

Quickstart

Create a client with your API key and run an agent. The org is derived from the key.

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

// The organization is derived from your API key — no org id needed.
const client = new EClipsClient({ apiKey: process.env.ECLIPS_API_KEY! });

// Fire and poll — resolves once the run reaches a terminal state
const result = await client.runAndWait(
  'procurement_specialist',
  'Get 3 vendor quotes for 500 laptops — Dell, HP, Lenovo',
);

console.log(result.status);   // "completed"
console.log(result.result);   // { vendors: [...], recommended: "Dell" }

Batch runs

Run the same agent over many rows in a single call and 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 trusting 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 — 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 failure is a catchable error class so you can branch on exactly 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) {
    // err.runId is still valid — 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 + poll until terminal

client.waitForRun()Runs

Poll an existing run until terminal

client.getRun()Runs

Fetch a single run by id

client.listRuns()Runs

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

client.listTriage()Triage

Pending human-in-the-loop items

client.approveTriage()Triage

Approve and continue the blocked run

client.rejectTriage()Triage

Reject an item with an optional reason

client.createWebhook()Webhooks

Register a URL + events; returns the secret once

client.listWebhooks()Webhooks

List registered webhook endpoints

client.deleteWebhook()Webhooks

Delete a webhook by id

client.listWorkflows()Workflows

List workflows for your org

client.getWorkflow()Workflows

Fetch a single workflow by id

client.createWorkflow()Workflows

Create a workflow ({ name, steps, edges })

client.triggerWorkflow()Workflows

Run a workflow with optional input

client.listWorkflowRuns()Workflows

List runs for a workflow

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 referenceScaffold a project