@hartl-services/medusa-storefront 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hartl Services GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @hartl-services/medusa-storefront
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Headless storefront for Next.js shops on a Medusa backend with the
+`@hartl-services/medusa-*` plugins: cart, checkout (Stripe), customer account,
+UID check and partner portal. The package holds the commerce logic, the Next
+server/browser adapters and the React hooks; the shop keeps only its markup,
+CMS content and tracking. Bug fixes reach every shop through a version bump.
+
+Next.js App Router (16.2+) and React 19.2+ only. ESM only.
+
+```bash
+pnpm add @hartl-services/medusa-storefront @hartl-services/medusa-contracts \
+  @medusajs/framework@^2.19.0 @medusajs/js-sdk @medusajs/types \
+  @tanstack/react-query @tanstack/react-form \
+  @stripe/stripe-js @stripe/react-stripe-js zod
+```
+
+`@medusajs/framework` is the peer of `@hartl-services/medusa-contracts`, whose
+schemas the package validates with. Install exactly one copy of Contracts
+(`pnpm why @hartl-services/medusa-contracts`).
+
+## Subpaths
+
+| Import | Runs | Contents |
+|---|---|---|
+| `/core` | anywhere | Pure logic: cart and price breakdown, coupon and payment rules, address drafts and schema factories, UID feedback, plugin-feature evaluation, `fields` constants, text codes (`Translate`, `createTranslator`, `StorefrontError`). |
+| `/core/texts-de` | anywhere | German wording of every text code (`textsDe`, `translateDe`). |
+| `/server` | Next server | `createStorefrontServer(config)`: session cookies, every server function behind the shop's Server Actions, cached loaders (region, plugin features, merchant country), Route Handlers (document download, partner portal reads). |
+| `/browser` | browser | `createStorefrontBrowser(config)`: credentialed Medusa client, cart mutations, referral capture, react-query options, Stripe loader. |
+| `/react` | browser | `StorefrontProvider` and the hooks for cart, sign-in, account, checkout, UID check and partner portal. |
+
+## A new shop
+
+The package ships a [shadcn](https://ui.shadcn.com) registry of unstyled
+copy-in components that wire the hooks together. Add it to the shop's
+`components.json`, pinned to the installed package version:
+
+```json
+{
+  "registries": {
+    "@hartl-storefront": "https://cdn.jsdelivr.net/npm/@hartl-services/medusa-storefront@0.1.0/dist/registry/{name}.json"
+  }
+}
+```
+
+```bash
+pnpm dlx shadcn@latest add @hartl-storefront/setup @hartl-storefront/form @hartl-storefront/cart @hartl-storefront/checkout @hartl-storefront/account @hartl-storefront/affiliate
+```
+
+| Item | Adds |
+|---|---|
+| `setup` | `lib/storefront/{server,client,actions,texts,report-error,public-env,image-url}.ts`, `components/storefront/{storefront-providers,storefront-root}.tsx` |
+| `form` | `hooks/use-app-form.ts` and the field components it registers |
+| `cart` | cart widget, line items, totals, add-to-cart, cart page |
+| `checkout` | checkout page, address, shipping/payment (Stripe), coupon, order confirmation |
+| `account` | sign-in (password, code), password reset, verification, addresses, profile, orders, document download route |
+| `affiliate` | partner portal: registration with UID check, links, coupons, commissions, consignment, its Route Handlers |
+
+Then wrap the content of `app/(frontend)/[countryCode]/layout.tsx` in
+`<StorefrontRoot>` and set the environment:
+
+| Variable | |
+|---|---|
+| `NEXT_PUBLIC_MEDUSA_BACKEND_URL` | public Medusa URL (browser and images) |
+| `MEDUSA_BACKEND_URL` | optional internal URL for server calls |
+| `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` | Medusa publishable key |
+| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | Stripe key; without it the payment step shows "not configured" |
+
+The Medusa backend's `STORE_CORS` and `AUTH_CORS` must contain the shop's
+origin (the browser calls Medusa with credentials).
+
+The copied files belong to the shop: style them, rename them, change the
+wording. Keep the commerce logic in the package — a fix there reaches the shop
+with the next version; a fix only in a copied file does not.
+
+## Wiring rules
+
+- Create `createStorefrontServer` and `createStorefrontBrowser` once each, at
+  module level (`lib/storefront/server.ts`, `lib/storefront/client.ts`). The
+  server's per-request cache and the browser's shared state (refunded-cart
+  replacements, in-flight referral captures) rely on a single instance.
+- Every server function the browser calls goes through a `"use server"`
+  wrapper defined in the shop (`lib/storefront/actions.ts`); Next accepts no
+  Server Action from a package. Never re-export from a `"use server"` file.
+- Texts: the package returns text codes; `t` (`translateDe`, or
+  `createTranslator(textsDe, "de-DE", overrides)`) turns them into wording.
+- Tracking goes into the browser config's `callbacks` (`onAddedToCart`,
+  `onCheckoutStarted`, `onPaymentMethodSelected`, `onLoggedOut`); each fires
+  once from the package's hooks.
+- Errors: `reportError(error, { area, context, tags })` receives everything
+  the package reports; hand it to the shop's error tracking.
+- Forms: the shop's TanStack `useAppForm` (its field components are the
+  design) takes the `formOptions` a hook returns.

