@zaamx/netme-bundle 0.0.4 → 0.0.5

package/README.md

@@ -1,64 +1,459 @@
-<p align="center">
-  <a href="https://www.medusajs.com">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
-    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
-    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
-    </picture>
-  </a>
-</p>
-<h1 align="center">
-  Medusa Plugin Starter
-</h1>
+# @zaamx/netme-bundle
 
-<h4 align="center">
-  <a href="https://docs.medusajs.com">Documentation</a> |
-  <a href="https://www.medusajs.com">Website</a>
-</h4>
+A Medusa v2 plugin for creating and managing **product bundles** — linking a parent product to one or more child products with configurable quantities, pricing rules, and metadata.
 
-<p align="center">
-  Building blocks for digital commerce
-</p>
-<p align="center">
-  <a href="https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md">
-    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
-  </a>
-    <a href="https://www.producthunt.com/posts/medusa"><img src="https://img.shields.io/badge/Product%20Hunt-%231%20Product%20of%20the%20Day-%23DA552E" alt="Product Hunt"></a>
-  <a href="https://discord.gg/xpCwq3Kfn8">
-    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
-  </a>
-  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
-    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
-  </a>
-</p>
+**Version**: `0.0.4` | **License**: MIT | **Requires**: Medusa `>= 2.4.0` | **Node**: `>= 20`
 
-## Compatibility
+---
 
-This starter is compatible with versions >= 2.4.0 of `@medusajs/medusa`. 
+## Table of Contents
 
