# hyperspell/node-sdk architecture

> Architecture diagram of the GitHub repository hyperspell/node-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hyperspell/node-sdk
- Repository: https://github.com/hyperspell/node-sdk

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Application
    DeveloperApp["Developer Application"]:::app

    %% Client Library Layer
    subgraph "Client Library" 
        direction TB
        Core["Core (core.ts, index.ts)"]:::codeModule
        Resources["Resource Modules"]:::codeModule
        DynamicLoader["Dynamic Tools Loader"]:::codeModule
        RequestBuilder["Request Builder & Pagination"]:::codeModule
        ErrorHandling["Error Handling & Response Parser"]:::codeModule
    end

    %% Runtime Shims
    subgraph "Runtime Shims" 
        direction TB
        ShimsIndex["Shims Index"]:::shims
        MultipartBody["MultipartBody"]:::shims
        RuntimeNode["Node Runtime"]:::shims
        RuntimeDeno["Deno Runtime"]:::shims
        RuntimeBun["Bun Runtime"]:::shims
        RuntimeWeb["Web Runtime"]:::shims
    end

    %% External Hyperspell REST API
    ExternalAPI[(External Hyperspell REST API)]:::externalApi

    %% MCP-Server Package
    subgraph "MCP-Server Package" 
        direction TB
        MCPIndex["Index"]:::codeModule
        MCPServer["Server"]:::codeModule
        MCPDynamic["Dynamic Tools"]:::codeModule
        MCPCompat["Compatibility"]:::codeModule
        MCPOptions["Options"]:::codeModule
        MCPTools["Tools"]:::codeModule
    end

    %% CI/CD & Pipelines
    subgraph "Build/Test/Publish Pipeline"
        direction TB
        Scripts["Scripts"]:::pipeline
        Workflows["GitHub Workflows"]:::pipeline
        Bin["CLI Helpers"]:::pipeline
        NpmRegistry[(npm Registry)]:::externalApi
    end

    %% Connections
    DeveloperApp -->|"import Hyperspell & calls"| Core
    Core --> Resources
    Resources --> DynamicLoader
    DynamicLoader --> RequestBuilder
    RequestBuilder --> ErrorHandling
    ErrorHandling --> ShimsIndex
    ShimsIndex --> MultipartBody
    MultipartBody --> RuntimeNode
    RuntimeNode --> RuntimeDeno
    RuntimeDeno --> RuntimeBun
    RuntimeBun --> RuntimeWeb
    RuntimeWeb --> ExternalAPI
    DeveloperApp -->|"local dev calls"| MCPServer
    MCPServer --> MCPDynamic
    MCPDynamic --> MCPTools
    MCPTools --> MCPCompat
    MCPCompat --> MCPOptions
    Scripts --> Workflows
    Workflows --> Bin
    Bin --> NpmRegistry

    %% Click Events - Client Library
    click Core "https://github.com/hyperspell/node-sdk/blob/main/src/core.ts"
    click Core "https://github.com/hyperspell/node-sdk/blob/main/src/index.ts"
    click Resources "https://github.com/hyperspell/node-sdk/blob/main/src/resources/index.ts"
    click Resources "https://github.com/hyperspell/node-sdk/blob/main/src/resources/auth.ts"
    click Resources "https://github.com/hyperspell/node-sdk/blob/main/src/resources/collections.ts"
    click Resources "https://github.com/hyperspell/node-sdk/blob/main/src/resources/documents.ts"
    click Resources "https://github.com/hyperspell/node-sdk/blob/main/src/resources/integrations.ts"
    click Resources "https://github.com/hyperspell/node-sdk/blob/main/src/resources/query.ts"
    click Resources "https://github.com/hyperspell/node-sdk/blob/main/src/resources/integrations/google-calendar.ts"
    click Resources "https://github.com/hyperspell/node-sdk/blob/main/src/resources/integrations/web-crawler.ts"
    click DynamicLoader "https://github.com/hyperspell/node-sdk/blob/main/src/resources.ts"
    click DynamicLoader "https://github.com/hyperspell/node-sdk/blob/main/src/resource.ts"
    click RequestBuilder "https://github.com/hyperspell/node-sdk/blob/main/src/pagination.ts"
    click RequestBuilder "https://github.com/hyperspell/node-sdk/blob/main/src/uploads.ts"
    click ErrorHandling "https://github.com/hyperspell/node-sdk/blob/main/src/error.ts"
    click ErrorHandling "https://github.com/hyperspell/node-sdk/blob/main/src/responses.test.ts"

    %% Click Events - Runtime Shims
    click ShimsIndex "https://github.com/hyperspell/node-sdk/blob/main/src/_shims/index.js"
    click ShimsIndex "https://github.com/hyperspell/node-sdk/blob/main/src/_shims/index.mjs"
    click ShimsIndex "https://github.com/hyperspell/node-sdk/blob/main/src/_shims/index.d.ts"
    click MultipartBody "https://github.com/hyperspell/node-sdk/blob/main/src/_shims/MultipartBody.ts"
    click RuntimeNode "https://github.com/hyperspell/node-sdk/blob/main/src/_shims/node-runtime.ts"
    click RuntimeDeno "https://github.com/hyperspell/node-sdk/blob/main/src/_shims/runtime-deno.ts"
    click RuntimeBun "https://github.com/hyperspell/node-sdk/blob/main/src/_shims/runtime-bun.ts"
    click RuntimeWeb "https://github.com/hyperspell/node-sdk/blob/main/src/_shims/web-runtime.ts"
    click RuntimeNode "https://github.com/hyperspell/node-sdk/blob/main/src/shims/node.ts"
    click RuntimeWeb "https://github.com/hyperspell/node-sdk/blob/main/src/shims/web.ts"

    %% Click Events - MCP-Server
    click MCPIndex "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/index.ts"
    click MCPServer "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/server.ts"
    click MCPDynamic "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/dynamic-tools.ts"
    click MCPCompat "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/compat.ts"
    click MCPOptions "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/options.ts"
    click MCPTools "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/tools.ts"
    click MCPTools "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/tools/index.ts"
    click MCPTools "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/tools/auth/user-info.ts"
    click MCPTools "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/tools/documents/add-document.ts"
    click MCPTools "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/tools/documents/get-document.ts"
    click MCPTools "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/tools/documents/upload-file.ts"
    click MCPTools "https://github.com/hyperspell/node-sdk/blob/main/packages/mcp-server/src/tools/query/search.ts"

    %% Click Events - Pipeline
    click Scripts "https://github.com/hyperspell/node-sdk/tree/main/scripts/"
    click Workflows "https://github.com/hyperspell/node-sdk/blob/main/.github/workflows/ci.yml"
    click Workflows "https://github.com/hyperspell/node-sdk/blob/main/.github/workflows/publish-npm.yml"
    click Workflows "https://github.com/hyperspell/node-sdk/blob/main/.github/workflows/release-doctor.yml"
    click Bin "https://github.com/hyperspell/node-sdk/tree/main/bin/check-release-environment"
    click Bin "https://github.com/hyperspell/node-sdk/tree/main/bin/publish-npm"

    %% Styles
    classDef codeModule fill:#AED6F1,stroke:#3498DB
    classDef shims fill:#D6EAF8,stroke:#2980B9
    classDef externalApi fill:#ABEBC6,stroke:#27AE60
    classDef app fill:#F2F3F4,stroke:#BDC3C7
    classDef pipeline fill:#FAD7A0,stroke:#EB984E
```
