@stockfind/twelve-data 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# @stockfind/twelve-data
+
+TypeScript SDK for the [Twelve Data](https://twelvedata.com) financial API.   
+
+## Planned Features
+
+- Full coverage of 60+ REST endpoints (market data, fundamentals, analysis, technical indicators, etc.)
+- Real-time price streaming via WebSocket
+- Fully typed request/response interfaces
+- Zero runtime dependencies (native `fetch`)
+- Namespaced API design (`td.marketData.*`, `td.fundamentals.*`, `td.technicalIndicators.*`)
+
+## Research
+
+Design docs and API reference are stored as a Claude Code skill in `.claude/skills/twelve-data-sdk/`.

package/dist/index.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+class MarketDataEndpoints {
+  constructor(http) {
+    this.http = http;
+  }
+  timeSeries(params) {
+    return this.http.get("/time_series", params);
+  }
+  quote(params) {
+    return this.http.get("/quote", params);
+  }
+  price(params) {
+    return this.http.get("/price", params);
+  }
+}
+
+class TwelveDataError extends Error {
+  code;
+  status;
+  constructor(message, code) {
+    super(message);
+    this.name = "TwelveDataError";
+    this.code = code;
+    this.status = "error";
+  }
+}
+
+class HttpClient {
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(apiKey, baseUrl, timeout) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+    this.timeout = timeout;
+  }
+  async get(path, params = {}) {
+    const url = new URL(path, this.baseUrl);
+    for (const [key, value] of Object.entries(
+      params
+    )) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await fetch(url.toString(), {
+        headers: { Authorization: `apikey ${this.apiKey}` },
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const body = await response.json();
+    if (body.status === "error") {
+      throw new TwelveDataError(
+        body.message ?? "Unknown error",
+        body.code ?? response.status
+      );
+    }
+    return body;
+  }
+}
+
+class TwelveData {
+  marketData;
+  http;
+  constructor(config) {
+    this.http = new HttpClient(
+      config.apiKey,
+      config.baseUrl ?? "https://api.twelvedata.com",
+      config.timeout ?? 3e4
+    );
+    this.marketData = new MarketDataEndpoints(this.http);
+  }
+}
+
+exports.TwelveData = TwelveData;
+exports.TwelveDataError = TwelveDataError;

package/dist/index.d.cts

@@ -0,0 +1,108 @@
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    constructor(apiKey: string, baseUrl: string, timeout: number);
+    get<T>(path: string, params?: object): Promise<T>;
+}
+
+type Interval = "1min" | "5min" | "15min" | "30min" | "45min" | "1h" | "2h" | "4h" | "1day" | "1week" | "1month";
+interface TwelveDataConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+
+interface TimeSeriesParams {
+    symbol: string;
+    interval: Interval;
+    outputsize?: number;
+    start_date?: string;
+    end_date?: string;
+    timezone?: string;
+    format?: "JSON" | "CSV";
+}
+interface TimeSeriesValue {
+    datetime: string;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    volume?: string;
+}
+interface TimeSeriesResponse {
+    meta: {
+        symbol: string;
+        interval: string;
+        currency: string;
+        exchange_timezone: string;
+        exchange: string;
+        mic_code: string;
+        type: string;
+    };
+    values: TimeSeriesValue[];
+    status: string;
+}
+interface QuoteParams {
+    symbol: string;
+    interval?: Interval;
+    eod?: boolean;
+    rolling_period?: number;
+}
+interface QuoteResponse {
+    symbol: string;
+    name: string;
+    exchange: string;
+    mic_code: string;
+    currency: string;
+    datetime: string;
+    timestamp: number;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    volume: string;
+    previous_close: string;
+    change: string;
+    percent_change: string;
+    average_volume: string;
+    is_market_open: boolean;
+    fifty_two_week: {
+        low: string;
+        high: string;
+        low_change: string;
+        high_change: string;
+        low_change_percent: string;
+        high_change_percent: string;
+        range: string;
+    };
+}
+interface PriceParams {
+    symbol: string;
+    format?: "JSON" | "CSV";
+}
+interface PriceResponse {
+    price: string;
+}
+declare class MarketDataEndpoints {
+    private http;
+    constructor(http: HttpClient);
+    timeSeries(params: TimeSeriesParams): Promise<TimeSeriesResponse>;
+    quote(params: QuoteParams): Promise<QuoteResponse>;
+    price(params: PriceParams): Promise<PriceResponse>;
+}
+
+declare class TwelveData {
+    readonly marketData: MarketDataEndpoints;
+    private http;
+    constructor(config: TwelveDataConfig);
+}
+
+declare class TwelveDataError extends Error {
+    code: number;
+    status: "error";
+    constructor(message: string, code: number);
+}
+
+export { TwelveData, TwelveDataError };
+export type { Interval, PriceParams, PriceResponse, QuoteParams, QuoteResponse, TimeSeriesParams, TimeSeriesResponse, TimeSeriesValue, TwelveDataConfig };

package/dist/index.d.mts

@@ -0,0 +1,108 @@
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    constructor(apiKey: string, baseUrl: string, timeout: number);
+    get<T>(path: string, params?: object): Promise<T>;
+}
+
+type Interval = "1min" | "5min" | "15min" | "30min" | "45min" | "1h" | "2h" | "4h" | "1day" | "1week" | "1month";
+interface TwelveDataConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+
+interface TimeSeriesParams {
+    symbol: string;
+    interval: Interval;
+    outputsize?: number;
+    start_date?: string;
+    end_date?: string;
+    timezone?: string;
+    format?: "JSON" | "CSV";
+}
+interface TimeSeriesValue {
+    datetime: string;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    volume?: string;
+}
+interface TimeSeriesResponse {
+    meta: {
+        symbol: string;
+        interval: string;
+        currency: string;
+        exchange_timezone: string;
+        exchange: string;
+        mic_code: string;
+        type: string;
+    };
+    values: TimeSeriesValue[];
+    status: string;
+}
+interface QuoteParams {
+    symbol: string;
+    interval?: Interval;
+    eod?: boolean;
+    rolling_period?: number;
+}
+interface QuoteResponse {
+    symbol: string;
+    name: string;
+    exchange: string;
+    mic_code: string;
+    currency: string;
+    datetime: string;
+    timestamp: number;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    volume: string;
+    previous_close: string;
+    change: string;
+    percent_change: string;
+    average_volume: string;
+    is_market_open: boolean;
+    fifty_two_week: {
+        low: string;
+        high: string;
+        low_change: string;
+        high_change: string;
+        low_change_percent: string;
+        high_change_percent: string;
+        range: string;
+    };
+}
+interface PriceParams {
+    symbol: string;
+    format?: "JSON" | "CSV";
+}
+interface PriceResponse {
+    price: string;
+}
+declare class MarketDataEndpoints {
+    private http;
+    constructor(http: HttpClient);
+    timeSeries(params: TimeSeriesParams): Promise<TimeSeriesResponse>;
+    quote(params: QuoteParams): Promise<QuoteResponse>;
+    price(params: PriceParams): Promise<PriceResponse>;
+}
+
+declare class TwelveData {
+    readonly marketData: MarketDataEndpoints;
+    private http;
+    constructor(config: TwelveDataConfig);
+}
+
+declare class TwelveDataError extends Error {
+    code: number;
+    status: "error";
+    constructor(message: string, code: number);
+}
+
+export { TwelveData, TwelveDataError };
+export type { Interval, PriceParams, PriceResponse, QuoteParams, QuoteResponse, TimeSeriesParams, TimeSeriesResponse, TimeSeriesValue, TwelveDataConfig };

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+declare class HttpClient {
+    private baseUrl;
+    private apiKey;
+    private timeout;
+    constructor(apiKey: string, baseUrl: string, timeout: number);
+    get<T>(path: string, params?: object): Promise<T>;
+}
+
+type Interval = "1min" | "5min" | "15min" | "30min" | "45min" | "1h" | "2h" | "4h" | "1day" | "1week" | "1month";
+interface TwelveDataConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+
+interface TimeSeriesParams {
+    symbol: string;
+    interval: Interval;
+    outputsize?: number;
+    start_date?: string;
+    end_date?: string;
+    timezone?: string;
+    format?: "JSON" | "CSV";
+}
+interface TimeSeriesValue {
+    datetime: string;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    volume?: string;
+}
+interface TimeSeriesResponse {
+    meta: {
+        symbol: string;
+        interval: string;
+        currency: string;
+        exchange_timezone: string;
+        exchange: string;
+        mic_code: string;
+        type: string;
+    };
+    values: TimeSeriesValue[];
+    status: string;
+}
+interface QuoteParams {
+    symbol: string;
+    interval?: Interval;
+    eod?: boolean;
+    rolling_period?: number;
+}
+interface QuoteResponse {
+    symbol: string;
+    name: string;
+    exchange: string;
+    mic_code: string;
+    currency: string;
+    datetime: string;
+    timestamp: number;
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+    volume: string;
+    previous_close: string;
+    change: string;
+    percent_change: string;
+    average_volume: string;
+    is_market_open: boolean;
+    fifty_two_week: {
+        low: string;
+        high: string;
+        low_change: string;
+        high_change: string;
+        low_change_percent: string;
+        high_change_percent: string;
+        range: string;
+    };
+}
+interface PriceParams {
+    symbol: string;
+    format?: "JSON" | "CSV";
+}
+interface PriceResponse {
+    price: string;
+}
+declare class MarketDataEndpoints {
+    private http;
+    constructor(http: HttpClient);
+    timeSeries(params: TimeSeriesParams): Promise<TimeSeriesResponse>;
+    quote(params: QuoteParams): Promise<QuoteResponse>;
+    price(params: PriceParams): Promise<PriceResponse>;
+}
+
+declare class TwelveData {
+    readonly marketData: MarketDataEndpoints;
+    private http;
+    constructor(config: TwelveDataConfig);
+}
+
+declare class TwelveDataError extends Error {
+    code: number;
+    status: "error";
+    constructor(message: string, code: number);
+}
+
+export { TwelveData, TwelveDataError };
+export type { Interval, PriceParams, PriceResponse, QuoteParams, QuoteResponse, TimeSeriesParams, TimeSeriesResponse, TimeSeriesValue, TwelveDataConfig };

