@punchcommerce/punchcommerce-medusa-plugin 0.1.0

package/README.md

@@ -0,0 +1,513 @@
+# PunchCommerce Plugin for Medusa
+
+A Medusa v2 plugin that integrates with [PunchCommerce](https://www.punchcommerce.de/) to enable cXML/PunchOut procurement gateway functionality. 
+Procurement systems redirect buyers to your Medusa storefront where they can browse and add items to a cart, 
+then transfer the cart back to the procurement system.
+
+## How It Works
+
+1. **Buyer clicks a PunchOut link** in their ERP → PunchCommerce redirects to your **storefront's entry route** with `sID` and `uID` query parameters
+2. **Storefront authenticates the buyer** via the Medusa SDK using the `punchcommerce` auth provider (`sdk.auth.login("customer", "punchcommerce", { sID, uID })`)
+3. **Storefront creates a fresh cart** for the session and stores `sID` in `cart.metadata.punchcommerce_session_id`. The buyer shops normally — items are added through the standard Store API.
+4. **On checkout**, the storefront calls `GET /store/punchout/basket?cart_id=...` to receive the PunchOut basket payload + a `punchoutUrl`, then submits the basket as a `multipart/form-data` form to that URL.
+
+## Installation
+
+```shell
+npm install @punchcommerce/punchcommerce-medusa-plugin
+```
+
+## Configuration
+
+The plugin requires you to add **two** entries to your `medusa-config.ts`: the plugin itself and an auth provider inside the Auth module.
+
+Add the plugin to `medusa-config.ts`:
+
+```ts
+ plugins: [
+     // ... other plugins
+    {
+      resolve: "punchcommerce",
+      options: {
+        punchcommerceUrl: process.env.PUNCHCOMMERCE_URL,
+      },
+    },
+ ]
+```
+
+Register the punchcommerce-auth-Provider:
+
+
+```ts
+// medusa-config.ts
+module.exports = defineConfig({
+  modules: [
+    {
+      resolve: "@medusajs/medusa/auth",
+      options: {
+        providers: [
+           // ... other providers
+          {
+            resolve: "punchcommerce/providers/punchcommerce-auth",
+            id: "punchcommerce",
+            options: {
+              punchcommerceUrl: process.env.PUNCHCOMMERCE_URL,
+              disableSessionValidation: false, // never disable in production
+            },
+          },
+        ],
+      },
+    },
+  ],
+})
+```
+
+### Options
+
+| Option | Required | Default | Description |
+| --- | --- | --- | --- |
+| `punchcommerceUrl` | No | `https://www.punchcommerce.de` | Base URL of the PunchCommerce gateway. Override for staging or self-hosted instances. Pass to **both** the plugin entry and the auth-provider entry. |
+| `disableSessionValidation` | No | `false` | Auth-provider option. When `true`, skips the call to `GET /gateway/v3/session/validate` and accepts any well-formed `sID`. Intended for local development without a live PunchCommerce instance — **never enable in production**. |
+
+> Note: the gateway version is currently pinned to `v3` (see `src/modules/punchcommerce-client/service.ts`).
+
+## Customer Setup
+
+Customers are linked to PunchCommerce via an identity in Medusa's Auth module.
+
+1. **In PunchCommerce**: create a customer and copy the *Customer identification* — this is the `uID`.
+2. **In Medusa admin**: open the customer's detail page. On the right sidebar, the **PunchCommerce** widget shows the current link.
+   - Click **Add** (or the pencil icon) and paste the `uID`.
+   - If the same `uID` is already linked to another customer, the API returns an error and the widget displays it.
+   - Use the trash icon to unlink. The link is also auto-removed when the customer is deleted.
+
+## PunchCommerce Configuration
+
+In the PunchCommerce dashboard, configure each customer with:
+
+* **Entry address**: your storefront's PunchOut landing route, e.g. `https://my-store.com/<region>/punchcommerce/authenticate`
+* **Customer identification**: the same `uID` you entered in the Medusa admin
+
+PunchCommerce will redirect buyers to the entry address with `?sID={UUID}&uID={identifier}` appended (plus any [action parameters](#punchout-actions-optional)).
+
+## Storefront Requirements
+
+The plugin is backend-only. The storefront must orchestrate the PunchOut flow.
+
+### 1. Authentication route
+
+Create a route that PunchCommerce redirects to. It must call the Medusa SDK with the `punchcommerce` provider and persist the auth token + `sID`.
+
+> All examples use the Next.js Starter Template: https://github.com/medusajs/nextjs-starter-medusa
+
+```ts
+// app/[region]/punchcommerce/authenticate/route.ts (Next.js)
+import { sdk } from "@lib/config"
+import { setAuthToken } from "@lib/data/cookies"
+import { NextRequest, NextResponse } from "next/server"
+
+export async function GET(request: NextRequest) {
+  const sID = request.nextUrl.searchParams.get("sID")
+  const uID = request.nextUrl.searchParams.get("uID")
+  if (!sID || !uID) {
+    // you can also render a error-page here  
+    return NextResponse.json({ error: "Missing sID or uID" }, { status: 400 })
+  }
+
+  const token = await sdk.auth.login("customer", "punchcommerce", { sID, uID })
+  if (typeof token !== "string") {
+    // you can also render a custom error-page here  
+    return NextResponse.json({ error: "Authentication failed" }, { status: 401 })
+  }
+
+  await setAuthToken(token)
+  const res = NextResponse.redirect(new URL("/store", process.env.NEXT_PUBLIC_BASE_URL))
+   
+  return res
+}
+```
+
+What this triggers in the backend (see `src/providers/punchcommerce-auth/service.ts`):
+
+1. The `sID` is validated against `GET /gateway/v3/session/validate` (unless `disableSessionValidation` is set).
+2. The provider identity is looked up by `entity_id = uID`. If no customer has that `uID` linked, the request fails with `"No PunchCommerce Identity found."`.
+3. On success, Medusa returns an auth token scoped to the linked customer.
+
+### 2. Session-scoped cart
+
+After authentication, create a **new** cart for the PunchOut session and attach the `sID` to its metadata. All Store API operations referencing this cart inherit the link.
+
+```ts
+const { cart } = await sdk.store.cart.create({ region_id, currency_code: "eur" })
+await sdk.store.cart.update(cart.id, {
+  metadata: { punchcommerce_session_id: sID },
+})
+```
+
+Existing carts the customer owns outside of PunchOut are untouched. `getPunchOutCartStep` enforces that the cart used for any transfer/action has `punchcommerce_session_id` set.
+
+### 3. PunchOut Page (replaces checkout)
+
+Instead of the normal checkout, render a dedicated `/punchout` page that loads the prepared basket from the backend, shows it to the buyer for review, and submits it to PunchCommerce via a form on click. The buyer never sees the JSON payload — only the cart summary and a "Submit to procurement" button.
+
+**Data loader** (server action that hits the Store API):
+
+```ts
+// lib/data/punchcommerce.ts
+"use server"
+import { sdk } from "@lib/config"
+import { getAuthHeaders, getCartId } from "./cookies"
+
+export async function getPunchOutBasket() {
+  const cartId = await getCartId()
+  if (!cartId) return null
+
+  return sdk.client.fetch<{ basket: PunchOutPosition[]; punchoutUrl: string }>(
+    `/store/punchout/basket`,
+    {
+      method: "GET",
+      cache: "no-store",
+      query: { cart_id: cartId },
+      headers: { ...(await getAuthHeaders()) },
+    }
+  )
+}
+```
+
+**PunchOut Page**:
+
+```tsx
+// app/[countryCode]/(main)/punchout/page.tsx
+export default async function PunchOutPage() {
+  const data = await getPunchOutBasket()
+  if (!data) return notFound()
+
+  const { basket, punchoutUrl } = data
+
+  return (
+    <div>
+      <h1>Complete PunchOut</h1>
+      <ul>
+        {basket.map((item, i) => (
+          <li key={i}>
+            {item.quantity} × {item.product_name} ({item.product_ordernumber})
+          </li>
+        ))}
+      </ul>
+
+      <form action={punchoutUrl} method="POST">
+        {/* The hidden field MUST wrap the array in `{ basket }` — that is the
+            shape PunchCommerce's /gateway/v3/return endpoint expects. */}
+        <input type="hidden" name="basket" value={JSON.stringify({ basket })} />
+        <button type="submit">Submit to procurement</button>
+      </form>
+    </div>
+  )
+}
+```
+
+### 4. PunchOut Actions (optional)
+
+PunchCommerce can append `actions[]` to the entry URL to ask the storefront to perform additional steps right after authentication. The backend exposes `GET /store/punchout/actions` to process them and the storefront decides what to do with the response.
+
+| Action | Required params | Effect |
+| --- | --- | --- |
+| `restore-basket` | `items=SKU:QTY,SKU:QTY` | Adds the listed items to the current cart. Missing SKUs return as warning notifications. |
+| `detail` | `ordernumber=SKU` | Looks up the product handle for the SKU. Storefront redirects to the product-detail page. |
+| `search` | `keyword=…` | Storefront redirects to its own search results page. |
+| `background-search` | `keyword=…` | Backend builds a basket from search results and returns it together with a `punchoutUrl` (for inline PunchOut sessions that submit search results back). |
+
+A few things to keep in mind before implementing:
+
+- **`restore-basket` always runs** when present, regardless of other actions. It mutates the cart and may add `warning` notifications for missing SKUs. It never sets a navigation response.
+- **Only the first result-producing action wins.** If `actions[]` contains both `detail` and `search`, the backend processes the first one and skips the rest.
+- The input action name is `background-search` (hyphen) but the response discriminant is `background_search` (**underscore**) — always branch on `response.type`, not the raw input string.
+- `notifications` (e.g. "SKU X not found") survive the action call even when a redirect follows. Store them in a cookie or flash session to surface them to the buyer after the redirect.
+
+**Data loader** (add alongside `getPunchOutBasket` in `lib/data/punchcommerce.ts`):
+
+> **Note:** In the authenticate route the auth token and cart were just created, so `getCartId()`/`getAuthHeaders()` may not yet read the freshly-set cookies. Pass both values explicitly from the route; the defaults still work for other callers (e.g. loading the loader from the `/punchout` page after the session is established).
+
+```ts
+// lib/data/punchcommerce.ts
+"use server"
+import { sdk } from "@lib/config"
+import { getAuthHeaders, getCartId } from "./cookies"
+
+type PunchOutActionNotification = { type: "info" | "warning"; message: string }
+type PunchOutActionResponse =
+  | { type: "default" }
+  | { type: "detail"; product_handle: string }
+  | { type: "search"; keyword: string }
+  | { type: "background_search"; basket: PunchOutPosition[]; punchoutUrl: string }
+
+export async function processPunchOutActions(
+  params: URLSearchParams,
+  opts: { cartId?: string; authHeaders?: Record<string, string> } = {}
+): Promise<{ notifications: PunchOutActionNotification[]; response: PunchOutActionResponse } | null> {
+  const cartId = opts.cartId ?? (await getCartId())
+  if (!cartId) return null
+  const headers = opts.authHeaders ?? { ...(await getAuthHeaders()) }
+
+  // Forward all action params (actions[], items, ordernumber, keyword) plus the cart.
+  const query = new URLSearchParams(params)
+  query.set("cart_id", cartId)
+
+  return sdk.client.fetch(`/store/punchout/actions?${query.toString()}`, {
+    method: "GET",
+    cache: "no-store",
+    headers,
+  })
+}
+```
+
+**Extended authenticate route** — after `setAuthToken` and cart creation (Steps 1–2), check for actions and branch on the result:
+
+```ts
+// app/[countryCode]/punchcommerce/authenticate/route.ts (extended from Step 1)
+import { sdk } from "@lib/config"
+import { getCacheTag, setAuthToken, setCartId } from "@lib/data/cookies"
+import { processPunchOutActions, PunchOutPosition } from "@lib/data/punchcommerce"
+import { NextRequest, NextResponse } from "next/server"
+
+// Renders a page that auto-submits a POST form to PunchCommerce on load.
+// Used for background_search, where the buyer never reviews the basket manually.
+function renderAutoSubmitForm(punchoutUrl: string, basket: PunchOutPosition[]) {
+  // Escape double-quotes so the JSON is safe inside an HTML attribute value.
+  const payload = JSON.stringify({ basket }).replace(/"/g, "&quot;")
+  return `<!doctype html><html><body onload="document.forms[0].submit()">
+    <form action="${punchoutUrl}" method="POST">
+      <input type="hidden" name="basket" value="${payload}" />
+      <noscript><button type="submit">Submit to procurement</button></noscript>
+    </form>
+  </body></html>`
+}
+
+export async function GET(request: NextRequest, { params }) {
+  const { countryCode } = await params
+  const url = request.nextUrl
+  const sID = url.searchParams.get("sID")
+  const uID = url.searchParams.get("uID")
+  if (!sID || !uID) {
+    return NextResponse.json({ error: "Missing sID or uID" }, { status: 400 })
+  }
+
+  const token = await sdk.auth.login("customer", "punchcommerce", { sID, uID })
+  if (typeof token !== "string") {
+    return NextResponse.json({ error: "Authentication failed" }, { status: 401 })
+  }
+
+  await setAuthToken(token)
+
+  // Step 2: create a new session-scoped cart with punchcommerce_session_id in metadata.
+  const authHeaders = { authorization: `Bearer ${token}` }
+  const { cart } = await sdk.store.cart.create(
+    { region_id, metadata: { punchcommerce_session_id: sID } },
+    {},
+    authHeaders
+  )
+  await setCartId(cart.id)
+
+  const baseUrl = process.env.NEXT_PUBLIC_BASE_URL!
+  const hasActions = url.searchParams.has("actions[]") || url.searchParams.has("actions")
+
+  if (!hasActions) {
+    return NextResponse.redirect(new URL(`/${countryCode}/store`, baseUrl))
+  }
+
+  // Pass cart.id and the token explicitly — cookies are not yet readable in this request.
+  const dispatch = await processPunchOutActions(url.searchParams, {
+    cartId: cart.id,
+    authHeaders,
+  })
+  const response = dispatch?.response ?? { type: "default" as const }
+
+  switch (response.type) {
+    case "detail":
+      return NextResponse.redirect(
+        new URL(`/${countryCode}/products/${response.product_handle}`, baseUrl)
+      )
+
+    case "search":
+      // Redirect to the store page with a search keyword.
+      return NextResponse.redirect(
+        new URL(`/${countryCode}/store?q=${encodeURIComponent(response.keyword)}`, baseUrl)
+      )
+
+    case "background_search":
+      // The backend already built a basket from the keyword search results.
+      // Return an auto-submitting page so the browser POSTs the basket straight to
+      // PunchCommerce — the basket MUST be wrapped in { basket } (same as Step 3).
+      return new NextResponse(
+        renderAutoSubmitForm(response.punchoutUrl, response.basket),
+        { headers: { "content-type": "text/html" } }
+      )
+
+    default:
+      // restore-basket ran (if requested) but set no navigation response — go to the store.
+      return NextResponse.redirect(new URL(`/${countryCode}/store`, baseUrl))
+  }
+}
+```
+
+> Also see https://www.punchcommerce.de/swagger#/E-Commerce-Integration/post_punchcommerce_authenticate
+
+## Cart Mapping
+
+The plugin maps each Medusa cart line item to a `PunchOutPosition` (`src/modules/punchcommerce-client/transform.ts`):
+
+* `price_net` = the line `subtotal` (net), `price` = `total` (gross), `item_price` = `subtotal / quantity` (net unit price)
+* `tax_rate` is forwarded from the cart line (decimal, e.g. `0.19`)
+* `product_name` is truncated to **39 characters** (OCI/cXML constraint)
+* `packaging_unit` is hardcoded to `"Piece"`; per-variant unit mapping (`PCE`, `KG`, `LTR`, …) is **not yet implemented**
+* The basket is submitted to `${punchcommerceUrl}/gateway/v3/return` as `multipart/form-data` by the storefront
+
+## Cart Lifecycle
+
+After a successful transfer, the Medusa cart is **not** automatically marked complete, archived, or deleted — it remains in its current state. Recommended storefront behavior:
+
+* Start the next PunchOut session by creating a brand-new cart with the new `sID` in its metadata
+
+(The actual purchase order is created later through PunchCommerce / the ERP — Medusa is only the catalog browsing surface.)
+
+## Parallel Sessions
+
+Carts are scoped per `cart_id`, not per customer, so a single PunchCommerce-linked customer can have multiple independent PunchOut sessions in flight.
+
+## REST API Reference
+
+### `GET /store/punchout/basket`
+
+Customer-authenticated (bearer or session). Builds a PunchOut basket from a session-scoped Medusa cart.
+
+| Query | Required | Description |
+| --- | --- | --- |
+| `cart_id` | Yes | Cart whose metadata contains `punchcommerce_session_id`. |
+
+**Response:** `{ basket: PunchOutPosition[], punchoutUrl: string }`
+
+### `GET /store/punchout/actions`
+
+Customer-authenticated. Processes one or more PunchOut entry actions.
+
+| Query | Required | Description |
+| --- | --- | --- |
+| `cart_id` | Yes | Cart to operate on. |
+| `actions[]` | Yes | One or more of `restore-basket`, `detail`, `search`, `background-search`. |
+| `items` | For `restore-basket` | Comma-separated `SKU:QTY` pairs. |
+| `ordernumber` | For `detail` | SKU to look up. |
+| `keyword` | For `search` / `background-search` | Free-text search term. |
+
+**Response:** `{ notifications: PunchOutActionNotification[], response: PunchOutActionResponse }` — see `src/modules/punchcommerce-client/types.ts`.
+
+### `GET | POST | DELETE /admin/customers/:id/punchcommerce-customer`
+
+Admin-authenticated. Backs the customer-detail widget.
+
+* **GET** → `{ punchcommerce_customer: { uid: string } | null }`
+* **POST** body `{ uid: string }` — upserts the link.
+* **DELETE** — removes the link.
+
+## Types Reference
+
+All types are exported from `punchcommerce/modules/punchcommerce-client/types`.
+
+### `PunchOutPosition`
+
+A single line in the PunchOut basket. The plugin builds one position per Medusa cart line item.
+
+```ts
+type PunchOutPosition = {
+  product_ordernumber: string   // SKU of the variant; primary key in PunchCommerce
+  product_name: string          // Display name, truncated to 39 chars (OCI/cXML limit)
+  quantity: number              // Whole-unit count for this line
+  item_price: number            // Net unit price (= price_net / quantity)
+  price: number                 // Gross line total (with tax) — Medusa's `line.total`
+  price_net: number             // Net line total (without tax) — Medusa's `line.subtotal`
+  tax_rate: number              // Decimal tax rate, e.g. 0.19 for 19%
+  type: "product" | "shipping-costs"  // "shipping-costs" reserved; currently all lines are products
+  product: PunchOutProduct      // Embedded product master data (see below)
+}
+```
+
+### `PunchOutProduct`
+
+Product-Data embedded in each PunchOutPosition. Sent to PunchCommerce so the procurement system can store/display the product even if the buyer's catalog doesn't have it.
+
+```ts
+type PunchOutProduct = {
+  id: string                    // Internal product id (Medusa product_id) — informational
+  ordernumber: string           // SKU — duplicates PunchOutPosition.product_ordernumber
+  brand_ordernumber: string     // Manufacturer ordering reference; currently same as `ordernumber`
+  title: string                 // Full untruncated product title
+  description: string           // Plain-text product description
+  image_url?: string | null     // Variant or product thumbnail URL
+  price: number                 // Net unit price (mirrors PunchOutPosition.item_price)
+  currency: string              // ISO 4217 code, lowercase (e.g. "eur") — taken from the cart
+  tax_rate: number              // Same decimal value as PunchOutPosition.tax_rate
+  packaging_unit: string        // Hardcoded "Piece" today; future: per-variant mapping
+  shipping_time: number         // Hardcoded 0 today
+  active: "true" | "false"      // String (not boolean) — PunchCommerce convention
+
+  // Optional fields — not populated by this plugin yet, but accepted by PunchCommerce:
+  brand?: string
+  customer_ordernumber?: string
+  category?: string
+  description_long?: string
+  purchase_unit?: number
+  reference_unit?: number
+  unit?: string                 // OCI unit code, e.g. "PCE", "KG", "LTR"
+  unit_name?: string            // Human-readable unit name
+  weight?: number
+  classification_type?: string
+  classification?: string
+}
+```
+
+### `PunchOutBasket`
+
+Top-level basket wrapper. **This is the shape the PunchCommerce `/gateway/v3/return` endpoint expects** — when submitting the form, wrap the position array in `{ basket: [...] }`.
+
+```ts
+type PunchOutBasket = {
+  basket: PunchOutPosition[]
+}
+```
+
+### `PunchOutActionItem`
+
+Item passed to the `restore-basket` action. The route parses the `items=SKU:QTY,SKU:QTY` query string into an array of these.
+
+```ts
+type PunchOutActionItem = {
+  sku: string
+  quantity: number
+}
+```
+
+### `PunchOutActionNotification`
+
+Warning / info message returned alongside an action response (e.g. when a SKU in `restore-basket` was not found).
+
+```ts
+type PunchOutActionNotification = {
+  type: "info" | "warning"
+  message: string
+}
+```
+
+### `PunchOutActionResponse`
+
+Discriminated union returned by `GET /store/punchout/actions`. The storefront branches on `type` to decide what to do next.
+
+```ts
+type PunchOutActionResponse =
+  | { type: "default" }                                   // No action produced a result — proceed normally
+  | { type: "detail"; product_handle: string }            // Redirect the buyer to the PDP at this handle
+  | { type: "search"; keyword: string }                   // Redirect to your storefront's search page
+  | {                                                     // Inline-search PunchOut: submit the returned basket
+      type: "background_search"
+      basket: PunchOutPosition[]
+      punchoutUrl: string
+    }
+```

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@punchcommerce/punchcommerce-medusa-plugin",
+  "version": "0.1.0",
+  "description": "PunchCommerce Plugin for Medusa",
+  "author": "netzdirektion | Gesellschaft für digitale Wertarbeit mbH",
+  "homepage": "https://www.punchcommerce.de",
+  "license": "UNLICENSED",
+  "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"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "medusa",
+    "plugin",
+    "medusa-plugin-other",
+    "medusa-plugin",
+    "medusa-v2"
+  ],
+  "scripts": {
+    "build": "medusa plugin:build",
+    "dev": "medusa plugin:develop",
+    "prepublishOnly": "medusa plugin:build"
+  },
+  "devDependencies": {
+    "@medusajs/admin-sdk": "2.13.6",
+    "@medusajs/cli": "2.13.6",
+    "@medusajs/framework": "2.13.6",
+    "@medusajs/medusa": "2.13.6",
+    "@medusajs/test-utils": "2.13.6",
+    "@medusajs/ui": "4.1.6",
+    "@medusajs/icons": "2.13.6",
+    "@swc/core": "^1.7.28",
+    "@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",
+    "yalc": "^1.0.0-pre.53"
+  },
+  "peerDependencies": {
+    "@medusajs/admin-sdk": "2.13.0",
+    "@medusajs/cli": "2.13.0",
+    "@medusajs/framework": "2.13.0",
+    "@medusajs/test-utils": "2.13.0",
+    "@medusajs/medusa": "2.13.0",
+    "@medusajs/ui": "4.1.6",
+    "@medusajs/icons": "2.13.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "npm@10.8.2"
+}