@nightlybuildgroup/apple-ads

Zero-dependency Node ESM client for the Apple Ads (App Store Search Ads) Campaign Management API. OAuth2 client-credentials: signs an ES256 client-secret JWT with the EC P-256 private key, exchanges it for a bearer token, then calls api.searchads.apple.com/api/v5.

Credentials

The client reads four values from the environment and never touches the filesystem or logs secrets — source them from your secret store at runtime:

| Var | What | |-----|------| | AA_CLIENT_ID | from Apple Ads → Account Settings → API → client | | AA_TEAM_ID | same | | AA_KEY_ID | same | | AA_PRIVATE_KEY | the EC P-256 private key (PEM, or base64-of-PEM; newline-stripped is tolerated) |

Obtaining these requires an Apple Ads account with an Account Admin who provisions an API user and creates the API client (which yields the client/team/ key IDs and registers your public key). See Apple's Implementing OAuth for the Apple Ads API.

Commands

apple-ads acls
apple-ads campaigns | diag
apple-ads report        <orgId> <campId> [start] [end]
apple-ads search-terms  <orgId> <campId> [start] [end]
apple-ads optimize      <orgId> <campId> <adGroupId>      # bounded deterministic tuning
apple-ads get-campaign  <orgId> <campId>
apple-ads update-campaign <orgId> <campId> '<json>'
apple-ads add-keywords  <orgId> <campId> <adGroupId> '<json-array>'
apple-ads update-keywords <orgId> <campId> <adGroupId> '<json-array>'   # pause / bid
apple-ads add-negatives <orgId> <campId> <adGroupId> '<json-array>'
apple-ads provision     <specFile.json>                  # create campaign+adgroup+keywords

Apple Ads gotchas

• Lifetime budgetAmount is not supported — daily budget + end date only.
• timeZone is not a campaign-creation field.
• An expired campaign's endTime cannot be modified (END_TIME_CANNOT_BE_MODIFIED) — recreate.
• APP_NOT_CATEGORIZED is an Ads-side classification lag, not an App Store category gap.

Part of the cli-tools monorepo (@nightlybuildgroup/apple-ads).