package/dist/browser/account-verification-channel.d.ts

@@ -0,0 +1,11 @@
+export type AccountVerificationMessage = {
+    type: "email-verified";
+} | {
+    type: "signed-in";
+    path: string;
+};
+export declare function parseAccountVerificationMessage(data: unknown): AccountVerificationMessage | null;
+export declare function canReachOtherTabs(): boolean;
+/** Null where the browser has no BroadcastChannel; callers then simply skip the shortcut. */
+export declare function openAccountVerificationChannel(): BroadcastChannel | null;
+export declare function postAccountVerificationMessage(message: AccountVerificationMessage): void;

package/dist/browser/account-verification-channel.js

@@ -0,0 +1,32 @@
+// Tabs of one browser talk about a pending e-mail confirmation: the tab that
+// opened the confirmation link announces it, the tab that waits with the login
+// signs in and names the page the visitor came from.
+const CHANNEL_NAME = "account-verification";
+// Only pages that show the login form; never an arbitrary path another tab sends.
+const RETURN_PATH = /^\/[a-z]{2}\/(checkout|account|partnerportal)(\/[a-z0-9-]+)*$/;
+export function parseAccountVerificationMessage(data) {
+    if (typeof data !== "object" || data === null) {
+        return null;
+    }
+    const type = Reflect.get(data, "type");
+    if (type === "email-verified") {
+        return { type };
+    }
+    const path = Reflect.get(data, "path");
+    if (type === "signed-in" && typeof path === "string" && RETURN_PATH.test(path)) {
+        return { type, path };
+    }
+    return null;
+}
+export function canReachOtherTabs() {
+    return typeof BroadcastChannel !== "undefined";
+}
+/** Null where the browser has no BroadcastChannel; callers then simply skip the shortcut. */
+export function openAccountVerificationChannel() {
+    return canReachOtherTabs() ? new BroadcastChannel(CHANNEL_NAME) : null;
+}
+export function postAccountVerificationMessage(message) {
+    const channel = openAccountVerificationChannel();
+    channel?.postMessage(message);
+    channel?.close();
+}

package/dist/browser/actions.d.ts

