@superlogic/spree-pay 0.4.12 → 0.5.1

package/README.md

@@ -49,7 +49,6 @@ function CheckoutContent() {
       const result = await process({
         hash: order.hash,
         capture: true, // Optional: auto-capture payment
-        metadata: { orderId: order.id }, // Optional: additional data
       });
 
       console.log('Payment result:', result);
@@ -59,6 +58,7 @@ function CheckoutContent() {
 
       setStatus('success');
     } catch (err) {
+      // `process` always rejects with a PaymentError — see "Error Handling" below
       console.error('Payment failed:', err);
       setStatus('error');
     }
@@ -177,11 +177,10 @@ async function process(params: ProcessFnParams): Promise<PaymentMethodResult>;
 type ProcessFnParams = {
   hash: string; // Order hash from your backend
   capture?: boolean; // Optional: auto-capture payment (default: false)
-  metadata?: Record<string, unknown>; // Optional: additional metadata to pass through
 };
 
 type PaymentMethodResult = {
-  status: SlapiPaymentStatus; // Payment status (AUTHORIZED, CAPTURED, FAILED, etc.)
+  status: PaymentStatus; // Payment status (AUTHORIZED, CAPTURED, FAILED, etc.)
   paymentId: string; // Unique payment identifier
   txHash: string | null; // Transaction hash (for crypto payments)
   txId: string | null; // Transaction ID
@@ -200,7 +199,7 @@ enum PaymentType {
   POINTS = 'POINTS',
 }
 
-enum SlapiPaymentStatus {
+enum PaymentStatus {
   AUTHORIZED = 'AUTHORIZED', // Payment authorized (success)
   CAPTURED = 'CAPTURED', // Payment captured (success)
   FAILED = 'FAILED', // Payment failed
@@ -211,11 +210,76 @@ enum SlapiPaymentStatus {
 }
 ```
 
+### Error Handling
+
+`process()` always rejects with a `PaymentError`. **Branch on `code`** (the failure category) to show your own UI copy. The original error — including any raw backend detail — is kept on `cause` **for logging only; never render it to end users.**
+
+| `code`                           | When                                                                                                       | Suggested UX                                              |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| `PaymentErrorCode.CARD_ERROR`    | A card payment was rejected by the backend (a 4xx response, or a terminal `FAILED` status on a card flow). | "We couldn't process your card — check it / try another." |
+| `PaymentErrorCode.PAYMENT_ERROR` | Anything else: network/server error, timeout, cancelled flow, or a crypto/points failure.                  | Generic "payment failed, try again".                      |
+
+> **Safety:** `message` is a fixed, generic label (e.g. `"Card payment failed"`) — it never contains raw backend text, so it's safe to log or show. To distinguish a real decline (e.g. "insufficient funds") from another 4xx, the backend must return a machine-readable error code; the widget intentionally does **not** surface the backend's free-text message to end users.
+
+```typescript
+import { PaymentError, PaymentErrorCode, SpreePayHttpError, isPaymentError } from '@superlogic/spree-pay';
+
+try {
+  const result = await process({ hash, capture: true });
+  // result.status is AUTHORIZED or CAPTURED
+} catch (err) {
+  if (isPaymentError(err)) {
+    // Choose user-facing copy from the category — do NOT show err.cause to users.
+    if (err.code === PaymentErrorCode.CARD_ERROR) {
+      // card-payment problem — prompt the user to check the card or try another
+    }
+
+    err.code; // PaymentErrorCode — the category to branch on
+    err.status; // PaymentStatus — e.g. FAILED
+    err.backendCode; // string | undefined — a stable backend code when available (e.g. 'INSUFFICIENT_FUNDS')
+
+    // For logging/debugging only — may carry sensitive backend detail:
+    if (err.cause instanceof SpreePayHttpError) {
+      err.cause.status; // numeric HTTP status (e.g. 400, 500)
+      err.cause.body; // raw response body
+      err.cause.url; // request URL
+    }
+  }
+}
+```
+
+```typescript
+enum PaymentErrorCode {
+  CARD_ERROR = 'CARD_ERROR', // a card payment was rejected by the backend
+  PAYMENT_ERROR = 'PAYMENT_ERROR', // network/server/timeout/cancelled/crypto/points failure
+}
+
+// Thrown by the widget; detect it with `isPaymentError` and read its fields.
+// Not meant to be constructed by consumers.
+class PaymentError extends Error {
+  message: string; // fixed, generic label — never raw backend text; safe to log/show
+  code: PaymentErrorCode; // failure category to branch on (defaults to PAYMENT_ERROR)
+  status: PaymentStatus; // payment status at the point of failure
+  backendCode?: string; // stable machine code from the backend when available (e.g. 'INSUFFICIENT_FUNDS') — for finer branching
+  cause?: unknown; // the original thrown value (standard Error.cause) — log only, may hold sensitive detail
+}
+
+// Type guard for consumers — the supported way to detect a PaymentError
+function isPaymentError(e: unknown): e is PaymentError;
+
+// Thrown by the fetcher on a non-ok HTTP response; reachable via PaymentError.cause
+class SpreePayHttpError extends Error {
+  status: number; // HTTP status code
+  body: string; // raw response body
+  url: string; // request URL
+}
+```
+
 ### useCapture3DS Hook
 
 ```typescript
 // Use in your 3DS redirect page to capture payment intent and close the modal
-useCapture3DS(searchParams: Record<string, string | null>);
+useCapture3DS(params: { paymentIntent?: string | null });
 ```
 
 ### Logger API
@@ -248,6 +312,19 @@ enum LogLevel {
 }
 ```
 
+Supporting types are exported so you can name them in your own code:
+
+```typescript
+import type { Environment, LogContext, LoggerConfig } from '@superlogic/spree-pay';
+
+type Environment = 'dev' | 'stg' | 'prod'; // also the `environment` field of the provider's ENV
+type LoggerConfig = { minLevel: LogLevel; prefix: string; environment?: Environment };
+type LogContext = Record<string, unknown>; // the optional context arg on logger.debug/info/warn/error
+
+// configureLogger accepts a partial config:
+function configureLogger(config: Partial<LoggerConfig> & { environment?: Environment }): void;
+```
+
 ## Theme Customization
 
 SpreePay uses CSS variables for theming (see all 58+ variables in `packages/spree-pay/src/styles/globals.css:22-82`). You can override these using CSS or CSS-in-JS.

package/build/{CryptoComTab-DAKL7IZF.js → CryptoComTab-ZAWBJUCM.js}

@@ -1,18 +1,20 @@
 import {
   Iframe3ds
-} from "./chunk-JXZZJ7NS.js";
+} from "./chunk-AXNTOSBU.js";
 import {
   InfoBanner,
   Legal,
-  PaymentError,
   SlapiPaymentService,
   logger,
+  settlePaymentResult,
+  toPaymentError,
+  useIsLoggedIn,
   useSpreePayConfig,
   useSpreePayEnv,
   useSpreePayRegister,
   useSpreePaymentMethod,
   useStaticConfig
-} from "./chunk-WRFG6YIS.js";
+} from "./chunk-PTEQVWLJ.js";
 
 // src/components/CryptoComTab/CryptoComTab.tsx
 import { useCallback, useEffect } from "react";
@@ -27,11 +29,10 @@ var useCryptoComPayment = () => {
     if (selectedPaymentMethod.type !== "CDC" /* CDC */) {
       throw new Error("Unsupported payment method");
     }
-    const { hash, metadata } = params;
+    const { hash } = params;
     cryptoComLogger.info("Starting Crypto.com Pay payment", { hash });
     const { data: paymentResData } = await SlapiPaymentService.createPayment({
       hash,
-      metadata,
       type: "CDC" /* CDC */,
       cdc: {
         returnUrl: `${typeof window !== "undefined" ? window.location.origin : ""}${redirect3dsURI}?payment_intent=success`,
@@ -77,13 +78,14 @@ var useCryptoComPayment = () => {
 // src/components/CryptoComTab/Checkout.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
 var Checkout = () => {
+  const isLoggedIn = useIsLoggedIn();
   const { appProps } = useStaticConfig();
   const { isInternalProcessing } = useSpreePaymentMethod();
   return /* @__PURE__ */ jsx(
     "button",
     {
       onClick: appProps.onProcess,
-      disabled: !!appProps.isProcessing || isInternalProcessing,
+      disabled: !isLoggedIn || !!appProps.isProcessing || isInternalProcessing,
       className: "flex flex-col items-center rounded-md bg-(--crypto-pay-bg) p-2 text-(--brand-primary) hover:bg-(--crypto-pay-bg-hover) disabled:cursor-not-allowed disabled:bg-(--crypto-pay-bg-hover) disabled:text-(--disabled)",
       children: /* @__PURE__ */ jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", className: "h-7 w-[76px]", fill: "none", viewBox: "0 0 76 28", children: [
         /* @__PURE__ */ jsx(
@@ -146,12 +148,9 @@ var CryptoComTab = () => {
     async (data) => {
       try {
         const res = await cryptoComPayment(data);
-        if (["AUTHORIZED" /* AUTHORIZED */, "CAPTURED" /* CAPTURED */].includes(res.status)) {
-          return Promise.resolve(res);
-        }
-        return Promise.reject(new PaymentError("Crypto payment failed", res.status));
-      } catch (_) {
-        return Promise.reject(new PaymentError("Payment failed", "FAILED" /* FAILED */));
+        return settlePaymentResult(res, "Crypto payment failed");
+      } catch (e) {
+        return Promise.reject(toPaymentError(e, "Crypto payment failed"));
       }
     },
     [cryptoComPayment]

package/build/{CryptoTab-57MMM4AG.js → CryptoTab-632DRL2D.js}

@@ -2,21 +2,23 @@ import {
   CheckoutButton,
   PointsSwitch,
   cn as cn2
-} from "./chunk-RORSHUSF.js";
+} from "./chunk-4BM6VTMT.js";
 import {
   Dialog,
   DialogContent,
   DialogDescription,
   DialogTitle,
   InfoBanner,
-  PaymentError,
   SlapiPaymentService,
   cn,
   logger,
+  settlePaymentResult,
+  toPaymentError,
+  useIsLoggedIn,
   useSpreePayConfig,
   useSpreePayRegister,
   useSpreePaymentMethod
-} from "./chunk-WRFG6YIS.js";
+} from "./chunk-PTEQVWLJ.js";
 
 // src/components/CryptoTab/Crypto/CryptoWrapper.tsx
 import { useMemo as useMemo2 } from "react";
@@ -153,7 +155,7 @@ var useCryptoPayment = () => {
       });
       throw error;
     }
-    const { capture, hash, metadata } = params;
+    const { capture, hash } = params;
     const TOKEN = selectedPaymentMethod.method.symbol;
     cryptoPaymentLogger.info("Starting crypto payment", {
       hash,
@@ -213,7 +215,6 @@ var useCryptoPayment = () => {
     const paymentRes = await SlapiPaymentService.createPayment({
       hash,
       capture,
-      metadata,
       type: "CRYPTO" /* CRYPTO */,
       crypto: {
         token: TOKEN,
@@ -763,12 +764,9 @@ var Crypto = () => {
     async (data) => {
       try {
         const res = await cryptoPayment(data);
-        if (["AUTHORIZED" /* AUTHORIZED */, "CAPTURED" /* CAPTURED */].includes(res.status)) {
-          return Promise.resolve(res);
-        }
-        return Promise.reject(new PaymentError("Crypto payment failed", res.status));
-      } catch (_) {
-        return Promise.reject(new PaymentError("Payment failed", "FAILED" /* FAILED */));
+        return settlePaymentResult(res, "Crypto payment failed");
+      } catch (e) {
+        return Promise.reject(toPaymentError(e, "Crypto payment failed"));
       }
     },
     [cryptoPayment]
@@ -812,23 +810,24 @@ function getCachedWagmiConfig(projectId, appName) {
   return cfg;
 }
 var CryptoWrapper = () => {
+  const isLoggedIn = useIsLoggedIn();
   const { spreePayConfig, configIsLoading } = useSpreePayConfig();
   const wagmiConfig = useMemo2(() => {
     if (!spreePayConfig) return null;
     return getCachedWagmiConfig(spreePayConfig.rainbowProjectId, spreePayConfig.rainbowAppName);
   }, [spreePayConfig]);
-  if (configIsLoading || !wagmiConfig) return null;
+  if (!isLoggedIn || configIsLoading || !wagmiConfig) return null;
   return /* @__PURE__ */ jsx12(WagmiProvider, { config: wagmiConfig, children: /* @__PURE__ */ jsx12(QueryClientProvider, { client: queryClient, children: /* @__PURE__ */ jsx12(RainbowKitProvider, { theme: lightTheme({ borderRadius: "large" }), children: /* @__PURE__ */ jsx12(NiceModal3.Provider, { children: /* @__PURE__ */ jsx12(Crypto, {}) }) }) }) });
 };
 
 // src/components/CryptoTab/CryptoTab.tsx
 import { jsx as jsx13, jsxs as jsxs8 } from "react/jsx-runtime";
-var CryptoTab = ({ isLoggedIn }) => {
+var CryptoTab = () => {
   const { spreePayConfig } = useSpreePayConfig();
   return /* @__PURE__ */ jsxs8("div", { children: [
     /* @__PURE__ */ jsx13("div", { className: "border-b border-(--border-component-specific-card) px-5 py-5 md:px-7 md:py-6", children: /* @__PURE__ */ jsx13(CryptoWrapper, {}) }),
     !spreePayConfig?.crypto.hidePoints && /* @__PURE__ */ jsx13("div", { className: "border-b border-(--border-component-specific-card) px-5 py-5 md:px-7 md:py-6", children: /* @__PURE__ */ jsx13(PointsSwitch, { disabled: true, message: spreePayConfig?.crypto.pointsInfoMessage }) }),
-    /* @__PURE__ */ jsx13(CheckoutButton, { isLoggedIn })
+    /* @__PURE__ */ jsx13(CheckoutButton, {})
   ] });
 };
 export {

package/build/{chunk-RORSHUSF.js → chunk-4BM6VTMT.js}

@@ -2,11 +2,12 @@ import {
   InfoBanner,
   Legal,
   cn,
+  useIsLoggedIn,
   useSpreePayConfig,
   useSpreePayEnv,
   useSpreePaymentMethod,
   useStaticConfig
-} from "./chunk-WRFG6YIS.js";
+} from "./chunk-PTEQVWLJ.js";
 
 // src/components/common/PointsSwitch.tsx
 import { useId } from "react";
@@ -205,7 +206,8 @@ var getTransactionFee = (amount = 0, transactionFeePercentage) => {
 
 // src/components/CheckoutButton.tsx
 import { Fragment, jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
-var CheckoutButton = ({ isLoggedIn }) => {
+var CheckoutButton = () => {
+  const isLoggedIn = useIsLoggedIn();
   const { appProps, staticConfig } = useStaticConfig();
   const {
     amount,
@@ -257,15 +259,12 @@ var CheckoutButton = ({ isLoggedIn }) => {
   const checkoutClass = "text-(--inverse) h-14 leading-14 w-full cursor-pointer rounded-4xl bg-(--s-brand) hover:bg-(--s-brand-hover) px-4 text-center text-xl leading-6 font-medium disabled:cursor-not-allowed disabled:bg-(--s-disabled) disabled:text-(--disabled)";
   return /* @__PURE__ */ jsxs3("div", { className: "flex w-full flex-col gap-4 p-6 text-xs leading-5 font-medium text-(--secondary) md:px-7", children: [
     /* @__PURE__ */ jsx5(Legal, {}),
-    isLoggedIn ? /* @__PURE__ */ jsx5(Fragment, { children: onProcess && /* @__PURE__ */ jsx5("button", { disabled: isDisabled, onClick: onProcess, className: checkoutClass, children: getCheckoutContent() }) }) : /* @__PURE__ */ jsxs3(
+    isLoggedIn ? /* @__PURE__ */ jsx5(Fragment, { children: onProcess && /* @__PURE__ */ jsx5("button", { disabled: isDisabled, onClick: onProcess, className: checkoutClass, children: getCheckoutContent() }) }) : /* @__PURE__ */ jsx5(
       "a",
       {
         href: `${staticConfig.keycloakUrl}/realms/${tenantId}/protocol/openid-connect/auth?client_id=${keycloakClientId ?? "oneof-next"}&response_type=code&redirect_uri=${window.location.href}`,
         className: checkoutClass,
-        children: [
-          "Log in / Sign up",
-          tenantId === "moca" ? " for an AIR account" : ""
-        ]
+        children: spreePayConfig?.loginLabel || "Log in / Sign up"
       }
     ),
     /* @__PURE__ */ jsxs3("a", { href: "https://www.spree.finance/", className: "flex items-center justify-center gap-2 hover:underline", children: [

package/build/{chunk-JXZZJ7NS.js → chunk-AXNTOSBU.js}

@@ -3,7 +3,7 @@ import {
   DialogContent,
   DialogDescription,
   DialogTitle
-} from "./chunk-WRFG6YIS.js";
+} from "./chunk-PTEQVWLJ.js";
 
 // src/modals/Iframe3ds.tsx
 import { useEffect } from "react";