Masterlink Backend SDK

專為後端應用程式設計的 Masterlink SDK 封裝，提供簡潔易用的 API 來存取台灣證券市場的交易和行情資料。

⚠️ 重要注意事項

原始 SDK 出處: 本套件基於 Masterlink Fugle API 進行封裝。

非官方套件: 這不是由 Masterlink 官方提供的 SDK，而是基於官方 SDK 的一層封裝，提供更簡潔易用的 API 介面。請自行到官方網站下載 package 包

版本對應: 目前對應到官方 SDK 1.0.1 版本。

使用責任: 使用者需自行承擔使用風險，並遵守相關法規和服務條款。

功能特色

• ✅ 登入認證: 支援身分證號、密碼、憑證登入
• ✅ 即時股價: 取得股票即時報價資料
• ✅ 歷史資料: 取得股票歷史 K 線和收盤價
• ✅ 交易日檢查: 檢查指定日期是否為交易日
• ✅ 自動重新認證: 處理 token 過期自動重新登入
• ✅ TypeScript 支援: 完整的型別定義
• ✅ 可配置日誌: 支援自定義日誌輸出
• ✅ 無敏感資訊: 不在 library 內存放登入資訊

安裝

1. 從 Masterlink Fugle API 下載 masterlink-sdk-1.0.1.tgz
2. 執行 npm install masterlink-sdk-1.0.1.tgz 安裝官方套件
3. 執行 npm install masterlink-backend-sdk 安裝本套件

基本使用

1. 建立 SDK 實例

import { MasterlinkBackendSDK } from 'masterlink-backend-sdk';

const sdk = new MasterlinkBackendSDK({
  logger: {
    info: console.log,
    error: console.error,
    warn: console.warn,
    debug: console.debug
  }
});

2. 登入

import { LoginCredentials } from 'masterlink-backend-sdk';

const credentials: LoginCredentials = {
  personalId: 'YOUR_PERSONAL_ID',
  password: 'YOUR_PASSWORD',
  certPath: '/path/to/your/cert.p12',
  certPass: 'YOUR_CERT_PASSWORD'
};

const accounts = sdk.login(credentials);
console.log('登入成功，取得帳戶:', accounts);

3. 取得股票即時報價

const quote = await sdk.getStockQuote('2330'); // 台積電
console.log('台積電即時報價:', {
  symbol: quote.symbol,
  name: quote.name,
  lastPrice: quote.lastPrice,
  change: quote.change,
  changePercent: quote.changePercent
});

4. 取得股票歷史資料

const historicalData = await sdk.getStockHistoricalData(
  '2330',
  '2024-01-01',
  '2024-01-31'
);
console.log('歷史資料筆數:', historicalData.data.length);

5. 取得股票收盤價

const closePrices = await sdk.getStockClosePrices(
  '2330',
  '2024-01-01',
  '2024-01-31'
);
console.log('收盤價筆數:', closePrices.length);

6. 檢查交易日狀態

const tradingStatus = sdk.isTradingDay('2024-01-15');
console.log('是否為交易日:', tradingStatus.isTradingDay);
console.log('交易時間:', tradingStatus.regularHours);

7. 取得下一個交易日

const nextTradingDay = sdk.getNextTradingDay('2024-01-15');
console.log('下一個交易日:', nextTradingDay);

進階功能

自動重新認證

SDK 會自動處理 token 過期，並提供事件回調：

sdk.onReauth((event) => {
  switch (event.type) {
    case 'reauth_required':
      console.log('需要重新認證...');
      break;
    case 'reauth_success':
      console.log('重新認證成功！');
      break;
    case 'reauth_failed':
      console.log('重新認證失敗:', event.error);
      break;
  }
});

批量檢查交易日

const dates = ['2024-01-15', '2024-01-16', '2024-01-17'];
const results = await sdk.checkMultipleTradingDays(dates);
console.log('交易日檢查結果:', results);

取得日期範圍內的交易日

const tradingDays = await sdk.getTradingDaysInRange('2024-01-01', '2024-01-31');
console.log('一月份的交易日:', tradingDays);

API 參考

MasterlinkBackendSDK

建構函數

constructor(config?: MasterlinkBackendConfig)

方法

• login(credentials: LoginCredentials): Account[] - 登入並取得帳戶資訊
• getStockQuote(symbol: string): Promise<StockQuote> - 取得股票即時報價
• getStockHistoricalData(symbol: string, fromDate: string, toDate: string): Promise<StockHistoricalData> - 取得股票歷史資料
• getStockClosePrices(symbol: string, fromDate: string, toDate: string): Promise<StockClosePrice[]> - 取得股票收盤價
• isTradingDay(date: string): TradingDayStatus - 檢查指定日期是否為交易日
• getNextTradingDay(date: string): string | null - 取得下一個交易日
• getLastTradingDay(date: string): string | null - 取得上一個交易日
• checkMultipleTradingDays(dates: string[]): Promise<Record<string, TradingDayStatus>> - 批量檢查交易日
• getTradingDaysInRange(startDate: string, endDate: string): Promise<string[]> - 取得日期範圍內的交易日
• onReauth(callback: ReauthCallback): void - 註冊重新認證事件回調
• offReauth(callback: ReauthCallback): void - 移除重新認證事件回調
• isLoggedIn(): boolean - 檢查是否已登入
• getCurrentAccount(): Account | null - 取得當前帳戶資訊

型別定義

LoginCredentials

interface LoginCredentials {
  personalId: string;
  password: string;
  certPath: string;
  certPass?: string | undefined | null;
}

StockQuote

interface StockQuote {
  symbol: string;
  name: string;
  lastPrice: number;
  lastSize: number;
  openPrice: number;
  highPrice: number;
  lowPrice: number;
  closePrice: number;
  change: number;
  changePercent: number;
  bids: Array<{ price: number; size: number }>;
  asks: Array<{ price: number; size: number }>;
  total: {
    tradeValue: number;
    tradeVolume: number;
    transaction: number;
  };
}

StockHistoricalData

interface StockHistoricalData {
  symbol: string;
  type: string;
  exchange: string;
  market: string;
  data: Array<{
    date: string;
    open: number;
    high: number;
    low: number;
    close: number;
    volume: number;
    turnover: number;
    change: number;
  }>;
}

StockClosePrice

interface StockClosePrice {
  date: string;
  close: number;
}

TradingDayStatus

interface TradingDayStatus {
  isTradingDay: boolean;
  regularHours: {
    openTime: string;
    closeTime: string;
  };
  lastTradingDay: string;
  nextTradingDay: string;
}

MasterlinkBackendConfig

interface MasterlinkBackendConfig {
  logger?: {
    info: (message: string) => void;
    error: (message: string, error?: Error) => void;
    warn: (message: string) => void;
    debug: (message: string) => void;
  };
}

ReauthEvent

interface ReauthEvent {
  type: 'reauth_required' | 'reauth_success' | 'reauth_failed';
  timestamp: Date;
  error?: Error;
}

ReauthCallback

type ReauthCallback = (event: ReauthEvent) => void;

注意事項

1. 憑證管理: 請妥善保管交易憑證，避免外洩
2. 登入資訊: 不要在程式碼中硬編碼登入資訊，建議使用配置檔案或環境變數
3. 錯誤處理: 所有 API 呼叫都應該包含適當的錯誤處理
4. 重新認證: SDK 會自動處理 token 過期，但建議監聽重新認證事件
5. 效能考量: 大量資料查詢時建議使用分頁或限制查詢範圍

授權

MIT License

支援

如有問題或建議，請提交 Issue 或 Pull Request。