feat: add source

Author: ThanhPTP

.github/workflows/publish-npm-beta.yml

@@ -0,0 +1,54 @@
+name: Publish npm Beta
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "js-sdk-v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Validate beta version and tag alignment
+        shell: bash
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          echo "Package version: ${VERSION}"
+
+          if [[ "${VERSION}" != *"-beta"* ]]; then
+            echo "package.json version must include -beta for beta channel publish."
+            exit 1
+          fi
+
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            TAG_VERSION="${GITHUB_REF_NAME#js-sdk-v}"
+            if [[ "${TAG_VERSION}" != "${VERSION}" ]]; then
+              echo "Tag/version mismatch. Tag=${TAG_VERSION}, package.json=${VERSION}"
+              exit 1
+            fi
+          fi
+
+      - name: Build package
+        run: npm run build
+
+      - name: Publish to npm beta channel
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --tag beta --access public

.gitignore

@@ -0,0 +1,43 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+# …but keep example templates committed
+!.env*.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

README.md

@@ -0,0 +1,184 @@
+# RealMarketAPI JavaScript SDK (Beta)
+
+Official beta JavaScript/TypeScript SDK for RealMarketAPI REST and WebSocket market data endpoints.
+
+Website: https://realmarketapi.com/
+
+## Install
+
+```bash
+npm install realmarketapi-js-sdk-beta
+```
+
+## Requirements
+
+- Node.js 18+ (recommended).
+- RealMarketAPI key.
+
+## Quick Start
+
+### REST
+
+```ts
+import { RealMarketApiClient } from "realmarketapi-js-sdk-beta";
+
+const client = new RealMarketApiClient({
+  apiKey: process.env.REALMARKET_API_KEY!
+});
+
+const price = await client.getPrice("EURUSD", "M1");
+console.log(price.closePrice);
+```
+
+### WebSocket
+
+```ts
+import { RealMarketApiWebSocket } from "realmarketapi-js-sdk-beta";
+
+const ws = new RealMarketApiWebSocket({
+  apiKey: process.env.REALMARKET_API_KEY!
+});
+
+const stop = ws.streamPrice("BTCUSDT", "M1", {
+  onOpen: () => console.log("connected"),
+  onMessage: msg => console.log(msg),
+  onError: err => console.error(err),
+  onClose: () => console.log("closed")
+});
+
+setTimeout(() => stop(), 30_000);
+```
+
+## Client Configuration
+
+### `RealMarketApiClient`
+
+```ts
+const client = new RealMarketApiClient({
+  apiKey: "YOUR_API_KEY",
+  baseUrl: "https://api.realmarketapi.com", // optional
+  fetchImpl: fetch // optional custom fetch
+});
+```
+
+Options:
+- `apiKey` (required): your RealMarketAPI key.
+- `baseUrl` (optional): defaults to `https://api.realmarketapi.com`.
+- `fetchImpl` (optional): inject a custom fetch implementation.
+
+### `RealMarketApiWebSocket`
+
+```ts
+const ws = new RealMarketApiWebSocket({
+  apiKey: "YOUR_API_KEY",
+  baseUrl: "https://api.realmarketapi.com", // optional
+  reconnectDelayMs: 2000 // optional
+});
+```
+
+Options:
+- `apiKey` (required): your RealMarketAPI key.
+- `baseUrl` (optional): defaults to `https://api.realmarketapi.com`.
+- `reconnectDelayMs` (optional): reconnect delay after disconnect, default `2000` ms.
+
+## REST API Reference
+
+### `getPrice(symbolCode, timeFrame)`
+- Returns latest ticker payload for one symbol/timeframe.
+
+### `getCandles(symbolCode, timeFrame)`
+- Returns latest candle array for one symbol/timeframe.
+
+### `getHistory(symbolCode, startTime, endTime, pageNumber?, pageSize?)`
+- Returns paginated historical ticker data in the provided ISO 8601 time range.
+
+### `getSymbols()`
+- Returns list of available symbols.
+
+### `getSma(symbolCode, timeFrame, period?)`
+- Returns SMA points for one symbol/timeframe.
+
+## WebSocket API Reference
+
+### `streamPrice(symbolCode, timeFrame, handlers)`
+- Streams live price updates.
+- Returns a stop function `() => void`.
+
+### `streamCandles(symbolCode, timeFrame, handlers)`
+- Streams live candle updates.
+- Returns a stop function `() => void`.
+
+Handlers:
+- `onMessage(message)` required.
+- `onError(error)` optional.
+- `onOpen()` optional.
+- `onClose()` optional.
+
+## Type Shapes
+
+```ts
+type ListResult<T> = { data: T[] };
+
+type PagedResult<T> = {
+  data: T[];
+  pageNumber: number;
+  pageSize: number;
+  totalPages: number;
+  totalRecords: number;
+};
+
+type PriceTickerResult = {
+  symbolCode: string;
+  timeFrame: string;
+  openTime: string;
+  closePrice: number;
+  askPrice?: number;
+  bidPrice?: number;
+};
+
+type PriceCandleResult = {
+  symbolCode: string;
+  timeFrame: string;
+  openTime: string;
+  openPrice: number;
+  highPrice: number;
+  lowPrice: number;
+  closePrice: number;
+  volume: number;
+};
+
+type SymbolResult = {
+  symbolCode: string;
+  name?: string;
+  category?: string;
+};
+
+type IndicatorPoint = {
+  openTime: string;
+  value: number;
+};
+```
+
+## Error Handling
+
+REST methods throw `Error` when the API response is not successful.
+
+```ts
+try {
+  const data = await client.getSymbols();
+  console.log(data.data.length);
+} catch (error) {
+  console.error("Request failed:", error);
+}
+```
+
+## Beta Notes
+
+- Current REST scope: price, candles, history, symbols, SMA.
+- Current WebSocket scope: price and candles with automatic reconnect.
+- API surface may expand before stable `1.0`.
+
+## Links
+
+- Main site: https://realmarketapi.com/
+- API base URL default: https://api.realmarketapi.com

