@factucat/cli 0.2.1 → 0.2.2

package/README.md

@@ -0,0 +1,337 @@
+# FactuCat CLI
+
+FactuCat CLI is the command-line interface for [FactuCat](https://factucat.com), a cloud-only product for issuing **Mexican CFDI 4.0 invoices**.
+
+It is designed for two use cases:
+
+- interactive invoicing for humans who want a guided flow
+- unattended automation for agents, scripts, and integrations that need stable `--json` output
+
+FactuCat CLI works with **Mexican tax concepts and SAT terminology** such as CFDI, timbrado, RFC, razón social, régimen fiscal, uso CFDI, XML, and PDF.
+
+## Install
+
+```bash
+npm install -g @factucat/cli
+```
+
+Verify the installation:
+
+```bash
+factucat --help
+```
+
+Update to the latest version:
+
+```bash
+npm install -g @factucat/cli@latest
+```
+
+## Authenticate
+
+Generate an API key in FactuCat, then save it locally:
+
+```bash
+factucat auth api-key set
+```
+
+You can also provide it explicitly:
+
+```bash
+factucat auth api-key set --value fc_live_xxxxx
+```
+
+Or through standard input:
+
+```bash
+printf 'fc_live_xxxxx\n' | factucat auth api-key set
+```
+
+Validate the current key:
+
+```bash
+factucat auth status
+factucat auth status --json
+```
+
+## How the workflow works
+
+FactuCat CLI uses a **remote draft workflow**:
+
+1. Create a draft in FactuCat Cloud
+2. Assign the customer or receiver data
+3. Set invoice metadata such as `uso CFDI`, payment method, and currency
+4. Add line items
+5. Review the invoice preview
+6. Stamp the invoice
+7. Download the XML or PDF if needed
+
+The server is always the source of truth. The CLI only remembers your current draft locally for convenience.
+
+## Interactive workflow
+
+Create a draft:
+
+```bash
+factucat invoice create
+```
+
+Create a draft and automatically resolve a customer by name or RFC:
+
+```bash
+factucat invoice create --customer "Donde nacen las ideas"
+```
+
+That command is a shortcut: it creates the draft and internally tries to find the customer before linking it to the draft.
+
+Add a line item:
+
+```bash
+factucat invoice add-item \
+  --description "Desarrollo de sistema de facturación" \
+  --unit-price 10000
+```
+
+If you omit SAT product code, SAT unit code, IVA, or retained ISR, FactuCat tries to infer them automatically.
+
+Set invoice metadata:
+
+```bash
+factucat invoice set-meta \
+  --cfdi-use G03 \
+  --payment-method PUE \
+  --payment-form 03
+```
+
+If you switch the invoice to USD without specifying an exchange rate, FactuCat automatically fetches the official DOF exchange rate:
+
+```bash
+factucat invoice set-meta --currency USD
+```
+
+Preview the full invoice before stamping:
+
+```bash
+factucat invoice show
+```
+
+Stamp interactively:
+
+```bash
+factucat invoice stamp
+```
+
+In an interactive terminal, `invoice stamp` shows the full preview first and can ask whether you want to send the stamped invoice through the customer contact channels registered in FactuCat.
+
+## Unattended workflow
+
+For agents and scripts, prefer `--json` and `--no-input`.
+
+Create a draft:
+
+```bash
+factucat invoice create --json
+```
+
+Set receiver data:
+
+```bash
+factucat invoice set-receiver \
+  --draft-id dft_123 \
+  --rfc XAXX010101000 \
+  --legal-name "Público en general" \
+  --postal-code 06000 \
+  --tax-regime 616 \
+  --json
+```
+
+Set invoice metadata:
+
+```bash
+factucat invoice set-meta \
+  --draft-id dft_123 \
+  --cfdi-use S01 \
+  --payment-method PUE \
+  --payment-form 01 \
+  --currency MXN \
+  --json
+```
+
+Add a line item with explicit taxes:
+
+```bash
+factucat invoice add-item \
+  --draft-id dft_123 \
+  --description "Servicios de consultoría" \
+  --quantity 1 \
+  --unit-price 1000 \
+  --iva 16 \
+  --isr-retenido 10 \
+  --json
+```
+
+Preview the draft:
+
+```bash
+factucat invoice show --draft-id dft_123 --json
+```
+
+Stamp without prompts:
+
+```bash
+factucat invoice stamp --draft-id dft_123 --no-input --json
+```
+
+Stamp and request delivery to customer contacts:
+
+```bash
+factucat invoice stamp \
+  --draft-id dft_123 \
+  --send-to-customer-contacts \
+  --no-input \
+  --json
+```
+
+Or request specific channels:
+
+```bash
+factucat invoice stamp \
+  --draft-id dft_123 \
+  --send-customer-email \
+  --send-customer-whatsapp \
+  --no-input \
+  --json
+```
+
+## Current draft helpers
+
+Select an existing draft as your current one:
+
+```bash
+factucat invoice use dft_123
+```
+
+Check which draft is currently selected:
+
+```bash
+factucat invoice current
+```
+
+Discard the current draft:
+
+```bash
+factucat invoice discard
+```
+
+## Customer commands
+
+Search customers:
+
+```bash
+factucat customer search "Donde nacen"
+```
+
+List customers:
+
+```bash
+factucat customer list --limit 20
+```
+
+Create a customer:
+
+```bash
+factucat customer create \
+  --legal-name "Donde nacen las ideas" \
+  --rfc DNI240101AB1 \
+  --postal-code 45116 \
+  --tax-regime 601 \
+  --email hola@ejemplo.com
+```
+
+## Review and artifact download
+
+List issued invoices:
+
+```bash
+factucat invoice list
+```
+
+Get a stamped invoice by UUID or folio:
+
+```bash
+factucat invoice get 019d231a-779b-771b-a666-ecefc6803fd2
+factucat invoice get MIAU-00036
+```
+
+Download XML:
+
+```bash
+factucat invoice download xml MIAU-00036
+factucat invoice download xml MIAU-00036 --output ./facturas/
+```
+
+Download PDF:
+
+```bash
+factucat invoice download pdf MIAU-00036
+factucat invoice download pdf MIAU-00036 --output ./facturas/factura-marzo.pdf
+```
+
+If you do not pass `--output`, the file is saved in the current working directory.
+
+## Notes about inference
+
+FactuCat automatically infers several values when possible:
+
+- `invoice add-item` can infer SAT product code, SAT unit code, IVA, and retained ISR
+- `invoice set-meta --currency USD` can infer the official DOF exchange rate if you omit `--exchange-rate`
+
+This mirrors the behavior of FactuCat's guided product flows and keeps the CLI aligned with the rest of the platform.
+
+## Troubleshooting
+
+### `API key inválida o revocada`
+
+The configured API key is wrong, expired, or has been revoked. Save a valid key again:
+
+```bash
+factucat auth api-key set
+factucat auth status
+```
+
+### `No hay borrador activo`
+
+You tried to mutate a draft without selecting one first. Either create a draft or point to one explicitly:
+
+```bash
+factucat invoice create
+factucat invoice use dft_123
+```
+
+### Customer lookup is ambiguous
+
+If `invoice create --customer "..."` matches multiple customers, search first and then pass the exact customer id:
+
+```bash
+factucat customer search "Donde nacen"
+factucat invoice create --customer-id cus_123
+```
+
+### Stamping fails
+
+Review the draft before retrying:
+
+```bash
+factucat invoice show
+```
+
+Common causes are incomplete CFDI data, missing receiver information, or invalid concepts.
+
+### Downloaded artifact location
+
+If you are unsure where a file was saved, use `--output` explicitly to control the destination path.
+
+## Learn more
+
+- FactuCat: [https://factucat.com](https://factucat.com)
+- Help page in npm package format: this README

package/package.json

@@ -1,8 +1,28 @@
 {
   "name": "@factucat/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": false,
+  "description": "CLI for Mexican CFDI 4.0 invoicing with FactuCat Cloud",
   "type": "module",
+  "keywords": [
+    "factucat",
+    "cli",
+    "cfdi",
+    "cfdi-4.0",
+    "mexico",
+    "sat",
+    "facturacion",
+    "invoicing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ocruzv/factucat.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/ocruzv/factucat/tree/main/packages/cli",
+  "bugs": {
+    "url": "https://github.com/ocruzv/factucat/issues"
+  },
   "publishConfig": {
     "access": "public"
   },