@upbit-official/upbit-sdk 0.9.0

package/src/internal/utils/values.ts

@@ -0,0 +1,104 @@
+
+import { UpbitError } from '../../core/error';
+
+// https://url.spec.whatwg.org/#url-scheme-string
+const startsWithSchemeRegexp = /^[a-z][a-z0-9+.-]*:/i;
+
+export const isAbsoluteURL = (url: string): boolean => {
+  return startsWithSchemeRegexp.test(url);
+};
+
+export let isArray = (val: unknown): val is unknown[] => ((isArray = Array.isArray), isArray(val));
+export let isReadonlyArray = isArray as (val: unknown) => val is readonly unknown[];
+
+/** Returns an object if the given value isn't an object, otherwise returns as-is */
+export function maybeObj(x: unknown): object {
+  if (typeof x !== 'object') {
+    return {};
+  }
+
+  return x ?? {};
+}
+
+// https://stackoverflow.com/a/34491287
+export function isEmptyObj(obj: Object | null | undefined): boolean {
+  if (!obj) return true;
+  for (const _k in obj) return false;
+  return true;
+}
+
+// https://eslint.org/docs/latest/rules/no-prototype-builtins
+export function hasOwn<T extends object = object>(obj: T, key: PropertyKey): key is keyof T {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+
+export function isObj(obj: unknown): obj is Record<string, unknown> {
+  return obj != null && typeof obj === 'object' && !Array.isArray(obj);
+}
+
+export const ensurePresent = <T>(value: T | null | undefined): T => {
+  if (value == null) {
+    throw new UpbitError(`Expected a value to be given but received ${value} instead.`);
+  }
+
+  return value;
+};
+
+export const validatePositiveInteger = (name: string, n: unknown): number => {
+  if (typeof n !== 'number' || !Number.isInteger(n)) {
+    throw new UpbitError(`${name} must be an integer`);
+  }
+  if (n < 0) {
+    throw new UpbitError(`${name} must be a positive integer`);
+  }
+  return n;
+};
+
+export const coerceInteger = (value: unknown): number => {
+  if (typeof value === 'number') return Math.round(value);
+  if (typeof value === 'string') return parseInt(value, 10);
+
+  throw new UpbitError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceFloat = (value: unknown): number => {
+  if (typeof value === 'number') return value;
+  if (typeof value === 'string') return parseFloat(value);
+
+  throw new UpbitError(`Could not coerce ${value} (type: ${typeof value}) into a number`);
+};
+
+export const coerceBoolean = (value: unknown): boolean => {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') return value === 'true';
+  return Boolean(value);
+};
+
+export const maybeCoerceInteger = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceInteger(value);
+};
+
+export const maybeCoerceFloat = (value: unknown): number | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceFloat(value);
+};
+
+export const maybeCoerceBoolean = (value: unknown): boolean | undefined => {
+  if (value == null) {
+    return undefined;
+  }
+  return coerceBoolean(value);
+};
+
+export const safeJSON = (text: string) => {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    return undefined;
+  }
+};

package/src/internal/utils.ts

@@ -0,0 +1,8 @@
+
+export * from './utils/values';
+export * from './utils/base64';
+export * from './utils/env';
+export * from './utils/log';
+export * from './utils/uuid';
+export * from './utils/sleep';
+export * from './utils/query';

package/src/internal/ws.ts

