medusa-contact-us 0.0.17 → 0.0.21

package/.medusa/server/src/workflows/steps/send-status-notification-step.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendStatusNotificationStep = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const utils_1 = require("@medusajs/framework/utils");
+/**
+ * Prepare email payload for notification service
+ */
+function prepareEmailPayload(to, subject, template, contactRequest) {
+    const payload = {
+        to,
+        channel: "email",
+        data: {
+            subject,
+            contactRequest,
+        },
+    };
+    if (template) {
+        payload.template = template;
+    }
+    return payload;
+}
+/**
+ * Send email notification for status change
+ */
+exports.sendStatusNotificationStep = (0, workflows_sdk_1.createStep)("send-status-notification", async (input, { container }) => {
+    // If no email subject provided, skip sending
+    if (!input.emailSubject) {
+        return new workflows_sdk_1.StepResponse({
+            sent: false,
+        });
+    }
+    const payload = prepareEmailPayload(input.contactRequest.email, input.emailSubject, input.emailTemplate ?? null, input.contactRequest);
+    const notificationService = container.resolve(utils_1.Modules.NOTIFICATION);
+    if (!notificationService) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.INVALID_DATA, "Notification service is not configured.");
+    }
+    try {
+        if (typeof notificationService.create === "function") {
+            await notificationService.create(payload);
+        }
+        else if (typeof notificationService.createNotifications === "function") {
+            await notificationService.createNotifications([payload]);
+        }
+        else {
+            throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, "Notification service does not support sending notifications.");
+        }
+    }
+    catch (error) {
+        throw new utils_1.MedusaError(utils_1.MedusaError.Types.UNEXPECTED_STATE, `Failed to send notification: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return new workflows_sdk_1.StepResponse({
+        sent: true,
+    });
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2VuZC1zdGF0dXMtbm90aWZpY2F0aW9uLXN0ZXAuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9zcmMvd29ya2Zsb3dzL3N0ZXBzL3NlbmQtc3RhdHVzLW5vdGlmaWNhdGlvbi1zdGVwLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLHFFQUE0RTtBQUM1RSxxREFBZ0U7QUFlaEU7O0dBRUc7QUFDSCxTQUFTLG1CQUFtQixDQUMxQixFQUFVLEVBQ1YsT0FBZSxFQUNmLFFBQXVCLEVBQ3ZCLGNBQWlDO0lBRWpDLE1BQU0sT0FBTyxHQVFUO1FBQ0YsRUFBRTtRQUNGLE9BQU8sRUFBRSxPQUFPO1FBQ2hCLElBQUksRUFBRTtZQUNKLE9BQU87WUFDUCxjQUFjO1NBQ2Y7S0FDRixDQUFBO0lBRUQsSUFBSSxRQUFRLEVBQUUsQ0FBQztRQUNiLE9BQU8sQ0FBQyxRQUFRLEdBQUcsUUFBUSxDQUFBO0lBQzdCLENBQUM7SUFFRCxPQUFPLE9BQU8sQ0FBQTtBQUNoQixDQUFDO0FBRUQ7O0dBRUc7QUFDVSxRQUFBLDBCQUEwQixHQUFHLElBQUEsMEJBQVUsRUFDbEQsMEJBQTBCLEVBQzFCLEtBQUssRUFBRSxLQUFrQyxFQUFFLEVBQUUsU0FBUyxFQUFFLEVBQUUsRUFBRTtJQUMxRCw2Q0FBNkM7SUFDN0MsSUFBSSxDQUFDLEtBQUssQ0FBQyxZQUFZLEVBQUUsQ0FBQztRQUN4QixPQUFPLElBQUksNEJBQVksQ0FBK0I7WUFDcEQsSUFBSSxFQUFFLEtBQUs7U0FDWixDQUFDLENBQUE7SUFDSixDQUFDO0lBRUQsTUFBTSxPQUFPLEdBQUcsbUJBQW1CLENBQ2pDLEtBQUssQ0FBQyxjQUFjLENBQUMsS0FBSyxFQUMxQixLQUFLLENBQUMsWUFBWSxFQUNsQixLQUFLLENBQUMsYUFBYSxJQUFJLElBQUksRUFDM0IsS0FBSyxDQUFDLGNBQWMsQ0FDckIsQ0FBQTtJQUVELE1BQU0sbUJBQW1CLEdBQUcsU0FBUyxDQUFDLE9BQU8sQ0FBQyxlQUFPLENBQUMsWUFBWSxDQUdqRSxDQUFBO0lBRUQsSUFBSSxDQUFDLG1CQUFtQixFQUFFLENBQUM7UUFDekIsTUFBTSxJQUFJLG1CQUFXLENBQ25CLG1CQUFXLENBQUMsS0FBSyxDQUFDLFlBQVksRUFDOUIseUNBQXlDLENBQzFDLENBQUE7SUFDSCxDQUFDO0lBRUQsSUFBSSxDQUFDO1FBQ0gsSUFBSSxPQUFPLG1CQUFtQixDQUFDLE1BQU0sS0FBSyxVQUFVLEVBQUUsQ0FBQztZQUNyRCxNQUFNLG1CQUFtQixDQUFDLE1BQU0sQ0FBQyxPQUFPLENBQUMsQ0FBQTtRQUMzQyxDQUFDO2FBQU0sSUFBSSxPQUFPLG1CQUFtQixDQUFDLG1CQUFtQixLQUFLLFVBQVUsRUFBRSxDQUFDO1lBQ3pFLE1BQU0sbUJBQW1CLENBQUMsbUJBQW1CLENBQUMsQ0FBQyxPQUFPLENBQUMsQ0FBQyxDQUFBO1FBQzFELENBQUM7YUFBTSxDQUFDO1lBQ04sTUFBTSxJQUFJLG1CQUFXLENBQ25CLG1CQUFXLENBQUMsS0FBSyxDQUFDLGdCQUFnQixFQUNsQyw4REFBOEQsQ0FDL0QsQ0FBQTtRQUNILENBQUM7SUFDSCxDQUFDO0lBQUMsT0FBTyxLQUFLLEVBQUUsQ0FBQztRQUNmLE1BQU0sSUFBSSxtQkFBVyxDQUNuQixtQkFBVyxDQUFDLEtBQUssQ0FBQyxnQkFBZ0IsRUFDbEMsZ0NBQWdDLEtBQUssWUFBWSxLQUFLLENBQUMsQ0FBQyxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUN6RixDQUFBO0lBQ0gsQ0FBQztJQUVELE9BQU8sSUFBSSw0QkFBWSxDQUErQjtRQUNwRCxJQUFJLEVBQUUsSUFBSTtLQUNYLENBQUMsQ0FBQTtBQUNKLENBQUMsQ0FDRixDQUFBIn0=

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 contact_requests_1 = require("../../modules/contact-requests");
+exports.updateContactRequestStatusStep = (0, workflows_sdk_1.createStep)("update-contact-request-status", async (input, { container }) => {
+    const service = container.resolve(contact_requests_1.CONTACT_REQUEST_MODULE);
+    // Get current request to capture previous status
+    const currentRequest = await service.getRequest(input.id);
+    const previousStatus = currentRequest.status;
+    const request = await service.updateStatus(input);
+    return new workflows_sdk_1.StepResponse({
+        request,
+        previousStatus,
+    });
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXBkYXRlLWNvbnRhY3QtcmVxdWVzdC1zdGF0dXMtc3RlcC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uLy4uLy4uLy4uL3NyYy93b3JrZmxvd3Mvc3RlcHMvdXBkYXRlLWNvbnRhY3QtcmVxdWVzdC1zdGF0dXMtc3RlcC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSxxRUFBNEU7QUFDNUUscUVBQXVFO0FBWTFELFFBQUEsOEJBQThCLEdBQUcsSUFBQSwwQkFBVSxFQUN0RCwrQkFBK0IsRUFDL0IsS0FBSyxFQUNILEtBQXNDLEVBQ3RDLEVBQUUsU0FBUyxFQUFFLEVBQ2dELEVBQUU7SUFDL0QsTUFBTSxPQUFPLEdBQUcsU0FBUyxDQUFDLE9BQU8sQ0FDL0IseUNBQXNCLENBQ3ZCLENBQUE7SUFFRCxpREFBaUQ7SUFDakQsTUFBTSxjQUFjLEdBQUcsTUFBTSxPQUFPLENBQUMsVUFBVSxDQUFDLEtBQUssQ0FBQyxFQUFFLENBQUMsQ0FBQTtJQUN6RCxNQUFNLGNBQWMsR0FBRyxjQUFjLENBQUMsTUFBTSxDQUFBO0lBRTVDLE1BQU0sT0FBTyxHQUFHLE1BQU0sT0FBTyxDQUFDLFlBQVksQ0FBQyxLQUFLLENBQUMsQ0FBQTtJQUVqRCxPQUFPLElBQUksNEJBQVksQ0FBdUM7UUFDNUQsT0FBTztRQUNQLGNBQWM7S0FDZixDQUFDLENBQUE7QUFDSixDQUFDLENBQ0YsQ0FBQSJ9

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

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateContactRequestStatusWorkflow = void 0;
+const workflows_sdk_1 = require("@medusajs/framework/workflows-sdk");
+const update_contact_request_status_step_1 = require("./steps/update-contact-request-status-step");
+const resolve_status_transition_step_1 = require("./steps/resolve-status-transition-step");
+const send_status_notification_step_1 = require("./steps/send-status-notification-step");
+exports.updateContactRequestStatusWorkflow = (0, workflows_sdk_1.createWorkflow)("update-contact-request-status", (input) => {
+    // Step 1: Update status (validation happens inside the step)
+    const { request, previousStatus } = (0, update_contact_request_status_step_1.updateContactRequestStatusStep)(input);
+    // Step 2: Resolve transition config for email notification
+    const { transition, options } = (0, resolve_status_transition_step_1.resolveStatusTransitionStep)({
+        fromStatus: previousStatus,
+        toStatus: input.status,
+    });
+    // Step 3: Send notification if configured
+    (0, send_status_notification_step_1.sendStatusNotificationStep)({
+        contactRequest: request,
+        fromStatus: previousStatus,
+        toStatus: input.status,
+        emailSubject: transition?.send_email && options.email.enabled
+            ? transition.email_subject ?? options.email.default_subject
+            : undefined,
+        emailTemplate: transition?.send_email && options.email.enabled
+            ? transition.email_template ?? options.email.default_template
+            : undefined,
+    });
+    return new workflows_sdk_1.WorkflowResponse({
+        request,
+    });
+});
+exports.default = exports.updateContactRequestStatusWorkflow;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXBkYXRlLWNvbnRhY3QtcmVxdWVzdC1zdGF0dXMtd29ya2Zsb3cuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi9zcmMvd29ya2Zsb3dzL3VwZGF0ZS1jb250YWN0LXJlcXVlc3Qtc3RhdHVzLXdvcmtmbG93LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLHFFQUcwQztBQUMxQyxtR0FBMkY7QUFDM0YsMkZBQW9GO0FBQ3BGLHlGQUFrRjtBQWFyRSxRQUFBLGtDQUFrQyxHQUFHLElBQUEsOEJBQWMsRUFDOUQsK0JBQStCLEVBQy9CLENBQ0UsS0FBOEMsRUFDYyxFQUFFO0lBQzlELDZEQUE2RDtJQUM3RCxNQUFNLEVBQUUsT0FBTyxFQUFFLGNBQWMsRUFBRSxHQUFHLElBQUEsbUVBQThCLEVBQUMsS0FBSyxDQUFDLENBQUE7SUFFekUsMkRBQTJEO0lBQzNELE1BQU0sRUFBRSxVQUFVLEVBQUUsT0FBTyxFQUFFLEdBQUcsSUFBQSw0REFBMkIsRUFBQztRQUMxRCxVQUFVLEVBQUUsY0FBYztRQUMxQixRQUFRLEVBQUUsS0FBSyxDQUFDLE1BQU07S0FDdkIsQ0FBQyxDQUFBO0lBRUYsMENBQTBDO0lBQzFDLElBQUEsMERBQTBCLEVBQUM7UUFDekIsY0FBYyxFQUFFLE9BQU87UUFDdkIsVUFBVSxFQUFFLGNBQWM7UUFDMUIsUUFBUSxFQUFFLEtBQUssQ0FBQyxNQUFNO1FBQ3RCLFlBQVksRUFDVixVQUFVLEVBQUUsVUFBVSxJQUFJLE9BQU8sQ0FBQyxLQUFLLENBQUMsT0FBTztZQUM3QyxDQUFDLENBQUMsVUFBVSxDQUFDLGFBQWEsSUFBSSxPQUFPLENBQUMsS0FBSyxDQUFDLGVBQWU7WUFDM0QsQ0FBQyxDQUFDLFNBQVM7UUFDZixhQUFhLEVBQ1gsVUFBVSxFQUFFLFVBQVUsSUFBSSxPQUFPLENBQUMsS0FBSyxDQUFDLE9BQU87WUFDN0MsQ0FBQyxDQUFDLFVBQVUsQ0FBQyxjQUFjLElBQUksT0FBTyxDQUFDLEtBQUssQ0FBQyxnQkFBZ0I7WUFDN0QsQ0FBQyxDQUFDLFNBQVM7S0FDaEIsQ0FBQyxDQUFBO0lBRUYsT0FBTyxJQUFJLGdDQUFnQixDQUFDO1FBQzFCLE9BQU87S0FDUixDQUFDLENBQUE7QUFDSixDQUFDLENBQ0YsQ0FBQTtBQUVELGtCQUFlLDBDQUFrQyxDQUFBIn0=

package/README.md

@@ -1,14 +1,31 @@
-<h1 align="center">Medusa Contact Email Subscriptions Plugin</h1>
+<h1 align="center">Medusa Contact Us Plugin</h1>
 
-Manage storefront email subscriptions (opt-ins and opt-outs) inside the Medusa Admin. The plugin provides a complete solution: database-backed subscriptions, admin APIs, helper utilities, and a polished admin UI.
+A comprehensive Medusa v2 plugin for managing contact requests and email subscriptions. The plugin provides a complete solution: database-backed contact requests with configurable status workflows, email subscriptions, admin APIs, helper utilities, and a polished admin UI.
+
+**Features:**
+- 📝 Contact request management with status workflow and email notifications
+- ✉️ Email subscription management (opt-ins and opt-outs)
+- 🔄 Configurable status transitions and validation
+- 📧 Automatic email notifications on status changes
+- 🎯 Payload validation against configurable field definitions
 
 ## Features
 
+### Email Subscriptions
 - ✉️ Storefront opt-in helper + admin list for email subscriptions (subscribed/unsubscribed)
 - 🖥️ React Admin extension with list view, filters, and search
 - 🔌 Frontend helper (`upsertContactSubscription`) to abstract API wiring
 - 🧪 Table-driven tests for helper logic
 
+### Contact Requests
+- 📝 Contact request management with configurable status workflow
+- 🔄 Status transition validation with configurable allowed transitions
+- 📧 Email notifications on status changes (configurable per transition)
+- 🎯 Payload validation against configurable field definitions
+- 📊 Admin API for listing, filtering, and managing requests
+- 🔌 Storefront helper (`submitContactRequest`) for easy integration
+- 📈 Status history tracking with timestamps and actor information
+
 ## Installation
 
 ```bash
@@ -25,16 +42,79 @@ Inside `medusa-config.ts` register the plugin:
 import type { ConfigModule } from "@medusajs/framework/types"
 import {
   ContactSubscriptionModule,
+  ContactRequestModule,
 } from "medusa-contact-us"
 
 const plugins = [
   {
     resolve: "medusa-contact-us",
+    options: {
+      // Contact Request Configuration
+      default_status: "pending",
+      payload_fields: [
+        {
+          key: "subject",
+          type: "text",
+          required: true,
+          label: "Subject",
+          placeholder: "Enter subject",
+        },
+        {
+          key: "message",
+          type: "textarea",
+          required: true,
+          label: "Message",
+          placeholder: "Enter your message",
+        },
+        {
+          key: "priority",
+          type: "select",
+          required: false,
+          label: "Priority",
+          options: [
+            { value: "low", label: "Low" },
+            { value: "medium", label: "Medium" },
+            { value: "high", label: "High" },
+          ],
+        },
+      ],
+      allowed_statuses: ["pending", "in_progress", "resolved", "closed"],
+      status_transitions: [
+        {
+          from: null,
+          to: "pending",
+          send_email: false,
+        },
+        {
+          from: "pending",
+          to: "in_progress",
+          send_email: true,
+          email_subject: "Your request is being processed",
+          email_template: null, // Optional: path to email template
+        },
+        {
+          from: "in_progress",
+          to: "resolved",
+          send_email: true,
+          email_subject: "Your request has been resolved",
+        },
+        {
+          from: "resolved",
+          to: "closed",
+          send_email: false,
+        },
+      ],
+      email: {
+        enabled: true,
+        default_subject: "Contact Request Status Update",
+        default_template: null, // Optional: default email template path
+      },
+    },
   },
 ]
 
-// Register the ContactSubscriptionModule
-const modules = [ContactSubscriptionModule]
+// Register the modules
+const modules = [ContactSubscriptionModule, ContactRequestModule]
 
 export default {
   projectConfig: {
@@ -47,10 +127,91 @@ export default {
 } satisfies ConfigModule
 ```
 
+### Configuration Options
+
+#### Contact Request Options
+
+- **`default_status`** (string, optional): Default status for new requests. Default: `"pending"`
+- **`payload_fields`** (array, optional): Field definitions for payload validation. Each field supports:
+  - `key` (string, required): Field identifier
+  - `type` (string, required): Field type - `"text"`, `"textarea"`, `"number"`, `"email"`, `"select"`, `"checkbox"`
+  - `required` (boolean, optional): Whether field is required
+  - `label` (string, optional): Display label
+  - `placeholder` (string, optional): Placeholder text
+  - `options` (array, optional): For select type - `[{ value: string, label: string }]`
+  - `validation` (object, optional): Validation rules (min, max, pattern)
+- **`allowed_statuses`** (array, optional): List of allowed status values. Default: `["pending", "in_progress", "resolved", "closed"]`
+- **`status_transitions`** (array, optional): Allowed status transitions. Each transition supports:
+  - `from` (string | null): Source status (null = initial status)
+  - `to` (string, required): Target status
+  - `send_email` (boolean, optional): Whether to send email on this transition
+  - `email_subject` (string, optional): Custom email subject for this transition
+  - `email_template` (string | null, optional): Custom email template path
+- **`email`** (object, optional): Email notification settings
+  - `enabled` (boolean, optional): Enable/disable email notifications. Default: `true`
+  - `default_subject` (string, optional): Default email subject. Default: `"Contact Request Status Update"`
+  - `default_template` (string | null, optional): Default email template path
+
 ## REST API
 
 ### Storefront (open)
 
+#### Contact Requests
+
+Create a contact request:
+
+```bash
+curl -X POST https://your-medusa.com/store/contact-requests \
+  -H "Content-Type: application/json" \
+  -H "x-publishable-api-key: pk_storefront" \
+  -d '{
+        "email": "customer@example.com",
+        "payload": {
+          "subject": "Order inquiry",
+          "message": "I need help with my order #12345"
+        },
+        "metadata": {
+          "source_page": "contact"
+        },
+        "source": "storefront"
+      }'
+```
+
+Body fields:
+- `email` – required, valid email address
+- `payload` – optional, JSON object with custom fields (validated against configured `payload_fields`)
+- `metadata` – optional, additional metadata
+- `source` – optional, request source identifier (default: `"storefront"`)
+
+Response:
+
+```json
+{
+  "request": {
+    "id": "creq_123",
+    "email": "customer@example.com",
+    "payload": {
+      "subject": "Order inquiry",
+      "message": "I need help with my order #12345"
+    },
+    "status": "pending",
+    "status_history": [
+      {
+        "from": null,
+        "to": "pending",
+        "changed_at": "2024-11-29T16:33:17.000Z"
+      }
+    ],
+    "metadata": {
+      "source_page": "contact"
+    },
+    "source": "storefront",
+    "created_at": "2024-11-29T16:33:17.000Z",
+    "updated_at": "2024-11-29T16:33:17.000Z"
+  }
+}
+```
+
 #### Email subscriptions
 
 ```bash
@@ -85,6 +246,83 @@ Response:
 
 ### Admin (requires admin auth cookie/token)
 
+#### Contact Requests
+
+List contact requests:
+
+```bash
+curl -X GET "https://your-medusa.com/admin/contact-requests?status=pending&email=customer@example.com&limit=20&offset=0" \
+  -H "Authorization: Bearer <token>"
+```
+
+Query parameters:
+- `email` – optional, filter by email (partial match)
+- `status` – optional, filter by status
+- `source` – optional, filter by source
+- `created_at.gte` – optional, filter by creation date (ISO 8601)
+- `created_at.lte` – optional, filter by creation date (ISO 8601)
+- `limit` – optional, number of results (default: 20, max: 100)
+- `offset` – optional, pagination offset (default: 0)
+- `order` – optional, sort field: `created_at`, `updated_at`, `email` (default: `created_at`)
+- `order_direction` – optional, sort direction: `ASC` or `DESC` (default: `DESC`)
+
+Get contact request details:
+
+```bash
+curl -X GET "https://your-medusa.com/admin/contact-requests/creq_123" \
+  -H "Authorization: Bearer <token>"
+```
+
+Response includes the request and `next_allowed_statuses` array for the admin UI:
+
+```json
+{
+  "request": {
+    "id": "creq_123",
+    "email": "customer@example.com",
+    "payload": { ... },
+    "status": "pending",
+    "status_history": [ ... ],
+    "metadata": { ... },
+    "source": "storefront",
+    "created_at": "2024-11-29T16:33:17.000Z",
+    "updated_at": "2024-11-29T16:33:17.000Z"
+  },
+  "next_allowed_statuses": ["in_progress"]
+}
+```
+
+Create contact request (admin):
+
+```bash
+curl -X POST https://your-medusa.com/admin/contact-requests \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{
+        "email": "customer@example.com",
+        "payload": {
+          "subject": "Support request",
+          "message": "Need assistance"
+        },
+        "source": "admin"
+      }'
+```
+
+Update contact request status:
+
+```bash
+curl -X POST https://your-medusa.com/admin/contact-requests/creq_123/status \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <token>" \
+  -d '{
+        "status": "in_progress"
+      }'
+```
+
+**Note**: Only status transitions defined in `status_transitions` configuration are allowed. The API will return an error if an invalid transition is attempted.
+
+#### Email Subscriptions
+
 List subscriptions:
 
 ```bash
@@ -109,10 +347,88 @@ After running `medusa admin dev --plugins medusa-contact-us`, the sidebar will i
 
 Skip hand-writing `fetch` calls by importing the provided helpers. **Storefront requests must include a publishable API key** (create one under `Settings → API Keys` in the Medusa admin). The helpers automatically attach the header for you.
 
+### Contact Requests
+
+Submit a contact request from your storefront:
+
+```ts
+import { submitContactRequest } from "medusa-contact-us/helpers"
+
+const result = await submitContactRequest(
+  {
+    email: "customer@example.com",
+    payload: {
+      subject: "Order inquiry",
+      message: "I need help with my order #12345",
+      priority: "high",
+    },
+    metadata: {
+      source_page: "contact",
+      user_agent: navigator.userAgent,
+    },
+    source: "storefront",
+  },
+  {
+    baseUrl: "https://store.myshop.com",
+    publishableApiKey: "pk_test_storefront",
+  }
+)
+
+console.log("Request created:", result.request.id)
+```
+
+Using a Medusa JS client:
+
+```ts
+import Medusa from "@medusajs/medusa-js"
+import { submitContactRequest } from "medusa-contact-us/helpers"
+
+const medusa = new Medusa({
+  baseUrl: "https://store.myshop.com",
+  publishableKey: "pk_live_client",
+})
+
+await submitContactRequest(
+  {
+    email: "customer@example.com",
+    payload: {
+      subject: "Support request",
+      message: "Need assistance",
+    },
+  },
+  {
+    client: medusa,
+    publishableApiKey: "pk_live_client",
+  }
+)
+```
+
+For SSR or edge runtimes, preconfigure the helper:
+
+```ts
+import { createSubmitContactRequest } from "medusa-contact-us/helpers"
+
+export const submitRequest = createSubmitContactRequest({
+  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_URL,
+  publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+})
+
+export async function action(formData: FormData) {
+  await submitRequest({
+    email: formData.get("email") as string,
+    payload: {
+      subject: formData.get("subject") as string,
+      message: formData.get("message") as string,
+    },
+    source: "contact_form",
+  })
+}
+```
+
 ### Email subscriptions
 
 ```ts
-import { upsertContactSubscription } from "medusa-contact-us"
+import { upsertContactSubscription } from "medusa-contact-us/helpers"
 
 await upsertContactSubscription(
   {
@@ -131,7 +447,7 @@ Using a Medusa JS client keeps credentials in one place while still letting you
 
 ```ts
 import Medusa from "@medusajs/medusa-js"
-import { upsertContactSubscription } from "medusa-contact-us"
+import { upsertContactSubscription } from "medusa-contact-us/helpers"
 
 const medusa = new Medusa({
   baseUrl: "https://store.myshop.com",
@@ -156,7 +472,7 @@ await upsertContactSubscription(
 For SSR or edge runtimes, preconfigure the helper once:
 
 ```ts
-import { createUpsertContactSubscription } from "medusa-contact-us"
+import { createUpsertContactSubscription } from "medusa-contact-us/helpers"
 
 export const upsertSubscription = createUpsertContactSubscription({
   baseUrl: process.env.NEXT_PUBLIC_MEDUSA_URL,
@@ -166,8 +482,8 @@ export const upsertSubscription = createUpsertContactSubscription({
 export async function action(formData: FormData) {
   await upsertSubscription({
     email: formData.get("email") as string,
-    status: input.unsubscribe ? "unsubscribed" : "subscribed",
-    source: input.source ?? "footer_form",
+    status: formData.get("unsubscribe") ? "unsubscribed" : "subscribed",
+    source: "footer_form",
   })
 }
 ```
@@ -182,6 +498,57 @@ export async function action(formData: FormData) {
 
 Customer-authenticated endpoints still require the appropriate session cookie or JWT. Provide those via the `headers` option if they're not already managed by the browser fetch call.
 
+## Status Workflow
+
+Contact requests follow a configurable status workflow:
+
+1. **Initial Status**: New requests are created with the `default_status` (typically `"pending"`)
+2. **Status Transitions**: Only transitions defined in `status_transitions` are allowed
+3. **Status History**: All status changes are tracked with timestamps and actor information
+4. **Email Notifications**: Emails can be sent on specific transitions when `send_email: true`
+
+### Example Workflow
+
+```
+pending → in_progress → resolved → closed
+```
+
+In this example:
+- Admin can move requests from `pending` to `in_progress` (email sent)
+- Admin can move requests from `in_progress` to `resolved` (email sent)
+- Admin can move requests from `resolved` to `closed` (no email)
+
+### Admin UI Integration
+
+When fetching a contact request via the admin API, the response includes `next_allowed_statuses`:
+
+```json
+{
+  "request": { ... },
+  "next_allowed_statuses": ["in_progress"]
+}
+```
+
+Use this array to populate a status dropdown in your admin UI, ensuring only valid transitions are shown.
+
+## Database Migrations
+
+After installing the plugin, run migrations to create the required tables:
+
+```bash
+npx medusa db:migrate
+```
+
+This will create:
+- `contact_email_subscription` table (for email subscriptions)
+- `contact_request` table (for contact requests)
+
+**Note**: If you're developing the plugin locally, generate migrations after model changes:
+
+```bash
+npx medusa plugin:db:generate
+```
+
 ## Testing & build
 
 ```bash
@@ -193,4 +560,8 @@ Always run `yarn build` after development to ensure the bundler succeeds before
 
 ## Troubleshooting
 
-- Admin UI blank: rebuild the plugin (`yarn build`) and restart the Admin app with the plugin registered in `medusa-config.ts`.
+- **Admin UI blank**: Rebuild the plugin (`yarn build`) and restart the Admin app with the plugin registered in `medusa-config.ts`.
+- **Status transition errors**: Ensure the transition is defined in `status_transitions` configuration. Only transitions from the current status to an allowed next status are permitted.
+- **Payload validation errors**: Check that all required fields defined in `payload_fields` are provided and match the expected types.
+- **Email notifications not sending**: Verify that `email.enabled` is `true` in configuration and that the transition has `send_email: true`. Ensure the notification service is properly configured in your Medusa instance.
+- **Service resolution errors**: Make sure both `ContactSubscriptionModule` and `ContactRequestModule` are registered in the `modules` array in `medusa-config.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-contact-us",
-  "version": "0.0.17",
+  "version": "0.0.21",
   "description": "Manage storefront email subscriptions (opt-ins and opt-outs) in Medusa Admin.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",
@@ -9,6 +9,7 @@
   ],
   "exports": {
     "./package.json": "./package.json",
+    "./workflows": "./.medusa/server/src/workflows/index.js",
     "./helpers": "./.medusa/server/src/helpers/index.js",
     "./.medusa/server/src/modules/*": "./.medusa/server/src/modules/*/index.js",
     "./modules/*": "./.medusa/server/src/modules/*/index.js",