@railblock/opencommodity-sdk 1.0.3 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +59 -42
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -26,92 +26,109 @@ npm install @railblock/opencommodity-sdk
26
26
  ## Quick start
27
27
 
28
28
  ```ts
29
- import { OpenCommodity } from "@railblock/opencommodity-sdk";
29
+ import { OpenCommodityClient } from "@railblock/opencommodity-sdk";
30
30
 
31
- const client = new OpenCommodity({
32
- apiKey: process.env.OPENCOMMODITY_API_KEY,
33
- endpoint: "https://api.opencommodity.pro",
31
+ const client = new OpenCommodityClient({
32
+ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
33
+ baseUrl: "https://api.opencommodity.pro",
34
34
  });
35
35
  ```
36
36
 
37
37
  ## One-liner usage
38
38
 
39
39
  ```ts
40
- const client = new OpenCommodity({ apiKey: process.env.OPENCOMMODITY_API_KEY });
40
+ const client = new OpenCommodityClient({ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "" });
41
41
  ```
42
42
 
43
43
  ## What this SDK does
44
44
 
45
45
  - Talks to the OpenCommodity API
46
- - Supports contract-backed commodity, listing, and marketplace flows
46
+ - Supports contract-backed commodity, listing, marketplace, and escrow lifecycle flows
47
47
  - Falls back to REST when no contract config is provided
48
- - Exposes contract ABIs for `CommodityRegistry`, `OpenCommodity`, and `MarketplaceRegistry`
48
+ - Exposes contract ABIs for `UniversalEscrow` and the current SDK client surface
49
49
 
50
- ## Contract-backed usage
50
+ ## Escrow lifecycle usage
51
51
 
52
- ### Commodity registration
52
+ The SDK now includes UniversalEscrow lifecycle methods for the `ship → receive → accept quality → dispute → auto-release` flow.
53
+
54
+ ### Create an escrow sale
53
55
 
54
56
  ```ts
55
- const client = new OpenCommodity({
56
- apiKey: process.env.OPENCOMMODITY_API_KEY,
57
- endpoint: "https://api.opencommodity.pro",
57
+ const client = new OpenCommodityClient({
58
+ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
58
59
  provider: window.ethereum,
59
60
  contracts: {
60
- commodityRegistry: "0xYourCommodityRegistryAddress",
61
+ universalEscrow: "0xYourUniversalEscrowAddress",
61
62
  },
62
63
  });
63
64
 
64
- const result = await client.registerCommodity("ipfs://metadata-uri");
65
+ const saleId = await client.createUniversalEscrowSale({
66
+ tokenId: 1,
67
+ amount: 10,
68
+ price: 1000,
69
+ seller: "0xSellerAddress",
70
+ });
65
71
  ```
66
72
 
67
- ### Listing management
73
+ ### Confirm shipment
68
74
 
69
75
  ```ts
70
- const client = new OpenCommodity({
71
- apiKey: process.env.OPENCOMMODITY_API_KEY,
72
- endpoint: "https://api.opencommodity.pro",
73
- provider: window.ethereum,
74
- contracts: {
75
- listingManager: "0xYourListingManagerAddress",
76
- },
76
+ await client.confirmUniversalEscrowShipment({
77
+ saleId,
77
78
  });
79
+ ```
78
80
 
79
- await client.createListing(1, "1.5");
80
- await client.updatePrice(1, "2.0");
81
- await client.cancelListing(1);
81
+ ### Confirm receipt
82
+
83
+ ```ts
84
+ await client.confirmUniversalEscrowReceipt({
85
+ saleId,
86
+ });
82
87
  ```
83
88
 
84
- ### Marketplace registration
89
+ ### Accept quality
85
90
 
86
- Marketplace operators can configure their own marketplace fee percentage. Protocol, listing, and buy-side fees continue to route to the contract treasury.
91
+ ```ts
92
+ await client.acceptUniversalEscrowQuality({
93
+ saleId,
94
+ });
95
+ ```
96
+
97
+ ### Open a dispute
87
98
 
88
99
  ```ts
89
- const client = new OpenCommodity({
90
- apiKey: process.env.OPENCOMMODITY_API_KEY,
91
- endpoint: "https://api.opencommodity.pro",
92
- provider: window.ethereum,
93
- contracts: {
94
- marketplaceRegistry: "0xYourMarketplaceRegistryAddress",
95
- },
100
+ await client.initiateUniversalEscrowDispute({
101
+ saleId,
102
+ reason: "Item arrived damaged",
96
103
  });
104
+ ```
105
+
106
+ ### Resolve a dispute
97
107
 
98
- const marketplace = await client.registerMarketplace({
99
- fee_percent: 1.5,
108
+ ```ts
109
+ await client.resolveUniversalEscrowDispute({
110
+ saleId,
111
+ favorBuyer: true,
112
+ refundPercentage: 50,
100
113
  });
114
+ ```
115
+
116
+ ### Auto-release funds
101
117
 
102
- await client.updateMarketplaceFee(marketplace.marketplaceId, 2.0);
103
- await client.deactivateMarketplace(marketplace.marketplaceId);
118
+ ```ts
119
+ await client.autoReleaseUniversalEscrowFunds({
120
+ saleId,
121
+ });
104
122
  ```
105
123
 
106
124
  ## REST fallback
107
125
 
108
126
  ```ts
109
- const client = new OpenCommodity({
110
- apiKey: process.env.OPENCOMMODITY_API_KEY,
111
- endpoint: "https://api.opencommodity.pro",
127
+ const client = new OpenCommodityClient({
128
+ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
112
129
  });
113
130
 
114
- const listings = await client.getListings();
131
+ const listings = await client.listListings();
115
132
  ```
116
133
 
117
134
  ## Why OpenCommodity
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@railblock/opencommodity-sdk",
3
- "version": "1.0.3",
3
+ "version": "1.0.4",
4
4
  "description": "TypeScript SDK for the OpenCommodity Protocol API",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",