sendly 1.0.5

data/lib/sendly/messages.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+module Sendly
+  # Messages resource for sending and managing SMS
+  class Messages
+    # @return [Sendly::Client] The API client
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Send an SMS message
+    #
+    # @param to [String] Recipient phone number in E.164 format
+    # @param text [String] Message content (max 1600 characters)
+    # @return [Sendly::Message] The sent message
+    #
+    # @raise [Sendly::ValidationError] If parameters are invalid
+    # @raise [Sendly::InsufficientCreditsError] If account has no credits
+    # @raise [Sendly::RateLimitError] If rate limit is exceeded
+    #
+    # @example
+    #   message = client.messages.send(
+    #     to: "+15551234567",
+    #     text: "Hello from Sendly!"
+    #   )
+    #   puts message.id
+    #   puts message.status
+    def send(to:, text:)
+      validate_phone!(to)
+      validate_text!(text)
+
+      response = client.post("/messages", { to: to, text: text })
+      # API returns message directly at top level
+      Message.new(response)
+    end
+
+    # List messages
+    #
+    # @param limit [Integer] Maximum messages to return (default: 20, max: 100)
+    # @param offset [Integer] Number of messages to skip
+    # @param status [String] Filter by status
+    # @param to [String] Filter by recipient
+    # @return [Sendly::MessageList] Paginated list of messages
+    #
+    # @example
+    #   messages = client.messages.list(limit: 50)
+    #   messages.each { |m| puts m.to }
+    #
+    # @example With filters
+    #   messages = client.messages.list(
+    #     status: "delivered",
+    #     to: "+15551234567"
+    #   )
+    def list(limit: 20, offset: 0, status: nil, to: nil)
+      params = {
+        limit: [limit, 100].min,
+        offset: offset
+      }
+      params[:status] = status if status
+      params[:to] = to if to
+
+      response = client.get("/messages", params.compact)
+      MessageList.new(response)
+    end
+
+    # Get a message by ID
+    #
+    # @param id [String] Message ID
+    # @return [Sendly::Message] The message
+    #
+    # @raise [Sendly::NotFoundError] If message is not found
+    #
+    # @example
+    #   message = client.messages.get("msg_abc123")
+    #   puts message.status
+    def get(id)
+      raise ValidationError, "Message ID is required" if id.nil? || id.empty?
+
+      # URL encode the ID to prevent path injection
+      encoded_id = URI.encode_www_form_component(id)
+      response = client.get("/messages/#{encoded_id}")
+      # API returns message directly at top level
+      Message.new(response)
+    end
+
+    # Iterate over all messages with automatic pagination
+    #
+    # @param status [String] Filter by status
+    # @param to [String] Filter by recipient
+    # @param batch_size [Integer] Number of messages per request
+    # @yield [Message] Each message
+    # @return [Enumerator] If no block given
+    #
+    # @example
+    #   client.messages.each do |message|
+    #     puts "#{message.id}: #{message.to}"
+    #   end
+    def each(status: nil, to: nil, batch_size: 100, &block)
+      return enum_for(:each, status: status, to: to, batch_size: batch_size) unless block_given?
+
+      offset = 0
+      loop do
+        page = list(limit: batch_size, offset: offset, status: status, to: to)
+        page.each(&block)
+
+        break unless page.has_more
+
+        offset += batch_size
+      end
+    end
+
+    # Schedule an SMS message for future delivery
+    #
+    # @param to [String] Recipient phone number in E.164 format
+    # @param text [String] Message content (max 1600 characters)
+    # @param scheduled_at [String] ISO 8601 datetime for when to send
+    # @param from [String] Sender ID or phone number (optional)
+    # @return [Hash] The scheduled message
+    #
+    # @raise [Sendly::ValidationError] If parameters are invalid
+    #
+    # @example
+    #   scheduled = client.messages.schedule(
+    #     to: "+15551234567",
+    #     text: "Reminder: Your appointment is tomorrow!",
+    #     scheduled_at: "2025-01-20T10:00:00Z"
+    #   )
+    #   puts scheduled["id"]
+    def schedule(to:, text:, scheduled_at:, from: nil)
+      validate_phone!(to)
+      validate_text!(text)
+      raise ValidationError, "scheduled_at is required" if scheduled_at.nil? || scheduled_at.empty?
+
+      body = { to: to, text: text, scheduledAt: scheduled_at }
+      body[:from] = from if from
+
+      client.post("/messages/schedule", body)
+    end
+
+    # List scheduled messages
+    #
+    # @param limit [Integer] Maximum messages to return (default: 20, max: 100)
+    # @param offset [Integer] Number of messages to skip
+    # @param status [String] Filter by status (scheduled, sent, cancelled, failed)
+    # @return [Hash] Paginated list of scheduled messages
+    #
+    # @example
+    #   scheduled = client.messages.list_scheduled(limit: 50)
+    #   scheduled["data"].each { |m| puts m["scheduledAt"] }
+    def list_scheduled(limit: 20, offset: 0, status: nil)
+      params = {
+        limit: [limit, 100].min,
+        offset: offset
+      }
+      params[:status] = status if status
+
+      client.get("/messages/scheduled", params.compact)
+    end
+
+    # Get a scheduled message by ID
+    #
+    # @param id [String] Scheduled message ID
+    # @return [Hash] The scheduled message
+    #
+    # @raise [Sendly::NotFoundError] If scheduled message is not found
+    #
+    # @example
+    #   scheduled = client.messages.get_scheduled("sched_abc123")
+    #   puts scheduled["status"]
+    def get_scheduled(id)
+      raise ValidationError, "Scheduled message ID is required" if id.nil? || id.empty?
+
+      encoded_id = URI.encode_www_form_component(id)
+      client.get("/messages/scheduled/#{encoded_id}")
+    end
+
+    # Cancel a scheduled message
+    #
+    # @param id [String] Scheduled message ID
+    # @return [Hash] The cancelled message with refund details
+    #
+    # @raise [Sendly::NotFoundError] If scheduled message is not found
+    # @raise [Sendly::ValidationError] If message cannot be cancelled
+    #
+    # @example
+    #   result = client.messages.cancel_scheduled("sched_abc123")
+    #   puts "Refunded #{result['creditsRefunded']} credits"
+    def cancel_scheduled(id)
+      raise ValidationError, "Scheduled message ID is required" if id.nil? || id.empty?
+
+      encoded_id = URI.encode_www_form_component(id)
+      client.delete("/messages/scheduled/#{encoded_id}")
+    end
+
+    # Send multiple SMS messages in a batch
+    #
+    # @param messages [Array<Hash>] Array of messages with :to and :text keys
+    # @param from [String] Sender ID or phone number (optional, applies to all)
+    # @return [Hash] Batch response with batch_id and status
+    #
+    # @raise [Sendly::ValidationError] If parameters are invalid
+    # @raise [Sendly::InsufficientCreditsError] If account has insufficient credits
+    #
+    # @example
+    #   result = client.messages.send_batch(
+    #     messages: [
+    #       { to: "+15551234567", text: "Hello Alice!" },
+    #       { to: "+15559876543", text: "Hello Bob!" }
+    #     ]
+    #   )
+    #   puts "Batch #{result['batchId']}: #{result['queued']} queued"
+    def send_batch(messages:, from: nil)
+      raise ValidationError, "Messages array is required" if messages.nil? || messages.empty?
+
+      messages.each_with_index do |msg, i|
+        raise ValidationError, "Message at index #{i} missing 'to'" unless msg[:to] || msg["to"]
+        raise ValidationError, "Message at index #{i} missing 'text'" unless msg[:text] || msg["text"]
+
+        to = msg[:to] || msg["to"]
+        text = msg[:text] || msg["text"]
+        validate_phone!(to)
+        validate_text!(text)
+      end
+
+      body = { messages: messages }
+      body[:from] = from if from
+
+      client.post("/messages/batch", body)
+    end
+
+    # Get batch status by ID
+    #
+    # @param batch_id [String] Batch ID
+    # @return [Hash] Batch status and details
+    #
+    # @raise [Sendly::NotFoundError] If batch is not found
+    #
+    # @example
+    #   batch = client.messages.get_batch("batch_abc123")
+    #   puts "#{batch['sent']}/#{batch['total']} sent"
+    def get_batch(batch_id)
+      raise ValidationError, "Batch ID is required" if batch_id.nil? || batch_id.empty?
+
+      encoded_id = URI.encode_www_form_component(batch_id)
+      client.get("/messages/batch/#{encoded_id}")
+    end
+
+    # List batches
+    #
+    # @param limit [Integer] Maximum batches to return (default: 20, max: 100)
+    # @param offset [Integer] Number of batches to skip
+    # @param status [String] Filter by status (processing, completed, failed)
+    # @return [Hash] Paginated list of batches
+    #
+    # @example
+    #   batches = client.messages.list_batches(limit: 10)
+    #   batches["data"].each { |b| puts "#{b['batchId']}: #{b['status']}" }
+    def list_batches(limit: 20, offset: 0, status: nil)
+      params = {
+        limit: [limit, 100].min,
+        offset: offset
+      }
+      params[:status] = status if status
+
+      client.get("/messages/batches", params.compact)
+    end
+
+    private
+
+    def validate_phone!(phone)
+      return if phone.is_a?(String) && phone.match?(/^\+[1-9]\d{1,14}$/)
+
+      raise ValidationError, "Invalid phone number format. Use E.164 format (e.g., +15551234567)"
+    end
+
+    def validate_text!(text)
+      raise ValidationError, "Message text is required" if text.nil? || text.empty?
+      raise ValidationError, "Message text exceeds maximum length (1600 characters)" if text.length > 1600
+    end
+  end
+end

