feat: add filecoin pay funding planner

[SgtPooki]

Summary

Expose Filecoin Pay funding logic as a reusable core API, refactor CLI funding to use it, and add coverage/docs. Remove legacy top-up calc in favor of the new planner.

What Changed

• Added planFilecoinPayFunding, executeFilecoinPayFunding, and getFilecoinPayFundingInsights in src/core/payments/funding.ts, exported via core/payments.
• Updated funding types (FilecoinPayFundingPlan/Execution/Insights, options) and refactored payments fund / auto-fund to consume the new API.
• Documented the planner/executor in src/core/payments/README.md with usage examples.
• Added unit tests for the planner (wallet shortfall, minimum/no-withdraw, zero-spend) and executor deposit path.

Removal

• Removed calculateRequiredTopUp/formatTopUpReason path to avoid duplication; callers should use planFilecoinPayFunding + executeFilecoinPayFunding.

[Copilot]

Pull request overview

This PR introduces a comprehensive Filecoin Pay funding planner API that consolidates and improves upon the legacy top-up calculation logic. The new API provides a cleaner separation between planning (calculation) and execution phases, with detailed insights about current and projected funding states.

Key changes:

• Added planFilecoinPayFunding, executeFilecoinPayFunding, and getFilecoinPayFundingInsights as the new core funding APIs
• Removed legacy calculateRequiredTopUp and formatTopUpReason functions to eliminate duplication
• Refactored CLI payments fund and auto-fund commands to use the new planner
• Added comprehensive unit tests covering wallet shortfall detection, minimum mode, and zero-spend scenarios

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/core/payments/funding.ts	New file introducing the funding planner with calculation, planning, and execution functions
src/core/payments/types.ts	Added new types (FundingMode, FundingReasonCode, FilecoinPayFundingPlan, etc.) and updated documentation for existing types
src/core/payments/index.ts	Exports new funding module (export * from './funding.js')
src/core/payments/top-up.ts	Removed calculateRequiredTopUp and formatTopUpReason, kept executeTopUp for backward compatibility
src/core/payments/README.md	Added documentation and usage examples for the new funding planner API
src/payments/types.ts	Updated to re-export FundingMode from core, replaced deprecated FundMode type
src/payments/fund.ts	Refactored to use planFilecoinPayFunding and executeFilecoinPayFunding, but contains a critical bug with parameter passing
upload-action/src/filecoin.js	Migrated to use calculateFilecoinPayFundingPlan and formatFundingReason
upload-action/package-lock.json	Version bump from 0.13.0 to 0.14.0 reflecting the minor version change
src/test/unit/payments-funding.test.ts	New comprehensive unit tests for the funding planner functions

Files not reviewed (1)

• upload-action/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rvagg]

I guess this is OK, I haven't reviewed it all in depth, if it works in practice I'll take your word for it!

[rjan90]

@SgtPooki Is this good to merge now? Or is there other work that you want landed first?

[SgtPooki]

@rjan90 this is ready to merge once all tests pass here.