@coloop-ai/openai-ads-sdk

Type-safe TypeScript SDK for the OpenAI Ads API.

This package is maintained by CoLoop. It is not an official OpenAI SDK. It requires Node.js 18 or newer.

Install

pnpm add @coloop-ai/openai-ads-sdk

Quick start

import { OpenAIAds } from '@coloop-ai/openai-ads-sdk'

const ads = new OpenAIAds({
  apiKey: process.env.OPENAI_ADS_API_KEY!,
  adAccountId: 'ad-account-id',
})

const campaigns = await ads.campaigns.list({ limit: 100 })
const campaign = await ads.campaigns.get('campaign-id')

Methods accept typed query objects and request bodies. They return the parsed response body. Query, request, and response fields use the names defined by the API, including snake_case names.

Authentication

Create a client with exactly one credential:

• apiKey for an OpenAI Ads API key
• accessToken for an Ads OAuth access token

A credential can be a string or a function. The SDK resolves a credential function before every request, which allows the application to refresh OAuth tokens outside the SDK.

const ads = new OpenAIAds({
  accessToken: async () => getAdsAccessToken(),
  adAccountId: 'ad-account-id',
})

adAccountId sets the OpenAI-Ad-Account request header. The header is required for OAuth access tokens and shared API keys. An advertiser API key may omit it. A request can override the client value with { adAccountId: 'another-account-id' }.

Most methods accept either credential. The following methods require a specific credential:

| Credential | Methods | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | OAuth access token | adAccountCreationSessions.create, oauth.getMe | | API key | businessAgentTools.list, apiKeys.create, conversions.apiKeys.create, conversions.events.list, partnerData.uploads.create, partnerData.uploads.get |

Request options

Pass supported request options as the final argument:

| Option | Effect | | ---------------- | ------------------------------------------------- | | adAccountId | Overrides the client account for one request. | | signal | Cancels the request with an AbortSignal. | | timeoutMs | Overrides the client timeout for one request. | | idempotencyKey | Sets Idempotency-Key where the API supports it. |

await ads.campaigns.get('campaign-id', {}, { timeoutMs: 10_000 })

Set timeoutMs on the client to apply one timeout to every request. A timeout must be a positive integer. The SDK does not set a timeout by default, retry failed requests, or auto-paginate list responses.

The TypeScript signature requires an idempotency key when the API requires one:

await ads.customAudiences.addMembers('audience-id', body, {
  idempotencyKey: crypto.randomUUID(),
})

File uploads

uploadBlob accepts a Blob or File and sends multipart form data:

await ads.files.uploadBlob({
  file: new Blob([bytes]),
  purpose: 'custom_audience',
})

uploadImage accepts either an image URL or a Blob or File:

await ads.files.uploadImage({ image_url: 'https://example.com/image.png' })
await ads.files.uploadImage({ file: imageBlob })

Errors

import { OpenAIAdsApiError } from '@coloop-ai/openai-ads-sdk'

try {
  await ads.campaigns.get('campaign-id')
} catch (error) {
  if (error instanceof OpenAIAdsApiError) {
    console.error(error.status, error.code, error.message)
  }
}

| Error | Cause | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | OpenAIAdsApiError | An API response with a status outside 200-299. Includes status, code, param, type, payload, response, and a request summary. | | OpenAIAdsTimeoutError | The client or request timeout elapsed. Includes timeoutMs and a request summary. | | OpenAIAdsConfigurationError | The client configuration is invalid, or the method requires a different credential type. | | Native fetch or AbortSignal error | The network request failed, or the caller cancelled it. The SDK preserves the original error. |

API

The client groups methods by API resource:

| Resource | Methods | | ----------------------------- | -------------------------------------------------------------------------------------------- | | campaigns | list, create, get, update, activate, pause, archive | | customAudiences | list, create, get, archive, addMembers, removeMembers, replaceMembers, merge | | customAudiences.operations | get | | businessAgentTools | list | | businessAgents | list, create, get, update, preview, publish | | leadForms | list, create, get, update, publish, archive | | leadForms.testSubmissions | create | | apiKeys | create | | adAccount | get, updateBrand, updateNegativeKeywords, activate, pause | | adAccount.spendLimitWindows | list, create, update, delete | | adAccounts | list | | adAccountCreationSessions | create | | oauth | getMe | | insights | adAccount, campaign, adGroup, ad | | geo | search | | leadSync.subscriptions | create, list, get, delete | | conversions.apiKeys | create | | conversions.eventSettings | create, list | | conversions.pixels | create, list | | conversions.events | list | | conversions.insights | query | | adGroups | list, create, get, update, activate, pause, archive | | ads | list, create, get, update, preview, activate, pause, archive | | files | uploadBlob, uploadImage | | productFeeds | archive, create, list | | productFeeds.uploads | list | | productFeeds.products | query, patch | | productFeeds.sftpAccess | get, createOrReplace, activate, pause | | partnerData.uploads | create, get |

Raw client

Import @coloop-ai/openai-ads-sdk/raw for low-level operations and API types. Raw operations return result objects instead of only response bodies.

License

MIT License. See LICENSE.