sendgo-python 1.0.1__tar.gz → 1.1.0__tar.gz

{sendgo_python-1.0.1 → sendgo_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendgo-python
-Version: 1.0.1
+Version: 1.1.0
 Summary: Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
 Author-email: Sendgo <dev@sendgo.io>
 License: MIT
@@ -232,6 +232,42 @@ client.sms.send_mms(
 
 ---
 
+## 브랜드메시지 사용법
+
+브랜드메시지는 친구톡의 후속 채널입니다. 메시지 타입이 친구톡과 1:1 대응되며
+(`FT`→`BT`, `FI`→`BI`, `FW`→`BW`, `FL`→`BL`, `FC`→`BC`, `FM`→`BM`, `FP`→`BP`, `FA`→`BA`),
+요청에는 **친구톡 코드를 그대로** 넘기고 변환은 서버가 처리합니다.
+
+친구톡과 달리 다음이 가능합니다.
+
+- 채널 친구가 **아닌** 수신자에게 발송 (`targeting: N`)
+- 수신 동의한 **전체 채널 친구 동보** 발송 (`targeting: F`, 수신자 목록 불필요)
+- 리스트·캐러셀·커머스·동영상 등 **템플릿 기반 리치 메시지**
+
+> v2 전용입니다. `FT`/`FI`/`FW`를 채널 친구에게만 보낼 때는 친구톡 API가 더 간단합니다.
+
+```python
+# 단건 발송 — 채널 친구 대상
+client.brand_message.send(
+    targeting="M",
+    message_type="FL",
+    friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
+    contacts=[{"contact": "01012345678", "var1": "29,000원"}],
+)
+
+# 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 불필요)
+client.brand_message.broadcast(
+    message_type="FW",
+    friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
+)
+
+# 캠페인 조회 (from 은 예약어이므로 from_ 사용)
+campaigns = client.brand_message.campaigns(from_="2026-08-01", count=10)
+one = client.brand_message.campaign("1f0a6d0e-6b3b-4f0f-9b2f-2f6f6a1b7c11")
+```
+
+---
+
 ## 프레임워크 통합
 
 ### Django

{sendgo_python-1.0.1 → sendgo_python-1.1.0}/README.md

@@ -205,6 +205,42 @@ client.sms.send_mms(
 
 ---
 
+## 브랜드메시지 사용법
+
+브랜드메시지는 친구톡의 후속 채널입니다. 메시지 타입이 친구톡과 1:1 대응되며
+(`FT`→`BT`, `FI`→`BI`, `FW`→`BW`, `FL`→`BL`, `FC`→`BC`, `FM`→`BM`, `FP`→`BP`, `FA`→`BA`),
+요청에는 **친구톡 코드를 그대로** 넘기고 변환은 서버가 처리합니다.
+
+친구톡과 달리 다음이 가능합니다.
+
+- 채널 친구가 **아닌** 수신자에게 발송 (`targeting: N`)
+- 수신 동의한 **전체 채널 친구 동보** 발송 (`targeting: F`, 수신자 목록 불필요)
+- 리스트·캐러셀·커머스·동영상 등 **템플릿 기반 리치 메시지**
+
+> v2 전용입니다. `FT`/`FI`/`FW`를 채널 친구에게만 보낼 때는 친구톡 API가 더 간단합니다.
+
+```python
+# 단건 발송 — 채널 친구 대상
+client.brand_message.send(
+    targeting="M",
+    message_type="FL",
+    friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
+    contacts=[{"contact": "01012345678", "var1": "29,000원"}],
+)
+
+# 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 불필요)
+client.brand_message.broadcast(
+    message_type="FW",
+    friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
+)
+
+# 캠페인 조회 (from 은 예약어이므로 from_ 사용)
+campaigns = client.brand_message.campaigns(from_="2026-08-01", count=10)
+one = client.brand_message.campaign("1f0a6d0e-6b3b-4f0f-9b2f-2f6f6a1b7c11")
+```
+
+---
+
 ## 프레임워크 통합
 
 ### Django

{sendgo_python-1.0.1 → sendgo_python-1.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sendgo-python"
-version = "1.0.1"
+version = "1.1.0"
 description = "Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS"
 readme = "README.md"
 license = {text = "MIT"}

sendgo_python-1.1.0/sendgo/__init__.py

@@ -0,0 +1,34 @@
+"""
+Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
+
+사용법:
+    from sendgo import Sendgo
+
+    client = Sendgo(
+        access_key="your_access_key",
+        secret_key="your_secret_key",
+        kakao_sender_key="your_kakao_key",
+        sms_sender_key="your_sms_key",
+        api_version="v2",
+    )
+
+    client.alimtalk.send(
+        template_code="ORDER_CONFIRM_001",
+        contacts=[{"contact": "01012345678", "var1": "ORD-001"}],
+    )
+"""
+
+from .brand_message import BrandMessageService
+from .short_url import ShortUrlService
+from .client import Sendgo
+from .exceptions import SendgoError
+
+__all__ = ["Sendgo", "SendgoError", "BrandMessageService", "ShortUrlService"]
+try:
+    from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+    # 버전은 pyproject.toml 이 단일 출처다. 여기에 값을 또 적으면
+    # 릴리스마다 두 곳을 맞춰야 하고, 실제로 어긋난 적이 있다.
+    __version__ = _pkg_version("sendgo-python")
+except PackageNotFoundError:  # 설치되지 않은 소스 트리에서 import 한 경우
+    __version__ = "0.0.0.dev0"

sendgo_python-1.1.0/sendgo/brand_message.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from .http_client import HttpClient
+
+BrandMessageType = Literal["FT", "FI", "FW", "FL", "FM", "FC", "FA", "FP"]
+BrandMessageTargeting = Literal["M", "N", "I", "F"]
+
+
+class BrandMessageService:
+    """카카오 브랜드메시지 전송 서비스.
+
+    브랜드메시지는 친구톡의 후속 채널로, 메시지 타입이 친구톡과 1:1 대응됩니다
+    (FT→BT, FI→BI, FW→BW, FL→BL, FC→BC, FM→BM, FP→BP, FA→BA).
+    ``message_type`` 에는 친구톡 코드를 그대로 넘기고, 변환은 서버가 처리합니다.
+
+    친구톡과 달리 채널 친구가 아닌 수신자에게도 보낼 수 있고(``targeting="N"``),
+    수신 동의한 전체 채널 친구에게 동보 발송할 수 있습니다(``targeting="F"``).
+
+    Example::
+
+        # 단건 발송 — 채널 친구 대상
+        client.brand_message.send(
+            targeting="M",
+            message_type="FL",
+            friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
+            contacts=[{"contact": "01012345678", "var1": "29,000원"}],
+        )
+
+        # 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 불필요)
+        client.brand_message.broadcast(
+            message_type="FW",
+            friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
+        )
+    """
+
+    def __init__(self, http: HttpClient, kakao_sender_key: str | None, sms_sender_key: str | None) -> None:
+        self._http = http
+        self._kakao_sender_key = kakao_sender_key
+        self._sms_sender_key = sms_sender_key
+
+    def send(
+        self,
+        *,
+        friend_template_uuid: str,
+        message_type: BrandMessageType = "FT",
+        targeting: BrandMessageTargeting = "M",
+        contacts: list[dict] | None = None,
+        content: str | None = None,
+        schedule_type: Literal["DIRECTLY", "SCHEDULED"] = "DIRECTLY",
+        at: str | None = None,
+        buttons: list[dict] | None = None,
+        image_url: str | None = None,
+        image_link: str | None = None,
+        ad_flag: Literal["Y", "N"] = "Y",
+        adult: Literal["Y", "N"] = "N",
+        push_alarm: Literal["Y", "N"] = "Y",
+        header: str | None = None,
+        coupon: dict | None = None,
+        item: dict | None = None,
+        commerce: dict | None = None,
+        list_: list[dict] | None = None,
+        head: dict | None = None,
+        tail: dict | None = None,
+        video: dict | None = None,
+        additional_content: str | None = None,
+        friend_group_key: str | None = None,
+        replace_sms: Literal["Y", "N"] = "N",
+        sms_subject: str | None = None,
+        sms_content: str | None = None,
+        reject_service_id: str | None = None,
+        webhooks: list[str] | None = None,
+    ) -> dict:
+        """브랜드메시지를 전송합니다.
+
+        ``targeting`` 이 ``"M"`` / ``"N"`` / ``"I"`` 이면 ``contacts`` 가 필요하고
+        응답 ``data`` 에 발송 건수(``sentCount``)가 담깁니다. ``"F"`` 는 동보 발송이라
+        ``contacts`` 없이 접수 여부(``accepted``)만 반환됩니다 — 그 경우
+        :meth:`broadcast` 가 더 명확합니다.
+
+        ``list_`` 는 파이썬 내장 ``list`` 와 충돌을 피하기 위한 이름이며,
+        요청에는 ``list`` 로 전송됩니다.
+        """
+        body: dict[str, Any] = {
+            "at": at,
+            "scheduleType": schedule_type,
+            "targeting": targeting,
+            "messageType": message_type,
+            "friendTemplateUuid": friend_template_uuid,
+            "content": content,
+            "buttons": buttons or [],
+            "imageUrl": image_url,
+            "imageLink": image_link,
+            "adFlag": ad_flag,
+            "adult": adult,
+            "pushAlarm": push_alarm,
+            "header": header,
+            "coupon": coupon,
+            "item": item,
+            "commerce": commerce,
+            "list": list_,
+            "head": head,
+            "tail": tail,
+            "video": video,
+            "additionalContent": additional_content,
+            "friendGroupKey": friend_group_key,
+            "replaceSms": replace_sms,
+            "smsSubject": sms_subject if replace_sms == "Y" else None,
+            "smsContent": sms_content if replace_sms == "Y" else None,
+            "rejectServiceId": reject_service_id,
+            "webhooks": webhooks or [],
+            "kakaoSenderKey": self._kakao_sender_key,
+            "senderKey": self._sms_sender_key,
+        }
+
+        # A broadcast has no recipient list; sending an empty ``contacts`` would be
+        # rejected as an invalid request, so the key is omitted entirely.
+        if targeting != "F":
+            body["contacts"] = contacts or []
+
+        return self._http.post("brand-messages/send", body)
+
+    def broadcast(self, **kwargs: Any) -> dict:
+        """동보 발송 — 수신 동의한 전체 채널 친구 (``targeting="F"``).
+
+        수신자 목록은 카카오 측에서 확장하므로 ``contacts`` 를 넘기지 않습니다.
+        결과는 :meth:`campaigns` / :meth:`campaign` 으로 확인합니다.
+        """
+        kwargs.pop("contacts", None)
+        kwargs["targeting"] = "F"
+
+        return self.send(**kwargs)
+
+    def campaigns(
+        self,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+        count: int | None = None,
+    ) -> dict:
+        """브랜드메시지 캠페인 목록을 조회합니다.
+
+        ``from_`` 은 파이썬 예약어 ``from`` 을 피하기 위한 이름이며,
+        요청에는 ``from`` 으로 전송됩니다.
+        """
+        return self._http.get(
+            "brand-messages",
+            {"from": from_, "to": to, "count": count},
+        )
+
+    def campaign(self, campaign_id: str) -> dict:
+        """브랜드메시지 캠페인 상세를 조회합니다.
+
+        :param campaign_id: 발송 응답의 ``campaignId`` (UUID)
+        """
+        return self._http.get(f"brand-messages/{campaign_id}")

{sendgo_python-1.0.1 → sendgo_python-1.1.0}/sendgo/client.py

@@ -1,8 +1,10 @@
 from __future__ import annotations
 
 from .alimtalk import AlimtalkService
+from .brand_message import BrandMessageService
 from .friendtalk import FriendtalkService
 from .http_client import HttpClient
+from .short_url import ShortUrlService
 from .sms import SmsService
 from .token_manager import TokenManager
 
@@ -45,6 +47,10 @@ class Sendgo:
         token_manager = TokenManager(base_url, access_key, secret_key, api_version)
         http = HttpClient(token_manager, base_url, api_version)
 
-        self.alimtalk   = AlimtalkService(http, kakao_sender_key, sms_sender_key)
-        self.friendtalk = FriendtalkService(http, kakao_sender_key, sms_sender_key)
-        self.sms        = SmsService(http, sms_sender_key)
+        self.alimtalk      = AlimtalkService(http, kakao_sender_key, sms_sender_key)
+        self.friendtalk    = FriendtalkService(http, kakao_sender_key, sms_sender_key)
+        # 카카오 브랜드메시지 — 친구톡의 후속 채널. v2 전용.
+        self.brand_message = BrandMessageService(http, kakao_sender_key, sms_sender_key)
+        # 짧은 URL — 링크 단축과 클릭 반응 분석. v2 전용.
+        self.short_url     = ShortUrlService(http)
+        self.sms           = SmsService(http, sms_sender_key)

{sendgo_python-1.0.1 → sendgo_python-1.1.0}/sendgo/http_client.py

@@ -17,15 +17,34 @@ class HttpClient:
         self._session.headers.update({"Content-Type": "application/json"})
 
     def post(self, path: str, body: dict) -> dict:
-        return self._do_post(path, body, is_retry=False)
+        return self._request("POST", path, body=body, is_retry=False)
 
-    def _do_post(self, path: str, body: dict, *, is_retry: bool) -> dict:
+    def get(self, path: str, params: dict | None = None) -> dict:
+        """GET request, used by the campaign lookup endpoints."""
+        return self._request("GET", path, params=params, is_retry=False)
+
+    def delete(self, path: str) -> dict:
+        """`_request()` drives the verb, so DELETE only needs to skip the body."""
+        return self._request("DELETE", path, is_retry=False)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict | None = None,
+        params: dict | None = None,
+        is_retry: bool,
+    ) -> dict:
         url = f"{self._base_url}/api/{self._api_version}/{path}"
         token = self._token_manager.get_token()
 
-        resp = self._session.post(
+        resp = self._session.request(
+            method,
             url,
             json=body,
+            # Drop unset filters so the server applies its own defaults.
+            params={k: v for k, v in (params or {}).items() if v is not None} or None,
             headers={"Authorization": self._make_bearer(token)},
             timeout=15,
         )
@@ -37,7 +56,7 @@ class HttpClient:
             endpoint = path.split("/")[-1]
             if not is_retry and self._token_manager.should_refresh(resp.status_code, error_code):
                 self._token_manager.invalidate()
-                return self._do_post(path, body, is_retry=True)
+                return self._request(method, path, body=body, params=params, is_retry=True)
             raise SendgoError.from_response(resp.status_code, response_body, endpoint, self._api_version)
 
         return response_body

sendgo_python-1.1.0/sendgo/short_url.py

@@ -0,0 +1,86 @@
+"""짧은 URL — 메시지에 넣는 링크를 줄이고 클릭 반응을 집계한다."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .http_client import HttpClient
+
+
+class ShortUrlService:
+    """짧은 URL 서비스. v2 전용이다.
+
+    Example:
+        created = client.short_url.create(
+            target_url="https://example.com/promotions/summer-sale",
+            title="여름 세일 랜딩",
+        )
+
+        # created["data"]["shortUrl"] 를 문자/알림톡 본문에 넣는다.
+        stats = client.short_url.stats(created["data"]["code"])
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(
+        self,
+        *,
+        target_url: str,
+        title: str | None = None,
+        expires_at: str | None = None,
+        force_new: bool = False,
+    ) -> dict[str, Any]:
+        """짧은 URL 을 만든다.
+
+        같은 원본 URL 을 다시 줄이면 기존 링크가 그대로 반환된다.
+        캠페인별로 반응을 분리해 집계하려면 ``force_new=True`` 를 쓴다.
+        """
+        body: dict[str, Any] = {"targetUrl": target_url, "forceNew": force_new}
+
+        if title is not None:
+            body["title"] = title
+        if expires_at is not None:
+            body["expiresAt"] = expires_at
+
+        return self._http.post("short-urls", body)
+
+    def list(
+        self,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+        count: int | None = None,
+    ) -> dict[str, Any]:
+        """목록 조회. ``from`` 은 파이썬 예약어이므로 ``from_`` 을 쓴다."""
+        params = {"from": from_, "to": to, "count": count}
+
+        return self._http.get("short-urls", {k: v for k, v in params.items() if v is not None})
+
+    def show(self, code: str) -> dict[str, Any]:
+        """상세 조회."""
+        return self._http.get(f"short-urls/{quote(code, safe='')}")
+
+    def stats(
+        self,
+        code: str,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+    ) -> dict[str, Any]:
+        """반응 통계. 일별 추이와 디바이스/유입경로/국가별 분해를 반환한다."""
+        params = {"from": from_, "to": to}
+
+        return self._http.get(
+            f"short-urls/{quote(code, safe='')}/stats",
+            {k: v for k, v in params.items() if v is not None},
+        )
+
+    def deactivate(self, code: str) -> dict[str, Any]:
+        """리다이렉트를 중지한다.
+
+        링크는 삭제되지 않고 누적 통계도 남는다. 이후 그 링크로 들어오면
+        410 Gone 이 반환된다.
+        """
+        return self._http.delete(f"short-urls/{quote(code, safe='')}")

{sendgo_python-1.0.1 → sendgo_python-1.1.0}/sendgo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendgo-python
-Version: 1.0.1
+Version: 1.1.0
 Summary: Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
 Author-email: Sendgo <dev@sendgo.io>
 License: MIT
@@ -232,6 +232,42 @@ client.sms.send_mms(
 
 ---
 
+## 브랜드메시지 사용법
+
+브랜드메시지는 친구톡의 후속 채널입니다. 메시지 타입이 친구톡과 1:1 대응되며
+(`FT`→`BT`, `FI`→`BI`, `FW`→`BW`, `FL`→`BL`, `FC`→`BC`, `FM`→`BM`, `FP`→`BP`, `FA`→`BA`),
+요청에는 **친구톡 코드를 그대로** 넘기고 변환은 서버가 처리합니다.
+
+친구톡과 달리 다음이 가능합니다.
+
+- 채널 친구가 **아닌** 수신자에게 발송 (`targeting: N`)
+- 수신 동의한 **전체 채널 친구 동보** 발송 (`targeting: F`, 수신자 목록 불필요)
+- 리스트·캐러셀·커머스·동영상 등 **템플릿 기반 리치 메시지**
+
+> v2 전용입니다. `FT`/`FI`/`FW`를 채널 친구에게만 보낼 때는 친구톡 API가 더 간단합니다.
+
+```python
+# 단건 발송 — 채널 친구 대상
+client.brand_message.send(
+    targeting="M",
+    message_type="FL",
+    friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
+    contacts=[{"contact": "01012345678", "var1": "29,000원"}],
+)
+
+# 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 불필요)
+client.brand_message.broadcast(
+    message_type="FW",
+    friend_template_uuid="9cd5460b-6458-4edc-9b11-c26d3013c340",
+)
+
+# 캠페인 조회 (from 은 예약어이므로 from_ 사용)
+campaigns = client.brand_message.campaigns(from_="2026-08-01", count=10)
+one = client.brand_message.campaign("1f0a6d0e-6b3b-4f0f-9b2f-2f6f6a1b7c11")
+```
+
+---
+
 ## 프레임워크 통합
 
 ### Django

{sendgo_python-1.0.1 → sendgo_python-1.1.0}/sendgo_python.egg-info/SOURCES.txt

@@ -2,10 +2,12 @@ README.md
 pyproject.toml
 sendgo/__init__.py
 sendgo/alimtalk.py
+sendgo/brand_message.py
 sendgo/client.py
 sendgo/exceptions.py
 sendgo/friendtalk.py
 sendgo/http_client.py
+sendgo/short_url.py
 sendgo/sms.py
 sendgo/token_manager.py
 sendgo_python.egg-info/PKG-INFO

sendgo_python-1.0.1/sendgo/__init__.py

@@ -1,25 +0,0 @@
-"""
-Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
-
-사용법:
-    from sendgo import Sendgo
-
-    client = Sendgo(
-        access_key="your_access_key",
-        secret_key="your_secret_key",
-        kakao_sender_key="your_kakao_key",
-        sms_sender_key="your_sms_key",
-        api_version="v2",
-    )
-
-    client.alimtalk.send(
-        template_code="ORDER_CONFIRM_001",
-        contacts=[{"contact": "01012345678", "var1": "ORD-001"}],
-    )
-"""
-
-from .client import Sendgo
-from .exceptions import SendgoError
-
-__all__ = ["Sendgo", "SendgoError"]
-__version__ = "1.0.0"