vatio-sdk 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3ca193521e55a9d1c5c6918c5f7100f632effa64168fa4ccd8bc1ba27918357
-  data.tar.gz: 71f39cb25a704a68b4cd47d0cd45fb7ca7a0162a879a1c281b4a47d86f2d911f
+  metadata.gz: f58bd6f7a713426a74eb89e6393bcd5b678d02abc6e29cc5e9e8286a1bc6366b
+  data.tar.gz: 36b34dfc45e5f65e74f24f14d74c54833a55ef11f8339396c3af7e0277db8b7b
 SHA512:
-  metadata.gz: 8755693383c6f26e929c9dc0be96de067fdbaeed3d2d5dff227b9eed9fe034cfab244d17fa0f8b5baa0464c9849efffcb8b390039c672b4aeafdf87d6129f004
-  data.tar.gz: a5f349288b444d346dcb2d951e7a5305aef998f2564120306b40ea39c8a5b74dc9bd123e9e897de36df7dcc8517db30c05c196fa9fe7ee113915c0c4a6d5d0e6
+  metadata.gz: 313a84c0a4b58cf9234f99acd6136bd7729bd2afc68a250341c63e63e5c9c85dcf5bd1712037763b6eaf1e3b34e468a67d3e5d36cc96430fb929e13382bdd784
+  data.tar.gz: 994c112d1aa656138ccd9b6855b52c45422610addaee8b1a2fe47e3bb97c1f10c295da6e396c4273e77851a4e4a4b1c9aa3e2b4630be1a90994296379ba49633

data/README.md

@@ -8,8 +8,13 @@ That is the property that makes it reasonable for a platform to be verifying
 identity at all — and it is also why everything dangerous about the arrangement
 sits on *your* side of the line. This gem is that side, done once.
 
