@vellumai/assistant 0.12.2-dev.202609211115.1844039 → 0.12.2-dev.202609211515.9bea579

package/openapi.yaml

@@ -12949,6 +12949,62 @@ paths:
               schema:
                 type: string
                 format: binary
+  /v1/documents/create:
+    post:
+      operationId: documents_create_post
+      summary: Create a document
+      description: Create an empty document owned by a conversation and return it with its new surface ID.
+      tags:
+        - documents
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                conversationId:
+                  type: string
+                  description: Owning conversation
+                title:
+                  description: Document title. Defaults to "Untitled Document".
+                  type: string
+              required:
+                - conversationId
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  surfaceId:
+                    type: string
+                  conversationId:
+                    type: string
+                  title:
+                    type: string
+                  content:
+                    type: string
+                  wordCount:
+                    type: number
+                  createdAt:
+                    type: number
+                  updatedAt:
+                    type: number
+                required:
+                  - success
+                  - surfaceId
+                  - conversationId
+                  - title
+                  - content
+                  - wordCount
+                  - createdAt
+                  - updatedAt
+                additionalProperties: false
   /v1/domain/register:
     post:
       operationId: domain_register_post

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-dev.202609211115.1844039",
+  "version": "0.12.2-dev.202609211515.9bea579",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/document-create-route.test.ts

@@ -0,0 +1,88 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+
+import {
+  DEFAULT_DOCUMENT_TITLE,
+  getDocumentsForConversation,
+} from "../documents/document-store.js";
+import { createConversation } from "../persistence/conversation-crud.js";
+import { getDb } from "../persistence/db-connection.js";
+import { initializeDb } from "../persistence/db-init.js";
+import { ROUTES as DOCUMENT_ROUTES } from "../runtime/routes/documents-routes.js";
+import type { RouteDefinition } from "../runtime/routes/types.js";
+import { resetDbForTesting } from "./db-test-helpers.js";
+
+await initializeDb();
+
+const CONVERSATION_ID = "conv-doc-create";
+
+async function create(body: Record<string, unknown>): Promise<unknown> {
+  const route = DOCUMENT_ROUTES.find(
+    (r: RouteDefinition) => r.operationId === "createDocument",
+  )!;
+  return await route.handler({ body });
+}
+
+beforeEach(() => {
+  const db = getDb();
+  db.run("DELETE FROM document_conversations");
+  db.run("DELETE FROM documents");
+  db.run("DELETE FROM conversations");
+  createConversation({ id: CONVERSATION_ID });
+});
+
+afterAll(() => {
+  resetDbForTesting();
+});
+
+describe("createDocument route", () => {
+  test("creates an empty document under a new surface ID and returns it", async () => {
+    const result = await create({
+      conversationId: CONVERSATION_ID,
+      title: "Trip plan",
+    });
+
+    expect(result).toMatchObject({
+      success: true,
+      conversationId: CONVERSATION_ID,
+      title: "Trip plan",
+      content: "",
+      wordCount: 0,
+    });
+    const { surfaceId } = result as { surfaceId: string };
+    expect(surfaceId).toMatch(/^doc-[0-9a-f-]{36}$/);
+    expect(
+      getDocumentsForConversation(CONVERSATION_ID).map((d) => d.surfaceId),
+    ).toEqual([surfaceId]);
+  });
+
+  test("a missing or blank title falls back to the default", async () => {
+    await expect(
+      create({ conversationId: CONVERSATION_ID }),
+    ).resolves.toMatchObject({ title: DEFAULT_DOCUMENT_TITLE });
+    await expect(
+      create({ conversationId: CONVERSATION_ID, title: "   " }),
+    ).resolves.toMatchObject({ title: DEFAULT_DOCUMENT_TITLE });
+  });
+
+  test("each create mints a distinct document", async () => {
+    const first = (await create({ conversationId: CONVERSATION_ID })) as {
+      surfaceId: string;
+    };
+    const second = (await create({ conversationId: CONVERSATION_ID })) as {
+      surfaceId: string;
+    };
+
+    expect(first.surfaceId).not.toBe(second.surfaceId);
+    expect(getDocumentsForConversation(CONVERSATION_ID)).toHaveLength(2);
+  });
+
+  test("rejects a request without a conversation", async () => {
+    await expect(create({})).rejects.toThrow(/conversationId is required/);
+  });
+
+  test("rejects a conversation that does not exist", async () => {
+    await expect(create({ conversationId: "conv-missing" })).rejects.toThrow(
+      /Conversation not found/,
+    );
+  });
+});

package/src/__tests__/document-sync-tags.test.ts

@@ -203,6 +203,22 @@ describe("document write routes publish documents:list", () => {
     });
   });
 
