@bergetai/odoo-cli 0.7.2 → 0.8.1

package/README.md

@@ -40,7 +40,9 @@ odoo project tasks list --project "Content Pipeline" --open
 odoo project tasks show 850
 odoo documents tree --count
 odoo documents records list --folder "Product Backlog" --limit 20
+odoo documents records list --folder "Projects > Product Backlog"  # nested path
 odoo documents records show 25
+odoo documents records download 25 --out ./spec.pdf
 
 # Mutations (support --dry-run)
 odoo crm leads create --name "New lead" --email info@example.com
@@ -78,7 +80,7 @@ Note: `odoo --version` prints the CLI's own version; `odoo version` queries the
 - Read-only Helpdesk surface (`helpdesk tickets list/show`) — `--open`/`--closed` via stage `fold`, strict team-scoped stage resolution, module-not-installed error (exit 4)
 - Read-only Project surface (`project list/show`) — `--user` (project manager) and `--tag` filters, archived projects excluded by default, module-not-installed error (exit 4)
 - Read-only Project task surface (`project tasks list/show`) — `--project` (required on list, resolved by name or id), project-scoped `--stage`, `--assignee` (many2many `user_ids`), `--tag`, `--priority` (0/Low, 1/High), `--open`/`--closed` via the task's `is_closed` flag, `--domain`/`--filter`, table/JSON output with `search_count` envelope, module-not-installed error (exit 4)
-- Documents surface (`documents`) — `tree` (hierarchical folder listing with `--count`/`--depth`/`--folder`), `records list/show` (folders excluded by default, `--type folder|binary|url|all`, `--folder`/`--owner`/`--partner`/`--tag`), `folders list`, `records create` (folder via `--folder-type folder`, link via `--link <url>`), `records update` (move via `--folder`), `records delete`, and `upload` (local file → base64 `datas`, MIME guessed from extension, `--dry-run` previews without sending bytes). Folders are `documents.document` rows with `type='folder'`; the hierarchy is `folder_id`. Module-not-installed error (exit 4)
+- Documents surface (`documents`) — `tree` (hierarchical folder listing with `--count`/`--depth`/`--folder`), `records list/show` (folders excluded by default, `--type folder|binary|url|all`, `--folder`/`--owner`/`--partner`/`--tag`), `folders list`, `records create` (folder via `--folder-type folder`, link via `--link <url>`), `records update` (move via `--folder`), `records delete`, `upload` (local file → base64 `datas`, MIME guessed from extension, `--dry-run` previews without sending bytes), and `records download <id>` (binary document → local file, `--out <path>`/`--force`, `--out -` streams to stdout). Everywhere a `--folder` is accepted, folders resolve by name, numeric id, or nested `'Parent > Child'` path (segments resolved within their parent, which disambiguates repeated folder names). Folders are `documents.document` rows with `type='folder'`; the hierarchy is `folder_id`. Module-not-installed error (exit 4)
 - Writes (`create`, `update`, `delete`) — single-call atomic batch `write`, client-side no-op diffing, delete convergence with `skipped` ids, post-failure "record may have been created" hint on `create`
 - `--dry-run` for all mutations — full validation, resolution, and before/after diffs without mutating
 - Internal notes (`add-note`) — creates internal Log Notes only (subtype_id=2, message_type=comment), **NEVER sends email to customer**, by design prevents accidental customer communication. Optional `--author <email|name|id>` attributes the note to the partner who actually sent the logged message (resolved via `res.partner`; ambiguous matches list candidates and never guess)

package/dist/cli.js

