medusa-contact-us 0.0.1

package/.medusa/server/src/workflows/steps/update-contact-request-status-step.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateContactRequestStatusStep = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const constants_1 = require("../../constants");
+exports.updateContactRequestStatusStep = (0, workflows_sdk_1.createStep)("update-contact-request-status", async (input, { container }) => {
+    const service = container.resolve(constants_1.CONTACT_REQUEST_MODULE);
+    const request = await service.updateStatus(input);
+    const options = service.getOptions();
+    const statusOption = options.status_options.find((option) => option.code === request.status);
+    return new workflows_sdk_1.StepResponse({
+        request,
+        options,
+        statusOption,
+    });
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXBkYXRlLWNvbnRhY3QtcmVxdWVzdC1zdGF0dXMtc3RlcC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uLy4uL3NyYy93b3JrZmxvd3Mvc3RlcHMvdXBkYXRlLWNvbnRhY3QtcmVxdWVzdC1zdGF0dXMtc3RlcC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSxxRUFBNEU7QUFDNUUsK0NBQXdEO0FBZTNDLFFBQUEsOEJBQThCLEdBQUcsSUFBQSwwQkFBVSxFQUN0RCwrQkFBK0IsRUFDL0IsS0FBSyxFQUNILEtBQStCLEVBQy9CLEVBQUUsU0FBUyxFQUFFLEVBQ3NCLEVBQUU7SUFDckMsTUFBTSxPQUFPLEdBQ1gsU0FBUyxDQUFDLE9BQU8sQ0FBOEIsa0NBQXNCLENBQUMsQ0FBQTtJQUV4RSxNQUFNLE9BQU8sR0FBRyxNQUFNLE9BQU8sQ0FBQyxZQUFZLENBQUMsS0FBSyxDQUFDLENBQUE7SUFDakQsTUFBTSxPQUFPLEdBQUcsT0FBTyxDQUFDLFVBQVUsRUFBRSxDQUFBO0lBQ3BDLE1BQU0sWUFBWSxHQUFHLE9BQU8sQ0FBQyxjQUFjLENBQUMsSUFBSSxDQUM5QyxDQUFDLE1BQU0sRUFBRSxFQUFFLENBQUMsTUFBTSxDQUFDLElBQUksS0FBSyxPQUFPLENBQUMsTUFBTSxDQUMzQyxDQUFBO0lBRUQsT0FBTyxJQUFJLDRCQUFZLENBQUM7UUFDdEIsT0FBTztRQUNQLE9BQU87UUFDUCxZQUFZO0tBQ2IsQ0FBQyxDQUFBO0FBQ0osQ0FBQyxDQUNGLENBQUEifQ==

package/.medusa/server/src/workflows/update-contact-request-status.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateContactRequestStatusWorkflow = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const send_contact_notification_step_1 = require("./steps/send-contact-notification-step");
+const update_contact_request_status_step_1 = require("./steps/update-contact-request-status-step");
+exports.updateContactRequestStatusWorkflow = (0, workflows_sdk_1.createWorkflow)("contact-us-update-status", (input) => {
+    const { request, options, statusOption } = (0, update_contact_request_status_step_1.updateContactRequestStatusStep)(input);
+    const isFinal = request.status === options.statuses.final;
+    const shouldNotify = isFinal &&
+        options.notifications.send_on_final_status &&
+        (statusOption?.notify_customer ?? true);
+    (0, send_contact_notification_step_1.sendContactNotificationStep)({
+        shouldSend: shouldNotify,
+        to: request.email,
+        from: options.notifications.from_address,
+        reply_to: options.notifications.reply_to,
+        template: statusOption?.template ??
+            options.notifications.final_status_template,
+        subject: statusOption?.label ?? "Your contact request was updated",
+        data: {
+            request_id: request.id,
+            status: request.status,
+            updated_at: request.updated_at,
+        },
+    });
+    return new workflows_sdk_1.WorkflowResponse({
+        request,
+    });
+});
+exports.default = exports.updateContactRequestStatusWorkflow;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXBkYXRlLWNvbnRhY3QtcmVxdWVzdC1zdGF0dXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvd29ya2Zsb3dzL3VwZGF0ZS1jb250YWN0LXJlcXVlc3Qtc3RhdHVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLHFFQUcwQztBQUUxQywyRkFBb0Y7QUFDcEYsbUdBQTJGO0FBRTlFLFFBQUEsa0NBQWtDLEdBQUcsSUFBQSw4QkFBYyxFQUM5RCwwQkFBMEIsRUFDMUIsQ0FBQyxLQUErQixFQUFFLEVBQUU7SUFDbEMsTUFBTSxFQUFFLE9BQU8sRUFBRSxPQUFPLEVBQUUsWUFBWSxFQUFFLEdBQ3RDLElBQUEsbUVBQThCLEVBQUMsS0FBSyxDQUFDLENBQUE7SUFFdkMsTUFBTSxPQUFPLEdBQUcsT0FBTyxDQUFDLE1BQU0sS0FBSyxPQUFPLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQTtJQUN6RCxNQUFNLFlBQVksR0FDaEIsT0FBTztRQUNQLE9BQU8sQ0FBQyxhQUFhLENBQUMsb0JBQW9CO1FBQzFDLENBQUMsWUFBWSxFQUFFLGVBQWUsSUFBSSxJQUFJLENBQUMsQ0FBQTtJQUV6QyxJQUFBLDREQUEyQixFQUFDO1FBQzFCLFVBQVUsRUFBRSxZQUFZO1FBQ3hCLEVBQUUsRUFBRSxPQUFPLENBQUMsS0FBSztRQUNqQixJQUFJLEVBQUUsT0FBTyxDQUFDLGFBQWEsQ0FBQyxZQUFZO1FBQ3hDLFFBQVEsRUFBRSxPQUFPLENBQUMsYUFBYSxDQUFDLFFBQVE7UUFDeEMsUUFBUSxFQUNOLFlBQVksRUFBRSxRQUFRO1lBQ3RCLE9BQU8sQ0FBQyxhQUFhLENBQUMscUJBQXFCO1FBQzdDLE9BQU8sRUFBRSxZQUFZLEVBQUUsS0FBSyxJQUFJLGtDQUFrQztRQUNsRSxJQUFJLEVBQUU7WUFDSixVQUFVLEVBQUUsT0FBTyxDQUFDLEVBQUU7WUFDdEIsTUFBTSxFQUFFLE9BQU8sQ0FBQyxNQUFNO1lBQ3RCLFVBQVUsRUFBRSxPQUFPLENBQUMsVUFBVTtTQUMvQjtLQUNGLENBQUMsQ0FBQTtJQUVGLE9BQU8sSUFBSSxnQ0FBZ0IsQ0FBQztRQUMxQixPQUFPO0tBQ1IsQ0FBQyxDQUFBO0FBQ0osQ0FBQyxDQUNGLENBQUE7QUFFRCxrQkFBZSwwQ0FBa0MsQ0FBQSJ9

package/README.md

@@ -0,0 +1,213 @@
+<h1 align="center">Medusa Contact Us Plugin</h1>
+
+Collect, triage, and resolve storefront “contact us” submissions inside the Medusa Admin. The plugin ships a full stack experience: configurable form schema, database-backed requests/comments, workflows with notification hooks, open store endpoint, admin APIs, helper utilities, and a polished admin UI.
+
+## Features
+
+- ✅ Configurable form schema (required email + arbitrary fields validated from plugin options)
+- 🧩 Status lifecycle definition (initial/intermediate/final, allowed transitions, metadata)
+- ✉️ Workflow-powered notifications on submission and on final status (re-uses Medusa notification module)
+- 🗒️ Admin-only comment trail per request with rich status history
+- 🖥️ React Admin extension with list + detail views, filters, status change controls, and comment composer
+- 🔌 Frontend helper (`submitContactRequest`) to abstract API wiring
+- 🧪 Table-driven tests for payload validation and helper logic
+
+## Installation
+
+```bash
+yarn add medusa-contact-us
+# or
+npm install medusa-contact-us
+```
+
+Inside `medusa-config.ts` register the plugin and tailor the options:
+
+```ts
+import {
+  defineContactUsPluginOptions,
+  ContactRequestModule,
+} from "medusa-contact-us"
+
+const plugins = [
+  {
+    resolve: "medusa-contact-us",
+    options: defineContactUsPluginOptions({
+      form: {
+        max_payload_kb: 128,
+        additional_fields: [
+          { key: "subject", label: "Subject", type: "text", required: true },
+          {
+            key: "priority",
+            label: "Priority",
+            type: "select",
+            options: [
+              { value: "low", label: "Low" },
+              { value: "high", label: "High" },
+            ],
+          },
+        ],
+      },
+      status_options: [
+        { code: "new", label: "New", notify_customer: true },
+        { code: "in_review", label: "In review" },
+        {
+          code: "closed",
+          label: "Closed",
+          notify_customer: true,
+          template: "emails/contact-final.mjml",
+        },
+      ],
+      statuses: {
+        initial: "new",
+        intermediates: ["in_review"],
+        final: "closed",
+        transitions: {
+          new: ["in_review", "closed"],
+          in_review: ["closed"],
+        },
+      },
+      notifications: {
+        send_on_create: true,
+        acknowledgement_template: "emails/contact-received.mjml",
+        send_on_final_status: true,
+      },
+      comments: {
+        enabled: true,
+        require_note_on_final: true,
+      },
+    }),
+  },
+]
+
+const modules = [ContactRequestModule]
+```
+
+### Status lifecycle best practices
+
+- Define unique status codes (kebab or snake case) and map them in `status_options`.
+- Provide at least one intermediate state when multiple review steps exist.
+- Set `notify_customer` to `true` for statuses that should trigger emails.
+- Configure `transitions` if you need granular control; otherwise the default is `(all non-final statuses) -> intermediates/final`.
+
+## REST API
+
+### Storefront (open)
+
+```bash
+curl -X POST https://your-medusa.com/store/contact-requests \
+  -H "Content-Type: application/json" \
+  -d '{
+        "email": "customer@example.com",
+        "payload": { "subject": "Need help", "priority": "high" },
+        "metadata": { "order_id": "order_123" }
+      }'
+```
+
+Response:
+
+```json
+{
+  "contact_request": {
+    "id": "crq_123",
+    "email": "customer@example.com",
+    "status": "new",
+    "payload": { "subject": "Need help", "priority": "high" },
+    "status_history": [
+      { "status": "new", "updated_at": "2024-11-24T10:00:00.000Z" }
+    ]
+  }
+}
+```
+
+### Admin (requires admin auth cookie/token)
+
+List:
+
+```bash
+curl -X GET "https://your-medusa.com/admin/contact-requests?status=new&limit=20" \
+  -H "Authorization: Bearer <token>"
+```
+
+Detail:
+
+```bash
+curl -X GET https://your-medusa.com/admin/contact-requests/crq_123 \
+  -H "Authorization: Bearer <token>"
+```
+
+Update status:
+
+```bash
+curl -X PATCH https://your-medusa.com/admin/contact-requests/crq_123 \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{ "status": "closed", "note": "Resolved via refund" }'
+```
+
+Add comment:
+
+```bash
+curl -X POST https://your-medusa.com/admin/contact-requests/crq_123/comments \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{ "comment": "Waiting on supplier" }'
+```
+
+## Admin UI
+
+After running `medusa admin dev --plugins medusa-contact-us`, the sidebar will include **Contact Requests**:
+
+- **List view** – search by email, filter by status, inspect creation dates, open details with a single click.
+- **Detail view** – see submitted fields, live status badge, change status (with optional notes), inspect the full history timeline, and append internal comments.
+- **Comments** – only admins can add comments. Comments are persisted and shown newest first.
+
+All UI components follow the Medusa UI kit spacing (8pt grid), color, and accessibility guidelines.
+
+## Frontend helper
+
+Skip hand-writing `fetch` calls by importing the provided helper:
+
+```ts
+import { submitContactRequest } from "medusa-contact-us"
+
+await submitContactRequest({
+  email: "customer@example.com",
+  payload: { subject: "Question", priority: "high" },
+})
+```
+
+Passing a Medusa JS client automatically reuses its transport:
+
+```ts
+import Medusa from "@medusajs/medusa-js"
+import { submitContactRequest } from "medusa-contact-us"
+
+const client = new Medusa({ baseUrl: "https://your-medusa.com" })
+
+await submitContactRequest({
+  client,
+  email: "customer@example.com",
+  payload: { subject: "Returns" },
+})
+```
+
+## Workflows & notifications
+
+- `createContactRequestWorkflow` validates payloads, persists the request, and optionally fires an acknowledgement email.
+- `updateContactRequestStatusWorkflow` enforces transitions, records history entries, and emits final-status notifications.
+- Notifications rely on the standard Medusa notification module. Ensure at least one email provider is configured; otherwise the workflows raise an error to surface misconfiguration early.
+
+## Testing & build
+
+```bash
+yarn test   # runs Vitest table-driven suites
+yarn build  # compiles the plugin via `medusa plugin:build`
+```
+
+Always run `yarn build` after development to ensure the bundler succeeds before publishing or yalc linking.
+
+## Troubleshooting
+
+- Submit endpoint returning `422`: ensure every field defined in `form.additional_fields` is provided and matches its type.
+- Notifications not sent: confirm `notifications.send_on_*` flags and that the notification module is registered (the workflows throw an actionable error otherwise).
+- Admin UI blank: rebuild the plugin (`yarn build`) and restart the Admin app with the plugin registered in `medusa-config.ts`.

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "medusa-contact-us",
+  "version": "0.0.1",
+  "description": "A starter for Medusa plugins.",
+  "author": "Medusa (https://medusajs.com)",
+  "license": "MIT",
+  "files": [
+    ".medusa/server"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./workflows": "./.medusa/server/src/workflows/index.js",
+    "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./modules/*": "./.medusa/server/src/modules/*/index.js",
+    "./providers/*": "./.medusa/server/src/providers/*/index.js",
+    "./*": "./.medusa/server/src/*.js",
+    "./admin": {
+      "import": "./.medusa/server/src/admin/index.mjs",
+      "require": "./.medusa/server/src/admin/index.js",
+      "default": "./.medusa/server/src/admin/index.js"
+    }
+  },
+  "keywords": [
+    "medusa",
+    "plugin",
+    "medusa-plugin-other",
+    "medusa-plugin",
+    "medusa-v2"
+  ],
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "scripts": {
+    "build": "medusa plugin:build",
+    "dev": "medusa plugin:develop",
+    "test": "vitest run",
+    "prepublishOnly": "medusa plugin:build"
+  },
+  "devDependencies": {
+    "@medusajs/admin-sdk": "2.11.2",
+    "@medusajs/cli": "2.11.2",
+    "@medusajs/framework": "2.11.2",
+    "@medusajs/medusa": "2.11.2",
+    "@medusajs/test-utils": "2.11.2",
+    "@medusajs/ui": "4.0.25",
+    "@medusajs/icons": "2.11.2",
+    "@swc/core": "1.5.7",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.2",
+    "@types/react-dom": "^18.2.25",
+    "prop-types": "^15.8.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.2",
+    "vite": "^5.2.11",
+    "vitest": "^1.2.2",
+    "yalc": "^1.0.0-pre.53"
+  },
+  "peerDependencies": {
+    "@medusajs/admin-sdk": "2.11.2",
+    "@medusajs/cli": "2.11.2",
+    "@medusajs/framework": "2.11.2",
+    "@medusajs/test-utils": "2.11.2",
+    "@medusajs/medusa": "2.11.2",
+    "@medusajs/ui": "4.0.25",
+    "@medusajs/icons": "2.11.2"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}