@@ -0,0 +1,68 @@
+/** Reconnection event passed to the `onReconnecting` handler and event listeners. */
+export interface ReconnectingEvent<Parameters = Record<string, unknown>> {
+  /** Which retry attempt this is (1-based). */
+  readonly attempt: number;
+  /** Total attempts that will be made. */
+  readonly maxAttempts: number;
+  /** Delay in ms before this attempt connects. */
+  readonly delay: number;
+  /** The WebSocket close code that triggered reconnection. */
+  readonly closeCode: number;
+  /** The current query parameters. */
+  readonly parameters: (Parameters & Record<string, unknown>) | undefined;
+}
+
+/**
+ * Optional overrides returned from the `onReconnecting` handler
+ * to customize the next reconnection attempt.
+ */
+export type ReconnectingOverrides<Parameters = Record<string, unknown>> =
+  | {
+      /**
+       * If provided, assigns the query parameters for the next connection.
+       * Set to `undefined` to clear all query parameters.
+       */
+      parameters?: (Parameters & Record<string, unknown>) | undefined;
+    }
+  | {
+      /**
+       * If set, will stop attempting to reconnect.
+       */
+      abort: true;
+    };
+
+// RFC 6455 §7.4.1
+export function isRecoverableClose(code: number): boolean {
+  switch (code) {
+    case 1000:
+      return false; // Normal closure
+    case 1001:
+      return true; // Going away (server shutting down)
+    case 1002:
+      return false; // Protocol error
+    case 1003:
+      return false; // Unsupported data
+    case 1005:
+      return true; // No status code (abnormal)
+    case 1006:
+      return true; // Abnormal closure (network drop)
+    case 1007:
+      return false; // Invalid payload
+    case 1008:
+      return false; // Policy violation
+    case 1009:
+      return false; // Message too big
+    case 1010:
+      return false; // Missing extension
+    case 1011:
+      return true; // Internal server error
+    case 1012:
+      return true; // Service restart
+    case 1013:
+      return true; // Try again later
+    case 1015:
+      return true; // TLS handshake failure
+    default:
+      return false;
+  }
+}

package/src/lib/index.ts

@@ -0,0 +1,4 @@
+export { createJwtToken } from './jwtAuth';
+export { WsStream, WsStreamManager } from './ws';
+export type { WsStreamOptions } from './ws';
+export { jsonParseFloat } from './jsonParseFloat';

package/src/lib/jsonParseFloat.ts

@@ -0,0 +1,73 @@
+/**
+ * Fields declared as `number` in the SDK response interfaces.
+ * All other fields with `typeof value === 'number'` at runtime
+ * are assumed to be `string`-typed and will be coerced to strings.
+ */
+const NUMBER_FIELDS: Set<string> = new Set([
+  'timestamp',
+  'trade_timestamp',
+  'sequential_id',
+  'trades_count',
+  'count',
+  'decimal_precision',
+  'minimum_deposit_confirmations',
+  'block_elapsed_minutes',
+  'fee_level',
+  'security_level',
+]);
+
+/**
+ * Parses a JSON string with type-aware coercion.
+ *
+ * 1st pass (JSON.parse reviver): float tokens (containing `.`, `e`, `E`) are
+ * preserved as their original string representation to avoid precision loss.
+ * Uses the reviver's third argument `context.source` (TypeScript 5.2+ / modern runtimes).
+ * Falls back to standard number parsing when `context.source` is unavailable.
+ *
+ * 2nd pass (constructType): coerces values to match SDK declared types.
+ * - `string`-declared fields: `number` → `string`  (e.g. balance `0` → `"0"`)
+ * - `number`-declared fields: `string` → `number`  (e.g. timestamp `"123.45"` → `123.45`)
+ *
+ * Mirrors the behavior of Python SDK's `json.loads(parse_float=str)` + `construct_type()`.
+ */
+export function jsonParseFloat(text: string): unknown {
+  const parsed = JSON.parse(text, (key: string, value: unknown, context?: { source?: string }) => {
+    if (typeof value !== 'number') return value;
+    const src = context?.source;
+    if (!src) return value;
+    return /[.eE]/.test(src) ? src : value;
+  });
+  return constructType(parsed);
+}
+
+function constructType(data: unknown): unknown {
+  if (Array.isArray(data)) {
+    return data.map(constructType);
+  }
+
+  if (data !== null && typeof data === 'object') {
+    const obj = data as Record<string, unknown>;
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(obj)) {
+      const value = obj[key];
+
+      if (NUMBER_FIELDS.has(key)) {
+        // number-declared field: coerce string → number
+        if (typeof value === 'string') {
+          result[key] = Number(value);
+        } else {
+          result[key] = value;
+        }
+      } else if (typeof value === 'number') {
+        // string-declared field: coerce number → string
+        result[key] = String(value);
+      } else {
+        // recurse into nested objects and arrays
+        result[key] = constructType(value);
+      }
+    }
+    return result;
+  }
+
+  return data;
+}

