SDK Reference

The @kb-labs/sdk package provides the TypeScript API for building plugins and integrating with the KB Labs platform.

Installation

pnpm add @kb-labs/sdk

HandlerContext

Every handler receives a HandlerContext as its second argument.

import type { HandlerContext } from '@kb-labs/sdk';

export async function handler(input: unknown, ctx: HandlerContext) {
  // ctx is fully typed
}

ctx.logger

Structured logger scoped to the current step run.

ctx.logger.info('Processing item', { id: item.id });
ctx.logger.warn('Rate limit approaching');
ctx.logger.error('Failed to fetch', { url, error: err.message });

ctx.cache

Optional cache client. Always check for null — cache may not be configured.

const cache = ctx.cache;
if (cache) {
  const cached = await cache.get<MyType>('my-key');
  if (cached) return cached;

  const result = await compute();
  await cache.set('my-key', result, 60_000); // TTL: 60s
  return result;
}

ctx.state

State Broker client for persistent key-value storage across steps and runs.

// Write state
await ctx.state.set('counter', 42);

// Read state
const count = await ctx.state.get<number>('counter');

// Delete
await ctx.state.delete('counter');

useCache()

Access the platform cache from anywhere using the composable pattern:

import { useCache } from '@kb-labs/sdk';

const cache = useCache();
if (cache) {
  await cache.set('key', value);
}

useLLM()

Access the LLM adapter from the global platform singleton:

import { useLLM } from '@kb-labs/sdk';

const llm = useLLM();
const response = await llm.chat([
  { role: 'user', content: 'Summarize this: ...' }
]);

Types

// Core handler type
type Handler<TInput, TOutput> = (
  input: TInput,
  ctx: HandlerContext
) => Promise<TOutput>;

// Logger
interface Logger {
  info(message: string, meta?: Record<string, unknown>): void;
  warn(message: string, meta?: Record<string, unknown>): void;
  error(message: string, meta?: Record<string, unknown>): void;
  debug(message: string, meta?: Record<string, unknown>): void;
}

// Cache
interface ICache {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
  delete(key: string): Promise<void>;
}