@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/sdk/index.ts

@@ -0,0 +1,244 @@
+/**
+ * Supermemory SDK
+ * A drop-in replacement for the official supermemory npm package
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import Supermemory from './sdk';
+ *
+ * const client = new Supermemory({
+ *   apiKey: process.env.SUPERMEMORY_API_KEY,
+ * });
+ *
+ * // Add content
+ * const doc = await client.add({ content: 'Hello, world!' });
+ *
+ * // Search documents
+ * const results = await client.search.documents({ q: 'hello' });
+ *
+ * // Upload files
+ * await client.documents.uploadFile({ file: myFile });
+ * ```
+ */
+
+// Main client export
+export { Supermemory, toFile } from './client.js'
+export { Supermemory as default } from './client.js'
+
+// HTTP utilities
+export { APIPromise } from './http.js'
+
+// Error classes
+export {
+  SupermemoryError,
+  APIError,
+  APIUserAbortError,
+  APIConnectionError,
+  APIConnectionTimeoutError,
+  BadRequestError,
+  AuthenticationError,
+  PermissionDeniedError,
+  NotFoundError,
+  ConflictError,
+  UnprocessableEntityError,
+  RateLimitError,
+  InternalServerError,
+  isAPIError,
+  isRateLimitError,
+  isRetryableError,
+} from './errors.js'
+
+// Type exports
+export type {
+  // Client types
+  ClientOptions,
+  RequestOptions,
+  LogLevel,
+  Logger,
+  Uploadable,
+  ToFileOptions,
+
+  // Common types
+  Metadata,
+  Pagination,
+  Chunk,
+  Filter,
+  OrFilter,
+  AndFilter,
+  FilterCondition,
+
+  // Add types
+  AddParams,
+  AddResponse,
+
+  // Profile types
+  ProfileParams,
+  ProfileResponse,
+  Profile,
+  ProfileMemory,
+
+  // Search types
+  SearchDocumentsParams,
+  SearchDocumentsResponse,
+  SearchMemoriesParams,
+  SearchMemoriesResponse,
+  SearchExecuteParams,
+  SearchExecuteResponse,
+  SearchResultItem,
+  SearchResults,
+  MemoryResult,
+
+  // Document types
+  Document,
+  DocumentListParams,
+  DocumentListResponse,
+  DocumentUpdateParams,
+  DocumentUpdateResponse,
+  DocumentAddParams,
+  DocumentAddResponse,
+  DocumentBatchAddParams,
+  DocumentBatchAddResponse,
+  DocumentDeleteBulkParams,
+  DocumentDeleteBulkResponse,
+  DocumentGetResponse,
+  DocumentListProcessingResponse,
+  DocumentUploadFileParams,
+  DocumentUploadFileResponse,
+
+  // Memory types
+  Memory,
+  MemoryListParams,
+  MemoryListResponse,
+  MemoryAddParams,
+  MemoryAddResponse,
+  MemoryUpdateParams,
+  MemoryUpdateResponse,
+  MemoryForgetParams,
+  MemoryForgetResponse,
+  MemoryGetResponse,
+  MemoryUpdateMemoryParams,
+  MemoryUpdateMemoryResponse,
+  MemoryUploadFileParams,
+  MemoryUploadFileResponse,
+
+  // Connection types
+  Connection,
+  ConnectionProvider,
+  ConnectionCreateParams,
+  ConnectionCreateResponse,
+  ConnectionListParams,
+  ConnectionListResponse,
+  ConnectionConfigureParams,
+  ConnectionConfigureResponse,
+  ConnectionDeleteByIDResponse,
+  ConnectionDeleteByProviderParams,
+  ConnectionDeleteByProviderResponse,
+  ConnectionGetByIDResponse,
+  ConnectionGetByTagParams,
+  ConnectionGetByTagResponse,
+  ConnectionImportParams,
+  ConnectionImportResponse,
+  ConnectionListDocumentsParams,
+  ConnectionListDocumentsResponse,
+  ConnectionResourcesParams,
+  ConnectionResource,
+  ConnectionResourcesResponse,
+
+  // Settings types
+  Settings,
+  SettingUpdateParams,
+  SettingUpdateResponse,
+  SettingGetResponse,
+} from './types.js'
+
+// Namespace for type convenience (matches official SDK pattern)
+// Types are available both at module level and under Supermemory namespace
+import type * as Types from './types.js'
+
+export namespace Supermemory {
+  // Re-export all types under the Supermemory namespace
+  export type ClientOptions = Types.ClientOptions
+  export type RequestOptions = Types.RequestOptions
+  export type LogLevel = Types.LogLevel
+  export type Logger = Types.Logger
+  export type Uploadable = Types.Uploadable
+  export type ToFileOptions = Types.ToFileOptions
+  export type Metadata = Types.Metadata
+  export type Pagination = Types.Pagination
+  export type Chunk = Types.Chunk
+  export type Filter = Types.Filter
+  export type OrFilter = Types.OrFilter
+  export type AndFilter = Types.AndFilter
+  export type FilterCondition = Types.FilterCondition
+  export type AddParams = Types.AddParams
+  export type AddResponse = Types.AddResponse
+  export type ProfileParams = Types.ProfileParams
+  export type ProfileResponse = Types.ProfileResponse
+  export type Profile = Types.Profile
+  export type ProfileMemory = Types.ProfileMemory
+  export type SearchDocumentsParams = Types.SearchDocumentsParams
+  export type SearchDocumentsResponse = Types.SearchDocumentsResponse
+  export type SearchMemoriesParams = Types.SearchMemoriesParams
+  export type SearchMemoriesResponse = Types.SearchMemoriesResponse
+  export type SearchExecuteParams = Types.SearchExecuteParams
+  export type SearchExecuteResponse = Types.SearchExecuteResponse
+  export type SearchResultItem = Types.SearchResultItem
+  export type SearchResults = Types.SearchResults
+  export type MemoryResult = Types.MemoryResult
+  export type Document = Types.Document
+  export type DocumentListParams = Types.DocumentListParams
+  export type DocumentListResponse = Types.DocumentListResponse
+  export type DocumentUpdateParams = Types.DocumentUpdateParams
+  export type DocumentUpdateResponse = Types.DocumentUpdateResponse
+  export type DocumentAddParams = Types.DocumentAddParams
+  export type DocumentAddResponse = Types.DocumentAddResponse
+  export type DocumentBatchAddParams = Types.DocumentBatchAddParams
+  export type DocumentBatchAddResponse = Types.DocumentBatchAddResponse
+  export type DocumentDeleteBulkParams = Types.DocumentDeleteBulkParams
+  export type DocumentDeleteBulkResponse = Types.DocumentDeleteBulkResponse
+  export type DocumentGetResponse = Types.DocumentGetResponse
+  export type DocumentListProcessingResponse = Types.DocumentListProcessingResponse
+  export type DocumentUploadFileParams = Types.DocumentUploadFileParams
+  export type DocumentUploadFileResponse = Types.DocumentUploadFileResponse
+  export type Memory = Types.Memory
+  export type MemoryListParams = Types.MemoryListParams
+  export type MemoryListResponse = Types.MemoryListResponse
+  export type MemoryAddParams = Types.MemoryAddParams
+  export type MemoryAddResponse = Types.MemoryAddResponse
+  export type MemoryUpdateParams = Types.MemoryUpdateParams
+  export type MemoryUpdateResponse = Types.MemoryUpdateResponse
+  export type MemoryForgetParams = Types.MemoryForgetParams
+  export type MemoryForgetResponse = Types.MemoryForgetResponse
+  export type MemoryGetResponse = Types.MemoryGetResponse
+  export type MemoryUpdateMemoryParams = Types.MemoryUpdateMemoryParams
+  export type MemoryUpdateMemoryResponse = Types.MemoryUpdateMemoryResponse
+  export type MemoryUploadFileParams = Types.MemoryUploadFileParams
+  export type MemoryUploadFileResponse = Types.MemoryUploadFileResponse
+  export type Connection = Types.Connection
+  export type ConnectionProvider = Types.ConnectionProvider
+  export type ConnectionCreateParams = Types.ConnectionCreateParams
+  export type ConnectionCreateResponse = Types.ConnectionCreateResponse
+  export type ConnectionListParams = Types.ConnectionListParams
+  export type ConnectionListResponse = Types.ConnectionListResponse
+  export type ConnectionConfigureParams = Types.ConnectionConfigureParams
+  export type ConnectionConfigureResponse = Types.ConnectionConfigureResponse
+  export type ConnectionDeleteByIDResponse = Types.ConnectionDeleteByIDResponse
+  export type ConnectionDeleteByProviderParams = Types.ConnectionDeleteByProviderParams
+  export type ConnectionDeleteByProviderResponse = Types.ConnectionDeleteByProviderResponse
+  export type ConnectionGetByIDResponse = Types.ConnectionGetByIDResponse
+  export type ConnectionGetByTagParams = Types.ConnectionGetByTagParams
+  export type ConnectionGetByTagResponse = Types.ConnectionGetByTagResponse
+  export type ConnectionImportParams = Types.ConnectionImportParams
+  export type ConnectionImportResponse = Types.ConnectionImportResponse
+  export type ConnectionListDocumentsParams = Types.ConnectionListDocumentsParams
+  export type ConnectionListDocumentsResponse = Types.ConnectionListDocumentsResponse
+  export type ConnectionResourcesParams = Types.ConnectionResourcesParams
+  export type ConnectionResource = Types.ConnectionResource
+  export type ConnectionResourcesResponse = Types.ConnectionResourcesResponse
+  export type Settings = Types.Settings
+  export type SettingUpdateParams = Types.SettingUpdateParams
+  export type SettingUpdateResponse = Types.SettingUpdateResponse
+  export type SettingGetResponse = Types.SettingGetResponse
+}

