npm package: @scope3/agentic-client
Description: TypeScript client for the Scope3 Agentic API with AdCP webhook support
Latest version: 1.0.4

# Scope3 Agentic Client

TypeScript client for the Scope3 Agentic API with AdCP webhook support.

## Features

- 🚀 Full TypeScript support with generated types from OpenAPI schema
- 📦 Complete API coverage for all Scope3 MCP tools
- 🔐 Bearer token authentication
- 🔌 Official MCP SDK (`@modelcontextprotocol/sdk`) with HTTP streaming transport
- 🪝 Optional webhook server for AdCP events
- ✨ Clean, intuitive API design
- 🧪 Comprehensive test coverage

**Architecture:** This client uses the official `@modelcontextprotocol/sdk` to connect to the Scope3 MCP server at `https://api.agentic.scope3.com/mcp` via Streamable HTTP transport. This uses HTTP POST for sending messages and HTTP GET with Server-Sent Events for receiving messages, providing reliable bidirectional communication with automatic reconnection support.

## Installation

```bash
npm install @scope3/agentic-client
```

## Quick Start

```typescript
import { Scope3AgenticClient } from '@scope3/agentic-client';

const client = new Scope3AgenticClient({
  apiKey: process.env.SCOPE3_API_KEY,
});

// List brand agents
const brandAgents = await client.brandAgents.list();

// Create a campaign
const campaign = await client.campaigns.create({
  prompt: 'Create a video campaign targeting tech enthusiasts',
  budget: {
    amount: 5000000, // $50,000 in cents
    currency: 'USD',
    pacing: 'even',
  },
});
```

## Configuration

```typescript
const client = new Scope3AgenticClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.agentic.scope3.com', // optional, defaults to production
  timeout: 30000, // optional, request timeout in ms
});
```

## API Resources

The client provides access to all Scope3 API resources:

### Assets
```typescript
await client.assets.upload({ brandAgentId, assets: [...] });
await client.assets.list({ brandAgentId });
```

### Brand Agents
```typescript
await client.brandAgents.list();
await client.brandAgents.create({ name: 'My Brand' });
await client.brandAgents.get({ brandAgentId });
await client.brandAgents.update({ brandAgentId, name: 'Updated Name' });
await client.brandAgents.delete({ brandAgentId });
```

### Campaigns
```typescript
await client.campaigns.list({ status: 'ACTIVE' });
await client.campaigns.create({ prompt: '...', budget: {...} });
await client.campaigns.update({ campaignId, status: 'PAUSED' });
await client.campaigns.getSummary({ campaignId });
await client.campaigns.listTactics({ campaignId });
await client.campaigns.delete({ campaignId });
```

### Creatives
```typescript
await client.creatives.list({ brandAgentId });
await client.creatives.create({ brandAgentId, name: '...' });
await client.creatives.assign({ creativeId, campaignId });
```

### Tactics
```typescript
await client.tactics.list({ campaignId });
await client.tactics.create({ name: '...', campaignId });
await client.tactics.update({ tacticId, channelCodes: ['DIGITAL-AUDIO'] });
```

### Media Buys
```typescript
await client.mediaBuys.list({ tacticId });
await client.mediaBuys.create({
  tacticId,
  name: '...',
  products: [{ mediaProductId, salesAgentId }],
  budget: { amount: 1000000 },
});
await client.mediaBuys.execute({ mediaBuyId });
```

### Agents
```typescript
// List all agents (sales and outcome)
await client.agents.list();
await client.agents.list({ type: 'SALES' });
await client.agents.list({ type: 'OUTCOME' });

// Register a new agent
await client.agents.register({
  type: 'SALES',
  name: '...',
  endpointUrl: '...',
  protocol: 'MCP',
  authenticationType: 'API_KEY',
});

// Get agent details
await client.agents.get({ agentId: '...' });

// Update agent
await client.agents.update({
  agentId: '...',
  name: 'Updated Name',
});

// Unregister agent
await client.agents.unregister({ agentId: '...' });
```

### Other Resources
- `client.brandStandards` - Brand safety standards
- `client.brandStories` - AI-powered audience definitions
- `client.channels` - Advertising channels
- `client.notifications` - System notifications
- `client.products` - Media product management

## Webhook Server

The client includes an optional webhook server for handling AdCP events:

```typescript
import { WebhookServer } from '@scope3/agentic-client';

const webhookServer = new WebhookServer({
  port: 3000,
  path: '/webhooks',
  secret: process.env.WEBHOOK_SECRET, // optional
});

// Register event handlers
webhookServer.on('campaign.created', async (event) => {
  console.log('Campaign created:', event.data);
});

webhookServer.on('media_buy.executed', async (event) => {
  console.log('Media buy executed:', event.data);
});

// Catch all events
webhookServer.on('*', async (event) => {
  console.log('Event received:', event.type);
});

// Start the server
await webhookServer.start();
console.log(`Webhook server running at ${webhookServer.getUrl()}`);

// Stop the server
await webhookServer.stop();
```

## Development

```bash
# Install dependencies
npm install

# Update schemas from upstream (downloads latest OpenAPI spec)
npm run update-schemas

# Type check without building
npm run type-check

# Build the project (includes type checking)
npm run build

# Run tests (includes pre-test type checking)
npm test

# Run linter
npm run lint

# Format code
npm run format

# Generate types from local OpenAPI spec
npm run generate-types
```

### Type Safety

This client is **fully typed** with no `any` types:

- **Generated types** from OpenAPI spec using `openapi-typescript`
- **Strict TypeScript** configuration enabled
- **Pre-commit hooks** via Husky that run:
  - Type checking (`tsc --noEmit`)
  - Linting with auto-fix
  - Code formatting
- **CI validation** on every PR:
  - Type checking
  - Linting
  - Format checking
  - Test execution
  - Build verification

To update types when the upstream API changes:
```bash
npm run update-schemas
```

This downloads the latest OpenAPI spec and regenerates TypeScript types.

## Contributing

### Versioning and Releases

This project uses [Changesets](https://github.com/changesets/changesets) for version management and automated NPM publishing.

#### Creating a Changeset

When making changes that should be released, add a changeset:

```bash
npm run changeset
```

Follow the prompts to:
1. Select the type of change (major, minor, patch)
2. Describe the changes for the changelog

The changeset file will be committed with your PR.

#### Release Process

When a PR with changesets is merged to `main`:
1. The Release workflow creates a "Version Packages" PR
2. This PR updates package versions and generates changelogs
3. When the Version PR is merged, packages are automatically published to NPM

**NPM Publishing:** Packages are published as `@scope3/agentic-client` with public access.

#### CI Requirements

Every PR to `main` must include a changeset. The CI will fail if no changeset is detected.

To bypass this check (for docs/config changes), create an empty changeset:
```bash
npm run changeset
# Select "patch" and leave the description empty
```

## Examples

See the `examples/` directory for more usage examples:
- `basic-usage.ts` - Basic API usage
- `create-campaign.ts` - Campaign creation workflow
- `webhook-server.ts` - Webhook server setup

## License

MIT