within-sdk 1.0.0

package/dist/modules/exporters/sentry.js

@@ -0,0 +1,386 @@
+import { writeToLog } from "../logging.js";
+import { traceContext } from "./trace-context.js";
+import { WITHIN_SOURCE } from "../constants.js";
+export class SentryExporter {
+    endpoint;
+    authHeader;
+    config;
+    parsedDSN;
+    constructor(config) {
+        this.config = config;
+        this.parsedDSN = this.parseDSN(config.dsn);
+        // Build envelope endpoint
+        this.endpoint = `${this.parsedDSN.protocol}://${this.parsedDSN.host}${this.parsedDSN.port ? `:${this.parsedDSN.port}` : ""}${this.parsedDSN.path}/api/${this.parsedDSN.projectId}/envelope/`;
+        // Build auth header
+        this.authHeader = `Sentry sentry_version=7, sentry_client=within-sdk/1.0.2, sentry_key=${this.parsedDSN.publicKey}`;
+        writeToLog(`SentryExporter: Initialized with endpoint ${this.endpoint}`);
+    }
+    parseDSN(dsn) {
+        // DSN format: protocol://publicKey@host[:port]/path/projectId
+        const regex = /^(https?):\/\/([a-f0-9]+)@([\w.-]+)(:\d+)?(\/.*)?\/(\d+)$/;
+        const match = dsn.match(regex);
+        if (!match) {
+            throw new Error(`Invalid Sentry DSN: ${dsn}`);
+        }
+        return {
+            protocol: match[1],
+            publicKey: match[2],
+            host: match[3],
+            port: match[4]?.substring(1), // Remove leading ':'
+            path: match[5] || "",
+            projectId: match[6],
+        };
+    }
+    async export(event) {
+        try {
+            // ALWAYS send log
+            const log = this.eventToLog(event);
+            const logEnvelope = this.createLogEnvelope(log);
+            writeToLog(`SentryExporter: Sending log for event ${event.id} to Sentry`);
+            const logResponse = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "X-Sentry-Auth": this.authHeader,
+                    "Content-Type": "application/x-sentry-envelope",
+                },
+                body: logEnvelope,
+            });
+            if (!logResponse.ok) {
+                const errorBody = await logResponse.text();
+                writeToLog(`Sentry log export failed - Status: ${logResponse.status}, Body: ${errorBody}`);
+            }
+            else {
+                writeToLog(`Sentry log export success - Event: ${event.id}`);
+            }
+            // OPTIONALLY send transaction for performance monitoring
+            if (this.config.enableTracing) {
+                const transaction = this.eventToTransaction(event);
+                const transactionEnvelope = this.createTransactionEnvelope(transaction);
+                writeToLog(`SentryExporter: Sending transaction ${transaction.event_id} to Sentry`);
+                const transactionResponse = await fetch(this.endpoint, {
+                    method: "POST",
+                    headers: {
+                        "X-Sentry-Auth": this.authHeader,
+                        "Content-Type": "application/x-sentry-envelope",
+                    },
+                    body: transactionEnvelope,
+                });
+                if (!transactionResponse.ok) {
+                    const errorBody = await transactionResponse.text();
+                    writeToLog(`Sentry transaction export failed - Status: ${transactionResponse.status}, Body: ${errorBody}`);
+                }
+                else {
+                    writeToLog(`Sentry transaction export success - Event: ${event.id}`);
+                }
+            }
+            // ALWAYS send error event for Issue creation if this is an error
+            if (event.isError) {
+                // Use transaction if available for better context, otherwise create minimal error event
+                const errorEvent = this.config.enableTracing
+                    ? this.eventToErrorEvent(event, this.eventToTransaction(event))
+                    : this.eventToErrorEvent(event);
+                const errorEnvelope = this.createErrorEnvelope(errorEvent);
+                writeToLog(`SentryExporter: Sending error event ${errorEvent.event_id} to Sentry for Issue creation`);
+                const errorResponse = await fetch(this.endpoint, {
+                    method: "POST",
+                    headers: {
+                        "X-Sentry-Auth": this.authHeader,
+                        "Content-Type": "application/x-sentry-envelope",
+                    },
+                    body: errorEnvelope,
+                });
+                if (!errorResponse.ok) {
+                    const errorBody = await errorResponse.text();
+                    writeToLog(`Sentry error export failed - Status: ${errorResponse.status}, Body: ${errorBody}`);
+                }
+                else {
+                    writeToLog(`Sentry error export success - Event: ${event.id}`);
+                }
+            }
+        }
+        catch (error) {
+            writeToLog(`Sentry export error: ${error}`);
+        }
+    }
+    eventToLog(event) {
+        const timestamp = event.timestamp
+            ? new Date(event.timestamp).getTime() / 1000
+            : Date.now() / 1000;
+        const traceId = traceContext.getTraceId(event.sessionId);
+        // Generate deterministic event_id for Sentry
+        const eventId = traceContext.getSpanId(event.id) + traceContext.getSpanId(event.id);
+        // Build message
+        const message = event.resourceName
+            ? `MCP ${event.eventType || "event"}: ${event.resourceName}`
+            : `MCP ${event.eventType || "event"}`;
+        return {
+            timestamp,
+            trace_id: traceId,
+            event_id: eventId,
+            level: event.isError ? "error" : "info",
+            body: message,
+            attributes: this.buildLogAttributes(event),
+        };
+    }
+    buildLogAttributes(event) {
+        const attributes = {};
+        if (event.eventType) {
+            attributes.eventType = { value: event.eventType, type: "string" };
+        }
+        if (event.resourceName) {
+            attributes.resourceName = { value: event.resourceName, type: "string" };
+        }
+        if (event.serverName) {
+            attributes.serverName = { value: event.serverName, type: "string" };
+        }
+        if (event.clientName) {
+            attributes.clientName = { value: event.clientName, type: "string" };
+        }
+        if (event.sessionId) {
+            attributes.sessionId = { value: event.sessionId, type: "string" };
+        }
+        if (event.projectId) {
+            attributes.projectId = { value: event.projectId, type: "string" };
+        }
+        if (event.duration !== undefined) {
+            attributes.duration_ms = { value: event.duration, type: "double" };
+        }
+        if (event.identifyActorGivenId) {
+            attributes.actorId = {
+                value: event.identifyActorGivenId,
+                type: "string",
+            };
+        }
+        if (event.identifyActorName) {
+            attributes.actorName = { value: event.identifyActorName, type: "string" };
+        }
+        if (event.userIntent) {
+            attributes.userIntent = { value: event.userIntent, type: "string" };
+        }
+        if (event.serverVersion) {
+            attributes.serverVersion = { value: event.serverVersion, type: "string" };
+        }
+        if (event.clientVersion) {
+            attributes.clientVersion = { value: event.clientVersion, type: "string" };
+        }
+        if (event.isError !== undefined) {
+            attributes.isError = { value: event.isError, type: "boolean" };
+        }
+        return attributes;
+    }
+    createLogEnvelope(log) {
+        // Envelope header
+        const envelopeHeader = {
+            event_id: log.event_id,
+            sent_at: new Date().toISOString(),
+        };
+        // Item header with ALL MANDATORY fields
+        const itemHeader = {
+            type: "log",
+            item_count: 1, // MANDATORY - must match number of logs
+            content_type: "application/vnd.sentry.items.log+json", // MANDATORY - exact string
+        };
+        // Payload with CORRECT key
+        const payload = {
+            items: [log], // Changed from 'logs' to 'items'
+        };
+        // Build envelope with TRAILING NEWLINE
+        return ([
+            JSON.stringify(envelopeHeader),
+            JSON.stringify(itemHeader),
+            JSON.stringify(payload),
+        ].join("\n") + "\n"); // Added required trailing newline
+    }
+    eventToTransaction(event) {
+        // Calculate timestamps
+        const endTimestamp = event.timestamp
+            ? new Date(event.timestamp).getTime() / 1000
+            : Date.now() / 1000;
+        const startTimestamp = event.duration
+            ? endTimestamp - event.duration / 1000
+            : endTimestamp;
+        const traceId = traceContext.getTraceId(event.sessionId);
+        const spanId = traceContext.getSpanId(event.id);
+        // Build transaction name
+        const transactionName = event.resourceName
+            ? `${event.eventType || "mcp"} - ${event.resourceName}`
+            : event.eventType || "mcp.event";
+        const transaction = {
+            type: "transaction",
+            event_id: traceContext.getSpanId(event.id) + traceContext.getSpanId(),
+            timestamp: endTimestamp,
+            start_timestamp: startTimestamp,
+            transaction: transactionName,
+            contexts: this.buildContexts(event, {
+                trace_id: traceId,
+                span_id: spanId,
+                op: event.eventType || "mcp.event",
+                status: event.isError ? "internal_error" : "ok",
+            }),
+            tags: this.buildTags(event),
+            extra: this.buildExtra(event),
+        };
+        return transaction;
+    }
+    buildTags(event) {
+        const tags = {
+            source: WITHIN_SOURCE,
+        };
+        if (this.config.environment)
+            tags.environment = this.config.environment;
+        if (this.config.release)
+            tags.release = this.config.release;
+        if (event.eventType)
+            tags.event_type = event.eventType;
+        if (event.resourceName)
+            tags.resource = event.resourceName;
+        if (event.serverName)
+            tags.server_name = event.serverName;
+        if (event.clientName)
+            tags.client_name = event.clientName;
+        if (event.identifyActorGivenId)
+            tags.actor_id = event.identifyActorGivenId;
+        // Add customer-defined tags (namespaced to avoid collisions with Sentry reserved fields)
+        if (event.tags) {
+            for (const [key, value] of Object.entries(event.tags)) {
+                tags[`within.${key}`] = value;
+            }
+        }
+        return tags;
+    }
+    buildExtra(event) {
+        const extra = {};
+        if (event.sessionId)
+            extra.session_id = event.sessionId;
+        if (event.projectId)
+            extra.project_id = event.projectId;
+        if (event.userIntent)
+            extra.user_intent = event.userIntent;
+        if (event.identifyActorName)
+            extra.actor_name = event.identifyActorName;
+        if (event.serverVersion)
+            extra.server_version = event.serverVersion;
+        if (event.clientVersion)
+            extra.client_version = event.clientVersion;
+        if (event.duration !== undefined)
+            extra.duration_ms = event.duration;
+        if (event.error)
+            extra.error = event.error;
+        return extra;
+    }
+    buildContexts(event, traceCtx) {
+        const contexts = {
+            trace: traceCtx,
+        };
+        // Add customer-defined properties as a custom context
+        if (event.properties) {
+            contexts.within = event.properties;
+        }
+        return contexts;
+    }
+    eventToErrorEvent(event, transaction) {
+        // Extract error message
+        let errorMessage = "Unknown error";
+        let errorType = "ToolCallError";
+        if (event.error) {
+            if (typeof event.error === "string") {
+                errorMessage = event.error;
+            }
+            else if (typeof event.error === "object" && event.error !== null) {
+                if ("message" in event.error) {
+                    errorMessage = String(event.error.message);
+                }
+                else {
+                    errorMessage = JSON.stringify(event.error);
+                }
+                if ("type" in event.error) {
+                    errorType = String(event.error.type);
+                }
+            }
+        }
+        // Use same trace context as the transaction for correlation (if available)
+        const traceId = transaction
+            ? transaction.contexts.trace.trace_id
+            : traceContext.getTraceId(event.sessionId);
+        const spanId = traceContext.getSpanId(event.id);
+        const timestamp = transaction
+            ? transaction.timestamp
+            : event.timestamp
+                ? new Date(event.timestamp).getTime() / 1000
+                : Date.now() / 1000;
+        const errorEvent = {
+            type: "event",
+            event_id: traceContext.getSpanId(event.id) + traceContext.getSpanId(),
+            timestamp,
+            level: "error",
+            exception: {
+                values: [
+                    {
+                        type: errorType,
+                        value: errorMessage,
+                        mechanism: {
+                            type: "mcp_tool_call",
+                            handled: false,
+                        },
+                    },
+                ],
+            },
+            contexts: {
+                ...this.buildContexts(event, {
+                    trace_id: traceId,
+                    span_id: spanId,
+                    parent_span_id: transaction?.contexts.trace.span_id,
+                    op: transaction?.contexts.trace.op || event.eventType || "mcp.event",
+                }),
+                mcp: {
+                    resource_name: event.resourceName,
+                    session_id: event.sessionId,
+                    event_type: event.eventType,
+                    user_intent: event.userIntent,
+                },
+            },
+            tags: this.buildTags(event),
+            extra: this.buildExtra(event),
+            transaction: transaction?.transaction ||
+                (event.resourceName
+                    ? `${event.eventType || "mcp"} - ${event.resourceName}`
+                    : event.eventType || "mcp.event"), // Generate transaction name if not available
+        };
+        return errorEvent;
+    }
+    createTransactionEnvelope(transaction) {
+        // Envelope header
+        const envelopeHeader = {
+            event_id: transaction.event_id,
+            sent_at: new Date().toISOString(),
+        };
+        // Item header for transaction
+        const itemHeader = {
+            type: "transaction",
+        };
+        // Build envelope (newline-separated JSON)
+        return [
+            JSON.stringify(envelopeHeader),
+            JSON.stringify(itemHeader),
+            JSON.stringify(transaction),
+        ].join("\n");
+    }
+    createErrorEnvelope(errorEvent) {
+        // Envelope header
+        const envelopeHeader = {
+            event_id: errorEvent.event_id,
+            sent_at: new Date().toISOString(),
+        };
+        // Item header for error event
+        const itemHeader = {
+            type: "event",
+            content_type: "application/json",
+        };
+        // Build envelope (newline-separated JSON)
+        return [
+            JSON.stringify(envelopeHeader),
+            JSON.stringify(itemHeader),
+            JSON.stringify(errorEvent),
+        ].join("\n");
+    }
+}

