purelymail 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5e4bdda524618b9f54fa2db24e50c78720d0e37ed092dd2a90943095a65ef1e1
+  data.tar.gz: e4167c8d6e8ff29be55e479bb45acdaf159e97edd30a8ce901a2f643b2902b48
+SHA512:
+  metadata.gz: f3ea3625f9066135040dfc9981b84a9f7f465ea75b4bd634a63be1c8b6da07eeaeae037c9477d80b2bb87cc582f39ad0e8c694d052031dac9fa9de051458b8d2
+  data.tar.gz: 56076ffc74848db74ac31a3c8f8b0c1c54f0960e6db801260ccf3c3747ad2026f7b3901e9ac8fd0cb189aae5144e85b61f1cb7dd0c7594f6dcc4a8b44ae19716

data/README.md

@@ -0,0 +1,134 @@
+# Purelymail
+
+A standalone Ruby client for the [Purelymail API](https://purelymail.com/).
+
+## Installation
+
+Add this to your `Gemfile`:
+
+```ruby
+gem "purelymail"
+```
+
+Then run `bundle install`.
+
+Or install it yourself:
+
+```bash
+gem install purelymail
+```
+
+## Usage
+
+### Per-Instance Configuration
+
+```ruby
+client = Purelymail::Client.new(api_token: "pm-live-xxxxxxxx")
+client.create_domain(name: "example.com")
+```
+
+### Global Configuration
+
+```ruby
+Purelymail.configure do |config|
+  config.api_token = "pm-live-xxxxxxxx"
+end
+
+client = Purelymail::Client.new
+client.create_user(name: "alice", domain: "example.com", password: "s3cret")
+```
+
+You can mix both: pass an `api_token` to `Client.new` to override the global config for that instance.
+
+### API Methods
+
+```ruby
+client = Purelymail::Client.new(api_token: "pm-live-xxxxxxxx")
+
+client.create_domain(name: "example.com")
+
+client.create_user(name: "alice", domain: "example.com", password: "s3cret")
+
+client.change_password(name: "alice", domain: "example.com", password: "newpass")
+
+client.create_routing_rule(
+  domain_name: "example.com",
+  match_user: "alice",
+  target_addresses: ["alice@destination.com"],
+  prefix: false,
+  catchall: false
+)
+
+client.configured?
+# => true
+```
+
+### Error Handling
+
+All API errors raise `Purelymail::ApiError`:
+
+```ruby
+begin
+  client.create_domain(name: "invalid@domain")
+rescue Purelymail::ApiError => e
+  puts e.message      # => "[Purelymail] addDomain failed: ..."
+  puts e.status       # => 400
+  puts e.response     # => {"type" => "error", "message" => "..."}
+end
+```
+
+## Rails Integration
+
+Add the gem to your `Gemfile`:
+
+```ruby
+gem "purelymail"
+```
+
+Configure via Rails credentials:
+
+```bash
+bin/rails credentials:edit
+```
+
+Add:
+
+```yaml
+purelymail:
+  api_token: pm-live-xxxxxxxx
+```
+
+The gem automatically picks up `Rails.application.credentials.dig(:purelymail, :api_token)` as a fallback, so you can use the client without any explicit configuration:
+
+```ruby
+# config/initializers/purelymail.rb
+Purelymail.configure do |config|
+  # config.api_token is optional here —
+  # it will fall back to Rails.application.credentials.purelymail.api_token
+end
+```
+
+Then anywhere in your app:
+
+```ruby
+Purelymail::Client.new.create_domain(name: "example.com")
+```
+
+If you need to override the token at the call site, pass it directly:
+
+```ruby
+Purelymail::Client.new(api_token: "pm-live-yyyyyyyy")
+```
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/purelymail/client.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+
+module Purelymail
+  class Client
+    BASE_URL = "https://purelymail.com/api/v0/"
+
+    def initialize(api_token: nil)
+      @api_token = api_token || Purelymail.configuration.api_token
+    end
+
+    def create_domain(name:)
+      post("addDomain", { domainName: name })
+    end
+
+    def create_user(name:, domain:, password:)
+      post("createUser", { userName: name, domainName: domain, password: password })
+    end
+
+    def change_password(name:, domain:, password:)
+      post("changePassword", { userName: name, domainName: domain, password: password })
+    end
+
+    def create_routing_rule(domain_name:, match_user:, target_addresses:, prefix: false, catchall: false)
+      post("createRoutingRule", {
+        domainName: domain_name,
+        matchUser: match_user,
+        targetAddresses: Array(target_addresses),
+        prefix: prefix,
+        catchall: catchall
+      })
+    end
+
+    def configured?
+      !api_token.nil? && api_token.to_s.strip != ""
+    end
+
+    private
+
+    attr_reader :api_token
+
+    def connection
+      @connection ||= Faraday.new(url: BASE_URL) do |f|
+        f.options.timeout = 5
+        f.options.open_timeout = 3
+        f.request :json
+        f.response :json
+        f.request :retry, max: 3, interval: 0.5, interval_randomness: 0.5,
+                          backoff_factor: 2,
+                          exceptions: [Faraday::ServerError, Faraday::TimeoutError, Faraday::ConnectionFailed]
+        f.adapter Faraday.default_adapter
+        f.headers["Purelymail-Api-Token"] = api_token
+      end
+    end
+
+    def post(endpoint, body)
+      response = connection.post(endpoint, body)
+      handle_response(response, endpoint)
+    end
+
+    def handle_response(response, endpoint)
+      body = response.body
+
+      if response.success? && body.is_a?(Hash) && body["type"] != "error"
+        body
+      else
+        error_msg = if body.is_a?(Hash)
+                      body["message"] || body["code"]
+                    else
+                      "HTTP Status #{response.status}"
+                    end
+
+        raise ApiError.new(
+          "[Purelymail] #{endpoint} failed: #{error_msg}",
+          status: response.status,
+          response: body
+        )
+      end
+    end
+  end
+end

data/lib/purelymail/configuration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Purelymail
+  class Configuration
+    attr_writer :api_token
+
+    def api_token
+      @api_token || rails_credentials_token
+    end
+
+    private
+
+    def rails_credentials_token
+      if defined?(Rails) && Rails.respond_to?(:application) && Rails.application.respond_to?(:credentials)
+        Rails.application.credentials.dig(:purelymail, :api_token)
+      end
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/purelymail/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Purelymail
+  class ApiError < StandardError
+    attr_reader :status, :response
+
+    def initialize(message = nil, status: nil, response: nil)
+      super(message)
+      @status = status
+      @response = response
+    end
+  end
+end

data/lib/purelymail/version.rb

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

data/lib/purelymail.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "purelymail/version"
+require "purelymail/error"
+require "purelymail/configuration"
+require "purelymail/client"
+
+module Purelymail
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: purelymail
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ben D'Angelo
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A standalone Ruby gem for interacting with the Purelymail API. Manage
+  domains, users, routing rules, and more.
+email:
+- ben@bendangelo.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/purelymail.rb
+- lib/purelymail/client.rb
+- lib/purelymail/configuration.rb
+- lib/purelymail/error.rb
+- lib/purelymail/version.rb
+homepage: https://github.com/bendangelo/purelymail-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/bendangelo/purelymail-rb
+  source_code_uri: https://github.com/bendangelo/purelymail-rb
+  changelog_uri: https://github.com/bendangelo/purelymail-rb/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Ruby client for the Purelymail API
+test_files: []