sentryagent-idp/openspec/changes/archive/2026-03-28-nodejs-sdk/design.md

Context

The SDK wraps the AgentIdP REST API. It must handle authentication transparently — caller provides clientId + clientSecret, SDK manages token acquisition and refresh automatically.

Architecture

• Single entrypoint: sdk/src/index.ts exports AgentIdPClient and all types
• AgentIdPClient constructor takes { baseUrl, clientId, clientSecret }
• Internal TokenManager handles token acquisition, caching, and refresh (re-issues when expired)
• Four service classes: AgentRegistryClient, CredentialClient, TokenClient, AuditClient
• AgentIdPClient composes all four
• HTTP: native fetch (Node 18+ built-in) — no axios dependency
• Types: re-exported from sdk/src/types.ts — mirrors the main app types

Standards

• TypeScript strict mode, zero any
• DRY: shared request() helper handles auth header, JSON parse, error mapping
• All errors are typed AgentIdPError with code and message
• JSDoc on all public methods

Package structure

sdk/
  src/
    index.ts          — exports AgentIdPClient + all types
    client.ts         — AgentIdPClient (composes all services)
    token-manager.ts  — token acquisition and refresh
    services/
      agents.ts       — AgentRegistryClient
      credentials.ts  — CredentialClient
      token.ts        — TokenClient
      audit.ts        — AuditClient
    types.ts          — all request/response types
    errors.ts         — AgentIdPError class
  package.json
  tsconfig.json
  README.md

Open Questions

(none)