@cimplify/sdk 0.6.6 → 0.6.8

package/dist/advanced.mjs

@@ -7,11 +7,84 @@ function err(error) {
 }
 
 // src/types/common.ts
+function money(value) {
+  return value;
+}
+function moneyFromNumber(value) {
+  return value.toFixed(2);
+}
+function currencyCode(value) {
+  return value;
+}
+var ErrorCode = {
+  // General
+  UNKNOWN_ERROR: "UNKNOWN_ERROR"};
+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 */
@@ -19,14 +92,104 @@ var CimplifyError = class extends Error {
     return this.message;
   }
 };
+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;
+}
+
+// src/query/builder.ts
+function escapeQueryValue(value) {
+  return value.replace(/'/g, "\\'");
+}
+var QueryBuilder = class {
+  constructor(entity) {
+    this.filters = [];
+    this.modifiers = [];
+    this.pathSegments = [];
+    this.entity = entity;
+  }
+  path(segment) {
+    this.pathSegments.push(segment);
+    return this;
+  }
+  where(field, op, value) {
+    const v = typeof value === "string" ? `'${escapeQueryValue(value)}'` : value;
+    if (op === "contains" || op === "startsWith") {
+      this.filters.push(`@.${field} ${op} ${v}`);
+    } else {
+      this.filters.push(`@.${field}${op}${v}`);
+    }
+    return this;
+  }
+  and(field, op, value) {
+    return this.where(field, op, value);
+  }
+  sort(field, order = "asc") {
+    this.modifiers.push(`sort(${field},${order})`);
+    return this;
+  }
+  limit(n) {
+    this.modifiers.push(`limit(${n})`);
+    return this;
+  }
+  offset(n) {
+    this.modifiers.push(`offset(${n})`);
+    return this;
+  }
+  count() {
+    this.modifiers.push("count");
+    return this;
+  }
+  enriched() {
+    this.modifiers.push("enriched");
+    return this;
+  }
+  build() {
+    let query2 = this.entity;
+    if (this.pathSegments.length > 0) {
+      query2 += "." + this.pathSegments.join(".");
+    }
+    if (this.filters.length > 0) {
+      query2 += `[?(${this.filters.join(" && ")})]`;
+    }
+    for (const mod of this.modifiers) {
+      query2 += `#${mod}`;
+    }
+    return query2;
+  }
+  toString() {
+    return this.build();
+  }
+};
+function query(entity) {
+  return new QueryBuilder(entity);
+}
 
 // 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 {
@@ -100,7 +263,7 @@ var CatalogueQueries = class {
     let query2 = "products";
     const filters = [];
     if (options?.category) {
-      filters.push(`@.category_id=='${options.category}'`);
+      filters.push(`@.category_id=='${escapeQueryValue(options.category)}'`);
     }
     if (options?.featured !== void 0) {
       filters.push(`@.featured==${options.featured}`);
@@ -109,7 +272,7 @@ var CatalogueQueries = class {
       filters.push(`@.in_stock==${options.in_stock}`);
     }
     if (options?.search) {
-      filters.push(`@.name contains '${options.search}'`);
+      filters.push(`@.name contains '${escapeQueryValue(options.search)}'`);
     }
     if (options?.min_price !== void 0) {
       filters.push(`@.price>=${options.min_price}`);
@@ -140,7 +303,9 @@ var CatalogueQueries = class {
   }
   async getProductBySlug(slug) {
     const filteredResult = await safe(
-      this.client.query(`products[?(@.slug=='${slug}')]`)
+      this.client.query(
+        `products[?(@.slug=='${escapeQueryValue(slug)}')]`
+      )
     );
     if (!filteredResult.ok) return filteredResult;
     const exactMatch = findProductBySlug(filteredResult.value, slug);
@@ -192,7 +357,7 @@ var CatalogueQueries = class {
   }
   async getCategoryBySlug(slug) {
     const result = await safe(
-      this.client.query(`categories[?(@.slug=='${slug}')]`)
+      this.client.query(`categories[?(@.slug=='${escapeQueryValue(slug)}')]`)
     );
     if (!result.ok) return result;
     if (!result.value.length) {
@@ -201,7 +366,11 @@ var CatalogueQueries = class {
     return ok(result.value[0]);
   }
   async getCategoryProducts(categoryId) {
-    return safe(this.client.query(`products[?(@.category_id=='${categoryId}')]`));
+    return safe(
+      this.client.query(
+        `products[?(@.category_id=='${escapeQueryValue(categoryId)}')]`
+      )
+    );
   }
   async getCollections() {
     return safe(this.client.query("collections"));
@@ -211,7 +380,9 @@ var CatalogueQueries = class {
   }
   async getCollectionBySlug(slug) {
     const result = await safe(
-      this.client.query(`collections[?(@.slug=='${slug}')]`)
+      this.client.query(
+        `collections[?(@.slug=='${escapeQueryValue(slug)}')]`
+      )
     );
     if (!result.ok) return result;
     if (!result.value.length) {
@@ -224,7 +395,9 @@ var CatalogueQueries = class {
   }
   async searchCollections(query2, limit = 20) {
     return safe(
-      this.client.query(`collections[?(@.name contains '${query2}')]#limit(${limit})`)
+      this.client.query(
+        `collections[?(@.name contains '${escapeQueryValue(query2)}')]#limit(${limit})`
+      )
     );
   }
   async getBundles() {
@@ -235,7 +408,9 @@ var CatalogueQueries = class {
   }
   async getBundleBySlug(slug) {
     const result = await safe(
-      this.client.query(`bundles[?(@.slug=='${slug}')]`)
+      this.client.query(
+        `bundles[?(@.slug=='${escapeQueryValue(slug)}')]`
+      )
     );
     if (!result.ok) return result;
     if (!result.value.length) {
@@ -245,7 +420,9 @@ var CatalogueQueries = class {
   }
   async searchBundles(query2, limit = 20) {
     return safe(
-      this.client.query(`bundles[?(@.name contains '${query2}')]#limit(${limit})`)
+      this.client.query(
+        `bundles[?(@.name contains '${escapeQueryValue(query2)}')]#limit(${limit})`
+      )
     );
   }
   async getComposites(options) {
@@ -285,9 +462,9 @@ var CatalogueQueries = class {
   }
   async search(query2, options) {
     const limit = options?.limit ?? 20;
-    let searchQuery = `products[?(@.name contains '${query2}')]`;
+    let searchQuery = `products[?(@.name contains '${escapeQueryValue(query2)}')]`;
     if (options?.category) {
-      searchQuery = `products[?(@.name contains '${query2}' && @.category_id=='${options.category}')]`;
+      searchQuery = `products[?(@.name contains '${escapeQueryValue(query2)}' && @.category_id=='${escapeQueryValue(options.category)}')]`;
     }
     searchQuery += `#limit(${limit})`;
     return safe(this.client.query(searchQuery));
@@ -304,7 +481,7 @@ var CatalogueQueries = class {
   async getMenu(options) {
     let query2 = "menu";
     if (options?.category) {
-      query2 = `menu[?(@.category=='${options.category}')]`;
+      query2 = `menu[?(@.category=='${escapeQueryValue(options.category)}')]`;
     }
     if (options?.limit) {
       query2 += `#limit(${options.limit})`;
@@ -321,11 +498,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 {
@@ -585,6 +762,8 @@ function normalizeStatusResponse(response) {
   }
   const res = response;
   const normalizedStatus = normalizePaymentStatusValue(res.status ?? void 0);
+  const normalizedAmount = typeof res.amount === "string" ? money(res.amount) : typeof res.amount === "number" && Number.isFinite(res.amount) ? moneyFromNumber(res.amount) : void 0;
+  const normalizedCurrency = typeof res.currency === "string" && res.currency.trim().length > 0 ? currencyCode(res.currency) : void 0;
   const paidValue = res.paid === true;
   const derivedPaid = paidValue || [
     "success",
@@ -597,8 +776,8 @@ function normalizeStatusResponse(response) {
   return {
     status: normalizedStatus,
     paid: derivedPaid,
-    amount: res.amount,
-    currency: res.currency,
+    amount: normalizedAmount,
+    currency: normalizedCurrency,
     reference: res.reference,
     message: res.message || ""
   };
@@ -1164,11 +1343,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 {
@@ -1290,14 +1469,17 @@ var CheckoutService = class {
       pay_currency: data.pay_currency,
       fx_quote_id: data.fx_quote_id
     };
-    const baseCurrency = (cart.pricing.currency || checkoutData.pay_currency || "GHS").toUpperCase();
+    const baseCurrency = currencyCode(
+      (cart.pricing.currency || checkoutData.pay_currency || "GHS").toUpperCase()
+    );
     const payCurrency = data.pay_currency?.trim().toUpperCase();
+    const payCurrencyCode = payCurrency ? currencyCode(payCurrency) : void 0;
     const cartTotalAmount = Number.parseFloat(cart.pricing.total_price || "0");
-    if (payCurrency && payCurrency !== baseCurrency && !checkoutData.fx_quote_id && Number.isFinite(cartTotalAmount) && cartTotalAmount > 0) {
+    if (payCurrencyCode && payCurrencyCode !== baseCurrency && !checkoutData.fx_quote_id && Number.isFinite(cartTotalAmount) && cartTotalAmount > 0) {
       const fxQuoteResult = await this.client.fx.lockQuote({
         from: baseCurrency,
-        to: payCurrency,
-        amount: cartTotalAmount
+        to: payCurrencyCode,
+        amount: cart.pricing.total_price
       });
       if (!fxQuoteResult.ok) {
         return ok(
@@ -1308,7 +1490,7 @@ var CheckoutService = class {
           )
         );
       }
-      checkoutData.pay_currency = payCurrency;
+      checkoutData.pay_currency = payCurrencyCode;
       checkoutData.fx_quote_id = fxQuoteResult.value.id;
     }
     data.on_status_change?.("processing", {});
@@ -1344,11 +1526,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 {
@@ -1605,11 +1787,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 {
@@ -1995,12 +2177,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
     }
   };
 }
@@ -2041,6 +2226,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;
@@ -2136,6 +2322,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",
@@ -2549,69 +2741,4 @@ function createElements(client, businessId, options) {
   return new CimplifyElements(client, businessId, options);
 }
 
-// src/query/builder.ts
-var QueryBuilder = class {
-  constructor(entity) {
-    this.filters = [];
-    this.modifiers = [];
-    this.pathSegments = [];
-    this.entity = entity;
-  }
-  path(segment) {
-    this.pathSegments.push(segment);
-    return this;
-  }
-  where(field, op, value) {
-    const v = typeof value === "string" ? `'${value}'` : value;
-    if (op === "contains" || op === "startsWith") {
-      this.filters.push(`@.${field} ${op} ${v}`);
-    } else {
-      this.filters.push(`@.${field}${op}${v}`);
-    }
-    return this;
-  }
-  and(field, op, value) {
-    return this.where(field, op, value);
-  }
-  sort(field, order = "asc") {
-    this.modifiers.push(`sort(${field},${order})`);
-    return this;
-  }
-  limit(n) {
-    this.modifiers.push(`limit(${n})`);
-    return this;
-  }
-  offset(n) {
-    this.modifiers.push(`offset(${n})`);
-    return this;
-  }
-  count() {
-    this.modifiers.push("count");
-    return this;
-  }
-  enriched() {
-    this.modifiers.push("enriched");
-    return this;
-  }
-  build() {
-    let query2 = this.entity;
-    if (this.pathSegments.length > 0) {
-      query2 += "." + this.pathSegments.join(".");
-    }
-    if (this.filters.length > 0) {
-      query2 += `[?(${this.filters.join(" && ")})]`;
-    }
-    for (const mod of this.modifiers) {
-      query2 += `#${mod}`;
-    }
-    return query2;
-  }
-  toString() {
-    return this.build();
-  }
-};
-function query(entity) {
-  return new QueryBuilder(entity);
-}
-
 export { AuthService, BusinessService, CartOperations, CatalogueQueries, CheckoutService as CheckoutOperations, CheckoutService, CimplifyElement, CimplifyElements, ELEMENT_TYPES, EVENT_TYPES, FxService, InventoryService, LinkService, LiteService, MESSAGE_TYPES, OrderQueries, QueryBuilder, SchedulingService, createElements, generateIdempotencyKey, query };