Plugin SDK Reference

interface PluginSDK {
  version: string
  readonly ton: TonSDK
  readonly telegram: TelegramSDK
  readonly db: Database | null
  readonly config: Record<string, unknown>
  readonly pluginConfig: Record<string, unknown>
  readonly secrets: SecretsSDK
  readonly storage: StorageSDK | null
  readonly log: PluginLogger
}

if (sdk.version !== '1.0.0') {
  sdk.log.warn('Untested SDK version: ' + sdk.version);
}

const result = await sdk.ton.verifyPayment({
  amount: '1.5',        // expected TON amount (1% tolerance)
  memo: 'order-123',    // expected transaction memo
  timeWindow: 600,      // seconds to look back (default: 600 = 10min)
  senderAddress: '...'  // optional: expected sender
});

// result: {
//   verified: boolean,
//   txHash: string,
//   amount: string,
//   playerWallet: string,
//   date: Date,
//   secondsAgo: number,
//   error?: string
// }

const balance = await sdk.ton.getBalance();
sdk.log.info(`Wallet balance: ${balance.balance} TON`);

const price = await sdk.ton.getPrice();
sdk.log.info(`TON/USD: $${price.usd}`);

if (sdk.ton.validateAddress(userAddr)) {
  const result = await sdk.ton.sendTON(userAddr, '0.5', 'reward');
  sdk.log.info(`Sent 0.5 TON, hash: ${result.hash}`);
}

// Send a message with inline buttons
const msgId = await sdk.telegram.sendMessage(chatId, 'Choose an option:', {
  buttons: [
    [{ text: 'Option A', data: 'opt_a' }],
    [{ text: 'Option B', data: 'opt_b' }]
  ]
});

// Download and re-send media
const buffer = await sdk.telegram.downloadMedia(chatId, mediaMessageId);
if (buffer) {
  await sdk.telegram.sendPhoto(chatId, buffer, { caption: 'Downloaded!' });
}

// Moderation
await sdk.telegram.muteUser(chatId, spammerId, Math.floor(Date.now() / 1000) + 3600);

export const migrate = (db: any) => {
  db.exec(`
    CREATE TABLE IF NOT EXISTS scores (
      user_id INTEGER PRIMARY KEY,
      points INTEGER NOT NULL DEFAULT 0,
      updated_at TEXT DEFAULT (datetime('now'))
    )
  `);
};

// Then in your tool:
export const tools = (sdk: PluginSDK): SimpleToolDef[] => [{
  name: 'get_score',
  description: 'Get user score',
  async execute(params, context) {
    const row = sdk.db!.prepare('SELECT points FROM scores WHERE user_id = ?')
      .get(context.senderId);
    return { success: true, data: row ?? { points: 0 } };
  }
}];

plugins:
  my_plugin:
    max_retries: 5
    api_endpoint: "https://api.example.com"

const maxRetries = (sdk.pluginConfig.max_retries as number) ?? 3;
const endpoint = sdk.pluginConfig.api_endpoint as string;

// Safe check
if (sdk.secrets.has('api_key')) {
  const key = sdk.secrets.get('api_key');
  // use key...
}

// Fail fast
const key = sdk.secrets.require('api_key'); // throws if missing

// Cache a value for 5 minutes
sdk.storage!.set('api_response', data, { ttl: 5 * 60 * 1000 });

// Retrieve it
const cached = sdk.storage!.get<ApiResponse>('api_response');
if (cached) {
  return { success: true, data: cached };
}

// Check and delete
if (sdk.storage!.has('old_key')) {
  sdk.storage!.delete('old_key');
}

sdk.log.info('Processing payment');
// Output: [plugin:my-plugin] Processing payment

sdk.log.error('Payment failed', { code: 'TIMEOUT', retries: 3 });
// Output: [plugin:my-plugin] Payment failed { code: 'TIMEOUT', retries: 3 }

interface PluginManifest {
  name: string            // lowercase, alphanumeric + hyphens, 1-64 chars
  version: string         // semver (e.g. "1.0.0")
  author?: string         // plugin author name
  description?: string    // max 256 characters
  dependencies?: string[] // required modules: ["deals", "ton"]
  defaultConfig?: Record<string, unknown>  // default config values
  sdkVersion?: string     // required SDK version range (e.g. ">=1.0.0")
  secrets?: Record<string, SecretDeclaration>  // declared secrets
}

export const manifest: PluginManifest = {
  name: 'price-alerts',
  version: '2.1.0',
  author: 'team@example.com',
  description: 'TON price alerts with configurable thresholds',
  dependencies: ['ton'],
  sdkVersion: '>=1.0.0',
  defaultConfig: {
    check_interval: 60,
    threshold_pct: 5
  },
  secrets: {
    webhook_url: {
      required: false,
      description: 'Optional webhook for external notifications'
    }
  }
};

interface SimpleToolDef {
  name: string                              // unique tool name
  description: string                       // what the tool does (shown to LLM)
  parameters?: Record<string, unknown>      // JSON Schema for input params
  execute: (params: any, context: PluginToolContext) => Promise<ToolResult>
  scope?: "always" | "dm-only" | "group-only" | "admin-only"
  category?: "data-bearing" | "action"
}

interface ToolResult {
  success: boolean
  data?: unknown
  error?: string
}

interface PluginToolContext {
  chatId: string
  senderId: number
  isGroup: boolean
  bridge: unknown       // raw TelegramBridge (prefer sdk.telegram)
  db: unknown           // raw database (prefer sdk.db)
  config?: unknown
}

export const tools = (sdk: PluginSDK): SimpleToolDef[] => [{
  name: 'check_balance',
  description: 'Check TON balance for the bot wallet or a given address',
  scope: 'always',
  category: 'data-bearing',
  parameters: {
    type: 'object',
    properties: {
      address: {
        type: 'string',
        description: 'TON address to check (optional, defaults to bot wallet)'
      }
    }
  },
  async execute(params, context) {
    try {
      const balance = await sdk.ton.getBalance(params.address);
      return {
        success: true,
        data: { balance: balance.balance, nano: balance.nanoBalance }
      };
    } catch (err) {
      sdk.log.error('Balance check failed', err);
      return { success: false, error: String(err) };
    }
  }
}];

import type { PluginSDK } from '@teleton-agent/sdk';

export const start = async (ctx: { sdk: PluginSDK; log: PluginLogger }) => {
  ctx.log.info('Plugin started, initializing cache...');
  ctx.sdk.storage?.set('boot_time', Date.now());
};

export const stop = async () => {
  // Cleanup timers, connections, etc.
};

export const onMessage = async (event: {
  chatId: string;
  senderId: number;
  text: string;
  messageId: number;
}) => {
  // React to messages without being called as a tool
  if (event.text.includes('gm')) {
    await sdk.telegram.sendReaction(event.chatId, event.messageId, '👋');
  }
};

export const onCallbackQuery = async (event: {
  chatId: string;
  senderId: number;
  data: string;
  messageId: number;
}) => {
  // Handle inline button presses
  if (event.data === 'opt_a') {
    await sdk.telegram.editMessage(event.chatId, event.messageId, 'You chose A!');
  }
};