@stackonward/onex-device-context

OneX browser request-context adapter for @stackonward/device-fingerprint. It maps a privacy-limited fingerprint result into the headers expected by OneX without taking ownership of operation idempotency.

Install

pnpm add @stackonward/onex-device-context

Quick start

import { getOneXDeviceContextHeaders } from "@stackonward/onex-device-context";

const headers = await getOneXDeviceContextHeaders({
  productCode: "product_alpha",
  appVersion: "1.0.0",
});

await fetch("/api/orders", {
  method: "POST",
  headers,
});

Options

| Option | Required | Purpose | | ------------- | -------- | --------------------------------------------------------------------- | | productCode | yes | Product scope matching ^[a-z][a-z0-9_]{1,49}$ | | appVersion | no | Value for X-Client-Version | | fingerprint | no | Injected async fingerprint provider for a specialized runtime or test |

The returned object always contains:

• X-Device-ID from the fingerprint visitorId;
• X-Client-Type: web;
• X-Client-Platform: web;
• X-Product-Code from the validated option.

X-Client-Version is included only when appVersion is present.

Idempotency boundary

This adapter never emits X-Idempotency-Key or Stripe's Idempotency-Key. The owner of each write operation must create the correct key and bind it to the complete business command. Device identity and operation identity are separate contracts.

Privacy and failure behavior

The default provider uses the low-entropy, salted fingerprint from @stackonward/device-fingerprint; it is request context, not authentication. Invalid product codes and fingerprint-provider failures reject the operation instead of returning incomplete headers.

Compatibility

• Modern browsers with the Web Crypto API when using the default fingerprint provider
• ESM with TypeScript declarations

Related packages

• @stackonward/device-fingerprint provides the provider-neutral fingerprint engine.

License

MIT