feat(access): implement client.access.check API and AccessDecision types (closes #495)

[rupesh-kumar-sah]

Description

Implements the strongly typed client.access.check() operation on GuildPassClient along with canonical AccessDecision and AccessCheckRequest domain types.

Key implementation characteristics:

1. Access Resource Layer: Introduced AccessResource mounted on GuildPassClient.access exposing .check(request: AccessCheckRequest): Promise<AccessDecision>.
2. Canonical Domain Types: Strongly typed AccessCheckRequest and AccessDecision (allowed: boolean, reason?: string, metadata?: Record<string, unknown>).
3. Stellar Identifier Support: Fully interoperable with both plain Stellar account string addresses and strongly-branded StellarAccountId.
4. Core Evaluation Delegation: Policy evaluation remains purely within GuildPass Core; the SDK cleanly forwards parameters (guildId, account, resource, action, context) without duplicating evaluation rules.
5. Normal Decision Representation on Denial: Gracefully represents HTTP 403 access denial responses as normal { allowed: false, reason: ... } decision objects rather than throwing raw errors.
6. Preserved Typed SDK Errors: Real transport and network failures (HTTP 400/500, network loss, timeouts, cancellations) strictly preserve typed SDK errors (HttpError, NetworkError, TimeoutError).

Semver impact: minor

Linked Issue

Closes #495

Type of Change

• ✨ New feature / method (minor)

Changes Made

• src/types/access.ts: Define AccessCheckRequest and canonical AccessDecision interfaces.
• src/types/index.ts: Re-export access domain types.
• src/resources/access.ts: Implement AccessResource with .check() logic, request normalization, and denial formatting.
• src/resources/index.ts: Re-export AccessResource.
• src/client/index.ts: Mount AccessResource under client.access using existing HttpTransport instance and configured headers.
• src/index.ts: Export resources module.
• tests/resources/access.test.ts: Added 15 comprehensive unit tests covering allowed, denied, error handling, Stellar ID support, context forwarding, and header propagation.

Public API Changes

// New exported types and resources:
export interface AccessCheckRequest {
  guildId: string;
  account: string | StellarAccountId;
  resource?: string;
  action?: string;
  context?: Record<string, unknown>;
}

export interface AccessDecision {
  allowed: boolean;
  reason?: string;
  guildId?: string;
  account?: string;
  resource?: string;
  action?: string;
  metadata?: Record<string, unknown>;
}

export class AccessResource {
  check(request: AccessCheckRequest): Promise<AccessDecision>;
}

// Added to GuildPassClient:
public readonly access: AccessResource;

Test Evidence

 ✓ tests/resources/access.test.ts (15 tests) 107ms
 Test Files  23 passed (23)
      Tests  680 passed (680)
   Duration  5.48s

Build Evidence

> tsc --noEmit
> tsup
ESM dist/index.js     74.08 KB
DTS dist/index.d.ts   57.29 KB
⚡️ Build success in 511ms

Checklist

• I have read CONTRIBUTING.md
• This PR is linked to an open issue (Implement access-check APIs in GuildPass SDK V2 #495)
• tsc --noEmit passes
• vitest run passes — all 680 tests green (15 new tests)
• tsup build succeeds — dist/ generated cleanly
• All new public methods/types have TypeDoc comments
• New behaviour is covered by comprehensive Vitest unit tests
• No new runtime dependencies added
• Backwards compatibility 100% maintained