wakio 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 38874499f377ba462c3e6b6309132fc3e755f83d53ba173c3f45c6f3c7a71b22
-  data.tar.gz: dd55b75c7b3d5ba2dd490c6d24c18bf284b4c389385e14627e840b5d73e56ea7
+  metadata.gz: 9795c3b6e4664844b3592b1e52fda609fb7ce969c6c330510e9c9f6f6b8a4c30
+  data.tar.gz: 95a22426d5dc1becadc7579b2785f27f75bc092dedce71735df1226952546a93
 SHA512:
-  metadata.gz: 96d287db49a082bdd79f41500482a7141e0aedae7ed1f7508ae070321a4ab10ac133496f6ba3214b328b780b13042a61e7d2f600e86a397337dfe0773047f6fe
-  data.tar.gz: 92402e1b1906380ede53db33c50f1ba806d746d8d63f9b3b8760105427e7a3349093dbfc46b1172ca1bdca07a73b4c671e6f7f48feea85930ea8f57053b97d5a
+  metadata.gz: 4958fb49ab19fbad6ba9e17a3fb763de4afe4fa0f01709077690b4e34ed400673c22218b14c6ebaab75d19a6067c17f5438a5c2452047b8a6d633c06c04a0bec
+  data.tar.gz: a927058f1018d75ec47ef541e29664c44879988b6802ec31deb7b3614f3bfa3d0917aa7a3e9591f7ae1b770e5effa90e875e12b35d6e3f1dac63c2113cb87dfc

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 WorkersLab LLC
+Copyright (c) 2026 ClayClock LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,5 +1,7 @@
 # wakio-rails
 
