@developerx12/invoices-medusa 0.0.1

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.
Files changed (2) hide show
  1. package/README.md +259 -0
  2. package/package.json +81 -0
package/README.md ADDED
@@ -0,0 +1,259 @@
1
+ # @developerx12/invoices-medusa
2
+
3
+ A Medusa v2 plugin that automatically generates sequential PDF invoices for orders and credit notes for refunds. PDFs are uploaded to your private file storage bucket and served to customers and admins via presigned URLs.
4
+
5
+ ## Requirements
6
+
7
+ - Medusa `>= 2.4.0`
8
+ - A configured [File Module Provider](https://docs.medusajs.com/resources/infrastructure-modules/file) (e.g. S3/R2) with private bucket support
9
+
10
+ ## Installation
11
+
12
+ ```bash
13
+ pnpm add @developerx12/invoices-medusa
14
+ ```
15
+
16
+ ## Configuration
17
+
18
+ Register the plugin in `medusa-config.ts`:
19
+
20
+ ```ts
21
+ import { defineConfig } from "@medusajs/framework/utils"
22
+
23
+ export default defineConfig({
24
+ plugins: [
25
+ {
26
+ resolve: "@developerx12/invoices-medusa",
27
+ options: {
28
+ // Optional: locale to fall back to when order.metadata.locale is absent
29
+ // or not a supported value. Defaults to "nl".
30
+ defaultLocale: "en",
31
+
32
+ addressInfo: {
33
+ // Optional: SVG string or base64 data URL shown in the default header
34
+ companyLogo: "<svg>...</svg>",
35
+ // Optional: rendered width of the logo in points (default: 110)
36
+ companyLogoWidth: 110,
37
+
38
+ companyName: "Acme B.V.",
39
+
40
+ // Receives the i18n countries object for the resolved locale so you
41
+ // can include a translated country name in the address block.
42
+ address: (countries) =>
43
+ `Streetname 1\n1234 AB Amsterdam, ${countries.nl}`,
44
+
45
+ cocNumber: "12345678",
46
+ vatNumber: "NL123456789B01",
47
+ iban: "NL00BANK0123456789",
48
+ email: "billing@example.com",
49
+ },
50
+
51
+ // Optional: accent colors used in table headers
52
+ colors: {
53
+ background: "#004534", // header cell fill (default: #000)
54
+ text: "#ffffff", // header cell text (default: #fff)
55
+ },
56
+
57
+ // Optional: pdfmake Content rendered as the page header.
58
+ // Overrides the default logo header when provided.
59
+ header: {
60
+ table: {
61
+ widths: ["*"],
62
+ body: [[{ text: "Acme B.V.", fontSize: 18, alignment: "center" }]],
63
+ },
64
+ layout: "noBorders",
65
+ },
66
+
67
+ // Optional: pdfmake Content rendered as the page footer.
68
+ footer: {
69
+ table: {
70
+ widths: ["*"],
71
+ body: [[{ text: "acme.com", alignment: "center" }]],
72
+ },
73
+ layout: "noBorders",
74
+ },
75
+ },
76
+ },
77
+ ],
78
+ })
79
+ ```
80
+
81
+ ### Configuration reference
82
+
83
+ | Option | Type | Required | Description |
84
+ |---|---|---|---|
85
+ | `defaultLocale` | `Locale` | No | Fallback locale when `order.metadata.locale` is absent or invalid. Defaults to `"nl"`. |
86
+ | `addressInfo.companyName` | `string` | Yes | Company name shown on the invoice. |
87
+ | `addressInfo.address` | `(countries: Record<string, string>) => string` | Yes | Function returning the company address. Receives the i18n country name map for the resolved locale. |
88
+ | `addressInfo.cocNumber` | `string` | Yes | Chamber of Commerce number. |
89
+ | `addressInfo.vatNumber` | `string` | Yes | VAT registration number. |
90
+ | `addressInfo.iban` | `string` | Yes | Bank account number. |
91
+ | `addressInfo.email` | `string` | Yes | Billing contact e-mail. |
92
+ | `addressInfo.companyLogo` | `string` | No | SVG string or data URL used in the default header. |
93
+ | `addressInfo.companyLogoWidth` | `number` | No | Rendered logo width in points. |
94
+ | `colors.background` | `string` | No | Table header fill color (CSS hex). |
95
+ | `colors.text` | `string` | No | Table header text color (CSS hex). |
96
+ | `header` | `Content` | No | pdfmake content block rendered as page header. Replaces the default logo header. |
97
+ | `footer` | `Content` | No | pdfmake content block rendered as page footer. |
98
+
99
+ ## How it works
100
+
101
+ ### Invoice lifecycle
102
+
103
+ 1. **Fulfillment created** — the `order.fulfillment_created` subscriber fires `createInvoiceWorkflow`, which:
104
+ - Creates a **debit** invoice record with an auto-incremented `display_id`
105
+ - Links it to the order via the `invoice_order` link table
106
+ - Generates the PDF and uploads it to the **private** storage bucket
107
+ - Stores the file ID in `invoice.pdf_url`
108
+ 2. **Refund processed** — `createCreditInvoiceWorkflow` follows the same steps for a **credit** invoice, referencing the original debit invoice as its parent.
109
+ 3. **Download requested** — the API route resolves `invoice.pdf_url` to a presigned download URL via `fileModuleService.retrieveFile()` and streams the PDF. Invoices without a stored PDF (created before this feature) are generated on-demand as a fallback.
110
+
111
+ ### Invoice numbering
112
+
113
+ `display_id` is a PostgreSQL auto-increment sequence. Voided invoices (created by workflow compensation on failure) preserve their sequence number to avoid gaps.
114
+
115
+ ### Localization
116
+
117
+ The PDF language is determined by `order.metadata.locale`. The value is validated against the list of supported locales; if it is absent or unrecognised, `defaultLocale` from the plugin config is used.
118
+
119
+ Supported locales:
120
+
121
+ | Value | Language |
122
+ |---|---|
123
+ | `nl` | Dutch |
124
+ | `nl-be` | Dutch (Belgium) — uses Dutch translations |
125
+ | `en` | English |
126
+ | `de` | German |
127
+ | `fr` | French |
128
+ | `it` | Italian |
129
+
130
+ Set the locale on an order at creation time:
131
+
132
+ ```ts
133
+ await orderModuleService.updateOrders(orderId, {
134
+ metadata: { locale: "en" },
135
+ })
136
+ ```
137
+
138
+ ## API routes
139
+
140
+ ### Admin
141
+
142
+ ```
143
+ GET /admin/orders/:id/invoice/:invoice_id
144
+ ```
145
+
146
+ Requires admin authentication. Streams the invoice PDF for download.
147
+
148
+ ```
149
+ POST /admin/orders/:id/invoice/:invoice_id
150
+ ```
151
+
152
+ Requires admin authentication. Regenerates the invoice PDF.
153
+
154
+ ### Store
155
+
156
+ ```
157
+ GET /store/orders/:id/invoice
158
+ ```
159
+
160
+ Requires customer authentication. Returns the **debit** invoice PDF for the order. The order must belong to the authenticated customer.
161
+
162
+ ```
163
+ GET /store/orders/:id/credit-invoice
164
+ ```
165
+
166
+ Requires customer authentication. Returns the **credit** invoice PDF for the order. Returns 404 if no credit invoice exists.
167
+
168
+ ## Admin widget
169
+
170
+ The plugin includes an admin widget that displays on the order details page (`order.details.side.before` zone).
171
+
172
+ **Features:**
173
+ - Lists all invoices (debit and credit) for the order
174
+ - Shows invoice type with colored badges (gray for debit, green for credit)
175
+ - Download button fetches PDF via API and triggers browser download
176
+ - Refresh button regenerates the invoice PDF
177
+
178
+ ## Workflows
179
+
180
+ The workflows can be called directly from your own subscribers, jobs, or API routes.
181
+
182
+ ```ts
183
+ import {
184
+ createInvoiceWorkflow,
185
+ createCreditInvoiceWorkflow,
186
+ generateInvoicePdfWorkflow,
187
+ refreshInvoicePdfWorkflow,
188
+ } from "@developerx12/invoices-medusa/workflows"
189
+ ```
190
+
191
+ ### `createInvoiceWorkflow`
192
+
193
+ Creates a debit invoice, links it to an order, and generates + uploads the PDF.
194
+
195
+ ```ts
196
+ await createInvoiceWorkflow(container).run({
197
+ input: { order_id: "order_01J..." },
198
+ })
199
+ ```
200
+
201
+ ### `createCreditInvoiceWorkflow`
202
+
203
+ Creates a credit invoice for a refund.
204
+
205
+ ```ts
206
+ await createCreditInvoiceWorkflow(container).run({
207
+ input: {
208
+ order_id: "order_01J...",
209
+ resource_id: "refund_01J...", // refund ID used as resource_id
210
+ parent_invoice_id: "inv_01J...", // optional: the debit invoice this offsets
211
+ },
212
+ })
213
+ ```
214
+
215
+ ### `generateInvoicePdfWorkflow`
216
+
217
+ Generates an invoice PDF on-demand and returns it as a base64 string. Useful for attaching to notification emails.
218
+
219
+ ```ts
220
+ const { result } = await generateInvoicePdfWorkflow(container).run({
221
+ input: {
222
+ order_id: "order_01J...",
223
+ invoice_id: "inv_01J...", // optional; omit to generate the debit invoice
224
+ },
225
+ })
226
+
227
+ // result.fileName — e.g. "invoice-42.pdf"
228
+ // result.data — base64-encoded PDF
229
+ ```
230
+
231
+ ### `refreshInvoicePdfWorkflow`
232
+
233
+ Regenerates an existing invoice PDF and replaces the stored file.
234
+
235
+ ```ts
236
+ const { result } = await refreshInvoicePdfWorkflow(container).run({
237
+ input: {
238
+ order_id: "order_01J...",
239
+ invoice_id: "inv_01J...",
240
+ },
241
+ })
242
+
243
+ // result.file_id — the new file ID
244
+ ```
245
+
246
+ ## Backfill script
247
+
248
+ To generate and upload PDFs for invoices created before file storage was introduced:
249
+
250
+ ```bash
251
+ # Dry run (default) — shows what would be processed
252
+ pnpm medusa exec ./src/scripts/backfill-invoice-pdf-urls.ts
253
+
254
+ # Execute
255
+ pnpm medusa exec ./src/scripts/backfill-invoice-pdf-urls.ts -- dry_run=false
256
+
257
+ # Smaller batches if memory is a concern
258
+ pnpm medusa exec ./src/scripts/backfill-invoice-pdf-urls.ts -- dry_run=false batch_size=10
259
+ ```
package/package.json ADDED
@@ -0,0 +1,81 @@
1
+ {
2
+ "name": "@developerx12/invoices-medusa",
3
+ "version": "0.0.1",
4
+ "description": "Add invoices to Medusa v2",
5
+ "license": "MIT",
6
+ "files": [
7
+ ".medusa/server"
8
+ ],
9
+ "exports": {
10
+ "./package.json": "./package.json",
11
+ "./workflows": "./.medusa/server/src/workflows/index.js",
12
+ "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
13
+ "./modules/*": "./.medusa/server/src/modules/*/index.js",
14
+ "./modules/invoice/service": "./.medusa/server/src/modules/invoice/service.js",
15
+ "./providers/*": "./.medusa/server/src/providers/*/index.js",
16
+ "./types/*": "./.medusa/server/src/types/*/index.js",
17
+ "./links": "./.medusa/server/src/links/index.js",
18
+ "./admin": {
19
+ "import": "./.medusa/server/src/admin/index.mjs",
20
+ "require": "./.medusa/server/src/admin/index.js",
21
+ "default": "./.medusa/server/src/admin/index.js"
22
+ },
23
+ "./*": "./.medusa/server/src/*.js"
24
+ },
25
+ "keywords": [
26
+ "medusa-v2",
27
+ "medusa-plugin-integration",
28
+ "invoices",
29
+ "medusa-webbers"
30
+ ],
31
+ "scripts": {
32
+ "build": "npx medusa plugin:build",
33
+ "dev": "npx medusa plugin:develop",
34
+ "prepublishOnly": "npx medusa plugin:build"
35
+ },
36
+ "devDependencies": {
37
+ "@medusajs/admin-sdk": "^2.13.5",
38
+ "@medusajs/cli": "^2.13.5",
39
+ "@medusajs/framework": "^2.13.5",
40
+ "@medusajs/icons": "^2.13.5",
41
+ "@medusajs/medusa": "^2.13.5",
42
+ "@medusajs/test-utils": "^2.13.5",
43
+ "@medusajs/types": "^2.13.5",
44
+ "@medusajs/ui": "4.0.25",
45
+ "@swc/core": "^1.15.21",
46
+ "@types/node": "^20.19.37",
47
+ "@types/pdfmake": "^0.3.2",
48
+ "@types/react": "^18.3.2",
49
+ "@types/react-dom": "^18.2.25",
50
+ "prop-types": "^15.8.1",
51
+ "react": "^18.2.0",
52
+ "react-dom": "^18.2.0",
53
+ "ts-node": "^10.9.2",
54
+ "typescript": "^5.6.2",
55
+ "vite": "^5.2.11",
56
+ "yalc": "^1.0.0-pre.53"
57
+ },
58
+ "peerDependencies": {
59
+ "@medusajs/admin-sdk": "^2.13.3",
60
+ "@medusajs/cli": "^2.13.3",
61
+ "@medusajs/framework": "^2.13.3",
62
+ "@medusajs/icons": "^2.13.3",
63
+ "@medusajs/medusa": "^2.13.3",
64
+ "@medusajs/test-utils": "^2.13.3",
65
+ "@medusajs/ui": "4.0.25"
66
+ },
67
+ "engines": {
68
+ "node": ">=20"
69
+ },
70
+ "packageManager": "pnpm@10.33.0",
71
+ "dependencies": {
72
+ "@medusajs/admin-shared": "^2.13.5",
73
+ "@medusajs/dashboard": "^2.13.5",
74
+ "@medusajs/js-sdk": "^2.13.5",
75
+ "@tanstack/react-query": "5.64.2",
76
+ "date-fns": "^4.1.0",
77
+ "lodash.merge": "^4.6.2",
78
+ "pdfmake": "^0.3.7",
79
+ "react-i18next": "^15.7.4"
80
+ }
81
+ }