zeroclick-sellers 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 516aac7120c0e979c3d70f57051151667cd4a3e5945ecca29e3202af78ef04df
-  data.tar.gz: 65f2ed28d951f1b9108f03c8dd64cead2ee3cf96ed8f4580b710d3d33ad3802e
+  metadata.gz: 6127c1b9413ac6cbf8d9690e972e319418e2bee6ba3a025ba057c6752d04a370
+  data.tar.gz: 384bfdd1ba3393497943aa9c37138f0b9fae69098a2404b3dfd6b2e51f61493b
 SHA512:
-  metadata.gz: e07f7f2cc9135b43b93f27babfe4109003ac388503d10f13085378b472c6837ae144542afe66b3c1a725199f96554cf2c73da7fe6a45d95dad76fac9b22a4bd3
-  data.tar.gz: ce8aa5c0cab3f67cfec797a1b05da45b581e3c77c96c685ced835e95e411c2585c934dd85215d97cc096b50e76e5399d18ca85e8bc80d2a04186af1e4c6a5b34
+  metadata.gz: 446af6c8cb1563130c222f09ec8ee8eeb4308636782925acd269d7353a1ed3cbc52f7aa8ac033fb0a1eb6bb4fe268b2d5178a5b483e7e7cf9348c18ea291a99d
+  data.tar.gz: 40f965870f70c61902865c586d930c39f4c1165a943244dfc6647d05abdbc93bb2faf65f184188cc80e03e45a860b5c410c5db8d2c97f48545206a5a663657cc

data/lib/zeroclick/sellers/agentify.rb

@@ -0,0 +1,208 @@
+# 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, :zcj_id
+
+        # +zcj_id+ is the journey id the conversion minted (x-zcj-id), or nil
+        # when the chain is off for this seller. Forwarded onto the agent's
+        # response so a wrapping page-view beacon can stitch this marketing
+        # view to the same journey as the storefront visit and purchase the
+        # agent reaches through the inlined links.
+        def initialize(markdown:, cache_control: nil, content_type: nil, etag: nil, zcj_id: nil)
+          @markdown = markdown
+          @cache_control = cache_control
+          @content_type = content_type
+          @etag = etag
+          @zcj_id = zcj_id
+          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"],
+          zcj_id: headers["x-zcj-id"]
+        )
+      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,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "agentify"
 require_relative "contracts"
 require_relative "errors"
+require_relative "page_views"
 require_relative "responses"
 require_relative "usage"
 require_relative "verify"
