@runtime-digital-twin/sdk 1.0.0

package/dist/trace-loader.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadTraceMeta = loadTraceMeta;
+exports.validateTraceStructure = validateTraceStructure;
+exports.formatTraceLoadFailure = formatTraceLoadFailure;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const fs_1 = require("fs");
+const constants_1 = require("./constants");
+/**
+ * Check if a file exists
+ */
+async function fileExists(path) {
+    try {
+        await (0, promises_1.access)(path, fs_1.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Load trace metadata with version guard.
+ *
+ * - If trace_format_version is missing: assumes version 1 and emits a warning
+ * - If trace_format_version > CURRENT_TRACE_FORMAT_VERSION: throws TraceLoadFailure
+ *
+ * @param traceDir - Path to the trace directory
+ * @returns TraceLoadResult with metadata and any warnings
+ * @throws TraceLoadFailure if trace cannot be loaded or version is unsupported
+ */
+async function loadTraceMeta(traceDir) {
+    const metaPath = (0, path_1.join)(traceDir, 'meta.json');
+    // Check file exists
+    if (!(await fileExists(metaPath))) {
+        const failure = {
+            type: 'missing_file',
+            location: metaPath,
+            expected: 'meta.json file',
+            actual: 'file not found',
+            hint: 'Ensure the trace directory contains a valid meta.json file',
+        };
+        throw failure;
+    }
+    // Read and parse meta.json
+    let rawMeta;
+    try {
+        const content = await (0, promises_1.readFile)(metaPath, 'utf8');
+        rawMeta = JSON.parse(content);
+    }
+    catch (error) {
+        const failure = {
+            type: 'parse_error',
+            location: metaPath,
+            expected: 'valid JSON',
+            actual: `parse error: ${error instanceof Error ? error.message : String(error)}`,
+            hint: 'Check that meta.json contains valid JSON',
+        };
+        throw failure;
+    }
+    const warnings = [];
+    let version;
+    // Check trace_format_version
+    if (rawMeta.trace_format_version === undefined) {
+        // Missing version: assume version 1 and emit warning
+        version = 1;
+        const warning = {
+            type: 'warning',
+            code: 'missing_trace_format_version',
+            message: `trace_format_version missing in ${metaPath}, assuming version 1`,
+            traceDir,
+            assumedVersion: 1,
+        };
+        warnings.push(warning);
+        // Output warning to stderr for CLI visibility
+        console.warn(`[Trace Loader] Warning: ${warning.message}`);
+    }
+    else {
+        version = Number(rawMeta.trace_format_version);
+        if (isNaN(version) || version < 1) {
+            const failure = {
+                type: 'validation_error',
+                location: metaPath,
+                expected: 'positive integer trace_format_version',
+                actual: String(rawMeta.trace_format_version),
+                hint: 'trace_format_version must be a positive integer',
+            };
+            throw failure;
+        }
+    }
+    // Check if version is higher than supported
+    if (version > constants_1.CURRENT_TRACE_FORMAT_VERSION) {
+        const failure = {
+            type: 'schema_drift',
+            location: metaPath,
+            expected: `trace_format_version <= ${constants_1.CURRENT_TRACE_FORMAT_VERSION}`,
+            actual: `trace_format_version = ${version}`,
+            hint: `This trace was created with a newer version of the SDK. Upgrade your SDK to version that supports trace format version ${version}.`,
+        };
+        throw failure;
+    }
+    // Build typed metadata
+    const meta = {
+        trace_format_version: version,
+        traceId: String(rawMeta.traceId || ''),
+        startedAt: String(rawMeta.startedAt || ''),
+        completedAt: rawMeta.completedAt ? String(rawMeta.completedAt) : null,
+        serviceName: String(rawMeta.serviceName || ''),
+        serviceVersion: String(rawMeta.serviceVersion || ''),
+        environment: String(rawMeta.environment || ''),
+        mode: rawMeta.mode === 'replay' ? 'replay' : 'record',
+        inboundRequest: rawMeta.inboundRequest,
+    };
+    return { meta, warnings };
+}
+/**
+ * Validate that a trace directory contains required files.
+ *
+ * @param traceDir - Path to the trace directory
+ * @throws TraceLoadFailure if required files are missing
+ */
+async function validateTraceStructure(traceDir) {
+    const eventsPath = (0, path_1.join)(traceDir, 'events.jsonl');
+    if (!(await fileExists(eventsPath))) {
+        const failure = {
+            type: 'missing_file',
+            location: eventsPath,
+            expected: 'events.jsonl file',
+            actual: 'file not found',
+            hint: 'Ensure the trace directory contains a valid events.jsonl file',
+        };
+        throw failure;
+    }
+}
+/**
+ * Helper to format TraceLoadFailure for CLI output
+ */
+function formatTraceLoadFailure(failure) {
+    return [
+        `[Trace Load Error] ${failure.type}`,
+        `  Location: ${failure.location}`,
+        `  Expected: ${failure.expected}`,
+        `  Actual: ${failure.actual}`,
+        `  Hint: ${failure.hint}`,
+    ].join('\n');
+}

package/dist/trace-uploader.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Trace Uploader
+ *
+ * Uploads trace bundles to the ingestion endpoint after capture
+ */
+export interface TraceUploadOptions {
+    uploadUrl: string;
+    apiKey: string;
+    traceDir: string;
+    traceId: string;
+    serviceName: string;
+    serviceVersion?: string;
+    environment?: string;
+}
+export interface TraceUploadResult {
+    success: boolean;
+    traceId: string;
+    blobRoot?: string;
+    error?: string;
+}
+/**
+ * Upload trace to ingestion endpoint
+ */
+export declare function uploadTrace(options: TraceUploadOptions): Promise<TraceUploadResult>;
+//# sourceMappingURL=trace-uploader.d.ts.map

package/dist/trace-uploader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-uploader.d.ts","sourceRoot":"","sources":["../src/trace-uploader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+CD;;GAEG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAiF5B"}

package/dist/trace-uploader.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * Trace Uploader
+ *
+ * Uploads trace bundles to the ingestion endpoint after capture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadTrace = uploadTrace;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const fs_1 = require("fs");
+const readline_1 = require("readline");
+/**
+ * Read trace events from events.jsonl
+ */
+async function readTraceEvents(eventsPath) {
+    const events = [];
+    try {
+        const fileStream = (0, fs_1.createReadStream)(eventsPath);
+        const rl = (0, readline_1.createInterface)({
+            input: fileStream,
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            const trimmed = line.trim();
+            if (trimmed) {
+                try {
+                    events.push(JSON.parse(trimmed));
+                }
+                catch (error) {
+                    console.warn(`[SDK] Failed to parse event line: ${error}`);
+                }
+            }
+        }
+    }
+    catch (error) {
+        // If file doesn't exist or can't be read, return empty array
+        if (error.code !== 'ENOENT') {
+            console.warn(`[SDK] Failed to read events.jsonl: ${error.message}`);
+        }
+    }
+    return events;
+}
+/**
+ * Read trace metadata from meta.json
+ */
+async function readTraceMeta(metaPath) {
+    try {
+        const content = await (0, promises_1.readFile)(metaPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Failed to read meta.json: ${error.message}`);
+    }
+}
+/**
+ * Upload trace to ingestion endpoint
+ */
+async function uploadTrace(options) {
+    const { uploadUrl, apiKey, traceDir, traceId, serviceName, serviceVersion, environment } = options;
+    try {
+        // Trace files are stored in traceDir/traceId/
+        const tracePath = (0, path_1.join)(traceDir, traceId);
+        const metaPath = (0, path_1.join)(tracePath, 'meta.json');
+        const eventsPath = (0, path_1.join)(tracePath, 'events.jsonl');
+        // Read metadata
+        const meta = await readTraceMeta(metaPath);
+        // Read events
+        const events = await readTraceEvents(eventsPath);
+        if (events.length === 0) {
+            return {
+                success: false,
+                traceId,
+                error: 'No events found in trace',
+            };
+        }
+        // Extract startedAt from metadata (convert ISO string to timestamp)
+        const startedAt = meta.startedAt
+            ? new Date(meta.startedAt).getTime()
+            : Date.now();
+        // Build batch payload
+        const batch = {
+            metadata: {
+                traceId,
+                serviceName,
+                serviceVersion: serviceVersion || meta.serviceVersion || '1.0.0',
+                environment: environment || meta.environment || 'production',
+                startedAt,
+                correlationIds: meta.correlationIds || [],
+            },
+            events: events.map(event => {
+                // Ensure all events have required base envelope fields
+                return {
+                    ...event,
+                    traceId: event.traceId || traceId,
+                    serviceName: event.serviceName || serviceName,
+                    parentSpanId: event.parentSpanId ?? null,
+                };
+            }),
+        };
+        // Upload to ingestion endpoint
+        const response = await fetch(uploadUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify(batch),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            return {
+                success: false,
+                traceId,
+                error: `Upload failed: ${response.status} ${response.statusText} - ${errorText}`,
+            };
+        }
+        const result = await response.json();
+        return {
+            success: true,
+            traceId: result.traceId || traceId,
+            blobRoot: result.blobRoot,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            traceId,
+            error: error.message || String(error),
+        };
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@runtime-digital-twin/sdk",
+  "version": "1.0.0",
+  "description": "SDK for capturing runtime behavior - automatic incident response and debugging",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./src/*": "./src/*",
+    "./dist/*": "./dist/*"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@runtime-digital-twin/core": "^1.0.0",
+    "fastify": "^4.24.0",
+    "fastify-plugin": "^4.5.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/your-org/WraithOnCallEngineer.git",
+    "directory": "packages/sdk"
+  },
+  "keywords": [
+    "runtime",
+    "digital-twin",
+    "tracing",
+    "replay",
+    "debugging",
+    "fastify",
+    "instrumentation",
+    "observability"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ]
+}
+