Skip to content

fix(node-sdk): declare @x402/fetch as an optional peer dependency - #191

Open
rohitsux wants to merge 1 commit into
agentmail-to:mainfrom
rohitsux:fix/x402-optional-peer-dep
Open

fix(node-sdk): declare @x402/fetch as an optional peer dependency#191
rohitsux wants to merge 1 commit into
agentmail-to:mainfrom
rohitsux:fix/x402-optional-peer-dep

Conversation

@rohitsux

Copy link
Copy Markdown

Fixes agentmail-to/agentmail-node#24.

Problem

The node SDK's wrapper lazily imports @x402/fetch (src/wrapper/x402.ts, src/wrapper/Client.ts) for the opt-in payments feature, but the package is not declared anywhere in package.json. As the issue lays out, that phantom dependency breaks bundlers (unresolvable-import errors), file tracers such as @vercel/nft (a configured external must be resolvable on disk), and isolated installers (pnpm, bun), forcing consumers to carry externalization workarounds. The wrapper's own src/wrapper/x402-types.d.ts module shim exists precisely because TypeScript cannot resolve the undeclared package.

Why the fix is here and not in agentmail-node

package.json in agentmail-node is Fern-generated and not listed in .fernignore, so declaring the dependency there directly would be overwritten on the next regeneration. The generator config in this repo is the durable layer: the packageJson block's fields (description, keywords, license) already flow into the published package, and the TypeScript generator supports extraPeerDependencies / extraPeerDependenciesMeta for exactly this case.

Change

extraPeerDependencies:
  "@x402/fetch": "^2"
extraPeerDependenciesMeta:
  "@x402/fetch":
    optional: true

This keeps payments opt-in (consumers install @x402/fetch only if they use the feature) while making the import visible to every toolchain. All published @x402/fetch versions are 2.x, and the wrapper uses only x402HTTPClient and wrapFetchWithPayment, both stable across 2.x.

Verification

npx fern-api check: 0 errors, 9 warnings — identical to unmodified main (the warnings are pre-existing).

Follow-up (out of scope here)

Once this is released, src/wrapper/x402-types.d.ts in agentmail-node could be dropped in favor of the real types from the now-resolvable package.

The node SDK's hand-written wrapper (src/wrapper/x402.ts and
src/wrapper/Client.ts) lazily imports @x402/fetch for the opt-in payments
feature, but the package was not declared anywhere in package.json. That
makes it a phantom optional dependency: bundlers fail with
unresolvable-import errors, file tracers cannot materialize the dependency
closure, and isolated installers (pnpm, bun) guarantee phantom resolution
never works. The wrapper even ships a local module declaration
(src/wrapper/x402-types.d.ts) to paper over TypeScript being unable to
resolve the undeclared package.

package.json in agentmail-node is Fern-generated and not covered by
.fernignore, so the durable fix lives here in the generator config:
extraPeerDependencies plus extraPeerDependenciesMeta mark @x402/fetch as an
optional peer, keeping the payments feature opt-in while letting every
toolchain see and resolve the import. All published @x402/fetch versions
are 2.x, matching the caret range.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Declare @x402/fetch as an optional peer dependency (undeclared dynamic import breaks bundlers/tracers)

1 participant