@beep-it/sdk-core 0.1.7 → 0.2.0

package/dist/index.js

@@ -28,16 +28,48 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
+  BeepAuthenticationError: () => BeepAuthenticationError,
   BeepClient: () => BeepClient,
+  BeepError: () => BeepError,
+  BeepErrorCode: () => BeepErrorCode,
+  BeepNetworkError: () => BeepNetworkError,
+  BeepPaymentError: () => BeepPaymentError,
   BeepPublicClient: () => BeepPublicClient,
+  BeepRateLimitError: () => BeepRateLimitError,
+  BeepValidationError: () => BeepValidationError,
+  InvoiceStatus: () => InvoiceStatus,
+  PayoutStatus: () => PayoutStatus,
   SupportedToken: () => SupportedToken,
-  TokenUtils: () => TokenUtils
+  TOKEN_ADDRESSES: () => TOKEN_ADDRESSES,
+  TOKEN_DECIMALS: () => TOKEN_DECIMALS,
+  TokenUtils: () => TokenUtils,
+  createBeepErrorFromAxios: () => createBeepErrorFromAxios
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 var import_axios = __toESM(require("axios"));
 
+// src/types/invoice.ts
+var InvoiceStatus = /* @__PURE__ */ ((InvoiceStatus2) => {
+  InvoiceStatus2["PENDING"] = "pending";
+  InvoiceStatus2["PAID"] = "paid";
+  InvoiceStatus2["CONFIRMED"] = "confirmed";
+  InvoiceStatus2["EXPIRED"] = "expired";
+  InvoiceStatus2["FAILED"] = "failed";
+  return InvoiceStatus2;
+})(InvoiceStatus || {});
+
+// src/types/payment.ts
+var PayoutStatus = /* @__PURE__ */ ((PayoutStatus2) => {
+  PayoutStatus2["PENDING"] = "PENDING";
+  PayoutStatus2["IN_PROGRESS"] = "IN_PROGRESS";
+  PayoutStatus2["COMPLETED"] = "COMPLETED";
+  PayoutStatus2["FAILED"] = "FAILED";
+  PayoutStatus2["CANCELED"] = "CANCELED";
+  return PayoutStatus2;
+})(PayoutStatus || {});
+
 // src/types/token.ts
 var SupportedToken = /* @__PURE__ */ ((SupportedToken3) => {
   SupportedToken3["USDC"] = "USDC";
@@ -149,11 +181,11 @@ var InvoicesModule = class {
   /**
    * Creates a new invoice for payment processing
    * Supports both product-based invoices (linked to existing products) and custom invoices
-   * 
+   *
    * @param payload - Invoice creation parameters (product-based or custom)
    * @returns Promise that resolves to the created invoice
    * @throws {Error} When invoice creation fails
-   * 
+   *
    * @example
    * ```typescript
    * // Create invoice from existing product
@@ -161,7 +193,7 @@ var InvoicesModule = class {
    *   productId: 'prod_123',
    *   payerType: 'customer_wallet'
    * });
-   * 
+   *
    * // Create custom invoice
    * const customInvoice = await beep.invoices.createInvoice({
    *   description: 'Consulting services',
@@ -174,18 +206,20 @@ var InvoicesModule = class {
   async createInvoice(payload) {
     const requestPayload = { ...payload };
     if ("token" in requestPayload && !("splTokenAddress" in requestPayload)) {
-      requestPayload.splTokenAddress = TokenUtils.getTokenAddress(requestPayload.token);
+      requestPayload.splTokenAddress = TokenUtils.getTokenAddress(
+        requestPayload.token
+      );
     }
     const response = await this.client.post("/v1/invoices", requestPayload);
     return response.data;
   }
   /**
    * Retrieves a specific invoice by its ID
-   * 
+   *
    * @param invoiceId - The unique identifier of the invoice to retrieve
    * @returns Promise that resolves to the invoice details
    * @throws {Error} When the invoice is not found or retrieval fails
-   * 
+   *
    * @example
    * ```typescript
    * const invoice = await beep.invoices.getInvoice('inv_123abc456def');
@@ -199,10 +233,10 @@ var InvoicesModule = class {
   }
   /**
    * Retrieves all invoices for the current merchant
-   * 
+   *
    * @returns Promise that resolves to an array of invoices
    * @throws {Error} When invoice retrieval fails
-   * 
+   *
    * @example
    * ```typescript
    * const invoices = await beep.invoices.listInvoices();
@@ -216,13 +250,13 @@ var InvoicesModule = class {
   }
   /**
    * Deletes an existing invoice
-   * 
+   *
    * @param invoiceId - The unique identifier of the invoice to delete
    * @returns Promise that resolves when the invoice is successfully deleted
    * @throws {Error} When the invoice is not found or deletion fails
-   * 
+   *
    * @remarks Once deleted, an invoice cannot be recovered. Use with caution.
-   * 
+   *
    * @example
    * ```typescript
    * await beep.invoices.deleteInvoice('inv_123abc456def');
@@ -234,6 +268,211 @@ var InvoicesModule = class {
   }
 };
 
+// src/errors/index.ts
+var BeepErrorCode = /* @__PURE__ */ ((BeepErrorCode2) => {
+  BeepErrorCode2["INVALID_API_KEY"] = "BEEP_1001";
+  BeepErrorCode2["MISSING_API_KEY"] = "BEEP_1002";
+  BeepErrorCode2["UNAUTHORIZED"] = "BEEP_1003";
+  BeepErrorCode2["INVALID_PUBLISHABLE_KEY"] = "BEEP_1004";
+  BeepErrorCode2["NETWORK_ERROR"] = "BEEP_2001";
+  BeepErrorCode2["TIMEOUT"] = "BEEP_2002";
+  BeepErrorCode2["SERVER_ERROR"] = "BEEP_2003";
+  BeepErrorCode2["PAYMENT_FAILED"] = "BEEP_3001";
+  BeepErrorCode2["PAYMENT_EXPIRED"] = "BEEP_3002";
+  BeepErrorCode2["PAYMENT_NOT_FOUND"] = "BEEP_3003";
+  BeepErrorCode2["INSUFFICIENT_FUNDS"] = "BEEP_3004";
+  BeepErrorCode2["PAYMENT_ALREADY_PROCESSED"] = "BEEP_3005";
+  BeepErrorCode2["INVOICE_NOT_FOUND"] = "BEEP_4001";
+  BeepErrorCode2["INVOICE_EXPIRED"] = "BEEP_4002";
+  BeepErrorCode2["INVOICE_ALREADY_PAID"] = "BEEP_4003";
+  BeepErrorCode2["INVALID_PARAMETER"] = "BEEP_5001";
+  BeepErrorCode2["MISSING_PARAMETER"] = "BEEP_5002";
+  BeepErrorCode2["INVALID_AMOUNT"] = "BEEP_5003";
+  BeepErrorCode2["INVALID_TOKEN"] = "BEEP_5004";
+  BeepErrorCode2["RATE_LIMIT_EXCEEDED"] = "BEEP_6001";
+  BeepErrorCode2["UNKNOWN_ERROR"] = "BEEP_9999";
+  return BeepErrorCode2;
+})(BeepErrorCode || {});
+var BeepError = class _BeepError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "BeepError";
+    this.code = options.code;
+    this.statusCode = options.statusCode;
+    this.details = options.details;
+    this.timestamp = /* @__PURE__ */ new Date();
+    this.requestId = options.requestId;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _BeepError);
+    }
+  }
+  /**
+   * Returns a user-friendly error message
+   */
+  getUserMessage() {
+    switch (this.code) {
+      case "BEEP_1001" /* INVALID_API_KEY */:
+        return "The API key provided is invalid. Please check your credentials.";
+      case "BEEP_1002" /* MISSING_API_KEY */:
+        return "No API key provided. Please provide a valid API key.";
+      case "BEEP_2001" /* NETWORK_ERROR */:
+        return "Unable to connect to BEEP servers. Please check your internet connection.";
+      case "BEEP_3002" /* PAYMENT_EXPIRED */:
+        return "This payment request has expired. Please create a new one.";
+      case "BEEP_3004" /* INSUFFICIENT_FUNDS */:
+        return "Insufficient funds to complete this transaction.";
+      case "BEEP_6001" /* RATE_LIMIT_EXCEEDED */:
+        return "Too many requests. Please try again later.";
+      default:
+        return this.message || "An unexpected error occurred.";
+    }
+  }
+  /**
+   * Returns a JSON representation of the error for logging
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      statusCode: this.statusCode,
+      details: this.details,
+      timestamp: this.timestamp,
+      requestId: this.requestId,
+      stack: this.stack
+    };
+  }
+};
+var BeepAuthenticationError = class extends BeepError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code ?? "BEEP_1003" /* UNAUTHORIZED */,
+      statusCode: 401,
+      details: options.details
+    });
+    this.name = "BeepAuthenticationError";
+  }
+};
+var BeepValidationError = class extends BeepError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code ?? "BEEP_5001" /* INVALID_PARAMETER */,
+      statusCode: 400,
+      details: options.details
+    });
+    this.name = "BeepValidationError";
+  }
+};
+var BeepPaymentError = class extends BeepError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code ?? "BEEP_3001" /* PAYMENT_FAILED */,
+      statusCode: 402,
+      details: options.details
+    });
+    this.name = "BeepPaymentError";
+  }
+};
+var BeepNetworkError = class extends BeepError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: options.code ?? "BEEP_2001" /* NETWORK_ERROR */,
+      details: options.details
+    });
+    this.name = "BeepNetworkError";
+  }
+};
+var BeepRateLimitError = class extends BeepError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: "BEEP_6001" /* RATE_LIMIT_EXCEEDED */,
+      statusCode: 429,
+      details: options.details
+    });
+    this.name = "BeepRateLimitError";
+    this.retryAfter = options.retryAfter;
+  }
+};
+function createBeepErrorFromAxios(error) {
+  const response = error.response;
+  const requestId = response?.headers?.["x-request-id"];
+  if (!response) {
+    return new BeepNetworkError(error.message || "Network connection failed", {
+      code: "BEEP_2001" /* NETWORK_ERROR */,
+      details: { originalError: error }
+    });
+  }
+  const status = response.status;
+  const data = response.data;
+  const message = data?.message || data?.error || error.message;
+  switch (status) {
+    case 401:
+      return new BeepAuthenticationError(message, {
+        code: "BEEP_1003" /* UNAUTHORIZED */,
+        details: { response: data }
+      });
+    case 400: {
+      if (message.toLowerCase().includes("api key")) {
+        return new BeepAuthenticationError(message, {
+          code: "BEEP_1001" /* INVALID_API_KEY */,
+          details: { response: data }
+        });
+      }
+      return new BeepValidationError(message, {
+        code: "BEEP_5001" /* INVALID_PARAMETER */,
+        details: { response: data, fields: data?.fields }
+      });
+    }
+    case 402:
+      return new BeepPaymentError(message, {
+        code: "BEEP_3001" /* PAYMENT_FAILED */,
+        details: { response: data }
+      });
+    case 404: {
+      if (message.toLowerCase().includes("invoice")) {
+        return new BeepError(message, {
+          code: "BEEP_4001" /* INVOICE_NOT_FOUND */,
+          statusCode: 404,
+          details: { response: data },
+          requestId
+        });
+      }
+      if (message.toLowerCase().includes("payment")) {
+        return new BeepError(message, {
+          code: "BEEP_3003" /* PAYMENT_NOT_FOUND */,
+          statusCode: 404,
+          details: { response: data },
+          requestId
+        });
+      }
+      break;
+    }
+    case 429: {
+      const retryAfter = response.headers?.["retry-after"];
+      return new BeepRateLimitError(message, {
+        retryAfter: retryAfter ? parseInt(retryAfter) : void 0,
+        details: { response: data }
+      });
+    }
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return new BeepError(message, {
+        code: "BEEP_2003" /* SERVER_ERROR */,
+        statusCode: status,
+        details: { response: data },
+        requestId
+      });
+  }
+  return new BeepError(message, {
+    code: "BEEP_9999" /* UNKNOWN_ERROR */,
+    statusCode: status,
+    details: { response: data },
+    requestId
+  });
+}
+
 // src/modules/payments.ts
 var PaymentsModule = class {
   constructor(client) {
@@ -407,12 +646,13 @@ var PaymentsModule = class {
         input
       );
       if (!response.data || !response.data.data) {
-        throw new Error("No data returned from solana transaction signing");
+        throw new BeepPaymentError("No data returned from solana transaction signing", {
+          code: "BEEP_3001" /* PAYMENT_FAILED */
+        });
       }
       return response.data.data;
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to sign solana transaction: ${errorMessage}`);
+      throw createBeepErrorFromAxios(error);
     }
   }
   // --- Streaming Payment Methods ---
@@ -808,6 +1048,176 @@ var UserModule = class {
   }
 };
 
+// src/utils/debug.ts
+var defaultLogger = (options) => {
+  const { level, message, data } = options;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const prefix = `[BEEP SDK ${level}] ${timestamp}`;
+  switch (level) {
+    case "error":
+      console.error(prefix, message, data);
+      break;
+    case "warn":
+      console.warn(prefix, message, data);
+      break;
+    case "info":
+      console.info(prefix, message, data);
+      break;
+    case "debug":
+      console.debug(prefix, message, data);
+      break;
+    default:
+      console.log(prefix, message, data);
+  }
+};
+var BeepDebugger = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.logger = options.logger || defaultLogger;
+  }
+  /**
+   * Log an error with context
+   */
+  error(message, error) {
+    if (error instanceof BeepError) {
+      this.logger({
+        level: "error",
+        message,
+        data: {
+          code: error.code,
+          statusCode: error.statusCode,
+          details: error.details,
+          requestId: error.requestId,
+          userMessage: error.getUserMessage()
+        }
+      });
+    } else {
+      this.logger({ level: "error", message, data: error });
+    }
+  }
+  /**
+   * Log a warning
+   */
+  warn(message, data) {
+    this.logger({ level: "warn", message, data });
+  }
+  /**
+   * Log info message
+   */
+  info(message, data) {
+    if (this.options.debug) {
+      this.logger({ level: "info", message, data });
+    }
+  }
+  /**
+   * Log debug message
+   */
+  debug(message, data) {
+    if (this.options.debug) {
+      this.logger({ level: "debug", message, data });
+    }
+  }
+  /**
+   * Log API request
+   */
+  logRequest(options) {
+    if (this.options.logRequests && this.options.debug) {
+      const { method, url, data } = options;
+      this.logger({
+        level: "debug",
+        message: `API Request: ${method} ${url}`,
+        data: {
+          method,
+          url,
+          data: this.sanitizeData(data)
+        }
+      });
+    }
+  }
+  /**
+   * Log API response
+   */
+  logResponse(options) {
+    if (this.options.logResponses && this.options.debug) {
+      const { method, url, status, data } = options;
+      this.logger({
+        level: "debug",
+        message: `API Response: ${method} ${url} (${status})`,
+        data: {
+          method,
+          url,
+          status,
+          data: this.sanitizeData(data)
+        }
+      });
+    }
+  }
+  /**
+   * Sanitize sensitive data before logging
+   */
+  sanitizeData(data) {
+    if (!data) return data;
+    const sensitiveFields = ["apiKey", "api_key", "authorization", "password", "secret"];
+    if (typeof data === "string") {
+      return data;
+    }
+    if (Array.isArray(data)) {
+      return data.map((item) => this.sanitizeData(item));
+    }
+    if (typeof data === "object") {
+      const sanitized = {};
+      for (const [key, value] of Object.entries(data)) {
+        if (sensitiveFields.some((field) => key.toLowerCase().includes(field))) {
+          sanitized[key] = "[REDACTED]";
+        } else {
+          sanitized[key] = this.sanitizeData(value);
+        }
+      }
+      return sanitized;
+    }
+    return data;
+  }
+};
+function createDebugInterceptors(axios2, beepDebugger) {
+  axios2.interceptors.request.use(
+    (config) => {
+      beepDebugger.logRequest({
+        method: config.method?.toUpperCase() || "GET",
+        url: config.url || "",
+        data: config.data
+      });
+      return config;
+    },
+    (error) => {
+      beepDebugger.error("Request interceptor error", error);
+      return Promise.reject(error);
+    }
+  );
+  axios2.interceptors.response.use(
+    (response) => {
+      beepDebugger.logResponse({
+        method: response.config.method?.toUpperCase() || "GET",
+        url: response.config.url || "",
+        status: response.status,
+        data: response.data
+      });
+      return response;
+    },
+    (error) => {
+      if (error.response) {
+        beepDebugger.logResponse({
+          method: error.config?.method?.toUpperCase() || "GET",
+          url: error.config?.url || "",
+          status: error.response.status,
+          data: error.response.data
+        });
+      }
+      beepDebugger.error("API Error", error);
+      return Promise.reject(error);
+    }
+  );
+}
+
 // src/index.ts
 var BeepClient = class {
   /**
@@ -818,8 +1228,11 @@ var BeepClient = class {
    */
   constructor(options) {
     if (!options.apiKey) {
-      throw new Error("API key is required to initialize BeepClient");
+      throw new BeepAuthenticationError("API key is required to initialize BeepClient", {
+        code: "BEEP_1002" /* MISSING_API_KEY */
+      });
     }
+    this.debugger = new BeepDebugger(options.debug);
     this.client = import_axios.default.create({
       baseURL: options.serverUrl || "https://api.justbeep.it",
       headers: {
@@ -828,6 +1241,9 @@ var BeepClient = class {
         "X-Beep-Client": "beep-sdk"
       }
     });
+    if (options.debug?.debug) {
+      createDebugInterceptors(this.client, this.debugger);
+    }
     this.products = new ProductsModule(this.client);
     this.invoices = new InvoicesModule(this.client);
     this.payments = new PaymentsModule(this.client);
@@ -884,7 +1300,12 @@ var BeepPublicClient = class {
    */
   constructor(options) {
     if (!options.publishableKey) {
-      throw new Error("publishableKey is required to initialize BeepPublicClient");
+      throw new BeepAuthenticationError(
+        "publishableKey is required to initialize BeepPublicClient",
+        {
+          code: "BEEP_1002" /* MISSING_API_KEY */
+        }
+      );
     }
     this.client = import_axios.default.create({
       baseURL: options.serverUrl || "https://api.justbeep.it",
@@ -899,8 +1320,20 @@ var BeepPublicClient = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BeepAuthenticationError,
   BeepClient,
+  BeepError,
+  BeepErrorCode,
+  BeepNetworkError,
+  BeepPaymentError,
   BeepPublicClient,
+  BeepRateLimitError,
+  BeepValidationError,
+  InvoiceStatus,
+  PayoutStatus,
   SupportedToken,
-  TokenUtils
+  TOKEN_ADDRESSES,
+  TOKEN_DECIMALS,
+  TokenUtils,
+  createBeepErrorFromAxios
 });