kakaome 0.1.0__tar.gz

kakaome-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

kakaome-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kakaome contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kakaome-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: kakaome
+Version: 0.1.0
+Summary: Send KakaoTalk messages to your own chat from the command line
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,kakao,kakaotalk,message
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# kakaome
+
+카카오톡 **나에게 보내기** REST API를 사용하는 작은 Python CLI입니다.
+
+> 비공식 프로젝트이며 Kakao Corp.와 제휴하거나 Kakao가 보증하는 제품이 아닙니다.
+
+## 설치
+
+```console
+pipx install kakaome
+```
+
+개발 버전은 프로젝트 디렉터리에서 다음과 같이 실행할 수 있습니다.
+
+```console
+uv sync
+uv run kakaome --help
+```
+
+## Kakao Developers 설정
+
+1. 앱에서 **카카오 로그인**을 활성화합니다.
+2. Redirect URI로 `http://127.0.0.1:8765/callback`을 등록합니다.
+3. 동의 항목에서 **카카오톡 메시지 전송 (`talk_message`)**을 활성화합니다.
+4. 메시지 링크에 사용할 도메인을 **제품 링크 > 웹 도메인**에 등록합니다.
+
+REST API 키와 기본 링크를 저장하고 최초 한 번 로그인합니다.
+
+```console
+kakaome configure --rest-api-key YOUR_KEY --default-link https://example.com
+kakaome auth
+```
+
+Client Secret 기능을 활성화한 앱은 `--client-secret`도 지정합니다.
+
+## 사용
+
+```console
+kakaome send "배치 작업이 완료되었습니다."
+kakaome send "결과 보기" --link https://example.com/report
+kakaome send "오늘의 결과" --image-url https://example.com/result.png
+```
+
+카카오 기본 텍스트 템플릿은 링크를 필수로 요구하고 최대 200자까지 지원합니다.
+`--image-url`은 인터넷에서 공개 접근 가능한 이미지여야 합니다. PDF나 ZIP 같은 로컬
+파일을 카카오톡 첨부파일로 직접 업로드하는 기능은 공식 나에게 보내기 REST API에서
+지원하지 않습니다.
+
+설정과 OAuth 토큰은 Windows의 `%APPDATA%\kakaome\config.json` 또는 다른
+운영체제의 `~/.config/kakaome/config.json`에 저장됩니다. 경로는
+`KAKAOME_CONFIG` 환경 변수로 바꿀 수 있습니다.
+
+## 배포 빌드
+
+```console
+uv build
+uv run twine check dist/*
+```

kakaome-0.1.0/README.md

@@ -0,0 +1,58 @@
+# kakaome
+
+카카오톡 **나에게 보내기** REST API를 사용하는 작은 Python CLI입니다.
+
+> 비공식 프로젝트이며 Kakao Corp.와 제휴하거나 Kakao가 보증하는 제품이 아닙니다.
+
+## 설치
+
+```console
+pipx install kakaome
+```
+
+개발 버전은 프로젝트 디렉터리에서 다음과 같이 실행할 수 있습니다.
+
+```console
+uv sync
+uv run kakaome --help
+```
+
+## Kakao Developers 설정
+
+1. 앱에서 **카카오 로그인**을 활성화합니다.
+2. Redirect URI로 `http://127.0.0.1:8765/callback`을 등록합니다.
+3. 동의 항목에서 **카카오톡 메시지 전송 (`talk_message`)**을 활성화합니다.
+4. 메시지 링크에 사용할 도메인을 **제품 링크 > 웹 도메인**에 등록합니다.
+
+REST API 키와 기본 링크를 저장하고 최초 한 번 로그인합니다.
+
+```console
+kakaome configure --rest-api-key YOUR_KEY --default-link https://example.com
+kakaome auth
+```
+
+Client Secret 기능을 활성화한 앱은 `--client-secret`도 지정합니다.
+
+## 사용
+
+```console
+kakaome send "배치 작업이 완료되었습니다."
+kakaome send "결과 보기" --link https://example.com/report
+kakaome send "오늘의 결과" --image-url https://example.com/result.png
+```
+
+카카오 기본 텍스트 템플릿은 링크를 필수로 요구하고 최대 200자까지 지원합니다.
+`--image-url`은 인터넷에서 공개 접근 가능한 이미지여야 합니다. PDF나 ZIP 같은 로컬
+파일을 카카오톡 첨부파일로 직접 업로드하는 기능은 공식 나에게 보내기 REST API에서
+지원하지 않습니다.
+
+설정과 OAuth 토큰은 Windows의 `%APPDATA%\kakaome\config.json` 또는 다른
+운영체제의 `~/.config/kakaome/config.json`에 저장됩니다. 경로는
+`KAKAOME_CONFIG` 환경 변수로 바꿀 수 있습니다.
+
+## 배포 빌드
+
+```console
+uv build
+uv run twine check dist/*
+```