+Building your app with Claude Code, Cursor or Codex? Start with
+`npx @vatio-ai/skills` and `/vatio-init` in its project. When the agent needs to
+know who your users are and your backend is Rails, your coding agent can set
+this gem up for it. See [vatio.ai](https://vatio.ai).
+
 ```ruby
-gem "vatio-sdk", "~> 0.6"
+gem "vatio-sdk", "~> 0.7"
 ```
 
 On [RubyGems](https://rubygems.org/gems/vatio-sdk) from 0.6.0. Until then it was
@@ -186,14 +191,14 @@ separate require, so an app that only signs tokens never loads it:
 require "vatio/server"
 
 Vatio::Server.configure do |c|
-  c.server_key     = ENV.fetch("VATIO_SERVER_KEY")       # vsk_..., from `vatio keys create`
+  c.server_key     = ENV.fetch("VATIO_SERVER_KEY")       # vsk_..., from `vatio keys create secret`
   c.workspace      = "acme"                               # defaults to Vatio::Identity's audience
   c.webhook_secret = ENV["VATIO_WEBHOOK_SECRET"]          # whsec_..., for the receiver below
 end
 ```
 
-A server key belongs to one workspace and one environment, and a preview key
-can only write to a test phone verified under Test → WhatsApp in the console. Keep
+A secret key belongs to one workspace and one environment, and a preview key
+can only write to a test phone verified in the inbox's Try the agent panel (WhatsApp). Keep
 it on your server: it can message your customers. Net::HTTP does the talking
 (`base_url`, `open_timeout` and `read_timeout` are there if you need them);
 there is no other dependency.
@@ -290,7 +295,7 @@ end
 | `TemplateError` | `template_not_found` (often created in Meta a minute ago: Vatio is syncing, retry shortly), `template_not_approved`, `template_params`, `template_required` |
 | `InvalidRequest` | Any other 422: `invalid_recipient`, `content_required`, `invalid_identity`, `not_a_test_phone`… |
 | `Unauthorized` | 401 / 403: the key is wrong, revoked, or another workspace's |
-| `Conflict` | Any other 409: `idempotency_conflict` (`details["message_id"]`), `identity_conflict`, `whatsapp_not_connected`, `whatsapp_paused` |
+| `Conflict` | Any other 409: `idempotency_conflict` (`details["message_id"]`), `identity_conflict`, `whatsapp_not_connected`, `whatsapp_paused`, `whatsapp_number_unhealthy` (Meta refuses every send from the number; `details["issue"]` says why and the fix) |
 | `NotFound` | `message_status` with an id this key cannot see |
 | `RateLimited` | 429, more than 60 a minute on one key |
 | `Unavailable` | 5xx, timeouts, refused connections |
@@ -330,7 +335,9 @@ Vatio POSTs `message.sent`, `message.failed`, `message.delivered`,
 `message.read`, `message.delivery_failed` and `message.replied` to your
 endpoint, signed with its `whsec_` secret. `data["message"]` is the message
 as `message_status` returns it, and `message.replied` adds `data["reply"]`
-(`chat_message_id`, `content`, `at`):
+(`chat_message_id`, `content`, `at`). `feedback.submitted` is a visitor's
+rating of a conversation, with `data["feedback"]`, `data["chat"]` and
+`data["contact"]` ([payload](https://vatio.ai/docs/api/webhooks#ratings)):
 
 ```ruby
 # config/routes.rb
@@ -400,6 +407,76 @@ expect { Order.ship!(order) }.to have_sent_message(to: order.phone, brief: a_str
 
 See [Messages](https://vatio.ai/docs/api/messages) for the API itself.
 
+## Async tools
+
+A tool declared `async:` in its `tools/*.yml` is one whose work takes longer
+than a reply can wait: Vatio calls your endpoint with a job, your endpoint
+answers 202 at once, and your worker posts the result when it has it. The
+agent tells the person it is on it, knows the job is running on every turn,
+and gives them the result in the same conversation, on any channel
+([Long-running tools](https://vatio.ai/docs/guides/ai-agent-long-running-tools)).
+It is part of `require "vatio/server"`, and needs no server key: the job's
+callback URL is signed and names that one job.
+
+```ruby
+class Vatio::MatchesController < ApplicationController
+  include Vatio::Server::AsyncTool
+  before_action :check_tool_key            # the tool's own Authorization, as for any tool
+
+  def create
+    MatchTherapistsJob.perform_later(vatio_job, reason: params[:reason], area: params[:area])
+    accept_vatio_job(message: "Finding matches; this usually takes about two minutes.")
+  end
+end
+
+class MatchTherapistsJob < ApplicationJob
+  def perform(vatio_job, reason:, area:)
+    vatio_job.run do |job|
+      job.progress("Reviewing 12 therapists in your area", notify: true)
+      therapists = Therapists.match(reason, area)
+      { result: "ok", message: "#{therapists.size} found", data: { therapists: therapists.map(&:to_h) } }
+    end
+  end
+end
+```
+
+- **`vatio_job`** reads the job from the request (`X-Vatio-Job-Id`,
+  `X-Vatio-Callback-Url`), or is nil when the call carries none: answer as any
+  tool then. A callback URL on any host but Vatio's raises
+  `InvalidRequest`, so a forged request cannot send your worker's results
+  elsewhere. **`accept_vatio_job`** answers 202; its `message` reaches the
+  agent.
+- **The job is an ActiveJob argument** as it is. For another queue, store
+  `job.to_h` and rebuild it with `Vatio::Server::Job.from(hash)`. Your queue
+  stores the callback URL: treat it as a secret (`inspect` leaves it out).
+- **`run`** posts what the block returns as the result: the body your
+  endpoint would have answered had it been fast, read through the tool's
+  `respond:`. If the block raises, the job is reported failed, so the
+  person hears now rather than at the timeout, and the error is raised on
+  for your queue. If the job is over while it runs (it timed out, or the
+  person called it off) it stops and returns nil.
+- **By hand:** `progress(text, notify:)`, `complete(message:, data:)`,
+  `failed(message, error_key:)` and `respond(hash)`. Each returns the job's
+  `status` and whether the result was a `duplicate?`. Vatio unreachable or
+  rate limiting is retried three times in the call, over about 20 seconds,
+  rather than by your queue, which would redo the work. `JobClosed` means
+  the job is over: stop.
+
+In tests, `Vatio::Server::Testing.job` builds a job to pass to your code,
+`job_headers(job)` the headers for a request test of the endpoint, and
+`callbacks` is what your code posted:
+
+```ruby
+setup { Vatio::Server::Testing.fake! }
+
+test "matches are reported" do
+  MatchTherapistsJob.perform_now(Vatio::Server::Testing.job, reason: "anxiety", area: "Ñuñoa")
+  result = Vatio::Server::Testing.callbacks.last
+  assert result.result?
+  assert_equal "ok", result.body["result"]
+end
+```
+
 ## What it does not do
 
 Rotate keys, or cache tokens. Verification is repeated on every gate by

data/lib/vatio/identity/version.rb

@@ -2,6 +2,6 @@
 
 module Vatio
   module Identity
-    VERSION = "0.6.0"
+    VERSION = "0.7.1"
   end
 end

data/lib/vatio/server/async_tool.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Vatio
+  module Server
+    # For the controller behind a tool declared `async:`: the job Vatio sent
+    # with the call, and the 202 that says it was accepted.
+    #
+    #   class Vatio::MatchesController < ApplicationController
+    #     include Vatio::Server::AsyncTool
+    #
+    #     def create
+    #       return render(json: match_now) unless vatio_job   # not async: answer as any tool
+    #
+    #       MatchTherapistsJob.perform_later(vatio_job, reason: params[:reason], area: params[:area])
+    #       accept_vatio_job(message: "Finding matches; this usually takes about two minutes.")
+    #     end
+    #   end
+    #
+    # Check the tool's own credential as you would for any tool: the job
+    # headers say where to post, not who is calling.
+    module AsyncTool
+      private
+
+      # The Vatio::Server::Job this request carries, or nil when it carries
+      # none.
+      def vatio_job
+        return @vatio_job if defined?(@vatio_job)
+
+        @vatio_job = Job.from_headers(request.headers)
+      end
+
+      # 202: the agent is told the job started and the person that it is on
+      # its way. `message` reaches the agent, so say how long it usually
+      # takes.
+      def accept_vatio_job(message: nil)
+        render json: { message: message }.compact, status: :accepted
+      end
+    end
+  end
+end

data/lib/vatio/server/client.rb

@@ -24,10 +24,21 @@ module Vatio
       # later -- read it back with `message_status` or hear about it on your
       # webhook.
       #
+      # to:       a phone number, or on Instagram the person's @username or
+      #           Instagram-scoped id.
+      # channel:  "whatsapp" (the default) or "instagram". An Instagram DM
+      #           only reaches someone who wrote in the last 24 hours, and
+      #           takes no template.
+      # comment_id: an Instagram comment on your posts (an `instagram.comment`
+      #           webhook, or `instagram_comments`): a private reply, the one
+      #           DM Instagram lets you send whoever wrote it, within 7 days.
+      #           Needs no `to` or `channel`.
       # 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.
+      #           An authentication template takes `code:` instead of params,
+      #           with no brief or text, and is sent whatever the window.
       #
       # idempotency_key defaults to external_ref. Same key, same request:
       # Vatio answers with the message the first one made and sends nothing
@@ -38,14 +49,16 @@ module Vatio
       # 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)
+      def send_message(to: nil, channel: nil, comment_id: nil, 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,
+          to: to&.to_s,
+          channel: channel&.to_s,
+          comment_id: comment_id&.to_s,
           brief: brief,
           text: text,
           template: template && normalize_template(template),
@@ -68,6 +81,13 @@ module Vatio
         MessageList.from(request(:get, "messages", query: query).body)
       end
 
+      # Comments on your Instagram posts, newest first, up to 50 a page.
+      # `replyable: true` keeps the ones still waiting for a private reply.
+      def instagram_comments(replyable: nil, media_id: nil, limit: nil, before: nil)
+        query = { replyable: replyable, media_id: media_id, limit: limit, before: before }.compact
+        InstagramCommentList.from(request(:get, "instagram/comments", query: query).body)
+      end
+
       def templates
         Array(request(:get, "templates").body["templates"]).map { |item| Template.from(item) }
       end
@@ -128,7 +148,8 @@ module Vatio
       # 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) }
+        { name: hash["name"], language: hash["language"], params: Array(hash["params"]).map(&:to_s),
+          code: hash["code"]&.to_s }.compact
       end
 
       def present(value)

data/lib/vatio/server/errors.rb

@@ -34,6 +34,8 @@ module Vatio
         when "rate_limited" then RateLimited
         when "invalid_key", "workspace_forbidden" then Unauthorized
         when "not_found" then NotFound
+        when "job_closed", "unknown_job" then JobClosed
+        when "invalid_callback_url", "invalid_progress", "invalid_body", "result_too_large" then InvalidRequest
         else
           case status.to_i
           when 401, 403 then Unauthorized
@@ -100,6 +102,12 @@ module Vatio
     # A message id this key's workspace and environment do not have.
     NotFound = Class.new(Error)
 
+    # A job (Vatio::Server::Job) that is over for the conversation: it timed
+    # out, the person called it off, or its callback URL expired a day after
+    # its timeout. Nothing posted to it reaches anyone, so stop working on
+    # it; `Job#run` does.
+    JobClosed = 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

data/lib/vatio/server/job.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "uri"
+
+module Vatio
+  module Server
+    # A job an async tool started: a tool declared `async:` in its tools/*.yml
+    # is called with a job id and the URL to post the result to, and its
+    # endpoint answers 202 and does the work later. This is that job, on your
+    # side: read it in the endpoint, put it on your queue, and report back.
+    #
+    #   class Vatio::MatchesController < ApplicationController
+    #     include Vatio::Server::AsyncTool
+    #
+    #     def create
+    #       MatchTherapistsJob.perform_later(vatio_job, reason: params[:reason], area: params[:area])
+    #       accept_vatio_job(message: "Finding matches; this usually takes about two minutes.")
+    #     end
+    #   end
+    #
+    #   class MatchTherapistsJob < ApplicationJob
+    #     def perform(vatio_job, reason:, area:)
+    #       vatio_job.run do |job|
+    #         job.progress("Reviewing 12 therapists in your area", notify: true)
+    #         { result: "ok", message: "2 found", data: { therapists: find_matches(reason, area) } }
+    #       end
+    #     end
+    #   end
+    #
+    # What a job posts is what your endpoint would have answered had it been
+    # fast: Vatio reads it through the tool's `respond:`, writes it into the
+    # conversation as the tool's answer and has the agent give it to the
+    # person. No server key is needed: the callback URL is signed and names
+    # this one job. Treat it as a secret -- `inspect` leaves it out, but
+    # your queue stores it.
+    class Job
+      HEADER_ID = "X-Vatio-Job-Id"
+      HEADER_CALLBACK_URL = "X-Vatio-Callback-Url"
+      HEADER_EXPIRES_AT = "X-Vatio-Job-Expires-At"
+
+      CALLBACK_PATH = "/api/jobs/v1/"
+
+      # Seconds between the attempts to post one callback when Vatio is
+      # unreachable or rate limiting. Retried here rather than by your queue,
+      # which would redo the work to post it again.
+      RETRY_WAITS = [ 1, 4, 15 ].freeze
+
+      # The answer to a callback: the job's status after it ("pending" after
+      # progress, "completed" or "failed" after the result), and whether this
+      # result had already been taken.
+      State = Struct.new(:job_id, :status, :duplicate, keyword_init: true) do
+        def duplicate? = duplicate == true
+      end
+
+      class << self
+        # How it waits between attempts. Vatio::Server::Testing waits for
+        # nothing.
+        attr_writer :sleeper
+
+        def sleeper = @sleeper || ->(seconds) { sleep(seconds) }
+
+        # The job a request carries, or nil when it carries none: the tool is
+        # not declared `async:`, or the call is not from Vatio. Takes
+        # Rails' `request.headers`, a Rack env or a Hash of header names.
+        #
+        # A callback URL on any host but Vatio's (`base_url`) is refused: a
+        # request that could choose where your worker posts a customer's
+        # data must not get to.
+        def from_headers(headers, config: Server.config)
+          id = header(headers, HEADER_ID)
+          url = header(headers, HEADER_CALLBACK_URL)
+          return nil if blank?(id) || blank?(url)
+
+          new(id: id, callback_url: url, expires_at: header(headers, HEADER_EXPIRES_AT), config: config)
+        end
+
+        # The inverse of `to_h`: for a queue that stores Hashes (Sidekiq, a
+        # database row). ActiveJob takes the Job itself.
+        def from(hash, config: Server.config)
+          hash = hash.to_h.transform_keys(&:to_s)
+          new(id: hash["id"], callback_url: hash["callback_url"], expires_at: hash["expires_at"], config: config)
+        end
+
+        private
+
+        def header(headers, name)
+          value = [ name, name.downcase, "HTTP_#{name.upcase.tr("-", "_")}" ].lazy.map { |key| headers[key] }
+            .find { |candidate| !blank?(candidate) }
+          value&.to_s&.strip
+        end
+
+        def blank?(value) = value.nil? || value.to_s.strip.empty?
+      end
+
+      attr_reader :id, :callback_url, :expires_at
+
+      def initialize(id:, callback_url:, expires_at: nil, config: Server.config)
+        @id = id.to_s
+        @callback_url = callback_url.to_s
+        @expires_at = parse_time(expires_at)
+        @config = config
+        check_callback_url!
+      end
+
+      # How far along it is. Kept for when the person asks how it is going;
+      # with `notify: true` the agent tells them now. For jobs that take
+      # minutes, not for every step.
+      def progress(text, notify: false)
+        post({ progress: text.to_s, notify: notify })
+      end
+
+      # The result: `respond:` maps `data` (or whatever else you send) as it
+      # maps your endpoint's answer, and `message` is relayed when the tool
+      # declares none.
+      def complete(message: nil, data: nil, **fields)
+        respond({ result: "ok", message: message, data: data }.compact.merge(fields))
+      end
+
+      # It could not be done. The agent tells the person, from `message`.
+      def failed(message, error_key: nil, **fields)
+        respond({ result: "error", message: message.to_s, error_key: error_key }.compact.merge(fields))
+      end
+
+      # The result as your endpoint would have answered it, exactly.
+      def respond(body)
+        raise ArgumentError, "vatio job: the result must be a Hash, got #{body.class}" unless body.is_a?(Hash)
+
+        post(body)
+      end
+
+      FAILURE_MESSAGE = "It could not be finished this time."
+
+      # Runs the block and posts what it returns (a Hash, as `respond`) as
+      # the result. If it raises, the job is reported failed with
+      # `failure_message` -- the person hears it now rather than when the
+      # job times out -- and the error is raised on, for your queue and your
+      # error tracker. If Vatio says the job is over (timed out, or the
+      # person called it off) while it runs, it stops there and returns nil.
+      def run(failure_message: FAILURE_MESSAGE)
+        result = yield(self)
+        respond(result)
+      rescue JobClosed
+        nil
+      rescue StandardError => e
+        begin
+          failed(failure_message)
+        rescue Error
+          nil
+        end
+        raise e
+      end
+
+      def expired?
+        !expires_at.nil? && Time.now >= expires_at
+      end
+
+      def to_h
+        { "id" => id, "callback_url" => callback_url, "expires_at" => expires_at&.utc&.iso8601 }
+      end
+
+      def ==(other)
+        other.is_a?(Job) && other.id == id && other.callback_url == callback_url
+      end
+      alias eql? ==
+
+      def hash = [ id, callback_url ].hash
+
+      # Without the callback URL: it is the job's credential.
+      def inspect
+        "#<#{self.class.name} #{id}#{" expires_at=#{expires_at.utc.iso8601}" if expires_at}>"
+      end
+      alias to_s inspect
+
+      private
+
+      def post(body)
+        attempt = 0
+        begin
+          attempt += 1
+          deliver(body)
+        rescue RateLimited, Unavailable
+          raise if attempt > RETRY_WAITS.size
+
+          self.class.sleeper.call(RETRY_WAITS[attempt - 1])
+          retry
+        end
+      end
+
+      def deliver(body)
+        response = Server.transport.call(
+          method: :post, url: callback_url, body: JSON.generate(body),
+          headers: { "Accept" => "application/json", "Content-Type" => "application/json",
+                     "User-Agent" => "vatio-sdk-ruby/#{Identity::VERSION}" },
+          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)
+
+        parsed = {} unless parsed.is_a?(Hash)
+        State.new(job_id: parsed["job_id"] || id, status: parsed["status"], duplicate: parsed["duplicate"] == true)
+      end
+
+      def parse(body)
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def parse_time(value)
+        return value if value.is_a?(Time)
+        return nil if value.nil? || value.to_s.strip.empty?
+
+        Time.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def check_callback_url!
+        uri = URI.parse(callback_url)
+        base = URI.parse(@config.base_url!)
+        same_host = uri.host&.downcase == base.host&.downcase && uri.scheme == base.scheme && uri.port == base.port
+        return if same_host && uri.path.start_with?(CALLBACK_PATH)
+
+        raise InvalidRequest.new("vatio job: the callback URL is not Vatio's (#{base.scheme}://#{base.host})",
+          code: "invalid_callback_url")
+      rescue URI::InvalidURIError
+        raise InvalidRequest.new("vatio job: the callback URL is not a URL", code: "invalid_callback_url")
+      end
+    end
+  end
+end

data/lib/vatio/server/job_serializer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Vatio
+  module Server
+    # Lets a Vatio::Server::Job be an ActiveJob argument:
+    # `perform_later(vatio_job, ...)` stores its Hash and `perform` gets the
+    # Job back.
+    class JobSerializer < ActiveJob::Serializers::ObjectSerializer
+      def serialize(job) = super(job.to_h)
+
+      def deserialize(hash) = Job.from(hash)
+
+      def klass = Job
+    end
+  end
+end
+
+ActiveJob::Serializers.add_serializers(Vatio::Server::JobSerializer)

data/lib/vatio/server/message.rb

@@ -35,7 +35,7 @@ module Vatio
     # 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,
+      :id, :status, :mode, :channel, :environment, :to, :comment_id, :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
@@ -58,6 +58,38 @@ module Vatio
       def error_code = error && error["code"]
     end
 
+    # A comment on your Instagram posts, which a private reply answers:
+    # `send_message(comment_id: comment.id, brief: ...)`. `from` is
+    # `{"id", "username"}`, `media` `{"id", "product_type"}`. `reply_until` is
+    # when Instagram stops taking the reply; `replied_message_id` the message
+    # that took it, once one did.
+    InstagramComment = Struct.new(
+      :id, :text, :from, :media, :parent_id, :live, :created_at, :reply_until, :replied_message_id,
+      keyword_init: true
+    ) do
+      def self.from(hash)
+        hash = (hash || {}).transform_keys(&:to_s)
+        times = %w[created_at reply_until].to_h { |key| [ key, Value.time(hash[key]) ] }
+        Value.build(self, hash.merge(times))
+      end
+
+      def username = from && from["username"]
+      def replied? = !replied_message_id.nil?
+      def replyable?(now: Time.now) = !replied? && !reply_until.nil? && now < reply_until
+    end
+
+    InstagramCommentList = Struct.new(:comments, :next_before, keyword_init: true) do
+      include Enumerable
+
+      def self.from(hash)
+        hash = (hash || {}).transform_keys(&:to_s)
+        new(comments: Array(hash["comments"]).map { |item| InstagramComment.from(item) }.freeze,
+            next_before: hash["next_before"]).freeze
+      end
+
+      def each(&) = comments.each(&)
+    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

data/lib/vatio/server/testing.rb

@@ -35,6 +35,7 @@ module Vatio
       # 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,
+        :channel, :comment_id,
         keyword_init: true
       )
 
@@ -46,16 +47,28 @@ module Vatio
         "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,
+        "whatsapp_number_unhealthy" => 409,
         "idempotency_conflict" => 409, "identity_conflict" => 409, "invalid_key" => 401,
-        "workspace_forbidden" => 403, "not_found" => 404, "rate_limited" => 429, "unavailable" => 503
+        "workspace_forbidden" => 403, "not_found" => 404, "rate_limited" => 429, "unavailable" => 503,
+        "instagram_not_connected" => 409, "unknown_recipient" => 422, "templates_not_supported" => 422,
+        "not_a_test_account" => 422, "comment_not_found" => 404, "comment_reply_expired" => 422,
+        "comment_already_replied" => 409, "comment_recipient_mismatch" => 422, "comments_not_enabled" => 409,
+        "comments_need_live_key" => 409, "job_closed" => 409, "unknown_job" => 404, "result_too_large" => 413
       }.freeze
 
+      # A job's callback, as the fake received it: `kind` is :progress or
+      # :result, and `body` what was posted.
+      Callback = Struct.new(:job_id, :kind, :body, keyword_init: true) do
+        def result? = kind == :result
+        def progress? = kind == :progress
+      end
+
       # `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
+        attr_writer :templates, :window_open, :instagram_comments
 
         # 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_`.
@@ -68,6 +81,8 @@ module Vatio
             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
+            @previous[:sleeper] = Job.instance_variable_get(:@sleeper)
+            Job.sleeper = ->(_seconds) { }
           end
           reset!
           return self unless block_given?
@@ -83,6 +98,7 @@ module Vatio
           return unless faking?
 
           Server.transport = @previous[:transport]
+          Job.sleeper = @previous[:sleeper]
           Server.config.server_key = @previous[:server_key]
           Server.config.workspace = @previous[:workspace]
           @previous = nil
@@ -95,6 +111,7 @@ module Vatio
         def reset!
           @templates = []
           @window_open = true
+          @instagram_comments = []
           fake.reset! if faking?
         end
 
@@ -105,6 +122,29 @@ module Vatio
         # Every request, reads included: [method, path, body].
         def requests = faking? ? fake.requests : []
 
+        # What your code posted to the jobs' callback URLs, oldest first.
+        def callbacks = faking? ? fake.callbacks : []
+
+        # A job as Vatio would hand one to your async tool's endpoint, to
+        # pass to the code under test. Its callbacks land in `callbacks`.
+        #
+        #   job = Vatio::Server::Testing.job
+        #   MatchTherapistsJob.perform_now(job, reason: "anxiety", area: "Ñuñoa")
+        #   assert_equal "ok", Vatio::Server::Testing.callbacks.last.body["result"]
+        def job(id: "job_test#{rand(1_000_000)}", expires_in: 600)
+          Job.new(id: id, callback_url: "#{Server.config.base_url!}#{Job::CALLBACK_PATH}test-#{id}",
+            expires_at: Time.now + expires_in)
+        end
+
+        # The headers Vatio calls an async tool with, for a request test of
+        # its endpoint:
+        #
+        #   post "/vatio/match", params: { reason: "anxiety" }, headers: Vatio::Server::Testing.job_headers(job)
+        def job_headers(job = self.job)
+          { Job::HEADER_ID => job.id, Job::HEADER_CALLBACK_URL => job.callback_url,
+            Job::HEADER_EXPIRES_AT => job.expires_at&.utc&.iso8601 }.compact
+        end
+
         # 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)
@@ -119,6 +159,11 @@ module Vatio
 
         def window_open? = @window_open != false
 
+        # What `Vatio::Server.instagram_comments` answers, and the comments a
+        # `send_message(comment_id:)` can reply to: Hashes as the API sends
+        # them (`id`, `text`, `from`, ...).
+        def instagram_comments = @instagram_comments || []
+
         # A webhook request as Vatio would deliver it, for testing your
         # receiver: post `body` with `headers` to its route.
         #
@@ -153,7 +198,7 @@ module Vatio
       # answered from memory.
       class FakeTransport
         attr_accessor :fail_next
-        attr_reader :messages, :requests
+        attr_reader :messages, :requests, :callbacks
 
         def initialize
           @lock = Mutex.new
@@ -166,6 +211,7 @@ module Vatio
             @payloads = {}
             @by_key = {}
             @requests = []
+            @callbacks = []
             @fail_next = nil
             @next_id = 0
           end
@@ -190,10 +236,13 @@ module Vatio
         private
 
         def route(method, path, query, params, headers)
+          return job_callback(path, params) if method == "post" && path.start_with?(Job::CALLBACK_PATH)
+
           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 method == "get" && path == "instagram/comments" then comments(query)
           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}")
@@ -210,12 +259,31 @@ module Vatio
           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
+          comment = nil
+          if params["comment_id"]
+            comment = Testing.instagram_comments.map { |item| item.transform_keys(&:to_s) }
+              .find { |item| item["id"].to_s == params["comment_id"].to_s }
+            return refusal(404, "comment_not_found", "No comment #{params["comment_id"]}.") unless comment
+            if @messages.any? { |message| message.comment_id == params["comment_id"].to_s }
+              return refusal(409, "comment_already_replied", "Comment #{params["comment_id"]} already has its private reply.")
+            end
+
+            to = "@#{comment.dig("from", "username") || comment.dig("from", "id")}"
+          end
+          instagram = params["channel"].to_s == "instagram" || !comment.nil?
+          if comment
+            return refusal(422, "templates_not_supported", "Instagram has no message templates.") if params["template"]
+          elsif instagram
+            return refusal(422, "invalid_recipient", "to must be an Instagram @username or id.") unless to.match?(/\A@?[A-Za-z0-9._]{1,32}\z/)
+            return refusal(422, "templates_not_supported", "Instagram has no message templates.") if params["template"]
+          elsif to.gsub(/\D/, "").length < 8
+            return refusal(422, "invalid_recipient", "to must be a phone number in international format.")
+          end
           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"
+          mode = if comment || Testing.window_open? then params["text"] ? "text" : "agent"
           elsif params["template"] then "template"
           end
           unless mode
@@ -230,8 +298,8 @@ module Vatio
 
           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,
+            id: id, status: "queued", mode: mode, channel: instagram ? "instagram" : "whatsapp", environment: "live",
+            to: instagram ? to : "+#{to.gsub(/\D/, "")}", comment_id: comment && comment["id"].to_s, 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
           }
@@ -241,11 +309,44 @@ module Vatio
             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
+            mode: mode, channel: instagram ? "instagram" : "whatsapp", comment_id: comment && comment["id"].to_s
           ).freeze
           json(202, payload)
         end
 
+        # As the callback endpoint answers: progress 202 while the job runs,
+        # the result 200 once, the same result again 200 with `duplicate`,
+        # anything after a different end 409.
+        def job_callback(path, params)
+          job_id = path.delete_prefix(Job::CALLBACK_PATH)[/\Atest-(.+)\z/, 1]
+          finished = @callbacks.find { |callback| callback.job_id == job_id && callback.result? }
+          progress = params.key?("progress") && !params.key?("result")
+
+          if finished
+            if progress || finished.body != params
+              return refusal(409, "job_closed", "Job #{job_id} already ended.", status: finished_status(finished.body))
+            end
+
+            return json(200, { job_id: job_id, status: finished_status(params), duplicate: true })
+          end
+
+          @callbacks << Callback.new(job_id: job_id, kind: progress ? :progress : :result, body: params).freeze
+          return json(202, { job_id: job_id, status: "pending" }) if progress
+
+          json(200, { job_id: job_id, status: finished_status(params) })
+        end
+
+        def finished_status(body) = body["result"] == "error" ? "failed" : "completed"
+
+        def comments(query)
+          items = Testing.instagram_comments.map { |item| JSON.parse(JSON.generate(item)) }
+          if query["replyable"] == "true"
+            replied = @messages.filter_map(&:comment_id)
+            items = items.reject { |item| replied.include?(item["id"].to_s) }
+          end
+          json(200, { comments: items.first((query["limit"] || 50).to_i.clamp(1, 50)), next_before: nil })
+        end
+
         def list(query)
           items = @payloads.values.reverse
           items = items.select { |item| item["external_ref"] == query["external_ref"] } if query["external_ref"]

data/lib/vatio/server/webhook_receiver.rb

@@ -38,7 +38,8 @@ module Vatio
       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.
+        # message.replied, feedback.submitted, 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
 

data/lib/vatio/server.rb

@@ -12,6 +12,8 @@ require_relative "server/transport"
 require_relative "server/client"
 require_relative "server/webhook"
 require_relative "server/webhook_receiver"
+require_relative "server/job"
+require_relative "server/async_tool"
 
 module Vatio
   # The part of this gem that talks to Vatio, and only if you ask for it:
@@ -20,7 +22,8 @@ module Vatio
   #
   # 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.
+  # tomorrow -- and hears back through a signed webhook. And it reports on
+  # the jobs its async tools started (Job, AsyncTool), which needs no key.
   #
   #   require "vatio/server"
   #
@@ -69,6 +72,7 @@ module Vatio
       def message_status(id) = client.message_status(id)
       def messages(**filters) = client.messages(**filters)
       def templates = client.templates
+      def instagram_comments(**filters) = client.instagram_comments(**filters)
       def identity_for(**options) = client.identity_for(**options)
     end
   end
@@ -83,3 +87,8 @@ if defined?(ActiveJob)
 elsif defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
   ActiveSupport.on_load(:active_job) { require_relative "server/send_message_job" }
 end
+# So a Job can be an ActiveJob argument. Once ActiveJob::Base loads, which in
+# a Rails app is after this file and runs this at once if it already has.
+if defined?(ActiveSupport) && ActiveSupport.respond_to?(:on_load)
+  ActiveSupport.on_load(:active_job) { require_relative "server/job_serializer" }
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vatio-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Urcalab
@@ -45,9 +45,12 @@ files:
 - lib/vatio/identity/version.rb
 - lib/vatio/sdk.rb
 - lib/vatio/server.rb
+- lib/vatio/server/async_tool.rb
 - lib/vatio/server/client.rb
 - lib/vatio/server/config.rb
 - lib/vatio/server/errors.rb
+- lib/vatio/server/job.rb
+- lib/vatio/server/job_serializer.rb
 - lib/vatio/server/message.rb
 - lib/vatio/server/send_message_job.rb
 - lib/vatio/server/template.rb