extractContext()

extractContext() is a static method that reads IP, user-agent, and geolocation headers from an HTTP request object and returns a TelemetryContext. Call it when you want to extract context separately from log().

Signature

static extractContext(req: any): TelemetryContext

Supported request formats

• Web API Request: Cloudflare Workers, Next.js Route Handlers, Deno, Bun
• Node.js IncomingMessage: Express, Fastify, raw Node HTTP servers

The method checks for req.headers.get() (Web API) first, then falls back to req.headers[name] (Node.js object).

Headers read

Header	Used for
cf-connecting-ip	Client IP (Cloudflare)
x-real-ip	Client IP (Nginx, common proxies)
x-forwarded-for	Client IP (load balancers, first value used)
user-agent	Browser / OS detection
cf-ipcountry	Country code (Cloudflare)
x-vercel-ip-country	Country code (Vercel)
cf-region-code	Region code (Cloudflare)
x-vercel-ip-country-region	Region code (Vercel)
cf-ipcity	City (Cloudflare)
x-vercel-ip-city	City (Vercel)

TelemetryContext

interface TelemetryContext {
  ip?: string;
  userAgent?: string;
  location?: {
    country?: string;
    region?: string;
    city?: string;
  };
  device?: {
    browser?: string;
    os?: string;
    type?: string;
  };
  [key: string]: any;
}

Example

import { VolidatorClient } from '@volidator/node';

// Extract once, reuse across multiple log calls
const context = VolidatorClient.extractContext(request);

await volidator.log({ actor: userId, action: 'page.view', target: pageId, context });
await volidator.log({ actor: userId, action: 'click.cta', target: 'upgrade', context });

Notes

• extractContext() does not apply any telemetry config. It returns the raw extracted values.
• The log() method calls extractContext() internally when you pass req. Use extractContext() directly only when you need the context object for other purposes.
• device is populated by log() based on the telemetry config, not by extractContext() directly.

Related

• Telemetry — controlling what context data is stored
• log() — how req and context interact in a log call