zeroclick-sellers 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21a687776a099cffab368909929c6181de3425e83d6fe94bcfaba52cc40e76a8
-  data.tar.gz: 15b009873e6410a7703a6385ebdfc0d737f1be8d3d475b18ed22e96683117904
+  metadata.gz: c4d8cedea5994f6b40e5d7505027dfe9bf1fa9df5dfe32863070534bee183859
+  data.tar.gz: ff203775e81db08e529b7fe0908da260c3142b7e1a82783f9eaac4cf3624fdcd
 SHA512:
-  metadata.gz: 10cc75f795e921fa55d77b5dce9f101d1f3c4afadb191fe70546db9bd01dd309fe8453cfedd24de1d1991e1716567de26378b17cb87fb8338866f1132d4e96bd
-  data.tar.gz: 82a1860e38b1a2b53195b1aa0c17830b60f2c7ad5cdc80efc280c6547678f74771ed799a42ddabaf405c1df3f00f36de6344402e3c104c03078cc94e2d00f90e
+  metadata.gz: ccdf34f7bfccb29b898b0e71212b4573124c58b852417a883a812d24520a776710a73a1c46c2a5741e85bbad2760bc20dfd97047639a7e59e5623884937cc778
+  data.tar.gz: 0ddb34edef539de4e5cbdd1d78747e6424bf4f95db680fde8dbf1cb7db2492b350711ee83c93653ca0df7edf64e96ab57174587c22cf881c579e46f8c6e92c78

