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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendgo-python
-Version: 1.0.1
+Version: 1.2.0
 Summary: Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
 Author-email: Sendgo <dev@sendgo.io>
 License: MIT
@@ -27,7 +27,7 @@ Requires-Dist: httpx>=0.27; extra == "async"
 
 # sendgo-python
 
-> **Python / Django / FastAPI에서 카카오 알림톡, 친구톡, SMS를 가장 쉽게 발송하는 SDK**
+> **Python / Django / FastAPI에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 SDK**
 
 [![PyPI version](https://img.shields.io/pypi/v/sendgo-python?logo=pypi)](https://pypi.org/project/sendgo-python/)
 [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python)](https://python.org)
@@ -184,6 +184,19 @@ client.alimtalk.send(
 
 ### 카카오 친구톡
 
+> ⚠️ **Deprecated — 친구톡은 카카오 정책에 따라 2025-12-31 종료되었습니다.**
+> 2026-01-01 부터 친구톡 발송 요청은 카카오 측에서 **브랜드메시지(자유형)** 로 자동 대체 발송됩니다.
+> 호출은 계속 성공하며, 자유 본문 타입(`FT`/`FI`/`FW`)을 개별 수신자에게 보내는 경로는
+> 현재 이것뿐이므로 기존 코드를 당장 바꿀 필요는 없습니다.
+>
+> 다음의 경우에는 **브랜드메시지**를 사용하세요.
+> - 템플릿 기반 리치 타입 (`FL`/`FC`/`FM`/`FP`/`FA`)
+> - 채널 친구가 **아닌** 수신자 (`targeting` = `N` / `I`)
+> - 수신 동의한 전체 채널 친구 동보 (`targeting` = `F`)
+>
+> 메시지 타입은 1:1 대응되며 변환은 서버가 처리합니다 — `FT`→`BT`, `FI`→`BI`, `FW`→`BW`,
+> `FL`→`BL`, `FC`→`BC`, `FM`→`BM`, `FP`→`BP`, `FA`→`BA`.
+
 ```python
 # 텍스트형
 client.friendtalk.send(
@@ -232,6 +245,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 를 쓰세요 — 이 엔드포인트는 그 조합에 `NOT_A_BRAND_MESSAGE` 를 반환합니다. 친구톡 요청은 카카오 측에서 브랜드메시지(자유형)로 대체 발송됩니다.
+
+```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
@@ -419,6 +468,56 @@ A. Sendgo 플랜별로 TPS 제한이 있습니다. [요금 정책](https://sendg
 
 ---
 
+## 짧은 URL
+
+짧은 URL 은 메시지 본문의 링크를 줄이고, 그 링크가 실제로 눌렸는지 집계합니다.
+문자는 바이트 수가 요금과 직결되므로 링크를 줄이면 그만큼 본문을 더 쓸 수 있습니다.
+
+같은 원본 URL 을 다시 줄이면 **기존 링크가 그대로 반환**됩니다. 캠페인별로 반응을
+따로 집계하려면 `forceNew` 로 새 코드를 만드세요.
+
+`deactivate` 는 링크를 삭제하지 않고 리다이렉트만 중지합니다. 이미 발송한 메시지의
+링크를 무효화할 때 쓰며, 누적 통계는 남고 이후 접속은 `410 Gone` 이 됩니다.
+
+```python
+# 짧은 URL 생성 (v2 전용)
+created = sendgo.short_url.create(
+    target_url="https://example.com/promotions/summer-sale",
+    title="여름 세일 랜딩",
+)
+
+code = created["data"]["code"]
+link = created["data"]["shortUrl"]
+
+# 반응 통계 — 일별 추이 + 디바이스/유입경로/국가별 분해
+# `from` 은 파이썬 예약어이므로 `from_` 을 쓴다
+stats = sendgo.short_url.stats(code, from_="2026-08-01")
+
+sendgo.short_url.list(count=10)
+sendgo.short_url.show(code)
+sendgo.short_url.deactivate(code)   # 리다이렉트만 중지, 통계는 남는다
+```
+
+`stats` 는 일별 추이(`daily`)와 디바이스(`byDevice`)·유입경로(`byReferer`)·국가(`byCountry`)별
+분해를 반환합니다. 일별 추이는 사전 집계 표에서 읽으므로 클릭이 많아도 응답 시간이 일정합니다.
+
+## 변경 사항
+
+### 1.2.0 (2026-08-14)
+
+- **친구톡 Deprecated 표기** — 친구톡은 카카오 정책에 따라 2025-12-31 종료되었고,
+  2026-01-01 부터 발송 요청이 브랜드메시지(자유형)로 자동 대체 발송됩니다.
+  관련 API 에 각 언어의 표준 deprecation 표기를 달았습니다.
+- 자유 본문 타입(`FT`/`FI`/`FW`)의 개별 발송 경로는 아직 친구톡 API 뿐이라는 점을
+  문서에 명시했습니다 — 브랜드메시지 API 는 그 조합에 `NOT_A_BRAND_MESSAGE` 를 반환합니다.
+- 브랜드메시지 전환 안내와 메시지 타입 1:1 대응표를 README 에 추가했습니다.
+
+### 1.1.0 (2026-08-11)
+
+- 짧은 URL 추가 — `client.short_url`
+- `HttpClient.delete()` 추가
+- **버전 단일화** — `__init__.py` 에 하드코딩된 `__version__` 을 제거하고 `importlib.metadata` 로 `pyproject.toml` 값을 읽는다. 두 곳이 어긋나 릴리스가 실패한 적이 있다.
+
 ## 라이선스
 
 MIT License © 2026 [Sendgo](https://sendgo.io)

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

@@ -1,6 +1,6 @@
 # sendgo-python
 
-> **Python / Django / FastAPI에서 카카오 알림톡, 친구톡, SMS를 가장 쉽게 발송하는 SDK**
+> **Python / Django / FastAPI에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 SDK**
 
 [![PyPI version](https://img.shields.io/pypi/v/sendgo-python?logo=pypi)](https://pypi.org/project/sendgo-python/)
 [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python)](https://python.org)
@@ -157,6 +157,19 @@ client.alimtalk.send(
 
 ### 카카오 친구톡
 
+> ⚠️ **Deprecated — 친구톡은 카카오 정책에 따라 2025-12-31 종료되었습니다.**
+> 2026-01-01 부터 친구톡 발송 요청은 카카오 측에서 **브랜드메시지(자유형)** 로 자동 대체 발송됩니다.
+> 호출은 계속 성공하며, 자유 본문 타입(`FT`/`FI`/`FW`)을 개별 수신자에게 보내는 경로는
+> 현재 이것뿐이므로 기존 코드를 당장 바꿀 필요는 없습니다.
+>
+> 다음의 경우에는 **브랜드메시지**를 사용하세요.
+> - 템플릿 기반 리치 타입 (`FL`/`FC`/`FM`/`FP`/`FA`)
+> - 채널 친구가 **아닌** 수신자 (`targeting` = `N` / `I`)
+> - 수신 동의한 전체 채널 친구 동보 (`targeting` = `F`)
+>
+> 메시지 타입은 1:1 대응되며 변환은 서버가 처리합니다 — `FT`→`BT`, `FI`→`BI`, `FW`→`BW`,
+> `FL`→`BL`, `FC`→`BC`, `FM`→`BM`, `FP`→`BP`, `FA`→`BA`.
+
 ```python
 # 텍스트형
 client.friendtalk.send(
@@ -205,6 +218,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 를 쓰세요 — 이 엔드포인트는 그 조합에 `NOT_A_BRAND_MESSAGE` 를 반환합니다. 친구톡 요청은 카카오 측에서 브랜드메시지(자유형)로 대체 발송됩니다.
+
+```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
@@ -392,6 +441,56 @@ A. Sendgo 플랜별로 TPS 제한이 있습니다. [요금 정책](https://sendg
 
 ---
 
+## 짧은 URL
+
+짧은 URL 은 메시지 본문의 링크를 줄이고, 그 링크가 실제로 눌렸는지 집계합니다.
+문자는 바이트 수가 요금과 직결되므로 링크를 줄이면 그만큼 본문을 더 쓸 수 있습니다.
+
+같은 원본 URL 을 다시 줄이면 **기존 링크가 그대로 반환**됩니다. 캠페인별로 반응을
+따로 집계하려면 `forceNew` 로 새 코드를 만드세요.
+
+`deactivate` 는 링크를 삭제하지 않고 리다이렉트만 중지합니다. 이미 발송한 메시지의
+링크를 무효화할 때 쓰며, 누적 통계는 남고 이후 접속은 `410 Gone` 이 됩니다.
+
+```python
+# 짧은 URL 생성 (v2 전용)
+created = sendgo.short_url.create(
+    target_url="https://example.com/promotions/summer-sale",
+    title="여름 세일 랜딩",
+)
+
+code = created["data"]["code"]
+link = created["data"]["shortUrl"]
+
+# 반응 통계 — 일별 추이 + 디바이스/유입경로/국가별 분해
+# `from` 은 파이썬 예약어이므로 `from_` 을 쓴다
+stats = sendgo.short_url.stats(code, from_="2026-08-01")
+
+sendgo.short_url.list(count=10)
+sendgo.short_url.show(code)
+sendgo.short_url.deactivate(code)   # 리다이렉트만 중지, 통계는 남는다
+```
+
+`stats` 는 일별 추이(`daily`)와 디바이스(`byDevice`)·유입경로(`byReferer`)·국가(`byCountry`)별
+분해를 반환합니다. 일별 추이는 사전 집계 표에서 읽으므로 클릭이 많아도 응답 시간이 일정합니다.
+
+## 변경 사항
+
+### 1.2.0 (2026-08-14)
+
+- **친구톡 Deprecated 표기** — 친구톡은 카카오 정책에 따라 2025-12-31 종료되었고,
+  2026-01-01 부터 발송 요청이 브랜드메시지(자유형)로 자동 대체 발송됩니다.
+  관련 API 에 각 언어의 표준 deprecation 표기를 달았습니다.
+- 자유 본문 타입(`FT`/`FI`/`FW`)의 개별 발송 경로는 아직 친구톡 API 뿐이라는 점을
+  문서에 명시했습니다 — 브랜드메시지 API 는 그 조합에 `NOT_A_BRAND_MESSAGE` 를 반환합니다.
+- 브랜드메시지 전환 안내와 메시지 타입 1:1 대응표를 README 에 추가했습니다.
+
+### 1.1.0 (2026-08-11)
+
+- 짧은 URL 추가 — `client.short_url`
+- `HttpClient.delete()` 추가
+- **버전 단일화** — `__init__.py` 에 하드코딩된 `__version__` 을 제거하고 `importlib.metadata` 로 `pyproject.toml` 값을 읽는다. 두 곳이 어긋나 릴리스가 실패한 적이 있다.
+
 ## 라이선스
 
 MIT License © 2026 [Sendgo](https://sendgo.io)

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

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

sendgo_python-1.2.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.2.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.2.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,11 @@ 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)
+        # Deprecated — 친구톡은 2025-12-31 종료. brand_message 를 사용한다.
+        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.2.0}/sendgo/friendtalk.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from typing import Any, Literal
 
 from .http_client import HttpClient
@@ -10,6 +11,17 @@ FriendtalkMessageType = Literal["FT", "FI", "FW", "FL", "FM", "FC", "FA", "FP"]
 class FriendtalkService:
     """카카오 친구톡 전송 서비스.
 
+    .. deprecated::
+        친구톡은 카카오 정책에 따라 2025-12-31 종료되었습니다. 2026-01-01 부터
+        친구톡 발송 요청은 카카오 측에서 브랜드메시지(자유형)로 자동 대체 발송되므로,
+        이 서비스를 호출해도 실제로 나가는 것은 브랜드메시지입니다.
+        신규 연동은 :class:`~sendgo.brand_message.BrandMessageService`
+        (``client.brand_message``) 를 사용하세요. 다만 자유 본문 타입(FT/FI/FW)을
+        개별 수신자에게 보내는 경로는 아직 이 서비스뿐입니다 — 브랜드메시지 API 는
+        그 조합에 ``NOT_A_BRAND_MESSAGE`` 를 반환합니다.
+        메시지 타입은 1:1 대응됩니다 — FT→BT, FI→BI, FW→BW, FL→BL,
+        FC→BC, FM→BM, FP→BP, FA→BA.
+
     Example::
 
         client.friendtalk.send(
@@ -42,7 +54,19 @@ class FriendtalkService:
         sms_subject: str | None = None,
         sms_content: str | None = None,
     ) -> dict:
-        """친구톡을 전송합니다."""
+        """친구톡을 전송합니다.
+
+        .. deprecated::
+            2025-12-31 종료. ``client.brand_message.send()`` 를 사용하세요.
+        """
+        # 파이썬의 DeprecationWarning 은 기본적으로 숨겨지므로 운영 로그를 더럽히지
+        # 않으면서, 테스트(-W error)나 개발 모드(-X dev)에서는 확실히 드러난다.
+        warnings.warn(
+            "친구톡은 2025-12-31 종료되어 2026-01-01 부터 브랜드메시지(자유형)로 "
+            "자동 대체 발송됩니다. client.brand_message.send() 를 사용하세요.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         body: dict[str, Any] = {
             "at": at,
             "scheduleType": schedule_type,

{sendgo_python-1.0.1 → sendgo_python-1.2.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.2.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.2.0}/sendgo_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sendgo-python
-Version: 1.0.1
+Version: 1.2.0
 Summary: Sendgo Python SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
 Author-email: Sendgo <dev@sendgo.io>
 License: MIT
@@ -27,7 +27,7 @@ Requires-Dist: httpx>=0.27; extra == "async"
 
 # sendgo-python
 
-> **Python / Django / FastAPI에서 카카오 알림톡, 친구톡, SMS를 가장 쉽게 발송하는 SDK**
+> **Python / Django / FastAPI에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 SDK**
 
 [![PyPI version](https://img.shields.io/pypi/v/sendgo-python?logo=pypi)](https://pypi.org/project/sendgo-python/)
 [![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python)](https://python.org)
@@ -184,6 +184,19 @@ client.alimtalk.send(
 
 ### 카카오 친구톡
 
+> ⚠️ **Deprecated — 친구톡은 카카오 정책에 따라 2025-12-31 종료되었습니다.**
+> 2026-01-01 부터 친구톡 발송 요청은 카카오 측에서 **브랜드메시지(자유형)** 로 자동 대체 발송됩니다.
+> 호출은 계속 성공하며, 자유 본문 타입(`FT`/`FI`/`FW`)을 개별 수신자에게 보내는 경로는
+> 현재 이것뿐이므로 기존 코드를 당장 바꿀 필요는 없습니다.
+>
+> 다음의 경우에는 **브랜드메시지**를 사용하세요.
+> - 템플릿 기반 리치 타입 (`FL`/`FC`/`FM`/`FP`/`FA`)
+> - 채널 친구가 **아닌** 수신자 (`targeting` = `N` / `I`)
+> - 수신 동의한 전체 채널 친구 동보 (`targeting` = `F`)
+>
+> 메시지 타입은 1:1 대응되며 변환은 서버가 처리합니다 — `FT`→`BT`, `FI`→`BI`, `FW`→`BW`,
+> `FL`→`BL`, `FC`→`BC`, `FM`→`BM`, `FP`→`BP`, `FA`→`BA`.
+
 ```python
 # 텍스트형
 client.friendtalk.send(
@@ -232,6 +245,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 를 쓰세요 — 이 엔드포인트는 그 조합에 `NOT_A_BRAND_MESSAGE` 를 반환합니다. 친구톡 요청은 카카오 측에서 브랜드메시지(자유형)로 대체 발송됩니다.
+
+```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
@@ -419,6 +468,56 @@ A. Sendgo 플랜별로 TPS 제한이 있습니다. [요금 정책](https://sendg
 
 ---
 
+## 짧은 URL
+
+짧은 URL 은 메시지 본문의 링크를 줄이고, 그 링크가 실제로 눌렸는지 집계합니다.
+문자는 바이트 수가 요금과 직결되므로 링크를 줄이면 그만큼 본문을 더 쓸 수 있습니다.
+
+같은 원본 URL 을 다시 줄이면 **기존 링크가 그대로 반환**됩니다. 캠페인별로 반응을
+따로 집계하려면 `forceNew` 로 새 코드를 만드세요.
+
+`deactivate` 는 링크를 삭제하지 않고 리다이렉트만 중지합니다. 이미 발송한 메시지의
+링크를 무효화할 때 쓰며, 누적 통계는 남고 이후 접속은 `410 Gone` 이 됩니다.
+
+```python
+# 짧은 URL 생성 (v2 전용)
+created = sendgo.short_url.create(
+    target_url="https://example.com/promotions/summer-sale",
+    title="여름 세일 랜딩",
+)
+
+code = created["data"]["code"]
+link = created["data"]["shortUrl"]
+
+# 반응 통계 — 일별 추이 + 디바이스/유입경로/국가별 분해
+# `from` 은 파이썬 예약어이므로 `from_` 을 쓴다
+stats = sendgo.short_url.stats(code, from_="2026-08-01")
+
+sendgo.short_url.list(count=10)
+sendgo.short_url.show(code)
+sendgo.short_url.deactivate(code)   # 리다이렉트만 중지, 통계는 남는다
+```
+
+`stats` 는 일별 추이(`daily`)와 디바이스(`byDevice`)·유입경로(`byReferer`)·국가(`byCountry`)별
+분해를 반환합니다. 일별 추이는 사전 집계 표에서 읽으므로 클릭이 많아도 응답 시간이 일정합니다.
+
+## 변경 사항
+
+### 1.2.0 (2026-08-14)
+
+- **친구톡 Deprecated 표기** — 친구톡은 카카오 정책에 따라 2025-12-31 종료되었고,
+  2026-01-01 부터 발송 요청이 브랜드메시지(자유형)로 자동 대체 발송됩니다.
+  관련 API 에 각 언어의 표준 deprecation 표기를 달았습니다.
+- 자유 본문 타입(`FT`/`FI`/`FW`)의 개별 발송 경로는 아직 친구톡 API 뿐이라는 점을
+  문서에 명시했습니다 — 브랜드메시지 API 는 그 조합에 `NOT_A_BRAND_MESSAGE` 를 반환합니다.
+- 브랜드메시지 전환 안내와 메시지 타입 1:1 대응표를 README 에 추가했습니다.
+
+### 1.1.0 (2026-08-11)
+
+- 짧은 URL 추가 — `client.short_url`
+- `HttpClient.delete()` 추가
+- **버전 단일화** — `__init__.py` 에 하드코딩된 `__version__` 을 제거하고 `importlib.metadata` 로 `pyproject.toml` 값을 읽는다. 두 곳이 어긋나 릴리스가 실패한 적이 있다.
+
 ## 라이선스
 
 MIT License © 2026 [Sendgo](https://sendgo.io)

{sendgo_python-1.0.1 → sendgo_python-1.2.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"