@lodashventure/medusa-product-content 1.1.0

package/README.md

@@ -0,0 +1,202 @@
+# Medusa Product Content Plugin
+
+Enhanced product content management with rich text editor and i18n specifications for Medusa Admin.
+
+## Features
+
+- **Rich Text Editor**: TipTap-based editor for long product descriptions
+- **i18n Specifications**: Multilingual key-value product specifications
+- **Version History**: Automatic versioning of content changes
+- **Import/Export**: CSV/JSON import and export for specifications
+- **SEO-Friendly**: HTML sanitization and auto-excerpt generation
+- **Drag & Drop**: Reorder specification groups and items
+- **Locale Support**: Full internationalization support
+
+## Installation
+
+```bash
+npm install @medusajs/admin-product-content
+# or
+yarn add @medusajs/admin-product-content
+```
+
+## Configuration
+
+Add the plugin to your `medusa-config.js`:
+
+```js
+module.exports = {
+  // ... other config
+  plugins: [
+    {
+      resolve: '@medusajs/admin-product-content',
+      options: {
+        locales: [
+          { code: 'th-TH', label: 'ไทย', isDefault: true },
+          { code: 'en-US', label: 'English' }
+        ],
+        defaultLocale: 'th-TH',
+        versioning: {
+          enabled: true,
+          maxVersions: 10
+        }
+      }
+    }
+  ]
+}
+```
+
+## Usage
+
+### Admin Interface
+
+1. Navigate to any product in Medusa Admin
+2. Find the "Product Content" widget on the product detail page
+3. Click "Manage Content" to open the content editor
+4. Use the tabs to manage:
+   - **Overview**: View product information and content status
+   - **Long Description**: Edit rich text content
+   - **Specifications**: Manage i18n product specs
+   - **Versions**: View and restore content history
+
+### Storefront Integration
+
+Fetch product content via the Store API:
+
+```js
+// Fetch product with metadata
+const product = await fetch('/store/products/prod_123?expand=metadata')
+  .then(res => res.json())
+
+// Access long description
+const longDescription = product.metadata?.long_description
+
+// Access specifications
+const specs = product.metadata?.specs
+
+// Helper function for locale fallback
+function getSpecValue(item, locale, fallbackLocale) {
+  return item.i18n[locale]?.value ||
+         item.i18n[fallbackLocale]?.value ||
+         ''
+}
+```
+
+## Data Structure
+
+### Long Description
+
+```json
+{
+  "metadata": {
+    "long_description": {
+      "html": "<h1>Product Title</h1><p>...</p>",
+      "richjson": { /* TipTap JSON */ },
+      "locale": "th-TH",
+      "updated_at": "2025-01-01T00:00:00Z",
+      "updated_by": "user@example.com"
+    }
+  }
+}
+```
+
+### Specifications
+
+```json
+{
+  "metadata": {
+    "specs": {
+      "default_locale": "th-TH",
+      "groups": [
+        {
+          "key": "electrical",
+          "position": 1,
+          "i18n": {
+            "th-TH": { "label": "ข้อมูลไฟฟ้า" },
+            "en-US": { "label": "Electrical" }
+          },
+          "items": [
+            {
+              "position": 1,
+              "i18n": {
+                "th-TH": { "key": "กำลังไฟ", "value": "18 วัตต์" },
+                "en-US": { "key": "Power", "value": "18 W" }
+              },
+              "visible": true
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+## Import/Export
+
+### CSV Format
+
+```csv
+group_key,group_position,group_label.th-TH,group_label.en-US,item_position,key.th-TH,value.th-TH,key.en-US,value.en-US,visible
+electrical,1,ข้อมูลไฟฟ้า,Electrical,1,กำลังไฟ,18 วัตต์,Power,18 W,true
+electrical,1,ข้อมูลไฟฟ้า,Electrical,2,ความสว่าง,1800 ลูเมน,Brightness,1800 lm,true
+```
+
+### JSON Format
+
+Export and import full specification structure as JSON for complete data preservation.
+
+## API
+
+### Hooks
+
+```typescript
+import { useProductContent } from '@medusajs/admin-product-content'
+
+const {
+  product,
+  longDescription,
+  specs,
+  versions,
+  updateLongDescription,
+  updateSpecs,
+  restoreVersion
+} = useProductContent({ productId: 'prod_123' })
+```
+
+### Utilities
+
+```typescript
+import {
+  sanitizeHTML,
+  generateExcerpt,
+  localeUtils,
+  getLocalizedSpec
+} from '@medusajs/admin-product-content'
+
+// Sanitize HTML
+const clean = sanitizeHTML(dirtyHtml)
+
+// Generate excerpt
+const excerpt = generateExcerpt(html, 160)
+
+// Get localized value
+const value = getLocalizedSpec(item, 'en-US', 'th-TH', 'value')
+
+// Calculate completeness
+const completeness = localeUtils.calculateLocaleCompleteness(specs, 'en-US')
+```
+
+## Security
+
+- All HTML content is sanitized using DOMPurify
+- Scripts and dangerous attributes are removed
+- Only admin users with `product:update` permission can edit content
+
+## License
+
+MIT
+
+## Support
+
+For issues and feature requests, please visit the [GitHub repository](https://github.com/medusajs/admin-product-content).

package/dist/admin/hooks/useProductContent.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Custom hook for product content management
+ */
+import { ProductContentMetadata, LongDescription, LongDescriptionVersion, ProductSpecs } from "../../types";
+export interface UseProductContentOptions {
+    productId: string;
+    maxVersions?: number;
+    autoSanitize?: boolean;
+}
+export interface UseProductContentReturn {
+    product: any;
+    isLoading: boolean;
+    error: Error | null;
+    metadata: ProductContentMetadata;
+    longDescription: LongDescription | null;
+    specs: ProductSpecs | null;
+    versions: LongDescriptionVersion[];
+    updateLongDescription: (html: string, richjson?: any, locale?: string) => Promise<void>;
+    updateSpecs: (specs: ProductSpecs) => Promise<void>;
+    createVersion: (description: LongDescription) => Promise<void>;
+    restoreVersion: (version: number) => Promise<void>;
+    deleteVersion: (version: number) => Promise<void>;
+    updateMetadata: (updates: Partial<ProductContentMetadata>) => Promise<void>;
+}
+export declare function useProductContent(options: UseProductContentOptions): UseProductContentReturn;

package/dist/admin/hooks/useProductContent.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Custom hook for product content management
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useProductContent = useProductContent;
+const react_1 = require("react");
+const react_query_1 = require("@tanstack/react-query");
+const sdk_1 = require("../lib/sdk");
+const sanitize_1 = require("../utils/sanitize");
+function useProductContent(options) {
+    const { productId, maxVersions = 10, autoSanitize = true } = options;
+    // Fetch product with expanded metadata
+    const { data: product, isLoading, error, } = (0, react_query_1.useQuery)({
+        queryKey: ["product", productId],
+        queryFn: async () => {
+            const response = await sdk_1.sdk.admin.product.retrieve(productId, {
+                fields: "*variants,*variants.prices,*variants.options,*options,*images,*collection,*categories,*metadata,*tags",
+            });
+            return response.product;
+        },
+    });
+    // Update mutation
+    const updateProduct = (0, react_query_1.useMutation)({
+        mutationFn: async (data) => {
+            return await sdk_1.sdk.admin.product.update(productId, data);
+        },
+    });
+    // Extract metadata
+    const metadata = (0, react_1.useMemo)(() => {
+        if (!product || !product.metadata)
+            return {};
+        return product.metadata;
+    }, [product]);
+    const longDescription = (0, react_1.useMemo)(() => {
+        return metadata.long_description || null;
+    }, [metadata.long_description]);
+    const specs = (0, react_1.useMemo)(() => {
+        return metadata.specs || null;
+    }, [metadata.specs]);
+    const versions = (0, react_1.useMemo)(() => {
+        return metadata.long_description_versions || [];
+    }, [metadata.long_description_versions]);
+    // Update long description
+    const updateLongDescription = (0, react_1.useCallback)(async (html, richjson, locale = "th-TH") => {
+        const sanitizedHtml = autoSanitize ? (0, sanitize_1.sanitizeHTML)(html) : html;
+        const newDescription = {
+            html: sanitizedHtml,
+            richjson,
+            locale,
+            updated_at: new Date().toISOString(),
+            updated_by: "current_user", // TODO: Get from auth context
+        };
+        // Create version if exists
+        let newVersions = [...versions];
+        if (longDescription) {
+            const version = {
+                ...longDescription,
+                version: versions.length + 1,
+                created_at: longDescription.updated_at || new Date().toISOString(),
+            };
+            newVersions = [version, ...versions].slice(0, maxVersions);
+        }
+        await updateProduct.mutateAsync({
+            metadata: {
+                ...metadata,
+                long_description: newDescription,
+                long_description_versions: newVersions,
+                content_last_updated: new Date().toISOString(),
+                content_updated_by: "current_user",
+            },
+        });
+    }, [
+        autoSanitize,
+        longDescription,
+        maxVersions,
+        metadata,
+        updateProduct,
+        versions,
+    ]);
+    // Update specifications
+    const updateSpecs = (0, react_1.useCallback)(async (newSpecs) => {
+        await updateProduct.mutateAsync({
+            metadata: {
+                ...metadata,
+                specs: newSpecs,
+                content_last_updated: new Date().toISOString(),
+                content_updated_by: "current_user",
+            },
+        });
+    }, [metadata, updateProduct]);
+    // Create version
+    const createVersion = (0, react_1.useCallback)(async (description) => {
+        const version = {
+            ...description,
+            version: versions.length + 1,
+            created_at: new Date().toISOString(),
+        };
+        const newVersions = [version, ...versions].slice(0, maxVersions);
+        await updateProduct.mutateAsync({
+            metadata: {
+                ...metadata,
+                long_description_versions: newVersions,
+            },
+        });
+    }, [maxVersions, metadata, updateProduct, versions]);
+    // Restore version
+    const restoreVersion = (0, react_1.useCallback)(async (versionNumber) => {
+        const version = versions.find((v) => v.version === versionNumber);
+        if (!version) {
+            throw new Error(`Version ${versionNumber} not found`);
+        }
+        const restoredDescription = {
+            html: version.html,
+            richjson: version.richjson,
+            locale: version.locale,
+            updated_at: new Date().toISOString(),
+            updated_by: "current_user",
+        };
+        await updateProduct.mutateAsync({
+            metadata: {
+                ...metadata,
+                long_description: restoredDescription,
+                content_last_updated: new Date().toISOString(),
+                content_updated_by: "current_user",
+            },
+        });
+    }, [metadata, updateProduct, versions]);
+    // Delete version
+    const deleteVersion = (0, react_1.useCallback)(async (versionNumber) => {
+        const newVersions = versions.filter((v) => v.version !== versionNumber);
+        await updateProduct.mutateAsync({
+            metadata: {
+                ...metadata,
+                long_description_versions: newVersions,
+            },
+        });
+    }, [metadata, updateProduct, versions]);
+    // Update metadata
+    const updateMetadata = (0, react_1.useCallback)(async (updates) => {
+        await updateProduct.mutateAsync({
+            metadata: {
+                ...metadata,
+                ...updates,
+                content_last_updated: new Date().toISOString(),
+                content_updated_by: "current_user",
+            },
+        });
+    }, [metadata, updateProduct]);
+    return {
+        product,
+        isLoading,
+        error,
+        metadata,
+        longDescription,
+        specs,
+        versions,
+        updateLongDescription,
+        updateSpecs,
+        createVersion,
+        restoreVersion,
+        deleteVersion,
+        updateMetadata,
+    };
+}

package/dist/admin/lib/sdk.d.ts

@@ -0,0 +1,2 @@
+import Medusa from "@medusajs/js-sdk";
+export declare const sdk: Medusa;

package/dist/admin/lib/sdk.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sdk = void 0;
+// @ts-nocheck
+const js_sdk_1 = __importDefault(require("@medusajs/js-sdk"));
+exports.sdk = new js_sdk_1.default({
+    baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
+    debug: import.meta.env.DEV,
+    auth: {
+        type: "session",
+    },
+});

package/dist/admin/routes/product-content/page.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Product Content Management Page
+ * Main listing page accessible from admin menu
+ */
+import React from "react";
+declare const ProductContentPage: () => React.JSX.Element;
+export declare const config: import("@medusajs/admin-sdk").RouteConfig;
+export default ProductContentPage;

package/dist/admin/routes/product-content/page.js

@@ -0,0 +1,158 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+/**
+ * Product Content Management Page
+ * Main listing page accessible from admin menu
+ */
+// @ts-nocheck
+const react_1 = __importStar(require("react"));
+const ui_1 = require("@medusajs/ui");
+const icons_1 = require("@medusajs/icons");
+const admin_sdk_1 = require("@medusajs/admin-sdk");
+const sdk_1 = require("../../lib/sdk");
+const ProductContentPage = () => {
+    const [products, setProducts] = (0, react_1.useState)([]);
+    const [loading, setLoading] = (0, react_1.useState)(true);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [searchQuery, setSearchQuery] = (0, react_1.useState)("");
+    (0, react_1.useEffect)(() => {
+        fetchProducts();
+    }, []);
+    const fetchProducts = async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            const response = await sdk_1.sdk.client.fetch("/admin/products?limit=100", {
+                credentials: "include",
+            });
+            if (response.ok) {
+                const data = await response.json();
+                setProducts(data.products || []);
+            }
+            else {
+                setError("Failed to fetch products");
+            }
+        }
+        catch (err) {
+            setError("Error fetching products");
+            console.error("Error fetching products:", err);
+        }
+        finally {
+            setLoading(false);
+        }
+    };
+    const handleManageContent = (productId) => {
+        window.location.href = `/app/products/${productId}`;
+    };
+    const filteredProducts = products.filter((product) => {
+        if (!searchQuery)
+            return true;
+        const query = searchQuery.toLowerCase();
+        return (product.title?.toLowerCase().includes(query) ||
+            product.handle?.toLowerCase().includes(query));
+    });
+    const hasContent = (product) => {
+        return product.metadata?.long_description || product.metadata?.specs;
+    };
+    const getContentStatus = (product) => {
+        const hasLongDesc = !!product.metadata?.long_description;
+        const hasSpecs = !!product.metadata?.specs;
+        if (hasLongDesc && hasSpecs)
+            return { label: "Complete", color: "green" };
+        if (hasLongDesc || hasSpecs)
+            return { label: "Partial", color: "orange" };
+        return { label: "Empty", color: "grey" };
+    };
+    if (loading) {
+        return (react_1.default.createElement(ui_1.Container, null,
+            react_1.default.createElement("div", { className: "flex h-64 items-center justify-center" },
+                react_1.default.createElement(ui_1.Text, null, "Loading products..."))));
+    }
+    if (error) {
+        return (react_1.default.createElement(ui_1.Container, null,
+            react_1.default.createElement(ui_1.Alert, { variant: "error", dismissible: true }, error)));
+    }
+    return (react_1.default.createElement(ui_1.Container, null,
+        react_1.default.createElement("div", { className: "mb-8" },
+            react_1.default.createElement("div", { className: "flex items-center justify-between mb-4" },
+                react_1.default.createElement("div", null,
+                    react_1.default.createElement(ui_1.Heading, { level: "h1", className: "mb-2" }, "Product Content"),
+                    react_1.default.createElement(ui_1.Text, { className: "text-ui-fg-subtle" }, "Manage long descriptions and specifications for all products"))),
+            react_1.default.createElement("div", { className: "flex items-center gap-4" },
+                react_1.default.createElement("div", { className: "relative flex-1 max-w-md" },
+                    react_1.default.createElement(ui_1.Input, { placeholder: "Search products...", value: searchQuery, onChange: (e) => setSearchQuery(e.target.value), className: "pl-10" }),
+                    react_1.default.createElement(icons_1.MagnifyingGlass, { className: "absolute left-3 top-1/2 -translate-y-1/2 text-ui-fg-muted" })))),
+        filteredProducts.length === 0 ? (react_1.default.createElement("div", { className: "flex h-64 flex-col items-center justify-center rounded-lg border-2 border-dashed border-ui-border-base" },
+            react_1.default.createElement(icons_1.SquareTwoStack, { className: "mb-4 text-ui-fg-subtle", style: { width: "3rem", height: "3rem" } }),
+            react_1.default.createElement(ui_1.Text, { className: "mb-2 text-lg font-medium" }, searchQuery ? "No products found" : "No products yet"),
+            react_1.default.createElement(ui_1.Text, { className: "mb-4 text-ui-fg-subtle" }, searchQuery
+                ? "Try adjusting your search query"
+                : "Create products to manage their content"))) : (react_1.default.createElement("div", { className: "overflow-hidden rounded-lg border" },
+            react_1.default.createElement(ui_1.Table, null,
+                react_1.default.createElement(ui_1.Table.Header, null,
+                    react_1.default.createElement(ui_1.Table.Row, null,
+                        react_1.default.createElement(ui_1.Table.HeaderCell, null, "Product"),
+                        react_1.default.createElement(ui_1.Table.HeaderCell, null, "Handle"),
+                        react_1.default.createElement(ui_1.Table.HeaderCell, null, "Status"),
+                        react_1.default.createElement(ui_1.Table.HeaderCell, null, "Content Status"),
+                        react_1.default.createElement(ui_1.Table.HeaderCell, { className: "text-right" }, "Actions"))),
+                react_1.default.createElement(ui_1.Table.Body, null, filteredProducts.map((product) => {
+                    const contentStatus = getContentStatus(product);
+                    return (react_1.default.createElement(ui_1.Table.Row, { key: product.id },
+                        react_1.default.createElement(ui_1.Table.Cell, null,
+                            react_1.default.createElement(ui_1.Text, { className: "font-medium" }, product.title)),
+                        react_1.default.createElement(ui_1.Table.Cell, null,
+                            react_1.default.createElement(ui_1.Badge, { color: "blue" }, product.handle || "—")),
+                        react_1.default.createElement(ui_1.Table.Cell, null,
+                            react_1.default.createElement(ui_1.Badge, { color: product.status === "published" ? "green" : "grey" }, product.status || "draft")),
+                        react_1.default.createElement(ui_1.Table.Cell, null,
+                            react_1.default.createElement("div", { className: "flex items-center gap-2" },
+                                react_1.default.createElement(ui_1.Badge, { color: contentStatus.color }, contentStatus.label),
+                                product.metadata?.long_description && (react_1.default.createElement(ui_1.Badge, { color: "green", size: "xsmall" }, "Description")),
+                                product.metadata?.specs && (react_1.default.createElement(ui_1.Badge, { color: "green", size: "xsmall" }, "Specs")))),
+                        react_1.default.createElement(ui_1.Table.Cell, null,
+                            react_1.default.createElement("div", { className: "flex items-center justify-end" },
+                                react_1.default.createElement(ui_1.Button, { variant: "secondary", size: "small", onClick: () => handleManageContent(product.id) },
+                                    react_1.default.createElement(icons_1.PencilSquare, { className: "mr-1" }),
+                                    "View Product")))));
+                })))))));
+};
+exports.config = (0, admin_sdk_1.defineRouteConfig)({
+    label: "Product Content",
+    icon: icons_1.SquareTwoStack,
+});
+exports.default = ProductContentPage;

package/dist/admin/utils/import-export.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Import/Export utility for specifications
+ */
+import { ProductSpecs, ImportValidationResult } from '../../types';
+/**
+ * Export specifications to CSV
+ */
+export declare function exportSpecsToCSV(specs: ProductSpecs): string;
+/**
+ * Export specifications to JSON
+ */
+export declare function exportSpecsToJSON(specs: ProductSpecs): string;
+/**
+ * Import specifications from CSV
+ */
+export declare function importSpecsFromCSV(csvContent: string, defaultLocale?: string): Promise<{
+    specs: ProductSpecs | null;
+    validation: ImportValidationResult;
+}>;
+/**
+ * Import specifications from JSON
+ */
+export declare function importSpecsFromJSON(jsonContent: string): Promise<{
+    specs: ProductSpecs | null;
+    validation: ImportValidationResult;
+}>;
+/**
+ * Merge imported specs with existing specs
+ */
+export declare function mergeSpecs(existing: ProductSpecs, imported: ProductSpecs, strategy?: 'replace' | 'merge' | 'append'): ProductSpecs;