sentryagent-idp/openspec/changes/nodejs-sdk/design.md at aa5167835e3ea527c1f318601796308e5672068e

Files

SentryAgent.ai Developer aa5167835e feat: Phase 1 P1 — Dockerfile, AGNTCY alignment docs, Node.js SDK

Three remaining Phase 1 P1 deliverables:

1. Dockerfile — multi-stage build (builder + production), node:18-alpine,
   non-root USER node, .dockerignore excluding secrets and dev artifacts

2. AGNTCY alignment docs (docs/agntcy/) — README and alignment.md mapping
   all 6 AGNTCY domains to AgentIdP features with Phase 2/3 pending items noted

3. Node.js SDK (@sentryagent/idp-sdk) — TypeScript strict, zero any, native
   fetch (Node 18+), TokenManager with 60s auto-refresh, service clients for
   all 14 endpoints (agents, credentials, tokens, audit), AgentIdPError typed
   error hierarchy, full README

All three changes tracked under openspec/changes/ with tasks marked complete.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-28 14:46:53 +00:00

1.5 KiB

Raw Blame History

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)

1.5 KiB Raw Blame History