package/dist/modules/exporters/trace-context.d.ts

@@ -0,0 +1,8 @@
+declare class TraceContext {
+    getTraceId(sessionId?: string): string;
+    getSpanId(eventId?: string): string;
+    getDatadogTraceId(sessionId?: string): string;
+    getDatadogSpanId(eventId?: string): string;
+}
+export declare const traceContext: TraceContext;
+export {};

package/dist/modules/exporters/trace-context.js

@@ -0,0 +1,27 @@
+import { createHash, randomBytes } from "crypto";
+class TraceContext {
+    getTraceId(sessionId) {
+        if (!sessionId) {
+            return randomBytes(16).toString("hex");
+        }
+        return createHash("sha256")
+            .update(sessionId)
+            .digest("hex")
+            .substring(0, 32);
+    }
+    getSpanId(eventId) {
+        if (!eventId) {
+            return randomBytes(8).toString("hex");
+        }
+        return createHash("sha256").update(eventId).digest("hex").substring(0, 16);
+    }
+    getDatadogTraceId(sessionId) {
+        const hex = this.getTraceId(sessionId);
+        return BigInt("0x" + hex.substring(16, 32)).toString();
+    }
+    getDatadogSpanId(eventId) {
+        const hex = this.getSpanId(eventId);
+        return BigInt("0x" + hex).toString();
+    }
+}
+export const traceContext = new TraceContext();