@@ -7,7 +7,7 @@ import { ticketsCreateCommand, ticketsDeleteCommand, ticketsListCommand, tickets
 import { addNoteCommand, deleteMessageCommand, listMessagesCommand, updateMessageCommand, } from "./commands/notes.js";
 import { activitiesListCommand, activityDoneCommand, activityUpdateCommand, scheduleCommand, } from "./commands/activities.js";
 import { createTaskCommand, projectListCommand, projectShowCommand, tasksListCommand, tasksShowCommand, } from "./commands/project.js";
-import { documentsDocuments, documentsListCommand, foldersListCommand, documentsShowCommand, documentsCreateCommand, documentsUpdateCommand, documentsDeleteCommand, treeCommand, uploadCommand, } from "./commands/documents.js";
+import { documentsDocuments, documentsListCommand, foldersListCommand, documentsShowCommand, documentsCreateCommand, documentsUpdateCommand, documentsDeleteCommand, treeCommand, uploadCommand, downloadCommand, } from "./commands/documents.js";
 import { versionCommand } from "./commands/version.js";
 import { partnersCreateCommand, partnersDeleteCommand, partnersListCommand, partnersShowCommand, partnersUpdateCommand, resPartner, } from "./commands/partners.js";
 import { CliError } from "./errors.js";
@@ -140,6 +140,7 @@ Examples:
         .option("--body <text>", "note body (HTML allowed)")
         .option("--body-file <path>", "read note body from file ('-' for stdin)")
         .option("--author <email|name|id>", "note author (res.partner; default: your own partner)")
+        .option("--attach <path>", "attach a file to the note; repeatable", collect, [])
         .addHelpText("after", `
 IMPORTANT: This command creates INTERNAL notes only. These notes:
   • Are NEVER sent to the customer via email
@@ -153,7 +154,8 @@ Examples:
   $ odoo crm records add-note 338 --body "Internal note text"
   $ odoo crm records add-note 338 --body-file note.md
   $ cat note.md | odoo crm records add-note 338 --body-file -
-  $ odoo crm records add-note 338 --body "Kundens svar: ..." --author andreas@berget.ai`)
+  $ odoo crm records add-note 338 --body "Kundens svar: ..." --author andreas@berget.ai
+  $ odoo crm records add-note 338 --body "Mötesanteckningar" --attach whiteboard.png --attach offert.pdf`)
         .action(async (id, opts) => {
         await run((g) => addNoteCommand(id, opts, g, "crm.lead"), program);
     });
@@ -394,6 +396,7 @@ the raw form.`)
         .option("--body <text>", "note body (HTML allowed)")
         .option("--body-file <path>", "read note body from file ('-' for stdin)")
         .option("--author <email|name|id>", "note author (res.partner; default: your own partner)")
