smbcloud-email 1.0.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fdfa94e477228e1a9a72921e3019626671bd8e444efbd03977158dbffdcb96e6
+  data.tar.gz: bac9c3b12c512b99d386bdf5c1dde38137feb5ced0a292bf90b0f576f6bce0ba
+SHA512:
+  metadata.gz: a29a51de615228acfaed0f405ac9f3d0d67726c8a988723c0dbf1023cd9fd0d2d99426465291aa21156c838006d2e89d72dd2570bba8a8cb579683a272e160c9
+  data.tar.gz: cf9230f941020c2ef39a01800e254a9deb8c53db698d820babb4ce3df1d4327a3fd8c418ecaa9ec074b5bb31831d4921dbb90d0097b843a7f4ab20e8a8be1d49

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.4.7] - 2026-06-30
+
+- Initial release. Ruby bindings for the smbCloud transactional email API:
+  `SmbCloud::Email::Client#send`, `#get_message`, and `#list_messages`,
+  powered by the shared Rust SDK (`smbcloud-email-sdk`) via a native Magnus
+  extension.

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/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,77 @@
+--- !ruby/object:Gem::Specification
+name: smbcloud-email
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: x86_64-linux
+authors:
+- Seto Elkahfi
+autorequire: 
+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'
+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: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- ext/.keep
+- lib/email.rb
+- lib/email/3.1/email.so
+- lib/email/3.2/email.so
+- lib/email/3.3/email.so
+- lib/email/3.4/email.so
+- lib/email/4.0/email.so
+- 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
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby bindings for the smbCloud transactional email API.
+test_files: []