+The Ruby client for Wakio. It has two parts: an Action Mailer delivery method that sends your app's email through Wakio, and `Wakio::Contacts`, which keeps your Wakio contacts in step with your own user table.
+
 ```ruby
 # Gemfile
 gem "wakio"
@@ -20,7 +22,65 @@ config.action_mailer.wakio_settings = {
 
 Every existing mailer keeps working unchanged. Its rendered subject, its HTML and text parts, and its `from` go to Wakio as they are, with no server-side template involved. A text-only mailer sends a text-only email. Recipients keep their display names (`to`, `cc`, `bcc`); `reply_to` is sent as bare addresses.
 
-The `from` domain must be one of your account's sendable sending domains, matched exactly: `hello@acme.com` needs `acme.com` itself verified, and a verified `mail.acme.com` does not cover it. A mismatch is refused with `422 no_verified_sending_domain`. A mailer with no `from` goes out as `no-reply@` your first sendable domain. `GET /v1/sending-identities` reports which domains are currently sendable.
+The `from` domain must be one of your account's sendable sending domains, matched exactly: `hello@acme.com` needs `acme.com` itself verified, and a verified `mail.acme.com` does not cover it. A mismatch is refused with `422 no_verified_sending_domain`. A mailer with no `from` goes out as `no-reply@` your first sendable domain, as long as your account has one brand. Once it has more than one, every mailer needs a `from`, and one without it raises `Wakio::Misconfigured` with `422 from_required`. `GET /v1/sending-identities` reports which domains are currently sendable.
+
+## Syncing contacts
+
+Add a customer's users to Wakio from your own app. The key needs the `contacts` scope.
+
+```ruby
+contacts = Wakio::Contacts.new(Wakio::Client.new(api_key: Rails.application.credentials.wakio_api_key))
+
+contact = contacts.create(email: "anna@example.com", first_name: "Anna", external_id: "user-42")
+contacts.update(contact["id"], fields: { plan: "pro" })
+contacts.unsubscribe(contact["id"], lists: [ "lst_abc" ])
+contacts.resubscribe(contact["id"], list: "lst_abc", consent_ip: request.remote_ip)
+contacts.unsubscribe_all(contact["id"])
+contacts.erase(contact["id"])
+```
+
+For a person who agreed to marketing email, say so and add them to lists. Send `subscribed: true` only for people who actually agreed. Pass `enroll: false` when backfilling, so existing users do not start any welcome flow.
+
+```ruby
+contacts.create(email: "anna@example.com", subscribed: true, consented_at: Time.current.iso8601, lists: [ "lst_abc" ], enroll: false)
+```
+
+`create`, `get`, `update`, `unsubscribe`, `unsubscribe_all`, `resubscribe` and `erase` return the parsed JSON response, or `nil` for a `204`. `resubscribe` sends the person a confirmation email and changes nothing until they click it.
+
+`unsubscribe_all` stops all marketing email to the person and keeps the contact, its history and its consent record. It is not erasure: for a person who asks to be forgotten, call `erase`. When someone closes their account, unsubscribe them from everything if you keep their data, and erase them if you delete it: `unsubscribe_all` and `erase`.
+
+Pass `lists:` when backfilling. A `subscribed: true` add without it joins the brand's default list.
+
+### Errors and retries
+
+The client's `endpoint` defaults to `https://wakio.net` and must be `https`. Any non-2xx response raises a subclass of `Wakio::Error` carrying `status`, `code` (the response's `error`, such as `"contact_not_found"`) and the parsed `body`:
+
+- `Wakio::NotFound`: a `404`. For an unsubscribe, a delete or an erase it means the person is already gone, so treat it as done. To sync a user nightly, `update` by `external_id` and `create` when it raises `NotFound`.
+- `Wakio::Unavailable`: a `429`, a `5xx`, a timeout (`Net::OpenTimeout`, `Net::ReadTimeout`) or a connection failure. Retry it.
+- `Wakio::Error`: any other refusal, such as `409 email_taken` or `422 invalid_contact`. Retrying the same call cannot help.
+
+A call that raised `Wakio::Unavailable` may already have taken effect, so a retried POST can find its work done. That is safe for every contacts call: a repeated `resubscribe` answers `already_sent` and sends nothing.
+
+```ruby
+def with_retries(attempts: 5)
+  tries = 0
+  begin
+    yield
+  rescue Wakio::Unavailable
+    tries += 1
+    raise if tries >= attempts
+
+    sleep(2**tries)
+    retry
+  end
+end
+
+with_retries { contacts.update("user-42", first_name: "Anna") }
+```
+
+A `Wakio::Client` keeps one connection open and reuses it, so build one and share it instead of building one per call. Calls on a shared client run one at a time, so it is safe across threads but does not run them in parallel: give each worker thread its own client for that. `client.close` drops the connection, and the next call opens a new one.
+
+Build the client after the process forks, lazily in each process, never before a Puma or Sidekiq fork: a child forked with it would share the parent's open connection.
 
 ## Limitations worth knowing before you switch a mailer over
 
