Add Request ID Exposure for API Responses

[Lakes41]

Difficulty: Advanced

Type: Feature

Summary

Expose safe response metadata such as request IDs so SDK consumers can correlate client-side failures with backend logs and support tickets.

Current Behaviour

SDK service methods return typed data objects and throw GuildPassError on failures, but successful calls do not expose response metadata. If the backend returns headers such as X-Request-ID, X-Correlation-ID, or Traceparent, consumers have no clear way to access those values for diagnostics.

Expected Behaviour

Consumers should be able to access safe response metadata when they need it, without changing the default ergonomic service method return values.

Suggested Implementation

Add an optional request option such as includeMeta: true or provide parallel methods that return { data, meta }. Capture safe headers like request ID, correlation ID, trace ID, status, and duration. Keep the default API backwards-compatible by returning plain data unless metadata is explicitly requested.

Files or Areas Likely Affected

• src/http/httpClient.ts
• src/http/http.types.ts
• src/types/common.ts
• src/access/access.service.ts
• src/membership/membership.service.ts
• src/roles/roles.service.ts
• src/guilds/guilds.service.ts
• docs/sdk-guide.md
• tests/

Acceptance Criteria

• SDK consumers can opt into response metadata.
• Default service method behaviour remains backwards-compatible.
• Request ID or correlation ID headers are captured when present.
• Metadata does not expose API keys or sensitive headers.
• Error paths preserve useful request metadata where safe.
• Documentation shows how to use response metadata for support/debugging.
• Tests cover success, error, and missing-header cases.

Additional Notes

Do not make every service return a new shape by default. This should be an opt-in diagnostic feature to avoid breaking existing consumers.

[chidii]

Hi Maintainer, haven reviewed the description of the issue, and well experienced with it,
I would like to hop on the issue and sure to deliver at ETA 2hrs

[clintjeff2]

Hello, I have 6 years of experience working on tasks like this and handling similar challenges across backend, frontend, and smart-contract development. I have carefully read and fully understood the task requirements, and I am confident I can deliver a clean, efficient, and well-tested solution promptly. I always ensure high-quality implementation, maintainability, and adherence to best practices.

ETA 2 hours

[OTobi21]

I'd love to build this surfacing request IDs and trace headers is exactly the kind of small addition that turns a frustrating support ticket into a five-minute diagnosis.

I'd add an opt-in includeMeta option to request calls so the default return shape stays completely unchanged for existing consumers. When opted in, safe headers like X-Request-ID, X-Correlation-ID, Traceparent, status, and duration get captured and returned alongside the data. Sensitive headers never make it through. Error paths preserve whatever metadata is available. Tests cover success, error, and missing-header cases, and the SDK guide gets a clear debugging example showing how to pull a request ID for a support ticket.

[GBOYEE]

The SDK service methods return typed data but drop response headers like X-Request-ID and Traceparent — makes it hard to correlate client failures with backend logs.

Plan:

• Add includeMeta?: boolean option to request options in src/http/http.types.ts
• When true, service methods return { data, meta } where meta contains safe headers (request ID, correlation ID, trace ID, status, duration)
• Default behavior unchanged (backwards compatible)
• Capture timing via performance.now() around the fetch call
• Add tests in the existing service test files

Requesting assignment, PR same day.

[jesutobaadedejidev]

I would like to work on this. Do assign it to me.

[AbuJulaybeeb]

Hi Maintainer, haven reviewed the description of the issue, and well experienced with Js Library,
I would like to hop on the issue and sure to deliver at ETA 2hrs

[Yerimahjr]

I recently completed PR #140 on this repo (partial retry config validation — just submitted). Familiar with the codebase including httpClient.ts, http.types.ts, and the service layer.
For this issue I'll add an includeMeta: true request option to HttpRequestOptions, capture safe headers (X-Request-ID, X-Correlation-ID, Traceparent, status, duration) in httpClient.ts, add a WithMeta wrapper type returning { data: T, meta: ResponseMeta }, update service methods to support the opt-in path, preserve backward compatibility so default calls still return plain data, and document the feature in docs/sdk-guide.md. Tests will cover success with meta, error paths, and missing headers.
30 minutes pr delivered

[akinboyewaSamson]

Hello,

I’m a smart contract and full-stack developer interested in contributing to this issue. My technical background includes Rust, Soroban, Cairo, Solidity, and TypeScript, with a focus on building secure, scalable, and maintainable blockchain applications.

Based on the scope of this issue, I’m confident I can deliver a complete and well-tested solution within 10hours of assignment. I prioritize clean code, clear documentation, and efficient implementation.

I’d appreciate the opportunity to contribute and help move this issue forward.

Thank you.

[akinboyewaSamson]

Hello,

I’m a smart contract and full-stack developer interested in contributing to this issue. My technical background includes Rust, Soroban, Cairo, Solidity, and TypeScript, with a focus on building secure, scalable, and maintainable blockchain applications.

Based on the scope of this issue, I’m confident I can deliver a complete and well-tested solution within 10hours of assignment. I prioritize clean code, clear documentation, and efficient implementation.

I’d appreciate the opportunity to contribute and help move this issue forward.

Thank you.

[grantfox-oss]

🦊 GrantFox — @OTobi21 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 #128)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.