package/dist/index.mjs

@@ -0,0 +1,80 @@
+class MarketDataEndpoints {
+  constructor(http) {
+    this.http = http;
+  }
+  timeSeries(params) {
+    return this.http.get("/time_series", params);
+  }
+  quote(params) {
+    return this.http.get("/quote", params);
+  }
+  price(params) {
+    return this.http.get("/price", params);
+  }
+}
+
+class TwelveDataError extends Error {
+  code;
+  status;
+  constructor(message, code) {
+    super(message);
+    this.name = "TwelveDataError";
+    this.code = code;
+    this.status = "error";
+  }
+}
+
+class HttpClient {
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(apiKey, baseUrl, timeout) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+    this.timeout = timeout;
+  }
+  async get(path, params = {}) {
+    const url = new URL(path, this.baseUrl);
+    for (const [key, value] of Object.entries(
+      params
+    )) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let response;
+    try {
+      response = await fetch(url.toString(), {
+        headers: { Authorization: `apikey ${this.apiKey}` },
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+    const body = await response.json();
+    if (body.status === "error") {
+      throw new TwelveDataError(
+        body.message ?? "Unknown error",
+        body.code ?? response.status
+      );
+    }
+    return body;
+  }
+}
+
+class TwelveData {
+  marketData;
+  http;
+  constructor(config) {
+    this.http = new HttpClient(
+      config.apiKey,
+      config.baseUrl ?? "https://api.twelvedata.com",
+      config.timeout ?? 3e4
+    );
+    this.marketData = new MarketDataEndpoints(this.http);
+  }
+}
+
+export { TwelveData, TwelveDataError };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@stockfind/twelve-data",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "TypeScript SDK for the Twelve Data financial API",
+  "author": "Ru Chern CHONG <ruchern.chong@stockfind.app>",
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.2",
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.9.3",
+    "unbuild": "^3.6.1"
+  },
+  "lint-staged": {
+    "*": [
+      "biome check --write --no-errors-on-unmatched"
+    ]
+  },
+  "scripts": {
+    "build": "unbuild",
+    "check": "biome check",
+    "format": "biome check --write",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}