@hiai-gg/docsmint 0.8.7 → 0.9.0

package/README.md

@@ -42,17 +42,19 @@ instructions, and verify the connection. Hosted MCP follows your plan and
 workspace permissions. Prefer workspace-bound or category-scoped credentials.
 
 The Cloud endpoint is `https://docsmint.com/mcp` (Streamable HTTP). OAuth-capable
-clients discover authorization and open DocsMint login and consent in the browser.
-Choose your workspace and explicit scopes; the authorization code uses PKCE S256.
-Access tokens expire after one hour; reconnect through browser authorization when
-they expire (no refresh tokens). API-key clients
-send `Authorization: Bearer <key>`. Credentials cannot create or elevate other
-credentials; lifecycle management belongs to the signed-in browser session.
+clients discover the hosted resource and authorization-server metadata; current
+authorization and client-connection methods are described in the
+[DocsMint Cloud setup guide](https://docsmint.com/mcp/connect?source=github_mcp).
+Browser consent binds the one-hour opaque access token to the selected workspace,
+optional category, and requested scopes. Refresh tokens are not issued. API-key clients can instead send
+`Authorization: Bearer <key>` with an MCP/API credential created in the authenticated
+browser UI. Credentials cannot create or elevate other credentials; lifecycle
+management belongs to the signed-in browser session.
 
 **Self-hosted alternative:** run [DocsMint with Docker](#quickstart), create an API
 key in its browser UI, and configure `HIAI_DOCS_URL` and `HIAI_DOCS_API_KEY` for
 `npx --yes --package @hiai-gg/docsmint docsmint-mcp`. The npm package is a stdio
-bridge to your running deployment, not a server installer. See the
+bridge to your own API, not a server installer or hosted OAuth server. See the
 [MCP guide](https://github.com/HiAi-gg/docsmint/blob/main/packages/mcp-server/README.md) for client configuration.
 
 ## Why DocsMint?
@@ -70,20 +72,19 @@ bridge to your running deployment, not a server installer. See the
 - **Choose how you run it.** Use [managed DocsMint](https://docsmint.com) or
   self-host the application, database, search, queues, and files.
 
-## What's new in 0.8.7?
+## What's new in 0.9.0?
 
-Agents can now complete more document workflows without leaving MCP:
+- Keep MCP `list_documents` output aligned with the public SDK by returning
+  folder and category names, and invalidate stale list entries after metadata
+  changes for every member of the affected workspace.
+- Publish all 21 MCP tools with stable schemas and clearer parameter guidance;
+  expose the canonical `capabilityCatalog` for hosted contract checks.
+- Reject category-scoped document creation when the selected folder belongs to
+  a different category.
+- Keep category-list response types and Cloud connection guidance aligned with
+  the public API and supported setup flow.
 
-- Move documents to trash, remove folders or categories, and restore saved versions.
-- Keep changes within workspace/category permissions; version restoration requires edit access.
-- Discover clearer tool descriptions, parameter guidance, and destructive-operation annotations.
-- Apply GraphRAG query text and related-document result limits consistently.
-
-The MCP surface grows additively from 17 to 21 tools. Existing tool names remain
-available. No database migration is required. Hosted clients receive these tools
-when their DocsMint host adopts this release.
-
-Read the [release notes](https://github.com/HiAi-gg/docsmint/releases/tag/v0.8.7)
+This release adds no database migration. See the [release notes](https://github.com/HiAi-gg/docsmint/releases/tag/v0.9.0)
 and [changelog](https://github.com/HiAi-gg/docsmint/blob/main/CHANGELOG.md).
 
 ## Install with an AI agent
@@ -136,7 +137,7 @@ docker pull vgalibov/docsmint:web-latest
 docker pull vgalibov/docsmint:caddy-latest
 ```
 
-Use versioned tags `api-v0.8.7`, `web-v0.8.7`, and `caddy-v0.8.7` for
+Use versioned tags `api-v0.9.0`, `web-v0.9.0`, and `caddy-v0.9.0` for
 reproducible deploys. Caddy is the supporting reverse proxy with rate limiting;
 it is separate from the API and web application. The quickstart still builds the Compose stack from this repository so PostgreSQL,
 Redis, and SeaweedFS start together with the application.
@@ -221,7 +222,7 @@ command and configuration precedence.
 ## Connect an MCP client
 
 Give agents a secure path to search, read, and maintain your knowledge without
-database or filesystem access. DocsMint publishes 21 tools plus ready-made
+database or filesystem access. DocsMint publishes MCP tools plus ready-made
 research prompts, scoped resources, and a document-manager skill.
 
 ### Hosted DocsMint

package/dist/backend/index.js

@@ -200640,6 +200640,112 @@ function buildApiAccessValues(input) {
   };
 }
 
+// ../../backend/src/lib/doc-cache.ts
+init_logger3();
+init_redis();
+var LIST_PREFIX = "hiai-docs:cache:docs:list:";
+var SINGLE_PREFIX = "hiai-docs:cache:docs:single:";
+function docListKey(userId, folderId, tag2, page = 1, limit = 20, workspaceId) {
+  const parts = [`${LIST_PREFIX}${userId}`];
+  if (workspaceId)
+    parts.push(`w:${workspaceId}`);
+  if (folderId)
+    parts.push(`f:${folderId}`);
+  if (tag2)
+    parts.push(`t:${tag2}`);
+  parts.push(`p:${page}`, `l:${limit}`);
+  return parts.join(":");
+}
+function docSingleKey(docId, userId, workspaceId) {
+  return `${SINGLE_PREFIX}${userId}${workspaceId ? `:w:${workspaceId}` : ""}:${docId}`;
+}
+async function cacheGetOrSet(key, ttl, compute, options = {}) {
+  try {
+    const cached2 = await redis.get(key);
+    if (cached2)
+      return JSON.parse(cached2);
+  } catch (err) {
+    logger3.warn({ err, key }, "Redis get failed, falling through to DB");
+  }
+  const value = await compute();
+  if (options.shouldCache && !options.shouldCache(value))
+    return value;
+  try {
+    await redis.set(key, JSON.stringify(value), "EX", ttl);
+  } catch (err) {
+    logger3.warn({ err, key }, "Redis set failed");
+  }
+  return value;
+}
+function isHttpCacheEnvelope(value) {
+  return typeof value === "object" && value !== null && "version" in value && value.version === 1 && "kind" in value && value.kind === "http-response" && "status" in value && typeof value.status === "number" && Number.isInteger(value.status) && value.status >= 100 && value.status <= 599 && "body" in value;
+}
+async function cacheHttpResponse(key, ttl, compute, options = {}) {
+  try {
+    const cached2 = await redis.get(key);
+    if (cached2) {
+      const parsed = JSON.parse(cached2);
+      if (isHttpCacheEnvelope(parsed)) {
+        return {
+          status: parsed.status,
+          body: parsed.body,
+          cacheHit: true
+        };
+      }
+    }
+  } catch (err) {
+    logger3.warn({ err, key }, "Redis HTTP cache get failed, falling through to DB");
+  }
+  const value = await compute();
+  if (options.shouldCache && !options.shouldCache(value)) {
+    return { ...value, cacheHit: false };
+  }
+  const envelope = {
+    version: 1,
+    kind: "http-response",
+    status: value.status,
+    body: value.body
+  };
+  try {
+    await redis.set(key, JSON.stringify(envelope), "EX", ttl);
+  } catch (err) {
+    logger3.warn({ err, key }, "Redis HTTP cache set failed");
+  }
+  return { ...value, cacheHit: false };
+}
+async function invalidateDocListCache(userId, workspaceId) {
+  const patterns = new Set([`${LIST_PREFIX}${userId}:*`]);
+  if (workspaceId)
+    patterns.add(`${LIST_PREFIX}*:w:${workspaceId}:*`);
+  try {
+    for (const pattern of patterns) {
+      let cursor = "0";
+      do {
+        const [newCursor, keys] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
+        cursor = newCursor;
+        if (keys.length > 0)
+          await redis.del(...keys);
+      } while (cursor !== "0");
+    }
+  } catch (err) {
+    logger3.warn({ err, userId, workspaceId }, "Failed to invalidate doc list cache");
+  }
+}
+async function invalidateDocCache(docId) {
+  const pattern = `${SINGLE_PREFIX}*:${docId}:scope:*`;
+  try {
+    let cursor = "0";
+    do {
+      const [newCursor, keys] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
+      cursor = newCursor;
+      if (keys.length > 0)
+        await redis.del(...keys);
+    } while (cursor !== "0");
+  } catch (err) {
+    logger3.warn({ err, docId }, "Failed to invalidate doc cache");
+  }
+}
+
 // ../../backend/src/api/routes/categories.ts
 init_logger3();
 var createCategorySchema = exports_external2.object({
@@ -200861,6 +200967,7 @@ var categoryRoutes = new Elysia({ prefix: "/api" }).get("/categories", async ({
       set2.status = 404;
       return { error: "Category not found" };
     }
+    await invalidateDocListCache(ctx.userId, ctx.workspaceId);
     if (parsed.data.name !== undefined) {
       dispatchMetadataReembedOutbox(updated.operationId, metadataReembedPageSize("category"));
     }
@@ -200908,6 +201015,7 @@ var categoryRoutes = new Elysia({ prefix: "/api" }).get("/categories", async ({
       set2.status = 404;
       return { error: "Category not found" };
     }
+    await invalidateDocListCache(ctx.userId, ctx.workspaceId);
     dispatchMetadataReembedOutbox(deletion.operationId, metadataReembedPageSize("category"));
     return { success: true };
   } catch (err) {
@@ -228024,110 +228132,6 @@ function createYjsRoomKey(input) {
 
 // ../../backend/src/api/routes/collaboration.ts
 init_config();
-
-// ../../backend/src/lib/doc-cache.ts
-init_logger3();
-init_redis();
-var LIST_PREFIX = "hiai-docs:cache:docs:list:";
-var SINGLE_PREFIX = "hiai-docs:cache:docs:single:";
-function docListKey(userId, folderId, tag2, page = 1, limit = 20, workspaceId) {
-  const parts = [`${LIST_PREFIX}${userId}`];
-  if (workspaceId)
-    parts.push(`w:${workspaceId}`);
-  if (folderId)
-    parts.push(`f:${folderId}`);
-  if (tag2)
-    parts.push(`t:${tag2}`);
-  parts.push(`p:${page}`, `l:${limit}`);
-  return parts.join(":");
-}
-function docSingleKey(docId, userId, workspaceId) {
-  return `${SINGLE_PREFIX}${userId}${workspaceId ? `:w:${workspaceId}` : ""}:${docId}`;
-}
-async function cacheGetOrSet(key, ttl, compute, options = {}) {
-  try {
-    const cached2 = await redis.get(key);
-    if (cached2)
-      return JSON.parse(cached2);
-  } catch (err) {
-    logger3.warn({ err, key }, "Redis get failed, falling through to DB");
-  }
-  const value = await compute();
-  if (options.shouldCache && !options.shouldCache(value))
-    return value;
-  try {
-    await redis.set(key, JSON.stringify(value), "EX", ttl);
-  } catch (err) {
-    logger3.warn({ err, key }, "Redis set failed");
-  }
-  return value;
-}
-function isHttpCacheEnvelope(value) {
-  return typeof value === "object" && value !== null && "version" in value && value.version === 1 && "kind" in value && value.kind === "http-response" && "status" in value && typeof value.status === "number" && Number.isInteger(value.status) && value.status >= 100 && value.status <= 599 && "body" in value;
-}
-async function cacheHttpResponse(key, ttl, compute, options = {}) {
-  try {
-    const cached2 = await redis.get(key);
-    if (cached2) {
-      const parsed = JSON.parse(cached2);
-      if (isHttpCacheEnvelope(parsed)) {
-        return {
-          status: parsed.status,
-          body: parsed.body,
-          cacheHit: true
-        };
-      }
-    }
-  } catch (err) {
-    logger3.warn({ err, key }, "Redis HTTP cache get failed, falling through to DB");
-  }
-  const value = await compute();
-  if (options.shouldCache && !options.shouldCache(value)) {
-    return { ...value, cacheHit: false };
-  }
-  const envelope = {
-    version: 1,
-    kind: "http-response",
-    status: value.status,
-    body: value.body
-  };
-  try {
-    await redis.set(key, JSON.stringify(envelope), "EX", ttl);
-  } catch (err) {
-    logger3.warn({ err, key }, "Redis HTTP cache set failed");
-  }
-  return { ...value, cacheHit: false };
-}
-async function invalidateDocListCache(userId) {
-  const pattern = `${LIST_PREFIX}${userId}:*`;
-  try {
-    let cursor = "0";
-    do {
-      const [newCursor, keys4] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
-      cursor = newCursor;
-      if (keys4.length > 0)
-        await redis.del(...keys4);
-    } while (cursor !== "0");
-  } catch (err) {
-    logger3.warn({ err, userId }, "Failed to invalidate doc list cache");
-  }
-}
-async function invalidateDocCache(docId) {
-  const pattern = `${SINGLE_PREFIX}*:${docId}:scope:*`;
-  try {
-    let cursor = "0";
-    do {
-      const [newCursor, keys4] = await redis.scan(cursor, "MATCH", pattern, "COUNT", 100);
-      cursor = newCursor;
-      if (keys4.length > 0)
-        await redis.del(...keys4);
-    } while (cursor !== "0");
-  } catch (err) {
-    logger3.warn({ err, docId }, "Failed to invalidate doc cache");
-  }
-}
-
-// ../../backend/src/api/routes/collaboration.ts
 init_logger3();
 
 // ../../node_modules/.bun/y-protocols@1.0.7+48ebd0cf55a3d4ab/node_modules/y-protocols/sync.js
@@ -228514,7 +228518,7 @@ collaborationRoutes.ws("/api/ws/collab/:documentId", {
         });
         await Promise.all([
           invalidateDocCache(documentId),
-          invalidateDocListCache(access.userId)
+          invalidateDocListCache(access.userId, access.ctx.workspaceId)
         ]);
         enqueueReembed([
           {
@@ -228982,6 +228986,27 @@ async function withTags(ctx, rows) {
   }
   return rows.map((r4) => ({ ...r4, tags: byDoc.get(r4.id) ?? [] }));
 }
+async function withDocumentLocationNames(ctx, rows) {
+  if (rows.length === 0)
+    return [];
+  const folderIds = [
+    ...new Set(rows.flatMap((row) => row.folderId ? [row.folderId] : []))
+  ];
+  const categoryIds = [
+    ...new Set(rows.flatMap((row) => row.categoryId ? [row.categoryId] : []))
+  ];
+  const [folderRows, categoryRows] = await withTenant(ctx, async (tx) => Promise.all([
+    folderIds.length > 0 ? tx.select({ id: folders.id, name: folders.name }).from(folders).where(inArray(folders.id, folderIds)) : Promise.resolve([]),
+    categoryIds.length > 0 ? tx.select({ id: categories.id, name: categories.name }).from(categories).where(inArray(categories.id, categoryIds)) : Promise.resolve([])
+  ]));
+  const folderNames = new Map(folderRows.map((folder) => [folder.id, folder.name]));
+  const categoryNames = new Map(categoryRows.map((category) => [category.id, category.name]));
+  return rows.map((row) => ({
+    ...row,
+    folderName: row.folderId ? folderNames.get(row.folderId) ?? null : null,
+    categoryName: row.categoryId ? categoryNames.get(row.categoryId) ?? null : null
+  }));
+}
 var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ query, set: set2, request }) => {
   const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "unknown";
   const rl = await documentRateLimiter(ip, request);
@@ -229009,7 +229034,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
   }
   const { folderId, tag: tag2, page, limit } = parsed.data;
   const offset = (page - 1) * limit;
-  const cacheKey = `${docListKey(userId, folderId, tag2, page, limit, ctx.workspaceId)}:scope:${access.categoryId ?? "all"}`;
+  const cacheKey = `${docListKey(userId, folderId, tag2, page, limit, ctx.workspaceId)}:scope:${access.categoryId ?? "all"}:response:v2`;
   try {
     return await cacheGetOrSet(cacheKey, 30, async () => {
       const conditions2 = [
@@ -229038,7 +229063,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
           ]);
         });
         return {
-          items: await withTags(ctx, rows2),
+          items: await withDocumentLocationNames(ctx, await withTags(ctx, rows2)),
           total: countResult2[0]?.total ?? 0,
           page,
           limit
@@ -229060,7 +229085,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
         ]);
       });
       return {
-        items: await withTags(ctx, rows),
+        items: await withDocumentLocationNames(ctx, await withTags(ctx, rows)),
         total: countResult[0]?.total ?? 0,
         page,
         limit
@@ -229231,9 +229256,9 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
         await acquireTenantTopologyLock(tx, ctx);
       }
       let categoryId = requestedCategoryId;
-      if (folderId && !categoryId) {
-        const resolvedCategoryId = await resolveFolderEffectiveCategory(tx, ctx, folderId);
-        if (resolvedCategoryId === undefined) {
+      if (folderId) {
+        const folderCategoryId = await resolveFolderEffectiveCategory(tx, ctx, folderId);
+        if (folderCategoryId === undefined) {
           return {
             row: null,
             replayed: false,
@@ -229241,7 +229266,16 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
             forbidden: true
           };
         }
-        categoryId = resolvedCategoryId;
+        if (access.restricted && !isAuthorizedCategory(access, folderCategoryId)) {
+          return {
+            row: null,
+            replayed: false,
+            conflict: false,
+            forbidden: true
+          };
+        }
+        if (!categoryId)
+          categoryId = folderCategoryId;
       }
       if (!isAuthorizedCategory(access, categoryId)) {
         return {
@@ -229325,7 +229359,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
       revision: contentHash(created.title, created.content ?? ""),
       source: "interactive"
     }).catch((err) => logger3.warn({ err, documentId: created.id }, "Pipeline enqueue failed"));
-    invalidateDocListCache(userId);
+    invalidateDocListCache(userId, ctx.workspaceId);
     set2.status = 201;
     const ipAddress = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "";
     const userAgent = request.headers.get("user-agent") ?? "";
@@ -230051,7 +230085,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
     }
     await Promise.all([
       invalidateDocCache(params2.id),
-      invalidateDocListCache(userId)
+      invalidateDocListCache(userId, ctx.workspaceId)
     ]);
     const ipAddress = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "";
     const userAgent = request.headers.get("user-agent") ?? "";
@@ -230316,7 +230350,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
       revision: contentHash(copy3.title, copy3.content ?? ""),
       source: "interactive"
     }).catch((err) => logger3.warn({ err, documentId: copy3.id }, "Pipeline enqueue failed"));
-    invalidateDocListCache(userId);
+    invalidateDocListCache(userId, ctx.workspaceId);
     set2.status = 201;
     return copy3;
   } catch (err) {
@@ -230386,7 +230420,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
     return { error: "Document not found" };
   }
   invalidateDocCache(params2.id);
-  invalidateDocListCache(ctx.userId);
+  invalidateDocListCache(ctx.userId, ctx.workspaceId);
   return { success: true };
 }).delete("/trash/documents/:id", async ({ params: params2, request, set: set2 }) => {
   const access = await resolveContentAccess(request);
@@ -230496,7 +230530,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
       });
     }
     invalidateDocCache(params2.id);
-    invalidateDocListCache(ctx.userId);
+    invalidateDocListCache(ctx.userId, ctx.workspaceId);
     return { success: true };
   } catch (error53) {
     if (error53 instanceof DocumentPurgeNotFoundError) {
@@ -230552,7 +230586,7 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
       return { error: "Document not found" };
     }
     invalidateDocCache(params2.id);
-    invalidateDocListCache(userId);
+    invalidateDocListCache(userId, ctx.workspaceId);
     const ipAddress = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "";
     const userAgent = request.headers.get("user-agent") ?? "";
     recordAuditEvent({
@@ -231397,7 +231431,7 @@ var folderRoutes = new Elysia({ prefix: "/api/folders" }).get("/:id", async ({ p
     }
     if (parsed.data.name !== undefined || parsed.data.parentId !== undefined || parsed.data.categoryId !== undefined) {
       dispatchMetadataReembedOutbox(result.operationId, metadataReembedPageSize("folder"));
-      invalidateDocListCache(userId);
+      await invalidateDocListCache(userId, ctx.workspaceId);
     }
     return result.updated;
   } catch (err) {
@@ -231450,6 +231484,7 @@ var folderRoutes = new Elysia({ prefix: "/api/folders" }).get("/:id", async ({ p
       set2.status = 404;
       return { error: "Folder not found" };
     }
+    await invalidateDocListCache(ctx.userId, ctx.workspaceId);
     dispatchMetadataReembedOutbox(deletion.operationId, metadataReembedPageSize("folder"));
     return { success: true };
   } catch (err) {
@@ -232059,50 +232094,6 @@ function stripQuotes2(value) {
   return trimmed;
 }
 
-// ../../backend/src/api/routes/health.ts
-function createHealthRoutes(dependencies) {
-  return new Elysia().get("/api/health", async ({ request, set: set2 }) => {
-    const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "unknown";
-    const rateLimit = await dependencies.rateLimiter(ip, request);
-    set2.headers = {
-      "X-RateLimit-Remaining": String(rateLimit.remaining),
-      ...rateLimit.retryAfter ? { "Retry-After": String(rateLimit.retryAfter) } : {}
-    };
-    if (!rateLimit.allowed) {
-      set2.status = 429;
-      return { error: "Too many requests" };
-    }
-    const [databaseAvailable, redisAvailable, storageAvailable] = await Promise.all([
-      dependencies.databaseAvailable(),
-      dependencies.redisAvailable(),
-      dependencies.storageAvailable()
-    ]);
-    const queueAvailable = dependencies.queueAvailable();
-    const readiness = evaluatePipelineHealth({
-      databaseAvailable,
-      redisAvailable,
-      storageAvailable,
-      queueAvailable,
-      recoveryAvailable: true,
-      oldestInteractiveWaitMs: 0,
-      interactiveSloMs: Number.POSITIVE_INFINITY,
-      graphAvailable: true
-    });
-    if (readiness.status === "unhealthy")
-      set2.status = 503;
-    return {
-      status: readiness.status === "unhealthy" ? "unhealthy" : "ok",
-      service: "docsmint",
-      timestamp: new Date().toISOString(),
-      database: databaseAvailable ? "ok" : "error",
-      redis: redisAvailable ? "ok" : "error",
-      storage: storageAvailable ? "ok" : "error",
-      queue: queueAvailable ? "ok" : "error",
-      ...readiness.reasons.length ? { reasons: readiness.reasons } : {}
-    };
-  });
-}
-
 // ../../backend/src/api/routes/keys.ts
 init_schema2();
 init_drizzle_orm();
@@ -235959,6 +235950,53 @@ var webhookRoutes = new Elysia({ prefix: "/api/webhooks" }).post("/storage", asy
   return { received: true };
 });
 
+// ../../backend/src/api/register-routes.ts
+var selfHostedApiRoutes = new Elysia().use(authRoutes).use(tagRoutes).use(categoryRoutes).use(attachmentRoutes).use(shareRoutes).use(searchRoutes).use(documentRoutes).use(folderRoutes).use(versionRoutes).use(webhookRoutes).use(collaborationRoutes).use(graphRoutes).use(keysRoutes).use(pluginsRoutes).use(visibilityRoutes).use(adminRoutes).use(metricsRoutes);
+
+// ../../backend/src/api/routes/health.ts
+function createHealthRoutes(dependencies) {
+  return new Elysia().get("/api/health", async ({ request, set: set2 }) => {
+    const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? request.headers.get("x-real-ip") ?? "unknown";
+    const rateLimit = await dependencies.rateLimiter(ip, request);
+    set2.headers = {
+      "X-RateLimit-Remaining": String(rateLimit.remaining),
+      ...rateLimit.retryAfter ? { "Retry-After": String(rateLimit.retryAfter) } : {}
+    };
+    if (!rateLimit.allowed) {
+      set2.status = 429;
+      return { error: "Too many requests" };
+    }
+    const [databaseAvailable, redisAvailable, storageAvailable] = await Promise.all([
+      dependencies.databaseAvailable(),
+      dependencies.redisAvailable(),
+      dependencies.storageAvailable()
+    ]);
+    const queueAvailable = dependencies.queueAvailable();
+    const readiness = evaluatePipelineHealth({
+      databaseAvailable,
+      redisAvailable,
+      storageAvailable,
+      queueAvailable,
+      recoveryAvailable: true,
+      oldestInteractiveWaitMs: 0,
+      interactiveSloMs: Number.POSITIVE_INFINITY,
+      graphAvailable: true
+    });
+    if (readiness.status === "unhealthy")
+      set2.status = 503;
+    return {
+      status: readiness.status === "unhealthy" ? "unhealthy" : "ok",
+      service: "docsmint",
+      timestamp: new Date().toISOString(),
+      database: databaseAvailable ? "ok" : "error",
+      redis: redisAvailable ? "ok" : "error",
+      storage: storageAvailable ? "ok" : "error",
+      queue: queueAvailable ? "ok" : "error",
+      ...readiness.reasons.length ? { reasons: readiness.reasons } : {}
+    };
+  });
+}
+
 // ../../backend/src/lib/api-key-owner.ts
 init_schema2();
 init_config();
@@ -238422,7 +238460,7 @@ var swaggerConfig = {
     },
     info: {
       title: "DocsMint API",
-      version: "0.8.7",
+      version: "0.9.0",
       description: "Self-hosted AI-native knowledge workspace and installable PWA with hybrid search, GraphRAG, REST, SDK, CLI, and MCP access for people and AI agents.",
       contact: { name: "HiAi-gg", url: "https://github.com/HiAi-gg/docsmint" },
       license: {
@@ -238476,7 +238514,7 @@ var app = new Elysia().use(bodySizeLimit).onError(({ error: error53, set: set2 }
   redisAvailable: () => redis.ping().then(() => true, () => false),
   storageAvailable: () => storage.send(new ListBucketsCommand({})).then(() => true, () => false),
   queueAvailable: () => pipelineRuntime.workers.size === PIPELINE_STAGES.length && [...pipelineRuntime.workers.values()].every((worker2) => worker2.isRunning?.() === true)
-})).use(csrfMiddleware).use(authMiddleware).use(authRoutes).use(tagRoutes).use(categoryRoutes).use(attachmentRoutes).use(shareRoutes).use(searchRoutes).use(documentRoutes).use(folderRoutes).use(versionRoutes).use(webhookRoutes).use(collaborationRoutes).use(graphRoutes).use(keysRoutes).use(pluginsRoutes).use(visibilityRoutes).use(adminRoutes).use(metricsRoutes);
+})).use(csrfMiddleware).use(authMiddleware).use(selfHostedApiRoutes);
 app.listen({
   port: config3.API_PORT,
   development: config3.NODE_ENV !== "production",

package/dist/client.d.ts

@@ -7,7 +7,7 @@
  * failures (502 / 503 / 504 / timeout / network reset) are retried
  * with exponential backoff up to `config.retries` attempts.
  */
-import type { DocsApiKeyCreated, DocsApiKeyListResponse, DocsAttachment, DocsAttachmentConfirmInput, DocsAttachmentListResponse, DocsAttachmentPresignInput, DocsAttachmentPresignResponse, DocsCategory, DocsCategoryInput, DocsCategoryUpdate, DocsDocument, DocsDocumentCreateInput, DocsDocumentCursorPage, DocsDocumentIndexRefresh, DocsDocumentIndexStatus, DocsDocumentKnowledgeSummary, DocsDocumentListResponse, DocsDocumentPipeline, DocsPipelineWarningRetry, DocsDocumentUpdateInput, DocsFolder, DocsFolderCreateInput, DocsFolderUpdateInput, DocsGraphEntitiesResponse, DocsGraphRelatedResponse, DocsGraphSearchResponse, DocsHealthResponse, DocsRequestContext, DocsSearchOptions, DocsSearchResponse, DocsSearchSuggestItem, DocsSharedContent, DocsShareLink, DocsShareListResponse, DocsShareRole, DocsTag, DocsVersion, DocsVersionDiff } from "./types.js";
+import type { DocsApiKeyCreated, DocsApiKeyListResponse, DocsAttachment, DocsAttachmentConfirmInput, DocsAttachmentListResponse, DocsAttachmentPresignInput, DocsAttachmentPresignResponse, DocsCategory, DocsCategoryListItem, DocsCategoryInput, DocsCategoryUpdate, DocsDocument, DocsDocumentCreateInput, DocsDocumentCursorPage, DocsDocumentIndexRefresh, DocsDocumentIndexStatus, DocsDocumentKnowledgeSummary, DocsDocumentListResponse, DocsDocumentPipeline, DocsPipelineWarningRetry, DocsDocumentUpdateInput, DocsFolder, DocsFolderCreateInput, DocsFolderUpdateInput, DocsGraphEntitiesResponse, DocsGraphRelatedResponse, DocsGraphSearchResponse, DocsHealthResponse, DocsRequestContext, DocsSearchOptions, DocsSearchResponse, DocsSearchSuggestItem, DocsSharedContent, DocsShareLink, DocsShareListResponse, DocsShareRole, DocsTag, DocsVersion, DocsVersionDiff } from "./types.js";
 export interface DocsClientConfig {
     /** Base URL of the DocsMint API, e.g. `http://localhost:50700`. */
     baseUrl: string;
@@ -126,7 +126,7 @@ export declare class DocsClient {
     deleteTag(id: string, context?: DocsRequestContext): Promise<void>;
     addTagToDoc(documentId: string, tagId: string, context?: DocsRequestContext): Promise<void>;
     removeTagFromDoc(documentId: string, tagId: string, context?: DocsRequestContext): Promise<void>;
-    listCategories(context?: DocsRequestContext): Promise<DocsCategory[]>;
+    listCategories(context?: DocsRequestContext): Promise<DocsCategoryListItem[]>;
     createCategory(input: DocsCategoryInput, context?: DocsRequestContext): Promise<DocsCategory>;
     updateCategory(id: string, updates: DocsCategoryUpdate, context?: DocsRequestContext): Promise<DocsCategory>;
     deleteCategory(id: string, context?: DocsRequestContext): Promise<void>;