sendly 1.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8ede8c7152df0e2261bf901af9012076aef1e8606d4c4ceb096620c6ade299aa
+  data.tar.gz: b898bece3e69f9f2181e33d0e5d9ba487430c0577a422147621a0be2658ea086
+SHA512:
+  metadata.gz: 053a7b98c18a0f0ba8422f6e0282ef31b6f456927501f9047917b597006a92dc5b0573592d4f56935f12c402ed5c64aed7d1b3e58787e2a805d804e32b9d130f
+  data.tar.gz: 14cf12613830faacffb654404318e5f61c67767f719cdcc2421a6742c0e30bbdd49c53c7e0fd1773ab7dc335d112617a8d801dc665676bdabb72dbee7c69abeb

data/.ruby-version

@@ -0,0 +1 @@
+3.4.5

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,95 @@
+PATH
+  remote: .
+  specs:
+    sendly (1.0.5)
+      faraday (~> 2.0)
+      faraday-retry (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (3.3.1)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.2)
+      net-http (~> 0.5)
+    faraday-retry (2.3.2)
+      faraday (~> 2.0)
+    hashdiff (1.2.1)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    net-http (0.8.0)
+      uri (>= 0.11.1)
+    parallel (1.27.0)
+    parser (3.3.10.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.6.0)
+    public_suffix (7.0.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.81.7)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.48.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.1.1)
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.0)
+  sendly!
+  webmock (~> 3.0)
+
+BUNDLED WITH
+   2.6.9

data/README.md

