@cimplify/sdk 0.6.5 → 0.6.7

package/dist/index.mjs

@@ -38,11 +38,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 */
@@ -53,6 +114,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;
@@ -136,11 +219,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 {
@@ -435,11 +518,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 {
@@ -1654,11 +1737,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 {
@@ -1834,11 +1917,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 {
@@ -2095,11 +2178,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 {
@@ -2485,12 +2568,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
     }
   };
 }
@@ -2531,8 +2617,10 @@ var CimplifyElements = class {
     this.paymentData = null;
     this.checkoutInProgress = false;
     this.activeCheckoutAbort = null;
+    this.hasWarnedMissingAuthElement = false;
+    this.businessIdResolvePromise = null;
     this.client = client;
-    this.businessId = businessId;
+    this.businessId = businessId ?? null;
     this.linkUrl = options.linkUrl || DEFAULT_LINK_URL;
     this.options = options;
     this.boundHandleMessage = this.handleMessage.bind(this);
@@ -2625,6 +2713,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",
@@ -2755,6 +2849,24 @@ var CimplifyElements = class {
   getPublicKey() {
     return this.client.getPublicKey();
   }
+  getBusinessId() {
+    return this.businessId;
+  }
+  async resolveBusinessId() {
+    if (this.businessId) {
+      return this.businessId;
+    }
+    if (this.businessIdResolvePromise) {
+      return this.businessIdResolvePromise;
+    }
+    this.businessIdResolvePromise = this.client.resolveBusinessId().then((resolvedBusinessId) => {
+      this.businessId = resolvedBusinessId;
+      return resolvedBusinessId;
+    }).catch(() => null).finally(() => {
+      this.businessIdResolvePromise = null;
+    });
+    return this.businessIdResolvePromise;
+  }
   getAppearance() {
     return this.options.appearance;
   }
@@ -2859,8 +2971,8 @@ var CimplifyElement = class {
       return;
     }
     this.container = target;
-    this.createIframe();
     this.mounted = true;
+    void this.createIframe();
   }
   destroy() {
     if (this.iframe) {
@@ -2914,11 +3026,21 @@ var CimplifyElement = class {
   isMounted() {
     return this.mounted && Boolean(this.iframe) && this.iframe?.isConnected === true;
   }
-  createIframe() {
+  async createIframe() {
     if (!this.container) return;
+    const resolvedBusinessId = this.businessId ?? await this.parent.resolveBusinessId();
+    if (!resolvedBusinessId || !this.container || !this.mounted) {
+      console.error("Unable to mount element without a resolved business ID");
+      this.emit(EVENT_TYPES.ERROR, {
+        code: "BUSINESS_ID_REQUIRED",
+        message: "Unable to initialize checkout without a business ID."
+      });
+      return;
+    }
+    this.businessId = resolvedBusinessId;
     const iframe = document.createElement("iframe");
     const url = new URL(`${this.linkUrl}/elements/${this.type}`);
-    url.searchParams.set("businessId", this.businessId);
+    url.searchParams.set("businessId", resolvedBusinessId);
     if (this.options.prefillEmail) url.searchParams.set("email", this.options.prefillEmail);
     if (this.options.mode) url.searchParams.set("mode", this.options.mode);
     iframe.src = url.toString();
@@ -2938,7 +3060,7 @@ var CimplifyElement = class {
       const publicKey = this.parent.getPublicKey();
       this.sendMessage({
         type: MESSAGE_TYPES.INIT,
-        businessId: this.businessId,
+        businessId: resolvedBusinessId,
         publicKey,
         demoMode: publicKey.length === 0,
         prefillEmail: this.options.prefillEmail,
@@ -3033,28 +3155,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() {
@@ -3083,6 +3214,8 @@ var CimplifyClient = class {
   constructor(config = {}) {
     this.accessToken = null;
     this.context = {};
+    this.businessId = null;
+    this.businessIdResolvePromise = null;
     this.inflightRequests = /* @__PURE__ */ new Map();
     this.publicKey = config.publicKey || getEnvPublicKey() || "";
     const urls = deriveUrls();
@@ -3114,6 +3247,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;
@@ -3146,6 +3282,47 @@ var CimplifyClient = class {
   getLocationId() {
     return this.context.location_id ?? null;
   }
+  /** Cache a resolved business ID for future element/checkouts initialization. */
+  setBusinessId(businessId) {
+    const normalized = businessId.trim();
+    if (!normalized) {
+      return;
+    }
+    this.businessId = normalized;
+  }
+  /** Get cached business ID if available. */
+  getBusinessId() {
+    return this.businessId;
+  }
+  /**
+   * Resolve business ID from public key once and cache it.
+   * Subsequent calls return the cached value (or shared in-flight promise).
+   */
+  async resolveBusinessId() {
+    if (this.businessId) {
+      return this.businessId;
+    }
+    if (this.businessIdResolvePromise) {
+      return this.businessIdResolvePromise;
+    }
+    this.businessIdResolvePromise = (async () => {
+      const result = await this.business.getInfo();
+      if (!result.ok || !result.value?.id) {
+        throw new CimplifyError(
+          ErrorCode.NOT_FOUND,
+          "Unable to resolve business ID from the current public key.",
+          true
+        );
+      }
+      this.businessId = result.value.id;
+      return result.value.id;
+    })();
+    try {
+      return await this.businessIdResolvePromise;
+    } finally {
+      this.businessIdResolvePromise = null;
+    }
+  }
   loadAccessToken() {
     if (typeof window !== "undefined" && window.localStorage) {
       return localStorage.getItem(ACCESS_TOKEN_STORAGE_KEY);
@@ -3222,7 +3399,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?.({
@@ -3245,7 +3422,7 @@ var CimplifyClient = class {
         await sleep(delay);
       }
     }
-    const finalError = toNetworkError(lastError);
+    const finalError = toNetworkError(lastError, this.isTestMode());
     this.hooks.onRequestError?.({
       ...context,
       error: finalError,
@@ -3363,22 +3540,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;
   }
@@ -3463,7 +3658,10 @@ var CimplifyClient = class {
    * ```
    */
   elements(businessId, options) {
-    return createElements(this, businessId, options);
+    if (businessId) {
+      this.setBusinessId(businessId);
+    }
+    return createElements(this, businessId ?? this.businessId ?? void 0, options);
   }
 };
 function createCimplifyClient(config = {}) {
@@ -3535,4 +3733,4 @@ function query(entity) {
   return new QueryBuilder(entity);
 }
 
-export { AUTHORIZATION_TYPE, AUTH_MUTATION, AuthService, BusinessService, CHECKOUT_MODE, CHECKOUT_MUTATION, CHECKOUT_STEP, CONTACT_TYPE, CURRENCY_SYMBOLS, CartOperations, CatalogueQueries, CheckoutService as CheckoutOperations, CheckoutService, CimplifyClient, CimplifyElement, CimplifyElements, CimplifyError, DEFAULT_COUNTRY, DEFAULT_CURRENCY, DEVICE_TYPE, ELEMENT_TYPES, EVENT_TYPES, ErrorCode, FxService, InventoryService, LINK_MUTATION, LINK_QUERY, LinkService, LiteService, MESSAGE_TYPES, MOBILE_MONEY_PROVIDER, MOBILE_MONEY_PROVIDERS, ORDER_MUTATION, ORDER_TYPE, OrderQueries, PAYMENT_METHOD, PAYMENT_MUTATION, PAYMENT_STATE, PICKUP_TIME_TYPE, QueryBuilder, SchedulingService, categorizePaymentError, combine, combineObject, createCimplifyClient, createElements, detectMobileMoneyProvider, err, flatMap, formatMoney, formatNumberCompact, formatPrice, formatPriceAdjustment, formatPriceCompact, formatProductPrice, fromPromise, generateIdempotencyKey, getBasePrice, getCurrencySymbol, getDiscountPercentage, getDisplayPrice, getMarkupPercentage, getOrElse, getProductCurrency, isCimplifyError, isErr, isOk, isOnSale, isPaymentStatusFailure, isPaymentStatusRequiresAction, isPaymentStatusSuccess, isRetryableError, mapError, mapResult, normalizePaymentResponse, normalizeStatusResponse, ok, parsePrice, query, toNullable, tryCatch, unwrap };
+export { AUTHORIZATION_TYPE, AUTH_MUTATION, AuthService, BusinessService, CHECKOUT_MODE, CHECKOUT_MUTATION, CHECKOUT_STEP, CONTACT_TYPE, CURRENCY_SYMBOLS, CartOperations, CatalogueQueries, CheckoutService as CheckoutOperations, CheckoutService, CimplifyClient, CimplifyElement, CimplifyElements, CimplifyError, DEFAULT_COUNTRY, DEFAULT_CURRENCY, DEVICE_TYPE, ELEMENT_TYPES, ERROR_HINTS, EVENT_TYPES, ErrorCode, FxService, InventoryService, LINK_MUTATION, LINK_QUERY, LinkService, LiteService, MESSAGE_TYPES, MOBILE_MONEY_PROVIDER, MOBILE_MONEY_PROVIDERS, ORDER_MUTATION, ORDER_TYPE, OrderQueries, PAYMENT_METHOD, PAYMENT_MUTATION, PAYMENT_STATE, PICKUP_TIME_TYPE, QueryBuilder, SchedulingService, categorizePaymentError, combine, combineObject, createCimplifyClient, createElements, detectMobileMoneyProvider, enrichError, err, flatMap, formatMoney, formatNumberCompact, formatPrice, formatPriceAdjustment, formatPriceCompact, formatProductPrice, fromPromise, generateIdempotencyKey, getBasePrice, getCurrencySymbol, getDiscountPercentage, getDisplayPrice, getErrorHint, getMarkupPercentage, getOrElse, getProductCurrency, isCimplifyError, isErr, isOk, isOnSale, isPaymentStatusFailure, isPaymentStatusRequiresAction, isPaymentStatusSuccess, isRetryableError, mapError, mapResult, normalizePaymentResponse, normalizeStatusResponse, ok, parsePrice, query, toNullable, tryCatch, unwrap };

package/dist/payment-pjpfIKX8.d.mts

@@ -0,0 +1,181 @@
+/** Decimal value represented as string for precision */
+type Money = string;
+/** Supported currencies */
+type Currency = "GHS" | "USD" | "NGN" | "KES" | "ZAR" | string;
+/** Pagination parameters */
+interface PaginationParams {
+    page?: number;
+    limit?: number;
+    offset?: number;
+}
+/** Pagination metadata in response */
+interface Pagination {
+    total_count: number;
+    current_page: number;
+    page_size: number;
+    total_pages: number;
+}
+/** Strongly-typed error codes for better DX */
+declare const ErrorCode: {
+    readonly UNKNOWN_ERROR: "UNKNOWN_ERROR";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly UNAUTHORIZED: "UNAUTHORIZED";
+    readonly FORBIDDEN: "FORBIDDEN";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly VALIDATION_ERROR: "VALIDATION_ERROR";
+    readonly CART_EMPTY: "CART_EMPTY";
+    readonly CART_EXPIRED: "CART_EXPIRED";
+    readonly CART_NOT_FOUND: "CART_NOT_FOUND";
+    readonly ITEM_UNAVAILABLE: "ITEM_UNAVAILABLE";
+    readonly VARIANT_NOT_FOUND: "VARIANT_NOT_FOUND";
+    readonly VARIANT_OUT_OF_STOCK: "VARIANT_OUT_OF_STOCK";
+    readonly ADDON_REQUIRED: "ADDON_REQUIRED";
+    readonly ADDON_MAX_EXCEEDED: "ADDON_MAX_EXCEEDED";
+    readonly CHECKOUT_VALIDATION_FAILED: "CHECKOUT_VALIDATION_FAILED";
+    readonly DELIVERY_ADDRESS_REQUIRED: "DELIVERY_ADDRESS_REQUIRED";
+    readonly CUSTOMER_INFO_REQUIRED: "CUSTOMER_INFO_REQUIRED";
+    readonly PAYMENT_FAILED: "PAYMENT_FAILED";
+    readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
+    readonly INSUFFICIENT_FUNDS: "INSUFFICIENT_FUNDS";
+    readonly CARD_DECLINED: "CARD_DECLINED";
+    readonly INVALID_OTP: "INVALID_OTP";
+    readonly OTP_EXPIRED: "OTP_EXPIRED";
+    readonly AUTHORIZATION_FAILED: "AUTHORIZATION_FAILED";
+    readonly PAYMENT_ACTION_NOT_COMPLETED: "PAYMENT_ACTION_NOT_COMPLETED";
+    readonly SLOT_UNAVAILABLE: "SLOT_UNAVAILABLE";
+    readonly BOOKING_CONFLICT: "BOOKING_CONFLICT";
+    readonly SERVICE_NOT_FOUND: "SERVICE_NOT_FOUND";
+    readonly OUT_OF_STOCK: "OUT_OF_STOCK";
+    readonly INSUFFICIENT_QUANTITY: "INSUFFICIENT_QUANTITY";
+};
+type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** API error structure */
+interface ApiError {
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+interface ErrorHint {
+    docs_url: string;
+    suggestion: string;
+}
+declare const ERROR_HINTS: Record<string, ErrorHint>;
+/**
+ * Custom error class for SDK errors with typed error codes.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.cart.addItem({ item_id: "prod_123" });
+ * } catch (error) {
+ *   if (isCimplifyError(error)) {
+ *     switch (error.code) {
+ *       case ErrorCode.ITEM_UNAVAILABLE:
+ *         toast.error("This item is no longer available");
+ *         break;
+ *       case ErrorCode.VARIANT_OUT_OF_STOCK:
+ *         toast.error("Selected option is out of stock");
+ *         break;
+ *       default:
+ *         toast.error(error.message);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare class CimplifyError extends Error {
+    code: string;
+    retryable: boolean;
+    docs_url?: string | undefined;
+    suggestion?: string | undefined;
+    constructor(code: string, message: string, retryable?: boolean, docs_url?: string | undefined, suggestion?: string | undefined);
+    /** User-friendly message safe to display */
+    get userMessage(): string;
+}
+/** Type guard for CimplifyError */
+declare function isCimplifyError(error: unknown): error is CimplifyError;
+declare function getErrorHint(code: string): ErrorHint | undefined;
+declare function enrichError(error: CimplifyError, options?: {
+    isTestMode?: boolean;
+}): CimplifyError;
+/** Check if error is retryable */
+declare function isRetryableError(error: unknown): boolean;
+
+type PaymentStatus = "pending" | "processing" | "created" | "pending_confirmation" | "success" | "succeeded" | "failed" | "declined" | "authorized" | "refunded" | "partially_refunded" | "partially_paid" | "paid" | "unpaid" | "requires_action" | "requires_payment_method" | "requires_capture" | "captured" | "cancelled" | "completed" | "voided" | "error" | "unknown";
+type PaymentProvider = "stripe" | "paystack" | "mtn" | "vodafone" | "airtel" | "cellulant" | "offline" | "cash" | "manual";
+type PaymentMethodType = "card" | "mobile_money" | "bank_transfer" | "cash" | "custom";
+/** Authorization types for payment verification (OTP, PIN, etc.) */
+type AuthorizationType = "otp" | "pin" | "phone" | "birthday" | "address";
+/** Payment processing state machine states (for UI) */
+type PaymentProcessingState = "initial" | "preparing" | "processing" | "verifying" | "awaiting_authorization" | "success" | "error" | "timeout";
+interface PaymentMethod {
+    type: PaymentMethodType;
+    provider?: string;
+    phone_number?: string;
+    card_last_four?: string;
+    custom_value?: string;
+}
+interface Payment {
+    id: string;
+    order_id: string;
+    business_id: string;
+    amount: Money;
+    currency: Currency;
+    payment_method: PaymentMethod;
+    status: PaymentStatus;
+    provider: PaymentProvider;
+    provider_reference?: string;
+    failure_reason?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface InitializePaymentResult {
+    payment_id: string;
+    status: PaymentStatus;
+    redirect_url?: string;
+    authorization_url?: string;
+    reference: string;
+    provider: PaymentProvider;
+}
+/** Normalized payment response from checkout or payment initialization */
+interface PaymentResponse {
+    method: string;
+    provider: string;
+    requires_action: boolean;
+    public_key?: string;
+    client_secret?: string;
+    access_code?: string;
+    redirect_url?: string;
+    transaction_id?: string;
+    order_id?: string;
+    reference?: string;
+    metadata?: Record<string, unknown>;
+    instructions?: string;
+    display_text?: string;
+    requires_authorization?: boolean;
+    authorization_type?: AuthorizationType;
+    provider_payment_id?: string;
+}
+/** Payment status polling response */
+interface PaymentStatusResponse {
+    status: PaymentStatus;
+    paid: boolean;
+    amount?: Money;
+    currency?: string;
+    reference?: string;
+    message?: string;
+}
+interface PaymentErrorDetails {
+    code: string;
+    message: string;
+    recoverable: boolean;
+    technical?: string;
+}
+interface SubmitAuthorizationInput {
+    reference: string;
+    auth_type: AuthorizationType;
+    value: string;
+}
+
+export { type ApiError as A, type Currency as C, ErrorCode as E, type InitializePaymentResult as I, type Money as M, type PaginationParams as P, type SubmitAuthorizationInput as S, type Pagination as a, type ErrorCodeType as b, type ErrorHint as c, ERROR_HINTS as d, CimplifyError as e, enrichError as f, getErrorHint as g, isRetryableError as h, isCimplifyError as i, type PaymentStatus as j, type PaymentProvider as k, type PaymentMethodType as l, type AuthorizationType as m, type PaymentProcessingState as n, type PaymentMethod as o, type Payment as p, type PaymentResponse as q, type PaymentStatusResponse as r, type PaymentErrorDetails as s };