sendgo 1.0.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a89b23db406e7ccf7ab1fe29fe9cfb2ddb5508cc7ce0367731cdbb5e3153c01f
-  data.tar.gz: bc4763817d9e59830e69e6547d406240b910727476c676cac88233fc431ee0cc
+  metadata.gz: b284db84cf34d157e88508177769ef77a16544aef167a94c24e5760c724dd92a
+  data.tar.gz: 5fe6a34c4feea8876c6ccd87f80100d1072e4a1eec7ddfc16bcd8ebe8a96ab8d
 SHA512:
-  metadata.gz: 5eb5c76e420bf0f4fb5e6b73db72480c5859077ff3b6288be19a89dec37a5275f7589d7f92a8a3ada0d36bb065e1c2cf477d8613e82468bfb5e1d2bd7ac19bd1
-  data.tar.gz: 428977e7d3d037a17cf20b7c22cb4785cce578abd1766fa5db76a6c1fdb658e33181e213d589f9e6067002c2ac3525c1b7ccb2e6ef836440158dc7cddd8beca2
+  metadata.gz: f3657ed33b9adfbe67a300afed3ef8550700eb24f4d678e53b5c404612d38fa2b172cefe185d17eed1cb8e60ac314e4041754434ff87f19b9672b4c63eeebd8b
+  data.tar.gz: f2cdbb4f5f441e6b629a6acef33548fa13c63c9a453407c4d42dffdace8f85f92aa39fa4901e29af00662d0c79b21f391d4e0875a9e36d7544585d3fbc84a1b2

data/README.md

@@ -1,6 +1,6 @@
 # sendgo
 
