@railblock/opencommodity-sdk 1.0.2 → 1.0.4

package/README.md

@@ -26,92 +26,109 @@ npm install @railblock/opencommodity-sdk
 ## Quick start
 
 ```ts
-import { OpenCommodity } from "@railblock/opencommodity-sdk";
+import { OpenCommodityClient } from "@railblock/opencommodity-sdk";
 
-const client = new OpenCommodity({
-  apiKey: process.env.OPENCOMMODITY_API_KEY,
-  endpoint: "https://api.opencommodity.pro",
+const client = new OpenCommodityClient({
+  apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
+  baseUrl: "https://api.opencommodity.pro",
 });
 ```
 
 ## One-liner usage
 
 ```ts
-const client = new OpenCommodity({ apiKey: process.env.OPENCOMMODITY_API_KEY });
+const client = new OpenCommodityClient({ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "" });
 ```
 
 ## What this SDK does
 
 - Talks to the OpenCommodity API
-- Supports contract-backed commodity, listing, and marketplace flows
+- Supports contract-backed commodity, listing, marketplace, and escrow lifecycle flows
 - Falls back to REST when no contract config is provided
-- Exposes contract ABIs for `CommodityRegistry`, `OpenCommodity`, and `MarketplaceRegistry`
+- Exposes contract ABIs for `UniversalEscrow` and the current SDK client surface
 
-## Contract-backed usage
+## Escrow lifecycle usage
 
-### Commodity registration
+The SDK now includes UniversalEscrow lifecycle methods for the `ship → receive → accept quality → dispute → auto-release` flow.
+
+### Create an escrow sale
 
 ```ts
-const client = new OpenCommodity({
-  apiKey: process.env.OPENCOMMODITY_API_KEY,
-  endpoint: "https://api.opencommodity.pro",
+const client = new OpenCommodityClient({
+  apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
   provider: window.ethereum,
   contracts: {
-    commodityRegistry: "0xYourCommodityRegistryAddress",
+    universalEscrow: "0xYourUniversalEscrowAddress",
   },
 });
 
-const result = await client.registerCommodity("ipfs://metadata-uri");
+const saleId = await client.createUniversalEscrowSale({
+  tokenId: 1,
+  amount: 10,
+  price: 1000,
+  seller: "0xSellerAddress",
+});
 ```
 
-### Listing management
+### Confirm shipment
 
 ```ts
-const client = new OpenCommodity({
-  apiKey: process.env.OPENCOMMODITY_API_KEY,
-  endpoint: "https://api.opencommodity.pro",
-  provider: window.ethereum,
-  contracts: {
-    listingManager: "0xYourListingManagerAddress",
-  },
+await client.confirmUniversalEscrowShipment({
+  saleId,
 });
+```
 
-await client.createListing(1, "1.5");
-await client.updatePrice(1, "2.0");
-await client.cancelListing(1);
+### Confirm receipt
+
+```ts
+await client.confirmUniversalEscrowReceipt({
+  saleId,
+});
 ```
 
-### Marketplace registration
+### Accept quality
 
-Marketplace operators can configure their own marketplace fee percentage. Protocol, listing, and buy-side fees continue to route to the contract treasury.
+```ts
+await client.acceptUniversalEscrowQuality({
+  saleId,
+});
+```
+
+### Open a dispute
 
 ```ts
-const client = new OpenCommodity({
-  apiKey: process.env.OPENCOMMODITY_API_KEY,
-  endpoint: "https://api.opencommodity.pro",
-  provider: window.ethereum,
-  contracts: {
-    marketplaceRegistry: "0xYourMarketplaceRegistryAddress",
-  },
+await client.initiateUniversalEscrowDispute({
+  saleId,
+  reason: "Item arrived damaged",
 });
+```
+
+### Resolve a dispute
 