data/lib/zeroclick/sellers/agentify.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+require_relative "errors"
+require_relative "usage"
+
+module ZeroClick
+  module Sellers
+    # Agentify: serve a marketing page as agent-optimized markdown.
+    #
+    # Detection is one pure boolean over two request headers; the conversion is
+    # a GET against ZeroClick's Agentify API, authenticated with a zc_ key
+    # carrying the agentify:convert scope. As in Usage, transport and
+    # interpretation are separate: interpret_markdown is pure, so what a
+    # response MEANS is decided in one place and tested without a socket.
+    module Agentify
+      # Calendar version of the detection rules below, matching the
+      # `detectionVersion` in agentify-detection-vectors.json. The vector file
+      # is generated by packages/sellers-python/tests/vectors/
+      # generate_agentify_detection_vectors.py — the authority on this
+      # contract — and a vector test pins this constant and the substring list
+      # to it, so an update cannot land here without regenerating the vectors
+      # (and vice versa).
+      DETECTION_VERSION = "2026-08-25.01"
+
+      # Case-insensitive substrings that mark an AI agent's user-agent: the
+      # AI-operator crawlers, assistant fetchers, and browser agents. Classic
+      # search crawlers (googlebot, bingbot, ...) are deliberately absent —
+      # serving them different content than browsers is cloaking — and so are
+      # generic http tools (curl, python, ...), which ask for markdown via
+      # Accept when they want it.
+      AI_USER_AGENT_SUBSTRINGS = %w[
+        anthropic
+        bytespider
+        ccbot
+        chatgpt
+        claude
+        duckassistbot
+        google-cloudvertexbot
+        googleagent-mariner
+        gptbot
+        meta-externalagent
+        meta-externalfetcher
+        mistralai
+        oai-searchbot
+        openai
+        perplexity
+      ].freeze
+
+      MARKDOWN_PATH = "/v1/agentify/markdown"
+
+      # The converted document plus the response headers worth forwarding to
+      # the agent — the customer's CDN caches the markdown too.
+      class MarkdownResult
+        attr_reader :markdown, :cache_control, :content_type, :etag
+
+        def initialize(markdown:, cache_control: nil, content_type: nil, etag: nil)
+          @markdown = markdown
+          @cache_control = cache_control
+          @content_type = content_type
+          @etag = etag
+          freeze
+        end
+      end
+
+      module_function
+
+      # Whether a request should be answered with agentified markdown: the
+      # client either negotiates for it (Accept prefers text/markdown over
+      # text/html) or announces an AI agent user-agent. A pure predicate over
+      # the two header values — absent or empty headers are simply false,
+      # never an error.
+      def wants_agent_markdown?(accept: nil, user_agent: nil)
+        prefers_markdown?(accept) || ai_user_agent?(user_agent)
+      end
+
+      # Whether text/markdown outranks text/html in an Accept header.
+      #
+      # Agent fetchers (Claude's WebFetch and kin) send `Accept:
+      # text/markdown, text/html, */*`; browsers never list text/markdown.
+      # Markdown wins only when explicitly listed with q > 0 and not outranked
+      # by text/html (higher q, or listed first on a tie). Ported from the
+      # platform's negotiation and pinned by the shared detection vectors: the
+      # first entry of each media type and the first parseable q parameter of
+      # an entry count.
+      def prefers_markdown?(accept)
+        return false if accept.nil? || accept.empty?
+
+        markdown = nil
+        html = nil
+        accept.downcase.split(",").each_with_index do |raw_entry, index|
+          parts = raw_entry.strip.split(";")
+          media_type = parts[0].to_s.strip
+          q = 1.0
+          parts[1..].each do |raw_param|
+            param = raw_param.strip
+            next unless param.start_with?("q=")
+
+            # An unparseable q contributes nothing: the default of 1 stands
+            # unless a later q parameter parses.
+            value = q_value(param)
+            next if value.nil?
+
+            q = value
+            break
+          end
+          entry = { q: q, index: index }
+          markdown ||= entry if media_type == "text/markdown"
+          html ||= entry if media_type == "text/html"
+        end
+
+        return false if markdown.nil? || markdown[:q] <= 0
+        return true if html.nil? || html[:q] <= 0
+
+        markdown[:q] > html[:q] || (markdown[:q] == html[:q] && markdown[:index] < html[:index])
+      end
+
+      def ai_user_agent?(user_agent)
+        return false if user_agent.nil? || user_agent.empty?
+
+        lowered = user_agent.downcase
+        AI_USER_AGENT_SUBSTRINGS.any? { |token| lowered.include?(token) }
+      end
+
+      # The q of one already-trimmed "q=..." parameter, or nil when unusable.
+      def q_value(param)
+        value = Float(param[2..])
+        value.nan? || value.infinite? ? nil : value
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      # ----------------------------------------------------------- build
+
+      # Reject anything but an absolute http(s) URL before it reaches the API.
+      def validate_page_url!(url, operation:)
+        parsed = begin
+          URI.parse(url.to_s)
+        rescue URI::InvalidURIError
+          nil
+        end
+        return if parsed.is_a?(URI::HTTP) && !parsed.host.nil? && !parsed.host.empty?
+
+        raise Error.new("malformed_input", operation: operation,
+                                           message: "url must be an absolute http(s) URL, got #{url.inspect}")
+      end
+
+      def request_headers(api_key)
+        {
+          "accept" => "text/markdown",
+          "authorization" => "Bearer #{api_key}",
+          "user-agent" => Usage::USER_AGENT
+        }
+      end
+
+      # ------------------------------------------------------- interpret
+
+      def interpret_markdown(status, body, headers)
+        raise Error.new("api_status_error", operation: "fetch_agentify_markdown", status: status) unless (200..299).cover?(status)
+
+        MarkdownResult.new(
+          markdown: body,
+          cache_control: headers["cache-control"],
+          content_type: headers["content-type"],
+          etag: headers["etag"]
+        )
+      end
+
+      # ------------------------------------------------------- transport
+
+      # Returns [status, body, headers] with lowercase header names. Raises
+      # only api_transport_error — an HTTP status is data here, not a failure,
+      # and interpretation happens above.
+      def get(base_url:, path:, query:, api_key:, timeout:, operation:)
+        uri = URI.join(base_url, path)
+        uri.query = URI.encode_www_form(query)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        # Both halves, or a server that accepts the connection and then stalls
+        # hangs the request past the caller's budget.
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+
+        request = Net::HTTP::Get.new(uri)
+        request_headers(api_key).each { |name, value| request[name] = value }
+
+        response = http.request(request)
+        headers = response.each_header.to_h { |name, value| [name.downcase, value] }
+        [response.code.to_i, response.body.to_s, headers]
+      rescue *Usage::TRANSPORT_ERRORS => e
+        raise Error.new("api_transport_error", operation: operation, cause: e.message)
+      ensure
+        http&.finish if http&.started?
+      end
+    end
+  end
+end

