within-sdk 1.0.0

package/dist/modules/exporters/datadog.d.ts

@@ -0,0 +1,17 @@
+import { Event, Exporter } from "../../types.js";
+export interface DatadogExporterConfig {
+    type: "datadog";
+    apiKey: string;
+    site: string;
+    service: string;
+    env?: string;
+}
+export declare class DatadogExporter implements Exporter {
+    private logsUrl;
+    private metricsUrl;
+    private config;
+    constructor(config: DatadogExporterConfig);
+    export(event: Event): Promise<void>;
+    private eventToLog;
+    private eventToMetrics;
+}

package/dist/modules/exporters/datadog.js

@@ -0,0 +1,166 @@
+import { writeToLog } from "../logging.js";
+import { traceContext } from "./trace-context.js";
+import { WITHIN_SOURCE } from "../constants.js";
+export class DatadogExporter {
+    logsUrl;
+    metricsUrl;
+    config;
+    constructor(config) {
+        this.config = config;
+        // Build API endpoints based on site
+        const site = config.site.replace(/^https?:\/\//, "").replace(/\/$/, "");
+        this.logsUrl = `https://http-intake.logs.${site}/api/v2/logs`;
+        this.metricsUrl = `https://api.${site}/api/v1/series`;
+    }
+    async export(event) {
+        writeToLog("DatadogExporter: Sending event immediately to Datadog");
+        // Convert event to log and metrics
+        const log = this.eventToLog(event);
+        const metrics = this.eventToMetrics(event);
+        // Debug: Log the metrics URL and count (never the serialized payload)
+        writeToLog(`DatadogExporter: Metrics URL: ${this.metricsUrl}`);
+        writeToLog(`DatadogExporter: Sending ${metrics.length} metric series`);
+        // Send logs with response checking
+        const logsPromise = fetch(this.logsUrl, {
+            method: "POST",
+            headers: {
+                "DD-API-KEY": this.config.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify([log]),
+        })
+            .then(async (response) => {
+            if (!response.ok) {
+                writeToLog(`Datadog logs failed - Status: ${response.status}`);
+            }
+            else {
+                writeToLog(`Datadog logs success - Status: ${response.status}`);
+            }
+            return response;
+        })
+            .catch((err) => {
+            writeToLog(`Datadog logs network error: ${err}`);
+        });
+        // Send metrics with response checking
+        const metricsPromise = fetch(this.metricsUrl, {
+            method: "POST",
+            headers: {
+                "DD-API-KEY": this.config.apiKey,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ series: metrics }),
+        })
+            .then(async (response) => {
+            if (!response.ok) {
+                writeToLog(`Datadog metrics failed - Status: ${response.status}`);
+            }
+            else {
+                writeToLog(`Datadog metrics success - Status: ${response.status}`);
+            }
+            return response;
+        })
+            .catch((err) => {
+            writeToLog(`Datadog metrics network error: ${err}`);
+        });
+        // Wait for both to complete
+        await Promise.all([logsPromise, metricsPromise]);
+    }
+    eventToLog(event) {
+        const tags = [];
+        // Add basic tags
+        if (this.config.env)
+            tags.push(`env:${this.config.env}`);
+        if (event.eventType)
+            tags.push(`event_type:${event.eventType.replace(/\//g, ".")}`);
+        if (event.resourceName)
+            tags.push(`resource:${event.resourceName}`);
+        if (event.isError)
+            tags.push("error:true");
+        tags.push(`source:${WITHIN_SOURCE}`);
+        // Add customer-defined tags to ddtags (namespaced to avoid collisions with reserved Datadog tags)
+        if (event.tags) {
+            for (const [key, value] of Object.entries(event.tags)) {
+                const sanitizedKey = key.toLowerCase().replace(/[\s:,]+/g, "_");
+                const sanitizedValue = value.replace(/,/g, "_");
+                tags.push(`within.${sanitizedKey}:${sanitizedValue}`);
+            }
+        }
+        const log = {
+            message: `${event.eventType || "unknown"} - ${event.resourceName || "unknown"}`,
+            service: this.config.service,
+            ddsource: WITHIN_SOURCE,
+            ddtags: tags.join(","),
+            timestamp: event.timestamp ? event.timestamp.getTime() : Date.now(),
+            status: event.isError ? "error" : "info",
+            dd: {
+                trace_id: traceContext.getDatadogTraceId(event.sessionId),
+                span_id: traceContext.getDatadogSpanId(event.id),
+            },
+            mcp: {
+                session_id: event.sessionId,
+                event_id: event.id,
+                event_type: event.eventType,
+                resource: event.resourceName,
+                duration_ms: event.duration,
+                user_intent: event.userIntent,
+                actor_id: event.identifyActorGivenId,
+                actor_name: event.identifyActorName,
+                client_name: event.clientName,
+                client_version: event.clientVersion,
+                server_name: event.serverName,
+                server_version: event.serverVersion,
+                is_error: event.isError,
+                error: event.error,
+                tags: event.tags,
+                properties: event.properties,
+            },
+        };
+        // Add error at root level if it exists
+        if (event.isError && event.error) {
+            log.error = {
+                message: typeof event.error === "string"
+                    ? event.error
+                    : JSON.stringify(event.error),
+            };
+        }
+        return log;
+    }
+    eventToMetrics(event) {
+        const metrics = [];
+        const timestamp = Math.floor((event.timestamp?.getTime() || Date.now()) / 1000);
+        const tags = [`service:${this.config.service}`];
+        // Add optional tags
+        if (this.config.env)
+            tags.push(`env:${this.config.env}`);
+        if (event.eventType)
+            tags.push(`event_type:${event.eventType.replace(/\//g, ".")}`);
+        if (event.resourceName)
+            tags.push(`resource:${event.resourceName}`);
+        // Event count metric
+        metrics.push({
+            metric: "mcp.events.count",
+            type: "count",
+            points: [[timestamp, 1]],
+            tags,
+        });
+        // Duration metric (only if duration exists)
+        if (event.duration) {
+            metrics.push({
+                metric: "mcp.event.duration",
+                type: "gauge",
+                points: [[timestamp, event.duration]],
+                tags,
+            });
+        }
+        // Error count metric
+        if (event.isError) {
+            metrics.push({
+                metric: "mcp.errors.count",
+                type: "count",
+                points: [[timestamp, 1]],
+                tags,
+            });
+        }
+        return metrics;
+    }
+}

package/dist/modules/exporters/otlp.d.ts

@@ -0,0 +1,13 @@
+import { Event, Exporter } from "../../types.js";
+export interface OTLPExporterConfig {
+    type: "otlp";
+    endpoint: string;
+    headers?: Record<string, string>;
+}
+export declare class OTLPExporter implements Exporter {
+    private endpoint;
+    private headers;
+    constructor(config: OTLPExporterConfig);
+    export(event: Event): Promise<void>;
+    private convertToOTLPSpan;
+}

package/dist/modules/exporters/otlp.js

@@ -0,0 +1,140 @@
+import { writeToLog } from "../logging.js";
+import { traceContext } from "./trace-context.js";
+import { WITHIN_SOURCE } from "../constants.js";
+export class OTLPExporter {
+    endpoint;
+    headers;
+    constructor(config) {
+        // Auto-append /v1/traces per OTLP spec if not already present
+        const url = config.endpoint.replace(/\/+$/, "");
+        this.endpoint = url.endsWith("/v1/traces") ? url : `${url}/v1/traces`;
+        this.headers = {
+            "Content-Type": "application/json", // Using JSON for now for easier debugging
+            ...config.headers,
+        };
+    }
+    async export(event) {
+        try {
+            // Convert Within event to OTLP trace format
+            const span = this.convertToOTLPSpan(event);
+            // Create OTLP JSON format
+            const otlpRequest = {
+                resourceSpans: [
+                    {
+                        resource: {
+                            attributes: [
+                                {
+                                    key: "service.name",
+                                    value: { stringValue: event.serverName || "mcp-server" },
+                                },
+                                {
+                                    key: "service.version",
+                                    value: { stringValue: event.serverVersion || "unknown" },
+                                },
+                            ],
+                        },
+                        scopeSpans: [
+                            {
+                                scope: {
+                                    name: "within-sdk",
+                                    version: event.sdkVersion || "unknown",
+                                },
+                                spans: [span],
+                            },
+                        ],
+                    },
+                ],
+            };
+            // Use JSON format for now
+            const body = JSON.stringify(otlpRequest);
+            // Use fetch to send the data
+            const response = await fetch(this.endpoint, {
+                method: "POST",
+                headers: this.headers,
+                body,
+            });
+            if (!response.ok) {
+                throw new Error(`OTLP export failed: ${response.status} ${response.statusText}`);
+            }
+            writeToLog(`Successfully exported event to OTLP: ${event.id}`);
+        }
+        catch (error) {
+            throw new Error(`OTLP export error: ${error}`);
+        }
+    }
+    convertToOTLPSpan(event) {
+        const startTimeNanos = event.timestamp
+            ? BigInt(event.timestamp.getTime()) * BigInt(1_000_000)
+            : BigInt(Date.now()) * BigInt(1_000_000);
+        const endTimeNanos = event.duration
+            ? startTimeNanos + BigInt(event.duration) * BigInt(1_000_000)
+            : startTimeNanos;
+        return {
+            traceId: traceContext.getTraceId(event.sessionId),
+            spanId: traceContext.getSpanId(event.id),
+            name: event.eventType || "mcp.event",
+            kind: 2, // SPAN_KIND_SERVER
+            startTimeUnixNano: startTimeNanos.toString(),
+            endTimeUnixNano: endTimeNanos.toString(),
+            attributes: [
+                {
+                    key: "source",
+                    value: { stringValue: WITHIN_SOURCE },
+                },
+                {
+                    key: "mcp.event_type",
+                    value: { stringValue: event.eventType || "" },
+                },
+                {
+                    key: "mcp.session_id",
+                    value: { stringValue: event.sessionId || "" },
+                },
+                {
+                    key: "mcp.vendor_slug",
+                    value: { stringValue: event.vendorSlug || event.projectId || "" },
+                },
+                {
+                    key: "mcp.resource_name",
+                    value: { stringValue: event.resourceName || "" },
+                },
+                {
+                    key: "mcp.user_intent",
+                    value: { stringValue: event.userIntent || "" },
+                },
+                {
+                    key: "mcp.actor_id",
+                    value: { stringValue: event.identifyActorGivenId || "" },
+                },
+                {
+                    key: "mcp.actor_name",
+                    value: { stringValue: event.identifyActorName || "" },
+                },
+                {
+                    key: "mcp.client_name",
+                    value: { stringValue: event.clientName || "" },
+                },
+                {
+                    key: "mcp.client_version",
+                    value: { stringValue: event.clientVersion || "" },
+                },
+                // Add customer-defined tags as individual attributes
+                ...Object.entries(event.tags || {}).map(([key, value]) => ({
+                    key: `within.tag.${key}`,
+                    value: { stringValue: value },
+                })),
+                // Add customer-defined properties as JSON
+                ...(event.properties
+                    ? [
+                        {
+                            key: "within.properties",
+                            value: { stringValue: JSON.stringify(event.properties) },
+                        },
+                    ]
+                    : []),
+            ].filter((attr) => attr.value.stringValue), // Remove empty attributes
+            status: {
+                code: event.isError ? 2 : 1, // ERROR : OK
+            },
+        };
+    }
+}

package/dist/modules/exporters/posthog.d.ts

@@ -0,0 +1,32 @@
+import { Event, Exporter } from "../../types.js";
+/**
+ * Generates a deterministic UUIDv7 from a prefixed KSUID (e.g. ses_xxx).
+ * Uses the KSUID's embedded timestamp for the UUIDv7 timestamp portion
+ * and a SHA-256 hash of the full ID for the random bits.
+ */
+export declare function toUUIDv7(prefixedId: string): string;
+export interface PostHogExporterConfig {
+    type: "posthog";
+    apiKey: string;
+    host?: string;
+    /**
+     * Emits `$ai_span` events for tool calls alongside regular capture events,
+     * integrating with PostHog's AI observability views. Each tool call is its own
+     * trace (`$ai_trace_id`), grouped into sessions via `$ai_session_id`.
+     * Customer-defined `eventTags` are spread directly onto `$ai_span` properties
+     * and can override any default, including reserved `$ai_*` fields.
+     * @default false
+     */
+    enableAITracing?: boolean;
+}
+export declare class PostHogExporter implements Exporter {
+    private batchUrl;
+    private apiKey;
+    private config;
+    constructor(config: PostHogExporterConfig);
+    export(event: Event): Promise<void>;
+    private buildCaptureEvent;
+    private buildExceptionEvent;
+    private buildAISpanEvent;
+    private mapEventType;
+}

package/dist/modules/exporters/posthog.js

@@ -0,0 +1,272 @@
+import { createHash } from "crypto";
+import { writeToLog } from "../logging.js";
+import { WITHIN_SOURCE, WithinEventType } from "../constants.js";
+import KSUID from "../../thirdparty/ksuid/index.js";
+/**
+ * Generates a deterministic UUIDv7 from a prefixed KSUID (e.g. ses_xxx).
+ * Uses the KSUID's embedded timestamp for the UUIDv7 timestamp portion
+ * and a SHA-256 hash of the full ID for the random bits.
+ */
+export function toUUIDv7(prefixedId) {
+    // Strip prefix (ses_, evt_, etc.) and parse KSUID
+    const ksuidStr = prefixedId.replace(/^[a-z]+_/, "");
+    let timestampMs;
+    try {
+        const ksuid = KSUID.parse(ksuidStr);
+        timestampMs = ksuid.date.getTime();
+    }
+    catch {
+        // Fallback: if KSUID parsing fails, use current time
+        timestampMs = Date.now();
+    }
+    // Hash the full ID for deterministic random bits
+    const hash = createHash("sha256").update(prefixedId).digest();
+    const buf = Buffer.alloc(16);
+    // Bytes 0-5: 48-bit Unix timestamp in milliseconds
+    buf.writeUIntBE(timestampMs, 0, 6);
+    // Byte 6: version 7 (0111) + high 4 bits of rand_a from hash
+    buf[6] = 0x70 | (hash[0] & 0x0f);
+    // Byte 7: low 8 bits of rand_a from hash
+    buf[7] = hash[1];
+    // Byte 8: variant 10 + high 6 bits of rand_b from hash
+    buf[8] = 0x80 | (hash[2] & 0x3f);
+    // Bytes 9-15: remaining rand_b from hash
+    buf[9] = hash[3];
+    buf[10] = hash[4];
+    buf[11] = hash[5];
+    buf[12] = hash[6];
+    buf[13] = hash[7];
+    buf[14] = hash[8];
+    buf[15] = hash[9];
+    const hex = buf.toString("hex");
+    return [
+        hex.substring(0, 8),
+        hex.substring(8, 12),
+        hex.substring(12, 16),
+        hex.substring(16, 20),
+        hex.substring(20, 32),
+    ].join("-");
+}
+function getDistinctId(event) {
+    return event.identifyActorGivenId || event.sessionId || "anonymous";
+}
+function getTimestamp(event) {
+    return event.timestamp
+        ? event.timestamp.toISOString()
+        : new Date().toISOString();
+}
+export class PostHogExporter {
+    batchUrl;
+    apiKey;
+    config;
+    constructor(config) {
+        this.config = config;
+        const host = (config.host || "https://us.i.posthog.com").replace(/\/$/, "");
+        this.batchUrl = `${host}/batch`;
+        this.apiKey = config.apiKey;
+        writeToLog(`PostHogExporter: Initialized with endpoint ${this.batchUrl}`);
+    }
+    async export(event) {
+        try {
+            const batch = [];
+            // Always send the regular event
+            batch.push(this.buildCaptureEvent(event));
+            // Send $exception event alongside if this is an error
+            if (event.isError && event.error) {
+                batch.push(this.buildExceptionEvent(event));
+            }
+            // Send $ai_span for tool calls when AI tracing is enabled
+            if (this.config.enableAITracing &&
+                event.eventType === WithinEventType.mcpToolsCall) {
+                batch.push(this.buildAISpanEvent(event));
+            }
+            writeToLog(`PostHogExporter: Sending ${batch.length} event(s) for ${event.id}`);
+            const response = await fetch(this.batchUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    api_key: this.apiKey,
+                    batch,
+                }),
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                writeToLog(`PostHog export failed - Status: ${response.status}, Body: ${errorBody}`);
+            }
+            else {
+                writeToLog(`PostHog export success - Event: ${event.id}`);
+            }
+        }
+        catch (error) {
+            writeToLog(`PostHog export error: ${error}`);
+        }
+    }
+    buildCaptureEvent(event) {
+        const distinctId = getDistinctId(event);
+        const eventName = this.mapEventType(event.eventType);
+        const timestamp = getTimestamp(event);
+        const properties = {
+            $session_id: toUUIDv7(event.sessionId),
+            source: WITHIN_SOURCE,
+        };
+        if (event.resourceName) {
+            properties.resource_name = event.resourceName;
+            if (event.eventType === WithinEventType.mcpToolsCall) {
+                properties.tool_name = event.resourceName;
+            }
+        }
+        if (event.duration !== undefined) {
+            properties.duration_ms = event.duration;
+        }
+        if (event.serverName)
+            properties.server_name = event.serverName;
+        if (event.serverVersion)
+            properties.server_version = event.serverVersion;
+        if (event.clientName)
+            properties.client_name = event.clientName;
+        if (event.clientVersion)
+            properties.client_version = event.clientVersion;
+        if (event.projectId)
+            properties.project_id = event.projectId;
+        if (event.userIntent)
+            properties.user_intent = event.userIntent;
+        if (event.isError !== undefined)
+            properties.is_error = event.isError;
+        if (event.parameters !== undefined) {
+            properties.parameters = event.parameters;
+        }
+        if (event.response !== undefined) {
+            properties.response = event.response;
+        }
+        // Set person properties from identity data
+        const $set = {};
+        if (event.identifyActorName)
+            $set.name = event.identifyActorName;
+        if (event.identifyActorData) {
+            Object.assign($set, event.identifyActorData);
+        }
+        if (Object.keys($set).length > 0) {
+            properties.$set = $set;
+        }
+        // Spread customer-defined tags directly (can override Within defaults)
+        if (event.tags) {
+            for (const [key, value] of Object.entries(event.tags)) {
+                properties[key] = value;
+            }
+        }
+        // Spread customer-defined properties directly (can override Within defaults)
+        if (event.properties) {
+            for (const [key, value] of Object.entries(event.properties)) {
+                properties[key] = value;
+            }
+        }
+        return {
+            event: eventName,
+            distinct_id: distinctId,
+            properties,
+            timestamp,
+            type: "capture",
+        };
+    }
+    buildExceptionEvent(event) {
+        const distinctId = getDistinctId(event);
+        const timestamp = getTimestamp(event);
+        const properties = {
+            $exception_source: "backend",
+            $session_id: toUUIDv7(event.sessionId),
+        };
+        if (event.error) {
+            if (event.error.message) {
+                properties.$exception_message = event.error.message;
+            }
+            if (event.error.type) {
+                properties.$exception_type = event.error.type;
+            }
+            if (event.error.stack) {
+                properties.$exception_stacktrace = event.error.stack;
+            }
+        }
+        // Add tool/resource context
+        if (event.resourceName) {
+            properties.resource_name = event.resourceName;
+            if (event.eventType === WithinEventType.mcpToolsCall) {
+                properties.tool_name = event.resourceName;
+            }
+        }
+        if (event.serverName)
+            properties.server_name = event.serverName;
+        if (event.serverVersion)
+            properties.server_version = event.serverVersion;
+        if (event.clientName)
+            properties.client_name = event.clientName;
+        if (event.clientVersion)
+            properties.client_version = event.clientVersion;
+        return {
+            event: "$exception",
+            distinct_id: distinctId,
+            properties,
+            timestamp,
+            type: "capture",
+        };
+    }
+    buildAISpanEvent(event) {
+        const distinctId = getDistinctId(event);
+        const timestamp = getTimestamp(event);
+        const properties = {
+            $ai_session_id: `within_${event.sessionId}`,
+            $ai_trace_id: toUUIDv7(event.sessionId),
+            $ai_span_id: toUUIDv7(event.id),
+            $ai_span_name: event.resourceName || "unknown_tool",
+            $ai_is_error: event.isError || false,
+            $session_id: toUUIDv7(event.sessionId),
+            source: WITHIN_SOURCE,
+        };
+        if (event.duration !== undefined) {
+            properties.$ai_latency = event.duration / 1000;
+        }
+        if (event.isError && event.error) {
+            properties.$ai_error = event.error;
+        }
+        if (event.parameters !== undefined) {
+            properties.$ai_input_state = event.parameters;
+        }
+        if (event.response !== undefined) {
+            properties.$ai_output_state = event.response;
+        }
+        if (event.serverName)
+            properties.server_name = event.serverName;
+        if (event.clientName)
+            properties.client_name = event.clientName;
+        // Spread customer tags directly (can override Within defaults)
+        if (event.tags) {
+            for (const [key, value] of Object.entries(event.tags)) {
+                properties[key] = value;
+            }
+        }
+        // Spread customer properties directly (can override Within defaults)
+        if (event.properties) {
+            for (const [key, value] of Object.entries(event.properties)) {
+                properties[key] = value;
+            }
+        }
+        return {
+            event: "$ai_span",
+            distinct_id: distinctId,
+            properties,
+            timestamp,
+            type: "capture",
+        };
+    }
+    mapEventType(eventType) {
+        // Map Within event types to PostHog event names
+        const mapping = {
+            [WithinEventType.mcpToolsCall]: "mcp_tool_call",
+            [WithinEventType.mcpToolsList]: "mcp_tools_list",
+            [WithinEventType.mcpInitialize]: "mcp_initialize",
+        };
+        return (mapping[eventType] ||
+            `mcp_${eventType.replace(/^mcp:/, "").replace(/\//g, "_")}`);
+    }
+}

package/dist/modules/exporters/sentry.d.ts

@@ -0,0 +1,27 @@
+import { Event, Exporter } from "../../types.js";
+export interface SentryExporterConfig {
+    type: "sentry";
+    dsn: string;
+    environment?: string;
+    release?: string;
+    enableTracing?: boolean;
+}
+export declare class SentryExporter implements Exporter {
+    private endpoint;
+    private authHeader;
+    private config;
+    private parsedDSN;
+    constructor(config: SentryExporterConfig);
+    private parseDSN;
+    export(event: Event): Promise<void>;
+    private eventToLog;
+    private buildLogAttributes;
+    private createLogEnvelope;
+    private eventToTransaction;
+    private buildTags;
+    private buildExtra;
+    private buildContexts;
+    private eventToErrorEvent;
+    private createTransactionEnvelope;
+    private createErrorEnvelope;
+}