codemail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8642b106a9ff9e6155704db2a0c3c0796c4a54b167bb4f61e19939c3492fed39
+  data.tar.gz: 534bf7af8368ce614660e7db9e715331118ac7e531136e9c8ddce0cb02820786
+SHA512:
+  metadata.gz: 887d88c965334332ef40410ee229308a529716da7ad7566df3a700c59e4f0c12bb7b285b1928468071bf6244a7ce7c8e2130dc9ce07ae95f0cdaa2de75fdd99d
+  data.tar.gz: d0e0e268d8008e77ce87d820ef8eb28b0a3256780b805eedd3d6634166941dc256ff9e7d3574f6296c0094a9579b93717103604f6ab8dda9cfe838c877fd6aae

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codemail
+
+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,31 @@
+# Codemail para Ruby
+
+```bash
+gem install codemail
+```
+
+```ruby
+require "codemail"
+
+cm = Codemail::Client.new("cm_live_...")   # ou defina CODEMAIL_API_KEY
+
+r = cm.emails.create(
+  from: "alerta@meudominio.com.br",        # precisa ser do domínio da chave
+  to: "ana@cliente.com",                   # um endereço ou um array
+  subject: "Seu pedido foi enviado",
+  html: "<p>Olá!</p>",
+  attachments: [Codemail::Attachment.from_file("nota.pdf")]
+)
+puts r.id, r.status                        # status: queued (o envio é assíncrono)
+
+cm.emails.get(r.id)
+cm.emails.events(r.id)
+cm.emails.list(status: "bounced", limit: 20)
+```
+
+`emails.create` é o `send` dos outros SDKs (em Ruby, `send` já é um método de `Object`); `deliver` é um alias.
+
+- **Idempotente por padrão** e com retentativas (rede, 429 com `Retry-After`, 5xx), até `max_retries` (padrão 2).
+- **Erros** (`Codemail::...`): `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `InvalidRequestError`
+  (`#param`), `RateLimitError` (`#retry_after`), `ServerError`, `ConnectionError`; todos herdam de `Codemail::Error`.
+- Só biblioteca padrão. Ruby 3.0+.

data/lib/codemail/errors.rb

