Read Amazon report files on the server and add finance tools - #1645

Summary

A Starter customer on the Amazon Seller Central connector asked for three things: a way to read report files (the AI client cannot open the pre-signed S3 link that amazon_get_report_document returns, and the file is often gzip), a way to look at one kind of financial event or at totals per fee type, and why some calls failed. This PR covers all three.

1. Server-side report download. A new optional endpointMapping.download block on REST tools: the tool makes its API call as usual, then fetches the link in the response on the server, decompresses gzip, parses TSV/CSV/JSON and returns one page of rows (with paging, a column filter and column selection). The new amazon_seller_download_report_document tool uses it.
2. Finance tools. Amazon has no event-type filter on listFinancialEvents, so instead of a filter there are three tools: amazon_seller_list_transactions (Finances 2024-06-19, filter by date, status, order or settlement), amazon_seller_get_finance_summary (totals per charge type for a period or settlement) and amazon_seller_list_service_fee_events (only the ServiceFeeEventList, through a JMESPath transform).
3. Swagger 2.0 request bodies were dropped by the OpenAPI importer. Swagger 2.0 declares the body as a parameter in: body. The importer only read OpenAPI 3 requestBody, so tools imported from a Swagger 2.0 spec (all Amazon SP-API models, among others) had no body parameters and sent no body and no Content-Type. Amazon then answered 400 Content type must be set to application/json (seen on generatePlacementOptions). The importer now maps the body schema into bodyMapping and its required fields. A required body whose schema has no fields of its own gets bodyTemplate: "{}".

Changes

• connectors/engines/download-follow.util.ts (new): fetch via fetchOutbound (SSRF checks on the link and every redirect, no connector credentials, 25 MB cap, 60 s timeout), https only, allowedHosts required, gunzip with maxOutputLength 64 MB (gzip-bomb safe), charset from Content-Type (Amazon uses Cp1252 for some reports), TSV and RFC 4180 CSV, page size default 50 and max 500.
• rest.engine.ts: when a mapping has download, run the API call without it, then hand the body to followDownload. Tools without the block take exactly the old path.
• engine-types.ts: download on RestEndpointMapping.
• parsers/openapi.parser.ts: Swagger 2.0 in: body parameters; {} body for a required body without fields.
• adapters/intl/amazon-seller.json: 4 new tools (amazon_seller_* prefix), descriptions of amazon_get_report_document and amazon_list_financial_events point to them, instructions gain the new step 3 and a Finances section.
• adapters/catalog.spec.ts: arguments read by download count as used.
• docs/tool-definition.md: new section "Download links in the response (download)".

Cloud and self-hosted behave the same. No new environment variable, no schema change, nothing under ee/.

Type

• Bug fix
• New feature
• Documentation
• Refactoring
• Performance improvement
• Other (describe below)

Testing

• Added/updated unit tests
• Tested manually (describe steps below)
• No tests needed (explain why)

New specs: download-follow.util.spec.ts (gzip by marker and by magic bytes, paging, filter with several values, column selection, error messages that list the columns, page cap, JSON, Cp1252, https and host checks including amazonaws.com.evil.example, gzip bomb), rest.engine.download.spec.ts (the API call carries the connector's key, the link fetch does not; tools without the block are unchanged), Swagger 2.0 cases in openapi.parser.spec.ts, and a static assertion in amazon-seller.live.spec.ts.

Commands, in packages/backend unless noted:

• npx jest --maxWorkers=4 src/connectors/engines src/connectors/parsers src/adapters/intl/amazon-seller.live.spec.ts: 63 suites passed (1 skipped live suite), 1148 tests passed.
• npx jest --maxWorkers=4 src/adapters/catalog.spec.ts: 15 904 passed.
• npx eslint on the changed files: clean.
• Repository root: node scripts/validate-adapters.mjs --warn: 748 passed, 0 failed. The 15 warnings on amazon-seller are the existing tool-prefix ones on the original amazon_* names; the new tools add none.
• Repository root: node scripts/regenerate-catalog.mjs: no diff. node scripts/adapter-count.mjs --check: OK.
• Full suite locally (npx jest --maxWorkers=4): 31 871 passed. Failures are environmental, none in touched code. 68 suites failed to compile because this checkout's shared node_modules lacks @types/picomatch, @aws-sdk/client-s3 and basic-ftp (they are in package.json). 14 tests in jwt-or-management-key.guard.spec.ts need a local Postgres. tsc --noEmit shows only those same missing-module errors. CI runs on a clean install and is the reference.

Not tested against live Amazon (no seller credentials here).

Checklist

• My code follows the existing code style
• I have tested my changes locally
• I have updated documentation (if applicable)
• All existing tests pass (npm test): see the note under Testing
• This PR has a descriptive title

Related Issues

Support request (Libredesk #268).