fiscalisto 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -30,6 +30,18 @@ const invoice = await fiscalisto.invoices.create(
30
30
  console.log(invoice.uuid, invoice.total);
31
31
  ```
32
32
 
33
+ ## Con agentes de IA
34
+
35
+ Para que Claude Code, Cursor, Codex u otro agente integre Fiscalisto, conecte el servidor MCP de la documentación (sin llave) y pídale que empiece con `get_started`:
36
+
37
+ `npx fiscalisto init --agents` deja además la guía en `.claude/skills/fiscalisto/SKILL.md` y una sección en su `AGENTS.md`. Para conectar la documentación:
38
+
39
+ ```bash
40
+ claude mcp add --transport http fiscalisto-docs https://fiscalisto.com/docs/api/mcp
41
+ ```
42
+
43
+ La guía de integración en una página está en [fiscalisto.com/docs/api/SKILL.md](https://fiscalisto.com/docs/api/SKILL.md) y el índice de la documentación para agentes en [llms.txt](https://fiscalisto.com/docs/api/llms.txt). Otros clientes y más: [fiscalisto.com/docs/api/agentes](https://fiscalisto.com/docs/api/agentes).
44
+
33
45
  ## CLI
34
46
 
35
47
  El mismo paquete trae el CLI: `npx fiscalisto login` inicia sesión por el navegador, `npx fiscalisto init` deja el SDK y su llave en su proyecto, y `npx fiscalisto listen --forward-to http://localhost:3000/webhooks` le manda los webhooks de pruebas a su computadora. Con `--json`, para agentes y scripts. Vea [fiscalisto.com/docs/api/cli](https://fiscalisto.com/docs/api/cli).
@@ -0,0 +1,10 @@
1
+ /**
2
+ * How a coding agent adds Fiscalisto to an app, in one page: the Agent Skill that
3
+ * `fiscalisto init --agents` leaves in .claude/skills/fiscalisto/SKILL.md, the same text the site
4
+ * serves at https://fiscalisto.com/docs/api/SKILL.md and the docs MCP answers with get_started.
5
+ * Written by hand; keep it short (an agent reads all of it) and true to the docs it links.
6
+ */
7
+ export declare const AGENT_SKILL_DESCRIPTION = "Agregar facturaci\u00F3n electr\u00F3nica mexicana (CFDI 4.0) a una app con la API y los SDKs de Fiscalisto: timbrar facturas, pagos (PPD), notas de cr\u00E9dito, n\u00F3mina y retenciones, cancelar, webhooks. Use it whenever the user wants to issue Mexican invoices (CFDI, SAT, timbrado, factura electr\u00F3nica) or integrate Fiscalisto.";
8
+ export declare const AGENT_GUIDE = "# Facturar con Fiscalisto (CFDI 4.0)\n\nFiscalisto es una API REST que timbra comprobantes fiscales mexicanos (CFDI 4.0): revisa las reglas\ndel SAT antes de gastar un timbre, sella con el certificado del emisor y timbra con el PAC. Los\nnombres de la API est\u00E1n en ingl\u00E9s (`customer`, `items`, `unit_price`); la documentaci\u00F3n, los\nmensajes de error y los textos, en espa\u00F1ol (`Accept-Language: en` los da en ingl\u00E9s).\n\n- Base: `https://api.fiscalisto.com/v1`, JSON, `Authorization: Bearer <llave>`.\n- Llaves: `fk_test_\u2026` timbra en el ambiente de pruebas del SAT, gratis; `fk_live_\u2026` timbra CFDI\n reales y usa un timbre cada uno. Se crean en **Desarrolladores \u203A Llaves**.\n- Documentaci\u00F3n para agentes: https://fiscalisto.com/docs/api/llms.txt (\u00EDndice; cada p\u00E1gina tambi\u00E9n en `.md`), la\n referencia OpenAPI 3.1 en https://api.fiscalisto.com/v1/openapi.json y el servidor MCP\n https://fiscalisto.com/docs/api/mcp (sin llave) con search_docs, describe_operation, describe_object, explain_error y\n call_api.\n\n## Antes de escribir c\u00F3digo\n\n1. **La llave.** P\u00EDdasela a la persona y gu\u00E1rdela en `FISCALISTO_API_KEY` (en `.env`, nunca en el\n repositorio). Si no tiene: `npx fiscalisto login` abre el navegador y guarda su llave de\n pruebas; `npx fiscalisto init` instala el SDK y deja la llave en `.env`. Nunca invente una.\n2. **Sin llave todav\u00EDa:** `npx fiscalisto mock` levanta la API en http://127.0.0.1:12111, sin\n internet (`new Fiscalisto(\"fk_test_mock\", { baseUrl: \"http://127.0.0.1:12111\" })`). Contesta\n como la API pero no revisa reglas del SAT: pruebe despu\u00E9s con una `fk_test_`.\n3. **El SDK de su lenguaje** (los seis tienen cada ruta, tipos e Idempotency-Key autom\u00E1tica):\n\n| Lenguaje | Instalar | Cliente |\n| --- | --- | --- |\n| TypeScript / JavaScript | `npm install fiscalisto` | `new Fiscalisto()` |\n| Python | `pip install fiscalisto` | `Fiscalisto()` |\n| PHP | `composer require fiscalisto/fiscalisto` | `new Fiscalisto\\Fiscalisto()` |\n| Go | `go get fiscalisto.com/go` | `fiscalisto.NewClient(\"\")` |\n| Java | Maven `com.fiscalisto:fiscalisto` | `new FiscalistoClient()` |\n| C# / .NET | `dotnet add package Fiscalisto` | `new FiscalistoClient()` |\n\nSin argumento, cada cliente lee `FISCALISTO_API_KEY`. El c\u00F3digo de cada operaci\u00F3n en cada lenguaje:\n`describe_operation` del MCP (con `language`) o la p\u00E1gina `.md` de la referencia.\n\n## Timbrar una factura\n\n```ts\nimport { Fiscalisto } from \"fiscalisto\";\n\nconst fiscalisto = new Fiscalisto(); // FISCALISTO_API_KEY\n\nconst invoice = await fiscalisto.invoices.create(\n {\n customer: { tax_id: \"ICV060329BY0\", legal_name: \"INMOBILIARIA CVA\", tax_system: \"601\", zip: \"33826\" },\n payment_form: \"03\", // transferencia\n items: [{ description: \"Mensualidad\", product_key: \"86121700\", quantity: 2, unit_price: 2500 }],\n },\n { idempotencyKey: `pedido-${order.id}` },\n);\n// Guarde invoice.id (inv_\u2026) y invoice.uuid (el folio fiscal) con su pedido.\n```\n\n- **Idempotency-Key = el id de su pedido.** Si la respuesta se pierde, repetir con la misma nunca\n timbra dos veces. No use una al azar en cada intento.\n- **El cliente (Receptor) va exactamente como en su constancia de situaci\u00F3n fiscal:** RFC\n (`tax_id`), nombre sin r\u00E9gimen de capital (sin \u00ABS.A. de C.V.\u00BB), r\u00E9gimen (`tax_system`, c_RegimenFiscal)\n y c\u00F3digo postal (`zip`). Si su app no tiene esos datos, p\u00EDdalos con una liga\n (`POST /v1/customer_data_requests`) o rev\u00EDselos con `POST /v1/tax_ids/validate`; guarde clientes\n frecuentes con `/v1/customers` y mande su `cus_\u2026`.\n- Lo que omite toma el valor usual: PUE, MXN, uso G03 (S01 con r\u00E9gimen 616), objeto de impuesto 02,\n IVA 16 %, cantidad 1, unidad E48. `unit_price` es sin IVA, en pesos.\n- **Claves del SAT:** no las invente. B\u00FAsquelas en los cat\u00E1logos (`/v1/sat_catalogs/{name}`, por ejemplo\n `product_keys`) o guarde productos (`/v1/products`, `prd_\u2026`) con su clave.\n- **La respuesta** trae `status: \"valid\"` con UUID, PDF y XML. Si el PAC tarda llega\n `processing`: no repita con otra llave de idempotencia; espere el webhook `invoice.stamped`\n (o `invoice.failed`).\n- **PDF y XML:** `invoices.pdf(id)`, `invoices.xml(id)`; `invoices.send(id)` lo manda por correo.\n- **A cr\u00E9dito (PPD):** `payment_method: \"PPD\"`, `payment_form: \"99\"`; cada cobro lleva su\n complemento de pago (`POST /v1/payments`) a m\u00E1s tardar el d\u00EDa 5 del mes siguiente.\n- Otros comprobantes: notas de cr\u00E9dito (`/v1/credit_notes`), anticipos (`/v1/advances`), n\u00F3mina\n (`/v1/payroll_receipts`), retenciones (`/v1/retentions`), lotes de hasta 1,000\n (`/v1/invoice_batches`), factura global y autofactura por ticket (`/v1/tickets`).\n\n## Errores\n\nCada error trae `error.type`, `error.code`, `error.message` (en espa\u00F1ol) y `error.param` (el\ncampo a corregir). Un rechazo del SAT llega como `invoice_rejected` con su regla en\n`error.sat_code` (CFDI40\u2026): muestre el mensaje a la persona y corrija el dato; no reintente igual.\nEl SDK solo reintenta lo que es seguro repetir. `explain_error` del MCP dice qu\u00E9 hacer con cada\nc\u00F3digo; la lista completa est\u00E1 en https://fiscalisto.com/docs/api/errores.md.\n\n## Webhooks\n\nLo que pasa despu\u00E9s (timbrado tard\u00EDo, cancelaci\u00F3n aceptada d\u00EDas despu\u00E9s, lotes) llega a su endpoint\ncomo evento firmado. Cr\u00E9elo en **Desarrolladores \u203A Webhooks** o con `POST /v1/webhook_endpoints`\ny guarde su secreto `whsec_\u2026` en `FISCALISTO_WEBHOOK_SECRET`.\n\n```ts\nimport { FiscalistoWebhookError, verifyWebhook } from \"fiscalisto\";\n\nexport async function POST(request: Request) {\n try {\n // El cuerpo tal como lleg\u00F3 (texto), sin interpretarlo antes.\n const event = await verifyWebhook(await request.text(), request.headers, process.env.FISCALISTO_WEBHOOK_SECRET!);\n if (event.type === \"invoice.stamped\") await marcarFacturado(event.data.object);\n return new Response(null, { status: 200 });\n } catch (error) {\n if (error instanceof FiscalistoWebhookError) return new Response(null, { status: 400 });\n throw error;\n }\n}\n```\n\nConteste 2xx r\u00E1pido y procese aparte; un evento puede llegar m\u00E1s de una vez: ignore el `evt_\u2026` que\nya proces\u00F3. En desarrollo, `npx fiscalisto listen --forward-to http://localhost:3000/webhooks` le\nreenv\u00EDa los eventos de pruebas y `npx fiscalisto trigger invoice.stamped` provoca uno.\n\n## Cancelar\n\n`invoices.cancel(id, { motive: \"02\" })`: 02 con errores y sin sustituir (el usual), 01 con errores y sustituida\n(`substitution: \"inv_\u2026\"`, o `invoices.substitute` timbra la nueva y cancela la anterior), 03 no\nse llev\u00F3 a cabo y 04 solo en una factura global (una venta se factur\u00F3 despu\u00E9s a nombre del\ncliente). Si el cliente debe aceptar llega\n`invoice.cancellation_pending` y despu\u00E9s `invoice.canceled` o `invoice.cancellation_rejected`.\n\n## Probar\n\n- Las llaves `fk_test_` aplican las mismas revisiones del SAT que producci\u00F3n; una cuenta nueva ya\n tiene un emisor de pruebas listo.\n- RFC de prueba que provocan cada rechazo del SAT (por ejemplo `NOM010101FK9` \u2192 `CFDI40145`):\n https://fiscalisto.com/docs/api/pruebas-y-produccion.md#provocar-cada-rechazo-del-sat.\n- `call_api` del MCP prueba un cuerpo real con la llave de pruebas antes de escribirlo en c\u00F3digo.\n- Pruebas autom\u00E1ticas: `POST /v1/test_data/reset` deja el modo de pruebas como nuevo.\n\n## Nunca\n\n- Poner la llave en el navegador o en una app m\u00F3vil: la API rechaza el navegador\n (`browser_not_supported`). Llame desde su servidor.\n- Usar una `fk_live_` para probar: timbra CFDI reales con valor fiscal.\n- Inventar folios, UUID, RFC, reg\u00EDmenes o claves del SAT: cons\u00FAltelos.\n\n## Pasar a producci\u00F3n\n\nEmisor real (`POST /v1/issuers`), su CSD (`/certificates`), la firma con e.firma del contrato\ncon el PAC (`/efirma`) o, m\u00E1s f\u00E1cil, una liga para que el due\u00F1o lo haga\n(`POST /v1/issuers/{id}/onboarding_links`); timbres en **Desarrolladores \u203A Timbres**; y la llave\n`fk_live_` en el servidor. Detalle: https://fiscalisto.com/docs/api/pruebas-y-produccion.md#pasar-a-produccion.\n";
9
+ /** The guide as an Agent Skill (agentskills.io): SKILL.md with its name and description. */
10
+ export declare const AGENT_SKILL: string;
@@ -0,0 +1,156 @@
1
+ /**
2
+ * How a coding agent adds Fiscalisto to an app, in one page: the Agent Skill that
3
+ * `fiscalisto init --agents` leaves in .claude/skills/fiscalisto/SKILL.md, the same text the site
4
+ * serves at https://fiscalisto.com/docs/api/SKILL.md and the docs MCP answers with get_started.
5
+ * Written by hand; keep it short (an agent reads all of it) and true to the docs it links.
6
+ */
7
+ const DOCS = "https://fiscalisto.com/docs/api";
8
+ export const AGENT_SKILL_DESCRIPTION = "Agregar facturación electrónica mexicana (CFDI 4.0) a una app con la API y los SDKs de Fiscalisto: timbrar facturas, pagos (PPD), notas de crédito, nómina y retenciones, cancelar, webhooks. Use it whenever the user wants to issue Mexican invoices (CFDI, SAT, timbrado, factura electrónica) or integrate Fiscalisto.";
9
+ export const AGENT_GUIDE = `# Facturar con Fiscalisto (CFDI 4.0)
10
+
11
+ Fiscalisto es una API REST que timbra comprobantes fiscales mexicanos (CFDI 4.0): revisa las reglas
12
+ del SAT antes de gastar un timbre, sella con el certificado del emisor y timbra con el PAC. Los
13
+ nombres de la API están en inglés (\`customer\`, \`items\`, \`unit_price\`); la documentación, los
14
+ mensajes de error y los textos, en español (\`Accept-Language: en\` los da en inglés).
15
+
16
+ - Base: \`https://api.fiscalisto.com/v1\`, JSON, \`Authorization: Bearer <llave>\`.
17
+ - Llaves: \`fk_test_…\` timbra en el ambiente de pruebas del SAT, gratis; \`fk_live_…\` timbra CFDI
18
+ reales y usa un timbre cada uno. Se crean en **Desarrolladores › Llaves**.
19
+ - Documentación para agentes: ${DOCS}/llms.txt (índice; cada página también en \`.md\`), la
20
+ referencia OpenAPI 3.1 en https://api.fiscalisto.com/v1/openapi.json y el servidor MCP
21
+ ${DOCS}/mcp (sin llave) con search_docs, describe_operation, describe_object, explain_error y
22
+ call_api.
23
+
24
+ ## Antes de escribir código
25
+
26
+ 1. **La llave.** Pídasela a la persona y guárdela en \`FISCALISTO_API_KEY\` (en \`.env\`, nunca en el
27
+ repositorio). Si no tiene: \`npx fiscalisto login\` abre el navegador y guarda su llave de
28
+ pruebas; \`npx fiscalisto init\` instala el SDK y deja la llave en \`.env\`. Nunca invente una.
29
+ 2. **Sin llave todavía:** \`npx fiscalisto mock\` levanta la API en http://127.0.0.1:12111, sin
30
+ internet (\`new Fiscalisto("fk_test_mock", { baseUrl: "http://127.0.0.1:12111" })\`). Contesta
31
+ como la API pero no revisa reglas del SAT: pruebe después con una \`fk_test_\`.
32
+ 3. **El SDK de su lenguaje** (los seis tienen cada ruta, tipos e Idempotency-Key automática):
33
+
34
+ | Lenguaje | Instalar | Cliente |
35
+ | --- | --- | --- |
36
+ | TypeScript / JavaScript | \`npm install fiscalisto\` | \`new Fiscalisto()\` |
37
+ | Python | \`pip install fiscalisto\` | \`Fiscalisto()\` |
38
+ | PHP | \`composer require fiscalisto/fiscalisto\` | \`new Fiscalisto\\Fiscalisto()\` |
39
+ | Go | \`go get fiscalisto.com/go\` | \`fiscalisto.NewClient("")\` |
40
+ | Java | Maven \`com.fiscalisto:fiscalisto\` | \`new FiscalistoClient()\` |
41
+ | C# / .NET | \`dotnet add package Fiscalisto\` | \`new FiscalistoClient()\` |
42
+
43
+ Sin argumento, cada cliente lee \`FISCALISTO_API_KEY\`. El código de cada operación en cada lenguaje:
44
+ \`describe_operation\` del MCP (con \`language\`) o la página \`.md\` de la referencia.
45
+
46
+ ## Timbrar una factura
47
+
48
+ \`\`\`ts
49
+ import { Fiscalisto } from "fiscalisto";
50
+
51
+ const fiscalisto = new Fiscalisto(); // FISCALISTO_API_KEY
52
+
53
+ const invoice = await fiscalisto.invoices.create(
54
+ {
55
+ customer: { tax_id: "ICV060329BY0", legal_name: "INMOBILIARIA CVA", tax_system: "601", zip: "33826" },
56
+ payment_form: "03", // transferencia
57
+ items: [{ description: "Mensualidad", product_key: "86121700", quantity: 2, unit_price: 2500 }],
58
+ },
59
+ { idempotencyKey: \`pedido-\${order.id}\` },
60
+ );
61
+ // Guarde invoice.id (inv_…) y invoice.uuid (el folio fiscal) con su pedido.
62
+ \`\`\`
63
+
64
+ - **Idempotency-Key = el id de su pedido.** Si la respuesta se pierde, repetir con la misma nunca
65
+ timbra dos veces. No use una al azar en cada intento.
66
+ - **El cliente (Receptor) va exactamente como en su constancia de situación fiscal:** RFC
67
+ (\`tax_id\`), nombre sin régimen de capital (sin «S.A. de C.V.»), régimen (\`tax_system\`, c_RegimenFiscal)
68
+ y código postal (\`zip\`). Si su app no tiene esos datos, pídalos con una liga
69
+ (\`POST /v1/customer_data_requests\`) o revíselos con \`POST /v1/tax_ids/validate\`; guarde clientes
70
+ frecuentes con \`/v1/customers\` y mande su \`cus_…\`.
71
+ - Lo que omite toma el valor usual: PUE, MXN, uso G03 (S01 con régimen 616), objeto de impuesto 02,
72
+ IVA 16 %, cantidad 1, unidad E48. \`unit_price\` es sin IVA, en pesos.
73
+ - **Claves del SAT:** no las invente. Búsquelas en los catálogos (\`/v1/sat_catalogs/{name}\`, por ejemplo
74
+ \`product_keys\`) o guarde productos (\`/v1/products\`, \`prd_…\`) con su clave.
75
+ - **La respuesta** trae \`status: "valid"\` con UUID, PDF y XML. Si el PAC tarda llega
76
+ \`processing\`: no repita con otra llave de idempotencia; espere el webhook \`invoice.stamped\`
77
+ (o \`invoice.failed\`).
78
+ - **PDF y XML:** \`invoices.pdf(id)\`, \`invoices.xml(id)\`; \`invoices.send(id)\` lo manda por correo.
79
+ - **A crédito (PPD):** \`payment_method: "PPD"\`, \`payment_form: "99"\`; cada cobro lleva su
80
+ complemento de pago (\`POST /v1/payments\`) a más tardar el día 5 del mes siguiente.
81
+ - Otros comprobantes: notas de crédito (\`/v1/credit_notes\`), anticipos (\`/v1/advances\`), nómina
82
+ (\`/v1/payroll_receipts\`), retenciones (\`/v1/retentions\`), lotes de hasta 1,000
83
+ (\`/v1/invoice_batches\`), factura global y autofactura por ticket (\`/v1/tickets\`).
84
+
85
+ ## Errores
86
+
87
+ Cada error trae \`error.type\`, \`error.code\`, \`error.message\` (en español) y \`error.param\` (el
88
+ campo a corregir). Un rechazo del SAT llega como \`invoice_rejected\` con su regla en
89
+ \`error.sat_code\` (CFDI40…): muestre el mensaje a la persona y corrija el dato; no reintente igual.
90
+ El SDK solo reintenta lo que es seguro repetir. \`explain_error\` del MCP dice qué hacer con cada
91
+ código; la lista completa está en ${DOCS}/errores.md.
92
+
93
+ ## Webhooks
94
+
95
+ Lo que pasa después (timbrado tardío, cancelación aceptada días después, lotes) llega a su endpoint
96
+ como evento firmado. Créelo en **Desarrolladores › Webhooks** o con \`POST /v1/webhook_endpoints\`
97
+ y guarde su secreto \`whsec_…\` en \`FISCALISTO_WEBHOOK_SECRET\`.
98
+
99
+ \`\`\`ts
100
+ import { FiscalistoWebhookError, verifyWebhook } from "fiscalisto";
101
+
102
+ export async function POST(request: Request) {
103
+ try {
104
+ // El cuerpo tal como llegó (texto), sin interpretarlo antes.
105
+ const event = await verifyWebhook(await request.text(), request.headers, process.env.FISCALISTO_WEBHOOK_SECRET!);
106
+ if (event.type === "invoice.stamped") await marcarFacturado(event.data.object);
107
+ return new Response(null, { status: 200 });
108
+ } catch (error) {
109
+ if (error instanceof FiscalistoWebhookError) return new Response(null, { status: 400 });
110
+ throw error;
111
+ }
112
+ }
113
+ \`\`\`
114
+
115
+ Conteste 2xx rápido y procese aparte; un evento puede llegar más de una vez: ignore el \`evt_…\` que
116
+ ya procesó. En desarrollo, \`npx fiscalisto listen --forward-to http://localhost:3000/webhooks\` le
117
+ reenvía los eventos de pruebas y \`npx fiscalisto trigger invoice.stamped\` provoca uno.
118
+
119
+ ## Cancelar
120
+
121
+ \`invoices.cancel(id, { motive: "02" })\`: 02 con errores y sin sustituir (el usual), 01 con errores y sustituida
122
+ (\`substitution: "inv_…"\`, o \`invoices.substitute\` timbra la nueva y cancela la anterior), 03 no
123
+ se llevó a cabo y 04 solo en una factura global (una venta se facturó después a nombre del
124
+ cliente). Si el cliente debe aceptar llega
125
+ \`invoice.cancellation_pending\` y después \`invoice.canceled\` o \`invoice.cancellation_rejected\`.
126
+
127
+ ## Probar
128
+
129
+ - Las llaves \`fk_test_\` aplican las mismas revisiones del SAT que producción; una cuenta nueva ya
130
+ tiene un emisor de pruebas listo.
131
+ - RFC de prueba que provocan cada rechazo del SAT (por ejemplo \`NOM010101FK9\` → \`CFDI40145\`):
132
+ ${DOCS}/pruebas-y-produccion.md#provocar-cada-rechazo-del-sat.
133
+ - \`call_api\` del MCP prueba un cuerpo real con la llave de pruebas antes de escribirlo en código.
134
+ - Pruebas automáticas: \`POST /v1/test_data/reset\` deja el modo de pruebas como nuevo.
135
+
136
+ ## Nunca
137
+
138
+ - Poner la llave en el navegador o en una app móvil: la API rechaza el navegador
139
+ (\`browser_not_supported\`). Llame desde su servidor.
140
+ - Usar una \`fk_live_\` para probar: timbra CFDI reales con valor fiscal.
141
+ - Inventar folios, UUID, RFC, regímenes o claves del SAT: consúltelos.
142
+
143
+ ## Pasar a producción
144
+
145
+ Emisor real (\`POST /v1/issuers\`), su CSD (\`/certificates\`), la firma con e.firma del contrato
146
+ con el PAC (\`/efirma\`) o, más fácil, una liga para que el dueño lo haga
147
+ (\`POST /v1/issuers/{id}/onboarding_links\`); timbres en **Desarrolladores › Timbres**; y la llave
148
+ \`fk_live_\` en el servidor. Detalle: ${DOCS}/pruebas-y-produccion.md#pasar-a-produccion.
149
+ `;
150
+ /** The guide as an Agent Skill (agentskills.io): SKILL.md with its name and description. */
151
+ export const AGENT_SKILL = `---
152
+ name: fiscalisto
153
+ description: ${JSON.stringify(AGENT_SKILL_DESCRIPTION)}
154
+ ---
155
+
156
+ ${AGENT_GUIDE}`;
package/dist/cli.js CHANGED
@@ -15,6 +15,7 @@ import { homedir, hostname } from "node:os";
15
15
  import { dirname, join, resolve } from "node:path";
16
16
  import { createInterface } from "node:readline/promises";
17
17
  import { parseArgs } from "node:util";
18
+ import { AGENT_SKILL } from "./agent-guide.js";
18
19
  import { FiscalistoError, VERSION } from "./core.js";
19
20
  import { Fiscalisto } from "./index.js";
20
21
  import { createMock } from "./mock.js";
@@ -486,14 +487,18 @@ const AGENTS_SECTION = `
486
487
  ## Facturación (Fiscalisto)
487
488
 
488
489
  Facturas electrónicas (CFDI 4.0) con la API de Fiscalisto. La llave está en \`FISCALISTO_API_KEY\`
489
- (\`.env\`; \`fk_test_\` timbra en pruebas sin costo). Documentación completa para agentes:
490
- https://fiscalisto.com/docs/api/llms.txt y la referencia en https://api.fiscalisto.com/v1/openapi.json.
490
+ (\`.env\`; \`fk_test_\` timbra en pruebas sin costo). La guía de integración completa está en
491
+ \`.claude/skills/fiscalisto/SKILL.md\` (también en https://fiscalisto.com/docs/api/SKILL.md); el índice de la
492
+ documentación en https://fiscalisto.com/docs/api/llms.txt y el servidor MCP de la documentación, sin llave,
493
+ en https://fiscalisto.com/docs/api/mcp (empiece con get_started).
491
494
 
492
495
  - Use el SDK \`fiscalisto\` (npm, PyPI, Packagist, Go, Maven, NuGet). Cada timbrado lleva una Idempotency-Key
493
496
  (el id del pedido): repetirla nunca timbra dos veces.
494
497
  - El cliente va con su RFC, nombre, régimen y código postal exactamente como en su constancia.
498
+ - Llame a la API solo desde el servidor; verifique cada webhook con \`verifyWebhook\` y su secreto \`whsec_\`.
495
499
  - Para probar rechazos del SAT use los RFC de prueba (NOM010101FK9 y otros, ver "Pruebas y producción").
496
- - El CLI hace todo desde la terminal: \`npx fiscalisto --help\` (\`--json\` para leerlo).
500
+ - Sin internet o sin llave: \`npx fiscalisto mock\`. El CLI hace todo desde la terminal: \`npx fiscalisto --help\`
501
+ (\`--json\` para leerlo).
497
502
  `;
498
503
  async function init(args, g) {
499
504
  const { values } = parseArgs({
@@ -581,6 +586,12 @@ async function init(args, g) {
581
586
  await appendFile(agentsPath, AGENTS_SECTION);
582
587
  done.push(`${agentsPath.slice(dir.length + 1)}: cómo facturar, para su agente`);
583
588
  }
589
+ const skillPath = join(dir, ".claude", "skills", "fiscalisto", "SKILL.md");
590
+ if (!existsSync(skillPath)) {
591
+ await mkdir(dirname(skillPath), { recursive: true });
592
+ await writeFile(skillPath, AGENT_SKILL);
593
+ done.push(".claude/skills/fiscalisto/SKILL.md: la guía completa, para su agente");
594
+ }
584
595
  }
585
596
  print({ lang, dir, done, run: example.run }, () => {
586
597
  line(`${green("✓")} Listo para facturar (${lang}):`);
@@ -1269,7 +1280,7 @@ const HELP = `${bold("fiscalisto")} ${dim(VERSION)} · facturación electrónica
1269
1280
 
1270
1281
  ${bold("Empezar")}
1271
1282
  login [--live] [--key fk_…] Inicia sesión por el navegador y guarda su llave de pruebas
1272
- init [--lang node|python|php|go|dotnet|java] Deja el SDK, la llave en .env y un ejemplo en su proyecto (--agents: AGENTS.md)
1283
+ init [--lang node|python|php|go|dotnet|java] Deja el SDK, la llave en .env y un ejemplo en su proyecto (--agents: AGENTS.md y la guía para su agente)
1273
1284
  whoami Cuenta, modo, timbres y emisores
1274
1285
  logout Olvida las llaves en esta computadora
1275
1286
 
package/dist/core.d.ts CHANGED
@@ -4,7 +4,7 @@
4
4
  * llamar.
5
5
  */
6
6
  import type { ErrorCode } from "./error-codes.js";
7
- export declare const VERSION = "0.1.5";
7
+ export declare const VERSION = "0.1.6";
8
8
  /**
9
9
  * La versión de la API para la que se hizo este SDK: la manda en cada solicitud
10
10
  * (Fiscalisto-Version), así actualizar la API no cambia lo que recibe hasta que actualice el SDK.
package/dist/core.js CHANGED
@@ -3,7 +3,7 @@
3
3
  * errores y las listas que se recorren solas. Los recursos (generated.ts) solo dicen qué ruta
4
4
  * llamar.
5
5
  */
6
- export const VERSION = "0.1.5";
6
+ export const VERSION = "0.1.6";
7
7
  /**
8
8
  * La versión de la API para la que se hizo este SDK: la manda en cada solicitud
9
9
  * (Fiscalisto-Version), así actualizar la API no cambia lo que recibe hasta que actualice el SDK.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "fiscalisto",
3
- "version": "0.1.5",
3
+ "version": "0.1.6",
4
4
  "description": "SDK y CLI de la API de facturación electrónica (CFDI 4.0) de Fiscalisto, para TypeScript y JavaScript.",
5
5
  "keywords": [
6
6
  "cfdi",
@@ -9,7 +9,12 @@
9
9
  "sat",
10
10
  "mexico",
11
11
  "timbrado",
12
- "fiscalisto"
12
+ "fiscalisto",
13
+ "invoicing",
14
+ "e-invoicing",
15
+ "cfdi-4",
16
+ "mexico-invoicing",
17
+ "mcp"
13
18
  ],
14
19
  "homepage": "https://fiscalisto.com/docs/api/sdk",
15
20
  "repository": {