@@ -29,7 +89,7 @@ The `from` domain must be one of your account's sendable sending domains, matche
 **Refusals split by whether a retry can ever send the message.** A refusal from Wakio is a `Wakio::DeliveryError` carrying `status`, `code` (the response's `error`, such as `"invalid_request"`) and the parsed `body`. `code` is nil when the response is not JSON or names no `error`, so fall back to `status` when you log it.
 
 - `Wakio::Rejected`: retrying this message cannot help. `400`, `413`, `422 invalid_request` (usually a mailer bug; `detail` names the field) and `422 idempotency_key_reused` (an earlier request with that key already went out). Report it and drop it.
-- `Wakio::Misconfigured`: the account or its configuration is wrong, and the same message sends once that is fixed. `401 invalid_api_key`, `402 not_entitled`, `403 account_suspended`, `404`, `422 no_verified_sending_domain`, `422 unknown_template`, a redirect, an `http` host, and any 4xx this gem does not know. Retry it.
+- `Wakio::Misconfigured`: the account or its configuration is wrong, and the same message sends once that is fixed. `401 invalid_api_key`, `402 not_entitled`, `402 limit_reached`, `403 account_suspended`, `403 transactional_paused`, `404`, `422 no_verified_sending_domain`, `422 from_required`, `422 unknown_template`, a redirect, an `http` host, and any 4xx this gem does not know. Retry it once that is fixed. `402 limit_reached` means a Free plan has used up this month's emails, or the message has more recipients than are left. Retrying cannot send it until the monthly allowance resets or the account upgrades, and that can be longer than your job's retry window.
 - A plain `Wakio::DeliveryError`: `409 request_in_flight`, every 5xx, and a success response the gem cannot read. Retry it; after an unreadable success only a keyed send is safe to repeat.
 
 Action Mailer's delivery job retries nothing itself, and Solid Queue and GoodJob do not retry a failed job by default, so give it a policy:
@@ -68,10 +128,9 @@ ever approaches it. It reads "per request" and not "per message" for that reason
 the limit bounds what one `deliver!` call may name, not what any single message
 contains.
 
-**This gem does not send the mailer's `attachments`.** No files reach the recipient. Call the HTTP API directly for a send that needs them.
+**Attachments are sent; inline attachments are refused.** Every file in the mailer's `attachments` reaches each recipient. Wakio cannot reference a part by `cid:`, so a mailer using `attachments.inline` raises `Wakio::Rejected` before anything is sent, rather than delivering a broken image.
 
-**Ten megabytes of attachments per request** — a limit of the HTTP API you would call
-directly for the send above, since this gem posts no attachments of its own. Attachment
+**Ten megabytes of attachments per request**, checked by the API, which refuses a request over any limit below with `Wakio::Rejected`. Attachment
 content is read once from the request, not once per recipient — but Wakio still writes an
 independent copy of it to every recipient's own delivery record, so the same bytes are
 materialised once per recipient server-side. A second ceiling catches that: attachment

data/lib/wakio/client.rb

@@ -0,0 +1,84 @@
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require "wakio/http"
+
+module Wakio
+  class Client
+    DEFAULT_ENDPOINT = "https://wakio.net".freeze
+    CONNECTION_ERRORS = [ Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, EOFError, IOError, SocketError, SystemCallError, OpenSSL::SSL::SSLError ].freeze
+
+    def initialize(api_key:, endpoint: DEFAULT_ENDPOINT, open_timeout: 5, read_timeout: 10)
+      @api_key = api_key
+      @endpoint = endpoint
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @lock = Mutex.new
+      @connection = nil
+    end
+
+    def request(verb, path, payload = nil)
+      uri = URI.join(@endpoint, path)
+      Http.require_https!(uri, "endpoint", @endpoint)
+
+      parse(@lock.synchronize { transmit(uri, build(verb, uri, payload)) })
+    end
+
+    def close
+      @lock.synchronize { disconnect }
+    end
+
+    private
+
+    def transmit(uri, request)
+      connection(uri).request(request)
+    rescue *CONNECTION_ERRORS => error
+      disconnect
+      raise Unavailable, "Wakio could not be reached: #{error.class}: #{error.message}"
+    end
+
+    def connection(uri)
+      disconnect unless @connection && @connection.address == uri.hostname && @connection.port == uri.port
+      @connection ||= Net::HTTP.new(uri.hostname, uri.port).tap do |http|
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+      end
+      @connection.start unless @connection.started?
+      @connection
+    end
+
+    def disconnect
+      @connection&.finish if @connection&.started?
+    rescue IOError
+      nil
+    ensure
+      @connection = nil
+    end
+
+    def build(verb, uri, payload)
+      request = Net::HTTP.const_get(verb.to_s.capitalize).new(uri)
+      request["Authorization"] = "Bearer #{@api_key}"
+      request["Content-Type"] = "application/json"
+      request.body = payload.to_json unless payload.nil?
+      request
+    end
+
+    def parse(response)
+      status = response.code.to_i
+      raw = response.body.to_s
+      body = Http.parse_json(raw)
+      raise failure(status).new(Http.refusal_message(status, raw), status: status, body: body) unless status.between?(200, 299)
+
+      body
+    end
+
+    def failure(status)
+      if status == 404 then NotFound
+      elsif status == 429 || status >= 500 then Unavailable
+      else Error
+      end
+    end
+  end
+end

data/lib/wakio/contacts.rb

@@ -0,0 +1,44 @@
+require "erb"
+require "wakio/client"
+
+module Wakio
+  class Contacts
+    def initialize(client)
+      @client = client
+    end
+
+    def create(**attrs)
+      @client.request(:post, "/v1/contacts", attrs)
+    end
+
+    def get(id)
+      @client.request(:get, path(id))
+    end
+
+    def update(id, **attrs)
+      @client.request(:patch, path(id), attrs)
+    end
+
+    def unsubscribe_all(id)
+      @client.request(:delete, path(id))
+    end
+
+    def unsubscribe(id, lists: nil)
+      @client.request(:post, path(id, "unsubscribe"), { lists: lists }.compact)
+    end
+
+    def resubscribe(id, list: nil, consent_ip: nil)
+      @client.request(:post, path(id, "resubscribe"), { list: list, consent_ip: consent_ip }.compact)
+    end
+
+    def erase(id)
+      @client.request(:post, path(id, "erase"))
+    end
+
+    private
+
+    def path(id, action = nil)
+      [ "/v1/contacts/#{ERB::Util.url_encode(id.to_s)}", action ].compact.join("/")
+    end
+  end
+end

data/lib/wakio/delivery_method.rb

@@ -1,23 +1,10 @@
 require "json"
 require "net/http"
 require "uri"
+require "wakio/error"
+require "wakio/http"
 
 module Wakio
-  class DeliveryError < StandardError
-    attr_reader :status, :code, :body
-
-    def initialize(message = nil, status: nil, body: nil)
-      super(message)
-      @status = status
-      @body = body
-      @code = body["error"] if body.is_a?(Hash)
-    end
-  end
-
-  Suppressed = Class.new(DeliveryError)
-  Rejected = Class.new(DeliveryError)
-  Misconfigured = Class.new(DeliveryError)
-
   # An ActionMailer delivery method, so a host app keeps every existing mailer
   # untouched and changes only configuration.
   class DeliveryMethod
@@ -37,8 +24,6 @@ module Wakio
     # towards retrying rather than towards dropping mail.
     REJECTED_STATUSES = [ 400, 413 ].freeze
     REJECTED_CODES = %w[invalid_request idempotency_key_reused].freeze
-    LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
-    MESSAGE_BODY_LIMIT = 300
 
     def deliver!(mail)
       # Caller-supplied, never derived — and no key at all when the caller gives none.
@@ -80,10 +65,24 @@ module Wakio
         from: mail[:from]&.value,
         subject: mail.subject.to_s.gsub(/[[:space:]]+/, " ").strip,
         html: html,
-        text: text
+        text: text,
+        attachments: attachments_for(mail)
       }.compact
     end
 
