@hiai-gg/hiai-docs 0.0.1

package/backend/src/api/routes/tags.ts

@@ -0,0 +1,247 @@
+import { documents, documentTags, tags } from "@hiai-docs/db/schema";
+import { and, count, eq } from "drizzle-orm";
+import { Elysia } from "elysia";
+import { z } from "zod";
+import { getSessionUserId } from "../../lib/auth-helpers";
+import { db } from "../../lib/db";
+import { logger } from "../../lib/logger";
+import { writeRateLimiter } from "../middleware/rate-limit";
+
+const createTagSchema = z.object({
+	name: z.string().min(1).max(100),
+	color: z.string().max(20).optional(),
+});
+
+const updateTagSchema = z.object({
+	name: z.string().min(1).max(100).optional(),
+	color: z.string().max(20).optional(),
+});
+
+const addTagToDocSchema = z.object({
+	tagId: z.string().uuid(),
+});
+
+export const tagRoutes = new Elysia({ prefix: "/api" })
+	.get("/tags", async ({ set, request }) => {
+		const userId = await getSessionUserId(request.headers);
+		if (!userId) {
+			set.status = 401;
+			return { error: "Unauthorized" };
+		}
+		try {
+			const rows = await db
+				.select({
+					id: tags.id,
+					name: tags.name,
+					color: tags.color,
+					createdAt: tags.createdAt,
+					documentCount: count(documentTags.documentId),
+				})
+				.from(tags)
+				.leftJoin(documentTags, eq(tags.id, documentTags.tagId))
+				.where(eq(tags.ownerId, userId))
+				.groupBy(tags.id, tags.name, tags.color, tags.createdAt)
+				.orderBy(tags.name);
+			return rows;
+		} catch (err) {
+			logger.error({ err }, "Failed to list tags");
+			set.status = 500;
+			return { error: "Failed to list tags" };
+		}
+	})
+	.post("/tags", async ({ request, set }) => {
+		const ip =
+			request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+			request.headers.get("x-real-ip") ??
+			"unknown";
+		const rl = await writeRateLimiter(ip);
+		if (!rl.allowed) {
+			set.status = 429;
+			return { error: "Rate limited" };
+		}
+		const userId = await getSessionUserId(request.headers);
+		if (!userId) {
+			set.status = 401;
+			return { error: "Unauthorized" };
+		}
+		const body = createTagSchema.safeParse(await request.json());
+		if (!body.success) {
+			set.status = 400;
+			return { error: "Invalid input", details: body.error.flatten() };
+		}
+		try {
+			const existing = await db
+				.select({ id: tags.id })
+				.from(tags)
+				.where(and(eq(tags.ownerId, userId), eq(tags.name, body.data.name)))
+				.limit(1);
+			if (existing.length > 0) {
+				set.status = 409;
+				return { error: "Tag with this name already exists" };
+			}
+			const [created] = await db
+				.insert(tags)
+				.values({
+					ownerId: userId,
+					name: body.data.name,
+					color: body.data.color ?? null,
+				})
+				.returning();
+			set.status = 201;
+			return created;
+		} catch (err) {
+			logger.error({ err }, "Failed to create tag");
+			set.status = 500;
+			return { error: "Failed to create tag" };
+		}
+	})
+	.patch("/tags/:id", async ({ params, request, set }) => {
+		const ip =
+			request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+			request.headers.get("x-real-ip") ??
+			"unknown";
+		const rl = await writeRateLimiter(ip);
+		if (!rl.allowed) {
+			set.status = 429;
+			return { error: "Rate limited" };
+		}
+		const userId = await getSessionUserId(request.headers);
+		if (!userId) {
+			set.status = 401;
+			return { error: "Unauthorized" };
+		}
+		const body = updateTagSchema.safeParse(await request.json());
+		if (!body.success) {
+			set.status = 400;
+			return { error: "Invalid input", details: body.error.flatten() };
+		}
+		try {
+			const [updated] = await db
+				.update(tags)
+				.set({
+					...(body.data.name !== undefined && { name: body.data.name }),
+					...(body.data.color !== undefined && { color: body.data.color }),
+				})
+				.where(and(eq(tags.id, params.id), eq(tags.ownerId, userId)))
+				.returning();
+			if (!updated) {
+				set.status = 404;
+				return { error: "Tag not found" };
+			}
+			return updated;
+		} catch (err) {
+			logger.error({ err }, "Failed to update tag");
+			set.status = 500;
+			return { error: "Failed to update tag" };
+		}
+	})
+	.delete("/tags/:id", async ({ params, set, request }) => {
+		const ip =
+			request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+			request.headers.get("x-real-ip") ??
+			"unknown";
+		const rl = await writeRateLimiter(ip);
+		if (!rl.allowed) {
+			set.status = 429;
+			return { error: "Rate limited" };
+		}
+		const userId = await getSessionUserId(request.headers);
+		if (!userId) {
+			set.status = 401;
+			return { error: "Unauthorized" };
+		}
+		try {
+			await db
+				.delete(tags)
+				.where(and(eq(tags.id, params.id), eq(tags.ownerId, userId)));
+			return { success: true };
+		} catch (err) {
+			logger.error({ err }, "Failed to delete tag");
+			set.status = 500;
+			return { error: "Failed to delete tag" };
+		}
+	})
+	.post("/documents/:id/tags", async ({ params, request, set }) => {
+		const ip =
+			request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+			request.headers.get("x-real-ip") ??
+			"unknown";
+		const rl = await writeRateLimiter(ip);
+		if (!rl.allowed) {
+			set.status = 429;
+			return { error: "Rate limited" };
+		}
+		const userId = await getSessionUserId(request.headers);
+		if (!userId) {
+			set.status = 401;
+			return { error: "Unauthorized" };
+		}
+		const body = addTagToDocSchema.safeParse(await request.json());
+		if (!body.success) {
+			set.status = 400;
+			return { error: "Invalid input" };
+		}
+		try {
+			const [doc] = await db
+				.select({ id: documents.id })
+				.from(documents)
+				.where(and(eq(documents.id, params.id), eq(documents.ownerId, userId)))
+				.limit(1);
+			if (!doc) {
+				set.status = 404;
+				return { error: "Document not found" };
+			}
+
+			await db.insert(documentTags).values({
+				documentId: params.id,
+				tagId: body.data.tagId,
+			});
+			set.status = 201;
+			return { success: true };
+		} catch (err) {
+			logger.error({ err }, "Failed to add tag to document");
+			set.status = 500;
+			return { error: "Failed to add tag to document" };
+		}
+	})
+	.delete("/documents/:id/tags/:tagId", async ({ params, set, request }) => {
+		const ip =
+			request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
+			request.headers.get("x-real-ip") ??
+			"unknown";
+		const rl = await writeRateLimiter(ip);
+		if (!rl.allowed) {
+			set.status = 429;
+			return { error: "Rate limited" };
+		}
+		const userId = await getSessionUserId(request.headers);
+		if (!userId) {
+			set.status = 401;
+			return { error: "Unauthorized" };
+		}
+		try {
+			const [doc] = await db
+				.select({ id: documents.id })
+				.from(documents)
+				.where(and(eq(documents.id, params.id), eq(documents.ownerId, userId)))
+				.limit(1);
+			if (!doc) {
+				set.status = 404;
+				return { error: "Document not found" };
+			}
+
+			await db
+				.delete(documentTags)
+				.where(
+					and(
+						eq(documentTags.documentId, params.id),
+						eq(documentTags.tagId, params.tagId),
+					),
+				);
+			return { success: true };
+		} catch (err) {
+			logger.error({ err }, "Failed to remove tag from document");
+			set.status = 500;
+			return { error: "Failed to remove tag" };
+		}
+	});

