luosimao-sms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4b04f880e4d7bb95c53ca54950ddcb29a2c7e7780a8bcc1674d379812d957c59
+  data.tar.gz: d32d0083600b86cdeef688b06ff7d345f9928ed95fd64cf809dff474c4367091
+SHA512:
+  metadata.gz: dcf71f6970bda2685bc21baf2dfd4955fdf1f1ef33a28dd1587a16ca08760e1c13c7035493701aae9034802bd7efad1b524ed3fff9e33f36d45431862f5a31e6
+  data.tar.gz: 2181349a2b92bc23e455b8e17548916903187ce7fc04e2fd33f0ca318cf322e91b721c891bc9b9ddaf54c5c5b49d129507a45c8b25cdad2ffdf247cf92887bdb

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] - 2026-03-29
+### Added
+- Initial release of `luosimao-sms` gem.
+- Support for `send`, `send_batch`, and `status` API endpoints.
+- Error handling and response parsing.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 luosimao-oss
+
+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,189 @@
+# Luosimao SMS Ruby SDK
+
+[English](#english) | [中文](#chinese)
+
+<a id="english"></a>
+## English
+
+A Ruby SDK for sending SMS via the [Luosimao](https://luosimao.com) API.
+
+### Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'luosimao-sms'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install luosimao-sms
+```
+
+### Quick Start
+
+```ruby
+require 'luosimao-sms'
+
+client = Luosimao::SMS::Client.new(api_key: 'your_api_key')
+
+# Send SMS
+response = client.send(mobile: '13800138000', message: 'Verification code 123456【Your Company】')
+puts response.success?
+
+# Batch Send SMS
+response = client.send_batch(
+  mobiles: ['13800138000', '13800138001'],
+  message: 'Batch message【Your Company】'
+)
+
+# Check Balance
+status = client.status
+puts status.deposit
+```
+
+### Configuration
+
+You can configure the client with optional parameters:
+
+```ruby
+client = Luosimao::SMS::Client.new(
+  api_key: 'your_api_key',
+  timeout: 10,           # Read timeout in seconds (default: 30)
+  open_timeout: 5,       # Connection timeout in seconds (default: 10)
+  base_url: 'https://sms-api.luosimao.com' # API base URL
+)
+```
+
+The `api_key` can be provided with or without the `key-` prefix.
+
+### API Reference
+
+#### `client.send(mobile:, message:)`
+Sends a single SMS message. Returns `Luosimao::SMS::Response`. Raises `Luosimao::SMS::APIError` on API failure.
+
+#### `client.send_batch(mobiles:, message:, send_at: nil)`
+Sends a batch SMS message. Returns `Luosimao::SMS::Response`.
+
+#### `client.status`
+Queries the account balance. Returns `Luosimao::SMS::StatusResponse`.
+
+### Error Handling
+
+The SDK raises errors on failure:
+- `Luosimao::SMS::APIError`: API returned an error code. You can check specific errors via methods like `auth_failed?`, `insufficient_balance?`, `sensitive_words?`, `ip_not_allowed?`.
+- `Luosimao::SMS::NetworkError`: Network-related errors (timeout, connection refused).
+- `Luosimao::SMS::ArgumentError`: Invalid arguments provided.
+
+### Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/luosimao-oss/luosimao-sms-ruby.
+
+### License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+<a id="chinese"></a>
+## 中文
+
+螺丝帽 (Luosimao) 短信服务的 Ruby SDK。
+
+### Installation（安装）
+
+将以下代码添加到你的 `Gemfile`：
+
+```ruby
+gem 'luosimao-sms'
+```
+
+然后执行：
+
+```bash
+$ bundle install
+```
+
+或者直接安装：
+
+```bash
+$ gem install luosimao-sms
+```
+
+### Quick Start（快速开始）
+
+```ruby
+require 'luosimao-sms'
+
+client = Luosimao::SMS::Client.new(api_key: 'your_api_key')
+
+# 单发短信
+response = client.send(mobile: '13800138000', message: '验证码123456【你的公司】')
+puts response.success?
+
+# 批量发送
+response = client.send_batch(
+  mobiles: ['13800138000', '13800138001'],
+  message: '活动通知【你的公司】'
+)
+
+# 查询余额
+status = client.status
+puts status.deposit
+```
+
+### Configuration（配置项说明）
+
+支持以下可选配置参数：
+
+```ruby
+client = Luosimao::SMS::Client.new(
+  api_key: 'your_api_key',
+  timeout: 10,           # 超时秒数，默认 30
+  open_timeout: 5,       # 连接超时，默认 10
+  base_url: 'https://sms-api.luosimao.com' # 基础 URL
+)
+```
+
+`api_key` 传入时会自动补全 `key-` 前缀（如果未带）。
+
+### API Reference（接口说明）
+
+#### `client.send(mobile:, message:)`
+单发短信。返回 `Luosimao::SMS::Response` 对象。
+
+#### `client.send_batch(mobiles:, message:, send_at: nil)`
+批量发送。返回 `Luosimao::SMS::Response` 对象。
+
+#### `client.status`
+查询账户余额。返回 `Luosimao::SMS::StatusResponse` 对象。
+
+### Error Handling（异常处理）
+
+SDK 在遇到错误时会抛出异常：
+- `Luosimao::SMS::APIError`: 接口返回错误。支持使用 `auth_failed?`, `insufficient_balance?`, `sensitive_words?`, `ip_not_allowed?` 等方法检查具体错误。
+- `Luosimao::SMS::NetworkError`: 网络请求异常（超时、连接失败等）。
+- `Luosimao::SMS::ArgumentError`: 参数错误。
+
+### Development（本地开发）
+
+检出代码后，运行 `bundle install` 安装依赖。然后运行 `bundle exec rspec` 执行测试用例。
+
+### Contributing（贡献指南）
+
+欢迎提交 Issue 和 Pull Request：https://github.com/luosimao-oss/luosimao-sms-ruby。
+
+### License
+
+遵循 [MIT License](https://opensource.org/licenses/MIT) 开源协议。

data/lib/luosimao/sms/client.rb

@@ -0,0 +1,122 @@
+module Luosimao
+  module SMS
+    class Client
+      attr_reader :api_key, :timeout, :open_timeout, :base_url
+
+      def initialize(api_key:, timeout: 30, open_timeout: 10, base_url: "https://sms-api.luosimao.com")
+        @api_key = api_key.to_s.start_with?("key-") ? api_key.to_s : "key-#{api_key}"
+        @timeout = timeout
+        @open_timeout = open_timeout
+        @base_url = base_url.chomp("/")
+      end
+
+      # 单发短信
+      # @param mobile [String] 手机号
+      # @param message [String] 短信内容（含签名）
+      # @return [Luosimao::SMS::Response]
+      # @raise [Luosimao::SMS::APIError, Luosimao::SMS::NetworkError, Luosimao::SMS::ArgumentError]
+      def send(mobile:, message:)
+        raise Luosimao::SMS::ArgumentError, "mobile is required" if mobile.nil? || mobile.empty?
+        raise Luosimao::SMS::ArgumentError, "message is required" if message.nil? || message.empty?
+
+        response = request(
+          method: :post,
+          path: "/v1/send.json",
+          form_data: {
+            "mobile" => mobile,
+            "message" => message
+          }
+        )
+
+        handle_response(response, Response)
+      end
+
+      # 批量发送
+      # @param mobiles [Array<String>] 手机号数组
+      # @param message [String] 短信内容
+      # @param send_at [Time, nil] 定时发送时间（可选）
+      # @return [Luosimao::SMS::Response]
+      def send_batch(mobiles:, message:, send_at: nil)
+        raise Luosimao::SMS::ArgumentError, "mobiles array must be a non-empty array" unless mobiles.is_a?(Array) && !mobiles.empty?
+        raise Luosimao::SMS::ArgumentError, "message is required" if message.nil? || message.empty?
+
+        form_data = {
+          "mobile_list" => mobiles.join(","),
+          "message" => message
+        }
+        form_data["time"] = send_at.strftime("%Y-%m-%d %H:%M:%S") if send_at
+
+        response = request(
+          method: :post,
+          path: "/v1/send_batch.json",
+          form_data: form_data
+        )
+
+        handle_response(response, Response)
+      end
+
+      # 查询余额
+      # @return [Luosimao::SMS::StatusResponse]
+      def status
+        response = request(
+          method: :get,
+          path: "/v1/status.json"
+        )
+
+        handle_response(response, StatusResponse)
+      end
+
+      private
+
+      def request(method:, path:, form_data: nil)
+        uri = URI.parse("#{@base_url}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+        http.read_timeout = @timeout
+        http.open_timeout = @open_timeout
+
+        req = case method
+              when :get
+                Net::HTTP::Get.new(uri.request_uri)
+              when :post
+                Net::HTTP::Post.new(uri.request_uri)
+              else
+                raise Luosimao::SMS::ArgumentError, "unsupported method \#{method}"
+              end
+
+        req.basic_auth("api", @api_key)
+
+        if method == :post && form_data
+          req.set_form_data(form_data)
+        end
+
+        begin
+          http.request(req)
+        rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED, SocketError => e
+          raise Luosimao::SMS::NetworkError, e.message
+        end
+      end
+
+      def handle_response(http_response, response_class)
+        unless http_response.code.to_i.between?(200, 299)
+          raise Luosimao::SMS::NetworkError, "HTTP #{http_response.code}: #{http_response.message}"
+        end
+
+        begin
+          body = JSON.parse(http_response.body)
+        rescue JSON::ParserError => e
+          body_preview = http_response.body ? http_response.body[0..200] : ""
+          raise Luosimao::SMS::NetworkError, "Invalid JSON response: #{e.message}. Body: #{body_preview}"
+        end
+
+        resp = response_class.new(body, http_response.code.to_i)
+        if resp.success?
+          resp
+        else
+          raise Luosimao::SMS::APIError.new(code: resp.error_code, message: resp.message)
+        end
+      end
+    end
+  end
+end

data/lib/luosimao/sms/error.rb

@@ -0,0 +1,38 @@
+module Luosimao
+  module SMS
+    # 基础异常
+    class Error < StandardError; end
+
+    # API 返回错误
+    class APIError < Error
+      attr_reader :code
+
+      def initialize(code:, message:)
+        @code = code.to_i
+        super(message)
+      end
+
+      def auth_failed?
+        @code == -10
+      end
+
+      def insufficient_balance?
+        @code == -20
+      end
+
+      def sensitive_words?
+        @code == -30 || @code == -31
+      end
+
+      def ip_not_allowed?
+        @code == -50
+      end
+    end
+
+    # 网络请求异常
+    class NetworkError < Error; end
+
+    # 参数校验异常
+    class ArgumentError < Error; end
+  end
+end

data/lib/luosimao/sms/response.rb

@@ -0,0 +1,34 @@
+module Luosimao
+  module SMS
+    class Response
+      attr_reader :raw, :http_code
+
+      def initialize(raw, http_code = 200)
+        @raw = raw || {}
+        @http_code = http_code
+      end
+
+      def success?
+        error_code == 0
+      end
+
+      def error_code
+        @raw["error"].to_i
+      end
+
+      def message
+        @raw["msg"] || ""
+      end
+    end
+
+    class StatusResponse < Response
+      def deposit
+        if @raw["result"] && @raw["result"]["deposit"]
+          @raw["result"]["deposit"].to_f
+        else
+          0.0
+        end
+      end
+    end
+  end
+end

data/lib/luosimao/sms/version.rb

@@ -0,0 +1,5 @@
+module Luosimao
+  module SMS
+    VERSION = "0.1.0"
+  end
+end

data/lib/luosimao/sms.rb

@@ -0,0 +1,14 @@
+require "net/http"
+require "json"
+require "uri"
+require "openssl"
+
+require_relative "sms/version"
+require_relative "sms/error"
+require_relative "sms/response"
+require_relative "sms/client"
+
+module Luosimao
+  module SMS
+  end
+end

data/lib/luosimao-sms.rb

@@ -0,0 +1 @@
+require_relative "luosimao/sms"

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: luosimao-sms
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- luosimao-oss
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Ruby gem for sending SMS via Luosimao (螺丝帽) API
+email:
+- luosimao-oss@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/luosimao-sms.rb
+- lib/luosimao/sms.rb
+- lib/luosimao/sms/client.rb
+- lib/luosimao/sms/error.rb
+- lib/luosimao/sms/response.rb
+- lib/luosimao/sms/version.rb
+homepage: https://github.com/luosimao-oss/luosimao-sms-ruby
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby SDK for Luosimao SMS API
+test_files: []