dart-fss-cli 0.4.6 → 0.4.8

package/dist/bin.js

@@ -2,7 +2,7 @@
 import {
   createDartProgram,
   formatErrorJson
-} from "./chunk-UHR5UNEO.js";
+} from "./chunk-HYSOUXSY.js";
 
 // src/bin.ts
 createDartProgram().parseAsync(process.argv).catch((err) => {

package/dist/{chunk-UHR5UNEO.js → chunk-HYSOUXSY.js}

@@ -1173,11 +1173,11 @@ function getGlobalOpts(cmd) {
 }
 function registerDisclosureCommands(program) {
   const group = program.command("disclosure").description(
-    'DS001: Disclosure info \u2014 search filings, company overview, original documents, corp codes.\nUse "disclosure list" to search filings by company/date/type.\nUse "disclosure company" to get company profile (CEO, address, industry code).'
+    'DS001: Disclosure info \u2014 search filings, company overview, original documents, corp codes.\n\nExamples:\n  dart-fss disclosure company --corp "\uC0BC\uC131\uC804\uC790" --pretty\n  dart-fss disclosure list --corp "\uCE74\uCE74\uC624" --from 20250101 --to 20251231'
   );
   group.command("list").description(
     "Search DART disclosure filings. Returns paginated results with report name, filing date, receipt number.\nWithout --corp, searches ALL companies (date range limited to 3 months).\nWith --corp, searches specific company with no date limit.\nDisclosure types: A=Regular, B=Major events, C=Issuance, D=Equity, E=Other, F=Audit, G=Fund, H=ABS, I=Exchange, J=FTC"
-  ).option("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').option("--from <YYYYMMDD>", "Start date in YYYYMMDD format (e.g. 20240101)").option("--to <YYYYMMDD>", "End date in YYYYMMDD format (e.g. 20241231)").option("--type <code>", "Disclosure type: A=Regular, B=Major events, C=Issuance, D=Equity, E=Other, F=Audit, G=Fund, H=ABS, I=Exchange, J=FTC").option("--corp-cls <cls>", "Corp class filter: Y=KOSPI, K=KOSDAQ, N=KONEX, E=Other").option("--page <n>", "Page number, starting from 1 (default: 1)", "1").option("--count <n>", "Items per page, 1-100 (default: 10)", "10").action(async (opts) => {
+  ).option("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').option("--from <YYYYMMDD>", "Start date in YYYYMMDD format (e.g. 20240101)").option("--to <YYYYMMDD>", "End date in YYYYMMDD format (e.g. 20241231)").option("--type <code>", "Disclosure type: A=Regular, B=Major events, C=Issuance, D=Equity, E=Other, F=Audit, G=Fund, H=ABS, I=Exchange, J=FTC").option("--corp-cls <cls>", "Corp class filter: Y=KOSPI, K=KOSDAQ, N=KONEX, E=Other").option("--page <n>", "Page number, starting from 1 (default: 1)", "1").option("--count <n>", "Items per page, 1-100 (default: 10)", "10").addHelpText("after", '\nExamples:\n  dart-fss disclosure list --corp "\uC0BC\uC131\uC804\uC790" --from 20250101 --to 20251231 --pretty\n  dart-fss disclosure list --from 20250101 --to 20250131 --count 20').action(async (opts) => {
     const globalOpts = getGlobalOpts(group);
     const apiKey = getApiKey(globalOpts.apiKey);
     if (globalOpts.json) {
@@ -1203,7 +1203,7 @@ function registerDisclosureCommands(program) {
   });
   group.command("company").description(
     'Get company profile from DART. Returns corp name, CEO, address, stock code, industry code, incorporation date, fiscal month.\nAccepts company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code.'
-  ).requiredOption("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').action(async (opts) => {
+  ).requiredOption("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').addHelpText("after", '\nExamples:\n  dart-fss disclosure company --corp "\uC0BC\uC131\uC804\uC790" --pretty\n  dart-fss disclosure company --corp 00126380 --fields "corp_name,ceo_nm,adres"').action(async (opts) => {
     const globalOpts = getGlobalOpts(group);
     const apiKey = getApiKey(globalOpts.apiKey);
     if (globalOpts.json) {
@@ -1289,13 +1289,16 @@ function getGlobalOpts2(cmd) {
 }
 function registerPeriodicReportCommands(program) {
   const group = program.command("report").description(
-    "DS002: Periodic report key information \u2014 28 APIs extracting data from annual/quarterly reports.\nCovers: capital changes, dividends, treasury stock, shareholders, executives, employees,\ncompensation, debt securities, audit info, outside directors, investments, fund usage.\nData available from 2015 onward."
+    'DS002: Periodic report key information \u2014 28 APIs extracting data from annual/quarterly reports.\nCovers: capital changes, dividends, treasury stock, shareholders, executives, employees,\ncompensation, debt securities, audit info, outside directors, investments, fund usage.\nData available from 2015 onward.\n\nAll subcommands require: --corp <name> --year <YYYY> --quarter <q1|half|q3|annual>\n\nExamples:\n  dart-fss report employee --corp "\uC0BC\uC131\uC804\uC790" --year 2025 --quarter annual --pretty\n  dart-fss report dividend --corp "\uCE74\uCE74\uC624" --year 2025 --quarter annual\n  dart-fss report exec-pay-individual --corp "\uB124\uC774\uBC84" --year 2025 --quarter annual --fields "nm,ofcps,mendng_totamt"'
   );
   const endpoints = (REGISTRY_BY_GROUP.get("report") || []).filter(
     (ep) => ep.pattern === "periodic"
   );
   for (const ep of endpoints) {
-    group.command(ep.cliName).description(ep.summary).requiredOption("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').requiredOption("--year <YYYY>", "Business year in YYYY format (e.g. 2024). Data from 2015 onward").requiredOption("--quarter <q1|half|q3|annual>", "Report quarter: q1 (Q1), half (semi-annual), q3 (Q3), annual (full year)").action(async (opts) => {
+    group.command(ep.cliName).description(ep.summary).requiredOption("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').requiredOption("--year <YYYY>", "Business year in YYYY format (e.g. 2024). Data from 2015 onward").requiredOption("--quarter <q1|half|q3|annual>", "Report quarter: q1 (Q1), half (semi-annual), q3 (Q3), annual (full year)").addHelpText("after", `
+Examples:
+  dart-fss report ${ep.cliName} --corp "\uC0BC\uC131\uC804\uC790" --year 2025 --quarter annual --pretty
+  dart-fss report ${ep.cliName} --corp "\uC0BC\uC131\uC804\uC790" --year 2025 --quarter annual --fields "corp_name,nm"`).action(async (opts) => {
       const globalOpts = getGlobalOpts2(group);
       const apiKey = getApiKey(globalOpts.apiKey);
       if (globalOpts.json) {
@@ -1326,7 +1329,7 @@ function getGlobalOpts3(cmd) {
 }
 function registerFinancialCommands(program) {
   const group = program.command("financial").description(
-    "DS003: Financial data \u2014 statements, indices, and XBRL for listed companies (KOSPI/KOSDAQ).\nIncludes key accounts (assets, liabilities, revenue), full financial statements,\nfinancial indices (profitability, stability, growth, activity), and XBRL taxonomy."
+    'DS003: Financial data \u2014 statements, indices, and XBRL for listed companies (KOSPI/KOSDAQ).\nIncludes key accounts (assets, liabilities, revenue), full financial statements,\nfinancial indices (profitability, stability, growth, activity), and XBRL taxonomy.\n\nMost subcommands require: --corp <name> --year <YYYY> --quarter <q1|half|q3|annual>\n\nExamples:\n  dart-fss financial single-account --corp "\uC0BC\uC131\uC804\uC790" --year 2025 --quarter annual --pretty\n  dart-fss financial full-statement --corp "SK\uD558\uC774\uB2C9\uC2A4" --year 2025 --quarter annual --fs-div CFS'
   );
   const endpoints = REGISTRY_BY_GROUP.get("financial") || [];
   for (const ep of endpoints) {
@@ -1445,13 +1448,16 @@ function getGlobalOpts4(cmd) {
 }
 function registerEquityDisclosureCommands(program) {
   const group = program.command("equity").description(
-    'DS004: Equity disclosure \u2014 major shareholding reports and executive/major shareholder ownership.\nUse "equity major-stock" for large shareholding (5%+ ownership) status reports.\nUse "equity executive-stock" for executive and major shareholder ownership reports.'
+    'DS004: Equity disclosure \u2014 major shareholding reports and executive/major shareholder ownership.\n\nAll subcommands require: --corp <name>\n\nExamples:\n  dart-fss equity major-stock --corp "\uC0BC\uC131\uC804\uC790" --pretty\n  dart-fss equity executive-stock --corp "\uCE74\uCE74\uC624"'
   );
   const endpoints = (REGISTRY_BY_GROUP.get("equity") || []).filter(
     (ep) => ep.pattern === "corpOnly"
   );
   for (const ep of endpoints) {
-    group.command(ep.cliName).description(ep.summary).requiredOption("--corp <name-or-code>", "Company name or corp_code").action(async (opts) => {
+    group.command(ep.cliName).description(ep.summary).requiredOption("--corp <name-or-code>", "Company name or corp_code").addHelpText("after", `
+Examples:
+  dart-fss equity ${ep.cliName} --corp "\uC0BC\uC131\uC804\uC790" --pretty
+  dart-fss equity ${ep.cliName} --corp "\uC0BC\uC131\uC804\uC790" --fields "repror,stkqy,stkrt"`).action(async (opts) => {
       const globalOpts = getGlobalOpts4(group);
       const apiKey = getApiKey(globalOpts.apiKey);
       if (globalOpts.json) {
@@ -1478,13 +1484,16 @@ function getGlobalOpts5(cmd) {
 }
 function registerMajorReportCommands(program) {
   const group = program.command("major").description(
-    "DS005: Major event reports \u2014 36 APIs for significant corporate events.\nCovers: capital increases/reductions, bond issuances (convertible, exchangeable, warrant),\ntreasury stock, M&A (mergers, splits, business/asset transfers), lawsuits,\noverseas listings, defaults, business suspension, rehabilitation.\nData available from 2015 onward. Requires date range."
+    'DS005: Major event reports \u2014 36 APIs for significant corporate events.\nCovers: capital increases/reductions, bond issuances (convertible, exchangeable, warrant),\ntreasury stock, M&A (mergers, splits, business/asset transfers), lawsuits,\noverseas listings, defaults, business suspension, rehabilitation.\nData available from 2015 onward.\n\nAll subcommands require: --corp <name> --from <YYYYMMDD> --to <YYYYMMDD>\n\nExamples:\n  dart-fss major lawsuit --corp "\uC0BC\uC131\uC804\uC790" --from 20230101 --to 20251231 --pretty\n  dart-fss major convertible-bond --corp "\uCE74\uCE74\uC624" --from 20250101 --to 20251231'
   );
   const endpoints = (REGISTRY_BY_GROUP.get("major") || []).filter(
     (ep) => ep.pattern === "dateRange"
   );
   for (const ep of endpoints) {
-    group.command(ep.cliName).description(ep.summary).requiredOption("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').requiredOption("--from <YYYYMMDD>", "Start date in YYYYMMDD format (filing date). Data from 2015 onward").requiredOption("--to <YYYYMMDD>", "End date in YYYYMMDD format (filing date)").action(async (opts) => {
+    group.command(ep.cliName).description(ep.summary).requiredOption("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').requiredOption("--from <YYYYMMDD>", "Start date in YYYYMMDD format (filing date). Data from 2015 onward").requiredOption("--to <YYYYMMDD>", "End date in YYYYMMDD format (filing date)").addHelpText("after", `
+Examples:
+  dart-fss major ${ep.cliName} --corp "\uC0BC\uC131\uC804\uC790" --from 20230101 --to 20251231 --pretty
+  dart-fss major ${ep.cliName} --corp "\uCE74\uCE74\uC624" --from 20250101 --to 20251231`).action(async (opts) => {
       const globalOpts = getGlobalOpts5(group);
       const apiKey = getApiKey(globalOpts.apiKey);
       if (globalOpts.json) {
@@ -1511,13 +1520,15 @@ function getGlobalOpts6(cmd) {
 }
 function registerSecuritiesFilingCommands(program) {
   const group = program.command("securities").description(
-    "DS006: Securities registration statements \u2014 6 APIs for securities filings.\nCovers: equity securities, debt securities, depository receipts,\nmergers, comprehensive stock exchange/transfer, and splits.\nData available from 2015 onward. Requires date range."
+    'DS006: Securities registration statements \u2014 6 APIs for securities filings.\nCovers: equity securities, debt securities, depository receipts,\nmergers, comprehensive stock exchange/transfer, and splits.\nData available from 2015 onward.\n\nAll subcommands require: --corp <name> --from <YYYYMMDD> --to <YYYYMMDD>\n\nExamples:\n  dart-fss securities equity-securities --corp "\uC0BC\uC131\uC804\uC790" --from 20230101 --to 20251231'
   );
   const endpoints = (REGISTRY_BY_GROUP.get("securities") || []).filter(
     (ep) => ep.pattern === "dateRange"
   );
   for (const ep of endpoints) {
-    group.command(ep.cliName).description(ep.summary).requiredOption("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').requiredOption("--from <YYYYMMDD>", "Start date in YYYYMMDD format (filing date). Data from 2015 onward").requiredOption("--to <YYYYMMDD>", "End date in YYYYMMDD format (filing date)").action(async (opts) => {
+    group.command(ep.cliName).description(ep.summary).requiredOption("--corp <name-or-code>", 'Company name (e.g. "\uC0BC\uC131\uC804\uC790") or 8-digit corp_code').requiredOption("--from <YYYYMMDD>", "Start date in YYYYMMDD format (filing date). Data from 2015 onward").requiredOption("--to <YYYYMMDD>", "End date in YYYYMMDD format (filing date)").addHelpText("after", `
+Examples:
+  dart-fss securities ${ep.cliName} --corp "\uC0BC\uC131\uC804\uC790" --from 20230101 --to 20251231 --pretty`).action(async (opts) => {
       const globalOpts = getGlobalOpts6(group);
       const apiKey = getApiKey(globalOpts.apiKey);
       if (globalOpts.json) {
@@ -1666,7 +1677,15 @@ function createDartProgram() {
   const program = new Command();
   program.name("dart-fss").description(
     '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.'
-  ).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");
+  ).version("0.4.8").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").addHelpText("after", `
+Examples:
+  dart-fss lookup "\uC0BC\uC131\uC804\uC790"
+  dart-fss disclosure company --corp "\uC0BC\uC131\uC804\uC790" --pretty
+  dart-fss report employee --corp "\uC0BC\uC131\uC804\uC790" --year 2025 --quarter annual --pretty
+  dart-fss financial single-account --corp "SK\uD558\uC774\uB2C9\uC2A4" --year 2025 --quarter annual --fields "account_nm,thstrm_amount"
+  dart-fss major lawsuit --corp "\uCE74\uCE74\uC624" --from 20230101 --to 20251231
+  dart-fss endpoints --json-output
+  dart-fss schema employee`);
   registerDisclosureCommands(program);
   registerPeriodicReportCommands(program);
   registerFinancialCommands(program);

package/dist/cli.js

@@ -1,6 +1,6 @@
 import {
   createDartProgram
-} from "./chunk-UHR5UNEO.js";
+} from "./chunk-HYSOUXSY.js";
 export {
   createDartProgram
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dart-fss-cli",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "DART (금융감독원 전자공시) Open API CLI",
   "type": "module",
   "bin": {