medusa-storefront-core 1.1.0

package/dist/edge.d.ts

@@ -0,0 +1,2 @@
+export { medusaListRegions, medusaMergeCarts } from 'medusa-services';
+export type { MedusaMiddlewareClientOptions } from 'medusa-services';

package/dist/error-boundary.d.ts

@@ -0,0 +1,15 @@
+import { default as React, Component, ReactNode } from 'react';
+
+type Props = {
+    children: ReactNode;
+    fallback?: ReactNode | ((error: Error) => ReactNode);
+};
+type State = {
+    error: Error | null;
+};
+export declare class StorefrontErrorBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    render(): string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<React.AwaitedReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+export declare function parseMedusaStoreError(response: Response): Promise<string>;
+export declare function getErrorMessage(error: unknown, fallback?: string): string;

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './errors';
+export * from './provider';
+export * from './use-storefront-action';
+export * from './site-config';
+export { StorefrontErrorBoundary } from './error-boundary';

package/dist/provider.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+import { StorefrontCompanyConfig } from './site-config';
+
+export type MedusaSiteContextValue = {
+    countryCode?: string;
+    regionId?: string;
+    publishableKey?: string;
+    backendUrl?: string;
+    company?: StorefrontCompanyConfig;
+};
+export type MedusaSiteProviderProps = {
+    children: React.ReactNode;
+    value?: MedusaSiteContextValue;
+    countryCode?: string;
+    regionId?: string;
+    company?: StorefrontCompanyConfig;
+};
+export declare function MedusaSiteProvider({ children, value, countryCode, regionId, company, }: MedusaSiteProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useMedusaSite(): MedusaSiteContextValue;
+/** Shorthand for company details from site config. */
+export declare function useSiteCompany(): StorefrontCompanyConfig;

package/dist/site-config.d.ts

@@ -0,0 +1,52 @@
+import { Metadata } from 'next';
+
+/** Company / brand details passed from each storefront — never hardcode in libraries. */
+export type StorefrontCompanyConfig = {
+    name: string;
+    brandName?: string;
+    customerLabel?: string;
+    contactEmail?: string;
+    phone?: string;
+    description?: string;
+    helpTagline?: string;
+    mapTitle?: string;
+    whyChooseUsTitle?: string;
+    termsSubtitle?: string;
+    privacySubtitle?: string;
+};
+/** Site-specific values passed from each storefront project. */
+export type StorefrontSiteConfig = {
+    siteName: string;
+    siteUrl: string;
+    company?: StorefrontCompanyConfig;
+    gtmId?: string;
+    locale?: string;
+    htmlLang?: string;
+    icons?: {
+        icon?: string;
+        apple?: string;
+    };
+    seo: {
+        titleTemplate: string;
+        defaultTitle: string;
+        description: string;
+        openGraph?: {
+            title?: string;
+            description?: string;
+            image?: string;
+            imageAlt?: string;
+            locale?: string;
+        };
+        twitter?: {
+            title?: string;
+            description?: string;
+            image?: string;
+        };
+    };
+    features?: {
+        cookieConsent?: boolean;
+        metaPixelGuard?: boolean;
+        gtm?: boolean;
+    };
+};
+export declare function buildSiteMetadata(config: StorefrontSiteConfig, metadataBase: URL): Metadata;

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+export type StorefrontErrorCode = "UNKNOWN" | "NETWORK" | "UNAUTHORIZED" | "NOT_FOUND" | "VALIDATION" | "CONFIG";
+export type StorefrontResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    code: StorefrontErrorCode;
+    message: string;
+};
+export declare function ok<T>(data: T): StorefrontResult<T>;
+export declare function err<T = never>(message: string, code?: StorefrontErrorCode): StorefrontResult<T>;
+export declare function fromCaught(error: unknown, fallback?: string): StorefrontResult<never>;

package/dist/ui-library.js

