@codemind.ec/medusa-plugin-invoice 1.0.1 → 1.0.3

package/README.md

@@ -1,8 +1,7 @@
 # @codemind.ec/medusa-plugin-invoice
 
-Invoice & quotation **PDF widget** for the Medusa v2 admin dashboard — download order receipts and manage company billing configuration.
+Plugin de **facturación y cotización PDF** para Medusa v2 — genera facturas de pedido y proformas de cotización con plantillas HTML personalizables desde el admin.
 
-[![npm version](https://img.shields.io/npm/v/@codemind.ec/medusa-plugin-invoice.svg)](https://www.npmjs.com/package/@codemind.ec/medusa-plugin-invoice)
 [![Medusa v2](https://img.shields.io/badge/medusa-v2-blueviolet)](https://docs.medusajs.com)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
@@ -10,35 +9,35 @@ Invoice & quotation **PDF widget** for the Medusa v2 admin dashboard — downloa
 
 ## Features
 
-- **Order invoice widget** — "Download Receipt" button injected into the order detail sidebar in the Medusa admin.
-- **PDF generation** — fetches and downloads invoices as PDF files (`comprobante-pedido-{orderId}.pdf`).
-- **Invoice config page** — admin route for managing billing/invoicing settings.
-- **Medusa SDK integration** — uses the official `@medusajs/js-sdk` for authenticated API calls.
+- **Generación de PDFs** — facturas de pedido y proformas de cotización vía pdfmake + Handlebars.
+- **Plantillas HTML editables** — CRUD completo de plantillas con preview en tiempo real desde el admin.
+- **Configuración de empresa** — logo, RUC, dirección, teléfono, notas de pie de factura.
+- **Strategy Pattern** — cada tipo de documento (factura, proforma) tiene su propia estrategia extensible.
+- **Templates embebidos** — plantillas por defecto incluidas en el código; restaurables con un clic.
+- **Admin UI** — widget de descarga en pedidos, editor de plantillas con CodeMirror, página de configuración.
 
 ---
 
-## Prerequisites
+## Requisitos
 
-| Requirement | Version |
-|-------------|---------|
-| Node.js     | >= 20   |
-| Medusa      | >= 2.4.0 |
+| Requisito | Versión  |
+|-----------|----------|
+| Node.js   | >= 20    |
+| Medusa    | >= 2.13  |
 
 ---
 
-## Installation
+## Instalación
 
 ```bash
-npm install @codemind.ec/medusa-plugin-invoice
-# or
 pnpm add @codemind.ec/medusa-plugin-invoice
 ```
 
 ---
 
-## Configuration
+## Configuración
 
-Add the plugin to your `medusa-config.ts`:
+### 1. Registrar el plugin y módulo en `medusa-config.ts`
 
 ```typescript
 import { defineConfig } from "@medusajs/framework/utils"
@@ -51,63 +50,155 @@ export default defineConfig({
       options: {},
     },
   ],
+  modules: [
+    {
+      resolve: "@codemind.ec/medusa-plugin-invoice/modules/invoice-generator",
+      options: {},
+    },
+  ],
 })
 ```
 
-No environment variables are required. The admin widget uses `VITE_BACKEND_URL` if set, otherwise defaults to `"/"`.
+### 2. Variables de entorno (opcionales)
 
----
+El loader del módulo puede leer estas variables para configurar los valores iniciales de la empresa al crear la base de datos por primera vez:
 
-## Admin UI
+| Variable              | Descripción                        | Default        |
+|-----------------------|------------------------------------|----------------|
+| `STORE_NAME`          | Nombre de la empresa               | —              |
+| `STORE_ADDRESS`       | Dirección de la empresa            | —              |
+| `STORE_PHONE`         | Teléfono de la empresa             | —              |
+| `ADMIN_EMAIL`         | Email de notificaciones admin      | —              |
+| `MEDUSA_BACKEND_URL`  | URL base para embeber imágenes     | `http://localhost:9000` |
 
-### Order Invoice Widget
+Todos los valores se pueden editar después desde el admin.
 
-**Zone:** `order.details.side.before`
+---
 
-When viewing an order in the Medusa admin, a widget appears in the sidebar with a **"Descargar Comprobante"** (Download Receipt) button. Clicking it:
+## Arquitectura
 
-1. Calls `GET /admin/orders/{orderId}/invoices`
-2. Downloads the response as a PDF file
-3. Filename: `comprobante-pedido-{orderId}.pdf`
+```
+medusa-plugin-invoice/
+├── src/
+│   ├── admin/                          # UI del admin (widgets + rutas)
+│   │   ├── widgets/order-invoice.tsx   # Botón "Descargar comprobante" en pedidos
+│   │   └── routes/                     # Páginas de config y plantillas
+│   ├── api/                            # Rutas REST del plugin
+│   │   └── admin/
+│   │       ├── invoice-config/         # GET/POST configuración de empresa
+│   │       └── invoice-templates/      # CRUD de plantillas + preview + restore
+│   └── modules/
+│       └── invoice-generator/
+│           ├── models/                 # Invoice, InvoiceConfig, InvoiceTemplate
+│           ├── templates/
+│           │   ├── strategy.ts         # BaseDocumentStrategy + TemplateFactory
+│           │   ├── order-invoice.ts    # Estrategia de factura de pedido
+│           │   ├── quote-proforma.ts   # Estrategia de proforma de cotización
+│           │   └── defaults/index.ts   # HTML embebido de plantillas por defecto
+│           ├── loaders/                # Seed de config y plantillas iniciales
+│           ├── migrations/             # Migraciones de base de datos
+│           ├── service.ts              # InvoiceGeneratorService
+│           └── index.ts                # INVOICE_MODULE export
+└── index.d.ts                          # Declaraciones de tipos
+```
 
-### Invoice Configuration Page
+### Separación de responsabilidades
 
-**Route:** `/invoice-config`
+| Capa | Ubicación | Responsabilidad |
+|------|-----------|-----------------|
+| **Módulo** (modelos, servicio, migraciones, loader) | Plugin | Datos y lógica de dominio aislada |
+| **API routes** | Plugin | Endpoints CRUD del módulo (config, plantillas) |
+| **Admin UI** | Plugin | Widgets y páginas de administración |
+| **Workflows / Steps** | App (`apps/medusa/`) | Orquestación cross-module |
+| **Subscribers** | App (`apps/medusa/`) | Reacción a eventos del sistema |
 
-A dedicated admin page for managing company billing and invoicing settings.
+> **¿Por qué los workflows NO están en el plugin?**
+>
+> Los workflows son **orquestación cross-module** por naturaleza. Por ejemplo, `generate-invoice-pdf` consulta el módulo `order` (via query graph), resuelve países del módulo `country`, verifica metadata de cotizaciones desde tipos de la app, y *luego* llama al módulo invoice. Moverlos al plugin crearía dependencias circulares (plugin → app) y eliminaría la capacidad de la app de personalizar la orquestación. Esta es la convención recomendada por Medusa v2: los plugins exponen módulos + API, las apps controlan la orquestación.
 
 ---
 
-## Architecture
+## API Routes
+
+### Invoice Config
 
-This is an **admin-only** plugin — it does not register backend modules, API routes, or database models. It provides:
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `GET`  | `/admin/invoice-config` | Obtener configuración actual |
+| `POST` | `/admin/invoice-config` | Actualizar configuración |
 
-| Component | Location | Purpose |
-|-----------|----------|---------|
-| Order widget | `widgets/order-invoice.tsx` | PDF download button in order sidebar |
-| Config page | `routes/invoice-config/page.tsx` | Billing configuration UI |
-| SDK client | `lib/sdk.ts` | Authenticated Medusa client for API calls |
+### Invoice Templates
 
-The PDF generation endpoint (`/admin/orders/:id/invoices`) should be provided by your Medusa backend (e.g., via a custom API route or another plugin).
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `GET`    | `/admin/invoice-templates`              | Listar plantillas |
+| `POST`   | `/admin/invoice-templates`              | Crear plantilla |
+| `GET`    | `/admin/invoice-templates/:id`          | Obtener plantilla |
+| `POST`   | `/admin/invoice-templates/:id`          | Actualizar plantilla |
+| `DELETE` | `/admin/invoice-templates/:id`          | Eliminar plantilla (no defaults) |
+| `POST`   | `/admin/invoice-templates/:id/preview`  | Generar PDF de preview |
+| `POST`   | `/admin/invoice-templates/:id/restore`  | Restaurar HTML por defecto |
 
 ---
 
-## SDK Configuration
+## Uso desde la app
 
-The built-in SDK client is pre-configured for the admin:
+### Imports disponibles
 
 ```typescript
-import Medusa from "@medusajs/js-sdk"
+// Módulo y servicio
+import { INVOICE_MODULE, InvoiceGeneratorService } from "@codemind.ec/medusa-plugin-invoice"
+
+// Tipos de factura de pedido
+import type { InvoiceOrder, InvoiceLineItem, InvoiceOrderAddress, OrderInvoiceInput } from "@codemind.ec/medusa-plugin-invoice"
+
+// Tipos de proforma de cotización
+import type { QuoteProformaInput, ProformaConfigField, QuoteCustomerInfo, QuoteScheduleRules } from "@codemind.ec/medusa-plugin-invoice"
+
+// Enums
+import { InvoiceStatus, TemplateType } from "@codemind.ec/medusa-plugin-invoice"
+```
+
+### Generar un PDF desde un workflow/step
 
-const sdk = new Medusa({
-  baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
-  debug: import.meta.env.DEV,
-  auth: { type: "session" },
+```typescript
+const invoiceService = container.resolve<InvoiceGeneratorService>(INVOICE_MODULE)
+
+// Factura de pedido
+const pdfBuffer = await invoiceService.generatePdf({
+  template: "order_invoice",
+  data: { order, items, invoiceDisplayId: 1, created_at: "2025-01-01" },
+  invoice_id: "inv_01ABC...",
+})
+
+// Proforma de cotización
+const pdfBuffer = await invoiceService.generatePdf({
+  template: "quote_proforma",
+  data: { serviceType: "Catering", /* ... */ },
 })
 ```
 
 ---
 
+## Extensibilidad
+
+### Registrar una nueva estrategia de documento
+
+```typescript
+import { TemplateFactory, BaseDocumentStrategy } from "@codemind.ec/medusa-plugin-invoice"
+
+class MyCustomStrategy extends BaseDocumentStrategy<MyInput> {
+  async buildDocumentDefinition(input, config, htmlTemplate?) {
+    if (htmlTemplate) return this.renderHtmlTemplate(htmlTemplate, input)
+    // ... construir doc pdfmake programáticamente
+  }
+}
+
+TemplateFactory.register("my_custom_doc", MyCustomStrategy)
+```
+
+---
+
 ## License
 
 MIT — [CodeMind](https://codemind.ec)

package/index.d.ts

@@ -0,0 +1,138 @@
+declare module "@codemind.ec/medusa-plugin-invoice" {
+  export const INVOICE_MODULE: "invoiceGenerator"
+
+  export enum InvoiceStatus {
+    LATEST = "latest",
+    STALE = "stale",
+  }
+
+  export enum TemplateType {
+    ORDER_INVOICE = "order_invoice",
+    QUOTE_PROFORMA = "quote_proforma",
+  }
+
+  export interface InvoiceOrderAddress {
+    first_name?: string | null
+    last_name?: string | null
+    address_1?: string | null
+    address_2?: string | null
+    city?: string | null
+    province?: string | null
+    postal_code?: string | null
+    country_code?: string | null
+    phone?: string | null
+    metadata?: Record<string, unknown> | null
+  }
+
+  export interface InvoiceLineItem {
+    id: string
+    title: string
+    quantity: number
+    unit_price: number
+    subtotal?: number | null
+    variant_title?: string | null
+    variant?: { title?: string | null; product?: { title?: string | null } | null } | null
+    metadata?: Record<string, unknown> | null
+  }
+
+  export interface InvoiceOrder {
+    id: string
+    display_id?: number | null
+    email?: string | null
+    created_at: string | Date
+    currency_code?: string | null
+    total?: number | null
+    subtotal?: number | null
+    tax_total?: number | null
+    discount_total?: number | null
+    shipping_address?: InvoiceOrderAddress | null
+    billing_address?: InvoiceOrderAddress | null
+    shipping_methods?: Array<{ name?: string | null; amount?: number | null; shipping_option_id?: string | null }> | null
+    items?: InvoiceLineItem[] | null
+    metadata?: Record<string, unknown> | null
+  }
+
+  export interface OrderInvoiceInput {
+    order: InvoiceOrder
+    items: InvoiceLineItem[]
+    invoiceDisplayId: number
+    created_at: string
+  }
+
+  export interface ProformaConfigField {
+    label: string
+    value: string
+  }
+
+  export interface ProformaLineItem {
+    label: string
+    total: number
+  }
+
+  export interface QuoteCustomerInfo {
+    name: string
+    email: string
+    phone: string
+    cedula?: string
+    eventDate: string
+    eventTime: string
+    province?: string
+    city?: string
+    address?: string
+    addressDetails?: string
+  }
+
+  export interface QuoteScheduleRules {
+    minAdvanceDays: number
+    maxAdvanceDays: number
+    minEventTime: string
+    maxEventTime: string
+  }
+
+  export interface QuoteProformaInput {
+    serviceType: string
+    scheduleRules: QuoteScheduleRules
+    serviceName: string
+    configFields: ProformaConfigField[]
+    breakdown: ProformaLineItem[]
+    includes: string[]
+    customerInfo: QuoteCustomerInfo | null
+    totals: {
+      subtotal: number
+      extras: number
+      shipping?: number
+      discount?: number
+      taxes?: number
+      total: number
+    }
+    dateStr: string
+    quoteNumber: string
+    isHomeDelivery?: boolean
+  }
+
+  export type GeneratePdfParams =
+    | { template: "order_invoice"; data: OrderInvoiceInput }
+    | { template: "quote_proforma"; data: QuoteProformaInput }
+
+  export class InvoiceGeneratorService {
+    generatePdf(params: GeneratePdfParams & { invoice_id?: string }): Promise<Buffer>
+    listInvoiceConfigs(filters?: Record<string, unknown>): Promise<any[]>
+    updateInvoiceConfigs(data: Record<string, unknown>): Promise<any>
+    retrieveInvoiceConfig(id: string): Promise<any>
+    listInvoices(filters?: Record<string, unknown>): Promise<any[]>
+    updateInvoices(data: any): Promise<any>
+    createInvoices(data: Record<string, unknown>): Promise<any>
+    deleteInvoices(id: string): Promise<void>
+    retrieveInvoice(id: string): Promise<any>
+    listInvoiceTemplates(filters?: Record<string, unknown>): Promise<any[]>
+    createInvoiceTemplates(data: Record<string, unknown>): Promise<any>
+    updateInvoiceTemplates(data: Record<string, unknown>): Promise<any>
+    deleteInvoiceTemplates(id: string): Promise<void>
+    retrieveInvoiceTemplate(id: string): Promise<any>
+  }
+}
+
+declare module "@codemind.ec/medusa-plugin-invoice/modules/invoice-generator" {
+  export const INVOICE_MODULE: "invoiceGenerator"
+  export default object
+}

package/package.json

@@ -1,72 +1,93 @@
 {
-  "name": "@codemind.ec/medusa-plugin-invoice",
-  "version": "1.0.1",
-  "description": "Invoice & quotation PDF widget for Medusa v2 admin — download order receipts and manage company billing config.",
-  "author": "Kollor <dev@codemind.ec> (https://codemind.ec)",
-  "license": "MIT",
-  "files": [
-    ".medusa/server"
-  ],
-  "exports": {
-    "./package.json": "./package.json",
-    "./admin": {
-      "import": "./.medusa/server/src/admin/index.mjs",
-      "require": "./.medusa/server/src/admin/index.js",
-      "default": "./.medusa/server/src/admin/index.js"
+    "name": "@codemind.ec/medusa-plugin-invoice",
+    "version": "1.0.3",
+    "description": "Invoice & quotation PDF widget for Medusa v2 admin — download order receipts and manage company billing config.",
+    "author": "Kollor <dev@codemind.ec> (https://codemind.ec)",
+    "license": "MIT",
+    "files": [
+        ".medusa/server",
+        "index.d.ts"
+    ],
+    "types": "./index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./.medusa/server/src/index.js"
+        },
+        "./package.json": "./package.json",
+        "./modules/invoice-generator": {
+            "types": "./index.d.ts",
+            "default": "./.medusa/server/src/modules/invoice-generator/index.js"
+        },
+        "./modules/*": "./.medusa/server/src/modules/*/index.js",
+        "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+        "./admin": {
+            "import": "./.medusa/server/src/admin/index.mjs",
+            "require": "./.medusa/server/src/admin/index.js",
+            "default": "./.medusa/server/src/admin/index.js"
+        }
+    },
+    "keywords": [
+        "medusa",
+        "medusa-plugin",
+        "medusa-v2",
+        "plugin",
+        "invoice",
+        "pdf",
+        "comprobante",
+        "codemind",
+        "kollor"
+    ],
+    "scripts": {
+        "build": "medusa plugin:build",
+        "dev": "medusa plugin:develop",
+        "prepublishOnly": "medusa plugin:build"
+    },
+    "devDependencies": {
+        "@codemirror/lang-html": "^6.4.11",
+        "@codemirror/theme-one-dark": "^6.1.3",
+        "@medusajs/admin-sdk": "2.13.3",
+        "@medusajs/admin-shared": "2.13.3",
+        "@medusajs/cli": "2.13.3",
+        "@medusajs/framework": "2.13.3",
+        "@medusajs/icons": "^2.13.3",
+        "@medusajs/js-sdk": "^2.13.3",
+        "@medusajs/medusa": "2.13.3",
+        "@medusajs/test-utils": "2.13.3",
+        "@medusajs/ui": "^4.1.3",
+        "@swc/core": "^1.7.28",
+        "@tanstack/react-query": "^5.64.2",
+        "@types/jsdom": "^28.0.1",
+        "@types/node": "^20",
+        "@types/pdfmake": "^0.2.11",
+        "@types/react": "^18.3.3",
+        "@types/react-dom": "^18.3.0",
+        "@uiw/react-codemirror": "^4.25.8",
+        "handlebars": "^4.7.8",
+        "prop-types": "^15.8.1",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1",
+        "react-hook-form": "^7.54.2",
+        "ts-node": "^10.9.2",
+        "typescript": "^5",
+        "vite": "^5.4.14"
+    },
+    "dependencies": {
+        "axios": "^1.7.7",
+        "html-to-pdfmake": "^2.5.33",
+        "jsdom": "^29.0.1",
+        "pdfmake": "^0.2.20"
+    },
+    "peerDependencies": {
+        "@medusajs/admin-sdk": "2.13.3",
+        "@medusajs/cli": "2.13.3",
+        "@medusajs/framework": "2.13.3",
+        "@medusajs/icons": "^2.13.3",
+        "@medusajs/medusa": "2.13.3",
+        "@medusajs/test-utils": "2.13.3",
+        "@medusajs/ui": "^4.1.3"
+    },
+    "engines": {
+        "node": ">=20"
     }
-  },
-  "keywords": [
-    "medusa",
-    "medusa-plugin",
-    "medusa-v2",
-    "plugin",
-    "invoice",
-    "pdf",
-    "comprobante",
-    "codemind",
-    "kollor"
-  ],
-  "devDependencies": {
-    "@codemirror/lang-html": "^6.4.11",
-    "@codemirror/theme-one-dark": "^6.1.3",
-    "@medusajs/admin-sdk": "2.13.3",
-    "@medusajs/admin-shared": "2.13.3",
-    "@medusajs/cli": "2.13.3",
-    "@medusajs/framework": "2.13.3",
-    "@medusajs/icons": "^2.13.3",
-    "@medusajs/js-sdk": "^2.13.3",
-    "@medusajs/medusa": "2.13.3",
-    "@medusajs/test-utils": "2.13.3",
-    "@medusajs/ui": "^4.1.3",
-    "@swc/core": "^1.7.28",
-    "@tanstack/react-query": "^5.64.2",
-    "@types/node": "^20",
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "@uiw/react-codemirror": "^4.25.8",
-    "handlebars": "^4.7.8",
-    "prop-types": "^15.8.1",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "react-hook-form": "^7.54.2",
-    "ts-node": "^10.9.2",
-    "typescript": "^5",
-    "vite": "^5.4.14"
-  },
-  "peerDependencies": {
-    "@medusajs/admin-sdk": "2.13.3",
-    "@medusajs/cli": "2.13.3",
-    "@medusajs/framework": "2.13.3",
-    "@medusajs/icons": "^2.13.3",
-    "@medusajs/medusa": "2.13.3",
-    "@medusajs/test-utils": "2.13.3",
-    "@medusajs/ui": "^4.1.3"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "build": "medusa plugin:build",
-    "dev": "medusa plugin:develop"
-  }
-}
+}