data/lib/zeroclick/sellers/client.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "agentify"
 require_relative "contracts"
 require_relative "errors"
 require_relative "responses"
@@ -25,20 +26,29 @@ module ZeroClick
       def initialize(api_key: nil,
                      usage_read_key: nil,
                      usage_write_key: nil,
+                     agentify_key: nil,
                      signing_secrets: nil,
                      resolve_signing_secret: nil,
                      api_base_url: DEFAULT_API_BASE_URL,
                      tolerance_seconds: DEFAULT_TOLERANCE_SECONDS,
                      allowance_unavailable_policy: "allow",
                      check_timeout_seconds: DEFAULT_CHECK_TIMEOUT_SECONDS,
+                     agentify_timeout_seconds: DEFAULT_AGENTIFY_TIMEOUT_SECONDS,
                      on_allowance_unavailable: nil,
                      clock: -> { Time.now.to_i },
-                     # The transport, injectable so every decision this class
+                     # The transports, injectable so every decision this class
                      # makes about a response is testable without a socket.
-                     # Must return [status, body] or raise Error.
-                     http_post: Usage.method(:post))
+                     # http_post must return [status, body]; http_get must
+                     # return [status, body, headers]. Either may raise Error.
+                     http_post: Usage.method(:post),
+                     http_get: Agentify.method(:get))
         usage_read_key ||= api_key
         usage_write_key ||= api_key
