feat(sdk): TypeScript SDK — New Package, Publish to NPM

[sangalo20]

Overview

There is currently no TypeScript/JavaScript SDK for the Nexus Gateway. TypeScript is the dominant language for MCP server development and a large portion of AI agent tooling. A first-class TypeScript SDK is essential.

Problem

• No TypeScript SDK exists
• The nexus-mcp-adapter currently uses a mock token implementation
• MCP server and TypeScript agent developers must hand-roll Gateway HTTP calls

Proposed Solution

Build a new TypeScript SDK and publish to NPM as nexus-sdk.

Target interface

import { NexusClient } from 'nexus-sdk'

const nexus = new NexusClient({ gatewayUrl: 'https://nexus-gateway.acme.com' })

// Standard agent session
const session = await nexus.requestAgentSession({
  agentId: 'crm-agent',
  provider: 'salesforce',
  scopes: ['crm:contacts:read'],
  ttl: 900,
})
// session.accessToken, session.expiresAt, session.scopesGranted

// Use the token
const response = await fetch('https://api.salesforce.com/v1/contacts', {
  headers: { Authorization: `Bearer ${session.accessToken}` }
})

// OBO session
const obo = await nexus.requestOBOSession({
  agentId: 'ops-agent',
  provider: 'internal-ops',
  scopes: ['acme:gliding'],
  userContextToken: req.headers['x-user-token'],
})
// obo.actingFor, obo.tenantId, obo.clearanceLevel

// Close when done
await nexus.closeAgentSession(session.sessionId)

Installation

npm install nexus-sdk

Tasks

• Create nexus-sdk-ts/ directory in the monorepo (or separate repo)
• Implement NexusClient class against the Gateway REST API
• Implement requestConnection(), checkConnection(), waitForActive(), getToken(), refreshConnection()
• Implement requestAgentSession(), requestOBOSession(), closeAgentSession(), getAgentSession() (depends on P1/P2)
• Wire the real implementation into nexus-mcp-adapter (replace the mock fetchTokenFromGateway)
• Add retry logic with exponential backoff
• Full TypeScript types for all request/response shapes
• Publish to NPM as nexus-sdk

Priority

P4 — Medium effort

Reference

AGENT_AUTH_PROPOSAL.md — Proposal 5 (TypeScript)