@usetransactional/memory 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,914 @@
+/**
+ * Transactional Memory SDK - Type Definitions
+ */
+/**
+ * Configuration for MemoryClient.
+ */
+interface MemoryClientConfig {
+    /** API key for authentication */
+    apiKey: string;
+    /** Base URL for the API (default: https://api.usetransactional.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retries for failed requests (default: 3) */
+    maxRetries?: number;
+    /** Custom headers to include in all requests */
+    headers?: Record<string, string>;
+}
+/**
+ * Memory entity types.
+ */
+declare enum MemoryEntityType {
+    USER = "user",
+    FACT = "fact",
+    TOPIC = "topic",
+    PREFERENCE = "preference",
+    EVENT = "event",
+    MESSAGE = "message",
+    SUMMARY = "summary",
+    ORGANIZATION = "organization"
+}
+/**
+ * Memory edge types (relationships).
+ */
+declare enum MemoryEdgeType {
+    PREFERS = "prefers",
+    MENTIONED = "mentioned",
+    DISCUSSED = "discussed",
+    ASKED_ABOUT = "asked_about",
+    RELATES_TO = "relates_to",
+    FOLLOWS_UP = "follows_up",
+    SUMMARIZES = "summarizes",
+    EXTRACTED_FROM = "extracted_from",
+    WORKS_AT = "works_at",
+    INTERESTED_IN = "interested_in"
+}
+/**
+ * Source of a memory fact.
+ */
+declare enum MemoryFactSource {
+    EXTRACTED = "extracted",
+    EXPLICIT = "explicit",
+    INFERRED = "inferred"
+}
+/**
+ * Session status.
+ */
+declare enum MemorySessionStatus {
+    ACTIVE = "ACTIVE",
+    EXPIRED = "EXPIRED",
+    DELETED = "DELETED"
+}
+/**
+ * Message role.
+ */
+declare enum MemoryMessageRole {
+    USER = "user",
+    ASSISTANT = "assistant",
+    SYSTEM = "system"
+}
+/**
+ * A memory entity.
+ */
+interface Memory {
+    /** Unique entity ID */
+    id: string;
+    /** Session this entity belongs to */
+    sessionId: string;
+    /** Entity type */
+    type: MemoryEntityType;
+    /** Entity name/key */
+    name: string;
+    /** Additional properties */
+    properties: Record<string, unknown>;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** How the entity was created */
+    source: MemoryFactSource;
+    /** Relevance score */
+    score?: number;
+    /** Whether entity has embeddings */
+    hasEmbedding?: boolean;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+/**
+ * A memory edge (relationship).
+ */
+interface MemoryEdge {
+    /** Unique edge ID */
+    id: string;
+    /** Source entity ID */
+    from: string;
+    /** Target entity ID */
+    to: string;
+    /** Relationship type */
+    type: MemoryEdgeType;
+    /** Relationship strength (0-1) */
+    weight: number;
+    /** Additional properties */
+    properties: Record<string, unknown>;
+    /** Creation timestamp */
+    createdAt: string;
+}
+/**
+ * A memory session.
+ */
+interface Session {
+    /** Session ID */
+    id: string;
+    /** External reference ID */
+    externalId: string | null;
+    /** Agent/bot ID */
+    agentId: string | null;
+    /** User ID */
+    userId: string | null;
+    /** Session status */
+    status: MemorySessionStatus;
+    /** Session configuration */
+    config?: SessionConfig;
+    /** Session statistics */
+    stats?: {
+        entityCount: number;
+        edgeCount: number;
+        messageCount: number;
+        lastActivityAt?: string;
+    };
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** Expiration timestamp */
+    expiresAt: string | null;
+}
+/**
+ * Session configuration.
+ */
+interface SessionConfig {
+    /** Embedding provider */
+    embeddingProvider?: string;
+    /** Embedding model */
+    embeddingModel?: string;
+    /** Auto-extract entities */
+    autoExtract?: boolean;
+    /** Auto-summarize conversations */
+    autoSummarize?: boolean;
+    /** Message count threshold for summarization */
+    summarizeThreshold?: number;
+}
+/**
+ * Parameters for creating a session.
+ */
+interface CreateSessionParams {
+    /** External reference ID */
+    externalId?: string;
+    /** Agent/bot ID */
+    agentId?: string;
+    /** User ID */
+    userId?: string;
+    /** Time-to-live in seconds (default: 24 hours) */
+    ttl?: number;
+    /** Session configuration */
+    config?: SessionConfig;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for updating a session.
+ */
+interface UpdateSessionParams {
+    /** New TTL in seconds */
+    ttl?: number;
+    /** Configuration updates */
+    config?: Partial<SessionConfig>;
+    /** Metadata updates */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Parameters for listing sessions.
+ */
+interface ListSessionsParams {
+    /** Filter by status */
+    status?: MemorySessionStatus;
+    /** Filter by agent ID */
+    agentId?: string;
+    /** Filter by user ID */
+    userId?: string;
+    /** Search in external ID or agent ID */
+    search?: string;
+    /** Page number (1-based) */
+    page?: number;
+    /** Results per page (default: 20, max: 100) */
+    limit?: number;
+}
+/**
+ * Parameters for adding a memory.
+ */
+interface AddMemoryParams {
+    /** Content to add */
+    content: string;
+    /** Session ID */
+    sessionId?: string;
+    /** User ID */
+    userId?: string;
+    /** Entity type */
+    type?: MemoryEntityType;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from adding a memory.
+ */
+interface AddMemoryResult {
+    /** Created entity ID */
+    id: string;
+    /** Session ID */
+    sessionId: string;
+    /** Processing status */
+    status: 'processing' | 'completed';
+}
+/**
+ * Parameters for updating a memory.
+ */
+interface UpdateMemoryParams {
+    /** New name */
+    name?: string;
+    /** New properties */
+    properties?: Record<string, unknown>;
+    /** New confidence */
+    confidence?: number;
+}
+/**
+ * Search strategy.
+ */
+type SearchStrategy = 'auto' | 'keyword' | 'semantic' | 'hybrid';
+/**
+ * Parameters for searching memories.
+ */
+interface SearchParams {
+    /** Search query */
+    query: string;
+    /** Scope to specific session */
+    sessionId?: string;
+    /** Scope to specific sessions */
+    sessionIds?: string[];
+    /** Filter by user ID */
+    userId?: string;
+    /** Filter by entity types */
+    types?: MemoryEntityType[];
+    /** Search strategy */
+    strategy?: SearchStrategy;
+    /** Minimum similarity threshold (0-1, default: 0.7) */
+    threshold?: number;
+    /** Maximum results (default: 10, max: 50) */
+    limit?: number;
+    /** Include related entities */
+    includeRelated?: boolean;
+}
+/**
+ * A search hit.
+ */
+interface SearchHit {
+    /** The matching entity */
+    entity: Memory;
+    /** Relevance score (0-1) */
+    score: number;
+    /** How the match was found */
+    matchType: 'keyword' | 'semantic' | 'hybrid';
+    /** Text highlights */
+    highlights: string[];
+    /** Related entities */
+    relatedEntities?: Array<{
+        id: string;
+        type: MemoryEntityType;
+        name: string;
+    }>;
+}
+/**
+ * Search result.
+ */
+interface SearchResult {
+    /** Search hits */
+    results: SearchHit[];
+    /** Query information */
+    query: {
+        original: string;
+        tokens: number;
+    };
+    /** Metadata */
+    meta: {
+        strategy: SearchStrategy;
+        searchTime: number;
+        totalMatches: number;
+    };
+}
+/**
+ * Parameters for getting context.
+ */
+interface GetContextParams {
+    /** User ID */
+    userId: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Focus query */
+    query?: string;
+    /** Maximum tokens (default: 4000) */
+    maxTokens?: number;
+    /** Include user profile */
+    includeProfile?: boolean;
+    /** Include facts */
+    includeFacts?: boolean;
+    /** Include preferences */
+    includePreferences?: boolean;
+}
+/**
+ * Context result.
+ */
+interface ContextResult {
+    /** Formatted context string for LLM */
+    context: string;
+    /** Token count */
+    tokenCount: number;
+    /** User profile */
+    profile?: {
+        userId: string;
+        name?: string;
+        preferences: Record<string, unknown>;
+    };
+    /** Facts */
+    facts: Array<{
+        key: string;
+        value: unknown;
+        confidence: number;
+    }>;
+    /** Preferences */
+    preferences: Array<{
+        name: string;
+        value: unknown;
+    }>;
+    /** Recent topics */
+    recentTopics: Array<{
+        name: string;
+        sentiment?: string;
+        lastDiscussed: string;
+    }>;
+}
+/**
+ * Parameters for URL ingestion.
+ */
+interface IngestUrlParams {
+    /** URL to ingest */
+    url: string;
+    /** Session ID */
+    sessionId?: string;
+    /** User ID */
+    userId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Options */
+    options?: {
+        extractEntities?: boolean;
+        generateEmbeddings?: boolean;
+        chunkSize?: number;
+        chunkOverlap?: number;
+    };
+}
+/**
+ * Result from URL ingestion.
+ */
+interface IngestUrlResult {
+    /** Memory ID */
+    memoryId: string;
+    /** Job ID (for async tracking) */
+    jobId?: string;
+    /** Final URL after redirects */
+    url: string;
+    /** Page title */
+    title: string;
+    /** Page description */
+    description?: string;
+    /** Author */
+    author?: string;
+    /** Published date */
+    publishedDate?: string;
+    /** Site name */
+    siteName?: string;
+    /** Content length */
+    contentLength: number;
+    /** Number of chunks */
+    chunks: number;
+    /** Extracted entities */
+    entities: Array<{
+        type: MemoryEntityType;
+        name: string;
+        value?: string;
+        confidence: number;
+    }>;
+    /** Processing time in ms */
+    processingTime: number;
+    /** Status */
+    status: 'processing' | 'completed';
+}
+/**
+ * Parameters for PDF ingestion.
+ */
+interface IngestPdfParams {
+    /** PDF file (Buffer or Blob) */
+    file: Buffer | Blob;
+    /** Filename */
+    filename: string;
+    /** Session ID */
+    sessionId?: string;
+    /** User ID */
+    userId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Options */
+    options?: {
+        extractEntities?: boolean;
+        generateEmbeddings?: boolean;
+        ocrFallback?: boolean;
+    };
+}
+/**
+ * Result from PDF ingestion.
+ */
+interface IngestPdfResult {
+    /** Memory ID */
+    memoryId: string;
+    /** Job ID */
+    jobId: string;
+    /** Filename */
+    filename: string;
+    /** Document title */
+    title: string;
+    /** Author */
+    author?: string;
+    /** Creation date */
+    createdDate?: string;
+    /** Page count */
+    pageCount: number;
+    /** Content length */
+    contentLength: number;
+    /** Number of chunks */
+    chunks: number;
+    /** Extracted entities */
+    entities: Array<{
+        type: MemoryEntityType;
+        name: string;
+        value?: string;
+        confidence: number;
+    }>;
+    /** Has images */
+    hasImages: boolean;
+    /** Has tables */
+    hasTables: boolean;
+    /** Processing time in ms */
+    processingTime: number;
+    /** Status */
+    status: 'processing' | 'completed';
+}
+/**
+ * Parameters for text ingestion.
+ */
+interface IngestTextParams {
+    /** Text content */
+    content: string;
+    /** Content type */
+    contentType?: 'text' | 'json' | 'markdown' | 'code';
+    /** Session ID */
+    sessionId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result from text ingestion.
+ */
+interface IngestTextResult {
+    /** Session ID */
+    sessionId: string;
+    /** Message ID */
+    messageId: string;
+    /** Content type */
+    contentType: string;
+    /** Status */
+    status: 'processing' | 'completed';
+    /** Whether a new session was created */
+    isNewSession: boolean;
+}
+/**
+ * User profile.
+ */
+interface UserProfile {
+    /** Profile ID */
+    id: number;
+    /** User ID */
+    userId: string;
+    /** Static facts */
+    staticFacts: {
+        name?: string;
+        role?: string;
+        company?: string;
+        timezone?: string;
+        language?: string;
+        email?: string;
+        preferences?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    /** Dynamic facts */
+    dynamicFacts: {
+        recentTopics?: string[];
+        interests?: string[];
+        painPoints?: string[];
+        goals?: string[];
+        expertise?: string[];
+        sentimentHistory?: Array<{
+            date: string;
+            sentiment: string;
+        }>;
+        [key: string]: unknown;
+    };
+    /** Total fact count */
+    factCount: number;
+    /** Total session count */
+    sessionCount: number;
+    /** Last session ID */
+    lastSessionId: string | null;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** Last activity timestamp */
+    lastActiveAt: string | null;
+}
+/**
+ * Parameters for upserting a profile.
+ */
+interface UpsertProfileParams {
+    /** Static facts to set/update */
+    staticFacts?: Partial<UserProfile['staticFacts']>;
+    /** Dynamic facts to set/update */
+    dynamicFacts?: Partial<UserProfile['dynamicFacts']>;
+}
+/**
+ * Graph node.
+ */
+interface GraphNode {
+    /** Node ID */
+    id: string;
+    /** Entity type */
+    type: MemoryEntityType;
+    /** Display name */
+    name: string;
+    /** Properties */
+    properties: Record<string, unknown>;
+    /** Score */
+    score: number;
+    /** Confidence */
+    confidence: number;
+}
+/**
+ * Graph edge.
+ */
+interface GraphEdge {
+    /** Edge ID */
+    id: string;
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Relationship type */
+    type: MemoryEdgeType;
+    /** Weight */
+    weight: number;
+    /** Properties */
+    properties: Record<string, unknown>;
+}
+/**
+ * Graph result.
+ */
+interface GraphResult {
+    /** Nodes */
+    nodes: GraphNode[];
+    /** Edges */
+    edges: GraphEdge[];
+    /** Stats */
+    stats: {
+        totalNodes: number;
+        totalEdges: number;
+        depth: number;
+    };
+}
+/**
+ * Parameters for getting graph.
+ */
+interface GetGraphParams {
+    /** Session ID */
+    sessionId?: string;
+    /** Center entity ID */
+    centerEntityId?: string;
+    /** Traversal depth */
+    depth?: number;
+    /** Filter by entity types */
+    entityTypes?: MemoryEntityType[];
+    /** Filter by edge types */
+    edgeTypes?: MemoryEdgeType[];
+    /** Minimum edge weight */
+    minWeight?: number;
+    /** Maximum nodes */
+    limit?: number;
+}
+/**
+ * Parameters for graph traversal.
+ */
+interface TraverseParams {
+    /** Starting entity ID */
+    startEntityId: string;
+    /** Traversal depth */
+    depth?: number;
+    /** Direction */
+    direction?: 'outbound' | 'inbound' | 'any';
+    /** Filter by entity types */
+    entityTypes?: MemoryEntityType[];
+    /** Filter by edge types */
+    edgeTypes?: MemoryEdgeType[];
+    /** Minimum edge weight */
+    minWeight?: number;
+    /** Maximum nodes */
+    limit?: number;
+}
+/**
+ * Paginated list response.
+ */
+interface PaginatedResponse<T> {
+    /** Data items */
+    data: T[];
+    /** Pagination metadata */
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+    };
+}
+/**
+ * Job status response.
+ */
+interface JobStatus {
+    /** Job ID */
+    jobId: string;
+    /** Status */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Progress (0-100) */
+    progress?: number;
+    /** Result data */
+    result?: unknown;
+    /** Error message */
+    error?: string;
+    /** Created at */
+    createdAt: string;
+    /** Completed at */
+    completedAt?: string;
+}
+
+/**
+ * Transactional Memory SDK - Client Implementation
+ */
+
+interface RequestOptions {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    timeout?: number;
+}
+/**
+ * Transactional Memory API Client.
+ *
+ * @example
+ * ```typescript
+ * import { MemoryClient } from '@transactional/memory-sdk';
+ *
+ * const client = new MemoryClient({
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * // Add a memory
+ * const result = await client.add({
+ *   content: 'User prefers TypeScript',
+ *   userId: 'user_123',
+ * });
+ *
+ * // Search memories
+ * const searchResult = await client.search({
+ *   query: 'programming language preferences',
+ *   userId: 'user_123',
+ * });
+ * ```
+ */
+declare class MemoryClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    private readonly maxRetries;
+    private readonly customHeaders;
+    /** Session operations */
+    readonly sessions: SessionOperations;
+    /** Profile operations */
+    readonly profiles: ProfileOperations;
+    /** Graph operations */
+    readonly graph: GraphOperations;
+    /** Ingest operations */
+    readonly ingest: IngestOperations;
+    constructor(config: MemoryClientConfig);
+    /**
+     * Make an HTTP request to the API.
+     */
+    request<T>(options: RequestOptions): Promise<T>;
+    private sleep;
+    /**
+     * Add a memory.
+     */
+    add(params: AddMemoryParams): Promise<AddMemoryResult>;
+    /**
+     * Search memories.
+     */
+    search(params: SearchParams): Promise<SearchResult>;
+    /**
+     * Get a specific memory by ID.
+     */
+    get(sessionId: string, memoryId: string): Promise<Memory>;
+    /**
+     * Update a memory.
+     */
+    update(sessionId: string, memoryId: string, params: UpdateMemoryParams): Promise<Memory>;
+    /**
+     * Delete a memory.
+     */
+    delete(sessionId: string, memoryId: string): Promise<void>;
+    /**
+     * Get context for LLM prompts.
+     */
+    getContext(params: GetContextParams): Promise<ContextResult>;
+    /**
+     * Get job status.
+     */
+    getJobStatus(jobId: string): Promise<JobStatus>;
+}
+declare class SessionOperations {
+    private client;
+    constructor(client: MemoryClient);
+    /**
+     * Create a new session.
+     */
+    create(params?: CreateSessionParams): Promise<Session>;
+    /**
+     * Get a session by ID.
+     */
+    get(sessionId: string): Promise<Session>;
+    /**
+     * List sessions.
+     */
+    list(params?: ListSessionsParams): Promise<PaginatedResponse<Session>>;
+    /**
+     * Update a session.
+     */
+    update(sessionId: string, params: UpdateSessionParams): Promise<Session>;
+    /**
+     * Delete a session.
+     */
+    delete(sessionId: string): Promise<void>;
+}
+declare class ProfileOperations {
+    private client;
+    constructor(client: MemoryClient);
+    /**
+     * Get a user profile.
+     */
+    get(userId: string): Promise<UserProfile>;
+    /**
+     * Create or update a user profile.
+     */
+    upsert(userId: string, params: UpsertProfileParams): Promise<UserProfile>;
+    /**
+     * Delete a user profile.
+     */
+    delete(userId: string): Promise<void>;
+}
+declare class GraphOperations {
+    private client;
+    constructor(client: MemoryClient);
+    /**
+     * Get the knowledge graph.
+     */
+    get(params?: GetGraphParams): Promise<GraphResult>;
+    /**
+     * Traverse the graph from a starting entity.
+     */
+    traverse(params: TraverseParams): Promise<GraphResult>;
+}
+declare class IngestOperations {
+    private client;
+    constructor(client: MemoryClient);
+    /**
+     * Ingest URL content.
+     */
+    url(params: IngestUrlParams): Promise<IngestUrlResult>;
+    /**
+     * Ingest PDF content.
+     */
+    pdf(params: IngestPdfParams): Promise<IngestPdfResult>;
+    /**
+     * Ingest text content.
+     */
+    text(params: IngestTextParams): Promise<IngestTextResult>;
+}
+
+/**
+ * Transactional Memory SDK - Error Classes
+ */
+/**
+ * Base error class for Memory SDK errors.
+ */
+declare class MemoryError extends Error {
+    /** Error code */
+    readonly code: string;
+    /** HTTP status code */
+    readonly status: number;
+    /** Additional error details */
+    readonly details?: unknown;
+    constructor(message: string, code: string, status: number, details?: unknown);
+}
+/**
+ * Authentication error (invalid or missing API key).
+ */
+declare class AuthenticationError extends MemoryError {
+    constructor(message?: string);
+}
+/**
+ * Validation error (invalid request parameters).
+ */
+declare class ValidationError extends MemoryError {
+    /** Field-level errors */
+    readonly fieldErrors?: Array<{
+        field: string;
+        message: string;
+    }>;
+    constructor(message: string, fieldErrors?: Array<{
+        field: string;
+        message: string;
+    }>);
+}
+/**
+ * Not found error (resource doesn't exist).
+ */
+declare class NotFoundError extends MemoryError {
+    /** Resource type */
+    readonly resourceType: string;
+    /** Resource ID */
+    readonly resourceId?: string;
+    constructor(resourceType: string, resourceId?: string);
+}
+/**
+ * Rate limit error (too many requests).
+ */
+declare class RateLimitError extends MemoryError {
+    /** Time to wait before retrying (seconds) */
+    readonly retryAfter: number;
+    /** Rate limit */
+    readonly limit?: number;
+    /** Remaining requests */
+    readonly remaining?: number;
+    /** Reset timestamp */
+    readonly reset?: number;
+    constructor(retryAfter: number, options?: {
+        limit?: number;
+        remaining?: number;
+        reset?: number;
+    });
+}
+/**
+ * Server error (internal server error).
+ */
+declare class ServerError extends MemoryError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Timeout error (request timed out).
+ */
+declare class TimeoutError extends MemoryError {
+    /** Timeout duration in ms */
+    readonly timeout: number;
+    constructor(timeout: number);
+}
+/**
+ * Network error (connection failed).
+ */
+declare class NetworkError extends MemoryError {
+    constructor(message?: string, details?: unknown);
+}
+
+export { type AddMemoryParams, type AddMemoryResult, AuthenticationError, type ContextResult, type CreateSessionParams, type GetContextParams, type GetGraphParams, type GraphEdge, type GraphNode, type GraphResult, type IngestPdfParams, type IngestPdfResult, type IngestTextParams, type IngestTextResult, type IngestUrlParams, type IngestUrlResult, type JobStatus, type ListSessionsParams, type Memory, MemoryClient, type MemoryClientConfig, type MemoryEdge, MemoryEdgeType, MemoryEntityType, MemoryError, MemoryFactSource, MemoryMessageRole, MemorySessionStatus, NetworkError, NotFoundError, type PaginatedResponse, RateLimitError, type SearchHit, type SearchParams, type SearchResult, type SearchStrategy, ServerError, type Session, type SessionConfig, TimeoutError, type TraverseParams, type UpdateMemoryParams, type UpdateSessionParams, type UpsertProfileParams, type UserProfile, ValidationError };