test: split integration suite by resource and tighten SDK/API contract

[Gabrielpanga]

Summary

Restructures the integration test suite from one 338-line tests/integration.test.ts monolith into per-resource specs under tests/integration/. Per-resource isolation: each spec that needs server state owns the full lifecycle of its own sandbox item (beforeAll creates and waits for UPDATED, afterAll deletes defensively).

What's new

Helpers — tests/integration/helpers.ts

• createClient / createSandboxItem / deleteItemSafely.
• retry() for sandbox eventual consistency (some endpoints lag a beat after the item flips UPDATED).
• RUN_ID + TEST_TAG — every test run is tagged with GITHUB_RUN_ID (CI) or local-<timestamp>. Resources that accept free-form identifiers (connect token's clientUserId, webhook URLs) get tagged so orphans from failed runs are identifiable.
• captureRejection() — BaseApi rejects with the parsed error response body (not a thrown Error with .statusCode), so error tests capture the body and let each test inspect it.
• describeIntegration — auto-skip via describe.skip when PLUGGY_CLIENT_ID / PLUGGY_CLIENT_SECRET are absent.

Coverage additions vs the monolith

Spec	New coverage
items.test.ts	fetchItem shape + date instances
bills.test.ts	fetchCreditCardBills / fetchCreditCardBill (skips silently when sandbox has no CREDIT account)
errors.test.ts	4xx responses for non-existent ids on fetchItem, fetchAccount, fetchTransaction, fetchConnector
accounts.test.ts	fetchAccountStatements
transactions.test.ts	updateTransactionCategory
connectors.test.ts	validateParameters

Coverage retained from the monolith

Connectors list/get, accounts, transactions (cursor + by-id + dedup), investments + fetchAllInvestmentTransactions dedup, identity (by item + by id), consents, loans, categories, connect token, webhooks CRUD.

Cleanup is mandatory

Pluggy items are heavy enough that leaked fixtures pile up against the test tenant's quota. So every spec that creates an item registers afterAll with deleteItemSafely (try/catch + stderr on failure so leaks are visible but never mask test failures).

Why per-suite items (not shared via globalSetup)

Trade-off: ~30+ minutes of wall time per run (each suite waits a full sandbox sync) vs. true isolation between suites. Per-suite isolation means one broken test can't poison the next.

Out of scope (next PR)

PluggyPaymentsClient — recipients, requests, intents, payment customers, institutions, bulk, smart accounts, automatic PIX, scheduled, smart transfers. These need their own credentials path and live in a separate domain, so they belong in a focused follow-up (#167).

package.json script tweaks

• test: ignores tests/integration (directory) instead of the deleted single file.
• test:integration: matches tests/integration explicitly.

Test plan

• pnpm build — clean.
• pnpm test — 11/11 passing (unit suite unchanged).
• pnpm test:integration without credentials — 13 suites, 31 tests, all auto-skipped.
• Nightly SDK Integration Tests workflow run against sandbox is green after merge.

🤖 Generated with Claude Code