-## Getting Started
+- [Overview](#overview)
+- [Installation](#installation)
+- [Registration](#registration)
+- [Architecture](#architecture)
+- [Data Model](#data-model)
+- [Module](#module)
+- [Module Link](#module-link)
+- [Workflows](#workflows)
+- [API Reference](#api-reference)
+  - [Admin Routes](#admin-routes)
+  - [Store Routes](#store-routes)
+- [Admin UI](#admin-ui)
+- [Types](#types)
+- [Database Schema](#database-schema)
+- [Build & Development](#build--development)
 
-Visit the [Quickstart Guide](https://docs.medusajs.com/learn/installation) to set up a server.
+---
 
-Visit the [Plugins documentation](https://docs.medusajs.com/learn/fundamentals/plugins) to learn more about plugins and how to create them.
+## Overview
 
-Visit the [Docs](https://docs.medusajs.com/learn/installation#get-started) to learn more about our system requirements.
+`@zaamx/netme-bundle` adds full product bundle management to a Medusa v2 backend. It exposes:
 
-## What is Medusa
+- A **`bundle` module** with its own database table and service
+- A **module link** connecting Medusa's `ProductModule` to the `bundle` module
+- **Workflows** for creating, updating, and deleting bundles
+- **Admin REST API** routes for CRUD operations
+- **Store REST API** routes for storefront consumption and cart integration with dynamic pricing
+- An **Admin UI** page with full CRUD, infinite scroll product selection, and metadata management
 
-Medusa is a set of commerce modules and tools that allow you to build rich, reliable, and performant commerce applications without reinventing core commerce logic. The modules can be customized and used to build advanced ecommerce stores, marketplaces, or any product that needs foundational commerce primitives. All modules are open-source and freely available on npm.
+---
 
-Learn more about [Medusa’s architecture](https://docs.medusajs.com/learn/introduction/architecture) and [commerce modules](https://docs.medusajs.com/learn/fundamentals/modules/commerce-modules) in the Docs.
+## Installation
 
-## Community & Contributions
+```bash
+npm install @zaamx/netme-bundle
+# or
+yarn add @zaamx/netme-bundle
+```
 
-The community and core team are available in [GitHub Discussions](https://github.com/medusajs/medusa/discussions), where you can ask for support, discuss roadmap, and share ideas.
+---
 
-Join our [Discord server](https://discord.com/invite/medusajs) to meet other community members.
+## Registration
 
-## Other channels
+Add the plugin to your `medusa-config.ts`:
 
-- [GitHub Issues](https://github.com/medusajs/medusa/issues)
-- [Twitter](https://twitter.com/medusajs)
-- [LinkedIn](https://www.linkedin.com/company/medusajs)
-- [Medusa Blog](https://medusajs.com/blog/)
+```typescript
+import { defineConfig } from "@medusajs/framework/utils"
+
+export default defineConfig({
+  plugins: [
+    {
+      resolve: "@zaamx/netme-bundle",
+      options: {},
+    },
+  ],
+  // ...
+})
+```
+
+After registering, run database migrations:
+
+```bash
+npx medusa db:migrate
+```
+
+---
+
+## Architecture
+
+```
+@zaamx/netme-bundle
+├── modules/bundles          — Bundle data model, service, migrations
+├── links/product-bundle     — Module link: Product ↔ Bundle
+├── workflows/               — update-product-bundle, delete-product-bundle
+├── api/admin/               — Admin REST routes
+├── api/store/               — Store REST routes
+└── admin/                   — Admin dashboard UI (routes, components)
+```
+
+The plugin follows Medusa's modular architecture: the `bundle` module is isolated from the core `ProductModule` and connected via a module link. All write operations go through workflows that invoke the bundle service.
+
+---
+
+## Data Model
+
+**File**: `src/modules/bundles/models/bundle.ts`
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `id` | `TEXT` | — | Primary key, matches the associated product ID |
+| `child_products` | `JSONB` | `{"data":[]}` | Array of child product configurations |
+| `bundle_meta` | `JSONB` | `{"data":[]}` | Array of arbitrary key-value metadata pairs |
+| `is_bundle` | `BOOLEAN` | `false` | Whether this record represents an active bundle |
+| `created_at` | `TIMESTAMPTZ` | `now()` | Creation timestamp |
+| `updated_at` | `TIMESTAMPTZ` | `now()` | Last update timestamp |
+| `deleted_at` | `TIMESTAMPTZ` | `NULL` | Soft delete timestamp |
+
+An index `IDX_bundle_deleted_at` is created on `deleted_at` for efficient active-bundle queries.
+
+---
+
+## Module
+
+**File**: `src/modules/bundles/index.ts`
+
+```typescript
+export const BUNDLE_MODULE = "bundle"
+export default Module(BUNDLE_MODULE, { service: BundleService })
+```
+
+### BundleService
+
+Extends `MedusaService` with the `Bundle` model. Inherits CRUD methods:
+
+| Method | Description |
+|---|---|
+| `listBundles(filters?, config?)` | List bundles with optional filters |
+| `createBundles(data)` | Create one or more bundles |
+| `updateBundles(data)` | Update one or more bundles |
+| `deleteBundles(ids)` | Soft-delete bundles by ID |
+| `attachBundleToProduct(productId)` | Retrieve bundle data for a product with `child_products` relation |
+
+---
+
+## Module Link
+
+**File**: `src/links/product-bundle.ts`
+
+```typescript
+export default defineLink(
+  ProductModule.linkable.product,
+  BundleModule.linkable.bundle
+)
+```
+
+This link associates each bundle record with a Medusa product while keeping both modules independent. It enables querying products with their bundle data through Medusa's query layer.
+
+---
+
+## Workflows
+
+### `updateProductBundle`
+
+**File**: `src/workflows/update-product-bundle.ts`
+
+Creates or updates a bundle for a given product.
+
+**Input** (`UpdateProductBundleInput`):
+
+```typescript
+{
+  product_id: string
+  is_bundle?: boolean
+  child_product_ids?: Array<{
+    id: string
+    min_quantity?: number
+    max_quantity?: number
+    default_quantity?: number
+    optional?: boolean
+    separate_shipping?: boolean
+    individual_price?: boolean
+  }>
+  bundle_meta?: Array<{
+    key: string
+    value: string
+  }>
+}
+```
+
+**Steps**:
+1. Resolve bundle and product services via `MedusaModules`
+2. Check if a bundle already exists for `product_id`
+3. If none exists and `is_bundle=true`: create a new bundle record
+4. If one exists: update with the provided fields
+5. Return the product with enriched bundle data
+
+---
+
+### `deleteProductBundle`
+
+**File**: `src/workflows/delete-product-bundle.ts`
+
+Removes the bundle association from a product.
+
+**Input** (`DeleteProductBundleInput`):
+
+```typescript
+{
+  product_id: string
+}
+```
+
+**Steps**:
+1. Find the bundle record linked to `product_id`
+2. Delete it if found
+3. Return the updated product
+
+---
+
+## API Reference
+
+### Admin Routes
+
+All admin routes are authenticated and accessible under `/admin/`.
+
+---
+
+#### `GET /admin/bundled-products`
+
+Returns all bundled products with enriched child product data.
+
+**Query params**: `limit`, `offset`
+
+**Response**:
+```json
+{
+  "bundled_products": [
+    {
+      "id": "bundle_01J...",
+      "title": "Product Title",
+      "product": { "id": "prod_01J..." },
+      "items": [
+        {
+          "id": "prod_child_01J...",
+          "product": { "id": "prod_01J...", "title": "Child Title" },
+          "quantity": 1,
+          "min_quantity": 1,
+          "max_quantity": 5,
+          "optional": false,
+          "separate_shipping": false,
+          "individual_price": false
+        }
+      ],
+      "bundle_meta": [{ "key": "promo", "value": "summer" }],
+      "is_bundle": true,
+      "created_at": "2025-01-01T00:00:00Z",
+      "updated_at": "2025-01-01T00:00:00Z"
+    }
+  ],
+  "count": 10,
+  "limit": 15,
+  "offset": 0
+}
+```
+
+---
+
+#### `POST /admin/bundled-products`
+
+Creates a new bundled product.
+
+**Body**: `UpdateProductBundleInput` (see [Workflows](#workflows))
+
+---
+
+#### `GET /admin/products/:id/bundle`
+
+Retrieves bundle data for a specific product.
+
+**Response**: Bundle object for the product, or empty if none.
+
+---
+
+#### `POST /admin/products/:id/bundle`
+
+Creates or replaces the bundle for a product. Always deletes the existing bundle first, then applies the new configuration.
+
+**Body**: `UpdateProductBundleInput`
+
+---
+
+#### `DELETE /admin/products/:id/bundle`
+
+Removes the bundle from a product.
+
+---
+
+#### `GET /admin/plugin`
+
+Health check. Returns HTTP 200.
+
+---
+
+### Store Routes
+
+Unauthenticated routes for the storefront.
+
+---
+
+#### `GET /store/products/:id/bundle`
+
+Returns the bundle configuration for a product, with enriched child product data.
+
+**Response**: Same structure as the admin single-product bundle endpoint.
+
+---
+
+#### `POST /store/carts/:id/bundle-line-items`
+
+Adds items to a cart with bundle-aware dynamic pricing.
+
+**Body**:
+```typescript
+{
+  items: Array<{
+    variant_id: string
+    quantity: number
+    unit_price?: number
+    metadata?: {
+      bundle_id?: string
+      bundled_by?: string           // if set → price = 0.001 (free)
+      bundle_sticks_price?: {
+        nuevoPrecioPaquete: number  // if set → use this price
+      }
+      price_rules?: {
+        nuevoPrecio: number         // if set → use this price
+      }
+    }
+  }>
+}
+```
+
+**Pricing logic** (applied per item):
+
+| Condition | Price Applied |
+|---|---|
+| `metadata.bundled_by` is set | `0.001` (effectively free child item) |
+| `metadata.bundle_sticks_price` is set | `bundle_sticks_price.nuevoPrecioPaquete` |
+| `metadata.price_rules` is set | `price_rules.nuevoPrecio` |
+| None of the above | Default Medusa pricing |
+
+---
+
+#### `GET /store/plugin`
+
+Health check. Returns HTTP 200.
+
+---
+
+## Admin UI
+
+The plugin registers a custom page in the Medusa Admin dashboard.
+
+### Bundled Products Page
+
+**Route**: `/bundled-products` (sidebar entry with a cube icon, label "Bundled Products")
+
+**Features**:
+
+| Feature | Details |
+|---|---|
+| Bundle list | Table with columns: ID, Title, Items count, Product link, Status |
+| Pagination | 15 items per page |
+| Create bundle | Modal with product selector and item configuration |
+| Edit bundle | Same modal, product selector disabled during edit |
+| Delete bundle | Confirmation + API call |
+| Infinite scroll | Product selector loads products incrementally via Intersection Observer |
+| Bundle metadata | Key-value pairs, add/remove dynamically |
+
+### Per-Item Configuration (in Create/Edit modal)
+
+Each child product entry in a bundle supports:
+
+- Product selector (dropdown with search, infinite scroll)
+- `min_quantity`, `max_quantity`, `default_quantity` number inputs
+- Toggle: `optional`
+- Toggle: `separate_shipping`
+- Toggle: `individual_price`
+- Remove button
+
+---
+
+## Types
+
+```typescript
+// Child product configuration stored in bundle.child_products
+type ChildProductConfig = {
+  id: string
+  min_quantity?: number
+  max_quantity?: number
+  default_quantity?: number
+  optional?: boolean
+  separate_shipping?: boolean
+  individual_price?: boolean
+}
+
+// Key-value metadata stored in bundle.bundle_meta
+type BundleMeta = {
+  key: string
+  value: string
+}
+
+// Input for create/update workflow
+type UpdateProductBundleInput = {
+  product_id: string
+  is_bundle?: boolean
+  child_product_ids?: ChildProductConfig[]
+  bundle_meta?: BundleMeta[]
+}
+
+// Input for delete workflow
+type DeleteProductBundleInput = {
+  product_id: string
+}
+```
+
+---
+
+## Database Schema
+
+Migration: `src/modules/bundles/migrations/Migration20241229065751.ts`
+
+```sql
+CREATE TABLE IF NOT EXISTS "bundle" (
+  "id"              TEXT        NOT NULL,
+  "child_products"  JSONB       NOT NULL DEFAULT '{"data":[]}',
+  "bundle_meta"     JSONB       NOT NULL DEFAULT '{"data":[]}',
+  "is_bundle"       BOOLEAN     NOT NULL DEFAULT false,
+  "created_at"      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updated_at"      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "deleted_at"      TIMESTAMPTZ          DEFAULT NULL,
+  CONSTRAINT "bundle_pkey" PRIMARY KEY ("id")
+);
+
+CREATE INDEX IF NOT EXISTS "IDX_bundle_deleted_at"
+  ON "bundle" ("deleted_at");
+```
+
+---
+
+## Build & Development
+
+**Scripts**:
+
+| Command | Description |
+|---|---|
+| `yarn build` | Build plugin for production (`medusa plugin:build`) |
+| `yarn dev` | Start plugin in development mode (`medusa plugin:develop`) |
+
+**Output directory**: `.medusa/server/`
+
+**Package exports** (from built output):
+
+| Export | Path |
+|---|---|
+| `@zaamx/netme-bundle/workflows` | `.medusa/server/src/workflows/index.js` |
+| `@zaamx/netme-bundle/modules/*` | `.medusa/server/src/modules/*/index.js` |
+| `@zaamx/netme-bundle/admin` | `.medusa/server/src/admin/index.mjs` |
+| `@zaamx/netme-bundle/*` | `.medusa/server/src/*.js` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaamx/netme-bundle",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "A starter for Medusa plugins.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",