@@ -0,0 +1,227 @@
+# Sendly Ruby SDK
+
+Official Ruby SDK for the Sendly SMS API.
+
+## Installation
+
+```bash
+# gem
+gem install sendly
+
+# Bundler (add to Gemfile)
+gem 'sendly'
+
+# then run
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require 'sendly'
+
+# Create a client
+client = Sendly::Client.new("sk_live_v1_your_api_key")
+
+# Send an SMS
+message = client.messages.send(
+  to: "+15551234567",
+  text: "Hello from Sendly!"
+)
+
+puts message.id     # => "msg_abc123"
+puts message.status # => "queued"
+```
+
+## Prerequisites for Live Messaging
+
+Before sending live SMS messages, you need:
+
+1. **Business Verification** - Complete verification in the [Sendly dashboard](https://sendly.live/dashboard)
+   - **International**: Instant approval (just provide Sender ID)
+   - **US/Canada**: Requires carrier approval (3-7 business days)
+
+2. **Credits** - Add credits to your account
+   - Test keys (`sk_test_*`) work without credits (sandbox mode)
+   - Live keys (`sk_live_*`) require credits for each message
+
+3. **Live API Key** - Generate after verification + credits
+   - Dashboard → API Keys → Create Live Key
+
+### Test vs Live Keys
+
+| Key Type | Prefix | Credits Required | Verification Required | Use Case |
+|----------|--------|------------------|----------------------|----------|
+| Test | `sk_test_v1_*` | No | No | Development, testing |
+| Live | `sk_live_v1_*` | Yes | Yes | Production messaging |
+
+> **Note**: You can start development immediately with a test key. Messages to sandbox test numbers are free and don't require verification.
+
+## Configuration
+
+### Global Configuration
+
+```ruby
+Sendly.configure do |config|
+  config.api_key = "sk_live_v1_xxx"
+end
+
+# Use the default client
+Sendly.send_message(to: "+15551234567", text: "Hello!")
+```
+
+### Client Options
+
+```ruby
+client = Sendly::Client.new(
+  "sk_live_v1_xxx",
+  base_url: "https://api.sendly.live/v1",
+  timeout: 60,
+  max_retries: 5
+)
+```
+
+## Messages
+
+### Send an SMS
+
+```ruby
+message = client.messages.send(
+  to: "+15551234567",
+  text: "Hello from Sendly!"
+)
+
+puts message.id
+puts message.status
+puts message.credits_used
+```
+
+### List Messages
+
+```ruby
+# Basic listing
+messages = client.messages.list(limit: 50)
+messages.each { |m| puts m.to }
+
+# With filters
+messages = client.messages.list(
+  status: "delivered",
+  to: "+15551234567",
+  limit: 20,
+  offset: 0
+)
+
+# Pagination info
+puts messages.total
+puts messages.has_more
+```
+
+### Get a Message
+
+```ruby
+message = client.messages.get("msg_abc123")
+
+puts message.to
+puts message.text
+puts message.status
+puts message.delivered_at
+```
+
+### Iterate All Messages
+
+```ruby
+# Auto-pagination
+client.messages.each do |message|
+  puts "#{message.id}: #{message.to}"
+end
+
+# With filters
+client.messages.each(status: "delivered") do |message|
+  puts "Delivered: #{message.id}"
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  message = client.messages.send(
+    to: "+15551234567",
+    text: "Hello!"
+  )
+rescue Sendly::AuthenticationError => e
+  puts "Invalid API key"
+rescue Sendly::RateLimitError => e
+  puts "Rate limited, retry after #{e.retry_after} seconds"
+rescue Sendly::InsufficientCreditsError => e
+  puts "Add more credits to your account"
+rescue Sendly::ValidationError => e
+  puts "Invalid request: #{e.message}"
+rescue Sendly::NotFoundError => e
+  puts "Resource not found"
+rescue Sendly::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Sendly::Error => e
+  puts "Error: #{e.message} (#{e.code})"
+end
+```
+
+## Message Object
+
+```ruby
+message.id           # Unique identifier
+message.to           # Recipient phone number
+message.text         # Message content
+message.status       # queued, sending, sent, delivered, failed
+message.credits_used # Credits consumed
+message.created_at   # Creation time
+message.updated_at   # Last update time
+message.delivered_at # Delivery time (if delivered)
+message.error_code   # Error code (if failed)
+message.error_message # Error message (if failed)
+
+# Helper methods
+message.delivered?   # => true/false
+message.failed?      # => true/false
+message.pending?     # => true/false
+```
+
+## Message Status
+
+| Status | Description |
+|--------|-------------|
+| `queued` | Message is queued for delivery |
+| `sending` | Message is being sent |
+| `sent` | Message was sent to carrier |
+| `delivered` | Message was delivered |
+| `failed` | Message delivery failed |
+
+## Pricing Tiers
+
+| Tier | Countries | Credits per SMS |
+|------|-----------|-----------------|
+| Domestic | US, CA | 1 |
+| Tier 1 | GB, PL, IN, etc. | 8 |
+| Tier 2 | FR, JP, AU, etc. | 12 |
+| Tier 3 | DE, IT, MX, etc. | 16 |
+
+## Sandbox Testing
+
+Use test API keys (`sk_test_v1_xxx`) with these test numbers:
+
+| Number | Behavior |
+|--------|----------|
+| +15550001234 | Success |
+| +15550001001 | Invalid number |
+| +15550001002 | Carrier rejected |
+| +15550001003 | No credits |
+| +15550001004 | Rate limited |
+
+## Requirements
+
+- Ruby 3.0+
+- Faraday 2.0+
+
+## License
+
+MIT

data/examples/list_messages.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "sendly"
+
+client = Sendly::Client.new(ENV["SENDLY_API_KEY"] || "sk_test_v1_example")
+
+# List recent messages
+puts "=== Recent Messages ==="
+messages = client.messages.list(limit: 10)
+puts "Total: #{messages.total}"
+puts "Has more: #{messages.has_more}"
+puts
+
+messages.each do |msg|
+  puts "#{msg.id}: #{msg.to} - #{msg.status}"
+end
+
+# List with filters
+puts "\n=== Delivered Messages ==="
+delivered = client.messages.list(status: "delivered", limit: 5)
+delivered.each do |msg|
+  puts "#{msg.id}: Delivered at #{msg.delivered_at}"
+end
+
+# Iterate all with auto-pagination
+puts "\n=== All Messages (paginated) ==="
+count = 0
+client.messages.each(batch_size: 50) do |msg|
+  puts "#{msg.id}: #{msg.to}"
+  count += 1
+  break if count >= 20 # Limit for demo
+end

data/examples/send_sms.rb

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "sendly"
+
+# Configure with your API key
+client = Sendly::Client.new(ENV["SENDLY_API_KEY"] || "sk_test_v1_example")
+
+# Send an SMS
+begin
+  message = client.messages.send(
+    to: "+15551234567",
+    text: "Hello from Sendly Ruby SDK!"
+  )
+
+  puts "Message sent successfully!"
+  puts "  ID: #{message.id}"
+  puts "  To: #{message.to}"
+  puts "  Status: #{message.status}"
+  puts "  Credits used: #{message.credits_used}"
+rescue Sendly::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue Sendly::InsufficientCreditsError => e
+  puts "Insufficient credits: #{e.message}"
+rescue Sendly::ValidationError => e
+  puts "Validation error: #{e.message}"
+rescue Sendly::RateLimitError => e
+  puts "Rate limited. Retry after: #{e.retry_after} seconds"
+rescue Sendly::Error => e
+  puts "Error: #{e.message}"
+end

data/lib/sendly/client.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Sendly
+  # Main Sendly API client
+  class Client
+    # @return [String] API key
+    attr_reader :api_key
+
+    # @return [String] Base URL
+    attr_reader :base_url
+
+    # @return [Integer] Request timeout in seconds
+    attr_reader :timeout
+
+    # @return [Integer] Maximum retry attempts
+    attr_reader :max_retries
+
+    # Create a new Sendly client
+    #
+    # @param api_key [String] Your Sendly API key
+    # @param base_url [String] API base URL (optional)
+    # @param timeout [Integer] Request timeout in seconds (default: 30)
+    # @param max_retries [Integer] Maximum retry attempts (default: 3)
+    #
+    # @example
+    #   client = Sendly::Client.new("sk_live_v1_xxx")
+    #   client = Sendly::Client.new("sk_live_v1_xxx", timeout: 60, max_retries: 5)
+    def initialize(api_key:, base_url: nil, timeout: 30, max_retries: 3)
+      @api_key = api_key
+      @base_url = (base_url || Sendly.base_url).chomp("/")
+      @timeout = timeout
+      @max_retries = max_retries
+
+      validate_api_key!
+    end
+
+    # Access the Messages resource
+    #
+    # @return [Sendly::Messages]
+    def messages
+      @messages ||= Messages.new(self)
+    end
+
+    # Make a GET request
+    #
+    # @param path [String] API path
+    # @param params [Hash] Query parameters
+    # @return [Hash] Response body
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    # Make a POST request
+    #
+    # @param path [String] API path
+    # @param body [Hash] Request body
+    # @return [Hash] Response body
+    def post(path, body = {})
+      request(:post, path, body: body)
+    end
+
+    # Make a DELETE request
+    #
+    # @param path [String] API path
+    # @return [Hash] Response body
+    def delete(path)
+      request(:delete, path)
+    end
+
+    private
+
+    def validate_api_key!
+      raise AuthenticationError, "API key is required" if api_key.nil? || api_key.empty?
+
+      unless api_key.match?(/^sk_(test|live)_v1_[a-zA-Z0-9_-]+$/)
+        raise AuthenticationError, "Invalid API key format. Expected sk_test_v1_xxx or sk_live_v1_xxx"
+      end
+    end
+
+    def request(method, path, params: {}, body: nil)
+      uri = build_uri(path, params)
+      http = build_http(uri)
+      req = build_request(method, uri, body)
+
+      attempt = 0
+      begin
+        response = http.request(req)
+        handle_response(response)
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise TimeoutError, "Request timed out after #{timeout} seconds"
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, SocketError => e
+        raise NetworkError, "Connection failed: #{e.message}"
+      rescue RateLimitError => e
+        attempt += 1
+        if attempt <= max_retries && e.retry_after
+          sleep(e.retry_after)
+          retry
+        end
+        raise
+      rescue ServerError => e
+        attempt += 1
+        if attempt <= max_retries
+          sleep(2 ** attempt) # Exponential backoff
+          retry
+        end
+        raise
+      end
+    end
+
+    def build_uri(path, params)
+      url = "#{base_url}#{path}"
+      uri = URI.parse(url)
+
+      if params.any?
+        query = params.map { |k, v| "#{URI.encode_www_form_component(k)}=#{URI.encode_www_form_component(v)}" }.join("&")
+        uri.query = query
+      end
+
+      uri
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = 10
+      http.read_timeout = timeout
+      http
+    end
+
+    def build_request(method, uri, body)
+      req = case method
+            when :get
+              Net::HTTP::Get.new(uri)
+            when :post
+              Net::HTTP::Post.new(uri)
+            when :delete
+              Net::HTTP::Delete.new(uri)
+            else
+              raise ArgumentError, "Unsupported HTTP method: #{method}"
+            end
+
+      req["Authorization"] = "Bearer #{api_key}"
+      req["Content-Type"] = "application/json"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "sendly-ruby/#{VERSION}"
+
+      req.body = body.to_json if body
+
+      req
+    end
+
+    def handle_response(response)
+      body = parse_body(response.body)
+      status = response.code.to_i
+
+      return body if status >= 200 && status < 300
+
+      raise ErrorFactory.from_response(status, body)
+    end
+
+    def parse_body(body)
+      return {} if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "message" => body }
+    end
+  end
+end

