Implement a stable GuildPass SDK error hierarchy with safe serialisation

[Lakes41]

Difficulty: Expert
Type: Feature
Recommended labels (if available in this repo): error-handling, backend, type-safety, expert

Background

A public SDK must give consuming applications reliable ways to distinguish configuration failures, validation failures, transport failures, API failures, and cancellation without depending on fragile error-message matching.

This issue introduces the SDK-wide error contract independently of any specific GuildPass feature.

Problem

The rebuilt SDK does not yet expose a stable error hierarchy or machine-readable error codes.

Future contributors could otherwise create unrelated custom error types, causing an inconsistent public API.

Expected Outcome

Create a small, documented SDK error hierarchy with stable error codes, safe causal chaining, and controlled JSON serialisation.

Suggested Implementation

Introduce a base error such as:

class GuildPassError extends Error {
  readonly code: GuildPassErrorCode;
  readonly cause?: unknown;
}

Potential categories may include:

CONFIGURATION_ERROR
VALIDATION_ERROR
TRANSPORT_ERROR
HTTP_ERROR
TIMEOUT
ABORTED
RESPONSE_ERROR

The exact public model should be intentionally small and justified.

The implementation should:

• use machine-readable error codes;
• preserve instanceof Error behaviour;
• set correct error names;
• support error causes without blindly exposing them in serialised output;
• allow safe metadata such as HTTP status where appropriate;
• prevent secrets, raw request headers, tokens, or arbitrary nested objects from leaking via toJSON;
• provide a reliable public type guard such as isGuildPassError;
• remain compatible with JavaScript consumers as well as TypeScript consumers;
• avoid dependency on specific transport or API modules.

Acceptance Criteria

• A public base GuildPass SDK error type exists.
• Stable machine-readable error codes are defined.
• Error subclasses or discriminated categories are intentionally limited and documented.
• instanceof Error and instanceof GuildPassError work correctly.
• Error cause information can be retained internally.
• Safe JSON serialisation omits unsafe cause content and secrets.
• A type guard can identify SDK errors reliably.
• Stack traces remain available in normal development use.
• Unit tests cover construction, inheritance, type guards, serialisation, and cause handling.
• Tests verify that unsafe arbitrary cause properties are not copied into serialised output.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No network request or domain endpoint implementation is included.

Likely Affected Files/Directories

src/errors/
src/index.ts
tests/

Independence Requirement

This issue must define the error model without requiring the transport or configuration issues to be merged first.

[Santia2004]

Hi team! I’d love to work on this issue. I have solid experience with the tech stack, understand the requirements, and can deliver a clean implementation with full test coverage following your project guidelines. Could you please assign this to me? Thanks!