medusa-import-product-plugin 0.0.4 → 0.0.5
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 +196 -64
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,64 +1,196 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
-
|
|
1
|
+
# Medusa Import Product Plugin
|
|
2
|
+
|
|
3
|
+
A Medusa v2 plugin for bulk CSV-based product import with support for images, variants, inventory, pricing, categories, collections, tags, and custom attributes.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **CSV Upload** — Drag-and-drop UI or direct API upload
|
|
8
|
+
- **Idempotent Import** — Matches products by handle/SKU; creates new or updates existing
|
|
9
|
+
- **Variants** — Multi-variant products from a single CSV row per variant
|
|
10
|
+
- **Images** — Downloads external image URLs and uploads to Medusa's file service
|
|
11
|
+
- **Categories & Collections** — Auto-creates missing categories and collections
|
|
12
|
+
- **Tags** — Auto-creates missing product tags (from `brand_tag` column)
|
|
13
|
+
- **Custom Attributes** — Supports product attributes via `@empty-complete-org/medusa-product-attributes`
|
|
14
|
+
- **Inventory** — Creates inventory items, levels, and attaches to variants
|
|
15
|
+
- **Pricing** — Sets base prices (currency: INR) and optional dealer prices via a price list
|
|
16
|
+
- **Sales Channel** — Optionally links all imported products to a sales channel
|
|
17
|
+
- **Job Management** — View import history, track progress, pause/resume/delete jobs
|
|
18
|
+
- **Admin UI** — Full admin pages for uploading and monitoring imports
|
|
19
|
+
|
|
20
|
+
## Installation
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
npm install medusa-import-product-plugin
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Configuration
|
|
27
|
+
|
|
28
|
+
Add the plugin to your `medusa-config.ts`:
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
import { defineConfig } from "@medusajs/framework/utils";
|
|
32
|
+
|
|
33
|
+
export default defineConfig({
|
|
34
|
+
plugins: [
|
|
35
|
+
{
|
|
36
|
+
resolve: "medusa-import-product-plugin",
|
|
37
|
+
options: {
|
|
38
|
+
upload_dir: "./uploads", // default: "./uploads"
|
|
39
|
+
price_list_id: "pl_xxx", // required for dealer prices
|
|
40
|
+
sales_channel_id: "sc_xxx", // optional sales channel link
|
|
41
|
+
},
|
|
42
|
+
},
|
|
43
|
+
],
|
|
44
|
+
});
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Options
|
|
48
|
+
|
|
49
|
+
| Option | Type | Required | Default | Description |
|
|
50
|
+
|--------|------|----------|---------|-------------|
|
|
51
|
+
| `upload_dir` | `string` | No | `"./uploads"` | Directory for uploaded CSV files |
|
|
52
|
+
| `price_list_id` | `string` | No | — | Medusa price list ID for dealer prices |
|
|
53
|
+
| `sales_channel_id` | `string` | No | — | Sales channel to link imported products |
|
|
54
|
+
|
|
55
|
+
## CSV Format
|
|
56
|
+
|
|
57
|
+
The CSV should contain one row per variant. Below is the expected column structure:
|
|
58
|
+
|
|
59
|
+
| Column | Required | Description |
|
|
60
|
+
|--------|----------|-------------|
|
|
61
|
+
| `title` | Yes | Product title |
|
|
62
|
+
| `description` | No | Product description |
|
|
63
|
+
| `subtitle` | No | Product subtitle |
|
|
64
|
+
| `category` | No | Comma-separated category names |
|
|
65
|
+
| `brand_tag` | No | Brand tag value (auto-created) |
|
|
66
|
+
| `images` | No | Space or comma-separated image URLs |
|
|
67
|
+
| `option_1_name`, `option_1_value` | No | Variant option (repeat for option_2, etc.) |
|
|
68
|
+
| `variant_sku` | Yes | Variant SKU |
|
|
69
|
+
| `variant_title` | No | Variant title |
|
|
70
|
+
| `price` | Yes | Base price (currency: INR) |
|
|
71
|
+
| `dealer_price` | No | Dealer price (requires `price_list_id` option) |
|
|
72
|
+
| `inventory_quantity` | No | Stock quantity (default: 0) |
|
|
73
|
+
| `attribute_1_name`, `attribute_1_value` | No | Custom attributes (repeat for attribute_2, etc.) |
|
|
74
|
+
|
|
75
|
+
## Usage
|
|
76
|
+
|
|
77
|
+
### Admin UI
|
|
78
|
+
|
|
79
|
+
Navigate to **Import Products** in the Medusa admin panel:
|
|
80
|
+
|
|
81
|
+
1. **Upload** — Drag & drop a CSV file or click to select
|
|
82
|
+
2. **Start Import** — Click "Start Import" to begin processing
|
|
83
|
+
3. **Monitor** — View progress bars, row-level status, and stats
|
|
84
|
+
4. **Pause/Resume/Delete** — Manage active or completed jobs
|
|
85
|
+
|
|
86
|
+
### API Endpoints
|
|
87
|
+
|
|
88
|
+
#### `GET /admin/import`
|
|
89
|
+
List all import jobs.
|
|
90
|
+
|
|
91
|
+
| Query | Type | Default | Description |
|
|
92
|
+
|-------|------|---------|-------------|
|
|
93
|
+
| `page` | number | 1 | Page number |
|
|
94
|
+
| `limit` | number | 20 | Items per page (max 100) |
|
|
95
|
+
|
|
96
|
+
#### `POST /admin/import`
|
|
97
|
+
Create a new import job. Accepts multipart form data with a `file` field (CSV, max 10MB).
|
|
98
|
+
|
|
99
|
+
#### `GET /admin/import/:id`
|
|
100
|
+
Get import job details including row-level results.
|
|
101
|
+
|
|
102
|
+
#### `DELETE /admin/import/:id`
|
|
103
|
+
Delete an import job (must be paused if currently processing).
|
|
104
|
+
|
|
105
|
+
#### `POST /admin/import/:id/pause`
|
|
106
|
+
Pause a running import job.
|
|
107
|
+
|
|
108
|
+
#### `POST /admin/import/:id/resume`
|
|
109
|
+
Resume a paused import job (re-runs the full workflow idempotently).
|
|
110
|
+
|
|
111
|
+
## Architecture
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
Upload CSV → API (multer) → Save to disk → Emit event
|
|
115
|
+
│
|
|
116
|
+
product-import.start
|
|
117
|
+
│
|
|
118
|
+
Subscriber runs
|
|
119
|
+
processImportWorkflow
|
|
120
|
+
│
|
|
121
|
+
┌───────────┼───────────┐
|
|
122
|
+
▼ ▼ ▼
|
|
123
|
+
Parse CSV Download Find or Create
|
|
124
|
+
Images Categories, Tags,
|
|
125
|
+
Collections
|
|
126
|
+
│ │ │
|
|
127
|
+
└───────────┼───────────┘
|
|
128
|
+
▼
|
|
129
|
+
┌───────────────────────┐
|
|
130
|
+
│ Create / Update │
|
|
131
|
+
│ Products + Variants │
|
|
132
|
+
└───────────────────────┘
|
|
133
|
+
│
|
|
134
|
+
┌───────────┼───────────┐
|
|
135
|
+
▼ ▼ ▼
|
|
136
|
+
Custom Inventory Price Sets
|
|
137
|
+
Attributes & Levels & Dealer Prices
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Workflow Steps
|
|
141
|
+
|
|
142
|
+
The import is orchestrated by the `processImportWorkflow` (defined in `src/workflows/process-import.ts`) with these steps:
|
|
143
|
+
|
|
144
|
+
1. **Parse CSV** — Read and validate the uploaded CSV file
|
|
145
|
+
2. **Download Images** — Fetch external URLs and upload to Medusa
|
|
146
|
+
3. **Resolve Tags** — Find or create brand tags
|
|
147
|
+
4. **Find or Create Categories** — Resolve category IDs
|
|
148
|
+
5. **Find or Create Collections** — Resolve collection IDs
|
|
149
|
+
6. **Match Existing Products** — Look up by handle and variant SKU
|
|
150
|
+
7. **Create/Update Products** — Idempotent upsert
|
|
151
|
+
8. **Re-fetch Products** — Get full data with relations
|
|
152
|
+
9. **Link to Sales Channel** — If configured
|
|
153
|
+
10. **Set Custom Attributes** — Create definitions and set values
|
|
154
|
+
11. **Manage Inventory** — Create items, levels, attach to variants
|
|
155
|
+
12. **Set Prices** — Create price sets and set base + dealer prices
|
|
156
|
+
|
|
157
|
+
## Types
|
|
158
|
+
|
|
159
|
+
### ImportJobStatus
|
|
160
|
+
|
|
161
|
+
| Status | Description |
|
|
162
|
+
|--------|-------------|
|
|
163
|
+
| `pending` | Job created, awaiting processing |
|
|
164
|
+
| `processing` | Workflow is actively running |
|
|
165
|
+
| `paused` | Workflow paused by user |
|
|
166
|
+
| `done` | Completed successfully |
|
|
167
|
+
| `failed` | Encountered an error |
|
|
168
|
+
|
|
169
|
+
### ImportRowStatus
|
|
170
|
+
|
|
171
|
+
| Status | Description |
|
|
172
|
+
|--------|-------------|
|
|
173
|
+
| `created` | Product was created |
|
|
174
|
+
| `updated` | Product was updated |
|
|
175
|
+
| `skipped` | Row was skipped |
|
|
176
|
+
| `failed` | Row encountered an error |
|
|
177
|
+
|
|
178
|
+
## Development
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
# Build the plugin
|
|
182
|
+
npm run build
|
|
183
|
+
|
|
184
|
+
# Development mode
|
|
185
|
+
npm run dev
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Requirements
|
|
189
|
+
|
|
190
|
+
- Node.js >= 20
|
|
191
|
+
- Medusa >= 2.4.0
|
|
192
|
+
- `@empty-complete-org/medusa-product-attributes` (peer dependency for custom attributes)
|
|
193
|
+
|
|
194
|
+
## License
|
|
195
|
+
|
|
196
|
+
MIT
|