Project Description
ContextBase TypeScript SDK is a client library that provides a simple and intuitive interface for interacting with the ContextBase MCP API.
This SDK enables developers to easily integrate memory storage capabilities into their TypeScript applications,
with features like authentication, key-value operations, and semantic search functionality.
Technology Stack
TypeScript
Axios
Node.js
REST API
JSON
npm
High-Level Architecture
flowchart TD
User[Client Application] --- SDK[ContextBase SDK]
SDK --- API[ContextBase MCP API]
API --- Storage[Memory Storage]
subgraph SDK_Components["SDK Components"]
Client[context Class] --- Auth[Authentication Methods]
Client --- MemoryOps[Memory Operations]
Auth --- Signup["signup()"]
Auth --- Login["login()"]
Auth --- SetToken["setToken()"]
MemoryOps --- Set["set()"]
MemoryOps --- Get["get()"]
MemoryOps --- List["list()"]
MemoryOps --- Search["search()"]
MemoryOps --- Delete["delete()"]
end
SDK --- SDK_Components
classDef user fill:#d1e7dd,stroke:#20c997
classDef sdk fill:#cfe2ff,stroke:#0d6efd
classDef api fill:#e2e3e5,stroke:#6c757d
classDef storage fill:#f8d7da,stroke:#dc3545
class User user
class SDK sdk
class API api
class Storage storage
Detailed Component Architecture
flowchart TD
subgraph Core_SDK["Core SDK"]
ContextClass["context Class"] --> Constructor["constructor(options)"]
Constructor --> InitializeClient["Initialize Client"]
InitializeClient --> SetBaseUrl["Set Base URL"]
InitializeClient --> SetToken["Set Token (optional)"]
ContextClass --> AuthMethods["Authentication Methods"]
AuthMethods --> Signup["signup(email, password)"]
AuthMethods --> Login["login(email, password)"]
AuthMethods --> TokenSetter["setToken(token)"]
ContextClass --> MemoryMethods["Memory Methods"]
MemoryMethods --> Set["set(key, value, ttl)"]
MemoryMethods --> Get["get(key)"]
MemoryMethods --> List["list()"]
MemoryMethods --> Search["search(query)"]
MemoryMethods --> Delete["delete(key)"]
ContextClass --> HelperMethods["Helper Methods"]
HelperMethods --> Headers["headers()"]
end
subgraph API_Endpoints["API Endpoints"]
Signup --> SignupEndpoint["/api/auth/signup"]
Login --> LoginEndpoint["/api/auth/login"]
Set --> SetEndpoint["/api/memory"]
Get --> GetEndpoint["/api/memory/{key}"]
List --> ListEndpoint["/api/memory"]
Search --> SearchEndpoint["/api/memory/search/{query}"]
Delete --> DeleteEndpoint["/api/memory/delete"]
end
classDef core fill:#f0f7ff,stroke:#3b82f6
classDef endpoints fill:#f0fdf4,stroke:#22c55e
class Core_SDK core
class API_Endpoints endpoints
Project Structure
contextbase-ts/
├── dist/ # Compiled JavaScript files
│ ├── client.js # Compiled client implementation
│ ├── client.d.ts # TypeScript declaration file
│ ├── index.js # Compiled entry point
│ ├── index.d.ts # TypeScript declaration file
│ ├── types.js # Compiled type definitions
│ └── types.d.ts # TypeScript declaration file
├── node_modules/ # Dependencies
├── src/ # Source code
│ ├── client.ts # Main client implementation
│ ├── index.ts # Entry point
│ └── types.ts # TypeScript interfaces
├── test/ # Test files
│ ├── test.ts # Main test file
│ ├── test-delete.ts # Delete operation test
│ └── test-search.ts # Search operation test
├── .gitignore # Git ignore file
├── LICENSE # License file
├── README.md # Documentation
├── package.json # Package metadata and dependencies
├── package-lock.json # Dependency lock file
└── tsconfig.json # TypeScript configuration
Authentication Flow
sequenceDiagram
participant Client as Client Application
participant SDK as ContextBase SDK
participant API as ContextBase API
participant DB as Memory Storage
Client->>SDK: new context({ baseUrl })
Client->>SDK: signup(email, password)
SDK->>API: POST /api/auth/signup
API->>DB: Create User
DB->>API: User Created
API->>SDK: Return JWT Token
SDK->>SDK: Store Token Internally
SDK->>Client: Return Token
Client->>SDK: login(email, password)
SDK->>API: POST /api/auth/login
API->>DB: Validate Credentials
DB->>API: Credentials Valid
API->>SDK: Return JWT Token
SDK->>SDK: Store Token Internally
SDK->>Client: Return Token
Client->>SDK: setToken(existingToken)
SDK->>SDK: Store Token for Future Requests
Memory Operations Flow
flowchart LR
subgraph Memory_Operations["Memory Operations"]
Set["set(key, value, ttl)"] --> SetReq["POST /api/memory"]
Get["get(key)"] --> GetReq["GET /api/memory/{key}"]
List["list()"] --> ListReq["GET /api/memory"]
Search["search(query)"] --> SearchReq["GET /api/memory/search/{query}"]
Delete["delete(key)"] --> DeleteReq["POST /api/memory/delete"]
end
subgraph Request_Flow["Request Flow"]
SetReq --> Auth["Add Authorization Header"]
GetReq --> Auth
ListReq --> Auth
SearchReq --> Auth
DeleteReq --> Auth
Auth --> Send["Send HTTP Request"]
Send --> Response["Process Response"]
Response --> Return["Return Data to Client"]
end
classDef ops fill:#dbeafe,stroke:#3b82f6
classDef flow fill:#dcfce7,stroke:#22c55e
class Memory_Operations ops
class Request_Flow flow
Detailed API Endpoints
flowchart LR
subgraph Authentication_Endpoints["Authentication Endpoints"]
Signup["POST /api/auth/signup"] --- SignupPayload["{ email, password }"]
Login["POST /api/auth/login"] --- LoginPayload["{ email, password }"]
end
subgraph Memory_Endpoints["Memory Endpoints"]
Set["POST /api/memory"] --- SetPayload["{ key, value, ttl? }"]
Get["GET /api/memory/{key}"] --- GetParams["key (URL parameter)"]
List["GET /api/memory"] --- ListParams["No parameters"]
Search["GET /api/memory/search/{query}"] --- SearchParams["query (URL parameter)"]
Delete["POST /api/memory/delete"] --- DeletePayload["{ key }"]
end
subgraph Response_Format["Response Format"]
AuthResponse["Authentication Response"] --- Token["{ token: string }"]
MemoryResponse["Memory Response"] --- Data["{ success: boolean, data: any }"]
end
classDef auth fill:#dbeafe,stroke:#3b82f6
classDef memory fill:#dcfce7,stroke:#22c55e
classDef response fill:#fecaca,stroke:#ef4444
class Authentication_Endpoints auth
class Memory_Endpoints memory
class Response_Format response
Client Implementation Flow
flowchart LR
A["Client Initialization"] --> B["Set Base URL"]
B --> C["Set Optional Token"]
C --> D["Client Ready"]
D --> E["Auth Methods Available"]
D --> F["Memory Methods Available"]
E --> G["signup()"]
E --> H["login()"]
E --> I["setToken()"]
F --> J["set()"]
F --> K["get()"]
F --> L["list()"]
F --> M["search()"]
F --> N["delete()"]
style A fill:#d4f4e2,stroke:#34d399,stroke-width:3px,color:#065f46,font-weight:bold
style B fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style C fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style D fill:#d4f4e2,stroke:#34d399,stroke-width:3px,color:#065f46,font-weight:bold
style E fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style F fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style G fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style H fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style I fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style J fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style K fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style L fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style M fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style N fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
User Flow
flowchart LR
A["Start"] --> B["Install SDK"]
B --> C["Initialize Client"]
C --> D["Authenticate"]
D --> E["Perform Memory Operations"]
E --> F["Handle Responses"]
F --> G["Continue Operations"]
G --> E
style A fill:#d4f4e2,stroke:#34d399,stroke-width:3px,color:#065f46,font-weight:bold
style B fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style C fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style D fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style E fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style F fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
style G fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e40af
Class Implementation
classDiagram
class ContextOptions {
+string baseUrl
+string? token
}
class SetMemoryPayload {
+string key
+string value
+number? ttl
}
class context {
-string baseUrl
-string? token
+constructor(options: ContextOptions)
-headers()
+setToken(token: string)
+signup(email: string, password: string)
+login(email: string, password: string)
+set(key: string, value: string, ttl?: number)
+get(key: string)
+delete(key: string)
+list()
+search(query: string)
}
ContextOptions <|-- context : uses
SetMemoryPayload <|-- context : uses
Authentication Implementation
sequenceDiagram
participant Client as Client Code
participant SDK as context Class
participant Axios as Axios HTTP Client
participant API as ContextBase API
Client->>SDK: signup(email, password)
SDK->>Axios: axios.post(baseUrl + '/api/auth/signup', { email, password })
Axios->>API: HTTP POST Request
API->>Axios: Response with token
Axios->>SDK: Response data
SDK->>SDK: setToken(token)
SDK->>Client: Return token
Client->>SDK: login(email, password)
SDK->>Axios: axios.post(baseUrl + '/api/auth/login', { email, password })
Axios->>API: HTTP POST Request
API->>Axios: Response with token
Axios->>SDK: Response data
SDK->>SDK: setToken(token)
SDK->>Client: Return token
Memory Operations Implementation
sequenceDiagram
participant Client as Client Code
participant SDK as context Class
participant Axios as Axios HTTP Client
participant API as ContextBase API
Client->>SDK: set(key, value, ttl)
SDK->>Axios: axios.post(baseUrl + '/api/memory', { key, value, ttl }, { headers })
Axios->>API: HTTP POST Request
API->>Axios: Response
Axios->>SDK: Response data
SDK->>Client: Return data
Client->>SDK: get(key)
SDK->>Axios: axios.get(baseUrl + '/api/memory/' + key, { headers })
Axios->>API: HTTP GET Request
API->>Axios: Response
Axios->>SDK: Response data
SDK->>Client: Return data
Client->>SDK: list()
SDK->>Axios: axios.get(baseUrl + '/api/memory', { headers })
Axios->>API: HTTP GET Request
API->>Axios: Response
Axios->>SDK: Response data
SDK->>Client: Return data
Client->>SDK: search(query)
SDK->>SDK: encodeURIComponent(query)
SDK->>Axios: axios.get(baseUrl + '/api/memory/search/' + encoded, { headers })
Axios->>API: HTTP GET Request
API->>Axios: Response
Axios->>SDK: Response data
SDK->>Client: Return data
Client->>SDK: delete(key)
SDK->>Axios: axios.post(baseUrl + '/api/memory/delete', { key }, { headers })
Axios->>API: HTTP POST Request
API->>Axios: Response
Axios->>SDK: Response data
SDK->>Client: Return data
Headers Implementation
flowchart TD
subgraph Headers_Method["Headers Method"]
Headers["headers() method"] --> CheckToken["Check if token exists"]
CheckToken --> CreateHeaders["Create headers object"]
CreateHeaders --> AddAuth["Add Authorization header"]
AddAuth --> AddContentType["Add Content-Type header"]
AddContentType --> ReturnHeaders["Return headers object"]
end
subgraph Headers_Usage["Headers Usage"]
Set["set() method"] --> UseHeaders["Use headers in request"]
Get["get() method"] --> UseHeaders
List["list() method"] --> UseHeaders
Search["search() method"] --> UseHeaders
Delete["delete() method"] --> UseHeaders
end
classDef method fill:#f0f7ff,stroke:#3b82f6
classDef usage fill:#f0fdf4,stroke:#22c55e
class Headers_Method method
class Headers_Usage usage
State Management
flowchart TD
subgraph Client_State["Client State"]
BaseUrl["baseUrl: string"] --> ClientState["Client State"]
Token["token?: string"] --> ClientState
end
subgraph State_Management["State Management"]
Constructor["constructor()"] --> InitState["Initialize State"]
SetToken["setToken()"] --> UpdateToken["Update Token State"]
Login["login()"] --> UpdateToken
Signup["signup()"] --> UpdateToken
end
subgraph State_Usage["State Usage"]
Headers["headers()"] --> UseToken["Use Token State"]
MemoryOps["Memory Operations"] --> UseHeaders["Use Headers Method"]
UseHeaders --> UseToken
end
classDef state fill:#f0f7ff,stroke:#3b82f6
classDef management fill:#f0fdf4,stroke:#22c55e
classDef usage fill:#fecaca,stroke:#ef4444
class Client_State state
class State_Management management
class State_Usage usage
Development Workflow
sequenceDiagram
participant Developer
participant Git as Git Repository
participant NPM as NPM
participant TypeScript as TypeScript Compiler
participant Tests as Test Suite
Developer->>Git: Clone Repository
Developer->>NPM: Run npm install
NPM->>Developer: Dependencies Installed
Developer->>Developer: Make Code Changes
Developer->>TypeScript: Run tsc (npm run build)
TypeScript->>Developer: Compiled JavaScript
Developer->>Tests: Run Tests (npm run test)
Tests->>Developer: Test Results
Developer->>Git: Commit Changes
Developer->>NPM: Publish Package (npm publish)
Future Enhancements
flowchart TD
subgraph Planned_Features["Planned Features"]
BatchOps[Batch Operations] --> BatchSet[Batch Set]
BatchOps --> BatchGet[Batch Get]
BatchOps --> BatchDelete[Batch Delete]
AdvancedSearch[Advanced Search] --> Filtering[Filtering]
AdvancedSearch --> Sorting[Sorting]
AdvancedSearch --> Pagination[Pagination]
ErrorHandling[Error Handling] --> RetryLogic[Retry Logic]
ErrorHandling --> DetailedErrors[Detailed Error Messages]
ErrorHandling --> ErrorCallbacks[Error Callbacks]
TypeSafety[Enhanced Type Safety] --> StrongTypes[Stronger Type Definitions]
TypeSafety --> Generics[Generic Type Support]
TypeSafety --> ValidationRules[Validation Rules]
end
classDef future fill:#f0f7ff,stroke:#3b82f6
class Planned_Features future
Getting Started
To use the ContextBase TypeScript SDK in your project:
- Install the package:
- Run
npm install contextbase-ts to install the SDK
- Initialize the client:
- Import the SDK:
import { context } from 'contextbase-ts';
- Create a new client instance:
const ctx = new context({ baseUrl: 'https://contextbase.onrender.com' });
- Authenticate:
- Sign up:
const token = await ctx.signup('user@example.com', 'password');
- Or log in:
const token = await ctx.login('user@example.com', 'password');
- Or set an existing token:
ctx.setToken('your-auth-token');
- Perform memory operations:
- Store a memory:
await ctx.set('myKey', 'myValue', 3600);
- Retrieve a memory:
const memory = await ctx.get('myKey');
- List all memories:
const allMemories = await ctx.list();
- Search memories:
const results = await ctx.search('queryString');
- Delete a memory:
await ctx.delete('myKey');
Conclusion
The ContextBase TypeScript SDK provides a clean and intuitive interface for interacting with the ContextBase MCP API.
With its simple authentication flow and straightforward memory operations, the SDK makes it easy to integrate memory storage capabilities into any TypeScript application.
The SDK's architecture leverages Axios for HTTP requests and TypeScript for type safety, providing a robust and reliable foundation for building applications that require persistent memory storage.