@@ -0,0 +1,49 @@
+import type { StorefrontServer } from "../server/index.js";
+type Server = StorefrontServer;
+/**
+ * The shop's Server Actions, one per server function: Next.js only accepts
+ * `"use server"` functions defined in the app, so the shop wraps each server
+ * function and hands the wrappers to the browser side here.
+ */
+export interface StorefrontActions {
+    getActiveCart: Server["cart"]["getActiveCart"];
+    applyCustomerDefaultsToActiveCart: Server["cart"]["applyCustomerDefaultsToActiveCart"];
+    syncCartId: Server["cart"]["syncCartId"];
+    clearCartId: Server["cart"]["clearCartId"];
+    discardActiveCart: Server["cart"]["discardActiveCart"];
+    retrieveCustomer: Server["customer"]["retrieveCustomer"];
+    loginCustomer: Server["customer"]["loginCustomer"];
+    checkCustomerVerification: Server["customer"]["checkCustomerVerification"];
+    registerCustomer: Server["customer"]["registerCustomer"];
+    requestLoginCode: Server["customer"]["requestLoginCode"];
+    loginWithCode: Server["customer"]["loginWithCode"];
+    requestCustomerPasswordReset: Server["customer"]["requestCustomerPasswordReset"];
+    resetCustomerPassword: Server["customer"]["resetCustomerPassword"];
+    confirmCustomerEmail: Server["customer"]["confirmCustomerEmail"];
+    resendCustomerVerification: Server["customer"]["resendCustomerVerification"];
+    fetchCustomerPasswordPolicy: Server["customer"]["fetchCustomerPasswordPolicy"];
+    updateCustomer: Server["customer"]["updateCustomer"];
+    createCustomerAddress: Server["customer"]["createCustomerAddress"];
+    saveFirstCheckoutAddresses: Server["customer"]["saveFirstCheckoutAddresses"];
+    updateCustomerAddress: Server["customer"]["updateCustomerAddress"];
+    deleteCustomerAddress: Server["customer"]["deleteCustomerAddress"];
+    logoutCustomer: Server["customer"]["logoutCustomer"];
+    listShippingOptions: Server["checkout"]["listShippingOptions"];
+    listPaymentProviders: Server["checkout"]["listPaymentProviders"];
+    listRegions: Server["region"]["listRegions"];
+    fetchPluginFeatures: Server["pluginFeatures"]["fetchPluginFeatures"];
+    checkCartTaxIdentification: Server["taxCompliance"]["checkCartTaxIdentification"];
+    listCustomerTaxIdentifications: Server["taxCompliance"]["listCustomerTaxIdentifications"];
+    verifyCustomerAddressTaxIdentification: Server["taxCompliance"]["verifyCustomerAddressTaxIdentification"];
+    submitAffiliateApplication: Server["affiliate"]["submitAffiliateApplication"];
+    applyAffiliateOwnOrderPromotion: Server["affiliate"]["applyAffiliateOwnOrderPromotion"];
+    createAffiliateSlug: Server["affiliate"]["createAffiliateSlug"];
+    updateAffiliateSlug: Server["affiliate"]["updateAffiliateSlug"];
+    createAffiliateCouponCode: Server["affiliate"]["createAffiliateCouponCode"];
+    rotateAffiliateCouponCode: Server["affiliate"]["rotateAffiliateCouponCode"];
+    revokeAffiliateCouponCode: Server["affiliate"]["revokeAffiliateCouponCode"];
+    createConsignmentReport: Server["affiliate"]["createConsignmentReport"];
+    listOrders: Server["orders"]["listOrders"];
+    listDocuments: Server["documents"]["listDocuments"];
+}
+export {};

package/dist/browser/actions.js

@@ -0,0 +1 @@
+export {};

package/dist/browser/affiliate-referral.d.ts

