opensend 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 349126cf4fb71e6ae38091a0ca4e7a800031bbcf11b0284f033206fd16331f67
+  data.tar.gz: 01b7aec53d77983da3e737bed3f3575f45871eca0ce9f03dc7eaf18d92920fd9
+SHA512:
+  metadata.gz: a6ab3ec4098d2b45771e13ac5fa830eb8d910a5142591496fceb2c49f1da693c26441bc0b826730e6a88f2024d956278dab3d8532a3a70b3e745b2a5d49ae2a4
+  data.tar.gz: 657a432a912b857007d05b8cd133ad73b69e7f07016642fb877d5a2acfcc0daf1401cb4ae9c24ef59658bbdbd3cffcccbe74ee4363a1867ca39377f57f114989

data/README.md

@@ -0,0 +1,124 @@
+# opensend Ruby SDK
+
+Minimal first-party Ruby SDK for OpenSend transactional email sends with a
+familiar API surface.
+
+Use your OpenSend API key (`os_...`) with OpenSend's Ruby API surface.
+Existing Resend-style send calls can migrate through the alias documented
+below.
+
+## Installation
+
+This package is ready for RubyGems publishing. Until the RubyGems publish is
+complete, install the built gem from this repository:
+
+```bash
+cd packages/ruby-sdk
+gem build opensend.gemspec
+gem install ./opensend-0.1.0.gem
+```
+
+After `opensend` is published to RubyGems, install it with:
+
+```bash
+gem install opensend
+```
+
+## Setup
+
+Use an environment variable instead of hardcoding API keys:
+
+```bash
+export OPENSEND_API_KEY="os_your_api_key"
+```
+
+For self-hosted OpenSend, point the SDK at your deployment origin. The default
+hosted origin is `https://opensend.namuh.co`.
+
+```bash
+export OPENSEND_BASE_URL="http://localhost:3015"
+```
+
+## Send an email
+
+The module-level surface uses OpenSend while keeping familiar Ruby email-send
+ergonomics:
+
+```ruby
+require "opensend"
+
+OpenSend.api_key ENV.fetch("OPENSEND_API_KEY")
+OpenSend.base_url ENV.fetch("OPENSEND_BASE_URL", OpenSend::DEFAULT_BASE_URL)
+
+email = OpenSend::Emails.send(
+  from: "hello@yourdomain.com",
+  to: "recipient@example.com",
+  subject: "Hello from OpenSend",
+  html: "<h1>It works!</h1>"
+)
+
+puts email.fetch("id")
+```
+
+`Resend` is also exported as an alias constant for existing send code migrating
+to OpenSend:
+
+```ruby
+require "opensend"
+
+Resend.api_key ENV.fetch("OPENSEND_API_KEY")
+email = Resend::Emails.send(
+  from: "hello@yourdomain.com",
+  to: ["recipient@example.com"],
+  subject: "Hello from OpenSend",
+  text: "It works!"
+)
+```
+
+## Instance client
+
+```ruby
+client = OpenSend::Client.new(
+  api_key: ENV.fetch("OPENSEND_API_KEY"),
+  base_url: ENV.fetch("OPENSEND_BASE_URL", OpenSend::DEFAULT_BASE_URL)
+)
+
+email = client.emails.send(
+  from: "hello@yourdomain.com",
+  to: "recipient@example.com",
+  subject: "Hello from OpenSend",
+  html: "<h1>It works!</h1>"
+)
+```
+
+## Errors
+
+Non-2xx API responses raise `OpenSend::Error` (also exported as
+`OpenSend::APIError`). The exception keeps OpenSend's public error envelope
+fields when present.
+
+```ruby
+begin
+  OpenSend::Emails.send(params)
+rescue OpenSend::Error => error
+  warn [error.status_code, error.code, error.message, error.details].inspect
+end
+```
+
+## Supported first slice
+
+- `OpenSend::Emails.send(params)` → `POST /emails`
+- `OpenSend::Client#emails.send(params)` → `POST /emails`
+- Bearer API key auth
+- Configurable base URL
+- Structured API error envelope parsing
+- Resend alias constant for existing send code migrating to OpenSend
+
+This first package intentionally does not implement batch sends, async jobs,
+attachments helpers, or full resource-surface parity yet.
+
+## Tests
+
+```bash
+ruby -I packages/ruby-sdk/lib packages/ruby-sdk/test/opensend_test.rb
+```

data/lib/opensend/version.rb

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

