@railblock/opencommodity-sdk 1.0.3 → 1.0.5

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 +72 -48
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,12 +1,19 @@
1
1
  # OpenCommodity SDK
2
2
 
3
+
3
4
  ```
4
- ██████╗ ██████╗ ███████╗███╗ ██╗ ██╗ ██╗███████╗████████╗██╗███╗ ██╗ ██████╗
5
- ██╔═══██╗██╔══██╗██╔════╝████╗ ██║ ██║ ██║██╔════╝╚══██╔══╝██║████╗ ██║██╔════╝
6
- ██║ ██║████████╝█████╗ ██╔██╗ ██║ ██║ ██║███████╗ ██║ ██║██╔██╗ ██║██║ ███╗
7
- ██║ ██║██╔═══╝ ██╔══╝ ██║╚██╗██║ ██║ ██║╚════██║ ██║ ██║██║╚██╗██║██║ ██║
8
- ╚██████╔╝██║ ███████╗██║ ╚████║ ███████╗██║███████║ ██║ ██║██║ ╚████║╚██████╔╝
9
- ╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ ╚══════╝╚═╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝
5
+ ██████╗ ██████╗ ███████╗███╗ ██╗
6
+ ██╔═══██╗██╔══██╗██╔════╝████╗ ██║
7
+ ██║ ██║██████╔╝█████╗ ██╔██╗ ██║
8
+ ██║ ██║██╔═══╝ ██╔══╝ ██║╚██╗██║
9
+ ╚██████╗██║ ██║███████╗██║ ╚████║
10
+ ╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝
11
+ ██████╗ ██████╗ ███╗ ███╗███╗ ███╗ ██████╗ ██████╗ ██╗████████╗██╗ ██╗
12
+ ██╔════╝██╔═══██╗████╗ ████║████╗ ████║██╔═══██╗██╔══██╗██║╚══██╔══╝╚██╗ ██╔╝
13
+ ██║ ██║ ██║██╔████╔██║██╔████╔██║██║ ██║██║ ██║██║ ██║ ╚████╔╝
14
+ ██║ ██║ ██║██║╚██╔╝██║██║╚██╔╝██║██║ ██║██║ ██║██║ ██║ ╚██╔╝
15
+ ╚██████╗╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║╚██████╔╝██████╔╝██║ ██║ ██║
16
+ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝
10
17
  ```
11
18
 
12
19
  > The TypeScript SDK for OpenCommodity smart contract and API integrations.
@@ -26,92 +33,109 @@ npm install @railblock/opencommodity-sdk
26
33
  ## Quick start
27
34
 
28
35
  ```ts
29
- import { OpenCommodity } from "@railblock/opencommodity-sdk";
36
+ import { OpenCommodityClient } from "@railblock/opencommodity-sdk";
30
37
 
31
- const client = new OpenCommodity({
32
- apiKey: process.env.OPENCOMMODITY_API_KEY,
33
- endpoint: "https://api.opencommodity.pro",
38
+ const client = new OpenCommodityClient({
39
+ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
40
+ baseUrl: "https://api.opencommodity.pro",
34
41
  });
35
42
  ```
36
43
 
37
44
  ## One-liner usage
38
45
 
39
46
  ```ts
40
- const client = new OpenCommodity({ apiKey: process.env.OPENCOMMODITY_API_KEY });
47
+ const client = new OpenCommodityClient({ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "" });
41
48
  ```
42
49
 
43
50
  ## What this SDK does
44
51
 
45
52
  - Talks to the OpenCommodity API
46
- - Supports contract-backed commodity, listing, and marketplace flows
53
+ - Supports contract-backed commodity, listing, marketplace, and escrow lifecycle flows
47
54
  - Falls back to REST when no contract config is provided
48
- - Exposes contract ABIs for `CommodityRegistry`, `OpenCommodity`, and `MarketplaceRegistry`
55
+ - Exposes contract ABIs for `UniversalEscrow` and the current SDK client surface
56
+
57
+ ## Escrow lifecycle usage
49
58
 
50
- ## Contract-backed usage
59
+ The SDK now includes UniversalEscrow lifecycle methods for the `ship → receive → accept quality → dispute → auto-release` flow.
51
60
 
52
- ### Commodity registration
61
+ ### Create an escrow sale
53
62
 
54
63
  ```ts
55
- const client = new OpenCommodity({
56
- apiKey: process.env.OPENCOMMODITY_API_KEY,
57
- endpoint: "https://api.opencommodity.pro",
64
+ const client = new OpenCommodityClient({
65
+ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
58
66
  provider: window.ethereum,
59
67
  contracts: {
60
- commodityRegistry: "0xYourCommodityRegistryAddress",
68
+ universalEscrow: "0xYourUniversalEscrowAddress",
61
69
  },
62
70
  });
63
71
 
64
- const result = await client.registerCommodity("ipfs://metadata-uri");
72
+ const saleId = await client.createUniversalEscrowSale({
73
+ tokenId: 1,
74
+ amount: 10,
75
+ price: 1000,
76
+ seller: "0xSellerAddress",
77
+ });
65
78
  ```
66
79
 
67
- ### Listing management
80
+ ### Confirm shipment
68
81
 
69
82
  ```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
- },
83
+ await client.confirmUniversalEscrowShipment({
84
+ saleId,
77
85
  });
86
+ ```
87
+
88
+ ### Confirm receipt
78
89
 
79
- await client.createListing(1, "1.5");
80
- await client.updatePrice(1, "2.0");
81
- await client.cancelListing(1);
90
+ ```ts
91
+ await client.confirmUniversalEscrowReceipt({
92
+ saleId,
93
+ });
82
94
  ```
83
95
 
84
- ### Marketplace registration
96
+ ### Accept quality
97
+
98
+ ```ts
99
+ await client.acceptUniversalEscrowQuality({
100
+ saleId,
101
+ });
102
+ ```
85
103
 
86
- Marketplace operators can configure their own marketplace fee percentage. Protocol, listing, and buy-side fees continue to route to the contract treasury.
104
+ ### Open a dispute
87
105
 
88
106
  ```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
- },
107
+ await client.initiateUniversalEscrowDispute({
108
+ saleId,
109
+ reason: "Item arrived damaged",
96
110
  });
111
+ ```
97
112
 
98
- const marketplace = await client.registerMarketplace({
99
- fee_percent: 1.5,
113
+ ### Resolve a dispute
114
+
115
+ ```ts
116
+ await client.resolveUniversalEscrowDispute({
117
+ saleId,
118
+ favorBuyer: true,
119
+ refundPercentage: 50,
100
120
  });
121
+ ```
101
122
 
102
- await client.updateMarketplaceFee(marketplace.marketplaceId, 2.0);
103
- await client.deactivateMarketplace(marketplace.marketplaceId);
123
+ ### Auto-release funds
124
+
125
+ ```ts
126
+ await client.autoReleaseUniversalEscrowFunds({
127
+ saleId,
128
+ });
104
129
  ```
105
130
 
106
131
  ## REST fallback
107
132
 
108
133
  ```ts
109
- const client = new OpenCommodity({
110
- apiKey: process.env.OPENCOMMODITY_API_KEY,
111
- endpoint: "https://api.opencommodity.pro",
134
+ const client = new OpenCommodityClient({
135
+ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
112
136
  });
113
137
 
114
- const listings = await client.getListings();
138
+ const listings = await client.listListings();
115
139
  ```
116
140
 
117
141
  ## 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.5",
4
4
  "description": "TypeScript SDK for the OpenCommodity Protocol API",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.mjs",