Server

Emit events from Node or edge with createServerClient.

Create a client

pnpm add @hyperreal/landscape-server

import { createServerClient } from "@hyperreal/landscape-server";

const landscape = createServerClient({ endpoint: "https://api.example.com/events" });

landscape.track("invoice_paid", { amount: 49 }, { userId: "user_123" });
await landscape.flush();

Per-request context

landscape.track(
  "api_called",
  { route: "/checkout" },
  {
    visitorId: "vis_123",
    sessionId: "ses_123",
    userId: "user_123",
    headers: { "cf-ipcountry": "LK" },
    timeZone: "Asia/Colombo",
    locale: "en-LK",
  },
);

When visitorId or sessionId is omitted, the client uses ids created at construction. Pass request-scoped ids to correlate with the browser client.

Country is resolved from CDN headers (CF-IPCountry, x-vercel-ip-country, CloudFront-Viewer-Country, Fastly-Geo-Country-Code), then timezone, then locale. Add names with countryHeaders.

Defaults

Shut down

await landscape.shutdown();

Stops the interval timer and flushes remaining events. Call this on process exit.

Failed flush puts the batch back on the buffer and rethrows after onError.