sendgo-rails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e73a3c170a66bdaca233e405ceef78237fe56357c8a415b8cdc49b0506ffd2f1
+  data.tar.gz: bfe33dd39c516c9fbcf2e26e8d922b859b58e0140d841ab0acec31fe3062fde1
+SHA512:
+  metadata.gz: bd42ac8a99571798fc3c693d749c15a7a1e3d46e19a809abb983a93d5f62907b321168f833c3b0bd242ab06f93e04f1671171c7132f3110b62ff4e1b1f0c57db
+  data.tar.gz: 4f1503f7bc241dffa113c19cdfc87990e67ed868521547568f457a43e681111920238254a65fd6e65a049a5202ac2ad04f7c8ef5bd45e6d1bd38d122dd67ce76

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sendgo <dev@sendgo.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,314 @@
+# sendgo-rails
+
+> **Rails에서 카카오 알림톡, 친구톡, SMS를 가장 쉽게 발송하는 공식 Rails 확장 젬**
+
+[![Gem Version](https://img.shields.io/gem/v/sendgo-rails)](https://rubygems.org/gems/sendgo-rails)
+[![Rails](https://img.shields.io/badge/Rails-6.1%2B-CC0000?logo=rubyonrails)](https://rubyonrails.org)
+[![Ruby](https://img.shields.io/badge/Ruby-3.0%2B-CC342D?logo=ruby)](https://ruby-lang.org)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+`sendgo-rails`는 [`sendgo`](https://github.com/send-go/ruby) 코어 젬을 확장한 **Rails 전용 확장 젬**입니다.
+Railtie 자동 등록, `config.sendgo` 설정 바인딩, 초기화 파일 제너레이터, 메모이즈된 클라이언트를 제공합니다.
+
+---
+
+## 목차
+
+- [설치](#설치)
+- [빠른 시작](#빠른-시작)
+- [상세 사용법](#상세-사용법)
+  - [알림톡](#알림톡)
+  - [친구톡](#친구톡)
+  - [SMS / LMS / MMS](#sms--lms--mms)
+- [Active Job 비동기 발송](#active-job-비동기-발송)
+- [예외 처리](#예외-처리)
+- [설정 옵션](#설정-옵션)
+- [자주 묻는 질문 (FAQ)](#자주-묻는-질문-faq)
+- [관련 패키지](#관련-패키지)
+- [라이선스](#라이선스)
+
+---
+
+## 설치
+
+Gemfile에 추가합니다.
+
+```ruby
+gem "sendgo-rails", "~> 1.0"
+```
+
+그리고 설치합니다.
+
+```bash
+bundle install
+```
+
+---
+
+## 빠른 시작
+
+### 1단계 — 초기화 파일 생성
+
+```bash
+bin/rails g sendgo:install
+```
+
+`config/initializers/sendgo.rb` 파일이 생성됩니다.
+
+### 2단계 — 환경변수 설정 (`.env` 또는 배포 환경)
+
+```env
+SENDGO_ACCESS_KEY=your_access_key
+SENDGO_SECRET_KEY=your_secret_key
+SENDGO_KAKAO_SENDER_KEY=your_kakao_key
+SENDGO_SMS_SENDER_KEY=your_sms_key
+SENDGO_API_VERSION=v2
+```
+
+### 3단계 — 초기화 파일 확인 (`config/initializers/sendgo.rb`)
+
+```ruby
+Rails.application.config.sendgo.tap do |config|
+  config.access_key       = ENV["SENDGO_ACCESS_KEY"]
+  config.secret_key       = ENV["SENDGO_SECRET_KEY"]
+  config.kakao_sender_key = ENV["SENDGO_KAKAO_SENDER_KEY"]
+  config.sms_sender_key   = ENV["SENDGO_SMS_SENDER_KEY"]
+  config.api_version      = ENV.fetch("SENDGO_API_VERSION", "v2")
+  config.url              = ENV.fetch("SENDGO_URL", "https://sendgo.io")
+end
+```
+
+> 설정값을 지정하지 않으면 동일한 이름의 ENV 환경변수로 자동 폴백합니다.
+> 즉, 초기화 파일 없이 환경변수만으로도 동작합니다.
+
+### 4단계 — 컨트롤러에서 알림톡 발송
+
+```ruby
+class OrdersController < ApplicationController
+  def confirm
+    order = Order.find(params[:id])
+
+    Sendgo::Rails.client.alimtalk.send(
+      template_code: "ORDER_CONFIRM_001",
+      contacts: [
+        { contact: order.user.phone, name: order.user.name,
+          var1: order.number, var2: "#{order.total}원" }
+      ]
+    )
+
+    render json: { success: true }
+  end
+end
+```
+
+---
+
+## 상세 사용법
+
+`Sendgo::Rails.client`는 코어 `Sendgo::Client` 인스턴스를 메모이즈하여 반환합니다.
+`.alimtalk`, `.friendtalk`, `.sms` 서비스를 그대로 사용할 수 있습니다.
+
+### 알림톡
+
+```ruby
+# 다건 발송
+Sendgo::Rails.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원" }
+  ]
+)
+
+# 예약 발송
+Sendgo::Rails.client.alimtalk.send(
+  template_code: "PROMO_SUMMER_2026",
+  schedule_type: "SCHEDULED",
+  at:            "2026-07-28 09:00:00",
+  contacts:      [{ contact: "01012345678", var1: "여름 한정 50% 할인" }]
+)
+
+# SMS 자동 대체 발송
+Sendgo::Rails.client.alimtalk.send(
+  template_code: "DELIVERY_START_001",
+  replace_sms:   "Y",
+  sms_subject:   "[배송 시작 안내]",
+  sms_content:   "주문하신 상품이 출고되었습니다.",
+  contacts:      [{ contact: "01012345678", var1: "ORD-001", var2: "1234567890" }]
+)
+```
+
+### 친구톡
+
+```ruby
+# 텍스트형
+Sendgo::Rails.client.friendtalk.send(
+  content:  "안녕하세요! 7월 한정 특가 이벤트를 확인해보세요.",
+  contacts: [{ contact: "01012345678" }]
+)
+
+# 이미지형
+Sendgo::Rails.client.friendtalk.send(
+  message_type: "FI",
+  content:      "이번 주 특가 상품을 확인하세요!",
+  image_url:    "https://cdn.example.com/banner.jpg",
+  image_link:   "https://example.com/event",
+  contacts:     [{ contact: "01012345678" }]
+)
+
+# 버튼 포함
+Sendgo::Rails.client.friendtalk.send(
+  content:  "7월 쿠폰이 도착했습니다! 지금 바로 사용하세요.",
+  buttons:  [{ name: "쿠폰 받기", type: "WL", link_mo: "https://example.com/coupon" }],
+  contacts: [{ contact: "01012345678" }]
+)
+```
+
+### SMS / LMS / MMS
+
+```ruby
+# SMS (90자 이하)
+Sendgo::Rails.client.sms.send_sms(
+  content:  "[Sendgo] 인증번호: 123456 (5분 이내 입력)",
+  contacts: [{ contact: "01012345678" }]
+)
+
+# LMS (장문, 2,000자 이하)
+Sendgo::Rails.client.sms.send_lms(
+  subject:  "[중요] 서비스 점검 안내",
+  content:  "안녕하세요. 서비스 점검이 예정되어 있습니다.\n■ 일시: 2026-07-25 02:00 ~ 06:00",
+  contacts: [{ contact: "01012345678" }]
+)
+
+# MMS (이미지 포함)
+Sendgo::Rails.client.sms.send_mms(
+  subject:  "[이벤트] 7월 특가",
+  content:  "이번 달 특가 상품을 확인하세요!",
+  contacts: [{ contact: "01011111111" }, { contact: "01022222222" }]
+)
+```
+
+---
+
+## Active Job 비동기 발송
+
+발송은 외부 API 호출이므로 백그라운드 잡으로 처리하는 것을 권장합니다.
+
+```ruby
+# app/jobs/send_alimtalk_job.rb
+class SendAlimtalkJob < ApplicationJob
+  queue_as :notifications
+  retry_on Sendgo::Error, wait: 10.seconds, attempts: 3
+
+  def perform(template_code, contacts)
+    Sendgo::Rails.client.alimtalk.send(
+      template_code: template_code,
+      contacts:      contacts
+    )
+  end
+end
+
+# 디스패치 예시
+SendAlimtalkJob.perform_later("ORDER_CONFIRM_001", [
+  { contact: "01012345678", var1: "ORD-001" }
+])
+```
+
+서비스 클래스 패턴도 자연스럽게 사용할 수 있습니다.
+
+```ruby
+# app/services/notification_service.rb
+class NotificationService
+  def initialize(client = Sendgo::Rails.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
+end
+```
+
+---
+
+## 예외 처리
+
+```ruby
+begin
+  Sendgo::Rails.client.alimtalk.send(template_code: "ORDER_CONFIRM_001", contacts: [...])
+rescue Sendgo::Error => e
+  Rails.logger.error "Sendgo 발송 실패: 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
+```
+
+---
+
+## 설정 옵션
+
+`config/initializers/sendgo.rb`에서 `Rails.application.config.sendgo`로 설정합니다.
+각 값이 비어 있으면 동일 이름의 환경변수로 폴백합니다.
+
+| 키 | 환경변수 | 기본값 | 설명 |
+|----|---------|--------|------|
+| `access_key` | `SENDGO_ACCESS_KEY` | — | Sendgo 액세스 키 |
+| `secret_key` | `SENDGO_SECRET_KEY` | — | Sendgo 시크릿 키 |
+| `kakao_sender_key` | `SENDGO_KAKAO_SENDER_KEY` | `nil` | 카카오 발신프로필 키 |
+| `sms_sender_key` | `SENDGO_SMS_SENDER_KEY` | `nil` | SMS 발신자 키 |
+| `api_version` | `SENDGO_API_VERSION` | `"v2"` | API 버전 |
+| `url` | `SENDGO_URL` | `"https://sendgo.io"` | API 기본 URL |
+
+> 테스트에서 설정을 바꾼 뒤에는 `Sendgo::Rails.reset!`을 호출해 메모이즈된 클라이언트를 초기화하세요.
+
+---
+
+## 자주 묻는 질문 (FAQ)
+
+**Q. `sendgo`(코어 젬)와의 차이는 무엇인가요?**
+A. `sendgo`는 프레임워크 독립적인 순수 Ruby 코어 젬입니다. `sendgo-rails`는 이를 확장해 Railtie 자동 등록, `config.sendgo` 설정 바인딩, 초기화 제너레이터, 메모이즈된 `Sendgo::Rails.client`를 추가합니다.
+
+**Q. 어떤 Rails 버전을 지원하나요?**
+A. `railties >= 6.1`을 지원합니다. (Rails 6.1, 7.x 이상)
+
+**Q. 초기화 파일 없이 환경변수만으로 쓸 수 있나요?**
+A. 네. 설정값이 없으면 `SENDGO_*` 환경변수로 자동 폴백하므로 `bin/rails g sendgo:install` 없이도 동작합니다.
+
+**Q. 테스트 시 클라이언트를 초기화하려면?**
+A. `Sendgo::Rails.reset!`을 호출하면 메모이즈된 클라이언트가 초기화되어 다음 호출 시 다시 생성됩니다.
+
+---
+
+## 관련 패키지
+
+| 언어/프레임워크 | 패키지 | GitHub |
+|----------------|--------|--------|
+| Ruby (코어) | `sendgo` | [ruby](https://github.com/send-go/ruby) |
+| PHP (Laravel) | `sendgo/laravel` | [laravel](https://github.com/send-go/laravel) |
+| 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) |
+| 전체 목록 | — | [send-go GitHub 조직](https://github.com/send-go) |
+
+---
+
+## 라이선스
+
+MIT License © 2026 [Sendgo](https://sendgo.io)
+
+---
+
+*키워드: 카카오 알림톡 Rails, 카카오 친구톡 Rails, SMS 발송 Rails, 알림톡 Rails gem, Rails 카카오 API 연동, Rails Railtie, Sendgo Rails SDK*

data/lib/generators/sendgo/install_generator.rb

@@ -0,0 +1,19 @@
+require "rails/generators/base"
+
+module Sendgo
+  module Generators
+    # `bin/rails g sendgo:install` 제너레이터.
+    #
+    # config/initializers/sendgo.rb 초기화 파일을 생성한다.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Sendgo 초기화 파일(config/initializers/sendgo.rb)을 생성합니다."
+
+      # 초기화 파일 템플릿을 복사한다.
+      def copy_initializer
+        template "sendgo.rb.tt", "config/initializers/sendgo.rb"
+      end
+    end
+  end
+end

data/lib/generators/sendgo/templates/sendgo.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Sendgo Rails 설정
+#
+# 아래 값들은 Rails.application.config.sendgo(ActiveSupport::OrderedOptions)에 저장되며
+# Sendgo::Rails.client 가 최초 호출될 때 Sendgo::Client 생성에 사용됩니다.
+#
+# 값을 비워두면 동일한 이름의 ENV 환경변수로 자동 폴백합니다.
+# 시크릿 키는 코드에 하드코딩하지 말고 환경변수 또는 Rails credentials로 관리하세요.
+Rails.application.config.sendgo.tap do |config|
+  # Sendgo 액세스 키 (필수)
+  config.access_key       = ENV["SENDGO_ACCESS_KEY"]
+
+  # Sendgo 시크릿 키 (필수)
+  config.secret_key       = ENV["SENDGO_SECRET_KEY"]
+
+  # 카카오 발신프로필 키 (알림톡/친구톡 사용 시)
+  config.kakao_sender_key = ENV["SENDGO_KAKAO_SENDER_KEY"]
+
+  # SMS 발신자 키 (SMS/LMS/MMS 사용 시)
+  config.sms_sender_key   = ENV["SENDGO_SMS_SENDER_KEY"]
+
+  # API 버전 (기본값: v2)
+  config.api_version      = ENV.fetch("SENDGO_API_VERSION", "v2")
+
+  # API 기본 URL (기본값: https://sendgo.io)
+  config.url              = ENV.fetch("SENDGO_URL", "https://sendgo.io")
+end

data/lib/sendgo/rails/railtie.rb

@@ -0,0 +1,22 @@
+# Rails가 존재할 때만 Railtie를 정의한다.
+# (순수 Ruby 환경에서 이 파일이 require되어도 안전하게 no-op)
+if defined?(::Rails::Railtie)
+  module Sendgo
+    module Rails
+      # Sendgo Rails 통합 Railtie.
+      #
+      # `config.sendgo`(ActiveSupport::OrderedOptions)를 기본 등록하여
+      # `config/initializers/sendgo.rb`에서 설정값을 지정할 수 있게 한다.
+      class Railtie < ::Rails::Railtie
+        # config.sendgo 네임스페이스 초기화
+        config.sendgo = ActiveSupport::OrderedOptions.new
+
+        # 애플리케이션 부팅 시점에 추가 초기화가 필요하면 여기서 처리한다.
+        initializer "sendgo.rails.setup" do
+          # 현재는 config.sendgo 등록만으로 충분하므로 별도 동작 없음.
+          # (지연 초기화: 클라이언트는 Sendgo::Rails.client 최초 호출 시 생성)
+        end
+      end
+    end
+  end
+end

data/lib/sendgo/rails/version.rb

@@ -0,0 +1,6 @@
+module Sendgo
+  module Rails
+    # sendgo-rails 젬 버전
+    VERSION = "1.0.0"
+  end
+end

data/lib/sendgo/rails.rb

@@ -0,0 +1,64 @@
+require "sendgo"
+require "sendgo/rails/version"
+
+# Rails가 로드된 환경에서만 Railtie를 등록한다.
+# (순수 Ruby 환경에서 `require "sendgo/rails"`가 동작하도록 가드)
+require "sendgo/rails/railtie" if defined?(::Rails::Railtie)
+
+module Sendgo
+  # Rails 통합 모듈.
+  #
+  # `Rails.application.config.sendgo`(ActiveSupport::OrderedOptions) 설정을
+  # 우선 사용하고, 값이 없으면 ENV 환경변수로 폴백하여 `Sendgo::Client`를 생성한다.
+  #
+  # @example 컨트롤러에서 사용
+  #   Sendgo::Rails.client.alimtalk.send(
+  #     template_code: "ORDER_CONFIRM_001",
+  #     contacts: [{ contact: "01012345678", var1: "ORD-001" }]
+  #   )
+  module Rails
+    class << self
+      # 메모이즈된 Sendgo::Client 인스턴스를 반환한다.
+      #
+      # @return [Sendgo::Client]
+      def client
+        @client ||= build_client
+      end
+
+      # 메모이즈된 클라이언트를 초기화한다. (주로 테스트에서 사용)
+      #
+      # @return [void]
+      def reset!
+        @client = nil
+      end
+
+      private
+
+      # 설정(config.sendgo) + ENV 폴백으로 Sendgo::Client를 생성한다.
+      def build_client
+        Sendgo::Client.new(
+          access_key:       config_value(:access_key,       "SENDGO_ACCESS_KEY"),
+          secret_key:       config_value(:secret_key,       "SENDGO_SECRET_KEY"),
+          kakao_sender_key: config_value(:kakao_sender_key, "SENDGO_KAKAO_SENDER_KEY"),
+          sms_sender_key:   config_value(:sms_sender_key,   "SENDGO_SMS_SENDER_KEY"),
+          api_version:      config_value(:api_version,      "SENDGO_API_VERSION") || "v2",
+          base_url:         config_value(:url,              "SENDGO_URL") || "https://sendgo.io"
+        )
+      end
+
+      # config.sendgo 값 → ENV 값 순으로 설정을 조회한다.
+      def config_value(key, env_key)
+        value = sendgo_config&.public_send(key)
+        value.nil? ? ENV[env_key] : value
+      end
+
+      # Rails 애플리케이션의 config.sendgo(OrderedOptions)를 반환한다.
+      # Rails가 없으면 nil을 반환하여 ENV 폴백만 사용한다.
+      def sendgo_config
+        return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        ::Rails.application.config.sendgo
+      end
+    end
+  end
+end

data/lib/sendgo-rails.rb

@@ -0,0 +1,2 @@
+# sendgo-rails 진입점 — 관례상 하이픈 파일명도 로드 가능하도록 별칭 제공
+require "sendgo/rails"

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification
+name: sendgo-rails
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Sendgo
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sendgo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: Sendgo Ruby SDK를 Rails에 통합하는 공식 확장 젬입니다. Railtie 자동 등록, 설정 초기화 제너레이터,
+  ENV 폴백 클라이언트를 제공합니다.
+email:
+- dev@sendgo.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/generators/sendgo/install_generator.rb
+- lib/generators/sendgo/templates/sendgo.rb.tt
+- lib/sendgo-rails.rb
+- lib/sendgo/rails.rb
+- lib/sendgo/rails/railtie.rb
+- lib/sendgo/rails/version.rb
+homepage: https://sendgo.io
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/send-go/rails
+  homepage_uri: https://sendgo.io
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+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 Rails 통합 — 카카오 알림톡/친구톡, SMS/LMS/MMS
+test_files: []