package/backend/src/api/routes/versions.ts

@@ -0,0 +1,99 @@
+import { documents, versions } from "@hiai-docs/db/schema";
+import { and, desc, eq } from "drizzle-orm";
+import { Elysia } from "elysia";
+import { getSessionUserId } from "../../lib/auth-helpers";
+import { db } from "../../lib/db";
+import { logger } from "../../lib/logger";
+
+export const versionRoutes = new Elysia({
+	prefix: "/api/documents/:id/versions",
+})
+	// GET /api/documents/:id/versions — list versions
+	.get("/", async ({ params, set, request }) => {
+		const userId = await getSessionUserId(request.headers);
+		if (!userId) {
+			set.status = 401;
+			return { error: "Unauthorized" };
+		}
+		try {
+			const doc = await db
+				.select({ id: documents.id })
+				.from(documents)
+				.where(and(eq(documents.id, params.id), eq(documents.ownerId, userId)))
+				.limit(1);
+
+			if (doc.length === 0) {
+				set.status = 404;
+				return { error: "Document not found" };
+			}
+
+			const rows = await db
+				.select({
+					id: versions.id,
+					documentId: versions.documentId,
+					content: versions.content,
+					contentJson: versions.contentJson,
+					createdBy: versions.createdBy,
+					createdAt: versions.createdAt,
+				})
+				.from(versions)
+				.where(eq(versions.documentId, params.id))
+				.orderBy(desc(versions.createdAt));
+
+			return rows;
+		} catch (err) {
+			logger.error({ err, docId: params.id }, "Failed to list versions");
+			set.status = 500;
+			return { error: "Failed to list versions" };
+		}
+	})
+
+	// GET /api/documents/:id/versions/:vid — get specific version
+	.get("/:vid", async ({ params, set, request }) => {
+		const userId = await getSessionUserId(request.headers);
+		if (!userId) {
+			set.status = 401;
+			return { error: "Unauthorized" };
+		}
+		try {
+			const doc = await db
+				.select({ id: documents.id })
+				.from(documents)
+				.where(and(eq(documents.id, params.id), eq(documents.ownerId, userId)))
+				.limit(1);
+
+			if (doc.length === 0) {
+				set.status = 404;
+				return { error: "Document not found" };
+			}
+
+			const rows = await db
+				.select({
+					id: versions.id,
+					documentId: versions.documentId,
+					content: versions.content,
+					contentJson: versions.contentJson,
+					createdBy: versions.createdBy,
+					createdAt: versions.createdAt,
+				})
+				.from(versions)
+				.where(
+					and(eq(versions.id, params.vid), eq(versions.documentId, params.id)),
+				)
+				.limit(1);
+
+			if (rows.length === 0) {
+				set.status = 404;
+				return { error: "Version not found" };
+			}
+
+			return rows[0];
+		} catch (err) {
+			logger.error(
+				{ err, docId: params.id, vid: params.vid },
+				"Failed to get version",
+			);
+			set.status = 500;
+			return { error: "Failed to get version" };
+		}
+	});

