Implement pagination cursors for SDK reads

[meshackyaro]

Description

This issue aims to address the implementation of Implement pagination cursors for SDK reads.

The core objective is to: Automatically handle paginated returns for .getGigs() matching backend schema.

By completing this feature, we will ensure that the TrustFlow protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the SDK Wrapper architecture and adherence to the existing project conventions.

When picking up this issue, please ensure you document any new dependencies or architectural decisions made during development.

Component

SDK Wrapper

Difficulty

🟡 Medium

Tasks

• Review existing Typescript abstract classes
• Implement SDK method for: Implement pagination cursors for SDK reads
• Ensure Tsup successfully exports to ESM and CJS
• Update typedoc comments for the new feature
• Write Jest tests validating XDR payloads
• Run npm run build to verify standard bundling

Acceptance Criteria

• Feature accurately implements the objective: Automatically handle paginated returns for .getGigs() matching backend schema.
• Any PR that introduces TypeScript/Rust errors is automatically blocked
• CI pipeline runs in under 3 minutes per PR
• Code is properly reviewed and approved by codeowners

Estimated Time

4-8 hours

[stephanieoghenemega-eng]

Went through the codebase before commenting. TrustFlowEscrowClient in src/escrow/client.ts has createEscrow, releaseEscrow, and getEscrow but no getGigs() at all. The client config already carries apiBaseUrl and apiKey on TrustFlowClient so the shape for hitting a backend endpoint is there, but ContractConfig (what the escrow client actually takes) doesn't expose those fields yet.

My plan:

Extend ContractConfig with optional apiBaseUrl and apiKey, then add a getGigs method to TrustFlowEscrowClient that builds a cursor-paginated request against the backend:

export interface GetGigsParams {
  cursor?: string;
  limit?: number;
  status?: 'pending' | 'active' | 'released' | 'disputed' | 'cancelled';
  depositor?: StellarAddress;
  beneficiary?: StellarAddress;
}

export interface GigsPage {
  data: EscrowState[];
  nextCursor: string | null;
  hasMore: boolean;
}

async getGigs(params: GetGigsParams = {}): Promise<SDKResult<GigsPage>> {
  if (!this.contractConfig.apiBaseUrl) {
    return { ok: false, error: 'apiBaseUrl is required to call getGigs' };
  }
  const query = new URLSearchParams();
  if (params.cursor)      query.set('cursor',      params.cursor);
  if (params.limit)       query.set('limit',       String(Math.min(params.limit, 100)));
  if (params.status)      query.set('status',      params.status);
  if (params.depositor)   query.set('depositor',   params.depositor);
  if (params.beneficiary) query.set('beneficiary', params.beneficiary);

  const res = await fetch(`${this.contractConfig.apiBaseUrl}/gigs?${query}`, {
    headers: { Authorization: `Bearer ${this.contractConfig.apiKey}` },
  });
  if (!res.ok) return { ok: false, error: `HTTP ${res.status}` };
  return { ok: true, data: await res.json() };
}

Traverse all pages:

let cursor: string | undefined;
do {
  const result = await client.getGigs({ cursor, limit: 20, status: 'active' });
  if (!result.ok) break;
  processBatch(result.data.data);
  cursor = result.data.nextCursor ?? undefined;
} while (cursor);

I'd cover this with Jest tests: missing apiBaseUrl error path, empty page, all query params forwarded correctly, limit capped at 100, Authorization header present, multi-page cursor traversal, non-2xx error handling. tsup outputs ESM+CJS already so no bundling changes needed.

Happy to take this.

[grantfox-oss]

🦊 GrantFox — @stephanieoghenemega-eng has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #24)
2. Your PR will be reviewed by the trustflow-protocol maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@stephanieoghenemega-eng's PR #61 was approved and merged by @meshackyaro.

🏆 @stephanieoghenemega-eng: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (156 total points). Track your full progress on GrantFox.

👏 Great work, @stephanieoghenemega-eng! Keep contributing to trustflow-protocol.