@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/types/api.types.ts

@@ -0,0 +1,193 @@
+import { z } from 'zod'
+
+// ============================================================================
+// Security Constants
+// ============================================================================
+
+/** Maximum content size in characters (50KB) */
+const MAX_CONTENT_CHARS = 50000
+
+/** Maximum query size in characters (10KB) */
+const MAX_QUERY_CHARS = 10000
+
+/** Maximum metadata size in bytes (10KB) */
+const MAX_METADATA_BYTES = 10240
+
+// ============================================================================
+// Base Response Types
+// ============================================================================
+
+export interface SuccessResponse<T> {
+  data: T
+  timing: number
+}
+
+export interface ErrorResponse {
+  error: {
+    code: string
+    message: string
+  }
+  status: number
+}
+
+export type ApiResponse<T> = SuccessResponse<T> | ErrorResponse
+
+// ============================================================================
+// Document Types
+// ============================================================================
+
+export const DocumentMetadataSchema = z
+  .record(z.unknown())
+  .optional()
+  .refine(
+    (metadata) => {
+      if (!metadata) return true
+      try {
+        const jsonSize = new TextEncoder().encode(JSON.stringify(metadata)).length
+        return jsonSize <= MAX_METADATA_BYTES
+      } catch {
+        return false
+      }
+    },
+    { message: `Metadata must be at most ${MAX_METADATA_BYTES} bytes (10KB)` }
+  )
+
+export const CreateDocumentSchema = z.object({
+  content: z
+    .string()
+    .min(1, 'Content is required')
+    .max(MAX_CONTENT_CHARS, `Content must be at most ${MAX_CONTENT_CHARS} characters`),
+  containerTag: z.string().min(1).max(100).optional(),
+  metadata: DocumentMetadataSchema,
+  customId: z.string().min(1).max(255).optional(),
+})
+
+export const UpdateDocumentSchema = z.object({
+  content: z
+    .string()
+    .min(1)
+    .max(MAX_CONTENT_CHARS, `Content must be at most ${MAX_CONTENT_CHARS} characters`)
+    .optional(),
+  containerTag: z.string().min(1).max(100).optional(),
+  metadata: DocumentMetadataSchema,
+})
+
+export const ListDocumentsQuerySchema = z.object({
+  containerTag: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(20),
+  offset: z.coerce.number().int().min(0).default(0),
+})
+
+export const BulkDeleteSchema = z
+  .object({
+    ids: z.array(z.string()).optional(),
+    containerTags: z.array(z.string()).optional(),
+  })
+  .refine((data) => data.ids?.length || data.containerTags?.length, {
+    message: 'Either ids or containerTags must be provided',
+  })
+
+export interface ApiDocument {
+  id: string
+  content: string
+  containerTag?: string
+  metadata?: Record<string, unknown>
+  customId?: string
+  createdAt: string
+  updatedAt: string
+}
+
+export type CreateDocumentInput = z.infer<typeof CreateDocumentSchema>
+export type UpdateDocumentInput = z.infer<typeof UpdateDocumentSchema>
+export type ListDocumentsQuery = z.infer<typeof ListDocumentsQuerySchema>
+export type BulkDeleteInput = z.infer<typeof BulkDeleteSchema>
+
+// ============================================================================
+// Search Types
+// ============================================================================
+
+export const SearchModeSchema = z.enum(['vector', 'fulltext', 'hybrid'])
+
+export const SearchFiltersSchema = z.object({
+  createdAfter: z.string().datetime().optional(),
+  createdBefore: z.string().datetime().optional(),
+  metadata: z.record(z.unknown()).optional(),
+})
+
+export const SearchRequestSchema = z.object({
+  q: z.string().min(1, 'Query is required').max(MAX_QUERY_CHARS, `Query must be at most ${MAX_QUERY_CHARS} characters`),
+  containerTag: z.string().max(100).optional(),
+  searchMode: SearchModeSchema.default('hybrid'),
+  limit: z.coerce.number().int().min(1).max(100).default(10),
+  threshold: z.coerce.number().min(0).max(1).default(0.7),
+  rerank: z.boolean().default(false),
+  filters: SearchFiltersSchema.optional(),
+})
+
+export interface SearchResult {
+  id: string
+  content: string
+  score: number
+  containerTag?: string
+  metadata?: Record<string, unknown>
+  highlights?: string[]
+}
+
+export interface SearchResponse {
+  results: SearchResult[]
+  total: number
+  query: string
+  searchMode: string
+}
+
+export type SearchRequest = z.infer<typeof SearchRequestSchema>
+export type SearchFilters = z.infer<typeof SearchFiltersSchema>
+
+// ============================================================================
+// Profile Types
+// ============================================================================
+
+export const UpdateProfileSchema = z.object({
+  name: z.string().min(1).max(255).optional(),
+  description: z.string().max(1000).optional(),
+  settings: z.record(z.unknown()).optional(),
+})
+
+export interface ApiProfile {
+  containerTag: string
+  name?: string
+  description?: string
+  settings?: Record<string, unknown>
+  documentCount: number
+  createdAt: string
+  updatedAt: string
+}
+
+export type UpdateProfileInput = z.infer<typeof UpdateProfileSchema>
+
+// ============================================================================
+// Authentication Types
+// ============================================================================
+
+export interface AuthContext {
+  userId: string
+  apiKey: string
+  scopes: string[]
+}
+
+// ============================================================================
+// Error Codes
+// ============================================================================
+
+export const ErrorCodes = {
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  RATE_LIMITED: 'RATE_LIMITED',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  BAD_REQUEST: 'BAD_REQUEST',
+} as const
+
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes]

