postscale 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eb9a38ed2e7fa18e4a523855431fe47856c78d5bd7ea264be016e0cfd6909673
+  data.tar.gz: e62f7e0c2373bcf34ab465019abe871635e1d3274d4d57a8f89b4985c362220c
+SHA512:
+  metadata.gz: a3bf1e293bda9a1bf5dfa5ad1d9b60a5b119c9bbfaac94b14d292a88cafc6100964c228d232b31f4cd559b8f5361fc0ae6f2e87fc595ca09e99e3bed3a6195c3
+  data.tar.gz: f0226c8b2dbfe5c230aee5e178c754b7f5513e47df8c8f7a8a8cb71f6390136c82f0f42637c2c5c606f36df8ede84aacbe8da9dce7f7797df0fd80c2eafdb3db

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Postscale
+
+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,224 @@
+# Postscale Ruby SDK
+
+Official Ruby SDK for the [Postscale](https://postscale.io) email API.
+
+## Install
+
+```bash
+gem install postscale
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'postscale'
+```
+
+Requires Ruby 3.0 or newer.
+
+## Send Email
+
+```ruby
+require 'postscale'
+
+postscale = Postscale::Client.new(api_key: ENV.fetch('POSTSCALE_API_KEY'))
+
+result = postscale.emails.send(
+  from: 'hello@example.com',
+  to: ['user@example.com'],
+  subject: 'Welcome!',
+  html_body: '<strong>It works.</strong>'
+)
+
+if result.error
+  raise "#{result.error.code}: #{result.error.message}"
+end
+
+puts result.data['message_id']
+```
+
+The SDK keeps Postscale API-native field names. Use `html_body`,
+`text_body`, `template_id`, and `unsubscribe_scope`; the MVP SDK does not add
+`html` or `text` aliases.
+
+## Configuration
+
+```ruby
+postscale = Postscale::Client.new(
+  api_key: ENV['POSTSCALE_API_KEY'],
+  base_url: 'https://api.postscale.io',
+  timeout: 30,
+  max_retries: 3,
+  headers: {}
+)
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `api_key` | Your Postscale API key. Falls back to `POSTSCALE_API_KEY`. | Required |
+| `base_url` | API base URL | `https://api.postscale.io` |
+| `timeout` | Request timeout in seconds | `30` |
+| `max_retries` | Retries for idempotent `GET`, `HEAD`, and `OPTIONS` requests | `3` |
+| `headers` | Additional default request headers | `{}` |
+
+If no base URL is passed, the SDK reads `POSTSCALE_BASE_URL` and then falls
+back to `https://api.postscale.io`.
+
+## Results and Errors
+
+Every API method returns a result object:
+
+```ruby
+result = postscale.domains.list(limit: 10)
+
+if result.error
+  warn "#{result.error.code}: #{result.error.message}"
+  warn result.error.request_id
+else
+  puts result.data
+end
+```
+
+API errors are returned as `Postscale::APIError` objects inside
+`result.error`. Configuration and local validation errors are raised before a
+request is sent.
+
+## Attachments
+
+```ruby
+attachment = Postscale.attachment_from_file('invoice.pdf', 'application/pdf')
+
+result = postscale.emails.send(
+  from: 'billing@example.com',
+  to: ['customer@example.com'],
+  subject: 'Invoice',
+  text_body: 'Attached.',
+  attachments: [attachment]
+)
+```
+
+Attachment helpers return API-native hashes with `filename`, `content`, and
+`content_type`. Client-side checks enforce the documented limits: 10
+attachments, 25 MB per attachment, and 50 MB total decoded attachment payload.
+
+## Webhook Verification
+
+```ruby
+result = Postscale.verify_webhook_signature(
+  raw_body,
+  request.get_header('HTTP_X_POSTSCALE_SIGNATURE'),
+  [current_secret, previous_secret]
+)
+
+halt 401 unless result.valid?
+```
+
+The verifier requires the Postscale signature format:
+`t=<unix_seconds>,v1=<hex_hmac_sha256>`, signed over `<t>.<raw_body>`. It
+supports multiple `v1=` signatures and multiple candidate secrets for rotation
+windows.
+
+## API Reference
+
+### Emails
+
+```ruby
+postscale.emails.send(...)
+postscale.emails.send_batch(emails: [...])
+postscale.emails.list(...)
+postscale.emails.get(email_id)
+postscale.emails.list_events(email_id)
+```
+
+### Domains
+
+```ruby
+postscale.domains.create(domain: 'example.com')
+postscale.domains.list
+postscale.domains.get(domain_id)
+postscale.domains.update(domain_id, active: true)
+postscale.domains.verify(domain_id)
+postscale.domains.dns(domain_id)
+postscale.domains.delete(domain_id)
+```
+
+### DKIM
+
+```ruby
+postscale.dkim.generate(domain_id, selector: 's1')
+postscale.dkim.list(domain_id)
+postscale.dkim.rotate(domain_id, old_selector: 's1', new_selector: 's2')
+postscale.dkim.deactivate(domain_id, 's1')
+```
+
+### Inbound
+
+```ruby
+postscale.inbound.list(...)
+postscale.inbound.get(email_id)
+postscale.inbound.download_attachment(email_id, attachment_id)
+```
+
+### Suppressions
+
+```ruby
+postscale.suppressions.list
+postscale.suppressions.add(email: 'user@example.com', reason: 'hard_bounce')
+postscale.suppressions.check('user@example.com')
+postscale.suppressions.remove('user@example.com')
+postscale.suppressions.import_preview(...)
+postscale.suppressions.import_job(job_id)
+postscale.suppressions.commit_import(job_id)
+```
+
+### Templates
+
+```ruby
+postscale.templates.create(...)
+postscale.templates.list
+postscale.templates.get(template_id)
+postscale.templates.update(template_id, ...)
+postscale.templates.preview(template_id, ...)
+postscale.templates.delete(template_id)
+```
+
+### Webhooks
+
+```ruby
+postscale.webhooks.create(url: 'https://example.com/webhooks', events: ['email.delivered'])
+postscale.webhooks.list
+postscale.webhooks.deliveries
+postscale.webhooks.endpoint_deliveries(webhook_id)
+postscale.webhooks.rotate_secret(webhook_id)
+postscale.webhooks.delete(webhook_id)
+postscale.webhooks.verify_signature(raw_body, signature_header, secrets)
+```
+
+### Warming, Stats, Usage, and Trust
+
+```ruby
+postscale.warming.get_status(domain_id)
+postscale.warming.history(domain_id)
+postscale.warming.start(domain_id)
+postscale.warming.pause(domain_id)
+postscale.warming.resume(domain_id)
+
+postscale.stats.aggregate(domain_id)
+postscale.stats.daily(domain_id)
+postscale.stats.hourly(domain_id)
+postscale.stats.isp(domain_id)
+
+postscale.usage.summary
+postscale.trust.get_review_request
+postscale.trust.create_review_request(...)
+```
+
+## Testing
+
+```bash
+rake test
+```
+
+## License
+
+MIT

data/lib/postscale/attachments.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Attachments
+    MAX_ATTACHMENTS_PER_EMAIL = 10
+    MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024
+    MAX_TOTAL_ATTACHMENT_BYTES = 50 * 1024 * 1024
+
+    module_function
+
+    def from_file(path, content_type = "application/octet-stream")
+      from_bytes(File.basename(path), File.binread(path), content_type)
+    end
+
+    def from_bytes(filename, data, content_type = "application/octet-stream")
+      {
+        "filename" => filename,
+        "content" => Base64.strict_encode64(data.to_s),
+        "content_type" => content_type
+      }
+    end
+
+    def validate(attachments)
+      return if attachments.nil? || attachments.empty?
+
+      unless attachments.is_a?(Array)
+        raise ValidationError, "attachments must be an array."
+      end
+
+      if attachments.length > MAX_ATTACHMENTS_PER_EMAIL
+        raise ValidationError, "Postscale supports at most #{MAX_ATTACHMENTS_PER_EMAIL} attachments per email."
+      end
+
+      total = 0
+      attachments.each_with_index do |attachment, index|
+        filename = value_for(attachment, "filename")
+        content = value_for(attachment, "content")
+
+        raise ValidationError, "attachments[#{index}].filename is required." if blank?(filename)
+        raise ValidationError, "attachments[#{index}].content is required." if blank?(content)
+
+        bytes = decoded_bytes(content, index)
+        if bytes > MAX_ATTACHMENT_BYTES
+          raise ValidationError, "attachments[#{index}] exceeds the 25 MB per-attachment limit."
+        end
+        total += bytes
+      end
+
+      raise ValidationError, "Attachments exceed the 50 MB total message limit." if total > MAX_TOTAL_ATTACHMENT_BYTES
+    end
+
+    def value_for(hash, key)
+      return nil unless hash.respond_to?(:[])
+
+      hash[key] || hash[key.to_sym]
+    end
+    private_class_method :value_for
+
+    def blank?(value)
+      value.nil? || value.to_s.empty?
+    end
+    private_class_method :blank?
+
+    def decoded_bytes(content, index)
+      Base64.strict_decode64(strip_data_url(content.to_s)).bytesize
+    rescue ArgumentError
+      raise ValidationError, "attachments[#{index}].content must be valid base64."
+    end
+    private_class_method :decoded_bytes
+
+    def strip_data_url(value)
+      value.include?(",") ? value.split(",", 2).last : value
+    end
+    private_class_method :strip_data_url
+  end
+end

data/lib/postscale/client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Postscale
+  class Client
+    attr_reader :config, :http
+
+    # Initialize a new Postscale API client.
+    #
+    #   client = Postscale::Client.new(api_key: "ps_live_...")
+    #   client = Postscale::Client.new(
+    #     api_key:  "ps_test_...",
+    #     base_url: "https://api.postscale.io",
+    #     timeout:  30,
+    #     retries:  3,
+    #     debug:    false
+    #   )
+    #
+    def initialize(api_key: nil, base_url: nil, timeout: Configuration::DEFAULT_TIMEOUT, max_retries: Configuration::DEFAULT_MAX_RETRIES, headers: nil, transport: nil, sleeper: nil)
+      resolved_api_key = api_key || ENV["POSTSCALE_API_KEY"]
+      resolved_base_url = base_url || ENV["POSTSCALE_BASE_URL"] || Configuration::DEFAULT_BASE_URL
+
+      @config = Configuration.new(
+        api_key: resolved_api_key,
+        base_url: resolved_base_url,
+        timeout: timeout,
+        max_retries: max_retries,
+        headers: headers,
+        transport: transport,
+        sleeper: sleeper
+      )
+      @http = HttpClient.new(@config)
+    end
+
+    # ----- Resource accessors -----
+
+    def emails
+      @emails ||= Resources::Emails.new(@http)
+    end
+
+    def domains
+      @domains ||= Resources::Domains.new(@http)
+    end
+
+    def dkim
+      @dkim ||= Resources::DKIM.new(@http)
+    end
+
+    def aliases
+      @aliases ||= Resources::Aliases.new(@http)
+    end
+
+    def inbound
+      @inbound ||= Resources::Inbound.new(@http)
+    end
+
+    def stats
+      @stats ||= Resources::Stats.new(@http)
+    end
+
+    def warming
+      @warming ||= Resources::Warming.new(@http)
+    end
+
+    def suppressions
+      @suppressions ||= Resources::Suppressions.new(@http)
+    end
+
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(@http)
+    end
+
+    def templates
+      @templates ||= Resources::Templates.new(@http)
+    end
+
+    def usage
+      @usage ||= Resources::Usage.new(@http)
+    end
+
+    def trust
+      @trust ||= Resources::Trust.new(@http)
+    end
+  end
+end

data/lib/postscale/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Postscale
+  class Configuration
+    DEFAULT_BASE_URL   = "https://api.postscale.io"
+    DEFAULT_TIMEOUT    = 30
+    DEFAULT_MAX_RETRIES = 3
+
+    attr_reader :api_key, :base_url, :timeout, :max_retries, :headers, :transport, :sleeper
+
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES, headers: nil, transport: nil, sleeper: nil)
+      @api_key  = api_key
+      @base_url = base_url.chomp("/")
+      @timeout  = timeout
+      @max_retries = max_retries
+      @headers = headers || {}
+      @transport = transport
+      @sleeper = sleeper || Kernel.method(:sleep)
+
+      validate!
+    end
+
+    def validate!
+      raise ConfigurationError, "API key is required" if @api_key.nil? || @api_key.strip.empty?
+
+      raise ConfigurationError, "Timeout must be a positive number" unless @timeout.is_a?(Numeric) && @timeout.positive?
+      unless @max_retries.is_a?(Integer) && @max_retries >= 0
+        raise ConfigurationError, "max_retries must be a non-negative integer"
+      end
+    end
+
+    def live?
+      @api_key.start_with?("ps_live_")
+    end
+
+    def test?
+      @api_key.start_with?("ps_test_")
+    end
+  end
+end

data/lib/postscale/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Postscale
+  # Base error class for all Postscale SDK errors.
+  class Error < StandardError; end
+
+  # Raised when the client configuration is invalid (e.g. missing API key).
+  class ConfigurationError < Error; end
+
+  # Raised when local SDK input validation fails before a request is sent.
+  class ValidationError < Error; end
+
+  # Structured error object returned inside Postscale::Result for API and
+  # transport failures. API responses are not raised by public SDK methods.
+  class APIError < Error
+    attr_reader :code, :status_code, :request_id, :body
+
+    def initialize(message:, code: "api_error", status_code: nil, request_id: nil, body: nil)
+      @code = code
+      @status_code = status_code
+      @request_id = request_id
+      @body = body
+      super(message)
+    end
+  end
+end