kb-bot-sdk

A powerful TypeScript SDK for creating type-safe integrations with full autocomplete support, built with Zod validation and ready for npm publishing.

Features

• ✅ TypeScript support with full type definitions
• ✅ CommonJS and ESM builds
• ✅ Source maps included
• ✅ Tree-shaking friendly
• ✅ Zod validation for all inputs and outputs
• ✅ TypeScript autocompletion
• ✅ Schema-driven integration creation
• ✅ CLI tool with kbs alias

Installation

npm install kb-bot-sdk

Usage

TypeScript

import { createSchema, createIntegration, z } from 'kb-bot-sdk';

// Create a schema for your integration
const mySchema = createSchema({
  name: 'my-integration',
  version: '1.0.0',
  description: 'My awesome integration',
  config_settings: {
    schema: z.object({
      apiKey: z.string(),
      baseUrl: z.string().url()
    })
  },
  action_functions: {
    greet: {
      inputParameter: { schema: z.object({ name: z.string() }) },
      outputParameter: { schema: z.object({ message: z.string() }) }
    },
    calculate: {
      inputParameter: { schema: z.object({ a: z.number(), b: z.number() }) },
      outputParameter: { schema: z.object({ result: z.number() }) }
    }
  },
  incoming_events: {
    userCreated: {
      inputParameter: { schema: z.object({ userId: z.string(), email: z.string() }) },
      outputParameter: { schema: z.object({ success: z.boolean() }) }
    }
  },
  message_channels: {},
  webhooks: {}
});

// Create the integration implementation
const myIntegration = createIntegration(mySchema, {
  action_functions: {
    greet: ({ input }) => ({ message: `Hello, ${input.name}!` }),
    calculate: ({ input }) => ({ result: input.a + input.b })
  },
  incoming_events: {
    userCreated: ({ input }) => {
      console.log(`User created: ${input.email}`);
      return { success: true };
    }
  },
  config_settings: {
    apiKey: 'your-api-key',
    baseUrl: 'https://api.example.com'
  }
});

// Use the integration
const greeting = await myIntegration.action_functions.greet({ name: 'World' });
console.log(greeting.message); // "Hello, World!"

const calculation = await myIntegration.action_functions.calculate({ a: 5, b: 3 });
console.log(calculation.result); // 8

JavaScript (CommonJS)

const { createSchema, createIntegration, z } = require('kb-bot-sdk');

// Same usage as TypeScript but without type safety
const schema = createSchema({
  name: 'my-integration',
  version: '1.0.0',
  config_settings: {
    schema: z.object({
      apiKey: z.string()
    })
  },
  action_functions: {
    greet: {
      inputParameter: { schema: z.object({ name: z.string() }) },
      outputParameter: { schema: z.object({ message: z.string() }) }
    }
  },
  incoming_events: {},
  message_channels: {},
  webhooks: {}
});

CLI Usage

# Install globally
npm install -g kb-bot-sdk

# Use the CLI
kbs example
kbs help

API Reference

Core Functions

createSchema<T>(props: SchemaPropsType): SchemaCreator<T>

Creates a typed schema for your integration.

createIntegration<T>(schema: SchemaCreator, impl: IntegrationAllImplementations): WrappedIntegrationAllImplementations

Creates a type-safe integration from a schema and implementation.

Schema Types

SchemaPropsType

type SchemaPropsType = {
  name: string;
  description?: string;
  version: string;
  config_settings: {
    schema: ZodObject;
  };
  action_functions: Record<string, ActionDefinition>;
  incoming_events: Record<string, EventDefinition>;
  message_channels: Record<string, MessageChannelDefinition>;
  webhooks: Record<string, WebhookDefinition>;
};

ActionDefinition

type ActionDefinition<TInput, TOutput> = {
  inputParameter: { schema: TInput };
  outputParameter: { schema: TOutput };
};

Function Props

ActionFunctionProps<TInput>

type ActionFunctionProps<TInput> = {
  input: TInput;
  ctx?: {
    userId?: string;
    sessionId?: string;
    timestamp?: number;
    [key: string]: any;
  };
  logger?: {
    info: (message: string, data?: any) => void;
    error: (message: string, error?: any) => void;
    warn: (message: string, data?: any) => void;
    debug: (message: string, data?: any) => void;
  };
  [key: string]: any;
};

Development

Prerequisites

• Node.js 16+
• npm

Setup

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode for development
npm run dev

# Clean build directory
npm run clean

Publishing

# Build and publish to npm
npm run prepublishOnly
npm publish

License

MIT