@railblock/opencommodity-sdk 1.0.10 → 1.0.11
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.
- package/README.md +6 -139
- package/dist/index.d.mts +4 -57
- package/dist/index.d.ts +4 -57
- package/dist/index.js +48 -27561
- package/dist/index.mjs +28 -27563
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,28 +1,6 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @railblock/opencommodity-sdk
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
```
|
|
5
|
-
██████╗ ██████╗ ███████╗███╗ ██╗
|
|
6
|
-
██╔═══██╗██╔══██╗██╔════╝████╗ ██║
|
|
7
|
-
██║ ██║██████╔╝█████╗ ██╔██╗ ██║
|
|
8
|
-
██║ ██║██╔═══╝ ██╔══╝ ██║╚██╗██║
|
|
9
|
-
╚██████╗██║ ██║███████╗██║ ╚████║
|
|
10
|
-
╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝
|
|
11
|
-
██████╗ ██████╗ ███╗ ███╗███╗ ███╗ ██████╗ ██████╗ ██╗████████╗██╗ ██╗
|
|
12
|
-
██╔════╝██╔═══██╗████╗ ████║████╗ ████║██╔═══██╗██╔══██╗██║╚══██╔══╝╚██╗ ██╔╝
|
|
13
|
-
██║ ██║ ██║██╔████╔██║██╔████╔██║██║ ██║██║ ██║██║ ██║ ╚████╔╝
|
|
14
|
-
██║ ██║ ██║██║╚██╔╝██║██║╚██╔╝██║██║ ██║██║ ██║██║ ██║ ╚██╔╝
|
|
15
|
-
╚██████╗╚██████╔╝██║ ╚═╝ ██║██║ ╚═╝ ██║╚██████╔╝██████╔╝██║ ██║ ██║
|
|
16
|
-
╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
> The TypeScript SDK for OpenCommodity smart contract and API integrations.
|
|
20
|
-
|
|
21
|
-
[](https://www.npmjs.com/package/@railblock/opencommodity-sdk)
|
|
22
|
-
[](./LICENSE)
|
|
23
|
-
[](https://www.typescriptlang.org/)
|
|
24
|
-
|
|
25
|
-
---
|
|
3
|
+
TypeScript SDK for the OpenCommodity Protocol API.
|
|
26
4
|
|
|
27
5
|
## Install
|
|
28
6
|
|
|
@@ -30,120 +8,9 @@
|
|
|
30
8
|
npm install @railblock/opencommodity-sdk
|
|
31
9
|
```
|
|
32
10
|
|
|
33
|
-
##
|
|
34
|
-
|
|
35
|
-
```ts
|
|
36
|
-
import { OpenCommodityClient } from "@railblock/opencommodity-sdk";
|
|
37
|
-
|
|
38
|
-
const client = new OpenCommodityClient({
|
|
39
|
-
apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
|
|
40
|
-
baseUrl: "https://api.opencommodity.pro",
|
|
41
|
-
});
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
## One-liner usage
|
|
45
|
-
|
|
46
|
-
```ts
|
|
47
|
-
const client = new OpenCommodityClient({ apiKey: process.env.OPENCOMMODITY_API_KEY ?? "" });
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
## What this SDK does
|
|
51
|
-
|
|
52
|
-
- Talks to the OpenCommodity API
|
|
53
|
-
- Supports contract-backed commodity, listing, marketplace, and escrow lifecycle flows
|
|
54
|
-
- Falls back to REST when no contract config is provided
|
|
55
|
-
- Exposes contract ABIs for `UniversalEscrow` and the current SDK client surface
|
|
56
|
-
|
|
57
|
-
## Escrow lifecycle usage
|
|
58
|
-
|
|
59
|
-
The SDK now includes UniversalEscrow lifecycle methods for the `ship → receive → accept quality → dispute → auto-release` flow.
|
|
60
|
-
|
|
61
|
-
### Create an escrow sale
|
|
62
|
-
|
|
63
|
-
```ts
|
|
64
|
-
const client = new OpenCommodityClient({
|
|
65
|
-
apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
|
|
66
|
-
provider: window.ethereum,
|
|
67
|
-
contracts: {
|
|
68
|
-
universalEscrow: "0xYourUniversalEscrowAddress",
|
|
69
|
-
},
|
|
70
|
-
});
|
|
71
|
-
|
|
72
|
-
const saleId = await client.createUniversalEscrowSale({
|
|
73
|
-
tokenId: 1,
|
|
74
|
-
amount: 10,
|
|
75
|
-
price: 1000,
|
|
76
|
-
seller: "0xSellerAddress",
|
|
77
|
-
});
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
### Confirm shipment
|
|
81
|
-
|
|
82
|
-
```ts
|
|
83
|
-
await client.confirmUniversalEscrowShipment({
|
|
84
|
-
saleId,
|
|
85
|
-
});
|
|
86
|
-
```
|
|
11
|
+
## Commands
|
|
87
12
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
await client.confirmUniversalEscrowReceipt({
|
|
92
|
-
saleId,
|
|
93
|
-
});
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
### Accept quality
|
|
97
|
-
|
|
98
|
-
```ts
|
|
99
|
-
await client.acceptUniversalEscrowQuality({
|
|
100
|
-
saleId,
|
|
101
|
-
});
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
### Open a dispute
|
|
105
|
-
|
|
106
|
-
```ts
|
|
107
|
-
await client.initiateUniversalEscrowDispute({
|
|
108
|
-
saleId,
|
|
109
|
-
reason: "Item arrived damaged",
|
|
110
|
-
});
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
### Resolve a dispute
|
|
114
|
-
|
|
115
|
-
```ts
|
|
116
|
-
await client.resolveUniversalEscrowDispute({
|
|
117
|
-
saleId,
|
|
118
|
-
favorBuyer: true,
|
|
119
|
-
refundPercentage: 50,
|
|
120
|
-
});
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
### Auto-release funds
|
|
124
|
-
|
|
125
|
-
```ts
|
|
126
|
-
await client.autoReleaseUniversalEscrowFunds({
|
|
127
|
-
saleId,
|
|
128
|
-
});
|
|
129
|
-
```
|
|
130
|
-
|
|
131
|
-
## REST fallback
|
|
132
|
-
|
|
133
|
-
```ts
|
|
134
|
-
const client = new OpenCommodityClient({
|
|
135
|
-
apiKey: process.env.OPENCOMMODITY_API_KEY ?? "",
|
|
136
|
-
});
|
|
137
|
-
|
|
138
|
-
const listings = await client.listListings();
|
|
13
|
+
```bash
|
|
14
|
+
npm run build
|
|
15
|
+
npm run test
|
|
139
16
|
```
|
|
140
|
-
|
|
141
|
-
## Why OpenCommodity
|
|
142
|
-
|
|
143
|
-
OpenCommodity is built for marketplace workflows that need a simple SDK entry point for contract operations and API access. This package is designed to be easy to install, easy to brand, and easy to use in a one-line consumer setup.
|
|
144
|
-
|
|
145
|
-
## Publishing notes
|
|
146
|
-
|
|
147
|
-
- Keep the README install snippet current with the published npm package name.
|
|
148
|
-
- Use this file as the public-facing entry point for npm consumers.
|
|
149
|
-
- Update examples when contract ABIs or method signatures change.
|
package/dist/index.d.mts
CHANGED
|
@@ -1,11 +1,6 @@
|
|
|
1
|
-
interface ContractConfig {
|
|
2
|
-
universalEscrow?: string;
|
|
3
|
-
}
|
|
4
1
|
interface ClientConfig {
|
|
5
2
|
apiKey: string;
|
|
6
3
|
baseUrl?: string;
|
|
7
|
-
provider?: unknown;
|
|
8
|
-
contracts?: ContractConfig;
|
|
9
4
|
}
|
|
10
5
|
interface PaginatedResponse<T> {
|
|
11
6
|
data: T[];
|
|
@@ -17,7 +12,7 @@ interface Commodity {
|
|
|
17
12
|
id: string;
|
|
18
13
|
commodity_id: number;
|
|
19
14
|
owner_wallet: string;
|
|
20
|
-
metadata: Record<string,
|
|
15
|
+
metadata: Record<string, any>;
|
|
21
16
|
metadata_uri: string | null;
|
|
22
17
|
verified: boolean;
|
|
23
18
|
category: string | null;
|
|
@@ -104,54 +99,21 @@ interface MarketplaceFilters {
|
|
|
104
99
|
page?: number;
|
|
105
100
|
limit?: number;
|
|
106
101
|
}
|
|
107
|
-
interface CreateCommodityParams {
|
|
108
|
-
name: string;
|
|
109
|
-
category: string;
|
|
110
|
-
owner_wallet: string;
|
|
111
|
-
metadata?: Record<string, unknown>;
|
|
112
|
-
metadata_uri?: string;
|
|
113
|
-
}
|
|
114
|
-
interface CreateListingParams {
|
|
115
|
-
commodity_id: number;
|
|
116
|
-
seller_wallet: string;
|
|
117
|
-
price: number;
|
|
118
|
-
gcid?: string;
|
|
119
|
-
}
|
|
120
|
-
interface CreateEscrowSaleParams {
|
|
121
|
-
tokenId: number;
|
|
122
|
-
amount: number;
|
|
123
|
-
price: number;
|
|
124
|
-
seller: string;
|
|
125
|
-
}
|
|
126
|
-
interface ConfirmEscrowActionParams {
|
|
127
|
-
saleId: string | number;
|
|
128
|
-
}
|
|
129
|
-
interface ResolveEscrowDisputeParams {
|
|
130
|
-
saleId: string | number;
|
|
131
|
-
favorBuyer: boolean;
|
|
132
|
-
refundPercentage: number;
|
|
133
|
-
}
|
|
134
102
|
|
|
135
103
|
declare class OpenCommodityError extends Error {
|
|
136
104
|
status: number;
|
|
137
|
-
|
|
138
|
-
constructor(status: number, message: string, body?: unknown);
|
|
105
|
+
constructor(status: number, message: string);
|
|
139
106
|
}
|
|
140
107
|
declare class OpenCommodityClient {
|
|
141
108
|
private apiKey;
|
|
142
109
|
private baseUrl;
|
|
143
|
-
private provider?;
|
|
144
|
-
private contracts?;
|
|
145
110
|
constructor(config: ClientConfig);
|
|
146
111
|
private request;
|
|
147
|
-
private readJson;
|
|
148
|
-
private readErrorBody;
|
|
149
|
-
private extractErrorMessage;
|
|
150
112
|
private toQuery;
|
|
151
113
|
listCommodities(filters?: CommodityFilters): Promise<PaginatedResponse<Commodity>>;
|
|
152
114
|
getCommodity(id: string): Promise<Commodity>;
|
|
153
115
|
getCommodityByGCID(gcid: string): Promise<Commodity>;
|
|
154
|
-
uploadMetadata(metadata: Record<string,
|
|
116
|
+
uploadMetadata(metadata: Record<string, any>): Promise<IpfsUploadResult>;
|
|
155
117
|
listSales(filters?: SaleFilters): Promise<PaginatedResponse<Sale>>;
|
|
156
118
|
getSale(id: string): Promise<Sale>;
|
|
157
119
|
createSale(params: CreateSaleParams): Promise<Sale>;
|
|
@@ -165,23 +127,8 @@ declare class OpenCommodityClient {
|
|
|
165
127
|
}): Promise<PaginatedResponse<Listing>>;
|
|
166
128
|
getListing(id: string): Promise<Listing>;
|
|
167
129
|
getStats(): Promise<ProtocolStats>;
|
|
168
|
-
createCommodity(params: CreateCommodityParams): Promise<Commodity>;
|
|
169
|
-
createListing(params: CreateListingParams): Promise<Listing>;
|
|
170
|
-
createUniversalEscrowSale(params: CreateEscrowSaleParams): Promise<string>;
|
|
171
|
-
confirmUniversalEscrowShipment(params: ConfirmEscrowActionParams): Promise<string>;
|
|
172
|
-
confirmUniversalEscrowReceipt(params: ConfirmEscrowActionParams): Promise<string>;
|
|
173
|
-
acceptUniversalEscrowQuality(params: ConfirmEscrowActionParams): Promise<string>;
|
|
174
|
-
initiateUniversalEscrowDispute(params: ConfirmEscrowActionParams & {
|
|
175
|
-
reason: string;
|
|
176
|
-
}): Promise<string>;
|
|
177
|
-
resolveUniversalEscrowDispute(params: ResolveEscrowDisputeParams): Promise<string>;
|
|
178
|
-
autoReleaseUniversalEscrowFunds(params: ConfirmEscrowActionParams): Promise<string>;
|
|
179
|
-
private hasUniversalEscrowContract;
|
|
180
|
-
private callUniversalEscrowContract;
|
|
181
130
|
}
|
|
182
131
|
|
|
183
|
-
declare const UNIVERSAL_ESCROW_ABI: string[];
|
|
184
|
-
|
|
185
132
|
declare const COMMODITY_TYPE_CODES: Record<string, string>;
|
|
186
133
|
declare function generateGCID(subcategory: string, countryCode: string, grade: string, commodityId: number, year?: number | string): string;
|
|
187
134
|
declare function parseGCID(gcid: string): {
|
|
@@ -192,4 +139,4 @@ declare function parseGCID(gcid: string): {
|
|
|
192
139
|
commodityId: number | null;
|
|
193
140
|
};
|
|
194
141
|
|
|
195
|
-
export { COMMODITY_TYPE_CODES, type ClientConfig, type Commodity, type CommodityFilters, type CreateMarketplaceParams, type CreateSaleParams, type IpfsUploadResult, type Listing, type Marketplace, type MarketplaceFilters, OpenCommodityClient, OpenCommodityError, type PaginatedResponse, type ProtocolStats, type Sale, type SaleAction, type SaleFilters,
|
|
142
|
+
export { COMMODITY_TYPE_CODES, type ClientConfig, type Commodity, type CommodityFilters, type CreateMarketplaceParams, type CreateSaleParams, type IpfsUploadResult, type Listing, type Marketplace, type MarketplaceFilters, OpenCommodityClient, OpenCommodityError, type PaginatedResponse, type ProtocolStats, type Sale, type SaleAction, type SaleFilters, type UpdateSaleParams, generateGCID, parseGCID };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,6 @@
|
|
|
1
|
-
interface ContractConfig {
|
|
2
|
-
universalEscrow?: string;
|
|
3
|
-
}
|
|
4
1
|
interface ClientConfig {
|
|
5
2
|
apiKey: string;
|
|
6
3
|
baseUrl?: string;
|
|
7
|
-
provider?: unknown;
|
|
8
|
-
contracts?: ContractConfig;
|
|
9
4
|
}
|
|
10
5
|
interface PaginatedResponse<T> {
|
|
11
6
|
data: T[];
|
|
@@ -17,7 +12,7 @@ interface Commodity {
|
|
|
17
12
|
id: string;
|
|
18
13
|
commodity_id: number;
|
|
19
14
|
owner_wallet: string;
|
|
20
|
-
metadata: Record<string,
|
|
15
|
+
metadata: Record<string, any>;
|
|
21
16
|
metadata_uri: string | null;
|
|
22
17
|
verified: boolean;
|
|
23
18
|
category: string | null;
|
|
@@ -104,54 +99,21 @@ interface MarketplaceFilters {
|
|
|
104
99
|
page?: number;
|
|
105
100
|
limit?: number;
|
|
106
101
|
}
|
|
107
|
-
interface CreateCommodityParams {
|
|
108
|
-
name: string;
|
|
109
|
-
category: string;
|
|
110
|
-
owner_wallet: string;
|
|
111
|
-
metadata?: Record<string, unknown>;
|
|
112
|
-
metadata_uri?: string;
|
|
113
|
-
}
|
|
114
|
-
interface CreateListingParams {
|
|
115
|
-
commodity_id: number;
|
|
116
|
-
seller_wallet: string;
|
|
117
|
-
price: number;
|
|
118
|
-
gcid?: string;
|
|
119
|
-
}
|
|
120
|
-
interface CreateEscrowSaleParams {
|
|
121
|
-
tokenId: number;
|
|
122
|
-
amount: number;
|
|
123
|
-
price: number;
|
|
124
|
-
seller: string;
|
|
125
|
-
}
|
|
126
|
-
interface ConfirmEscrowActionParams {
|
|
127
|
-
saleId: string | number;
|
|
128
|
-
}
|
|
129
|
-
interface ResolveEscrowDisputeParams {
|
|
130
|
-
saleId: string | number;
|
|
131
|
-
favorBuyer: boolean;
|
|
132
|
-
refundPercentage: number;
|
|
133
|
-
}
|
|
134
102
|
|
|
135
103
|
declare class OpenCommodityError extends Error {
|
|
136
104
|
status: number;
|
|
137
|
-
|
|
138
|
-
constructor(status: number, message: string, body?: unknown);
|
|
105
|
+
constructor(status: number, message: string);
|
|
139
106
|
}
|
|
140
107
|
declare class OpenCommodityClient {
|
|
141
108
|
private apiKey;
|
|
142
109
|
private baseUrl;
|
|
143
|
-
private provider?;
|
|
144
|
-
private contracts?;
|
|
145
110
|
constructor(config: ClientConfig);
|
|
146
111
|
private request;
|
|
147
|
-
private readJson;
|
|
148
|
-
private readErrorBody;
|
|
149
|
-
private extractErrorMessage;
|
|
150
112
|
private toQuery;
|
|
151
113
|
listCommodities(filters?: CommodityFilters): Promise<PaginatedResponse<Commodity>>;
|
|
152
114
|
getCommodity(id: string): Promise<Commodity>;
|
|
153
115
|
getCommodityByGCID(gcid: string): Promise<Commodity>;
|
|
154
|
-
uploadMetadata(metadata: Record<string,
|
|
116
|
+
uploadMetadata(metadata: Record<string, any>): Promise<IpfsUploadResult>;
|
|
155
117
|
listSales(filters?: SaleFilters): Promise<PaginatedResponse<Sale>>;
|
|
156
118
|
getSale(id: string): Promise<Sale>;
|
|
157
119
|
createSale(params: CreateSaleParams): Promise<Sale>;
|
|
@@ -165,23 +127,8 @@ declare class OpenCommodityClient {
|
|
|
165
127
|
}): Promise<PaginatedResponse<Listing>>;
|
|
166
128
|
getListing(id: string): Promise<Listing>;
|
|
167
129
|
getStats(): Promise<ProtocolStats>;
|
|
168
|
-
createCommodity(params: CreateCommodityParams): Promise<Commodity>;
|
|
169
|
-
createListing(params: CreateListingParams): Promise<Listing>;
|
|
170
|
-
createUniversalEscrowSale(params: CreateEscrowSaleParams): Promise<string>;
|
|
171
|
-
confirmUniversalEscrowShipment(params: ConfirmEscrowActionParams): Promise<string>;
|
|
172
|
-
confirmUniversalEscrowReceipt(params: ConfirmEscrowActionParams): Promise<string>;
|
|
173
|
-
acceptUniversalEscrowQuality(params: ConfirmEscrowActionParams): Promise<string>;
|
|
174
|
-
initiateUniversalEscrowDispute(params: ConfirmEscrowActionParams & {
|
|
175
|
-
reason: string;
|
|
176
|
-
}): Promise<string>;
|
|
177
|
-
resolveUniversalEscrowDispute(params: ResolveEscrowDisputeParams): Promise<string>;
|
|
178
|
-
autoReleaseUniversalEscrowFunds(params: ConfirmEscrowActionParams): Promise<string>;
|
|
179
|
-
private hasUniversalEscrowContract;
|
|
180
|
-
private callUniversalEscrowContract;
|
|
181
130
|
}
|
|
182
131
|
|
|
183
|
-
declare const UNIVERSAL_ESCROW_ABI: string[];
|
|
184
|
-
|
|
185
132
|
declare const COMMODITY_TYPE_CODES: Record<string, string>;
|
|
186
133
|
declare function generateGCID(subcategory: string, countryCode: string, grade: string, commodityId: number, year?: number | string): string;
|
|
187
134
|
declare function parseGCID(gcid: string): {
|
|
@@ -192,4 +139,4 @@ declare function parseGCID(gcid: string): {
|
|
|
192
139
|
commodityId: number | null;
|
|
193
140
|
};
|
|
194
141
|
|
|
195
|
-
export { COMMODITY_TYPE_CODES, type ClientConfig, type Commodity, type CommodityFilters, type CreateMarketplaceParams, type CreateSaleParams, type IpfsUploadResult, type Listing, type Marketplace, type MarketplaceFilters, OpenCommodityClient, OpenCommodityError, type PaginatedResponse, type ProtocolStats, type Sale, type SaleAction, type SaleFilters,
|
|
142
|
+
export { COMMODITY_TYPE_CODES, type ClientConfig, type Commodity, type CommodityFilters, type CreateMarketplaceParams, type CreateSaleParams, type IpfsUploadResult, type Listing, type Marketplace, type MarketplaceFilters, OpenCommodityClient, OpenCommodityError, type PaginatedResponse, type ProtocolStats, type Sale, type SaleAction, type SaleFilters, type UpdateSaleParams, generateGCID, parseGCID };
|