@justanalyticsapp/node 0.1.0

package/dist/utils/headers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @file packages/node-sdk/src/utils/headers.ts
+ * @description W3C Trace Context traceparent header parsing and serialization.
+ *
+ * Implements Story 035 - Node.js SDK Core
+ *
+ * Format: "00-{traceId}-{spanId}-{flags}"
+ * - version: "00" (only supported version)
+ * - traceId: 32-char lowercase hex (128-bit, must not be all zeros)
+ * - spanId: 16-char lowercase hex (64-bit, must not be all zeros)
+ * - flags: 2-char hex ("01" = sampled, "00" = not sampled)
+ *
+ * References:
+ * - W3C Trace Context: https://www.w3.org/TR/trace-context/
+ */
+/** Parsed W3C traceparent header data */
+export interface TraceparentData {
+    /** Version field, always "00" */
+    version: string;
+    /** 32-character hex trace ID */
+    traceId: string;
+    /** 16-character hex parent span ID */
+    parentSpanId: string;
+    /** 2-character hex trace flags ("01" = sampled, "00" = not sampled) */
+    traceFlags: string;
+}
+/**
+ * Parse a W3C traceparent header string.
+ *
+ * Format: "00-{traceId}-{spanId}-{flags}"
+ *
+ * Returns `null` for invalid or malformed headers (does not throw).
+ *
+ * @param header - The traceparent header string to parse
+ * @returns Parsed traceparent data, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const data = parseTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01');
+ * // { version: '00', traceId: '4bf92f...', parentSpanId: '00f067...', traceFlags: '01' }
+ * ```
+ */
+export declare function parseTraceparent(header: string): TraceparentData | null;
+/**
+ * Serialize a W3C traceparent header string.
+ *
+ * Produces: "00-{traceId}-{spanId}-{flags}"
+ *
+ * @param traceId - 32-character hex trace ID
+ * @param spanId - 16-character hex span ID
+ * @param sampled - Whether the trace is sampled (default: true). true = "01", false = "00"
+ * @returns W3C traceparent header string
+ *
+ * @example
+ * ```typescript
+ * const header = serializeTraceparent('4bf92f3577b34da6a3ce929d0e0e4736', '00f067aa0ba902b7');
+ * // "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+ * ```
+ */
+export declare function serializeTraceparent(traceId: string, spanId: string, sampled?: boolean): string;

package/dist/utils/headers.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * @file packages/node-sdk/src/utils/headers.ts
+ * @description W3C Trace Context traceparent header parsing and serialization.
+ *
+ * Implements Story 035 - Node.js SDK Core
+ *
+ * Format: "00-{traceId}-{spanId}-{flags}"
+ * - version: "00" (only supported version)
+ * - traceId: 32-char lowercase hex (128-bit, must not be all zeros)
+ * - spanId: 16-char lowercase hex (64-bit, must not be all zeros)
+ * - flags: 2-char hex ("01" = sampled, "00" = not sampled)
+ *
+ * References:
+ * - W3C Trace Context: https://www.w3.org/TR/trace-context/
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTraceparent = parseTraceparent;
+exports.serializeTraceparent = serializeTraceparent;
+/** Regex for validating a 32-char lowercase hex string */
+const TRACE_ID_REGEX = /^[0-9a-f]{32}$/;
+/** Regex for validating a 16-char lowercase hex string */
+const SPAN_ID_REGEX = /^[0-9a-f]{16}$/;
+/** Regex for validating a 2-char lowercase hex string */
+const FLAGS_REGEX = /^[0-9a-f]{2}$/;
+/** All-zero trace ID (invalid per W3C spec) */
+const ZERO_TRACE_ID = '00000000000000000000000000000000';
+/** All-zero span ID (invalid per W3C spec) */
+const ZERO_SPAN_ID = '0000000000000000';
+/**
+ * Parse a W3C traceparent header string.
+ *
+ * Format: "00-{traceId}-{spanId}-{flags}"
+ *
+ * Returns `null` for invalid or malformed headers (does not throw).
+ *
+ * @param header - The traceparent header string to parse
+ * @returns Parsed traceparent data, or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const data = parseTraceparent('00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01');
+ * // { version: '00', traceId: '4bf92f...', parentSpanId: '00f067...', traceFlags: '01' }
+ * ```
+ */
+function parseTraceparent(header) {
+    if (!header || typeof header !== 'string') {
+        return null;
+    }
+    const parts = header.split('-');
+    if (parts.length !== 4) {
+        return null;
+    }
+    const [version, traceId, parentSpanId, traceFlags] = parts;
+    // Validate version (only "00" supported)
+    if (version !== '00') {
+        return null;
+    }
+    // Validate traceId: 32 hex chars, not all zeros
+    if (!TRACE_ID_REGEX.test(traceId) || traceId === ZERO_TRACE_ID) {
+        return null;
+    }
+    // Validate parentSpanId: 16 hex chars, not all zeros
+    if (!SPAN_ID_REGEX.test(parentSpanId) || parentSpanId === ZERO_SPAN_ID) {
+        return null;
+    }
+    // Validate traceFlags: 2 hex chars
+    if (!FLAGS_REGEX.test(traceFlags)) {
+        return null;
+    }
+    return { version, traceId, parentSpanId, traceFlags };
+}
+/**
+ * Serialize a W3C traceparent header string.
+ *
+ * Produces: "00-{traceId}-{spanId}-{flags}"
+ *
+ * @param traceId - 32-character hex trace ID
+ * @param spanId - 16-character hex span ID
+ * @param sampled - Whether the trace is sampled (default: true). true = "01", false = "00"
+ * @returns W3C traceparent header string
+ *
+ * @example
+ * ```typescript
+ * const header = serializeTraceparent('4bf92f3577b34da6a3ce929d0e0e4736', '00f067aa0ba902b7');
+ * // "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+ * ```
+ */
+function serializeTraceparent(traceId, spanId, sampled = true) {
+    const flags = sampled ? '01' : '00';
+    return `00-${traceId}-${spanId}-${flags}`;
+}
+//# sourceMappingURL=headers.js.map

