PyPI - kiwoom-cli - Versions diffs - 2.2.0__tar.gz → 2.3.0__tar.gz - Mend

kiwoom-cli 2.2.0tar.gz → 2.3.0tar.gz

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 (53) hide show

{kiwoom_cli-2.2.0 → kiwoom_cli-2.3.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiwoom-cli
-Version: 2.2.0
+Version: 2.3.0
 Summary: User-friendly CLI for the Kiwoom Securities REST API (키움증권)
 License: LicenseRef-kiwoom-cli-Source-Available-1.0
 Project-URL: Homepage, https://github.com/gejyn14/kiwoom-cli
@@ -512,13 +512,61 @@ kiwoom --no-color stock info 005930     # 색상 없이 (파일 저장용)
 ```
 ```bash
-# jq로 필터링
-kiwoom -f json market rank volume | jq '.[].stk_nm'
+# jq로 필터링 (본문은 .data 아래)
+kiwoom -f json market rank volume | jq '.data[].stk_nm'
 # CSV를 파일로 저장
 kiwoom -f csv stock daily 005930 > samsung_daily.csv
 ```
+### JSON 응답 envelope (v1)
+`-f json`의 모든 응답은 성공/실패 모두 하나의 안정적인 envelope로 감쌉니다. table/csv 모드는 그대로입니다.
+```json
+{
+  "ok": true,
+  "schema": "v1",
+  "data": { "stk_nm": "삼성전자", "cur_prc": "+70000" },
+  "meta": { "profile": "default", "env": "prod", "cont": { "next_key": "..." } },
+  "error": null
+}
+```
+- `data` — 기존 응답 본문 그대로 (`return_code`/`return_msg`만 제거)
+- `meta.profile` / `meta.env` — 해석된 프로필과 도메인(`prod`/`mock`)
+- `meta.cont` — 연속조회 커서. 값이 있으면 다음 페이지가 존재: `kiwoom api <api_id> <body> --next-key <meta.cont.next_key>`
+- 실패 시 `ok: false`, `data: null`이고 `error`에 안정적인 코드가 담깁니다:
+```json
+{ "code": "TOKEN_EXPIRED", "retryable": false, "message": "Token이 유효하지 않습니다", "upstream_code": 8005 }
+```
+`error.code`는 키움 오류코드/HTTP 상태를 분류한 stable enum입니다 — 에이전트는 메시지 문자열 대신 이 코드로 분기하세요:
+| code | retryable | 의미 (upstream) |
+| --- | :---: | --- |
+| `INVALID_INPUT` | X | 입력 값/필수 파라미터 오류 (2, 1511, 1512, 1517) |
+| `INVALID_API` | X | 잘못된 API ID (1501, 1504, 1505) |
+| `NOT_FOUND` | X | 시장/종목 정보 없음 (1901, 1902) |
+| `AUTH_REQUIRED` | X | 인증 헤더/토큰 누락 (1513~1516, 토큰 미보유 시 로컬 감지) |
+| `TOKEN_EXPIRED` | X | 토큰 무효·만료 (8005, HTTP 401) |
+| `TOKEN_ISSUE_FAILED` | X | 토큰 발급 실패 (8003, 8006, 8009, 8011, 8012) |
+| `TOKEN_REVOKE_FAILED` | X | 토큰 폐기 실패 (8015, 8016) |
+| `INVALID_CREDENTIALS` | X | appkey/secretkey 검증 실패 (8001, 8002, 8020) |
+| `IP_MISMATCH` | X | 발급 IP와 요청 IP 불일치 (8010) |
+| `ENV_MISMATCH` | X | 실전/모의 구분 불일치 (8030, 8031) |
+| `DEVICE_AUTH_FAILED` | X | 단말기 인증 실패 (8040, 8050, 8103) |
+| `RATE_LIMITED` | 1700·429는 O | 요청 개수 초과 (1700, HTTP 429) / 재귀 호출 제한 (1687) |
+| `NETWORK_ERROR` | O | API 서버 연결 실패 |
+| `KEYCHAIN_UNAVAILABLE` | X | OS 키체인 접근 불가 (샌드박스/CI) |
+| `NOT_CONFIGURED` | X | `config setup` 미실행 (CLI 로컬 감지) |
+| `UPSTREAM_ERROR` | 5xx·1999는 O | 미분류 업스트림 오류 (기본값) |
+CLI 수준의 인자/옵션 오류(잘못된 값, 인자 누락 등)도 json 모드에서는 `INVALID_INPUT` envelope로 출력됩니다 (`upstream_code: null`, exit 1). `kiwoom api --raw`는 json 모드에서도 envelope로 감싸되 `data`에 응답 원본을 그대로(`return_code` 포함) 담습니다. `auth login`은 json 모드에서 `{profile, token_storage, saved, token}`을 반환하며, `token` 원문은 env 모드에서만 포함됩니다.
+exit code 계약은 그대로입니다 (0=성공, 1=입력오류, 2=API오류, 3=인증필요).
 ## Shell 자동완성
 ```bash

{kiwoom_cli-2.2.0 → kiwoom_cli-2.3.0}/README.md RENAMED Viewed

@@ -475,13 +475,61 @@ kiwoom --no-color stock info 005930     # 색상 없이 (파일 저장용)
 ```
 ```bash
-# jq로 필터링
-kiwoom -f json market rank volume | jq '.[].stk_nm'
+# jq로 필터링 (본문은 .data 아래)
+kiwoom -f json market rank volume | jq '.data[].stk_nm'
 # CSV를 파일로 저장
 kiwoom -f csv stock daily 005930 > samsung_daily.csv
 ```
+### JSON 응답 envelope (v1)
+`-f json`의 모든 응답은 성공/실패 모두 하나의 안정적인 envelope로 감쌉니다. table/csv 모드는 그대로입니다.
+```json
+{
+  "ok": true,
+  "schema": "v1",
+  "data": { "stk_nm": "삼성전자", "cur_prc": "+70000" },
+  "meta": { "profile": "default", "env": "prod", "cont": { "next_key": "..." } },
+  "error": null
+}
+```
+- `data` — 기존 응답 본문 그대로 (`return_code`/`return_msg`만 제거)
+- `meta.profile` / `meta.env` — 해석된 프로필과 도메인(`prod`/`mock`)
+- `meta.cont` — 연속조회 커서. 값이 있으면 다음 페이지가 존재: `kiwoom api <api_id> <body> --next-key <meta.cont.next_key>`
+- 실패 시 `ok: false`, `data: null`이고 `error`에 안정적인 코드가 담깁니다:
+```json
+{ "code": "TOKEN_EXPIRED", "retryable": false, "message": "Token이 유효하지 않습니다", "upstream_code": 8005 }
+```
+`error.code`는 키움 오류코드/HTTP 상태를 분류한 stable enum입니다 — 에이전트는 메시지 문자열 대신 이 코드로 분기하세요:
+| code | retryable | 의미 (upstream) |
+| --- | :---: | --- |
+| `INVALID_INPUT` | X | 입력 값/필수 파라미터 오류 (2, 1511, 1512, 1517) |
+| `INVALID_API` | X | 잘못된 API ID (1501, 1504, 1505) |
+| `NOT_FOUND` | X | 시장/종목 정보 없음 (1901, 1902) |
+| `AUTH_REQUIRED` | X | 인증 헤더/토큰 누락 (1513~1516, 토큰 미보유 시 로컬 감지) |
+| `TOKEN_EXPIRED` | X | 토큰 무효·만료 (8005, HTTP 401) |
+| `TOKEN_ISSUE_FAILED` | X | 토큰 발급 실패 (8003, 8006, 8009, 8011, 8012) |
+| `TOKEN_REVOKE_FAILED` | X | 토큰 폐기 실패 (8015, 8016) |
+| `INVALID_CREDENTIALS` | X | appkey/secretkey 검증 실패 (8001, 8002, 8020) |
+| `IP_MISMATCH` | X | 발급 IP와 요청 IP 불일치 (8010) |
+| `ENV_MISMATCH` | X | 실전/모의 구분 불일치 (8030, 8031) |
+| `DEVICE_AUTH_FAILED` | X | 단말기 인증 실패 (8040, 8050, 8103) |
+| `RATE_LIMITED` | 1700·429는 O | 요청 개수 초과 (1700, HTTP 429) / 재귀 호출 제한 (1687) |
+| `NETWORK_ERROR` | O | API 서버 연결 실패 |
+| `KEYCHAIN_UNAVAILABLE` | X | OS 키체인 접근 불가 (샌드박스/CI) |
+| `NOT_CONFIGURED` | X | `config setup` 미실행 (CLI 로컬 감지) |
+| `UPSTREAM_ERROR` | 5xx·1999는 O | 미분류 업스트림 오류 (기본값) |
+CLI 수준의 인자/옵션 오류(잘못된 값, 인자 누락 등)도 json 모드에서는 `INVALID_INPUT` envelope로 출력됩니다 (`upstream_code: null`, exit 1). `kiwoom api --raw`는 json 모드에서도 envelope로 감싸되 `data`에 응답 원본을 그대로(`return_code` 포함) 담습니다. `auth login`은 json 모드에서 `{profile, token_storage, saved, token}`을 반환하며, `token` 원문은 env 모드에서만 포함됩니다.
+exit code 계약은 그대로입니다 (0=성공, 1=입력오류, 2=API오류, 3=인증필요).
 ## Shell 자동완성
 ```bash

{kiwoom_cli-2.2.0 → kiwoom_cli-2.3.0}/kiwoom_cli/__init__.py RENAMED Viewed

@@ -1,3 +1,3 @@
 """Kiwoom Securities REST API CLI."""
-__version__ = "2.2.0"
+__version__ = "2.3.0"

{kiwoom_cli-2.2.0 → kiwoom_cli-2.3.0}/kiwoom_cli/client.py RENAMED Viewed

@@ -24,6 +24,10 @@ class KiwoomAPIError(Exception):
         super().__init__(f"[{code}] {msg}")
+class KiwoomAuthError(Exception):
+    """No access token available — the caller must authenticate first."""
 class KiwoomClient:
     """Synchronous client for the Kiwoom REST API."""
@@ -80,6 +84,8 @@ class KiwoomClient:
         next_key: str = "",
     ) -> tuple[dict[str, Any], dict[str, str]]:
         """Make a single API request. Returns (body_json, response_headers)."""
