@cilow/sdk 0.2.0 → 0.2.1

package/dist/types.d.mts

@@ -0,0 +1,494 @@
+/**
+ * Cilow SDK TypeScript Type Definitions
+ *
+ * Comprehensive type definitions for the Cilow memory system.
+ */
+/**
+ * Memory tier classification based on access frequency and recency
+ */
+type MemoryTier = 'hot' | 'warm' | 'cold';
+/**
+ * Memory status for lifecycle management
+ */
+type MemoryStatus = 'active' | 'archived' | 'deleted';
+/**
+ * Core memory entity representing a stored piece of information
+ */
+interface Memory {
+    /** Unique identifier for the memory */
+    id: string;
+    /** The content of the memory */
+    content: string;
+    /** Tags for categorization and filtering */
+    tags: string[];
+    /** User ID associated with this memory */
+    userId?: string;
+    /** Session ID for grouping related memories */
+    sessionId?: string;
+    /** Current tier classification */
+    tier: MemoryTier;
+    /** Memory status */
+    status: MemoryStatus;
+    /** Access count for prioritization */
+    accessCount: number;
+    /** Token count for the content */
+    tokenCount: number;
+    /** Embedding vector (if available) */
+    embedding?: number[];
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+    /** ISO timestamp of creation */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+    /** ISO timestamp of last access */
+    lastAccessedAt: string;
+}
+/**
+ * Minimal memory representation for list operations
+ */
+interface MemorySummary {
+    id: string;
+    content: string;
+    tags: string[];
+    tier: MemoryTier;
+    createdAt: string;
+}
+/**
+ * Options for creating a new memory
+ */
+interface CreateMemoryOptions {
+    /** Tags to apply to the memory */
+    tags?: string[];
+    /** User ID to associate */
+    userId?: string;
+    /** Session ID for grouping */
+    sessionId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Force a specific tier */
+    tier?: MemoryTier;
+}
+/**
+ * Options for updating a memory
+ */
+interface UpdateMemoryOptions {
+    /** New content */
+    content?: string;
+    /** New tags (replaces existing) */
+    tags?: string[];
+    /** Updated metadata (merged with existing) */
+    metadata?: Record<string, unknown>;
+    /** Force tier change */
+    tier?: MemoryTier;
+}
+/**
+ * Search result containing a memory and its relevance score
+ */
+interface SearchResult {
+    /** The matching memory */
+    memory: Memory;
+    /** Relevance score (0.0 - 1.0) */
+    score: number;
+    /** Matched terms or phrases */
+    matchedTerms?: string[];
+    /** Highlighted content snippets */
+    highlights?: string[];
+}
+/**
+ * Search query parameters
+ */
+interface SearchQuery {
+    /** The search text */
+    text: string;
+    /** Maximum number of results */
+    limit?: number;
+    /** Minimum relevance score threshold (0.0 - 1.0) */
+    minRelevance?: number;
+    /** Filter by tags (AND logic) */
+    tags?: string[];
+    /** Filter by user ID */
+    userId?: string;
+    /** Filter by session ID */
+    sessionId?: string;
+    /** Filter by tier */
+    tier?: MemoryTier;
+    /** Filter by date range - start */
+    createdAfter?: string;
+    /** Filter by date range - end */
+    createdBefore?: string;
+    /** Include archived memories */
+    includeArchived?: boolean;
+    /** Search mode */
+    mode?: 'semantic' | 'keyword' | 'hybrid';
+}
+/**
+ * Advanced search options for complex queries
+ */
+interface AdvancedSearchOptions extends SearchQuery {
+    /** Boost recent memories */
+    recencyBoost?: number;
+    /** Boost frequently accessed memories */
+    frequencyBoost?: number;
+    /** Required tags (must have all) */
+    requiredTags?: string[];
+    /** Excluded tags (must not have any) */
+    excludedTags?: string[];
+    /** Metadata filters */
+    metadataFilters?: Record<string, unknown>;
+    /** Custom reranking function name */
+    reranker?: string;
+}
+/**
+ * Node in the memory knowledge graph
+ */
+interface GraphNode {
+    /** Unique node identifier */
+    id: string;
+    /** Node type/label */
+    type: string;
+    /** Display name */
+    name: string;
+    /** Node properties */
+    properties: Record<string, unknown>;
+    /** Associated memory IDs */
+    memoryIds: string[];
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+}
+/**
+ * Edge connecting two nodes in the graph
+ */
+interface GraphEdge {
+    /** Unique edge identifier */
+    id: string;
+    /** Source node ID */
+    sourceId: string;
+    /** Target node ID */
+    targetId: string;
+    /** Relationship type */
+    type: string;
+    /** Edge weight/strength */
+    weight: number;
+    /** Edge properties */
+    properties: Record<string, unknown>;
+    /** Creation timestamp */
+    createdAt: string;
+}
+/**
+ * Subgraph result for graph traversal queries
+ */
+interface GraphSubgraph {
+    /** Nodes in the subgraph */
+    nodes: GraphNode[];
+    /** Edges in the subgraph */
+    edges: GraphEdge[];
+    /** Central node ID (if applicable) */
+    centerId?: string;
+}
+/**
+ * Options for graph traversal
+ */
+interface GraphTraversalOptions {
+    /** Starting node ID */
+    startNodeId: string;
+    /** Maximum traversal depth */
+    maxDepth?: number;
+    /** Filter by relationship types */
+    relationshipTypes?: string[];
+    /** Maximum nodes to return */
+    limit?: number;
+    /** Traversal direction */
+    direction?: 'outbound' | 'inbound' | 'both';
+}
+/**
+ * Memory system statistics
+ */
+interface MemoryStats {
+    /** Total number of memories */
+    totalMemories: number;
+    /** Number of hot tier memories */
+    hotMemories: number;
+    /** Number of warm tier memories */
+    warmMemories: number;
+    /** Number of cold tier memories */
+    coldMemories: number;
+    /** Total token count across all memories */
+    totalTokens: number;
+    /** Average tokens per memory */
+    averageTokensPerMemory: number;
+    /** Number of unique users */
+    uniqueUsers: number;
+    /** Number of unique sessions */
+    uniqueSessions: number;
+    /** Total number of tags */
+    totalTags: number;
+    /** Storage size in bytes */
+    storageSizeBytes: number;
+    /** Stats generation timestamp */
+    generatedAt: string;
+}
+/**
+ * Tag with usage count
+ */
+interface TagCount {
+    /** Tag name */
+    tag: string;
+    /** Usage count */
+    count: number;
+}
+/**
+ * User activity statistics
+ */
+interface UserStats {
+    /** User ID */
+    userId: string;
+    /** Number of memories */
+    memoryCount: number;
+    /** Total tokens used */
+    totalTokens: number;
+    /** Number of sessions */
+    sessionCount: number;
+    /** First activity timestamp */
+    firstActivityAt: string;
+    /** Last activity timestamp */
+    lastActivityAt: string;
+}
+/**
+ * Base event type
+ */
+interface BaseEvent {
+    /** Event type identifier */
+    type: string;
+    /** Event timestamp */
+    timestamp: string;
+    /** Correlation ID for tracking */
+    correlationId?: string;
+}
+/**
+ * Memory created event
+ */
+interface MemoryCreatedEvent extends BaseEvent {
+    type: 'memory.created';
+    /** The created memory */
+    memory: Memory;
+}
+/**
+ * Memory updated event
+ */
+interface MemoryUpdatedEvent extends BaseEvent {
+    type: 'memory.updated';
+    /** The updated memory */
+    memory: Memory;
+    /** Changed fields */
+    changedFields: string[];
+}
+/**
+ * Memory deleted event
+ */
+interface MemoryDeletedEvent extends BaseEvent {
+    type: 'memory.deleted';
+    /** Deleted memory ID */
+    memoryId: string;
+}
+/**
+ * Memory tier changed event
+ */
+interface MemoryTierChangedEvent extends BaseEvent {
+    type: 'memory.tier_changed';
+    /** Memory ID */
+    memoryId: string;
+    /** Previous tier */
+    previousTier: MemoryTier;
+    /** New tier */
+    newTier: MemoryTier;
+}
+/**
+ * Graph node created event
+ */
+interface GraphNodeCreatedEvent extends BaseEvent {
+    type: 'graph.node_created';
+    /** The created node */
+    node: GraphNode;
+}
+/**
+ * Graph edge created event
+ */
+interface GraphEdgeCreatedEvent extends BaseEvent {
+    type: 'graph.edge_created';
+    /** The created edge */
+    edge: GraphEdge;
+}
+/**
+ * Connection status event
+ */
+interface ConnectionStatusEvent extends BaseEvent {
+    type: 'connection.status';
+    /** Connection status */
+    status: 'connected' | 'disconnected' | 'reconnecting';
+    /** Reason for status change */
+    reason?: string;
+}
+/**
+ * Union type of all events
+ */
+type CilowEvent = MemoryCreatedEvent | MemoryUpdatedEvent | MemoryDeletedEvent | MemoryTierChangedEvent | GraphNodeCreatedEvent | GraphEdgeCreatedEvent | ConnectionStatusEvent;
+/**
+ * Pagination parameters
+ */
+interface PaginationParams {
+    /** Number of items per page */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Cursor for cursor-based pagination */
+    cursor?: string;
+}
+/**
+ * Paginated response wrapper
+ */
+interface PaginatedResponse<T> {
+    /** Items in this page */
+    items: T[];
+    /** Total count of items */
+    total: number;
+    /** Current offset */
+    offset: number;
+    /** Items per page */
+    limit: number;
+    /** Cursor for next page */
+    nextCursor?: string;
+    /** Whether there are more items */
+    hasMore: boolean;
+}
+/**
+ * API error response
+ */
+interface ApiError {
+    /** Error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Additional error details */
+    details?: Record<string, unknown>;
+    /** Request ID for debugging */
+    requestId?: string;
+}
+/**
+ * Health check response
+ */
+interface HealthCheck {
+    /** Service status */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Service version */
+    version: string;
+    /** Uptime in seconds */
+    uptimeSeconds: number;
+    /** Component statuses */
+    components: {
+        name: string;
+        status: 'healthy' | 'degraded' | 'unhealthy';
+        latencyMs?: number;
+    }[];
+}
+/**
+ * Client configuration options
+ */
+interface CilowConfig {
+    /** Base URL of the Cilow API */
+    apiUrl: string;
+    /** API key for authentication */
+    apiKey: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Number of retry attempts for failed requests */
+    retries?: number;
+    /** Custom headers to include in requests */
+    headers?: Record<string, string>;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * WebSocket configuration options
+ */
+interface WebSocketConfig {
+    /** WebSocket URL (defaults to apiUrl with ws:// protocol) */
+    wsUrl?: string;
+    /** Reconnection attempts */
+    reconnectAttempts?: number;
+    /** Reconnection delay in milliseconds */
+    reconnectDelay?: number;
+    /** Heartbeat interval in milliseconds */
+    heartbeatInterval?: number;
+    /** Message queue size for offline buffering */
+    messageQueueSize?: number;
+}
+/**
+ * Combined configuration for full client
+ */
+interface FullCilowConfig extends CilowConfig, WebSocketConfig {
+    /** Default user ID for all operations */
+    defaultUserId?: string;
+    /** Default session ID */
+    defaultSessionId?: string;
+    /** Default tags to apply */
+    defaultTags?: string[];
+}
+/**
+ * Context result for AI integrations
+ */
+interface ContextResult {
+    /** Formatted context string */
+    context: string;
+    /** Number of memories used */
+    memoriesUsed: number;
+    /** Estimated token count */
+    estimatedTokens: number;
+    /** Memory IDs included */
+    memoryIds: string[];
+    /** Search scores */
+    scores: number[];
+}
+/**
+ * Conversation turn for storing dialogues
+ */
+interface ConversationTurn {
+    /** User's message */
+    userMessage: string;
+    /** Assistant's response */
+    assistantResponse: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Batch operation result
+ */
+interface BatchResult<T> {
+    /** Successful operations */
+    succeeded: T[];
+    /** Failed operations with errors */
+    failed: {
+        item: T;
+        error: string;
+    }[];
+    /** Total operations attempted */
+    total: number;
+}
+/**
+ * Check if an event is a memory event
+ */
+declare function isMemoryEvent(event: CilowEvent): event is MemoryCreatedEvent | MemoryUpdatedEvent | MemoryDeletedEvent;
+/**
+ * Check if an event is a graph event
+ */
+declare function isGraphEvent(event: CilowEvent): event is GraphNodeCreatedEvent | GraphEdgeCreatedEvent;
+/**
+ * Check if an object is an API error
+ */
+declare function isApiError(obj: unknown): obj is ApiError;
+
+export { type AdvancedSearchOptions, type ApiError, type BaseEvent, type BatchResult, type CilowConfig, type CilowEvent, type ConnectionStatusEvent, type ContextResult, type ConversationTurn, type CreateMemoryOptions, type FullCilowConfig, type GraphEdge, type GraphEdgeCreatedEvent, type GraphNode, type GraphNodeCreatedEvent, type GraphSubgraph, type GraphTraversalOptions, type HealthCheck, type Memory, type MemoryCreatedEvent, type MemoryDeletedEvent, type MemoryStats, type MemoryStatus, type MemorySummary, type MemoryTier, type MemoryTierChangedEvent, type MemoryUpdatedEvent, type PaginatedResponse, type PaginationParams, type SearchQuery, type SearchResult, type TagCount, type UpdateMemoryOptions, type UserStats, type WebSocketConfig, isApiError, isGraphEvent, isMemoryEvent };