@hiai-gg/docsmint 0.5.10 → 0.6.0

package/LICENSE

@@ -1,4 +1,5 @@
-Apache License
+
+                                 Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 
@@ -34,7 +35,8 @@ Apache License
 
       "Work" shall mean the work of authorship, whether in Source or
       Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work.
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
 
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
@@ -90,16 +92,17 @@ Apache License
       modifications, and in Source or Object form, provided that You
       meet the following conditions:
 
-      (a) You must give any other recipients of the Work or Derivative Works
-          a copy of this License; and
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
 
       (b) You must cause any modified files to carry prominent notices
           stating that You changed the files; and
 
-      (c) You must retain, in the Source form of any Derivative Works that
-          You distribute, all copyright, patent, trademark, and attribution
-          notices from the Source form of the Work, excluding those notices
-          that do not pertain to any part of the Derivative Works; and
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
 
       (d) If the Work includes a "NOTICE" text file as part of its
           distribution, then any Derivative Works that You distribute must
@@ -129,6 +132,9 @@ Apache License
       any Contribution intentionally submitted for inclusion in the Work
       by You to the Licensor shall be under the terms and conditions of
       this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
 
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
@@ -169,3 +175,28 @@ Apache License
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,6 +1,7 @@
 # DocsMint
 
-**A self-hosted, AI-native knowledge workspace for people, applications, and agents.**
+**A self-hosted AI-native knowledge workspace and installable PWA for people,
+applications, and AI agents.**
 
 DocsMint stores documents in a structured JSON editor model first. Markdown is
 the convenient second format for editing, importing, and exporting content.
@@ -38,24 +39,36 @@ server.
 - **Own the full stack**: application data, vectors, graph, queue, and files run
   on infrastructure you control.
 
-## What is new in the 0.3.0 release line?
-
-- **Installable Progressive Web App (PWA)** with a manifest, service worker,
-  responsive mobile shell, install prompt, update safety, and an offline
-  fallback shell.
-- **Offline document access** through identity-partitioned IndexedDB/Dexie
-  snapshots. Offline mode is cached read plus explicit local drafts; reconnect
-  never silently replays mutations.
-- **Explicit local drafts** with local autosave, review/apply, optimistic
-  concurrency (`expectedUpdatedAt`), and actionable conflict handling.
-- **Composable self-hosted UI** with typed dashboard/search hosts and extension
-  slots.
-- **Mobile-first editor polish** including a single responsive sidebar, safe
-  PWA updates, raw Markdown auto-height, and accessible narrow-screen controls.
-
-Search terms: installable self-hosted PWA knowledge base, offline document
-reading, local drafts, semantic multilingual search, GraphRAG, MCP, TypeScript
-SDK, CLI, and frontend extension hosts.
+## What's new in DocsMint 0.6.0?
+
+- **Installable, update-safe PWA.** A versioned service worker, responsive app
+  shell, install prompt, and deterministic offline fallback make DocsMint feel
+  at home on desktop and mobile browsers.
+- **Private offline reading and explicit drafts.** Identity-partitioned local
+  snapshots keep selected documents readable offline. Drafts autosave locally,
+  then return through a deliberate review-and-apply flow after reconnecting;
+  DocsMint never silently replays offline mutations.
+- **Touch-safe mobile navigation.** Sidebar document actions, Copy controls, and
+  overflow menus remain reachable on touch devices without depending on hover,
+  with accessible targets and narrow-screen layouts.
+- **A flexible editor contract.** Reactive visual/Markdown mode preferences,
+  Minimal toolbar support, and a reusable compact TipTap editor let hosts match
+  the writing surface to the task without forking editor internals.
+- **Stable document discovery.** The public API and TypeScript SDK provide
+  deterministic cursor pagination and global sorting by title, category,
+  folder, or update time, with canonical category and folder metadata.
+- **Clear public and restricted sharing.** Share creation exposes the resulting
+  URL for both public links and restricted invitation workflows, with an
+  explicit Copy action that works on narrow screens.
+- **Knowledge built for agents.** REST, the typed SDK, CLI, and MCP server expose
+  scoped document operations, while multilingual hybrid search and GraphRAG
+  help people and AI agents retrieve connected knowledge instead of isolated
+  keyword matches.
+
+DocsMint combines an installable self-hosted PWA knowledge base, mobile document
+workspace, offline reading, local drafts, multilingual semantic search,
+GraphRAG, MCP, a TypeScript SDK, CLI, and composable frontend hosts in one
+open-source system.
 
 For self-hosted customization, see [PWA hosting](docs/PWA_HOSTING.md) and
 [extension points](docs/EXTENDING.md).