data/lib/sendly/types.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Sendly
+  # Represents an SMS message
+  class Message
+    # @return [String] Unique message identifier
+    attr_reader :id
+
+    # @return [String] Recipient phone number
+    attr_reader :to
+
+    # @return [String, nil] Sender ID or phone number
+    attr_reader :from
+
+    # @return [String] Message content
+    attr_reader :text
+
+    # @return [String] Delivery status
+    attr_reader :status
+
+    # @return [String, nil] Error message if failed
+    attr_reader :error
+
+    # @return [Integer] Number of SMS segments
+    attr_reader :segments
+
+    # @return [Integer] Credits used
+    attr_reader :credits_used
+
+    # @return [Boolean] Whether sent in sandbox mode
+    attr_reader :is_sandbox
+
+    # @return [Time, nil] Creation timestamp
+    attr_reader :created_at
+
+    # @return [Time, nil] Delivery timestamp
+    attr_reader :delivered_at
+
+    # Message status constants
+    STATUSES = %w[queued sending sent delivered failed].freeze
+
+    def initialize(data)
+      @id = data["id"]
+      @to = data["to"]
+      @from = data["from"]
+      @text = data["text"]
+      @status = data["status"]
+      @error = data["error"]
+      @segments = data["segments"] || 1
+      @credits_used = data["creditsUsed"] || 0
+      @is_sandbox = data["isSandbox"] || false
+      @created_at = parse_time(data["createdAt"])
+      @delivered_at = parse_time(data["deliveredAt"])
+    end
+
+    # Check if message was delivered
+    # @return [Boolean]
+    def delivered?
+      status == "delivered"
+    end
+
+    # Check if message failed
+    # @return [Boolean]
+    def failed?
+      status == "failed"
+    end
+
+    # Check if message is pending
+    # @return [Boolean]
+    def pending?
+      %w[queued sending sent].include?(status)
+    end
+
+    # Convert to hash
+    # @return [Hash]
+    def to_h
+      {
+        id: id,
+        to: to,
+        from: from,
+        text: text,
+        status: status,
+        error: error,
+        segments: segments,
+        credits_used: credits_used,
+        is_sandbox: is_sandbox,
+        created_at: created_at&.iso8601,
+        delivered_at: delivered_at&.iso8601
+      }.compact
+    end
+
+    private
+
+    def parse_time(value)
+      return nil if value.nil?
+
+      Time.parse(value)
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # Represents a paginated list of messages
+  class MessageList
+    include Enumerable
+
+    # @return [Array<Message>] Messages in this page
+    attr_reader :data
+
+    # @return [Integer] Total number of messages
+    attr_reader :total
+
+    # @return [Integer] Current limit
+    attr_reader :limit
+
+    # @return [Integer] Current offset
+    attr_reader :offset
+
+    # @return [Boolean] Whether there are more pages
+    attr_reader :has_more
+
+    def initialize(response)
+      @data = (response["data"] || []).map { |m| Message.new(m) }
+      @total = response["count"] || @data.length
+      @limit = response["limit"] || 20
+      @offset = response["offset"] || 0
+      @has_more = (@offset + @data.length) < @total
+    end
+
+    # Iterate over messages
+    def each(&block)
+      data.each(&block)
+    end
+
+    # Get message count
+    # @return [Integer]
+    def count
+      data.length
+    end
+
+    alias size count
+    alias length count
+
+    # Check if empty
+    # @return [Boolean]
+    def empty?
+      data.empty?
+    end
+
+    # Get first message
+    # @return [Message, nil]
+    def first
+      data.first
+    end
+
+    # Get last message
+    # @return [Message, nil]
+    def last
+      data.last
+    end
+  end
+end

