@railblock/opencommodity-sdk 1.0.1

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 ADDED
@@ -0,0 +1,126 @@
1
+ # OpenCommodity SDK
2
+
3
+ ```
4
+ ██████╗ ██████╗ ███████╗███╗ ██╗ ██╗ ██╗███████╗████████╗██╗███╗ ██╗ ██████╗
5
+ ██╔═══██╗██╔══██╗██╔════╝████╗ ██║ ██║ ██║██╔════╝╚══██╔══╝██║████╗ ██║██╔════╝
6
+ ██║ ██║████████╝█████╗ ██╔██╗ ██║ ██║ ██║███████╗ ██║ ██║██╔██╗ ██║██║ ███╗
7
+ ██║ ██║██╔═══╝ ██╔══╝ ██║╚██╗██║ ██║ ██║╚════██║ ██║ ██║██║╚██╗██║██║ ██║
8
+ ╚██████╔╝██║ ███████╗██║ ╚████║ ███████╗██║███████║ ██║ ██║██║ ╚████║╚██████╔╝
9
+ ╚═════╝ ╚═╝ ╚══════╝╚═╝ ╚═══╝ ╚══════╝╚═╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═══╝ ╚═════╝
10
+ ```
11
+
12
+ > The TypeScript SDK for OpenCommodity smart contract and API integrations.
13
+
14
+ [![npm version](https://img.shields.io/npm/v/@railblock/opencommodity-sdk.svg)](https://www.npmjs.com/package/@railblock/opencommodity-sdk)
15
+ [![license](https://img.shields.io/npm/l/@railblock/opencommodity-sdk.svg)](./LICENSE)
16
+ [![types](https://img.shields.io/badge/types-TypeScript-blue.svg)](https://www.typescriptlang.org/)
17
+
18
+ ---
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ npm install @railblock/opencommodity-sdk
24
+ ```
25
+
26
+ ## Quick start
27
+
28
+ ```ts
29
+ import { OpenCommodity } from "@railblock/opencommodity-sdk";
30
+
31
+ const client = new OpenCommodity({
32
+ apiKey: process.env.OPENCOMMODITY_API_KEY,
33
+ endpoint: "https://api.opencommodity.pro",
34
+ });
35
+ ```
36
+
37
+ ## One-liner usage
38
+
39
+ ```ts
40
+ const client = new OpenCommodity({ apiKey: process.env.OPENCOMMODITY_API_KEY });
41
+ ```
42
+
43
+ ## What this SDK does
44
+
45
+ - Talks to the OpenCommodity API
46
+ - Supports contract-backed commodity, listing, and marketplace flows
47
+ - Falls back to REST when no contract config is provided
48
+ - Exposes contract ABIs for `CommodityRegistry`, `OpenCommodity`, and `MarketplaceRegistry`
49
+
50
+ ## Contract-backed usage
51
+
52
+ ### Commodity registration
53
+
54
+ ```ts
55
+ const client = new OpenCommodity({
56
+ apiKey: process.env.OPENCOMMODITY_API_KEY,
57
+ endpoint: "https://api.opencommodity.pro",
58
+ provider: window.ethereum,
59
+ contracts: {
60
+ commodityRegistry: "0xYourCommodityRegistryAddress",
61
+ },
62
+ });
63
+
64
+ const result = await client.registerCommodity("ipfs://metadata-uri");
65
+ ```
66
+
67
+ ### Listing management
68
+
69
+ ```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
+ },
77
+ });
78
+
79
+ await client.createListing(1, "1.5");
80
+ await client.updatePrice(1, "2.0");
81
+ await client.cancelListing(1);
82
+ ```
83
+
84
+ ### Marketplace registration
85
+
86
+ ```ts
87
+ const client = new OpenCommodity({
88
+ apiKey: process.env.OPENCOMMODITY_API_KEY,
89
+ endpoint: "https://api.opencommodity.pro",
90
+ provider: window.ethereum,
91
+ contracts: {
92
+ marketplaceRegistry: "0xYourMarketplaceRegistryAddress",
93
+ },
94
+ });
95
+
96
+ const marketplace = await client.registerMarketplace({
97
+ name: "Main",
98
+ wallet: "0xYourWalletAddress",
99
+ fee_percent: 1.5,
100
+ escrow_enabled: true,
101
+ });
102
+
103
+ await client.updateMarketplaceFee(marketplace.marketplaceId, 2.0);
104
+ await client.deactivateMarketplace(marketplace.marketplaceId);
105
+ ```
106
+
107
+ ## REST fallback
108
+
109
+ ```ts
110
+ const client = new OpenCommodity({
111
+ apiKey: process.env.OPENCOMMODITY_API_KEY,
112
+ endpoint: "https://api.opencommodity.pro",
113
+ });
114
+
115
+ const listings = await client.getListings();
116
+ ```
117
+
118
+ ## Why OpenCommodity
119
+
120
+ 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.
121
+
122
+ ## Publishing notes
123
+
124
+ - Keep the README install snippet current with the published npm package name.
125
+ - Use this file as the public-facing entry point for npm consumers.
126
+ - Update examples when contract ABIs or method signatures change.
@@ -0,0 +1,179 @@
1
+ interface ContractConfig {
2
+ universalEscrow?: string;
3
+ }
4
+ interface ClientConfig {
5
+ apiKey: string;
6
+ baseUrl?: string;
7
+ provider?: unknown;
8
+ contracts?: ContractConfig;
9
+ }
10
+ interface PaginatedResponse<T> {
11
+ data: T[];
12
+ total: number;
13
+ page: number;
14
+ limit: number;
15
+ }
16
+ interface Commodity {
17
+ id: string;
18
+ commodity_id: number;
19
+ owner_wallet: string;
20
+ metadata: Record<string, unknown>;
21
+ metadata_uri: string | null;
22
+ verified: boolean;
23
+ category: string | null;
24
+ gcid: string;
25
+ created_at: string;
26
+ updated_at: string;
27
+ }
28
+ interface Listing {
29
+ id: string;
30
+ commodity_id: number;
31
+ seller_wallet: string;
32
+ price: number;
33
+ active: boolean;
34
+ gcid: string | null;
35
+ created_at: string;
36
+ }
37
+ interface Sale {
38
+ id: string;
39
+ commodity_id: number;
40
+ seller_wallet: string;
41
+ buyer_wallet: string;
42
+ price: number;
43
+ amount: number;
44
+ status: string;
45
+ gcid: string | null;
46
+ created_at: string;
47
+ }
48
+ interface Marketplace {
49
+ id: string;
50
+ name: string;
51
+ wallet: string;
52
+ fee_percent: number;
53
+ escrow_enabled: boolean;
54
+ commission_model: string;
55
+ created_at: string;
56
+ }
57
+ interface ProtocolStats {
58
+ total_commodities: number;
59
+ active_listings: number;
60
+ total_marketplaces: number;
61
+ total_events: number;
62
+ total_revenue: number;
63
+ }
64
+ interface IpfsUploadResult {
65
+ metadataURI: string;
66
+ cid: string;
67
+ }
68
+ interface CreateSaleParams {
69
+ token_id: number;
70
+ amount: number;
71
+ price: number;
72
+ seller_wallet: string;
73
+ buyer_wallet: string;
74
+ commodity_id: number;
75
+ }
76
+ type SaleAction = "confirm_shipment" | "confirm_receipt" | "accept_quality" | "initiate_dispute" | "cancel";
77
+ interface UpdateSaleParams {
78
+ sale_id: string;
79
+ action: SaleAction;
80
+ dispute_reason?: string;
81
+ }
82
+ interface CreateMarketplaceParams {
83
+ name: string;
84
+ wallet: string;
85
+ fee_percent?: number;
86
+ escrow_enabled?: boolean;
87
+ commission_model?: string;
88
+ }
89
+ interface CommodityFilters {
90
+ page?: number;
91
+ limit?: number;
92
+ category?: string;
93
+ verified?: boolean;
94
+ gcid?: string;
95
+ }
96
+ interface SaleFilters {
97
+ page?: number;
98
+ limit?: number;
99
+ status?: string;
100
+ seller_wallet?: string;
101
+ buyer_wallet?: string;
102
+ }
103
+ interface MarketplaceFilters {
104
+ page?: number;
105
+ limit?: number;
106
+ }
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
+
121
+ declare class OpenCommodityError extends Error {
122
+ status: number;
123
+ body?: unknown;
124
+ constructor(status: number, message: string, body?: unknown);
125
+ }
126
+ declare class OpenCommodityClient {
127
+ private apiKey;
128
+ private baseUrl;
129
+ private provider?;
130
+ private contracts?;
131
+ constructor(config: ClientConfig);
132
+ private request;
133
+ private readJson;
134
+ private readErrorBody;
135
+ private extractErrorMessage;
136
+ private toQuery;
137
+ listCommodities(filters?: CommodityFilters): Promise<PaginatedResponse<Commodity>>;
138
+ getCommodity(id: string): Promise<Commodity>;
139
+ getCommodityByGCID(gcid: string): Promise<Commodity>;
140
+ uploadMetadata(metadata: Record<string, unknown>): Promise<IpfsUploadResult>;
141
+ listSales(filters?: SaleFilters): Promise<PaginatedResponse<Sale>>;
142
+ getSale(id: string): Promise<Sale>;
143
+ createSale(params: CreateSaleParams): Promise<Sale>;
144
+ updateSale(params: UpdateSaleParams): Promise<Sale>;
145
+ listMarketplaces(filters?: MarketplaceFilters): Promise<PaginatedResponse<Marketplace>>;
146
+ getMarketplace(id: string): Promise<Marketplace>;
147
+ createMarketplace(params: CreateMarketplaceParams): Promise<Marketplace>;
148
+ listListings(filters?: {
149
+ page?: number;
150
+ limit?: number;
151
+ }): Promise<PaginatedResponse<Listing>>;
152
+ getListing(id: string): Promise<Listing>;
153
+ getStats(): Promise<ProtocolStats>;
154
+ createCommodity(params: CreateCommodityParams): Promise<Commodity>;
155
+ createListing(params: CreateListingParams): Promise<Listing>;
156
+ createUniversalEscrowSale(params: CreateSaleParams): Promise<Sale>;
157
+ confirmUniversalEscrowShipment(saleId: string | number): Promise<Sale>;
158
+ confirmUniversalEscrowReceipt(saleId: string | number): Promise<Sale>;
159
+ acceptUniversalEscrowQuality(saleId: string | number): Promise<Sale>;
160
+ initiateUniversalEscrowDispute(saleId: string | number, reason: string): Promise<Sale>;
161
+ resolveUniversalEscrowDispute(saleId: string | number, favorBuyer: boolean, refundPercentage: number): Promise<Sale>;
162
+ autoReleaseUniversalEscrowFunds(saleId: string | number): Promise<Sale>;
163
+ private hasUniversalEscrowContract;
164
+ private callUniversalEscrowContract;
165
+ }
166
+
167
+ declare const UNIVERSAL_ESCROW_ABI: string[];
168
+
169
+ declare const COMMODITY_TYPE_CODES: Record<string, string>;
170
+ declare function generateGCID(subcategory: string, countryCode: string, grade: string, commodityId: number, year?: number | string): string;
171
+ declare function parseGCID(gcid: string): {
172
+ typeCode: string;
173
+ countryCode: string;
174
+ grade: string;
175
+ year: string;
176
+ commodityId: number | null;
177
+ };
178
+
179
+ 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, UNIVERSAL_ESCROW_ABI, type UpdateSaleParams, generateGCID, parseGCID };
@@ -0,0 +1,179 @@
1
+ interface ContractConfig {
2
+ universalEscrow?: string;
3
+ }
4
+ interface ClientConfig {
5
+ apiKey: string;
6
+ baseUrl?: string;
7
+ provider?: unknown;
8
+ contracts?: ContractConfig;
9
+ }
10
+ interface PaginatedResponse<T> {
11
+ data: T[];
12
+ total: number;
13
+ page: number;
14
+ limit: number;
15
+ }
16
+ interface Commodity {
17
+ id: string;
18
+ commodity_id: number;
19
+ owner_wallet: string;
20
+ metadata: Record<string, unknown>;
21
+ metadata_uri: string | null;
22
+ verified: boolean;
23
+ category: string | null;
24
+ gcid: string;
25
+ created_at: string;
26
+ updated_at: string;
27
+ }
28
+ interface Listing {
29
+ id: string;
30
+ commodity_id: number;
31
+ seller_wallet: string;
32
+ price: number;
33
+ active: boolean;
34
+ gcid: string | null;
35
+ created_at: string;
36
+ }
37
+ interface Sale {
38
+ id: string;
39
+ commodity_id: number;
40
+ seller_wallet: string;
41
+ buyer_wallet: string;
42
+ price: number;
43
+ amount: number;
44
+ status: string;
45
+ gcid: string | null;
46
+ created_at: string;
47
+ }
48
+ interface Marketplace {
49
+ id: string;
50
+ name: string;
51
+ wallet: string;
52
+ fee_percent: number;
53
+ escrow_enabled: boolean;
54
+ commission_model: string;
55
+ created_at: string;
56
+ }
57
+ interface ProtocolStats {
58
+ total_commodities: number;
59
+ active_listings: number;
60
+ total_marketplaces: number;
61
+ total_events: number;
62
+ total_revenue: number;
63
+ }
64
+ interface IpfsUploadResult {
65
+ metadataURI: string;
66
+ cid: string;
67
+ }
68
+ interface CreateSaleParams {
69
+ token_id: number;
70
+ amount: number;
71
+ price: number;
72
+ seller_wallet: string;
73
+ buyer_wallet: string;
74
+ commodity_id: number;
75
+ }
76
+ type SaleAction = "confirm_shipment" | "confirm_receipt" | "accept_quality" | "initiate_dispute" | "cancel";
77
+ interface UpdateSaleParams {
78
+ sale_id: string;
79
+ action: SaleAction;
80
+ dispute_reason?: string;
81
+ }
82
+ interface CreateMarketplaceParams {
83
+ name: string;
84
+ wallet: string;
85
+ fee_percent?: number;
86
+ escrow_enabled?: boolean;
87
+ commission_model?: string;
88
+ }
89
+ interface CommodityFilters {
90
+ page?: number;
91
+ limit?: number;
92
+ category?: string;
93
+ verified?: boolean;
94
+ gcid?: string;
95
+ }
96
+ interface SaleFilters {
97
+ page?: number;
98
+ limit?: number;
99
+ status?: string;
100
+ seller_wallet?: string;
101
+ buyer_wallet?: string;
102
+ }
103
+ interface MarketplaceFilters {
104
+ page?: number;
105
+ limit?: number;
106
+ }
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
+
121
+ declare class OpenCommodityError extends Error {
122
+ status: number;
123
+ body?: unknown;
124
+ constructor(status: number, message: string, body?: unknown);
125
+ }
126
+ declare class OpenCommodityClient {
127
+ private apiKey;
128
+ private baseUrl;
129
+ private provider?;
130
+ private contracts?;
131
+ constructor(config: ClientConfig);
132
+ private request;
133
+ private readJson;
134
+ private readErrorBody;
135
+ private extractErrorMessage;
136
+ private toQuery;
137
+ listCommodities(filters?: CommodityFilters): Promise<PaginatedResponse<Commodity>>;
138
+ getCommodity(id: string): Promise<Commodity>;
139
+ getCommodityByGCID(gcid: string): Promise<Commodity>;
140
+ uploadMetadata(metadata: Record<string, unknown>): Promise<IpfsUploadResult>;
141
+ listSales(filters?: SaleFilters): Promise<PaginatedResponse<Sale>>;
142
+ getSale(id: string): Promise<Sale>;
143
+ createSale(params: CreateSaleParams): Promise<Sale>;
144
+ updateSale(params: UpdateSaleParams): Promise<Sale>;
145
+ listMarketplaces(filters?: MarketplaceFilters): Promise<PaginatedResponse<Marketplace>>;
146
+ getMarketplace(id: string): Promise<Marketplace>;
147
+ createMarketplace(params: CreateMarketplaceParams): Promise<Marketplace>;
148
+ listListings(filters?: {
149
+ page?: number;
150
+ limit?: number;
151
+ }): Promise<PaginatedResponse<Listing>>;
152
+ getListing(id: string): Promise<Listing>;
153
+ getStats(): Promise<ProtocolStats>;
154
+ createCommodity(params: CreateCommodityParams): Promise<Commodity>;
155
+ createListing(params: CreateListingParams): Promise<Listing>;
156
+ createUniversalEscrowSale(params: CreateSaleParams): Promise<Sale>;
157
+ confirmUniversalEscrowShipment(saleId: string | number): Promise<Sale>;
158
+ confirmUniversalEscrowReceipt(saleId: string | number): Promise<Sale>;
159
+ acceptUniversalEscrowQuality(saleId: string | number): Promise<Sale>;
160
+ initiateUniversalEscrowDispute(saleId: string | number, reason: string): Promise<Sale>;
161
+ resolveUniversalEscrowDispute(saleId: string | number, favorBuyer: boolean, refundPercentage: number): Promise<Sale>;
162
+ autoReleaseUniversalEscrowFunds(saleId: string | number): Promise<Sale>;
163
+ private hasUniversalEscrowContract;
164
+ private callUniversalEscrowContract;
165
+ }
166
+
167
+ declare const UNIVERSAL_ESCROW_ABI: string[];
168
+
169
+ declare const COMMODITY_TYPE_CODES: Record<string, string>;
170
+ declare function generateGCID(subcategory: string, countryCode: string, grade: string, commodityId: number, year?: number | string): string;
171
+ declare function parseGCID(gcid: string): {
172
+ typeCode: string;
173
+ countryCode: string;
174
+ grade: string;
175
+ year: string;
176
+ commodityId: number | null;
177
+ };
178
+
179
+ 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, UNIVERSAL_ESCROW_ABI, type UpdateSaleParams, generateGCID, parseGCID };