-> **Ruby에서 카카오 알림톡, 친구톡, SMS를 가장 쉽게 발송하는 공식 Ruby SDK**
+> **Ruby에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Ruby SDK**
 
 [![Gem Version](https://img.shields.io/gem/v/sendgo)](https://rubygems.org/gems/sendgo)
 [![Ruby](https://img.shields.io/badge/Ruby-3.1%2B-CC342D?logo=ruby)](https://ruby-lang.org)
@@ -99,6 +99,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`.
+
 ```ruby
 # 텍스트형
 client.friendtalk.send(
@@ -125,6 +138,42 @@ client.friendtalk.send(
 
 ---
 
+## 브랜드메시지 사용법
+
+브랜드메시지는 친구톡의 후속 채널입니다. 메시지 타입이 친구톡과 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` 를 반환합니다. 친구톡 요청은 카카오 측에서 브랜드메시지(자유형)로 대체 발송됩니다.
+
+```ruby
+# 단건 발송 — 채널 친구 대상
+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"
+)
+
+# 캠페인 조회
+campaigns = client.brand_message.campaigns(from: "2026-08-01", count: 10)
+one = client.brand_message.campaign("1f0a6d0e-6b3b-4f0f-9b2f-2f6f6a1b7c11")
+```
+
+---
+
 ## SMS / LMS / MMS 사용법
 
 ```ruby
@@ -279,6 +328,55 @@ end
 
 ---
 
+## 짧은 URL
+
+짧은 URL 은 메시지 본문의 링크를 줄이고, 그 링크가 실제로 눌렸는지 집계합니다.
+문자는 바이트 수가 요금과 직결되므로 링크를 줄이면 그만큼 본문을 더 쓸 수 있습니다.
+
+같은 원본 URL 을 다시 줄이면 **기존 링크가 그대로 반환**됩니다. 캠페인별로 반응을
+따로 집계하려면 `forceNew` 로 새 코드를 만드세요.
+
+`deactivate` 는 링크를 삭제하지 않고 리다이렉트만 중지합니다. 이미 발송한 메시지의
+링크를 무효화할 때 쓰며, 누적 통계는 남고 이후 접속은 `410 Gone` 이 됩니다.
+
+```ruby
+# 짧은 URL 생성 (v2 전용)
+created = sendgo.short_url.create(
+  target_url: "https://example.com/promotions/summer-sale",
+  title: "여름 세일 랜딩"
+)
+
+code = created.dig("data", "code")
+link = created.dig("data", "shortUrl")
+
+# 반응 통계 — 일별 추이 + 디바이스/유입경로/국가별 분해
+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` 추가
+- **버그 수정** — `request()` 가 Get/Post 만 만들어 `:delete` 가 조용히 POST 로 나가고 있었다. `Net::HTTP::Delete` 분기 추가.
+
 ## 라이선스
 
 MIT License © 2026 [Sendgo](https://sendgo.io)

data/lib/sendgo/brand_message.rb

@@ -0,0 +1,106 @@
+module Sendgo
+  # 카카오 브랜드메시지 전송 서비스.
+  #
+  # 브랜드메시지는 친구톡의 후속 채널로, 메시지 타입이 친구톡과 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원" }]
+  #   )
+  #
+  # @example 동보 발송 — 수신 동의한 전체 채널 친구 (contacts 불필요)
+  #   client.brand_message.broadcast(
+  #     message_type: "FW",
+  #     friend_template_uuid: "9cd5460b-6458-4edc-9b11-c26d3013c340"
+  #   )
+  class BrandMessageService
+    def initialize(http:, kakao_sender_key:, sms_sender_key:)
+      @http             = http
+      @kakao_sender_key = kakao_sender_key
+      @sms_sender_key   = sms_sender_key
+    end
+
+    # 브랜드메시지를 전송한다.
+    #
+    # +targeting+ 이 "M"/"N"/"I" 이면 +contacts+ 가 필요하고 응답 data 에
+    # 발송 건수(sentCount)가 담긴다. "F" 는 동보 발송이라 +contacts+ 없이
+    # 접수 여부(accepted)만 반환되므로, 그 경우 #broadcast 가 더 명확하다.
+    #
+    # +list+ 는 캐러셀 리스트(BC/BA)이며 요청에는 그대로 list 로 전송된다.
+    def send(friend_template_uuid:, message_type: "FT", targeting: "M",
+             contacts: nil, content: nil, schedule_type: "DIRECTLY", at: nil,
+             buttons: [], image_url: nil, image_link: nil,
+             ad_flag: "Y", adult: "N", push_alarm: "Y", header: nil,
+             coupon: nil, item: nil, commerce: nil, list: nil,
+             head: nil, tail: nil, video: nil, additional_content: nil,
+             friend_group_key: nil, replace_sms: "N",
+             sms_subject: nil, sms_content: nil,
+             reject_service_id: nil, webhooks: [])
+      body = {
+        at: at,
+        scheduleType: schedule_type,
+        targeting: targeting,
+        messageType: message_type,
+        friendTemplateUuid: friend_template_uuid,
+        content: content,
+        buttons: buttons,
+        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: replace_sms == "Y" ? sms_subject : nil,
+        smsContent: replace_sms == "Y" ? sms_content : nil,
+        rejectServiceId: reject_service_id,
+        webhooks: webhooks,
+        kakaoSenderKey: @kakao_sender_key,
+        senderKey: @sms_sender_key,
+      }
+
+      # 동보는 수신자 목록이 없다. 빈 배열을 보내면 잘못된 요청으로 거절되므로
+      # 키 자체를 넣지 않는다.
+      body[:contacts] = contacts || [] unless targeting == "F"
+
+      @http.post("brand-messages/send", body)
+    end
+
+    # 동보 발송 — 수신 동의한 전체 채널 친구 (+targeting: "F"+).
+    #
+    # 수신자 목록은 카카오 측에서 확장하므로 +contacts+ 를 넘기지 않는다.
+    # 결과는 #campaigns / #campaign 으로 확인한다.
+    def broadcast(**kwargs)
+      kwargs.delete(:contacts)
+      send(**kwargs, targeting: "F")
+    end
+
+    # 브랜드메시지 캠페인 목록을 조회한다.
+    def campaigns(from: nil, to: nil, count: nil)
+      @http.get("brand-messages", { from: from, to: to, count: count })
+    end
+
+    # 브랜드메시지 캠페인 상세를 조회한다.
+    # +campaign_id+ 는 발송 응답의 campaignId (UUID).
+    def campaign(campaign_id)
+      @http.get("brand-messages/#{campaign_id}")
+    end
+  end
+end

data/lib/sendgo/client.rb

@@ -10,7 +10,9 @@ module Sendgo
   #     api_version: "v2"
   #   )
   class Client
-    attr_reader :alimtalk, :friendtalk, :sms
+    # brand_message: 카카오 브랜드메시지 — 친구톡의 후속 채널. v2 전용.
+    # friendtalk: @deprecated 2025-12-31 종료. brand_message 를 사용하세요.
+    attr_reader :alimtalk, :friendtalk, :brand_message, :short_url, :sms
 
     def initialize(access_key:, secret_key:, kakao_sender_key: nil, sms_sender_key: nil,
                    api_version: "v1", base_url: "https://sendgo.io")
@@ -22,6 +24,9 @@ module Sendgo
 
       @alimtalk   = AlimtalkService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
       @friendtalk = FriendtalkService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
+      @brand_message = BrandMessageService.new(http: http, kakao_sender_key: kakao_sender_key, sms_sender_key: sms_sender_key)
+      # 짧은 URL — 링크 단축과 클릭 반응 분석. v2 전용.
+      @short_url  = ShortUrlService.new(http: http)
       @sms        = SmsService.new(http: http, sms_sender_key: sms_sender_key)
     end
   end

data/lib/sendgo/friendtalk.rb

@@ -1,5 +1,14 @@
 module Sendgo
   # 카카오 친구톡 전송 서비스.
+  #
+  # @deprecated 친구톡은 카카오 정책에 따라 2025-12-31 종료되었습니다.
+  #   2026-01-01 부터 친구톡 발송 요청은 카카오 측에서 브랜드메시지(자유형)로
+  #   자동 대체 발송되므로, 이 서비스를 호출해도 실제로 나가는 것은 브랜드메시지입니다.
+  #   신규 연동은 {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.
   class FriendtalkService
     def initialize(http:, kakao_sender_key:, sms_sender_key:)
       @http            = http
@@ -7,6 +16,7 @@ module Sendgo
       @sms_sender_key  = sms_sender_key
     end
 
+    # @deprecated 2025-12-31 종료. +client.brand_message.send+ 를 사용하세요.
     def send(content:, contacts:, message_type: "FT", schedule_type: "DIRECTLY",
              at: nil, buttons: [], image_url: nil, image_link: nil,
              ad_flag: "Y", wide: "N", adult: "N", header: nil,

data/lib/sendgo/http_client.rb

@@ -12,21 +12,46 @@ module Sendgo
     end
 
     def post(path, body)
-      do_post(path, body, is_retry: false)
+      request(:post, path, body: body, is_retry: false)
+    end
+
+    # GET 요청. 캠페인 조회 엔드포인트에서 사용한다.
+    # params 의 nil 값은 제외되어 서버 기본값이 적용된다.
+    def get(path, params = {})
+      request(:get, path, params: params, is_retry: false)
+    end
+
+    # DELETE 요청. 짧은 URL 리다이렉트 중지에서 사용한다.
+    def delete(path)
+      request(:delete, path, is_retry: false)
     end
 
     private
 
-    def do_post(path, body, is_retry: false)
-      token  = @token_manager.get_token
-      url    = "#{@base_url}/api/#{@api_version}/#{path}"
-      uri    = URI(url)
-      payload = body.to_json
+    def request(method, path, body: nil, params: nil, is_retry: false)
+      token = @token_manager.get_token
+      url   = "#{@base_url}/api/#{@api_version}/#{path}"
+      uri   = URI(url)
 
-      req = Net::HTTP::Post.new(uri)
-      req["Content-Type"]  = "application/json"
+      if params && !params.empty?
+        query = params.reject { |_, v| v.nil? }
+        uri.query = URI.encode_www_form(query) unless query.empty?
+      end
+
+      req =
+        case method
+        when :get
+          Net::HTTP::Get.new(uri)
+        when :delete
+          # 바디 없는 DELETE. Post 분기로 흘러가면 조용히 POST 로 나간다.
+          Net::HTTP::Delete.new(uri)
+        else
+          Net::HTTP::Post.new(uri).tap do |r|
+            r["Content-Type"] = "application/json"
+            r.body = body.to_json
+          end
+        end
       req["Authorization"] = bearer_auth(token)
-      req.body = payload
 
       resp = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
                              read_timeout: 15, open_timeout: 10) { |h| h.request(req) }
@@ -38,7 +63,7 @@ module Sendgo
         endpoint   = path.split("/").last
         if !is_retry && @token_manager.should_refresh?(resp.code.to_i, error_code)
           @token_manager.invalidate
-          return do_post(path, body, is_retry: true)
+          return request(method, path, body: body, params: params, is_retry: true)
         end
         raise SendgoError.from_response(resp.code.to_i, resp_body, endpoint, @api_version)
       end

data/lib/sendgo/short_url.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Sendgo
+  # 짧은 URL — 메시지에 넣는 링크를 줄이고 클릭 반응을 집계한다.
+  #
+  # v2 전용이다.
+  #
+  # @example
+  #   created = client.short_url.create(
+  #     target_url: "https://example.com/promotions/summer-sale",
+  #     title: "여름 세일 랜딩"
+  #   )
+  #
+  #   # created.dig("data", "shortUrl") 를 문자/알림톡 본문에 넣는다.
+  #   stats = client.short_url.stats(created.dig("data", "code"))
+  class ShortUrlService
+    def initialize(http:)
+      @http = http
+    end
+
+    # 짧은 URL 을 만든다.
+    #
+    # 같은 원본 URL 을 다시 줄이면 기존 링크가 그대로 반환된다.
+    # 캠페인별로 반응을 분리해 집계하려면 +force_new: true+ 를 쓴다.
+    def create(target_url:, title: nil, expires_at: nil, force_new: false)
+      body = { targetUrl: target_url, forceNew: force_new }
+      body[:title] = title unless title.nil?
+      body[:expiresAt] = expires_at unless expires_at.nil?
+
+      @http.post("short-urls", body)
+    end
+
+    # 목록 조회.
+    def list(from: nil, to: nil, count: nil)
+      @http.get("short-urls", { from: from, to: to, count: count })
+    end
+
+    # 상세 조회.
+    def show(code)
+      @http.get("short-urls/#{escape(code)}")
+    end
+
+    # 반응 통계. 일별 추이와 디바이스/유입경로/국가별 분해를 반환한다.
+    def stats(code, from: nil, to: nil)
+      @http.get("short-urls/#{escape(code)}/stats", { from: from, to: to })
+    end
+
+    # 리다이렉트를 중지한다. 링크는 삭제되지 않고 누적 통계도 남는다.
+    # 이후 그 링크로 들어오면 410 Gone 이 반환된다.
+    def deactivate(code)
+      @http.delete("short-urls/#{escape(code)}")
+    end
+
+    private
+
+    def escape(code)
+      CGI.escape(code.to_s)
+    end
+  end
+end

data/lib/sendgo/version.rb

@@ -1,3 +1,3 @@
 module Sendgo
-  VERSION = "1.0.1"
+  VERSION = "1.2.0"
 end

data/lib/sendgo.rb

@@ -4,6 +4,8 @@ require_relative "sendgo/token_manager"
 require_relative "sendgo/http_client"
 require_relative "sendgo/alimtalk"
 require_relative "sendgo/friendtalk"
+require_relative "sendgo/brand_message"
+require_relative "sendgo/short_url"
 require_relative "sendgo/sms"
 require_relative "sendgo/client"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendgo
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Sendgo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-14 00:00:00.000000000 Z
 dependencies: []
 description: Sendgo API를 Ruby에서 간편하게 사용하기 위한 공식 SDK
 email:
@@ -20,10 +20,12 @@ files:
 - README.md
 - lib/sendgo.rb
 - lib/sendgo/alimtalk.rb
+- lib/sendgo/brand_message.rb
 - lib/sendgo/client.rb
 - lib/sendgo/error.rb
 - lib/sendgo/friendtalk.rb
 - lib/sendgo/http_client.rb
+- lib/sendgo/short_url.rb
 - lib/sendgo/sms.rb
 - lib/sendgo/token_manager.rb
 - lib/sendgo/version.rb