package/src/sdk/resources/base.ts

@@ -0,0 +1,65 @@
+/**
+ * Base resource class for API resources
+ */
+
+import { HTTPClient, APIPromise } from '../http.js'
+import type { RequestOptions } from '../types.js'
+
+export abstract class APIResource {
+  protected client: HTTPClient
+
+  constructor(client: HTTPClient) {
+    this.client = client
+  }
+
+  protected _get<T>(
+    path: string,
+    options?: { query?: Record<string, unknown>; requestOptions?: RequestOptions }
+  ): APIPromise<T> {
+    return this.client.get<T>(path, options)
+  }
+
+  protected _post<T>(
+    path: string,
+    options?: {
+      body?: unknown
+      query?: Record<string, unknown>
+      requestOptions?: RequestOptions
+    }
+  ): APIPromise<T> {
+    return this.client.post<T>(path, options)
+  }
+
+  protected _put<T>(
+    path: string,
+    options?: {
+      body?: unknown
+      query?: Record<string, unknown>
+      requestOptions?: RequestOptions
+    }
+  ): APIPromise<T> {
+    return this.client.put<T>(path, options)
+  }
+
+  protected _patch<T>(
+    path: string,
+    options?: {
+      body?: unknown
+      query?: Record<string, unknown>
+      requestOptions?: RequestOptions
+    }
+  ): APIPromise<T> {
+    return this.client.patch<T>(path, options)
+  }
+
+  protected _delete<T>(
+    path: string,
+    options?: {
+      body?: unknown
+      query?: Record<string, unknown>
+      requestOptions?: RequestOptions
+    }
+  ): APIPromise<T> {
+    return this.client.delete<T>(path, options)
+  }
+}

