TypeScript SDK

Relevant source files

The following files were used as context for generating this wiki page:

• sdks/typescript/src/index.ts
• sdks/typescript/README.md
• sdks/typescript/package.json
• scripts/sdk_release.py
• sdks/typescript/src/models.ts
• README.md

The monGARS TypeScript SDK provides a modern, Promise-based wrapper around the monGARS REST API. It is designed to run in both Node.js and browser environments, leveraging cross-fetch for universal compatibility. The SDK simplifies interactions with the API by providing typed methods for all major endpoints, handling authentication, and throwing typed errors for robust error management.

The SDK is a key component for building frontend applications or Node.js-based integrations that communicate with the monGARS backend, as highlighted in the project's roadmap for API refinement.

Sources: sdks/typescript/README.md, sdks/typescript/package.json, ROADMAP.md

Installation and Building

Installation

The SDK is available as an NPM package and can be installed using a standard package manager.

npm install @mongars/sdk

The package name is defined as @mongars/sdk with version 0.1.0. It depends on cross-fetch for making HTTP requests.

Sources: sdks/typescript/README.md:10-12, sdks/typescript/package.json:2, 16

Building from Source

To build the package locally from the repository root, a shared release script is provided. This script compiles the TypeScript source and packages it into an npm tarball.

python -m scripts.sdk_release --output dist/sdk

This command performs the following steps for the TypeScript SDK:

1. Runs npm ci to install dependencies.
2. Runs npm run build to execute the TypeScript compiler (tsc).
3. Runs npm pack to create a .tgz tarball in the specified destination (dist/sdk/typescript/).

Sources: sdks/typescript/README.md:14-20, scripts/sdk_release.py:70-86

Client Architecture

The primary component of the SDK is the MonGARSClient class, which serves as the main interface for all API interactions.

Sources: sdks/typescript/src/index.ts:56

Client Configuration

The MonGARSClient is instantiated with a configuration object that defines its behavior.

Option	Type	Description	Default
baseUrl	string	Required. The base URL of the monGARS API endpoint.	-
defaultHeaders	HeadersInit	Optional headers to be sent with every request.	Accept: "application/json", User-Agent: "monGARS-SDK/1.0"
fetchImpl	typeof fetch	An optional fetch implementation.	cross-fetch
credentials	"omit" | "same-origin" | "include"	Controls how browser credentials (e.g., cookies) are handled.	"omit"

The credentials option defaults to "omit" to prevent Cross-Site Request Forgery (CSRF) vulnerabilities when used in a browser context.

Sources: sdks/typescript/src/index.ts:25-36, 62-66, sdks/typescript/README.md:37-43

Class Structure

The diagram below shows the structure of the MonGARSClient class.

This diagram illustrates the MonGARSClient and its configuration object ClientOptions.

Sources: sdks/typescript/src/index.ts:25-36, 56-231

Authentication Flow

Authentication is handled via the login method. Upon successful login, the client receives a JWT (access_token) and stores it internally. This token is then automatically included as a Bearer token in the Authorization header for all subsequent requests.

The following sequence diagram demonstrates the authentication and subsequent API call flow.

Request Lifecycle and Error Handling

All API calls are routed through a private request method. This method constructs headers, makes the fetch call, and handles the response. If the API returns a non-OK status (not in the 2xx range), the SDK throws a typed error.

The internal request flow is as follows:

This diagram shows the logic within the request method, from header construction to response and error handling.

Sources: sdks/typescript/src/index.ts:84-117

Two custom error classes are defined for specific failure scenarios:

• AuthenticationError: Thrown for 401 or 403 status codes.
• ApiError: Thrown for all other non-successful status codes.

Both error types contain the status code and the response payload from the API.

Sources: sdks/typescript/src/index.ts:46-54, sdks/typescript/README.md:57-59

API Coverage

The SDK provides methods that map directly to the monGARS REST API endpoints.

Method	HTTP Request	Endpoint	Description
login	POST	/token	Authenticates a user and retrieves a JWT.
registerUser	POST	/api/v1/user/register	Registers a new user.
chat	POST	/api/v1/conversation/chat	Sends a message to the conversation endpoint.
history	GET	/api/v1/conversation/history	Fetches conversation history for a user.
fetchRagContext	POST	/api/v1/review/rag-context	Fetches RAG context for review.
suggestActions	POST	/api/v1/ui/suggestions	Gets UI action suggestions based on a prompt.
registerPeer	POST	/api/v1/peer/register	Registers a peer in the network.
unregisterPeer	POST	/api/v1/peer/unregister	Unregisters a peer from the network.
listPeers	GET	/api/v1/peer/list	Lists all registered peers.
peerLoad	GET	/api/v1/peer/load	Gets the load snapshot of a peer.
publishPeerTelemetry	POST	/api/v1/peer/telemetry	Publishes telemetry data for a peer.
peerTelemetry	GET	/api/v1/peer/telemetry	Retrieves peer telemetry.
modelConfiguration	GET	/api/v1/models	Gets the current model configuration.
provisionModels	POST	/api/v1/models/provision	Triggers provisioning of LLM models.

Sources: sdks/typescript/src/index.ts:119-231, sdks/typescript/README.md:50-56

Data Models

The SDK includes TypeScript interfaces for all request and response payloads, ensuring type safety. These models are defined in src/models.ts.

For example, the chat method uses the ChatRequest and ChatResponse models.

ChatRequest

export interface ChatRequest {
  user_id: string;
  message: string;
  session_id?: string;
  image_url?: string;
  context?: Record<string, unknown>;
}

ChatResponse

export interface ChatResponse {
  response: string;
  session_id: string;
  user_id: string;
  interaction_id: string;
  metadata?: Record<string, unknown>;
}

These models ensure that data sent to and received from the API conforms to the expected structure.

Sources: sdks/typescript/src/models.ts