Build a runtime-safe GuildPass client configuration parser

[Lakes41]

Difficulty: Advanced
Type: Feature
Recommended labels (if available in this repo): config, type-safety, backend, advanced

Background

GuildPass SDK consumers will configure values such as API base URLs, request timeouts, and network settings. Runtime configuration should be validated once when a client is created instead of failing much later during requests.

This issue introduces a standalone client configuration parser.

Problem

The current GuildPassClientOptions only stores a base URL string and performs no meaningful runtime validation.

Invalid URLs, unsupported schemes, negative timeout values, or mutated configuration objects could cause inconsistent failures elsewhere in the SDK.

Expected Outcome

Implement a runtime-safe configuration parser that converts user-provided client options into an immutable canonical configuration object.

Suggested Implementation

A public input may conceptually include:

interface GuildPassClientOptions {
  baseUrl: string;
  timeoutMs?: number;
  headers?: Record<string, string>;
}

The parser should:

• validate the base URL using the URL API;
• allow only documented protocols such as https: and optionally http: for local development;
• reject embedded usernames and passwords;
• remove URL fragments;
• normalise trailing slashes consistently;
• validate timeout values as finite positive integers within a documented maximum;
• defensively copy caller-provided headers;
• normalise header names where useful;
• prevent mutation of the final internal configuration;
• reject dangerous or invalid header values such as embedded newline characters;
• provide sensible defaults for omitted optional fields;
• expose typed validation errors rather than generic exceptions.

Acceptance Criteria

• Valid HTTPS base URLs are accepted.
• Invalid URLs are rejected.
• Unsupported protocols are rejected.
• Embedded URL credentials are rejected.
• Trailing-slash behaviour is deterministic and tested.
• Invalid, negative, zero, NaN, and excessively large timeout values are rejected.
• Default timeout behaviour is documented and tested.
• Caller mutation of the original options object after client construction does not mutate internal configuration.
• Invalid header names or values are rejected safely.
• Public configuration types remain strongly typed.
• Unit tests cover valid, invalid, boundary, and mutation scenarios.
• pnpm typecheck passes.
• pnpm build passes.
• pnpm test passes.
• No HTTP requests are made by this module.

Likely Affected Files/Directories

src/config/
src/client/
src/errors/
tests/

Independence Requirement

This issue must not depend on the HTTP transport issue or any GuildPass endpoint implementation.

[GiftedGiftB]

Hi maintainer, I can get this work done in less than 24 hours.

[s6pa1rta3n-lab]

/try