medusa-contact-us 0.0.11 → 0.0.20

package/README.md

@@ -1,17 +1,30 @@
 <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.
+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
 
-- ✅ 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
+### Email Subscriptions
 - ✉️ Storefront opt-in helper + admin list for email subscriptions (subscribed/unsubscribed)
-- 🧪 Table-driven tests for payload validation and helper logic
+- 🖥️ 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
 
@@ -23,160 +36,85 @@ npm install medusa-contact-us
 
 ## Configuration
 
-Inside `medusa-config.ts` register the plugin and tailor the options:
+Inside `medusa-config.ts` register the plugin:
 
 ```ts
 import type { ConfigModule } from "@medusajs/framework/types"
 import {
-  defineContactUsPluginOptions,
-  ContactRequestModule,
   ContactSubscriptionModule,
+  ContactRequestModule,
 } from "medusa-contact-us"
 
 const plugins = [
   {
     resolve: "medusa-contact-us",
-    options: defineContactUsPluginOptions({
-      // Form configuration
-      form: {
-        // Maximum payload size in KB
-        max_payload_kb: 128,
-        // Additional custom fields beyond the required email field
-        additional_fields: [
-          {
-            key: "subject",
-            label: "Subject",
-            description: "Brief description of your inquiry",
-            type: "text",
-            required: true,
-            placeholder: "e.g., Order inquiry",
-            helper_text: "Please provide a clear subject line",
-          },
-          {
-            key: "message",
-            label: "Message",
-            description: "Detailed message about your inquiry",
-            type: "textarea",
-            required: true,
-            placeholder: "Please describe your issue or question...",
-          },
-          {
-            key: "priority",
-            label: "Priority",
-            description: "How urgent is your request?",
-            type: "select",
-            required: false,
-            options: [
-              { value: "low", label: "Low" },
-              { value: "medium", label: "Medium" },
-              { value: "high", label: "High" },
-              { value: "urgent", label: "Urgent" },
-            ],
-          },
-          {
-            key: "order_number",
-            label: "Order Number",
-            description: "If this relates to an order, please provide the order number",
-            type: "text",
-            required: false,
-            placeholder: "order_123456",
-          },
-          {
-            key: "phone",
-            label: "Phone Number",
-            type: "text",
-            required: false,
-            placeholder: "+1 (555) 123-4567",
-          },
-          {
-            key: "preferred_contact_method",
-            label: "Preferred Contact Method",
-            type: "select",
-            required: false,
-            options: [
-              { value: "email", label: "Email" },
-              { value: "phone", label: "Phone" },
-            ],
-          },
-          {
-            key: "is_return_request",
-            label: "Is this a return request?",
-            type: "boolean",
-            required: false,
-          },
-        ],
-      },
-      // Status lifecycle configuration
-      statuses: {
-        // Initial status when a request is created
-        initial: "new",
-        // Intermediate statuses (work in progress)
-        intermediates: ["in_review", "waiting_for_customer"],
-        // Final status (request is complete)
-        final: "closed",
-        // Allowed status transitions
-        transitions: {
-          new: ["in_review", "closed"],
-          in_review: ["waiting_for_customer", "closed"],
-          waiting_for_customer: ["in_review", "closed"],
+    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",
         },
-      },
-      // Status options with labels and notification settings
-      status_options: [
         {
-          code: "new",
-          label: "New",
-          description: "Recently submitted requests awaiting review",
-          notify_customer: true,
-          template: "emails/contact-received.mjml",
+          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,
         },
         {
-          code: "in_review",
-          label: "In Review",
-          description: "Assigned to an agent and being reviewed",
-          notify_customer: false,
+          from: "pending",
+          to: "in_progress",
+          send_email: true,
+          email_subject: "Your request is being processed",
+          email_template: null, // Optional: path to email template
         },
         {
-          code: "waiting_for_customer",
-          label: "Waiting for Customer",
-          description: "Awaiting response from customer",
-          notify_customer: true,
-          template: "emails/contact-waiting.mjml",
+          from: "in_progress",
+          to: "resolved",
+          send_email: true,
+          email_subject: "Your request has been resolved",
         },
         {
-          code: "closed",
-          label: "Closed",
-          description: "Resolved and completed",
-          notify_customer: true,
-          template: "emails/contact-final.mjml",
+          from: "resolved",
+          to: "closed",
+          send_email: false,
         },
       ],
-      // Notification configuration
-      notifications: {
-        // Send email when a contact request is created
-        send_on_create: true,
-        // Template for acknowledgement email
-        acknowledgement_template: "emails/contact-received.mjml",
-        // Send email when request reaches final status
-        send_on_final_status: true,
-        // Optional: Custom from address
-        from_address: "support@yourstore.com",
-        // Optional: Reply-to address
-        reply_to: "support@yourstore.com",
-      },
-      // Comments configuration
-      comments: {
-        // Enable admin comments on contact requests
+      email: {
         enabled: true,
-        // Require a note when changing status to final
-        require_note_on_final: true,
+        default_subject: "Contact Request Status Update",
+        default_template: null, // Optional: default email template path
       },
-    }),
+    },
   },
 ]
 
-// Register the ContactRequestModule
-const modules = [ContactRequestModule, ContactSubscriptionModule]
+// Register the modules
+const modules = [ContactSubscriptionModule, ContactRequestModule]
 
 export default {
   projectConfig: {
@@ -189,50 +127,87 @@ export default {
 } satisfies ConfigModule
 ```
 
