sendgo 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e838cbd6f30a61b781b74b37eb2a088710b8a6a41594b0fcbd6eb2a874dd2849
-  data.tar.gz: ca411988c2a81bc7957a339690392a8de14b1b0e710332305787be9a65f23302
+  metadata.gz: 230cdcfeecd39f64c4518a917ee0758f158e3b92bda05e56f28caaa4f96edcb6
+  data.tar.gz: f829e4cb4afbde0adf19e51ef13f8f0f94db6a52a402a22d24c991a5177cee8c
 SHA512:
-  metadata.gz: a1d58de2204cb3471c287a8f4485a54cf53100b8267585e7189632883d2542cc4a5a293cce5a33c9351bfd74fcf84066e27510caba6bb5d61e784f7592c03911
-  data.tar.gz: 90d2b439c9f969a1d13bb302694cdc6b3f0a9b01466f2b7488aa25c286a0bada3b96c3f709cdad680296e2d6e1256a753e217e6ba875fd2f0f39f70e57b42ba7
+  metadata.gz: c7efbe668a9a7655dc47e0411b2c1ad4bede013459a0247731818182adcbacea52993f3e3d7f35f18bfd74fcdb5b56a404930b90210f3c4dd4d87602d220c96f
+  data.tar.gz: e192b6145d4057babaa514061aa4f251c9705a398ae234a0e2ebb71202846ece3d5e6b9bb4d504dc5d6fd2249867119887d19b2f299e8329615b688bf72f28f1

data/README.md

@@ -673,3 +673,54 @@ MIT License © 2026 [Sendgo](https://sendgo.io)
 ---
 
 *키워드: 카카오 알림톡 Ruby, 카카오 친구톡 Rails, SMS 발송 Ruby, 알림톡 Ruby gem, Ruby 카카오 API 연동, Sendgo Ruby SDK, Rails 알림 발송*
+
+## 계정·조직·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는 차단됩니다.
+에이전트 토큰과 키는 브라우저·모바일 앱에 포함하거나 응답·로그에 출력하지 않습니다.
+
+```ruby
+account = Sendgo::AccountClient.new(agent_token: ENV.fetch('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`는 서버 설정의 실제 승인 정책을 나타냅니다.
+
+```ruby
+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: nil
+)
+client.notice_templates.list(folder_uuid: "none")
+# 템플릿 생성 시 folder_uuid: 폴더_UUID를 선택 인자로 전달합니다.
+```

data/lib/sendgo/account.rb

@@ -0,0 +1,103 @@
+require "net/http"
+require "json"
+require "uri"
+require_relative "error"
+
+module Sendgo
+  # 서버 전용 계정 API. 에이전트 토큰은 자동 갱신하지 않는다.
+  class AccountClient
+    def initialize(agent_token:, base_url: "https://sendgo.io")
+      raise ArgumentError, "Sendgo: agent_token은 필수입니다." if agent_token.to_s.strip.empty?
+      @agent_token = agent_token
+      @base_url = base_url.sub(%r{/+$}, "")
+    end
+
+    # 계정 상태와 다음 단계 조회.
+    def me()
+      request("GET", "")
+    end
+
+    # 조직 목록 조회.
+    def organizations()
+      request("GET", "organizations")
+    end
+
+    # 조직 선택. null은 개인 계정.
+    def select_organization(organization_id)
+      request("POST", "organizations/select", {'organizationId' => organization_id})
+    end
+
+    # 현재 조직의 API 키 목록.
+    def api_keys()
+      request("GET", "api-keys")
+    end
+
+    # API 키 발급. secretKey는 이 응답에서만 반환.
+    def create_api_key(params)
+      request("POST", "api-keys", params)
+    end
+
+    # API 키 상세 조회.
+    def api_key(api_key_id)
+      request("GET", "api-keys/#{segment(api_key_id)}")
+    end
+
+    # API 키 이름 변경.
+    def update_api_key(api_key_id, name)
+      request("PATCH", "api-keys/#{segment(api_key_id)}", {'name' => name})
+    end
+
+    # API 키 폐기.
+    def delete_api_key(api_key_id)
+      request("DELETE", "api-keys/#{segment(api_key_id)}")
+    end
+
+    # 승인된 API 키의 발송용 토큰 발급.
+    def issue_token(api_key_id)
+      request("POST", "api-keys/#{segment(api_key_id)}/token", {})
+    end
+
+    # 허용 IP 목록과 호출자 IP 조회.
+    def allowed_ips(api_key_id)
+      request("GET", "api-keys/#{segment(api_key_id)}/allowed-ips")
+    end
+
+    # 허용 IP 추가. ip와 선택적 description 사용.
+    def add_allowed_ip(api_key_id, params)
+      request("POST", "api-keys/#{segment(api_key_id)}/allowed-ips", params)
+    end
+
+    # 허용 IP 삭제.
+    def delete_allowed_ip(api_key_id, ip_id)
+      request("DELETE", "api-keys/#{segment(api_key_id)}/allowed-ips/#{segment(ip_id)}")
+    end
+
+    private
+
+    def segment(value)
+      URI.encode_www_form_component(value).gsub("+", "%20")
+    end
+
+    def request(method, path, body = nil)
+      uri = URI("#{@base_url}/api/v2/account#{path.empty? ? '' : '/' + path}")
+      req = Net::HTTP.const_get(method.capitalize).new(uri)
+      req["Authorization"] = "Bearer #{@agent_token}"
+      req["Accept"] = "application/json"
+      unless body.nil?
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                 open_timeout: 10, read_timeout: 15) { |http| http.request(req) }
+      data = begin
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        {}
+      end
+      unless response.is_a?(Net::HTTPSuccess)
+        raise SendgoError.from_response(response.code.to_i, data, path.empty? ? "account" : path, "v2")
+      end
+      data
+    end
+  end
+end

