sendgo 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e838cbd6f30a61b781b74b37eb2a088710b8a6a41594b0fcbd6eb2a874dd2849
-  data.tar.gz: ca411988c2a81bc7957a339690392a8de14b1b0e710332305787be9a65f23302
+  metadata.gz: 2b098fb0eec763f43b7d70391b8a7fa5840960adc8abdf0d75f7a88106741a67
+  data.tar.gz: '078319bc664b5d4cb9cef93db7ba02906e4125379d2a8f0775f9f9d39d9853e7'
 SHA512:
-  metadata.gz: a1d58de2204cb3471c287a8f4485a54cf53100b8267585e7189632883d2542cc4a5a293cce5a33c9351bfd74fcf84066e27510caba6bb5d61e784f7592c03911
-  data.tar.gz: 90d2b439c9f969a1d13bb302694cdc6b3f0a9b01466f2b7488aa25c286a0bada3b96c3f709cdad680296e2d6e1256a753e217e6ba875fd2f0f39f70e57b42ba7
+  metadata.gz: e90950557127c42fb44fd94c297d8e4cd5995ddc1e34da038d30ed95286985aa976a0f0c93b64364812d3866c8d713622d26b4b8d578e507ba2ace574b1648f1
+  data.tar.gz: a746896ca8b37b6e06507a5800b58372826531cb6ff26233e89111c5304ad3d28e2f1c91c0450542ce411cb602f8984378ad2d3aed8387ded7b4b03edf251f9c

data/README.md

@@ -673,3 +673,28 @@ MIT License © 2026 [Sendgo](https://sendgo.io)
 ---
 
 *키워드: 카카오 알림톡 Ruby, 카카오 친구톡 Rails, SMS 발송 Ruby, 알림톡 Ruby gem, Ruby 카카오 API 연동, Sendgo Ruby SDK, Rails 알림 발송*
+
+## 계정·조직·API 키 관리 (1.4.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)를 사용합니다.

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

data/lib/sendgo/version.rb

@@ -1,3 +1,3 @@
 module Sendgo
-  VERSION = "1.3.0"
+  VERSION = "1.4.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.4.0
 platform: ruby
 authors:
 - Sendgo
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-22 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