package/src/sdk/resources/connections.ts

@@ -0,0 +1,204 @@
+/**
+ * Connections Resource
+ * Manages external provider connections (GitHub, Gmail, Google Drive, etc.)
+ */
+
+import { APIResource } from './base.js'
+import { APIPromise } from '../http.js'
+import type {
+  RequestOptions,
+  ConnectionProvider,
+  ConnectionCreateParams,
+  ConnectionCreateResponse,
+  ConnectionListParams,
+  ConnectionListResponse,
+  ConnectionConfigureParams,
+  ConnectionConfigureResponse,
+  ConnectionDeleteByIDResponse,
+  ConnectionDeleteByProviderParams,
+  ConnectionDeleteByProviderResponse,
+  ConnectionGetByIDResponse,
+  ConnectionGetByTagParams,
+  ConnectionGetByTagResponse,
+  ConnectionImportParams,
+  ConnectionImportResponse,
+  ConnectionListDocumentsParams,
+  ConnectionListDocumentsResponse,
+  ConnectionResourcesParams,
+  ConnectionResourcesResponse,
+} from '../types.js'
+
+export class Connections extends APIResource {
+  /**
+   * Create a new connection to an external provider
+   *
+   * @param provider - Provider type (github, gmail, google-drive, notion, etc.)
+   * @param body - Connection configuration
+   * @param options - Request options
+   * @returns Authorization link and connection details
+   */
+  create(
+    provider: ConnectionProvider | string,
+    body?: ConnectionCreateParams | null,
+    options?: RequestOptions
+  ): APIPromise<ConnectionCreateResponse> {
+    return this._post<ConnectionCreateResponse>(`/v3/connections/${encodeURIComponent(provider)}`, {
+      body: body || {},
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * List all connections
+   *
+   * @param body - List parameters including filters
+   * @param options - Request options
+   * @returns Array of connections
+   */
+  list(body?: ConnectionListParams | null, options?: RequestOptions): APIPromise<ConnectionListResponse> {
+    return this._post<ConnectionListResponse>('/v3/connections/list', {
+      body: body || {},
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Get connection details by ID
+   *
+   * @param id - Connection ID
+   * @param options - Request options
+   * @returns Connection details
+   */
+  getByID(id: string, options?: RequestOptions): APIPromise<ConnectionGetByIDResponse> {
+    return this.client.get<ConnectionGetByIDResponse>(`/v3/connections/${encodeURIComponent(id)}`, {
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Get connections by container tag
+   *
+   * @param provider - Provider type
+   * @param body - Container tags to filter by
+   * @param options - Request options
+   * @returns Connection details
+   */
+  getByTag(
+    provider: ConnectionProvider | string,
+    body: ConnectionGetByTagParams,
+    options?: RequestOptions
+  ): APIPromise<ConnectionGetByTagResponse> {
+    return this._post<ConnectionGetByTagResponse>(`/v3/connections/${encodeURIComponent(provider)}/by-tag`, {
+      body,
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Configure resources for a connection
+   *
+   * @param id - Connection ID
+   * @param body - Resources to configure
+   * @param options - Request options
+   * @returns Configuration result
+   */
+  configure(
+    id: string,
+    body: ConnectionConfigureParams,
+    options?: RequestOptions
+  ): APIPromise<ConnectionConfigureResponse> {
+    return this._post<ConnectionConfigureResponse>(`/v3/connections/${encodeURIComponent(id)}/configure`, {
+      body,
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Delete a connection by ID
+   *
+   * @param id - Connection ID
+   * @param options - Request options
+   * @returns Deleted connection details
+   */
+  deleteByID(id: string, options?: RequestOptions): APIPromise<ConnectionDeleteByIDResponse> {
+    return this.client.delete<ConnectionDeleteByIDResponse>(`/v3/connections/${encodeURIComponent(id)}`, {
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Delete connections by provider and container tags
+   *
+   * @param provider - Provider type
+   * @param body - Container tags to filter which connections to delete
+   * @param options - Request options
+   * @returns Deleted connection details
+   */
+  deleteByProvider(
+    provider: ConnectionProvider | string,
+    body: ConnectionDeleteByProviderParams,
+    options?: RequestOptions
+  ): APIPromise<ConnectionDeleteByProviderResponse> {
+    return this.client.delete<ConnectionDeleteByProviderResponse>(`/v3/connections/${encodeURIComponent(provider)}`, {
+      body,
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Import resources from a connection
+   *
+   * @param id - Connection ID
+   * @param body - Import parameters
+   * @param options - Request options
+   * @returns Import results
+   */
+  import(
+    id: string,
+    body?: ConnectionImportParams | null,
+    options?: RequestOptions
+  ): APIPromise<ConnectionImportResponse> {
+    return this._post<ConnectionImportResponse>(`/v3/connections/${encodeURIComponent(id)}/import`, {
+      body: body || {},
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * List documents from a connection
+   *
+   * @param id - Connection ID
+   * @param body - List parameters
+   * @param options - Request options
+   * @returns Documents from the connection
+   */
+  listDocuments(
+    id: string,
+    body?: ConnectionListDocumentsParams | null,
+    options?: RequestOptions
+  ): APIPromise<ConnectionListDocumentsResponse> {
+    return this._post<ConnectionListDocumentsResponse>(`/v3/connections/${encodeURIComponent(id)}/documents`, {
+      body: body || {},
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Get available resources from a connection
+   *
+   * @param id - Connection ID
+   * @param body - Pagination parameters
+   * @param options - Request options
+   * @returns Available resources
+   */
+  resources(
+    id: string,
+    body?: ConnectionResourcesParams | null,
+    options?: RequestOptions
+  ): APIPromise<ConnectionResourcesResponse> {
+    return this.client.get<ConnectionResourcesResponse>(`/v3/connections/${encodeURIComponent(id)}/resources`, {
+      query: body as Record<string, unknown> | undefined,
+      requestOptions: options,
+    })
+  }
+}

package/src/sdk/resources/documents.ts

@@ -0,0 +1,163 @@
+/**
+ * Documents Resource
+ * Provides CRUD operations for documents
+ */
+
+import { APIResource } from './base.js'
+import { APIPromise } from '../http.js'
+import type {
+  RequestOptions,
+  DocumentListParams,
+  DocumentListResponse,
+  DocumentUpdateParams,
+  DocumentUpdateResponse,
+  DocumentAddParams,
+  DocumentAddResponse,
+  DocumentBatchAddParams,
+  DocumentBatchAddResponse,
+  DocumentDeleteBulkParams,
+  DocumentDeleteBulkResponse,
+  DocumentGetResponse,
+  DocumentListProcessingResponse,
+  DocumentUploadFileParams,
+  DocumentUploadFileResponse,
+} from '../types.js'
+
+export class Documents extends APIResource {
+  /**
+   * Retrieve a specific document by ID
+   *
+   * @param id - Document ID or customId
+   * @param options - Request options
+   * @returns The document with full details
+   */
+  get(id: string, options?: RequestOptions): APIPromise<DocumentGetResponse> {
+    return this.client.get<DocumentGetResponse>(`/v3/documents/${encodeURIComponent(id)}`, {
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Retrieve a paginated collection of documents
+   *
+   * @param body - List parameters including filters and pagination
+   * @param options - Request options
+   * @returns Paginated list of documents
+   */
+  list(body?: DocumentListParams | null, options?: RequestOptions): APIPromise<DocumentListResponse> {
+    return this._post<DocumentListResponse>('/v3/documents/list', {
+      body: body || {},
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Insert a new document
+   *
+   * @param body - Document content and metadata
+   * @param options - Request options
+   * @returns Created document ID and status
+   */
+  add(body: DocumentAddParams, options?: RequestOptions): APIPromise<DocumentAddResponse> {
+    return this._post<DocumentAddResponse>('/v3/add', {
+      body,
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Insert multiple documents in one request
+   *
+   * @param body - Array of documents to add
+   * @param options - Request options
+   * @returns Results for each document including any failures
+   */
+  batchAdd(body: DocumentBatchAddParams, options?: RequestOptions): APIPromise<DocumentBatchAddResponse> {
+    return this._post<DocumentBatchAddResponse>('/v3/documents/batch', {
+      body,
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Update a document's content or metadata
+   *
+   * @param id - Document ID or customId
+   * @param body - Updated content and/or metadata
+   * @param options - Request options
+   * @returns Updated document status
+   */
+  update(id: string, body?: DocumentUpdateParams | null, options?: RequestOptions): APIPromise<DocumentUpdateResponse> {
+    return this._patch<DocumentUpdateResponse>(`/v3/documents/${encodeURIComponent(id)}`, {
+      body: body || {},
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Delete a document by ID
+   *
+   * @param id - Document ID or customId
+   * @param options - Request options
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this.client.delete<void>(`/v3/documents/${encodeURIComponent(id)}`, {
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Delete multiple documents by IDs or container tags
+   *
+   * @param body - IDs or container tags to delete
+   * @param options - Request options
+   * @returns Count and IDs of deleted documents
+   */
+  deleteBulk(body?: DocumentDeleteBulkParams | null, options?: RequestOptions): APIPromise<DocumentDeleteBulkResponse> {
+    return this._post<DocumentDeleteBulkResponse>('/v3/documents/delete', {
+      body: body || {},
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Get documents currently being processed
+   *
+   * @param options - Request options
+   * @returns List of documents in processing state
+   */
+  listProcessing(options?: RequestOptions): APIPromise<DocumentListProcessingResponse> {
+    return this.client.get<DocumentListProcessingResponse>('/v3/documents/processing', {
+      requestOptions: options,
+    })
+  }
+
+  /**
+   * Upload a file for processing
+   *
+   * @param body - File and metadata for upload
+   * @param options - Request options
+   * @returns Created document ID and status
+   */
+  uploadFile(body: DocumentUploadFileParams, options?: RequestOptions): APIPromise<DocumentUploadFileResponse> {
+    const { file, containerTag, customId, metadata } = body
+
+    // Build additional form fields
+    const additionalFields: Record<string, string> = {}
+    if (containerTag) {
+      additionalFields.containerTag = containerTag
+    }
+    if (customId) {
+      additionalFields.customId = customId
+    }
+    if (metadata) {
+      additionalFields.metadata = JSON.stringify(metadata)
+    }
+
+    return this.client.uploadFile<DocumentUploadFileResponse>('/v3/documents/upload', file, {
+      fieldName: 'file',
+      additionalFields,
+      requestOptions: options,
+    })
+  }
+}

package/src/sdk/resources/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Resource exports
+ */
+
+export { APIResource } from './base.js'
+export { Search } from './search.js'
+export { Documents } from './documents.js'
+export { Memories } from './memories.js'
+export { Connections } from './connections.js'
+export { Settings } from './settings.js'