package/src/types/document.types.ts

@@ -0,0 +1,103 @@
+/**
+ * Document and extraction types for supermemory content pipeline
+ */
+
+export type ContentType = 'text' | 'url' | 'pdf' | 'markdown' | 'code' | 'unknown'
+
+export type DocumentStatus = 'queued' | 'extracting' | 'chunking' | 'embedding' | 'indexing' | 'done' | 'error'
+
+export interface Document {
+  id: string
+  content: string
+  contentType?: ContentType
+  sourceUrl?: string
+  fileName?: string
+  language?: string
+  status: DocumentStatus
+  metadata: DocumentMetadata
+  createdAt: Date
+  updatedAt: Date
+  errorMessage?: string
+  retryCount: number
+}
+
+export interface DocumentMetadata {
+  title?: string
+  author?: string
+  description?: string
+  tags?: string[]
+  source?: string
+  mimeType?: string
+  wordCount?: number
+  charCount?: number
+  [key: string]: unknown
+}
+
+export interface Chunk {
+  id: string
+  documentId: string
+  content: string
+  type: ChunkType
+  position: ChunkPosition
+  metadata: ChunkMetadata
+  embedding?: number[]
+}
+
+export type ChunkType =
+  | 'paragraph'
+  | 'heading'
+  | 'code_block'
+  | 'function'
+  | 'class'
+  | 'list'
+  | 'table'
+  | 'quote'
+  | 'section'
+  | 'raw'
+
+export interface ChunkPosition {
+  index: number
+  start: number
+  end: number
+  lineStart?: number
+  lineEnd?: number
+}
+
+export interface ChunkMetadata {
+  headingLevel?: number
+  headingText?: string
+  language?: string
+  functionName?: string
+  className?: string
+  parentChunkId?: string
+  wordCount: number
+  charCount: number
+  [key: string]: unknown
+}
+
+export interface ExtractionResult {
+  content: string
+  contentType: ContentType
+  metadata: DocumentMetadata
+  rawContent?: string
+}
+
+export interface ChunkingOptions {
+  maxChunkSize?: number
+  minChunkSize?: number
+  overlap?: number
+  preserveStructure?: boolean
+}
+
+export interface PipelineResult {
+  documentId: string
+  status: DocumentStatus
+  chunks: Chunk[]
+  processingTimeMs: number
+  error?: string
+}
+
+export interface ExtractorInterface {
+  extract(content: string | Buffer, options?: Record<string, unknown>): Promise<ExtractionResult>
+  canHandle(content: string | Buffer): boolean
+}

package/src/types/index.ts