package/dist/modules/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./compatibility.js";
+export * from "./context-parameters.js";
+export * from "./exceptions.js";
+export * from "./internal.js";
+export * from "./logging.js";
+export * from "./session.js";
+export * from "./tools.js";
+export * from "./tracing.js";

package/dist/modules/index.js

@@ -0,0 +1,8 @@
+export * from "./compatibility.js";
+export * from "./context-parameters.js";
+export * from "./exceptions.js";
+export * from "./internal.js";
+export * from "./logging.js";
+export * from "./session.js";
+export * from "./tools.js";
+export * from "./tracing.js";

package/dist/modules/internal.d.ts

@@ -0,0 +1,33 @@
+import { WithinTrackingData, MCPServerLike, UserIdentity, CompatibleRequestHandlerExtra } from "../types.js";
+export declare function getServerTrackingData(server: MCPServerLike): WithinTrackingData | undefined;
+export declare function setServerTrackingData(server: MCPServerLike, data: WithinTrackingData): void;
+/**
+ * Deep comparison of two UserIdentity objects
+ */
+export declare function areIdentitiesEqual(a: UserIdentity, b: UserIdentity): boolean;
+/**
+ * Merges two UserIdentity objects, overwriting userId and userName,
+ * but merging userData fields
+ */
+export declare function mergeIdentities(previous: UserIdentity | undefined, next: UserIdentity): UserIdentity;
+/**
+ * Handles user identification for a request.
+ * Calls the identify function if configured, compares with previous identity,
+ * and publishes an identify event only if the identity has changed.
+ *
+ * @param server - The MCP server instance
+ * @param data - The server tracking data
+ * @param request - The request object to pass to identify function
+ * @param extra - Optional extra parameters containing headers, sessionId, etc.
+ */
+export declare function handleIdentify(server: MCPServerLike, data: WithinTrackingData, request: any, extra?: CompatibleRequestHandlerExtra): Promise<void>;
+/**
+ * Resolves the eventTags callback, validates the result, and returns validated tags.
+ * Returns null if no callback configured, callback returns nullish, or callback throws.
+ */
+export declare function resolveEventTags(data: WithinTrackingData, request: any, extra?: CompatibleRequestHandlerExtra): Promise<Record<string, string> | null>;
+/**
+ * Resolves the eventProperties callback and returns the result.
+ * Returns null if no callback configured, callback returns nullish, or callback throws.
+ */
+export declare function resolveEventProperties(data: WithinTrackingData, request: any, extra?: CompatibleRequestHandlerExtra): Promise<Record<string, any> | null>;

