Page views SDK middleware

Every seller SDK ships Page views middleware for its language’s dominant boundary: a fetch-handler wrapper in TypeScript, ASGI and WSGI adapters in Python, net/http middleware in Go, and Rack middleware in Ruby. Mount it around the handler that serves your marketing site, and each page load is reported to Page views in the background. Agents, crawlers, and people all get your site exactly as before. All four implement one contract:

Only GET requests to non-asset paths are reported; assets and every other method pass through unobserved.
The handler runs first, so the beacon carries the real response status and the request duration. The visitor’s User-Agent, Accept, and connecting IP are forwarded for server-side classification.
It records the response’s representation (html or markdown, read from the response’s content-type) and, when Agentify attached one, the journey id that stitches this view to the agentified read. Both are captured automatically; you set nothing.
The beacon is fire-and-forget and fails open. A missing key, a network error, a non-204, a timeout, or a malformed report is handed to onError and swallowed. The middleware never delays or breaks the page.

Only the request’s path is reported, never its query string, so tracking parameters never reach ZeroClick.

Configure the key

Reporting uses a zc_ key with the page-views:write scope. TypeScript is standalone: the key rides inline on the middleware as apiKey, with no createSeller and no signing secrets. The other three SDKs read it from a page_views_key / PageViewsKey field on the client you already build for the guard; when that field is unset, they fall back to the combined API key.

import { withPageViews } from "@zeroclickai/sellers";

// Standalone: no createSeller, no signing secrets. The key rides inline
// on the middleware. See "Mount the middleware" below.
const handler = withPageViews(renderPage, {
  seller: process.env.ZEROCLICK_SELLER_ID!,
  apiKey: process.env.ZEROCLICK_PAGE_VIEWS_KEY!,
});

# Set page_views_key on the client (create_seller or create_async_seller);
# the middleware reads it from there.
zeroclick = create_async_seller(
    api_key=os.environ["ZEROCLICK_API_KEY"],
    page_views_key=os.environ["ZEROCLICK_PAGE_VIEWS_KEY"],
)

seller, err := sellers.New(sellers.Config{
	APIKey:       os.Getenv("ZEROCLICK_API_KEY"),
	PageViewsKey: os.Getenv("ZEROCLICK_PAGE_VIEWS_KEY"),
})

config.zeroclick.api_key = ENV.fetch("ZEROCLICK_API_KEY")
config.zeroclick.page_views_key = ENV.fetch("ZEROCLICK_PAGE_VIEWS_KEY")

Delivery is fire-and-forget on a short timeout: Go’s PageViewsTimeout defaults to DefaultPageViewTimeout (2 seconds), and the other SDKs use an equally short page-view default (timeoutMs in TypeScript, page_view_timeout_seconds in Ruby), long enough to send the beacon, short enough never to sit on a page.

Mount the middleware

import { withPageViews } from "@zeroclickai/sellers";

// Wrap the fetch handler that serves your site. Works anywhere the SDK
// works: Node.js servers, Hono, Next.js route handlers, edge runtimes.
const handler = withPageViews(renderPage, {
  seller: process.env.ZEROCLICK_SELLER_ID!,
  apiKey: process.env.ZEROCLICK_PAGE_VIEWS_KEY!,
});

export default { fetch: handler };

# ASGI (Starlette, FastAPI). Pass the async client and your seller id:
from zeroclick_sellers.adapters import PageViewsAsgiMiddleware

app.add_middleware(PageViewsAsgiMiddleware, seller=zeroclick, seller_id="sel_x")

# WSGI (Flask, Django). Pass the blocking client from create_seller:
from zeroclick_sellers.adapters import PageViewsWsgiMiddleware

app.wsgi_app = PageViewsWsgiMiddleware(app.wsgi_app, zeroclick, "sel_x")

// A plain func(http.Handler) http.Handler, like Meter and Agentify: it
// composes with net/http, chi, gorilla/mux, and gin's WrapH.
mux.Handle("/", seller.PageViews(sellers.PageViewsOptions{})(site))

# Rails: mount it in config/application.rb. Omit `seller:` and the
# middleware resolves the process-wide client on the first request.
config.middleware.use ZeroClick::Sellers::Middleware::PageViews, seller_id: "sel_x"

# Outside Rails, pass the client explicitly:
use ZeroClick::Sellers::Middleware::PageViews, seller: SELLER, seller_id: "sel_x"

Mount it in front of the pages people and agents read (your marketing routes), not in front of your billed API, which already reports usage through the guard. If your marketing site runs as its own process, configure a client there the same way; Page views only ever needs the seller id and the page-views:write key.

Combining with Agentify

Page views and Agentify are independent opt-ins: run either alone or both. When you run both, Page views must be the outer middleware, wrapping Agentify, and this ordering is load-bearing, not cosmetic.

