Convilyn developers

Client

The Convilyn client — install, authenticate, construct, and tune retry / timeout / auto-throttle for @convilyn/sdk.

Install

npm install @convilyn/sdk      # or: pnpm add @convilyn/sdk / yarn add @convilyn/sdk

Requires Node 18+ (uses global fetch). The only runtime dependency is commander (for the CLI). The package ships ESM + CJS + type declarations.

Authentication

Consumer API keys start with ck_. Mint one under Settings → API.

import { Convilyn } from "@convilyn/sdk";
 
const client = new Convilyn({ apiKey: myKey }); // explicit
const client = new Convilyn(); // or reads CONVILYN_API_KEY

Constructing the client

const client = new Convilyn({ apiKey: process.env.CONVILYN_API_KEY });
// ... use client.files / .convert / .goals / .workflows / .account
await client.close();

There is a single promise-based Convilyn (no AsyncConvilyn). The version is exported as the VERSION constant.

Configuration reference

Constructor optionEnv varDefault
apiKeyCONVILYN_API_KEY— (required)
baseUrlCONVILYN_BASE_URLhttps://api.convilyn.corenovus.com
wsUrlCONVILYN_WS_URL—
timeout (seconds)—30
maxRetries / retryPolicy—5-attempt backoff
autoThrottle—disabled
disableIdempotency—false

Retry, timeout & auto-throttle

import {
  Convilyn,
  ExponentialBackoffRetry,
  NoRetry,
  AutoThrottleConfig,
} from "@convilyn/sdk";
 
const client = new Convilyn({
  timeout: 30, // per-request, in seconds
  maxRetries: 5, // cap (0 = no retries); or pass a full policy:
  retryPolicy: new ExponentialBackoffRetry({
    maxAttempts: 5,
    baseDelay: 0.2,
    maxDelay: 30,
  }),
  autoThrottle: true, // sleep+retry on a 402 quota error
});
  • retryPolicy / maxRetries handle transient transport failures (408 / 429 / 5xx) with capped exponential backoff + jitter, honouring Retry-After. Pass new NoRetry() to fail fast.
  • autoThrottle is a distinct, opt-in shim for the 402 QUOTA_EXCEEDED envelope, where the remedy is waiting for the quota window. true enables defaults (1 retry, 60s cap); pass new AutoThrottleConfig({ maxRetries: 2, maxSleep: 120, fallbackSleep: 5 }) to tune.
  • A soft-limit signal (X-Quota-State: soft_limit) surfaces via Node's process.emitWarning whether or not auto-throttle is enabled.

Quickstart

const client = new Convilyn({ apiKey: process.env.CONVILYN_API_KEY });
const file = await client.files.upload({ path: "report.docx" });
const job = await client.convert.createAndWait({ file, targetFormat: "pdf" });
await client.convert.downloadTo(job, { to: "report.pdf" });
await client.close();
 
const result = await client.goals.run({
  workflowId: "wf_grade_sheet",
  files: [file.fileId],
});
console.log(result.status); // 'completed' | 'partial' | 'failed' | 'slots_pending' | …

Where to go next

TypeScript SDKResources

files, convert, goals (HITL + WebSocket events), workflows, account.

TypeScript SDKErrors

The error class hierarchy and handling patterns.

TypeScript SDKCLI

The convilyn binary and its exit codes.

OverviewConsumer SDK

All consumer SDK languages and guides.