package/dist/modules/internal.js

@@ -0,0 +1,195 @@
+import { publishEvent } from "./eventQueue.js";
+import { writeToLog } from "./logging.js";
+import { validateTags } from "./validation.js";
+import { WithinEventType } from "./constants.js";
+import { sanitizeIdentity } from "./privacy.js";
+/**
+ * Simple LRU cache for session identities.
+ * Prevents memory leaks by capping at maxSize entries.
+ * This cache persists across server instance restarts.
+ */
+class IdentityCache {
+    cache;
+    maxSize;
+    constructor(maxSize = 1000) {
+        this.cache = new Map();
+        this.maxSize = maxSize;
+    }
+    get(sessionId) {
+        const entry = this.cache.get(sessionId);
+        if (entry) {
+            // Update timestamp on access (LRU behavior)
+            entry.timestamp = Date.now();
+            // Move to end (most recently used)
+            this.cache.delete(sessionId);
+            this.cache.set(sessionId, entry);
+            return entry.identity;
+        }
+        return undefined;
+    }
+    set(sessionId, identity) {
+        // Remove if already exists (to re-add at end)
+        this.cache.delete(sessionId);
+        // Evict oldest if at capacity
+        if (this.cache.size >= this.maxSize) {
+            const oldestKey = this.cache.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        this.cache.set(sessionId, { identity, timestamp: Date.now() });
+    }
+    has(sessionId) {
+        return this.cache.has(sessionId);
+    }
+    size() {
+        return this.cache.size;
+    }
+}
+// Global identity cache shared across all server instances
+// This prevents duplicate identify events when server objects are recreated
+const _globalIdentityCache = new IdentityCache(1000);
+// Internal tracking storage
+const _serverTracking = new WeakMap();
+export function getServerTrackingData(server) {
+    return _serverTracking.get(server);
+}
+export function setServerTrackingData(server, data) {
+    _serverTracking.set(server, data);
+}
+/**
+ * Deep comparison of two UserIdentity objects
+ */
+export function areIdentitiesEqual(a, b) {
+    if (a.userId !== b.userId)
+        return false;
+    if (a.userName !== b.userName)
+        return false;
+    // Deep compare userData objects
+    const aData = a.userData || {};
+    const bData = b.userData || {};
+    const aKeys = Object.keys(aData);
+    const bKeys = Object.keys(bData);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const key of aKeys) {
+        if (!(key in bData))
+            return false;
+        if (JSON.stringify(aData[key]) !== JSON.stringify(bData[key]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Merges two UserIdentity objects, overwriting userId and userName,
+ * but merging userData fields
+ */
+export function mergeIdentities(previous, next) {
+    if (!previous) {
+        return next;
+    }
+    return {
+        userId: next.userId,
+        userName: next.userName,
+        userData: {
+            ...(previous.userData || {}),
+            ...(next.userData || {}),
+        },
+    };
+}
+/**
+ * Handles user identification for a request.
+ * Calls the identify function if configured, compares with previous identity,
+ * and publishes an identify event only if the identity has changed.
+ *
+ * @param server - The MCP server instance
+ * @param data - The server tracking data
+ * @param request - The request object to pass to identify function
+ * @param extra - Optional extra parameters containing headers, sessionId, etc.
+ */
+export async function handleIdentify(server, data, request, extra) {
+    if (!data.options.identify) {
+        return;
+    }
+    const sessionId = data.sessionId;
+    let identifyEvent = {
+        sessionId: sessionId,
+        resourceName: request.params?.name || "Unknown",
+        eventType: WithinEventType.identify,
+        parameters: {
+            request: request,
+            extra: extra,
+        },
+        timestamp: new Date(),
+        redactionFn: data.options.redactSensitiveInformation,
+    };
+    try {
+        const rawIdentity = await data.options.identify(request, extra);
+        const identityResult = rawIdentity
+            ? sanitizeIdentity(data.vendorSlug, rawIdentity, data.options.privacy)
+            : null;
+        if (identityResult) {
+            // Now use the (possibly updated) sessionId for all subsequent operations
+            const currentSessionId = data.sessionId;
+            // Check global cache first (works across server instance restarts)
+            const previousIdentity = _globalIdentityCache.get(currentSessionId);
+            // Merge identities (overwrite userId/userName, merge userData)
+            const mergedIdentity = mergeIdentities(previousIdentity, identityResult);
+            // Only publish if identity has changed
+            const hasChanged = !previousIdentity ||
+                !areIdentitiesEqual(previousIdentity, mergedIdentity);
+            // Update BOTH caches to keep them in sync
+            // Global cache: persists across server instances
+            _globalIdentityCache.set(currentSessionId, mergedIdentity);
+            // Per-server cache: used by getSessionInfo() for fast local access
+            data.identifiedSessions.set(data.sessionId, mergedIdentity);
+            data.sessionInfo.identifyActorGivenId = mergedIdentity.userId;
+            data.sessionInfo.identifyActorName = undefined;
+            data.sessionInfo.identifyActorData = mergedIdentity.userData || {};
+            setServerTrackingData(server, data);
+            if (hasChanged) {
+                writeToLog(`Identified session ${currentSessionId} (actor: ${mergedIdentity.userId})`);
+                publishEvent(server, identifyEvent);
+            }
+        }
+        else {
+            writeToLog(`Warning: Supplied identify function returned null for session ${sessionId}`);
+        }
+    }
+    catch (error) {
+        writeToLog(`Error: User supplied identify function threw an error while identifying session ${sessionId} - ${error}`);
+    }
+}
+/**
+ * Resolves the eventTags callback, validates the result, and returns validated tags.
+ * Returns null if no callback configured, callback returns nullish, or callback throws.
+ */
+export async function resolveEventTags(data, request, extra) {
+    if (!data.options.eventTags)
+        return null;
+    try {
+        const raw = (await data.options.eventTags(request, extra)) ?? null;
+        if (!raw)
+            return null;
+        return validateTags(raw);
+    }
+    catch (e) {
+        writeToLog(`eventTags callback error: ${e}`);
+        return null;
+    }
+}
+/**
+ * Resolves the eventProperties callback and returns the result.
+ * Returns null if no callback configured, callback returns nullish, or callback throws.
+ */
+export async function resolveEventProperties(data, request, extra) {
+    if (!data.options.eventProperties)
+        return null;
+    try {
+        return (await data.options.eventProperties(request, extra)) ?? null;
+    }
+    catch (e) {
+        writeToLog(`eventProperties callback error: ${e}`);
+        return null;
+    }
+}

package/dist/modules/logging.d.ts

@@ -0,0 +1,2 @@
+export declare function setDiagnosticsSink(fn: ((entry: string) => void) | null): void;
+export declare function writeToLog(message: string): void;