Skip to main content

​
Installation

npm install @adrelay/sdk
Or with yarn: 
yarn add @adrelay/sdk

​
Quick Start

import { AdRelay } from "@adrelay/sdk";

const client = new AdRelay({
  apiKey: process.env.ADRELAY_API_KEY!,
});

// List all campaigns
const { data, pagination } = await client.campaigns.list();
console.log(data); // AdsCampaign[]

// Filter by platform and status
const google = await client.campaigns.list({
  platform: "google_ads",
  status: "ACTIVE",
  limit: 10,
});

​
Configuration

const client = new AdRelay({
  apiKey: process.env.ADRELAY_API_KEY!,
  baseUrl: "https://api.adrelay.dev/v1", // default
  maxRetries: 3, // retry on 429 and 5xx, default 3
});

​
Campaigns

// List with cursor pagination
const page1 = await client.campaigns.list({ limit: 20 });
if (page1.pagination.hasMore) {
  const page2 = await client.campaigns.list({
    cursor: page1.pagination.cursor!,
  });
}

// Create
const { data: campaign } = await client.campaigns.create({
  platform: "google_ads",
  organization_id: "org_123",
  name: "Summer Sale 2026",
  budget_amount: 50.0,
  budget_period: "DAILY",
  goal: "SALES",
});

// Update
const { data: updated } = await client.campaigns.update("google_abc123", {
  organization_id: "org_123",
  status: "ACTIVE",
  budget_amount: 75.0,
});

// Delete
await client.campaigns.delete("google_abc123", "org_123");

​
Ad Groups

// List ad groups (optionally filter by campaign)
const groups = await client.adGroups.list({
  campaign_id: "google_abc123",
  platform: "google_ads",
});

// Create
const { data: group } = await client.adGroups.create({
  platform: "google_ads",
  organization_id: "org_123",
  campaign_id: "google_abc123",
  name: "US Audience",
  bid_amount: 2.5,
});

// Update
const { data: updatedGroup } = await client.adGroups.update("google_ag456", {
  organization_id: "org_123",
  status: "PAUSED",
});

// Delete
await client.adGroups.delete("google_ag456", "org_123");

​
Reports

const { data: reports } = await client.reports.list({
  platform: "google_ads",
  organization_id: "org_123",
  start_date: "2026-01-01",
  end_date: "2026-01-31",
  campaign_id: "google_abc123", // optional
});

​
Connections

// List connected ad accounts
const { data: connections } = await client.connections.list();

// Get OAuth URL for a platform
const { data: { url } } = await client.connections.getAuthUrl("google_ads");

// Sync connection data
const { data: synced } = await client.connections.sync();

// Remove a connection
await client.connections.delete("conn_123");

​
Error Handling

The SDK provides typed error classes for different failure modes: 
import {
  AdRelay,
  AdRelayError,
  AdRelayAuthError,
  AdRelayRateLimitError,
  AdRelayPlatformError,
} from "@adrelay/sdk";

try {
  await client.campaigns.create({ /* ... */ });
} catch (error) {
  if (error instanceof AdRelayAuthError) {
    // 401 — invalid or missing API key
    console.error("Auth failed:", error.message);
  } else if (error instanceof AdRelayRateLimitError) {
    // 429 — exhausted after maxRetries
    console.error("Rate limited, retry after:", error.retryAfter);
  } else if (error instanceof AdRelayPlatformError) {
    // Upstream platform (Google/Meta/TikTok) returned an error
    console.error("Platform:", error.platform);
    console.error("Detail:", error.platformError);
  } else if (error instanceof AdRelayError) {
    // Any other API error
    console.error(`${error.code} (${error.status}): ${error.message}`);
    console.error("Retryable:", error.retryable);
    console.error("Request ID:", error.requestId);
  }
}

​
Automatic Retries

The SDK automatically retries on 429 (rate limited) and 5xx (server error) responses with exponential backoff (1s, 2s, 4s, up to 8s max). Authentication errors (401) and client errors (4xx) are never retried.

​
TypeScript Support

All API types are re-exported from @adrelay/types: 
import type {
  AdsCampaign,
  AdsGroup,
  AdsReport,
  AdsStatus,
  Platform,
} from "@adrelay/types";