Type-safe TypeScript client for the EventZR Ads API. Covers all 139 endpoints across campaigns, creatives, audiences, serving, conversions, reporting, and billing.
pnpm add @eventzr/ads-client
# or
npm install @eventzr/ads-clientPeer dependency: @eventzr/http-client is included automatically.
import { AdsClient } from '@eventzr/ads-client';
const adsClient = new AdsClient({
baseUrl: process.env.ADS_SVC_URL ?? 'https://api.eventzr.com/ads/v1',
tenantId: '<your-tenant-uuid>',
accessToken: '<jwt-token>',
});
// Or use environment-based configuration (recommended for backend services)
const adsClient = new AdsClient({
baseUrl: process.env.API_GATEWAY_URL + '/ads/v1',
tenantId: process.env.TENANT_ID,
accessToken: jwtToken,
timeout: 30000, // Request timeout in ms (default: 30s)
retries: 3, // Retry count on transient errors (default: 3)
});| Method | Signature | Description |
|---|---|---|
| campaigns.list | (query?: CampaignQueryDto) => Promise<PaginatedResponse<Campaign>> | List campaigns with filters and pagination |
| campaigns.create | (dto: CreateCampaignDto) => Promise<Campaign> | Create a new campaign |
| campaigns.get | (id: string) => Promise<Campaign> | Get campaign by ID |
| campaigns.update | (id: string, dto: UpdateCampaignDto) => Promise<Campaign> | Update campaign settings |
| campaigns.delete | (id: string) => Promise<void> | Delete a campaign |
| campaigns.launch | (id: string) => Promise<Campaign> | Launch a draft campaign |
| campaigns.pause | (id: string) => Promise<Campaign> | Pause a running campaign |
| campaigns.resume | (id: string) => Promise<Campaign> | Resume a paused campaign |
| campaigns.clone | (id: string) => Promise<Campaign> | Clone campaign and creatives |
| Method | Signature | Description |
|---|---|---|
| creatives.list | (query?: CreativeQueryDto) => Promise<PaginatedResponse<Creative>> | List creatives with filters |
| creatives.create | (dto: CreateCreativeDto) => Promise<Creative> | Create a new creative |
| creatives.get | (id: string) => Promise<Creative> | Get creative by ID |
| creatives.update | (id: string, dto: UpdateCreativeDto) => Promise<Creative> | Update creative content |
| creatives.delete | (id: string) => Promise<void> | Delete a creative |
| creatives.approve | (id: string) => Promise<Creative> | Approve creative for serving |
| creatives.reject | (id: string, reason: string) => Promise<Creative> | Reject creative |
| Method | Signature | Description |
|---|---|---|
| audiences.list | (query?: AudienceQueryDto) => Promise<PaginatedResponse<Audience>> | List audiences |
| audiences.create | (dto: CreateAudienceDto) => Promise<Audience> | Create a targeting audience |
| audiences.get | (id: string) => Promise<Audience> | Get audience with size estimate |
| audiences.update | (id: string, dto: UpdateAudienceDto) => Promise<Audience> | Update audience criteria |
| audiences.delete | (id: string) => Promise<void> | Delete an audience |
| Method | Signature | Description |
|---|---|---|
| serve.requestAd | (dto: AdRequestDto) => Promise<AdResponse> | Request an ad for a placement |
| serve.requestBatch | (dto: BatchAdRequestDto) => Promise<AdResponse[]> | Request multiple ads |
| impressions.track | (dto: ImpressionDto) => Promise<void> | Track an impression |
| clicks.track | (dto: ClickDto) => Promise<void> | Track a click |
| Method | Signature | Description |
|---|---|---|
| conversions.track | (dto: TrackConversionDto) => Promise<Conversion> | Track a conversion event |
| conversions.list | (query?: ConversionQueryDto) => Promise<PaginatedResponse<Conversion>> | List conversions |
| conversions.trackBatch | (dto: BatchConversionDto) => Promise<void> | Track multiple conversions |
| Method | Signature | Description |
|---|---|---|
| reports.getCampaignReport | (id: string, opts?: ReportOptions) => Promise<CampaignReport> | Campaign performance report |
| reports.getCreativeReport | (id: string, opts?: ReportOptions) => Promise<CreativeReport> | Creative performance report |
| reports.getOverview | (opts?: ReportOptions) => Promise<AccountOverview> | Account-level overview |
| reports.schedule | (dto: ScheduleReportDto) => Promise<ScheduledReport> | Schedule recurring reports |
| reports.export | (dto: ExportReportDto) => Promise<ExportResult> | Export report as CSV/JSON |
| Method | Signature | Description |
|---|---|---|
| billing.getBalance | () => Promise<Balance> | Get current ad balance |
| billing.addFunds | (dto: AddFundsDto) => Promise<FundingResult> | Add funds to ad account |
| billing.listInvoices | (query?: InvoiceQueryDto) => Promise<PaginatedResponse<Invoice>> | List invoices |
| billing.getInvoice | (id: string) => Promise<Invoice> | Get invoice details |
import { AdsClient } from '@eventzr/ads-client';
const client = new AdsClient({
baseUrl: 'https://api.eventzr.com/ads/v1',
tenantId: 'tenant_abc123',
accessToken: '<jwt>',
});
// 1. Create campaign
const campaign = await client.campaigns.create({
name: 'Q3 Event Push',
type: 'display',
budgetType: 'daily',
budgetAmount: 2000,
currency: 'USD',
startDate: '2026-07-01T00:00:00Z',
endDate: '2026-09-30T23:59:59Z',
bidStrategy: 'target_cpa',
targetCpa: 5.00,
});
// 2. Create audience
const audience = await client.audiences.create({
name: 'Event Enthusiasts 25-45',
rules: [
{ field: 'age', operator: 'between', value: [25, 45] },
{ field: 'interests', operator: 'contains', value: 'live-events' },
],
});
// 3. Attach creative
const creative = await client.creatives.create({
campaignId: campaign.data.id,
name: 'Hero Banner',
type: 'image',
format: 'banner',
width: 728,
height: 90,
imageUrl: 'https://cdn.example.com/banner.png',
headline: 'Do not miss these events!',
callToAction: 'Explore',
destinationUrl: 'https://example.com/events',
});
// 4. Launch
await client.campaigns.launch(campaign.data.id);
// 5. Check performance after some time
const report = await client.reports.getCampaignReport(
campaign.data.id,
{ dateRange: 'last_7_days' },
);
console.log(`CTR: ${report.data.ctr}%, ROAS: ${report.data.roas}x`);The SDK throws typed errors that include the error code, HTTP status, and message from the API response.
import { AdsClient, AdsApiError } from '@eventzr/ads-client';
try {
await client.campaigns.launch('cmp_invalid');
} catch (error) {
if (error instanceof AdsApiError) {
console.error('Code:', error.code); // e.g. "ERR_ADS_NOT_FOUND"
console.error('Status:', error.status); // e.g. 404
console.error('Message:', error.message); // Human-readable message
switch (error.code) {
case 'ERR_ADS_INSUFFICIENT_BUDGET':
// Handle insufficient budget
break;
case 'ERR_ADS_CREATIVE_NOT_APPROVED':
// Handle creative not yet approved
break;
default:
throw error;
}
}
}