zeroclick-sellers 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4d8cedea5994f6b40e5d7505027dfe9bf1fa9df5dfe32863070534bee183859
-  data.tar.gz: ff203775e81db08e529b7fe0908da260c3142b7e1a82783f9eaac4cf3624fdcd
+  metadata.gz: 27bd4f5d8f10f026b12a89ee8681fef45ffbf58129df180f40903a55ec9743d3
+  data.tar.gz: 1ea73b94f08215d28c2974ac4937bdc423aa2f52a66c688a5746656ad837c8f2
 SHA512:
-  metadata.gz: ccdf34f7bfccb29b898b0e71212b4573124c58b852417a883a812d24520a776710a73a1c46c2a5741e85bbad2760bc20dfd97047639a7e59e5623884937cc778
-  data.tar.gz: 0ddb34edef539de4e5cbdd1d78747e6424bf4f95db680fde8dbf1cb7db2492b350711ee83c93653ca0df7edf64e96ab57174587c22cf881c579e46f8c6e92c78
+  metadata.gz: 73ef4fc05515a9d11212ca90c7df1c9f97c157bdc2628c4b1bb81738849552fbd7aca334986fc60f1c4d0d5cb6ca311b7663c453c1633a756950e82af4f06b42
+  data.tar.gz: 00dbf768601b7808759518ad6a507e0d238f4c6c65aecdd91ce5106488841a19538f5ea49ea5df93e776a049330f32f834d7d9216dd0ce58b212bf6da24e1748

data/lib/zeroclick/sellers/agentify.rb

@@ -54,13 +54,19 @@ module ZeroClick
       # 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)
+        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
@@ -164,7 +170,8 @@ module ZeroClick
           markdown: body,
           cache_control: headers["cache-control"],
           content_type: headers["content-type"],
-          etag: headers["etag"]
+          etag: headers["etag"],
+          zcj_id: headers["x-zcj-id"]
         )
       end
 

data/lib/zeroclick/sellers/client.rb

@@ -3,6 +3,7 @@
 require_relative "agentify"
 require_relative "contracts"
 require_relative "errors"
+require_relative "page_views"
 require_relative "responses"
 require_relative "usage"
 require_relative "verify"
@@ -27,6 +28,7 @@ module ZeroClick
                      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,
@@ -34,6 +36,7 @@ module ZeroClick
                      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 transports, injectable so every decision this class
@@ -44,11 +47,12 @@ module ZeroClick
                      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.
+        # 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",
@@ -74,6 +78,7 @@ 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
@@ -81,6 +86,7 @@ module ZeroClick
         @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
@@ -173,6 +179,45 @@ module ZeroClick
         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, host: nil,
+                           eval_tag: nil, eval_signature: nil, eval_signature_input: nil,
+                           eval_signature_agent: nil, source: nil, source_signature: 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, host: host,
+          eval_tag: eval_tag, eval_signature: eval_signature,
+          eval_signature_input: eval_signature_input, eval_signature_agent: eval_signature_agent,
+          source: source, source_signature: source_signature
+        )
+        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

@@ -13,6 +13,9 @@ module ZeroClick
     # 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

@@ -14,6 +14,8 @@ module ZeroClick
         "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

@@ -72,6 +72,12 @@ module ZeroClick
           }
           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
 

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

