@coloop-ai/openai-ads-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Genie Technology Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# @coloop-ai/openai-ads-sdk
+
+[![npm version](https://img.shields.io/npm/v/@coloop-ai/openai-ads-sdk.svg)](https://www.npmjs.com/package/@coloop-ai/openai-ads-sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@coloop-ai/openai-ads-sdk.svg)](https://www.npmjs.com/package/@coloop-ai/openai-ads-sdk)
+[![License: MIT](https://img.shields.io/npm/l/@coloop-ai/openai-ads-sdk.svg)](https://github.com/Genei-Ltd/openai-ads-sdk/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue?logo=typescript)](https://www.typescriptlang.org/)
+
+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
+
+```zsh
+pnpm add @coloop-ai/openai-ads-sdk
+```
+
+## Quick start
+
+```ts
+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.
+
+```ts
+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. |
+
+```ts
+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:
+
+```ts
+await ads.customAudiences.addMembers('audience-id', body, {
+  idempotencyKey: crypto.randomUUID(),
+})
+```
+
+## File uploads
+
+`uploadBlob` accepts a `Blob` or `File` and sends multipart form data:
+
+```ts
+await ads.files.uploadBlob({
+  file: new Blob([bytes]),
+  purpose: 'custom_audience',
+})
+```
+
+`uploadImage` accepts either an image URL or a `Blob` or `File`:
+
+```ts
+await ads.files.uploadImage({ image_url: 'https://example.com/image.png' })
+await ads.files.uploadImage({ file: imageBlob })
+```
+
+## Errors
+
+```ts
+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](./LICENSE).