dart-fss-cli 0.4.4 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +56 -61
  2. package/dist/bin.js +1 -1
  3. package/dist/{chunk-537OSLFG.js → chunk-UHR5UNEO.js} +6 -4
  4. package/dist/cli.js +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -3,131 +3,126 @@
3
3
  [![npm version](https://img.shields.io/npm/v/dart-fss-cli)](https://www.npmjs.com/package/dart-fss-cli)
4
4
  [![license](https://img.shields.io/npm/l/dart-fss-cli)](LICENSE)
5
5
 
6
- 금융감독원 [DART Open API](https://opendart.fss.or.kr)의 **83개 전체 엔드포인트**를 커맨드라인에서 사용할 수 있는 CLI.
6
+ CLI for the Korea FSS [DART Open API](https://opendart.fss.or.kr) (Electronic Disclosure System).
7
7
 
8
- 사람이 직접 쓰기에도, AI 에이전트(Claude Code 등)에게 시키기에도 좋게 설계했습니다.
8
+ Access all **83 DART API endpoints** from the command line. Designed for both humans and AI agents (Claude Code, etc.).
9
9
 
10
- **[Demo & 사용 예시](DEMO.md)** | **[AI 에이전트 연동 가이드](AGENTS.md)** | **[한국어 가이드](docs/ko.md)**
10
+ **[Demo & Examples](DEMO.md)** | **[Agent Integration Guide](AGENTS.md)** | **[한국어 가이드](docs/ko.md)**
11
11
 
12
- ## 설치
12
+ ## Install
13
13
 
14
14
  ```bash
15
15
  npx dart-fss-cli --help
16
16
  ```
17
17
 
18
- 설치 없이 바로 실행됩니다. 글로벌 설치를 원하면:
18
+ Runs instantly without installation. For global install:
19
19
 
20
20
  ```bash
21
21
  npm install -g dart-fss-cli
22
22
  ```
23
23
 
24
- ## 사전 준비
24
+ ## Setup
25
25
 
26
- [DART Open API](https://opendart.fss.or.kr)에서 API 키를 발급받으세요.
26
+ Get an API key from [DART Open API](https://opendart.fss.or.kr).
27
27
 
28
28
  ```bash
29
29
  export DART_API_KEY=your_api_key_here
30
30
  ```
31
31
 
32
- ## 사용 예시
32
+ ## Usage
33
33
 
34
34
  ```bash
35
- # 회사 검색
35
+ # Look up a company (Korean name → corp_code)
36
36
  dart-fss lookup "삼성전자"
37
37
 
38
- # 기업 개황
38
+ # Company overview
39
39
  dart-fss disclosure company --corp "삼성전자" --pretty
40
40
 
41
- # 공시 검색
41
+ # Search filings
42
42
  dart-fss disclosure list --corp "카카오" --from 20250101 --to 20260101
43
43
 
44
- # 직원 현황 (필요한 필드만)
44
+ # Employee status (filtered fields)
45
45
  dart-fss report employee --corp "삼성전자" --year 2025 --quarter annual \
46
46
  --fields "sexdstn,fo_bbm,sm,avrg_cnwk_sdytrn"
47
47
 
48
- # 재무제표
48
+ # Financial statements
49
49
  dart-fss financial single-account --corp "SK하이닉스" --year 2025 --quarter annual --pretty
50
50
 
51
- # 대량보유 상황
51
+ # Major shareholding
52
52
  dart-fss equity major-stock --corp "네이버"
53
53
 
54
- # 전환사채 발행 이력
55
- dart-fss major convertible-bond --corp "카카오" --from 20230101 --to 20251231
56
-
57
- # 결과를 파일로 저장
54
+ # Save to file
58
55
  dart-fss disclosure company --corp "삼성전자" --output result.json
59
56
  ```
60
57
 
61
- > 한글 회사명을 그대로 입력하면 됩니다. 영문 등록 회사(NAVER, LG 등)도 한글로 검색 가능합니다.
62
-
63
- ## 커맨드 그룹
58
+ > Korean company names work directly. Companies registered with English names (NAVER, LG, etc.) can also be found using Korean input.
64
59
 
65
- | 커맨드 | 설명 | API 수 |
66
- |--------|------|--------|
67
- | `disclosure` | 공시정보 (공시 검색, 기업 개황 등) | 4 |
68
- | `report` | 정기보고서 (직원현황, 임원현황, 배당 등) | 28 |
69
- | `financial` | 재무정보 (재무제표, 재무지표, XBRL) | 7 |
70
- | `equity` | 지분공시 (대량보유, 임원 주요주주) | 2 |
71
- | `major` | 주요사항보고서 (증자/감자, M&A 등) | 36 |
72
- | `securities` | 증권신고서 (지분증권, 채무증권 등) | 6 |
60
+ ## Command Groups
73
61
 
74
- ## 주요 옵션
62
+ | Command | Description | APIs |
63
+ |---------|-------------|------|
64
+ | `disclosure` | Filings search, company overview, documents | 4 |
65
+ | `report` | Periodic reports (employees, executives, dividends, audit) | 28 |
66
+ | `financial` | Financial statements, indices, XBRL | 7 |
67
+ | `equity` | Equity disclosure (major holdings, executive ownership) | 2 |
68
+ | `major` | Major events (capital changes, bonds, M&A, lawsuits) | 36 |
69
+ | `securities` | Securities registration statements | 6 |
75
70
 
76
- | 옵션 | 설명 |
77
- |------|------|
78
- | `--pretty` | JSON 보기 좋게 출력 |
79
- | `--fields <f1,f2>` | 응답 필드 필터링 (context window 절약) |
80
- | `--dry-run` | API 호출 없이 파라미터 검증 |
81
- | `--output <file>` | 결과를 파일로 저장 |
82
- | `--json <params>` | raw API 파라미터를 JSON으로 직접 전달 |
83
- | `--api-key <key>` | API 키 (기본: `DART_API_KEY` 환경변수) |
71
+ ## Options
84
72
 
85
- ## 분기 코드
73
+ | Option | Description |
74
+ |--------|-------------|
75
+ | `--pretty` | Pretty-print JSON output |
76
+ | `--fields <f1,f2>` | Filter response fields (saves context window for agents) |
77
+ | `--dry-run` | Validate parameters without calling the API |
78
+ | `--output <file>` | Save result to file |
79
+ | `--json <params>` | Pass raw API parameters as JSON |
80
+ | `--api-key <key>` | DART API key (default: `DART_API_KEY` env) |
86
81
 
87
- `--quarter` 옵션에 사용하는 값:
82
+ ## Quarter Codes
88
83
 
89
- | 값 | 의미 |
90
- |------|------|
91
- | `q1` | 1분기 |
92
- | `half` | 반기 |
93
- | `q3` | 3분기 |
94
- | `annual` | 사업보고서 |
84
+ | Value | Meaning |
85
+ |-------|---------|
86
+ | `q1` | Q1 report |
87
+ | `half` | Semi-annual |
88
+ | `q3` | Q3 report |
89
+ | `annual` | Annual report |
95
90
 
96
- ## AI 에이전트 연동
91
+ ## Agent Integration
97
92
 
98
- dart-fss-cli는 AI 에이전트가 스스로 API를 탐색하고 호출할 수 있도록 설계되었습니다.
93
+ Built for AI agents to self-discover and call endpoints:
99
94
 
100
95
  ```bash
101
- # 엔드포인트 탐색 (파이프 시 자동 JSON)
96
+ # Discover endpoints (auto-JSON when piped)
102
97
  dart-fss endpoints --json-output
103
98
 
104
- # 파라미터 스키마 조회
99
+ # Inspect parameter schema
105
100
  dart-fss schema dividend
106
101
 
107
- # API 호출 없이 검증
102
+ # Validate without API call
108
103
  dart-fss report dividend --corp "삼성전자" --year 2025 --quarter annual --dry-run
109
104
 
110
- # 에러도 JSON
105
+ # Structured JSON errors
111
106
  # {"error":true,"code":"013","description":"No data found","message":"..."}
112
107
  ```
113
108
 
114
- Claude Code의 `CLAUDE.md`에 추가하면 자연어로 DART 데이터를 조회할 수 있습니다:
109
+ Add to your `CLAUDE.md` to use as a tool:
115
110
 
116
111
  ```markdown
117
112
  ## Available Tools
118
113
 
119
- dart-fss-cli가 설치되어 있습니다. 한국 기업의 공시 정보가 필요하면 사용하세요.
114
+ dart-fss-cli is installed. Use it for Korean corporate disclosure data.
120
115
 
121
- - `dart-fss endpoints --json-output` — 사용 가능한 API 목록
122
- - `dart-fss schema <endpoint>` — API 파라미터 확인
123
- - `dart-fss lookup <회사명>` — 회사 코드 검색
124
- - 항상 `--fields`로 필요한 필드만 요청하세요
125
- - 예시: `dart-fss report employee --corp "삼성전자" --year 2025 --quarter annual --fields "corp_name,sm"`
116
+ - `dart-fss endpoints --json-output` — list available APIs
117
+ - `dart-fss schema <endpoint>` — get parameter schema
118
+ - `dart-fss lookup <name>` — search company by name
119
+ - Always use `--fields` to limit response size
120
+ - Example: `dart-fss report employee --corp "삼성전자" --year 2025 --quarter annual --fields "corp_name,sm"`
126
121
  ```
127
122
 
128
- 자세한 내용은 [AGENTS.md](AGENTS.md)와 [DEMO.md](DEMO.md)를 참고하세요.
123
+ See [AGENTS.md](AGENTS.md) and [DEMO.md](DEMO.md) for detailed examples.
129
124
 
130
- ## 프로그래밍 방식 사용
125
+ ## Programmatic Usage
131
126
 
132
127
  ```typescript
133
128
  import { createDartProgram } from 'dart-fss-cli';
package/dist/bin.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  createDartProgram,
4
4
  formatErrorJson
5
- } from "./chunk-537OSLFG.js";
5
+ } from "./chunk-UHR5UNEO.js";
6
6
 
7
7
  // src/bin.ts
8
8
  createDartProgram().parseAsync(process.argv).catch((err) => {
package/dist/{chunk-537OSLFG.js → chunk-UHR5UNEO.js} RENAMED
@@ -2,11 +2,12 @@
2
2
  import { Command } from "commander";
3
3
 
4
4
  // src/config.ts
5
- import { homedir } from "os";
5
+ import { homedir as homedir2 } from "os";
6
6
  import { join as join2 } from "path";
7
7
 
8
8
  // src/env.ts
9
9
  import { existsSync, readFileSync } from "fs";
10
+ import { homedir } from "os";
10
11
  import { join, resolve } from "path";
11
12
  var loaded = false;
12
13
  function loadEnv() {
@@ -15,7 +16,8 @@ function loadEnv() {
15
16
  const candidates = [
16
17
  process.cwd(),
17
18
  resolve(process.cwd(), ".."),
18
- resolve(import.meta.dirname, "..")
19
+ resolve(import.meta.dirname, ".."),
20
+ join(homedir(), ".dart-fss")
19
21
  ];
20
22
  for (const base of candidates) {
21
23
  const envPath = join(base, ".env");
@@ -40,7 +42,7 @@ function loadEnv() {
40
42
  // src/config.ts
41
43
  loadEnv();
42
44
  var DART_BASE_URL = "https://opendart.fss.or.kr/api/";
43
- var CACHE_DIR = join2(homedir(), ".dart-fss");
45
+ var CACHE_DIR = join2(homedir2(), ".dart-fss");
44
46
  var CORP_CODE_CACHE_PATH = join2(CACHE_DIR, "corp-codes.json");
45
47
  var CORP_CODE_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1e3;
46
48
  function getApiKey(optionKey) {
@@ -1664,7 +1666,7 @@ function createDartProgram() {
1664
1666
  const program = new Command();
1665
1667
  program.name("dart-fss").description(
1666
1668
  'DART Open API CLI \u2014 access Korea Financial Supervisory Service (FSS) electronic disclosure system.\nProvides 83 API endpoints for company filings, financial statements, equity disclosures, and more.\nAuthentication: set DART_API_KEY env var or pass --api-key. Get a key at https://opendart.fss.or.kr\nCompanies are identified by 8-digit corp_code or company name. Use "dart-fss lookup <name>" to find corp_code.\nOutput is JSON by default (compact single-line). Use --pretty for formatted output.\nRate limit: approximately 20,000 requests per day per API key.'
1667
- ).version("0.4.4").option("--api-key <key>", "DART API key (default: DART_API_KEY env). Get one at https://opendart.fss.or.kr").option("--pretty", "Pretty-print JSON output (default: compact single-line JSON)").option("--output <file>", "Save result to file instead of stdout").option("--json <params>", "Pass raw API parameters as JSON string, bypassing flag parsing").option("--fields <f1,f2,...>", "Comma-separated field names to include in output (reduces response size for agents)").option("--dry-run", "Validate parameters and print the resolved API request without calling the API");
1669
+ ).version("0.4.6").option("--api-key <key>", "DART API key (default: DART_API_KEY env). Get one at https://opendart.fss.or.kr").option("--pretty", "Pretty-print JSON output (default: compact single-line JSON)").option("--output <file>", "Save result to file instead of stdout").option("--json <params>", "Pass raw API parameters as JSON string, bypassing flag parsing").option("--fields <f1,f2,...>", "Comma-separated field names to include in output (reduces response size for agents)").option("--dry-run", "Validate parameters and print the resolved API request without calling the API");
1668
1670
  registerDisclosureCommands(program);
1669
1671
  registerPeriodicReportCommands(program);
1670
1672
  registerFinancialCommands(program);
package/dist/cli.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  createDartProgram
3
- } from "./chunk-537OSLFG.js";
3
+ } from "./chunk-UHR5UNEO.js";
4
4
  export {
5
5
  createDartProgram
6
6
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dart-fss-cli",
3
- "version": "0.4.4",
3
+ "version": "0.4.6",
4
4
  "description": "DART (금융감독원 전자공시) Open API CLI",
5
5
  "type": "module",
6
6
  "bin": {