REFERENCE

SDK reference

Complete reference for @taskclan/sdk. TypeScript-first, works in Node 18+, edge runtimes, and any server environment.

Installation

npm install @taskclan/sdk

new Taskclan(options)

Creates a client. All requests inherit these defaults.

import { Taskclan } from "@taskclan/sdk";

const taskclan = new Taskclan({
  apiKey: process.env.TASKCLAN_API_KEY,
  defaultProfile: "t1-flow",
});

taskclan.run(params)

Runs a goal to completion and resolves with a RunResult.

RunResult

taskclan.run.stream(params)

Same params as run(), but returns an async iterable of StreamEvents.

const stream = await taskclan.run.stream({ goal: "Write a haiku about the sea" });

for await (const event of stream) {
  if (event.type === "text") process.stdout.write(event.delta);
  if (event.type === "done") console.log("\n", event.result.usage);
}

tool(definition)

Defines a typed tool. See Agents & tools for the full pattern.

Studio & Engine namespaces

• taskclan.studio.generate() / edit(), multimodal creation. See the Studio guide.
• taskclan.engine.run(workflow, options), deterministic workflows. See the Engine guide.

Errors

All failures throw a TaskclanError with a type, code, status, requestId, and a boolean retryable. A 402 also carries balance (credits remaining) and topUpUrl (where to recharge). See Errors & rate limits.

import { TaskclanError } from "@taskclan/sdk";

try {
  await taskclan.run({ goal: "..." });
} catch (err) {
  // Duck-typed (cross-realm safe, no instanceof needed):
  if (TaskclanError.isInsufficientCredits(err)) {
    // err.balance === 0, err.topUpUrl points at platform.taskclan.com/billing/recharge
    return promptTopUp(err.topUpUrl);
  }
  if (err instanceof TaskclanError) {
    console.error(err.status, err.code, err.requestId);
  }
}

TaskclanError.isInsufficientCredits(err) is the recommended way to detect a 402 — it works on any thrown value (including plain { status: 402 } objects), so cross-realm and bundler splits don't break the check.