+    # Wakio has no content_id, so an inline part would arrive as a separate file and its cid: image
+    # would break. Refused here, before the request, rather than delivered broken.
+    def attachments_for(mail)
+      return if mail.attachments.empty?
+
+      inline = mail.attachments.select(&:inline?)
+      raise Rejected, "Wakio does not send inline attachments: #{inline.map(&:filename).join(', ')}" if inline.any?
+
+      mail.attachments.map do |file|
+        { filename: file.filename, content_type: file.mime_type, content: [ file.decoded ].pack("m0") }
+      end
+    end
+
     # `formatted` keeps each recipient's display name, which Wakio shows in the To line and ignores
     # for matching. reply_to stays bare above: Wakio takes no name there.
     # A header Mail cannot parse is an UnstructuredField with no #formatted; sent as written, Wakio
@@ -145,7 +144,7 @@ module Wakio
     end
 
     def refusal(status, raw)
-      body = parsed(raw)
+      body = Http.parse_json(raw)
       code = body["error"] if body.is_a?(Hash)
       kind =
         if status.between?(300, 399) then Misconfigured
@@ -153,13 +152,7 @@ module Wakio
         elsif REJECTED_STATUSES.include?(status) || REJECTED_CODES.include?(code) then Rejected
         else Misconfigured
         end
