Reference

Server API

@parlox/server: the adapters, createParlox, purchase, ucp, flush, and every option.

@parlox/server 1.2.0. No runtime dependencies; Node 20 and later, edge runtimes, Cloudflare Workers, Deno and Bun. ES modules and CommonJS, with type declarations for each. Nothing in it throws into your code.

Adapters

ImportForUse
@parlox/server/nextNext.js middleware (middleware.ts, or proxy.ts in Next.js 16)export default withParlox(middleware?, options?)
@parlox/server/expressExpress and any Connect-style serverapp.use(parlox(options?))
@parlox/server/honoHono on Node, Bun, Cloudflare Workers and Pages, Vercel, AWS Lambdaapp.use(parlox(options?))
@parlox/server/vercelVercel Routing Middleware, for a static siteexport default withParlox({ next, ...options }) or withParlox(existing, { next, ...options })
@parlox/server/fetchRemix, SvelteKit, Astro, Deno and other Web-standard serversconst parlox = parloxFetch(options?)
@parlox/serverOrders, UCP reports, and anything elsecreateParlox(options?), flush()

Each adapter answers GET /.well-known/parlox-verify with PARLOX_VERIFY_TOKEN, lets the request through, and reports it in the background if it looks automated, never delaying the response. The Next.js and Vercel middleware report as the request arrives, before your page answers, so their reports carry no status. A wrapped middleware's result is returned unchanged.

  • withParlox(middleware) never skips the middleware it wraps: it keeps guarding every route it guarded. runWrapped(pathname) narrows where it runs.
  • parlox.flush(): the Express and Hono adapters' parlox function itself (the one you import, not the middleware it returns) has a flush method for shutdown: await parlox.flush().
  • parloxFetch() returns handle(request) (the ownership check's Response, or null to continue), observe(request, status, waitUntil?), purchase, ucp and flush.
  • Every adapter also takes clientIp(request), your own source of the client address, which overrides ipHeader.

createParlox

TypeScript
import { createParlox } from "@parlox/server";

const orders = createParlox({ secretKey: process.env.PARLOX_ORDERS_KEY, onError: (e) => console.error(e) });

Returns an instance with purchase(), ucp() and flush() among its methods. An instance with no key does nothing.

purchase

TypeScript
purchase(order: {
  sid?: string | null;    // the browser's sessionId(), stored on the order
  order_id: string;
  value_cents: number;    // the total in the smallest currency unit
  currency: string;       // ISO 4217, "USD"
  items?: number;
}): Promise<{ ok: boolean; status: number }>;

Posts a confirmed order at once, in a request of its own, never batched. Never rejects. It checks the order first: if order_id is not a non-empty string, value_cents is not a whole number of 0 or more, or currency is not three capital letters, nothing is sent, the promise resolves { ok: false, status: 0 } and onError says which field. An unreadable sid is left out, and the order is still sent. Needs a send key: a "Crawler reports only" key gets 403, and onError gets Parlox's reason. At most 10 are posted at the same time in the process (maxPurchasesInFlight); beyond that it resolves { ok: false, status: 0 } at once. Guide: Purchases from the server.

ucp

TypeScript
ucp(report: UcpReport, context?: UcpContext): Promise<{ ok: boolean; status: number }>;

For a store that runs its own UCP server (the Universal Commerce Protocol, through which agent platforms search a catalog and check out without loading a page): report each call it answers, after it has answered. op is required: discovery, catalog_search, catalog_lookup, catalog_product, checkout_create, checkout_get, checkout_update, checkout_complete, checkout_cancel, order_get, order_update, handoff_opened, handoff_linked or handoff_completed. The rest of the report is what your server answered, each field optional: http_status, ms, checkout_id, order_id, checkout_status, codes, total_cents, items, item_ids, discount_codes, fulfillment, query, results, platform. The optional context is about the caller: ua (its user agent), ip (checked against published ranges and discarded; pass it only for an agent platform's server), ip_hash and sid (the browser's sessionId(), for handoff_linked).

TypeScript
const parlox = createParlox({ secretKey: process.env.PARLOX_ORDERS_KEY });

// After your UCP server has answered POST /checkout-sessions:
await parlox.ucp(
  { op: "checkout_create", http_status: 201, ms: Date.now() - started, checkout_id: checkout.id, checkout_status: checkout.status, total_cents: 12998, items: 2, platform: "agent.example.com" },
  { ua: request.headers.get("user-agent") },
);
  • Like orders, UCP reports need a send key, and each is posted in a request of its own (at most 10 at a time, maxUcpReportsInFlight, apart from the orders' 10).
  • Each value is checked before it is sent the way Parlox checks it, and one Parlox would not keep is left out. Fields ucp() does not know are not sent.
  • In the search query, emails and runs of four or more digits are replaced with [email] and [number], and it is cut to 200 characters. Nothing else in it is changed, so pass what the agent searched for, never buyer data.
  • Never sent: buyer names, emails, phone numbers, addresses, payment instruments or tokens. ucp() has no field for them.

Every field and its bounds: the package README.

flush

TypeScript
import { flush } from "@parlox/server";

await flush(); // or flush(ms)

Sends the reports queued so far by every instance in the process, keeping the process running until they are sent, for at most 30 seconds by default. Never rejects. For apps that stop on a signal: Shutdown.

Options

Every adapter and createParlox take these.

OptionDefault
secretKeyPARLOX_SECRET_KEY (Hono: c.env first)Read from the environment only when the option is not given. A secretKey that is passed but unset or empty is used as it is: nothing is sent, and the log says so once
verifyTokenPARLOX_VERIFY_TOKEN (Hono: c.env first)The answer to the ownership check
ipHeaderPARLOX_IP_HEADER, else x-real-ip on Vercel, else (Hono and fetch) cf-connecting-ip for a request Cloudflare delivered, else noneThe header that carries the client address. null turns it off
timeoutMs2000For reports sent on their own, and purchases
flushAt20Long-running servers: send a batch once this many reports wait
flushIntervalMs10000And at least this often
maxBatchSize100Reports per request; 100 is also the most the gateway accepts
maxBatchBytes200000Bytes per request, at most
maxQueueSize1000When full, the oldest report is dropped and counted
batchTimeoutMs10000For a batch request
retryCount3Further attempts for a batch Parlox provably did not store; 0 turns retries off
retryDelayMs3000Between those attempts, when Parlox names no Retry-After
maxPurchasesInFlight10For the whole process
maxUcpReportsInFlight10For the whole process, apart from purchases
includeApifalseReport GET requests under /api/ too
runWrapped(pathname)every requestNext.js only: which requests the wrapped middleware runs for
onError(err)ignoredCalled with every reporting failure. A key Parlox refuses (401, 403) is also written to the log, once per instance for each of crawler reports, orders and UCP reports

Environment variables

Variable
PARLOX_SECRET_KEYThe "Crawler reports only" key the middleware sends with
PARLOX_VERIFY_TOKENOptional: the site's verification token
PARLOX_IP_HEADEROptional: the header your own proxy sets with the client address (x-real-ip behind nginx, cf-connecting-ip behind Cloudflare)
PARLOX_ORDERS_KEYA name for the send key that orders and UCP reports use. The package reads it only where you pass it as secretKey

On Deno, variables are read only with --allow-env (for all of them, or naming each one), so Deno never shows its permission prompt for them.