@@ -0,0 +1,144 @@
+var g = Object.defineProperty;
+var h = (e, t, r) => t in e ? g(e, t, { enumerable: !0, configurable: !0, writable: !0, value: r }) : e[t] = r;
+var p = (e, t, r) => h(e, typeof t != "symbol" ? t + "" : t, r);
+import { parseStoreErrorMessage as y } from "medusa-services";
+import { jsx as f } from "react/jsx-runtime";
+import { useMemo as U, useContext as S, createContext as C, useTransition as _, useState as l, useCallback as b, Component as N } from "react";
+function L(e) {
+  return { ok: !0, data: e };
+}
+function M(e, t = "UNKNOWN") {
+  return { ok: !1, code: t, message: e };
+}
+function k(e, t = "Something went wrong") {
+  const r = e instanceof Error ? e.message : t;
+  return M(r);
+}
+async function P(e) {
+  return y(e);
+}
+function B(e, t = "Something went wrong") {
+  return e instanceof Error ? e.message : typeof e == "string" ? e : t;
+}
+const m = {
+  name: "Store",
+  brandName: "Store",
+  customerLabel: "Customer"
+}, d = C({
+  company: m
+});
+function K({
+  children: e,
+  value: t,
+  countryCode: r,
+  regionId: s,
+  company: i
+}) {
+  const a = U(
+    () => ({
+      countryCode: (t == null ? void 0 : t.countryCode) ?? r,
+      regionId: (t == null ? void 0 : t.regionId) ?? s,
+      publishableKey: (t == null ? void 0 : t.publishableKey) ?? process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,
+      backendUrl: (t == null ? void 0 : t.backendUrl) ?? process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL ?? process.env.MEDUSA_BACKEND_URL,
+      company: (t == null ? void 0 : t.company) ?? i ?? m
+    }),
+    [t, r, s, i]
+  );
+  return /* @__PURE__ */ f(d.Provider, { value: a, children: e });
+}
+function I() {
+  return S(d);
+}
+function j() {
+  return S(d).company ?? m;
+}
+function F(e) {
+  const [t, r] = _(), [s, i] = l(null), [a, u] = l(null);
+  return { run: b(
+    (...E) => (i(null), new Promise((c) => {
+      r(() => {
+        (async () => {
+          try {
+            const n = await e(...E);
+            if (n && typeof n == "object" && "ok" in n) {
+              const o = n;
+              o.ok ? u(o.data) : i(o.message), c(o);
+            } else
+              u(n), c({ ok: !0, data: n });
+          } catch (n) {
+            const o = k(n);
+            o.ok || i(o.message), c(o);
+          }
+        })();
+      });
+    })),
+    [e]
+  ), isPending: t, error: s, data: a, clearError: () => i(null) };
+}
+function G(e, t) {
+  const r = e.seo.openGraph ?? {}, s = e.seo.twitter ?? {};
+  return {
+    metadataBase: t,
+    title: {
+      template: e.seo.titleTemplate,
+      default: e.seo.defaultTitle
+    },
+    description: e.seo.description,
+    openGraph: {
+      title: r.title ?? e.seo.defaultTitle,
+      description: r.description ?? e.seo.description,
+      url: e.siteUrl,
+      siteName: e.siteName,
+      images: r.image ? [
+        {
+          url: r.image,
+          width: 1200,
+          height: 630,
+          alt: r.imageAlt ?? e.siteName
+        }
+      ] : void 0,
+      locale: r.locale ?? e.locale ?? "en_US",
+      type: "website"
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: s.title ?? e.seo.defaultTitle,
+      description: s.description ?? e.seo.description,
+      images: s.image ? [s.image] : r.image ? [r.image] : void 0
+    },
+    icons: e.icons,
+    alternates: {
+      canonical: e.siteUrl
+    }
+  };
+}
+class O extends N {
+  constructor() {
+    super(...arguments);
+    p(this, "state", { error: null });
+  }
+  static getDerivedStateFromError(r) {
+    return { error: r };
+  }
+  render() {
+    const { error: r } = this.state;
+    if (r) {
+      const { fallback: s } = this.props;
+      return typeof s == "function" ? s(r) : s || /* @__PURE__ */ f("div", { role: "alert", className: "p-4 text-sm text-red-700", children: r.message });
+    }
+    return this.props.children;
+  }
+}
+export {
+  K as MedusaSiteProvider,
+  O as StorefrontErrorBoundary,
+  G as buildSiteMetadata,
+  M as err,
+  k as fromCaught,
+  B as getErrorMessage,
+  L as ok,
+  P as parseMedusaStoreError,
+  I as useMedusaSite,
+  j as useSiteCompany,
+  F as useStorefrontAction
+};

