@tokentop/plugin-sdk

SDK for building tokentop plugins. Types, helpers, and a test harness for provider, agent, theme, and notification plugins.

Install

bun add @tokentop/plugin-sdk

Quick Example

import {
  createProviderPlugin,
  apiKeyCredential,
  credentialFound,
  credentialMissing,
} from '@tokentop/plugin-sdk';

export default createProviderPlugin({
  id: 'my-provider',
  type: 'provider',
  name: 'My Provider',
  version: '1.0.0',
  meta: { brandColor: '#3b82f6' },
  permissions: {
    network: { enabled: true, allowedDomains: ['api.example.com'] },
    env: { read: true, vars: ['MY_API_KEY'] },
  },
  capabilities: {
    usageLimits: false,
    apiRateLimits: false,
    tokenUsage: false,
    actualCosts: true,
  },
  auth: {
    async discover(ctx) {
      const key = ctx.authSources.env.get('MY_API_KEY');
      return key ? credentialFound(apiKeyCredential(key)) : credentialMissing();
    },
    isConfigured: (creds) => !!creds.apiKey,
  },
  async fetchUsage(ctx) {
    const resp = await ctx.http.fetch('https://api.example.com/usage', {
      headers: { Authorization: `Bearer ${ctx.credentials.apiKey}` },
    });
    const data = await resp.json();
    return { fetchedAt: Date.now(), cost: { total: data.total, currency: 'USD', source: 'api' } };
  },
});

Plugin Types

Type	Interface	Purpose
provider	ProviderPlugin	Fetch usage data from AI model providers
agent	AgentPlugin	Parse coding agent sessions for token tracking
theme	ThemePlugin	Color schemes for the TUI
notification	NotificationPlugin	Alert delivery (Slack, Discord, terminal bell)

Subpath Exports

Import	Contents
@tokentop/plugin-sdk	Everything (types + helpers)
@tokentop/plugin-sdk/types	Type definitions only
@tokentop/plugin-sdk/helpers	createPlugin helpers, auth helpers, version utils
@tokentop/plugin-sdk/testing	Test harness and mock factories

Testing

Test plugins without running tokentop:

import { createTestContext } from '@tokentop/plugin-sdk/testing';
import plugin from './src/index.ts';

const ctx = createTestContext({
  env: { MY_API_KEY: 'test-key' },
  httpMocks: {
    'https://api.example.com/usage': {
      status: 200,
      body: { total: 4.50 },
    },
  },
});

const creds = await plugin.auth.discover(ctx);
assert(creds.ok);

Naming Convention

Tier	Pattern	Example
Official	@tokentop/{type}-<name>	@tokentop/agent-opencode
Community	tokentop-{type}-<name>	tokentop-provider-replicate
Scoped community	@scope/tokentop-{type}-<name>	@myname/tokentop-theme-catppuccin

Versioning

Version	What it is
SDK semver (1.1.0)	Package version on npm. Normal semver rules.
apiVersion (2)	Plugin contract version. Core checks at load time. Bumped rarely.

Use CURRENT_API_VERSION and isCompatible() to check compatibility. The createProviderPlugin() / createAgentPlugin() / etc. helpers stamp apiVersion automatically.

Documentation

See docs/plugin-development.md for the full API reference covering all plugin types, credential discovery, lifecycle hooks, configuration schemas, and testing patterns.

Contributing

See the Contributing Guide.

License

MIT