@bergetai/odoo-cli 0.3.0 → 0.3.2

package/README.md

@@ -31,6 +31,9 @@ odoo helpdesk tickets list --team Support --json
 odoo project list --json
 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 show 25
 
 # Mutations (support --dry-run)
 odoo crm leads create --name "New lead" --email info@example.com
@@ -52,6 +55,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)
 - 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

package/dist/cli.js

@@ -5,6 +5,7 @@ import { leadsCreateCommand, leadsDeleteCommand, leadsListCommand, leadsShowComm
 import { ticketsCreateCommand, ticketsDeleteCommand, ticketsListCommand, ticketsShowCommand, ticketsUpdateCommand, helpdeskTickets, } from "./commands/helpdesk.js";
 import { addNoteCommand, listMessagesCommand, } from "./commands/notes.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 { versionCommand } from "./commands/version.js";
 import { CliError } from "./errors.js";
 import { applyGlobalOptions, enforceTransportSecurity, DEFAULT_TIMEOUT, } from "./global-options.js";
@@ -328,6 +329,91 @@ Examples:
         .action(async (opts) => {
         await run((g) => createTaskCommand(opts, g), program);
     });
+    const documents = program
+        .command("documents")
+        .description("Documents app (documents.document, Enterprise)");
+    const records = documents
+        .command("records")
+        .description("files, links and folders");
+    records
+        .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("--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, [])
+        .option("--filter <f=v>", "equality filter; repeatable, AND-ed", collect, [])
+        .option("--domain <json>", "Odoo domain as a JSON array (mutually exclusive with --filter)")
+        .option("--fields <a,b,c>", "columns to display")
+        .option("--limit <n>", "max records (default: 50)", "50")
+        .option("--offset <n>", "skip the first n records", "0")
+        .option("--order <order>", 'sort order, e.g. "create_date desc"', undefined)
+        .action(async (opts) => {
+        await run((g) => documentsListCommand(opts, g), program);
+    });
+    records
+        .command("show")
+        .description("read one document or folder")
+        .argument("<id>", "record id")
+        .option("--fields <a,b,c>", "fields to display")
+        .option("--all-fields", "display every readable field")
+        .action(async (id, opts) => {
+        await run((g) => documentsShowCommand(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) => {
+        await run((g) => documentsCreateCommand(opts, g), program);
+    });
+    addMutationFlags(records
+        .command("update")
+        .description("update documents (preview with --dry-run)"), documentsDocuments)
+        .argument("<id...>", "record ids")
+        .action(async (ids, opts) => {
+        await run((g) => documentsUpdateCommand(ids, opts, g), program);
+    });
+    records
+        .command("delete")
+        .description("delete documents (preview with --dry-run; unknown ids are skipped)")
+        .argument("<id...>", "record ids")
+        .action(async (ids) => {
+        await run((g) => documentsDeleteCommand(ids, g), program);
+    });
+    const folders = documents.command("folders").description("folders");
+    folders
+        .command("list")
+        .description("list all folders")
+        .option("--fields <a,b,c>", "columns to display")
+        .option("--limit <n>", "max records (default: 50)", "50")
+        .option("--offset <n>", "skip the first n records", "0")
+        .option("--order <order>", 'sort order, e.g. "name asc"', undefined)
+        .action(async (opts) => {
+        await run((g) => foldersListCommand(opts, g), program);
+    });
+    documents
+        .command("tree")
+        .description("print the folder tree with document counts")
+        .option("--folder <name|id>", "start from this folder (default: roots)")
+        .option("--depth <n>", "max depth", "10")
+        .option("--count", "show the number of documents per folder")
+        .action(async (opts) => {
+        await run((g) => treeCommand(opts, g), program);
+    });
+    documents
+        .command("upload")
+        .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("--owner <name|id>", "owner (login, email, or name)")
+        .option("--partner <name|id>", "linked contact")
+        .option("--tag <name|id>", "tag; repeatable, AND-ed", collect, [])
+        .option("--description <text>", "description")
+        .option("--mimetype <type>", "MIME type (default: guessed from extension)")
+        .action(async (opts) => {
+        await run((g) => uploadCommand(opts, g), program);
+    });
     return program;
 }
 async function run(fn, program) {

package/dist/commands/crm.js

@@ -134,7 +134,24 @@ const crmLeadsMutation = {
             field: "description",
             help: "Notes",
         },
+        {
+            flags: "--lead-type <type>",
+            option: "leadType",
+            field: "x_studio_lead_type",
+            help: "Lead type: Inbound|Outbound|Not sure (default: Inbound)",
+            parse: (raw, flagName) => {
+                const v = raw.trim();
+                const valid = ["Inbound", "Outbound", "Not sure"];
+                if (!valid.includes(v)) {
+                    throw usageError(`invalid ${flagName} ${JSON.stringify(raw)}`, `expected one of: ${valid.join(", ")}`);
+                }
+                return v;
+            },
+        },
     ],
+    createDefaultValues: {
+        x_studio_lead_type: "Inbound",
+    },
 };
 export const crmLeads = {
     model: "crm.lead",

package/dist/commands/documents.js

@@ -0,0 +1,402 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+import { usageError } from "../errors.js";
+import { ModelFields, resolveReference } from "../model.js";
+import { createCommand, deleteCommand, updateCommand, } from "../mutation.js";
+import { colorEnabled, printJson } from "../output.js";
+import { authenticatedClient, listCommand, showCommand, } from "../resource.js";
+import { formatTable, humanCell } from "../table.js";
+const FOLDER_DOMAIN = [["type", "=", "folder"]];
+/** documents.document mutation flags (folders + binary files share the model). */
+const documentsMutation = {
+    flags: [
+        {
+            flags: "--name <name>",
+            option: "name",
+            field: "name",
+            help: "Document or folder name",
+            requiredOnCreate: true,
+        },
+        {
+            flags: "--folder <name|id>",
+            option: "folder",
+            field: "folder_id",
+            help: "Parent folder",
+            reference: { model: "documents.document", label: "folder" },
+        },
+        {
+            flags: "--owner <name|id>",
+            option: "owner",
+            field: "owner_id",
+            help: "Owner (login, email, or name)",
+            reference: {
+                model: "res.users",
+                label: "user",
+                searchFields: ["login", "email", "name"],
+            },
+        },
+        {
+            flags: "--partner <name|id>",
+            option: "partner",
+            field: "partner_id",
+            help: "Related partner",
+            reference: { model: "res.partner", label: "partner" },
+        },
+        {
+            flags: "--tag <name|id>",
+            option: "tag",
+            field: "tag_ids",
+            help: "Tag; repeatable, replaces all tags",
+            multi: true,
+            reference: { model: "documents.tag", label: "tag" },
+        },
+        {
+            flags: "--description <text>",
+            option: "description",
+            field: "description",
+            help: "Description",
+        },
+        {
+            flags: "--link <url>",
+            option: "link",
+            field: "url",
+            help: "External URL (creates a link document)",
+        },
+        {
+            flags: "--folder-type <folder>",
+            option: "folderType",
+            field: "type",
+            help: "Create a folder instead of a document (pass --folder-type folder)",
+            parse: (raw, flagName) => {
+                if (raw !== "folder") {
+                    throw usageError(`invalid ${flagName} value ${JSON.stringify(raw)}`, "expected: folder");
+                }
+                return "folder";
+            },
+        },
+    ],
+};
+export const documentsDocuments = {
+    model: "documents.document",
+    showCommand: "odoo documents records show",
+    defaultListFields: [
+        "id",
+        "name",
+        "type",
+        "folder_id",
+        "mimetype",
+        "file_size",
+        "owner_id",
+        "create_date",
+    ],
+    showExtraFields: [
+        "partner_id",
+        "tag_ids",
+        "description",
+        "url",
+        "access_internal",
+        "access_via_link",
+        "access_url",
+        "is_editable_attachment",
+        "handler",
+        "active",
+        "shortcut_document_id",
+        "write_date",
+    ],
+    resolutionHints: {
+        folder_id: "--folder",
+        owner_id: "--owner",
+        partner_id: "--partner",
+        tag_ids: "--tag",
+    },
+    priorityLabels: {},
+    pinnedDomain: [["type", "!=", "folder"]],
+    references: {
+        assignee: {
+            model: "res.users",
+            label: "user",
+            field: "owner_id",
+            searchFields: ["login", "email", "name"],
+        },
+        tag: { model: "documents.tag", label: "tag", field: "tag_ids" },
+    },
+    mutation: documentsMutation,
+    extraFilters: async (opts, client) => {
+        const o = opts;
+        const clauses = [];
+        if (o.folder !== undefined) {
+            clauses.push(["folder_id", "=", await resolveFolderId(client, o.folder)]);
+        }
+        if (o.type === "folder") {
+            clauses.push(["type", "=", "folder"]);
+        }
+        else if (o.type === "binary") {
+            clauses.push(["type", "=", "binary"]);
+        }
+        else if (o.type === "url") {
+            clauses.push(["type", "=", "url"]);
+        }
+        else if (o.type === "all") {
+            // no extra clause — but pinnedDomain excludes folders, so drop it
+            // (handled by caller clearing pinnedDomain)
+        }
+        return clauses;
+    },
+};
+/**
+ * List folders only (type = 'folder'). Same list engine, pinned domain
+ * flipped to folders-only.
+ */
+export const documentsFolders = {
+    ...documentsDocuments,
+    showCommand: "odoo documents folders show",
+    pinnedDomain: FOLDER_DOMAIN,
+};
+export const documentsAll = {
+    ...documentsDocuments,
+    pinnedDomain: [],
+};
+export function documentsListCommand(opts, globals) {
+    const config = opts.type === "all"
+        ? documentsAll
+        : opts.type === "folder"
+            ? documentsFolders
+            : documentsDocuments;
+    return listCommand(config, opts, globals);
+}
+export function foldersListCommand(opts, globals) {
+    return listCommand(documentsFolders, opts, globals);
+}
+export function documentsShowCommand(idArg, opts, globals) {
+    return showCommand(documentsAll, idArg, opts, globals);
+}
+export function documentsCreateCommand(opts, globals) {
+    const config = opts.folderType === "folder" ? documentsAll : documentsDocuments;
+    return createCommand(config, opts, globals);
+}
+export function documentsUpdateCommand(idArgs, opts, globals) {
+    return updateCommand(documentsAll, idArgs, opts, globals);
+}
+export function documentsDeleteCommand(idArgs, globals) {
+    return deleteCommand(documentsAll, idArgs, globals);
+}
+export async function treeCommand(opts, globals) {
+    const client = await authenticatedClient(globals);
+    await ModelFields.load(client, "documents.document"); // module-installed check
+    const maxDepth = Number(opts.depth);
+    if (!Number.isInteger(maxDepth) || maxDepth < 1) {
+        throw usageError(`invalid --depth value ${JSON.stringify(opts.depth)}`, "expected a positive integer");
+    }
+    // Root resolution: --folder given → that folder as root; otherwise roots.
+    let rootId = false;
+    let rootName = "Documents";
+    if (opts.folder !== undefined) {
+        rootId = await resolveFolderId(client, opts.folder);
+        const rows = (await client.executeKw("documents.document", "read", [
+            [rootId],
+            ["name"],
+        ]));
+        rootName = rows[0]?.name ?? rootName;
+    }
+    const [folders, docs] = await Promise.all([
+        client.executeKw("documents.document", "search_read", [FOLDER_DOMAIN], { fields: ["id", "name", "folder_id"], limit: 5000 }),
+        opts.count
+            ? client.executeKw("documents.document", "search_read", [[["type", "!=", "folder"]]], { fields: ["id", "folder_id"], limit: 50000 })
+            : Promise.resolve([]),
+    ]);
+    const countByFolder = new Map();
+    for (const d of docs) {
+        const fid = Array.isArray(d.folder_id) ? d.folder_id[0] : false;
+        if (fid !== false) {
+            countByFolder.set(fid, (countByFolder.get(fid) ?? 0) + 1);
+        }
+    }
+    const nodes = new Map();
+    for (const f of folders) {
+        nodes.set(f.id, {
+            id: f.id,
+            name: f.name,
+            parentId: Array.isArray(f.folder_id) ? f.folder_id[0] : false,
+            documentCount: countByFolder.get(f.id) ?? 0,
+            children: [],
+        });
+    }
+    for (const node of nodes.values()) {
+        if (node.parentId !== false) {
+            const parent = nodes.get(node.parentId);
+            if (parent)
+                parent.children.push(node);
+        }
+    }
+    // Root set: explicit folder, or all folders without a parent in the map.
+    const roots = [];
+    if (rootId !== false) {
+        const root = nodes.get(rootId);
+        if (root)
+            roots.push(root);
+    }
+    else {
+        for (const node of nodes.values()) {
+            if (node.parentId === false || !nodes.has(node.parentId)) {
+                roots.push(node);
+            }
+        }
+    }
+    roots.sort((a, b) => a.name.localeCompare(b.name));
+    if (globals.json) {
+        const toJson = (n) => ({
+            id: n.id,
+            name: n.name,
+            document_count: n.documentCount,
+            children: n.children
+                .sort((a, b) => a.name.localeCompare(b.name))
+                .map(toJson),
+        });
+        printJson({ root: rootName, tree: roots.map(toJson) });
+        return;
+    }
+    const lines = [];
+    const renderRec = (node, prefix, depth) => {
+        const countSuffix = opts.count ? ` (${node.documentCount})` : "";
+        lines.push(`${prefix}${node.name}${countSuffix}`);
+        if (depth >= maxDepth)
+            return;
+        const children = [...node.children].sort((a, b) => a.name.localeCompare(b.name));
+        for (let i = 0; i < children.length; i++) {
+            const last = i === children.length - 1;
+            renderRec(children[i], prefix + (last ? "└── " : "├── "), depth + 1);
+        }
+    };
+    for (const root of roots) {
+        renderRec(root, "", 1);
+    }
+    process.stdout.write(lines.join("\n") + "\n");
+}
+// ---------------------------------------------------------------------------
+// upload — local file → binary document
+// ---------------------------------------------------------------------------
+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",
+    ".html": "text/html",
+    ".xml": "application/xml",
+};
+export async function uploadCommand(opts, globals) {
+    const client = await authenticatedClient(globals);
+    const fieldsMeta = await ModelFields.load(client, "documents.document");
+    const filePath = resolve(opts.file);
+    let fileStat;
+    try {
+        fileStat = await stat(filePath);
+    }
+    catch {
+        throw usageError(`file not found: ${opts.file}`);
+    }
+    if (!fileStat.isFile()) {
+        throw usageError(`not a regular file: ${opts.file}`);
+    }
+    const name = opts.name ?? basename(filePath);
+    const mimetype = opts.mimetype ??
+        MIME_BY_EXT[extname(filePath).toLowerCase()] ??
+        "application/octet-stream";
+    // Read + base64
+    const buffer = await readFile(filePath);
+    const datas = buffer.toString("base64");
+    const checksum = createHash("sha1").update(buffer).digest("hex");
+    const values = {
+        name,
+        mimetype,
+        file_size: fileStat.size,
+        checksum,
+        datas,
+    };
+    if (opts.folder !== undefined) {
+        values.folder_id = await resolveFolderId(client, opts.folder);
+    }
+    if (opts.owner !== undefined) {
+        const user = await resolveReference(client, "res.users", opts.owner, {
+            label: "user",
+            searchFields: ["login", "email", "name"],
+        });
+        values.owner_id = user.id;
+    }
+    if (opts.partner !== undefined) {
+        const partner = await resolveReference(client, "res.partner", opts.partner, { label: "partner" });
+        values.partner_id = partner.id;
+    }
+    if (opts.tag && opts.tag.length > 0) {
+        const ids = [];
+        for (const t of opts.tag) {
+            const tag = await resolveReference(client, "documents.tag", t, {
+                label: "tag",
+            });
+            ids.push(tag.id);
+        }
+        values.tag_ids = [[6, 0, ids]];
+    }
+    if (opts.description !== undefined) {
+        values.description = opts.description;
+    }
+    if (globals.dryRun) {
+        const preview = { ...values, datas: `<${buffer.length} bytes base64>` };
+        if (globals.json) {
+            printJson({
+                model: "documents.document",
+                action: "upload",
+                dry_run: true,
+                values: preview,
+            });
+            return;
+        }
+        process.stdout.write(`Would upload documents.document:\n` +
+            Object.entries(preview)
+                .map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`)
+                .join("\n") +
+            "\n");
+        return;
+    }
+    const id = (await client.executeKw("documents.document", "create", [
+        values,
+    ]));
+    if (globals.json) {
+        printJson({
+            model: "documents.document",
+            action: "upload",
+            dry_run: false,
+            id,
+            name,
+            mimetype,
+            file_size: fileStat.size,
+        });
+        return;
+    }
+    const color = colorEnabled(false) && process.stdout.isTTY === true;
+    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). */
+async function resolveFolderId(client, input) {
+    const resolved = await resolveReference(client, "documents.document", input, {
+        label: "folder",
+        domain: FOLDER_DOMAIN,
+    });
+    return resolved.id;
+}
+export { formatTable, humanCell };

package/dist/mutation.js

@@ -40,13 +40,10 @@ export async function buildValues(client, config, spec, opts, mode, globals) {
     const resolvedByOption = {};
     const claim = (field, source) => {
         const prev = sourceOf[field];
-        if (prev === undefined) {
+        if (prev === undefined || prev === "default") {
             sourceOf[field] = source;
             return;
         }
-        if (prev === "pinned") {
-            throw usageError(`field "${field}" is pinned by this collection and cannot be overridden`, `remove --${kebab(/* context only */ "")}: the ${config.model.split(".")[0]} surface fixes ${field}`);
-        }
         throw usageError(`field "${field}" given by both ${prev} and ${source}`, "pass each field exactly once (SPEC §4.2)");
     };
     // 1. Pinned create values first (e.g. type=lead). They cannot be overridden
@@ -56,6 +53,13 @@ export async function buildValues(client, config, spec, opts, mode, globals) {
             values[k] = v;
             sourceOf[k] = "pinned";
         }
+        // 1b. Default create values — can be overridden by explicit flags/--set/--values.
+        for (const [k, v] of Object.entries(spec.createDefaultValues ?? {})) {
+            if (values[k] === undefined) {
+                values[k] = v;
+                sourceOf[k] = "default";
+            }
+        }
     }
     // 2. Exclusive groups (--partner vs --customer-*/--customer-name, §6.3).
     for (const group of spec.exclusiveGroups ?? []) {

package/package.json

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