data/lib/sendly/errors.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Sendly
+  # Base error class for all Sendly errors
+  class Error < StandardError
+    # @return [String, nil] Error code from the API
+    attr_reader :code
+
+    # @return [Hash, nil] Additional error details
+    attr_reader :details
+
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status_code
+
+    def initialize(message = nil, code: nil, details: nil, status_code: nil)
+      @code = code
+      @details = details
+      @status_code = status_code
+      super(message)
+    end
+  end
+
+  # Raised when the API key is invalid or missing
+  class AuthenticationError < Error
+    def initialize(message = "Invalid or missing API key")
+      super(message, code: "AUTHENTICATION_ERROR", status_code: 401)
+    end
+  end
+
+  # Raised when the rate limit is exceeded
+  class RateLimitError < Error
+    # @return [Integer, nil] Seconds to wait before retrying
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: nil)
+      @retry_after = retry_after
+      super(message, code: "RATE_LIMIT_EXCEEDED", status_code: 429)
+    end
+  end
+
+  # Raised when the account has insufficient credits
+  class InsufficientCreditsError < Error
+    def initialize(message = "Insufficient credits")
+      super(message, code: "INSUFFICIENT_CREDITS", status_code: 402)
+    end
+  end
+
+  # Raised when the request contains invalid parameters
+  class ValidationError < Error
+    # @return [Hash, nil] Field-specific validation errors
+    attr_reader :field_errors
+
+    def initialize(message = "Validation failed", field_errors: nil, details: nil)
+      @field_errors = field_errors
+      super(message, code: "VALIDATION_ERROR", details: details, status_code: 400)
+    end
+  end
+
+  # Raised when the requested resource is not found
+  class NotFoundError < Error
+    def initialize(message = "Resource not found")
+      super(message, code: "NOT_FOUND", status_code: 404)
+    end
+  end
+
+  # Raised when a network error occurs
+  class NetworkError < Error
+    def initialize(message = "Network error occurred")
+      super(message, code: "NETWORK_ERROR")
+    end
+  end
+
+  # Raised when a timeout occurs
+  class TimeoutError < NetworkError
+    def initialize(message = "Request timed out")
+      super(message)
+      @code = "TIMEOUT_ERROR"
+    end
+  end
+
+  # Raised for unexpected API errors
+  class APIError < Error
+    def initialize(message = "An unexpected error occurred", status_code: nil, code: nil, details: nil)
+      super(message, code: code || "API_ERROR", status_code: status_code, details: details)
+    end
+  end
+
+  # Raised for server errors (5xx)
+  class ServerError < Error
+    def initialize(message = "Server error occurred", status_code: 500)
+      super(message, code: "SERVER_ERROR", status_code: status_code)
+    end
+  end
+
+  # Convert API response to appropriate error
+  class ErrorFactory
+    def self.from_response(status, body)
+      message = body["message"] || body["error"] || "Unknown error"
+      code = body["code"]
+      details = body["details"]
+
+      case status
+      when 400, 422
+        ValidationError.new(message, details: details)
+      when 401
+        AuthenticationError.new(message)
+      when 402
+        InsufficientCreditsError.new(message)
+      when 404
+        NotFoundError.new(message)
+      when 429
+        retry_after = body["retry_after"] || body["retryAfter"]
+        RateLimitError.new(message, retry_after: retry_after)
+      when 500..599
+        ServerError.new(message, status_code: status)
+      else
+        APIError.new(message, status_code: status, code: code, details: details)
+      end
+    end
+  end
+end