@bergetai/odoo-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berget AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# odoo-cli
+
+Agent-first CLI for the [Odoo External API](https://www.odoo.com/documentation/18.0/developer/reference/external_api.html).
+
+Every command is non-interactive, scriptable, and supports `--json` for stable machine-readable output.
+
+## Usage
+
+```bash
+# Authenticate (API key via stdin — never as a flag)
+pass odoo/key | odoo auth login --url https://acme.odoo.com --db acme --username automation
+
+# Check credentials and their configuration sources
+odoo auth status --json
+
+# Unauthenticated connectivity check
+odoo version
+```
+
+Configuration precedence: flags > environment (`ODOO_URL`, `ODOO_DB`, `ODOO_USERNAME`, `ODOO_API_KEY`) > `$XDG_CONFIG_HOME/odoo/config.json`. The API key is never accepted as a flag value.
+
+Note: `odoo --version` prints the CLI's own version; `odoo version` queries the server.
+
+## Development
+
+```bash
+npm install
+npm run build   # compile to dist/
+npm test        # build + unit/e2e tests against a fake XML-RPC server
+```
+
+## Status
+
+- [x] Skeleton, transport, and auth — command tree, global flags, config sources and precedence with atomic `0600` config writes, XML-RPC transport with timeouts and HTTPS enforcement, `odoo version`, `odoo auth login`, `odoo auth status` with the auth failure taxonomy (db missing / bad credentials / unreachable)
+- [x] Read-only CRM surface (`crm leads list/show`) — default columns, `--fields`/`--all-fields`, `--limit`/`--offset`/`--order`, `--domain`/`--filter` with `fields_get` type checking, reference resolution (`--stage`/`--team`/`--assignee`/`--tag`), table/JSON output with `search_count` envelope
+- [x] Read-only Helpdesk surface (`helpdesk tickets list/show`) — `--open`/`--closed` via stage `fold`, strict team-scoped stage resolution, module-not-installed error (exit 4)
+- [x] `--dry-run` machinery for mutations — full validation, resolution, and before/after diffs without mutating
+- [x] 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`
+- [ ] Polish and packaging
+
+## Production-instance notes
+
+Validated against a real Odoo 18.0+e instance. Schema realities discovered
+against the live server:
+
+- `helpdesk.ticket.ticket_type_id` may be absent (edition/version-dependent).
+  Curated `show` fields are intersected with `fields_get`, so absent optional
+  fields degrade gracefully instead of faulting the read.
+- `helpdesk.stage` links to teams via `team_ids` (many2many, shared stages) on
+  some instances rather than `team_id` (many2one). Stage scoping introspects
+  the stage model's schema and uses whichever field exists.
+- `execute_kw` kwargs must be a separate trailing dict param; packing it into
+  the positional-args array makes the server silently ignore it (this caused
+  `fields_get` to return full/empty structs).

package/dist/cli.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+import { Command, CommanderError } from "commander";
+import { authLoginCommand, authStatusCommand } from "./commands/auth.js";
+import { leadsCreateCommand, leadsDeleteCommand, leadsListCommand, leadsShowCommand, leadsUpdateCommand, crmLeads, } from "./commands/crm.js";
+import { ticketsCreateCommand, ticketsDeleteCommand, ticketsListCommand, ticketsShowCommand, ticketsUpdateCommand, helpdeskTickets, } from "./commands/helpdesk.js";
+import { versionCommand } from "./commands/version.js";
+import { CliError } from "./errors.js";
+import { applyGlobalOptions, enforceTransportSecurity, DEFAULT_TIMEOUT, } from "./global-options.js";
+import { printError } from "./output.js";
+const CLI_VERSION = "0.1.0";
+/** commander value parser for repeatable options (accumulates values). */
+function collect(value, previous) {
+    return [...previous, value];
+}
+/**
+ * Register a resource's first-class mutation flags + --set/--values onto a
+ * commander command (SPEC §4.2). Help text states the underlying field
+ * (§10). Returns the command so create/update can chain .argument/.action.
+ */
+function addMutationFlags(cmd, config) {
+    const spec = config.mutation;
+    if (!spec)
+        return cmd;
+    for (const flag of spec.flags) {
+        if (flag.multi) {
+            cmd.option(flag.flags, `${flag.help} [${flag.field}]`, collect, []);
+        }
+        else {
+            cmd.option(flag.flags, `${flag.help} [${flag.field}]`);
+        }
+    }
+    cmd.option("--set <f=v>", "set any field (technical name, JSON scalar); repeatable", collect, []);
+    cmd.option("--values <file>", "read field values from a JSON file ('-' for stdin)");
+    return cmd;
+}
+function buildProgram() {
+    const program = new Command();
+    program
+        .name("odoo")
+        .description(`Agent-first CLI for the Odoo External API.
+
+All commands are non-interactive and scriptable; every command supports
+--json for machine-readable output. Note that \`odoo --version\` prints the
+CLI's own version, while \`odoo version\` queries the server's version.`)
+        .version(CLI_VERSION, "--version", "print the CLI's own version")
+        .showHelpAfterError("(add --help for additional information)")
+        .showSuggestionAfterError(true)
+        .configureHelp({ sortSubcommands: true });
+    program.addHelpText("after", `
+Examples:
+  $ pass odoo/key | odoo auth login --url https://acme.odoo.com --db acme --username automation
+  $ odoo auth status --json
+  $ odoo version
+
+Docs: https://www.odoo.com/documentation/18.0/developer/reference/external_api.html`);
+    applyGlobalOptions(program);
+    program
+        .command("version")
+        .description("query the server's version (unauthenticated connectivity check)")
+        .action(async () => {
+        await run(versionCommand, program);
+    });
+    const auth = program.command("auth").description("manage credentials");
+    auth
+        .command("login")
+        .description("verify credentials and write them to the config file (key via stdin/env/file)")
+        .addHelpText("after", `
+Examples:
+  $ pass odoo/key | odoo auth login --url https://acme.odoo.com --db acme --username automation
+  $ ODOO_API_KEY=... odoo auth login --url https://acme.odoo.com --db acme --username automation`)
+        .action(async () => {
+        await run(authLoginCommand, program);
+    });
+    auth
+        .command("status")
+        .description("show resolved credentials and verify them against the server")
+        .action(async () => {
+        await run(authStatusCommand, program);
+    });
+    const crm = program.command("crm").description("CRM app (crm.lead)");
+    const leads = crm.command("leads").description("leads (type=lead)");
+    leads
+        .command("list")
+        .description("search and list leads with curated default columns")
+        .option("--stage <name|id>", "filter by stage (resolved by name)")
+        .option("--team <name|id>", "filter by sales team (resolved by name)")
+        .option("--assignee <name|id>", "filter by salesperson (login, email, or name)")
+        .option("--tag <name|id>", "filter by tag; repeatable, AND-ed", collect, [])
+        .option("--priority <level>", "filter by priority: low, medium, high, urgent")
+        .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. "expected_revenue desc"', undefined)
+        .action(async (opts) => {
+        await run((g) => leadsListCommand(opts, g), program);
+    });
+    leads
+        .command("show")
+        .description("read one lead")
+        .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) => leadsShowCommand(id, opts, g), program);
+    });
+    addMutationFlags(leads
+        .command("create")
+        .description("create a lead (preview with --dry-run)"), crmLeads).action(async (opts) => {
+        await run((g) => leadsCreateCommand(opts, g), program);
+    });
+    addMutationFlags(leads
+        .command("update")
+        .description("update leads (preview with --dry-run)"), crmLeads)
+        .argument("<id...>", "record ids")
+        .action(async (ids, opts) => {
+        await run((g) => leadsUpdateCommand(ids, opts, g), program);
+    });
+    leads
+        .command("delete")
+        .description("delete leads (preview with --dry-run; unknown ids are skipped)")
+        .argument("<id...>", "record ids")
+        .action(async (ids) => {
+        await run((g) => leadsDeleteCommand(ids, g), program);
+    });
+    const helpdesk = program
+        .command("helpdesk")
+        .description("Helpdesk app (helpdesk.ticket, Enterprise)");
+    const tickets = helpdesk.command("tickets").description("support tickets");
+    tickets
+        .command("list")
+        .description("search and list tickets with curated default columns")
+        .option("--team <name|id>", "filter by helpdesk team (resolved by name)")
+        .option("--stage <name|id>", "filter by stage (resolved within --team when given)")
+        .option("--assignee <name|id>", "filter by assignee (login, email, or name)")
+        .option("--tag <name|id>", "filter by tag; repeatable, AND-ed", collect, [])
+        .option("--priority <level>", "filter by priority: low, medium, high, urgent")
+        .option("--open", "only tickets in unfolded (open) stages — see note below")
+        .option("--closed", "only tickets in folded (closed) stages — see note below")
+        .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)
+        .addHelpText("after", `
+Note: --open/--closed select on the stage's "fold" flag, a kanban presentation
+attribute conventionally set on closing stages (Done, Cancelled). It is the
+only server-side signal available, but an admin can fold any stage — for exact
+stage selection use --stage, or --domain '[["stage_id.fold","=",false]]' for
+the raw form.`)
+        .action(async (opts) => {
+        await run((g) => ticketsListCommand(opts, g), program);
+    });
+    tickets
+        .command("show")
+        .description("read one ticket")
+        .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) => ticketsShowCommand(id, opts, g), program);
+    });
+    addMutationFlags(tickets
+        .command("create")
+        .description("create a ticket (preview with --dry-run)"), helpdeskTickets).action(async (opts) => {
+        await run((g) => ticketsCreateCommand(opts, g), program);
+    });
+    addMutationFlags(tickets
+        .command("update")
+        .description("update tickets (preview with --dry-run)"), helpdeskTickets)
+        .argument("<id...>", "record ids")
+        .action(async (ids, opts) => {
+        await run((g) => ticketsUpdateCommand(ids, opts, g), program);
+    });
+    tickets
+        .command("delete")
+        .description("delete tickets (preview with --dry-run; unknown ids are skipped)")
+        .argument("<id...>", "record ids")
+        .action(async (ids) => {
+        await run((g) => ticketsDeleteCommand(ids, g), program);
+    });
+    return program;
+}
+async function run(fn, program) {
+    const globals = collectGlobalOptions(program);
+    // URL security is enforced here for flag/env-provided URLs; config-file
+    // URLs are validated after resolution inside each command.
+    const url = globals.url ?? process.env.ODOO_URL;
+    if (url) {
+        enforceTransportSecurity(url, globals.allowInsecureHttp);
+    }
+    await fn(globals);
+}
+function collectGlobalOptions(program) {
+    const o = program.opts();
+    return {
+        json: Boolean(o.json),
+        dryRun: Boolean(o.dryRun),
+        url: o.url,
+        db: o.db,
+        username: o.username,
+        apiKeyFile: o.apiKeyFile,
+        allowInsecureHttp: Boolean(o.allowInsecureHttp),
+        timeout: o.timeout ??
+            process.env.ODOO_TIMEOUT ??
+            DEFAULT_TIMEOUT,
+        quiet: Boolean(o.quiet),
+        verbose: Boolean(o.verbose),
+        noColor: Boolean(o.noColor),
+    };
+}
+async function main() {
+    const program = buildProgram();
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            // commander already printed help/usage text
+            process.exitCode = error.exitCode;
+            return;
+        }
+        const globals = safeGlobals(program);
+        if (error instanceof CliError) {
+            printError(error, { json: globals.json, verbose: globals.verbose });
+            process.exitCode = error.exitCode;
+            return;
+        }
+        // Unexpected/internal error (exit 1)
+        const err = error;
+        process.stderr.write(`Error: internal error: ${err.message}\n`);
+        if (globals.verbose && err.stack) {
+            process.stderr.write(`${err.stack}\n`);
+        }
+        process.exitCode = 1;
+    }
+}
+function safeGlobals(program) {
+    try {
+        const o = program.opts();
+        return { json: Boolean(o.json), verbose: Boolean(o.verbose) };
+    }
+    catch {
+        return { json: false, verbose: false };
+    }
+}
+await main();

