@cimplify/sdk 0.6.6 → 0.6.7

package/dist/index.js

@@ -40,11 +40,72 @@ var ErrorCode = {
   OUT_OF_STOCK: "OUT_OF_STOCK",
   INSUFFICIENT_QUANTITY: "INSUFFICIENT_QUANTITY"
 };
+var DOCS_ERROR_BASE_URL = "https://docs.cimplify.io/reference/error-codes";
+function docsUrlForCode(code) {
+  return `${DOCS_ERROR_BASE_URL}#${code.toLowerCase().replace(/_/g, "-")}`;
+}
+var ERROR_SUGGESTIONS = {
+  UNKNOWN_ERROR: "An unexpected error occurred. Capture the request/response payload and retry with exponential backoff.",
+  NETWORK_ERROR: "Check the shopper's connection and retry. If this persists, inspect CORS, DNS, and API reachability.",
+  TIMEOUT: "The request exceeded the timeout. Retry once, then poll order status before charging again.",
+  UNAUTHORIZED: "Authentication is missing or expired. Ensure a valid access token is set and refresh the session if needed.",
+  FORBIDDEN: "The key/session lacks permission for this resource. Verify business ownership and API key scope.",
+  NOT_FOUND: "The requested resource does not exist or is not visible in this environment.",
+  VALIDATION_ERROR: "One or more fields are invalid. Validate required fields and enum values before retrying.",
+  CART_EMPTY: "The cart has no items. Redirect back to menu/catalogue and require at least one line item.",
+  CART_EXPIRED: "This cart is no longer active. Recreate a new cart and re-add shopper selections.",
+  CART_NOT_FOUND: "Cart could not be located. It may have expired or belongs to a different key/location.",
+  ITEM_UNAVAILABLE: "The selected item is unavailable at this location/time. Prompt the shopper to pick an alternative.",
+  VARIANT_NOT_FOUND: "The requested variant no longer exists. Refresh product data and require re-selection.",
+  VARIANT_OUT_OF_STOCK: "The selected variant is out of stock. Show in-stock variants and block checkout for this line.",
+  ADDON_REQUIRED: "A required add-on is missing. Ensure required modifier groups are completed before add-to-cart.",
+  ADDON_MAX_EXCEEDED: "Too many add-ons were selected. Enforce max selections client-side before submission.",
+  CHECKOUT_VALIDATION_FAILED: "Checkout payload failed validation. Verify customer, order type, and address fields are complete.",
+  DELIVERY_ADDRESS_REQUIRED: "Delivery orders require an address. Collect and pass address info before processing checkout.",
+  CUSTOMER_INFO_REQUIRED: "Customer details are required. Ensure name/email/phone are available before checkout.",
+  PAYMENT_FAILED: "Payment provider rejected or failed processing. Show retry/change-method options to the shopper.",
+  PAYMENT_CANCELLED: "Payment was cancelled by the shopper or provider flow. Allow a safe retry path.",
+  INSUFFICIENT_FUNDS: "Payment method has insufficient funds. Prompt shopper to use another method.",
+  CARD_DECLINED: "Card was declined. Ask shopper to retry or switch payment method.",
+  INVALID_OTP: "Authorization code is invalid. Let shopper re-enter OTP/PIN and retry.",
+  OTP_EXPIRED: "Authorization code expired. Request a new OTP and re-submit authorization.",
+  AUTHORIZATION_FAILED: "Additional payment authorization failed. Retry authorization or change payment method.",
+  PAYMENT_ACTION_NOT_COMPLETED: "Required payment action was not completed. Resume provider flow and poll for status.",
+  SLOT_UNAVAILABLE: "Selected schedule slot is unavailable. Refresh available slots and ask shopper to reselect.",
+  BOOKING_CONFLICT: "The requested booking conflicts with an existing reservation. Pick another slot/resource.",
+  SERVICE_NOT_FOUND: "Requested service no longer exists. Refresh service catalogue and retry selection.",
+  OUT_OF_STOCK: "Inventory is depleted for this item. Remove it or reduce quantity before checkout.",
+  INSUFFICIENT_QUANTITY: "Requested quantity exceeds available inventory. Reduce quantity and retry.",
+  BUSINESS_ID_REQUIRED: "Business context could not be resolved. Verify the public key and business bootstrap call.",
+  INVALID_CART: "Cart is invalid for checkout. Sync cart state, ensure items exist, then retry.",
+  ORDER_TYPE_REQUIRED: "Order type is required. Provide one of delivery, pickup, or dine_in before checkout.",
+  NO_PAYMENT_ELEMENT: "PaymentElement is required for processCheckout(). Mount it before triggering checkout.",
+  PAYMENT_NOT_MOUNTED: "PaymentElement iframe is not mounted. Mount it in the DOM before processCheckout().",
+  AUTH_INCOMPLETE: "AuthElement has not completed authentication. Wait for AUTHENTICATED before checkout.",
+  AUTH_LOST: "Session was cleared during checkout. Re-authenticate and restart checkout safely.",
+  ALREADY_PROCESSING: "Checkout is already in progress. Disable duplicate submits until completion.",
+  CHECKOUT_NOT_READY: "Checkout elements are still initializing. Wait for readiness before submit.",
+  CANCELLED: "Checkout was cancelled. Preserve cart state and allow shopper to retry.",
+  REQUEST_TIMEOUT: "Provider call timed out. Poll payment/order status before issuing another charge attempt.",
+  POPUP_BLOCKED: "Browser blocked provider popup. Ask shopper to enable popups and retry.",
+  FX_QUOTE_FAILED: "Failed to lock FX quote. Retry currency quote or fallback to base currency."
+};
+var ERROR_HINTS = Object.fromEntries(
+  Object.entries(ERROR_SUGGESTIONS).map(([code, suggestion]) => [
+    code,
+    {
+      docs_url: docsUrlForCode(code),
+      suggestion
+    }
+  ])
+);
 var CimplifyError = class extends Error {
-  constructor(code, message, retryable = false) {
+  constructor(code, message, retryable = false, docs_url, suggestion) {
     super(message);
     this.code = code;
     this.retryable = retryable;
+    this.docs_url = docs_url;
+    this.suggestion = suggestion;
     this.name = "CimplifyError";
   }
   /** User-friendly message safe to display */
@@ -55,6 +116,28 @@ var CimplifyError = class extends Error {
 function isCimplifyError(error) {
   return error instanceof CimplifyError;
 }
+function getErrorHint(code) {
+  return ERROR_HINTS[code];
+}
+function enrichError(error, options = {}) {
+  const hint = getErrorHint(error.code);
+  if (hint) {
+    if (!error.docs_url) {
+      error.docs_url = hint.docs_url;
+    }
+    if (!error.suggestion) {
+      error.suggestion = hint.suggestion;
+    }
+  } else if (!error.docs_url) {
+    error.docs_url = docsUrlForCode(error.code || ErrorCode.UNKNOWN_ERROR);
+  }
+  if (options.isTestMode && !error.message.includes("pk_test_")) {
+    error.message = `${error.message}
+
+\u2139 Your API key is a test-mode key (pk_test_...). Verify test data/session before retrying.`;
+  }
+  return error;
+}
 function isRetryableError(error) {
   if (isCimplifyError(error)) {
     return error.retryable;
@@ -138,11 +221,11 @@ function combineObject(results) {
 
 // src/catalogue.ts
 function toCimplifyError(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe(promise) {
   try {
@@ -437,11 +520,11 @@ var CatalogueQueries = class {
 
 // src/cart.ts
 function toCimplifyError2(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe2(promise) {
   try {
@@ -1656,11 +1739,11 @@ var CheckoutResolver = class {
 
 // src/checkout.ts
 function toCimplifyError3(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe3(promise) {
   try {
@@ -1836,11 +1919,11 @@ var CheckoutService = class {
 
 // src/orders.ts
 function toCimplifyError4(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe4(promise) {
   try {
@@ -2097,11 +2180,11 @@ var AuthService = class {
 
 // src/business.ts
 function toCimplifyError7(error) {
-  if (error instanceof CimplifyError) return error;
+  if (error instanceof CimplifyError) return enrichError(error);
   if (error instanceof Error) {
-    return new CimplifyError("UNKNOWN_ERROR", error.message, false);
+    return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, error.message, false));
   }
-  return new CimplifyError("UNKNOWN_ERROR", String(error), false);
+  return enrichError(new CimplifyError(ErrorCode.UNKNOWN_ERROR, String(error), false));
 }
 async function safe7(promise) {
   try {
@@ -2487,12 +2570,15 @@ var EVENT_TYPES = {
 
 // src/elements.ts
 function toCheckoutError(code, message, recoverable) {
+  const hint = getErrorHint(code);
   return {
     success: false,
     error: {
       code,
       message,
-      recoverable
+      recoverable,
+      docs_url: hint?.docs_url,
+      suggestion: hint?.suggestion
     }
   };
 }
@@ -2533,6 +2619,7 @@ var CimplifyElements = class {
     this.paymentData = null;
     this.checkoutInProgress = false;
     this.activeCheckoutAbort = null;
+    this.hasWarnedMissingAuthElement = false;
     this.businessIdResolvePromise = null;
     this.client = client;
     this.businessId = businessId ?? null;
@@ -2628,6 +2715,12 @@ var CimplifyElements = class {
         );
       }
       const authElement = this.elements.get(ELEMENT_TYPES.AUTH);
+      if (!authElement && !this.hasWarnedMissingAuthElement) {
+        this.hasWarnedMissingAuthElement = true;
+        console.warn(
+          "[Cimplify] processCheckout() called without AuthElement mounted. For best conversion and Link enrollment, mount <AuthElement> before checkout."
+        );
+      }
       if (authElement && !this.accessToken) {
         return toCheckoutError(
           "AUTH_INCOMPLETE",
@@ -3064,28 +3157,37 @@ function isRetryable(error) {
   }
   return false;
 }
-function toNetworkError(error) {
+function toNetworkError(error, isTestMode) {
   if (error instanceof DOMException && error.name === "AbortError") {
-    return new CimplifyError(
-      ErrorCode.TIMEOUT,
-      "Request timed out. Please check your connection and try again.",
-      true
+    return enrichError(
+      new CimplifyError(
+        ErrorCode.TIMEOUT,
+        "Request timed out. Please check your connection and try again.",
+        true
+      ),
+      { isTestMode }
     );
   }
   if (error instanceof TypeError && error.message.includes("fetch")) {
-    return new CimplifyError(
-      ErrorCode.NETWORK_ERROR,
-      "Network error. Please check your internet connection.",
-      true
+    return enrichError(
+      new CimplifyError(
+        ErrorCode.NETWORK_ERROR,
+        "Network error. Please check your internet connection.",
+        true
+      ),
+      { isTestMode }
     );
   }
   if (error instanceof CimplifyError) {
-    return error;
-  }
-  return new CimplifyError(
-    ErrorCode.UNKNOWN_ERROR,
-    error instanceof Error ? error.message : "An unknown error occurred",
-    false
+    return enrichError(error, { isTestMode });
+  }
+  return enrichError(
+    new CimplifyError(
+      ErrorCode.UNKNOWN_ERROR,
+      error instanceof Error ? error.message : "An unknown error occurred",
+      false
+    ),
+    { isTestMode }
   );
 }
 function deriveUrls() {
@@ -3147,6 +3249,9 @@ var CimplifyClient = class {
   getPublicKey() {
     return this.publicKey;
   }
+  isTestMode() {
+    return this.publicKey.trim().startsWith("pk_test_");
+  }
   setAccessToken(token) {
     const previous = this.accessToken;
     this.accessToken = token;
@@ -3296,7 +3401,7 @@ var CimplifyClient = class {
         return response;
       } catch (error) {
         lastError = error;
-        const networkError = toNetworkError(error);
+        const networkError = toNetworkError(error, this.isTestMode());
         const errorRetryable = isRetryable(error);
         if (!errorRetryable || attempt >= this.maxRetries) {
           this.hooks.onRequestError?.({
@@ -3319,7 +3424,7 @@ var CimplifyClient = class {
         await sleep(delay);
       }
     }
-    const finalError = toNetworkError(lastError);
+    const finalError = toNetworkError(lastError, this.isTestMode());
     this.hooks.onRequestError?.({
       ...context,
       error: finalError,
@@ -3437,22 +3542,40 @@ var CimplifyClient = class {
   async handleRestResponse(response) {
     const json = await response.json();
     if (!response.ok) {
-      throw new CimplifyError(
-        json.error?.error_code || "API_ERROR",
-        json.error?.error_message || "An error occurred",
-        false
+      const error = enrichError(
+        new CimplifyError(
+          json.error?.error_code || "API_ERROR",
+          json.error?.error_message || "An error occurred",
+          false
+        ),
+        { isTestMode: this.isTestMode() }
       );
+      if (response.status === 401 || error.code === ErrorCode.UNAUTHORIZED) {
+        console.warn(
+          "[Cimplify] Received 401 Unauthorized. Access token may be missing/expired. Refresh authentication and retry the request."
+        );
+      }
+      throw error;
     }
     return json.data;
   }
   async handleResponse(response) {
     const json = await response.json();
     if (!json.success || json.error) {
-      throw new CimplifyError(
-        json.error?.code || "UNKNOWN_ERROR",
-        json.error?.message || "An unknown error occurred",
-        json.error?.retryable || false
+      const error = enrichError(
+        new CimplifyError(
+          json.error?.code || "UNKNOWN_ERROR",
+          json.error?.message || "An unknown error occurred",
+          json.error?.retryable || false
+        ),
+        { isTestMode: this.isTestMode() }
       );
+      if (response.status === 401 || error.code === ErrorCode.UNAUTHORIZED) {
+        console.warn(
+          "[Cimplify] Received 401 Unauthorized. Access token may be missing/expired. Refresh authentication and retry the request."
+        );
+      }
+      throw error;
     }
     return json.data;
   }
@@ -3633,6 +3756,7 @@ exports.DEFAULT_COUNTRY = DEFAULT_COUNTRY;
 exports.DEFAULT_CURRENCY = DEFAULT_CURRENCY;
 exports.DEVICE_TYPE = DEVICE_TYPE;
 exports.ELEMENT_TYPES = ELEMENT_TYPES;
+exports.ERROR_HINTS = ERROR_HINTS;
 exports.EVENT_TYPES = EVENT_TYPES;
 exports.ErrorCode = ErrorCode;
 exports.FxService = FxService;
@@ -3659,6 +3783,7 @@ exports.combineObject = combineObject;
 exports.createCimplifyClient = createCimplifyClient;
 exports.createElements = createElements;
 exports.detectMobileMoneyProvider = detectMobileMoneyProvider;
+exports.enrichError = enrichError;
 exports.err = err;
 exports.flatMap = flatMap;
 exports.formatMoney = formatMoney;
@@ -3673,6 +3798,7 @@ exports.getBasePrice = getBasePrice;
 exports.getCurrencySymbol = getCurrencySymbol;
 exports.getDiscountPercentage = getDiscountPercentage;
 exports.getDisplayPrice = getDisplayPrice;
+exports.getErrorHint = getErrorHint;
 exports.getMarkupPercentage = getMarkupPercentage;
 exports.getOrElse = getOrElse;
 exports.getProductCurrency = getProductCurrency;