@@ -96,6 +109,7 @@ git clone https://github.com/HiAi-gg/docsmint.git
 cd docsmint
 bash scripts/quickstart.sh
 ```
+
 On its first run, the script creates an ignored root `.env`, generates the
 database, authentication, and storage secrets, builds the PostgreSQL image,
 applies migrations, and starts the complete application.
@@ -105,12 +119,14 @@ For OpenRouter, add one value to `.env` and run the script again:
 ```dotenv
 OPENROUTER_API_KEY=sk-or-your-key
 ```
+
 For Ollama, select the local provider instead:
 
 ```dotenv
 AI_PROVIDER=ollama
 OLLAMA_PORT=11434
 ```
+
 Then make sure the configured local models are available:
 
 ```bash
@@ -118,6 +134,7 @@ ollama pull bge-m3
 ollama pull qwen3:8b
 bash scripts/quickstart.sh
 ```
+
 Open **http://localhost:50701**. The API health endpoint is
 **http://localhost:50700/api/health**.
 
@@ -133,14 +150,14 @@ Open **http://localhost:50701**. The API health endpoint is
 
 The canonical local ports are:
 
-| Service | Port |
-|---|---:|
-| Web application | `50701` |
-| REST API | `50700` |
-| PostgreSQL | `5437` |
-| Redis | `6384` |
+| Service              |    Port |
+| -------------------- | ------: |
+| Web application      | `50701` |
+| REST API             | `50700` |
+| PostgreSQL           |  `5437` |
+| Redis                |  `6384` |
 | SeaweedFS S3 gateway | `50702` |
-| SeaweedFS filer UI | `50703` |
+| SeaweedFS filer UI   | `50703` |
 
 See [Deployment](docs/DEPLOYMENT.md) for domains, TLS, provider tuning,
 backups, and production operation.
@@ -165,6 +182,7 @@ bunx --package @hiai-gg/docsmint docsmint read <document-id>
 bunx --package @hiai-gg/docsmint docsmint create \
   --title "Release notes" --content "# Version 0.2.9"
 ```
+
 Credentials can also be supplied through `HIAI_DOCS_URL` and
 `HIAI_DOCS_API_KEY`. See the [CLI guide](packages/cli/README.md) for every
 command and configuration precedence.
@@ -188,11 +206,13 @@ snapshots, history, and export as MCP tools.
   }
 }
 ```
+
 Run the server directly to verify the installation:
 
 ```bash
 bunx --package @hiai-gg/docsmint docsmint-mcp
 ```
+
 The server uses stdio and works with MCP-capable clients such as Claude
 Desktop, Cursor, and coding agents that accept standard MCP configuration. See
 the [MCP guide](packages/mcp-server/README.md) for its ten tools and routes.
@@ -211,22 +231,24 @@ the CLI, SDK, or REST API.
 ```bash
 bun add @hiai-gg/docsmint
 ```
+
 ```ts
-import { DocsClient } from "@hiai-gg/docsmint";
+import { DocsClient } from '@hiai-gg/docsmint';
 
 const docs = new DocsClient({
-  baseUrl: "http://localhost:50700",
+  baseUrl: 'http://localhost:50700',
   apiKey: process.env.HIAI_DOCS_API_KEY,
 });
 
 const created = await docs.createDoc({
-  title: "Meeting notes",
-  content: "# Agenda",
+  title: 'Meeting notes',
+  content: '# Agenda',
 });
 