@@ -0,0 +1,152 @@
+import type { HttpTypes } from "@medusajs/types";
+import type { CredentialedMedusaClient } from "./client.js";
+export interface CaptureAffiliateReferralInput {
+    cartId?: string;
+    slug: string;
+}
+type RefreshActiveCart = () => Promise<Pick<HttpTypes.StoreCart, "id"> | null | undefined>;
+export declare function runAffiliateReferralCapture<T>(capture: () => Promise<T>): Promise<T>;
+export declare function waitForAffiliateReferralCapture(): Promise<void>;
+export declare function removeCapturedAffiliateReferral(searchParams: URLSearchParams, capturedSlug: string): URLSearchParams;
+export declare function captureAffiliateReferralWithClient(sdk: CredentialedMedusaClient, input: CaptureAffiliateReferralInput): Promise<{
+    status: "captured" | "replaced" | "ignored_existing_assignment" | "kept_existing";
+    referral: {
+        id: string;
+        source: "link" | "coupon";
+        status: "active" | "replaced" | "ignored_existing_assignment" | "pending_email_validation" | "consumed" | "expired" | "invalidated";
+        affiliate: {
+            id: string;
+            status: "active";
+        };
+        captured_at: string;
+        expires_at: string;
+    } | null;
+}>;
+export declare function captureAffiliateReferralAfterCartRefreshWithClient(sdk: CredentialedMedusaClient, slug: string, refreshActiveCart: RefreshActiveCart): Promise<{
+    status: "captured" | "replaced" | "ignored_existing_assignment" | "kept_existing";
+    referral: {
+        id: string;
+        source: "link" | "coupon";
+        status: "active" | "replaced" | "ignored_existing_assignment" | "pending_email_validation" | "consumed" | "expired" | "invalidated";
+        affiliate: {
+            id: string;
+            status: "active";
+        };
+        captured_at: string;
+        expires_at: string;
+    } | null;
+}>;
+export interface ApplyCheckoutCouponOptions {
+    useAffiliatePath: boolean;
+}
+export declare function applyCheckoutCouponWithClient(sdk: CredentialedMedusaClient, cartId: string, code: string, { useAffiliatePath }: ApplyCheckoutCouponOptions): Promise<{
+    cart: HttpTypes.StoreCart;
+    kind: "promotion";
+    response?: undefined;
+} | {
+    kind: "affiliate";
+    response: {
+        status: "captured" | "replaced" | "ignored_existing_assignment" | "kept_existing" | "pending_email_validation" | "expired" | "coupon_already_redeemed";
+        referral: {
+            id: string;
+            source: "link" | "coupon";
+            status: "active" | "replaced" | "ignored_existing_assignment" | "pending_email_validation" | "consumed" | "expired" | "invalidated";
+            affiliate: {
+                id: string;
+                status: "active";
+            };
+            captured_at: string;
+            expires_at: string;
+        } | null;
+        discount_applied: boolean;
+        message?: string | undefined;
+    };
+    cart?: undefined;
+}>;
+export declare function resolveCouponLabelsWithClient(sdk: CredentialedMedusaClient, codes: string[]): Promise<{
+    labels: {
+        code: string;
+        label: string;
+        discount_percentage: number;
+    }[];
+}>;
+/** The referral and coupon calls bound to the shop's credentialed client. */
+export declare function createAffiliateReferral(createClient: () => CredentialedMedusaClient): {
+    runAffiliateReferralCapture: typeof runAffiliateReferralCapture;
+    waitForAffiliateReferralCapture: typeof waitForAffiliateReferralCapture;
+    removeCapturedAffiliateReferral: typeof removeCapturedAffiliateReferral;
+    captureAffiliateReferral: (input: CaptureAffiliateReferralInput) => Promise<{
+        status: "captured" | "replaced" | "ignored_existing_assignment" | "kept_existing";
+        referral: {
+            id: string;
+            source: "link" | "coupon";
+            status: "active" | "replaced" | "ignored_existing_assignment" | "pending_email_validation" | "consumed" | "expired" | "invalidated";
+            affiliate: {
+                id: string;
+                status: "active";
+            };
+            captured_at: string;
+            expires_at: string;
+        } | null;
+    }>;
+    captureAffiliateReferralAfterCartRefresh: (slug: string, refreshActiveCart: RefreshActiveCart) => Promise<{
+        status: "captured" | "replaced" | "ignored_existing_assignment" | "kept_existing";
+        referral: {
+            id: string;
+            source: "link" | "coupon";
+            status: "active" | "replaced" | "ignored_existing_assignment" | "pending_email_validation" | "consumed" | "expired" | "invalidated";
+            affiliate: {
+                id: string;
+                status: "active";
+            };
+            captured_at: string;
+            expires_at: string;
+        } | null;
+    }>;
+    applyCheckoutCoupon: (cartId: string, code: string, options: ApplyCheckoutCouponOptions) => Promise<{
+        cart: HttpTypes.StoreCart;
+        kind: "promotion";
+        response?: undefined;
+    } | {
+        kind: "affiliate";
+        response: {
+            status: "captured" | "replaced" | "ignored_existing_assignment" | "kept_existing" | "pending_email_validation" | "expired" | "coupon_already_redeemed";
+            referral: {
+                id: string;
+                source: "link" | "coupon";
+                status: "active" | "replaced" | "ignored_existing_assignment" | "pending_email_validation" | "consumed" | "expired" | "invalidated";
+                affiliate: {
+                    id: string;
+                    status: "active";
+                };
+                captured_at: string;
+                expires_at: string;
+            } | null;
+            discount_applied: boolean;
+            message?: string | undefined;
+        };
+        cart?: undefined;
+    }>;
+    getAffiliateCartReferral: (cartId: string) => Promise<{
+        referral: {
+            id: string;
+            source: "link" | "coupon";
+            status: "active" | "replaced" | "ignored_existing_assignment" | "pending_email_validation" | "consumed" | "expired" | "invalidated";
+            affiliate: {
+                id: string;
+                status: "active";
+            };
+            captured_at: string;
+            expires_at: string;
+        } | null;
+    }>;
+    resolveCouponLabels: (codes: string[]) => Promise<{
+        labels: {
+            code: string;
+            label: string;
+            discount_percentage: number;
+        }[];
+    }>;
+};
+export type BrowserAffiliateReferral = ReturnType<typeof createAffiliateReferral>;
+export {};