package/dist/ui-library.umd.cjs

@@ -0,0 +1 @@
+(function(r,o){typeof exports=="object"&&typeof module<"u"?o(exports,require("medusa-services"),require("react/jsx-runtime"),require("react")):typeof define=="function"&&define.amd?define(["exports","medusa-services","react/jsx-runtime","react"],o):(r=typeof globalThis<"u"?globalThis:r||self,o(r.MedusaStorefrontCore={},r.MedusaServices,r.jsxRuntime,r.React))})(this,function(r,o,d,i){"use strict";var A=Object.defineProperty;var P=(r,o,d)=>o in r?A(r,o,{enumerable:!0,configurable:!0,writable:!0,value:d}):r[o]=d;var g=(r,o,d)=>P(r,typeof o!="symbol"?o+"":o,d);function h(e){return{ok:!0,data:e}}function S(e,t="UNKNOWN"){return{ok:!1,code:t,message:e}}function y(e,t="Something went wrong"){const n=e instanceof Error?e.message:t;return S(n)}async function M(e){return o.parseStoreErrorMessage(e)}function C(e,t="Something went wrong"){return e instanceof Error?e.message:typeof e=="string"?e:t}const m={name:"Store",brandName:"Store",customerLabel:"Customer"},l=i.createContext({company:m});function U({children:e,value:t,countryCode:n,regionId:s,company:c}){const f=i.useMemo(()=>({countryCode:(t==null?void 0:t.countryCode)??n,regionId:(t==null?void 0:t.regionId)??s,publishableKey:(t==null?void 0:t.publishableKey)??process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,backendUrl:(t==null?void 0:t.backendUrl)??process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL??process.env.MEDUSA_BACKEND_URL,company:(t==null?void 0:t.company)??c??m}),[t,n,s,c]);return d.jsx(l.Provider,{value:f,children:e})}function b(){return i.useContext(l)}function _(){return i.useContext(l).company??m}function N(e){const[t,n]=i.useTransition(),[s,c]=i.useState(null),[f,E]=i.useState(null);return{run:i.useCallback((...w)=>(c(null),new Promise(p=>{n(()=>{(async()=>{try{const a=await e(...w);if(a&&typeof a=="object"&&"ok"in a){const u=a;u.ok?E(u.data):c(u.message),p(u)}else E(a),p({ok:!0,data:a})}catch(a){const u=y(a);u.ok||c(u.message),p(u)}})()})})),[e]),isPending:t,error:s,data:f,clearError:()=>c(null)}}function k(e,t){const n=e.seo.openGraph??{},s=e.seo.twitter??{};return{metadataBase:t,title:{template:e.seo.titleTemplate,default:e.seo.defaultTitle},description:e.seo.description,openGraph:{title:n.title??e.seo.defaultTitle,description:n.description??e.seo.description,url:e.siteUrl,siteName:e.siteName,images:n.image?[{url:n.image,width:1200,height:630,alt:n.imageAlt??e.siteName}]:void 0,locale:n.locale??e.locale??"en_US",type:"website"},twitter:{card:"summary_large_image",title:s.title??e.seo.defaultTitle,description:s.description??e.seo.description,images:s.image?[s.image]:n.image?[n.image]:void 0},icons:e.icons,alternates:{canonical:e.siteUrl}}}class T extends i.Component{constructor(){super(...arguments);g(this,"state",{error:null})}static getDerivedStateFromError(n){return{error:n}}render(){const{error:n}=this.state;if(n){const{fallback:s}=this.props;return typeof s=="function"?s(n):s||d.jsx("div",{role:"alert",className:"p-4 text-sm text-red-700",children:n.message})}return this.props.children}}r.MedusaSiteProvider=U,r.StorefrontErrorBoundary=T,r.buildSiteMetadata=k,r.err=S,r.fromCaught=y,r.getErrorMessage=C,r.ok=h,r.parseMedusaStoreError=M,r.useMedusaSite=b,r.useSiteCompany=_,r.useStorefrontAction=N,Object.defineProperty(r,Symbol.toStringTag,{value:"Module"})});

