feat: support executor callback overrides on WormholeConfig

[kev1n-peters]

Allow users to pass a getCapabilities callback when constructing the Wormhole SDK object so every route can use it without per-route config.

Summary by CodeRabbit

• New Features
  • Added optional custom executor capabilities fetcher so users can supply their own async capability retrieval.
• Behavior Changes
  • Configuration partials now preserve function-typed properties (function types remain intact in overrides), improving type accuracy and developer ergonomics.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds an optional executor.getCapabilities config hook and updates Wormhole.getExecutorCapabilities() to call that hook when present; otherwise it falls back to existing fetchCapabilities behavior. Adjusts RecursivePartial<T> to preserve function-typed properties.

Changes

Cohort / File(s)	Summary
Configuration Type Updates connect/src/config.ts	Added optional executor?: { getCapabilities?: (network: Network) => Promise<CapabilitiesResponse> } to WormholeConfig; updated RecursivePartial<T> to preserve function types; imported CapabilitiesResponse.
Executor Capability Delegation connect/src/wormhole.ts	Wormhole.getExecutorCapabilities() now delegates to this.config.executor?.getCapabilities(this._network) when available, otherwise calls fetchCapabilities(this.config.executorAPI).

Sequence Diagram(s)

sequenceDiagram
  participant Client as Client
  participant Wormhole as Wormhole.getExecutorCapabilities
  participant Executor as Config.executor.getCapabilities (optional)
  participant API as fetchCapabilities(API)

  Client->>Wormhole: request executor capabilities
  alt executor.getCapabilities configured
    Wormhole->>Executor: getCapabilities(network)
    Executor-->>Wormhole: CapabilitiesResponse
  else no executor hook
    Wormhole->>API: fetchCapabilities(executorAPI)
    API-->>Wormhole: CapabilitiesResponse
  end
  Wormhole-->>Client: return capabilities

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• feat: group executor overrides under executor namespace on Config #993 — Implements the same executor.getCapabilities config override and threads its use through executor/quote/gas-related flows.

Suggested reviewers

• connorstake

Poem

🐰 A rabbit hops into config bright,

I gave the executor a new light,
Functions stay whole, types keep their cheer,
Capabilities fetched — now local or near,
Hooray for hooks, and code that’s clear! 🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: adding executor callback overrides to WormholeConfig, which aligns with the file changes and PR objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch kevin/executor-config-overrides

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[kev1n-peters]

@claude review this pr and make sure no bugs were introduced, and the getCapabilities callback will work correctly when passed in

[github-actions]

Claude finished @kev1n-peters's task in 2m 16s —— View job

---

Review of PR #997

• Gather context and read changed files
• Review connect/src/config.ts changes
• Review connect/src/wormhole.ts changes
• Verify getCapabilities callback works correctly through the override system
• Post review findings

---

Verdict: Looks good, no bugs found ✅

I reviewed both changed files and traced the full execution path through the override system. The getCapabilities callback will work correctly when passed in.

Detailed Analysis

1. Runtime override merging works correctly (config.ts:94-104)

The override() function uses typeof value === "object" to decide whether to recurse. Since typeof someFunction === "function" (not "object"), a user-provided getCapabilities callback flows through the else branch and gets assigned directly. When a user passes:

new Wormhole("Mainnet", platforms, {
  executor: { getCapabilities: myCustomFetcher }
})

• executor (object) → recurses into it, creating a new executor object on the base config
• getCapabilities (function) → directly assigned as-is

2. RecursivePartial<T> type fix is necessary and correct (config.ts:58-59)

The new check T[P] extends (...args: any[]) => any ? T[P] before the object | undefined check prevents TypeScript from recursively expanding function types into their property keys. Without this, RecursivePartial<(network: Network) => Promise<CapabilitiesResponse>> would break the callback type signature.

3. Optional chaining in getExecutorCapabilities is correct (wormhole.ts:455)

this.config.executor?.getCapabilities safely handles the case where executor is undefined (which it will be when no override is provided, since the base CONFIG constant doesn't include it).

4. Two-level override precedence is clean

This PR complements PR #993 nicely:

1. Route-level (ExecutorTokenBridgeRoute.Config.executor.getCapabilities) → used directly if provided
2. Global-level (WormholeConfig.executor.getCapabilities) → checked by wh.getExecutorCapabilities() as fallback
3. Default → fetchCapabilities(this.config.executorAPI)

The route-level functions (quoteTransfer, getExecutorGasDropOffLimit) check their own getCapabilities param first, then fall back to wh.getExecutorCapabilities(), which now respects the global config. This is the expected precedence.

One Minor Observation (not a bug)

getExecutorQuote() and getExecutorTxStatus() in wormhole.ts don't have override support yet. This is presumably intentional since they're request-specific (not easily cacheable), but worth noting for consistency if the override pattern is extended later.

---

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

connect/src/config.ts (1)

17-20: Tighten callback typing to the config’s network generic.

Line 19 currently accepts Network; using N preserves stronger compile-time guarantees for per-network configs.

♻️ Suggested type refinement

   executor?: {
     /** Override the default capabilities fetcher (e.g. to cache or use a custom endpoint). */
-    getCapabilities?: (network: Network) => Promise<CapabilitiesResponse>;
+    getCapabilities?: (network: N) => Promise<CapabilitiesResponse>;
   };

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@connect/src/config.ts` around lines 17 - 20, The getCapabilities callback on
executor currently accepts the concrete Network type; tighten it to the config's
network generic by changing its parameter to the generic (N) used by the
surrounding config so the signature is getCapabilities?: (network: N) =>
Promise<CapabilitiesResponse>; update the executor type declaration
(executor.getCapabilities) and any call sites to accept/forward the generic N
instead of the concrete Network to preserve per-network type guarantees.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@connect/src/config.ts`:
- Around line 58-61: The RecursivePartial type incorrectly treats optional
function properties (e.g., executor?.getCapabilities) as objects because the
function branch fails for unions with undefined; update the conditional to
detect functions after removing undefined using NonNullable (e.g., change the
function check to use NonNullable<T[P]> extends (...args: any[]) => any) so
optional function properties are preserved as functions rather than recursing
into object types; locate the RecursivePartial type in connect/src/config.ts and
adjust its conditional branches accordingly.

---

Nitpick comments:
In `@connect/src/config.ts`:
- Around line 17-20: The getCapabilities callback on executor currently accepts
the concrete Network type; tighten it to the config's network generic by
changing its parameter to the generic (N) used by the surrounding config so the
signature is getCapabilities?: (network: N) => Promise<CapabilitiesResponse>;
update the executor type declaration (executor.getCapabilities) and any call
sites to accept/forward the generic N instead of the concrete Network to
preserve per-network type guarantees.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 89a310db-c327-48ad-9cd3-80b8a4e1eb67

📥 Commits

Reviewing files that changed from the base of the PR and between 0ccc9eb and 6f969d1.

📒 Files selected for processing (2)

• connect/src/config.ts
• connect/src/wormhole.ts

✅ Files skipped from review due to trivial changes (1)

• connect/src/wormhole.ts