@codemind.ec/medusa-plugin-invoice 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeMindEC
+
+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,204 @@
+# @codemind.ec/medusa-plugin-invoice
+
+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.
+
+[![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)
+
+---
+
+## Features
+
+- **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.
+
+---
+
+## Requisitos
+
+| Requisito | Versión  |
+|-----------|----------|
+| Node.js   | >= 20    |
+| Medusa    | >= 2.13  |
+
+---
+
+## Instalación
+
+```bash
+pnpm add @codemind.ec/medusa-plugin-invoice
+```
+
+---
+
+## Configuración
+
+### 1. Registrar el plugin y módulo en `medusa-config.ts`
+
+```typescript
+import { defineConfig } from "@medusajs/framework/utils"
+
+export default defineConfig({
+  // ...
+  plugins: [
+    {
+      resolve: "@codemind.ec/medusa-plugin-invoice",
+      options: {},
+    },
+  ],
+  modules: [
+    {
+      resolve: "@codemind.ec/medusa-plugin-invoice/modules/invoice-generator",
+      options: {},
+    },
+  ],
+})
+```
+
+### 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:
+
+| 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` |
+
+Todos los valores se pueden editar después desde el admin.
+
+---
+
+## Arquitectura
+
+```
+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
+```
+
+### Separación de responsabilidades
+
+| 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 |
+
+> **¿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.
+
+---
+
+## API Routes
+
+### Invoice Config
+
+| Método | Ruta | Descripción |
+|--------|------|-------------|
+| `GET`  | `/admin/invoice-config` | Obtener configuración actual |
+| `POST` | `/admin/invoice-config` | Actualizar configuración |
+
+### Invoice Templates
+
+| 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 |
+
+---
+
+## Uso desde la app
+
+### Imports disponibles
+
+```typescript
+// 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
+
+```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,14 +1,26 @@
 {
     "name": "@codemind.ec/medusa-plugin-invoice",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "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"
+        ".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",
@@ -32,6 +44,8 @@
         "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",
@@ -43,9 +57,13 @@
         "@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",
@@ -54,6 +72,12 @@
         "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",