package/dist/use-storefront-action.d.ts

@@ -0,0 +1,9 @@
+import { StorefrontResult } from './types';
+
+export declare function useStorefrontAction<TArgs extends unknown[], TData>(action: (...args: TArgs) => Promise<StorefrontResult<TData> | TData>): {
+    run: (...args: TArgs) => Promise<StorefrontResult<TData>>;
+    isPending: boolean;
+    error: string | null;
+    data: TData | null;
+    clearError: () => void;
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "medusa-storefront-core",
+  "version": "1.1.0",
+  "description": "Core types, providers, and error handling for Medusa storefronts.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/ui-library.js",
+      "require": "./dist/ui-library.umd.cjs",
+      "default": "./dist/ui-library.js"
+    },
+    "./edge": {
+      "types": "./src/edge.ts",
+      "import": "./src/edge.ts",
+      "default": "./src/edge.ts"
+    },
+    "./site-config": {
+      "types": "./src/site-config.ts",
+      "import": "./src/site-config.ts",
+      "default": "./src/site-config.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src/edge.ts",
+    "src/site-config.ts"
+  ],
+  "scripts": {
+    "build": "tsc && vite build",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "next": ">=14.0.0",
+    "medusa-services": "^1.1.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "medusa-services": "workspace:*",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0"
+  }
+}

package/src/edge.ts

@@ -0,0 +1,2 @@
+export { medusaListRegions, medusaMergeCarts } from "medusa-services";
+export type { MedusaMiddlewareClientOptions } from "medusa-services";

package/src/site-config.ts

@@ -0,0 +1,97 @@
+import type { Metadata } from "next"
+
+/** Company / brand details passed from each storefront — never hardcode in libraries. */
+export type StorefrontCompanyConfig = {
+  name: string
+  brandName?: string
+  customerLabel?: string
+  contactEmail?: string
+  phone?: string
+  description?: string
+  helpTagline?: string
+  mapTitle?: string
+  whyChooseUsTitle?: string
+  termsSubtitle?: string
+  privacySubtitle?: string
+}
+
+/** Site-specific values passed from each storefront project. */
+export type StorefrontSiteConfig = {
+  siteName: string
+  siteUrl: string
+  company?: StorefrontCompanyConfig
+  gtmId?: string
+  locale?: string
+  htmlLang?: string
+  icons?: {
+    icon?: string
+    apple?: string
+  }
+  seo: {
+    titleTemplate: string
+    defaultTitle: string
+    description: string
+    openGraph?: {
+      title?: string
+      description?: string
+      image?: string
+      imageAlt?: string
+      locale?: string
+    }
+    twitter?: {
+      title?: string
+      description?: string
+      image?: string
+    }
+  }
+  features?: {
+    cookieConsent?: boolean
+    metaPixelGuard?: boolean
+    gtm?: boolean
+  }
+}
+
+export function buildSiteMetadata(
+  config: StorefrontSiteConfig,
+  metadataBase: URL
+): Metadata {
+  const og = config.seo.openGraph ?? {}
+  const tw = config.seo.twitter ?? {}
+
+  return {
+    metadataBase,
+    title: {
+      template: config.seo.titleTemplate,
+      default: config.seo.defaultTitle,
+    },
+    description: config.seo.description,
+    openGraph: {
+      title: og.title ?? config.seo.defaultTitle,
+      description: og.description ?? config.seo.description,
+      url: config.siteUrl,
+      siteName: config.siteName,
+      images: og.image
+        ? [
+            {
+              url: og.image,
+              width: 1200,
+              height: 630,
+              alt: og.imageAlt ?? config.siteName,
+            },
+          ]
+        : undefined,
+      locale: og.locale ?? config.locale ?? "en_US",
+      type: "website",
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: tw.title ?? config.seo.defaultTitle,
+      description: tw.description ?? config.seo.description,
+      images: tw.image ? [tw.image] : og.image ? [og.image] : undefined,
+    },
+    icons: config.icons,
+    alternates: {
+      canonical: config.siteUrl,
+    },
+  }
+}