Amazon Ads Reporter

Fetch Amazon Ads Sponsored Products campaign reports asynchronously by requesting and polling separately to avoid API timeouts, with no npm dependencies.

Security Scan

The skill generally matches its stated purpose (fetch Amazon Ads reports and live keyword bids), but the documentation references missing scripts and some declared behavior (files written, region handling, declared env vars) doesn't match the included code — verify before installing or running with real credentials.

Purpose & Capability

Name/description align with the two included scripts (keyword-report.js and get-bids.js). However SKILL.md documents additional scripts (request-report.js, poll-report.js, get-report.js) and output files (~/.openclaw/workspace/tmp/amazon-report-*.json) that are not present in the package; region selection described in the README is not honored (both scripts hardcode the EU advertising API endpoint). These mismatches mean the skill package is incomplete or inconsistently documented.

Instruction Scope

Instructions tell the agent to run scripts that are missing and to write/read specific workspace files that the provided scripts do not create. Both scripts read credentials from a local JSON file (AMAZON_ADS_PATH or default in home). That credential access is expected for this purpose, but the SKILL.md and code disagree on how reports are requested/polled and where artifacts are stored — the agent would likely error or behave differently than documented.

Install Mechanism

No install spec (instruction-only plus two code files). No downloads or external installers are present, which lowers installation risk. The scripts use only Node built-ins and make HTTPS calls.

Credentials

The code reads sensitive local credentials from amazon-ads-api.json (refresh token, client id/secret, profileId) and get-bids.js expects CAMPAIGN_IDS in env. The registry metadata declares no required env vars or primary credential, which is inconsistent with the scripts and SKILL.md. Requesting a refresh token and client secret is appropriate for the advertised purpose, but the missing metadata and plaintext local credential requirement should be noted and validated.

Persistence & Privilege

always:false and user-invocable:true (defaults). The skill does not request persistent system-wide privileges or modify other skills' configs. It runs as ad-hoc Node scripts and does not install background services.

What to consider before installing

This package mostly does what it says (fetch reports, list bids) but it is inconsistent and incomplete. Before using it: 1) Do not run with real credentials until you verify the missing scripts — SKILL.md references request-report.js, poll-report.js, and get-report.js but only keyword-report.js and get-bids.js are included. 2) Inspect or obtain the missing scripts from a trusted source or ask the author for a complete release. 3) Store credentials carefully: amazon-ads-api.json contains a refresh token and client secret in plaintext — keep it readable only by you and consider using a short-lived profile or limited-scope account. 4) Confirm CAMPAIGN_IDS is set when running get-bids.js and that your Node runtime provides global fetch (or run on a Node version that supports it) or adjust the script. 5) Note that both scripts call Amazon endpoints and do not contact any other external servers — if you see network calls to non-Amazon domains, do not proceed. 6) Because the package metadata didn't declare required env vars, treat the skill as incomplete and verify behavior in a safe/test environment; rotate secrets if you accidentally exposed them during testing.

skill-amazon-ads-reporter

Description

Fetch Amazon Ads Sponsored Products campaign performance reports using a decoupled async pattern. Avoids timeout issues with the v3 Reporting API (2–10 min generation time) by splitting request and poll into separate steps. Also includes keyword-level winner/dead analysis and a quick bid inspector.

Why two steps?

Amazon's Reporting API v3 is async — you request a report, get a reportId, and poll until it's ready. Doing this inline in a cron causes timeouts. The correct pattern:

request → save reportId → (wait 1-2 min) → poll + download

Usage

Campaign-level report (step-by-step, recommended for crons)

# Step 1: Request report — exits immediately with reportId
node scripts/request-report.js --days 7

# Step 2: Poll + download (run 1-2 min later, or from a separate cron)
node scripts/poll-report.js

Campaign-level report (all-in-one, for manual runs)

node scripts/get-report.js --days 7

Keyword-level winner/dead analysis (14-day async report)

node scripts/keyword-report.js

Output: table of all ENABLED keywords with clicks > 0 OR impressions ≥ 50 (winners), plus count of dead keywords (0 clicks, <50 imp).

Quick bid inspector (live, across campaigns)

node scripts/get-bids.js

Output: all ENABLED + PAUSED keywords per campaign with current bids. Reads live data (no report needed).

Arguments

Arg	Default	Description
--days N	7	Number of days to include in report (campaign and keyword reports)

Configuration

Reads credentials from AMAZON_ADS_PATH env var, defaulting to ~/amazon-ads-api.json.

amazon-ads-api.json format

{
  "refreshToken": "...",
  "lwaClientId": "...",
  "lwaClientSecret": "...",
  "profileId": "...",
  "region": "EU"
}

Regions: EU (default, includes UAE), NA (North America), FE (Far East).

Output

• ~/.openclaw/workspace/tmp/amazon-report-pending.json — created by request-report.js
• ~/.openclaw/workspace/tmp/amazon-report-latest.json — created by poll-report.js after success
• Console table: Campaign | Impressions | Clicks | CTR% | Spend | Sales | ACOS%

Report columns (campaign-level)

campaignName, campaignId, impressions, clicks, spend, purchases7d, sales7d

Paused campaigns are automatically filtered out by cross-referencing GET /sp/campaigns/list.

Report columns (keyword-level — keyword-report.js)

keywordId, keywordText, matchType, impressions, clicks, cost, purchases7d, sales7d

Dependencies

Node.js built-ins only (https, zlib, fs, path). No npm install required.

Notes

• Access tokens expire — refresh via Amazon Login with Advertising if needed
• The GZIP_JSON format is gunzipped automatically by poll-report.js
• Reports are only available for the previous day and earlier (endDate = yesterday)
• get-bids.js uses the live v3 keyword list endpoint — no async report needed, instant response
• keyword-report.js uses the same async pattern as campaign reports (30s poll intervals, up to 10 min)