data/lib/sendly/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Sendly
+  VERSION = "1.0.5"
+end

data/lib/sendly/webhooks.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'json'
+
+module Sendly
+  # Webhook utilities for verifying and parsing Sendly webhook events.
+  #
+  # @example In a Rails controller
+  #   class WebhooksController < ApplicationController
+  #     skip_before_action :verify_authenticity_token
+  #
+  #     def handle
+  #       signature = request.headers['X-Sendly-Signature']
+  #       payload = request.raw_post
+  #
+  #       begin
+  #         event = Sendly::Webhooks.parse_event(payload, signature, ENV['WEBHOOK_SECRET'])
+  #
+  #         case event.type
+  #         when 'message.delivered'
+  #           puts "Message delivered: #{event.data.message_id}"
+  #         when 'message.failed'
+  #           puts "Message failed: #{event.data.error}"
+  #         end
+  #
+  #         head :ok
+  #       rescue Sendly::WebhookSignatureError
+  #         head :unauthorized
+  #       end
+  #     end
+  #   end
+  module Webhooks
+    class << self
+      # Verify webhook signature from Sendly.
+      #
+      # @param payload [String] Raw request body as string
+      # @param signature [String] X-Sendly-Signature header value
+      # @param secret [String] Your webhook secret from dashboard
+      # @return [Boolean] True if signature is valid, false otherwise
+      def verify_signature(payload, signature, secret)
+        return false if payload.nil? || payload.empty?
+        return false if signature.nil? || signature.empty?
+        return false if secret.nil? || secret.empty?
+
+        expected = 'sha256=' + OpenSSL::HMAC.hexdigest('SHA256', secret, payload)
+
+        # Timing-safe comparison
+        secure_compare(expected, signature)
+      end
+
+      # Parse and validate a webhook event.
+      #
+      # @param payload [String] Raw request body as string
+      # @param signature [String] X-Sendly-Signature header value
+      # @param secret [String] Your webhook secret from dashboard
+      # @return [WebhookEvent] Parsed and validated event
+      # @raise [WebhookSignatureError] If signature is invalid or payload is malformed
+      def parse_event(payload, signature, secret)
+        raise WebhookSignatureError, 'Invalid webhook signature' unless verify_signature(payload, signature, secret)
+
+        data = JSON.parse(payload, symbolize_names: true)
+
+        unless data[:id] && data[:type] && data[:data] && data[:created_at]
+          raise WebhookSignatureError, 'Invalid event structure'
+        end
+
+        WebhookEvent.new(data)
+      rescue JSON::ParserError => e
+        raise WebhookSignatureError, "Failed to parse webhook payload: #{e.message}"
+      end
+
+      # Generate a webhook signature for testing purposes.
+      #
+      # @param payload [String] The payload to sign
+      # @param secret [String] The secret to use for signing
+      # @return [String] The signature in the format "sha256=..."
+      def generate_signature(payload, secret)
+        'sha256=' + OpenSSL::HMAC.hexdigest('SHA256', secret, payload)
+      end
+
+      private
+
+      # Timing-safe string comparison
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        l = a.unpack('C*')
+        res = 0
+        b.each_byte { |byte| res |= byte ^ l.shift }
+        res.zero?
+      end
+    end
+  end
+
+  # Webhook signature verification error
+  class WebhookSignatureError < Error
+    def initialize(message = 'Invalid webhook signature')
+      super(message, code: 'WEBHOOK_SIGNATURE_ERROR')
+    end
+  end
+
+  # Webhook event from Sendly
+  class WebhookEvent
+    attr_reader :id, :type, :data, :created_at, :api_version
+
+    def initialize(data)
+      @id = data[:id]
+      @type = data[:type]
+      @data = WebhookMessageData.new(data[:data])
+      @created_at = data[:created_at]
+      @api_version = data[:api_version] || '2024-01-01'
+    end
+
+    def to_h
+      {
+        id: @id,
+        type: @type,
+        data: @data.to_h,
+        created_at: @created_at,
+        api_version: @api_version
+      }
+    end
+  end
+
+  # Webhook message data
+  class WebhookMessageData
+    attr_reader :message_id, :status, :to, :from, :error, :error_code,
+                :delivered_at, :failed_at, :segments, :credits_used
+
+    def initialize(data)
+      @message_id = data[:message_id]
+      @status = data[:status]
+      @to = data[:to]
+      @from = data[:from] || ''
+      @error = data[:error]
+      @error_code = data[:error_code]
+      @delivered_at = data[:delivered_at]
+      @failed_at = data[:failed_at]
+      @segments = data[:segments] || 1
+      @credits_used = data[:credits_used] || 0
+    end
+
+    def to_h
+      {
+        message_id: @message_id,
+        status: @status,
+        to: @to,
+        from: @from,
+        error: @error,
+        error_code: @error_code,
+        delivered_at: @delivered_at,
+        failed_at: @failed_at,
+        segments: @segments,
+        credits_used: @credits_used
+      }.compact
+    end
+  end
+end

