vatio-sdk 0.6.0

data/lib/vatio/server/template.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Vatio
+  module Server
+    # A WhatsApp template the key's number can send, from Vatio's mirror of
+    # Meta's: its body, how many `{{n}}` parameters that body takes, and the
+    # object `send_message` expects as `template:`.
+    #
+    #   shipped = Vatio::Server.templates.find { |t| t.name == "order_shipped" }
+    #   Vatio::Server.send_message(to: phone, brief: brief, template: shipped.with_params("Ana", "#1042"))
+    #
+    # Empty on a preview key: the preview number's templates are Vatio's.
+    Template = Struct.new(
+      :name, :language, :category, :status, :rejected_reason, :body, :parameter_count, :example,
+      keyword_init: true
+    ) do
+      def self.from(hash) = Value.build(self, hash)
+
+      def approved? = status == "APPROVED"
+
+      # Strings, in body order. The count is checked here when it is known,
+      # because Meta only reports a wrong one by refusing the send.
+      def with_params(*params)
+        params = params.flatten.map(&:to_s)
+        if parameter_count && params.size != parameter_count
+          raise ArgumentError, "vatio server: template #{name} (#{language}) takes #{parameter_count} " \
+            "param#{"s" unless parameter_count == 1}, got #{params.size}"
+        end
+
+        { name: name, language: language, params: params }
+      end
+    end
+  end
+end

