MVP: Auto-generated Ruby client for Amazon Ads API

[hakanensari]

Summary

Build an auto-generated Ruby client for the Amazon Ads API, following Peddler's architecture. Start with Sponsored Products (the most common ad type) and the minimal surface needed for automation: read campaigns, pause/resume, adjust bids/budgets.

---

Background

The Amazon Ads API is separate from SP-API but shares the same auth model (LWA/OAuth 2.0). Unlike SP-API, there are no push notifications—it's poll + command only.

Existing Ruby options:

• blurb — abandoned (last release March 2021), uses outdated API versions, depends on rest-client + oauth2

Reference implementations:

• whitebox-co/amazon-ads-api (TypeScript) — auto-generates from OpenAPI specs via daily CI
• python-amazon-ad-api — hand-written, well-maintained

---

OpenAPI Specs

Amazon publishes specs at their OpenAPI download directory.

Known issues (from whitebox-co):

• Some APIs lack schemas (require manual creation from docs)
• allOf/anyOf inheritance generates broken types
• Amazon creates new schema versions rather than updating existing ones

---

Architecture

Follow Peddler's patterns:

HTTP Stack

• http.rb (not Faraday) — same as Peddler
• Rate limiting via http.rb's built-in retriable
• No custom rate limiter class needed

Code Generation

• Custom ERB-based generator (not openapi-generator)
• openapi-generator's Ruby output is terrible; rewriting templates is fighting the tool
• Peddler's generator patterns should transfer with adaptation

Auth

• LWA OAuth 2.0 (identical to SP-API)
• Could copy Peddler::LWA initially
• Future: extract shared amazon-api core gem (like the old jeff gem did for AWS Sig v2)

Structure

lib/sponsor/
├── api.rb              # Base API class (http.rb wrapper)
├── lwa.rb              # Token management (copy from Peddler)
├── endpoint.rb         # Region routing (NA, EU, FE)
├── error.rb
├── response.rb
└── apis/
    ├── profiles.rb     # Account/marketplace selection
    └── sponsored_products/
        ├── campaigns.rb
        ├── ad_groups.rb
        └── keywords.rb

lib/generator/          # Separate from runtime, like Peddler
├── specs.rb            # Fetch/cache OpenAPI specs
├── api.rb              # Generate API classes
└── ...

---

MVP Scope

APIs

• Profiles — list profiles, select marketplace
• Sponsored Products — campaigns, ad groups, keywords

Operations

Operation	Use Case
List campaigns/ad groups	Populate UI, automation targets
Get campaign/ad group	Check current state
Update state (pause/resume)	Automation action
Update bid	Automation action
Update budget	Automation action

Not MVP

• Sponsored Brands / Sponsored Display
• Reporting APIs
• Campaign creation / keyword research
• Amazon DSP / Marketing Cloud

---

Dependencies

gem.add_dependency("http", "~> 5.3")
gem.add_dependency("zeitwerk", "~> 2.6")
# Maybe structure gem for typed responses, or use Data classes

---

Spec Fetching

Unlike SP-API (GitHub repo), Ads API specs are hosted on Amazon's docs site. Need a fetcher that:

1. Downloads specs from known URLs
2. Caches locally in specs/ directory
3. Rake task: rake specs:download

---

Open Questions

1. Typed responses: Use structure gem (like Peddler) or plain Data classes?
2. Shared core: Extract LWA/HTTP/Response to shared gem now, or copy-paste and extract later?
3. Spec discovery: Manually maintain list of spec URLs, or try to scrape the download directory?

---

References

• Amazon Ads API docs
• OpenAPI download directory
• Peddler — SP-API gem to mirror
• Pulsify integration issue — consumer of this gem