medusa-contact-us 0.0.2 → 0.0.8

package/README.md

@@ -10,6 +10,7 @@ Collect, triage, and resolve storefront “contact us” submissions inside the
 - 🗒️ 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
+- ✉️ Storefront opt-in helper + admin list for email subscriptions (subscribed/unsubscribed)
 - 🧪 Table-driven tests for payload validation and helper logic
 
 ## Installation
@@ -29,6 +30,7 @@ import type { ConfigModule } from "@medusajs/framework/types"
 import {
   defineContactUsPluginOptions,
   ContactRequestModule,
+  ContactSubscriptionModule,
 } from "medusa-contact-us"
 
 const plugins = [
@@ -174,7 +176,7 @@ const plugins = [
 ]
 
 // Register the ContactRequestModule
-const modules = [ContactRequestModule]
+const modules = [ContactRequestModule, ContactSubscriptionModule]
 
 export default {
   projectConfig: {
@@ -235,6 +237,38 @@ Response:
 }
 ```
 
+#### Email subscriptions
+
+```bash
+curl -X POST https://your-medusa.com/store/contact-email-subscriptions \
+  -H "Content-Type: application/json" \
+  -H "x-publishable-api-key: pk_storefront" \
+  -d '{
+        "email": "newsletter@example.com",
+        "status": "subscribed",
+        "source": "footer"
+      }'
+```
+
+Body fields:
+- `email` – required, unique per entry (case-insensitive).
+- `status` – optional, defaults to `subscribed`. Pass `"unsubscribed"` to honor opt-outs.
+- `metadata` / `source` – optional context stored alongside the entry.
+
+Response:
+
+```json
+{
+  "subscription": {
+    "id": "csub_123",
+    "email": "newsletter@example.com",
+    "status": "subscribed",
+    "source": "footer",
+    "created_at": "2024-11-26T10:00:00.000Z"
+  }
+}
+```
+
 ### Admin (requires admin auth cookie/token)
 
 List:
@@ -276,37 +310,123 @@ After running `medusa admin dev --plugins medusa-contact-us`, the sidebar will i
 - **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.
 
 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:
+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
 
 ```ts
 import { submitContactRequest } from "medusa-contact-us"
 
-await submitContactRequest({
-  email: "customer@example.com",
-  payload: { subject: "Question", priority: "high" },
-})
+await submitContactRequest(
+  {
+    email: "customer@example.com",
+    payload: { subject: "Question", priority: "high" },
+  },
+  {
+    baseUrl: "https://store.myshop.com",
+    publishableApiKey: "pk_test_storefront",
+  }
+)
 ```
 
-Passing a Medusa JS client automatically reuses its transport:
+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 { submitContactRequest } from "medusa-contact-us"
 
-const client = new Medusa({ baseUrl: "https://your-medusa.com" })
+const medusa = new Medusa({
+  baseUrl: "https://store.myshop.com",
+  publishableKey: "pk_live_client",
+})
+
+await submitContactRequest(
+  {
+    email: "customer@example.com",
+    payload: { subject: "Returns" },
+  },
+  {
+    client: medusa,
+    publishableApiKey: "pk_live_client",
+    headers: {
+      Cookie: "connect.sid=...",
+    },
+  }
+)
+```
+
+For SSR or edge runtimes, preconfigure the helper once:
 
-await submitContactRequest({
-  client,
-  email: "customer@example.com",
-  payload: { subject: "Returns" },
+```ts
+import { createSubmitContactRequest } from "medusa-contact-us"
+
+const submitContactRequest = createSubmitContactRequest({
+  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_URL,
+  publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
 })
+
+export async function action(formData: FormData) {
+  await submitContactRequest({
+    email: formData.get("email") as string,
+    payload: {
+      subject: formData.get("subject"),
+      message: formData.get("message"),
+    },
+  })
+}
 ```
 
+### Email subscriptions
+
+```ts
+import { upsertContactSubscription } from "medusa-contact-us"
+
+await upsertContactSubscription(
+  {
+    email: "newsletter@example.com",
+    status: "subscribed",
+    metadata: { channel: "footer" },
+  },
+  {
+    baseUrl: "https://store.myshop.com",
+    publishableApiKey: "pk_test_storefront",
+  }
+)
+```
+
+To keep deploys DRY, build a preconfigured helper and reuse it everywhere:
+
+```ts
+import { createUpsertContactSubscription } from "medusa-contact-us"
+
+export const upsertSubscription = createUpsertContactSubscription({
+  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_URL,
+  publishableApiKey: process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+})
+
+await upsertSubscription({
+  email: input.email,
+  status: input.unsubscribe ? "unsubscribed" : "subscribed",
+  source: input.source ?? "footer_form",
+})
+```
+
+### Shared helper options
+
+- `publishableApiKey` – Automatically sets the `x-publishable-api-key` header when no Medusa client is used.
+- `baseUrl` – Storefront API origin (ignored when `client` is provided).
+- `client` – Pre-configured Medusa JS/SDK instance (reuses its base URL and publishable key).
+- `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.
+
 ## Workflows & notifications
 
 - `createContactRequestWorkflow` validates payloads, persists the request, and optionally fires an acknowledgement email.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-contact-us",
-  "version": "0.0.2",
+  "version": "0.0.8",
   "description": "A starter for Medusa plugins.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",
@@ -10,6 +10,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",
     "./providers/*": "./.medusa/server/src/providers/*/index.js",