data/lib/vatio/server/testing.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require "jwt"
+require "uri"
+
+require_relative "../server"
+
+module Vatio
+  module Server
+    # For your own test suite: no network, no key, and a record of what your
+    # code asked Vatio to send.
+    #
+    #   require "vatio/server/testing"
+    #
+    #   setup { Vatio::Server::Testing.fake! }
+    #   teardown { Vatio::Server::Testing.real! }
+    #
+    #   Order.ship!(order)
+    #   sent = Vatio::Server::Testing.messages.last
+    #   assert_equal "+56912345678", sent.to
+    #   assert_equal "order-1042-shipped", sent.external_ref
+    #
+    #   Vatio::Server::Testing.fail_next!(:outside_window)
+    #   assert_raises(Vatio::Server::OutsideWindow) { Order.remind!(order) }
+    #
+    # The fake answers as the API does -- 202 and a queued message, 200 and
+    # the same message for an idempotency key it has seen, Conflict for one
+    # reused with a different request -- through the same parsing and error
+    # mapping as a real response, so what your code rescues is what it will
+    # rescue in production. It assumes the 24-hour window is open; set
+    # `window_open = false` and a message without a template raises
+    # OutsideWindow, as it would.
+    module Testing
+      # A request to send, as the fake received it. `subject` and `claims`
+      # are read back out of the identity token, unverified.
+      Recorded = Struct.new(
+        :id, :to, :brief, :text, :template, :external_ref, :idempotency_key, :identity, :subject, :claims, :mode,
+        keyword_init: true
+      )
+
+      # Status and code for the refusals `fail_next!` knows by name. Any
+      # other code is a 422, unless you pass `status:`.
+      FAILURES = {
+        "outside_window" => 422, "opted_out" => 409, "human_takeover" => 409, "handoff_pending" => 409,
+        "template_required" => 422, "template_not_found" => 422, "template_not_approved" => 422,
+        "template_params" => 422, "content_required" => 422, "brief_too_long" => 422, "text_too_long" => 422,
+        "invalid_recipient" => 422, "not_a_test_phone" => 422, "identity_not_configured" => 422,
+        "invalid_identity" => 422, "whatsapp_not_connected" => 409, "whatsapp_paused" => 409,
+        "idempotency_conflict" => 409, "identity_conflict" => 409, "invalid_key" => 401,
+        "workspace_forbidden" => 403, "not_found" => 404, "rate_limited" => 429, "unavailable" => 503
+      }.freeze
+
+      # `fail_next!(:timeout)` and `fail_next!(:network_error)` raise in the
+      # transport, as a socket would, rather than answering at all.
+      NETWORK_FAILURES = %w[timeout network_error].freeze
+
+      class << self
+        attr_writer :templates, :window_open
+
+        # Swaps the transport for the in-memory one, and fills a key and a
+        # workspace if the suite has none, so no test needs a real `vsk_`.
+        # With a block, puts everything back afterwards.
+        def fake!
+          unless faking?
+            @previous = { transport: Server.instance_variable_get(:@transport),
+                          server_key: Server.config.server_key,
+                          workspace: Server.config.instance_variable_get(:@workspace) }
+            Server.config.server_key = "vsk_test_fake" if Server.config.server_key.to_s.strip.empty?
+            Server.config.workspace = "test" if Server.config.workspace.nil?
+            Server.transport = FakeTransport.new
+          end
+          reset!
+          return self unless block_given?
+
+          begin
+            yield
+          ensure
+            real!
+          end
+        end
+
+        def real!
+          return unless faking?
+
+          Server.transport = @previous[:transport]
+          Server.config.server_key = @previous[:server_key]
+          Server.config.workspace = @previous[:workspace]
+          @previous = nil
+        end
+
+        def faking? = Server.instance_variable_get(:@transport).is_a?(FakeTransport)
+
+        # Forgets what was sent and any pending failure; templates and the
+        # window go back to their defaults.
+        def reset!
+          @templates = []
+          @window_open = true
+          fake.reset! if faking?
+        end
+
+        # Each message the fake created, oldest first. A replay of an
+        # idempotency key creates none, as it would not on Vatio.
+        def messages = faking? ? fake.messages : []
+
+        # Every request, reads included: [method, path, body].
+        def requests = faking? ? fake.requests : []
+
+        # The next call answers with this refusal instead -- any call, so
+        # `fail_next!(:not_found)` before `message_status` works too.
+        def fail_next!(code, status: nil, message: nil, **details)
+          code = code.to_s
+          fake.fail_next = { code: code, status: status || FAILURES.fetch(code, 422),
+                             message: message || "#{code} (Vatio::Server::Testing)", details: details }
+        end
+
+        # What `Vatio::Server.templates` answers: Hashes as the API sends
+        # them, or Templates.
+        def templates = @templates || []
+
+        def window_open? = @window_open != false
+
+        # A webhook request as Vatio would deliver it, for testing your
+        # receiver: post `body` with `headers` to its route.
+        #
+        #   hook = Vatio::Server::Testing.webhook("message.replied", message: { id: 1, external_ref: "x" })
+        #   post "/webhooks/vatio", params: hook.body, headers: hook.headers
+        #
+        # `data` as a Hash, or its keys as keywords, as above.
+        def webhook(type, data = {}, secret: Server.config.webhook_secret, id: "evt_#{rand(1_000_000)}", at: Time.now,
+                    **fields)
+          event = { id: id, type: type, created_at: at.utc.iso8601, workspace: Server.config.workspace,
+                    environment: "live", data: data.to_h.merge(fields) }
+          body = JSON.generate(event)
+          WebhookRequest.new(
+            body: body,
+            headers: { Webhook::HEADER => Webhook.sign(payload: body, secret: secret, at: at), "Content-Type" => "application/json" },
+            event: JSON.parse(body)
+          )
+        end
+
+        private
+
+        def fake
+          Server.instance_variable_get(:@transport)
+        end
+      end
+
+      # What `webhook` builds: the body to post, its headers, and the event
+      # your handler should receive.
+      WebhookRequest = Struct.new(:body, :headers, :event, keyword_init: true)
+
+      # The transport the fake installs: the same `call` as the real one,
+      # answered from memory.
+      class FakeTransport
+        attr_accessor :fail_next
+        attr_reader :messages, :requests
+
+        def initialize
+          @lock = Mutex.new
+          reset!
+        end
+
+        def reset!
+          @lock.synchronize do
+            @messages = []
+            @payloads = {}
+            @by_key = {}
+            @requests = []
+            @fail_next = nil
+            @next_id = 0
+          end
+        end
+
+        def call(method:, url:, headers: {}, body: nil, **)
+          uri = URI.parse(url)
+          path = uri.path.sub(%r{\A#{Client::API_PATH}/[^/]+/}o, "")
+          query = URI.decode_www_form(uri.query.to_s).to_h
+          params = body ? JSON.parse(body) : {}
+
+          @lock.synchronize do
+            @requests << [ method.to_s.upcase, path, params ]
+            failure = @fail_next
+            @fail_next = nil
+            return answer_failure(failure) if failure
+
+            route(method.to_s.downcase, path, query, params, headers)
+          end
+        end
+
+        private
+
+        def route(method, path, query, params, headers)
+          shown = method == "get" && path[%r{\Amessages/(\d+)\z}, 1]
+          if method == "post" && path == "messages" then create(params, headers["Idempotency-Key"])
+          elsif method == "get" && path == "messages" then list(query)
+          elsif method == "get" && path == "templates" then json(200, { templates: Testing.templates.map(&:to_h) })
+          elsif shown && @payloads[shown.to_i] then json(200, @payloads[shown.to_i])
+          elsif shown then refusal(404, "not_found", "Resource not found")
+          else refusal(404, "not_found", "No such endpoint in Vatio::Server::Testing: #{method.upcase} #{path}")
+          end
+        end
+
+        def create(params, key)
+          if key && (previous = @by_key[key])
+            return json(200, @payloads[previous[:id]], "idempotent-replayed" => "true") if previous[:params] == params
+
+            return refusal(409, "idempotency_conflict",
+              "Idempotency-Key #{key.inspect} was already used for a different message (#{previous[:id]}).",
+              message_id: previous[:id])
+          end
+
+          to = params["to"].to_s
+          return refusal(422, "invalid_recipient", "to must be a phone number in international format.") if to.gsub(/\D/, "").length < 8
+          if params["brief"].to_s.strip.empty? && params["text"].to_s.strip.empty?
+            return refusal(422, "content_required", "Send `text` or `brief`.")
+          end
+
+          mode = if Testing.window_open? then params["text"] ? "text" : "agent"
+          elsif params["template"] then "template"
+          end
+          unless mode
+            return refusal(422, "outside_window", "The contact has not written in the last 24 hours.",
+              last_inbound_at: nil)
+          end
+
+          claims = claims_of(params["identity"])
+          template = params["template"]&.slice("name", "language", "params")
+          text = (params["text"] if mode == "text")
+          template = (template if mode == "template")
+
+          id = (@next_id += 1)
+          payload = {
+            id: id, status: "queued", mode: mode, channel: "whatsapp", environment: "live",
+            to: "+#{to.gsub(/\D/, "")}", chat_id: id, external_ref: params["external_ref"], idempotency_key: key,
+            brief: params["brief"], text: text, template: template, content: nil, chat_message_id: nil,
+            delivery: nil, error: nil, sent_at: nil, replied_at: nil, created_at: Time.now.utc.iso8601
+          }
+          @payloads[id] = JSON.parse(JSON.generate(payload))
+          @by_key[key] = { id: id, params: params } if key
+          @messages << Recorded.new(
+            id: id, to: params["to"], brief: params["brief"], text: params["text"], template: params["template"],
+            external_ref: params["external_ref"], idempotency_key: key, identity: params["identity"],
+            subject: claims["sub"], claims: claims.reject { |name, _| Identity::REGISTERED_CLAIMS.include?(name) },
+            mode: mode
+          ).freeze
+          json(202, payload)
+        end
+
+        def list(query)
+          items = @payloads.values.reverse
+          items = items.select { |item| item["external_ref"] == query["external_ref"] } if query["external_ref"]
+          items = items.select { |item| item["status"] == query["status"] } if query["status"]
+          items = items.select { |item| item["id"] < query["before"].to_i } if query["before"]
+          limit = (query["limit"] || 50).to_i.clamp(1, 50)
+          page = items.first(limit)
+          json(200, { messages: page, next_before: (page.last["id"] if page.size == limit && !page.empty?) })
+        end
+
+        def answer_failure(failure)
+          if NETWORK_FAILURES.include?(failure[:code])
+            raise Unavailable.new("vatio server: #{failure[:message]}", code: failure[:code])
+          end
+
+          refusal(failure[:status], failure[:code], failure[:message], **failure[:details])
+        end
+
+        def claims_of(token)
+          return {} if token.to_s.empty?
+
+          JWT.decode(token, nil, false).first
+        rescue JWT::DecodeError
+          {}
+        end
+
+        def refusal(status, code, message, **details)
+          json(status, { error: { code: code, message: message, **details }, request_id: "req_test" },
+            "x-request-id" => "req_test")
+        end
+
+        def json(status, body, headers = {})
+          Response.new(status: status, headers: { "content-type" => "application/json" }.merge(headers),
+            body: JSON.generate(body))
+        end
+      end
+    end
+  end
+end
+
+if defined?(RSpec::Matchers)
+  # expect { Order.ship!(order) }.to have_sent_message(to: "+56912345678", external_ref: "order-1042-shipped")
+  # expect(Vatio::Server::Testing).to have_sent_message(to: "+56912345678")
+  #
+  # Every attribute but `to` is compared as given, RSpec matchers included
+  # (`brief: a_string_including("1042")`); `to` is compared by its digits,
+  # so "+56 9 1234 5678" matches "+56912345678".
+  RSpec::Matchers.define :have_sent_message do |to: nil, **expected|
+    supports_block_expectations
+
+    match do |actual|
+      before = Vatio::Server::Testing.messages.size
+      actual.call if actual.is_a?(Proc)
+      candidates = actual.is_a?(Proc) ? Vatio::Server::Testing.messages.drop(before) : Vatio::Server::Testing.messages
+
+      @found = candidates.select do |message|
+        (to.nil? || message.to.to_s.gsub(/\D/, "") == to.to_s.gsub(/\D/, "")) &&
+          expected.all? { |name, value| values_match?(value, message.public_send(name)) }
+      end
+      @candidates = candidates
+      !@found.empty?
+    end
+
+    failure_message do
+      wanted = { to: to, **expected }.compact
+      sent = @candidates.map { |message| message.to_h.slice(:to, *expected.keys) }
+      "expected a message matching #{wanted.inspect}, but #{sent.empty? ? "none was sent" : "sent: #{sent.inspect}"}"
+    end
+
+    failure_message_when_negated do
+      "expected no message matching #{{ to: to, **expected }.compact.inspect}, but #{@found.size} were sent"
+    end
+  end
+end

data/lib/vatio/server/transport.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module Vatio
+  module Server
+    # What a transport answers: the status, the headers with downcased names,
+    # and the body as it came.
+    Response = Struct.new(:status, :headers, :body, keyword_init: true)
+
+    # The one place the gem opens a socket, kept to an interface small enough
+    # that Vatio::Server::Testing swaps it for an in-memory one:
+    #
+    #   call(method:, url:, headers:, body:) -> Response
+    #
+    # A connection per request. Messages are sent one at a time, a few a
+    # minute at most, and a fresh connection is one fewer thing to share
+    # between threads.
+    class Transport
+      # Everything that means "Vatio did not answer", as opposed to "Vatio
+      # said no". All of it is worth retrying.
+      NETWORK_ERRORS = [
+        Timeout::Error, IOError, EOFError, SocketError, SystemCallError, OpenSSL::SSL::SSLError
+      ].freeze
+
+      def call(method:, url:, headers: {}, body: nil, open_timeout: nil, read_timeout: nil)
+        uri = URI.parse(url)
+        request = Net::HTTP.const_get(method.to_s.capitalize).new(uri.request_uri)
+        headers.each { |name, value| request[name] = value }
+        request.body = body if body
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = open_timeout || Config::DEFAULT_OPEN_TIMEOUT
+        http.read_timeout = read_timeout || Config::DEFAULT_READ_TIMEOUT
+        # A POST is never resent behind the caller's back: it is the
+        # idempotency key, not Net::HTTP, that makes a resend safe.
+        http.max_retries = 0 if http.respond_to?(:max_retries=)
+
+        response = http.start { |connection| connection.request(request) }
+        Response.new(status: response.code.to_i, headers: response.each_header.to_h, body: response.body.to_s)
+      rescue *NETWORK_ERRORS => e
+        raise Unavailable.new("vatio server: #{uri&.host} did not answer (#{e.class}: #{e.message})",
+          code: e.is_a?(Timeout::Error) ? "timeout" : "network_error")
+      end
+    end
+  end
+end

data/lib/vatio/server/webhook.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Vatio
+  module Server
+    # Checks that a webhook came from Vatio, the way it was signed:
+    #
+    #   Vatio-Signature: t=1696262400,v1=5257a8...
+    #
+    # `v1` is the hex HMAC-SHA256 of "#{t}.#{raw body}" under the endpoint's
+    # `whsec_` secret. The timestamp is inside what is signed, so a captured
+    # delivery cannot be replayed later with a fresh `t`, and one older than
+    # `tolerance` is refused.
+    #
+    # The raw body, byte for byte: a body parsed and serialized again is a
+    # different string, and its signature does not match. In Rails that is
+    # `request.raw_post`, never `params`.
+    module Webhook
+      HEADER = "Vatio-Signature"
+      TOLERANCE = 300
+
+      InvalidSignature = Class.new(StandardError)
+
+      module_function
+
+      # The event, parsed -- `{"id", "type", "created_at", "workspace",
+      # "environment", "data"}` -- or InvalidSignature.
+      #
+      # Vatio delivers at least once: a delivery that timed out on your side
+      # is sent again, with the same `event["id"]`. Dedupe on it.
+      def verify!(payload:, signature:, secret:, tolerance: TOLERANCE, now: Time.now)
+        secret = secret.to_s
+        # An empty secret is a key anyone can sign with.
+        raise ConfigurationError, "vatio server: the webhook secret is blank -- see Vatio::Server.configure" if secret.strip.empty?
+
+        payload = payload.to_s
+        timestamp, digests = parse(signature)
+        raise InvalidSignature, "no #{HEADER} header, or not t=...,v1=..." if timestamp.nil? || digests.empty?
+        raise InvalidSignature, "#{HEADER} timestamp is outside the tolerance" if (now.to_i - timestamp).abs > tolerance.to_i
+
+        expected = digest(secret, timestamp, payload)
+        raise InvalidSignature, "#{HEADER} does not match the body" unless digests.any? { |candidate| secure_compare(candidate, expected) }
+
+        event = JSON.parse(payload)
+        raise InvalidSignature, "the body is not a JSON object" unless event.is_a?(Hash)
+
+        event
+      rescue JSON::ParserError
+        raise InvalidSignature, "the body is not JSON"
+      end
+
+      # The header Vatio would send for this body, for your own tests of a
+      # receiver. Vatio::Server::Testing.webhook builds a whole request.
+      def sign(payload:, secret:, at: Time.now)
+        timestamp = at.to_i
+        "t=#{timestamp},v1=#{digest(secret.to_s, timestamp, payload.to_s)}"
+      end
+
+      def digest(secret, timestamp, payload)
+        OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{payload}")
+      end
+
+      # Every `v1` is a candidate: a header may one day carry two, while a
+      # secret is being rotated.
+      def parse(header)
+        timestamp = nil
+        digests = []
+        header.to_s.split(",").each do |part|
+          name, value = part.strip.split("=", 2)
+          case name
+          when "t" then timestamp = Integer(value.to_s, exception: false)
+          when "v1" then digests << value.to_s
+          end
+        end
+        [ timestamp, digests ]
+      end
+
+      def secure_compare(left, right)
+        left.bytesize == right.bytesize && OpenSSL.fixed_length_secure_compare(left, right)
+      end
+    end
+  end
+end

data/lib/vatio/server/webhook_receiver.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Vatio
+  module Server
+    # A controller that receives Vatio's webhooks: it checks the signature
+    # on the raw body, answers 400 to anything that does not verify, and
+    # hands each verified event to the handler for its type.
+    #
+    #   # config/routes.rb
+    #   post "/webhooks/vatio", to: "vatio_webhooks#create"
+    #
+    #   class VatioWebhooksController < ActionController::API
+    #     include Vatio::Server::WebhookReceiver
+    #
+    #     on_vatio_event "message.replied" do |event|
+    #       message = Vatio::Server::Message.from(event["data"]["message"])
+    #       Order.find_by(vatio_ref: message.external_ref)&.touch(:customer_answered_at)
+    #     end
+    #   end
+    #
+    # The secret is `Vatio::Server.config.webhook_secret` unless the
+    # controller defines `vatio_webhook_secret`. Override
+    # `handle_vatio_event(event)` instead of the macro to see every event.
+    #
+    # Vatio delivers at least once, so the same event can arrive twice:
+    # dedupe on `event["id"]`, which is the same on every retry. A handler
+    # that raises answers 500 and the delivery is retried later, which is
+    # what you want when your database was down, and why a handler should
+    # be safe to run twice.
+    module WebhookReceiver
+      def self.included(base)
+        base.extend(ClassMethods)
+        # Vatio has no session and no CSRF token: the signature is what
+        # authenticates this request.
+        base.skip_forgery_protection if base.respond_to?(:skip_forgery_protection)
+      end
+
+      module ClassMethods
+        # One or more event types -- message.sent, message.failed,
+        # message.delivered, message.read, message.delivery_failed,
+        # message.replied, ping. The block runs on the controller instance.
+        def on_vatio_event(*types, &handler)
+          raise ArgumentError, "vatio server: on_vatio_event needs a block" unless handler
+
+          own = (@vatio_event_handlers ||= {})
+          types.flatten.each { |type| (own[type.to_s] ||= []) << handler }
+        end
+
+        # Inherited handlers first, then this class's own.
+        def vatio_event_handlers
+          inherited = superclass.respond_to?(:vatio_event_handlers) ? superclass.vatio_event_handlers : {}
+          inherited.merge(@vatio_event_handlers || {}) { |_type, parent, child| parent + child }
+        end
+      end
+
+      def create
+        event = Webhook.verify!(
+          payload: request.raw_post,
+          signature: request.headers[Webhook::HEADER],
+          secret: vatio_webhook_secret,
+          tolerance: vatio_webhook_tolerance
+        )
+      rescue Webhook::InvalidSignature => e
+        logger&.warn("[Vatio::Server::WebhookReceiver] refused: #{e.message}")
+        head :bad_request
+      else
+        handle_vatio_event(event)
+        head :ok unless performed?
+      end
+
+      private
+
+      def handle_vatio_event(event)
+        self.class.vatio_event_handlers.fetch(event["type"].to_s, []).each do |handler|
+          instance_exec(event, &handler)
+        end
+      end
+
+      def vatio_webhook_secret
+        Server.config.webhook_secret
+      end
+
+      def vatio_webhook_tolerance
+        Webhook::TOLERANCE
+      end
+    end
+  end
+end

data/lib/vatio/server.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "identity"
+require_relative "server/config"
+require_relative "server/errors"
+require_relative "server/message"
+require_relative "server/template"
+require_relative "server/transport"
+require_relative "server/client"
+require_relative "server/webhook"
+require_relative "server/webhook_receiver"
+
+module Vatio
+  # The part of this gem that talks to Vatio, and only if you ask for it:
+  # `require "vatio/identity"` never loads it, so signing a token for the
+  # widget still makes no network call at all.
+  #
+  # Your backend calls the server API with a server key (`vsk_`) to have the
+  # agent write to someone first -- an order that shipped, an appointment
+  # tomorrow -- and hears back through a signed webhook.
+  #
+  #   require "vatio/server"
+  #
+  #   Vatio::Server.configure do |c|
+  #     c.server_key = ENV["VATIO_SERVER_KEY"]
+  #     c.workspace  = "acme"          # defaults to Vatio::Identity's audience
+  #   end
+  #
+  #   Vatio::Server.send_message(
+  #     to: "+56912345678",
+  #     brief: "Order #1042 shipped today with Starken, tracking 99812.",
+  #     external_ref: "order-1042-shipped"
+  #   )
+  module Server
+    # Long enough for the person to answer tomorrow and still be signed in
+    # when they do -- the token is what lets a private tool run on their
+    # reply -- and short enough that a conversation nobody came back to does
+    # not stay signed in for good.
+    IDENTITY_TTL = 48 * 3600
+
+    class << self
+      attr_writer :transport
+
+      def config
+        @config ||= Config.new
+      end
+
+      def configure
+        yield config
+        config
+      end
+
+      # Net::HTTP unless swapped, which is what Vatio::Server::Testing does.
+      def transport
+        @transport ||= Transport.new
+      end
+
+      # A client for the configured key. Build your own with
+      # `Client.new(server_key:, workspace:)` to use two keys at once -- a
+      # preview key in staging next to the live one, say.
+      def client
+        Client.new(config)
+      end
+
+      def send_message(**options) = client.send_message(**options)
+      def message_status(id) = client.message_status(id)
+      def messages(**filters) = client.messages(**filters)
+      def templates = client.templates
+      def identity_for(**options) = client.identity_for(**options)
+    end
+  end
+end
+
+# Only where there is a queue to put it on. Autoloaded rather than required:
+# in a Rails app ActiveJob::Base itself loads lazily, and the job is often
+# first named from a controller, before any job class has been. Without
+# ActiveJob loaded yet, `on_load` defines it when it is.
+if defined?(ActiveJob)
+  Vatio::Server.autoload(:SendMessageJob, File.expand_path("server/send_message_job", __dir__))
+elsif defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
+  ActiveSupport.on_load(:active_job) { require_relative "server/send_message_job" }
+end