+        # Unlike the usage keys, agentify has no construction-time
+        # requirement: the capability is optional, so a missing key surfaces
+        # as a typed error at call time instead of failing every create that
+        # never agentifies.
+        agentify_key ||= api_key
 
         if usage_read_key.nil? || usage_read_key.empty?
           raise Error.new("malformed_input", operation: "create",
@@ -63,15 +73,18 @@ module ZeroClick
 
         @usage_read_key = usage_read_key
         @usage_write_key = usage_write_key
+        @agentify_key = agentify_key
         @signing_secrets = signing_secrets&.to_h&.freeze
         @resolve_signing_secret = resolve_signing_secret
         @api_base_url = api_base_url
         @tolerance_seconds = tolerance_seconds
         @policy = allowance_unavailable_policy.to_s
         @timeout = check_timeout_seconds
+        @agentify_timeout = agentify_timeout_seconds
         @on_allowance_unavailable = on_allowance_unavailable
         @clock = clock
         @http_post = http_post
+        @http_get = http_get
         freeze
       end
 
@@ -133,6 +146,33 @@ module ZeroClick
         Allow.new(verification.context, "not_required")
       end
 
+      # Convert a public marketing page via GET /v1/agentify/markdown.
+      #
+      # Requires an API key with the agentify:convert scope (+agentify_key+,
+      # falling back to the both-scopes +api_key+). +seller+ is the seller
+      # whose storefront the document inlines (its public id); an organization
+      # with exactly one active seller never needs it. Returns an
+      # Agentify::MarkdownResult carrying the markdown plus the cache headers
+      # worth forwarding.
+      def fetch_agentify_markdown(url, seller: nil)
+        if @agentify_key.nil? || @agentify_key.empty?
+          raise Error.new("agentify_not_configured", operation: "fetch_agentify_markdown")
+        end
+
+        Agentify.validate_page_url!(url, operation: "fetch_agentify_markdown")
+        query = { "url" => url.to_s }
+        query["seller"] = seller unless seller.nil?
+        status, body, headers = @http_get.call(
+          base_url: @api_base_url,
+          path: Agentify::MARKDOWN_PATH,
+          query: query,
+          api_key: @agentify_key,
+          timeout: @agentify_timeout,
+          operation: "fetch_agentify_markdown"
+        )
+        Agentify.interpret_markdown(status, body, headers)
+      end
+
       def check_allowance(zc_request_id:, service_slug:, usage:)
         status, body = @http_post.call(
           base_url: @api_base_url,

data/lib/zeroclick/sellers/contracts.rb

@@ -9,6 +9,10 @@ module ZeroClick
     DEFAULT_API_BASE_URL = "https://api.zeroclick.io"
     DEFAULT_TOLERANCE_SECONDS = 300
     DEFAULT_CHECK_TIMEOUT_SECONDS = 1.5
+    # A cold conversion runs the full pipeline on the API side (page fetch,
+    # optional browser render, LLM cleanup), so agentify calls get a larger
+    # timeout default than the allowance check.
+    DEFAULT_AGENTIFY_TIMEOUT_SECONDS = 10.0
 
     # Reasons the allowance API gives for refusing. Any other reason on the wire
     # is treated as a malformed response rather than silently passed through.

data/lib/zeroclick/sellers/errors.rb

@@ -8,6 +8,8 @@ module ZeroClick
     # environment did (the ZeroClick API unreachable or answering nonsense).
     class Error < StandardError
       DEFAULT_MESSAGES = {
+        "agentify_not_configured" => "No API key covers agentify calls (set agentify_key, or an api_key " \
+                                     "with the agentify:convert scope)",
         "api_response_invalid" => "The ZeroClick API response is malformed",
         "api_status_error" => "The ZeroClick API returned an unsuccessful status",
         "api_transport_error" => "The ZeroClick API request failed",

data/lib/zeroclick/sellers/middleware/agentify.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../agentify"
+require_relative "../middleware"
+
+module ZeroClick
+  module Sellers
+    module Middleware
+      # Rack middleware that serves agent traffic agentified markdown and
+      # passes everyone else to the app untouched. Mount it in front of the
+      # marketing site, beside Meter/Identify:
+      #
+      #   use ZeroClick::Sellers::Middleware::Agentify, seller: SELLER
+      #
+      # The contract, shared by every ZeroClick seller SDK:
+      #
+      #   - only GET requests are considered; every other method passes
+      #     through;
+      #   - detection is Agentify.wants_agent_markdown? over the request's
+      #     Accept and User-Agent headers — markdown-preferring or AI-agent
+      #     traffic matches;
+      #   - a match short-circuits with 200 text/markdown, forwarding the
+      #     agentify response's cache-control and etag so the customer's CDN
+      #     caches it too;
+      #   - ANY agentify failure — missing key, network error, non-200,
+      #     timeout — falls through to the app. The middleware must never
+      #     break the customer's site; the worst case is an agent seeing HTML.
+      #
+      # Unlike Meter/Identify it never reads the request body — there is
+      # nothing to verify — so no buffering ceiling applies.
+      class Agentify
+        # +seller+ may be a client, a callable returning one, or omitted to
+        # resolve the process-wide ZeroClick::Sellers.seller on the first
+        # request (the Rails path — see Base#initialize for why).
+        #
+        # +seller_id+ is forwarded to the API's seller query param (its public
+        # id); needed only by multi-seller organizations. +resolve_url+ is a
+        # callable taking the Rack env and returning the public URL to
+        # convert, for servers behind a proxy that rewrites the scheme or host
+        # the runtime sees. +on_error+ observes the fail-open path; it is
+        # never re-raised.
+        def initialize(app, seller: nil, seller_id: nil, resolve_url: nil, on_error: nil)
+          @app = app
+          @seller_source = seller
+          @seller_id = seller_id
+          @resolve_url = resolve_url
+          @on_error = on_error
+        end
+
+        def call(env)
+          return @app.call(env) unless env["REQUEST_METHOD"] == "GET"
+
+          wanted = Sellers::Agentify.wants_agent_markdown?(
+            accept: env["HTTP_ACCEPT"], user_agent: env["HTTP_USER_AGENT"]
+          )
+          return @app.call(env) unless wanted
+
+          begin
+            url = @resolve_url ? @resolve_url.call(env) : Agentify.public_url(env)
+            result = seller.fetch_agentify_markdown(url, seller: @seller_id)
+          rescue StandardError => e
+            # Fail open — never break the site; the worst case is HTML.
+            @on_error&.call(e, env)
+            return @app.call(env)
+          end
+
+          headers = {
+            "content-type" => result.content_type || "text/markdown; charset=utf-8",
+            # The representation depends on both detection signals; without
+            # this a shared cache would hand the markdown to a browser.
+            "vary" => "accept, user-agent"
+          }
+          headers["cache-control"] = result.cache_control unless result.cache_control.nil?
+          headers["etag"] = result.etag unless result.etag.nil?
+          [200, headers, [result.markdown]]
+        end
+
+        # The URL the agent requested, as far as this process can see it.
+        def self.public_url(env)
+          scheme = env["rack.url_scheme"] || "http"
+          host = env["HTTP_HOST"]
+          if host.nil? || host.empty?
+            host = env["SERVER_NAME"].to_s
+            port = env["SERVER_PORT"]
+            default_port = scheme == "https" ? "443" : "80"
+            host = "#{host}:#{port}" if port && port != default_port
+          end
+          "#{scheme}://#{host}#{Middleware.path_and_query_from_env(env)}"
+        end
+
+        private
+
+        # Resolved once, on first use rather than at wire-up, exactly as
+        # Base#seller does — see that comment for the Rails ordering.
+        def seller
+          @seller ||= if @seller_source.nil?
+                        Sellers.seller
+                      elsif @seller_source.respond_to?(:call)
+                        @seller_source.call
+                      else
+                        @seller_source
+                      end
+        end
+      end
+    end
+  end
+end

data/lib/zeroclick/sellers/usage.rb

@@ -6,6 +6,7 @@ require "uri"
 
 require_relative "contracts"
 require_relative "errors"
+require_relative "version"
 
 module ZeroClick
   module Sellers
@@ -35,13 +36,18 @@ module ZeroClick
         OpenSSL::SSL::SSLError
       ].freeze
 
+      # SDK self-identification, most significant token first per RFC 9110:
+      # the gem release, then the Ruby runtime.
+      USER_AGENT = "zeroclick-sellers-ruby/#{VERSION} ruby/#{RUBY_VERSION}".freeze
+
       module_function
 
       def request_headers(api_key)
         {
           "accept" => "application/json",
           "authorization" => "Bearer #{api_key}",
-          "content-type" => "application/json"
+          "content-type" => "application/json",
+          "user-agent" => USER_AGENT
         }
       end
 

data/lib/zeroclick/sellers/version.rb

@@ -4,6 +4,6 @@ module ZeroClick
   module Sellers
     # Bump this to publish. The workflow reads it, asks RubyGems whether this
     # version already exists, and publishes only when it does not.
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

data/lib/zeroclick/sellers.rb

@@ -6,8 +6,10 @@ require_relative "sellers/contracts"
 require_relative "sellers/responses"
 require_relative "sellers/verify"
 require_relative "sellers/usage"
+require_relative "sellers/agentify"
 require_relative "sellers/client"
 require_relative "sellers/middleware"
+require_relative "sellers/middleware/agentify"
 
 # The ZeroClick billing guard for Ruby backends.
 #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zeroclick-sellers
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - ZeroClick
@@ -23,11 +23,13 @@ files:
 - LICENSE
 - README.md
 - lib/zeroclick/sellers.rb
+- lib/zeroclick/sellers/agentify.rb
 - lib/zeroclick/sellers/client.rb
 - lib/zeroclick/sellers/contracts.rb
 - lib/zeroclick/sellers/encryption.rb
 - lib/zeroclick/sellers/errors.rb
 - lib/zeroclick/sellers/middleware.rb
+- lib/zeroclick/sellers/middleware/agentify.rb
 - lib/zeroclick/sellers/railtie.rb
 - lib/zeroclick/sellers/responses.rb
 - lib/zeroclick/sellers/stateful.rb