data/lib/sendgo/client.rb

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

data/lib/sendgo/management.rb

@@ -119,9 +119,10 @@ module Sendgo
     end
 
     # 목록 조회.
-    def list(kakao_sender_key: nil, inspection_status: nil, search: nil, count: nil)
+    def list(kakao_sender_key: nil, inspection_status: nil, search: nil, count: nil, folder_uuid: nil)
       @http.get(RESOURCE, {
                   kakaoSenderKey: kakao_sender_key,
+                  folderUuid: folder_uuid,
                   inspectionStatus: inspection_status,
                   search: search,
                   count: count
@@ -250,8 +251,8 @@ module Sendgo
     end
 
     # 목록 조회.
-    def list(kakao_sender_key: nil, search: nil, count: nil)
-      @http.get(RESOURCE, { kakaoSenderKey: kakao_sender_key, search: search, count: count })
+    def list(kakao_sender_key: nil, search: nil, count: nil, folder_uuid: nil)
+      @http.get(RESOURCE, { folderUuid: folder_uuid, kakaoSenderKey: kakao_sender_key, search: search, count: count })
     end
 
     # 상세 조회. sendgo 코드(+KFT-...+)와 카카오 브랜드 템플릿 코드 둘 다 받는다.
@@ -594,3 +595,28 @@ module Sendgo
     end
   end
 end
+
+module Sendgo
+  # 템플릿 공용 폴더. v2 전용, 기업 계정 전용.
+  class TemplateFolderService
+    def initialize(http:)
+      @http = http
+    end
+
+    def list(template_type: nil, kakao_sender_key: nil)
+      @http.get("template-folders", { templateType: template_type, kakaoSenderKey: kakao_sender_key })
+    end
+
+    def create(name:, parent_uuid: nil)
+      @http.post("template-folders", { name: name, parentUuid: parent_uuid })
+    end
+
+    # folder_uuid: nil이면 미분류로 이동합니다. 1~100개 코드가 필요합니다.
+    def assign(template_type:, kakao_sender_key:, template_codes:, folder_uuid:)
+      @http.patch("template-folders/templates", {
+        templateType: template_type, kakaoSenderKey: kakao_sender_key,
+        templateCodes: template_codes, folderUuid: folder_uuid
+      })
+    end
+  end
+end

data/lib/sendgo/version.rb

@@ -1,3 +1,3 @@
 module Sendgo
-  VERSION = "1.3.0"
+  VERSION = "1.5.0"
 end

data/lib/sendgo.rb

@@ -27,3 +27,5 @@ require_relative "sendgo/client"
 #   )
 module Sendgo
 end
+
+require_relative "sendgo/account"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendgo
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Sendgo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-23 00:00:00.000000000 Z
 dependencies: []
 description: Sendgo API를 Ruby에서 간편하게 사용하기 위한 공식 SDK
 email:
@@ -19,6 +19,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/sendgo.rb
+- lib/sendgo/account.rb
 - lib/sendgo/alimtalk.rb
 - lib/sendgo/brand_message.rb
 - lib/sendgo/client.rb