-const marketplace = await client.registerMarketplace({
-  fee_percent: 1.5,
+```ts
+await client.resolveUniversalEscrowDispute({
+  saleId,
+  favorBuyer: true,
+  refundPercentage: 50,
 });
+```
+
+### Auto-release funds
 
-await client.updateMarketplaceFee(marketplace.marketplaceId, 2.0);
-await client.deactivateMarketplace(marketplace.marketplaceId);
+```ts
+await client.autoReleaseUniversalEscrowFunds({
+  saleId,
+});
 ```
 
 ## REST fallback
 
 ```ts
-const client = new OpenCommodity({
-  apiKey: process.env.OPENCOMMODITY_API_KEY,
-  endpoint: "https://api.opencommodity.pro",
+const client = new OpenCommodityClient({
+  apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
 });
 
-const listings = await client.getListings();
+const listings = await client.listListings();
 ```
 
 ## Why OpenCommodity

package/dist/index.d.mts

@@ -117,6 +117,20 @@ interface CreateListingParams {
     price: number;
     gcid?: string;
 }
+interface CreateEscrowSaleParams {
+    tokenId: number;
+    amount: number;
+    price: number;
+    seller: string;
+}
+interface ConfirmEscrowActionParams {
+    saleId: string | number;
+}
+interface ResolveEscrowDisputeParams {
+    saleId: string | number;
+    favorBuyer: boolean;
+    refundPercentage: number;
+}
 
 declare class OpenCommodityError extends Error {
     status: number;
@@ -153,13 +167,15 @@ declare class OpenCommodityClient {
     getStats(): Promise<ProtocolStats>;
     createCommodity(params: CreateCommodityParams): Promise<Commodity>;
     createListing(params: CreateListingParams): Promise<Listing>;
-    createUniversalEscrowSale(params: CreateSaleParams): Promise<Sale>;
-    confirmUniversalEscrowShipment(saleId: string | number): Promise<Sale>;
-    confirmUniversalEscrowReceipt(saleId: string | number): Promise<Sale>;
-    acceptUniversalEscrowQuality(saleId: string | number): Promise<Sale>;
-    initiateUniversalEscrowDispute(saleId: string | number, reason: string): Promise<Sale>;
-    resolveUniversalEscrowDispute(saleId: string | number, favorBuyer: boolean, refundPercentage: number): Promise<Sale>;
-    autoReleaseUniversalEscrowFunds(saleId: string | number): Promise<Sale>;
+    createUniversalEscrowSale(params: CreateEscrowSaleParams): Promise<string>;
+    confirmUniversalEscrowShipment(params: ConfirmEscrowActionParams): Promise<string>;
+    confirmUniversalEscrowReceipt(params: ConfirmEscrowActionParams): Promise<string>;
+    acceptUniversalEscrowQuality(params: ConfirmEscrowActionParams): Promise<string>;
+    initiateUniversalEscrowDispute(params: ConfirmEscrowActionParams & {
+        reason: string;
+    }): Promise<string>;
+    resolveUniversalEscrowDispute(params: ResolveEscrowDisputeParams): Promise<string>;
+    autoReleaseUniversalEscrowFunds(params: ConfirmEscrowActionParams): Promise<string>;
     private hasUniversalEscrowContract;
     private callUniversalEscrowContract;
 }

package/dist/index.d.ts

@@ -117,6 +117,20 @@ interface CreateListingParams {
     price: number;
     gcid?: string;
 }
+interface CreateEscrowSaleParams {
+    tokenId: number;
+    amount: number;
+    price: number;
+    seller: string;
+}
+interface ConfirmEscrowActionParams {
+    saleId: string | number;
+}
+interface ResolveEscrowDisputeParams {
+    saleId: string | number;
+    favorBuyer: boolean;
+    refundPercentage: number;
+}
 
 declare class OpenCommodityError extends Error {
     status: number;
@@ -153,13 +167,15 @@ declare class OpenCommodityClient {
     getStats(): Promise<ProtocolStats>;
     createCommodity(params: CreateCommodityParams): Promise<Commodity>;
     createListing(params: CreateListingParams): Promise<Listing>;
-    createUniversalEscrowSale(params: CreateSaleParams): Promise<Sale>;
-    confirmUniversalEscrowShipment(saleId: string | number): Promise<Sale>;
-    confirmUniversalEscrowReceipt(saleId: string | number): Promise<Sale>;
-    acceptUniversalEscrowQuality(saleId: string | number): Promise<Sale>;
-    initiateUniversalEscrowDispute(saleId: string | number, reason: string): Promise<Sale>;
-    resolveUniversalEscrowDispute(saleId: string | number, favorBuyer: boolean, refundPercentage: number): Promise<Sale>;
-    autoReleaseUniversalEscrowFunds(saleId: string | number): Promise<Sale>;
+    createUniversalEscrowSale(params: CreateEscrowSaleParams): Promise<string>;
+    confirmUniversalEscrowShipment(params: ConfirmEscrowActionParams): Promise<string>;
+    confirmUniversalEscrowReceipt(params: ConfirmEscrowActionParams): Promise<string>;
+    acceptUniversalEscrowQuality(params: ConfirmEscrowActionParams): Promise<string>;
+    initiateUniversalEscrowDispute(params: ConfirmEscrowActionParams & {
+        reason: string;
+    }): Promise<string>;
+    resolveUniversalEscrowDispute(params: ResolveEscrowDisputeParams): Promise<string>;
+    autoReleaseUniversalEscrowFunds(params: ConfirmEscrowActionParams): Promise<string>;
     private hasUniversalEscrowContract;
     private callUniversalEscrowContract;
 }

package/dist/index.js

@@ -27548,55 +27548,39 @@ var OpenCommodityClient = class {
     });
   }
   async createUniversalEscrowSale(params) {
-    if (this.hasUniversalEscrowContract()) {
-      const saleId = await this.callUniversalEscrowContract("createSale", [
-        params.token_id,
-        params.amount,
-        params.price,
-        params.seller_wallet
-      ]);
-      return {
-        id: String(saleId),
-        commodity_id: params.commodity_id,
-        seller_wallet: params.seller_wallet,
-        buyer_wallet: params.buyer_wallet,
-        price: params.price,
-        amount: params.amount,
-        status: "FUNDED",
-        gcid: null,
-        created_at: (/* @__PURE__ */ new Date()).toISOString()
-      };
+    if (!this.hasUniversalEscrowContract()) {
+      throw new Error("universalEscrow contract configuration is required");
     }
-    return this.createSale(params);
+    const saleId = await this.callUniversalEscrowContract("createSale", [
+      params.tokenId,
+      params.amount,
+      params.price,
+      params.seller
+    ], "SaleCreated");
+    return String(saleId);
   }
-  async confirmUniversalEscrowShipment(saleId) {
-    await this.callUniversalEscrowContract("confirmShipment", [saleId]);
-    return this.getSale(String(saleId));
+  async confirmUniversalEscrowShipment(params) {
+    return this.callUniversalEscrowContract("confirmShipment", [params.saleId], "Shipped");
   }
-  async confirmUniversalEscrowReceipt(saleId) {
-    await this.callUniversalEscrowContract("confirmReceipt", [saleId]);
-    return this.getSale(String(saleId));
+  async confirmUniversalEscrowReceipt(params) {
+    return this.callUniversalEscrowContract("confirmReceipt", [params.saleId], "ReceiptConfirmed");
   }
-  async acceptUniversalEscrowQuality(saleId) {
-    await this.callUniversalEscrowContract("acceptQuality", [saleId]);
-    return this.getSale(String(saleId));
+  async acceptUniversalEscrowQuality(params) {
+    return this.callUniversalEscrowContract("acceptQuality", [params.saleId], "QualityAccepted");
   }
-  async initiateUniversalEscrowDispute(saleId, reason) {
-    await this.callUniversalEscrowContract("initiateDispute", [saleId, reason]);
-    return this.getSale(String(saleId));
+  async initiateUniversalEscrowDispute(params) {
+    return this.callUniversalEscrowContract("initiateDispute", [params.saleId, params.reason], "DisputeInitiated");
   }
-  async resolveUniversalEscrowDispute(saleId, favorBuyer, refundPercentage) {
-    await this.callUniversalEscrowContract("resolveDispute", [saleId, favorBuyer, refundPercentage]);
-    return this.getSale(String(saleId));
+  async resolveUniversalEscrowDispute(params) {
+    return this.callUniversalEscrowContract("resolveDispute", [params.saleId, params.favorBuyer, params.refundPercentage], "DisputeResolved");
   }
-  async autoReleaseUniversalEscrowFunds(saleId) {
-    await this.callUniversalEscrowContract("autoReleaseFunds", [saleId]);
-    return this.getSale(String(saleId));
+  async autoReleaseUniversalEscrowFunds(params) {
+    return this.callUniversalEscrowContract("autoReleaseFunds", [params.saleId], "AutoReleased");
   }
   hasUniversalEscrowContract() {
     return !!(this.provider && this.contracts?.universalEscrow);
   }
-  async callUniversalEscrowContract(method, args) {
+  async callUniversalEscrowContract(method, args, eventName) {
     if (!this.hasUniversalEscrowContract()) {
       throw new Error("universalEscrow contract configuration is required");
     }
@@ -27614,8 +27598,8 @@ var OpenCommodityClient = class {
       } catch {
         return null;
       }
-    }).find((e) => e?.name === "SaleCreated");
-    return event?.args?.saleId ?? receipt.hash;
+    }).find((e) => e?.name === eventName);
+    return String(event?.args?.saleId ?? receipt.hash);
   }
 };
 

package/dist/index.mjs

@@ -27540,55 +27540,39 @@ var OpenCommodityClient = class {
     });
   }
   async createUniversalEscrowSale(params) {
-    if (this.hasUniversalEscrowContract()) {
-      const saleId = await this.callUniversalEscrowContract("createSale", [
-        params.token_id,
-        params.amount,
-        params.price,
-        params.seller_wallet
-      ]);
-      return {
-        id: String(saleId),
-        commodity_id: params.commodity_id,
-        seller_wallet: params.seller_wallet,
-        buyer_wallet: params.buyer_wallet,
-        price: params.price,
-        amount: params.amount,
-        status: "FUNDED",
-        gcid: null,
-        created_at: (/* @__PURE__ */ new Date()).toISOString()
-      };
+    if (!this.hasUniversalEscrowContract()) {
+      throw new Error("universalEscrow contract configuration is required");
     }
-    return this.createSale(params);
+    const saleId = await this.callUniversalEscrowContract("createSale", [
+      params.tokenId,
+      params.amount,
+      params.price,
+      params.seller
+    ], "SaleCreated");
+    return String(saleId);
   }
-  async confirmUniversalEscrowShipment(saleId) {
-    await this.callUniversalEscrowContract("confirmShipment", [saleId]);
-    return this.getSale(String(saleId));
+  async confirmUniversalEscrowShipment(params) {
+    return this.callUniversalEscrowContract("confirmShipment", [params.saleId], "Shipped");
   }
-  async confirmUniversalEscrowReceipt(saleId) {
-    await this.callUniversalEscrowContract("confirmReceipt", [saleId]);
-    return this.getSale(String(saleId));
+  async confirmUniversalEscrowReceipt(params) {
+    return this.callUniversalEscrowContract("confirmReceipt", [params.saleId], "ReceiptConfirmed");
   }
-  async acceptUniversalEscrowQuality(saleId) {
-    await this.callUniversalEscrowContract("acceptQuality", [saleId]);
-    return this.getSale(String(saleId));
+  async acceptUniversalEscrowQuality(params) {
+    return this.callUniversalEscrowContract("acceptQuality", [params.saleId], "QualityAccepted");
   }
-  async initiateUniversalEscrowDispute(saleId, reason) {
-    await this.callUniversalEscrowContract("initiateDispute", [saleId, reason]);
-    return this.getSale(String(saleId));
+  async initiateUniversalEscrowDispute(params) {
+    return this.callUniversalEscrowContract("initiateDispute", [params.saleId, params.reason], "DisputeInitiated");
   }
-  async resolveUniversalEscrowDispute(saleId, favorBuyer, refundPercentage) {
-    await this.callUniversalEscrowContract("resolveDispute", [saleId, favorBuyer, refundPercentage]);
-    return this.getSale(String(saleId));
+  async resolveUniversalEscrowDispute(params) {
+    return this.callUniversalEscrowContract("resolveDispute", [params.saleId, params.favorBuyer, params.refundPercentage], "DisputeResolved");
   }
-  async autoReleaseUniversalEscrowFunds(saleId) {
-    await this.callUniversalEscrowContract("autoReleaseFunds", [saleId]);
-    return this.getSale(String(saleId));
+  async autoReleaseUniversalEscrowFunds(params) {
+    return this.callUniversalEscrowContract("autoReleaseFunds", [params.saleId], "AutoReleased");
   }
   hasUniversalEscrowContract() {
     return !!(this.provider && this.contracts?.universalEscrow);
   }
-  async callUniversalEscrowContract(method, args) {
+  async callUniversalEscrowContract(method, args, eventName) {
     if (!this.hasUniversalEscrowContract()) {
       throw new Error("universalEscrow contract configuration is required");
     }
@@ -27606,8 +27590,8 @@ var OpenCommodityClient = class {
       } catch {
         return null;
       }
-    }).find((e) => e?.name === "SaleCreated");
-    return event?.args?.saleId ?? receipt.hash;
+    }).find((e) => e?.name === eventName);
+    return String(event?.args?.saleId ?? receipt.hash);
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@railblock/opencommodity-sdk",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "TypeScript SDK for the OpenCommodity Protocol API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",