ocean-brain 0.8.2 → 0.11.0

package/server/dist/features/note/services/trash.js

@@ -4,6 +4,8 @@ import {
   RECOVERY_CLEANUP_BATCH_LIMIT,
   TRASH_RETENTION_DAYS
 } from "../../../modules/recovery-retention.js";
+import { replaceNoteReferences } from "./note-reference-index.js";
+import { resolveRestoredPropertyTarget } from "./property-restore.js";
 import { buildNoteSearchProjection, extractVisibleSearchTextFromContent } from "./search.js";
 const TRASHED_NOTE_CONTENT_PREVIEW_MAX_LENGTH = 240;
 class NoteRestoreConflictError extends Error {
@@ -288,42 +290,27 @@ const noteTrashService = createNoteTrashService({
           } : {}
         }
       });
+      await replaceNoteReferences(tx, note.id, restoredContent);
       for (const property of deletedNote.properties ?? []) {
-        const definition = await tx.propertyDefinition.upsert({
-          where: { key: property.key },
-          create: {
-            key: property.key,
-            name: property.name,
-            valueType: property.valueType
-          },
-          update: {
-            name: property.name,
-            valueType: property.valueType
-          }
-        });
-        const option = property.valueType === "select" && property.optionValue ? await tx.propertyOption.upsert({
-          where: {
-            propertyDefinitionId_value: {
-              propertyDefinitionId: definition.id,
-              value: property.optionValue
+        const target = await resolveRestoredPropertyTarget(property, {
+          findDefinitionByKey: (key) => tx.propertyDefinition.findUnique({ where: { key } }),
+          findOptionByValue: (propertyDefinitionId, value) => tx.propertyOption.findUnique({
+            where: {
+              propertyDefinitionId_value: {
+                propertyDefinitionId,
+                value
+              }
             }
-          },
-          create: {
-            propertyDefinitionId: definition.id,
-            value: property.optionValue,
-            label: property.optionLabel ?? property.optionValue,
-            color: property.optionColor
-          },
-          update: {
-            label: property.optionLabel ?? property.optionValue,
-            color: property.optionColor
-          }
-        }) : null;
+          })
+        });
+        if (!target) {
+          continue;
+        }
         await tx.noteProperty.create({
           data: {
             noteId: note.id,
-            propertyDefinitionId: definition.id,
-            optionId: option?.id ?? null,
+            propertyDefinitionId: target.propertyDefinitionId,
+            optionId: target.optionId,
             textValue: property.textValue,
             textValueNormalized: property.textValueNormalized,
             numberValue: property.numberValue,

package/server/dist/features/note/services/write.js

@@ -1,4 +1,5 @@
 import models, { Prisma } from "../../../models.js";
+import { replaceNoteReferences } from "./note-reference-index.js";
 import { buildNoteSearchProjection } from "./search.js";
 import { captureNoteBaseline } from "./snapshot.js";
 import { createNoteVersionConflictError, MissingNoteVersionError, parseNoteVersion } from "./write-conflict.js";
@@ -101,9 +102,15 @@ const defaultNoteWriteService = createNoteWriteService({
     }
   }),
   captureBaseline: captureNoteBaseline,
-  updateNote: ({ where, data }) => models.note.update({
-    where,
-    data
+  updateNote: ({ where, data }) => models.$transaction(async (tx) => {
+    const note = await tx.note.update({
+      where,
+      data
+    });
+    if (data.content !== void 0) {
+      await replaceNoteReferences(tx, note.id, data.content);
+    }
+    return note;
   }),
   isRecordNotFoundError
 });

package/server/dist/features/search/embedding-api-key-store.js

@@ -0,0 +1,57 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+const MAX_EMBEDDING_API_KEY_LENGTH = 8192;
+const normalizeEmbeddingApiKey = (value) => {
+  const apiKey = value.trim();
+  if (apiKey.length > MAX_EMBEDDING_API_KEY_LENGTH) {
+    throw new Error("Embedding API key is too long.");
+  }
+  return apiKey || void 0;
+};
+const createEmbeddingApiKeyFingerprint = (apiKey) => {
+  if (!apiKey) {
+    return "";
+  }
+  return createHash("sha256").update(apiKey).digest("hex");
+};
+class FileEmbeddingApiKeyStore {
+  constructor(filePath) {
+    this.filePath = filePath;
+    try {
+      this.apiKey = normalizeEmbeddingApiKey(readFileSync(filePath, "utf8"));
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+  filePath;
+  apiKey;
+  get() {
+    return this.apiKey;
+  }
+  set(value) {
+    const apiKey = value === void 0 ? void 0 : normalizeEmbeddingApiKey(value);
+    if (!apiKey) {
+      rmSync(this.filePath, { force: true });
+      this.apiKey = void 0;
+      return;
+    }
+    mkdirSync(path.dirname(this.filePath), { recursive: true });
+    const temporaryPath = `${this.filePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(temporaryPath, apiKey, { encoding: "utf8", mode: 384, flag: "wx" });
+      renameSync(temporaryPath, this.filePath);
+      this.apiKey = apiKey;
+    } finally {
+      rmSync(temporaryPath, { force: true });
+    }
+  }
+}
+export {
+  FileEmbeddingApiKeyStore,
+  MAX_EMBEDDING_API_KEY_LENGTH,
+  createEmbeddingApiKeyFingerprint,
+  normalizeEmbeddingApiKey
+};

package/server/dist/features/search/embedding-client.js

@@ -0,0 +1,179 @@
+import { stripTrailingSlashes } from "./url-normalization.js";
+const DEFAULT_EMBEDDING_TIMEOUT_MS = 6e4;
+const DEFAULT_MODEL_DISCOVERY_TIMEOUT_MS = 1e4;
+const buildOpenAiCompatibleUrl = (baseUrl, resource) => {
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(baseUrl);
+  } catch {
+    throw new Error("Embedding API URL must be a valid http or https URL.");
+  }
+  if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+    throw new Error("Embedding API URL must use http or https.");
+  }
+  if (parsedUrl.username || parsedUrl.password) {
+    throw new Error("Embedding API URL must not contain credentials.");
+  }
+  const normalizedPath = stripTrailingSlashes(parsedUrl.pathname);
+  const normalizedPathLower = normalizedPath.toLowerCase();
+  const resourceSuffix = ["/embeddings", "/models"].find((suffix) => normalizedPathLower.endsWith(suffix));
+  const basePath = resourceSuffix ? normalizedPath.slice(0, -resourceSuffix.length) : normalizedPath;
+  parsedUrl.pathname = `${basePath || "/v1"}/${resource}`;
+  parsedUrl.search = "";
+  parsedUrl.hash = "";
+  return parsedUrl.toString();
+};
+const buildEmbeddingsUrl = (baseUrl) => buildOpenAiCompatibleUrl(baseUrl, "embeddings");
+const buildModelsUrl = (baseUrl) => buildOpenAiCompatibleUrl(baseUrl, "models");
+const validateEmbedding = (value, expectedIndex) => {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`Embedding API returned an empty vector for input ${expectedIndex}.`);
+  }
+  const embedding = value.map((item) => {
+    if (typeof item !== "number" || !Number.isFinite(item)) {
+      throw new Error(`Embedding API returned an invalid vector value for input ${expectedIndex}.`);
+    }
+    return item;
+  });
+  return embedding;
+};
+const parseEmbeddingResponse = (payload, expectedCount) => {
+  if (!payload || typeof payload !== "object" || !("data" in payload) || !Array.isArray(payload.data)) {
+    throw new Error("Embedding API response does not contain a data array.");
+  }
+  const items = payload.data;
+  if (items.length !== expectedCount) {
+    throw new Error(`Embedding API returned ${items.length} vectors for ${expectedCount} inputs.`);
+  }
+  const orderedItems = [...items].sort((left, right) => {
+    const leftIndex = typeof left.index === "number" ? left.index : items.indexOf(left);
+    const rightIndex = typeof right.index === "number" ? right.index : items.indexOf(right);
+    return leftIndex - rightIndex;
+  });
+  const embeddings = orderedItems.map((item, index) => validateEmbedding(item.embedding, index));
+  const dimensions = embeddings[0]?.length;
+  if (!dimensions || embeddings.some((embedding) => embedding.length !== dimensions)) {
+    throw new Error("Embedding API returned vectors with inconsistent dimensions.");
+  }
+  return embeddings;
+};
+const redactSecret = (message, secret) => {
+  if (!secret || !message.includes(secret)) {
+    return message;
+  }
+  return message.split(secret).join("[redacted]");
+};
+const readApiErrorMessage = async (response, secret) => {
+  try {
+    const payload = await response.json();
+    const message = payload.error?.message ?? payload.message;
+    return typeof message === "string" && message.trim() ? redactSecret(message.trim(), secret) : void 0;
+  } catch {
+    return void 0;
+  }
+};
+const looksLikeEmbeddingModel = (modelId) => /(^|[-_/])(embed|embedding|bge|e5|gte)([-_/.]|$)/i.test(modelId);
+const listOpenAiCompatibleEmbeddingModels = async (baseUrl, options = {}) => {
+  const endpoint = buildModelsUrl(baseUrl);
+  const fetchImpl = options.fetch ?? fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_MODEL_DISCOVERY_TIMEOUT_MS;
+  const response = await fetchImpl(endpoint, {
+    method: "GET",
+    headers: {
+      Accept: "application/json",
+      ...options.apiKey ? { Authorization: `Bearer ${options.apiKey}` } : {}
+    },
+    redirect: "error",
+    signal: AbortSignal.timeout(timeoutMs)
+  });
+  if (!response.ok) {
+    const apiMessage = await readApiErrorMessage(response, options.apiKey);
+    throw new Error(
+      apiMessage ? `Model discovery failed (${response.status}): ${apiMessage}` : `Model discovery failed with status ${response.status}.`
+    );
+  }
+  const payload = await response.json();
+  if (!Array.isArray(payload.data)) {
+    throw new Error("Model discovery response does not contain a data array.");
+  }
+  const modelIds = [
+    ...new Set(
+      payload.data.map((item) => {
+        if (!item || typeof item !== "object") return "";
+        const id = item.id;
+        return typeof id === "string" ? id.trim() : "";
+      }).filter(Boolean)
+    )
+  ];
+  if (modelIds.length === 0) {
+    throw new Error("The API returned no models.");
+  }
+  return modelIds.map((id) => ({ id, likelyEmbedding: looksLikeEmbeddingModel(id) })).sort((left, right) => {
+    if (left.likelyEmbedding !== right.likelyEmbedding) {
+      return left.likelyEmbedding ? -1 : 1;
+    }
+    return left.id.localeCompare(right.id);
+  });
+};
+const buildQueryInput = (query, instruction) => {
+  const normalizedInstruction = instruction?.trim();
+  if (!normalizedInstruction) {
+    return query;
+  }
+  return `Instruct: ${normalizedInstruction}
+Query: ${query}`;
+};
+const createOpenAiCompatibleEmbeddingClient = (config, options = {}) => {
+  const endpoint = buildEmbeddingsUrl(config.baseUrl);
+  const model = config.model.trim();
+  const fetchImpl = options.fetch ?? fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_EMBEDDING_TIMEOUT_MS;
+  if (!model) {
+    throw new Error("Embedding model is required.");
+  }
+  const embed = async (inputs) => {
+    if (inputs.length === 0) {
+      return [];
+    }
+    const response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+      },
+      body: JSON.stringify({
+        model,
+        input: inputs,
+        encoding_format: "float"
+      }),
+      redirect: "error",
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) {
+      const apiMessage = await readApiErrorMessage(response, config.apiKey);
+      throw new Error(
+        apiMessage ? `Embedding API request failed (${response.status}): ${apiMessage}` : `Embedding API request failed with status ${response.status}.`
+      );
+    }
+    return parseEmbeddingResponse(await response.json(), inputs.length);
+  };
+  return {
+    embedDocuments: embed,
+    async embedQuery(query) {
+      const normalizedQuery = query.trim();
+      if (!normalizedQuery) {
+        throw new Error("Embedding query must not be empty.");
+      }
+      const [embedding] = await embed([buildQueryInput(normalizedQuery, config.queryInstruction)]);
+      return embedding;
+    }
+  };
+};
+const normalizeEmbeddingApiUrl = buildEmbeddingsUrl;
+const normalizeEmbeddingModelsUrl = buildModelsUrl;
+export {
+  createOpenAiCompatibleEmbeddingClient,
+  listOpenAiCompatibleEmbeddingModels,
+  normalizeEmbeddingApiUrl,
+  normalizeEmbeddingModelsUrl
+};

package/server/dist/features/search/graphql/index.js

@@ -0,0 +1,6 @@
+import { searchResolvers } from "./resolver.js";
+import { searchTypeDefs } from "./type-defs.js";
+export {
+  searchResolvers,
+  searchTypeDefs
+};

package/server/dist/features/search/graphql/resolver.js

@@ -0,0 +1,32 @@
+import { searchNotesHybrid } from "../hybrid-search.js";
+import { searchRelatedNotes } from "../related-notes.js";
+const createSearchNotesResolver = (search = searchNotesHybrid) => {
+  return async (_, { query, pagination, mode = "HYBRID" }) => {
+    return search({
+      query,
+      limit: Math.min(50, Math.max(0, pagination.limit)),
+      offset: Math.max(0, pagination.offset),
+      mode: mode.toLowerCase()
+    });
+  };
+};
+const createSearchRelatedNotesResolver = (findRelatedNotes = searchRelatedNotes) => {
+  return async (_, { noteId, limit = 5 }) => {
+    const numericNoteId = Number(noteId);
+    if (!Number.isSafeInteger(numericNoteId) || numericNoteId <= 0) {
+      return [];
+    }
+    return findRelatedNotes(numericNoteId, Math.min(5, Math.max(0, Number(limit))));
+  };
+};
+const searchResolvers = {
+  Query: {
+    searchNotes: createSearchNotesResolver(),
+    searchRelatedNotes: createSearchRelatedNotesResolver()
+  }
+};
+export {
+  createSearchNotesResolver,
+  createSearchRelatedNotesResolver,
+  searchResolvers
+};

package/server/dist/features/search/graphql/type-defs.js

@@ -0,0 +1,37 @@
+import { gql } from "../../../modules/graphql.js";
+const searchTypeDefs = gql`
+    enum SearchMode {
+        HYBRID
+        LEXICAL
+        SEMANTIC
+    }
+
+    type SearchNoteMatch {
+        noteId: ID!
+        lexical: Boolean!
+        semantic: Boolean!
+    }
+
+    type SearchRelatedNote {
+        id: ID!
+        title: String!
+        reasons: [String!]!
+    }
+
+    type SearchNotesResult {
+        totalCount: Int!
+        notes: [Note!]!
+        matches: [SearchNoteMatch!]!
+        semanticAvailable: Boolean!
+        semanticUsed: Boolean!
+        semanticError: String
+    }
+
+    extend type Query {
+        searchNotes(query: String!, pagination: PaginationInput!, mode: SearchMode = HYBRID): SearchNotesResult!
+        searchRelatedNotes(noteId: ID!, limit: Int = 5): [SearchRelatedNote!]!
+    }
+`;
+export {
+  searchTypeDefs
+};

package/server/dist/features/search/http/handlers.js

@@ -0,0 +1,108 @@
+import { createAppError } from "../../../modules/error-handler.js";
+import { normalizeEmbeddingApiKey } from "../embedding-api-key-store.js";
+import { normalizeEmbeddingModelsUrl } from "../embedding-client.js";
+import { normalizeSemanticSearchConfig } from "../search-config.js";
+import {
+  getDefaultSemanticSearchManager
+} from "../search-manager.js";
+import { stripTrailingSlashes } from "../url-normalization.js";
+const parseApiKeyInput = (value) => {
+  if (!value || typeof value !== "object" || !Object.hasOwn(value, "apiKey")) {
+    return { provided: false };
+  }
+  const rawApiKey = value.apiKey;
+  if (rawApiKey !== null && typeof rawApiKey !== "string") {
+    throw createAppError(400, "INVALID_EMBEDDING_API_KEY", "Embedding API key must be a string or null.");
+  }
+  try {
+    return {
+      provided: true,
+      apiKey: rawApiKey === null ? void 0 : normalizeEmbeddingApiKey(rawApiKey)
+    };
+  } catch (error) {
+    throw createAppError(
+      400,
+      "INVALID_EMBEDDING_API_KEY",
+      error instanceof Error ? error.message : "Embedding API key is invalid."
+    );
+  }
+};
+const parseConfig = (value) => {
+  if (!value || typeof value !== "object") {
+    throw createAppError(400, "INVALID_SEARCH_CONFIG", "Semantic search settings must be an object.");
+  }
+  const config = value;
+  if (typeof config.enabled !== "boolean" || typeof config.baseUrl !== "string" || typeof config.model !== "string" || typeof config.queryInstruction !== "string") {
+    throw createAppError(
+      400,
+      "INVALID_SEARCH_CONFIG",
+      "enabled, baseUrl, model, and queryInstruction are required."
+    );
+  }
+  try {
+    return normalizeSemanticSearchConfig(config);
+  } catch (error) {
+    throw createAppError(
+      400,
+      "INVALID_SEARCH_CONFIG",
+      error instanceof Error ? error.message : "Semantic search settings are invalid."
+    );
+  }
+};
+const parseBaseUrl = (value) => {
+  if (!value || typeof value !== "object" || typeof value.baseUrl !== "string") {
+    throw createAppError(400, "INVALID_EMBEDDING_API_URL", "Embedding API URL is required.");
+  }
+  const inputBaseUrl = value.baseUrl;
+  if (inputBaseUrl.length > 2048) {
+    throw createAppError(400, "INVALID_EMBEDDING_API_URL", "Embedding API URL is too long.");
+  }
+  const baseUrl = stripTrailingSlashes(inputBaseUrl.trim());
+  try {
+    normalizeEmbeddingModelsUrl(baseUrl);
+  } catch (error) {
+    throw createAppError(
+      400,
+      "INVALID_EMBEDDING_API_URL",
+      error instanceof Error ? error.message : "Embedding API URL is invalid."
+    );
+  }
+  return baseUrl;
+};
+const createSearchAdminStatusHandler = (manager = getDefaultSemanticSearchManager()) => {
+  return async (_req, res) => {
+    res.status(200).json(await manager.getStatus()).end();
+  };
+};
+const createSearchAdminSaveConfigHandler = (manager = getDefaultSemanticSearchManager()) => {
+  return async (req, res) => {
+    const status = await manager.saveConfig(parseConfig(req.body), parseApiKeyInput(req.body));
+    res.status(200).json(status).end();
+  };
+};
+const createSearchAdminTestConnectionHandler = (manager = getDefaultSemanticSearchManager()) => {
+  return async (req, res) => {
+    const config = parseConfig({ ...req.body, enabled: true });
+    const result = await manager.testConnection(config, parseApiKeyInput(req.body));
+    res.status(200).json(result).end();
+  };
+};
+const createSearchAdminListModelsHandler = (listModels = (baseUrl, apiKeyInput) => getDefaultSemanticSearchManager().listModels(baseUrl, apiKeyInput)) => {
+  return async (req, res) => {
+    const models = await listModels(parseBaseUrl(req.body), parseApiKeyInput(req.body));
+    res.status(200).json({ models }).end();
+  };
+};
+const createSearchAdminReindexHandler = (manager = getDefaultSemanticSearchManager()) => {
+  return async (_req, res) => {
+    const result = await manager.startReindex();
+    res.status(result.started ? 202 : 200).json(result).end();
+  };
+};
+export {
+  createSearchAdminListModelsHandler,
+  createSearchAdminReindexHandler,
+  createSearchAdminSaveConfigHandler,
+  createSearchAdminStatusHandler,
+  createSearchAdminTestConnectionHandler
+};

package/server/dist/features/search/hybrid-ranking.js

@@ -0,0 +1,57 @@
+const DEFAULT_LEXICAL_WEIGHT = 1;
+const DEFAULT_SEMANTIC_WEIGHT = 1.25;
+const DEFAULT_RANK_CONSTANT = 60;
+const uniqueNoteIds = (noteIds) => {
+  return [...new Set(noteIds.filter((noteId) => Number.isInteger(noteId) && noteId > 0))];
+};
+const fuseHybridSearchRanks = ({
+  lexicalNoteIds,
+  semanticNoteIds,
+  lexicalWeight = DEFAULT_LEXICAL_WEIGHT,
+  semanticWeight = DEFAULT_SEMANTIC_WEIGHT,
+  rankConstant = DEFAULT_RANK_CONSTANT
+}) => {
+  const lexicalIds = uniqueNoteIds(lexicalNoteIds);
+  const semanticIds = uniqueNoteIds(semanticNoteIds);
+  const candidates = /* @__PURE__ */ new Map();
+  const addRankedIds = (noteIds, source, weight) => {
+    noteIds.forEach((noteId, index) => {
+      const rank = index + 1;
+      const candidate = candidates.get(noteId) ?? {
+        noteId,
+        lexicalRank: null,
+        semanticRank: null,
+        score: 0
+      };
+      candidate.score += weight / (rankConstant + rank);
+      if (source === "lexical") {
+        candidate.lexicalRank = rank;
+      } else {
+        candidate.semanticRank = rank;
+      }
+      candidates.set(noteId, candidate);
+    });
+  };
+  addRankedIds(lexicalIds, "lexical", lexicalWeight);
+  addRankedIds(semanticIds, "semantic", semanticWeight);
+  return [...candidates.values()].sort((left, right) => {
+    if (left.score !== right.score) {
+      return right.score - left.score;
+    }
+    const leftBestRank = Math.min(left.lexicalRank ?? Number.POSITIVE_INFINITY, left.semanticRank ?? Infinity);
+    const rightBestRank = Math.min(right.lexicalRank ?? Number.POSITIVE_INFINITY, right.semanticRank ?? Infinity);
+    if (leftBestRank !== rightBestRank) {
+      return leftBestRank - rightBestRank;
+    }
+    if (left.lexicalRank !== null && right.lexicalRank === null) {
+      return -1;
+    }
+    if (left.lexicalRank === null && right.lexicalRank !== null) {
+      return 1;
+    }
+    return left.noteId - right.noteId;
+  });
+};
+export {
+  fuseHybridSearchRanks
+};