feat: accept the native fetch directly as the HTTPProvider fetch option

[LautaroPetaccio]

Problem

HTTPProvider's FetchFunction option typed its params with mode?: string:

export type FetchFunction = (url: string, params: { body?: any; method?: string; mode?: string; headers?: any }) => Promise<any>

The global native fetch types its init as RequestInit, whose mode is RequestMode (a string union). Since string is not assignable to RequestMode, the native fetch is not assignable to FetchFunction, so every caller has to cast:

new HTTPProvider(url, { fetch: fetch.fetch as unknown as FetchFunction })   // 👎 cast

Fix

HTTPProvider never sets mode (it only sends body/method/headers), so the field is dead weight. Dropping it makes the option accept, with no cast:

• the global native fetch — the same WHATWG signature on web and server;
• native-fetch components (e.g. @dcl/fetch-component's fetch);
• and node-fetch (still assignable — existing callers keep compiling).

new HTTPProvider(url, { fetch: globalThis.fetch })   // ✅ no cast

This is a type-only change — the emitted JS is identical, so there is no runtime/behavior change.

Tests

Added compile-time assertions in test/HTTPProvider.spec.ts that globalThis.fetch and a native-fetch-component-shaped function are assignable to the option without a cast. The existing node-fetch integration spec still typechecks.

Verification

• tsc src + full test project (incl. the node-fetch integration spec): clean
• unit suite: 10/10
• make build: succeeds; API report regenerated (idempotent) and committed; docs updated
• lint: clean

Follow-up

Once published, consumers can drop their as unknown as FetchFunction casts (e.g. archipelago-workers' ws-connector).

🤖 Generated with Claude Code

[github-actions]

Test this pull request

• The package can be tested by running

  yarn upgrade "https://sdk-team-cdn.decentraland.org/"

[decentraland-bot]

Review — feat: accept the native fetch directly as the HTTPProvider fetch option

Summary

Clean, well-motivated type-only change. Removes the unused mode?: string field from the exported FetchFunction type so that globalThis.fetch, @dcl/fetch-component, and node-fetch are directly assignable without casts.

Analysis

Type safety: The params object type is in contravariant position (parameter of the callback). Removing an optional field that HTTPProvider never sets makes the callback type strictly wider — more functions satisfy it, none are excluded. This is not a breaking change for any consumer that passes a fetch implementation.

Consumer impact: Searched across the org:

• decentraland/lamb2 — imports FetchFunction and currently casts with as unknown as FetchFunction, with a comment at src/components.ts:141-143 explaining exactly this type mismatch. After this publishes, lamb2 can drop the cast. ✅
• decentraland/governance / governance-ui — have unrelated local fetchFunction definitions, not importing from eth-connect. No impact.
• No consumers found that reference mode in the params object.

Runtime impact: None. The emitted JS is identical — mode was never set by HTTPProvider (it only sets body, method, headers).

Tests: Good approach — compile-time assertions that globalThis.fetch and a @dcl/fetch-component-shaped function are assignable without casts. Existing tests unaffected. CI passes.

Docs & API report: Updated consistently with the type change.

Git conventions (ADR-6): PR title (feat: ...) and branch (feat/fetchfunction-accept-native-fetch) both comply.

Security: No security issues found. Type-only change with no runtime impact.

Verdict

No P0 or P1 findings. LGTM — approve.

---

Reviewed by Jarvis 🤖 · Requested by Lautaro Petaccio via Slack