-### Field Types
-
-Available field types for `additional_fields`:
-- `text`: Single-line text input
-- `textarea`: Multi-line text input
-- `number`: Numeric input
-- `select`: Dropdown selection (requires `options` array)
-- `multi_select`: Multiple selection (requires `options` array)
-- `boolean`: Checkbox
-- `date`: Date picker
-
-### 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`.
+### 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": "Need help", "priority": "high" },
-        "metadata": { "order_id": "order_123" }
+        "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
 {
-  "contact_request": {
-    "id": "crq_123",
+  "request": {
+    "id": "creq_123",
     "email": "customer@example.com",
-    "status": "new",
-    "payload": { "subject": "Need help", "priority": "high" },
+    "payload": {
+      "subject": "Order inquiry",
+      "message": "I need help with my order #12345"
+    },
+    "status": "pending",
     "status_history": [
-      { "status": "new", "updated_at": "2024-11-24T10:00:00.000Z" }
-    ]
+      {
+        "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"
   }
 }
 ```
@@ -271,75 +246,142 @@ Response:
 
 ### Admin (requires admin auth cookie/token)
 
-List:
+#### Contact Requests
+
+List contact requests:
 
 ```bash
-curl -X GET "https://your-medusa.com/admin/contact-requests?status=new&limit=20" \
+curl -X GET "https://your-medusa.com/admin/contact-requests?status=pending&email=customer@example.com&limit=20&offset=0" \
   -H "Authorization: Bearer <token>"
 ```
 
-Detail:
+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/crq_123 \
+curl -X GET "https://your-medusa.com/admin/contact-requests/creq_123" \
   -H "Authorization: Bearer <token>"
 ```
 
-Update status:
+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 PATCH https://your-medusa.com/admin/contact-requests/crq_123 \
-  -H "Authorization: Bearer <token>" \
+curl -X POST https://your-medusa.com/admin/contact-requests \
   -H "Content-Type: application/json" \
-  -d '{ "status": "closed", "note": "Resolved via refund" }'
+  -H "Authorization: Bearer <token>" \
+  -d '{
+        "email": "customer@example.com",
+        "payload": {
+          "subject": "Support request",
+          "message": "Need assistance"
+        },
+        "source": "admin"
+      }'
 ```
 
-Add comment:
+Update contact request status:
 
 ```bash
-curl -X POST https://your-medusa.com/admin/contact-requests/crq_123/comments \
-  -H "Authorization: Bearer <token>" \
+curl -X POST https://your-medusa.com/admin/contact-requests/creq_123/status \
   -H "Content-Type: application/json" \
-  -d '{ "comment": "Waiting on supplier" }'
+  -H "Authorization: Bearer <token>" \
+  -d '{
+        "status": "in_progress"
+      }'
 ```
 
-## Admin UI
+**Note**: Only status transitions defined in `status_transitions` configuration are allowed. The API will return an error if an invalid transition is attempted.
 
-After running `medusa admin dev --plugins medusa-contact-us`, the sidebar will include **Contact Requests**:
+#### Email Subscriptions
 
-- **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.
-- **Contact email list** – dedicated table that displays every storefront opt-in, highlights unsubscribes, and supports filtering/searching by status or email.
+List subscriptions:
 
-All UI components follow the Medusa UI kit spacing (8pt grid), color, and accessibility guidelines.
+```bash
+curl -X GET "https://your-medusa.com/admin/contact-email-subscriptions?status=subscribed&limit=20" \
+  -H "Authorization: Bearer <token>"
+```
+
+Query parameters:
+- `status` – optional, filter by `subscribed` or `unsubscribed`
+- `q` – optional, search by email
+- `limit` – optional, number of results (default: 20)
+- `offset` – optional, pagination offset
+
+## Admin UI
+
+After running `medusa admin dev --plugins medusa-contact-us`, the sidebar will include **Contact email list**:
+
+- **List view** – search by email, filter by status (subscribed/unsubscribed), inspect creation dates and unsubscribe timestamps.
+- 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 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
+### Contact Requests
+
+Submit a contact request from your storefront:
 
 ```ts
