SharedID Edge

@sharedid-edge/core ​

The platform-neutral part of SharedID Edge: the request handler that sets the Prebid SharedID as a server-set first-party cookie, the consent checks, and the module interface. It uses only web-standard APIs (Request, Response, URL, crypto) and has no runtime dependencies, so every adapter bundles the same code.

Most publishers don't use this package directly: deploy one of the adapters instead (Cloudflare, Node.js, AWS Lambda). Use it to write an adapter for another platform, or a module.

Using it in code ​

ts
import { createHandler, resolveConfig } from '@sharedid-edge/core';
import { builtInModules } from '@sharedid-edge/modules';

const handler = createHandler({ config: resolveConfig(env), modules: builtInModules });

// Per request: the platform fills in what only it knows, such as the connecting address.
const response = await handler(request, { clientIp: '192.0.2.1', country: 'DE', isEU: true });
  • resolveConfig(env) reads the SID_* settings (the Configuration reference) and throws ConfigError on an invalid one.
  • createHandler(options) returns (request, platform?) => Promise<Response>. It answers the routes under SID_BASE_PATH and returns a 404 for any other path, so send it only that path and serve the rest of the site as before.
  • PlatformInfo carries what the platform knows about the visitor: clientIp, isEU and location fields. Fill location with locationInfo, which drops empty and invalid values the same way on every platform. Only use data the platform itself sets; see packages/adapters/AGENTS.md. Its optional traffic is the platform's own bot verdict (a TrafficReport, such as Cloudflare Bot Management's score), merged as source platform.
  • TrafficReport, TrafficSignal, mergeTraffic and skipsBot are the shared traffic signal (ortb2.device.ext.traffic): modules report with traffic in their result and core merges the reports, most cautious first, on /v1 and /sync (where only SID_SKIP_BOTS uses them). See the spec's Traffic signal.
  • parseCookies(header) reads a Cookie header (the first value of each name), cookieValues(header, name) every value of one name in header order, for cookies that may be duplicated across Domains (a host-only copy next to a domain one), and serializeCookie(name, value, options, date) writes a Set-Cookie.
  • For an adapter's plumbing around the handler: splitHeaders(response.headers) gives each Set-Cookie separately (for platforms that keep one value per header name) and the other headers; logRequestFailure(error) logs a failed request without its message, which may hold request data; handlerOrMisconfigured(build, misconfigured) builds the handler, or logs a ConfigError and returns your handler that answers every request with a 500; publicOriginFromEnv(env) reads SID_PUBLIC_ORIGIN as an option; booleanFromEnv(value, fallback) accepts 1/true/yes/on or 0/false/no/off (case-insensitive, with surrounding whitespace ignored) and returns fallback for missing, blank or unrecognized values; headerValue(headers, name) gives a trimmed header, or undefined when it's blank; parseHeaderMap(value, setting, fields, example) parses a JSON setting that maps fields to header names (throwing ConfigError), with isHeaderName for single names; and locationWithEU(source) is locationInfo plus isEU from the country, for platforms that report no EU flag.
  • defineModule, EdgeModule, ModuleContext and ModuleRoute are the module interface (EdgeModule.routes chooses /v1, /sync or both); see Adding a module and packages/modules/AGENTS.md.

The exact behaviour (routes, cookies, consent, responses) is in spec/SPEC.md, and the conformance suite checks it against every adapter.