# Project memory — blazemedia/amazon-creators-api

Contesto durevole del progetto, versionato col codice. Aggiornare questo file
nella stessa PR che cambia i fatti qui descritti.

## Cos'è

Libreria PHP che fa da **wrapper/adapter unico** sulle Amazon Creators API (le API
di affiliazione con cui Amazon espone catalogo e reportistica ai creator). Client
autenticato istanziabile per account/marketplace, che nasconde l'auth OAuth2 ed
espone metodi per catalogo, feed e report. Ritorna **DTO/array normalizzati** come
contratto pubblico (parità prevista con una futura versione Node).

- Namespace: `App\CreatorsApi` — Sorgenti: `src/` — Test: Pest in `tests/` (PHP 8.3).
- Runner di test offline: `docker compose run --rm php vendor/bin/pest --group=unit`.

## Stella polare

Deve diventare la **dipendenza unica** che i progetti del gruppo includono al posto
delle loro reimplementazioni Creators fatte in casa. Consumatori target:

- **`data-layer`** — ha un SDK Creators esteso a mano (report + auth v3.x).
- **`gclid-mapper`** — ha un `CreatorsApiClient` proprio (feed/report + auth v3.x,
  usa la 3.2).

Obiettivo: entrambi migrano su questa libreria e ritirano il codice bespoke. Per
renderlo possibile la libreria deve coprire ciò che quei client usano oggi.

## Policy di versioning (SemVer)

1. **Segnalare sempre l'impatto sulla retrocompatibilità** dell'interfaccia pubblica
   (firme dei metodi, forma dei DTO/array, config del costruttore) a ogni fix o
   feature — anche quando è "compatibile".
2. **Una release per ogni avanzamento significativo** (fix o feature): breaking →
   major, feature → minor, fix → patch. Sempre da branch + PR.

## Contratto auth per credential version

L'endpoint del token dipende dalla **versione**, non dalla region:

| Version | Flusso | Token endpoint | Body | Scope |
| :-- | :-- | :-- | :-- | :-- |
| 2.1 / 2.2 / 2.3 | Cognito | `…us-east-1` / `…eu-south-2` / `…us-west-2` `.amazoncognito.com/oauth2/token` | form-urlencoded | `creatorsapi/default` |
| 3.1 / 3.2 / 3.3 | Login with Amazon | `api.amazon.com` / `api.amazon.co.uk` / `api.amazon.co.jp` `/auth/o2/token` | JSON | `creatorsapi::default` |

`Authorization` sulle chiamate API **dipende dalla famiglia di credenziali**:

| Version | Header `Authorization` |
| :-- | :-- |
| 2.x (Cognito) | `Bearer <token>, Version <credentialVersion>` |
| 3.x (LwA) | `Bearer <token>` — **senza** suffisso `Version` |

Inviare il suffisso con credenziali 3.x fa rifiutare la richiesta. Sempre presente
l'header `x-marketplace`. Base API: `https://creatorsapi.amazon`.

## Stato e roadmap

- **Presente**: `getItems` (catalogo), `listFeeds`/`getFeed`, `listReports`/`getReport`,
  DTO (`AmazonItem`, `Price`, `ProductItem`, `ReportMetadata`), auth 2.x + 3.x.
- **On-demand (prossime release)**: `searchItems`, `getVariations`, `getBrowseNodes`;
  helper di download (`getReport` → scarica `.tsv.gz` → gzdecode); normalizzazione
  delle liste feed/report; versione Node.

## Riferimenti

- **Auth v3.x (LwA)**: confermata contro la **doc ufficiale** — vedi la sezione
  "Token Generation for v3.x Credentials (LwA)" in `docs/en/get-started/using-curl.md`
  (tabella endpoint per versione + body JSON + scope `creatorsapi::default`). Verifica
  a tre vie (libreria `src/`, `data-layer`, `gclid-mapper`): **concordano al 100%**.
  Dettaglio consolidato in [`docs/it/knowledge-base/autenticazione-per-versione.md`](docs/it/knowledge-base/autenticazione-per-versione.md).
- **Limite noto (non nella doc ufficiale)**: le credenziali **v3 spesso non sono
  abilitate ai feed** → `listFeeds`/`getFeed` rispondono `HTTP 404`; per i feed EU/IT
  usare una credenziale **2.2**. Fonte: `gclid-mapper::throwHelpfulFeedError`.
- Contratto report (`/reports/v1`): ancora confermato **solo** dall'uso in produzione
  in `data-layer` e `gclid-mapper` (le operazioni report/feed non sono nella doc
  ufficiale, che copre catalogo: getItems/searchItems/getVariations/getBrowseNodes).
- Doc ufficiale tradotta e knowledge base interna: `docs/README.md` (indice).
