{"id":49307409,"url":"https://github.com/tokentopapp/plugin-sdk","last_synced_at":"2026-04-26T10:02:55.297Z","repository":{"id":338438219,"uuid":"1157870408","full_name":"tokentopapp/plugin-sdk","owner":"tokentopapp","description":"SDK for building tokentop plugins — type definitions, helpers, and test harness for providers, agents, themes, and notifications","archived":false,"fork":false,"pushed_at":"2026-04-17T00:03:15.000Z","size":116,"stargazers_count":0,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T02:14:01.223Z","etag":null,"topics":["ai","bun","developer-tools","plugin-sdk","plugin-system","sdk","tokentop","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/tokentopapp/tokentop","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tokentopapp.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-14T12:36:36.000Z","updated_at":"2026-04-06T23:00:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tokentopapp/plugin-sdk","commit_stats":null,"previous_names":["tokentopapp/plugin-sdk"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/tokentopapp/plugin-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokentopapp%2Fplugin-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokentopapp%2Fplugin-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokentopapp%2Fplugin-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokentopapp%2Fplugin-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tokentopapp","download_url":"https://codeload.github.com/tokentopapp/plugin-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tokentopapp%2Fplugin-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32292960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bun","developer-tools","plugin-sdk","plugin-system","sdk","tokentop","typescript"],"created_at":"2026-04-26T10:02:54.631Z","updated_at":"2026-04-26T10:02:55.282Z","avatar_url":"https://github.com/tokentopapp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @tokentop/plugin-sdk\n\n[![npm](https://img.shields.io/npm/v/@tokentop/plugin-sdk?style=flat-square\u0026color=CB3837\u0026logo=npm)](https://www.npmjs.com/package/@tokentop/plugin-sdk)\n[![CI](https://img.shields.io/github/actions/workflow/status/tokentopapp/plugin-sdk/ci.yml?style=flat-square\u0026label=CI)](https://github.com/tokentopapp/plugin-sdk/actions/workflows/ci.yml)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)\n\nSDK for building [tokentop](https://github.com/tokentopapp/tokentop) plugins. Types, helpers, and a test harness for provider, agent, theme, and notification plugins.\n\n## Install\n\n```bash\nbun add @tokentop/plugin-sdk\n```\n\n## Quick Example\n\n```typescript\nimport {\n  createProviderPlugin,\n  apiKeyCredential,\n  credentialFound,\n  credentialMissing,\n} from '@tokentop/plugin-sdk';\n\nexport default createProviderPlugin({\n  id: 'my-provider',\n  type: 'provider',\n  name: 'My Provider',\n  version: '1.0.0',\n  meta: { brandColor: '#3b82f6' },\n  permissions: {\n    network: { enabled: true, allowedDomains: ['api.example.com'] },\n    env: { read: true, vars: ['MY_API_KEY'] },\n  },\n  capabilities: {\n    usageLimits: false,\n    apiRateLimits: false,\n    tokenUsage: false,\n    actualCosts: true,\n  },\n  auth: {\n    async discover(ctx) {\n      const key = ctx.authSources.env.get('MY_API_KEY');\n      return key ? credentialFound(apiKeyCredential(key)) : credentialMissing();\n    },\n    isConfigured: (creds) =\u003e !!creds.apiKey,\n  },\n  async fetchUsage(ctx) {\n    const resp = await ctx.http.fetch('https://api.example.com/usage', {\n      headers: { Authorization: `Bearer ${ctx.credentials.apiKey}` },\n    });\n    const data = await resp.json();\n    return { fetchedAt: Date.now(), cost: { total: data.total, currency: 'USD', source: 'api' } };\n  },\n});\n```\n\n## Plugin Types\n\n| Type | Interface | Purpose |\n|------|-----------|---------|\n| `provider` | `ProviderPlugin` | Fetch usage data from AI model providers |\n| `agent` | `AgentPlugin` | Parse coding agent sessions for token tracking |\n| `theme` | `ThemePlugin` | Color schemes for the TUI |\n| `notification` | `NotificationPlugin` | Alert delivery (Slack, Discord, terminal bell) |\n\n## Subpath Exports\n\n| Import | Contents |\n|--------|----------|\n| `@tokentop/plugin-sdk` | Everything (types + helpers) |\n| `@tokentop/plugin-sdk/types` | Type definitions only |\n| `@tokentop/plugin-sdk/helpers` | `createPlugin` helpers, auth helpers, version utils |\n| `@tokentop/plugin-sdk/testing` | Test harness and mock factories |\n\n## Testing\n\nTest plugins without running tokentop:\n\n```typescript\nimport { createTestContext } from '@tokentop/plugin-sdk/testing';\nimport plugin from './src/index.ts';\n\nconst ctx = createTestContext({\n  env: { MY_API_KEY: 'test-key' },\n  httpMocks: {\n    'https://api.example.com/usage': {\n      status: 200,\n      body: { total: 4.50 },\n    },\n  },\n});\n\nconst creds = await plugin.auth.discover(ctx);\nassert(creds.ok);\n```\n\n## Naming Convention\n\n| Tier | Pattern | Example |\n|------|---------|---------|\n| Official | `@tokentop/{type}-\u003cname\u003e` | `@tokentop/agent-opencode` |\n| Community | `tokentop-{type}-\u003cname\u003e` | `tokentop-provider-replicate` |\n| Scoped community | `@scope/tokentop-{type}-\u003cname\u003e` | `@myname/tokentop-theme-catppuccin` |\n\n## Versioning\n\n| Version | What it is |\n|---------|------------|\n| SDK semver (`1.1.0`) | Package version on npm. Normal semver rules. |\n| `apiVersion` (`2`) | Plugin contract version. Core checks at load time. Bumped rarely. |\n\nUse `CURRENT_API_VERSION` and `isCompatible()` to check compatibility. The `createProviderPlugin()` / `createAgentPlugin()` / etc. helpers stamp `apiVersion` automatically.\n\n## Documentation\n\nSee [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.\n\n## Contributing\n\nSee the [Contributing Guide](https://github.com/tokentopapp/.github/blob/main/CONTRIBUTING.md).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokentopapp%2Fplugin-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftokentopapp%2Fplugin-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftokentopapp%2Fplugin-sdk/lists"}