smbcloud-email 1.0.0

data/Cargo.toml

@@ -0,0 +1,8 @@
+# This Cargo.toml is here to let external tools (IDEs, etc.) know that this is a
+# Rust project. Your extension dependencies should be added to the Cargo.toml in
+# the ext/ directory.
+
+[workspace]
+members = ["./ext/email"]
+resolver = "2"
+

data/README.md

@@ -0,0 +1,68 @@
+# smbcloud-email (Ruby)
+
+Ruby bindings for the **smbCloud transactional email API**, powered by the shared
+Rust SDK ([`smbcloud-email-sdk`](../../../crates/smbcloud-email-sdk)) and a native
+[Magnus](https://github.com/matsadler/magnus) extension.
+
+## Install
+
+```ruby
+gem 'smbcloud-email'
+```
+
+The gem ships a native extension; `bundle install` compiles it (Rust toolchain
+required).
+
+## Usage
+
+```ruby
+require 'email'
+
+client = SmbCloud::Email.client(
+  environment: SmbCloud::Email::Environment::PRODUCTION,
+  api_key: 'smb_mail_your_key',
+)
+
+# Send
+sent = client.send(
+  from: 'billing@example.com',
+  to: ['customer@acme.com'],
+  subject: 'Your receipt',
+  html: '<h1>Thanks!</h1>',
+  text: 'Thanks!',
+  idempotency_key: 'receipt-2026-0001',
+)
+sent[:id]      # => "eml_…"
+sent[:status]  # => 1 (sent)
+
+# Attachments, cc/bcc, headers, tags
+client.send(
+  from: 'billing@example.com',
+  to: ['customer@acme.com'],
+  subject: 'Invoice',
+  html: '<p>See attached.</p>',
+  cc: ['accounts@acme.com'],
+  attachments: [{ filename: 'invoice.pdf', content_base64: 'JVBERi0xLjQ...' }],
+  headers: { 'X-Entity-Ref-ID' => 'inv_123' },
+  tags: { 'category' => 'invoice' },
+)
+
+# Delivery status (needs a read-scope key)
+message = client.get_message('eml_…')
+message[:status]
+message[:events]
+
+client.list_messages(status: 'bounced', limit: 20)
+```
+
+Mint an API key for your Mail app in the smbCloud console. Sending is scoped to
+that app's verified domain; reading messages needs a read-scope key.
+
+## Errors
+
+Non-2xx API responses and transport failures raise `SmbCloud::Email::Error`, with
+the parsed response body available on `#payload`.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rb_sys/extensiontask'
+
+task build: :compile
+
+GEMSPEC = Gem::Specification.load('email.gemspec')
+
+RbSys::ExtensionTask.new('email', GEMSPEC) do |ext|
+  ext.lib_dir = 'lib/email'
+  ext.cross_compile = true
+  ext.cross_platform = %w[x86_64-linux aarch64-linux arm64-darwin x86_64-darwin]
+end
+
+task default: :compile

data/ext/email/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "email"
+version = "1.0.0"
+edition = "2024"
+authors = ["Seto Elkahfi <seto@smbcloud.xyz>"]
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = "0.8"
+serde_json = "1"
+tokio = { version = "1", features = ["rt-multi-thread"] }
+
+# The published transactional-email SDK. For local development this is patched
+# to the in-repo crate via `[patch.crates-io]` in the gem workspace Cargo.toml.
+smbcloud-email-sdk = { version = "1.0" }

data/ext/email/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('email/email')

data/ext/email/src/lib.rs

@@ -0,0 +1,95 @@
+use magnus::{function, prelude::*, Error, Ruby};
+use smbcloud_email_sdk::{EmailClient, EmailCredentials, Environment, SendEmail};
+use tokio::runtime::Runtime;
+
+// Every helper here runs on the Ruby thread that called into the extension
+// (tokio's `block_on` stays on the calling thread), so the handle is available.
+fn ruby() -> Ruby {
+    Ruby::get().expect("smbcloud-email called outside a Ruby thread")
+}
+
+fn parse_environment(value: String) -> Result<Environment, Error> {
+    value.parse().map_err(|_| {
+        Error::new(
+            ruby().exception_arg_error(),
+            format!("invalid environment `{value}`, expected `dev` or `production`"),
+        )
+    })
+}
+
+fn with_runtime<T, F>(f: F) -> Result<T, Error>
+where
+    F: FnOnce(&Runtime) -> Result<T, Error>,
+{
+    let runtime = Runtime::new().map_err(|err| {
+        Error::new(
+            ruby().exception_runtime_error(),
+            format!("failed to initialize tokio runtime: {err}"),
+        )
+    })?;
+    f(&runtime)
+}
+
+fn runtime_error(message: impl std::fmt::Display) -> Error {
+    Error::new(ruby().exception_runtime_error(), message.to_string())
+}
+
+fn client(environment: Environment, api_key: &str) -> EmailClient {
+    EmailClient::from_credentials(environment, EmailCredentials { api_key })
+}
+
+/// `message_json` is the SendEmail payload built on the Ruby side. Returns the
+/// created message as JSON.
+fn send_json(environment: String, api_key: String, message_json: String) -> Result<String, Error> {
+    let env = parse_environment(environment)?;
+    let message: SendEmail = serde_json::from_str(&message_json)
+        .map_err(|err| Error::new(ruby().exception_arg_error(), format!("invalid message: {err}")))?;
+
+    with_runtime(|runtime| {
+        match runtime.block_on(client(env, &api_key).send(&message)) {
+            Ok(result) => serde_json::to_string(&result).map_err(runtime_error),
+            Err(error) => Err(runtime_error(error)),
+        }
+    })
+}
+
+fn get_message_json(environment: String, api_key: String, id: String) -> Result<String, Error> {
+    let env = parse_environment(environment)?;
+    with_runtime(|runtime| {
+        match runtime.block_on(client(env, &api_key).get_message(&id)) {
+            Ok(result) => serde_json::to_string(&result).map_err(runtime_error),
+            Err(error) => Err(runtime_error(error)),
+        }
+    })
+}
+
+/// `status` empty string means "no filter"; `limit` <= 0 means "server default".
+fn list_messages_json(
+    environment: String,
+    api_key: String,
+    status: String,
+    limit: i64,
+) -> Result<String, Error> {
+    let env = parse_environment(environment)?;
+    let status = if status.trim().is_empty() { None } else { Some(status) };
+    let limit = if limit > 0 { Some(limit as u32) } else { None };
+
+    with_runtime(|runtime| {
+        match runtime.block_on(client(env, &api_key).list_messages(status.as_deref(), limit)) {
+            Ok(result) => serde_json::to_string(&result).map_err(runtime_error),
+            Err(error) => Err(runtime_error(error)),
+        }
+    })
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let smbcloud = ruby.define_module("SmbCloud")?;
+    let email = smbcloud.define_module("Email")?;
+
+    email.define_singleton_method("__send", function!(send_json, 3))?;
+    email.define_singleton_method("__get_message", function!(get_message_json, 3))?;
+    email.define_singleton_method("__list_messages", function!(list_messages_json, 4))?;
+
+    Ok(())
+}

data/lib/email/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Email
+  VERSION = '1.0.0'
+end

data/lib/email.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'email/version'
+# Fat native gems ship one extension per Ruby minor (lib/email/3.4/email.bundle);
+# source and single-ABI builds put it directly under lib/email/.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "email/#{Regexp.last_match(1)}/email"
+rescue LoadError
+  require_relative 'email/email'
+end
+
+module Email
+end
+
+module SmbCloud
+  # Ruby bindings for the smbCloud transactional email API, powered by the shared
+  # Rust SDK (smbcloud-email-sdk) and a native Magnus extension.
+  #
+  # @example
+  #   client = SmbCloud::Email.client(environment: "production", api_key: "smb_mail_…")
+  #   sent = client.send(
+  #     from: "billing@example.com",
+  #     to: ["customer@acme.com"],
+  #     subject: "Your receipt",
+  #     html: "<h1>Thanks!</h1>",
+  #     idempotency_key: "receipt-2026-0001",
+  #   )
+  #   sent[:id] # => "eml_…"
+  module Email
+    class Error < StandardError
+      attr_reader :payload
+
+      def initialize(message = nil, payload: nil)
+        super(message)
+        @payload = payload
+      end
+    end
+
+    module Environment
+      DEV = 'dev'
+      PRODUCTION = 'production'
+    end
+
+    class Client
+      attr_reader :environment, :api_key
+
+      def initialize(environment:, api_key:)
+        @environment = environment
+        @api_key = api_key
+      end
+
+      # Send a transactional email. `from` must be on the API key's verified
+      # domain; provide at least one of `html`/`text`. `attachments` is an array
+      # of { filename:, content_base64: }. Returns the created message hash.
+      def send(from:, to:, subject: nil, html: nil, text: nil, cc: nil, bcc: nil,
+               reply_to: nil, attachments: nil, headers: nil, tags: nil,
+               idempotency_key: nil)
+        message = {
+          from: from,
+          to: Array(to),
+          cc: Array(cc),
+          bcc: Array(bcc),
+          reply_to: Array(reply_to),
+          subject: subject,
+          html: html,
+          text: text,
+          attachments: Array(attachments),
+          headers: headers || {},
+          tags: tags || {},
+          idempotency_key: idempotency_key
+        }.compact
+
+        Email.send(:parse_json, Email.__send(environment, api_key, JSON.generate(message)))
+      rescue RuntimeError => e
+        raise Email.send(:normalize_error, e)
+      end
+
+      # Fetch one message by id, including its delivery-event timeline. Requires
+      # a read-scope key.
+      def get_message(id)
+        Email.send(:parse_json, Email.__get_message(environment, api_key, id))
+      rescue RuntimeError => e
+        raise Email.send(:normalize_error, e)
+      end
+
+      # List recent messages. `status` filters by delivery status name; `limit`
+      # is clamped server-side to 1..=100. Requires a read-scope key.
+      def list_messages(status: nil, limit: nil)
+        Email.send(:parse_json,
+                   Email.__list_messages(environment, api_key, status.to_s, limit.to_i))
+      rescue RuntimeError => e
+        raise Email.send(:normalize_error, e)
+      end
+    end
+
+    class << self
+      def client(environment:, api_key:)
+        Client.new(environment:, api_key:)
+      end
+
+      def send_with_client(environment:, api_key:, **kwargs)
+        client(environment:, api_key:).send(**kwargs)
+      end
+
+      def get_message_with_client(environment:, api_key:, id:)
+        client(environment:, api_key:).get_message(id)
+      end
+
+      def list_messages_with_client(environment:, api_key:, status: nil, limit: nil)
+        client(environment:, api_key:).list_messages(status:, limit:)
+      end
+
+      private
+
+      def parse_json(payload)
+        return payload unless payload.is_a?(String)
+
+        JSON.parse(payload, symbolize_names: true)
+      end
+
+      def normalize_error(error)
+        payload = parse_json(error.message)
+        message = payload.is_a?(Hash) ? (payload[:message] || error.message) : error.message
+        Error.new(message, payload: payload)
+      rescue JSON::ParserError, NoMethodError, TypeError
+        Error.new(error.message)
+      end
+    end
+  end
+end

data/sig/email.rbs

@@ -0,0 +1,28 @@
+module Email
+  VERSION: String
+end
+
+module SmbCloud
+  module Email
+    class Error < StandardError
+      attr_reader payload: untyped
+    end
+
+    module Environment
+      DEV: String
+      PRODUCTION: String
+    end
+
+    class Client
+      attr_reader environment: String
+      attr_reader api_key: String
+
+      def initialize: (environment: String, api_key: String) -> void
+      def send: (from: String, to: untyped, ?subject: String?, ?html: String?, ?text: String?, ?cc: untyped, ?bcc: untyped, ?reply_to: untyped, ?attachments: untyped, ?headers: untyped, ?tags: untyped, ?idempotency_key: String?) -> Hash[Symbol, untyped]
+      def get_message: (String) -> Hash[Symbol, untyped]
+      def list_messages: (?status: String?, ?limit: Integer?) -> Array[Hash[Symbol, untyped]]
+    end
+
+    def self.client: (environment: String, api_key: String) -> Client
+  end
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: smbcloud-email
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Seto Elkahfi
+bindir: exe
+cert_chain: []
+date: 2026-10-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.9.130
+description: Send transactional email from a verified domain and read delivery status,
+  powered by the shared Rust SDK and a native Magnus extension.
+email:
+- seto@smbcloud.xyz
+executables: []
+extensions:
+- ext/email/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Cargo.lock
+- Cargo.toml
+- README.md
+- Rakefile
+- ext/.keep
+- ext/email/Cargo.toml
+- ext/email/extconf.rb
+- ext/email/src/lib.rs
+- lib/email.rb
+- lib/email/version.rb
+- sig/email.rbs
+homepage: https://github.com/smbcloudXYZ/smbcloud-cli/tree/main/sdk/gems/email
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/smbcloudXYZ/smbcloud-cli/tree/main/sdk/gems/email
+  source_code_uri: https://github.com/smbcloudXYZ/smbcloud-cli/tree/main/sdk/gems/email
+  changelog_uri: https://github.com/smbcloudXYZ/smbcloud-cli/tree/main/sdk/gems/email/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Ruby bindings for the smbCloud transactional email API.
+test_files: []