satuchain-api 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SATU TEAM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# satuchain-api
+
+Official JavaScript/TypeScript SDK for the **SATUCHAIN Developer API** — live forex rates, crypto prices, and commodity data.
+
+[![npm version](https://img.shields.io/npm/v/satuchain-api.svg)](https://www.npmjs.com/package/satuchain-api)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Requirements
+
+- **≥ 10,000 STU** tokens on BNB Chain to generate an API key
+- Get your key at [dev.satuchain.com](https://dev.satuchain.com)
+
+## Installation
+
+```bash
+npm install satuchain-api
+# or
+yarn add satuchain-api
+# or
+pnpm add satuchain-api
+```
+
+## Quick Start
+
+```typescript
+import { SatuChainAPI } from "satuchain-api";
+
+const api = new SatuChainAPI("sk_live_YOUR_KEY");
+
+const data = await api.getCommodities();
+
+// Forex — units per 1 USD
+console.log(data.forex.IDR.value);   // e.g. 16250
+console.log(data.forex.MYR.value);   // e.g. 4.71
+console.log(data.forex.EUR.value);   // e.g. 0.9251
+
+// Crypto — price in USD
+console.log(data.crypto.BTC.value);  // e.g. 67420.50
+console.log(data.crypto.BNB.value);  // e.g. 580.10
+console.log(data.crypto.STU.value);  // e.g. 0.00182
+
+// Commodities
+console.log(data.commodities.XAU.value);          // Gold  e.g. 2680.50 (USD/troy oz)
+console.log(data.commodities.XAU.changePercent);  // e.g. -0.42 (% from prev close)
+console.log(data.commodities.XAG.value);          // Silver e.g. 31.40 (USD/troy oz)
+console.log(data.commodities.COPPER.value);       // Copper e.g. 4.20 (USD/lb)
+```
+
+## Constructor
+
+```typescript
+// Simple — just pass the key
+const api = new SatuChainAPI("sk_live_...");
+
+// Full options
+const api = new SatuChainAPI({
+  apiKey: "sk_live_...",
+  baseUrl: "https://dev.satuchain.com", // optional, default
+  timeout: 10000,                        // optional, ms
+});
+```
+
+## Methods
+
+### `getCommodities(opts?)`
+
+Fetches all available data in a single request.
+
+```typescript
+const data = await api.getCommodities();
+// data.crypto   — BTC, BNB, STU
+// data.forex    — CNY, EUR, IDR, JPY, MYR, NGN, SGD, VND
+// data.commodities — XAU, XAG, COPPER
+```
+
+### `getForex(opts?)`
+
+Returns only forex rates.
+
+```typescript
+const forex = await api.getForex();
+console.log(forex.IDR.value); // IDR per 1 USD
+```
+
+### `getCrypto(opts?)`
+
+Returns only crypto prices.
+
+```typescript
+const crypto = await api.getCrypto();
+console.log(crypto.BTC.value); // USD
+```
+
+### `getMetals(opts?)`
+
+Returns only commodity prices.
+
+```typescript
+const metals = await api.getMetals();
+console.log(metals.XAU.value);          // USD/troy oz
+console.log(metals.XAU.changePercent);  // % change from prev close
+```
+
+## Rate Limits
+
+Each API key is limited to **60 requests per minute**. Rate limit info is available after any request:
+
+```typescript
+const data = await api.getCommodities();
+
+console.log(api.rateLimit);
+// { limit: 60, remaining: 59, resetAt: 1712345678 }
+```
+
+On rate limit exceeded, a `SatuChainRateLimitError` is thrown with a `retryAfter` field (seconds):
+
+```typescript
+import { SatuChainRateLimitError } from "satuchain-api";
+
+try {
+  const data = await api.getCommodities();
+} catch (err) {
+  if (err instanceof SatuChainRateLimitError) {
+    console.log(`Retry after ${err.retryAfter}s`);
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+import {
+  SatuChainAuthError,
+  SatuChainRateLimitError,
+  SatuChainUpstreamError,
+  SatuChainError,
+} from "satuchain-api";
+
+try {
+  const data = await api.getCommodities();
+} catch (err) {
+  if (err instanceof SatuChainAuthError) {
+    // 401 — invalid or revoked API key
+  } else if (err instanceof SatuChainRateLimitError) {
+    // 429 — slow down, check err.retryAfter
+  } else if (err instanceof SatuChainUpstreamError) {
+    // 502 — upstream data source unavailable
+  } else if (err instanceof SatuChainError) {
+    // network timeout or other SDK error
+  }
+}
+```
+
+## Request Cancellation
+
+```typescript
+const controller = new AbortController();
+
+setTimeout(() => controller.abort(), 3000);
+
+const data = await api.getCommodities({ signal: controller.signal });
+```
+
+## CommonJS
+
+```javascript
+const { SatuChainAPI } = require("satuchain-api");
+
+const api = new SatuChainAPI("sk_live_YOUR_KEY");
+api.getCommodities().then((data) => {
+  console.log(data.forex.IDR.value);
+});
+```
+
+## Response Shape
+
+```typescript
+{
+  ok: true,
+  base: "USD",
+  updatedAtUnix: 1712345600,      // forex update time
+  nextUpdateUnix: 1712349200,
+  crypto: {
+    BTC:  { name: "Bitcoin",    value: 67420.50 },
+    BNB:  { name: "BNB",        value: 580.10   },
+    STU:  { name: "SATU Token", value: 0.00182  }
+  },
+  forex: {
+    CNY: { name: "Chinese Yuan",       value: 7.2412  },
+    EUR: { name: "Euro",               value: 0.9251  },
+    IDR: { name: "Indonesian Rupiah",  value: 16250   },
+    JPY: { name: "Japanese Yen",       value: 151.82  },
+    MYR: { name: "Malaysian Ringgit",  value: 4.7120  },
+    NGN: { name: "Nigerian Naira",     value: 1580    },
+    SGD: { name: "Singapore Dollar",   value: 1.3510  },
+    VND: { name: "Vietnamese Dong",    value: 25100   }
+  },
+  commodities: {
+    XAU:    { name: "Gold",   value: 2680.50, changePercent: -0.42, unit: "USD/troy oz" },
+    XAG:    { name: "Silver", value: 31.40,   changePercent:  0.81, unit: "USD/troy oz" },
+    COPPER: { name: "Copper", value: 4.20,    changePercent: -0.15, unit: "USD/lb"      }
+  }
+}
+```
+
+## Links
+
+- **API Portal**: [dev.satuchain.com](https://dev.satuchain.com)
+- **SATUCHAIN**: [satuchain.com](https://satuchain.com)
+- **X (Twitter)**: [@SatuChain](https://x.com/SatuChain)
+- **Telegram**: [t.me/satuchain](https://t.me/satuchain)
+
+## License
+
+MIT — see [LICENSE](LICENSE)

package/dist/cjs/client.cjs

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SatuChainAPI = void 0;
+const errors_js_1 = require("./errors.js");
+const DEFAULT_BASE_URL = "https://dev.satuchain.com";
+const DEFAULT_TIMEOUT = 10000;
+class SatuChainAPI {
+    constructor(options) {
+        /** Last rate-limit info from the most recent response */
+        this.rateLimit = null;
+        if (typeof options === "string") {
+            this.apiKey = options;
+            this.baseUrl = DEFAULT_BASE_URL;
+            this.timeout = DEFAULT_TIMEOUT;
+        }
+        else {
+            this.apiKey = options.apiKey;
+            this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+            this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        }
+        if (!this.apiKey.startsWith("sk_live_")) {
+            throw new errors_js_1.SatuChainError("API key must start with sk_live_");
+        }
+    }
+    async request(path, opts) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        const signal = opts?.signal
+            ? AbortSignal.any
+                ? AbortSignal.any([opts.signal, controller.signal])
+                : controller.signal
+            : controller.signal;
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method: "GET",
+                headers: {
+                    "X-API-Key": this.apiKey,
+                    "Accept": "application/json",
+                    "User-Agent": "satuchain-sdk/1.0.1",
+                },
+                signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err?.name === "AbortError") {
+                throw new errors_js_1.SatuChainError(`Request timed out after ${this.timeout}ms`);
+            }
+            throw new errors_js_1.SatuChainError(`Network error: ${err?.message ?? err}`);
+        }
+        clearTimeout(timer);
+        // Parse rate-limit headers
+        const rlLimit = parseInt(res.headers.get("x-ratelimit-limit") ?? "");
+        const rlRemaining = parseInt(res.headers.get("x-ratelimit-remaining") ?? "");
+        const rlReset = parseInt(res.headers.get("x-ratelimit-reset") ?? "");
+        if (!isNaN(rlLimit)) {
+            this.rateLimit = { limit: rlLimit, remaining: rlRemaining, resetAt: rlReset };
+        }
+        if (res.status === 401) {
+            const body = await res.json().catch(() => ({}));
+            throw new errors_js_1.SatuChainAuthError(body?.error);
+        }
+        if (res.status === 429) {
+            const retryAfter = parseInt(res.headers.get("retry-after") ?? "60");
+            const body = await res.json().catch(() => ({}));
+            throw new errors_js_1.SatuChainRateLimitError(retryAfter, body?.error);
+        }
+        if (!res.ok) {
+            throw new errors_js_1.SatuChainUpstreamError(res.status);
+        }
+        const json = await res.json();
+        if (!json.ok) {
+            throw new errors_js_1.SatuChainError(json.error ?? "API error");
+        }
+        return json;
+    }
+    /**
+     * Fetch live commodity, forex, and crypto price data.
+     *
+     * @example
+     * const data = await api.getCommodities();
+     * console.log(data.forex.IDR.value);      // IDR per 1 USD
+     * console.log(data.crypto.BTC.value);     // BTC price in USD
+     * console.log(data.commodities.XAU.value); // Gold price in USD/troy oz
+     */
+    async getCommodities(opts) {
+        return this.request("/api/commodities", opts);
+    }
+    /**
+     * Get just the forex rates (subset of getCommodities).
+     */
+    async getForex(opts) {
+        const data = await this.getCommodities(opts);
+        return data.forex;
+    }
+    /**
+     * Get just the crypto prices (subset of getCommodities).
+     */
+    async getCrypto(opts) {
+        const data = await this.getCommodities(opts);
+        return data.crypto;
+    }
+    /**
+     * Get just the commodity prices (subset of getCommodities).
+     */
+    async getMetals(opts) {
+        const data = await this.getCommodities(opts);
+        return data.commodities;
+    }
+}
+exports.SatuChainAPI = SatuChainAPI;
+//# sourceMappingURL=client.js.map

package/dist/cjs/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/cjs/errors.cjs

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SatuChainUpstreamError = exports.SatuChainRateLimitError = exports.SatuChainAuthError = exports.SatuChainError = void 0;
+class SatuChainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SatuChainError";
+    }
+}
+exports.SatuChainError = SatuChainError;
+class SatuChainAuthError extends SatuChainError {
+    constructor(message = "Invalid or missing API key") {
+        super(message);
+        this.status = 401;
+        this.name = "SatuChainAuthError";
+    }
+}
+exports.SatuChainAuthError = SatuChainAuthError;
+class SatuChainRateLimitError extends SatuChainError {
+    constructor(retryAfter, message) {
+        super(message ?? `Rate limit exceeded. Retry after ${retryAfter}s`);
+        this.status = 429;
+        this.name = "SatuChainRateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+exports.SatuChainRateLimitError = SatuChainRateLimitError;
+class SatuChainUpstreamError extends SatuChainError {
+    constructor(status, message) {
+        super(message ?? `Upstream error: ${status}`);
+        this.name = "SatuChainUpstreamError";
+        this.status = status;
+    }
+}
+exports.SatuChainUpstreamError = SatuChainUpstreamError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAAA,MAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AALD,wCAKC;AAED,MAAa,kBAAmB,SAAQ,cAAc;IAEpD,YAAY,OAAO,GAAG,4BAA4B;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QAFR,WAAM,GAAG,GAAG,CAAC;QAGpB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAND,gDAMC;AAED,MAAa,uBAAwB,SAAQ,cAAc;IAGzD,YAAY,UAAkB,EAAE,OAAgB;QAC9C,KAAK,CAAC,OAAO,IAAI,oCAAoC,UAAU,GAAG,CAAC,CAAC;QAH7D,WAAM,GAAG,GAAG,CAAC;QAIpB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AARD,0DAQC;AAED,MAAa,sBAAuB,SAAQ,cAAc;IAExD,YAAY,MAAc,EAAE,OAAgB;QAC1C,KAAK,CAAC,OAAO,IAAI,mBAAmB,MAAM,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAPD,wDAOC"}

package/dist/cjs/index.cjs

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SatuChainUpstreamError = exports.SatuChainRateLimitError = exports.SatuChainAuthError = exports.SatuChainError = exports.SatuChainAPI = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "SatuChainAPI", { enumerable: true, get: function () { return client_js_1.SatuChainAPI; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "SatuChainError", { enumerable: true, get: function () { return errors_js_1.SatuChainError; } });
+Object.defineProperty(exports, "SatuChainAuthError", { enumerable: true, get: function () { return errors_js_1.SatuChainAuthError; } });
+Object.defineProperty(exports, "SatuChainRateLimitError", { enumerable: true, get: function () { return errors_js_1.SatuChainRateLimitError; } });
+Object.defineProperty(exports, "SatuChainUpstreamError", { enumerable: true, get: function () { return errors_js_1.SatuChainUpstreamError; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAA2C;AAAlC,yGAAA,YAAY,OAAA;AACrB,yCAKqB;AAJnB,2GAAA,cAAc,OAAA;AACd,+GAAA,kBAAkB,OAAA;AAClB,oHAAA,uBAAuB,OAAA;AACvB,mHAAA,sBAAsB,OAAA"}

package/dist/cjs/types.cjs

@@ -0,0 +1,4 @@
+"use strict";
+// ─── Response Types ──────────────────────────────────────────────────────────
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA,gFAAgF"}

package/dist/esm/client.d.ts

@@ -0,0 +1,33 @@
+import type { SatuChainAPIOptions, RequestOptions, CommoditiesResponse, RateLimitInfo } from "./types.js";
+export declare class SatuChainAPI {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /** Last rate-limit info from the most recent response */
+    rateLimit: RateLimitInfo | null;
+    constructor(options: SatuChainAPIOptions | string);
+    private request;
+    /**
+     * Fetch live commodity, forex, and crypto price data.
+     *
+     * @example
+     * const data = await api.getCommodities();
+     * console.log(data.forex.IDR.value);      // IDR per 1 USD
+     * console.log(data.crypto.BTC.value);     // BTC price in USD
+     * console.log(data.commodities.XAU.value); // Gold price in USD/troy oz
+     */
+    getCommodities(opts?: RequestOptions): Promise<CommoditiesResponse>;
+    /**
+     * Get just the forex rates (subset of getCommodities).
+     */
+    getForex(opts?: RequestOptions): Promise<CommoditiesResponse["forex"]>;
+    /**
+     * Get just the crypto prices (subset of getCommodities).
+     */
+    getCrypto(opts?: RequestOptions): Promise<CommoditiesResponse["crypto"]>;
+    /**
+     * Get just the commodity prices (subset of getCommodities).
+     */
+    getMetals(opts?: RequestOptions): Promise<CommoditiesResponse["commodities"]>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/esm/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,aAAa,EACd,MAAM,YAAY,CAAC;AAWpB,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,yDAAyD;IAClD,SAAS,EAAE,aAAa,GAAG,IAAI,CAAQ;gBAElC,OAAO,EAAE,mBAAmB,GAAG,MAAM;YAgBnC,OAAO;IAiErB;;;;;;;;OAQG;IACG,cAAc,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIzE;;OAEG;IACG,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAK5E;;OAEG;IACG,SAAS,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAK9E;;OAEG;IACG,SAAS,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;CAIpF"}

package/dist/esm/client.js

@@ -0,0 +1,109 @@
+import { SatuChainAuthError, SatuChainRateLimitError, SatuChainUpstreamError, SatuChainError, } from "./errors.js";
+const DEFAULT_BASE_URL = "https://dev.satuchain.com";
+const DEFAULT_TIMEOUT = 10000;
+export class SatuChainAPI {
+    constructor(options) {
+        /** Last rate-limit info from the most recent response */
+        this.rateLimit = null;
+        if (typeof options === "string") {
+            this.apiKey = options;
+            this.baseUrl = DEFAULT_BASE_URL;
+            this.timeout = DEFAULT_TIMEOUT;
+        }
+        else {
+            this.apiKey = options.apiKey;
+            this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+            this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+        }
+        if (!this.apiKey.startsWith("sk_live_")) {
+            throw new SatuChainError("API key must start with sk_live_");
+        }
+    }
+    async request(path, opts) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        const signal = opts?.signal
+            ? AbortSignal.any
+                ? AbortSignal.any([opts.signal, controller.signal])
+                : controller.signal
+            : controller.signal;
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method: "GET",
+                headers: {
+                    "X-API-Key": this.apiKey,
+                    "Accept": "application/json",
+                    "User-Agent": "satuchain-sdk/1.0.1",
+                },
+                signal,
+            });
+        }
+        catch (err) {
+            clearTimeout(timer);
+            if (err?.name === "AbortError") {
+                throw new SatuChainError(`Request timed out after ${this.timeout}ms`);
+            }
+            throw new SatuChainError(`Network error: ${err?.message ?? err}`);
+        }
+        clearTimeout(timer);
+        // Parse rate-limit headers
+        const rlLimit = parseInt(res.headers.get("x-ratelimit-limit") ?? "");
+        const rlRemaining = parseInt(res.headers.get("x-ratelimit-remaining") ?? "");
+        const rlReset = parseInt(res.headers.get("x-ratelimit-reset") ?? "");
+        if (!isNaN(rlLimit)) {
+            this.rateLimit = { limit: rlLimit, remaining: rlRemaining, resetAt: rlReset };
+        }
+        if (res.status === 401) {
+            const body = await res.json().catch(() => ({}));
+            throw new SatuChainAuthError(body?.error);
+        }
+        if (res.status === 429) {
+            const retryAfter = parseInt(res.headers.get("retry-after") ?? "60");
+            const body = await res.json().catch(() => ({}));
+            throw new SatuChainRateLimitError(retryAfter, body?.error);
+        }
+        if (!res.ok) {
+            throw new SatuChainUpstreamError(res.status);
+        }
+        const json = await res.json();
+        if (!json.ok) {
+            throw new SatuChainError(json.error ?? "API error");
+        }
+        return json;
+    }
+    /**
+     * Fetch live commodity, forex, and crypto price data.
+     *
+     * @example
+     * const data = await api.getCommodities();
+     * console.log(data.forex.IDR.value);      // IDR per 1 USD
+     * console.log(data.crypto.BTC.value);     // BTC price in USD
+     * console.log(data.commodities.XAU.value); // Gold price in USD/troy oz
+     */
+    async getCommodities(opts) {
+        return this.request("/api/commodities", opts);
+    }
+    /**
+     * Get just the forex rates (subset of getCommodities).
+     */
+    async getForex(opts) {
+        const data = await this.getCommodities(opts);
+        return data.forex;
+    }
+    /**
+     * Get just the crypto prices (subset of getCommodities).
+     */
+    async getCrypto(opts) {
+        const data = await this.getCommodities(opts);
+        return data.crypto;
+    }
+    /**
+     * Get just the commodity prices (subset of getCommodities).
+     */
+    async getMetals(opts) {
+        const data = await this.getCommodities(opts);
+        return data.commodities;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/esm/errors.d.ts

@@ -0,0 +1,17 @@
+export declare class SatuChainError extends Error {
+    constructor(message: string);
+}
+export declare class SatuChainAuthError extends SatuChainError {
+    readonly status = 401;
+    constructor(message?: string);
+}
+export declare class SatuChainRateLimitError extends SatuChainError {
+    readonly status = 429;
+    readonly retryAfter: number;
+    constructor(retryAfter: number, message?: string);
+}
+export declare class SatuChainUpstreamError extends SatuChainError {
+    readonly status: number;
+    constructor(status: number, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,QAAQ,CAAC,MAAM,OAAO;gBACV,OAAO,SAA+B;CAInD;AAED,qBAAa,uBAAwB,SAAQ,cAAc;IACzD,QAAQ,CAAC,MAAM,OAAO;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAKjD;AAED,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK7C"}

package/dist/esm/errors.js

@@ -0,0 +1,29 @@
+export class SatuChainError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SatuChainError";
+    }
+}
+export class SatuChainAuthError extends SatuChainError {
+    constructor(message = "Invalid or missing API key") {
+        super(message);
+        this.status = 401;
+        this.name = "SatuChainAuthError";
+    }
+}
+export class SatuChainRateLimitError extends SatuChainError {
+    constructor(retryAfter, message) {
+        super(message ?? `Rate limit exceeded. Retry after ${retryAfter}s`);
+        this.status = 429;
+        this.name = "SatuChainRateLimitError";
+        this.retryAfter = retryAfter;
+    }
+}
+export class SatuChainUpstreamError extends SatuChainError {
+    constructor(status, message) {
+        super(message ?? `Upstream error: ${status}`);
+        this.name = "SatuChainUpstreamError";
+        this.status = status;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IAEpD,YAAY,OAAO,GAAG,4BAA4B;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QAFR,WAAM,GAAG,GAAG,CAAC;QAGpB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,cAAc;IAGzD,YAAY,UAAkB,EAAE,OAAgB;QAC9C,KAAK,CAAC,OAAO,IAAI,oCAAoC,UAAU,GAAG,CAAC,CAAC;QAH7D,WAAM,GAAG,GAAG,CAAC;QAIpB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,sBAAuB,SAAQ,cAAc;IAExD,YAAY,MAAc,EAAE,OAAgB;QAC1C,KAAK,CAAC,OAAO,IAAI,mBAAmB,MAAM,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { SatuChainAPI } from "./client.js";
+export { SatuChainError, SatuChainAuthError, SatuChainRateLimitError, SatuChainUpstreamError, } from "./errors.js";
+export type { SatuChainAPIOptions, RequestOptions, CommoditiesResponse, ForexEntry, CryptoEntry, CommodityEntry, RateLimitInfo, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export { SatuChainAPI } from "./client.js";
+export { SatuChainError, SatuChainAuthError, SatuChainRateLimitError, SatuChainUpstreamError, } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,aAAa,CAAC"}

package/dist/esm/types.d.ts

@@ -0,0 +1,65 @@
+export interface ForexEntry {
+    name: string;
+    /** Units of this currency per 1 USD */
+    value: number | null;
+}
+export interface CryptoEntry {
+    name: string;
+    /** Price in USD */
+    value: number | null;
+}
+export interface CommodityEntry {
+    name: string;
+    /** Price in USD per unit (troy oz for XAU/XAG, lb for COPPER) */
+    value: number | null;
+    /** Percentage change from previous close (positive = up, negative = down) */
+    changePercent?: number | null;
+    /** Unit description e.g. "USD/troy oz" */
+    unit?: string;
+    note?: string;
+}
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    resetAt: number;
+}
+export interface CommoditiesResponse {
+    ok: true;
+    base: "USD";
+    updatedAtUnix: number | null;
+    nextUpdateUnix: number | null;
+    crypto: {
+        BTC: CryptoEntry;
+        BNB: CryptoEntry;
+        STU: CryptoEntry;
+    };
+    forex: {
+        CNY: ForexEntry;
+        EUR: ForexEntry;
+        IDR: ForexEntry;
+        JPY: ForexEntry;
+        MYR: ForexEntry;
+        NGN: ForexEntry;
+        SGD: ForexEntry;
+        VND: ForexEntry;
+        [key: string]: ForexEntry;
+    };
+    commodities: {
+        XAU: CommodityEntry;
+        XAG: CommodityEntry;
+        COPPER: CommodityEntry;
+    };
+}
+export interface SatuChainAPIOptions {
+    /** Your API key — starts with sk_live_ */
+    apiKey: string;
+    /** Base URL (default: https://dev.satuchain.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+export interface RequestOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,KAAK,CAAC;IACZ,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE;QACN,GAAG,EAAE,WAAW,CAAC;QACjB,GAAG,EAAE,WAAW,CAAC;QACjB,GAAG,EAAE,WAAW,CAAC;KAClB,CAAC;IACF,KAAK,EAAE;QACL,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC;KAC3B,CAAC;IACF,WAAW,EAAE;QACX,GAAG,EAAE,cAAc,CAAC;QACpB,GAAG,EAAE,cAAc,CAAC;QACpB,MAAM,EAAE,cAAc,CAAC;KACxB,CAAC;CACH;AAID,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}

package/dist/esm/types.js

@@ -0,0 +1,3 @@
+// ─── Response Types ──────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF"}

package/dist/types/client.d.ts

@@ -0,0 +1,33 @@
+import type { SatuChainAPIOptions, RequestOptions, CommoditiesResponse, RateLimitInfo } from "./types.js";
+export declare class SatuChainAPI {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    /** Last rate-limit info from the most recent response */
+    rateLimit: RateLimitInfo | null;
+    constructor(options: SatuChainAPIOptions | string);
+    private request;
+    /**
+     * Fetch live commodity, forex, and crypto price data.
+     *
+     * @example
+     * const data = await api.getCommodities();
+     * console.log(data.forex.IDR.value);      // IDR per 1 USD
+     * console.log(data.crypto.BTC.value);     // BTC price in USD
+     * console.log(data.commodities.XAU.value); // Gold price in USD/troy oz
+     */
+    getCommodities(opts?: RequestOptions): Promise<CommoditiesResponse>;
+    /**
+     * Get just the forex rates (subset of getCommodities).
+     */
+    getForex(opts?: RequestOptions): Promise<CommoditiesResponse["forex"]>;
+    /**
+     * Get just the crypto prices (subset of getCommodities).
+     */
+    getCrypto(opts?: RequestOptions): Promise<CommoditiesResponse["crypto"]>;
+    /**
+     * Get just the commodity prices (subset of getCommodities).
+     */
+    getMetals(opts?: RequestOptions): Promise<CommoditiesResponse["commodities"]>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,aAAa,EACd,MAAM,YAAY,CAAC;AAWpB,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,yDAAyD;IAClD,SAAS,EAAE,aAAa,GAAG,IAAI,CAAQ;gBAElC,OAAO,EAAE,mBAAmB,GAAG,MAAM;YAgBnC,OAAO;IAiErB;;;;;;;;OAQG;IACG,cAAc,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIzE;;OAEG;IACG,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAK5E;;OAEG;IACG,SAAS,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAK9E;;OAEG;IACG,SAAS,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;CAIpF"}

package/dist/types/errors.d.ts

@@ -0,0 +1,17 @@
+export declare class SatuChainError extends Error {
+    constructor(message: string);
+}
+export declare class SatuChainAuthError extends SatuChainError {
+    readonly status = 401;
+    constructor(message?: string);
+}
+export declare class SatuChainRateLimitError extends SatuChainError {
+    readonly status = 429;
+    readonly retryAfter: number;
+    constructor(retryAfter: number, message?: string);
+}
+export declare class SatuChainUpstreamError extends SatuChainError {
+    readonly status: number;
+    constructor(status: number, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,QAAQ,CAAC,MAAM,OAAO;gBACV,OAAO,SAA+B;CAInD;AAED,qBAAa,uBAAwB,SAAQ,cAAc;IACzD,QAAQ,CAAC,MAAM,OAAO;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAChB,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAKjD;AAED,qBAAa,sBAAuB,SAAQ,cAAc;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBACZ,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK7C"}

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { SatuChainAPI } from "./client.js";
+export { SatuChainError, SatuChainAuthError, SatuChainRateLimitError, SatuChainUpstreamError, } from "./errors.js";
+export type { SatuChainAPIOptions, RequestOptions, CommoditiesResponse, ForexEntry, CryptoEntry, CommodityEntry, RateLimitInfo, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/types/types.d.ts

@@ -0,0 +1,65 @@
+export interface ForexEntry {
+    name: string;
+    /** Units of this currency per 1 USD */
+    value: number | null;
+}
+export interface CryptoEntry {
+    name: string;
+    /** Price in USD */
+    value: number | null;
+}
+export interface CommodityEntry {
+    name: string;
+    /** Price in USD per unit (troy oz for XAU/XAG, lb for COPPER) */
+    value: number | null;
+    /** Percentage change from previous close (positive = up, negative = down) */
+    changePercent?: number | null;
+    /** Unit description e.g. "USD/troy oz" */
+    unit?: string;
+    note?: string;
+}
+export interface RateLimitInfo {
+    limit: number;
+    remaining: number;
+    resetAt: number;
+}
+export interface CommoditiesResponse {
+    ok: true;
+    base: "USD";
+    updatedAtUnix: number | null;
+    nextUpdateUnix: number | null;
+    crypto: {
+        BTC: CryptoEntry;
+        BNB: CryptoEntry;
+        STU: CryptoEntry;
+    };
+    forex: {
+        CNY: ForexEntry;
+        EUR: ForexEntry;
+        IDR: ForexEntry;
+        JPY: ForexEntry;
+        MYR: ForexEntry;
+        NGN: ForexEntry;
+        SGD: ForexEntry;
+        VND: ForexEntry;
+        [key: string]: ForexEntry;
+    };
+    commodities: {
+        XAU: CommodityEntry;
+        XAG: CommodityEntry;
+        COPPER: CommodityEntry;
+    };
+}
+export interface SatuChainAPIOptions {
+    /** Your API key — starts with sk_live_ */
+    apiKey: string;
+    /** Base URL (default: https://dev.satuchain.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+export interface RequestOptions {
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,KAAK,CAAC;IACZ,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,MAAM,EAAE;QACN,GAAG,EAAE,WAAW,CAAC;QACjB,GAAG,EAAE,WAAW,CAAC;QACjB,GAAG,EAAE,WAAW,CAAC;KAClB,CAAC;IACF,KAAK,EAAE;QACL,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,GAAG,EAAE,UAAU,CAAC;QAChB,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC;KAC3B,CAAC;IACF,WAAW,EAAE;QACX,GAAG,EAAE,cAAc,CAAC;QACpB,GAAG,EAAE,cAAc,CAAC;QACpB,MAAM,EAAE,cAAc,CAAC;KACxB,CAAC;CACH;AAID,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "satuchain-api",
+  "version": "1.0.1",
+  "description": "Official JavaScript/TypeScript SDK for the SATUCHAIN Developer API",
+  "keywords": ["satuchain", "crypto", "forex", "commodities", "gold", "api", "sdk"],
+  "author": "SATU TEAM <dev@satuchain.com>",
+  "license": "MIT",
+  "homepage": "https://dev.satuchain.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/satuchain/dev-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/satuchain/dev-api/issues"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.cjs",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json && node scripts/rename-cjs.mjs",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}