X Ads SDK for TypeScript

A TypeScript SDK for the X Ads API, providing type-safe access to advertising campaigns, analytics, media management, and more.

Features

• 🔒 OAuth 1.0a Authentication - Secure authentication with X Ads API
• 📊 Analytics & Reporting - Comprehensive analytics with async job support
• 🎯 Campaign Management - Create, update, and manage advertising campaigns
• 📱 Media Management - Upload and manage media assets
• 🎨 Targeting Options - Advanced audience targeting capabilities
• 📈 Rate Limiting - Built-in rate limiting with exponential backoff
• 🛡️ Type Safety - Full TypeScript support with comprehensive type definitions
• 🌐 Runtime Agnostic - Works in browsers, Node.js, and edge environments
• 🧪 Well Tested - Comprehensive test coverage with contract and integration tests

Installation

npm install x-ads-sdk

Quick Start

import { XAdsClient } from 'x-ads-sdk';

// Initialize the client
const client = new XAdsClient({
  credentials: {
    consumerKey: 'your-consumer-key',
    consumerSecret: 'your-consumer-secret',
    accessToken: 'your-access-token',
    accessTokenSecret: 'your-access-token-secret',
  },
  environment: 'sandbox', // or 'production'
});

// Get advertising accounts
const accounts = await client.accounts.list();
console.log(`Found ${accounts.data.length} accounts`);

// Create a campaign
const campaign = await client.campaigns.create(accounts.data[0].id, {
  name: 'My First Campaign',
  funding_instrument_id: 'funding-instrument-id',
  entity_status: 'PAUSED',
  objective: 'AWARENESS',
  start_time: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
  daily_budget_amount_local_micro: 10000000, // $10 in micro currency
});

// Get campaign analytics
const analytics = await client.analytics.getStats(accounts.data[0].id, {
  entity: 'CAMPAIGN',
  entity_ids: [campaign.data.id],
  start_time: '2024-01-01T00:00:00Z',
  end_time: '2024-01-07T00:00:00Z',
  granularity: 'DAY',
  placement: 'ALL_ON_TWITTER',
  metrics: ['impressions', 'clicks', 'spend_micro'],
});

API Reference

Client Initialization

const client = new XAdsClient({
  credentials: {
    consumerKey: string;
    consumerSecret: string;
    accessToken: string;
    accessTokenSecret: string;
  },
  environment: 'sandbox' | 'production';
  timeout?: number; // Request timeout in ms (default: 60000)
  debug?: boolean; // Enable debug logging (default: false)
  rateLimitBuffer?: number; // Rate limit buffer (0-1, default: 0.1)
});

Available Resources

Accounts

// List advertising accounts
const accounts = await client.accounts.list();

// Get specific account
const account = await client.accounts.get(accountId);

Campaigns

// List campaigns
const campaigns = await client.campaigns.list(accountId, {
  count: 10,
  entity_statuses: ['ACTIVE', 'PAUSED'],
});

// Create campaign
const campaign = await client.campaigns.create(accountId, {
  name: 'Campaign Name',
  funding_instrument_id: 'funding-id',
  objective: 'AWARENESS',
  // ... other campaign data
});

// Update campaign
const updatedCampaign = await client.campaigns.update(accountId, campaignId, {
  name: 'Updated Name',
  entity_status: 'ACTIVE',
});

// Get campaign details
const campaign = await client.campaigns.getCampaign(accountId, campaignId);

// Delete campaign
await client.campaigns.delete(accountId, campaignId);

Line Items

// List line items
const lineItems = await client.lineItems.list(accountId, {
  campaign_ids: ['campaign-id'],
});

// Create line item
const lineItem = await client.lineItems.create(accountId, {
  name: 'Line Item Name',
  campaign_id: 'campaign-id',
  objective: 'AWARENESS',
  product_type: 'PROMOTED_TWEETS',
  // ... other line item data
});

Analytics

// Get synchronous analytics (small date ranges)
const analytics = await client.analytics.getStats(accountId, {
  entity: 'CAMPAIGN',
  entity_ids: ['campaign-id'],
  start_time: '2024-01-01T00:00:00Z',
  end_time: '2024-01-07T00:00:00Z',
  granularity: 'DAY',
  placement: 'ALL_ON_TWITTER',
  metrics: ['impressions', 'clicks', 'spend_micro'],
});

// Create asynchronous analytics job (large date ranges)
const job = await client.analytics.createJob(accountId, {
  entity: 'CAMPAIGN',
  entity_ids: ['campaign-id'],
  start_time: '2024-01-01T00:00:00Z',
  end_time: '2024-03-31T00:00:00Z',
  granularity: 'DAY',
  placement: 'ALL_ON_TWITTER',
  metrics: ['impressions', 'clicks', 'spend_micro'],
});

// Check job status
const jobStatus = await client.analytics.getJob(accountId, job.data.job_id);

// List recent jobs
const jobs = await client.analytics.listJobs(accountId, { count: 10 });

Media

// Upload media
const media = await client.media.upload(accountId, {
  file: fileData, // File object or Blob
  media_category: 'TWEET_IMAGE',
  name: 'My Creative Asset',
});

// List media library
const mediaList = await client.media.list(accountId, {
  media_category: 'TWEET_IMAGE',
  count: 20,
});

// Get media details
const mediaDetails = await client.media.getMedia(accountId, mediaId);

// Delete media
await client.media.delete(accountId, mediaId);

Targeting

// Get targeting criteria
const locations = await client.targeting.getLocations('US');
const interests = await client.targeting.getInterests('technology');
const behaviors = await client.targeting.getBehaviors();

Rate Limiting

The SDK includes built-in rate limiting with exponential backoff:

// Check current rate limit status
const status = client.getRateLimitStatus();
console.log(`Remaining requests: ${status.remaining}`);

// Reset rate limiter (if needed)
client.resetRateLimit();

Error Handling

try {
  const campaigns = await client.campaigns.list(accountId);
} catch (error) {
  if (error instanceof Error) {
    console.error('API Error:', error.message);

    // Handle specific error types
    if (error.message.includes('rate limit')) {
      // Handle rate limiting
    } else if (error.message.includes('unauthorized')) {
      // Handle authentication errors
    }
  }
}

Authentication

To use the X Ads API, you need to:

1. Create a Twitter/X Developer App
2. Apply for Ads API access
3. Generate OAuth 1.0a credentials

Environment Variables

For security, use environment variables for credentials:

# For Vite projects (browser)
VITE_CONSUMER_KEY=your-consumer-key
VITE_CONSUMER_SECRET=your-consumer-secret
VITE_ACCESS_TOKEN=your-access-token
VITE_ACCESS_TOKEN_SECRET=your-access-token-secret

# For Node.js projects
CONSUMER_KEY=your-consumer-key
CONSUMER_SECRET=your-consumer-secret
ACCESS_TOKEN=your-access-token
ACCESS_TOKEN_SECRET=your-access-token-secret

Examples

Comprehensive examples are available in the examples/ directory:

• Basic Usage - SDK initialization and basic operations
• Campaign Management - Creating and managing campaigns
• Analytics - Retrieving analytics data and managing jobs
• Media Upload - Uploading and managing media assets

Running Examples

# Install dependencies
npm install

# Run specific example
npx ts-node examples/01-basic-usage.ts

# Or use the example scripts
npm run example:basic
npm run example:campaigns
npm run example:analytics
npm run example:media

License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Resources

• X Ads API Documentation
• X Developer Platform
• X Ads Python SDK
• X TypeScript SDK

Note: This SDK is not officially endorsed by X. It's a community-driven project to help developers integrate with the X Ads API more easily.