{"_id":"@apple/apple-ads-platform","_rev":"3-efffa73b56ffcf630ab7208ec9926e27","name":"@apple/apple-ads-platform","dist-tags":{"latest":"1.109.0"},"versions":{"0.0.1":{"name":"@apple/apple-ads-platform","version":"0.0.1","author":"","license":"MIT","_id":"@apple/apple-ads-platform@0.0.1","maintainers":[{"name":"athasach","email":"athasach+npm@gmail.com"},{"name":"fehguy","email":"fehguy@gmail.com"},{"name":"cp_apple","email":"cphu@apple.com"},{"name":"kwapple","email":"kent_wong@apple.com"},{"name":"apple-admin","email":"npmjs@apple.com"},{"name":"mdrob-apple","email":"mdrob@apple.com"}],"homepage":"https://github.com/apple/apple-ads-platform-api-node#readme","bugs":{"url":"https://github.com/apple/apple-ads-platform-api-node/issues"},"dist":{"shasum":"9981c1d3ec529331a2fa6009b8bc8ae33ad63d72","tarball":"https://registry.npmjs.org/@apple/apple-ads-platform/-/apple-ads-platform-0.0.1.tgz","fileCount":1,"integrity":"sha512-okR6hKqdEumWtAGOBlGI9ocbC4PVxKY8lPqYUT7AtB4DDt5agJUeRyiRAqNZ/WgBxuIRvZy3Wqx5GZ0+1xMkSw==","signatures":[{"sig":"MEUCIE5bdXhIqw0DHqIIiee7ekc6QisIp2vlNn2qUMYPmL9aAiEAiC8HHJU1Zr3CAdtOF8Pbv9/l8N2Z5wNe7ayPdlRPvV4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":504},"main":"index.js","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"mdrob-apple","email":"mdrob@apple.com"},"repository":{"url":"git+https://github.com/apple/apple-ads-platform-api-node.git","type":"git"},"_npmVersion":"10.9.8","description":"","directories":{},"_nodeVersion":"22.22.3","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/apple-ads-platform_0.0.1_1786724297852_0.8160240193454669","host":"s3://npm-registry-packages-npm-production"}},"1.109.0":{"name":"@apple/apple-ads-platform","version":"1.109.0","description":"Node.js client library for the Apple Ads Platform API","main":"dist/index.js","types":"dist/index.d.ts","repository":{"type":"git","url":"git+https://github.com/apple/apple-ads-platform-api-node.git"},"scripts":{"build":"tsc","build:watch":"tsc --watch","clean":"rm -rf dist","prebuild":"npm run clean","test":"jest","test:coverage":"jest --coverage","lint":"eslint src tests","lint:fix":"eslint src tests --fix","audit":"npm audit --omit=dev --audit-level=high","install-hooks":"git config core.hooksPath .githooks || true","prepare":"npm run install-hooks && npm run build","sync-version":"npm pkg set version=$(bash scripts/lib_version.sh)","check-version":"bash scripts/check_version.sh","prepack":"npm run sync-version && npm run build","update-deps":"npx npm-check-updates -u --target minor && npm install"},"keywords":["apple","ads"],"license":"MIT","dependencies":{"agentkeepalive":"^4.6.0","axios":"1.18.1","jsonwebtoken":"^9.0.3"},"devDependencies":{"@types/jest":"^29.5.14","@types/jsonwebtoken":"^9.0.10","@types/node":"^25.6.0","@typescript-eslint/parser":"^8.59.2","axios-mock-adapter":"^2.1.0","eslint":"^10.3.0","eslint-plugin-license-header":"^0.9.0","jest":"^29.7.0","ts-jest":"^29.2.6","typescript":"^5.8.2"},"gitHead":"f90ac18b616e0ba2bbf2d17d73f54deeb2dd7af1","_id":"@apple/apple-ads-platform@1.109.0","bugs":{"url":"https://github.com/apple/apple-ads-platform-api-node/issues"},"homepage":"https://github.com/apple/apple-ads-platform-api-node#readme","_nodeVersion":"24.19.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-RWL141fprFQ97nWn7MH51hOw/ZGXeS0fqKIQaRQQCz2kBxd7BMT2hO11lRsQFyxBXY5iz+5FJ8FAeseYoeUSTw==","shasum":"970b4c88df55e9180586347e91d48da7feeac813","tarball":"https://registry.npmjs.org/@apple/apple-ads-platform/-/apple-ads-platform-1.109.0.tgz","fileCount":1571,"unpackedSize":1610718,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@apple%2fapple-ads-platform@1.109.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIG/EWgl6bX52cLj/9Qb6Nk6KS8+BQodHpI0DCJX2CaEtAiEAsymaJnlWcuCi2iZamzzNNOPjHSPTVdRO+ycBcX9VORw="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:f325c028-794c-4ed5-9d14-e4fcee5b7ee3"}},"directories":{},"maintainers":[{"name":"athasach","email":"athasach+npm@gmail.com"},{"name":"fehguy","email":"fehguy@gmail.com"},{"name":"cp_apple","email":"cphu@apple.com"},{"name":"kwapple","email":"kent_wong@apple.com"},{"name":"apple-admin","email":"npmjs@apple.com"},{"name":"mdrob-apple","email":"mdrob@apple.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/apple-ads-platform_1.109.0_1786726598907_0.6074199790378023"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T16:18:17.593Z","modified":"2026-08-14T16:56:39.466Z","0.0.1":"2026-08-14T16:18:17.988Z","1.109.0":"2026-08-14T16:56:39.082Z"},"bugs":{"url":"https://github.com/apple/apple-ads-platform-api-node/issues"},"license":"MIT","homepage":"https://github.com/apple/apple-ads-platform-api-node#readme","repository":{"type":"git","url":"git+https://github.com/apple/apple-ads-platform-api-node.git"},"maintainers":[{"name":"athasach","email":"athasach+npm@gmail.com"},{"name":"fehguy","email":"fehguy@gmail.com"},{"name":"cp_apple","email":"cphu@apple.com"},{"name":"kwapple","email":"kent_wong@apple.com"},{"name":"apple-admin","email":"npmjs@apple.com"},{"name":"mdrob-apple","email":"mdrob@apple.com"}],"readme":"# Apple Ads Platform API Node\n\nA Node.js / TypeScript client library for the Apple Ads Platform API.\n\n## Model and Endpoint Documentation\n\nThis README serves as the primary documentation for installation and usage of this library. For\ninformation on data models and API endpoints, see the\n[Apple Ads Platform API documentation](https://developer.apple.com/documentation/apple-ads-platform-api)\nfound on Apple's developer website.\n\n## Installation\n\nInstall this library from npm. Like nearly any software dependency, you should pin a\nspecific version and update it only when you explicitly intend to do so.\n\n```bash\nnpm install @apple/apple-ads-platform\n```\n\nOr add it to your `package.json` `dependencies`:\n\n```json\n{\n  \"dependencies\": {\n    \"@apple/apple-ads-platform\": \"VERSION\"\n  }\n}\n```\n\nThe library ships with TypeScript type declarations — no separate `@types/...` package is needed.\n\n## Getting Started\n\nThis library makes it easy to create an [`AppleAdsApi`](src/api/apple-ads-api.ts) instance backed by\nan [`axios`](https://axios-http.com/) HTTP client that is ready to call the Apple Ads Platform API.\nThe [`createAppleAdsApi`](src/factory.ts) factory accepts the information needed for authentication\nalong with various optional settings. The resulting client performs the OAuth flow transparently.\n\n### Client Construction\n\nYou can instantiate a client in three ways, selected by the `authMode` field on the options object.\n\n#### Using Your Private Key\n\nThe first way to create the client is to provide a path to your `.pem` private key file along with\nthe rest of the associated metadata. The library reads the key once at construction time and\ngenerates a fresh client secret every time a new access token is needed.\n\n```ts\nimport { createAppleAdsApi } from '@apple/apple-ads-platform';\n\nconst api = await createAppleAdsApi({\n  authMode: 'key',\n  clientId: '...',\n  teamId: '...',\n  keyId: '...',\n  privateKeyPath: '/path/to/your/private/key.pem',\n});\n```\n\n#### Using a Custom ClientSecretProvider\n\nIf you wish to generate client secrets in a different way (for example generating them offline and\nusing a fixed one at runtime, or using a separate service for signing), pass an implementation of\n[`ClientSecretProvider`](src/auth/types.ts). The library calls it whenever a client secret is needed\nfor fetching a new access token.\n\n```ts\nimport { createAppleAdsApi, ClientSecretProvider } from '@apple/apple-ads-platform';\n\nconst clientSecretProvider: ClientSecretProvider = {\n  getClientSecret: () => '...',\n};\n\nconst api = await createAppleAdsApi({\n  authMode: 'clientSecret',\n  clientId: '...',\n  clientSecretProvider,\n});\n```\n\n#### Implementing OAuth Yourself\n\nWe recommend letting the library handle the OAuth flow. If you have specific requirements, you can\nimplement it yourself by constructing the client with an\n[`AccessTokenProvider`](src/auth/types.ts). In this case, the library calls it before every API\nrequest in order to attach an access token as an HTTP header.\n\n```ts\nimport { createAppleAdsApi, AccessTokenProvider } from '@apple/apple-ads-platform';\n\nconst accessTokenProvider: AccessTokenProvider = new MyAccessTokenProvider(/* ... */);\n\nconst api = await createAppleAdsApi({\n  authMode: 'token',\n  accessTokenProvider,\n});\n```\n\n### Optional Settings\n\nAll options below have sensible defaults and may be omitted. Options are passed as fields on the\nsame options object.\n\n#### Common (all `authMode` values)\n\n| Field                 | Type                                | Description                                                                                                                                                                              | Default                        |\n|-----------------------|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------|\n| `apiTimeout`          | `number` (ms)                       | Timeout for API requests.                                                                                                                                                                | `5000`                         |\n| `maxSockets`          | `number`                            | Maximum open sockets per host for the API connection pool.                                                                                                                               | `50`                           |\n| `maxFreeSockets`      | `number`                            | Maximum idle keep-alive sockets per host for the API connection pool.                                                                                                                    | `10`                           |\n| `freeSocketTimeout`   | `number` (ms)                       | Idle sockets are evicted from the API pool after this many milliseconds. Set below the server's keep-alive idle timeout to avoid stale connection errors.                                | `30000`                        |\n| `apiAxiosCustomizer`  | `(instance: AxiosInstance) => void` | Callback applied to the main API axios instance after it is created, allowing additional customization (proxy setup, additional interceptors, headers, etc.). See the [axios](https://axios-http.com/docs/interceptors) documentation for what is possible. | None applied                   |\n| `logger`              | `Logger \\| null`                    | Logger used by the request/response logging interceptors. Pass `null` to disable logging entirely. Any object implementing the [`Logger`](src/auth/types.ts) interface works (compatible with `console`, `winston`, and `pino` with a small wrapper). The `Authorization` header is never logged. | `console`                      |\n| `requestLogLevel`     | `'debug' \\| 'info' \\| 'warn' \\| 'error'` | Log level for request start and successful responses. Applies to both API and auth axios instances.                                                                                     | `'info'`                       |\n| `errorLogLevel`       | `'debug' \\| 'info' \\| 'warn' \\| 'error'` | Log level for request errors. Applies to both API and auth axios instances.                                                                                                             | `'error'`                      |\n\n#### Additional for `authMode: 'key'` and `authMode: 'clientSecret'`\n\n| Field                 | Type                                | Description                                                                             | Default                          |\n|-----------------------|-------------------------------------|-----------------------------------------------------------------------------------------|----------------------------------|\n| `authTimeout`         | `number` (ms)                       | Timeout for token requests to the auth server.                                          | `5000`                           |\n| `authAxiosCustomizer` | `(instance: AxiosInstance) => void` | Same as `apiAxiosCustomizer` but for the axios instance used for auth token requests.   | None applied                     |\n\n#### Example with Optional Settings\n\n```ts\nconst api = await createAppleAdsApi({\n  authMode: 'key',\n  clientId: '...',\n  teamId: '...',\n  keyId: '...',\n  privateKeyPath: '/path/to/your/private/key.pem',\n  apiTimeout: 10_000,\n  requestLogLevel: 'debug',\n});\n```\n\n## Examples\n\nThe `xApContext` header identifies the ad account to which the request applies.\nIt is a plain string — construct it as required by the API for the endpoint you are calling.\n\n#### Query Running Campaigns\n\n```ts\nimport {\n  createAppleAdsApi,\n  QueryRequest,\n  QueryFilterOperator,\n  CampaignSystemStatus,\n} from '@apple/apple-ads-platform';\n\nconst api = await createAppleAdsApi({\n  authMode: 'key',\n  clientId: '...',\n  teamId: '...',\n  keyId: '...',\n  privateKeyPath: '/path/to/your/private/key.pem',\n});\n\nconst runningCampaignsRequest: QueryRequest = {\n  filters: [\n    {\n      field: 'systemStatus',\n      operator: QueryFilterOperator.Equals,\n      value: CampaignSystemStatus.Running,\n    },\n  ],\n};\n\nconst xApContext = '...'; // e.g. \"adAccountId=12345678;\" \n\nconst response = await api.campaignsQueryPost(xApContext, runningCampaignsRequest);\n```\n\n#### Get a Business Brand by ID\n\n```ts\nconst api = await createAppleAdsApi({\n  authMode: 'key',\n  clientId: '...',\n  teamId: '...',\n  keyId: '...',\n  privateKeyPath: '/path/to/your/private/key.pem',\n});\n\nconst brandId = '...';\nconst xApContext = '...';\n\nconst response = await api.getBrand(xApContext, brandId);\n```\n\n#### Update a Keyword Bid\n\n```ts\nimport { createAppleAdsApi, KeywordUpdate } from '@apple/apple-ads-platform';\n\nconst api = await createAppleAdsApi({\n  authMode: 'key',\n  clientId: '...',\n  teamId: '...',\n  keyId: '...',\n  privateKeyPath: '/path/to/your/private/key.pem',\n});\n\nconst keywordId = '...';\nconst xApContext = '...';\n\nconst keywordUpdate: KeywordUpdate = {\n  bid: { amount: '1.00', currency: 'USD' },\n};\n\nconst response = await api.keywordsIdPut(keywordId, xApContext, keywordUpdate);\n```\n\n## Error Handling\n\nEvery failed request — non-2xx response or transport/network failure — is converted into an\n[`ApiRequestError`](src/errors.ts) before it escapes the library. The error is flat and fully\nserializable (safe to `JSON.stringify` and to log): it carries only scalar fields (`code`,\n`status`, `statusText`, `method`, `url`) plus the server's response payload (`data`). It never\nholds a reference to the underlying axios error, socket, or connection-pool agent.\n\n```ts\nimport { ApiRequestError } from '@apple/apple-ads-platform';\n\ntry {\n  await api.getBrand(xApContext, brandId);\n} catch (err) {\n  if (err instanceof ApiRequestError) {\n    console.error(err.status, err.data);\n  }\n  throw err;\n}\n```\n\n## Keeping Your Credentials Secure\n\nYour private key and client secrets are sensitive credentials. Don't store them as plain text.\nTreat access tokens as secrets too. The library does not log any of these values (the\n`Authorization` header is explicitly omitted from log output). Do the same if you choose to add any\nadditional logging or observability through additional customization of the client.\n\n## Reusing the Client\n\nThe client is safe to use concurrently across many in-flight requests. Create a single instance\nper process and share it across your entire application. This maximizes the benefit of the\nunderlying keep-alive connection pool and minimizes calls to the OAuth server. If you provide your\nown `AccessTokenProvider`, concurrency behavior depends on the implementation.\n\n## Enum Types\n\nThe model definitions use TypeScript `enum` types with string values (see\n[`src/model`](src/model)) throughout the API model. As the API itself evolves over time, new enum\nvalues may appear. Because the library does not throw on unknown enum values during\ndeserialization, a response can contain a string that does not match any current member of the\nenum. Compare against the known enum members with care, and keep your library up to date to ensure\nyou have model types that match the latest version of the API.\n\n# Node Commands\n\n## Testing\n\n### `npm test`\nRun the full test suite once and report results. Use this for CI or a quick local check.\n\n### `npm run test:coverage`\nRun the full test suite and generate a code-coverage report under `coverage/`. Open `coverage/lcov-report/index.html` in a browser for a detailed line-by-line view.\n\n## Building\n\n### `npm run build`\nCompile TypeScript source in `src/` to JavaScript in `dist/`, including type declaration files (`.d.ts`). The `prebuild` step automatically cleans `dist/` first. Run this before publishing.\n\n## Dependency Management\n\n### `npm run update-deps`\nCheck for newer versions of all dependencies and interactively upgrade `package.json`, then install the updated packages. Powered by `npm-check-updates` (`ncu`). Review and test after running — major-version bumps may contain breaking changes.\n\n## License\n\nThis project is released under the MIT License. See [LICENSE](LICENSE) for details.\n\nThis project includes third-party software components; see [ACKNOWLEDGEMENTS](ACKNOWLEDGEMENTS) for attribution.","readmeFilename":"README.md","description":"Node.js client library for the Apple Ads Platform API","keywords":["apple","ads"]}