@stainlessdev/xray-node 0.6.0-dev.c5f614b → 0.7.0

package/README.md

@@ -0,0 +1,77 @@
+# @stainlessdev/xray-node
+
+Node.js HTTP adapter for Stainless X-ray request logging. Use this for `node:http` servers or to power framework integrations (Express/Fastify).
+
+## Install
+
+```sh
+pnpm add @stainlessdev/xray-node
+```
+
+## Basic usage (node:http)
+
+```ts
+import { createServer } from 'node:http';
+import { createEmitter, wrapHttpHandler } from '@stainlessdev/xray-node';
+
+const xray = createEmitter({
+  serviceName: 'my-service',
+  endpointUrl: 'http://localhost:4318',
+  // Optional: customize the request ID header name
+  requestId: { header: 'request-id' },
+});
+
+const server = createServer(
+  wrapHttpHandler((_req, res) => {
+    res.statusCode = 200;
+    res.setHeader('Content-Type', 'text/plain');
+    res.end('ok');
+  }, xray),
+);
+
+server.listen(3000);
+```
+
+## Access the X-ray context
+
+```ts
+import { getXrayContext } from '@stainlessdev/xray-node';
+
+const handler = wrapHttpHandler((req, res) => {
+  const ctx = getXrayContext(req);
+  ctx?.setUserId('user-123');
+  res.end('ok');
+}, xray);
+```
+
+## Request IDs and response headers
+
+X-ray will **auto-generate a request ID and inject it into your response headers** under the configured name (`requestId.header`, default `request-id`, emitted as `Request-Id`) if the header is missing. If you set your own request ID first (via `options.requestId` or by setting the response header yourself), X-ray preserves it and does not overwrite the header.
+
+## Configuration
+
+`createEmitter(config)` accepts `XrayRuntimeConfig` from `@stainlessdev/xray-core`:
+
+- `serviceName` (required)
+- `endpointUrl` (required; falls back to `STAINLESS_XRAY_ENDPOINT_URL` when omitted; explicit `endpointUrl` wins)
+- `environment`, `version`, `logger`, `logLevel`
+- `exporter`: `endpointUrl`, `headers`, `timeoutMs`, `spanProcessor`, `instance` (custom SpanExporter)
+- `capture`: request/response headers and bodies
+- `redaction`: headers/query/body JSON-path redaction
+- `requestId`: header name to read/write
+- `route`: normalization options
+
+## Adapter options (WrapOptions)
+
+`wrapHttpHandler(handler, xray, options)` and `createEmitter(config, options?)` share:
+
+- `route`: override the route name for the request
+- `requestId`: explicit request ID to use (prevents auto-generation)
+- `capture`: per-request capture overrides
+- `redaction`: per-request redaction overrides
+- `onRequest(ctx)`, `onResponse(ctx, log)`, `onError(ctx, err)` hooks
+
+## Notes
+
+- This package depends on OpenTelemetry packages as peer dependencies.
+- Node.js >= 20 is required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stainlessdev/xray-node",
-  "version": "0.6.0-dev.c5f614b",
+  "version": "0.7.0",
   "description": "Node.js HTTP adapter for Stainless X-ray request logging",
   "files": [
     "dist"
@@ -20,7 +20,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@stainlessdev/xray-core": "0.6.0-dev.c5f614b"
+    "@stainlessdev/xray-core": "0.7.0"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.0",