It is the only way Page views sees agent traffic at all. The Agentify middleware short-circuits agent requests: on a match it returns markdown and never calls the inner handler. A Page views beacon mounted inside Agentify would therefore never fire for those requests, silently dropping exactly the agent page views you most want to measure. Only the outer layer observes them.
It stitches the journey. Being outside is also how the page view picks up the journey id Agentify attaches to its response, tying the marketing view to the agentified read on one journey.

Wrap Agentify with Page views in each language’s idiom:

// withPageViews on the outside, wrapping withAgentify.
const handler = withPageViews(withAgentify(zeroClick, renderPage), {
  seller: process.env.ZEROCLICK_SELLER_ID!,
  apiKey: process.env.ZEROCLICK_PAGE_VIEWS_KEY!,
});

export default { fetch: handler };

# WSGI: the LAST wrap is the outermost, so apply Agentify first and
# Page views second. Page views ends up outside Agentify.
app.wsgi_app = AgentifyWsgiMiddleware(app.wsgi_app, seller=zeroclick)
app.wsgi_app = PageViewsWsgiMiddleware(app.wsgi_app, zeroclick, "sel_x")

# ASGI: add Agentify first and Page views last, so Page views is outermost.

// PageViews wraps Agentify wraps your site.
mux.Handle("/", seller.PageViews(sellers.PageViewsOptions{})(
	seller.Agentify(sellers.AgentifyOptions{})(site)))

# In Rack the FIRST `use` is the OUTERMOST layer, so mount Page views
# before Agentify to keep Page views on the outside.
use ZeroClick::Sellers::Middleware::PageViews, seller_id: "sel_x"
use ZeroClick::Sellers::Middleware::Agentify

The direction differs by framework because the composition primitives do. TypeScript and Go nest explicitly, so the outer call is Page views. Python’s WSGI wrapping and Rack’s use build a stack instead: in WSGI the last wrap is outermost, so Page views is applied second; in Rack the first use is outermost, so Page views is mounted first. In every case the result is the same: Page views sits on the outside of Agentify.

Options

Each middleware takes the same options, named in its language’s idiom:

Option	TypeScript	Python	Go	Ruby
The seller whose site this is (`sel_…`); required	`seller`	`seller_id`	`Seller`	`seller_id`
Override the public URL whose path is reported	`resolveUrl`	`resolve_url`	`ResolveURL`	`resolve_url`
Observe the fail-open path; never re-raised	`onError`	`on_error`	`OnError`	`on_error`

The key itself is not an option here: TypeScript passes apiKey inline on the middleware, while Python, Go, and Ruby configure it once on the client as page_views_key / PageViewsKey. Behind a proxy that rewrites the scheme or host, set the URL override so the reported path comes from the public URL rather than the one your process sees: only the path is ever reported.

Report without the middleware

Any language or framework can report by calling the REST endpoint directly, once per page-content GET. Each SDK also exposes a one-shot reporter for when the middleware boundary does not fit (a background job, a custom router, a hand-rolled handler):

SDK	Reporter
TypeScript	`reportPageView(input, { apiKey })`
Python	`client.report_page_view(ReportPageViewInput(...))` (`await` it on the async client)
Go	`seller.ReportPageView(ctx, sellers.ReportPageViewInput{...})`
Ruby	`client.report_page_view(seller:, path:, ...)`

A direct reporter carries the same body the middleware sends, and can set representation and the journey id explicitly rather than deriving them from a response it never saw.

Failing open, observably

The middleware exists to add a measurement, never an outage or a delay: any error on the reporting path leaves the response untouched. That silence is deliberate, and it means a misconfigured key looks exactly like a working page, so wire the error hook to your logger:

const handler = withPageViews(renderPage, {
  seller: process.env.ZEROCLICK_SELLER_ID!,
  apiKey: process.env.ZEROCLICK_PAGE_VIEWS_KEY!,
  onError: (error, request) =>
    logger.warn({ error, url: request.url }, "page-view beacon failed"),
});

In Go, a nil OnError falls back to the client’s configured Logger.

Next steps

REST endpoint

The underlying request: body, response, and errors.

Overview

What is captured, how viewers are classified, and the key scope.

Get started

Concepts

Integrate your API

Your agent storefront

Agentify

Page views

Resources

Page views SDK middleware

Configure the key

Mount the middleware

Combining with Agentify

Options

Report without the middleware

Failing open, observably

Next steps

REST endpoint

Overview

​Configure the key

​Mount the middleware

​Combining with Agentify

​Options

​Report without the middleware

​Failing open, observably

​Next steps

REST endpoint

Overview

Configure the key

Mount the middleware

Combining with Agentify

Options

Report without the middleware

Failing open, observably

Next steps