sendgo-python 1.3.0__tar.gz → 1.5.0__tar.gz

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendgo-python
-Version: 1.3.0
+Version: 1.5.0
 Summary: Sendgo Python SDK — 카카오 알림톡/브랜드메시지, SMS/LMS/MMS
 Author-email: Sendgo <dev@sendgo.io>
 License: MIT
@@ -808,3 +808,56 @@ MIT License © 2026 [Sendgo](https://sendgo.io)
 ---
 
 *키워드: 카카오 알림톡 Python, 카카오 친구톡 Django, SMS 발송 FastAPI, 알림톡 SDK pip, Python 카카오 API 연동, Django 문자 발송, FastAPI 알림톡, Celery 알림톡 비동기, Sendgo Python SDK*
+
+## 계정·조직·API 키 관리 (1.5.0)
+
+발송용 `accessKey`/`secretKey`가 없는 단계에서 사용하는 **별도 계정 클라이언트**입니다.
+콘솔에서 발급받은 에이전트 토큰(`SENDGO_AGENT_TOKEN`)으로 `/api/v2/account`를 호출합니다.
+계정 조회에는 `account:read`, 키·허용 IP 변경에는 `keys:write` 권한이 필요합니다.
+토큰 만료나 권한 부족(401/403)은 그대로 예외로 반환하며 자동 갱신·재시도하지 않습니다.
+
+조직 선택은 서버에 저장되는 **사용자 계정의 현재 조직**을 바꿉니다. 같은 사용자로
+여러 조직의 설정을 동시에 변경하지 마세요. 개인 계정으로 돌아가려면 조직 ID에
+`null`(Python `None`, Ruby `nil`, Go `nil`) 또는 `personal`을 전달합니다.
+키 발급 응답의 `data.apiKey.secretKey`는 한 번만 반환되므로 서버의 비밀 저장소에 보관하세요.
+허용 IP가 하나라도 등록되면 목록 밖의 IP는 차단됩니다.
+에이전트 토큰과 키는 브라우저·모바일 앱에 포함하거나 응답·로그에 출력하지 않습니다.
+
+```python
+import os
+from sendgo import AccountClient
+account = AccountClient(agent_token=os.environ['SENDGO_AGENT_TOKEN'])
+result = account.me()
+account.select_organization('team-uuid')
+issued = account.create_api_key({'name': '서버 연동'})
+```
+
+지원 메서드: `me`, `organizations`, `select_organization`, `api_keys`, `create_api_key`, `api_key`, `update_api_key`, `delete_api_key`, `issue_token`, `allowed_ips`, `add_allowed_ip`, `delete_allowed_ip`.
+
+키 생성 인자는 `name`, 선택적 `ipAddresses: [{ip, description}]`이며, 허용 IP 추가 인자는 `ip`, 선택적 `description`입니다. 키·IP 식별자는 응답의 `id`(UUID)를 사용합니다.
+
+## 템플릿 폴더 (1.5.0)
+
+기업 계정의 발송용 API 키와 `apiVersion=v2` 설정으로 사용하는 서버 전용 API입니다.
+폴더는 알림톡·브랜드메시지가 공유하며, 목록의 `templateType`은 `notice` 또는 `brand`입니다.
+목록은 `data.folders` 트리와 `total`, `uncategorised` 개수를 반환합니다.
+`templateCount`는 하위 폴더를 제외한 해당 폴더의 템플릿 수입니다.
+
+- 생성: `name`, 선택 `parentUuid`. 최대 5단계이며 같은 부모 아래 이름 중복은 409입니다.
+- 이동: 동일 발신프로필의 `templateCodes` 1~100개. `folderUuid`는 필수이며 `null`이면 미분류로 이동합니다.
+- 템플릿 목록: `folderUuid=none`은 미분류, UUID는 해당 폴더, 생략은 전체입니다.
+- 템플릿 등록: 선택 필드 `folderUuid`로 폴더를 지정합니다. 기존 템플릿 수정 API 대신 폴더 이동 API를 사용하세요.
+
+승인되지 않은 키의 `403 ACCESS_KEY_NOT_APPROVED`는 토큰 재발급·재시도 없이 반환합니다.
+계정 API의 `autoApprove`는 서버 설정의 실제 승인 정책을 나타냅니다.
+
+```python
+client.template_folders.list(template_type="notice")
+client.template_folders.create(name="주문 안내")
+client.template_folders.assign(
+    template_type="notice", kakao_sender_key=kakao_sender_key,
+    template_codes=["ORDER_001"], folder_uuid=None,
+)
+client.notice_templates.list(folder_uuid="none")
+# 템플릿 생성 시 folder_uuid=폴더_UUID를 선택 인자로 전달합니다.
+```

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/README.md

@@ -781,3 +781,56 @@ MIT License © 2026 [Sendgo](https://sendgo.io)
 ---
 
 *키워드: 카카오 알림톡 Python, 카카오 친구톡 Django, SMS 발송 FastAPI, 알림톡 SDK pip, Python 카카오 API 연동, Django 문자 발송, FastAPI 알림톡, Celery 알림톡 비동기, Sendgo Python SDK*
+
+## 계정·조직·API 키 관리 (1.5.0)
+
+발송용 `accessKey`/`secretKey`가 없는 단계에서 사용하는 **별도 계정 클라이언트**입니다.
+콘솔에서 발급받은 에이전트 토큰(`SENDGO_AGENT_TOKEN`)으로 `/api/v2/account`를 호출합니다.
+계정 조회에는 `account:read`, 키·허용 IP 변경에는 `keys:write` 권한이 필요합니다.
+토큰 만료나 권한 부족(401/403)은 그대로 예외로 반환하며 자동 갱신·재시도하지 않습니다.
+
+조직 선택은 서버에 저장되는 **사용자 계정의 현재 조직**을 바꿉니다. 같은 사용자로
+여러 조직의 설정을 동시에 변경하지 마세요. 개인 계정으로 돌아가려면 조직 ID에
+`null`(Python `None`, Ruby `nil`, Go `nil`) 또는 `personal`을 전달합니다.
+키 발급 응답의 `data.apiKey.secretKey`는 한 번만 반환되므로 서버의 비밀 저장소에 보관하세요.
+허용 IP가 하나라도 등록되면 목록 밖의 IP는 차단됩니다.
+에이전트 토큰과 키는 브라우저·모바일 앱에 포함하거나 응답·로그에 출력하지 않습니다.
+
+```python
+import os
+from sendgo import AccountClient
+account = AccountClient(agent_token=os.environ['SENDGO_AGENT_TOKEN'])
+result = account.me()
+account.select_organization('team-uuid')
+issued = account.create_api_key({'name': '서버 연동'})
+```
+
+지원 메서드: `me`, `organizations`, `select_organization`, `api_keys`, `create_api_key`, `api_key`, `update_api_key`, `delete_api_key`, `issue_token`, `allowed_ips`, `add_allowed_ip`, `delete_allowed_ip`.
+
+키 생성 인자는 `name`, 선택적 `ipAddresses: [{ip, description}]`이며, 허용 IP 추가 인자는 `ip`, 선택적 `description`입니다. 키·IP 식별자는 응답의 `id`(UUID)를 사용합니다.
+
+## 템플릿 폴더 (1.5.0)
+
+기업 계정의 발송용 API 키와 `apiVersion=v2` 설정으로 사용하는 서버 전용 API입니다.
+폴더는 알림톡·브랜드메시지가 공유하며, 목록의 `templateType`은 `notice` 또는 `brand`입니다.
+목록은 `data.folders` 트리와 `total`, `uncategorised` 개수를 반환합니다.
+`templateCount`는 하위 폴더를 제외한 해당 폴더의 템플릿 수입니다.
+
+- 생성: `name`, 선택 `parentUuid`. 최대 5단계이며 같은 부모 아래 이름 중복은 409입니다.
+- 이동: 동일 발신프로필의 `templateCodes` 1~100개. `folderUuid`는 필수이며 `null`이면 미분류로 이동합니다.
+- 템플릿 목록: `folderUuid=none`은 미분류, UUID는 해당 폴더, 생략은 전체입니다.
+- 템플릿 등록: 선택 필드 `folderUuid`로 폴더를 지정합니다. 기존 템플릿 수정 API 대신 폴더 이동 API를 사용하세요.
+
+승인되지 않은 키의 `403 ACCESS_KEY_NOT_APPROVED`는 토큰 재발급·재시도 없이 반환합니다.
+계정 API의 `autoApprove`는 서버 설정의 실제 승인 정책을 나타냅니다.
+
+```python
+client.template_folders.list(template_type="notice")
+client.template_folders.create(name="주문 안내")
+client.template_folders.assign(
+    template_type="notice", kakao_sender_key=kakao_sender_key,
+    template_codes=["ORDER_001"], folder_uuid=None,
+)
+client.notice_templates.list(folder_uuid="none")
+# 템플릿 생성 시 folder_uuid=폴더_UUID를 선택 인자로 전달합니다.
+```

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sendgo-python"
-version = "1.3.0"
+version = "1.5.0"
 description = "Sendgo Python SDK — 카카오 알림톡/브랜드메시지, SMS/LMS/MMS"
 readme = "README.md"
 license = {text = "MIT"}

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/sendgo/__init__.py

@@ -18,6 +18,7 @@ Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
     )
 """
 
+from .account import AccountClient
 from .brand_message import BrandMessageService
 from .brand_template import BrandTemplateService
 from .kakao_image import (
@@ -40,6 +41,7 @@ from .client import Sendgo
 from .exceptions import SendgoError
 
 __all__ = [
+    "AccountClient",
     "Sendgo",
     "SendgoError",
     "BrandMessageService",

sendgo_python-1.5.0/sendgo/account.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+import requests
+from .exceptions import SendgoError
+
+
+class AccountClient:
+    """서버 전용 계정 API. 에이전트 토큰은 자동 갱신하지 않는다."""
+
+    def __init__(self, *, agent_token: str, base_url: str = "https://sendgo.io") -> None:
+        if not agent_token or not agent_token.strip():
+            raise ValueError("Sendgo: agent_token은 필수입니다.")
+        self._agent_token = agent_token
+        self._base_url = base_url.rstrip("/")
+
+    def me(self) -> dict:
+        """계정 상태와 다음 단계 조회."""
+        return self._request("GET", f"")
+
+    def organizations(self) -> dict:
+        """조직 목록 조회."""
+        return self._request("GET", f"organizations")
+
+    def select_organization(self, organization_id: str | None) -> dict:
+        """조직 선택. null은 개인 계정."""
+        return self._request("POST", f"organizations/select", {'organizationId': organization_id})
+
+    def api_keys(self) -> dict:
+        """현재 조직의 API 키 목록."""
+        return self._request("GET", f"api-keys")
+
+    def create_api_key(self, params: dict) -> dict:
+        """API 키 발급. secretKey는 이 응답에서만 반환."""
+        return self._request("POST", f"api-keys", params)
+
+    def api_key(self, api_key_id: str) -> dict:
+        """API 키 상세 조회."""
+        return self._request("GET", f"api-keys/{quote(api_key_id, safe='')}")
+
+    def update_api_key(self, api_key_id: str, name: str) -> dict:
+        """API 키 이름 변경."""
+        return self._request("PATCH", f"api-keys/{quote(api_key_id, safe='')}", {'name': name})
+
+    def delete_api_key(self, api_key_id: str) -> dict:
+        """API 키 폐기."""
+        return self._request("DELETE", f"api-keys/{quote(api_key_id, safe='')}")
+
+    def issue_token(self, api_key_id: str) -> dict:
+        """승인된 API 키의 발송용 토큰 발급."""
+        return self._request("POST", f"api-keys/{quote(api_key_id, safe='')}/token", {})
+
+    def allowed_ips(self, api_key_id: str) -> dict:
+        """허용 IP 목록과 호출자 IP 조회."""
+        return self._request("GET", f"api-keys/{quote(api_key_id, safe='')}/allowed-ips")
+
+    def add_allowed_ip(self, api_key_id: str, params: dict) -> dict:
+        """허용 IP 추가. ip와 선택적 description 사용."""
+        return self._request("POST", f"api-keys/{quote(api_key_id, safe='')}/allowed-ips", params)
+
+    def delete_allowed_ip(self, api_key_id: str, ip_id: str) -> dict:
+        """허용 IP 삭제."""
+        return self._request("DELETE", f"api-keys/{quote(api_key_id, safe='')}/allowed-ips/{quote(ip_id, safe='')}")
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> dict:
+        response = requests.request(
+            method, f"{self._base_url}/api/v2/account" + (f"/{path}" if path else ""),
+            headers={"Authorization": f"Bearer {self._agent_token}", "Accept": "application/json"},
+            json=body, timeout=15, allow_redirects=False,
+        )
+        try:
+            data = response.json() if response.content else {}
+        except ValueError:
+            data = {}
+        if not 200 <= response.status_code < 300:
+            raise SendgoError.from_response(response.status_code, data, path or "account", "v2")
+        return data

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/sendgo/brand_template.py

@@ -43,11 +43,12 @@ class BrandTemplateService:
         kakao_sender_key: str | None = None,
         search: str | None = None,
         count: int | None = None,
+        folder_uuid: str | None = None,
     ) -> dict[str, Any]:
         """목록 조회."""
         return self._http.get(
             self._RESOURCE,
-            {"kakaoSenderKey": kakao_sender_key, "search": search, "count": count},
+            {"folderUuid": folder_uuid, "kakaoSenderKey": kakao_sender_key, "search": search, "count": count},
         )
 
     def show(self, template_code: str) -> dict[str, Any]:

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/sendgo/client.py

@@ -15,6 +15,7 @@ from .short_url import ShortUrlService
 from .sms import SmsService
 from .token_manager import TokenManager
 from .webhook import WebhookService
+from .template_folder import TemplateFolderService
 
 
 class Sendgo:
@@ -66,9 +67,13 @@ class Sendgo:
 
         # ------------------------------------------------------ 관리 API (v2)
         # 콘솔에서만 되던 등록·심사. 발송과 달리 대부분 즉시 완료되지 않는다 —
-        # 등록 성공은 "접수됨"이지 "사용 가능"이 아니다.
-        # 카카오 채널 등록의 인증번호와 휴대폰 발신번호의 본인인증은 사람이
-        # 개입해야 하므로 API 로 대체되지 않는다.
+        # 등록 성공은 "접수됨"이지 "사용 가능"이 아니다. 결과는 웹훅으로 받는다.
+        #
+        # 사람이 개입하는 지점은 카카오 채널 인증번호 하나뿐이고, 그마저도
+        # 여러분 화면에서 끝난다 — request_token() 이 채널 관리자 휴대폰으로
+        # SMS 를 보내고, 사용자가 입력한 코드를 create() 가 받는다. 휴대폰
+        # 발신번호는 PASS 대신 신분증 사본을 첨부해 접수하면 sendgo 가 대신
+        # 심사한다.
         self.kakao_senders       = KakaoSenderService(http)
         self.notice_templates    = NoticeTemplateService(http)
         self.brand_templates     = BrandTemplateService(http)
@@ -77,3 +82,4 @@ class Sendgo:
         self.kakao_images        = KakaoImageService(http)
         self.rejected_numbers    = RejectedNumberService(http)
         self.webhook             = WebhookService(http)
+        self.template_folders    = TemplateFolderService(http)

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/sendgo/notice_template.py

@@ -52,11 +52,13 @@ class NoticeTemplateService:
         inspection_status: str | None = None,
         search: str | None = None,
         count: int | None = None,
+        folder_uuid: str | None = None,
     ) -> dict[str, Any]:
         """목록 조회."""
         return self._http.get(
             self._RESOURCE,
             {
+                "folderUuid": folder_uuid,
                 "kakaoSenderKey": kakao_sender_key,
                 "inspectionStatus": inspection_status,
                 "search": search,

sendgo_python-1.5.0/sendgo/template_folder.py

@@ -0,0 +1,25 @@
+"""템플릿 공용 폴더. v2 전용, 기업 계정 전용."""
+from __future__ import annotations
+from typing import Any, Literal
+from .http_client import HttpClient
+
+class TemplateFolderService:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, *, template_type: Literal["notice", "brand"] | None = None,
+             kakao_sender_key: str | None = None) -> dict[str, Any]:
+        """폴더 트리와 유형별 템플릿 수를 조회합니다."""
+        return self._http.get("template-folders", {"templateType": template_type, "kakaoSenderKey": kakao_sender_key})
+
+    def create(self, *, name: str, parent_uuid: str | None = None) -> dict[str, Any]:
+        """루트 또는 하위 폴더를 생성합니다."""
+        return self._http.post("template-folders", {"name": name, "parentUuid": parent_uuid})
+
+    def assign(self, *, template_type: Literal["notice", "brand"], kakao_sender_key: str,
+               template_codes: list[str], folder_uuid: str | None) -> dict[str, Any]:
+        """1~100개 템플릿을 이동합니다. None이면 미분류로 이동합니다."""
+        return self._http.patch("template-folders/templates", {
+            "templateType": template_type, "kakaoSenderKey": kakao_sender_key,
+            "templateCodes": template_codes, "folderUuid": folder_uuid,
+        })

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/sendgo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendgo-python
-Version: 1.3.0
+Version: 1.5.0
 Summary: Sendgo Python SDK — 카카오 알림톡/브랜드메시지, SMS/LMS/MMS
 Author-email: Sendgo <dev@sendgo.io>
 License: MIT
@@ -808,3 +808,56 @@ MIT License © 2026 [Sendgo](https://sendgo.io)
 ---
 
 *키워드: 카카오 알림톡 Python, 카카오 친구톡 Django, SMS 발송 FastAPI, 알림톡 SDK pip, Python 카카오 API 연동, Django 문자 발송, FastAPI 알림톡, Celery 알림톡 비동기, Sendgo Python SDK*
+
+## 계정·조직·API 키 관리 (1.5.0)
+
+발송용 `accessKey`/`secretKey`가 없는 단계에서 사용하는 **별도 계정 클라이언트**입니다.
+콘솔에서 발급받은 에이전트 토큰(`SENDGO_AGENT_TOKEN`)으로 `/api/v2/account`를 호출합니다.
+계정 조회에는 `account:read`, 키·허용 IP 변경에는 `keys:write` 권한이 필요합니다.
+토큰 만료나 권한 부족(401/403)은 그대로 예외로 반환하며 자동 갱신·재시도하지 않습니다.
+
+조직 선택은 서버에 저장되는 **사용자 계정의 현재 조직**을 바꿉니다. 같은 사용자로
+여러 조직의 설정을 동시에 변경하지 마세요. 개인 계정으로 돌아가려면 조직 ID에
+`null`(Python `None`, Ruby `nil`, Go `nil`) 또는 `personal`을 전달합니다.
+키 발급 응답의 `data.apiKey.secretKey`는 한 번만 반환되므로 서버의 비밀 저장소에 보관하세요.
+허용 IP가 하나라도 등록되면 목록 밖의 IP는 차단됩니다.
+에이전트 토큰과 키는 브라우저·모바일 앱에 포함하거나 응답·로그에 출력하지 않습니다.
+
+```python
+import os
+from sendgo import AccountClient
+account = AccountClient(agent_token=os.environ['SENDGO_AGENT_TOKEN'])
+result = account.me()
+account.select_organization('team-uuid')
+issued = account.create_api_key({'name': '서버 연동'})
+```
+
+지원 메서드: `me`, `organizations`, `select_organization`, `api_keys`, `create_api_key`, `api_key`, `update_api_key`, `delete_api_key`, `issue_token`, `allowed_ips`, `add_allowed_ip`, `delete_allowed_ip`.
+
+키 생성 인자는 `name`, 선택적 `ipAddresses: [{ip, description}]`이며, 허용 IP 추가 인자는 `ip`, 선택적 `description`입니다. 키·IP 식별자는 응답의 `id`(UUID)를 사용합니다.
+
+## 템플릿 폴더 (1.5.0)
+
+기업 계정의 발송용 API 키와 `apiVersion=v2` 설정으로 사용하는 서버 전용 API입니다.
+폴더는 알림톡·브랜드메시지가 공유하며, 목록의 `templateType`은 `notice` 또는 `brand`입니다.
+목록은 `data.folders` 트리와 `total`, `uncategorised` 개수를 반환합니다.
+`templateCount`는 하위 폴더를 제외한 해당 폴더의 템플릿 수입니다.
+
+- 생성: `name`, 선택 `parentUuid`. 최대 5단계이며 같은 부모 아래 이름 중복은 409입니다.
+- 이동: 동일 발신프로필의 `templateCodes` 1~100개. `folderUuid`는 필수이며 `null`이면 미분류로 이동합니다.
+- 템플릿 목록: `folderUuid=none`은 미분류, UUID는 해당 폴더, 생략은 전체입니다.
+- 템플릿 등록: 선택 필드 `folderUuid`로 폴더를 지정합니다. 기존 템플릿 수정 API 대신 폴더 이동 API를 사용하세요.
+
+승인되지 않은 키의 `403 ACCESS_KEY_NOT_APPROVED`는 토큰 재발급·재시도 없이 반환합니다.
+계정 API의 `autoApprove`는 서버 설정의 실제 승인 정책을 나타냅니다.
+
+```python
+client.template_folders.list(template_type="notice")
+client.template_folders.create(name="주문 안내")
+client.template_folders.assign(
+    template_type="notice", kakao_sender_key=kakao_sender_key,
+    template_codes=["ORDER_001"], folder_uuid=None,
+)
+client.notice_templates.list(folder_uuid="none")
+# 템플릿 생성 시 folder_uuid=폴더_UUID를 선택 인자로 전달합니다.
+```

{sendgo_python-1.3.0 → sendgo_python-1.5.0}/sendgo_python.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ README.md
 pyproject.toml
 sendgo/__init__.py
 sendgo/_payload.py
+sendgo/account.py
 sendgo/alimtalk.py
 sendgo/brand_message.py
 sendgo/brand_template.py
@@ -17,6 +18,7 @@ sendgo/rejected_number.py
 sendgo/sender_registration.py
 sendgo/short_url.py
 sendgo/sms.py
+sendgo/template_folder.py
 sendgo/token_manager.py
 sendgo/webhook.py
 sendgo_python.egg-info/PKG-INFO