@@ -25,20 +27,32 @@ module ZeroClick
       def initialize(api_key: nil,
                      usage_read_key: nil,
                      usage_write_key: nil,
+                     agentify_key: nil,
+                     page_views_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,
+                     page_view_timeout_seconds: DEFAULT_PAGE_VIEW_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 and page views have no
+        # construction-time requirement: each capability is optional, so a
+        # missing key surfaces as a typed error at call time instead of failing
+        # every create that never uses it.
+        agentify_key ||= api_key
+        page_views_key ||= api_key
 
         if usage_read_key.nil? || usage_read_key.empty?
           raise Error.new("malformed_input", operation: "create",
@@ -63,15 +77,20 @@ module ZeroClick
 
         @usage_read_key = usage_read_key
         @usage_write_key = usage_write_key
+        @agentify_key = agentify_key
+        @page_views_key = page_views_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
+        @page_view_timeout = page_view_timeout_seconds
         @on_allowance_unavailable = on_allowance_unavailable
         @clock = clock
         @http_post = http_post
+        @http_get = http_get
         freeze
       end
 
@@ -133,6 +152,67 @@ 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
+
+      # Report one marketing-site page view to POST /v1/page-views.
+      #
+      # Requires an API key with the page-views:write scope (+page_views_key+,
+      # falling back to the both-scopes +api_key+). Fire-and-forget by design:
+      # the API answers 204 without waiting for warehouse delivery. Raises a
+      # typed Error on transport failure or a non-2xx status so a direct caller
+      # can observe problems; the Middleware::PageViews wrapper swallows those
+      # so a beacon failure never affects the page being observed.
+      #
+      # +seller+ is the seller's public id; +path+ must be an absolute path.
+      def report_page_view(seller:, path:, status: nil, duration_ms: nil, representation: nil,
+                           journey_id: nil, captured_at: nil, user_agent: nil, accept: nil,
+                           client_ip: nil, country: nil, referrer_host: nil)
+        if @page_views_key.nil? || @page_views_key.empty?
+          raise Error.new("page_views_not_configured", operation: "report_page_view")
+        end
+
+        payload = PageViews.build_payload(
+          seller: seller, path: path, status: status, duration_ms: duration_ms,
+          representation: representation, journey_id: journey_id, captured_at: captured_at,
+          user_agent: user_agent, accept: accept, client_ip: client_ip,
+          country: country, referrer_host: referrer_host
+        )
+        status_code, body = @http_post.call(
+          base_url: @api_base_url,
+          path: PageViews::REPORT_PATH,
+          api_key: @page_views_key,
+          payload: payload,
+          timeout: @page_view_timeout,
+          operation: "report_page_view"
+        )
+        PageViews.interpret_report(status_code, body)
+      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,13 @@ 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
+    # The page-view beacon is a cheap fire-and-forget 204; its default timeout
+    # is short so a slow ingress never delays the page it is observing.
+    DEFAULT_PAGE_VIEW_TIMEOUT_SECONDS = 2.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,10 +8,14 @@ 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",
         "malformed_input" => "The SDK input is malformed",
+        "page_views_not_configured" => "No API key covers page-view calls (set page_views_key, or an api_key " \
+                                       "with the page-views:write scope)",
         "signing_secret_resolution_failed" => "The signing secret could not be resolved"
       }.freeze
 

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

@@ -0,0 +1,113 @@
+# 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?
+          unless result.zcj_id.nil?
+            # Re-expose the journey id on the agent's response so a wrapping
+            # page-view beacon can stamp this view onto the same journey.
+            headers["x-zcj-id"] = result.zcj_id
+            headers["access-control-expose-headers"] = "x-zcj-id"
+          end
+          [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/middleware/page_views.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "time"
+require "uri"
+
+require_relative "../middleware"
+require_relative "agentify"
+
+module ZeroClick
+  module Sellers
+    module Middleware
+      # Rack middleware that emits a fire-and-forget page-view beacon for every
+      # page-content request, without changing the response. Mount it in front
+      # of the marketing site:
+      #
+      #   use ZeroClick::Sellers::Middleware::PageViews, seller: SELLER, seller_id: "sel_public"
+      #
+      # The contract, shared by every ZeroClick seller SDK:
+      #
+      #   - only GET requests to non-asset paths are reported (an asset is a
+      #     final path segment ending in an extension — .css, .ico, .png);
+      #   - the app runs FIRST, so the beacon carries the real status and
+      #     duration; the visitor's user-agent, accept, and connecting IP are
+      #     forwarded for server-side classification;
+      #   - ANY beacon failure — missing key, network error, non-204, timeout,
+      #     a bad resolve_url or clock — is handed to +on_error+ and swallowed.
+      #     The middleware must never break or alter the customer's site.
+      #
+      # Compose it as the OUTER middleware around Agentify — mount PageViews
+      # before Agentify — so the agent-markdown variant's re-exposed x-zcj-id is
+      # visible on the response and stitches the view onto the same journey.
+      #
+      # Like Agentify it never reads the request body, so no buffering ceiling
+      # applies.
+      class PageViews
+        # A page-content request has no asset extension on its final path
+        # segment. This skips /_astro/app.css, /favicon.ico, /logo.png and the
+        # like while still reporting /pricing, /blog/post, and / for both
+        # browsers and agents.
+        ASSET_PATH = /\.[a-z0-9]+$/i
+
+        # Wall clock in epoch milliseconds, for the observation time and the
+        # duration. Injectable so a test can make both deterministic.
+        DEFAULT_CLOCK = -> { Process.clock_gettime(Process::CLOCK_REALTIME, :float_millisecond) }
+
+        # +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 the seller's public id, sent in every beacon (required
+        # by the wire contract). +clock+ returns epoch milliseconds.
+        # +resolve_url+ is a callable taking the Rack env and returning the
+        # public URL of the request, for servers behind a proxy that rewrites
+        # the host the runtime sees. +on_error+ observes the fire-and-forget
+        # path; it is never re-raised.
+        def initialize(app, seller_id:, seller: nil, clock: nil, resolve_url: nil, on_error: nil)
+          @app = app
+          @seller_source = seller
+          @seller_id = seller_id
+          @clock = clock || DEFAULT_CLOCK
+          @resolve_url = resolve_url
+          @on_error = on_error
+        end
+
+        def call(env)
+          started_at = @clock.call
+          status, headers, body = @app.call(env)
+
+          # The whole observation path is wrapped: a bad resolve_url, an
+          # unparseable URL, a misbehaving clock, or the beacon delivery itself
+          # must never break the page. Every failure — synchronous or from the
+          # blocking beacon — is routed to on_error, and the app's response is
+          # returned untouched regardless.
+          begin
+            observe(env, started_at: started_at, status: status, headers: headers)
+          rescue StandardError => e
+            @on_error&.call(e, env)
+          end
+
+          [status, headers, body]
+        end
+
+        private
+
+        def observe(env, started_at:, status:, headers:)
+          return unless env["REQUEST_METHOD"] == "GET"
+
+          url = @resolve_url ? @resolve_url.call(env) : Agentify.public_url(env)
+          path = URI.parse(url.to_s).path
+          path = "/" if path.nil? || path.empty?
+          return if ASSET_PATH.match?(path)
+
+          seller.report_page_view(
+            seller: @seller_id,
+            path: path,
+            status: status.to_i,
+            duration_ms: [0, (@clock.call - started_at).round].max,
+            representation: representation_of(headers),
+            captured_at: Time.at(started_at / 1000.0).utc.iso8601(3),
+            user_agent: env["HTTP_USER_AGENT"],
+            accept: env["HTTP_ACCEPT"],
+            client_ip: client_ip_of(env),
+            country: env["HTTP_CF_IPCOUNTRY"],
+            referrer_host: referrer_host_of(env),
+            journey_id: journey_id_of(headers)
+          )
+        end
+
+        # What the app served for this page-content request, read off the
+        # response content-type so it reflects the real representation
+        # regardless of what produced it.
+        def representation_of(headers)
+          header_value(headers, "content-type").to_s.include?("markdown") ? "markdown" : "html"
+        end
+
+        # The journey id an upstream Agentify conversion minted for this same
+        # request, re-exposed by Middleware::Agentify. Present only for the
+        # agent-markdown variant; omitted otherwise.
+        def journey_id_of(headers)
+          header_value(headers, "x-zcj-id")
+        end
+
+        # The forwarded client IP, from the edge's connecting-IP headers. The
+        # API turns it into the viewer id and never stores it raw; nil when the
+        # runtime exposes no client address.
+        def client_ip_of(env)
+          direct = env["HTTP_CF_CONNECTING_IP"] || env["HTTP_X_REAL_IP"]
+          return direct.strip if direct && !direct.strip.empty?
+
+          forwarded = env["HTTP_X_FORWARDED_FOR"]
+          return nil if forwarded.nil?
+
+          first = forwarded.split(",").first.to_s.strip
+          first.empty? ? nil : first
+        end
+
+        # The referrer reduced to its host at the edge, so the full referrer
+        # (its path and query, which can carry identifying values) never leaves
+        # the site. A malformed referrer yields no host rather than the full URL.
+        def referrer_host_of(env)
+          referer = env["HTTP_REFERER"]
+          return nil if referer.nil? || referer.empty?
+
+          uri = begin
+            URI.parse(referer)
+          rescue URI::InvalidURIError
+            nil
+          end
+          host = uri&.host
+          return nil if host.nil? || host.empty?
+
+          # Host and any non-default port only, matching the JS SDK's URL.host.
+          uri.port && uri.port != uri.default_port ? "#{host}:#{uri.port}" : host
+        end
+
+        # Case-insensitive lookup over the app's response headers.
+        def header_value(headers, name)
+          target = name.downcase
+          headers.each { |key, value| return value if key.to_s.downcase == target }
+          nil
+        end
+
+        # 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/page_views.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "contracts"
+require_relative "errors"
+
+module ZeroClick
+  module Sellers
+    # POST /v1/page-views: one fire-and-forget marketing page-view beacon.
+    #
+    # As in Usage and Agentify, building the payload and interpreting the
+    # response are separate from transport, so what a response MEANS is decided
+    # in one pure place. Unlike the usage endpoints the API answers 204 with no
+    # body, so the success path parses nothing — see #interpret_report.
+    #
+    # The visitor's user-agent/accept/IP are forwarded so the API can classify
+    # the viewer and derive the shared viewer id; they are consumed there and
+    # never stored raw. Only the path is ever sent, never the query.
+    module PageViews
+      REPORT_PATH = "/v1/page-views"
+
+      # What the site actually served for a page-content request: the agent
+      # markdown variant, or the normal HTML.
+      REPRESENTATIONS = %w[html markdown].freeze
+
+      module_function
+
+      # Build the wire body: camelCase string keys, every absent optional key
+      # omitted. +seller+ is the seller's public id and +path+ must be an
+      # absolute path, both rejected before any request leaves the process.
+      def build_payload(seller:, path:, status: nil, duration_ms: nil, representation: nil,
+                        journey_id: nil, captured_at: nil, user_agent: nil, accept: nil,
+                        client_ip: nil, country: nil, referrer_host: nil)
+        Sellers.require_slug!(seller, "seller", "report_page_view")
+        unless path.is_a?(String) && path.start_with?("/")
+          raise Error.new("malformed_input", operation: "report_page_view",
+                                             message: "path must be a string beginning with \"/\"")
+        end
+        if !representation.nil? && !REPRESENTATIONS.include?(representation)
+          raise Error.new("malformed_input", operation: "report_page_view",
+                                             message: "representation must be \"html\" or \"markdown\"")
+        end
+
+        payload = { "seller" => seller, "path" => path }
+        payload["status"] = status unless status.nil?
+        payload["durationMs"] = duration_ms unless duration_ms.nil?
+        payload["representation"] = representation unless representation.nil?
+        payload["journeyId"] = journey_id unless journey_id.nil?
+        payload["capturedAt"] = captured_at unless captured_at.nil?
+        payload["userAgent"] = user_agent unless user_agent.nil?
+        payload["accept"] = accept unless accept.nil?
+        payload["clientIp"] = client_ip unless client_ip.nil?
+        payload["country"] = country unless country.nil?
+        payload["referrerHost"] = referrer_host unless referrer_host.nil?
+        payload
+      end
+
+      # A 204 carries no body, so there is nothing to parse; a non-2xx is the
+      # only failure a well-formed beacon can hit here. Distinct from
+      # Usage.interpret_report, which requires a JSON body.
+      def interpret_report(status, _body)
+        return if (200..299).cover?(status)
+
+        raise Error.new("api_status_error", operation: "report_page_view", status: status)
+      end
+    end
+  end
+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.1"
+    VERSION = "0.6.0"
   end
 end

data/lib/zeroclick/sellers.rb

@@ -6,8 +6,12 @@ require_relative "sellers/contracts"
 require_relative "sellers/responses"
 require_relative "sellers/verify"
 require_relative "sellers/usage"
+require_relative "sellers/agentify"
+require_relative "sellers/page_views"
 require_relative "sellers/client"
 require_relative "sellers/middleware"
+require_relative "sellers/middleware/agentify"
+require_relative "sellers/middleware/page_views"
 
 # 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.1
+  version: 0.6.0
 platform: ruby
 authors:
 - ZeroClick
@@ -23,11 +23,15 @@ 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/middleware/page_views.rb
+- lib/zeroclick/sellers/page_views.rb
 - lib/zeroclick/sellers/railtie.rb
 - lib/zeroclick/sellers/responses.rb
 - lib/zeroclick/sellers/stateful.rb