data/lib/sendly.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "sendly/version"
+require_relative "sendly/errors"
+require_relative "sendly/types"
+require_relative "sendly/client"
+require_relative "sendly/messages"
+require_relative "sendly/webhooks"
+
+# Sendly Ruby SDK
+#
+# Official Ruby client for the Sendly SMS API.
+#
+# @example Basic usage
+#   client = Sendly::Client.new("sk_live_v1_xxx")
+#   message = client.messages.send(to: "+15551234567", text: "Hello!")
+#
+module Sendly
+  class << self
+    # @return [String, nil] Default API key
+    attr_accessor :api_key
+
+    # @return [String] Default base URL
+    attr_accessor :base_url
+
+    # Configure the SDK with default options
+    #
+    # @yield [self] Yields self for configuration
+    # @return [void]
+    #
+    # @example
+    #   Sendly.configure do |config|
+    #     config.api_key = "sk_live_v1_xxx"
+    #   end
+    def configure
+      yield self
+    end
+
+    # Create a client with the default API key
+    #
+    # @return [Sendly::Client]
+    def client
+      @client ||= Client.new(api_key: api_key)
+    end
+
+    # Send a message using the default client
+    #
+    # @param to [String] Recipient phone number
+    # @param text [String] Message content
+    # @return [Sendly::Message]
+    def send_message(to:, text:)
+      client.messages.send(to: to, text: text)
+    end
+  end
+
+  self.base_url = "https://sendly.live/api/v1"
+end