How hyperspell/node-sdk works
Project type & purpose
• It’s an open-source, TypeScript/JavaScript SDK (client library) for the Hyperspell REST API, plus a secondary “mcp-server” server package.
• Primary use: embed import Hyperspell from 'hyperspell' into Node/Deno/Bun/web code to call Hyperspell endpoints.
File structure
• Top-level: config files (tsconfig*.json, .eslintrc.js, GitHub Actions workflows), build & utility scripts (scripts/), CLI helpers (bin/), examples (examples/), and two code trees:
– Root src/ → the Hyperspell client library
– packages/mcp-server/ → a standalone HTTP server for “micro-tool” plugins and mock implementations
• tests/ & packages/mcp-server/tests/: unit/integration tests
• scripts/: orchestrate build, lint, test, bootstrap, publish
• GitHub workflows: CI, publish-to-npm, release automation
Extract insights from README
• Core functionality: typed Request/Response, auto-pagination, retries, timeouts, file-upload helpers, error subclasses
• Runtime shims: pluggable fetch implementations for Node, Deno, Bun, browsers
• Extensibility: direct client.get/post for undocumented endpoints; custom middleware
• Packaging: outputs multiple module formats (CJS/ESM/types), publishes to NPM
Main components & interactions (to show
A. Developer Application
– Your code imports Hyperspell and calls methods (e.g. client.documents.add(...)).
B. Hyperspell Client Library (root src/)
1. Core (core.ts, index.ts)
2. Resource modules (resources/*.ts) & dynamic tools loader (dynamic-tools.ts)
3. Request builder (params → HTTP Request object)
4. HTTP layer (uses fetch shim)
5. Response parser (error mapping → APIError subclasses)
C. Runtime Shims (src/_shims/*)
– Adapters for Node, Deno, Bun, Web fetch APIs; polyfills if needed
D. External Hyperspell REST API
– HTTPS endpoints (auth, documents, collections, integrations, query, etc.)
E. MCP-Server Package (packages/mcp-server/)
– Local server exposing a similar API for testing/micro-services
– Dynamic tool registration, auth & document handlers
– Exposes endpoints that mirror Hyperspell API for local dev or extended use
F. Build & Release Pipeline
– Scripts (scripts/), CI workflows (.github/workflows/*), publish to npm
Architectural patterns & design principles
• Modular layering:
– Separation of concerns between core logic, resource modules, transports (fetch), and environment shims
• Dependency injection: custom fetch, httpAgent, maxRetries, timeout
• Code generation: uses Stainless to generate resource stubs and types from API spec
• Monorepo pattern: two co-published packages sharing root config, scripts, and CI
• Blue rectangles for code modules (Core, Resources, Shims, MCP-Server)
• From Developer App → Client Library (method calls)
• From Client Library → Runtime Shims → HTTPS (fetch) → External API
• From CLI/CI → Build/Test/Publish → NPM Registry
• From Developer App → MCP-Server (when used locally)