@2oolkit/kiwoom-cli 0.1.0 → 0.1.2

package/README.md

@@ -106,7 +106,25 @@ kiwoom-cli chart week  <코드>                             주봉 (ka10082)
 kiwoom-cli chart month <코드>                             월봉 (ka10083)
 kiwoom-cli chart year  <코드>                             년봉 (ka10094)
 ```
-모두 `-n, --count <n>`(행 수, 기본 50), `--raw`(수정주가 미적용) 지원.
+모두 `-n, --count <n>`(봉 개수, 기본 50), `--raw`(수정주가 미적용), `-p, --paginate`(강제 다중 페이지) 지원.
+
+**1회 요청당 최대 봉 개수 (per-request cap)** — 그 이상은 `cont-yn`/`next-key` 헤더로 **자동 페이지네이션**:
+
+| 차트 | 1회 최대 | `--count` 한도 |
+|---|---|---|
+| tick / min | 900 | 100,000 (자동 분할) |
+| day | 600 | 100,000 (자동 분할) |
+| week | 300 | 100,000 (자동 분할) |
+| month | 240 | 100,000 (자동 분할) |
+| year | 30 | 100,000 (자동 분할) |
+
+`--count`가 1회 최대를 넘으면 자동으로 여러 페이지를 받아 합칩니다(시간순 정렬·중복 제거는 API 순서를 그대로 유지). `-p/--paginate`로 강제할 수도 있습니다. `--count`는 양의 정수여야 하며 100,000으로 클램프됩니다.
+
+```bash
+kiwoom-cli chart day 005930 -n 600              # 한 페이지(최대) — 일봉 600개
+kiwoom-cli chart day 005930 -n 2000 -o json     # 자동 페이지네이션 — 일봉 ~2000개
+kiwoom-cli chart min 005930 -i 1 -n 2000 -o json # 1분봉 ~2000개 (여러 페이지)
+```
 
 ### `account` — 계좌
 ```
@@ -129,6 +147,7 @@ kiwoom-cli ranking volume                 당일 거래량 상위 (ka10030)
 kiwoom-cli ranking amount                 거래대금 상위 (ka10032)
 kiwoom-cli ranking surge                  거래량 급증 (ka10023)
 kiwoom-cli ranking prev-volume            전일 거래량 상위 (ka10031)
+kiwoom-cli ranking net-buy [옵션]         수급: 외국인·기관 순매수 상위 (ka90009)
 
 kiwoom-cli sector price [-m -c]   업종 현재가 (ka20001)
 kiwoom-cli sector stocks          업종 구성종목 (ka20002)
@@ -138,6 +157,9 @@ kiwoom-cli sector codes           업종 코드 목록 (ka10101)
 ```
 순위: `-m 000=전체/001=코스피/101=코스닥`, `-x 1=KRX/2=NXT/3=통합`.
 
+수급(`net-buy`, alias `supply`)은 한 번의 ka90009 호출로 외국인·기관 매매상위를 함께 반환합니다:
+`-b foreign|institution|both`(기본 both), `--side buy|sell`(기본 buy=순매수), `-n <1-50>`(기본 10), `-q 1=금액/2=수량`(기본 1), `-d YYYYMMDD`(기본 최신). 예: `kiwoom-cli ranking net-buy -b both -n 10`.
+
 ### `order` — ⚠ `real`에서는 실제 자금
 ```
 kiwoom-cli order buy  <코드> <수량> [-p 가격] [-t 유형] [-x KRX|NXT|SOR] [--credit] [-y]