package/dist/utils/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../src/utils/headers.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;AA6CH,4CAiCC;AAkBD,oDAOC;AAzFD,0DAA0D;AAC1D,MAAM,cAAc,GAAG,gBAAgB,CAAC;AAExC,0DAA0D;AAC1D,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAEvC,yDAAyD;AACzD,MAAM,WAAW,GAAG,eAAe,CAAC;AAEpC,+CAA+C;AAC/C,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAEzD,8CAA8C;AAC9C,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAExC;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,gBAAgB,CAAC,MAAc;IAC7C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,CAAC,GAAG,KAAK,CAAC;IAE3D,yCAAyC;IACzC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gDAAgD;IAChD,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,aAAa,EAAE,CAAC;QAC/D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,YAAY,KAAK,YAAY,EAAE,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,mCAAmC;IACnC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,oBAAoB,CAClC,OAAe,EACf,MAAc,EACd,UAAmB,IAAI;IAEvB,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IACpC,OAAO,MAAM,OAAO,IAAI,MAAM,IAAI,KAAK,EAAE,CAAC;AAC5C,CAAC"}

package/dist/utils/id.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file packages/node-sdk/src/utils/id.ts
+ * @description Cryptographically random ID generation for trace and span IDs.
+ *
+ * Implements Story 035 - Node.js SDK Core
+ *
+ * Uses Node.js built-in `crypto.randomBytes` for 128-bit trace IDs (32 hex chars)
+ * and 64-bit span IDs (16 hex chars), per W3C Trace Context specification.
+ */
+/**
+ * Generate a 32-character lowercase hex trace ID.
+ * Uses `crypto.randomBytes(16)` for 128 bits of cryptographic randomness.
+ *
+ * @returns 32-character lowercase hex string (e.g. "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6")
+ */
+export declare function generateTraceId(): string;
+/**
+ * Generate a 16-character lowercase hex span ID.
+ * Uses `crypto.randomBytes(8)` for 64 bits of cryptographic randomness.
+ *
+ * @returns 16-character lowercase hex string (e.g. "a1b2c3d4e5f6a7b8")
+ */
+export declare function generateSpanId(): string;

package/dist/utils/id.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * @file packages/node-sdk/src/utils/id.ts
+ * @description Cryptographically random ID generation for trace and span IDs.
+ *
+ * Implements Story 035 - Node.js SDK Core
+ *
+ * Uses Node.js built-in `crypto.randomBytes` for 128-bit trace IDs (32 hex chars)
+ * and 64-bit span IDs (16 hex chars), per W3C Trace Context specification.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateTraceId = generateTraceId;
+exports.generateSpanId = generateSpanId;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Generate a 32-character lowercase hex trace ID.
+ * Uses `crypto.randomBytes(16)` for 128 bits of cryptographic randomness.
+ *
+ * @returns 32-character lowercase hex string (e.g. "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6")
+ */
+function generateTraceId() {
+    return crypto_1.default.randomBytes(16).toString('hex');
+}
+/**
+ * Generate a 16-character lowercase hex span ID.
+ * Uses `crypto.randomBytes(8)` for 64 bits of cryptographic randomness.
+ *
+ * @returns 16-character lowercase hex string (e.g. "a1b2c3d4e5f6a7b8")
+ */
+function generateSpanId() {
+    return crypto_1.default.randomBytes(8).toString('hex');
+}
+//# sourceMappingURL=id.js.map

package/dist/utils/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/utils/id.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;;;AAUH,0CAEC;AAQD,wCAEC;AApBD,oDAA4B;AAE5B;;;;;GAKG;AACH,SAAgB,eAAe;IAC7B,OAAO,gBAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,SAAgB,cAAc;IAC5B,OAAO,gBAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@justanalyticsapp/node",
+  "version": "0.1.0",
+  "description": "JustAnalytics Node.js SDK for distributed tracing and observability",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./next": {
+      "require": "./dist/integrations/next.js",
+      "import": "./dist/integrations/next.js",
+      "types": "./dist/integrations/next.d.ts"
+    },
+    "./winston": {
+      "require": "./dist/integrations/winston.js",
+      "import": "./dist/integrations/winston.js",
+      "types": "./dist/integrations/winston.d.ts"
+    },
+    "./pino": {
+      "require": "./dist/integrations/pino.js",
+      "import": "./dist/integrations/pino.js",
+      "types": "./dist/integrations/pino.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "analytics",
+    "tracing",
+    "observability",
+    "apm",
+    "justanalytics",
+    "logging"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "winston-transport": ">=4.0.0",
+    "pino-abstract-transport": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "winston-transport": {
+      "optional": true
+    },
+    "pino-abstract-transport": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  }
+}