scope3

Scope3 SDK

TypeScript client for the Scope3 Agentic Platform. Supports two personas (buyer, partner) with REST and MCP adapters.

Installation

npm install scope3

API Keys

Obtain your API key from the Scope3 dashboard:

• Production: https://agentic.scope3.com -> Manage API Keys
• Staging: https://agentic.staging.scope3.com -> Manage API Keys

Environment URLs

Environment	URL
Production	https://api.agentic.scope3.com
Staging	https://api.agentic.staging.scope3.com

Quick Start

The SDK uses a unified Scope3Client with a persona parameter to determine available resources.

Buyer Persona

For programmatic advertising -- manage advertisers, bundles, campaigns, and signals.

import { Scope3Client } from 'scope3';

const client = new Scope3Client({
  apiKey: process.env.SCOPE3_API_KEY!,
  persona: 'buyer',
});

// List advertisers
const advertisers = await client.advertisers.list();

// Create a bundle for inventory discovery
const bundle = await client.bundles.create({
  advertiserId: 'adv-123',
  channels: ['display', 'video'],
});

// Discover products in the bundle
const products = await client.bundles.discoverProducts(bundle.data.bundleId);

// Add products to the bundle
await client.bundles.products(bundle.data.bundleId).add({
  products: [{ productId: 'prod-1', salesAgentId: 'sa-1', groupId: 'g-1', groupName: 'Group 1' }],
});

// Create and execute a discovery campaign
const campaign = await client.campaigns.createDiscovery({
  advertiserId: 'adv-123',
  bundleId: bundle.data.bundleId,
  name: 'Q1 Campaign',
  flightDates: { startDate: '2025-01-15', endDate: '2025-03-31' },
  budget: { total: 50000, currency: 'USD' },
});
await client.campaigns.execute(campaign.data.id);

Partner Persona

For partner and agent management.

const partnerClient = new Scope3Client({
  apiKey: process.env.SCOPE3_API_KEY!,
  persona: 'partner',
});

// List partners
const partners = await partnerClient.partners.list();

// Register an agent
const agent = await partnerClient.agents.register({
  name: 'My Agent',
  type: 'SALES',
  partnerId: 'partner-123',
});

Configuration

const client = new Scope3Client({
  apiKey: 'your-api-key',       // Required: Bearer token
  persona: 'buyer',              // Required: 'buyer' | 'partner'
  environment: 'production',     // Optional: 'production' (default) | 'staging'
  baseUrl: 'https://custom.com', // Optional: overrides environment
  adapter: 'rest',               // Optional: 'rest' (default) | 'mcp'
  timeout: 30000,                // Optional: request timeout in ms
  debug: false,                  // Optional: enable debug logging
});

CLI

# Configure
scope3 config set apiKey your_api_key_here
scope3 config set environment staging

# Use
scope3 advertisers list
scope3 advertisers get adv-123
scope3 campaigns list --format json
scope3 bundles create --advertiser-id adv-123 --channels display,video

# Override persona per-command
scope3 --persona partner partners list

# See all commands
scope3 commands

API Resources

Buyer Resources

• client.advertisers -- CRUD and sub-resources (conversionEvents, creativeSets, testCohorts)
• client.campaigns -- list, get, createDiscovery, updateDiscovery, createPerformance, updatePerformance, createAudience, execute, pause
• client.bundles -- create, discoverProducts, browseProducts, products(bundleId)
• client.signals -- Discover signals
• client.reporting -- Get reporting metrics
• client.salesAgents -- List sales agents, register accounts

Partner Resources

• client.partners -- list, create, update, archive
• client.agents -- list, get, register, update

skill.md Support

// Get parsed skill documentation
const skill = await client.getSkill();
console.log(skill.name, skill.version);
console.log(skill.commands); // Available API commands

Webhook Server

A WebhookServer class is available for handling AdCP events. See docs/getting-started.md for usage details.

Development

npm install
npm run type-check
npm run build
npm test
npm run lint

Updating the SDK When the API Changes

The SDK is manually maintained. When the Agentic API changes, update these files:

What changed	Files to update
Request/response shapes	src/types/index.ts
Endpoints added/removed	src/resources/ (the relevant resource class)
CLI commands	src/cli/commands/ (the relevant command file)
Bundled skill.md	src/skill/bundled.ts (copy from API response)

Steps:

• Check the latest skill.md for your persona:

  curl https://api.agentic.scope3.com/api/v2/buyer/skill.md
  curl https://api.agentic.scope3.com/api/v2/partner/skill.md
  

• Compare against src/skill/bundled.ts and update if needed
• Update types in src/types/index.ts to match any schema changes
• Update resource methods in src/resources/ for endpoint changes
• Update CLI commands in src/cli/commands/ if applicable
• Run npm test and npm run build to verify
• Run manual workflow tests: npm run test:buyer, npm run test:partner

Integration Tests

export SCOPE3_API_KEY=your_key
npm run test:buyer     # Buyer workflow
npm run test:partner   # Partner workflow
npm run test:all       # All workflows

Documentation

• Getting Started
• Buyer Guide
• Partner Guide
• CLI Reference

Contributing

This project uses Changesets for version management. When making changes that should be released, run npm run changeset and follow the prompts to describe your change. The changeset file is committed with your PR.

License

MIT