+  test("creating a document publishes with the caller's client id", async () => {
+    const events = await captureSyncEvents(() =>
+      invoke("createDocument", {
+        body: { conversationId: CONVERSATION_ID },
+        headers: { "x-vellum-client-id": "client-abc" },
+      }),
+    );
+
+    expect(events).toHaveLength(1);
+    expect(events[0].message).toMatchObject({
+      type: "sync_changed",
+      tags: [SYNC_TAGS.documentsList],
+      originClientId: "client-abc",
+    });
+  });
+
   test("linking a document to a conversation publishes", async () => {
     await saveViaRoute();
 
@@ -251,6 +267,17 @@ describe("document routes that change nothing the list shows stay silent", () =>
     expect(events).toEqual([]);
   });
 
+  test("a create for a conversation that does not exist publishes nothing", async () => {
+    const events = await captureSyncEvents(async () => {
+      await expect(
+        invoke("createDocument", {
+          body: { conversationId: MISSING_CONVERSATION_ID },
+        }),
+      ).rejects.toThrow(/Conversation not found/);
+    });
+    expect(events).toEqual([]);
+  });
+
   test("a link to a document that does not exist publishes nothing", async () => {
     const events = await captureSyncEvents(async () => {
       await expect(

package/src/documents/document-store.ts

@@ -5,6 +5,8 @@
  * background jobs (e.g. proactive artifact generation) can persist documents
  * without going through the HTTP layer.
  */
+import { randomUUID } from "node:crypto";
+
 import { rawAll, rawGet, rawRun } from "../persistence/raw-query.js";
 import { getLogger } from "../util/logger.js";
 
@@ -456,6 +458,27 @@ export function saveDocument(params: {
   }
 }
 
+export const DEFAULT_DOCUMENT_TITLE = "Untitled Document";
+
+/**
+ * Create a new document owned by `conversationId` under a freshly minted
+ * surface ID. A missing or empty title falls back to `DEFAULT_DOCUMENT_TITLE`.
+ */
+export function createDocument(params: {
+  conversationId: string;
+  title?: string;
+  content?: string;
+}): ReturnType<typeof saveDocument> {
+  const content = params.content ?? "";
+  return saveDocument({
+    surfaceId: `doc-${randomUUID()}`,
+    conversationId: params.conversationId,
+    title: params.title || DEFAULT_DOCUMENT_TITLE,
+    content,
+    wordCount: countWords(content),
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Find-and-replace
 // ---------------------------------------------------------------------------

package/src/runtime/routes/documents-routes.ts

@@ -8,10 +8,13 @@ import { z } from "zod";
 
 import {
   addDocumentConversation,
+  createDocument,
+  DEFAULT_DOCUMENT_TITLE,
   getDocumentById,
   getDocumentsForConversation,
   saveDocument,
 } from "../../documents/document-store.js";
+import { getConversation } from "../../persistence/conversation-crud.js";
 import { rawAll } from "../../persistence/raw-query.js";
 import { getLogger } from "../../util/logger.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
@@ -214,6 +217,54 @@ export const ROUTES: RouteDefinition[] = [
     },
   },
 
+  {
+    operationId: "createDocument",
+    endpoint: "documents/create",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Create a document",
+    description:
+      "Create an empty document owned by a conversation and return it with its new surface ID.",
+    tags: ["documents"],
+    requestBody: z.object({
+      conversationId: z.string().describe("Owning conversation"),
+      title: z
+        .string()
+        .optional()
+        .describe(`Document title. Defaults to "${DEFAULT_DOCUMENT_TITLE}".`),
+    }),
+    responseBody: documentPayloadSchema,
+    handler: ({ body, headers }) => {
+      const { conversationId, title } = (body ?? {}) as {
+        conversationId?: string;
+        title?: string;
+      };
+      if (!conversationId || typeof conversationId !== "string") {
+        throw new BadRequestError("conversationId is required");
+      }
+      if (title !== undefined && typeof title !== "string") {
+        throw new BadRequestError("title must be a string");
+      }
+      if (!getConversation(conversationId)) {
+        throw new NotFoundError("Conversation not found");
+      }
+
+      const result = createDocument({ conversationId, title: title?.trim() });
+      if (!result.success) {
+        throw new InternalError(result.error);
+      }
+      const doc = getDocumentById(result.surfaceId);
+      if (!doc) {
+        throw new InternalError("Created document could not be read back");
+      }
+      publishDocumentsChanged(getOriginClientId(headers));
+      return { success: true, ...doc };
+    },
+  },
+
   {
     operationId: "linkDocumentConversation",
     endpoint: "documents/:id/conversations",

package/src/tools/document/document-tool.ts

@@ -1,9 +1,9 @@
-import { randomUUID } from "node:crypto";
-
 import { z } from "zod";
 
 import {
   addDocumentConversation,
+  createDocument,
+  DEFAULT_DOCUMENT_TITLE,
   deleteDocument,
   findInDocument,
   findRecentEmptyDocumentByTitle,
@@ -11,7 +11,6 @@ import {
   getDocumentsForConversation,
   isDocumentAssociatedWithConversation,
   replaceInDocument,
-  saveDocument,
   searchDocumentsByTitle,
   updateDocumentContent,
 } from "../../documents/document-store.js";
@@ -283,7 +282,7 @@ export function executeDocumentCreate(
     return invalidToolInputResult("document_create", parsedInput.error);
   }
   throwIfCancelled(context);
-  const title = parsedInput.data.title || "Untitled Document";
+  const title = parsedInput.data.title || DEFAULT_DOCUMENT_TITLE;
   const initialContent = parsedInput.data.initial_content || "";
 
   const reused = maybeReuseEmptyDocument(title, initialContent, context);
@@ -291,21 +290,21 @@ export function executeDocumentCreate(
     return reused;
   }
 
-  const surfaceId = `doc-${randomUUID()}`;
-
   // Persist the document so any client (web or macOS) can fetch it via
   // GET /v1/documents/:id. The macOS client may later update the row
   // via document_save; ON CONFLICT DO UPDATE handles that.
-  const wordCount = initialContent
-    .split(/\s+/)
-    .filter((w) => w.length > 0).length;
-  saveDocument({
-    surfaceId,
+  const created = createDocument({
     conversationId: context.conversationId,
     title,
     content: initialContent,
-    wordCount,
   });
+  if (!created.success) {
+    return {
+      content: JSON.stringify({ success: false, error: created.error }),
+      isError: true,
+    };
+  }
+  const { surfaceId } = created;
 
   // Send document_editor_show message to open the built-in RTE
   if (context.sendToClient) {