npm package: @tab-platform/sdk
Description: Official TypeScript/Node SDK for TAB Platform — The Verification Layer for AI Agents
Author: TAB Platform LLC
Latest version: 1.0.0

# @tab-platform/sdk

**Official TypeScript/Node SDK for [TAB Platform](https://tabverified.ai) — The Verification Layer for AI Agents**

[![npm version](https://img.shields.io/npm/v/@tab-platform/sdk)](https://www.npmjs.com/package/@tab-platform/sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node 18+](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org/)

## Install

```bash
npm install @tab-platform/sdk
```

## Quick Start

```typescript
import { TABClient } from '@tab-platform/sdk';

const tab = new TABClient({ apiKey: 'pk_live_xxx' });

// Run benchmarks against your agent
const result = await tab.benchmarks.run({
  agentId: 'your-agent-uuid',
  benchmarkSlugs: ['data-exfiltration', 'safety-refusal'],
  maxSpend: 3.00,
});
console.log(`Score: ${result.overall_score}/100`);
console.log(`Trust Seal: ${result.trust_seal_grade}`);
```

## Authentication

### API Key (recommended)

```typescript
// Pass directly
const tab = new TABClient({ apiKey: 'pk_live_xxx' });

// Or set environment variable
// export TAB_API_KEY=pk_live_xxx
const tab = new TABClient(); // auto-reads TAB_API_KEY
```

### Username/Password

```typescript
const tab = new TABClient({ baseUrl: 'https://tabverified.ai' });
await tab.auth.login({ username: 'dev@company.com', password: 'xxx' });
```

## Core Operations

### Agents

```typescript
// List your agents
const agents = await tab.agents.list();

// Create an agent
const agent = await tab.agents.create({
  name: 'My Agent',
  description: 'Does amazing things',
  agentType: 'general',
  tags: ['coding', 'analysis'],
});

// Get agent details
const agent = await tab.agents.get('agent-uuid');

// Update an agent
const updated = await tab.agents.update('agent-uuid', { name: 'New Name' });

// Delete an agent
await tab.agents.delete('agent-uuid');

// Publish to marketplace
await tab.agents.publish('agent-uuid');
```

### Benchmarks

```typescript
// List available benchmarks
const benchmarks = await tab.benchmarks.list();

// List categories
const categories = await tab.benchmarks.categories();

// Run benchmarks
const result = await tab.benchmarks.run({
  agentId: 'agent-uuid',
  benchmarkSlugs: ['swe-bench-pro', 'data-exfiltration'],
  model: 'claude-sonnet-4-20250514',
  maxSpend: 5.00,
});

// Get all your results
const results = await tab.benchmarks.results();

// Get a specific result
const result = await tab.benchmarks.result('result-uuid');
```

### Verification (the Equifax for AI agents)

```typescript
// Check verification status
const v = await tab.verification.check('agent-uuid');
console.log(`Verified: ${v.is_verified}`);
console.log(`Grade: ${v.trust_seal_grade}`);
console.log(`Health: ${v.health_score}`);

// Get full verification report
const report = await tab.verification.report('agent-uuid');
```

### Marketplace

```typescript
// Browse verified agents
const agents = await tab.marketplace.list();

// Get agent details with Trust Seal
const agent = await tab.marketplace.get('agent-uuid');

// View leaderboard
const leaderboard = await tab.marketplace.leaderboard();
```

### Credits

```typescript
// Check balance
const balance = await tab.credits.balance();
console.log(`Balance: ${balance.balance}`);

// View transaction history
const transactions = await tab.credits.transactions();

// Purchase credits (returns Stripe checkout URL)
const purchase = await tab.credits.purchase({ amount: 20.00 });
console.log(`Checkout: ${purchase.checkout_url}`);
```

### Models

```typescript
// List available models
const models = await tab.models.list();

// List providers
const providers = await tab.models.providers();
```

### Harnesses

```typescript
// List all harnesses
const harnesses = await tab.harnesses.list();

// Get harnesses for an agent
const agentHarnesses = await tab.harnesses.getForAgent('agent-uuid');

// Update agent harnesses
await tab.harnesses.updateForAgent('agent-uuid', ['h1', 'h2']);
```

### Webhooks

```typescript
// List webhooks
const webhooks = await tab.webhooks.list();

// Create webhook
const webhook = await tab.webhooks.create({
  url: 'https://example.com/webhook',
  events: ['benchmark.completed', 'agent.verified'],
});

// Delete webhook
await tab.webhooks.delete('webhook-uuid');
```

## CI/CD Integration

### GitHub Actions

```yaml
# .github/workflows/agent-verify.yml
name: TAB Agent Verification
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install @tab-platform/sdk
      - name: Run TAB Benchmarks
        env:
          TAB_API_KEY: ${{ secrets.TAB_API_KEY }}
        run: |
          node -e "
          const { TABClient } = require('@tab-platform/sdk');
          (async () => {
            const tab = new TABClient();
            const result = await tab.benchmarks.run({
              agentId: '${{ vars.TAB_AGENT_ID }}',
              benchmarkSlugs: ['data-exfiltration', 'safety-refusal', 'prompt-injection'],
              maxSpend: 3.00,
            });
            console.log('TAB Score: ' + result.overall_score + '/100');
            console.log('Trust Seal: ' + result.trust_seal_grade);
            if (result.overall_score < 70) {
              console.error('FAILED: Agent does not meet minimum verification threshold');
              process.exit(1);
            }
            console.log('PASSED: Agent verified by TAB');
          })();
          "
```

## Error Handling

```typescript
import { TABClient, TABInsufficientCreditsError, TABAuthError, TABRateLimitError, TABError } from '@tab-platform/sdk';

try {
  const result = await tab.benchmarks.run({
    agentId: 'uuid',
    benchmarkSlugs: ['swe-bench'],
    maxSpend: 1.00,
  });
} catch (e) {
  if (e instanceof TABInsufficientCreditsError) {
    console.log('Not enough credits — purchase more at tabverified.ai');
  } else if (e instanceof TABAuthError) {
    console.log('Invalid API key or session expired');
  } else if (e instanceof TABRateLimitError) {
    console.log(`Rate limited — retry after ${e.retryAfter}s`);
  } else if (e instanceof TABError) {
    console.log(`API error: ${e.message} (${e.statusCode})`);
  }
}
```

All errors include `statusCode`, `url`, and `body` properties for debugging.

## Type Reference

All request/response types are exported as TypeScript interfaces:

- `Agent`, `AgentCreateParams`, `AgentUpdateParams`
- `BenchmarkInfo`, `BenchmarkResult`, `BenchmarkRunParams`, `BenchmarkCategory`
- `MarketplaceAgent`, `LeaderboardEntry`
- `VerificationStatus`, `VerificationReport`
- `CreditBalance`, `CreditTransaction`, `PurchaseResponse`
- `ModelInfo`, `ProviderInfo`
- `Harness`, `Webhook`
- `User`, `AuthToken`

## API Reference

Full API documentation: [tabverified.ai/static/api-docs.html](https://tabverified.ai/static/api-docs.html)

## License

MIT — see [LICENSE](LICENSE)