kakaome-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kakaome"
+version = "0.1.0"
+description = "Send KakaoTalk messages to your own chat from the command line"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["kakao", "kakaotalk", "cli", "message"]
+classifiers = [
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.scripts]
+kakaome = "kakao_self.cli:main"
+
+[dependency-groups]
+dev = [
+  "build>=1.2",
+  "pytest>=8.0",
+  "twine>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kakao_self"]

kakaome-0.1.0/src/kakao_self/__init__.py

@@ -0,0 +1,4 @@
+"""KakaoTalk self-message CLI."""
+
+__version__ = "0.1.0"
+

kakaome-0.1.0/src/kakao_self/api.py

@@ -0,0 +1,101 @@
+import json
+import time
+from typing import Any
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .config import save_config
+
+TOKEN_URL = "https://kauth.kakao.com/oauth/token"
+SEND_URL = "https://kapi.kakao.com/v2/api/talk/memo/default/send"
+
+
+class KakaoAPIError(RuntimeError):
+    pass
+
+
+def _post_form(url: str, data: dict[str, str], token: str | None = None) -> dict[str, Any]:
+    headers = {"Content-Type": "application/x-www-form-urlencoded;charset=utf-8"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    request = Request(url, data=urlencode(data).encode(), headers=headers, method="POST")
+    try:
+        with urlopen(request, timeout=30) as response:
+            return json.loads(response.read().decode())
+    except HTTPError as exc:
+        body = exc.read().decode(errors="replace")
+        raise KakaoAPIError(f"Kakao API 오류 ({exc.code}): {body}") from exc
+    except (URLError, TimeoutError) as exc:
+        raise KakaoAPIError(f"Kakao API에 연결할 수 없습니다: {exc}") from exc
+
+
+def exchange_code(config: dict[str, Any], code: str) -> dict[str, Any]:
+    data = {
+        "grant_type": "authorization_code",
+        "client_id": config["rest_api_key"],
+        "redirect_uri": config["redirect_uri"],
+        "code": code,
+    }
+    if config.get("client_secret"):
+        data["client_secret"] = config["client_secret"]
+    return _post_form(TOKEN_URL, data)
+
+
+def store_tokens(config: dict[str, Any], tokens: dict[str, Any]) -> None:
+    config["access_token"] = tokens["access_token"]
+    if tokens.get("refresh_token"):
+        config["refresh_token"] = tokens["refresh_token"]
+    config["expires_at"] = int(time.time()) + int(tokens.get("expires_in", 0))
+    save_config(config)
+
+
+def access_token(config: dict[str, Any]) -> str:
+    token = config.get("access_token")
+    if not token:
+        raise KakaoAPIError("인증 정보가 없습니다. 먼저 `kakaome auth`를 실행하세요.")
+    if int(config.get("expires_at", 0)) > int(time.time()) + 60:
+        return str(token)
+
+    refresh_token = config.get("refresh_token")
+    if not refresh_token:
+        raise KakaoAPIError("토큰이 만료되었습니다. `kakaome auth`를 다시 실행하세요.")
+    data = {
+        "grant_type": "refresh_token",
+        "client_id": config["rest_api_key"],
+        "refresh_token": str(refresh_token),
+    }
+    if config.get("client_secret"):
+        data["client_secret"] = config["client_secret"]
+    tokens = _post_form(TOKEN_URL, data)
+    store_tokens(config, tokens)
+    return str(config["access_token"])
+
+
+def send_message(
+    config: dict[str, Any], text: str, link: str, image_url: str | None = None
+) -> None:
+    if image_url:
+        template = {
+            "object_type": "feed",
+            "content": {
+                "title": text,
+                "image_url": image_url,
+                "link": {"web_url": link, "mobile_web_url": link},
+            },
+        }
+    else:
+        if len(text) > 200:
+            raise KakaoAPIError("텍스트 메시지는 200자 이하여야 합니다.")
+        template = {
+            "object_type": "text",
+            "text": text,
+            "link": {"web_url": link, "mobile_web_url": link},
+        }
+    result = _post_form(
+        SEND_URL,
+        {"template_object": json.dumps(template, ensure_ascii=False)},
+        access_token(config),
+    )
+    if result.get("result_code") != 0:
+        raise KakaoAPIError(f"메시지 전송 실패: {result}")

kakaome-0.1.0/src/kakao_self/auth.py

@@ -0,0 +1,76 @@
+import secrets
+import threading
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse
+
+from .api import KakaoAPIError, exchange_code, store_tokens
+
+AUTHORIZE_URL = "https://kauth.kakao.com/oauth/authorize"
+
+
+def authenticate(config: dict[str, Any], timeout: int = 180) -> None:
+    redirect = urlparse(config["redirect_uri"])
+    if redirect.scheme != "http" or redirect.hostname not in {"127.0.0.1", "localhost"}:
+        raise KakaoAPIError("Redirect URI는 로컬 HTTP 주소여야 합니다.")
+    if not redirect.port:
+        raise KakaoAPIError("Redirect URI에 포트가 필요합니다.")
+
+    state = secrets.token_urlsafe(24)
+    result: dict[str, str] = {}
+    expected_path = redirect.path or "/"
+
+    class CallbackHandler(BaseHTTPRequestHandler):
+        def do_GET(self) -> None:
+            parsed = urlparse(self.path)
+            query = parse_qs(parsed.query)
+            if parsed.path != expected_path:
+                self.send_error(404)
+                return
+            if query.get("state", [""])[0] != state:
+                result["error"] = "OAuth state가 일치하지 않습니다."
+                status = 400
+            elif query.get("code"):
+                result["code"] = query["code"][0]
+                status = 200
+            else:
+                result["error"] = query.get("error_description", ["인증이 취소되었습니다."])[0]
+                status = 400
+            body = "인증이 완료되었습니다. 이 창을 닫아도 됩니다." if status == 200 else result["error"]
+            encoded = body.encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("Content-Length", str(len(encoded)))
+            self.end_headers()
+            self.wfile.write(encoded)
+
+        def log_message(self, format: str, *args: object) -> None:
+            return
+
+    server = HTTPServer((redirect.hostname, redirect.port), CallbackHandler)
+    server.timeout = timeout
+    query = urlencode(
+        {
+            "response_type": "code",
+            "client_id": config["rest_api_key"],
+            "redirect_uri": config["redirect_uri"],
+            "scope": "talk_message",
+            "state": state,
+        }
+    )
+    print("브라우저에서 카카오 로그인을 완료하세요.")
+    webbrowser.open(f"{AUTHORIZE_URL}?{query}")
+    timer = threading.Timer(timeout, server.server_close)
+    timer.start()
+    try:
+        server.handle_request()
+    finally:
+        timer.cancel()
+        server.server_close()
+    if result.get("error"):
+        raise KakaoAPIError(result["error"])
+    if not result.get("code"):
+        raise KakaoAPIError("인증 대기 시간이 초과되었습니다.")
+    store_tokens(config, exchange_code(config, result["code"]))
+

kakaome-0.1.0/src/kakao_self/cli.py

@@ -0,0 +1,79 @@
+import argparse
+import sys
+from urllib.parse import urlparse
+
+from .api import KakaoAPIError, send_message
+from .auth import authenticate
+from .config import config_path, load_config, save_config
+
+
+def _url(value: str) -> str:
+    parsed = urlparse(value)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise argparse.ArgumentTypeError("http:// 또는 https:// URL이어야 합니다.")
+    return value
+
+
+def parser() -> argparse.ArgumentParser:
+    root = argparse.ArgumentParser(
+        prog="kakaome", description="카카오톡 '나에게 보내기' CLI"
+    )
+    sub = root.add_subparsers(dest="command", required=True)
+
+    configure = sub.add_parser("configure", help="Kakao Developers 앱 설정 저장")
+    configure.add_argument("--rest-api-key", required=True)
+    configure.add_argument("--default-link", required=True, type=_url)
+    configure.add_argument("--client-secret")
+    configure.add_argument(
+        "--redirect-uri", type=_url, default="http://127.0.0.1:8765/callback"
+    )
+
+    sub.add_parser("auth", help="브라우저에서 카카오 로그인 및 권한 동의")
+
+    send = sub.add_parser("send", help="내 채팅방으로 메시지 전송")
+    send.add_argument("message", help="보낼 메시지(텍스트 템플릿은 최대 200자)")
+    send.add_argument("--link", type=_url, help="메시지를 눌렀을 때 열 URL")
+    send.add_argument("--image-url", type=_url, help="공개 접근 가능한 이미지 URL")
+    return root
+
+
+def run(argv: list[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    config = load_config()
+    if args.command == "configure":
+        config.update(
+            rest_api_key=args.rest_api_key,
+            default_link=args.default_link,
+            redirect_uri=args.redirect_uri,
+        )
+        if args.client_secret:
+            config["client_secret"] = args.client_secret
+        save_config(config)
+        print(f"설정을 저장했습니다: {config_path()}")
+        return 0
+
+    if not config.get("rest_api_key"):
+        raise KakaoAPIError("설정이 없습니다. 먼저 `kakaome configure ...`를 실행하세요.")
+    if args.command == "auth":
+        authenticate(config)
+        print("카카오 인증을 저장했습니다.")
+        return 0
+
+    link = args.link or config.get("default_link")
+    if not link:
+        raise KakaoAPIError("--link 또는 configure의 --default-link가 필요합니다.")
+    send_message(config, args.message, str(link), args.image_url)
+    print("메시지를 전송했습니다.")
+    return 0
+
+
+def main() -> None:
+    try:
+        raise SystemExit(run())
+    except (KakaoAPIError, RuntimeError) as exc:
+        print(f"오류: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":
+    main()

kakaome-0.1.0/src/kakao_self/config.py

@@ -0,0 +1,36 @@
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def config_path() -> Path:
+    override = os.environ.get("KAKAOME_CONFIG")
+    if override:
+        return Path(override).expanduser()
+    base = Path(os.environ.get("APPDATA", Path.home() / ".config"))
+    return base / "kakaome" / "config.json"
+
+
+def load_config() -> dict[str, Any]:
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RuntimeError(f"설정 파일을 읽을 수 없습니다: {path}: {exc}") from exc
+
+
+def save_config(config: dict[str, Any]) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(
+        json.dumps(config, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    temporary.replace(path)
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass

kakaome-0.1.0/tests/test_api.py

@@ -0,0 +1,46 @@
+import json
+import time
+from unittest.mock import patch
+
+import pytest
+
+from kakao_self import api
+
+
+def test_send_text_builds_kakao_template() -> None:
+    config = {"access_token": "token", "expires_at": int(time.time()) + 3600}
+    with patch("kakao_self.api._post_form", return_value={"result_code": 0}) as post:
+        api.send_message(config, "완료", "https://example.com")
+    url, data, token = post.call_args.args
+    assert url == api.SEND_URL
+    assert token == "token"
+    assert json.loads(data["template_object"]) == {
+        "object_type": "text",
+        "text": "완료",
+        "link": {
+            "web_url": "https://example.com",
+            "mobile_web_url": "https://example.com",
+        },
+    }
+
+
+def test_send_rejects_text_over_200_characters() -> None:
+    with pytest.raises(api.KakaoAPIError, match="200자"):
+        api.send_message({}, "가" * 201, "https://example.com")
+
+
+def test_access_token_refreshes_expired_token() -> None:
+    config = {
+        "rest_api_key": "key",
+        "access_token": "old",
+        "refresh_token": "refresh",
+        "expires_at": 0,
+    }
+    with (
+        patch("kakao_self.api._post_form", return_value={"access_token": "new", "expires_in": 3600}),
+        patch("kakao_self.api.save_config") as save,
+    ):
+        assert api.access_token(config) == "new"
+    assert config["refresh_token"] == "refresh"
+    save.assert_called_once_with(config)
+

kakaome-0.1.0/tests/test_cli.py

@@ -0,0 +1,32 @@
+from unittest.mock import patch
+
+from kakao_self.cli import run
+
+
+def test_configure_saves_values() -> None:
+    with patch("kakao_self.cli.load_config", return_value={}), patch(
+        "kakao_self.cli.save_config"
+    ) as save:
+        result = run(
+            [
+                "configure",
+                "--rest-api-key",
+                "key",
+                "--default-link",
+                "https://example.com",
+            ]
+        )
+    assert result == 0
+    saved = save.call_args.args[0]
+    assert saved["rest_api_key"] == "key"
+    assert saved["redirect_uri"] == "http://127.0.0.1:8765/callback"
+
+
+def test_send_uses_configured_default_link() -> None:
+    config = {"rest_api_key": "key", "default_link": "https://example.com"}
+    with patch("kakao_self.cli.load_config", return_value=config), patch(
+        "kakao_self.cli.send_message"
+    ) as send:
+        assert run(["send", "hello"]) == 0
+    send.assert_called_once_with(config, "hello", "https://example.com", None)
+