@@ -176,7 +198,7 @@ kiwoom-cli order cancel 0000139 005930      # 잔량 전부 취소
 }
 ```
 
-도구: `get_stock_info`, `get_price`, `get_orderbook`, `get_daily_price`, `get_recent_trades`, `search_stocks`, `get_chart`, `get_balance`, `get_deposit`, `get_open_orders`, `get_executions`, `get_realized_pnl`, `get_ranking`, `get_sector`, `place_order`, `modify_order`, `cancel_order`.
+도구: `get_stock_info`, `get_price`, `get_orderbook`, `get_daily_price`, `get_recent_trades`, `search_stocks`, `get_chart`, `get_balance`, `get_deposit`, `get_open_orders`, `get_executions`, `get_realized_pnl`, `get_ranking`, `get_net_buy_ranking`, `get_sector`, `place_order`, `modify_order`, `cancel_order`.
 
 주문 도구는 **`confirm: true`를 넘기지 않으면 미리보기만 반환하고 아무것도 실행하지 않습니다** — 에이전트가 실수로 실주문을 낼 수 없습니다.
 

package/dist/index.js

@@ -89,6 +89,15 @@ var ORDER_TYPES = {
   "81": "\uC7A5\uB9C8\uAC10\uD6C4\uC2DC\uAC04\uC678"
 };
 var MARKET_ORDER_TYPES = /* @__PURE__ */ new Set(["3", "13", "23"]);
+var CHART_PER_PAGE_CAP = {
+  tick: 900,
+  minute: 900,
+  day: 600,
+  week: 300,
+  month: 240,
+  year: 30
+};
+var CHART_MAX_COUNT = 1e5;
 
 // src/config/store.ts
 var DEFAULT_CONFIG = { env: "real" };
@@ -438,7 +447,7 @@ var KiwoomClient = class {
    */
   async callEndpoint(def, body = {}, opts = {}) {
     if (opts.paginate && def.listKey) {
-      const data = await this.requestAll(def.apiId, def.path, body, def.listKey);
+      const data = await this.requestAll(def.apiId, def.path, body, def.listKey, opts.maxPages);
       return { data, contYn: false, nextKey: "" };
     }
     return this.request(def.apiId, def.path, body, {
@@ -448,9 +457,11 @@ var KiwoomClient = class {
   }
   /**
    * Fetch all pages of a TR, concatenating the array under `listKey`.
-   * Caps at `maxPages` to avoid runaway loops.
+   * Caps at `maxPages` to avoid runaway loops (default 100 — high enough for
+   * large chart pulls; callers pass a tighter bound when they know how many
+   * pages a target row count needs).
    */
-  async requestAll(apiId, path2, body, listKey, maxPages = 20) {
+  async requestAll(apiId, path2, body, listKey, maxPages = 100) {
     let page = await this.request(apiId, path2, body);
     const acc = Array.isArray(page.data[listKey]) ? [...page.data[listKey]] : [];
     let pages = 1;
@@ -840,6 +851,7 @@ var ENDPOINTS = {
   rankTradeAmount: { apiId: "ka10032", path: PATHS.rkinfo, korean: "\uAC70\uB798\uB300\uAE08\uC0C1\uC704\uC694\uCCAD", listKey: "trde_prica_upper" },
   rankVolumeSurge: { apiId: "ka10023", path: PATHS.rkinfo, korean: "\uAC70\uB798\uB7C9\uAE09\uC99D\uC694\uCCAD", listKey: "trde_qty_sdnin" },
   rankPrevVolume: { apiId: "ka10031", path: PATHS.rkinfo, korean: "\uC804\uC77C\uAC70\uB798\uB7C9\uC0C1\uC704\uC694\uCCAD", listKey: "pred_trde_qty_upper" },
+  rankForeignInst: { apiId: "ka90009", path: PATHS.rkinfo, korean: "\uC678\uAD6D\uC778\uAE30\uAD00\uB9E4\uB9E4\uC0C1\uC704\uC694\uCCAD", listKey: "frgnr_orgn_trde_upper" },
   // ── Sector / industry (업종) ───────────────────────────────────────────────
   sectorPrice: { apiId: "ka20001", path: PATHS.sect, korean: "\uC5C5\uC885\uD604\uC7AC\uAC00\uC694\uCCAD", listKey: "inds_cur_prc_tm" },
   sectorStocks: { apiId: "ka20002", path: PATHS.sect, korean: "\uC5C5\uC885\uBCC4\uC8FC\uAC00\uC694\uCCAD", listKey: "inds_stkpc" },
@@ -1254,81 +1266,102 @@ var CHART_ROW_FORMATTERS = {
   pred_pre: unpad,
   trde_tern_rt: unpad
 };
+var PER_PAGE_CAP = CHART_PER_PAGE_CAP;
+function parseCount(raw) {
+  const n = parseIntStrict(raw, "count");
+  if (n < 1) {
+    throw new ActionableError(`--count must be a positive integer (got ${n}).`);
+  }
+  return Math.min(n, CHART_MAX_COUNT);
+}
 function emitChart(data, ep, fmt, count) {
+  const all = Array.isArray(data[ep.listKey]) ? data[ep.listKey] : [];
+  const sliced = all.slice(0, count);
   if (fmt === "json") {
-    output(data, "json");
+    output({ ...data, [ep.listKey]: sliced }, "json");
     return;
   }
-  const all = Array.isArray(data[ep.listKey]) ? data[ep.listKey] : [];
-  if (all.length === 0) {
+  if (sliced.length === 0) {
     console.log("No data");
     return;
   }
   output(
-    all.slice(0, count).map((row) => formatFields(row, CHART_ROW_FORMATTERS)),
+    sliced.map((row) => formatFields(row, CHART_ROW_FORMATTERS)),
     "table"
   );
 }
 function registerChartCommands(program2) {
-  const chart = program2.command("chart").description("OHLC charts \u2014 tick / minute / daily / weekly / monthly / yearly");
-  async function runIntraday(ep, code, ticScope, options) {
+  const chart = program2.command("chart").description(
+    "OHLC charts \u2014 tick / minute / daily / weekly / monthly / yearly. Per-request caps: tick/min 900, day 600, week 300, month 240, year 30. --count beyond the cap auto-paginates via cont-yn/next-key."
+  );
+  function planFetch(type, count, paginate) {
+    const cap = PER_PAGE_CAP[type];
+    const active = paginate || count > cap;
+    const maxPages = active ? Math.max(1, Math.ceil(count / cap)) : 1;
+    return { paginate: active, maxPages };
+  }
+  async function runIntraday(ep, type, code, ticScope, options) {
     const client = createClient();
     const stk = normalizeStockCode(code);
-    const { data } = await client.callEndpoint(ep, {
-      stk_cd: stk,
-      tic_scope: ticScope,
-      upd_stkpc_tp: options.raw ? "0" : "1"
-    });
-    emitChart(data, ep, getOutputFormat(options), parseIntStrict(options.count, "count"));
+    const count = parseCount(options.count);
+    const plan = planFetch(type, count, !!options.paginate);
+    const { data } = await client.callEndpoint(
+      ep,
+      { stk_cd: stk, tic_scope: ticScope, upd_stkpc_tp: options.raw ? "0" : "1" },
+      { paginate: plan.paginate, maxPages: plan.maxPages }
+    );
+    emitChart(data, ep, getOutputFormat(options), count);
   }
-  async function runPeriod(ep, code, baseDt, options) {
+  async function runPeriod(ep, type, code, baseDt, options) {
     const client = createClient();
     const stk = normalizeStockCode(code);
-    const { data } = await client.callEndpoint(ep, {
-      stk_cd: stk,
-      base_dt: baseDt,
-      upd_stkpc_tp: options.raw ? "0" : "1"
-    });
-    emitChart(data, ep, getOutputFormat(options), parseIntStrict(options.count, "count"));
+    const count = parseCount(options.count);
+    const plan = planFetch(type, count, !!options.paginate);
+    const { data } = await client.callEndpoint(
+      ep,
+      { stk_cd: stk, base_dt: baseDt, upd_stkpc_tp: options.raw ? "0" : "1" },
+      { paginate: plan.paginate, maxPages: plan.maxPages }
+    );
+    emitChart(data, ep, getOutputFormat(options), count);
   }
-  chart.command("tick <code>").description("Tick chart (ka10079)").option("-s, --scope <n>", "Ticks per candle (1/3/5/10/30)", "1").option("-n, --count <n>", "Number of candles to display", "50").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
+  chart.command("tick <code>").description(`Tick chart (ka10079) \u2014 up to ${PER_PAGE_CAP.tick} candles/request, auto-paginates beyond that`).option("-s, --scope <n>", "Ticks per candle (1/3/5/10/30)", "1").option("-n, --count <n>", "Number of candles (auto-paginates when > 900)", "50").option("-p, --paginate", "Force fetching multiple pages (cont-yn/next-key)").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
     try {
-      await runIntraday(ENDPOINTS.tickChart, code, options.scope, options);
+      await runIntraday(ENDPOINTS.tickChart, "tick", code, options.scope, options);
     } catch (err) {
       handleError(err);
     }
   });
-  chart.command("min <code>").alias("minute").description("Minute chart (ka10080)").option("-i, --interval <n>", "Minutes per candle (1/3/5/10/15/30/45/60)", "1").option("-n, --count <n>", "Number of candles to display", "50").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
+  chart.command("min <code>").alias("minute").description(`Minute chart (ka10080) \u2014 up to ${PER_PAGE_CAP.minute} candles/request, auto-paginates beyond that`).option("-i, --interval <n>", "Minutes per candle (1/3/5/10/15/30/45/60)", "1").option("-n, --count <n>", "Number of candles (auto-paginates when > 900)", "50").option("-p, --paginate", "Force fetching multiple pages (cont-yn/next-key)").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
     try {
-      await runIntraday(ENDPOINTS.minuteChart, code, options.interval, options);
+      await runIntraday(ENDPOINTS.minuteChart, "minute", code, options.interval, options);
     } catch (err) {
       handleError(err);
     }
   });
-  chart.command("day <code>").alias("daily").description("Daily chart (ka10081)").option("-d, --date <yyyymmdd>", "Base date (most recent candle)", todayKst()).option("-n, --count <n>", "Number of candles to display", "50").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
+  chart.command("day <code>").alias("daily").description(`Daily chart (ka10081) \u2014 up to ${PER_PAGE_CAP.day} candles/request, auto-paginates beyond that`).option("-d, --date <yyyymmdd>", "Base date (most recent candle)", todayKst()).option("-n, --count <n>", "Number of candles (auto-paginates when > 600)", "50").option("-p, --paginate", "Force fetching multiple pages (cont-yn/next-key)").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
     try {
-      await runPeriod(ENDPOINTS.dailyChart, code, options.date, options);
+      await runPeriod(ENDPOINTS.dailyChart, "day", code, options.date, options);
     } catch (err) {
       handleError(err);
     }
   });
-  chart.command("week <code>").description("Weekly chart (ka10082)").option("-d, --date <yyyymmdd>", "Base date (most recent candle)", todayKst()).option("-n, --count <n>", "Number of candles to display", "50").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
+  chart.command("week <code>").description(`Weekly chart (ka10082) \u2014 up to ${PER_PAGE_CAP.week} candles/request, auto-paginates beyond that`).option("-d, --date <yyyymmdd>", "Base date (most recent candle)", todayKst()).option("-n, --count <n>", "Number of candles (auto-paginates when > 300)", "50").option("-p, --paginate", "Force fetching multiple pages (cont-yn/next-key)").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
     try {
-      await runPeriod(ENDPOINTS.weeklyChart, code, options.date, options);
+      await runPeriod(ENDPOINTS.weeklyChart, "week", code, options.date, options);
     } catch (err) {
       handleError(err);
     }
   });
-  chart.command("month <code>").description("Monthly chart (ka10083)").option("-d, --date <yyyymmdd>", "Base date (most recent candle)", todayKst()).option("-n, --count <n>", "Number of candles to display", "50").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
+  chart.command("month <code>").description(`Monthly chart (ka10083) \u2014 up to ${PER_PAGE_CAP.month} candles/request, auto-paginates beyond that`).option("-d, --date <yyyymmdd>", "Base date (most recent candle)", todayKst()).option("-n, --count <n>", "Number of candles (auto-paginates when > 240)", "50").option("-p, --paginate", "Force fetching multiple pages (cont-yn/next-key)").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
     try {
-      await runPeriod(ENDPOINTS.monthlyChart, code, options.date, options);
+      await runPeriod(ENDPOINTS.monthlyChart, "month", code, options.date, options);
     } catch (err) {
       handleError(err);
     }
   });
-  chart.command("year <code>").description("Yearly chart (ka10094)").option("-d, --date <yyyymmdd>", "Base date (most recent candle)", todayKst()).option("-n, --count <n>", "Number of candles to display", "50").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
+  chart.command("year <code>").description(`Yearly chart (ka10094) \u2014 up to ${PER_PAGE_CAP.year} candles/request, auto-paginates beyond that`).option("-d, --date <yyyymmdd>", "Base date (most recent candle)", todayKst()).option("-n, --count <n>", "Number of candles (auto-paginates when > 30)", "50").option("-p, --paginate", "Force fetching multiple pages (cont-yn/next-key)").option("--raw", "Unadjusted (\uC218\uC815\uC8FC\uAC00 \uBBF8\uBC18\uC601) prices").option("-o, --output <format>", "Output format (table/json)", "table").action(async (code, options) => {
     try {
-      await runPeriod(ENDPOINTS.yearlyChart, code, options.date, options);
+      await runPeriod(ENDPOINTS.yearlyChart, "year", code, options.date, options);
     } catch (err) {
       handleError(err);
     }
@@ -1756,6 +1789,21 @@ ${side.toUpperCase()} ${credit ? "(credit) " : ""}${stk}  qty ${qty}  ${priceLab
   await submit(def, body, options);
 }
 
+// src/utils/ranking.ts
+var NETTRADE_FIELDS = {
+  foreign: { buy: "for_netprps", sell: "for_netslmt" },
+  institution: { buy: "orgn_netprps", sell: "orgn_netslmt" }
+};
+function extractNetTrade(rows, prefix, n) {
+  return rows.slice(0, n).map((r, i) => ({
+    rank: i + 1,
+    code: r[`${prefix}_stk_cd`],
+    name: r[`${prefix}_stk_nm`],
+    \uAE08\uC561: won(unpad(r[`${prefix}_amt`] ?? "")),
+    \uC218\uB7C9: won(unpad(r[`${prefix}_qty`] ?? ""))
+  })).filter((x) => x.code);
+}
+
 // src/commands/ranking.ts
 function formatRankRow(row) {
   return formatFields(row, {
@@ -1857,6 +1905,45 @@ function registerRankingCommands(program2) {
       handleError(err);
     }
   });
+  ranking.command("net-buy").alias("supply").description("Foreign/institution net-buy \uC218\uAE09 ranking (ka90009)").option("-b, --by <foreign|institution|both>", "Investor: foreign=\uC678\uAD6D\uC778, institution=\uAE30\uAD00, both", "both").option("--side <buy|sell>", "buy=\uC21C\uB9E4\uC218, sell=\uC21C\uB9E4\uB3C4", "buy").option("-m, --market <000|001|101>", "Market: 000=all, 001=KOSPI, 101=KOSDAQ", "000").option("-x, --exchange <1|2|3>", "Exchange: 1=KRX, 2=NXT, 3=unified", "1").option("-n, --count <n>", "Top N (1-50)", "10").option("-q, --rank-by <1|2>", "Rank by 1=amount(\uAE08\uC561), 2=quantity(\uC218\uB7C9)", "1").option("-d, --date <YYYYMMDD>", "Query date (default: latest)").option("-o, --output <format>", "Output format (table/json)", "table").action(async (options) => {
+    try {
+      const side = options.side === "sell" ? "sell" : "buy";
+      const by = ["foreign", "institution", "both"].includes(options.by) ? options.by : "both";
+      const investors = by === "both" ? ["foreign", "institution"] : [by];
+      const n = Math.min(Math.max(parseInt(String(options.count), 10) || 10, 1), 50);
+      const client = createClient();
+      const { data } = await client.callEndpoint(ENDPOINTS.rankForeignInst, {
+        mrkt_tp: options.market,
+        amt_qty_tp: options.rankBy === "2" ? "2" : "1",
+        qry_dt_tp: options.date ? "1" : "0",
+        date: options.date || "",
+        stex_tp: options.exchange
+      });
+      const rows = Array.isArray(data?.[ENDPOINTS.rankForeignInst.listKey]) ? data[ENDPOINTS.rankForeignInst.listKey] : [];
+      const fmt = getOutputFormat(options);
+      const sideKo = side === "buy" ? "\uC21C\uB9E4\uC218" : "\uC21C\uB9E4\uB3C4";
+      const labelKo = { foreign: "\uC678\uAD6D\uC778", institution: "\uAE30\uAD00" };
+      if (fmt === "json") {
+        const result = {
+          side,
+          rankBy: options.rankBy === "2" ? "quantity" : "amount"
+        };
+        for (const inv of investors) {
+          result[inv] = extractNetTrade(rows, NETTRADE_FIELDS[inv][side], n);
+        }
+        output(result, "json");
+        return;
+      }
+      for (const inv of investors) {
+        const list = extractNetTrade(rows, NETTRADE_FIELDS[inv][side], n);
+        console.log(`
+${labelKo[inv]} ${sideKo} TOP${n} (${options.rankBy === "2" ? "\uC218\uB7C9" : "\uAE08\uC561"} \uAE30\uC900)`);
+        output(list, "table");
+      }
+    } catch (err) {
+      handleError(err);
+    }
+  });
 }
 
 // src/commands/sector.ts