package/dist/browser/affiliate-referral.js

@@ -0,0 +1,85 @@
+import { FetchError } from "@medusajs/js-sdk";
+import { affiliateStorePaths } from "@hartl-services/medusa-contracts/paths/affiliate";
+// One per browser page: cart creation waits for every "?ref=" capture still in
+// flight rather than losing it. Module state on purpose, so every caller in
+// the page shares the same set.
+const inFlightReferralCaptures = new Set();
+export function runAffiliateReferralCapture(capture) {
+    const capturePromise = Promise.resolve().then(capture);
+    inFlightReferralCaptures.add(capturePromise);
+    void capturePromise.then(() => inFlightReferralCaptures.delete(capturePromise), () => inFlightReferralCaptures.delete(capturePromise));
+    return capturePromise;
+}
+export async function waitForAffiliateReferralCapture() {
+    while (inFlightReferralCaptures.size > 0) {
+        await Promise.allSettled(inFlightReferralCaptures);
+    }
+}
+export function removeCapturedAffiliateReferral(searchParams, capturedSlug) {
+    if (searchParams.get("ref") !== capturedSlug) {
+        return searchParams;
+    }
+    const nextParams = new URLSearchParams(searchParams);
+    nextParams.delete("ref");
+    return nextParams;
+}
+export async function captureAffiliateReferralWithClient(sdk, input) {
+    return await sdk.client.fetch(affiliateStorePaths.post.captureReferral, {
+        body: { slug: input.slug, ...(input.cartId ? { cart_id: input.cartId } : {}) },
+        credentials: "include",
+        method: "POST",
+    });
+}
+export async function captureAffiliateReferralAfterCartRefreshWithClient(sdk, slug, refreshActiveCart) {
+    return await runAffiliateReferralCapture(async () => {
+        const activeCart = await refreshActiveCart();
+        return await captureAffiliateReferralWithClient(sdk, { cartId: activeCart?.id, slug });
+    });
+}
+export async function applyCheckoutCouponWithClient(sdk, cartId, code, { useAffiliatePath }) {
+    if (!useAffiliatePath) {
+        const { cart } = await sdk.store.cart.addPromotions(cartId, { promo_codes: [code] });
+        return { cart, kind: "promotion" };
+    }
+    try {
+        const response = await sdk.client.fetch(affiliateStorePaths.post.applyAffiliateCoupon, {
+            body: { cart_id: cartId, code },
+            credentials: "include",
+            method: "POST",
+        });
+        return { kind: "affiliate", response };
+    }
+    catch (error) {
+        if (!(error instanceof FetchError) || error.status !== 404) {
+            throw error;
+        }
+        const { cart } = await sdk.store.cart.addPromotions(cartId, { promo_codes: [code] });
+        return { cart, kind: "promotion" };
+    }
+}
+export async function resolveCouponLabelsWithClient(sdk, codes) {
+    if (codes.length === 0) {
+        return { labels: [] };
+    }
+    return await sdk.client.fetch(affiliateStorePaths.post.resolveCouponLabels, {
+        body: { codes },
+        credentials: "include",
+        method: "POST",
+    });
+}
+/** The referral and coupon calls bound to the shop's credentialed client. */
+export function createAffiliateReferral(createClient) {
+    return {
+        runAffiliateReferralCapture,
+        waitForAffiliateReferralCapture,
+        removeCapturedAffiliateReferral,
+        captureAffiliateReferral: (input) => captureAffiliateReferralWithClient(createClient(), input),
+        captureAffiliateReferralAfterCartRefresh: (slug, refreshActiveCart) => captureAffiliateReferralAfterCartRefreshWithClient(createClient(), slug, refreshActiveCart),
+        applyCheckoutCoupon: (cartId, code, options) => applyCheckoutCouponWithClient(createClient(), cartId, code, options),
+        getAffiliateCartReferral: async (cartId) => await createClient().client.fetch(affiliateStorePaths.get.cartReferral(cartId), {
+            credentials: "include",
+            method: "GET",
+        }),
+        resolveCouponLabels: (codes) => resolveCouponLabelsWithClient(createClient(), codes),
+    };
+}