+        if not self.token:
+            raise KiwoomAuthError()
         url_path = get_url(api_id)
         headers = self._headers(api_id, cont_yn, next_key)
         if self._should_spin():
@@ -98,6 +104,16 @@ class KiwoomClient:
             "cont-yn": resp.headers.get("cont-yn", ""),
             "next-key": resp.headers.get("next-key", ""),
         }
+        # 연속조회 커서를 Click 컨텍스트에 보관 → json envelope의 meta.cont로 노출
+        # (라이브러리로 쓰일 때는 컨텍스트가 없으므로 조용히 건너뜀)
+        ctx = click.get_current_context(silent=True)
+        if ctx is not None and isinstance(ctx.obj, dict):
+            if resp_headers["cont-yn"] == "Y" and resp_headers["next-key"]:
+                ctx.obj["last_cont"] = {"next_key": resp_headers["next-key"]}
+            else:
+                ctx.obj["last_cont"] = None
         return data, resp_headers
     def request_all(

kiwoom_cli-2.3.0/kiwoom_cli/envelope.py ADDED Viewed

@@ -0,0 +1,132 @@
+"""Stable JSON response envelope (v1) for `-f json` output.
+성공/실패 모두 하나의 envelope로 감쌉니다:
+{"ok": bool, "schema": "v1", "data": ..., "meta": {...}, "error": ...}
+에러는 안정적인 enum 코드로 분류되어 자동화/에이전트가 upstream 메시지를
+파싱하지 않고도 분기할 수 있습니다. csv/table 모드에는 적용되지 않습니다.
+"""
+from __future__ import annotations
+import json
+import os
+from typing import Any
+import click
+from . import config
+SCHEMA = "v1"
+# 키움 REST API 공식 오류코드 (docs/키움 REST API 문서.xlsx '오류코드' 시트)
+# → (stable_code, retryable). 미등록 코드는 ("UPSTREAM_ERROR", False).
+CODE_MAP: dict[int, tuple[str, bool]] = {
+    # API 라우팅
+    1501: ("INVALID_API", False),      # API ID Null/없음
+    1504: ("INVALID_API", False),      # URI가 지원하지 않는 API ID
+    1505: ("INVALID_API", False),      # 존재하지 않는 API ID
+    # 입력 검증
+    2: ("INVALID_INPUT", False),       # 입력 값 오류 (실측)
+    1511: ("INVALID_INPUT", False),    # 필수 입력 누락
+    1512: ("INVALID_INPUT", False),    # Http header 값 누락/불가독
+    1517: ("INVALID_INPUT", False),    # 입력 값 형식 오류
+    # 인증 헤더/토큰
+    1513: ("AUTH_REQUIRED", False),    # authorization 필드 없음
+    1514: ("AUTH_REQUIRED", False),    # authorization 형식 오류
+    1515: ("AUTH_REQUIRED", False),    # Grant Type 형식 오류
+    1516: ("AUTH_REQUIRED", False),    # Token 미정의
+    8005: ("TOKEN_EXPIRED", False),    # Token 유효하지 않음
+    # 호출 제한
+    1687: ("RATE_LIMITED", False),     # 재귀 호출 제한 (재시도 무의미)
+    1700: ("RATE_LIMITED", True),      # 허용 요청 개수 초과
+    # 종목/시장 조회
+    1901: ("NOT_FOUND", False),        # 시장 코드 없음
+    1902: ("NOT_FOUND", False),        # 종목 정보 없음
+    # 서버 오류
+    1999: ("UPSTREAM_ERROR", True),    # 예기치 못한 에러
+    # 앱키/토큰 발급·폐기
+    8001: ("INVALID_CREDENTIALS", False),  # App/Secret Key 검증 실패
+    8002: ("INVALID_CREDENTIALS", False),
+    8020: ("INVALID_CREDENTIALS", False),  # appkey/secretkey 미입력
+    8003: ("TOKEN_ISSUE_FAILED", False),   # Access Token 조회 실패
+    8006: ("TOKEN_ISSUE_FAILED", False),
+    8009: ("TOKEN_ISSUE_FAILED", False),
+    8011: ("TOKEN_ISSUE_FAILED", False),
+    8012: ("TOKEN_ISSUE_FAILED", False),
+    8015: ("TOKEN_REVOKE_FAILED", False),
+    8016: ("TOKEN_REVOKE_FAILED", False),
+    # 환경/단말 제약
+    8010: ("IP_MISMATCH", False),          # 발급 IP와 요청 IP 불일치
+    8030: ("ENV_MISMATCH", False),         # 실전/모의 구분 불일치 (Appkey)
+    8031: ("ENV_MISMATCH", False),         # 실전/모의 구분 불일치 (Token)
+    8040: ("DEVICE_AUTH_FAILED", False),
+    8050: ("DEVICE_AUTH_FAILED", False),
+    8103: ("DEVICE_AUTH_FAILED", False),
+}
+HTTP_MAP: dict[int, tuple[str, bool]] = {
+    401: ("TOKEN_EXPIRED", False),
+    429: ("RATE_LIMITED", True),
+}
+DEFAULT = ("UPSTREAM_ERROR", False)
+def classify(upstream_code: int | None = None, http_status: int | None = None) -> tuple[str, bool]:
+    """(stable_code, retryable)로 분류. http_status가 있으면 우선."""
+    if http_status is not None:
+        if http_status in HTTP_MAP:
+            return HTTP_MAP[http_status]
+        if 500 <= http_status < 600:
+            return ("UPSTREAM_ERROR", True)
+        return DEFAULT
+    if upstream_code is not None and upstream_code in CODE_MAP:
+        return CODE_MAP[upstream_code]
+    return DEFAULT
+def build_meta() -> dict[str, Any]:
+    ctx = click.get_current_context(silent=True)
+    obj = ctx.obj if ctx is not None and isinstance(ctx.obj, dict) else {}
+    profile = config.resolve_profile(obj.get("profile"))
+    env = os.environ.get("KIWOOM_DOMAIN")
+    if env not in config.DOMAINS:
+        cfg = config.load_config()
+        env = cfg.get("profiles", {}).get(profile, {}).get("domain", "mock")
+        if env not in config.DOMAINS:
+            env = "mock"
+    return {"profile": profile, "env": env, "cont": obj.get("last_cont") or None}
+def emit(data: Any = None, *, error: dict[str, Any] | None = None) -> None:
+    """Envelope 전체를 단일 JSON 문서로 stdout에 출력."""
+    doc = {
+        "ok": error is None,
+        "schema": SCHEMA,
+        "data": data,
+        "meta": build_meta(),
+        "error": error,
+    }
+    click.echo(json.dumps(doc, ensure_ascii=False, indent=2))
+def error_body(
+    message: str,
+    *,
+    upstream_code: int | None = None,
+    http_status: int | None = None,
+    code: str | None = None,
+    retryable: bool | None = None,
+) -> dict[str, Any]:
+    """에러 dict 구성. code/retryable을 직접 주지 않으면 classify()로 결정."""
+    if code is None or retryable is None:
+        c, r = classify(upstream_code=upstream_code, http_status=http_status)
+        code = code if code is not None else c
+        retryable = retryable if retryable is not None else r
+    return {
+        "code": code,
+        "retryable": retryable,
+        "message": message,
+        "upstream_code": upstream_code if upstream_code is not None else http_status,
+    }

{kiwoom_cli-2.2.0 → kiwoom_cli-2.3.0}/kiwoom_cli/formatters.py RENAMED Viewed

@@ -3,7 +3,6 @@
 from __future__ import annotations
 import csv
-import json
 import sys
 from typing import Any
@@ -12,6 +11,7 @@ from rich.panel import Panel
 from rich.table import Table
 from rich.text import Text
+from . import envelope
 from .output import console, err_console
@@ -35,11 +35,11 @@ def human(renderable: Any) -> None:
 def _output_json(data: Any) -> None:
-    """Write data as JSON to stdout."""
+    """Write data as an enveloped JSON document to stdout."""
     clean = data
     if isinstance(data, dict):
         clean = {k: v for k, v in data.items() if k not in ("return_code", "return_msg")}
-    click.echo(json.dumps(clean, ensure_ascii=False, indent=2))
+    envelope.emit(data=clean)
 def _output_csv(rows: list[dict], keys: list[str] | None = None) -> None:

{kiwoom_cli-2.2.0 → kiwoom_cli-2.3.0}/kiwoom_cli/main.py RENAMED Viewed

@@ -7,9 +7,10 @@ import os
 import click
 import httpx
+import keyring
-from . import __version__, auth, config
-from .client import KiwoomClient, KiwoomAPIError
+from . import __version__, auth, config, envelope
+from .client import KiwoomClient, KiwoomAPIError, KiwoomAuthError
 from .commands.account import account
 from .commands.dashboard import dashboard
 from .commands.market import market
@@ -35,26 +36,68 @@ click.exceptions.UsageError.exit_code = EXIT_INPUT
 class KiwoomGroup(click.Group):
     """Custom group that catches API/network errors globally."""
+    @staticmethod
+    def _json_mode(ctx) -> bool:
+        return (ctx.obj.get("format", "table") if ctx.obj else "table") == "json"
     def invoke(self, ctx):
         try:
             return super().invoke(ctx)
         except KiwoomAPIError as e:
-            fmt = ctx.obj.get("format", "table") if ctx.obj else "table"
-            if fmt == "json":
-                click.echo(json.dumps({"error": e.msg, "code": e.code}, ensure_ascii=False))
+            if self._json_mode(ctx):
+                envelope.emit(error=envelope.error_body(e.msg, upstream_code=e.code))
             else:
                 console.print(f"[red]API 오류:[/] {e}")
             ctx.exit(EXIT_API)
+        except KiwoomAuthError:
+            if self._json_mode(ctx):
+                envelope.emit(error=envelope.error_body(
+                    "토큰이 없습니다. 'kiwoom auth login'으로 발급하세요.",
+                    code="AUTH_REQUIRED", retryable=False,
+                ))
+            else:
+                console.print("[red]인증 필요:[/] 토큰이 없습니다. [dim]kiwoom auth login[/]")
+            ctx.exit(EXIT_AUTH)
+        except keyring.errors.KeyringError:
+            if self._json_mode(ctx):
+                envelope.emit(error=envelope.error_body(
+                    "OS 키체인에 접근할 수 없습니다. KIWOOM_TOKEN 환경변수를 사용하세요.",
+                    code="KEYCHAIN_UNAVAILABLE", retryable=False,
+                ))
+            else:
+                console.print("[red]키체인 오류:[/] OS 키체인에 접근할 수 없습니다 (잠김 또는 비대화형 세션).")
+                console.print(
+                    "[dim]키체인 없는 환경에서는 본인 터미널에서 토큰을 발급한 뒤 "
+                    "KIWOOM_TOKEN 환경변수로 전달하세요. (README '샌드박스 환경' 참고)[/]"
+                )
+            ctx.exit(EXIT_INPUT)
         except httpx.HTTPStatusError as e:
-            if e.response.status_code == 401:
+            status = e.response.status_code
+            if self._json_mode(ctx):
+                envelope.emit(error=envelope.error_body(f"HTTP {status}", http_status=status))
+            elif status == 401:
                 console.print("[red]인증 오류:[/] 토큰이 만료되었습니다. [dim]kiwoom auth login[/]")
-                ctx.exit(EXIT_AUTH)
             else:
-                console.print(f"[red]HTTP 오류:[/] {e.response.status_code}")
-                ctx.exit(EXIT_API)
+                console.print(f"[red]HTTP 오류:[/] {status}")
+            ctx.exit(EXIT_AUTH if status == 401 else EXIT_API)
         except httpx.ConnectError:
-            console.print("[red]연결 오류:[/] API 서버에 연결할 수 없습니다. 도메인을 확인하세요.")
+            if self._json_mode(ctx):
+                envelope.emit(error=envelope.error_body(
+                    "API 서버에 연결할 수 없습니다. 도메인을 확인하세요.",
+                    code="NETWORK_ERROR", retryable=True,
+                ))
+            else:
+                console.print("[red]연결 오류:[/] API 서버에 연결할 수 없습니다. 도메인을 확인하세요.")
             ctx.exit(EXIT_API)
+        except click.ClickException as e:
+            # 인자/옵션 오류(UsageError 포함)도 json 모드에서는 envelope로.
+            # table 모드는 Click 기본 출력 그대로 (re-raise).
+            if self._json_mode(ctx):
+                envelope.emit(error=envelope.error_body(
+                    e.format_message(), code="INVALID_INPUT", retryable=False,
+                ))
+                ctx.exit(e.exit_code)
+            raise
 @click.group(cls=KiwoomGroup)
@@ -228,6 +271,17 @@ def config_profiles():
     cfg = config.load_config()
     profiles = cfg.get("profiles", {})
     default = config.get_default_profile()
+    if _get_format() == "json":
+        envelope.emit(data=[
+            {
+                "name": name,
+                "domain": settings.get("domain", "mock"),
+                "account": settings.get("account", ""),
+                "default": name == default,
+            }
+            for name, settings in profiles.items()
+        ])
+        return
     if not profiles:
         human("[yellow]등록된 프로필이 없습니다.[/]")
         return
@@ -248,27 +302,43 @@ def auth_cmd():
     pass
+def _fail_not_configured():
+    msg = "설정이 필요합니다. 먼저 실행: kiwoom config setup"
+    if _get_format() == "json":
+        envelope.emit(error=envelope.error_body(msg, code="NOT_CONFIGURED", retryable=False))
+    else:
+        human(f"[red]{msg}[/]")
+    raise SystemExit(EXIT_INPUT)
 @auth_cmd.command("login")
 @click.pass_context
 def auth_login(ctx):
     """접근토큰 발급."""
     profile = config.resolve_profile(ctx.obj.get("profile") if ctx.obj else None)
     if not config.is_configured(profile):
-        human("[red]설정이 필요합니다. 먼저 실행: kiwoom config setup[/]")
-        raise SystemExit(1)
+        _fail_not_configured()
+    # 발급 실패(KiwoomAPIError)는 전역 핸들러가 envelope/exit 2로 처리
     with KiwoomClient() as c:
-        try:
-            token = c.issue_token()
-            human("[green]토큰 발급 완료![/]")
-            if config.get_token_storage(profile) == "env":
-                human("  저장 위치: [bold]없음 (env 모드)[/] — 아래를 셸에서 실행하세요:")
-                human(f"  export KIWOOM_TOKEN='{token}'")
-            else:
-                masked = token[:10] + "..." + token[-4:] if len(token) > 14 else token
-                human(f"  토큰: {masked}")
-                human("  저장 위치: [bold]키체인[/]")
-        except KiwoomAPIError as e:
-            human(f"[red]토큰 발급 실패:[/] {e}")
+        token = c.issue_token()
+    storage = config.get_token_storage(profile)
+    if _get_format() == "json":
+        # env 모드에서는 사용자가 직접 관리해야 하므로 토큰 원문을 포함
+        envelope.emit(data={
+            "profile": profile,
+            "token_storage": storage,
+            "saved": storage != "env",
+            "token": token if storage == "env" else None,
+        })
+        return
+    human("[green]토큰 발급 완료![/]")
+    if storage == "env":
+        human("  저장 위치: [bold]없음 (env 모드)[/] — 아래를 셸에서 실행하세요:")
+        human(f"  export KIWOOM_TOKEN='{token}'")
+    else:
+        masked = token[:10] + "..." + token[-4:] if len(token) > 14 else token
+        human(f"  토큰: {masked}")
+        human("  저장 위치: [bold]키체인[/]")
 @auth_cmd.command("logout")
@@ -277,14 +347,14 @@ def auth_logout(ctx):
     """접근토큰 폐기."""
     profile = config.resolve_profile(ctx.obj.get("profile") if ctx.obj else None)
     if not config.is_configured(profile):
-        human("[red]설정이 필요합니다. 먼저 실행: kiwoom config setup[/]")
-        raise SystemExit(1)
+        _fail_not_configured()
+    # 폐기 실패(KiwoomAPIError)는 전역 핸들러가 envelope/exit 2로 처리
     with KiwoomClient() as c:
-        try:
-            c.revoke_token()
-            human("[green]토큰 폐기 완료.[/]")
-        except KiwoomAPIError as e:
-            human(f"[red]토큰 폐기 실패:[/] {e}")
+        c.revoke_token()
+    if _get_format() == "json":
+        envelope.emit(data={"profile": profile, "revoked": True})
+    else:
+        human("[green]토큰 폐기 완료.[/]")
     if os.environ.get("KIWOOM_TOKEN"):
         human("[yellow]KIWOOM_TOKEN 환경변수가 설정되어 있어 이 셸에서는 해당 토큰이 계속 사용됩니다. unset KIWOOM_TOKEN 으로 제거하세요.[/]")
@@ -330,7 +400,8 @@ def auth_status(ctx):
 @click.argument("api_id")
 @click.argument("body", default="{}")
 @click.option("--raw", is_flag=True, help="JSON 원본 출력")
-def raw_api(api_id: str, body: str, raw: bool):
+@click.option("--next-key", "next_key", default="", help="연속조회 커서 (이전 응답의 meta.cont.next_key)")
+def raw_api(api_id: str, body: str, raw: bool, next_key: str):
     """Raw API 호출. (예: kiwoom api ka10001 '{"stk_cd":"005930"}')"""
     try:
         body_dict = json.loads(body)
@@ -338,9 +409,17 @@ def raw_api(api_id: str, body: str, raw: bool):
         raise click.ClickException(f"Invalid JSON body: {e}")
     with KiwoomClient() as c:
-        data, headers = c.request(api_id, body_dict)
+        data, headers = c.request(
+            api_id, body_dict,
+            cont_yn="Y" if next_key else "",
+            next_key=next_key,
+        )
         if raw:
-            console.print_json(json.dumps(data, ensure_ascii=False, indent=2))
+            if _get_format() == "json":
+                # --raw는 필드 제거만 생략: stdout은 여전히 단일 envelope 문서
+                envelope.emit(data=data)
+            else:
+                console.print_json(json.dumps(data, ensure_ascii=False, indent=2))
         else:
             from .api_spec import get_description
             title = get_description(api_id)

{kiwoom_cli-2.2.0 → kiwoom_cli-2.3.0}/kiwoom_cli.egg-info/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiwoom-cli
-Version: 2.2.0
+Version: 2.3.0
 Summary: User-friendly CLI for the Kiwoom Securities REST API (키움증권)
 License: LicenseRef-kiwoom-cli-Source-Available-1.0
 Project-URL: Homepage, https://github.com/gejyn14/kiwoom-cli
@@ -512,13 +512,61 @@ kiwoom --no-color stock info 005930     # 색상 없이 (파일 저장용)
 ```
 ```bash
-# jq로 필터링
-kiwoom -f json market rank volume | jq '.[].stk_nm'
+# jq로 필터링 (본문은 .data 아래)
+kiwoom -f json market rank volume | jq '.data[].stk_nm'
 # CSV를 파일로 저장
 kiwoom -f csv stock daily 005930 > samsung_daily.csv
 ```
+### JSON 응답 envelope (v1)
+`-f json`의 모든 응답은 성공/실패 모두 하나의 안정적인 envelope로 감쌉니다. table/csv 모드는 그대로입니다.
+```json
+{
+  "ok": true,
+  "schema": "v1",
+  "data": { "stk_nm": "삼성전자", "cur_prc": "+70000" },
+  "meta": { "profile": "default", "env": "prod", "cont": { "next_key": "..." } },
+  "error": null
+}
+```
+- `data` — 기존 응답 본문 그대로 (`return_code`/`return_msg`만 제거)
+- `meta.profile` / `meta.env` — 해석된 프로필과 도메인(`prod`/`mock`)
+- `meta.cont` — 연속조회 커서. 값이 있으면 다음 페이지가 존재: `kiwoom api <api_id> <body> --next-key <meta.cont.next_key>`
+- 실패 시 `ok: false`, `data: null`이고 `error`에 안정적인 코드가 담깁니다:
+```json
+{ "code": "TOKEN_EXPIRED", "retryable": false, "message": "Token이 유효하지 않습니다", "upstream_code": 8005 }
+```
+`error.code`는 키움 오류코드/HTTP 상태를 분류한 stable enum입니다 — 에이전트는 메시지 문자열 대신 이 코드로 분기하세요:
+| code | retryable | 의미 (upstream) |
+| --- | :---: | --- |
+| `INVALID_INPUT` | X | 입력 값/필수 파라미터 오류 (2, 1511, 1512, 1517) |
+| `INVALID_API` | X | 잘못된 API ID (1501, 1504, 1505) |
+| `NOT_FOUND` | X | 시장/종목 정보 없음 (1901, 1902) |
+| `AUTH_REQUIRED` | X | 인증 헤더/토큰 누락 (1513~1516, 토큰 미보유 시 로컬 감지) |
+| `TOKEN_EXPIRED` | X | 토큰 무효·만료 (8005, HTTP 401) |
+| `TOKEN_ISSUE_FAILED` | X | 토큰 발급 실패 (8003, 8006, 8009, 8011, 8012) |
+| `TOKEN_REVOKE_FAILED` | X | 토큰 폐기 실패 (8015, 8016) |
+| `INVALID_CREDENTIALS` | X | appkey/secretkey 검증 실패 (8001, 8002, 8020) |
+| `IP_MISMATCH` | X | 발급 IP와 요청 IP 불일치 (8010) |
+| `ENV_MISMATCH` | X | 실전/모의 구분 불일치 (8030, 8031) |
+| `DEVICE_AUTH_FAILED` | X | 단말기 인증 실패 (8040, 8050, 8103) |
+| `RATE_LIMITED` | 1700·429는 O | 요청 개수 초과 (1700, HTTP 429) / 재귀 호출 제한 (1687) |
+| `NETWORK_ERROR` | O | API 서버 연결 실패 |
+| `KEYCHAIN_UNAVAILABLE` | X | OS 키체인 접근 불가 (샌드박스/CI) |
+| `NOT_CONFIGURED` | X | `config setup` 미실행 (CLI 로컬 감지) |
+| `UPSTREAM_ERROR` | 5xx·1999는 O | 미분류 업스트림 오류 (기본값) |
+CLI 수준의 인자/옵션 오류(잘못된 값, 인자 누락 등)도 json 모드에서는 `INVALID_INPUT` envelope로 출력됩니다 (`upstream_code: null`, exit 1). `kiwoom api --raw`는 json 모드에서도 envelope로 감싸되 `data`에 응답 원본을 그대로(`return_code` 포함) 담습니다. `auth login`은 json 모드에서 `{profile, token_storage, saved, token}`을 반환하며, `token` 원문은 env 모드에서만 포함됩니다.
+exit code 계약은 그대로입니다 (0=성공, 1=입력오류, 2=API오류, 3=인증필요).
 ## Shell 자동완성
 ```bash

{kiwoom_cli-2.2.0 → kiwoom_cli-2.3.0}/kiwoom_cli.egg-info/SOURCES.txt RENAMED Viewed

@@ -6,6 +6,7 @@ kiwoom_cli/api_spec.py
 kiwoom_cli/auth.py
 kiwoom_cli/client.py
 kiwoom_cli/config.py
+kiwoom_cli/envelope.py
 kiwoom_cli/formatters.py
 kiwoom_cli/main.py
 kiwoom_cli/output.py
@@ -38,6 +39,7 @@ tests/test_auth_cli.py
 tests/test_cli.py
 tests/test_client.py
 tests/test_credentials.py
+tests/test_envelope.py
 tests/test_formatters.py
 tests/test_formatters_property.py
 tests/test_json_purity.py

kiwoom-cli 2.2.0__tar.gz → 2.3.0__tar.gz

kiwoom-cli 2.2.0tar.gz → 2.3.0tar.gz