-import { submitContactRequest } from "medusa-contact-us"
+import { submitContactRequest } from "medusa-contact-us/helpers"
 
-await submitContactRequest(
+const result = await submitContactRequest(
   {
     email: "customer@example.com",
-    payload: { subject: "Question", priority: "high" },
+    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 keeps credentials in one place while still letting you override headers (including publishable keys) per call:
+Using a Medusa JS client:
 
 ```ts
 import Medusa from "@medusajs/medusa-js"
-import { submitContactRequest } from "medusa-contact-us"
+import { submitContactRequest } from "medusa-contact-us/helpers"
 
 const medusa = new Medusa({
   baseUrl: "https://store.myshop.com",
@@ -349,35 +391,36 @@ const medusa = new Medusa({
 await submitContactRequest(
   {
     email: "customer@example.com",
-    payload: { subject: "Returns" },
+    payload: {
+      subject: "Support request",
+      message: "Need assistance",
+    },
   },
   {
     client: medusa,
     publishableApiKey: "pk_live_client",
-    headers: {
-      Cookie: "connect.sid=...",
-    },
   }
 )
 ```
 
-For SSR or edge runtimes, preconfigure the helper once:
+For SSR or edge runtimes, preconfigure the helper:
 
 ```ts
-import { createSubmitContactRequest } from "medusa-contact-us"
+import { createSubmitContactRequest } from "medusa-contact-us/helpers"
 
-const submitContactRequest = createSubmitContactRequest({
+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 submitContactRequest({
+  await submitRequest({
     email: formData.get("email") as string,
     payload: {
-      subject: formData.get("subject"),
-      message: formData.get("message"),
+      subject: formData.get("subject") as string,
+      message: formData.get("message") as string,
     },
+    source: "contact_form",
   })
 }
 ```
@@ -400,7 +443,33 @@ await upsertContactSubscription(
 )
 ```
 
-To keep deploys DRY, build a preconfigured helper and reuse it everywhere:
+Using a Medusa JS client keeps credentials in one place while still letting you override headers (including publishable keys) per call:
+
+```ts
+import Medusa from "@medusajs/medusa-js"
+import { upsertContactSubscription } from "medusa-contact-us"
+
+const medusa = new Medusa({
+  baseUrl: "https://store.myshop.com",
+  publishableKey: "pk_live_client",
+})
+
+await upsertContactSubscription(
+  {
+    email: "newsletter@example.com",
+    status: "subscribed",
+  },
+  {
+    client: medusa,
+    publishableApiKey: "pk_live_client",
+    headers: {
+      Cookie: "connect.sid=...",
+    },
+  }
+)
+```
+
+For SSR or edge runtimes, preconfigure the helper once:
 
 ```ts
 import { createUpsertContactSubscription } from "medusa-contact-us"
@@ -410,11 +479,13 @@ export const upsertSubscription = createUpsertContactSubscription({
   publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })
 
-await upsertSubscription({
-  email: input.email,
-  status: input.unsubscribe ? "unsubscribed" : "subscribed",
-  source: input.source ?? "footer_form",
-})
+export async function action(formData: FormData) {
+  await upsertSubscription({
+    email: formData.get("email") as string,
+    status: input.unsubscribe ? "unsubscribed" : "subscribed",
+    source: input.source ?? "footer_form",
+  })
+}
 ```
 
 ### Shared helper options
@@ -425,13 +496,58 @@ await upsertSubscription({
 - `fetchImpl` – Custom fetch implementation (SSR, React Native, etc.).
 - `headers` – Additional headers merged into the request (e.g., session cookie, localization). Values you pass here override the defaults, including the publishable key header if you need a per-request key.
 
-Customer-authenticated endpoints (like submitting a request from a logged-in area) 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.
+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
 
-## Workflows & notifications
+When fetching a contact request via the admin API, the response includes `next_allowed_statuses`:
 
-- `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.
+```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
 
@@ -444,6 +560,8 @@ Always run `yarn build` after development to ensure the bundler succeeds before
 
 ## 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`.
+- **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`.