TypeScript SDK Guide

Official typed client library for integrating Zynocode Labs computational tools, catalog discovery, and agent capabilities in Node.js and TypeScript environments.

Server-Side Execution Notice

While the browser tools on Zynocode Labs run zero-upload client-side code, the @zynocode/sdk connects to our hosted REST API. Calls to client.executeTool() send your parameters over TLS 1.3 to Zynocode Labs servers for processing.

Installation

The package is published as @zynocode/sdk and requires Node.js 18.0.0 or later. It provides dual ESM and CommonJS distributions with bundled TypeScript declarations.

# npm

npm install @zynocode/sdk

# pnpm

pnpm add @zynocode/sdk

# yarn

yarn add @zynocode/sdk

Client Initialization

Instantiate ZynocodeClient with your configuration. If no options are provided, it automatically reads the ZYNOCODE_API_KEY, ZYNOCODE_BASE_URL, and ZYNOCODE_WORKSPACE_ID environment variables.

import { ZynocodeClient } from '@zynocode/sdk'; const client = new ZynocodeClient({ apiKey: process.env.ZYNOCODE_API_KEY, // Optional: defaults to process.env.ZYNOCODE_API_KEY baseUrl: 'https://labs.zynocode.com', // Optional: defaults to https://labs.zynocode.com workspaceId: process.env.ZYNOCODE_WORKSPACE_ID, // Optional: defaults to process.env.ZYNOCODE_WORKSPACE_ID timeoutMs: 30000, // Optional: request timeout in ms (default: 30000) });

Entitlement Note:

API access requires an account with active API entitlements. Tool queries (listTools and getTool) do not require an API key.

Client Methods

client.listTools(options?: ListToolsOptions)

Returns: Promise<{ success: boolean; tools: ToolMetadata[]; count: number }>

Lists available tools from the catalog with optional filtering by category or keyword search.

Example Usage

const { tools, count } = await client.listTools({ category: 'developer', search: 'formatter', }); console.log(`Found ${count} developer tools:`); tools.forEach(t => console.log(`- ${t.name} (${t.slug})`));

client.getTool(slug: string)

Returns: Promise<ToolMetadata>

Retrieves authoritative metadata for a single tool by its canonical slug (e.g. 'emi-calculator').

Example Usage

const tool = await client.getTool('emi-calculator'); console.log(tool.name, tool.status, tool.creditCost);

client.executeTool<T = unknown>(slugOrId, params?, options?)

Returns: Promise<ToolExecutionResponse<T>>

Executes a tool on the server with typed input parameters and returns the execution result. Supports idempotency keys for safe retries.

Example Usage

interface WordCounterResult { words: number; characters: number; sentences: number; paragraphs: number; readingTimeMinutes: number; } const response = await client.executeTool<WordCounterResult>( 'word-counter', { text: 'Hello world from Zynocode API.' }, { idempotencyKey: 'exec_client_req_019' } ); console.log('Status:', response.status); console.log('Words:', response.result.words); console.log('Summary:', response.outputSummary);

Real Output

{
  "success": true,
  "executionId": "exec_079ebe1a-a28d-4ed2-9d7a-e901b3e0b80e",
  "status": "completed",
  "durationMs": 1,
  "creditsConsumed": 0,
  "isReplayed": false,
  "result": {
    "words": 5,
    "characters": 30,
    "sentences": 1,
    "paragraphs": 1,
    "readingTimeMinutes": 1
  },
  "outputSummary": "5 words, 1 sentences, ~1 min read"
}

client.getExecution(executionId, options?)

Returns: Promise<ExecutionRecordResponse>

Fetches an existing execution record, status, and input payload by its execution ID.

Example Usage

const record = await client.getExecution('exec_079ebe1a-a28d-4ed2-9d7a-e901b3e0b80e'); console.log(record.execution.toolSlug, record.execution.status);

Error Handling

The SDK exports ZynocodeError (base class) and ZynocodeApiError. When an API call fails or exceeds rate limits, ZynocodeApiError provides HTTP status code, API error code, and retryAfter seconds.

import { ZynocodeClient, ZynocodeApiError } from '@zynocode/sdk'; try { await client.executeTool('word-counter', { text: 'Testing errors' }); } catch (error) { if (error instanceof ZynocodeApiError) { console.error(`HTTP ${error.status} [${error.code}]: ${error.message}`); if (error.status === 429 && error.retryAfter) { console.warn(`Rate limited. Retry after ${error.retryAfter} seconds.`); } } else { console.error('Unexpected error:', error); } }

Tool Authoring & Testing Utilities

The SDK also exports builders for developing and testing tool manifests locally before deploying:

createTool(id)

Fluent builder to create universal manifests with validation.

ManifestValidator.validate()

Validates schema invariants, slug prefix, categories, and SEO fields.

testToolExecution(handler, input)

Harness to execute tool handlers locally without a database.

assertValidManifest(manifest)

Boolean validator for tool manifest compliance.