package/backend/src/api/routes/webhooks.ts

@@ -0,0 +1,43 @@
+import { attachments } from "@hiai-docs/db/schema";
+import { eq } from "drizzle-orm";
+import { Elysia } from "elysia";
+import { db } from "../../lib/db";
+import { logger } from "../../lib/logger";
+import { verifyWebhookSignature } from "../middleware/webhook-verify";
+
+export const webhookRoutes = new Elysia({ prefix: "/api/webhooks" }).post(
+	"/minio",
+	async ({ request, body }) => {
+		const rawBody = await request.text();
+		const sig = request.headers.get("x-minio-signature");
+
+		if (!verifyWebhookSignature(rawBody, sig)) {
+			logger.warn("Invalid MinIO webhook signature");
+			return { error: "Invalid signature" };
+		}
+
+		const event = body as Record<string, unknown>;
+		const records = (event.Records ?? []) as Array<Record<string, unknown>>;
+
+		for (const record of records) {
+			const eventName = record.eventName as string;
+			const s3 = record.s3 as Record<string, unknown> | undefined;
+			const key = (s3?.object as Record<string, unknown>)?.key as string;
+
+			if (!key) continue;
+
+			logger.info({ eventName, key }, "MinIO webhook event");
+
+			if (eventName === "s3:ObjectRemoved:Delete") {
+				await db
+					.delete(attachments)
+					.where(eq(attachments.minioKey, key))
+					.catch((err: unknown) =>
+						logger.error({ err, key }, "Failed to mark attachment deleted"),
+					);
+			}
+		}
+
+		return { received: true };
+	},
+);

package/backend/src/embedding/chunker.ts

