ask-anychat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94d004dde4b043c13876327f103c7c35e21cfd5027aace5cb8df0f3b8c97248a
+  data.tar.gz: b7abca34b3ca86d763fe170bd13ea469693a7dd62e135b59b068e2ab9aa8f7b6
+SHA512:
+  metadata.gz: c5d6e51b5b420cdfedf8b8f1feed43fbd3ffa478d3a4783d16ad8ca80b9205d0d070d172342344d2997fc7cbe1369c811bcb1fd80dee37dc9f74a4b4713bab03
+  data.tar.gz: dfc675d8e95290db9cfa45a6e0fefc80ea1df01197a3349e838428006c0ab24864b8fb89a9bc7a87081c37f673ce5b65df1aa6925f22c671ca35df79381a7cb4

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+## [0.1.0] - 2026-09-17
+
+### Added
+
+- **The Anychat API client** — `Ask::AnyChat.client` resolves its base URL from
+  the hosted app and its token through ask-auth (`ANYCHAT_TOKEN`, then the
+  credentials file, then Rails credentials, then the database), so most callers
+  pass neither.
+
+- **Workspace agent CRUD** — `workspace_agents`, `workspace_agent`,
+  `create_workspace_agent`, `update_workspace_agent` and
+  `destroy_workspace_agent`, addressing an agent by the address it answers on.
+  Creating takes a name and derives the address from it, handing a taken one the
+  first free variant rather than failing.
+
+- **Errors under one parent** — `Ask::AnyChat::Error` with `Unauthorized`,
+  `NotFound`, `Invalid`, `Api` and `Unreachable` beneath it, each carrying the
+  sentence the API answered with. A workspace the token cannot see is reported
+  as not found rather than forbidden, which is the API's answer as well.
+
+- **A bundled skill** — `anychat.use_anychat`, so a model that has the gem also
+  has the instructions for using it.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# Ask::AnyChat
+
+Anychat API client for the [ask-rb](https://github.com/ask-rb) ecosystem.
+
+Anychat gives a business an agent of its own — a page customers can visit, a chat
+they can talk to, and the words it answers with. This gem creates and manages the
+agents a workspace owns.
+
+This is the client layer only. Tool framing — MCP servers, native `Ask::Tools` —
+is provided by the consumers.
+
+## Installation
+
+```ruby
+gem "ask-anychat"
+```
+
+## Usage
+
+```ruby
+client = Ask::AnyChat.client
+
+client.workspace_agents("anywaye")             # every agent a workspace owns
+client.workspace_agent("anywaye", "support")   # one, by the address it answers on
+client.create_workspace_agent("anywaye", display_name: "Support")
+client.update_workspace_agent("anywaye", "support", display_name: "Help desk")
+client.destroy_workspace_agent("anywaye", "support")
+```
+
+The base URL defaults to the hosted app and the token is resolved through
+[ask-auth](https://github.com/ask-rb/ask-auth) — `ANYCHAT_TOKEN` in the
+environment, then the credentials file, then Rails credentials, then the
+database. Mint a token in Anychat under Settings → API tokens.
+
+Point it somewhere else with `Ask::AnyChat.client(base_url:, token:)`.
+
+An agent in Anychat is a **workspace agent**: the system templates every agent is
+cloned from are not what this reaches, only the agents a workspace owns. An
+address that belongs to a workspace the token cannot see is reported as not found
+rather than forbidden — the same answer as one that does not exist.
+
+### Failures
+
+Everything raises under `Ask::AnyChat::Error`, carrying the sentence the API
+answered with.
+
+| Raised | What it means |
+| --- | --- |
+| `Error::Unauthorized` | The token is missing, expired or refused |
+| `Error::NotFound` | No such workspace, or no such agent in it |
+| `Error::Invalid` | The request was understood and refused — the message says why |
+| `Error::Api` | The API failed, or answered with something unexpected |
+| `Error::Unreachable` | The API could not be reached at all |
+
+A refusal is not worth retrying; `Error::Unreachable` and `Error::Api` are.
+
+## Contributing
+
+Run `bin/setup` once, then `bundle exec rake test`.
+
+## License
+
+MIT.

data/lib/ask/anychat/client.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "erb"
+require "faraday"
+require "faraday/retry"
+require "ask/auth"
+
+module Ask
+  module AnyChat
+    # A client for the Anychat API.
+    #
+    # Every call names a workspace, because a workspace is what a token reaches:
+    # the API resolves it through the token's user, so a token sees only the
+    # workspaces its user belongs to. Naming somebody else's workspace is the
+    # same answer as naming one that does not exist, which is the point.
+    #
+    #   client = Ask::AnyChat.client(base_url: "https://anywaye.com", token: "...")
+    #   client.workspace_agents("anywaye")
+    #
+    # Failures raise under Error, carrying the sentence the API answered with.
+    class Client
+      RETRY_STATUSES = [429, 500, 502, 503].freeze
+      OPEN_TIMEOUT = 10
+
+      attr_reader :base_url
+
+      def initialize(base_url:, token:, timeout: 30)
+        @base_url = normalize(base_url)
+        @token = token
+        @timeout = timeout
+      end
+
+      # The agents a workspace owns, oldest first.
+      def workspace_agents(workspace)
+        fetch_key(get(agents_path(workspace)), "agents")
+      end
+
+      # One agent, by the address it answers on.
+      def workspace_agent(workspace, handle)
+        fetch_key(get("#{agents_path(workspace)}/#{encode(handle)}"), "agent")
+      end
+
+      def create_workspace_agent(workspace, **attributes)
+        fetch_key(post(agents_path(workspace), agent: attributes), "agent")
+      end
+
+      def update_workspace_agent(workspace, handle, **attributes)
+        fetch_key(patch("#{agents_path(workspace)}/#{encode(handle)}", agent: attributes), "agent")
+      end
+
+      # An address the owner printed is the reason they care about this one, so
+      # it is gone afterwards and free for the next agent to take. Nothing comes
+      # back but the fact that it worked; a failure raises.
+      def destroy_workspace_agent(workspace, handle)
+        delete("#{agents_path(workspace)}/#{encode(handle)}")
+      end
+
+      # The headers every request carries. Public because it is the honest
+      # answer to "what does this client send?" — and because a caller swapping
+      # the connection under it should be able to keep them.
+      def default_headers
+        {
+          "Authorization" => "Bearer #{token}",
+          "Accept" => "application/json",
+          "User-Agent" => "ask-anychat/#{VERSION}"
+        }
+      end
+
+      private
+
+      attr_reader :token, :timeout
+
+      def agents_path(workspace)
+        "/api/#{API_VERSION}/workspaces/#{encode(workspace)}/agents"
+      end
+
+      def get(path, params = nil)
+        request(:get, path, params: params)
+      end
+
+      def post(path, body = nil)
+        request(:post, path, body: body)
+      end
+
+      def patch(path, body = nil)
+        request(:patch, path, body: body)
+      end
+
+      def delete(path)
+        request(:delete, path)
+      end
+
+      def request(method, path, body: nil, params: nil)
+        response = connection.public_send(method, path) do |request|
+          request.params = params if params
+          request.body = body if body
+        end
+
+        response.success? ? parse(response) : raise_for(response)
+      rescue Faraday::Error => e
+        raise Error::Unreachable, "#{base_url} could not be reached: #{e.message}"
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: base_url, headers: default_headers) do |builder|
+          builder.request :json
+          builder.response :json, content_type: /\bjson$/
+          builder.request :retry, max: 3, retry_statuses: RETRY_STATUSES, interval: 0.5
+          builder.options.timeout = timeout
+          builder.options.open_timeout = OPEN_TIMEOUT
+          builder.adapter Faraday.default_adapter
+        end
+      end
+
+      # A body is an object, or nothing at all — a 204 has nothing to read. A
+      # body that is neither is the API answering with something this gem does
+      # not know what to do with, which is worth saying out loud.
+      def parse(response)
+        body = response.body
+        return {} if body.nil? || (body.is_a?(String) && body.strip.empty?)
+        return body if body.is_a?(Hash)
+
+        raise Error::Api, "the API answered with #{body.class} where an object was expected"
+      end
+
+      def raise_for(response)
+        message = message_from(response)
+
+        case response.status
+        when 401 then raise Error::Unauthorized, message
+        when 404 then raise Error::NotFound, message
+        when 422 then raise Error::Invalid, message
+        else raise Error::Api, "HTTP #{response.status} from #{base_url}: #{message}"
+        end
+      end
+
+      # A failure is answered as {"error" => "..."} and sometimes with a
+      # field-by-field map beside it. The sentence is what a person reads, so it
+      # is preferred over the map and over the status code.
+      def message_from(response)
+        body = response.body
+        return body.to_s unless body.is_a?(Hash)
+
+        sentence = body["error"].to_s.strip
+        return sentence unless sentence.empty?
+        return body["errors"].to_s if body["errors"]
+
+        "the request was refused"
+      end
+
+      def fetch_key(body, key)
+        body.fetch(key) { raise Error::Api, "the API answered without #{key.inspect}: #{body.inspect}" }
+      end
+
+      def encode(segment)
+        ERB::Util.url_encode(segment.to_s)
+      end
+
+      def normalize(url)
+        url.to_s.sub(%r{/+\z}, "")
+      end
+    end
+  end
+end

data/lib/ask/anychat/context.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    # What this is, for a model deciding whether to reach for it.
+    DESCRIPTION = "Anychat gives a business an agent of its own — a page customers " \
+                  "can visit, a chat they can talk to, and the words it answers with. " \
+                  "This client creates and manages those agents."
+
+    DOMAIN_URL = "https://anywaye.com"
+    DOCS_URL = "https://anywaye.com/docs/api"
+
+    # ask-auth resolves this name in order: ANYCHAT_TOKEN in the environment,
+    # the credentials file, Rails credentials, then the database.
+    AUTH_NAME = :anychat_token
+    AUTH_HOW = "Mint a token in Anychat under Settings → API tokens, then set it as " \
+               "ANYCHAT_TOKEN, or pass token: to Ask::AnyChat.client."
+
+    API_VERSION = "v1"
+
+    QUICK_START = <<~RUBY
+      client = Ask::AnyChat.client(token: ENV["ANYCHAT_TOKEN"])
+
+      client.workspace_agents("anywaye")             # every agent a workspace owns
+      client.workspace_agent("anywaye", "support")   # one, by the address it answers on
+      client.create_workspace_agent("anywaye", display_name: "Support")
+      client.update_workspace_agent("anywaye", "support", display_name: "Help desk")
+      client.destroy_workspace_agent("anywaye", "support")
+    RUBY
+  end
+end

data/lib/ask/anychat/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    # Everything this gem raises, under one parent, so a caller can rescue the
+    # library rather than a list of its moods. Each one carries the sentence the
+    # API answered with: "An agent needs a name." is worth more than "422".
+    class Error < StandardError
+      # The token was missing, expired, or refused.
+      class Unauthorized < Error; end
+
+      # No such workspace — or none this token can reach, which is the same
+      # answer on purpose.
+      class NotFound < Error; end
+
+      # The API understood the request and refused it; the message says why.
+      class Invalid < Error; end
+
+      # The API failed, or answered with something this gem did not expect.
+      class Api < Error; end
+
+      # The API could not be reached at all.
+      class Unreachable < Error; end
+    end
+  end
+end

data/lib/ask/anychat/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    VERSION = "0.1.0"
+  end
+end

data/lib/ask/skills/anychat.use_anychat/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: anychat.use_anychat
+description: Manage the agents an Anychat workspace owns — list them, bring a new one into being, rename or re-title one, or retire one. Use when a request concerns an Anychat agent's name, its address, or the set of agents a workspace has.
+---
+
+# Using Anychat
+
+Anychat gives a business an agent of its own: a page customers can visit, a chat
+they can talk to, and the words it answers with. This client creates and manages
+those agents.
+
+An agent in Anychat is a **workspace agent**. A workspace owns one or many, and
+each answers on `/<workspace>/<handle>` — the link the owner prints. The system
+templates every agent is cloned from are not what this reaches; only the agents a
+workspace owns.
+
+## Step 1: get the client
+
+```ruby
+client = Ask::AnyChat.client
+```
+
+The base URL defaults to the hosted app and the token is resolved through
+ask-auth, so this usually needs no arguments. To point somewhere else:
+
+```ruby
+Ask::AnyChat.client(base_url: "https://staging.anywaye.com", token: ENV["STAGING_TOKEN"])
+```
+
+## Step 2: name the workspace
+
+Every call names one, because a workspace is what a token reaches: the API
+resolves it through the token's user, so a token sees only the workspaces its
+user belongs to. Naming somebody else's workspace is the same answer as naming
+one that does not exist — a `NotFound`, not a `Forbidden`.
+
+```ruby
+client.workspace_agents("anywaye")
+```
+
+## Step 3: read before you write
+
+```ruby
+client.workspace_agents("anywaye")             # every agent, oldest first
+client.workspace_agent("anywaye", "support")   # one, by the address it answers on
+```
+
+Read first for two reasons: it tells you which addresses are already taken, and
+it gives you the `handle` that `update` and `destroy` need. There is no lookup
+by name — an agent is addressed by its address.
+
+## Step 4: create
+
+```ruby
+client.create_workspace_agent("anywaye", display_name: "Support")
+```
+
+Only a name is required. The address is derived from it, and a taken one is not
+a failure — the new agent is handed the first free variant (`support-2`,
+`support-3`). Pass `handle:` to choose the address yourself when the owner has
+one in mind.
+
+`description:` and `public:` may be given too; everything else an agent shows
+(branding, greeting, colour) is the owner's to edit afterwards.
+
+## Step 5: change one
+
+```ruby
+client.update_workspace_agent("anywaye", "support", display_name: "Help desk")
+client.update_workspace_agent("anywaye", "support", handle: "help")
+```
+
+Only the attributes you pass are written. Renaming the address is safe: the
+handler allocates a free one if what you asked for is taken.
+
+## Step 6: retire one
+
+```ruby
+client.destroy_workspace_agent("anywaye", "support")
+```
+
+The address goes with it and becomes free again. Conversations customers had
+with it are kept — they are a record of what somebody was told — so a retired
+agent still appears in that history.
+
+## When it is refused
+
+Every failure raises under `Ask::AnyChat::Error`, carrying the sentence the API
+answered with, which is written to be read out:
+
+| Raised | What it means |
+| --- | --- |
+| `Error::Unauthorized` | The token is missing, expired or refused |
+| `Error::NotFound` | No such workspace, or no such agent in it |
+| `Error::Invalid` | The request was understood and refused — the message says why |
+| `Error::Api` | The API failed, or answered with something unexpected |
+| `Error::Unreachable` | The API could not be reached at all |
+
+```ruby
+begin
+  client.create_workspace_agent("anywaye", display_name: "")
+rescue Ask::AnyChat::Error::Invalid => e
+  e.message   # => "An agent needs a name."
+end
+```
+
+A refusal is not something to retry. `Error::Unreachable` and `Error::Api` are.

data/lib/ask-anychat.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "ask/anychat/version"
+require_relative "ask/anychat/context"
+require_relative "ask/anychat/errors"
+require_relative "ask/anychat/client"
+
+module Ask
+  # Anychat: an agent for a business — a page, a chat, and the words it answers
+  # with — and the client that creates and manages one.
+  module AnyChat
+    # A client for the Anychat API.
+    #
+    #   Ask::AnyChat.client(token: ENV["ANYCHAT_TOKEN"])
+    #
+    # The base URL defaults to the hosted app, and the token is resolved through
+    # ask-auth (ANYCHAT_TOKEN, then the credentials file, then Rails
+    # credentials, then the database), so most callers pass one of the two —
+    # often neither.
+    def self.client(base_url: nil, token: nil, **options)
+      Client.new(
+        base_url: base_url || ENV["ANYCHAT_BASE_URL"] || DOMAIN_URL,
+        token: token || Auth.resolve(AUTH_NAME),
+        **options
+      )
+    end
+  end
+end

metadata

@@ -0,0 +1,141 @@
+--- !ruby/object:Gem::Specification
+name: ask-anychat
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-auth
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'Creates and manages the agents an Anychat workspace owns. Anychat gives
+  a business an agent of its own — a page customers can visit, a chat they can talk
+  to, and the words it answers with. This is the client layer only: the tool framing
+  that exposes it to an agent (MCP servers, native Ask::Tools) is provided by the
+  consumers.'
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ask-anychat.rb
+- lib/ask/anychat/client.rb
+- lib/ask/anychat/context.rb
+- lib/ask/anychat/errors.rb
+- lib/ask/anychat/version.rb
+- lib/ask/skills/anychat.use_anychat/SKILL.md
+homepage: https://github.com/ask-rb/ask-anychat
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-anychat
+  source_code_uri: https://github.com/ask-rb/ask-anychat
+  changelog_uri: https://github.com/ask-rb/ask-anychat/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: Anychat API client for the ask-rb ecosystem
+test_files: []