@jipsoft/factusync-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JipSoft Labs
+
+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,211 @@
+# factusync — FactuSync CLI for agents and scripts
+
+`factusync` issues and reads Ecuadorian SRI electronic documents in FactuSync from a shell. It is a
+thin client of the FactuSync MCP endpoint: every command calls one MCP tool, with the same input,
+the same API-key scopes, the same error texts and the same idempotency as the MCP tools.
+
+It is written to be used by an AI agent (for example Pi, which has no MCP support) and by shell
+scripts. Every command prints JSON.
+
+## Run it
+
+```bash
+# Once published to npm:
+npx @jipsoft/factusync-cli context
+npm install -g @jipsoft/factusync-cli && factusync context
+
+# From the FactuSync repository:
+pnpm --filter @jipsoft/factusync-cli build
+node packages/factusync-cli/dist/cli.js context
+```
+
+Requires Node.js 22 or newer.
+
+## Configuration (environment only)
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `FACTUSYNC_API_KEY` | yes | A FactuSync API key. Sent as the `X-API-Key` header. |
+| `FACTUSYNC_MCP_URL` | no | The MCP endpoint. Default `https://factusync-api.jipsoft.com/mcp`. |
+
+The key is **never** accepted as a flag (`--api-key`, `--key` are rejected as unknown options), so it
+does not end up in shell history or in the process list. Never print the key or paste it into a
+conversation.
+
+A key's **SRI environment** (testing or production) is fixed when the key is created: every document
+created through it goes to that environment. `factusync context` tells you which one it is.
+
+## The rule: create is not emit
+
+1. `factusync invoice create --file invoice.json` makes a **DRAFT** and returns a preview with the taxes
+   and totals FactuSync computed. Nothing is sent to the SRI.
+2. Show that preview to the user and get their approval.
+3. `factusync document emit <documentId> --yes` sends the draft to the SRI. With a production key this
+   issues a **legally binding** tax document. `--yes` is required; without it the command does nothing
+   and exits 2.
+4. Emission is asynchronous: poll `factusync documents get <documentId>` until `status` is `AUTHORIZED`
+   or `REJECTED` (the SRI reason is in `failure`).
+5. `factusync ride <documentId> --out invoice.pdf` downloads the RIDE (PDF) once it is `AUTHORIZED`.
+
+**Idempotency:** `externalReference` (for example your order id) identifies the invoice. Creating
+again with the same `externalReference` returns the existing document with `alreadyExisted: true` —
+as it is stored, even if the new input differs — instead of a second invoice. Retrying a create after
+a timeout is therefore safe. Emit is not idempotent in that sense: only a `DRAFT` can be emitted.
+
+## Commands
+
+Each command needs one scope on the API key. A key without it cannot see or call that tool
+(`TOOL_NOT_AVAILABLE`). `factusync tools` lists what the current key can call.
+
+| Command | MCP tool | Scope |
+|---|---|---|
+| `factusync context` | `factusync_context` | `documents:read` |
+| `factusync id lookup <identification>` | `factusync_lookup_id` | `validation:read` |
+| `factusync documents list [--type --status --from --to --recipient --limit --offset]` | `factusync_list_documents` | `documents:read` |
+| `factusync documents get <id>` | `factusync_get_document` | `documents:read` |
+| `factusync invoice create --file <path\|->` | `factusync_create_invoice` | `documents:write` |
+| `factusync document emit <id> --yes` | `factusync_emit_document` | `documents:emit` |
+| `factusync ride <id> [--out file.pdf] [--xml file.xml]` | `factusync_get_ride` | `documents:ride` (+ `documents:read` for the XML) |
+| `factusync tools` | `tools/list` | none |
+
+Every command accepts `--pretty` (indented JSON) and `--help` / `-h`. `factusync --help` and
+`factusync --version` work without a key.
+
+### `factusync context`
+
+Start here. Prints `{ company: { ruc, legalName, tradeName, defaultEstablishment, defaultEmissionPoint },
+keyEnvironment, companyEnvironment, quota: { period, used, limit, status, remainingIncludingGrace,
+graceEndsAt }, certificate: { status, notAfter } }`. `keyEnvironment` (`testing` / `production`) is
+where documents created with this key go. `certificate.status` is `VALID`, `EXPIRED`, `MISSING` or
+`UNKNOWN_EXPIRY`: nothing can be emitted without a valid signing certificate.
+
+### `factusync id lookup <identification>`
+
+`identification` is a cédula (10 digits) or RUC (13 digits). Prints `{ id, source, active, legalName,
+tradeName, taxStatus, taxpayerType, registeredAddress, email }`. Use `legalName` as the buyer name.
+
+### `factusync documents list`
+
+| Flag | Tool argument | Value |
+|---|---|---|
+| `--type` | `documentTypeCode` | `01` invoice, `03` purchase settlement, `04` credit note, `05` debit note, `06` waybill, `07` withholding |
+| `--status` | `status` | e.g. `DRAFT`, `SENT_TO_SRI`, `AUTHORIZED`, `REJECTED` |
+| `--from` / `--to` | `issuedFrom` / `issuedTo` | `YYYY-MM-DD`, inclusive, the SRI issue date. Drafts have none: a date filter never returns drafts |
+| `--recipient` | `recipientIdentification` | Buyer cédula or RUC, digits only |
+| `--limit` | `limit` | 1 to 50, default 20 |
+| `--offset` | `offset` | Rows to skip: the `nextOffset` of the previous page |
+
+Prints `{ items: [{ id, documentTypeCode, status, number, accessKey, environment,
+recipientIdentification, recipientName, total, issueDate, createdAt }], hasMore, nextOffset }`,
+newest first.
+
+### `factusync documents get <id>`
+
+Prints one document without its line items: `id`, `documentTypeCode`, `status`, `number`
+(`001-001-000000123`), `establishment`, `emissionPoint`, `sequenceNumber`, `accessKey`, `authorizedAt`,
+`failure` (the SRI rejection, when there is one), `cancellation`, `createdAt`, `updatedAt` and the
+last state the SRI reported (`sriObservedState`, `sriDiverges`).
+
+### `factusync invoice create --file <path|->`
+
+The file (or stdin, with `--file -`) is exactly the `factusync_create_invoice` input, one JSON object:
+
+```json
+{
+  "externalReference": "order-1001",
+  "buyer": {
+    "idType": "05",
+    "idNumber": "1710034065",
+    "name": "MARIA PEREZ",
+    "email": "maria@example.com",
+    "address": "Av. Amazonas N34-56, Quito"
+  },
+  "lines": [
+    {
+      "mainCode": "SKU-1",
+      "description": "Widget",
+      "quantity": 2,
+      "unitPrice": 10,
+      "discount": 1,
+      "ivaRateCode": "4"
+    }
+  ],
+  "payment": { "methodCode": "20" },
+  "additionalInfo": { "Pedido": "order-1001" }
+}
+```
+
+- `externalReference` (required): your idempotency key, up to 200 characters.
+- `establishment`, `emissionPoint` (optional): 3 digits each; default to the company defaults.
+- `buyer` (required): `idType` `04` RUC (13 digits), `05` cédula (10 digits), `06` passport, `07`
+  consumidor final (then `idNumber` must be `9999999999999` and `name` `CONSUMIDOR FINAL`); `name`;
+  optional `email` (the authorized invoice is emailed there) and `address`.
+- `lines` (required, 1 to 200, `mainCode` unique): `quantity` > 0, `unitPrice` ≥ 0 **before discount
+  and before IVA**, optional `discount` as an amount for the whole line, and `ivaRateCode` — the SRI
+  IVA rate **code**, not the percentage (`4` = 15%, `0` = 0%, `7` = exempt), checked against the live
+  catalog.
+- `payment` (optional): one SRI payment `methodCode` for the whole amount (for example `01` without
+  the financial system, `20` other with the financial system), plus `term` and `timeUnit` (for example
+  `"dias"`) together for credit.
+- `additionalInfo` (optional): key/value pairs printed on the RIDE; the key is what the buyer reads.
+
+FactuSync computes every tax and total. Prints `{ documentId, status: "DRAFT", alreadyExisted,
+externalReference, environment, establishment, emissionPoint, number, buyer, lines: [{ …, taxRate,
+taxableBase, taxAmount }], totals, payments }`.
+
+### `factusync document emit <id> --yes`
+
+Only after the user approved the draft. Prints `{ documentId, jobId, status, next }`; then follow the
+document with `documents get`. Only `DRAFT` documents can be emitted.
+
+### `factusync ride <id> [--out file.pdf] [--xml file.xml]`
+
+Only for `AUTHORIZED` documents. Prints `{ documentId, status, number, accessKey, rideUrl, rideDownload,
+xml?, xmlTruncated? }`.
+
+- `--out file.pdf` downloads the PDF from `rideUrl` with the same key and adds `rideFile` to the output.
+  The key is only sent when `rideUrl` is on the same origin as `FACTUSYNC_MCP_URL`
+  (otherwise `RIDE_URL_UNTRUSTED`).
+- `--xml file.xml` writes the authorized XML, adds `xmlFile` and leaves `xml` out of the output. The
+  XML is only returned when the key also has `documents:read` (otherwise `XML_NOT_AVAILABLE`); an XML
+  the server truncated is not written (`XML_TRUNCATED`).
+- If any check fails, no file is written.
+
+### `factusync tools`
+
+Prints `{ tools: [{ name, title, description, command }] }`: the tools this key can call and the CLI
+command for each.
+
+## Output and errors
+
+- Success: the tool's structured result as compact JSON on stdout, one line (`--pretty` indents it).
+- Failure: nothing on stdout; one JSON object on stderr: `{ "code": "…", "message": "…", "details": … }`
+  (`details` only when the server sent them). `code` is FactuSync's API error code when the server
+  gave one (for example `INVALID_STATE_TRANSITION`, `NOT_FOUND`, `VALIDATION_FAILED`,
+  `UNKNOWN_TAX_RATE`, `EXTERNAL_REFERENCE_IN_USE`), otherwise one of the codes below.
+
+| Exit | Meaning | Codes |
+|---|---|---|
+| 0 | OK | |
+| 1 | The tool answered with an error | the API code, `TOOL_ERROR`, `TOOL_NOT_AVAILABLE`, `INVALID_INPUT`, `MCP_ERROR`, `XML_NOT_AVAILABLE`, `XML_TRUNCATED`, `RIDE_URL_UNTRUSTED`, `RIDE_DOWNLOAD_FAILED` |
+| 2 | Usage error: nothing was sent | `USAGE`, `CONFIRMATION_REQUIRED`, `INVALID_INPUT_FILE`, `OUTPUT_FILE_NOT_WRITABLE` |
+| 3 | Authentication or network | `MISSING_API_KEY`, `UNAUTHORIZED`, `FORBIDDEN`, `HTTP_ERROR`, `NETWORK_ERROR`, `TIMEOUT` |
+
+A missing `FACTUSYNC_API_KEY` fails with exit 3 before any network request.
+
+## Example session
+
+```bash
+export FACTUSYNC_API_KEY=…   # from a secret store, never typed into a conversation
+factusync context --pretty
+factusync id lookup 1710034065
+factusync invoice create --file invoice.json      # → documentId, preview
+# … the user approves the preview …
+factusync document emit "$DOCUMENT_ID" --yes
+factusync documents get "$DOCUMENT_ID"            # until AUTHORIZED or REJECTED
+factusync ride "$DOCUMENT_ID" --out invoice.pdf --xml invoice.xml
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { run } from './run.js';
+process.exitCode = await run(process.argv.slice(2), process.env, {
+    stdout: (text) => process.stdout.write(text),
+    stderr: (text) => process.stderr.write(text),
+    readStdin: async () => {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+        return Buffer.concat(chunks).toString('utf8');
+    },
+    fetch: globalThis.fetch,
+});

package/dist/commands.js

@@ -0,0 +1,112 @@
+/**
+ * The MCP tools the CLI calls and the API-key scope each one needs on the server. Mirrors
+ * `MCP_TOOL_REQUIRED_SCOPES` in the backend; `mcp-tool-contract.json` pins the two together
+ * (see `test/tool-contract.spec.ts` and the backend's `mcp-cli-contract.spec.ts`).
+ */
+export const TOOL_SCOPES = {
+    factusync_context: 'documents:read',
+    factusync_lookup_id: 'validation:read',
+    factusync_list_documents: 'documents:read',
+    factusync_get_document: 'documents:read',
+    factusync_create_invoice: 'documents:write',
+    factusync_emit_document: 'documents:emit',
+    factusync_get_ride: 'documents:ride',
+};
+export const COMMANDS = [
+    {
+        words: ['context'],
+        tool: 'factusync_context',
+        usage: 'factusync context',
+        summary: 'Company, SRI environment of the key, plan quota and signing certificate. Start here.',
+        positionals: [],
+        flags: {},
+    },
+    {
+        words: ['id', 'lookup'],
+        tool: 'factusync_lookup_id',
+        usage: 'factusync id lookup <identification>',
+        summary: 'Validates a cédula (10 digits) or RUC (13 digits) and returns the legal name the SRI expects.',
+        positionals: [{ name: 'identification', argument: 'identification' }],
+        flags: {},
+    },
+    {
+        words: ['documents', 'list'],
+        tool: 'factusync_list_documents',
+        usage: 'factusync documents list [--type <code>] [--status <status>] [--from <YYYY-MM-DD>] [--to <YYYY-MM-DD>] [--recipient <id>] [--limit <n>] [--offset <n>]',
+        summary: 'Lists documents, newest first, as compact summaries. Page with --limit (max 50) and nextOffset.',
+        positionals: [],
+        flags: {
+            type: { type: 'string', argument: 'documentTypeCode', description: '01 invoice, 03 purchase settlement, 04 credit note, 05 debit note, 06 waybill, 07 withholding' },
+            status: { type: 'string', argument: 'status', description: 'Document status, e.g. DRAFT, AUTHORIZED, REJECTED' },
+            from: { type: 'string', argument: 'issuedFrom', description: 'SRI issue date from, inclusive (YYYY-MM-DD). Excludes drafts' },
+            to: { type: 'string', argument: 'issuedTo', description: 'SRI issue date to, inclusive (YYYY-MM-DD). Excludes drafts' },
+            recipient: { type: 'string', argument: 'recipientIdentification', description: 'Buyer cédula or RUC, digits only' },
+            limit: { type: 'string', argument: 'limit', integer: true, description: 'Page size, 1 to 50 (server default 20)' },
+            offset: { type: 'string', argument: 'offset', integer: true, description: 'Rows to skip: pass the nextOffset of the previous page' },
+        },
+    },
+    {
+        words: ['documents', 'get'],
+        tool: 'factusync_get_document',
+        usage: 'factusync documents get <id>',
+        summary: 'One document: status, number, access key, SRI rejection reason, cancellation request.',
+        positionals: [{ name: 'id', argument: 'id' }],
+        flags: {},
+        notes: ['Emission is asynchronous: call this again to follow SENT_TO_SRI → AUTHORIZED or REJECTED.'],
+    },
+    {
+        words: ['invoice', 'create'],
+        tool: 'factusync_create_invoice',
+        usage: 'factusync invoice create --file <path|->',
+        summary: 'Creates a DRAFT invoice from a JSON file (or stdin with -) and returns its preview with computed taxes and totals.',
+        positionals: [],
+        flags: {
+            file: { type: 'string', description: 'JSON file with the invoice input, or - to read it from stdin' },
+        },
+        inputFromFile: true,
+        notes: [
+            'Nothing is sent to the SRI. Show the preview to the user, then run factusync document emit <id> --yes.',
+            'Idempotent on externalReference: the same value returns the same document (alreadyExisted: true).',
+        ],
+    },
+    {
+        words: ['document', 'emit'],
+        tool: 'factusync_emit_document',
+        usage: 'factusync document emit <id> --yes',
+        summary: "Sends a DRAFT document to the SRI in the key's environment. Production keys issue legally binding documents.",
+        positionals: [{ name: 'id', argument: 'id' }],
+        flags: {
+            yes: { type: 'boolean', description: 'Required. Confirms the user approved this draft' },
+        },
+        requiresConfirmation: true,
+        notes: ['Asynchronous: follow the result with factusync documents get <id>.'],
+    },
+    {
+        words: ['ride'],
+        tool: 'factusync_get_ride',
+        usage: 'factusync ride <id> [--out <file.pdf>] [--xml <file.xml>]',
+        summary: 'For an AUTHORIZED document: the RIDE (PDF) URL, and the authorized XML when the key may read documents.',
+        positionals: [{ name: 'id', argument: 'id' }],
+        flags: {
+            out: { type: 'string', description: 'Download the RIDE PDF to this file (sent with the same API key)' },
+            xml: { type: 'string', description: 'Write the authorized XML to this file (needs documents:read too)' },
+        },
+    },
+    {
+        words: ['tools'],
+        tool: null,
+        usage: 'factusync tools',
+        summary: 'Lists the MCP tools this API key can call, with the CLI command for each.',
+        positionals: [],
+        flags: {},
+    },
+];
+/** The longest command whose words start `argv`, so `documents list` wins over a shorter match. */
+export function findCommand(argv) {
+    return [...COMMANDS]
+        .sort((a, b) => b.words.length - a.words.length)
+        .find((command) => command.words.every((word, index) => argv[index] === word));
+}
+export function commandForTool(tool) {
+    return COMMANDS.find((command) => command.tool === tool);
+}

package/dist/config.js

@@ -0,0 +1,24 @@
+import { CliFailure, EXIT_AUTH_OR_NETWORK, usageFailure } from './failure.js';
+export const DEFAULT_MCP_URL = 'https://factusync-api.jipsoft.com/mcp';
+/**
+ * Configuration comes from the environment only. The key in particular is never a flag: a flag
+ * lands in shell history and in the process list, where other users on the machine can read it.
+ */
+export function readConfig(env) {
+    const rawUrl = env['FACTUSYNC_MCP_URL']?.trim() || DEFAULT_MCP_URL;
+    let mcpUrl;
+    try {
+        mcpUrl = new URL(rawUrl);
+    }
+    catch {
+        throw usageFailure(`FACTUSYNC_MCP_URL is not a valid URL: ${rawUrl}`);
+    }
+    if (mcpUrl.protocol !== 'https:' && mcpUrl.protocol !== 'http:') {
+        throw usageFailure(`FACTUSYNC_MCP_URL must be an http(s) URL: ${rawUrl}`);
+    }
+    const apiKey = env['FACTUSYNC_API_KEY']?.trim();
+    if (!apiKey) {
+        throw new CliFailure(EXIT_AUTH_OR_NETWORK, 'MISSING_API_KEY', 'FACTUSYNC_API_KEY is not set. Export your FactuSync API key in that variable; it is never accepted as a flag.');
+    }
+    return { apiKey, mcpUrl };
+}

package/dist/failure.js

@@ -0,0 +1,26 @@
+export const EXIT_OK = 0;
+export const EXIT_TOOL_ERROR = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_AUTH_OR_NETWORK = 3;
+/** A failure the CLI reports as `{code, message, details?}` on stderr, with its exit code. */
+export class CliFailure extends Error {
+    exitCode;
+    code;
+    details;
+    constructor(exitCode, code, message, details) {
+        super(message);
+        this.exitCode = exitCode;
+        this.code = code;
+        this.details = details;
+    }
+    get body() {
+        return {
+            code: this.code,
+            message: this.message,
+            ...(this.details !== undefined ? { details: this.details } : {}),
+        };
+    }
+}
+export function usageFailure(message) {
+    return new CliFailure(EXIT_USAGE, 'USAGE', message);
+}

package/dist/help.js

@@ -0,0 +1,59 @@
+import { COMMANDS, TOOL_SCOPES } from './commands.js';
+import { DEFAULT_MCP_URL } from './config.js';
+const COMMON = [
+    'Environment:',
+    '  FACTUSYNC_API_KEY   Required. Your FactuSync API key. Never accepted as a flag.',
+    `  FACTUSYNC_MCP_URL   Optional. Default ${DEFAULT_MCP_URL}`,
+    '',
+    'Output: the tool result as JSON on stdout (--pretty indents it).',
+    'Errors: JSON {code, message, details?} on stderr.',
+    'Exit codes: 0 ok, 1 tool error, 2 usage error, 3 authentication or network error.',
+];
+function scopeOf(command) {
+    return command.tool ? TOOL_SCOPES[command.tool] : '-';
+}
+export function rootHelp() {
+    const width = Math.max(...COMMANDS.map((command) => command.words.join(' ').length));
+    const rows = COMMANDS.map((command) => `  ${command.words.join(' ').padEnd(width)}  ${scopeOf(command).padEnd(15)}  ${command.summary}`);
+    return [
+        'Usage: factusync <command> [arguments] [--pretty]',
+        '',
+        'FactuSync (Ecuador SRI e-invoicing) for AI agents and scripts, through the FactuSync MCP endpoint.',
+        '',
+        `Commands (required API-key scope):`,
+        ...rows,
+        '',
+        'Create is not emit: invoice create makes a DRAFT; show it to the user, then document emit <id> --yes.',
+        '',
+        ...COMMON,
+        '',
+        "Run 'factusync <command> --help' for a command's arguments. 'factusync --version' prints the version.",
+        '',
+    ].join('\n');
+}
+export function commandHelp(command) {
+    const flags = Object.entries(command.flags).map(([name, flag]) => {
+        const value = flag.type === 'string' ? ` <${flag.integer ? 'n' : 'value'}>` : '';
+        const target = flag.argument ? ` (tool argument ${flag.argument})` : '';
+        return `  --${name}${value}: ${flag.description}${target}`;
+    });
+    return [
+        `Usage: ${command.usage} [--pretty]`,
+        '',
+        command.summary,
+        '',
+        command.tool ? `MCP tool: ${command.tool}. Required API-key scope: ${TOOL_SCOPES[command.tool]}.` : 'Uses tools/list: shows only what this key can call.',
+        ...(command.positionals.length > 0
+            ? ['', 'Arguments:', ...command.positionals.map((positional) => `  <${positional.name}>: tool argument ${positional.argument}`)]
+            : []),
+        '',
+        'Options:',
+        ...flags,
+        '  --pretty: indent the JSON output',
+        '  --help, -h: this help',
+        ...(command.notes && command.notes.length > 0 ? ['', ...command.notes] : []),
+        '',
+        ...COMMON,
+        '',
+    ].join('\n');
+}

package/dist/mcp-session.js

@@ -0,0 +1,148 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport, StreamableHTTPError } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { TOOL_SCOPES } from './commands.js';
+import { CliFailure, EXIT_AUTH_OR_NETWORK, EXIT_TOOL_ERROR } from './failure.js';
+import { CLI_VERSION } from './version.js';
+/**
+ * Opens a stateless Streamable HTTP connection to FactuSync's `POST /mcp` with the key as
+ * `X-API-Key`, runs `action`, and closes it. Every SDK or transport failure leaves here already
+ * turned into a `CliFailure` with its exit code.
+ */
+export async function withMcpSession(config, action) {
+    const transport = new StreamableHTTPClientTransport(config.mcpUrl, {
+        requestInit: { headers: { 'X-API-Key': config.apiKey } },
+        fetch: config.fetch,
+    });
+    const client = new Client({ name: 'factusync-cli', version: CLI_VERSION });
+    const options = config.timeoutMs !== undefined ? { timeout: config.timeoutMs } : undefined;
+    try {
+        await client.connect(transport, options);
+        return await action({
+            callTool: async (tool, args) => {
+                let result;
+                try {
+                    result = (await client.callTool({ name: tool, arguments: args }, undefined, options));
+                }
+                catch (error) {
+                    throw toolCallFailure(tool, error);
+                }
+                if (result.isError)
+                    throw toolResultFailure(tool, result);
+                return result.structuredContent ?? parseTextContent(result);
+            },
+            listTools: async () => {
+                const tools = [];
+                let cursor;
+                do {
+                    const page = await client.listTools(cursor !== undefined ? { cursor } : undefined, options);
+                    tools.push(...page.tools);
+                    cursor = page.nextCursor;
+                } while (cursor);
+                return tools;
+            },
+        });
+    }
+    catch (error) {
+        throw transportFailure(error);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+/** A successful result without `structuredContent`: its first text block, as JSON when it is JSON. */
+function parseTextContent(result) {
+    const text = textBlocks(result)[0] ?? '';
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+    }
+    catch {
+        // not JSON: returned as text below
+    }
+    return { text };
+}
+function textBlocks(result) {
+    return result.content.flatMap((block) => (block.type === 'text' ? [block.text] : []));
+}
+const CODED_MESSAGE = /^([A-Z][A-Z0-9_]*): ([\s\S]*)$/;
+const SDK_ERROR_MESSAGE = /^MCP error (-?\d+): ([\s\S]*)$/;
+/**
+ * A tool error as the server wrote it: `CODE: message` (FactuSync's API error text) plus an
+ * optional `{"details": …}` block, or plain text. The SDK's own errors (`MCP error -32602: …`)
+ * arrive the same way: an unknown tool means this key's scopes do not include it.
+ */
+export function toolResultFailure(tool, result) {
+    const [first = '', ...rest] = textBlocks(result);
+    const details = rest.map(detailsOf).find((value) => value !== undefined);
+    const sdkError = SDK_ERROR_MESSAGE.exec(first);
+    if (sdkError)
+        return sdkFailure(tool, Number(sdkError[1]), sdkError[2] ?? '');
+    const coded = CODED_MESSAGE.exec(first);
+    if (coded)
+        return new CliFailure(EXIT_TOOL_ERROR, coded[1], coded[2], details);
+    return new CliFailure(EXIT_TOOL_ERROR, 'TOOL_ERROR', first || 'The tool failed without a message.', details);
+}
+function detailsOf(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed !== null && typeof parsed === 'object' && 'details' in parsed)
+            return parsed.details;
+    }
+    catch {
+        // not a details block
+    }
+    return undefined;
+}
+function sdkFailure(tool, code, message) {
+    if (code === ErrorCode.MethodNotFound || /^Tool \S+ (not found|disabled)$/.test(message)) {
+        return new CliFailure(EXIT_TOOL_ERROR, 'TOOL_NOT_AVAILABLE', `This API key cannot use ${tool}: it needs the '${TOOL_SCOPES[tool]}' scope. Run 'factusync tools' to see what it can call.`);
+    }
+    if (message.startsWith('Input validation error'))
+        return new CliFailure(EXIT_TOOL_ERROR, 'INVALID_INPUT', message);
+    return new CliFailure(EXIT_TOOL_ERROR, 'TOOL_ERROR', message);
+}
+/** `callTool` threw instead of returning an error result: a JSON-RPC error, or the transport. */
+function toolCallFailure(tool, error) {
+    if (error instanceof McpError && error.code !== ErrorCode.RequestTimeout && error.code !== ErrorCode.ConnectionClosed) {
+        return sdkFailure(tool, error.code, error.message.replace(/^MCP error -?\d+: /, ''));
+    }
+    return error;
+}
+/** Anything that is not already a `CliFailure`: authentication, HTTP, connection or timeout. */
+export function transportFailure(error) {
+    if (error instanceof CliFailure)
+        return error;
+    if (error instanceof StreamableHTTPError) {
+        if (error.code === 401) {
+            return new CliFailure(EXIT_AUTH_OR_NETWORK, 'UNAUTHORIZED', 'FactuSync rejected the API key (HTTP 401). Check FACTUSYNC_API_KEY.');
+        }
+        if (error.code === 403) {
+            return new CliFailure(EXIT_AUTH_OR_NETWORK, 'FORBIDDEN', 'FactuSync refused this API key (HTTP 403).');
+        }
+        return new CliFailure(EXIT_AUTH_OR_NETWORK, 'HTTP_ERROR', `The MCP endpoint answered HTTP ${error.code}.`, { status: error.code });
+    }
+    if (error instanceof McpError && error.code === ErrorCode.RequestTimeout) {
+        return new CliFailure(EXIT_AUTH_OR_NETWORK, 'TIMEOUT', 'FactuSync did not answer in time.');
+    }
+    if (error instanceof McpError && error.code !== ErrorCode.ConnectionClosed) {
+        return new CliFailure(EXIT_TOOL_ERROR, 'MCP_ERROR', error.message.replace(/^MCP error -?\d+: /, ''), { mcpCode: error.code });
+    }
+    return networkFailure(error);
+}
+/** `fetch` rejections: refused, unresolvable, reset or aborted connections. */
+export function networkFailure(error) {
+    if (error instanceof CliFailure)
+        return error;
+    if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {
+        return new CliFailure(EXIT_AUTH_OR_NETWORK, 'TIMEOUT', 'FactuSync did not answer in time.');
+    }
+    if (error instanceof TypeError || (error instanceof McpError && error.code === ErrorCode.ConnectionClosed)) {
+        const cause = error.cause;
+        const reason = typeof cause?.code === 'string' ? ` (${cause.code})` : '';
+        return new CliFailure(EXIT_AUTH_OR_NETWORK, 'NETWORK_ERROR', `Could not reach FactuSync${reason}. Check FACTUSYNC_MCP_URL and the network.`);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new CliFailure(EXIT_TOOL_ERROR, 'UNEXPECTED_ERROR', message);
+}

package/dist/run.js

@@ -0,0 +1,232 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { parseArgs } from 'node:util';
+import { commandForTool, findCommand } from './commands.js';
+import { readConfig } from './config.js';
+import { CliFailure, EXIT_AUTH_OR_NETWORK, EXIT_OK, EXIT_TOOL_ERROR, EXIT_USAGE, usageFailure } from './failure.js';
+import { commandHelp, rootHelp } from './help.js';
+import { networkFailure, withMcpSession } from './mcp-session.js';
+import { CLI_VERSION } from './version.js';
+/** Same default as the SDK's MCP requests, for the RIDE download. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Runs one CLI invocation and returns its exit code. Never throws. */
+export async function run(argv, env, io) {
+    try {
+        return await execute(argv, env, io);
+    }
+    catch (error) {
+        const failure = error instanceof CliFailure ? error : networkFailure(error);
+        io.stderr(`${JSON.stringify(failure.body)}\n`);
+        return failure.exitCode;
+    }
+}
+async function execute(argv, env, io) {
+    if (argv.length === 0) {
+        throw usageFailure("Missing command. Usage: factusync <command> [arguments]. Run 'factusync --help'.");
+    }
+    if (argv[0].startsWith('-'))
+        return rootFlags(argv, io);
+    const parsed = parseCommand(argv);
+    if (parsed.values['help']) {
+        io.stdout(commandHelp(parsed.command));
+        return EXIT_OK;
+    }
+    const { command } = parsed;
+    if (command.requiresConfirmation && parsed.values['yes'] !== true) {
+        throw new CliFailure(EXIT_USAGE, 'CONFIRMATION_REQUIRED', `${command.words.join(' ')} issues a real tax document with the SRI. Show the draft to the user first, then run it again with --yes.`);
+    }
+    const args = await toolArguments(parsed, io);
+    const config = readConfig(env);
+    const connection = { ...config, fetch: io.fetch, ...(io.timeoutMs !== undefined ? { timeoutMs: io.timeoutMs } : {}) };
+    const output = await withMcpSession(connection, async (session) => {
+        if (command.tool === null)
+            return listTools(session);
+        const result = await session.callTool(command.tool, args);
+        return command.tool === 'factusync_get_ride' ? saveRide(result, parsed, config, io) : result;
+    });
+    io.stdout(`${JSON.stringify(output, null, parsed.pretty ? 2 : undefined)}\n`);
+    return EXIT_OK;
+}
+function rootFlags(argv, io) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: [...argv],
+            options: { help: { type: 'boolean', short: 'h' }, version: { type: 'boolean' } },
+            strict: true,
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        throw usageFailure(`${parseErrorMessage(error)} Run 'factusync --help'.`);
+    }
+    if (values.version) {
+        io.stdout(`${CLI_VERSION}\n`);
+        return EXIT_OK;
+    }
+    if (values.help) {
+        io.stdout(rootHelp());
+        return EXIT_OK;
+    }
+    throw usageFailure("Missing command. Run 'factusync --help'.");
+}
+function parseCommand(argv) {
+    const command = findCommand(argv);
+    if (!command) {
+        const words = argv.filter((token) => !token.startsWith('-')).slice(0, 2).join(' ');
+        throw usageFailure(`Unknown command '${words}'. Run 'factusync --help'.`);
+    }
+    const options = {
+        pretty: { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+    };
+    for (const [name, flag] of Object.entries(command.flags))
+        options[name] = { type: flag.type };
+    let result;
+    try {
+        result = parseArgs({ args: argv.slice(command.words.length), options, strict: true, allowPositionals: true });
+    }
+    catch (error) {
+        throw usageFailure(`${parseErrorMessage(error)} Run 'factusync ${command.words.join(' ')} --help'.`);
+    }
+    const parsed = { command, positionals: result.positionals, values: result.values, pretty: result.values['pretty'] === true };
+    if (!parsed.values['help'] && parsed.positionals.length !== command.positionals.length) {
+        throw usageFailure(`Usage: ${command.usage}`);
+    }
+    return parsed;
+}
+/**
+ * Node's message names the option and nothing after it, except for an inline `--flag=value`, where
+ * it would echo the value: cut at `=`, so a key typed as `--api-key=…` never reaches stderr.
+ */
+function parseErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const unknown = /Unknown option '([^'=]+)/.exec(message);
+    if (unknown)
+        return `Unknown option '${unknown[1]}'.`;
+    return message.split('\n')[0].replace(/=[^']*/g, '');
+}
+async function toolArguments(parsed, io) {
+    const { command } = parsed;
+    if (command.inputFromFile)
+        return readInputFile(parsed.values['file'], command, io);
+    const args = {};
+    command.positionals.forEach((positional, index) => {
+        args[positional.argument] = parsed.positionals[index];
+    });
+    for (const [name, flag] of Object.entries(command.flags)) {
+        const value = parsed.values[name];
+        if (!flag.argument || value === undefined)
+            continue;
+        if (flag.integer) {
+            if (typeof value !== 'string' || !/^\d+$/.test(value))
+                throw usageFailure(`--${name} must be a whole number, got '${String(value)}'.`);
+            args[flag.argument] = Number(value);
+        }
+        else {
+            args[flag.argument] = value;
+        }
+    }
+    return args;
+}
+async function readInputFile(file, command, io) {
+    if (typeof file !== 'string' || file === '')
+        throw usageFailure(`Usage: ${command.usage}`);
+    let text;
+    try {
+        text = file === '-' ? await io.readStdin() : await readFile(file, 'utf8');
+    }
+    catch (error) {
+        const reason = error.code ?? 'unreadable';
+        throw new CliFailure(EXIT_USAGE, 'INVALID_INPUT_FILE', `Cannot read ${file} (${reason}).`);
+    }
+    let input;
+    try {
+        input = JSON.parse(text);
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_USAGE, 'INVALID_INPUT_FILE', `${file === '-' ? 'stdin' : file} is not valid JSON: ${error.message}`);
+    }
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new CliFailure(EXIT_USAGE, 'INVALID_INPUT_FILE', `${file === '-' ? 'stdin' : file} must hold one JSON object: the tool input.`);
+    }
+    return input;
+}
+async function listTools(session) {
+    const tools = await session.listTools();
+    return {
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            title: tool.title ?? tool.annotations?.title ?? null,
+            description: tool.description ?? null,
+            command: commandForTool(tool.name)?.usage ?? null,
+        })),
+    };
+}
+/**
+ * `ride --out/--xml`: every check runs before anything is written, so a failure leaves no file.
+ * The PDF is fetched with the key only from the MCP endpoint's own origin: the key never goes
+ * to a host the user did not configure, whatever URL a response carries.
+ */
+async function saveRide(result, parsed, config, io) {
+    const out = parsed.values['out'];
+    const xmlPath = parsed.values['xml'];
+    const tool = 'factusync_get_ride';
+    if (typeof xmlPath === 'string') {
+        if (typeof result['xml'] !== 'string') {
+            throw new CliFailure(EXIT_TOOL_ERROR, 'XML_NOT_AVAILABLE', `${tool} returned no XML: this API key needs the documents:read scope as well as documents:ride.`);
+        }
+        if (result['xmlTruncated'] === true) {
+            throw new CliFailure(EXIT_TOOL_ERROR, 'XML_TRUNCATED', 'The server truncated this XML; it was not written. Download it from the FactuSync API instead.');
+        }
+    }
+    let pdf;
+    if (typeof out === 'string')
+        pdf = await downloadRide(result['rideUrl'], config, io);
+    const saved = { ...result };
+    try {
+        if (pdf && typeof out === 'string') {
+            await writeFile(out, pdf);
+            saved['rideFile'] = out;
+        }
+        if (typeof xmlPath === 'string') {
+            await writeFile(xmlPath, result['xml'], 'utf8');
+            delete saved['xml'];
+            saved['xmlFile'] = xmlPath;
+        }
+    }
+    catch (error) {
+        throw new CliFailure(EXIT_USAGE, 'OUTPUT_FILE_NOT_WRITABLE', `Cannot write the output file: ${error.message}`);
+    }
+    return saved;
+}
+async function downloadRide(rideUrl, config, io) {
+    let url;
+    try {
+        url = new URL(String(rideUrl));
+    }
+    catch {
+        throw new CliFailure(EXIT_TOOL_ERROR, 'RIDE_URL_MISSING', 'The tool result has no valid rideUrl.');
+    }
+    if (url.origin !== config.mcpUrl.origin) {
+        throw new CliFailure(EXIT_TOOL_ERROR, 'RIDE_URL_UNTRUSTED', `The RIDE URL is on ${url.origin}, not on ${config.mcpUrl.origin} (FACTUSYNC_MCP_URL); the API key is not sent there.`);
+    }
+    let response;
+    try {
+        response = await io.fetch(url, {
+            headers: { 'X-API-Key': config.apiKey },
+            signal: AbortSignal.timeout(io.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        throw networkFailure(error);
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new CliFailure(EXIT_AUTH_OR_NETWORK, response.status === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN', `FactuSync refused the RIDE download (HTTP ${response.status}).`);
+    }
+    if (!response.ok) {
+        throw new CliFailure(EXIT_TOOL_ERROR, 'RIDE_DOWNLOAD_FAILED', `The RIDE download answered HTTP ${response.status}.`, {
+            status: response.status,
+        });
+    }
+    return new Uint8Array(await response.arrayBuffer());
+}

package/dist/version.js

@@ -0,0 +1,3 @@
+import { createRequire } from 'node:module';
+/** `../package.json` from both `src/` (tests) and `dist/` (the published binary). */
+export const CLI_VERSION = createRequire(import.meta.url)('../package.json').version;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@jipsoft/factusync-cli",
+  "version": "0.1.0",
+  "description": "FactuSync command line for AI agents (Pi) and shell scripts: Ecuadorian SRI e-invoicing through the FactuSync MCP endpoint",
+  "license": "MIT",
+  "keywords": [
+    "factusync",
+    "sri",
+    "ecuador",
+    "facturacion-electronica",
+    "mcp",
+    "cli"
+  ],
+  "homepage": "https://jipsoft.com/factusync/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jipsoft-labs/jipsoft-global.git",
+    "directory": "packages/factusync-cli"
+  },
+  "bugs": {
+    "url": "https://github.com/jipsoft-labs/jipsoft-global/issues"
+  },
+  "type": "module",
+  "bin": {
+    "factusync": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc --project tsconfig.build.json && chmod +x dist/cli.js",
+    "test": "pnpm run build && pnpm exec vitest run",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm run test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.8"
+  }
+}