-      kind.new("Wakio returned #{status}: #{raw.to_s[0, MESSAGE_BODY_LIMIT]}", status: status, body: body)
-    end
-
-    def parsed(body)
-      JSON.parse(body.to_s)
-    rescue JSON::ParserError
-      nil
+      kind.new(Http.refusal_message(status, raw), status: status, body: body)
     end
 
     def unreadable!(response)
@@ -168,9 +161,7 @@ module Wakio
 
     def post(payload, idempotency_key:)
       uri = URI.join(settings.fetch(:host), "/v1/emails")
-      unless uri.scheme == "https" || LOCAL_HOSTS.include?(uri.hostname)
-        raise Misconfigured, "Wakio host must be https, or the API key travels in cleartext: #{settings.fetch(:host)}"
-      end
+      Http.require_https!(uri, "host", settings.fetch(:host))
       request = Net::HTTP::Post.new(uri)
       request["Authorization"] = "Bearer #{settings.fetch(:api_key)}"
       request["Content-Type"] = "application/json"

data/lib/wakio/error.rb

@@ -0,0 +1,19 @@
+module Wakio
+  class Error < StandardError
+    attr_reader :status, :code, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      super(message)
+      @status = status
+      @body = body
+      @code = body["error"] if body.is_a?(Hash)
+    end
+  end
+
+  NotFound = Class.new(Error)
+  Unavailable = Class.new(Error)
+  DeliveryError = Class.new(Error)
+  Suppressed = Class.new(DeliveryError)
+  Rejected = Class.new(DeliveryError)
+  Misconfigured = Class.new(DeliveryError)
+end

data/lib/wakio/http.rb

@@ -0,0 +1,28 @@
+require "json"
+require "uri"
+require "wakio/error"
+
+module Wakio
+  module Http
+    LOCAL_HOSTS = %w[localhost 127.0.0.1 ::1].freeze
+    MESSAGE_BODY_LIMIT = 300
+
+    module_function
+
+    def require_https!(uri, setting, configured)
+      return if uri.scheme == "https" || LOCAL_HOSTS.include?(uri.hostname)
+
+      raise Misconfigured, "Wakio #{setting} must be https, or the API key travels in cleartext: #{configured}"
+    end
+
+    def refusal_message(status, raw)
+      "Wakio returned #{status}: #{raw.to_s[0, MESSAGE_BODY_LIMIT]}"
+    end
+
+    def parse_json(raw)
+      JSON.parse(raw.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/wakio.rb

@@ -1 +1,3 @@
 require "wakio/rails"
+require "wakio/client"
+require "wakio/contacts"

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: wakio
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: ruby
 authors:
-- WorkersLab LLC
+- ClayClock LLC
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -23,6 +23,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.0'
+description: 'Sends Action Mailer email through Wakio, and syncs your own users to
+  Wakio as contacts: add, update, unsubscribe, resubscribe and erase.'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -30,7 +32,11 @@ files:
 - LICENSE
 - README.md
 - lib/wakio.rb
+- lib/wakio/client.rb
+- lib/wakio/contacts.rb
 - lib/wakio/delivery_method.rb
+- lib/wakio/error.rb
+- lib/wakio/http.rb
 - lib/wakio/rails.rb
 homepage: https://wakio.net/docs
 licenses:
@@ -53,5 +59,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: ActionMailer delivery method for Wakio
+summary: ActionMailer delivery method and contacts client for Wakio
 test_files: []