@pythfeeds/sdk 1.0.0

package/README.md

@@ -0,0 +1,57 @@
+# @pythfeeds/sdk
+
+Official JavaScript/TypeScript client for the [PythFeeds API](https://pythfeeds.com/developers) — real-time Pyth oracle prices, market data and live streaming. Works in browsers and Node 18+.
+
+## Install
+
+```bash
+npm install @pythfeeds/sdk
+```
+
+## Usage
+
+```js
+import { PythFeeds } from "@pythfeeds/sdk";
+
+const pf = new PythFeeds("pf_live_xxx");
+
+// Single price
+const btc = await pf.getPrice("BTC");
+console.log(btc.price, btc.confidence);
+
+// Batch
+const prices = await pf.getPrices(["BTC", "ETH", "SOL"]);
+
+// Market data
+const coins = await pf.getCoins({ page: 1, perPage: 50 });
+const chart = await pf.getChart("bitcoin", 30);
+const global = await pf.getGlobal();
+```
+
+### Live streaming (SSE)
+
+```js
+const close = pf.stream(["BTC", "ETH"], (update) => {
+  console.log("tick", update);
+});
+// later: close();
+```
+
+In Node, provide an `EventSource` first:
+
+```js
+globalThis.EventSource = (await import("eventsource")).default;
+```
+
+## Errors
+
+Failed calls throw `PythFeedsError` with `.status` and a stable `.code` (`missing_key`, `invalid_key`, `rate_limited`, `quota_exceeded`).
+
+```js
+import { PythFeedsError } from "@pythfeeds/sdk";
+try { await pf.getPrice("BTC"); }
+catch (e) { if (e instanceof PythFeedsError && e.code === "rate_limited") { /* back off */ } }
+```
+
+## Rate limits & quota
+Responses carry `RateLimit-*` (per-minute) and `X-Quota-*` (monthly) headers. See [pythfeeds.com/pricing](https://pythfeeds.com/pricing).

package/index.d.ts

@@ -0,0 +1,33 @@
+export interface PythPrice {
+  symbol: string;
+  price: number;
+  confidence: number;
+  exponent: number;
+  publishTime: number;
+  [k: string]: unknown;
+}
+
+export interface PythFeedsOptions {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+
+export class PythFeedsError extends Error {
+  status?: number;
+  code?: string;
+}
+
+export class PythFeeds {
+  constructor(apiKey: string, options?: PythFeedsOptions);
+  getPrice(symbol: string): Promise<PythPrice>;
+  getPrices(symbols: string[] | string): Promise<Record<string, PythPrice> | PythPrice[]>;
+  getFeeds(query?: string): Promise<unknown>;
+  getCoins(opts?: { page?: number; perPage?: number }): Promise<unknown[]>;
+  getCoin(id: string): Promise<unknown>;
+  getOHLC(id: string, days?: number): Promise<unknown>;
+  getChart(id: string, days?: number): Promise<unknown>;
+  getGlobal(): Promise<unknown>;
+  stream(symbols: string[] | string, onUpdate: (update: unknown) => void, onError?: (err: unknown) => void): () => void;
+}
+
+export default PythFeeds;

package/index.js

@@ -0,0 +1,73 @@
+// PythFeeds official JS/TS SDK — a thin wrapper over the public API.
+// Works in browsers and Node 18+ (global fetch). MIT licensed.
+
+const DEFAULT_BASE = "https://pythfeeds.com/api/v1";
+
+export class PythFeedsError extends Error {
+  constructor(message, status, code) {
+    super(message);
+    this.name = "PythFeedsError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export class PythFeeds {
+  /**
+   * @param {string} apiKey  Your API key (create one at pythfeeds.com/developers).
+   * @param {{ baseUrl?: string, fetch?: typeof fetch }} [options]
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) throw new PythFeedsError("apiKey is required");
+    this.apiKey = apiKey;
+    this.baseUrl = (options.baseUrl || DEFAULT_BASE).replace(/\/$/, "");
+    this._fetch = options.fetch || globalThis.fetch;
+    if (!this._fetch) throw new PythFeedsError("No fetch available — pass options.fetch on older runtimes.");
+  }
+
+  async _get(path, params) {
+    const url = new URL(this.baseUrl + path);
+    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));
+    const res = await this._fetch(url.toString(), { headers: { "x-api-key": this.apiKey, accept: "application/json" } });
+    let body = {};
+    try { body = await res.json(); } catch { /* non-JSON */ }
+    if (!res.ok) throw new PythFeedsError(body.error || `HTTP ${res.status}`, res.status, body.code);
+    return body;
+  }
+
+  /** Real-time Pyth price for one symbol, e.g. "BTC". */
+  getPrice(symbol) { return this._get(`/price/${encodeURIComponent(symbol)}`); }
+  /** Real-time prices for many symbols in one call. */
+  getPrices(symbols) { return this._get("/prices", { symbols: Array.isArray(symbols) ? symbols.join(",") : symbols }); }
+  /** The full Pyth feed catalog (optionally filtered by query). */
+  getFeeds(query) { return this._get("/feeds", query ? { query } : undefined); }
+  /** Top coins by market cap. */
+  getCoins({ page = 1, perPage = 100 } = {}) { return this._get("/coins", { page, per_page: perPage }); }
+  /** Full detail for one coin. */
+  getCoin(id) { return this._get(`/coins/${encodeURIComponent(id)}`); }
+  /** OHLC candles. days ∈ {1,7,14,30,90,180,365}. */
+  getOHLC(id, days = 7) { return this._get(`/coins/${encodeURIComponent(id)}/ohlc`, { days }); }
+  /** Historical price / market-cap / volume series. */
+  getChart(id, days = 7) { return this._get(`/coins/${encodeURIComponent(id)}/chart`, { days }); }
+  /** Global market cap, 24h volume and BTC dominance. */
+  getGlobal() { return this._get("/global"); }
+
+  /**
+   * Subscribe to the live price stream (Server-Sent Events).
+   * Browser-native; in Node install `eventsource` and set `globalThis.EventSource`.
+   * @returns {() => void} a function that closes the stream.
+   */
+  stream(symbols, onUpdate, onError) {
+    const syms = Array.isArray(symbols) ? symbols.join(",") : symbols;
+    const ES = globalThis.EventSource;
+    if (!ES) throw new PythFeedsError("EventSource unavailable — in Node: `globalThis.EventSource = require('eventsource')`.");
+    // EventSource can't send headers, so the key goes in the query string.
+    const url = `${this.baseUrl}/stream?symbols=${encodeURIComponent(syms)}&api_key=${encodeURIComponent(this.apiKey)}`;
+    const es = new ES(url);
+    es.onmessage = (e) => { try { onUpdate(JSON.parse(e.data)); } catch { /* skip */ } };
+    if (onError) es.onerror = onError;
+    return () => es.close();
+  }
+}
+
+export default PythFeeds;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pythfeeds/sdk",
+  "version": "1.0.0",
+  "description": "Official JavaScript/TypeScript SDK for the PythFeeds API — real-time Pyth oracle prices, market data and live SSE streaming.",
+  "type": "module",
+  "main": "index.js",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "files": ["index.js", "index.d.ts", "README.md"],
+  "keywords": ["pyth", "pythfeeds", "crypto", "prices", "oracle", "market-data", "sdk"],
+  "homepage": "https://pythfeeds.com/developers",
+  "license": "MIT",
+  "engines": { "node": ">=18" }
+}