vertodigital 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1fb341d3711560cccd46da14a974a8ea3bf580510adc031af66af58e610b1f24
+  data.tar.gz: a406841df627a8123cbad93f94b58ff4aa8ba3c1b28d0bce05ed15787e11d21d
+SHA512:
+  metadata.gz: cdf669b4a0e076640bfc1cc4f59b7a1246c915d2452d82dcf43b092856e85e5530ad236a867e192342c4e85ee9fb46b5a643b0f906c8e220e9bd37ccfb0108c9
+  data.tar.gz: 2957d79669878265c3e7aaffabb85f93d277cddeb09dbc5117051085a4ed66b250dbb546af93868540241c91f9ecfabb291abf969612d8476f82eee7a038a296

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- First release: `health`, `case_studies` / `each_case_study`, `contact`, `openapi`, `llms_txt`, `page`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VertoDigital
+
+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,72 @@
+# vertodigital
+
+Official Ruby client for [VertoDigital's public agent API](https://vertodigital.com/developers). Every endpoint is anonymous, so there's no API key to set up. No runtime dependencies, just the Ruby standard library.
+
+## Install
+
+```
+gem install vertodigital
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "vertodigital"
+```
+
+## Usage
+
+```ruby
+require "vertodigital"
+
+client = VertoDigital::Client.new
+
+client.health
+# => {"status"=>"ok", "service"=>"vertodigital-agent-api", ...}
+
+# One page of case studies
+page = client.case_studies(limit: 10)
+page["items"].each { |cs| puts "#{cs["name"]}: #{cs["stat"]}" }
+
+# Or every case study, paginated for you
+client.each_case_study.map { |cs| cs["url"] }
+
+# Any page on vertodigital.com as markdown
+puts client.page("about")
+puts client.llms_txt
+
+# The OpenAPI 3.1 spec
+client.openapi["paths"].keys
+
+# Submit a contact enquiry on behalf of a user
+client.contact(
+  from_name: "Ada Lovelace",
+  from_email: "ada@example.com",
+  organization: "Analytical Engines Ltd",
+  topic: "services", # assessment, services, partnership, press, careers, general
+  message: "We'd like to discuss a marketing analytics engagement."
+)
+```
+
+`contact` sends an `Idempotency-Key` automatically. If you retry after a timeout, pass the same `idempotency_key:` again so the enquiry is only recorded once.
+
+Requests go to the pinned `/agent/v1/*` paths by default. Pass `api_version: nil` to use the unversioned `/agent/*` paths.
+
+## Errors
+
+- `VertoDigital::APIError` for any non-2xx response. It carries `status` and `body`.
+- `VertoDigital::RateLimitError` (a subclass) on 429. It adds `retry_after` in seconds.
+- `VertoDigital::ArgumentError` when input fails validation before a request is sent.
+
+Rate limits and the full API reference are at [vertodigital.com/developers](https://vertodigital.com/developers).
+
+## Publishing (maintainers)
+
+From this directory:
+
+```
+gem build vertodigital.gemspec
+gem push vertodigital-0.1.0.gem
+```
+
+Bump `VERSION` in `lib/vertodigital/version.rb` and add a `CHANGELOG.md` entry on every release. MFA is required to push.

data/lib/vertodigital/client.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+module VertoDigital
+  # Client for VertoDigital's public agent API (https://vertodigital.com/developers).
+  # Every endpoint is anonymous - no API key needed.
+  class Client
+    DEFAULT_BASE_URL = "https://vertodigital.com"
+    TOPICS = %w[assessment services partnership press careers general].freeze
+
+    attr_reader :base_url
+
+    # base_url - override for testing against a staging deploy.
+    # timeout  - open/read timeout in seconds.
+    # api_version - "v1" pins requests to /agent/v1/*; nil uses the unversioned /agent/* paths.
+    def initialize(base_url: DEFAULT_BASE_URL, timeout: 15, api_version: "v1")
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+      @prefix = api_version ? "/agent/#{api_version}" : "/agent"
+    end
+
+    # GET /agent/v1/health - service status and endpoint map.
+    def health
+      get_json("#{@prefix}/health")
+    end
+
+    # GET /agent/v1/case-studies - one page of case studies.
+    # Returns the raw page: {"items" => [...], "count", "total", "has_more", "next_cursor"}.
+    def case_studies(limit: nil, cursor: nil)
+      query = {}
+      query[:limit] = limit if limit
+      query[:cursor] = cursor if cursor
+      get_json("#{@prefix}/case-studies", query)
+    end
+
+    # Iterates every case study across all pages. Returns an Enumerator without a block.
+    def each_case_study(limit: 50, &block)
+      return enum_for(:each_case_study, limit: limit) unless block
+
+      cursor = nil
+      loop do
+        page = case_studies(limit: limit, cursor: cursor)
+        page.fetch("items", []).each(&block)
+        break unless page["has_more"] && page["next_cursor"]
+
+        cursor = page["next_cursor"]
+      end
+    end
+
+    # POST /agent/v1/contact - submit a contact enquiry on behalf of a user.
+    # A fresh Idempotency-Key is generated unless you pass one; reuse the same
+    # key when retrying so a timeout never produces a duplicate enquiry.
+    def contact(from_name:, from_email:, message:, organization: nil, topic: "general",
+                agent_id: nil, idempotency_key: SecureRandom.uuid)
+      unless TOPICS.include?(topic.to_s)
+        raise VertoDigital::ArgumentError, "topic must be one of: #{TOPICS.join(", ")}"
+      end
+      if message.to_s.strip.length < 10
+        raise VertoDigital::ArgumentError, "message must be at least 10 characters"
+      end
+
+      body = { fromName: from_name, fromEmail: from_email, message: message, topic: topic.to_s }
+      body[:organization] = organization if organization
+      body[:agentId] = agent_id if agent_id
+      request(Net::HTTP::Post, "#{@prefix}/contact", body: body,
+                                                    headers: { "Idempotency-Key" => idempotency_key })
+    end
+
+    # The OpenAPI 3.1 spec, parsed.
+    def openapi
+      get_json("/agent/openapi.json")
+    end
+
+    # /llms.txt - the site's page index, as markdown text.
+    def llms_txt
+      get_text("/llms.txt")
+    end
+
+    # Any page's markdown mirror, e.g. page("about") or page("case-studies/cloudflare-enterprise").
+    def page(slug)
+      clean = slug.to_s.sub(%r{\A/+}, "").sub(/\.md\z/, "")
+      raise VertoDigital::ArgumentError, "slug is required" if clean.empty?
+
+      get_text("/markdown/#{clean}.md")
+    end
+
+    private
+
+    def get_json(path, query = {})
+      request(Net::HTTP::Get, path, query: query)
+    end
+
+    def get_text(path)
+      request(Net::HTTP::Get, path, raw: true)
+    end
+
+    def request(klass, path, query: {}, body: nil, headers: {}, raw: false)
+      uri = URI("#{@base_url}#{path}")
+      uri.query = URI.encode_www_form(query) unless query.empty?
+
+      req = klass.new(uri)
+      req["User-Agent"] = "vertodigital-ruby/#{VERSION}"
+      req["Accept"] = raw ? "text/markdown, text/plain" : "application/json"
+      headers.each { |k, v| req[k] = v }
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                                open_timeout: @timeout, read_timeout: @timeout) do |http|
+        http.request(req)
+      end
+      handle(res, path, raw)
+    end
+
+    def handle(res, path, raw)
+      code = res.code.to_i
+      text = res.body.to_s.dup.force_encoding(Encoding::UTF_8)
+
+      if code.between?(200, 299)
+        return text if raw
+
+        return text.empty? ? {} : JSON.parse(text)
+      end
+
+      parsed = begin
+        JSON.parse(text)
+      rescue JSON::ParserError
+        text
+      end
+      if code == 429
+        retry_after = res["Retry-After"]&.to_i
+        raise RateLimitError.new(code, parsed, path, retry_after)
+      end
+      raise APIError.new(code, parsed, path)
+    end
+  end
+end

data/lib/vertodigital/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module VertoDigital
+  # Base class for everything this gem raises.
+  class Error < StandardError; end
+
+  # Raised when an argument fails validation before any request is sent.
+  class ArgumentError < Error; end
+
+  # Raised for any non-2xx response. `status` is the HTTP status code and
+  # `body` is the parsed JSON error body when there is one, otherwise the raw text.
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body, path)
+      @status = status
+      @body = body
+      super("#{status} from #{path}#{detail(body)}")
+    end
+
+    private
+
+    def detail(body)
+      return "" unless body.is_a?(Hash)
+
+      message = body["error"] || body["message"]
+      message ? ": #{message.is_a?(Hash) ? message["message"] || message : message}" : ""
+    end
+  end
+
+  # Raised on 429. `retry_after` is the number of seconds to wait, when the
+  # API sends a Retry-After header.
+  class RateLimitError < APIError
+    attr_reader :retry_after
+
+    def initialize(status, body, path, retry_after)
+      @retry_after = retry_after
+      super(status, body, path)
+    end
+  end
+end

data/lib/vertodigital/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module VertoDigital
+  VERSION = "0.1.0"
+end

data/lib/vertodigital.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "vertodigital/version"
+require_relative "vertodigital/errors"
+require_relative "vertodigital/client"
+
+# Ruby client for VertoDigital's public agent API. See https://vertodigital.com/developers.
+module VertoDigital
+  # Shortcut for VertoDigital::Client.new.
+  def self.client(**options)
+    Client.new(**options)
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: vertodigital
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- VertoDigital
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-30 00:00:00.000000000 Z
+dependencies: []
+description: 'Official Ruby SDK for VertoDigital''s anonymous REST API: health, paginated
+  case studies, contact enquiries, the OpenAPI spec, and markdown mirrors of every
+  page on vertodigital.com.'
+email:
+- team@vertodigital.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/vertodigital.rb
+- lib/vertodigital/client.rb
+- lib/vertodigital/errors.rb
+- lib/vertodigital/version.rb
+homepage: https://vertodigital.com/developers
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://vertodigital.com
+  documentation_uri: https://vertodigital.com/developers
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby client for VertoDigital's public agent API.
+test_files: []