@antseed/provider-claude-oauth 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# @antseed/provider-claude-oauth
+
+Third-party Anthropic Claude provider plugin with OAuth authentication for Antseed.
+
+This plugin demonstrates how a third-party developer can build, test, and publish an Antseed provider plugin using `@antseed/provider-core`.
+
+## How to Create a Plugin
+
+1. Create a new directory under `plugins/` (or anywhere on disk).
+2. Add a `package.json` with `@antseed/provider-core` as a dependency and `@antseed/node` as a peer dependency.
+3. Implement and default-export an `AntseedProviderPlugin` object from `src/index.ts`.
+4. Build with `tsc` and test with `vitest`.
+
+## Plugin Manifest Format
+
+Every provider plugin must default-export an object satisfying `AntseedProviderPlugin`:
+
+```typescript
+import type { AntseedProviderPlugin, ConfigField } from '@antseed/node';
+
+const plugin: AntseedProviderPlugin = {
+  name: 'my-provider',           // unique plugin name
+  displayName: 'My Provider',    // human-readable label
+  version: '0.1.0',
+  type: 'provider',
+  description: 'Description of the provider',
+  configSchema: [                // fields the user fills in
+    { key: 'API_KEY', label: 'API Key', type: 'secret', required: true },
+  ],
+  createProvider(config) {
+    // Return a Provider instance
+  },
+};
+export default plugin;
+```
+
+### ConfigField Types
+
+| Type       | Description                        |
+| ---------- | ---------------------------------- |
+| `string`   | Plain text input                   |
+| `number`   | Numeric input                      |
+| `boolean`  | Toggle / checkbox                  |
+| `secret`   | Masked input (tokens, keys)        |
+| `string[]` | Comma-separated list of strings    |
+
+## Using provider-core
+
+The `@antseed/provider-core` package provides reusable building blocks:
+
+- **`BaseProvider`** -- Implements the `Provider` interface and wires up `HttpRelay`.
+- **`StaticTokenProvider`** -- Wraps a static API key with no refresh logic.
+- **`OAuthTokenProvider`** -- Manages OAuth access/refresh token pairs with automatic renewal.
+- **`HttpRelay`** -- Forwards requests to an upstream API with auth header swapping, model validation, and concurrency control.
+
+```typescript
+import { BaseProvider, OAuthTokenProvider, StaticTokenProvider } from '@antseed/provider-core';
+```
+
+## Testing Locally
+
+```bash
+# Install dependencies
+npm install
+
+# Build the plugin
+npm run build
+
+# Run tests
+npm test
+```
+
+To test the plugin end-to-end with a local Antseed node, link it:
+
+```bash
+cd plugins/provider-claude-oauth
+npm link
+
+cd /path/to/your/antseed-project
+npm link @anthropic/provider-claude-oauth
+```
+
+Then configure the plugin in your node's plugin config with the required config fields.
+
+## Publishing to npm
+
+1. Ensure `package.json` has the correct `name`, `version`, and `description`.
+2. Build the plugin: `npm run build`
+3. Login to npm: `npm login`
+4. Publish: `npm publish --access public`
+
+For scoped packages like `@anthropic/provider-claude-oauth`, use `--access public` to publish as a public package.
+
+## Installing via antseed plugin add
+
+Once published, users can install the plugin:
+
+```bash
+antseed plugin add @anthropic/provider-claude-oauth
+```
+
+This will download the plugin from npm, register it with the local Antseed node, and prompt the user to configure the required fields (access token, etc.).
+
+## Configuration Reference
+
+| Key                            | Type     | Required | Default | Description                          |
+| ------------------------------ | -------- | -------- | ------- | ------------------------------------ |
+| `CLAUDE_ACCESS_TOKEN`          | secret   | Yes      | --      | Claude OAuth access token            |
+| `CLAUDE_REFRESH_TOKEN`         | secret   | No       | --      | OAuth refresh token for auto-renewal |
+| `CLAUDE_TOKEN_EXPIRES_AT`      | number   | No       | --      | Epoch ms when access token expires   |
+| `ANTSEED_INPUT_USD_PER_MILLION`| number   | No       | 10      | Input token price (USD per 1M)       |
+| `ANTSEED_OUTPUT_USD_PER_MILLION`| number  | No       | 10      | Output token price (USD per 1M)      |
+| `ANTSEED_MAX_CONCURRENCY`      | number   | No       | 5       | Max concurrent requests              |
+| `ANTSEED_ALLOWED_MODELS`       | string[] | No       | --      | Comma-separated list of model IDs    |
+
+## License
+
+See the root repository LICENSE file.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { AntseedProviderPlugin } from '@antseed/node';
+declare const plugin: AntseedProviderPlugin;
+export default plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAe,MAAM,eAAe,CAAC;AAaxE,QAAA,MAAM,MAAM,EAAE,qBAoDb,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/index.js

