@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/api/routes/documents.ts

@@ -0,0 +1,286 @@
+import { Hono } from 'hono'
+import { v4 as uuidv4 } from 'uuid'
+import {
+  CreateDocumentSchema,
+  UpdateDocumentSchema,
+  ListDocumentsQuerySchema,
+  BulkDeleteSchema,
+  ApiDocument,
+  SuccessResponse,
+} from '../../types/api.types.js'
+import { requireScopes } from '../middleware/auth.js'
+import { notFound, validationError } from '../middleware/errorHandler.js'
+import { uploadRateLimit } from '../middleware/rateLimit.js'
+import { getDocumentService } from '../../services/documents.service.js'
+import { enqueueDocumentForProcessing } from '../../services/ingestion.service.js'
+import { getLogger } from '../../utils/logger.js'
+
+const documentsRouter = new Hono()
+const documentsService = getDocumentService()
+const logger = getLogger('documents-route')
+
+/**
+ * POST / - Add a new document
+ */
+documentsRouter.post('/', requireScopes('write'), async (c) => {
+  const startTime = Date.now()
+
+  const body = await c.req.json()
+  const validatedData = CreateDocumentSchema.parse(body)
+
+  // Check for duplicate customId
+  if (validatedData.customId) {
+    const existing = await documentsService.getDocumentByCustomId(validatedData.customId)
+    if (existing) {
+      validationError(`Document with customId '${validatedData.customId}' already exists`)
+    }
+  }
+
+  const created = await documentsService.createDocument({
+    id: uuidv4(),
+    content: validatedData.content,
+    containerTag: validatedData.containerTag,
+    metadata: validatedData.metadata,
+    customId: validatedData.customId,
+    contentType: 'text/plain',
+  })
+
+  const ingestion = await enqueueDocumentForProcessing({
+    documentId: created.id,
+    content: created.content,
+    containerTag: created.containerTag ?? 'default',
+    sourceType: 'text',
+  })
+  if (ingestion.error) {
+    logger.warn('Document ingestion reported error', {
+      documentId: created.id,
+      mode: ingestion.mode,
+      error: ingestion.error,
+    })
+  }
+
+  const response: SuccessResponse<ApiDocument> = {
+    data: created,
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response, 201)
+})
+
+/**
+ * GET /:id - Get a document by ID
+ */
+documentsRouter.get('/:id', requireScopes('read'), async (c) => {
+  const startTime = Date.now()
+  const id = c.req.param('id')
+
+  const foundDocument = await documentsService.getDocument(id)
+
+  if (!foundDocument) {
+    return notFound('Document', id)
+  }
+
+  const response: SuccessResponse<ApiDocument> = {
+    data: foundDocument,
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+/**
+ * PUT /:id - Update a document
+ */
+documentsRouter.put('/:id', requireScopes('write'), async (c) => {
+  const startTime = Date.now()
+  const id = c.req.param('id')
+
+  const body = await c.req.json()
+  const validatedData = UpdateDocumentSchema.parse(body)
+
+  const updatedDocument = await documentsService.updateDocument(id, {
+    content: validatedData.content,
+    containerTag: validatedData.containerTag,
+    metadata: validatedData.metadata,
+  })
+
+  if (!updatedDocument) {
+    return notFound('Document', id)
+  }
+
+  if (validatedData.content) {
+    const ingestion = await enqueueDocumentForProcessing({
+      documentId: updatedDocument.id,
+      content: updatedDocument.content,
+      containerTag: updatedDocument.containerTag ?? 'default',
+      sourceType: 'text',
+    })
+    if (ingestion.error) {
+      logger.warn('Document re-ingestion reported error', {
+        documentId: updatedDocument.id,
+        mode: ingestion.mode,
+        error: ingestion.error,
+      })
+    }
+  }
+
+  const response: SuccessResponse<ApiDocument> = {
+    data: updatedDocument,
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+/**
+ * DELETE /:id - Delete a document
+ */
+documentsRouter.delete('/:id', requireScopes('write'), async (c) => {
+  const startTime = Date.now()
+  const id = c.req.param('id')
+
+  const deletedId = await documentsService.deleteDocument(id)
+
+  if (!deletedId) {
+    return notFound('Document', id)
+  }
+
+  const response: SuccessResponse<{ deleted: true; id: string }> = {
+    data: { deleted: true, id: deletedId },
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+/**
+ * GET / - List documents with optional filtering
+ */
+documentsRouter.get('/', requireScopes('read'), async (c) => {
+  const startTime = Date.now()
+
+  const query = ListDocumentsQuerySchema.parse({
+    containerTag: c.req.query('containerTag'),
+    limit: c.req.query('limit'),
+    offset: c.req.query('offset'),
+  })
+
+  const { documents: results, total } = await documentsService.listDocuments({
+    containerTag: query.containerTag,
+    limit: query.limit,
+    offset: query.offset,
+  })
+
+  const response: SuccessResponse<{
+    documents: ApiDocument[]
+    total: number
+    limit: number
+    offset: number
+  }> = {
+    data: {
+      documents: results,
+      total,
+      limit: query.limit,
+      offset: query.offset,
+    },
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+/**
+ * POST /file - Upload a file as a document
+ */
+documentsRouter.post('/file', requireScopes('write'), uploadRateLimit, async (c) => {
+  const startTime = Date.now()
+
+  const formData = await c.req.formData()
+  const file = formData.get('file')
+  const containerTag = formData.get('containerTag') as string | null
+  const metadataStr = formData.get('metadata') as string | null
+
+  if (!file || !(file instanceof File)) {
+    validationError('File is required')
+  }
+
+  // Parse metadata if provided
+  let metadata: Record<string, unknown> | undefined
+  if (metadataStr) {
+    try {
+      metadata = JSON.parse(metadataStr)
+    } catch {
+      validationError('Invalid metadata JSON')
+    }
+  }
+
+  // Read file content
+  const content = await file.text()
+
+  if (!content.trim()) {
+    validationError('File content is empty')
+  }
+
+  const newDocument = await documentsService.createDocument({
+    id: uuidv4(),
+    content,
+    containerTag: containerTag || undefined,
+    metadata: {
+      ...metadata,
+      filename: file.name,
+      fileType: file.type,
+      fileSize: file.size,
+    },
+    contentType: file.type || 'text/plain',
+  })
+
+  const ingestion = await enqueueDocumentForProcessing({
+    documentId: newDocument.id,
+    content: newDocument.content,
+    containerTag: newDocument.containerTag ?? 'default',
+    sourceType: 'file',
+  })
+  if (ingestion.error) {
+    logger.warn('File ingestion reported error', {
+      documentId: newDocument.id,
+      mode: ingestion.mode,
+      error: ingestion.error,
+    })
+  }
+
+  const responseTime = Date.now()
+  const response: SuccessResponse<ApiDocument> = {
+    data: newDocument,
+    timing: responseTime - startTime,
+  }
+
+  return c.json(response, 201)
+})
+
+/**
+ * POST /bulk-delete - Delete multiple documents
+ */
+documentsRouter.post('/bulk-delete', requireScopes('write'), async (c) => {
+  const startTime = Date.now()
+
+  const body = await c.req.json()
+  const validatedData = BulkDeleteSchema.parse(body)
+
+  const { deletedIds, notFoundIds } = await documentsService.bulkDelete({
+    ids: validatedData.ids,
+    containerTags: validatedData.containerTags,
+  })
+
+  const response: SuccessResponse<{ deleted: string[]; notFound: string[]; count: number }> = {
+    data: {
+      deleted: deletedIds,
+      notFound: notFoundIds,
+      count: deletedIds.length,
+    },
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+export { documentsRouter }

package/src/api/routes/profiles.ts

@@ -0,0 +1,237 @@
+import { Hono } from 'hono'
+import { UpdateProfileSchema, ApiProfile, SuccessResponse } from '../../types/api.types.js'
+import { requireScopes } from '../middleware/auth.js'
+import { notFound } from '../middleware/errorHandler.js'
+import { getDatabaseUrl } from '../../db/client.js'
+import { getPostgresDatabase } from '../../db/postgres.js'
+import { containerTags } from '../../db/schema/containers.schema.js'
+import { documents } from '../../db/schema/documents.schema.js'
+import { desc, eq, inArray, sql } from 'drizzle-orm'
+
+const profilesRouter = new Hono()
+const db = getPostgresDatabase(getDatabaseUrl())
+
+type ContainerTagRow = typeof containerTags.$inferSelect
+
+function normalizeSettings(value: unknown): Record<string, unknown> | undefined {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return { ...(value as Record<string, unknown>) }
+  }
+  return undefined
+}
+
+function toApiProfile(row: ContainerTagRow, documentCount: number): ApiProfile {
+  return {
+    containerTag: row.tag,
+    name: row.displayName ?? undefined,
+    description: row.description ?? undefined,
+    settings: normalizeSettings(row.settings) ?? undefined,
+    documentCount,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  }
+}
+
+async function ensureContainerTag(tag: string): Promise<ContainerTagRow | null> {
+  await db.insert(containerTags).values({ tag }).onConflictDoNothing({ target: containerTags.tag })
+  const [row] = await db.select().from(containerTags).where(eq(containerTags.tag, tag)).limit(1)
+  return row ?? null
+}
+
+async function getDocumentCount(containerTag: string): Promise<number> {
+  const [countRow] = await db
+    .select({ count: sql<number>`count(*)` })
+    .from(documents)
+    .where(eq(documents.containerTag, containerTag))
+  return Number(countRow?.count ?? 0)
+}
+
+/**
+ * GET /:containerTag - Get profile by container tag
+ * If the profile doesn't exist, creates one based on documents with that tag
+ */
+profilesRouter.get('/:containerTag', requireScopes('read'), async (c) => {
+  const startTime = Date.now()
+  const containerTag = c.req.param('containerTag')
+
+  const [existingRow] = await db.select().from(containerTags).where(eq(containerTags.tag, containerTag)).limit(1)
+
+  const documentCount = await getDocumentCount(containerTag)
+
+  let row = existingRow ?? null
+  if (!row) {
+    if (documentCount === 0) {
+      return notFound('Profile', containerTag)
+    }
+    row = await ensureContainerTag(containerTag)
+  }
+
+  if (!row) {
+    return notFound('Profile', containerTag)
+  }
+
+  const response: SuccessResponse<ApiProfile> = {
+    data: toApiProfile(row, documentCount),
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+/**
+ * PUT /:containerTag - Update or create a profile
+ */
+profilesRouter.put('/:containerTag', requireScopes('write'), async (c) => {
+  const startTime = Date.now()
+  const containerTag = c.req.param('containerTag')
+
+  const body = await c.req.json()
+  const validatedData = UpdateProfileSchema.parse(body)
+
+  const [existingRow] = await db.select().from(containerTags).where(eq(containerTags.tag, containerTag)).limit(1)
+
+  let row: ContainerTagRow | null = existingRow ?? null
+  const now = new Date()
+
+  if (!row) {
+    const [created] = await db
+      .insert(containerTags)
+      .values({
+        tag: containerTag,
+        displayName: validatedData.name,
+        description: validatedData.description,
+        settings: validatedData.settings ?? {},
+        createdAt: now,
+        updatedAt: now,
+      })
+      .returning()
+    row = created ?? null
+  } else {
+    const updatePayload: Partial<typeof containerTags.$inferInsert> = {
+      updatedAt: now,
+    }
+
+    if (validatedData.name !== undefined) {
+      updatePayload.displayName = validatedData.name
+    }
+
+    if (validatedData.description !== undefined) {
+      updatePayload.description = validatedData.description
+    }
+
+    if (validatedData.settings !== undefined) {
+      updatePayload.settings = validatedData.settings
+    }
+
+    const [updated] = await db
+      .update(containerTags)
+      .set(updatePayload)
+      .where(eq(containerTags.tag, containerTag))
+      .returning()
+    row = updated ?? row
+  }
+
+  if (!row) {
+    return notFound('Profile', containerTag)
+  }
+
+  const documentCount = await getDocumentCount(containerTag)
+
+  const response: SuccessResponse<ApiProfile> = {
+    data: toApiProfile(row, documentCount),
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+/**
+ * GET / - List all profiles
+ * Optional query params: limit, offset
+ */
+profilesRouter.get('/', requireScopes('read'), async (c) => {
+  const startTime = Date.now()
+
+  const limitParam = parseInt(c.req.query('limit') || '20', 10)
+  const offsetParam = parseInt(c.req.query('offset') || '0', 10)
+
+  const limit = Math.min(Number.isNaN(limitParam) ? 20 : Math.max(1, limitParam), 100)
+  const offset = Number.isNaN(offsetParam) ? 0 : Math.max(0, offsetParam)
+
+  const documentCounts = await db
+    .select({
+      tag: documents.containerTag,
+      count: sql<number>`count(*)`,
+    })
+    .from(documents)
+    .groupBy(documents.containerTag)
+
+  const documentCountMap = new Map<string, number>(documentCounts.map((row) => [row.tag, Number(row.count ?? 0)]))
+
+  const tagRows = await db.select().from(containerTags).orderBy(desc(containerTags.updatedAt))
+  const existingTags = new Set(tagRows.map((row) => row.tag))
+  const documentTags = documentCounts.map((row) => row.tag).filter(Boolean)
+  const missingTags = documentTags.filter((tag) => !existingTags.has(tag))
+
+  let allRows = tagRows
+  if (missingTags.length > 0) {
+    await db
+      .insert(containerTags)
+      .values(missingTags.map((tag) => ({ tag })))
+      .onConflictDoNothing({ target: containerTags.tag })
+
+    const insertedRows = await db.select().from(containerTags).where(inArray(containerTags.tag, missingTags))
+    allRows = [...tagRows, ...insertedRows]
+  }
+
+  const allProfiles = allRows.map((row) => toApiProfile(row, documentCountMap.get(row.tag) ?? 0))
+
+  allProfiles.sort((a, b) => b.documentCount - a.documentCount)
+
+  const total = allProfiles.length
+  const paginatedProfiles = allProfiles.slice(offset, offset + limit)
+
+  const response: SuccessResponse<{
+    profiles: ApiProfile[]
+    total: number
+    limit: number
+    offset: number
+  }> = {
+    data: {
+      profiles: paginatedProfiles,
+      total,
+      limit,
+      offset,
+    },
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+/**
+ * DELETE /:containerTag - Delete a profile
+ * Note: This only deletes the profile metadata, not the documents
+ */
+profilesRouter.delete('/:containerTag', requireScopes('write'), async (c) => {
+  const startTime = Date.now()
+  const containerTag = c.req.param('containerTag')
+
+  const deleted = await db
+    .delete(containerTags)
+    .where(eq(containerTags.tag, containerTag))
+    .returning({ tag: containerTags.tag })
+
+  if (deleted.length === 0) {
+    return notFound('Profile', containerTag)
+  }
+
+  const response: SuccessResponse<{ deleted: true; containerTag: string }> = {
+    data: { deleted: true, containerTag },
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(response)
+})
+
+export { profilesRouter }

package/src/api/routes/search.ts

@@ -0,0 +1,71 @@
+import { Hono } from 'hono'
+import { SearchRequestSchema, SearchResponse, SearchResult, SuccessResponse } from '../../types/api.types.js'
+import { requireScopes } from '../middleware/auth.js'
+import { searchRateLimit } from '../middleware/rateLimit.js'
+import { getSearchService } from '../../services/search.service.js'
+import type { MetadataFilter } from '../../services/search.types.js'
+
+const searchRouter = new Hono()
+const searchService = getSearchService()
+
+/**
+ * POST / - Unified search endpoint
+ * Supports vector, fulltext, and hybrid search modes
+ */
+searchRouter.post('/', requireScopes('read'), searchRateLimit, async (c) => {
+  const startTime = Date.now()
+
+  const body = await c.req.json()
+  const validatedData = SearchRequestSchema.parse(body)
+
+  const { q, containerTag, searchMode, limit, threshold, rerank, filters } = validatedData
+
+  const metadataFilters: MetadataFilter[] | undefined = filters?.metadata
+    ? Object.entries(filters.metadata)
+        .filter(([, value]) => typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        .map(([key, value]) => ({
+          key,
+          value: value as string | number | boolean,
+          operator: 'eq',
+        }))
+    : undefined
+
+  const dateRange =
+    filters?.createdAfter || filters?.createdBefore
+      ? {
+          from: filters.createdAfter ? new Date(filters.createdAfter) : undefined,
+          to: filters.createdBefore ? new Date(filters.createdBefore) : undefined,
+        }
+      : undefined
+
+  const response = await searchService.hybridSearch(q, containerTag, {
+    searchMode,
+    limit,
+    threshold,
+    rerank,
+    filters: metadataFilters,
+    dateRange,
+  })
+
+  const results: SearchResult[] = response.results.map((result) => ({
+    id: result.id,
+    content: result.memory?.content ?? result.chunk?.content ?? '',
+    score: result.rerankScore ?? result.similarity,
+    containerTag: result.memory?.containerTag,
+    metadata: result.metadata,
+  }))
+
+  const payload: SuccessResponse<SearchResponse> = {
+    data: {
+      results,
+      total: response.totalCount,
+      query: response.query,
+      searchMode,
+    },
+    timing: Date.now() - startTime,
+  }
+
+  return c.json(payload)
+})
+
+export { searchRouter }

package/src/api/stores/index.ts

@@ -0,0 +1,58 @@
+/**
+ * Shared in-memory stores for the API layer.
+ * In production, these would be replaced with a database connection.
+ */
+
+import { ApiDocument, ApiProfile } from '../../types/api.types.js'
+
+// Shared document store - single source of truth for all routes
+export const documentsStore = new Map<string, ApiDocument>()
+
+// Shared profile store - single source of truth for all routes
+export const profilesStore = new Map<string, ApiProfile>()
+
+/**
+ * Clear all stores - useful for testing
+ */
+export function clearAllStores(): void {
+  documentsStore.clear()
+  profilesStore.clear()
+}
+
+/**
+ * Get document count for a container tag
+ */
+export function getDocumentCountByTag(containerTag: string): number {
+  let count = 0
+  for (const doc of documentsStore.values()) {
+    if (doc.containerTag === containerTag) {
+      count++
+    }
+  }
+  return count
+}
+
+/**
+ * Get all documents as array
+ */
+export function getAllDocuments(): ApiDocument[] {
+  return Array.from(documentsStore.values())
+}
+
+/**
+ * Find document by ID or customId
+ */
+export function findDocument(idOrCustomId: string): ApiDocument | undefined {
+  // First try by ID
+  const doc = documentsStore.get(idOrCustomId)
+  if (doc) return doc
+
+  // Then try by customId
+  for (const d of documentsStore.values()) {
+    if (d.customId === idOrCustomId) {
+      return d
+    }
+  }
+
+  return undefined
+}

package/src/config/bootstrap-env.ts

@@ -0,0 +1,3 @@
+import { loadEnvFile } from './env.js'
+
+loadEnvFile()