+        .option("--attach <path>", "attach a file to the note; repeatable", collect, [])
         .addHelpText("after", `
 IMPORTANT: This command creates INTERNAL notes only. These notes:
   • Are NEVER sent to the customer via email
@@ -573,7 +576,7 @@ Examples:
         .command("list")
         .description("search and list documents (folders excluded by default)")
         .option("--type <type>", "record type: document (default), folder, or all")
-        .option("--folder <name|id>", "only records directly in this folder (resolved by name)")
+        .option("--folder <name|id|path>", "only records directly in this folder (name, id, or 'Parent > Child' path)")
         .option("--owner <name|id>", "filter by owner (login, email, or name)")
         .option("--partner <name|id>", "filter by linked contact")
         .option("--tag <name|id>", "filter by tag; repeatable, AND-ed", collect, [])
@@ -595,6 +598,15 @@ Examples:
         .action(async (id, opts) => {
         await run((g) => documentsShowCommand(id, opts, g), program);
     });
+    records
+        .command("download")
+        .description("download a document's file content to disk")
+        .argument("<id>", "record id")
+        .option("--out <path>", "output path (default: document name in cwd; '-' for stdout)")
+        .option("--force", "overwrite an existing output file")
+        .action(async (id, opts) => {
+        await run((g) => downloadCommand(id, opts, g), program);
+    });
     addMutationFlags(records
         .command("create")
         .description("create a folder or URL link (preview with --dry-run; upload files via 'documents upload')"), documentsDocuments).action(async (opts) => {
@@ -628,7 +640,7 @@ Examples:
     documents
         .command("tree")
         .description("print the folder tree with document counts")
-        .option("--folder <name|id>", "start from this folder (default: roots)")
+        .option("--folder <name|id|path>", "start from this folder (default: roots; name, id, or 'Parent > Child' path)")
         .option("--depth <n>", "max depth", "10")
         .option("--count", "show the number of documents per folder")
         .action(async (opts) => {
@@ -639,7 +651,7 @@ Examples:
         .description("upload a local file as a document (preview with --dry-run)")
         .requiredOption("--file <path>", "local file path ('-' for stdin)")
         .option("--name <name>", "document name (default: file basename)")
-        .option("--folder <name|id>", "target folder (resolved by name)")
+        .option("--folder <name|id|path>", "target folder (name, id, or 'Parent > Child' path)")
         .option("--owner <name|id>", "owner (login, email, or name)")
         .option("--partner <name|id>", "linked contact")
         .option("--tag <name|id>", "tag; repeatable, AND-ed", collect, [])

package/dist/commands/documents.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { readFile, stat } from "node:fs/promises";
+import { readFile, stat, writeFile } from "node:fs/promises";
 import { basename, extname, resolve } from "node:path";
-import { usageError } from "../errors.js";
+import { notFoundError, usageError } from "../errors.js";
 import { ModelFields, resolveReference } from "../model.js";
 import { createCommand, deleteCommand, updateCommand, } from "../mutation.js";
 import { colorEnabled, printJson } from "../output.js";
@@ -19,10 +19,10 @@ const documentsMutation = {
             requiredOnCreate: true,
         },
         {
-            flags: "--folder <name|id>",
+            flags: "--folder <name|id|path>",
             option: "folder",
             field: "folder_id",
-            help: "Parent folder",
+            help: "Parent folder (name, id, or 'Parent > Child' path)",
             reference: { model: "documents.document", label: "folder" },
         },
         {
@@ -391,12 +391,88 @@ export async function uploadCommand(opts, globals) {
     const line = `Uploaded documents.document ${id} (${name})`;
     process.stdout.write((color ? `\x1b[32m${line}\x1b[0m` : line) + "\n");
 }
-/** Resolve a folder by name or id (must be type=folder). */
+export async function downloadCommand(idArg, opts, globals) {
+    const client = await authenticatedClient(globals);
+    await ModelFields.load(client, "documents.document"); // module-installed check
+    if (!/^\d+$/.test(idArg)) {
+        throw usageError(`invalid document id ${JSON.stringify(idArg)}`, "expected a numeric id (see 'documents records list')");
+    }
+    const id = Number(idArg);
+    const rows = (await client.executeKw("documents.document", "read", [
+        [id],
+        ["name", "type", "datas", "mimetype"],
+    ]));
+    if (rows.length === 0) {
+        throw notFoundError("reference_not_found", `no document with id ${id}`);
+    }
+    const rec = rows[0];
+    if (rec.type === "folder") {
+        throw usageError(`document ${id} "${rec.name}" is a folder`, "download expects a binary document (folders excluded by default in 'records list')");
+    }
+    if (rec.type !== "binary" || rec.datas === false || rec.datas === "") {
+        throw usageError(`document ${id} "${rec.name}" has no file content (type: ${rec.type})`);
+    }
+    const buffer = Buffer.from(rec.datas, "base64");
+    // '--out -' streams raw bytes to stdout (for piping).
+    if (opts.out === "-") {
+        process.stdout.write(buffer);
+        return;
+    }
+    const outPath = resolve(opts.out ?? rec.name);
+    try {
+        await stat(outPath);
+        if (!opts.force) {
+            throw usageError(`file already exists: ${outPath}`, "pass --force to overwrite");
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    await writeFile(outPath, buffer);
+    if (globals.json) {
+        printJson({
+            model: "documents.document",
+            action: "download",
+            id,
+            name: rec.name,
+            path: outPath,
+            file_size: buffer.length,
+            mimetype: rec.mimetype,
+        });
+        return;
+    }
+    const color = colorEnabled(false) && process.stdout.isTTY === true;
+    const line = `Downloaded documents.document ${id} → ${outPath} (${buffer.length} bytes)`;
+    process.stdout.write((color ? `\x1b[32m${line}\x1b[0m` : line) + "\n");
+}
+/**
+ * Resolve a folder by name, id, or "Parent > Child > ..." path
+ * (must be type=folder). Path segments are resolved within their parent,
+ * which disambiguates repeated folder names (e.g. per-customer subfolders).
+ */
 async function resolveFolderId(client, input) {
-    const resolved = await resolveReference(client, "documents.document", input, {
-        label: "folder",
-        domain: FOLDER_DOMAIN,
-    });
-    return resolved.id;
+    const segments = input
+        .split(">")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (segments.length <= 1) {
+        const resolved = await resolveReference(client, "documents.document", input, {
+            label: "folder",
+            domain: FOLDER_DOMAIN,
+        });
+        return resolved.id;
+    }
+    let parentId = false;
+    let id = 0;
+    for (const segment of segments) {
+        const resolved = await resolveReference(client, "documents.document", segment, {
+            label: parentId === false ? "root folder" : `folder under ${parentId}`,
+            domain: [...FOLDER_DOMAIN, ["folder_id", "=", parentId]],
+        });
+        id = resolved.id;
+        parentId = id;
+    }
+    return id;
 }
 export { formatTable, humanCell };

package/dist/commands/notes.js

@@ -24,6 +24,57 @@ async function buildClient(globals) {
     const timeoutMs = parseDurationMs(globals.timeout);
     return new OdooClient(config.url, config.db, config.username, config.apiKey, { timeoutMs, verbose: globals.verbose });
 }
+const MIME_BY_EXT = {
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+    ".doc": "application/msword",
+    ".xls": "application/vnd.ms-excel",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".zip": "application/zip",
+};
+/**
+ * Read files for --attach and prepare ir.attachment values. Attachments are
+ * linked to the note's mail.message (res_model="mail.message", res_id=note id)
+ * so they render on the message in the chatter — same as uploading via the UI.
+ */
+async function prepareAttachments(paths) {
+    const { readFile, stat } = await import("node:fs/promises");
+    const { basename, extname } = await import("node:path");
+    const prepared = [];
+    for (const p of paths) {
+        let fileStat;
+        try {
+            fileStat = await stat(p);
+        }
+        catch {
+            throw usageError(`attachment file not found: ${p}`, "check the --attach path");
+        }
+        if (!fileStat.isFile()) {
+            throw usageError(`not a regular file: ${p}`);
+        }
+        const buffer = await readFile(p);
+        prepared.push({
+            path: p,
+            name: basename(p),
+            mimetype: MIME_BY_EXT[extname(p).toLowerCase()] ?? "application/octet-stream",
+            size: fileStat.size,
+            datas: buffer.toString("base64"),
+        });
+    }
+    return prepared;
+}
 async function readBody(opts) {
     let body = opts.body;
     if (opts.bodyFile) {
@@ -50,6 +101,9 @@ export async function addNoteCommand(recordId, opts, globals, model) {
         throw usageError(`invalid ${spec.label} id: ${recordId}`, "provide a positive integer");
     }
     const body = await readBody(opts);
+    const attachments = opts.attach?.length
+        ? await prepareAttachments(opts.attach)
+        : [];
     const client = await buildClient(globals);
     // Verify the record exists
     const rows = (await client.executeKw(spec.model, "search_read", [[["id", "=", id]]], { fields: ["id", "name"], limit: 1 }));
@@ -100,6 +154,11 @@ export async function addNoteCommand(recordId, opts, globals, model) {
             author: author ? { id: author.id, name: author.name } : null,
             body_preview: body.substring(0, 100) + (body.length > 100 ? "..." : ""),
             body_length: body.length,
+            attachments: attachments.map((a) => ({
+                name: a.name,
+                mimetype: a.mimetype,
+                size: a.size,
+            })),
         };
         if (globals.json) {
             printJson(result);
@@ -113,12 +172,45 @@ export async function addNoteCommand(recordId, opts, globals, model) {
             }
             console.log(`  Body length: ${body.length} characters`);
             console.log(`  Body preview: ${result.body_preview}`);
+            for (const a of attachments) {
+                console.log(`  Attachment: ${a.name} (${a.mimetype}, ${a.size} bytes)`);
+            }
         }
         return;
     }
-    const noteId = (await client.executeKw("mail.message", "create", [
+    // NOTE: batch create returns a list of ids — unwrap the single id,
+    // otherwise res_id on attachments becomes a nested list and the
+    // server faults with "unhashable type: 'list'".
+    const noteIdRaw = (await client.executeKw("mail.message", "create", [
         [noteParams],
     ]));
+    const noteId = Array.isArray(noteIdRaw) ? noteIdRaw[0] : noteIdRaw;
+    // Upload attachments, linked to the note's message so they render on it
+    // in the chatter (same as attaching via the Odoo UI).
+    const createdAttachments = [];
+    for (const a of attachments) {
+        const attachmentIdRaw = (await client.executeKw("ir.attachment", "create", [
+            [
+                {
+                    name: a.name,
+                    mimetype: a.mimetype,
+                    datas: a.datas,
+                    res_model: "mail.message",
+                    res_id: noteId,
+                },
+            ],
+        ]));
+        const attachmentId = Array.isArray(attachmentIdRaw)
+            ? attachmentIdRaw[0]
+            : attachmentIdRaw;
+        // Link the attachment into the message's attachment_ids m2m — without
+        // this the file exists but never renders on the message in the chatter.
+        await client.executeKw("mail.message", "write", [
+            [noteId],
+            { attachment_ids: [[4, attachmentId]] },
+        ]);
+        createdAttachments.push({ id: attachmentId, name: a.name });
+    }
     const result = {
         note_id: noteId,
         model: spec.model,
@@ -127,6 +219,7 @@ export async function addNoteCommand(recordId, opts, globals, model) {
         note_type: "internal_log_note",
         email_sent: false,
         author: author ? { id: author.id, name: author.name } : null,
+        attachments: createdAttachments,
     };
     if (globals.json) {
         printJson(result);
@@ -138,6 +231,9 @@ export async function addNoteCommand(recordId, opts, globals, model) {
         if (author) {
             console.log(`  Author: ${author.name} (${author.id})`);
         }
+        for (const a of createdAttachments) {
+            console.log(`  Attachment: ${a.name} (ID: ${a.id})`);
+        }
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bergetai/odoo-cli",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "Agent-first CLI for the Odoo External API",
   "publishConfig": {
     "access": "public"