@@ -0,0 +1,62 @@
+import { BaseProvider, OAuthTokenProvider, StaticTokenProvider } from '@antseed/provider-core';
+const configSchema = [
+    { key: 'CLAUDE_ACCESS_TOKEN', label: 'Access Token', type: 'secret', required: true, description: 'Claude OAuth access token' },
+    { key: 'CLAUDE_REFRESH_TOKEN', label: 'Refresh Token', type: 'secret', required: false, description: 'OAuth refresh token for auto-renewal' },
+    { key: 'CLAUDE_TOKEN_EXPIRES_AT', label: 'Token Expiry', type: 'number', required: false, description: 'Epoch ms when access token expires' },
+    { key: 'ANTSEED_INPUT_USD_PER_MILLION', label: 'Input Price', type: 'number', required: false, default: 10 },
+    { key: 'ANTSEED_OUTPUT_USD_PER_MILLION', label: 'Output Price', type: 'number', required: false, default: 10 },
+    { key: 'ANTSEED_MAX_CONCURRENCY', label: 'Max Concurrency', type: 'number', required: false, default: 5 },
+    { key: 'ANTSEED_ALLOWED_MODELS', label: 'Allowed Models', type: 'string[]', required: false },
+];
+const plugin = {
+    name: 'claude-oauth',
+    displayName: 'Claude (OAuth)',
+    version: '0.1.0',
+    type: 'provider',
+    description: 'Anthropic Claude with OAuth authentication (third-party example)',
+    configSchema,
+    configKeys: configSchema,
+    createProvider(config) {
+        const accessToken = config['CLAUDE_ACCESS_TOKEN'];
+        if (!accessToken)
+            throw new Error('CLAUDE_ACCESS_TOKEN is required');
+        const refreshToken = config['CLAUDE_REFRESH_TOKEN'];
+        const expiresAt = config['CLAUDE_TOKEN_EXPIRES_AT']
+            ? parseInt(config['CLAUDE_TOKEN_EXPIRES_AT'], 10)
+            : undefined;
+        const tokenProvider = refreshToken
+            ? new OAuthTokenProvider({
+                accessToken,
+                refreshToken,
+                expiresAt: expiresAt ?? Date.now() + 3600_000,
+                tokenEndpoint: 'https://console.anthropic.com/v1/oauth/token',
+            })
+            : new StaticTokenProvider(accessToken);
+        const inputPrice = parseFloat(config['ANTSEED_INPUT_USD_PER_MILLION'] ?? '10');
+        const outputPrice = parseFloat(config['ANTSEED_OUTPUT_USD_PER_MILLION'] ?? '10');
+        const maxConcurrency = parseInt(config['ANTSEED_MAX_CONCURRENCY'] ?? '5', 10);
+        const allowedModels = (config['ANTSEED_ALLOWED_MODELS'] ?? '')
+            .split(',').map(s => s.trim()).filter(Boolean);
+        return new BaseProvider({
+            name: 'claude-oauth',
+            models: allowedModels,
+            pricing: {
+                defaults: {
+                    inputUsdPerMillion: inputPrice,
+                    outputUsdPerMillion: outputPrice,
+                },
+            },
+            relay: {
+                baseUrl: 'https://api.anthropic.com',
+                authHeaderName: 'authorization',
+                authHeaderValue: `Bearer ${accessToken}`,
+                tokenProvider,
+                extraHeaders: { 'anthropic-beta': 'oauth-2025-04-20' },
+                maxConcurrency,
+                allowedModels,
+            },
+        });
+    },
+};
+export default plugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@antseed/provider-claude-oauth",
+  "version": "0.1.0",
+  "description": "Third-party Anthropic Claude provider with OAuth authentication",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@antseed/provider-core": "workspace:*"
+  },
+  "peerDependencies": {
+    "@antseed/node": ">=0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "@antseed/node": "workspace:*"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest';
+import plugin from './index.js';
+
+describe('provider-claude-oauth plugin manifest', () => {
+  it('has correct plugin metadata', () => {
+    expect(plugin.name).toBe('claude-oauth');
+    expect(plugin.displayName).toBe('Claude (OAuth)');
+    expect(plugin.version).toBe('0.1.0');
+    expect(plugin.type).toBe('provider');
+    expect(plugin.description).toBe('Anthropic Claude with OAuth authentication (third-party example)');
+  });
+
+  it('exposes configSchema with required fields', () => {
+    expect(plugin.configSchema).toBeDefined();
+    const keys = plugin.configSchema!.map(f => f.key);
+    expect(keys).toContain('CLAUDE_ACCESS_TOKEN');
+    expect(keys).toContain('CLAUDE_REFRESH_TOKEN');
+    expect(keys).toContain('CLAUDE_TOKEN_EXPIRES_AT');
+    expect(keys).toContain('ANTSEED_INPUT_USD_PER_MILLION');
+    expect(keys).toContain('ANTSEED_OUTPUT_USD_PER_MILLION');
+    expect(keys).toContain('ANTSEED_MAX_CONCURRENCY');
+    expect(keys).toContain('ANTSEED_ALLOWED_MODELS');
+    const accessField = plugin.configSchema!.find(f => f.key === 'CLAUDE_ACCESS_TOKEN');
+    expect(accessField!.required).toBe(true);
+    expect(accessField!.type).toBe('secret');
+  });
+});
+
+describe('createProvider', () => {
+  it('creates provider with access token only (static)', () => {
+    const provider = plugin.createProvider({
+      CLAUDE_ACCESS_TOKEN: 'test-access-token',
+    });
+    expect(provider).toBeDefined();
+    expect(provider.name).toBe('claude-oauth');
+    expect(provider.maxConcurrency).toBe(5);
+  });
+
+  it('creates provider with access + refresh token (OAuth)', () => {
+    const provider = plugin.createProvider({
+      CLAUDE_ACCESS_TOKEN: 'test-access-token',
+      CLAUDE_REFRESH_TOKEN: 'test-refresh-token',
+      CLAUDE_TOKEN_EXPIRES_AT: String(Date.now() + 3600_000),
+    });
+    expect(provider).toBeDefined();
+    expect(provider.name).toBe('claude-oauth');
+  });
+
+  it('rejects missing access token', () => {
+    expect(() => plugin.createProvider({})).toThrow('CLAUDE_ACCESS_TOKEN is required');
+  });
+
+  it('provider has correct name and pricing', () => {
+    const provider = plugin.createProvider({
+      CLAUDE_ACCESS_TOKEN: 'test-access-token',
+      ANTSEED_INPUT_USD_PER_MILLION: '15',
+      ANTSEED_OUTPUT_USD_PER_MILLION: '30',
+      ANTSEED_MAX_CONCURRENCY: '3',
+    });
+    expect(provider.name).toBe('claude-oauth');
+    expect(provider.pricing).toEqual({
+      defaults: {
+        inputUsdPerMillion: 15,
+        outputUsdPerMillion: 30,
+      },
+    });
+    expect(provider.maxConcurrency).toBe(3);
+  });
+});

package/src/index.ts

@@ -0,0 +1,68 @@
+import type { AntseedProviderPlugin, ConfigField } from '@antseed/node';
+import { BaseProvider, OAuthTokenProvider, StaticTokenProvider } from '@antseed/provider-core';
+
+const configSchema: ConfigField[] = [
+  { key: 'CLAUDE_ACCESS_TOKEN', label: 'Access Token', type: 'secret', required: true, description: 'Claude OAuth access token' },
+  { key: 'CLAUDE_REFRESH_TOKEN', label: 'Refresh Token', type: 'secret', required: false, description: 'OAuth refresh token for auto-renewal' },
+  { key: 'CLAUDE_TOKEN_EXPIRES_AT', label: 'Token Expiry', type: 'number', required: false, description: 'Epoch ms when access token expires' },
+  { key: 'ANTSEED_INPUT_USD_PER_MILLION', label: 'Input Price', type: 'number', required: false, default: 10 },
+  { key: 'ANTSEED_OUTPUT_USD_PER_MILLION', label: 'Output Price', type: 'number', required: false, default: 10 },
+  { key: 'ANTSEED_MAX_CONCURRENCY', label: 'Max Concurrency', type: 'number', required: false, default: 5 },
+  { key: 'ANTSEED_ALLOWED_MODELS', label: 'Allowed Models', type: 'string[]', required: false },
+];
+
+const plugin: AntseedProviderPlugin = {
+  name: 'claude-oauth',
+  displayName: 'Claude (OAuth)',
+  version: '0.1.0',
+  type: 'provider',
+  description: 'Anthropic Claude with OAuth authentication (third-party example)',
+  configSchema,
+  configKeys: configSchema,
+  createProvider(config: Record<string, string>) {
+    const accessToken = config['CLAUDE_ACCESS_TOKEN'];
+    if (!accessToken) throw new Error('CLAUDE_ACCESS_TOKEN is required');
+
+    const refreshToken = config['CLAUDE_REFRESH_TOKEN'];
+    const expiresAt = config['CLAUDE_TOKEN_EXPIRES_AT']
+      ? parseInt(config['CLAUDE_TOKEN_EXPIRES_AT'], 10)
+      : undefined;
+
+    const tokenProvider = refreshToken
+      ? new OAuthTokenProvider({
+          accessToken,
+          refreshToken,
+          expiresAt: expiresAt ?? Date.now() + 3600_000,
+          tokenEndpoint: 'https://console.anthropic.com/v1/oauth/token',
+        })
+      : new StaticTokenProvider(accessToken);
+
+    const inputPrice = parseFloat(config['ANTSEED_INPUT_USD_PER_MILLION'] ?? '10');
+    const outputPrice = parseFloat(config['ANTSEED_OUTPUT_USD_PER_MILLION'] ?? '10');
+    const maxConcurrency = parseInt(config['ANTSEED_MAX_CONCURRENCY'] ?? '5', 10);
+    const allowedModels = (config['ANTSEED_ALLOWED_MODELS'] ?? '')
+      .split(',').map(s => s.trim()).filter(Boolean);
+
+    return new BaseProvider({
+      name: 'claude-oauth',
+      models: allowedModels,
+      pricing: {
+        defaults: {
+          inputUsdPerMillion: inputPrice,
+          outputUsdPerMillion: outputPrice,
+        },
+      },
+      relay: {
+        baseUrl: 'https://api.anthropic.com',
+        authHeaderName: 'authorization',
+        authHeaderValue: `Bearer ${accessToken}`,
+        tokenProvider,
+        extraHeaders: { 'anthropic-beta': 'oauth-2025-04-20' },
+        maxConcurrency,
+        allowedModels,
+      },
+    });
+  },
+};
+
+export default plugin;

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
+}