@@ -0,0 +1,74 @@
+/**
+ * Text chunking for embedding pipeline.
+ * Strategy: split by paragraphs, then merge into ~500 token chunks with 50 token overlap.
+ * Token estimation: 1 token ≈ 4 chars (rough heuristic).
+ */
+
+const CHARS_PER_TOKEN = 4;
+const TARGET_TOKENS = 500;
+const OVERLAP_TOKENS = 50;
+
+const TARGET_CHARS = TARGET_TOKENS * CHARS_PER_TOKEN; // 2000
+const OVERLAP_CHARS = OVERLAP_TOKENS * CHARS_PER_TOKEN; // 200
+
+/**
+ * Split text into chunks suitable for embedding.
+ * Each chunk is approximately 500 tokens (~2000 characters).
+ * Adjacent chunks overlap by ~50 tokens (~200 characters).
+ */
+export function chunkText(text: string): string[] {
+	if (!text || text.trim().length === 0) {
+		return [];
+	}
+
+	// Split into paragraphs (preserve double-newline boundaries)
+	const paragraphs = text.split(/\n\s*\n/).filter((p) => p.trim().length > 0);
+
+	if (paragraphs.length === 0) {
+		return [];
+	}
+
+	// If a single paragraph exceeds target, split it further by sentences
+	const normalizedParagraphs: string[] = [];
+	for (const para of paragraphs) {
+		if (para.length > TARGET_CHARS * 1.5) {
+			// Split oversized paragraph by sentences
+			const sentences = para.match(/[^.!?]+[.!?]+[\s]*/g) || [para];
+			normalizedParagraphs.push(...sentences);
+		} else {
+			normalizedParagraphs.push(para);
+		}
+	}
+
+	const chunks: string[] = [];
+	let currentChunk = "";
+
+	for (const paragraph of normalizedParagraphs) {
+		const candidate = currentChunk
+			? `${currentChunk}\n\n${paragraph}`
+			: paragraph;
+
+		if (candidate.length <= TARGET_CHARS) {
+			currentChunk = candidate;
+		} else {
+			// Flush current chunk if non-empty
+			if (currentChunk.length > 0) {
+				chunks.push(currentChunk.trim());
+			}
+			// Start new chunk with overlap from end of previous chunk
+			if (OVERLAP_CHARS > 0 && currentChunk.length > 0) {
+				const overlap = currentChunk.slice(-OVERLAP_CHARS);
+				currentChunk = `${overlap}\n\n${paragraph}`;
+			} else {
+				currentChunk = paragraph;
+			}
+		}
+	}
+
+	// Flush remaining chunk
+	if (currentChunk.trim().length > 0) {
+		chunks.push(currentChunk.trim());
+	}
+
+	return chunks;
+}

package/backend/src/embedding/index.ts

