SDK Reference Overview

npm install @teleton-agent/sdk

interface PluginSDK {
  readonly version: string;            // SDK version (e.g. "1.0.0")
  readonly ton: TonSDK;               // TON blockchain operations
  readonly telegram: TelegramSDK;     // Telegram messaging & users
  readonly db: Database | null;        // Isolated SQLite database
  readonly config: Record<string, unknown>;      // Sanitized app config
  readonly pluginConfig: Record<string, unknown>; // Plugin-specific config
  readonly secrets: SecretsSDK;        // Secure secret access
  readonly storage: StorageSDK | null; // Key-value storage
  readonly log: PluginLogger;          // Prefixed logger
  readonly bot: BotSDK | null;         // Inline bot mode
}

import type { PluginSDK, SimpleToolDef, PluginManifest } from "@teleton-agent/sdk";

export const manifest: PluginManifest = {
  name: "balance-checker",
  version: "1.0.0",
  description: "Check any TON address balance with USD conversion",
};

export const tools = (sdk: PluginSDK): SimpleToolDef[] => [
  {
    name: "check_balance",
    description: "Check the TON balance and USD value of an address",
    parameters: {
      type: "object",
      properties: {
        address: {
          type: "string",
          description: "TON address to check (EQ... or UQ... format)",
        },
      },
      required: ["address"],
    },
    async execute(params) {
      const address = params.address as string;

      if (!sdk.ton.validateAddress(address)) {
        return { success: false, error: "Invalid TON address format" };
      }

      const [balance, price] = await Promise.all([
        sdk.ton.getBalance(address),
        sdk.ton.getPrice(),
      ]);

      if (!balance) {
        return { success: false, error: "Failed to fetch balance" };
      }

      const usdValue = price
        ? (parseFloat(balance.balance) * price.usd).toFixed(2)
        : "unavailable";

      sdk.log.info(`Balance check for ${address}: ${balance.balance} TON`);

      return {
        success: true,
        data: {
          address,
          balance: balance.balance,
          balanceNano: balance.balanceNano,
          usdValue: `$${usdValue}`,
        },
      };
    },
  },
];

interface PluginManifest {
  name: string;                        // Lowercase alphanumeric + hyphens, 1-64 chars
  version: string;                     // Semver (e.g. "1.0.0")
  author?: string;                     // Plugin author
  description?: string;                // Short description (max 256 chars)
  dependencies?: string[];             // Required built-in modules (e.g. ["deals"])
  defaultConfig?: Record<string, unknown>; // Default config values
  sdkVersion?: string;                 // Required SDK version range (e.g. ">=1.0.0")
  secrets?: Record<string, SecretDeclaration>; // Required API keys
  bot?: BotManifest;                   // Bot capabilities (inline, callbacks)
}

import type { PluginManifest } from "@teleton-agent/sdk";

export const manifest: PluginManifest = {
  name: "weather-report",
  version: "2.1.0",
  author: "dev@example.com",
  description: "Real-time weather data via OpenWeatherMap API",
  sdkVersion: ">=1.0.0",
  defaultConfig: {
    units: "metric",
    defaultCity: "Paris",
  },
  secrets: {
    api_key: {
      required: true,
      description: "OpenWeatherMap API key",
    },
    webhook_url: {
      required: false,
      description: "Optional webhook for alerts",
    },
  },
  bot: {
    inline: true,
    callbacks: true,
    rateLimits: {
      inlinePerMinute: 20,
      callbackPerMinute: 40,
    },
  },
};

interface SimpleToolDef {
  name: string;                // Unique tool name (e.g. "weather_forecast")
  description: string;         // Human-readable description for the LLM
  parameters?: Record<string, unknown>;  // JSON Schema for parameters
  execute: (
    params: Record<string, unknown>,
    context: PluginToolContext
  ) => Promise<ToolResult>;    // Tool executor function
  scope?: ToolScope;           // Visibility scope (default: "always")
  category?: ToolCategory;     // "data-bearing" or "action"
}

interface ToolResult {
  success: boolean;   // Whether the execution succeeded
  data?: unknown;     // Result data (serialized to JSON for the LLM)
  error?: string;     // Error message if failed
}

interface PluginToolContext {
  chatId: string;      // Telegram chat ID where the tool was invoked
  senderId: number;    // Telegram user ID of the sender
  isGroup: boolean;    // Whether this is a group chat (vs DM)
  bridge: unknown;     // TelegramBridge instance
  db: unknown;         // Plugin's isolated SQLite database
  config?: Record<string, unknown>;  // Sanitized bot config
}

export const tools = (sdk: PluginSDK): SimpleToolDef[] => [
  {
    name: "greet_user",
    description: "Send a personalized greeting to the current chat",
    parameters: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name to greet" },
      },
      required: ["name"],
    },
    scope: "dm-only",
    async execute(params, context) {
      const name = params.name as string;
      await sdk.telegram.sendMessage(
        context.chatId,
        `Hello, ${name}! Welcome to the chat.`
      );
      return { success: true, data: { greeted: name } };
    },
  },
];

{
  name: "transfer_funds",
  description: "Send TON from the bot wallet to a recipient",
  scope: "admin-only",
  async execute(params, context) {
    const to = params.address as string;
    const amount = params.amount as number;
    const result = await sdk.ton.sendTON(to, amount);
    return { success: true, data: result };
  },
}