@@ -0,0 +1,241 @@
+import { z } from 'zod'
+
+// ============================================================================
+// Memory Types
+// ============================================================================
+
+export const MemoryTypeSchema = z.enum(['fact', 'event', 'preference', 'skill', 'relationship', 'context', 'note'])
+
+export type MemoryType = z.infer<typeof MemoryTypeSchema>
+
+export const RelationshipTypeSchema = z.enum(['updates', 'extends', 'derives', 'contradicts', 'related', 'supersedes'])
+
+export type RelationshipType = z.infer<typeof RelationshipTypeSchema>
+
+export interface MemoryRelationship {
+  type: RelationshipType
+  targetId: string
+  confidence: number
+  metadata?: Record<string, unknown>
+}
+
+export interface Memory {
+  id: string
+  content: string
+  type: MemoryType
+  embedding?: number[]
+  relationships: MemoryRelationship[]
+  isLatest: boolean
+  supersededBy?: string
+  containerTag?: string
+  metadata: MemoryMetadata
+  createdAt: Date
+  updatedAt: Date
+}
+
+export interface MemoryMetadata {
+  source?: string
+  confidence?: number
+  extractedFrom?: string
+  keywords?: string[]
+  entities?: Entity[]
+  [key: string]: unknown
+}
+
+export interface Entity {
+  name: string
+  type: 'person' | 'place' | 'organization' | 'date' | 'concept' | 'other'
+  mentions: number
+}
+
+// ============================================================================
+// Search Types
+// ============================================================================
+
+export const SearchModeSchema = z.enum(['vector', 'keyword', 'hybrid'])
+export type SearchMode = z.infer<typeof SearchModeSchema>
+
+export interface SearchQuery {
+  query: string
+  mode?: SearchMode
+  containerTag?: string
+  filters?: SearchFilters
+  limit?: number
+  offset?: number
+  rerank?: boolean
+  minScore?: number
+}
+
+export interface SearchFilters {
+  types?: MemoryType[]
+  dateRange?: {
+    start?: Date
+    end?: Date
+  }
+  metadata?: Record<string, unknown>
+  isLatest?: boolean
+}
+
+export interface SearchResult {
+  memory: Memory
+  score: number
+  highlights?: string[]
+}
+
+export interface SearchResponse {
+  results: SearchResult[]
+  total: number
+  query: string
+  mode: SearchMode
+  took: number
+}
+
+// ============================================================================
+// Profile Types
+// ============================================================================
+
+import { FactLifecycleCategorySchema, FactLifecycleCategory, BaseProfileFact } from './profile.base.js'
+
+/**
+ * Fact lifecycle category - determines expiration behavior
+ * Re-exported from profile.base for convenience
+ */
+export const FactCategorySchema = FactLifecycleCategorySchema
+
+/**
+ * Fact lifecycle category type
+ * Note: This represents the fact's lifecycle (static/dynamic/inferred),
+ * not its semantic category. For semantic categories (identity, skill, etc.),
+ * see FactSemanticCategory in profile.base.ts
+ */
+export type FactCategory = FactLifecycleCategory
+
+/**
+ * API-level ProfileFact - simplified version for API contracts
+ * Extends BaseProfileFact with key-value structure for API compatibility
+ */
+export interface ProfileFact extends BaseProfileFact {
+  /** Key for the fact (for key-value style access) */
+  key: string
+  /** Value of the fact */
+  value: string
+  /** Lifecycle category */
+  category: FactCategory
+  /** Source identifier */
+  source?: string
+}
+
+export interface Profile {
+  id: string
+  name?: string
+  facts: ProfileFact[]
+  memories: string[]
+  containerTags: string[]
+  createdAt: Date
+  updatedAt: Date
+}
+
+// ============================================================================
+// Extraction Types
+// ============================================================================
+
+export const ContentTypeSchema = z.enum(['text', 'url', 'markdown', 'html', 'json', 'pdf', 'image', 'unknown'])
+
+export type ContentType = z.infer<typeof ContentTypeSchema>
+
+export const ChunkingStrategySchema = z.enum(['sentence', 'paragraph', 'fixed', 'semantic', 'sliding_window'])
+
+export type ChunkingStrategy = z.infer<typeof ChunkingStrategySchema>
+
+export interface ExtractionResult {
+  content: string
+  contentType: ContentType
+  chunks: ContentChunk[]
+  metadata: ExtractionMetadata
+}
+
+export interface ContentChunk {
+  id: string
+  content: string
+  index: number
+  startOffset: number
+  endOffset: number
+  metadata?: Record<string, unknown>
+}
+
+export interface ExtractionMetadata {
+  originalLength: number
+  chunkCount: number
+  processingTime: number
+  strategy: ChunkingStrategy
+  sourceUrl?: string
+  title?: string
+  author?: string
+  publishedAt?: Date
+}
+
+// ============================================================================
+// Document Types
+// ============================================================================
+
+export const DocumentSchema = z.object({
+  id: z.string().optional(),
+  content: z.string().min(1, 'Content is required'),
+  containerTag: z.string().optional(),
+  metadata: z.record(z.unknown()).optional(),
+})
+
+export type DocumentInput = z.infer<typeof DocumentSchema>
+
+export interface Document {
+  id: string
+  content: string
+  containerTag?: string
+  memories: Memory[]
+  metadata: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+}
+
+// ============================================================================
+// API Types
+// ============================================================================
+
+export interface APIError {
+  code: string
+  message: string
+  details?: unknown
+}
+
+export interface APIResponse<T> {
+  success: boolean
+  data?: T
+  error?: APIError
+}
+
+export interface PaginatedResponse<T> extends APIResponse<T[]> {
+  pagination: {
+    total: number
+    limit: number
+    offset: number
+    hasMore: boolean
+  }
+}
+
+// ============================================================================
+// SDK Types
+// ============================================================================
+
+export interface SDKConfig {
+  apiKey: string
+  baseUrl?: string
+  timeout?: number
+  retries?: number
+  retryDelay?: number
+}
+
+export interface RateLimitInfo {
+  limit: number
+  remaining: number
+  reset: Date
+}

