scope3

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
• 💻 CLI tool for all API resources (80+ commands)

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

npm install scope3

Quick Start

import { Scope3AgenticClient } from 'scope3';

const client = new Scope3AgenticClient({
  apiKey: process.env.SCOPE3_API_KEY,
  // Optional: specify environment (defaults to 'production')
  environment: 'production', // or 'staging'
});

// 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',
  },
});

CLI Usage

The CLI dynamically discovers available commands from the API server, ensuring it's always up-to-date.

Quick Start

# Use with npx (no install needed)
npx scope3 --help

# Or install globally
npm install -g scope3
scope3 --help

# Configure authentication
scope3 config set apiKey your_api_key_here

# Configure environment (optional - defaults to production)
scope3 config set environment staging

# Or use environment variables
export SCOPE3_API_KEY=your_api_key_here
export SCOPE3_ENVIRONMENT=staging  # or 'production'

# Or use command-line flags
scope3 --environment staging list-tools

# Discover available commands (80+ auto-generated)
scope3 list-tools

# Examples
scope3 brand-agent list
scope3 campaign create --prompt "Q1 2024 Spring Campaign" --brandAgentId 123
scope3 media-buy execute --mediaBuyId "buy_123"

# Switch environments on the fly
scope3 --environment production campaign list
scope3 --environment staging campaign list

Dynamic Updates: Commands automatically stay in sync with API changes. No manual updates needed!

SDK Configuration

const client = new Scope3AgenticClient({
  apiKey: 'your-api-key',

  // Option 1: Use environment (recommended)
  environment: 'production', // 'production' or 'staging' (default: 'production')

  // Option 2: Use custom base URL (overrides environment)
  baseUrl: 'https://custom-api.example.com',

  // Optional settings
  timeout: 30000, // request timeout in ms
});

Environment URLs

• Production: https://api.agentic.scope3.com
• Staging: https://api.agentic.staging.scope3.com

API Resources

The client provides access to all Scope3 API resources:

Assets

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

Brand Agents

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

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

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

Tactics

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

Media Buys

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

Agents

// 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:

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

# 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:

npm run update-schemas

This downloads the latest OpenAPI spec and regenerates TypeScript types.

Contributing

Versioning and Releases

This project uses Changesets for version management and automated NPM publishing.

Creating a Changeset

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

npm run changeset

Follow the prompts to:

• Select the type of change (major, minor, patch)
• 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:

• The Release workflow creates a "Version Packages" PR
• This PR updates package versions and generates changelogs
• 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:

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