package/dist/browser/browser-session.d.ts

@@ -0,0 +1,3 @@
+import type { CredentialedMedusaClient } from "./client.js";
+export declare function startMedusaBrowserSessionWithClient(sdk: CredentialedMedusaClient, token: string): Promise<void>;
+export declare function endMedusaBrowserSessionWithClient(sdk: CredentialedMedusaClient): Promise<void>;

package/dist/browser/browser-session.js

@@ -0,0 +1,27 @@
+import { FetchError } from "@medusajs/js-sdk";
+// Cart, payment-session and completion calls go to Medusa straight from the
+// browser, where the storefront's HttpOnly JWT cookie is invisible - so
+// without this, Medusa sees every such call as a guest and cannot tell a
+// logged-in customer from a stranger using their email. A Medusa session
+// cookie on the backend host gives those calls the customer's identity. The
+// JWT is handed over exactly once here and never stored in the browser.
+export async function startMedusaBrowserSessionWithClient(sdk, token) {
+    await sdk.client.fetch("/auth/session", {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}` },
+    });
+}
+// A 401 means Medusa no longer has the session (expired, or the backend
+// restarted with its in-memory session store) - the goal of ending it is
+// already reached, so logout must go on instead of failing for good.
+export async function endMedusaBrowserSessionWithClient(sdk) {
+    try {
+        await sdk.auth.logout();
+    }
+    catch (error) {
+        if (error instanceof FetchError && error.status === 401) {
+            return;
+        }
+        throw error;
+    }
+}

package/dist/browser/cart-mutations.d.ts

@@ -0,0 +1,35 @@
+import type { HttpTypes } from "@medusajs/types";
+import type { StorefrontActions } from "./actions.js";
+import type { BrowserAffiliateReferral } from "./affiliate-referral.js";
+import type { CredentialedMedusaClient } from "./client.js";
+interface CartMutationDependencies {
+    actions: Pick<StorefrontActions, "applyCustomerDefaultsToActiveCart" | "clearCartId" | "fetchPluginFeatures" | "getActiveCart" | "syncCartId">;
+    createClient: () => CredentialedMedusaClient;
+    referral: Pick<BrowserAffiliateReferral, "applyCheckoutCoupon" | "waitForAffiliateReferralCapture">;
+    reportCheckoutError: (error: unknown, context?: Record<string, unknown>) => void;
+}
+export declare function createCartMutations({ actions, createClient, referral, reportCheckoutError }: CartMutationDependencies): {
+    createCart: (data: HttpTypes.StoreCreateCart) => Promise<HttpTypes.StoreCart>;
+    replaceRefundedCart(cart: HttpTypes.StoreCart): Promise<HttpTypes.StoreCart | null>;
+    addCartLineItem: (cartId: string, data: HttpTypes.StoreAddCartLineItem) => Promise<HttpTypes.StoreCart>;
+    updateCartLineItem(cartId: string, lineItemId: string, data: HttpTypes.StoreUpdateCartLineItem): Promise<HttpTypes.StoreCart>;
+    removeCartLineItem(cartId: string, lineItemId: string): Promise<HttpTypes.StoreLineItemDeleteResponse>;
+    updateCart(cartId: string, data: HttpTypes.StoreUpdateCart): Promise<HttpTypes.StoreCart>;
+    addCartShippingMethod(cartId: string, data: HttpTypes.StoreAddCartShippingMethods): Promise<HttpTypes.StoreCart>;
+    addCartPromotion(cartId: string, data: HttpTypes.StoreCartAddPromotion): Promise<HttpTypes.StoreCart>;
+    removeCartPromotion(cartId: string, data: HttpTypes.StoreCartRemovePromotion): Promise<HttpTypes.StoreCart>;
+    initiateCartPayment(cartId: string, data: HttpTypes.StoreInitializePaymentSession): Promise<HttpTypes.StorePaymentCollection>;
+    checkCartCompletion(cartId: string): Promise<{
+        cart_id: string;
+        ready: true;
+    }>;
+    completeCart(cartId: string): Promise<HttpTypes.StoreCompleteCartResponse>;
+    /** Adds one unit of a variant, creating the cart first when there is none. */
+    addProductToCart({ activeCart, regionId, variantId }: {
+        activeCart: Pick<HttpTypes.StoreCart, "id"> | null;
+        regionId: string;
+        variantId: string;
+    }): Promise<Pick<HttpTypes.StoreCart, "id">>;
+};
+export type BrowserCartMutations = ReturnType<typeof createCartMutations>;
+export {};

package/dist/browser/cart-mutations.js

@@ -0,0 +1,137 @@
+import { checkoutStorePaths } from "@hartl-services/medusa-contracts/paths/checkout";
+import { buildReplacementCart, getCustomerCouponCodes } from "../core/cart/refunded-cart.js";
+import { hasCartPromotionCode } from "../core/checkout/checkout-coupon.js";
+import { isPluginFeatureEnabled } from "../core/plugin-features.js";
+// One per browser page, shared by every active-cart fetch: concurrent fetches
+// of a refunded cart share one replacement.
+const refundedCartReplacements = new Map();
+// Cart creation/mutation runs through the browser-credentialed client, not a
+// Server Action - Medusa's own host-only cookies must be attached directly
+// from the browser.
+export function createCartMutations({ actions, createClient, referral, reportCheckoutError }) {
+    async function createCartNow(data) {
+        const sdk = createClient();
+        const { cart } = await sdk.store.cart.create(data);
+        await actions.syncCartId(cart.id);
+        return (await actions.applyCustomerDefaultsToActiveCart()) ?? cart;
+    }
+    // Best effort through the coupon field's own path (affiliate coupon first,
+    // Medusa promotion on 404): a code that no longer applies is simply left off.
+    // A shipping coupon cannot apply before a shipping method is chosen.
+    async function reapplyCouponCodes(codes) {
+        if (codes.length === 0) {
+            return;
+        }
+        const cart = await actions.getActiveCart();
+        if (!cart) {
+            return;
+        }
+        try {
+            const useAffiliatePath = isPluginFeatureEnabled(await actions.fetchPluginFeatures(), "affiliate", "coupons");
+            for (const code of codes.filter((code) => !hasCartPromotionCode(cart, code))) {
+                await referral.applyCheckoutCoupon(cart.id, code, { useAffiliatePath }).catch((error) => reportCheckoutError(error, { cartId: cart.id }));
+            }
+        }
+        catch (error) {
+            // The replacement cart already exists; only its coupons are missing.
+            reportCheckoutError(error, { cartId: cart.id });
+        }
+    }
+    async function createCart(data) {
+        await referral.waitForAffiliateReferralCapture();
+        return await createCartNow(data);
+    }
+    async function addCartLineItem(cartId, data) {
+        const sdk = createClient();
+        const { cart } = await sdk.store.cart.createLineItem(cartId, data);
+        return cart;
+    }
+    return {
+        createCart,
+        // Swaps a cart whose payment was refunded (see refunded-cart.ts) for a fresh
+        // one with the same contents, so the customer simply pays again. Concurrent
+        // active-cart fetches share one replacement. Deliberately skips the referral
+        // wait: a "?ref=" capture refreshes the active cart itself and would wait on
+        // this replacement in turn; it then captures onto the new cart.
+        replaceRefundedCart(cart) {
+            const pending = refundedCartReplacements.get(cart.id);
+            if (pending) {
+                return pending;
+            }
+            const replacement = createCartNow(buildReplacementCart(cart))
+                .then(() => reapplyCouponCodes(getCustomerCouponCodes(cart)))
+                .then(() => actions.getActiveCart())
+                .catch((error) => {
+                // The refunded cart stays usable for display; its own error handling applies.
+                reportCheckoutError(error, { cartId: cart.id });
+                return cart;
+            })
+                .finally(() => refundedCartReplacements.delete(cart.id));
+            refundedCartReplacements.set(cart.id, replacement);
+            return replacement;
+        },
+        addCartLineItem,
+        async updateCartLineItem(cartId, lineItemId, data) {
+            const sdk = createClient();
+            const { cart } = await sdk.store.cart.updateLineItem(cartId, lineItemId, data);
+            return cart;
+        },
+        async removeCartLineItem(cartId, lineItemId) {
+            const sdk = createClient();
+            return await sdk.store.cart.deleteLineItem(cartId, lineItemId);
+        },
+        async updateCart(cartId, data) {
+            const sdk = createClient();
+            const { cart } = await sdk.store.cart.update(cartId, data);
+            return cart;
+        },
+        async addCartShippingMethod(cartId, data) {
+            const sdk = createClient();
+            const { cart } = await sdk.store.cart.addShippingMethod(cartId, data);
+            return cart;
+        },
+        async addCartPromotion(cartId, data) {
+            const sdk = createClient();
+            const { cart } = await sdk.store.cart.addPromotions(cartId, data);
+            return cart;
+        },
+        async removeCartPromotion(cartId, data) {
+            const sdk = createClient();
+            const { cart } = await sdk.store.cart.removePromotions(cartId, data);
+            return cart;
+        },
+        async initiateCartPayment(cartId, data) {
+            const sdk = createClient();
+            const { cart } = await sdk.store.cart.retrieve(cartId);
+            return (await sdk.store.payment.initiatePaymentSession(cart, data)).payment_collection;
+        },
+        // Runs every check the completion runs, without completing. Stripe captures
+        // when the payment is confirmed, so a refusal must come before that, not
+        // after (Medusa then refunds). Same transport and credentials as completeCart,
+        // so the registered-email gate sees the same session.
+        async checkCartCompletion(cartId) {
+            const sdk = createClient();
+            return await sdk.client.fetch(checkoutStorePaths.post.completionCheck(cartId), {
+                credentials: "include",
+                method: "POST",
+            });
+        },
+        async completeCart(cartId) {
+            const sdk = createClient();
+            const result = await sdk.store.cart.complete(cartId);
+            if (result.type === "order") {
+                await actions.clearCartId();
+            }
+            return result;
+        },
+        /** Adds one unit of a variant, creating the cart first when there is none. */
+        async addProductToCart({ activeCart, regionId, variantId }) {
+            const cart = activeCart ?? (await createCart({ region_id: regionId }));
+            await addCartLineItem(cart.id, {
+                quantity: 1,
+                variant_id: variantId,
+            });
+            return cart;
+        },
+    };
+}