@kb-labs/sdk

Core SDK — helpers for command, route, action, webhook definitions and testing.

Installation

pnpm add @kb-labs/sdk

Entry Points

| Entry Point | Description | |-------------|-------------| | @kb-labs/sdk | Main entry — all plugin building APIs | | @kb-labs/sdk/testing | Mock builders for unit testing |

Quick Start

import { defineCommand, defineManifest, useLogger, type CommandResult } from '@kb-labs/sdk';

export const hello = defineCommand({
  name: 'hello',
  flags: {
    name: { type: 'string', description: 'Name to greet' },
  },
  async handler(ctx, _argv, flags): Promise<CommandResult> {
    const logger = useLogger();
    logger.info('Running hello command');
    ctx.output?.write(`Hello, ${flags.name ?? 'world'}!`);
    return { ok: true };
  },
});

API Reference

Command Definitions

import {
  defineCommand,   // CLI command
  defineRoute,     // REST route handler
  defineAction,    // Workflow action
  defineWebhook,   // Webhook handler
  defineWebSocket, // WebSocket handler
  defineMessage,   // Message handler
} from '@kb-labs/sdk';

Manifest

import { defineManifest, defineCommandFlags } from '@kb-labs/sdk';

export default defineManifest({
  schema: 'kb.plugin/3',
  id: 'my-plugin',
  version: '1.0.0',
  commands: [{ name: 'hello', handler: './hello.js' }],
});

Platform Helpers

import {
  usePlatform,           // Global platform singleton
  useLogger,             // Structured logger
  useLoggerWithContext,  // Logger with persistent context
  useLLM,               // LLM adapter
  isLLMAvailable,
  getLLMTier,
  useEmbeddings,
  useVectorStore,
  useAnalytics,
  trackAnalyticsEvent,
  useStorage,
  useCache,             // Cache adapter (Redis / InMemory)
  isCacheAvailable,
  useConfig,            // Platform config
  isPlatformConfigured,
} from '@kb-labs/sdk';

Flags & Environment

import { defineFlags, defineEnv } from '@kb-labs/sdk';

// Type-safe CLI flags
export const myFlags = defineFlags({
  scope: { type: 'string', description: 'Limit to scope' },
  'dry-run': { type: 'boolean', default: false },
});

// Type-safe env variables
export const myEnv = defineEnv({
  MY_API_KEY: { type: 'string', description: 'API key' },
});

See DECLARATIVE-FLAGS-ENV.md for full reference.

UI Utilities

import {
  useLoader,
  displayArtifacts,
  displayArtifactsCompact,
  displaySingleArtifact,
  TimingTracker,
} from '@kb-labs/sdk';

Permission Presets

import {
  minimalPreset,
  gitWorkflowPreset,
  llmAccessPreset,
  combinePermissions,
} from '@kb-labs/sdk';

Platform Types

import type {
  ILLM, ICache, ILogger, IStorage,
  IEmbeddings, IVectorStore, IAnalytics,
  ManifestV3, CommandResult, PluginContextV3,
  HostType, PermissionSpec,
} from '@kb-labs/sdk';

Testing

import { createTestContext } from '@kb-labs/sdk';
// or full mock builders:
import { ... } from '@kb-labs/sdk/testing';

License

MIT