@@ -0,0 +1,117 @@
+/**
+ * Embedding pipeline entry point.
+ * Provider factory with fallback logic, document chunking, and graceful degradation.
+ */
+
+import { config } from "../lib/config";
+import { logger } from "../lib/logger";
+import { chunkText } from "./chunker";
+import { getOllamaEmbedding } from "./providers/ollama";
+import { getOpenRouterEmbedding } from "./providers/openrouter";
+
+const EMBEDDING_DIMENSIONS = 1024;
+
+/**
+ * Get an embedding vector using the primary provider.
+ */
+async function getPrimaryEmbedding(text: string): Promise<number[]> {
+	switch (config.EMBEDDING_PROVIDER) {
+		case "ollama":
+			return getOllamaEmbedding(
+				text,
+				config.EMBEDDING_MODEL,
+				config.EMBEDDING_OLLAMA_URL,
+			);
+		case "openrouter":
+			return getOpenRouterEmbedding(
+				text,
+				config.EMBEDDING_MODEL,
+				config.OPENROUTER_API_KEY ?? "",
+			);
+		case "voyage":
+			// Voyage not yet implemented — fall through to fallback
+			throw new Error("Voyage embedding provider is not yet implemented");
+		default:
+			throw new Error(
+				`Unknown embedding provider: ${config.EMBEDDING_PROVIDER}`,
+			);
+	}
+}
+
+/**
+ * Get an embedding vector using the fallback provider.
+ */
+async function getFallbackEmbedding(text: string): Promise<number[]> {
+	switch (config.EMBEDDING_FALLBACK_PROVIDER) {
+		case "ollama":
+			return getOllamaEmbedding(
+				text,
+				config.EMBEDDING_FALLBACK_MODEL,
+				config.EMBEDDING_OLLAMA_URL,
+			);
+		case "openrouter":
+			return getOpenRouterEmbedding(
+				text,
+				config.EMBEDDING_FALLBACK_MODEL,
+				config.OPENROUTER_API_KEY ?? "",
+			);
+		case "voyage":
+			throw new Error("Voyage embedding provider is not yet implemented");
+		default:
+			throw new Error(
+				`Unknown fallback embedding provider: ${config.EMBEDDING_FALLBACK_PROVIDER}`,
+			);
+	}
+}
+
+/**
+ * Get an embedding vector for a single text.
+ * Tries primary provider, then fallback, then returns a zero vector.
+ */
+export async function getEmbedding(text: string): Promise<number[]> {
+	try {
+		const embedding = await getPrimaryEmbedding(text);
+		return embedding;
+	} catch (primaryErr) {
+		logger.warn(
+			{ err: primaryErr, provider: config.EMBEDDING_PROVIDER },
+			"Primary embedding provider failed, trying fallback",
+		);
+
+		try {
+			const embedding = await getFallbackEmbedding(text);
+			return embedding;
+		} catch (fallbackErr) {
+			logger.error(
+				{ err: fallbackErr, provider: config.EMBEDDING_FALLBACK_PROVIDER },
+				"Fallback embedding provider also failed, returning zero vector",
+			);
+			return new Array(EMBEDDING_DIMENSIONS).fill(0);
+		}
+	}
+}
+
+/**
+ * Chunk a document and embed each chunk.
+ * Returns one embedding vector per chunk.
+ */
+export async function embedDocument(
+	title: string,
+	content: string,
+): Promise<number[][]> {
+	const fullText = `${title}\n\n${content}`;
+	const chunks = chunkText(fullText);
+
+	if (chunks.length === 0) {
+		return [new Array(EMBEDDING_DIMENSIONS).fill(0)];
+	}
+
+	const results: number[][] = [];
+	for (let i = 0; i < chunks.length; i += 5) {
+		const batch = chunks.slice(i, i + 5);
+		const batchResults = await Promise.all(batch.map(getEmbedding));
+		results.push(...batchResults);
+	}
+
+	return results;
+}

package/backend/src/embedding/providers/ollama.ts

@@ -0,0 +1,63 @@
+/**
+ * Ollama embedding provider.
+ * POST to ${OLLAMA_URL}/api/embeddings with configurable model.
+ */
+
+import { logger } from "../../lib/logger";
+import { normalizeDimensions } from "../utils";
+
+const EMBEDDING_DIMENSIONS = 1024;
+const TIMEOUT_MS = 30_000;
+
+interface OllamaEmbeddingResponse {
+	embedding: number[];
+}
+
+/**
+ * Get an embedding vector from Ollama.
+ * @param text - Text to embed
+ * @param model - Model name (default: nomic-embed-text)
+ * @param ollamaUrl - Ollama API base URL
+ * @returns number[] of length 1024
+ */
+export async function getOllamaEmbedding(
+	text: string,
+	model: string,
+	ollamaUrl: string,
+): Promise<number[]> {
+	const url = `${ollamaUrl}/api/embeddings`;
+
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ model, prompt: text }),
+			signal: controller.signal,
+		});
+
+		if (!response.ok) {
+			const body = await response.text().catch(() => "unknown");
+			throw new Error(`Ollama embedding failed: ${response.status} ${body}`);
+		}
+
+		const data = (await response.json()) as OllamaEmbeddingResponse;
+		const embedding = data.embedding;
+
+		if (!Array.isArray(embedding) || embedding.length === 0) {
+			throw new Error("Ollama returned empty or invalid embedding");
+		}
+
+		return normalizeDimensions(embedding, EMBEDDING_DIMENSIONS);
+	} catch (err) {
+		if (err instanceof Error && err.name === "AbortError") {
+			logger.error({ url, model }, "Ollama embedding request timed out");
+			throw new Error(`Ollama embedding timed out after ${TIMEOUT_MS}ms`);
+		}
+		throw err;
+	} finally {
+		clearTimeout(timeout);
+	}
+}