Generate SDK from OpenAPI specifications

[nastassiafulconis]

Summary

This PR implements automatic SDK generation from OpenAPI specifications, eliminating manual code maintenance and ensuring the SDK stays in sync with the API.

What Changed

New Features:

• ✅ Separate PlatformClient (for brand advertisers/buyers) and PartnerClient (for DSPs/publishers/partners)
• ✅ Custom SDK generator (scripts/generate-sdk.ts) that reads OpenAPI YAML and generates MCP-compatible TypeScript resource classes
• ✅ Automated schema updates from agentic-api repository via GitHub Actions
• ✅ Daily automated workflow that downloads latest OpenAPI specs and creates PRs when changes detected

Breaking Changes:

• Removed all manual resource files (src/resources/*.ts) - now fully auto-generated
• Removed SimpleMediaAgent (confirmed not in use)
• Scope3AgenticClient now extends PlatformClient for backwards compatibility

Technical Details:

• Generated clients have 26 resource groups with 90+ typed operations
• Full TypeScript type safety with openapi-typescript
• All methods properly call MCP tools via callTool()
• Supports both production and staging environments

Testing

✅ All 84 tests passing
✅ Verified with real API calls to production:

• PlatformClient: Successfully retrieved 141 brand agents
• PartnerClient: Successfully retrieved 12 channels
• Both clients confirmed working end-to-end

Commands

npm run generate-sdk              # Generate SDK from OpenAPI specs
npm run generate-all              # Generate types + SDK
npm run update-schemas            # Download latest specs + regenerate (needs GITHUB_TOKEN)

Migration Guide

For Platform/Buyer users:

// New (recommended)
import { PlatformClient } from 'scope3';
const client = new PlatformClient({ apiKey: '...' });

// Old (still works - backwards compatible)
import { Scope3AgenticClient } from 'scope3';
const client = new Scope3AgenticClient({ apiKey: '...' });

For Partner/DSP users:

import { PartnerClient } from 'scope3';
const client = new PartnerClient({ apiKey: '...' });

GitHub Actions Setup

The automated update workflow uses your existing PAT_TOKEN secret - no additional configuration needed. It will:

1. Run daily at 2 AM UTC (or on-demand via workflow_dispatch)
2. Download latest OpenAPI specs from agentic-api repo
3. Regenerate types and SDK
4. Create PR if changes detected

---

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[nastassiafulconis]

Updated: Separate Token Support

Added support for a dedicated AGENTIC_API_TOKEN secret specifically for downloading OpenAPI specs from the private agentic-api repository.

Setup Instructions:

1. Create a fine-grained PAT with:

   • Repository access: scope3data/agentic-api (read-only)
   • Permissions: Contents: Read

2. Add it as a repository secret named AGENTIC_API_TOKEN

Token Priorities:

AGENTIC_API_TOKEN (recommended) → PAT_TOKEN → GITHUB_TOKEN

This keeps your broader PAT_TOKEN separate from the schema download token.

[nastassiafulconis]

Update: Legacy Client Removed

Per feedback, I've removed all backwards compatibility code:

Changes in Latest Commits:

• ✅ Deleted src/sdk.ts containing Scope3AgenticClient
• ✅ Updated src/index.ts to only export PlatformClient and PartnerClient
• ✅ Updated all examples, tests, and CLI to use PlatformClient
• ✅ Updated README to remove legacy client documentation
• ✅ Added major version changeset with migration guide

Breaking Change:

Scope3AgenticClient has been completely removed. Users must migrate to either:

• PlatformClient - for brand advertisers/buyers
• PartnerClient - for DSPs/publishers/partners

Testing:

✅ All 84 tests passing
✅ Lint, build, and test workflows successful

This is now a clean, purpose-driven API with no legacy code.

[nastassiafulconis]

✅ All CI Checks Passing

All workflows are now green:

• ✅ Format Check
• ✅ Lint
• ✅ Type Check
• ✅ Build
• ✅ Test (84 tests passing)
• ✅ Changeset included (major version bump with migration guide)

Ready for review and merge!

Summary of Final State:

• Legacy Scope3AgenticClient completely removed
• Clean separation between PlatformClient and PartnerClient
• All examples, tests, and docs updated
• Breaking change properly documented with migration guide
• Production-ready code with no TODOs or unnecessary comments