package/src/lib/jwtAuth.ts

@@ -0,0 +1,39 @@
+import { createHmac, createHash } from 'crypto';
+import { uuid4 } from '../internal/utils/uuid';
+import { stringifyQuery } from '../internal/utils/query';
+
+function base64url(buf: Buffer): string {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+/**
+ * Creates a JWT token for Upbit API authentication (HS256).
+ *
+ * If query parameters are provided, their SHA512 hash is included in the payload.
+ */
+export function createJwtToken(
+  accessKey: string,
+  secretKey: string,
+  queryParams?: Record<string, unknown> | null,
+): string {
+  const header = { alg: 'HS256', typ: 'JWT' };
+
+  const payload: Record<string, unknown> = {
+    access_key: accessKey,
+    nonce: uuid4(),
+  };
+
+  if (queryParams && Object.keys(queryParams).length > 0) {
+    const queryString = decodeURIComponent(stringifyQuery(queryParams));
+    const queryHash = createHash('sha512').update(queryString, 'utf8').digest('hex');
+    payload['query_hash'] = queryHash;
+    payload['query_hash_alg'] = 'SHA512';
+  }
+
+  const encodedHeader = base64url(Buffer.from(JSON.stringify(header)));
+  const encodedPayload = base64url(Buffer.from(JSON.stringify(payload)));
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  const signature = base64url(createHmac('sha256', secretKey).update(signingInput).digest());
+
+  return `${signingInput}.${signature}`;
+}

package/src/lib/ws.ts

@@ -0,0 +1,282 @@
+import * as WS from 'ws';
+import { uuid4 } from '../internal/utils/uuid';
+import { createJwtToken } from './jwtAuth';
+import { jsonParseFloat } from './jsonParseFloat';
+import { buildURL as buildPublicURL } from '../resources/ws-public/internal-base';
+import { buildURL as buildPrivateURL } from '../resources/ws-private/internal-base';
+import type { ConnectPublicServerEvent } from '../resources/ws-public/ws-public';
+import type { ConnectPrivateServerEvent } from '../resources/ws-private/ws-private';
+import type { Upbit } from '../client';
+
+export interface WsStreamOptions {
+  /** Maximum number of reconnection attempts (default: 5) */
+  maxRetries?: number;
+  /** Reconnection delay in ms (default: 1000) */
+  retryDelayMs?: number;
+  /** Callback invoked on disconnection */
+  onDisconnect?: (code: number, reason: string) => void;
+  /** Callback invoked on successful reconnection */
+  onReconnect?: () => void;
+}
+
+type PublicSubscriptionType =
+  | { type: 'ticker'; codes: string[] }
+  | { type: 'trade'; codes: string[] }
+  | { type: 'orderbook'; codes: string[] }
+  | { type: string; codes: string[] }; // candle.{interval}
+
+type PrivateSubscriptionType = { type: 'myOrder'; codes?: string[] } | { type: 'myAsset' };
+
+type AnySubscriptionType = PublicSubscriptionType | PrivateSubscriptionType;
+
+function buildSubscriptionMessage(types: AnySubscriptionType[]): string {
+  const fields: object[] = [{ ticket: uuid4() }];
+  for (const t of types) {
+    if ('codes' in t && t.codes) {
+      fields.push({ type: t.type, codes: t.codes });
+    } else {
+      fields.push({ type: t.type });
+    }
+  }
+  return JSON.stringify(fields);
+}
+
+/**
+ * Manages a WebSocket stream as an AsyncIterable.
+ *
+ * Use with `for await (const event of manager) { ... }`.
+ */
+export class WsStreamManager implements AsyncIterable<ConnectPublicServerEvent | ConnectPrivateServerEvent> {
+  private readonly client: Upbit;
+  private readonly types: AnySubscriptionType[];
+  private readonly isPrivate: boolean;
+  private readonly maxRetries: number;
+  private readonly retryDelayMs: number;
+  private readonly onDisconnect: WsStreamOptions['onDisconnect'];
+  private readonly onReconnect: WsStreamOptions['onReconnect'];
+  private _currentWs: WS.WebSocket | null = null;
+
+  constructor(client: Upbit, types: AnySubscriptionType[], isPrivate: boolean, opts: WsStreamOptions = {}) {
+    this.client = client;
+    this.types = types;
+    this.isPrivate = isPrivate;
+    this.maxRetries = opts.maxRetries ?? 5;
+    this.retryDelayMs = opts.retryDelayMs ?? 1000;
+    if (opts.onDisconnect) this.onDisconnect = opts.onDisconnect;
+    if (opts.onReconnect) this.onReconnect = opts.onReconnect;
+  }
+
+  /** Closes the current WebSocket connection. */
+  close(): void {
+    if (
+      this._currentWs &&
+      (this._currentWs.readyState === WS.WebSocket.OPEN ||
+        this._currentWs.readyState === WS.WebSocket.CONNECTING)
+    ) {
+      this._currentWs.close(1000, 'close() called');
+    }
+  }
+
+  [Symbol.asyncIterator](): AsyncGenerator<ConnectPublicServerEvent | ConnectPrivateServerEvent> {
+    return this._iterate();
+  }
+
+  private async *_iterate(): AsyncGenerator<ConnectPublicServerEvent | ConnectPrivateServerEvent> {
+    let retries = 0;
+
+    while (true) {
+      const queue: Array<ConnectPublicServerEvent | ConnectPrivateServerEvent> = [];
+      let resolve: (() => void) | null = null;
+      let reject: ((err: Error) => void) | null = null;
+      let done = false;
+      let closeCode = 1000;
+      let closeReason = '';
+
+      const ws = await this._connect();
+      this._currentWs = ws;
+
+      ws.on('message', (data: WS.RawData) => {
+        try {
+          const parsed = jsonParseFloat(data.toString()) as
+            | ConnectPublicServerEvent
+            | ConnectPrivateServerEvent;
+          queue.push(parsed);
+          resolve?.();
+          resolve = null;
+        } catch {
+          // ignore JSON parse errors
+        }
+      });
+
+      ws.on('close', (code: number, reason: Buffer) => {
+        done = true;
+        closeCode = code;
+        closeReason = reason.toString();
+        resolve?.();
+        resolve = null;
+      });
+
+      ws.on('error', (err: Error) => {
+        done = true;
+        reject?.(err);
+        reject = null;
+        resolve?.();
+        resolve = null;
+      });
+
+      try {
+        while (!done || queue.length > 0) {
+          if (queue.length === 0) {
+            await new Promise<void>((res, rej) => {
+              resolve = res;
+              reject = rej;
+            });
+          }
+          while (queue.length > 0) {
+            yield queue.shift()!;
+          }
+        }
+      } finally {
+        this._currentWs = null;
+        if (ws.readyState === WS.WebSocket.OPEN || ws.readyState === WS.WebSocket.CONNECTING) {
+          ws.close();
+        }
+      }
+
+      // normal close (1000, 1001) — end the stream
+      if (closeCode === 1000 || closeCode === 1001) {
+        this.onDisconnect?.(closeCode, closeReason);
+        return;
+      }
+
+      // attempt reconnect
+      this.onDisconnect?.(closeCode, closeReason);
+
+      if (retries >= this.maxRetries) {
+        throw new Error(
+          `WebSocket disconnected (code=${closeCode}, reason=${closeReason}) after ${retries} retries`,
+        );
+      }
+
+      retries++;
+      await new Promise((r) => setTimeout(r, this.retryDelayMs));
+      this.onReconnect?.();
+    }
+  }
+
+  private async _connect(): Promise<WS.WebSocket> {
+    const url = this.isPrivate ? buildPrivateURL(this.client) : buildPublicURL(this.client);
+
+    const headers: Record<string, string> = {};
+
+    if (this.isPrivate) {
+      const { accessKey, secretKey } = this.client;
+      if (!accessKey || !secretKey) {
+        throw new Error('Private WebSocket requires accessKey and secretKey');
+      }
+      const token = createJwtToken(accessKey, secretKey);
+      headers['Authorization'] = `Bearer ${token}`;
+    }
+
+    return new Promise<WS.WebSocket>((resolve, reject) => {
+      const ws = new WS.WebSocket(url.toString(), { headers });
+
+      const onOpen = () => {
+        ws.removeListener('error', onError);
+        ws.send(buildSubscriptionMessage(this.types));
+        resolve(ws);
+      };
+
+      const onError = (err: Error) => {
+        ws.removeListener('open', onOpen);
+        reject(err);
+      };
+
+      ws.once('open', onOpen);
+      ws.once('error', onError);
+    });
+  }
+}
+
+/**
+ * Convenience API for WebSocket streams.
+ *
+ * Start a stream with `client.wsStream.ticker(['KRW-BTC'])` and
+ * receive events using `for await (const event of ...)`.
+ */
+export class WsStream {
+  constructor(private readonly client: Upbit) {}
+
+  /** Subscribe to the ticker (current price) stream. */
+  ticker(codes: string[], opts?: WsStreamOptions): WsStreamManager {
+    return new WsStreamManager(this.client, [{ type: 'ticker', codes }], false, opts);
+  }
+
+  /** Subscribe to the trade (executed order) stream. */
+  trade(codes: string[], opts?: WsStreamOptions): WsStreamManager {
+    return new WsStreamManager(this.client, [{ type: 'trade', codes }], false, opts);
+  }
+
+  /** Subscribe to the orderbook stream. */
+  orderbook(codes: string[], opts?: WsStreamOptions): WsStreamManager {
+    return new WsStreamManager(this.client, [{ type: 'orderbook', codes }], false, opts);
+  }
+
+  /** Subscribe to the candle stream. */
+  candle(codes: string[], opts?: { interval?: string } & WsStreamOptions): WsStreamManager {
+    const { interval = '1m', ...streamOpts } = opts ?? {};
+    return new WsStreamManager(this.client, [{ type: `candle.${interval}`, codes }], false, streamOpts);
+  }
+
+  /** Subscribe to the myOrder (my orders) stream. Requires authentication. */
+  myOrder(codes: string[], opts?: WsStreamOptions): WsStreamManager {
+    return new WsStreamManager(this.client, [{ type: 'myOrder', codes }], true, opts);
+  }
+
+  /** Subscribe to the myAsset (my assets) stream. Requires authentication. */
+  myAsset(opts?: WsStreamOptions): WsStreamManager {
+    return new WsStreamManager(this.client, [{ type: 'myAsset' }], true, opts);
+  }
+
+  /** Subscribe to multiple public streams at once. */
+  subscribe(
+    opts: {
+      ticker?: string[];
+      trade?: string[];
+      orderbook?: string[];
+      candle?: { codes: string[]; interval?: string };
+    } & WsStreamOptions,
+  ): WsStreamManager {
+    const { ticker, trade, orderbook, candle, maxRetries, retryDelayMs, onDisconnect, onReconnect } = opts;
+    const types: AnySubscriptionType[] = [];
+    if (ticker) types.push({ type: 'ticker', codes: ticker });
+    if (trade) types.push({ type: 'trade', codes: trade });
+    if (orderbook) types.push({ type: 'orderbook', codes: orderbook });
+    if (candle) types.push({ type: `candle.${candle.interval ?? '1m'}`, codes: candle.codes });
+    const streamOpts: WsStreamOptions = {};
+    if (maxRetries !== undefined) streamOpts.maxRetries = maxRetries;
+    if (retryDelayMs !== undefined) streamOpts.retryDelayMs = retryDelayMs;
+    if (onDisconnect) streamOpts.onDisconnect = onDisconnect;
+    if (onReconnect) streamOpts.onReconnect = onReconnect;
+    return new WsStreamManager(this.client, types, false, streamOpts);
+  }
+
+  /** Subscribe to multiple private streams at once. Requires authentication. */
+  subscribePrivate(
+    opts: {
+      myOrder?: string[];
+      myAsset?: boolean;
+    } & WsStreamOptions,
+  ): WsStreamManager {
+    const { myOrder, myAsset, maxRetries, retryDelayMs, onDisconnect, onReconnect } = opts;
+    const types: AnySubscriptionType[] = [];
+    if (myOrder) types.push({ type: 'myOrder', codes: myOrder });
+    if (myAsset) types.push({ type: 'myAsset' });
+    const streamOpts: WsStreamOptions = {};
+    if (maxRetries !== undefined) streamOpts.maxRetries = maxRetries;
+    if (retryDelayMs !== undefined) streamOpts.retryDelayMs = retryDelayMs;
+    if (onDisconnect) streamOpts.onDisconnect = onDisconnect;
+    if (onReconnect) streamOpts.onReconnect = onReconnect;
+    return new WsStreamManager(this.client, types, true, streamOpts);
+  }
+}

package/src/pagination.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/pagination instead */
+export * from './core/pagination';

package/src/resource.ts

@@ -0,0 +1,2 @@
+/** @deprecated Import from ./core/resource instead */
+export * from './core/resource';

package/src/resources/accounts.ts

@@ -0,0 +1,59 @@
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class Accounts extends APIResource {
+  /**
+   * Get Account Balances
+   *
+   * GET /v1/accounts
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/get-balance
+   * - docs(global): https://global-docs.upbit.com/reference/get-balance
+   */
+  list(options?: RequestOptions): APIPromise<AccountListResponse> {
+    return this._client.get('/v1/accounts', options);
+  }
+}
+
+export type AccountListResponse = Array<AccountListResponse.AccountListResponseItem>;
+
+export namespace AccountListResponse {
+  export interface AccountListResponseItem {
+    /**
+     * Average buy price of the asset.
+     */
+    avg_buy_price: string;
+
+    /**
+     * Indicates whether the average buy price has been modified.
+     */
+    avg_buy_price_modified: boolean;
+
+    /**
+     * Available amount or volume for orders. For digital assets, this represents the
+     * available quantity. For fiat currency, this represents the available amount.
+     */
+    balance: string;
+
+    /**
+     * Currency code to be queried.
+     */
+    currency: string;
+
+    /**
+     * Amount or quantity locked by pending orders or withdrawals.
+     */
+    locked: string;
+
+    /**
+     * Currency unit used as the basis for avg_buy_price.
+     */
+    unit_currency: string;
+  }
+}
+
+export declare namespace Accounts {
+  export { type AccountListResponse as AccountListResponse };
+}

package/src/resources/api-keys.ts

@@ -0,0 +1,40 @@
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { RequestOptions } from '../internal/request-options';
+
+export class APIKeys extends APIResource {
+  /**
+   * List API Keys
+   *
+   * GET /v1/api_keys
+   *
+   * - docs(kr): https://docs.upbit.com/kr/reference/list-api-keys
+   * - docs(global): https://global-docs.upbit.com/reference/list-api-keys
+   */
+  list(options?: RequestOptions): APIPromise<APIKeyListResponse> {
+    return this._client.get('/v1/api_keys', options);
+  }
+}
+
+export type APIKeyListResponse = Array<APIKeyListResponse.APIKeyListResponseItem>;
+
+export namespace APIKeyListResponse {
+  export interface APIKeyListResponseItem {
+    /**
+     * Access key of the API key.
+     */
+    access_key: string;
+
+    /**
+     * Expiration timestamp of the access key.
+     *
+     * [Format] yyyy-MM-dd'T'HH:mm:ss+09:00
+     */
+    expire_at: string;
+  }
+}
+
+export declare namespace APIKeys {
+  export { type APIKeyListResponse as APIKeyListResponse };
+}