package/dist/client.js

@@ -0,0 +1,97 @@
+import { authError, networkError, notFoundError, usageError, } from "./errors.js";
+import { callMethod, XmlRpcFaultError } from "./xmlrpc.js";
+const DB_MISSING_RE = /database "([^"]+)" does not exist/;
+export class OdooClient {
+    db;
+    username;
+    apiKey;
+    commonUrl;
+    objectUrl;
+    timeoutMs;
+    verbose;
+    uid;
+    constructor(baseUrl, db, username, apiKey, options) {
+        this.db = db;
+        this.username = username;
+        this.apiKey = apiKey;
+        const root = baseUrl.replace(/\/+$/, "");
+        this.commonUrl = `${root}/xmlrpc/2/common`;
+        this.objectUrl = `${root}/xmlrpc/2/object`;
+        this.timeoutMs = options.timeoutMs;
+        this.verbose = options.verbose ?? false;
+    }
+    callOptions(url) {
+        return { url, timeoutMs: this.timeoutMs, verbose: this.verbose };
+    }
+    /**
+     * Unauthenticated connectivity check. A reachable XML-RPC endpoint that
+     * does not behave like Odoo (no parseable version payload) is a usage
+     * error — the URL is wrong — not a network failure (SPEC §2.2).
+     */
+    async version() {
+        let result;
+        try {
+            result = await callMethod(this.callOptions(this.commonUrl), "version", []);
+        }
+        catch (error) {
+            if (error instanceof XmlRpcFaultError) {
+                throw usageError(`${this.commonUrl} does not look like an Odoo server (method 'version' failed)`, "check --url");
+            }
+            throw error;
+        }
+        if (typeof result !== "object" ||
+            result === null ||
+            typeof result.server_version !==
+                "string") {
+            throw usageError(`${this.commonUrl} does not look like an Odoo server (unexpected version response)`, "check --url");
+        }
+        return result;
+    }
+    /**
+     * Authenticate once and cache the uid for the process (SPEC §2).
+     * Maps the three server outcomes of §2.3 onto distinct errors:
+     * db missing (exit 4), bad credentials (exit 3), success (uid).
+     */
+    async authenticate() {
+        if (this.uid !== undefined)
+            return this.uid;
+        if (!this.db || !this.username || !this.apiKey) {
+            throw authError("authentication requires db, username, and api key");
+        }
+        let result;
+        try {
+            result = await callMethod(this.callOptions(this.commonUrl), "authenticate", [this.db, this.username, this.apiKey, {}]);
+        }
+        catch (error) {
+            if (error instanceof XmlRpcFaultError) {
+                const match = DB_MISSING_RE.exec(error.faultString);
+                if (match) {
+                    throw notFoundError("database_not_found", `database "${match[1]}" does not exist on the server`, "check --db");
+                }
+                throw networkError(`authentication request failed (fault ${error.faultCode})`, "retry with --verbose to see the full server response");
+            }
+            throw error;
+        }
+        if (typeof result === "number" && Number.isInteger(result) && result > 0) {
+            this.uid = result;
+            return result;
+        }
+        if (result === false) {
+            throw authError("invalid credentials: the server rejected the username/API key pair", "verify the username and generate a new API key under Odoo preferences");
+        }
+        throw networkError(`unexpected authenticate() response from the server: ${JSON.stringify(result)}`);
+    }
+    /** execute_kw against /xmlrpc/2/object (used from Phase 1 onward). */
+    async executeKw(model, method, args, kwargs = {}) {
+        const uid = await this.authenticate();
+        return callMethod(this.callOptions(this.objectUrl), "execute_kw", [
+            this.db,
+            uid,
+            this.apiKey,
+            model,
+            method,
+            args,
+            kwargs,
+        ]);
+    }
+}

