vatio-sdk 0.6.0

data/lib/vatio/identity.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "jwt"
+require "openssl"
+
+require_relative "identity/version"
+require_relative "identity/config"
+
+module Vatio
+  # Signs the one credential Vatio accepts, and verifies it on the way back.
+  #
+  # Vatio holds only the public half of the key, so the most it can do is
+  # check: it cannot mint a token for one of your users. That is the property
+  # that makes it reasonable for a platform to be verifying identity at all --
+  # and it is also why every way this can go wrong lives on this side of the
+  # line, in your application, which is what this library is for.
+  #
+  #   Vatio::Identity.configure do |c|
+  #     c.audience    = "acme"                        # your workspace slug
+  #     c.private_key = ENV["VATIO_IDENTITY_PRIVATE_KEY"]
+  #   end
+  module Identity
+    Error = Class.new(StandardError)
+    ConfigurationError = Class.new(Error)
+
+    # The same leeway Vatio verifies with. Clocks disagree by seconds; a minute
+    # covers the drift between two servers and is far too short to matter to
+    # anyone holding an expired token.
+    LEEWAY = 60
+
+    # `exp` because a token with no expiry is a permanent credential sitting in
+    # page source. `aud` because a signature proves who signed, not what for:
+    # without it any other JWT you sign with this key -- a password reset, a
+    # download link -- is accepted as an identity, since it also has a `sub`.
+    REQUIRED_CLAIMS = %w[sub exp aud].freeze
+
+    # Carried by every JWT and meaningful to the protocol rather than to you,
+    # so they are stripped back out of `claims` on the way in.
+    REGISTERED_CLAIMS = %w[iss sub aud exp nbf iat jti].freeze
+
+    Principal = Struct.new(:subject, :claims, :token, keyword_init: true)
+
+    SIGN_IN_HOST = "https://vatio.ai"
+    SIGN_IN_CODE = /\A[A-Za-z0-9_-]{16,64}\z/
+
+    # A week rather than the widget's hour. The widget gets a fresh token on
+    # every page load; a WhatsApp contact keeps this one until it expires and
+    # then has to sign in again, so an hour would mean signing in for every
+    # conversation. Pass `expires_in:` to choose otherwise.
+    SIGN_IN_EXPIRES_IN = 7 * 24 * 3600
+
+    class << self
+      def config
+        @config ||= Config.new
+      end
+
+      def configure
+        yield config
+        config
+      end
+
+      # A signed token for one of your users, ready to hand to the widget.
+      #
+      # Registered claims are merged last on purpose: a caller passing
+      # `aud:` or `exp:` in `claims` is either confused or being creative with
+      # someone else's session, and neither is worth honouring.
+      #
+      # `audience` is for Vatio::Server, which signs for the workspace its
+      # server key names; everyone else leaves it to the configured slug.
+      # `config` is for an app serving several workspaces: that workspace's
+      # Config, in place of the global one.
+      def token_for(subject:, claims: {}, expires_in: nil, audience: nil, config: self.config)
+        subject = subject.to_s.strip
+        raise ArgumentError, "vatio identity: subject cannot be blank" if subject.empty?
+
+        now = Time.now.to_i
+        payload = stringify(claims).merge(
+          "sub" => subject,
+          "aud" => audience.to_s.strip.empty? ? config.audience! : audience.to_s.strip,
+          "iat" => now,
+          "exp" => now + (expires_in || config.expires_in).to_i
+        )
+
+        JWT.encode(payload, config.private_key, config.algorithm)
+      end
+
+      # The other half, for your own API: a private tool forwards the same JWT
+      # as `$auth.token`, and the endpoint behind it has to check the signature
+      # itself rather than trust the caller. Returns nil for anything that does
+      # not verify -- expired, wrong key, wrong audience, absent.
+      #
+      # Nil is not an error. It means "not signed in", which on the web is the
+      # normal state of a visitor reading a marketing page.
+      def verify(raw, config: self.config)
+        raw = raw.to_s.strip
+        return nil if raw.empty?
+
+        payload, = JWT.decode(
+          raw, config.public_key, true,
+          # Pinned, never read from the token's header.
+          algorithms: [ config.algorithm ],
+          required_claims: REQUIRED_CLAIMS.dup,
+          verify_expiration: true,
+          leeway: LEEWAY,
+          aud: config.audience!,
+          verify_aud: true
+        )
+
+        Principal.new(
+          subject: payload["sub"].to_s,
+          claims: payload.reject { |k, _| REGISTERED_CLAIMS.include?(k) },
+          token: raw
+        )
+      rescue JWT::DecodeError
+        nil
+      end
+
+      # The script tag, with the token on it only when somebody is signed in.
+      #
+      # Beware of caching. Rails renders this per request, so it is safe by
+      # default -- but the moment this fragment lands in a page cache, a CDN,
+      # or `caches_action`, you are serving one customer's identity to the
+      # next visitor. If anything caches this page, render it without a token
+      # and call `window.VatioWidget.identify(token)` from an uncached
+      # endpoint instead.
+      def widget_tag(workspace:, token:, subject: nil, claims: {}, config: self.config, **attrs)
+        visitor = subject && token_for(subject: subject, claims: claims, config: config)
+        pairs = {
+          "src" => "https://cdn.vatio.ai/v1/widget.js",
+          "async" => "async",
+          "data-workspace" => workspace,
+          "data-token" => token,
+          "data-visitor-token" => visitor
+        }.merge(attrs.transform_keys { |k| "data-#{k.to_s.tr("_", "-")}" }).compact
+
+        "<script #{pairs.map { |k, v| %(#{k}="#{escape(v)}") }.join(" ")}></script>"
+      end
+
+      # Where to send someone who tapped "Sign in" on WhatsApp or Instagram,
+      # once they are signed in to your site. The page at `auth.sign_in_url`
+      # receives `?code=...`; redirect to this with that code and the same
+      # subject and claims you would put on the widget.
+      #
+      # The host is fixed on purpose. A url taken from the request would let
+      # anyone who can craft a link have your server sign a token for whoever
+      # opens it and hand it to them.
+      def sign_in_redirect_url(code:, subject:, claims: {}, expires_in: SIGN_IN_EXPIRES_IN, config: self.config)
+        code = code.to_s
+        raise ArgumentError, "vatio identity: not a Vatio sign-in code" unless code.match?(SIGN_IN_CODE)
+
+        token = token_for(subject: subject, claims: claims, expires_in: expires_in, config: config)
+        "#{SIGN_IN_HOST}/connect/#{code}?token=#{token}"
+      end
+
+      private
+
+      def stringify(claims)
+        Hash(claims).each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+
+      def escape(value)
+        value.to_s.gsub("&", "&amp;").gsub('"', "&quot;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+    end
+  end
+end
+
+require_relative "identity/railtie" if defined?(Rails::Railtie)

data/lib/vatio/sdk.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# What `Bundler.require` loads for `gem "vatio-sdk"`. The server API stays
+# opt-in: `require "vatio/server"`.
+require_relative "identity"

data/lib/vatio/server/client.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Vatio
+  module Server
+    # The server API, one method per endpoint. `Vatio::Server.send_message`
+    # and friends use one built from `Vatio::Server.config`; build your own
+    # for a second key:
+    #
+    #   staging = Vatio::Server::Client.new(server_key: ENV["VATIO_PREVIEW_KEY"], workspace: "acme")
+    class Client
+      API_PATH = "/api/server/v1"
+
+      attr_reader :config
+
+      def initialize(config = nil, transport: nil, **options)
+        @config = config || Config.new(**options)
+        @transport = transport
+      end
+
+      # Has the agent write to `to` first. Returns a Message, `queued`: it
+      # is recorded and on its way, and the send itself happens a moment
+      # later -- read it back with `message_status` or hear about it on your
+      # webhook.
+      #
+      # brief:    what the agent should write about, and the facts to use.
+      # text:     your own words, sent as is.
+      # template: { name:, language:, params: [] }, used only when the 24-hour
+      #           window is closed -- send it too to always reach the person.
+      #
+      # idempotency_key defaults to external_ref. Same key, same request:
+      # Vatio answers with the message the first one made and sends nothing
+      # (`replayed?`). Same key, different request: Conflict. So give each
+      # message its own ref -- "order-1042-shipped", not "order-1042".
+      #
+      # subject: signs an identity for that user (aud: the workspace, exp:
+      # now + identity_ttl), so a private tool can run when they answer. The
+      # exp has to cover how long they may take to: past it, they are
+      # answered as a stranger. Or pass a token you signed as `identity:`.
+      def send_message(to:, brief: nil, text: nil, template: nil, external_ref: nil, idempotency_key: nil,
+                       subject: nil, claims: {}, identity_ttl: IDENTITY_TTL, identity: nil)
+        raise ArgumentError, "vatio server: pass subject: or identity:, not both" if subject && identity
+
+        identity ||= identity_for(subject: subject, claims: claims, ttl: identity_ttl) if subject
+        key = present(idempotency_key) || present(external_ref)
+        body = {
+          to: to.to_s,
+          brief: brief,
+          text: text,
+          template: template && normalize_template(template),
+          external_ref: external_ref,
+          identity: identity
+        }.compact
+
+        response = request(:post, "messages", body: body, headers: key ? { "Idempotency-Key" => key } : {})
+        Message.from(response.body, replayed: response.headers["idempotent-replayed"] == "true")
+      end
+
+      def message_status(id)
+        Message.from(request(:get, "messages/#{escape(id)}").body)
+      end
+
+      # Newest first, up to 50 a page. `status` is queued, sent or failed;
+      # `external_ref` finds the messages for one of your own records.
+      def messages(external_ref: nil, status: nil, limit: nil, before: nil)
+        query = { external_ref: external_ref, status: status, limit: limit, before: before }.compact
+        MessageList.from(request(:get, "messages", query: query).body)
+      end
+
+      def templates
+        Array(request(:get, "templates").body["templates"]).map { |item| Template.from(item) }
+      end
+
+      # The identity token a message carries, signed with this client's
+      # `identity` config (Vatio::Identity's unless given) for its workspace.
+      # Sign once and pass it as `identity:` if you retry a call yourself: a
+      # token signed again is a different request to the idempotency check,
+      # and answers Conflict.
+      def identity_for(subject:, claims: {}, ttl: IDENTITY_TTL)
+        Identity.token_for(subject: subject, claims: claims, expires_in: ttl.to_i,
+                           audience: config.workspace!, config: config.identity)
+      end
+
+      private
+
+      def transport
+        @transport || Server.transport
+      end
+
+      def request(method, path, query: nil, body: nil, headers: {})
+        url = "#{config.base_url!}#{API_PATH}/#{escape(config.workspace!)}/#{path}"
+        url += "?#{URI.encode_www_form(query)}" if query && !query.empty?
+
+        response = transport.call(
+          method: method,
+          url: url,
+          headers: {
+            "Authorization" => "Bearer #{config.server_key!}",
+            "Accept" => "application/json",
+            "Content-Type" => "application/json",
+            "User-Agent" => "vatio-sdk-ruby/#{Identity::VERSION}"
+          }.merge(headers),
+          body: body && JSON.generate(body),
+          open_timeout: config.open_timeout,
+          read_timeout: config.read_timeout
+        )
+
+        parsed = parse(response.body)
+        raise Error.from_response(response.status, parsed, response.headers) unless (200..299).cover?(response.status)
+
+        unless parsed.is_a?(Hash)
+          raise Unavailable.new("vatio server: HTTP #{response.status} with a body that is not JSON",
+            code: "invalid_response", status: response.status, request_id: response.headers["x-request-id"])
+        end
+
+        Response.new(status: response.status, headers: response.headers, body: parsed)
+      end
+
+      def parse(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Accepts a Hash with symbol or string keys, or anything with `to_h`.
+      def normalize_template(template)
+        hash = template.to_h.transform_keys(&:to_s)
+        { name: hash["name"], language: hash["language"], params: Array(hash["params"]).map(&:to_s) }
+      end
+
+      def present(value)
+        value = value.to_s.strip
+        value.empty? ? nil : value
+      end
+
+      def escape(value) = URI.encode_www_form_component(value.to_s)
+    end
+  end
+end

data/lib/vatio/server/config.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Vatio
+  module Server
+    ConfigurationError = Class.new(StandardError)
+
+    # The server key and the workspace it belongs to, and where to reach it.
+    #
+    # The key already names its workspace and environment; the slug goes in
+    # the path anyway, and Vatio refuses a request whose two disagree. That is
+    # what keeps a key pasted into the wrong service from quietly writing to
+    # another workspace's customers.
+    class Config
+      DEFAULT_BASE_URL = "https://vatio.ai"
+
+      # A send is recorded and queued, never performed in the request, so it
+      # answers in milliseconds; anything slower than this is not coming.
+      DEFAULT_OPEN_TIMEOUT = 5
+      DEFAULT_READ_TIMEOUT = 15
+
+      # `webhook_secret` is the endpoint's `whsec_`, read by WebhookReceiver
+      # unless the controller defines `vatio_webhook_secret` itself.
+      attr_accessor :server_key, :base_url, :open_timeout, :read_timeout, :webhook_secret
+      attr_writer :workspace, :identity
+
+      def initialize(server_key: nil, workspace: nil, base_url: DEFAULT_BASE_URL,
+                     open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT, webhook_secret: nil,
+                     identity: nil)
+        @server_key = server_key
+        @workspace = workspace
+        @identity = identity
+        @base_url = base_url
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @webhook_secret = webhook_secret
+      end
+
+      # The Vatio::Identity::Config that signs `subject:` identities. The
+      # global one unless this client is for another workspace's key.
+      def identity
+        @identity || Identity.config
+      end
+
+      # The slug, falling back to the identity's audience: it is the same
+      # workspace, and saying it twice is a chance to say it differently.
+      def workspace
+        value = @workspace.to_s.strip
+        value = identity.audience.to_s.strip if value.empty?
+        value.empty? ? nil : value
+      end
+
+      def workspace!
+        workspace || raise(ConfigurationError, missing("workspace (your Vatio workspace slug)"))
+      end
+
+      # Never logged, never put in an error message.
+      def server_key!
+        value = server_key.to_s.strip
+        return value unless value.empty?
+
+        raise ConfigurationError, missing("server_key (a vsk_ key from `vatio keys create`)")
+      end
+
+      def base_url!
+        base_url.to_s.strip.delete_suffix("/").then { |url| url.empty? ? DEFAULT_BASE_URL : url }
+      end
+
+      private
+
+      def missing(name)
+        "vatio server: #{name} is not configured -- see Vatio::Server.configure"
+      end
+    end
+  end
+end

data/lib/vatio/server/errors.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Vatio
+  module Server
+    # Every refusal from the server API, with the `code` it was sent with.
+    #
+    # The subclasses are the decisions a caller actually makes: send a
+    # template instead (OutsideWindow), leave this person alone (OptedOut,
+    # HumanAnswering), fix the request (TemplateError, InvalidRequest), fix
+    # the key (Unauthorized), or try again later (RateLimited, Unavailable).
+    # Only the last two are worth retrying, and `retryable?` says so.
+    class Error < StandardError
+      attr_reader :code, :status, :details, :request_id
+
+      # `headers` is the response's, for the subclasses that read one.
+      def initialize(message = nil, code: nil, status: nil, details: {}, request_id: nil, headers: nil)
+        super(message || code || "vatio server error")
+        @code = code&.to_s
+        @status = status
+        @details = details || {}
+        @request_id = request_id
+      end
+
+      def retryable? = false
+
+      # The class a refusal maps to: by code first, since the code is the
+      # contract, and by status for codes this version does not know yet.
+      def self.class_for(status, code)
+        case code.to_s
+        when "outside_window" then OutsideWindow
+        when "opted_out" then OptedOut
+        when "human_takeover", "handoff_pending" then HumanAnswering
+        when /\Atemplate_/ then TemplateError
+        when "rate_limited" then RateLimited
+        when "invalid_key", "workspace_forbidden" then Unauthorized
+        when "not_found" then NotFound
+        else
+          case status.to_i
+          when 401, 403 then Unauthorized
+          when 404 then NotFound
+          when 409 then Conflict
+          when 400, 422 then InvalidRequest
+          when 429 then RateLimited
+          when 408, 500..599 then Unavailable
+          else Error
+          end
+        end
+      end
+
+      # From a response the API answered with: `{error: {code, message,
+      # ...details}, request_id}`. A body that is not that -- a proxy's HTML
+      # 502 -- still becomes an error of the right class, by its status.
+      def self.from_response(status, body, headers = {})
+        payload = body.is_a?(Hash) ? body : {}
+        error = payload["error"].is_a?(Hash) ? payload["error"] : {}
+        code = error["code"] || "http_#{status}"
+        message = error["message"] || "Vatio answered HTTP #{status}"
+        details = error.reject { |key, _| %w[code message].include?(key) }
+
+        class_for(status, code).new(
+          message, code: code, status: status, details: details,
+          request_id: payload["request_id"] || headers["x-request-id"], headers: headers
+        )
+      end
+    end
+
+    # The contact has not written in the last 24 hours, so WhatsApp only
+    # delivers an approved template, and none was sent. Only you can decide
+    # whether a template is the right thing to send instead.
+    class OutsideWindow < Error
+      def last_inbound_at
+        value = details["last_inbound_at"]
+        value && Time.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # The contact asked not to be written to from this number.
+    OptedOut = Class.new(Error)
+
+    # A person is answering this conversation from the inbox
+    # (`human_takeover`), or it is waiting for one (`handoff_pending`).
+    # Writing over them is exactly what this refusal is for.
+    HumanAnswering = Class.new(Error)
+
+    # The template cannot be sent as given: not found (often created in Meta a
+    # minute ago -- Vatio is syncing, retry shortly), not approved, or the
+    # wrong number of params.
+    TemplateError = Class.new(Error)
+
+    # Any other 422: an invalid number, no `brief` or `text`, an identity
+    # that does not verify, a preview key writing to a number that is not a
+    # test phone.
+    InvalidRequest = Class.new(Error)
+
+    # The key is missing, wrong, revoked, or belongs to another workspace.
+    Unauthorized = Class.new(Error)
+
+    # A message id this key's workspace and environment do not have.
+    NotFound = Class.new(Error)
+
+    # Any other 409: the idempotency key was already used for a different
+    # message (`details["message_id"]` names it), the conversation is
+    # signed in as someone else, or the WhatsApp number is not connected or
+    # not live.
+    Conflict = Class.new(Error)
+
+    # More than 60 messages a minute on one key.
+    class RateLimited < Error
+      attr_reader :retry_after
+
+      # Seconds, when Vatio says; nil when it does not.
+      def initialize(message = nil, headers: nil, **options)
+        super
+        @retry_after = Integer((headers || {})["retry-after"].to_s, exception: false)
+      end
+
+      def retryable? = true
+    end
+
+    # Vatio did not answer, or answered 5xx: a timeout, a refused connection,
+    # a deploy. Retry with the same idempotency key and a request that did
+    # get through is answered with the message it made, not a second one.
+    class Unavailable < Error
+      def retryable? = true
+    end
+  end
+end

data/lib/vatio/server/message.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Vatio
+  module Server
+    # Shared by the values below: the API's JSON, read into a frozen struct.
+    # Keys this version does not know are dropped rather than refused, so a
+    # field Vatio adds tomorrow does not break today's gem.
+    module Value
+      module_function
+
+      def time(value)
+        value && Time.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def build(klass, hash, **extra)
+        hash = (hash || {}).transform_keys(&:to_s)
+        attrs = klass.members.to_h { |name| [ name, hash[name.to_s] ] }
+        klass.new(**attrs, **extra).freeze
+      end
+    end
+
+    # A message your backend sent, as Vatio reports it -- the same shape on
+    # the response, on `message_status`, and in every webhook's
+    # `data["message"]`:
+    #
+    #   Vatio::Server::Message.from(event["data"]["message"])
+    #
+    # `status` is the message's own state: queued (recorded, not sent yet),
+    # sent, or failed (with `error["code"]`). `content` is what reached the
+    # phone -- the agent's words, your text as sent, or the template rendered
+    # -- and `chat_message_id` its row in the conversation, once it is sent.
+    # `delivery` is Meta's word on it -- sent, delivered, read or failed --
+    # once there is one. Nested hashes (`template`, `delivery`, `error`) keep
+    # the API's string keys.
+    Message = Struct.new(
+      :id, :status, :mode, :channel, :environment, :to, :chat_id, :external_ref, :idempotency_key,
+      :brief, :text, :template, :content, :chat_message_id, :delivery, :error, :sent_at, :replied_at,
+      :created_at, :replayed,
+      keyword_init: true
+    ) do
+      def self.from(hash, replayed: false)
+        hash = (hash || {}).transform_keys(&:to_s)
+        times = %w[sent_at replied_at created_at].to_h { |key| [ key, Value.time(hash[key]) ] }
+        Value.build(self, hash.merge(times).except("replayed"), replayed: replayed)
+      end
+
+      # True when the request reused an idempotency key: this is the message
+      # the first request made, as it stands now, and nothing new was sent.
+      def replayed? = replayed == true
+
+      def queued? = status == "queued"
+      def sent? = status == "sent"
+      def failed? = status == "failed"
+      def replied? = !replied_at.nil?
+
+      def error_code = error && error["code"]
+    end
+
+    # One page of `messages`, newest first. Pass `next_before` back as
+    # `before:` for the next one; it is nil on the last page.
+    MessageList = Struct.new(:messages, :next_before, keyword_init: true) do
+      include Enumerable
+
+      def self.from(hash)
+        hash = (hash || {}).transform_keys(&:to_s)
+        new(
+          messages: Array(hash["messages"]).map { |item| Message.from(item) }.freeze,
+          next_before: hash["next_before"]
+        ).freeze
+      end
+
+      def each(&block) = messages.each(&block)
+      def next_page? = !next_before.nil?
+
+      # The page's messages, not the struct's members, which is what Struct
+      # would answer for these ahead of Enumerable.
+      def to_a = messages.dup
+      alias_method :entries, :to_a
+      def size = messages.size
+      alias_method :length, :size
+    end
+  end
+end

data/lib/vatio/server/send_message_job.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "active_job"
+require "securerandom"
+
+module Vatio
+  module Server
+    # `Vatio::Server.send_message` on your queue, with the same keywords:
+    #
+    #   Vatio::Server::SendMessageJob.perform_later(
+    #     to: order.phone, brief: "Order #{order.number} shipped...",
+    #     external_ref: "order-#{order.id}-shipped", subject: order.user_id
+    #   )
+    #
+    # Retried when Vatio is rate limiting or unreachable, never when it said
+    # no: a closed window or an opted-out contact is the same answer on the
+    # tenth try. Those are logged and discarded; subclass and `discard_on` the
+    # one you want to act on -- a later declaration wins:
+    #
+    #   class ShippedMessageJob < Vatio::Server::SendMessageJob
+    #     discard_on(Vatio::Server::OutsideWindow) { |job, error| ... }
+    #   end
+    #
+    # A retry is safe because the request carries an idempotency key: yours,
+    # your external_ref, or one made here when the job is enqueued. And an
+    # identity for `subject:` is signed here too, once, rather than on every
+    # attempt -- a token signed again is a different request to the
+    # idempotency check, which would answer Conflict instead of the message
+    # the first attempt made. That token sits in your queue until the job
+    # runs, and its exp starts at enqueue: a job scheduled far ahead needs an
+    # identity_ttl that covers the wait too.
+    class SendMessageJob < ActiveJob::Base
+      queue_as :default
+
+      # Declared first so the retries below, declared later, take precedence.
+      discard_on Vatio::Server::Error do |job, error|
+        job.logger&.warn(
+          "[Vatio::Server::SendMessageJob] not sent: #{error.code} #{error.message} " \
+          "(status #{error.status.inspect}, request #{error.request_id.inspect})"
+        )
+      end
+
+      # About 3s, 18s, 1.5m, 4m, 10m... -- past a rate limit's minute and past
+      # most deploys, and then it fails where your queue shows failed jobs.
+      retry_on Vatio::Server::RateLimited, Vatio::Server::Unavailable,
+        wait: ->(executions) { (executions**4) + 2 }, attempts: 10
+
+      def self.prepare(arguments)
+        options = arguments.first
+        return arguments unless arguments.size == 1 && options.is_a?(Hash)
+
+        options = options.transform_keys(&:to_sym)
+        subject = options.delete(:subject)
+        claims = options.delete(:claims) || {}
+        ttl = options.delete(:identity_ttl) || IDENTITY_TTL
+        options[:identity] ||= Server.identity_for(subject: subject, claims: claims, ttl: ttl) if subject
+        options[:idempotency_key] ||= options[:external_ref] || "job-#{SecureRandom.uuid}"
+
+        [ Hash.ruby2_keywords_hash(options) ]
+      end
+
+      def initialize(*arguments)
+        super(*self.class.prepare(arguments))
+      end
+      ruby2_keywords(:initialize)
+
+      def perform(**options)
+        Server.send_message(**options)
+      end
+    end
+  end
+end