package/src/types/profile.base.ts

@@ -0,0 +1,133 @@
+/**
+ * Base Profile Types for Supermemory Clone
+ *
+ * Shared base interfaces for profile-related types to prevent duplication
+ * across profile.types.ts and types/index.ts
+ */
+
+import { z } from 'zod'
+
+// ============================================================================
+// Base Schemas
+// ============================================================================
+
+/**
+ * Fact lifecycle category - determines expiration behavior
+ * Used in types/index.ts Profile system
+ */
+export const FactLifecycleCategorySchema = z.enum([
+  'static', // Long-term, rarely changes
+  'dynamic', // Temporary, expires over time
+  'inferred', // Derived from other facts
+])
+
+export type FactLifecycleCategory = z.infer<typeof FactLifecycleCategorySchema>
+
+/**
+ * Fact semantic category - describes what the fact is about
+ * Used in services/profile.types.ts ProfileFact
+ */
+export const FactSemanticCategorySchema = z.enum([
+  'identity', // Name, role, company
+  'preference', // Likes, dislikes, preferences
+  'skill', // Technical skills, expertise
+  'background', // Education, history
+  'relationship', // Connections, team members
+  'project', // Current/past projects
+  'goal', // Objectives, aspirations
+  'context', // Current situation, temporary context
+  'other', // Uncategorized
+])
+
+export type FactSemanticCategory = z.infer<typeof FactSemanticCategorySchema>
+
+/**
+ * Fact type - static or dynamic lifecycle
+ */
+export const FactTypeSchema = z.enum(['static', 'dynamic'])
+
+export type FactType = z.infer<typeof FactTypeSchema>
+
+// ============================================================================
+// Base ProfileFact Schema
+// ============================================================================
+
+/**
+ * Base schema for ProfileFact - shared between service and type layers
+ * Contains the common fields that all ProfileFact implementations must have
+ */
+export const BaseProfileFactSchema = z.object({
+  /** Unique identifier for the fact */
+  id: z.string(),
+
+  /** The actual fact content */
+  content: z.string().min(1),
+
+  /** Confidence score of the extraction (0-1) */
+  confidence: z.number().min(0).max(1),
+
+  /** When this fact was created/extracted */
+  createdAt: z.date(),
+
+  /** When this fact was last updated */
+  updatedAt: z.date(),
+
+  /** Source content or document this was extracted from */
+  sourceId: z.string().optional(),
+})
+
+export type BaseProfileFact = z.infer<typeof BaseProfileFactSchema>
+
+// ============================================================================
+// Service Layer ProfileFact (extended version)
+// ============================================================================
+
+/**
+ * Service layer ProfileFact schema - used in profile.service.ts
+ * Extends base with service-specific fields
+ */
+export const ServiceProfileFactSchema = BaseProfileFactSchema.extend({
+  /** Whether this is a static (long-term) or dynamic (temporary) fact */
+  type: FactTypeSchema,
+
+  /** When this fact was extracted */
+  extractedAt: z.date(),
+
+  /** When this fact expires (only for dynamic facts) */
+  expiresAt: z.date().optional(),
+
+  /** Category of the fact for organization */
+  category: FactSemanticCategorySchema.optional(),
+
+  /** Number of times this fact has been reinforced */
+  reinforcementCount: z.number().int().min(0),
+
+  /** Last time this fact was accessed or reinforced */
+  lastAccessedAt: z.date(),
+})
+
+export type ServiceProfileFact = z.infer<typeof ServiceProfileFactSchema>
+
+// ============================================================================
+// Type Layer ProfileFact (API version)
+// ============================================================================
+
+/**
+ * Type layer ProfileFact schema - used in types/index.ts
+ * Simpler version for API contracts
+ */
+export const TypeProfileFactSchema = BaseProfileFactSchema.extend({
+  /** Key-value style fact key */
+  key: z.string(),
+
+  /** Fact value */
+  value: z.string(),
+
+  /** Lifecycle category */
+  category: FactLifecycleCategorySchema,
+
+  /** Source identifier */
+  source: z.string().optional(),
+})
+
+export type TypeProfileFact = z.infer<typeof TypeProfileFactSchema>