data/lib/opensend.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "opensend/version"
+
+module OpenSend
+  DEFAULT_BASE_URL = "https://opensend.namuh.co"
+  USER_AGENT = "opensend-ruby/#{VERSION}"
+
+  class << self
+    attr_writer :api_key, :base_url
+
+    def api_key(value = nil)
+      @api_key = value unless value.nil?
+      @api_key
+    end
+
+    def base_url(value = nil)
+      @base_url = value unless value.nil?
+      @base_url || DEFAULT_BASE_URL
+    end
+
+    def emails
+      EmailsResource.new(Client.new(api_key: configured_api_key, base_url: base_url))
+    end
+
+    private
+
+    def configured_api_key
+      key = api_key
+      raise ArgumentError, "set OpenSend.api_key before making API requests" if key.nil? || key.to_s.strip.empty?
+
+      key
+    end
+  end
+
+  class Error < StandardError
+    attr_reader :status_code, :name, :code, :details, :body
+
+    def initialize(message, status_code:, name: nil, code: nil, details: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @name = name
+      @code = code
+      @details = details
+      @body = body
+    end
+  end
+
+  APIError = Error
+
+  class Client
+    attr_reader :api_key, :base_url
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL)
+      @api_key = normalize_api_key(api_key)
+      @base_uri = normalize_base_url(base_url)
+      @base_url = @base_uri.to_s
+    end
+
+    def emails
+      EmailsResource.new(self)
+    end
+
+    def post(path, payload)
+      uri = endpoint(path)
+      request = Net::HTTP::Post.new(uri)
+      request["Authorization"] = "Bearer #{api_key}"
+      request["Content-Type"] = "application/json"
+      request["Accept"] = "application/json"
+      request["User-Agent"] = USER_AGENT
+      request.body = JSON.generate(payload)
+
+      response = perform_request(uri, request)
+      body = response.body.to_s
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise api_error(response, body)
+      end
+
+      body.empty? ? {} : JSON.parse(body)
+    rescue JSON::ParserError => error
+      raise Error.new(
+        "Invalid JSON response from OpenSend",
+        status_code: 0,
+        name: "parse_error",
+        code: "parse_error",
+        body: error.message
+      )
+    rescue IOError, SystemCallError, Timeout::Error, SocketError => error
+      raise Error.new(
+        error.message,
+        status_code: 0,
+        name: "request_error",
+        code: "request_error"
+      )
+    end
+
+    private
+
+    def normalize_api_key(value)
+      key = value.to_s.strip
+      raise ArgumentError, "API key is required" if key.empty?
+
+      key
+    end
+
+    def normalize_base_url(value)
+      raw = value.to_s.strip
+      raise ArgumentError, "base URL must be a non-empty string" if raw.empty?
+
+      uri = URI.parse(raw)
+      unless uri.is_a?(URI::HTTP) && uri.host
+        raise ArgumentError, "base URL must be a valid absolute http or https URL"
+      end
+
+      uri.path = uri.path.to_s.sub(%r{/+\z}, "")
+      uri.query = nil
+      uri.fragment = nil
+      uri
+    rescue URI::InvalidURIError
+      raise ArgumentError, "base URL must be a valid absolute http or https URL"
+    end
+
+    def endpoint(path)
+      uri = @base_uri.dup
+      base_path = uri.path.to_s.sub(%r{/+\z}, "")
+      request_path = "/#{path.to_s.sub(%r{\A/+}, "")}"
+      uri.path = base_path.empty? ? request_path : "#{base_path}#{request_path}"
+      uri.query = nil
+      uri.fragment = nil
+      uri
+    end
+
+    def perform_request(uri, request)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        http.request(request)
+      end
+    end
+
+    def api_error(response, body)
+      envelope = parse_json_object(body)
+      message = envelope["message"] || response.message || "OpenSend API request failed"
+
+      Error.new(
+        message,
+        status_code: response.code.to_i,
+        name: envelope["name"],
+        code: envelope["code"],
+        details: envelope["details"],
+        body: body
+      )
+    end
+
+    def parse_json_object(body)
+      parsed = body.empty? ? {} : JSON.parse(body)
+      parsed.is_a?(Hash) ? parsed : {}
+    rescue JSON::ParserError
+      {}
+    end
+  end
+
+  class EmailsResource
+    def initialize(client)
+      @client = client
+    end
+
+    def send(params)
+      @client.post("/emails", params)
+    end
+  end
+
+  module Emails
+    def self.send(params, api_key: nil, base_url: nil)
+      key = api_key || OpenSend.api_key
+      raise ArgumentError, "set OpenSend.api_key before making API requests" if key.nil? || key.to_s.strip.empty?
+
+      Client.new(api_key: key, base_url: base_url || OpenSend.base_url).emails.send(params)
+    end
+  end
+end
+
+Resend = OpenSend unless defined?(Resend)

data/opensend.gemspec

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lib/opensend/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "opensend"
+  spec.version = OpenSend::VERSION
+  spec.summary = "Ruby SDK for the OpenSend email API"
+  spec.description = "Minimal first-party Ruby SDK for OpenSend transactional email sends with a familiar API surface."
+  spec.authors = ["OpenSend"]
+  spec.homepage = "https://github.com/namuh-eng/opensend"
+  # RubyGems 3.0 does not recognize Elastic-2.0 as SPDX, so keep builds warning-free
+  # while linking to the repository license below.
+  spec.license = "Nonstandard"
+  spec.required_ruby_version = ">= 2.6"
+  spec.metadata = {
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/namuh-eng/opensend",
+    "bug_tracker_uri" => "https://github.com/namuh-eng/opensend/issues",
+    "license_uri" => "https://github.com/namuh-eng/opensend/blob/main/LICENSE"
+  }
+
+  spec.files = Dir["lib/**/*.rb", "README.md", "opensend.gemspec"]
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: opensend
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- OpenSend
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-23 00:00:00.000000000 Z
+dependencies: []
+description: Minimal first-party Ruby SDK for OpenSend transactional email sends with
+  a familiar API surface.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/opensend.rb
+- lib/opensend/version.rb
+- opensend.gemspec
+homepage: https://github.com/namuh-eng/opensend
+licenses:
+- Nonstandard
+metadata:
+  homepage_uri: https://github.com/namuh-eng/opensend
+  source_code_uri: https://github.com/namuh-eng/opensend
+  bug_tracker_uri: https://github.com/namuh-eng/opensend/issues
+  license_uri: https://github.com/namuh-eng/opensend/blob/main/LICENSE
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for the OpenSend email API
+test_files: []