dist/client.d.ts

@@ -0,0 +1,18 @@
+import type { IndicatorPoint, ListResult, PagedResult, PriceCandleResult, PriceTickerResult, SymbolResult } from "./types.js";
+export interface RealMarketApiClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class RealMarketApiClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: RealMarketApiClientOptions);
+    getPrice(symbolCode: string, timeFrame: string): Promise<PriceTickerResult>;
+    getCandles(symbolCode: string, timeFrame: string): Promise<ListResult<PriceCandleResult>>;
+    getHistory(symbolCode: string, startTime: string, endTime: string, pageNumber?: number, pageSize?: number): Promise<PagedResult<PriceTickerResult>>;
+    getSymbols(): Promise<ListResult<SymbolResult>>;
+    getSma(symbolCode: string, timeFrame: string, period?: number): Promise<ListResult<IndicatorPoint>>;
+    private get;
+}

dist/client.js

@@ -0,0 +1,44 @@
+export class RealMarketApiClient {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://api.realmarketapi.com").replace(/\/$/, "");
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async getPrice(symbolCode, timeFrame) {
+        return this.get("/api/v1/price", { symbolCode, timeFrame });
+    }
+    async getCandles(symbolCode, timeFrame) {
+        return this.get("/api/v1/candle", { symbolCode, timeFrame });
+    }
+    async getHistory(symbolCode, startTime, endTime, pageNumber = 1, pageSize = 20) {
+        return this.get("/api/v1/history", {
+            symbolCode,
+            startTime,
+            endTime,
+            pageNumber: String(pageNumber),
+            pageSize: String(pageSize)
+        });
+    }
+    async getSymbols() {
+        return this.get("/api/v1/symbol");
+    }
+    async getSma(symbolCode, timeFrame, period = 20) {
+        return this.get("/api/v1/indicator/sma", {
+            symbolCode,
+            timeFrame,
+            period: String(period)
+        });
+    }
+    async get(path, query = {}) {
+        const params = new URLSearchParams({ apiKey: this.apiKey, ...query });
+        const response = await this.fetchImpl(`${this.baseUrl}${path}?${params.toString()}`);
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`RealMarketApi error ${response.status}: ${body}`);
+        }
+        return (await response.json());
+    }
+}

dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./websocket.js";
+export * from "./types.js";

dist/index.js

@@ -0,0 +1,3 @@
+export * from "./client.js";
+export * from "./websocket.js";
+export * from "./types.js";

dist/types.d.ts

@@ -0,0 +1,37 @@
+export interface ListResult<T> {
+    data: T[];
+}
+export interface PagedResult<T> {
+    data: T[];
+    pageNumber: number;
+    pageSize: number;
+    totalPages: number;
+    totalRecords: number;
+}
+export interface PriceTickerResult {
+    symbolCode: string;
+    timeFrame: string;
+    openTime: string;
+    closePrice: number;
+    askPrice?: number;
+    bidPrice?: number;
+}
+export interface PriceCandleResult {
+    symbolCode: string;
+    timeFrame: string;
+    openTime: string;
+    openPrice: number;
+    highPrice: number;
+    lowPrice: number;
+    closePrice: number;
+    volume: number;
+}
+export interface SymbolResult {
+    symbolCode: string;
+    name?: string;
+    category?: string;
+}
+export interface IndicatorPoint {
+    openTime: string;
+    value: number;
+}

dist/types.js

@@ -0,0 +1 @@
+export {};