@@ -0,0 +1,28 @@
+module Codemail
+  # Base de todos os erros do SDK. Nunca carrega a chave de API.
+  class Error < StandardError
+    attr_reader :status, :type, :param, :retry_after
+
+    def initialize(message, status: nil, type: nil, param: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @type = type
+      @param = param
+      @retry_after = retry_after
+    end
+
+    def to_s
+      return super unless status
+
+      "#{super} (HTTP #{status}#{type ? ", #{type}" : ""})"
+    end
+  end
+
+  class AuthenticationError < Error; end   # 401
+  class PermissionDeniedError < Error; end # 403
+  class NotFoundError < Error; end         # 404
+  class InvalidRequestError < Error; end   # 400, 422 (param indica o campo)
+  class RateLimitError < Error; end        # 429 (retry_after em segundos)
+  class ServerError < Error; end           # 5xx
+  class ConnectionError < Error; end       # sem resposta
+end

data/lib/codemail/version.rb

@@ -0,0 +1,3 @@
+module Codemail
+  VERSION = "0.1.0"
+end

data/lib/codemail.rb

@@ -0,0 +1,172 @@
+require "json"
+require "net/http"
+require "securerandom"
+require "time"
+require "uri"
+require_relative "codemail/version"
+require_relative "codemail/errors"
+
+# SDK Ruby da Codemail.
+#
+#   cm = Codemail::Client.new("cm_live_...")
+#   r  = cm.emails.create(from: "ola@meudominio.com.br", to: "ana@cliente.com", subject: "Oi", text: "Olá!")
+#   r.id # => "..."
+module Codemail
+  BASE_URL = "https://api.codemail.com.br/v1".freeze
+  TETO_ESPERA = 30.0
+
+  # Anexo. `content` são os bytes do arquivo (o SDK codifica em base64).
+  Attachment = Struct.new(:filename, :content, :content_type, keyword_init: true) do
+    def self.from_file(path, filename: nil, content_type: nil)
+      new(filename: filename || File.basename(path), content: File.binread(path),
+          content_type: content_type || "application/octet-stream")
+    end
+
+    def to_h
+      { filename: filename, content: [content.to_s].pack("m0"), content_type: content_type || "application/octet-stream" }
+    end
+  end
+
+  SendResult = Struct.new(:id, :status, :to, :cc, :bcc, :subject, :created_at, keyword_init: true)
+  Email = Struct.new(:id, :status, :from, :to, :subject, :error, :created_at, :updated_at, keyword_init: true)
+  EmailEvent = Struct.new(:type, :occurred_at, keyword_init: true)
+  EmailList = Struct.new(:data, :total, :limit, :offset, keyword_init: true)
+
+  def self.hora(v)
+    return nil if v.nil? || v.to_s.empty?
+
+    s = v.to_s
+    # A API devolve UTC sem fuso (2026-10-15T12:00:00).
+    Time.parse(s =~ /(Z|[+-]\d\d:?\d\d)\z/ ? s : "#{s}Z")
+  end
+
+  class Emails
+    def initialize(client)
+      @client = client
+    end
+
+    # Enfileira um e-mail. `from` precisa ser do domínio da chave. O envio é assíncrono (status "queued").
+    def create(from:, to:, subject: nil, text: nil, html: nil, from_name: nil, cc: nil, bcc: nil, reply_to: nil,
+               attachments: nil, idempotency_key: nil)
+      destinos = Array(to)
+      raise InvalidRequestError.new("Informe ao menos um destinatário em `to`.", param: "to") if destinos.empty?
+
+      corpo = { from: from, to: destinos }
+      { from_name: from_name, cc: cc && Array(cc), bcc: bcc && Array(bcc), reply_to: reply_to, subject: subject,
+        text: text, html: html }.each { |k, v| corpo[k] = v unless v.nil? }
+      if attachments && !attachments.empty?
+        corpo[:attachments] = attachments.map { |a| a.respond_to?(:to_h) && !a.is_a?(Hash) ? a.to_h : a }
+      end
+      r = @client.request(:post, "/emails", body: corpo, idempotency_key: idempotency_key || SecureRandom.uuid)
+      SendResult.new(id: r["id"], status: r["status"], to: r["to"] || [], cc: r["cc"] || [], bcc: r["bcc"] || [],
+                     subject: r["subject"].to_s, created_at: Codemail.hora(r["created_at"]))
+    end
+    alias deliver create
+
+    def get(id)
+      email(@client.request(:get, "/emails/#{URI.encode_www_form_component(id)}"))
+    end
+
+    def list(status: nil, search: nil, start_date: nil, end_date: nil, limit: nil, offset: nil)
+      dia = ->(d) { d.respond_to?(:strftime) ? d.strftime("%Y-%m-%d") : d }
+      r = @client.request(:get, "/emails", query: { status: status, search: search, start_date: dia.(start_date),
+                                                    end_date: dia.(end_date), limit: limit, offset: offset })
+      EmailList.new(data: (r["data"] || []).map { |m| email(m) }, total: r["total"], limit: r["limit"],
+                    offset: r["offset"])
+    end
+
+    def events(id)
+      r = @client.request(:get, "/emails/#{URI.encode_www_form_component(id)}/events")
+      (r["data"] || []).map { |e| EmailEvent.new(type: e["type"], occurred_at: Codemail.hora(e["occurred_at"])) }
+    end
+
+    private
+
+    def email(d)
+      Email.new(id: d["id"], status: d["status"], from: d["mail_from"], to: d["to"] || [], subject: d["subject"],
+                error: d["error"], created_at: Codemail.hora(d["created_at"]), updated_at: Codemail.hora(d["updated_at"]))
+    end
+  end
+
+  class Client
+    attr_reader :emails, :base_url
+
+    def initialize(api_key = nil, base_url: nil, timeout: 30, max_retries: 2)
+      key = api_key || ENV["CODEMAIL_API_KEY"]
+      raise AuthenticationError, "Informe a chave de API ou defina CODEMAIL_API_KEY." if key.nil? || key.empty?
+
+      @api_key = key
+      @base_url = (base_url || ENV["CODEMAIL_API_URL"] || BASE_URL).sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = [max_retries.to_i, 0].max
+      @emails = Emails.new(self)
+    end
+
+    # A chave nunca aparece em inspect/logs.
+    def inspect
+      "#<Codemail::Client base_url=#{@base_url.inspect}>"
+    end
+    alias to_s inspect
+
+    # @api private
+    def request(metodo, caminho, body: nil, query: nil, idempotency_key: nil)
+      uri = URI.parse(@base_url + caminho)
+      q = (query || {}).reject { |_, v| v.nil? }
+      uri.query = URI.encode_www_form(q) unless q.empty?
+      tentativa = 0
+      loop do
+        begin
+          return uma_vez(metodo, uri, body, idempotency_key)
+        rescue ConnectionError, RateLimitError, ServerError => e
+          raise if tentativa >= @max_retries
+
+          espera = e.retry_after ? [e.retry_after, TETO_ESPERA].min : 0.5 * (2**tentativa) * (0.5 + rand / 2)
+          sleep(espera)
+          tentativa += 1
+        end
+      end
+    end
+
+    private
+
+    def uma_vez(metodo, uri, body, idem)
+      req = (metodo == :post ? Net::HTTP::Post : Net::HTTP::Get).new(uri)
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Accept"] = "application/json"
+      req["User-Agent"] = "codemail-ruby/#{VERSION}"
+      req["Idempotency-Key"] = idem if idem
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout,
+                                                read_timeout: @timeout) { |h| h.request(req) }
+      return res.body.to_s.empty? ? {} : JSON.parse(res.body) if res.code.to_i.between?(200, 299)
+
+      raise erro_http(res)
+    rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout, IOError, OpenSSL::SSL::SSLError => e
+      raise ConnectionError, "Não foi possível falar com a Codemail: #{e.class}: #{e.message}"
+    end
+
+    def erro_http(res)
+      status = res.code.to_i
+      info = begin
+        JSON.parse(res.body.to_s)["error"] || {}
+      rescue JSON::ParserError
+        {}
+      end
+      ra = res["Retry-After"]
+      retry_after = ra && ra =~ /\A\d+(\.\d+)?\z/ ? ra.to_f : nil
+      classe = case status
+               when 401 then AuthenticationError
+               when 403 then PermissionDeniedError
+               when 404 then NotFoundError
+               when 429 then RateLimitError
+               when 500.. then ServerError
+               else InvalidRequestError
+               end
+      classe.new(info["message"] || "A API respondeu #{status}", status: status, type: info["type"],
+                 param: info["param"], retry_after: retry_after)
+    end
+  end
+end

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: codemail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Codemail
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-19 00:00:00.000000000 Z
+dependencies: []
+description: Cliente oficial da API do Transacional da Codemail, com idempotência
+  automática, retentativas e erros tipados.
+email:
+- suporte@codemail.com.br
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/codemail.rb
+- lib/codemail/errors.rb
+- lib/codemail/version.rb
+homepage: https://codemail.com.br
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://codemail.com.br
+  source_code_uri: https://github.com/codemail/codemail-ruby
+  bug_tracker_uri: https://github.com/codemail/codemail-ruby/issues
+  changelog_uri: https://github.com/codemail/codemail-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+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: 'SDK Ruby da Codemail: envio de e-mail transacional por API.'
+test_files: []