Server API
@parlox/server: the adapters, createParlox, purchase, ucp, flush, and every option.
On this page
@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
| Import | For | Use |
|---|---|---|
@parlox/server/next | Next.js middleware (middleware.ts, or proxy.ts in Next.js 16) | export default withParlox(middleware?, options?) |
@parlox/server/express | Express and any Connect-style server | app.use(parlox(options?)) |
@parlox/server/hono | Hono on Node, Bun, Cloudflare Workers and Pages, Vercel, AWS Lambda | app.use(parlox(options?)) |
@parlox/server/vercel | Vercel Routing Middleware, for a static site | export default withParlox({ next, ...options }) or withParlox(existing, { next, ...options }) |
@parlox/server/fetch | Remix, SvelteKit, Astro, Deno and other Web-standard servers | const parlox = parloxFetch(options?) |
@parlox/server | Orders, UCP reports, and anything else | createParlox(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'parloxfunction itself (the one you import, not the middleware it returns) has aflushmethod for shutdown:await parlox.flush().parloxFetch()returnshandle(request)(the ownership check'sResponse, ornullto continue),observe(request, status, waitUntil?),purchase,ucpandflush.- Every adapter also takes
clientIp(request), your own source of the client address, which overridesipHeader.
createParlox
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
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
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).
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
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.
| Option | Default | |
|---|---|---|
secretKey | PARLOX_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 |
verifyToken | PARLOX_VERIFY_TOKEN (Hono: c.env first) | The answer to the ownership check |
ipHeader | PARLOX_IP_HEADER, else x-real-ip on Vercel, else (Hono and fetch) cf-connecting-ip for a request Cloudflare delivered, else none | The header that carries the client address. null turns it off |
timeoutMs | 2000 | For reports sent on their own, and purchases |
flushAt | 20 | Long-running servers: send a batch once this many reports wait |
flushIntervalMs | 10000 | And at least this often |
maxBatchSize | 100 | Reports per request; 100 is also the most the gateway accepts |
maxBatchBytes | 200000 | Bytes per request, at most |
maxQueueSize | 1000 | When full, the oldest report is dropped and counted |
batchTimeoutMs | 10000 | For a batch request |
retryCount | 3 | Further attempts for a batch Parlox provably did not store; 0 turns retries off |
retryDelayMs | 3000 | Between those attempts, when Parlox names no Retry-After |
maxPurchasesInFlight | 10 | For the whole process |
maxUcpReportsInFlight | 10 | For the whole process, apart from purchases |
includeApi | false | Report GET requests under /api/ too |
runWrapped(pathname) | every request | Next.js only: which requests the wrapped middleware runs for |
onError(err) | ignored | Called 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_KEY | The "Crawler reports only" key the middleware sends with |
PARLOX_VERIFY_TOKEN | Optional: the site's verification token |
PARLOX_IP_HEADER | Optional: the header your own proxy sets with the client address (x-real-ip behind nginx, cf-connecting-ip behind Cloudflare) |
PARLOX_ORDERS_KEY | A 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.