@memorylayerai/sdk 0.1.0

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@memorylayerai/sdk",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Official Node.js/TypeScript SDK for MemoryLayer",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "memorylayer",
+    "memory",
+    "ai",
+    "llm",
+    "sdk",
+    "typescript"
+  ],
+  "author": "MemoryLayer",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "fast-check": "^3.17.1",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.3",
+    "vitest": "^1.4.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,116 @@
+import { HTTPClient, ClientConfig as HTTPClientConfig } from './http-client.js';
+import { ValidationError } from './errors.js';
+
+/**
+ * Configuration options for the MemoryLayer client
+ */
+export interface ClientConfig {
+  /** API key for authentication (can also be set via MEMORYLAYER_API_KEY env var) */
+  apiKey?: string;
+  /** Base URL for the API (default: https://api.memorylayer.com) */
+  baseURL?: string;
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Maximum number of retry attempts (default: 3) */
+  maxRetries?: number;
+  /** Initial retry delay in milliseconds (default: 1000) */
+  retryDelay?: number;
+  /** Custom headers to include in all requests */
+  headers?: Record<string, string>;
+  /** Logger for debugging */
+  logger?: {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+  };
+}
+
+/**
+ * Main MemoryLayer SDK client
+ */
+export class MemoryLayerClient {
+  private httpClient: HTTPClient;
+  private _memories?: any;
+  private _search?: any;
+  private _ingest?: any;
+  private _router?: any;
+
+  constructor(config: ClientConfig = {}) {
+    // Get API key from config or environment variable
+    const apiKey = config.apiKey || process.env.MEMORYLAYER_API_KEY;
+    
+    if (!apiKey) {
+      throw new ValidationError(
+        'API key is required. Provide it via config.apiKey or MEMORYLAYER_API_KEY environment variable.',
+        [{ field: 'apiKey', message: 'API key is required' }]
+      );
+    }
+    
+    // Validate API key format (basic check)
+    if (typeof apiKey !== 'string' || apiKey.trim().length === 0) {
+      throw new ValidationError(
+        'API key must be a non-empty string',
+        [{ field: 'apiKey', message: 'API key must be a non-empty string' }]
+      );
+    }
+    
+    // Initialize HTTP client
+    const httpConfig: HTTPClientConfig = {
+      apiKey,
+      baseURL: config.baseURL,
+      timeout: config.timeout,
+      maxRetries: config.maxRetries,
+      retryDelay: config.retryDelay,
+      headers: config.headers,
+      logger: config.logger,
+    };
+    
+    this.httpClient = new HTTPClient(httpConfig);
+  }
+
+  /**
+   * Access memory operations
+   */
+  get memories() {
+    if (!this._memories) {
+      // Lazy load to avoid circular dependencies
+      const { MemoriesResource } = require('./resources/memories.js');
+      this._memories = new MemoriesResource(this.httpClient);
+    }
+    return this._memories;
+  }
+
+  /**
+   * Access search operations
+   */
+  get search() {
+    if (!this._search) {
+      const { SearchResource } = require('./resources/search.js');
+      this._search = new SearchResource(this.httpClient);
+    }
+    return this._search;
+  }
+
+  /**
+   * Access ingestion operations
+   */
+  get ingest() {
+    if (!this._ingest) {
+      const { IngestResource } = require('./resources/ingest.js');
+      this._ingest = new IngestResource(this.httpClient);
+    }
+    return this._ingest;
+  }
+
+  /**
+   * Access router operations
+   */
+  get router() {
+    if (!this._router) {
+      const { RouterResource } = require('./resources/router.js');
+      this._router = new RouterResource(this.httpClient);
+    }
+    return this._router;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,91 @@
+/**
+ * Base error class for all MemoryLayer SDK errors
+ */
+export class MemoryLayerError extends Error {
+  constructor(
+    message: string,
+    public statusCode?: number,
+    public requestId?: string,
+    public details?: any
+  ) {
+    super(message);
+    this.name = 'MemoryLayerError';
+    Object.setPrototypeOf(this, MemoryLayerError.prototype);
+  }
+}
+
+/**
+ * Error thrown when authentication fails (401)
+ */
+export class AuthenticationError extends MemoryLayerError {
+  constructor(message: string, requestId?: string) {
+    super(message, 401, requestId);
+    this.name = 'AuthenticationError';
+    Object.setPrototypeOf(this, AuthenticationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when rate limit is exceeded (429)
+ */
+export class RateLimitError extends MemoryLayerError {
+  constructor(
+    message: string,
+    public retryAfter: number,
+    requestId?: string
+  ) {
+    super(message, 429, requestId);
+    this.name = 'RateLimitError';
+    Object.setPrototypeOf(this, RateLimitError.prototype);
+  }
+}
+
+/**
+ * Validation error detail
+ */
+export interface ValidationErrorDetail {
+  field: string;
+  message: string;
+}
+
+/**
+ * Error thrown when request validation fails (400)
+ */
+export class ValidationError extends MemoryLayerError {
+  constructor(
+    message: string,
+    public errors: ValidationErrorDetail[],
+    requestId?: string
+  ) {
+    super(message, 400, requestId);
+    this.name = 'ValidationError';
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}
+
+/**
+ * Error thrown when network request fails
+ */
+export class NetworkError extends MemoryLayerError {
+  constructor(message: string, public cause: Error) {
+    super(message);
+    this.name = 'NetworkError';
+    Object.setPrototypeOf(this, NetworkError.prototype);
+  }
+}
+
+/**
+ * Error thrown for other API errors
+ */
+export class APIError extends MemoryLayerError {
+  constructor(
+    message: string,
+    statusCode: number,
+    requestId?: string,
+    details?: any
+  ) {
+    super(message, statusCode, requestId, details);
+    this.name = 'APIError';
+    Object.setPrototypeOf(this, APIError.prototype);
+  }
+}

package/src/http-client.ts

@@ -0,0 +1,304 @@
+import {
+  MemoryLayerError,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NetworkError,
+  APIError,
+} from './errors.js';
+
+/**
+ * Configuration for the HTTP client
+ */
+export interface ClientConfig {
+  apiKey: string;
+  baseURL?: string;
+  timeout?: number;
+  maxRetries?: number;
+  retryDelay?: number;
+  headers?: Record<string, string>;
+  logger?: Logger;
+}
+
+/**
+ * Logger interface
+ */
+export interface Logger {
+  debug(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  error(message: string, ...args: any[]): void;
+}
+
+/**
+ * Retry configuration
+ */
+export interface RetryConfig {
+  maxRetries: number;
+  initialDelay: number;
+  maxDelay: number;
+  backoffMultiplier: number;
+  retryableStatusCodes: number[];
+}
+
+/**
+ * Request options
+ */
+export interface RequestOptions {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  path: string;
+  body?: any;
+  query?: Record<string, string>;
+  headers?: Record<string, string>;
+  timeout?: number;
+}
+
+/**
+ * HTTP client with retry logic and error handling
+ */
+export class HTTPClient {
+  private config: ClientConfig;
+  private retryConfig: RetryConfig;
+  private baseURL: string;
+
+  constructor(config: ClientConfig, retryConfig?: Partial<RetryConfig>) {
+    this.config = config;
+    this.baseURL = config.baseURL || 'https://api.memorylayer.com';
+    this.retryConfig = {
+      maxRetries: config.maxRetries ?? 3,
+      initialDelay: config.retryDelay ?? 1000,
+      maxDelay: 30000,
+      backoffMultiplier: 2,
+      retryableStatusCodes: [429, 500, 502, 503, 504],
+      ...retryConfig,
+    };
+  }
+
+  /**
+   * Make an HTTP request with retry logic
+   */
+  async request<T>(options: RequestOptions): Promise<T> {
+    let lastError: Error | null = null;
+    
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      try {
+        return await this.makeRequest<T>(options);
+      } catch (error) {
+        lastError = error as Error;
+        
+        if (!this.shouldRetry(error as MemoryLayerError, attempt)) {
+          throw error;
+        }
+        
+        const delay = this.getRetryDelay(error as MemoryLayerError, attempt);
+        this.config.logger?.debug(`Retrying request after ${delay}ms (attempt ${attempt + 1}/${this.retryConfig.maxRetries})`);
+        await this.sleep(delay);
+      }
+    }
+    
+    throw lastError;
+  }
+
+  /**
+   * Make a streaming request
+   */
+  async *stream(options: RequestOptions): AsyncIterable<any> {
+    const url = this.buildURL(options.path, options.query);
+    const headers = this.buildHeaders(options.headers);
+    
+    try {
+      const response = await fetch(url, {
+        method: options.method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : undefined,
+        signal: AbortSignal.timeout(options.timeout || this.config.timeout || 60000),
+      });
+      
+      if (!response.ok) {
+        throw await this.handleErrorResponse(response);
+      }
+      
+      if (!response.body) {
+        throw new NetworkError('Response body is null', new Error('No response body'));
+      }
+      
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = '';
+      
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          
+          if (done) {
+            break;
+          }
+          
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split('\n');
+          buffer = lines.pop() || '';
+          
+          for (const line of lines) {
+            if (line.trim() === '') continue;
+            if (line.startsWith('data: ')) {
+              const data = line.slice(6);
+              if (data === '[DONE]') continue;
+              try {
+                yield JSON.parse(data);
+              } catch (e) {
+                this.config.logger?.warn('Failed to parse streaming chunk:', data);
+              }
+            }
+          }
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    } catch (error) {
+      if (error instanceof MemoryLayerError) {
+        throw error;
+      }
+      throw new NetworkError('Streaming request failed', error as Error);
+    }
+  }
+
+  /**
+   * Make the actual HTTP request
+   */
+  private async makeRequest<T>(options: RequestOptions): Promise<T> {
+    const url = this.buildURL(options.path, options.query);
+    const headers = this.buildHeaders(options.headers);
+    
+    try {
+      const response = await fetch(url, {
+        method: options.method,
+        headers,
+        body: options.body ? JSON.stringify(options.body) : undefined,
+        signal: AbortSignal.timeout(options.timeout || this.config.timeout || 30000),
+      });
+      
+      if (!response.ok) {
+        throw await this.handleErrorResponse(response);
+      }
+      
+      return await response.json();
+    } catch (error) {
+      if (error instanceof MemoryLayerError) {
+        throw error;
+      }
+      throw new NetworkError('Request failed', error as Error);
+    }
+  }
+
+  /**
+   * Build the full URL with query parameters
+   */
+  private buildURL(path: string, query?: Record<string, string>): string {
+    const url = new URL(path, this.baseURL);
+    if (query) {
+      Object.entries(query).forEach(([key, value]) => {
+        url.searchParams.append(key, value);
+      });
+    }
+    return url.toString();
+  }
+
+  /**
+   * Build request headers
+   */
+  private buildHeaders(additionalHeaders?: Record<string, string>): Record<string, string> {
+    return {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${this.config.apiKey}`,
+      'X-SDK-Version': '0.1.0',
+      'X-API-Version': 'v1',
+      ...this.config.headers,
+      ...additionalHeaders,
+    };
+  }
+
+  /**
+   * Handle error responses from the API
+   */
+  private async handleErrorResponse(response: Response): Promise<MemoryLayerError> {
+    const requestId = response.headers.get('x-request-id') || undefined;
+    let errorData: any;
+    
+    try {
+      errorData = await response.json();
+    } catch {
+      errorData = { message: response.statusText };
+    }
+    
+    const message = errorData.error?.message || errorData.message || 'Unknown error';
+    const details = errorData.error?.details || errorData.details;
+    
+    switch (response.status) {
+      case 401:
+        return new AuthenticationError(message, requestId);
+      case 429:
+        const retryAfter = parseInt(response.headers.get('retry-after') || '60', 10);
+        return new RateLimitError(message, retryAfter, requestId);
+      case 400:
+        const errors = errorData.error?.errors || [];
+        return new ValidationError(message, errors, requestId);
+      default:
+        return new APIError(message, response.status, requestId, details);
+    }
+  }
+
+  /**
+   * Determine if an error should be retried
+   */
+  private shouldRetry(error: MemoryLayerError, attempt: number): boolean {
+    if (attempt >= this.retryConfig.maxRetries) {
+      return false;
+    }
+    
+    // Retry network errors
+    if (error instanceof NetworkError) {
+      return true;
+    }
+    
+    // Retry rate limit errors
+    if (error instanceof RateLimitError) {
+      return true;
+    }
+    
+    // Retry specific status codes
+    if (error.statusCode && this.retryConfig.retryableStatusCodes.includes(error.statusCode)) {
+      return true;
+    }
+    
+    // Don't retry client errors (4xx except 429)
+    if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
+      return false;
+    }
+    
+    return false;
+  }
+
+  /**
+   * Calculate retry delay with exponential backoff
+   */
+  private getRetryDelay(error: MemoryLayerError, attempt: number): number {
+    // Respect Retry-After header for rate limit errors
+    if (error instanceof RateLimitError) {
+      return error.retryAfter * 1000;
+    }
+    
+    // Exponential backoff with jitter
+    const exponentialDelay = this.retryConfig.initialDelay * Math.pow(this.retryConfig.backoffMultiplier, attempt);
+    const jitter = Math.random() * 0.1 * exponentialDelay; // 10% jitter
+    const delay = Math.min(exponentialDelay + jitter, this.retryConfig.maxDelay);
+    
+    return delay;
+  }
+
+  /**
+   * Sleep for a specified duration
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}

package/src/index.ts

@@ -0,0 +1,50 @@
+/**
+ * MemoryLayer Node.js/TypeScript SDK
+ * 
+ * Official SDK for integrating MemoryLayer into your applications.
+ * 
+ * @packageDocumentation
+ */
+
+// Main client
+export { MemoryLayerClient } from './client.js';
+export type { ClientConfig } from './client.js';
+
+// Error classes
+export {
+  MemoryLayerError,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+  NetworkError,
+  APIError,
+} from './errors.js';
+export type { ValidationErrorDetail } from './errors.js';
+
+// Type definitions
+export type {
+  Memory,
+  CreateMemoryRequest,
+  UpdateMemoryRequest,
+  ListMemoriesRequest,
+  SearchRequest,
+  SearchResult,
+  SearchResponse,
+  IngestFileRequest,
+  IngestTextRequest,
+  IngestResponse,
+  Message,
+  RouterRequest,
+  RouterResponse,
+  Usage,
+  Choice,
+  StreamChunk,
+  StreamChoice,
+  StreamDelta,
+} from './types.js';
+
+// Resources (exported for advanced use cases)
+export { MemoriesResource } from './resources/memories.js';
+export { SearchResource } from './resources/search.js';
+export { IngestResource } from './resources/ingest.js';
+export { RouterResource } from './resources/router.js';

package/src/resources/ingest.ts

@@ -0,0 +1,77 @@
+import { HTTPClient } from '../http-client.js';
+import { IngestFileRequest, IngestTextRequest, IngestResponse } from '../types.js';
+import { ValidationError } from '../errors.js';
+
+/**
+ * Resource for ingestion operations
+ */
+export class IngestResource {
+  constructor(private httpClient: HTTPClient) {}
+
+  /**
+   * Ingest a file
+   * @param request - File ingestion request
+   * @returns Ingestion response with created memory IDs
+   */
+  async file(request: IngestFileRequest): Promise<IngestResponse> {
+    // Validate request
+    if (!request.file) {
+      throw new ValidationError(
+        'File is required',
+        [{ field: 'file', message: 'File is required' }]
+      );
+    }
+
+    if (!request.projectId || request.projectId.trim().length === 0) {
+      throw new ValidationError(
+        'Project ID is required',
+        [{ field: 'projectId', message: 'Project ID is required' }]
+      );
+    }
+
+    // For file uploads, we need to use FormData
+    // This is a simplified implementation - in production, you'd handle multipart/form-data properly
+    const body = {
+      projectId: request.projectId,
+      metadata: request.metadata,
+      chunkSize: request.chunkSize,
+      chunkOverlap: request.chunkOverlap,
+      // In a real implementation, you'd convert the file to base64 or use FormData
+      file: request.file,
+    };
+
+    return this.httpClient.request<IngestResponse>({
+      method: 'POST',
+      path: '/v1/ingest/file',
+      body,
+    });
+  }
+
+  /**
+   * Ingest text
+   * @param request - Text ingestion request
+   * @returns Ingestion response with created memory IDs
+   */
+  async text(request: IngestTextRequest): Promise<IngestResponse> {
+    // Validate request
+    if (!request.text || request.text.trim().length === 0) {
+      throw new ValidationError(
+        'Text cannot be empty',
+        [{ field: 'text', message: 'Text is required and cannot be empty' }]
+      );
+    }
+
+    if (!request.projectId || request.projectId.trim().length === 0) {
+      throw new ValidationError(
+        'Project ID is required',
+        [{ field: 'projectId', message: 'Project ID is required' }]
+      );
+    }
+
+    return this.httpClient.request<IngestResponse>({
+      method: 'POST',
+      path: '/v1/ingest/text',
+      body: request,
+    });
+  }
+}