https://github.com/tokentopapp/plugin-sdk
SDK for building tokentop plugins — type definitions, helpers, and test harness for providers, agents, themes, and notifications
https://github.com/tokentopapp/plugin-sdk
ai bun developer-tools plugin-sdk plugin-system sdk tokentop typescript
Last synced: 29 days ago
JSON representation
SDK for building tokentop plugins — type definitions, helpers, and test harness for providers, agents, themes, and notifications
- Host: GitHub
- URL: https://github.com/tokentopapp/plugin-sdk
- Owner: tokentopapp
- License: mit
- Created: 2026-02-14T12:36:36.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-17T00:03:15.000Z (about 1 month ago)
- Last Synced: 2026-04-17T02:14:01.223Z (about 1 month ago)
- Topics: ai, bun, developer-tools, plugin-sdk, plugin-system, sdk, tokentop, typescript
- Language: TypeScript
- Homepage: https://github.com/tokentopapp/tokentop
- Size: 113 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# @tokentop/plugin-sdk
[](https://www.npmjs.com/package/@tokentop/plugin-sdk)
[](https://github.com/tokentopapp/plugin-sdk/actions/workflows/ci.yml)
[](https://www.typescriptlang.org/)
[](LICENSE)
SDK for building [tokentop](https://github.com/tokentopapp/tokentop) plugins. Types, helpers, and a test harness for provider, agent, theme, and notification plugins.
## Install
```bash
bun add @tokentop/plugin-sdk
```
## Quick Example
```typescript
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:
```typescript
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}-` | `@tokentop/agent-opencode` |
| Community | `tokentop-{type}-` | `tokentop-provider-replicate` |
| Scoped community | `@scope/tokentop-{type}-` | `@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](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](https://github.com/tokentopapp/.github/blob/main/CONTRIBUTING.md).
## License
MIT