package/dist/commands/auth.js

@@ -0,0 +1,133 @@
+import { OdooClient } from "../client.js";
+import { missingValueHint, missingValues, resolveConfig, writeConfigFile, } from "../config.js";
+import { parseDurationMs } from "../duration.js";
+import { usageError } from "../errors.js";
+import { printJson } from "../output.js";
+async function readStdinKey() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+}
+function authFlags(globals) {
+    return {
+        url: globals.url,
+        db: globals.db,
+        username: globals.username,
+        apiKeyFile: globals.apiKeyFile,
+    };
+}
+/**
+ * `odoo auth login` (SPEC §2.2): verify credentials against the server, then
+ * write the config file. Key resolution order: stdin (non-TTY, consumed even
+ * if empty) → ODOO_API_KEY → --api-key-file. Never prompts.
+ */
+export async function authLoginCommand(globals) {
+    let stdinKey;
+    if (!process.stdin.isTTY) {
+        stdinKey = await readStdinKey();
+        if (stdinKey === "") {
+            throw usageError("API key read from stdin is empty", "pipe a key via stdin, or unset the pipe and use ODOO_API_KEY / --api-key-file");
+        }
+    }
+    else if (!process.env.ODOO_API_KEY && !globals.apiKeyFile) {
+        throw usageError("no API key provided", "pipe the key via stdin, set ODOO_API_KEY, or pass --api-key-file — login never prompts");
+    }
+    const resolved = await resolveConfig(authFlags(globals), {
+        apiKey: stdinKey,
+    });
+    const missing = missingValues(resolved);
+    if (missing.length > 0) {
+        const details = missing
+            .map((k) => `  ${k}: ${missingValueHint(k)}`)
+            .join("\n");
+        throw usageError(`missing required configuration: ${missing.join(", ")}`, `\n${details}`);
+    }
+    const client = new OdooClient(resolved.url, resolved.db, resolved.username, resolved.apiKey, {
+        timeoutMs: parseDurationMs(globals.timeout),
+        verbose: globals.verbose,
+    });
+    if (!globals.quiet) {
+        process.stderr.write(`Verifying credentials against ${resolved.url} ...\n`);
+    }
+    // 1. Prove the URL is a reachable Odoo server before authenticating.
+    const version = await client.version();
+    // 2. Authenticate; throws exit 3 (bad credentials) / exit 4 (db missing).
+    const uid = await client.authenticate();
+    await writeConfigFile({
+        url: resolved.url,
+        db: resolved.db,
+        username: resolved.username,
+        api_key: resolved.apiKey,
+        server_version: version.server_version,
+    });
+    if (globals.json) {
+        printJson({
+            url: resolved.url,
+            db: resolved.db,
+            username: resolved.username,
+            uid,
+            server_version: version.server_version,
+            authenticated: true,
+        });
+    }
+    else {
+        process.stdout.write(`Logged in as '${resolved.username}' (uid ${uid}) on ${resolved.url} (Odoo ${version.server_version})\n`);
+    }
+}
+/**
+ * `odoo auth status` (SPEC §2.2): report resolved credentials and verify them,
+ * without changing anything. With --json the envelope is always printed on
+ * stdout, even when exiting non-zero (SPEC §7.3 exception).
+ */
+export async function authStatusCommand(globals) {
+    const resolved = await resolveConfig(authFlags(globals));
+    const missing = missingValues(resolved);
+    const envelope = {
+        url: resolved.url ?? null,
+        db: resolved.db ?? null,
+        username: resolved.username ?? null,
+        server_version: null,
+        uid: null,
+        authenticated: false,
+        config_source: resolved.sources,
+    };
+    if (missing.length > 0) {
+        envelope.missing = missing;
+        if (globals.json) {
+            printJson(envelope);
+        }
+        else {
+            process.stderr.write("Error: missing configuration values:\n");
+            for (const key of missing) {
+                process.stderr.write(`  ${key}: ${missingValueHint(key)}\n`);
+            }
+        }
+        process.exitCode = 2;
+        return;
+    }
+    const client = new OdooClient(resolved.url, resolved.db, resolved.username, resolved.apiKey, {
+        timeoutMs: parseDurationMs(globals.timeout),
+        verbose: globals.verbose,
+    });
+    if (!globals.quiet) {
+        process.stderr.write(`Verifying credentials against ${resolved.url} ...\n`);
+    }
+    const version = await client.version();
+    envelope.server_version = version.server_version;
+    const uid = await client.authenticate();
+    envelope.uid = uid;
+    envelope.authenticated = true;
+    if (globals.json) {
+        printJson(envelope);
+    }
+    else {
+        process.stdout.write(`URL:            ${envelope.url} (${resolved.sources.url})\n`);
+        process.stdout.write(`Database:       ${envelope.db} (${resolved.sources.db})\n`);
+        process.stdout.write(`Username:       ${envelope.username} (${resolved.sources.username})\n`);
+        process.stdout.write(`API key:        configured (${resolved.sources.api_key})\n`);
+        process.stdout.write(`Server version: ${envelope.server_version}\n`);
+        process.stdout.write(`Authenticated:  yes (uid ${uid})\n`);
+    }
+}