feat(sdk-js): view bridge transaction history

[MicBun]

resolves: https://github.com/truflation/website/issues/3313

Summary by CodeRabbit

• New Features

  • Added wallet transaction history retrieval on bridges with pagination and a detailed history record type.

• Documentation

  • Added API reference and a runnable example showing history retrieval, formatting, and display.

• Tests

  • Added unit tests covering history retrieval behavior, null handling, and default pagination.

• Chores

  • Updated .gitignore and increased test harness timeout for CI stability.

[holdex]

Time Submission Status

Member	Status	Time	Action	Last Update
MicBun	✅ Submitted	4h	Update time	Feb 17, 2026, 9:36 PM

---

You can submit time with the command. Example:

@holdex pr submit-time 15m

See available commands to help comply with our Guidelines.

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

Adds a new BridgeHistory type and a public getHistory(bridgeIdentifier, walletAddress, limit?, offset?) API across Action and BaseTNClient, plus docs, an example, unit tests, a .gitignore entry, and an increased Vitest hookTimeout.

Changes

Cohort / File(s)	Summary
Types & Docs src/types/bridge.ts, docs/api-reference.md	Added exported BridgeHistory interface and documented client.getHistory(...) including params, return type, and example usage.
Core Implementation src/contracts-api/action.ts, src/client/client.ts	Added Action.getHistory(...) which calls <bridge>_get_history and BaseTNClient.getHistory(...) wrapper with default pagination (limit: 20, offset: 0).
Examples examples/history_example/index.ts	New TypeScript example demonstrating client init, fetching history, formatting/truncating addresses/hashes, timestamp formatting, and error handling.
Tests src/contracts-api/action.test.ts	Unit tests for getHistory verifying internal call endpoint/params, default pagination, and null→[] normalization.
Config & Misc vitest.config.ts, .gitignore	Increased Vitest hookTimeout (600000 → 900000). Added GEMINI.md to .gitignore.

Sequence Diagram

sequenceDiagram
    participant Client as Client App
    participant BaseTN as BaseTNClient
    participant Action as Action
    participant Bridge as Bridge Endpoint

    Client->>BaseTN: getHistory(bridgeId, wallet, limit, offset)
    BaseTN->>Action: load action / getHistory(bridgeId, wallet, limit, offset)
    Action->>Action: build params ($wallet_address, $limit, $offset)
    Action->>Bridge: call <bridge>_get_history
    Bridge-->>Action: BridgeHistory[] or null
    Action-->>BaseTN: normalized BridgeHistory[]
    BaseTN-->>Client: Promise<BridgeHistory[]>

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Possibly related PRs

• feat: bridge different kind of token in a chain #148 — touches the same core files (action.ts, client.ts, types/bridge.ts) and appears related to bridge/history API changes.

Suggested reviewers

• pr-time-tracker
• outerlook

Poem

🐰 I hopped through types and client code,
I fetched the history down the road,
With hashes trimmed and timestamps bright,
I logged each hop from left to right,
A little rabbit, bytes in tow.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main feature: adding functionality to view bridge transaction history, which is reflected across the added API method, types, documentation, and examples.

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

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch viewJsBridge

---

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.}

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

src/contracts-api/action.test.ts (1)

17-50: Test covers the happy path; consider adding edge-case coverage.

The delegation test is solid. Two cases worth adding when convenient:

1. Null/empty result normalization — verify that when the backend returns null, getHistory returns [] (the rows || [] fallback in action.ts).
2. Default parameters — call getHistory("bridge", "0x123") without limit/offset to confirm the defaults (20, 0) are forwarded.

🤖 Prompt for AI Agents

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

In `@src/contracts-api/action.test.ts` around lines 17 - 50, Add two new tests for
Action.getHistory: one where the mocked call (spy on Action.call) resolves to
Either.right(null) and assert getHistory(...) returns an empty array (exercise
the rows || [] branch), and another where you invoke
getHistory("bridge","0x123") without limit/offset and assert call was invoked
with defaults $limit: 20 and $offset: 0; reuse the existing pattern of spying on
action.call, mocking the resolved Either.right value, and asserting both the
call arguments and the returned value.

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@docs/api-reference.md`:
- Around line 632-634: The heading incorrectly attributes getHistory to
TransactionAction; update the docs to reference the correct owner: change
`transactionAction.getHistory(...)` to `client.getHistory(...)` (or
`action.getHistory(...)`) and ensure the text mentions that the method is
provided by Action (via client.loadAction()) and exposed on BaseTNClient as
`client.getHistory(...)`; also verify examples use `client.getHistory(...)`
consistently.
- Around line 656-669: Update the BridgeHistory documentation to match the
source type: change the to_address field to "string | null" (nullable) and
expand the type field to include 'transfer' in addition to 'deposit' and
'withdrawal'; ensure the doc block for the BridgeHistory interface reflects
these exact symbols (BridgeHistory, to_address, type) so it matches
src/types/bridge.ts JSDoc.

In `@src/types/bridge.ts`:
- Around line 79-133: BridgeHistory currently declares to_address as "string |
null" but the API docs treat it as non-nullable; make the type definition the
source of truth by changing the BridgeHistory interface's to_address property to
"string" (non-nullable) and update its JSDoc comment accordingly so the
interface (BridgeHistory and its to_address field) reflects that it always
contains a string.

---

Nitpick comments:
In `@src/contracts-api/action.test.ts`:
- Around line 17-50: Add two new tests for Action.getHistory: one where the
mocked call (spy on Action.call) resolves to Either.right(null) and assert
getHistory(...) returns an empty array (exercise the rows || [] branch), and
another where you invoke getHistory("bridge","0x123") without limit/offset and
assert call was invoked with defaults $limit: 20 and $offset: 0; reuse the
existing pattern of spying on action.call, mocking the resolved Either.right
value, and asserting both the call arguments and the returned value.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

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

Inline comments:
In `@docs/api-reference.md`:
- Around line 145-181: Move the misplaced getHistory docs from the "Stream
Querying" section into the "Bridge Operations" section so it sits alongside
related bridge methods; locate the documentation block for action.getHistory /
client.getHistory (the heading and code block beginning
"action.getHistory(bridgeIdentifier: string...") currently under the "Stream
Querying" heading and cut/paste it into the "Bridge Operations" section near the
docs for getWalletBalance, withdraw, and getWithdrawalProof to maintain
parameter and discoverability consistency. Ensure the heading level and
surrounding anchors/TOC entries remain consistent after relocation.