@@ -0,0 +1,244 @@
+# 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;
+      #   - a ZeroClick agent-eval request's tag and signature are forwarded
+      #     with the page's host, so the API can keep ZeroClick's own eval
+      #     traffic out of the seller's numbers; a browser-based run, which
+      #     cannot sign, is told by the +src+ marker on its start URL,
+      #     forwarded with the host and the signature beside it;
+      #   - 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) }
+
+        # ZeroClick's own start marker: the one query value the middleware
+        # forwards. A browser-based eval run's requests leave from the agent
+        # vendor's cloud, out of reach of the signed tag, so agent-eval marks
+        # its start URL as ?src=ze-<experiment>-<n> instead, and the API keeps
+        # the whole visit out of the seller's numbers from it.
+        EVAL_SOURCE_PREFIX = "ze-"
+
+        # +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; its path is reported and, with an eval
+        # tag, its host. +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)
+          uri = URI.parse(url.to_s)
+          path = uri.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),
+            **start_marker_of(uri),
+            **eval_run_of(env, uri)
+          )
+        end
+
+        # ZeroClick's own agent-eval run, when the visitor carried its tag: the
+        # tag, the signature agent-eval puts on a seller's site (under
+        # ZeroClick-only header names, never Web Bot Auth's) and the public
+        # host it was signed for. Forwarded as sent; the API labels the view
+        # only when the signature verifies, so a forged tag labels nothing. A
+        # value outside what the beacon accepts (empty, or longer than
+        # agent-eval ever sends) is left out rather than sent, so a visitor's
+        # odd header can never cost the page view itself.
+        def eval_run_of(env, uri)
+          tag = capped(env["HTTP_X_ZEROCLICK_EVAL"], 512)
+          return {} if tag.nil?
+
+          {
+            host: capped(host_of(uri), 300),
+            eval_tag: tag,
+            eval_signature: capped(env["HTTP_X_ZEROCLICK_EVAL_SIGNATURE"], 1_024),
+            eval_signature_input: capped(env["HTTP_X_ZEROCLICK_EVAL_SIGNATURE_INPUT"], 1_024),
+            eval_signature_agent: capped(env["HTTP_X_ZEROCLICK_EVAL_SIGNATURE_AGENT"], 512)
+          }
+        end
+
+        def capped(value, max)
+          value && !value.empty? && value.length <= max ? value : nil
+        end
+
+        # The public host the page was requested on, as the JS SDK's URL.host
+        # reads it: the host and any non-default port.
+        def host_of(uri)
+          return nil if uri.host.nil? || uri.host.empty?
+
+          uri.port && uri.port != uri.default_port ? "#{uri.host}:#{uri.port}" : uri.host
+        end
+
+        # ZeroClick's own start marker, keyed like report_page_view: empty
+        # without one. The +src+ query value when it is ours, the page's host
+        # and the +signature+ agent-eval puts beside the marker, as sent: the
+        # only query values the beacon carries. Any other +src+ stays on the
+        # site, and a marker or signature past what the beacon accepts (or a
+        # query that does not decode) is left out rather than sent.
+        def start_marker_of(uri)
+          return {} if uri.query.nil? || uri.query.empty?
+
+          values = URI.decode_www_form(uri.query)
+          src = values.assoc("src")&.last
+          return {} unless src&.start_with?(EVAL_SOURCE_PREFIX) && src.length <= 32
+
+          {
+            host: capped(host_of(uri), 300),
+            source: src,
+            source_signature: capped(values.assoc("signature")&.last, 256)
+          }
+        rescue ArgumentError
+          {}
+        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
+          uri && host_of(uri)
+        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,80 @@
+# 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.
+      # +host+ and the +eval_*+ values describe ZeroClick's own agent-eval run
+      # when the visitor carried its tag: the public host the run signed for
+      # and the tag with its signature, as sent. The API labels the view as
+      # eval traffic only when the signature verifies.
+      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, host: nil,
+                        eval_tag: nil, eval_signature: nil, eval_signature_input: nil,
+                        eval_signature_agent: nil, source: nil, source_signature: 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["host"] = host unless host.nil?
+        payload["evalTag"] = eval_tag unless eval_tag.nil?
+        payload["evalSignature"] = eval_signature unless eval_signature.nil?
+        payload["evalSignatureInput"] = eval_signature_input unless eval_signature_input.nil?
+        payload["evalSignatureAgent"] = eval_signature_agent unless eval_signature_agent.nil?
+        payload["source"] = source unless source.nil?
+        payload["sourceSignature"] = source_signature unless source_signature.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.5.0"
+    VERSION = "0.7.0"
   end
 end

data/lib/zeroclick/sellers.rb

@@ -7,9 +7,11 @@ 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.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - ZeroClick
@@ -30,6 +30,8 @@ files:
 - 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