sendgo 1.0.1

checksums.yaml

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

data/README.md

@@ -0,0 +1,288 @@
+# sendgo
+
+> **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)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+`sendgo`는 [Sendgo](https://sendgo.io) 알림 API를 위한 공식 Ruby SDK입니다.
+**표준 라이브러리만 사용**하며, MonitorMixin 기반 스레드 안전 토큰 관리를 제공합니다.
+Rails, Sinatra, Hanami 등 모든 Ruby 환경에서 사용할 수 있습니다.
+
+---
+
+## 설치
+
+```bash
+gem install sendgo
+```
+
+또는 Gemfile:
+
+```ruby
+gem 'sendgo', '~> 1.0'
+```
+
+---
+
+## 빠른 시작
+
+```ruby
+require 'sendgo'
+
+client = Sendgo::Client.new(
+  access_key:       ENV['SENDGO_ACCESS_KEY'],
+  secret_key:       ENV['SENDGO_SECRET_KEY'],
+  kakao_sender_key: ENV['SENDGO_KAKAO_SENDER_KEY'],
+  sms_sender_key:   ENV['SENDGO_SMS_SENDER_KEY'],
+  api_version:      'v2'
+)
+
+# 알림톡 발송
+client.alimtalk.send(
+  template_code: 'ORDER_CONFIRM_001',
+  contacts: [
+    { contact: '01012345678', name: '홍길동', var1: 'ORD-001', var2: '29,000원' }
+  ]
+)
+```
+
+---
+
+## 알림톡 상세 사용법
+
+```ruby
+require 'sendgo'
+
+client = Sendgo::Client.new(
+  access_key:       ENV['SENDGO_ACCESS_KEY'],
+  secret_key:       ENV['SENDGO_SECRET_KEY'],
+  kakao_sender_key: ENV['SENDGO_KAKAO_SENDER_KEY'],
+  sms_sender_key:   ENV['SENDGO_SMS_SENDER_KEY'],
+  api_version:      'v2'
+)
+
+# 다건 발송
+client.alimtalk.send(
+  template_code: 'ORDER_CONFIRM_001',
+  contacts: [
+    { contact: '01011111111', name: '홍길동', var1: 'ORD-001', var2: '29,000원' },
+    { contact: '01022222222', name: '김철수', var1: 'ORD-002', var2: '15,000원' },
+    { contact: '01033333333', name: '이영희', var1: 'ORD-003', var2: '52,000원' }
+  ]
+)
+
+# 예약 발송
+client.alimtalk.send(
+  template_code:  'PROMO_SUMMER_2026',
+  schedule_type:  'SCHEDULED',
+  at:             '2026-07-28 09:00:00',
+  contacts: [
+    { contact: '01012345678', var1: '여름 한정 50% 할인' }
+  ]
+)
+
+# SMS 자동 대체 발송
+client.alimtalk.send(
+  template_code: 'DELIVERY_START_001',
+  replace_sms:   'Y',
+  sms_subject:   '[배송 시작 안내]',
+  sms_content:   "주문하신 상품이 출고되었습니다.\n송장번호: \#{var2}",
+  contacts: [
+    { contact: '01012345678', var1: 'ORD-001', var2: '1234567890' }
+  ]
+)
+```
+
+---
+
+## 친구톡 사용법
+
+```ruby
+# 텍스트형
+client.friendtalk.send(
+  content:  '안녕하세요! 7월 한정 특가 이벤트를 확인해보세요.',
+  contacts: [{ contact: '01012345678' }]
+)
+
+# 이미지형
+client.friendtalk.send(
+  message_type: 'FI',
+  content:      '이번 주 특가 상품을 확인하세요!',
+  image_url:    'https://cdn.example.com/banner.jpg',
+  image_link:   'https://example.com/event',
+  contacts:     [{ contact: '01012345678' }]
+)
+
+# 버튼 포함
+client.friendtalk.send(
+  content:  '7월 쿠폰이 도착했습니다! 지금 바로 사용하세요.',
+  buttons:  [{ name: '쿠폰 받기', type: 'WL', link_mo: 'https://example.com/coupon' }],
+  contacts: [{ contact: '01012345678' }]
+)
+```
+
+---
+
+## SMS / LMS / MMS 사용법
+
+```ruby
+# SMS (90자 이하)
+client.sms.send_sms(
+  content:  '[Sendgo] 인증번호: 123456 (5분 이내 입력)',
+  contacts: [{ contact: '01012345678' }]
+)
+
+# LMS (장문)
+client.sms.send_lms(
+  subject:  '[중요] 서비스 점검 안내',
+  content:  "안녕하세요. 서비스 점검이 예정되어 있습니다.\n■ 일시: 2026-07-25 02:00 ~ 06:00",
+  contacts: [{ contact: '01012345678' }]
+)
+
+# MMS (이미지 포함)
+client.sms.send_mms(
+  subject:  '[이벤트] 7월 특가',
+  content:  '이번 달 특가 상품을 확인하세요!',
+  contacts: [{ contact: '01011111111' }, { contact: '01022222222' }]
+)
+```
+
+---
+
+## Rails 통합
+
+```ruby
+# config/initializers/sendgo.rb
+SENDGO_CLIENT = Sendgo::Client.new(
+  access_key:       ENV['SENDGO_ACCESS_KEY'],
+  secret_key:       ENV['SENDGO_SECRET_KEY'],
+  kakao_sender_key: ENV['SENDGO_KAKAO_SENDER_KEY'],
+  sms_sender_key:   ENV['SENDGO_SMS_SENDER_KEY'],
+  api_version:      'v2'
+)
+
+# app/services/notification_service.rb
+class NotificationService
+  def initialize(client = SENDGO_CLIENT)
+    @client = client
+  end
+
+  def send_order_confirm(phone:, order_no:, amount:)
+    @client.alimtalk.send(
+      template_code: 'ORDER_CONFIRM_001',
+      contacts:      [{ contact: phone, var1: order_no, var2: amount }]
+    )
+  end
+
+  def send_verification_code(phone:, code:)
+    @client.alimtalk.send(
+      template_code: 'VERIFY_CODE_001',
+      replace_sms:   'Y',
+      sms_content:   "[인증] 인증번호: #{code} (5분 이내 입력)",
+      contacts:      [{ contact: phone, var1: code }]
+    )
+  end
+end
+
+# app/models/order.rb
+class Order < ApplicationRecord
+  after_create :send_confirmation
+
+  private
+
+  def send_confirmation
+    NotificationService.new.send_order_confirm(
+      phone:    user.phone,
+      order_no: number,
+      amount:   "#{total.to_i.to_s(:delimited)}원"
+    )
+  end
+end
+```
+
+### Sidekiq 비동기 발송
+
+```ruby
+# app/workers/alimtalk_worker.rb
+class AlimtalkWorker
+  include Sidekiq::Worker
+  sidekiq_options retry: 3
+
+  def perform(template_code, contacts)
+    SENDGO_CLIENT.alimtalk.send(
+      template_code: template_code,
+      contacts:      contacts
+    )
+  rescue Sendgo::Error => e
+    logger.error "알림톡 발송 실패: #{e.message} [#{e.error_code}]"
+    raise e unless %w[INVALID_TEMPLATE_CODE PAYMENT_REQUIRED].include?(e.error_code)
+  end
+end
+
+# 사용
+AlimtalkWorker.perform_async('ORDER_CONFIRM_001', [
+  { 'contact' => '01012345678', 'var1' => 'ORD-001' }
+])
+```
+
+---
+
+## 예외 처리
+
+```ruby
+require 'sendgo'
+
+begin
+  client.alimtalk.send(template_code: 'ORDER_CONFIRM_001', contacts: [...])
+rescue Sendgo::Error => e
+  puts "발송 실패: HTTP #{e.status_code} [#{e.error_code}]"
+
+  case e.error_code
+  when 'INVALID_ACCESS_KEY', 'INVALID_SECRET_KEY'
+    alert_ops('Sendgo 인증키를 확인하세요.')
+  when 'INVALID_TEMPLATE_CODE'
+    Rails.logger.warn("존재하지 않는 템플릿: #{e.message}")
+  when 'PAYMENT_REQUIRED'
+    alert_ops('Sendgo 크레딧이 부족합니다.')
+  when 'IP_NOT_ALLOWED'
+    alert_ops('허용되지 않은 IP')
+  end
+end
+```
+
+---
+
+## 설정 옵션
+
+| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
+|---------|------|------|--------|------|
+| `access_key` | `String` | **필수** | — | Sendgo 액세스 키 |
+| `secret_key` | `String` | **필수** | — | Sendgo 시크릿 키 |
+| `kakao_sender_key` | `String` | 선택 | `nil` | 카카오 발신프로필 키 |
+| `sms_sender_key` | `String` | 선택 | `nil` | SMS 발신자 키 |
+| `api_version` | `String` | 선택 | `'v1'` | API 버전 (`v1` \| `v2`) |
+| `base_url` | `String` | 선택 | `'https://sendgo.io'` | API 기본 URL |
+
+---
+
+## 관련 패키지
+
+| 언어/프레임워크 | 패키지 | GitHub |
+|----------------|--------|--------|
+| Spring Boot | `io.sendgo:sendgo-spring` | [spring](https://github.com/send-go/spring) |
+| Node.js | `@sendgo/node` | [node](https://github.com/send-go/node) |
+| Python | `sendgo-python` | [python](https://github.com/send-go/python) |
+| PHP | `sendgo/php` | [php](https://github.com/send-go/php) |
+| 전체 목록 | — | [send-go GitHub 조직](https://github.com/send-go) |
+
+---
+
+## 라이선스
+
+MIT License © 2026 [Sendgo](https://sendgo.io)
+
+---
+
+*키워드: 카카오 알림톡 Ruby, 카카오 친구톡 Rails, SMS 발송 Ruby, 알림톡 Ruby gem, Ruby 카카오 API 연동, Sendgo Ruby SDK, Rails 알림 발송*

data/lib/sendgo/alimtalk.rb

@@ -0,0 +1,30 @@
+module Sendgo
+  # 카카오 알림톡 전송 서비스.
+  #
+  # @example
+  #   client.alimtalk.send(
+  #     template_code: "ORDER_CONFIRM_001",
+  #     contacts: [{ contact: "01012345678", var1: "ORD-001" }]
+  #   )
+  class AlimtalkService
+    def initialize(http:, kakao_sender_key:, sms_sender_key:)
+      @http            = http
+      @kakao_sender_key = kakao_sender_key
+      @sms_sender_key  = sms_sender_key
+    end
+
+    def send(template_code:, contacts:, schedule_type: "DIRECTLY", at: nil,
+             replace_sms: "N", sms_subject: nil, sms_content: nil)
+      body = {
+        at: at, scheduleType: schedule_type, templateCode: template_code,
+        replaceSms: replace_sms,
+        smsSubject: replace_sms == "Y" ? sms_subject : nil,
+        smsContent: replace_sms == "Y" ? sms_content : nil,
+        contacts: contacts,
+        kakaoSenderKey: @kakao_sender_key,
+        senderKey: @sms_sender_key,
+      }
+      @http.post("notices/send", body)
+    end
+  end
+end

data/lib/sendgo/client.rb

@@ -0,0 +1,28 @@
+module Sendgo
+  # Sendgo Ruby SDK 메인 클라이언트.
+  #
+  # @example
+  #   client = Sendgo::Client.new(
+  #     access_key: ENV["SENDGO_ACCESS_KEY"],
+  #     secret_key: ENV["SENDGO_SECRET_KEY"],
+  #     kakao_sender_key: ENV["SENDGO_KAKAO_KEY"],
+  #     sms_sender_key: ENV["SENDGO_SMS_KEY"],
+  #     api_version: "v2"
+  #   )
+  class Client
+    attr_reader :alimtalk, :friendtalk, :sms
+
+    def initialize(access_key:, secret_key:, kakao_sender_key: nil, sms_sender_key: nil,
+                   api_version: "v1", base_url: "https://sendgo.io")
+      raise ArgumentError, "access_key와 secret_key는 필수입니다" if access_key.nil? || secret_key.nil?
+
+      token_manager = TokenManager.new(base_url: base_url, access_key: access_key,
+                                       secret_key: secret_key, api_version: api_version)
+      http = HttpClient.new(token_manager: token_manager, base_url: base_url, api_version: api_version)
+
+      @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)
+      @sms        = SmsService.new(http: http, sms_sender_key: sms_sender_key)
+    end
+  end
+end

data/lib/sendgo/error.rb

@@ -0,0 +1,25 @@
+module Sendgo
+  # Sendgo API 호출 실패 시 발생하는 에러.
+  class SendgoError < StandardError
+    attr_reader :status_code, :error_code, :endpoint, :api_version, :response_body
+
+    def initialize(message, status_code: 0, error_code: nil, endpoint: "", api_version: "", response_body: {})
+      super(message)
+      @status_code   = status_code
+      @error_code    = error_code
+      @endpoint      = endpoint
+      @api_version   = api_version
+      @response_body = response_body
+    end
+
+    def self.from_response(status, body, endpoint, api_version)
+      error_code = body["code"]
+      message    = body["message"] || "Unknown error"
+      msg = "HTTP #{status}"
+      msg += " [#{error_code}]" if error_code
+      msg += " #{message}"
+      new(msg, status_code: status, error_code: error_code, endpoint: endpoint,
+          api_version: api_version, response_body: body)
+    end
+  end
+end

data/lib/sendgo/friendtalk.rb

@@ -0,0 +1,29 @@
+module Sendgo
+  # 카카오 친구톡 전송 서비스.
+  class FriendtalkService
+    def initialize(http:, kakao_sender_key:, sms_sender_key:)
+      @http            = http
+      @kakao_sender_key = kakao_sender_key
+      @sms_sender_key  = sms_sender_key
+    end
+
+    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,
+             replace_sms: "N", sms_subject: nil, sms_content: nil)
+      body = {
+        at: at, scheduleType: schedule_type, messageType: message_type,
+        content: content, buttons: buttons, image: nil,
+        imageUrl: image_url, imageLink: image_link,
+        adFlag: ad_flag, wide: wide, adult: adult, header: header,
+        replaceSms: replace_sms,
+        smsSubject: replace_sms == "Y" ? sms_subject : nil,
+        smsContent: replace_sms == "Y" ? sms_content : nil,
+        contacts: contacts,
+        kakaoSenderKey: @kakao_sender_key,
+        senderKey: @sms_sender_key,
+      }
+      @http.post("friends/send", body)
+    end
+  end
+end

data/lib/sendgo/http_client.rb

@@ -0,0 +1,54 @@
+require "net/http"
+require "json"
+require "base64"
+
+module Sendgo
+  # Sendgo API HTTP 클라이언트.
+  class HttpClient
+    def initialize(token_manager:, base_url:, api_version:)
+      @token_manager = token_manager
+      @base_url      = base_url
+      @api_version   = api_version
+    end
+
+    def post(path, body)
+      do_post(path, body, 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
+
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"]  = "application/json"
+      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) }
+
+      resp_body = JSON.parse(resp.body) rescue {}
+
+      unless resp.is_a?(Net::HTTPSuccess)
+        error_code = resp_body["code"]
+        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)
+        end
+        raise SendgoError.from_response(resp.code.to_i, resp_body, endpoint, @api_version)
+      end
+
+      resp_body
+    end
+
+    def bearer_auth(token)
+      return "Bearer #{token}" if @api_version == "v2"
+      "Bearer #{Base64.strict_encode64(token)}"
+    end
+  end
+end

data/lib/sendgo/sms.rb

@@ -0,0 +1,28 @@
+module Sendgo
+  # SMS / LMS / MMS 전송 서비스.
+  #
+  # @example
+  #   client.sms.send_sms(content: "인증번호: 123456", contacts: [{ contact: "01012345678" }])
+  class SmsService
+    def initialize(http:, sms_sender_key:)
+      @http          = http
+      @sms_sender_key = sms_sender_key
+    end
+
+    def send_sms(content:, contacts:, **opts) = send(content: content, contacts: contacts, message_type: "SMS", **opts)
+    def send_lms(content:, contacts:, **opts) = send(content: content, contacts: contacts, message_type: "LMS", **opts)
+    def send_mms(content:, contacts:, **opts) = send(content: content, contacts: contacts, message_type: "MMS", **opts)
+
+    def send(content:, contacts:, message_type: "SMS", campaign_type: "MESSAGE",
+             schedule_type: "DIRECTLY", at: nil, subject: nil, files: [])
+      body = {
+        campaignType: campaign_type, messageType: message_type,
+        scheduleType: schedule_type, at: at,
+        subject: subject, content: content,
+        files: files, contacts: contacts,
+        senderKey: @sms_sender_key,
+      }
+      @http.post("messages/send", body)
+    end
+  end
+end

data/lib/sendgo/token_manager.rb

@@ -0,0 +1,68 @@
+require "net/http"
+require "json"
+require "base64"
+require "monitor"
+
+module Sendgo
+  NO_REFRESH_CODES = %w[
+    INVALID_AUTH_HEADER INVALID_BASIC_AUTH INVALID_BASIC_AUTH_PAYLOAD
+    INVALID_ACCESS_KEY INVALID_SECRET_KEY ACCESS_KEY_NOT_APPROVED
+    TEAM_REQUIRED_FOR_KAKAO IP_NOT_ALLOWED INVALID_SENDER_KEY INVALID_KAKAO_SENDER_KEY
+  ].freeze
+
+  TOKEN_TTL = 50 * 60 # 50분 (초)
+
+  # 토큰 발급 및 캐시 관리.
+  class TokenManager
+    include MonitorMixin
+
+    def initialize(base_url:, access_key:, secret_key:, api_version:)
+      super()
+      @base_url    = base_url
+      @access_key  = access_key
+      @secret_key  = secret_key
+      @api_version = api_version
+      @token       = nil
+      @expires_at  = Time.at(0)
+    end
+
+    def get_token
+      synchronize do
+        return @token if @token && Time.now < @expires_at
+        fetch_token
+      end
+    end
+
+    def invalidate
+      synchronize { @token = nil; @expires_at = Time.at(0) }
+    end
+
+    def should_refresh?(status, error_code)
+      return false unless [401, 403].include?(status)
+      return false if @api_version == "v2" && NO_REFRESH_CODES.include?(error_code)
+      true
+    end
+
+    private
+
+    def fetch_token
+      uri = URI("#{@base_url}/api/#{@api_version}/token")
+      credentials = Base64.strict_encode64("#{@access_key}:#{@secret_key}")
+
+      req = Net::HTTP::Post.new(uri)
+      req["Content-Type"]  = "application/json"
+      req["Authorization"] = "Basic #{credentials}"
+
+      resp = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") { |h| h.request(req) }
+      body = JSON.parse(resp.body) rescue {}
+
+      unless resp.is_a?(Net::HTTPSuccess) && body.dig("data", "token")
+        raise SendgoError.from_response(resp.code.to_i, body, "token", @api_version)
+      end
+
+      @token      = body["data"]["token"]
+      @expires_at = Time.now + TOKEN_TTL
+      @token
+    end
+  end
+end

data/lib/sendgo/version.rb

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

data/lib/sendgo.rb

@@ -0,0 +1,26 @@
+require_relative "sendgo/version"
+require_relative "sendgo/error"
+require_relative "sendgo/token_manager"
+require_relative "sendgo/http_client"
+require_relative "sendgo/alimtalk"
+require_relative "sendgo/friendtalk"
+require_relative "sendgo/sms"
+require_relative "sendgo/client"
+
+# Sendgo Ruby SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
+#
+# @example
+#   client = Sendgo::Client.new(
+#     access_key: ENV["SENDGO_ACCESS_KEY"],
+#     secret_key: ENV["SENDGO_SECRET_KEY"],
+#     kakao_sender_key: ENV["SENDGO_KAKAO_KEY"],
+#     sms_sender_key: ENV["SENDGO_SMS_KEY"],
+#     api_version: "v2"
+#   )
+#
+#   client.alimtalk.send(
+#     template_code: "ORDER_CONFIRM_001",
+#     contacts: [{ contact: "01012345678", var1: "ORD-001" }]
+#   )
+module Sendgo
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: sendgo
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Sendgo
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-09 00:00:00.000000000 Z
+dependencies: []
+description: Sendgo API를 Ruby에서 간편하게 사용하기 위한 공식 SDK
+email:
+- dev@sendgo.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sendgo.rb
+- lib/sendgo/alimtalk.rb
+- lib/sendgo/client.rb
+- lib/sendgo/error.rb
+- lib/sendgo/friendtalk.rb
+- lib/sendgo/http_client.rb
+- lib/sendgo/sms.rb
+- lib/sendgo/token_manager.rb
+- lib/sendgo/version.rb
+homepage: https://sendgo.io
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Sendgo Ruby SDK — 카카오 알림톡/친구톡, SMS/LMS/MMS
+test_files: []