Goal: Amazon Import — Free-Text Search BFF Route

State

Lifecycle: Completed

Linear issues

PDEV-457 — Support free-text search in Amazon import (SearchItems API)
PDEV-477 — Integrate free-text Amazon search into the Add-from-Amazon UI (deferred UI follow-on)
PDEV-569 — Amazon search BFF — zero-result augmentation via LLM-generated suggestions (deferred v2)

Extend the Next.js BFF route surface in arda-frontend-app so that the Amazon import flow accepts free-text keyword queries via the Amazon Creators SearchItems endpoint, in addition to the URL and bare-ASIN inputs the existing /api/amazon/import route already handles. The deliverable is purely the server-side API. The frontend “Add from Amazon” UI is not in scope for this project — UI integration of the new route is tracked separately under PDEV-477, which is blocked by PDEV-457.

The detailed request/response contract, input processing, error codes, Amazon Creators API surface, and zero-result augmentation strategy are documented in spec-analysis.md. Background analysis for the augmentation strategy lives in query-relaxation-exploration.md.

Linear Tickets

PDEV-457 — Support free-text search in Amazon import (SearchItems API): Add a sibling BFF route for flexible free-text product search against the Amazon Creators API, preserving the existing /api/amazon/import route verbatim for URL/ASIN lookup. See spec-analysis.md for the chosen design.
PDEV-477 — Integrate free-text Amazon search into the Add-from-Amazon UI: Sibling follow-on issue covering the frontend integration of the new route. Blocked by PDEV-457; not part of this project’s deliverable but referenced here so the deferred UI work is visible.
PDEV-569 — Amazon search BFF — zero-result augmentation via LLM-generated suggestions (v2): Deferred v2 follow-on for LLM-driven zero-result suggestions (augmentation: "suggestions" request field, optional suggestions[] response field). Backlog, blocked by PDEV-457; parking-lot for the deferred feature so the design analysis in query-relaxation-exploration.md is not lost.

Repositories

Repository	Role	Planned Changes
`arda-frontend-app`	BFF route + supporting server-side client wrapper + MSW mocks + tests	New BFF route exposing keyword product search; a wrapper on the existing Creators API client; MSW handlers for all server-exercised paths; route and client tests.
`documentation`	Project docs	`goal.md`, `spec-analysis.md`, `query-relaxation-exploration.md`.

UI consumption of the new route is out of scope; no changes to React components, pages, hooks, or the ux-prototype design system.

Success Criteria

The BFF can accept a flexible free-text product search and return a list of matching Amazon products using the same per-item DTO shape as the existing import route. The contract has no pagination. On a zero-result primary call, the server performs a bounded, deterministic Amazon-side relaxation (always on, no caller opt-in) before returning an empty list. Richer zero-result strategies (LLM-generated suggestions, external web-search fallbacks) are explicitly out of scope and tracked separately under PDEV-569.
POST /api/amazon/import accepts a broader set of URL/ASIN input shapes via the new shared normalisation layer (schemeless URLs, path-only inputs, lowercase ASINs, extended US sub-hosts, old-form product paths, and plain text containing exactly one ASIN) — but its response contract is preserved verbatim: same DTO shape, same error codes, same HTTP statuses, and free text without an unambiguous ASIN still returns UNRECOGNIZED_AMAZON_URL. No silent re-routing of free text to keyword search.
Invalid request input is rejected with a clear error. Amazon-side failures (network, throttling, 5xx) surface as a distinct error. Zero matching items is a successful empty response, not an error.
No new external dependencies, server secrets, environment variables, or operations-backend changes. Existing Amazon Creators API credentials, marketplace, and rate-limit pool are reused.
All server-exercised paths are covered by MSW mocks and by route and client tests. No live Amazon calls run in CI.
Standard PR gates (npm run build, lint, typecheck, tests) pass locally before PR; PR-body ## CHANGELOG entry filed in the arda-frontend-app PR.

Context

The Amazon import flow currently accepts only Amazon product URLs and bare ASINs via POST /api/amazon/import (introduced under PDEV-446). This project extends the BFF surface so it can also accept free-text product queries against the Amazon Creators API, using the existing OAuth2 credentials and rate-limit pool.

Scope

In Scope

A BFF route exposing keyword product search.
A supporting wrapper on the existing Amazon Creators API client.
A shared URL/ASIN input normalisation layer (extractAsin strict + extractAsinLenient permissive) that broadens the set of accepted URL/ASIN shapes for both routes. /api/amazon/import switches to the lenient extractor (accepting schemeless URLs, path-only inputs, lowercase ASINs, extended US sub-hosts, old-form product paths, and plain text containing exactly one ASIN). /api/amazon/search’s ASIN-shortcut dispatcher uses the strict extractor so keyword queries that happen to contain an ASIN are still treated as searches.
MSW handlers covering every server-exercised path.
Route and client tests for the new surface.
Observability parity with recent Sentry conventions (user spans, external-call timing for Amazon API calls, error capture). The implementation plan audits the workspace’s current Sentry integration patterns and applies them to the new search route. If the audit shows that /api/amazon/import falls short of the same conventions, this project also retrofits the necessary observability probes onto the import route so the two routes match.
PR-body ## CHANGELOG entry in arda-frontend-app.

Out of Scope

Any UI/UX change — React components, pages, hooks, ux-prototype consumers, frontend input parsing, Storybook stories beyond what is needed to keep existing stories green.
Multiple-result picker UI / result list rendering.
Search suggestions, autocomplete, or debounce semantics in any input.
Operations-backend changes; no API contract negotiated with operations.
Affiliate-link rewriting strategy changes beyond reusing the existing helper.

Constraints

API-only deliverable. Frontend integration of any new route is explicitly deferred. This project may not modify React components, pages, or Storybook stories beyond keeping existing tests green.
Existing URL and bare-ASIN happy paths through /api/amazon/import continue to return the current response shape and status codes for their existing inputs.
Short-link and non-US-locale URLs continue to surface their existing, specific error codes — never silently re-routed to search.
Reuse the existing Amazon Creators API client and OAuth2 credentials; do not introduce a separate client or new server env vars.