-const results = await docs.search("what did we decide?");
+const results = await docs.search('what did we decide?');
 console.log(created.id, results.items);
 ```
+
 The SDK is a typed `fetch` client with retries for transient failures. See the
 [SDK reference](packages/sdk/README.md) and [REST API](docs/API.md).
 
@@ -234,11 +256,11 @@ The SDK is a typed `fetch` client with retries for transient failures. See the
 
 Create and revoke integration keys from **Settings → API**.
 
-| Credential | Intended use | Access |
-|---|---|---|
-| Global API key | Trusted owner-wide CLI, MCP, SDK, or service | All owner content |
-| Category key | Least-privilege agent or product integration | One category with selected permissions |
-| Operator key | Administration and reindex operations | `/api/admin/*` only |
+| Credential     | Intended use                                 | Access                                 |
+| -------------- | -------------------------------------------- | -------------------------------------- |
+| Global API key | Trusted owner-wide CLI, MCP, SDK, or service | All owner content                      |
+| Category key   | Least-privilege agent or product integration | One category with selected permissions |
+| Operator key   | Administration and reindex operations        | `/api/admin/*` only                    |
 
 Category permissions are explicit and non-hierarchical:
 
@@ -263,6 +285,7 @@ packages/cli/      Terminal client
 packages/mcp-server/  MCP stdio server
 postgres/          PostgreSQL image with vector and graph extensions
 ```
+
 The Docker deployment runs:
 
 - **Web** — document editor, folders, categories, sharing, settings, and search;
@@ -307,13 +330,13 @@ For pipeline internals and tuning, see [Architecture](docs/ARCHITECTURE.md) and
 DocsMint overlaps with several excellent open-source knowledge tools, but its
 focus is a compact knowledge runtime shared equally by humans and agents.
 
-| Project | Primary strength | Difference from DocsMint |
-|---|---|---|
-| [Outline](https://github.com/outline/outline) | Polished team wiki and collaboration | DocsMint emphasizes built-in retrieval, GraphRAG, scoped agent access, CLI, and MCP |
-| [Docmost](https://github.com/docmost/docmost) | Collaborative wiki and real-time editing | DocsMint centers automatic embeddings and agent-facing integration surfaces |
-| [AppFlowy](https://github.com/AppFlowy-IO/AppFlowy) | Broad local-first productivity workspace | DocsMint is narrower: a self-hosted document and retrieval service |
-| [AnythingLLM](https://github.com/Mintplex-Labs/anything-llm) | Chat-oriented RAG over imported sources | DocsMint starts with the editable knowledge base and exposes it to many clients |
-| [Danswer](https://github.com/danswer-ai/danswer) / Onyx | Enterprise search across external connectors | DocsMint owns and edits its native corpus rather than primarily indexing other systems |
+| Project                                                      | Primary strength                             | Difference from DocsMint                                                               |
+| ------------------------------------------------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| [Outline](https://github.com/outline/outline)                | Polished team wiki and collaboration         | DocsMint emphasizes built-in retrieval, GraphRAG, scoped agent access, CLI, and MCP    |
+| [Docmost](https://github.com/docmost/docmost)                | Collaborative wiki and real-time editing     | DocsMint centers automatic embeddings and agent-facing integration surfaces            |
+| [AppFlowy](https://github.com/AppFlowy-IO/AppFlowy)          | Broad local-first productivity workspace     | DocsMint is narrower: a self-hosted document and retrieval service                     |
+| [AnythingLLM](https://github.com/Mintplex-Labs/anything-llm) | Chat-oriented RAG over imported sources      | DocsMint starts with the editable knowledge base and exposes it to many clients        |
+| [Danswer](https://github.com/danswer-ai/danswer) / Onyx      | Enterprise search across external connectors | DocsMint owns and edits its native corpus rather than primarily indexing other systems |
 
 This is a product-positioning summary, not a claim that every listed project
 lacks a feature. Check each project's current documentation when choosing a
@@ -340,6 +363,7 @@ bun run typecheck
 bun run test
 bun run build
 ```
+
 Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Please
 report vulnerabilities through [SECURITY.md](SECURITY.md), not a public issue.
 

package/dist/backend/index.js

@@ -227119,7 +227119,9 @@ var listQuerySchema2 = exports_external2.object({
 var cursorListQuerySchema = exports_external2.object({
   categoryId: exports_external2.string().uuid().optional(),
   cursor: exports_external2.string().min(1).optional(),
-  limit: exports_external2.coerce.number().int().min(1).max(100).default(50)
+  limit: exports_external2.coerce.number().int().min(1).max(100).default(50),
+  sortBy: exports_external2.enum(["title", "category", "folder", "updated"]).default("updated"),
+  sortOrder: exports_external2.enum(["asc", "desc"]).default("desc")
 });
 function cursorScopeHash(input) {
   return Buffer.from(new Bun.CryptoHasher("sha256").update(input).digest("hex"), "utf8").toString("base64url");
@@ -227134,7 +227136,7 @@ function decodeDocumentCursor(value, expectedScopeHash) {
   if (!cursor || typeof cursor !== "object")
     throw new Error("Malformed cursor");
   const candidate = cursor;
-  if (candidate.v !== 1 || typeof candidate.updatedAt !== "string" || Number.isNaN(Date.parse(candidate.updatedAt)) || typeof candidate.id !== "string" || typeof candidate.scopeHash !== "string" || candidate.scopeHash !== expectedScopeHash) {
+  if (candidate.v !== 2 || !["title", "category", "folder", "updated"].includes(String(candidate.sortBy)) || !["asc", "desc"].includes(String(candidate.sortOrder)) || candidate.value !== null && typeof candidate.value !== "string" || typeof candidate.id !== "string" || typeof candidate.scopeHash !== "string" || candidate.scopeHash !== expectedScopeHash) {
     throw new Error("Cursor does not match this listing scope");
   }
   return candidate;
@@ -227378,12 +227380,20 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
     set2.status = 400;
     return { error: "Invalid query", details: parsed.error.flatten() };
   }
-  const { categoryId, cursor: encodedCursor, limit } = parsed.data;
+  const {
+    categoryId,
+    cursor: encodedCursor,
+    limit,
+    sortBy,
+    sortOrder
+  } = parsed.data;
   const effectiveCategoryId = access.restricted ? access.categoryId ?? categoryId : categoryId;
   const scopeHash = cursorScopeHash(JSON.stringify({
     workspaceId: ctx.workspaceId ?? null,
     actorUserId: access.userId,
-    categoryId: effectiveCategoryId ?? null
+    categoryId: effectiveCategoryId ?? null,
+    sortBy,
+    sortOrder
   }));
   let cursor;
   if (encodedCursor) {
@@ -227396,31 +227406,54 @@ var documentRoutes = new Elysia({ prefix: "/api" }).get("/documents", async ({ q
       };
     }
   }
+  const sortValue = sortBy === "title" ? sql`lower(${documents.title})` : sortBy === "category" ? sql`lower(${categories.name})` : sortBy === "folder" ? sql`lower(${folders.name})` : sql`${documents.updatedAt}`;
   const conditions2 = [
     tenantOwnerCondition(documents.ownerId, documents.workspaceId, ctx),
     isNull(documents.deletedAt),
-    ...effectiveCategoryId ? [eq(documents.categoryId, effectiveCategoryId)] : [],
-    ...cursor ? [
-      or(lt(documents.updatedAt, new Date(cursor.updatedAt)), and(eq(documents.updatedAt, new Date(cursor.updatedAt)), lt(documents.id, cursor.id)))
-    ] : []
+    ...effectiveCategoryId ? [eq(documents.categoryId, effectiveCategoryId)] : []
   ];
+  if (cursor) {
+    const idAfter = sortOrder === "asc" ? gt(documents.id, cursor.id) : lt(documents.id, cursor.id);
+    if (sortBy === "updated" && cursor.value) {
+      const cursorDate = new Date(cursor.value);
+      const valueAfter = sortOrder === "asc" ? gt(documents.updatedAt, cursorDate) : lt(documents.updatedAt, cursorDate);
+      const cursorCondition = or(valueAfter, and(eq(documents.updatedAt, cursorDate), idAfter));
+      if (cursorCondition)
+        conditions2.push(cursorCondition);
+    } else if (cursor.value === null) {
+      const cursorCondition = and(isNull(sortValue), idAfter);
+      if (cursorCondition)
+        conditions2.push(cursorCondition);
+    } else {
+      const valueAfter = sortOrder === "asc" ? gt(sortValue, cursor.value) : lt(sortValue, cursor.value);
+      const cursorCondition = or(valueAfter, and(eq(sortValue, cursor.value), idAfter), isNull(sortValue));
+      if (cursorCondition)
+        conditions2.push(cursorCondition);
+    }
+  }
   try {
     const rows = await withTenant(ctx, (tx) => tx.select({
       id: documents.id,
       title: documents.title,
       content: sql`LEFT(${documents.content}, 200)`.as("content"),
       folderId: documents.folderId,
+      folderName: folders.name,
+      categoryId: documents.categoryId,
+      categoryName: categories.name,
       createdAt: documents.createdAt,
       updatedAt: documents.updatedAt
-    }).from(documents).where(and(...conditions2)).orderBy(desc(documents.updatedAt), desc(documents.id)).limit(limit + 1));
+    }).from(documents).leftJoin(folders, eq(folders.id, documents.folderId)).leftJoin(categories, eq(categories.id, documents.categoryId)).where(and(...conditions2)).orderBy(sortOrder === "asc" ? sql`${sortValue} asc nulls last` : sql`${sortValue} desc nulls last`, sortOrder === "asc" ? asc(documents.id) : desc(documents.id)).limit(limit + 1));
     const hasMore = rows.length > limit;
     const page = rows.slice(0, limit);
     const last2 = page.at(-1);
+    const lastValue = last2 ? sortBy === "title" ? last2.title.toLocaleLowerCase() : sortBy === "category" ? last2.categoryName?.toLocaleLowerCase() ?? null : sortBy === "folder" ? last2.folderName?.toLocaleLowerCase() ?? null : new Date(last2.updatedAt).toISOString() : null;
     return {
       items: await withTags(ctx, page),
       nextCursor: hasMore && last2 ? encodeDocumentCursor({
-        v: 1,
-        updatedAt: new Date(last2.updatedAt).toISOString(),
+        v: 2,
+        sortBy,
+        sortOrder,
+        value: lastValue,
         id: last2.id,
         scopeHash
       }) : null
@@ -234286,7 +234319,7 @@ var swaggerConfig = {
     },
     info: {
       title: "DocsMint API",
-      version: "0.5.10",
+      version: "0.6.0",
       description: "Self-hosted AI-first documentation platform. Full-text + semantic search, version history, sharing, and folder organization.",
       contact: { name: "HiAi-gg", url: "https://github.com/HiAi-gg/docsmint" },
       license: {

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, DocsDocumentListResponse, DocsDocumentCursorPage, DocsDocumentPipeline, 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, DocsCategoryInput, DocsCategoryUpdate, DocsDocument, DocsDocumentCreateInput, DocsDocumentCursorPage, DocsDocumentListResponse, DocsDocumentPipeline, 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 hiai-docs API, e.g. `http://localhost:50700`. */
     baseUrl: string;
@@ -76,6 +76,8 @@ export declare class DocsClient {
         categoryId?: string;
         cursor?: string;
         limit?: number;
+        sortBy?: import("./types").DocsDocumentSortField;
+        sortOrder?: import("./types").DocsSortOrder;
     }, context?: DocsRequestContext): Promise<DocsDocumentCursorPage>;
     duplicateDoc(id: string, context?: DocsRequestContext): Promise<DocsDocument>;
     getDocumentPipeline(id: string, context?: DocsRequestContext): Promise<DocsDocumentPipeline>;

package/dist/client.js

@@ -112,6 +112,8 @@ export class DocsClient {
                 categoryId: options.categoryId,
                 cursor: options.cursor,
                 limit: options.limit,
+                sortBy: options.sortBy,
+                sortOrder: options.sortOrder,
             }),
         }, context);
     }