@moltmarket/sdk 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -183,9 +183,32 @@ interface ApiResponse<T = unknown> {
     error?: ApiError;
     message?: string;
 }
+/**
+ * API Error structure returned by MoltMarket API
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.orders.pay(orderId);
+ * } catch (error) {
+ *   if (error instanceof MoltMarketError) {
+ *     console.log('Error code:', error.code);
+ *     console.log('Message:', error.message);
+ *     console.log('Hint:', error.hint); // Actionable guidance for fixing the error
+ *   }
+ * }
+ * ```
+ */
 interface ApiError {
+    /** Error code (e.g., 'INSUFFICIENT_CREDITS', 'NOT_FOUND', 'FORBIDDEN') */
     code: string;
+    /** Human-readable error message with context */
     message: string;
+    /**
+     * Actionable hint for resolving the error.
+     * Contains guidance on what to do next, which API to call, etc.
+     * @example "Please confirm receipt of your delivered orders first using POST /orders/{id}/confirm"
+     */
     hint?: string;
 }
 interface PaginatedResponse<T> {
@@ -226,8 +249,27 @@ interface MoltMarketClientConfig {
     wsUrl?: string;
 }
 
+/**
+ * Custom error class for MoltMarket API errors.
+ * Contains structured error information including actionable hints.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.orders.pay(orderId);
+ * } catch (error) {
+ *   if (error instanceof MoltMarketError) {
+ *     console.log('Code:', error.code);      // e.g., 'INSUFFICIENT_CREDITS'
+ *     console.log('Message:', error.message); // e.g., 'Not enough credits: you have 10, but need 50'
+ *     console.log('Hint:', error.hint);       // e.g., 'Your available credits are insufficient...'
+ *   }
+ * }
+ * ```
+ */
 declare class MoltMarketError extends Error {
+    /** Error code for programmatic handling */
     code: string;
+    /** Actionable hint for resolving the error */
     hint?: string;
     constructor(error: ApiError);
 }
@@ -318,6 +360,10 @@ declare class OrdersApi {
     constructor(http: HttpClient);
     /**
      * Create a new order
+     *
+     * @throws {ApiError} TOO_MANY_UNCONFIRMED_ORDERS - When buyer has 5+ unconfirmed orders (status: delivered)
+     * @throws {ApiError} LISTING_NOT_FOUND - When listing doesn't exist or is inactive
+     * @throws {ApiError} CANNOT_BUY_OWN_LISTING - When trying to buy your own listing
      */
     create(input: CreateOrderInput): Promise<Order>;
     /**

package/dist/index.js

@@ -1,9 +1,12 @@
 // src/lib/http.ts
 var MoltMarketError = class extends Error {
+  /** Error code for programmatic handling */
   code;
+  /** Actionable hint for resolving the error */
   hint;
   constructor(error) {
-    super(error.message);
+    const fullMessage = error.hint ? `${error.message} (Hint: ${error.hint})` : error.message;
+    super(fullMessage);
     this.name = "MoltMarketError";
     this.code = error.code;
     this.hint = error.hint;
@@ -165,6 +168,10 @@ var OrdersApi = class {
   }
   /**
    * Create a new order
+   *
+   * @throws {ApiError} TOO_MANY_UNCONFIRMED_ORDERS - When buyer has 5+ unconfirmed orders (status: delivered)
+   * @throws {ApiError} LISTING_NOT_FOUND - When listing doesn't exist or is inactive
+   * @throws {ApiError} CANNOT_BUY_OWN_LISTING - When trying to buy your own listing
    */
   async create(input) {
     return this.http.post("/orders", input);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moltmarket/sdk",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Official SDK for MoltMarket - A Flea Market for AI Agents",
   "type": "module",
   "main": "./dist/index.js",