within-sdk 1.0.0

package/dist/modules/constants.d.ts

@@ -0,0 +1,12 @@
+export declare const SDK_VERSION = "1.0.0";
+export declare const DEFAULT_WITHIN_INGEST_URL = "https://hf3tic2qk3.us-east-2.awsapprunner.com";
+export declare const INACTIVITY_TIMEOUT_IN_MINUTES = 30;
+export declare const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = "Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): \"Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization.\"";
+export declare const WITHIN_CUSTOM_EVENT_TYPE = "within:custom";
+export declare const WITHIN_SOURCE = "within";
+export declare const WithinEventType: {
+    readonly mcpInitialize: "mcp:initialize";
+    readonly mcpToolsList: "mcp:tools/list";
+    readonly mcpToolsCall: "mcp:tools/call";
+    readonly identify: "within:identify";
+};

package/dist/modules/constants.js

@@ -0,0 +1,12 @@
+export const SDK_VERSION = "1.0.0";
+export const DEFAULT_WITHIN_INGEST_URL = "https://hf3tic2qk3.us-east-2.awsapprunner.com";
+export const INACTIVITY_TIMEOUT_IN_MINUTES = 30;
+export const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = `Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): "Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization."`;
+export const WITHIN_CUSTOM_EVENT_TYPE = "within:custom";
+export const WITHIN_SOURCE = "within";
+export const WithinEventType = {
+    mcpInitialize: "mcp:initialize",
+    mcpToolsList: "mcp:tools/list",
+    mcpToolsCall: "mcp:tools/call",
+    identify: "within:identify",
+};

package/dist/modules/context-parameters.d.ts

@@ -0,0 +1,13 @@
+import { RegisteredTool } from "../types.js";
+/**
+ * Adds a context parameter to a tool's JSON Schema.
+ * This function is called AFTER the MCP SDK has converted Zod schemas to JSON Schema,
+ * so we only need to handle JSON Schema format.
+ *
+ * Skips injection (with warning) for:
+ * - Tools that already have a 'context' parameter
+ * - Complex schemas (oneOf/allOf/anyOf) that can't safely have properties added
+ * - Schemas with additionalProperties: false
+ */
+export declare function addContextParameterToTool(tool: RegisteredTool, customContextDescription?: string): RegisteredTool;
+export declare function addContextParameterToTools(tools: RegisteredTool[], customContextDescription?: string): RegisteredTool[];

package/dist/modules/context-parameters.js

@@ -0,0 +1,74 @@
+import { DEFAULT_CONTEXT_PARAMETER_DESCRIPTION } from "./constants.js";
+import { writeToLog } from "./logging.js";
+/**
+ * Adds a context parameter to a tool's JSON Schema.
+ * This function is called AFTER the MCP SDK has converted Zod schemas to JSON Schema,
+ * so we only need to handle JSON Schema format.
+ *
+ * Skips injection (with warning) for:
+ * - Tools that already have a 'context' parameter
+ * - Complex schemas (oneOf/allOf/anyOf) that can't safely have properties added
+ * - Schemas with additionalProperties: false
+ */
+export function addContextParameterToTool(tool, customContextDescription) {
+    // Create a shallow copy of the tool to avoid modifying the original
+    const modifiedTool = { ...tool };
+    const toolName = tool.name || "unknown";
+    const schema = modifiedTool.inputSchema;
+    // Check if tool already has context parameter - skip to avoid collision
+    if (schema?.properties?.context) {
+        writeToLog(`WARN: Tool "${toolName}" already has 'context' parameter. Skipping context injection.`);
+        return modifiedTool;
+    }
+    // Skip complex schemas that can't safely have properties added at root level
+    if (schema?.oneOf || schema?.allOf || schema?.anyOf) {
+        writeToLog(`WARN: Tool "${toolName}" has complex schema (oneOf/allOf/anyOf). Skipping context injection.`);
+        return modifiedTool;
+    }
+    // Note: If additionalProperties is false, we'll need to remove that constraint
+    // when adding context, otherwise the schema would be invalid. We handle this
+    // after the deep copy below.
+    if (!modifiedTool.inputSchema) {
+        modifiedTool.inputSchema = {
+            type: "object",
+            properties: {},
+            required: [],
+        };
+    }
+    const contextDescription = customContextDescription || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION;
+    // Deep copy the inputSchema to avoid mutations
+    modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema));
+    // Ensure properties object exists
+    if (!modifiedTool.inputSchema.properties) {
+        modifiedTool.inputSchema.properties = {};
+    }
+    // Handle additionalProperties: false - must remove this constraint since we're adding context
+    // The MCP SDK adds this constraint when converting Zod schemas to JSON Schema
+    if (modifiedTool.inputSchema.additionalProperties === false) {
+        delete modifiedTool.inputSchema.additionalProperties;
+    }
+    // Add context property
+    modifiedTool.inputSchema.properties.context = {
+        type: "string",
+        description: contextDescription,
+    };
+    // Add context to required array
+    if (Array.isArray(modifiedTool.inputSchema.required)) {
+        if (!modifiedTool.inputSchema.required.includes("context")) {
+            modifiedTool.inputSchema.required.push("context");
+        }
+    }
+    else {
+        modifiedTool.inputSchema.required = ["context"];
+    }
+    return modifiedTool;
+}
+export function addContextParameterToTools(tools, customContextDescription) {
+    return tools.map((tool) => {
+        // Skip get_more_tools - it has its own special context parameter
+        if (tool.name === "get_more_tools") {
+            return tool;
+        }
+        return addContextParameterToTool(tool, customContextDescription);
+    });
+}

package/dist/modules/diagnostics.d.ts

@@ -0,0 +1,7 @@
+export declare function initDiagnostics(_opts: {
+    projectId: string | null;
+    disabled?: boolean;
+}): void;
+export declare function flushDiagnostics(): Promise<void>;
+export declare function isDiagnosticsEnabled(): boolean;
+export declare function _resetDiagnosticsForTest(): void;

package/dist/modules/diagnostics.js

@@ -0,0 +1,12 @@
+export function initDiagnostics(_opts) {
+    // Within does not send SDK diagnostics to a third-party collector.
+}
+export async function flushDiagnostics() {
+    // Local logging is handled by logging.ts; there is no network flush.
+}
+export function isDiagnosticsEnabled() {
+    return false;
+}
+export function _resetDiagnosticsForTest() {
+    // no-op
+}

package/dist/modules/eventQueue.d.ts

@@ -0,0 +1,32 @@
+import { UnredactedEvent, MCPServerLike } from "../types.js";
+import { TelemetryManager } from "./telemetry.js";
+interface QueueConfig {
+    maxRetries?: number;
+    maxQueueSize?: number;
+    concurrency?: number;
+}
+declare class EventQueue {
+    private queue;
+    private processing;
+    private maxRetries;
+    private maxQueueSize;
+    private concurrency;
+    private activeRequests;
+    private telemetryManager?;
+    configure(config?: QueueConfig): void;
+    setTelemetryManager(telemetryManager: TelemetryManager): void;
+    add(event: UnredactedEvent): void;
+    private process;
+    private sendEvent;
+    private delay;
+    getStats(): {
+        queueLength: number;
+        activeRequests: number;
+        isProcessing: boolean;
+    };
+    destroy(): Promise<void>;
+}
+export declare const eventQueue: EventQueue;
+export declare function setTelemetryManager(telemetryManager: TelemetryManager): void;
+export declare function publishEvent(server: MCPServerLike, eventInput: UnredactedEvent): void;
+export {};

package/dist/modules/eventQueue.js

@@ -0,0 +1,234 @@
+import { writeToLog } from "./logging.js";
+import { getServerTrackingData } from "./internal.js";
+import { getSessionInfo } from "./session.js";
+import { redactEvent } from "./redaction.js";
+import { sanitizeEvent } from "./sanitization.js";
+import { truncateEvent } from "./truncation.js";
+import { redactWithinValue, stripForbiddenIdentityFields } from "./privacy.js";
+import KSUID from "../thirdparty/ksuid/index.js";
+import { getMCPCompatibleErrorMessage } from "./compatibility.js";
+import { flushDiagnostics } from "./diagnostics.js";
+import { SDK_VERSION } from "./constants.js";
+class EventQueue {
+    queue = [];
+    processing = false;
+    maxRetries = 3;
+    maxQueueSize = 10000;
+    concurrency = 5;
+    activeRequests = 0;
+    telemetryManager;
+    configure(config = {}) {
+        if (config.maxRetries !== undefined)
+            this.maxRetries = config.maxRetries;
+        if (config.maxQueueSize !== undefined)
+            this.maxQueueSize = config.maxQueueSize;
+        if (config.concurrency !== undefined)
+            this.concurrency = config.concurrency;
+    }
+    setTelemetryManager(telemetryManager) {
+        this.telemetryManager = telemetryManager;
+    }
+    add(event) {
+        if (this.queue.length >= this.maxQueueSize) {
+            writeToLog("Event queue full, dropping oldest event");
+            this.queue.shift();
+        }
+        this.queue.push(event);
+        this.process();
+    }
+    async process() {
+        if (this.processing)
+            return;
+        this.processing = true;
+        while (this.queue.length > 0 && this.activeRequests < this.concurrency) {
+            const event = this.queue.shift();
+            if (!event)
+                continue;
+            try {
+                if (event.redactionFn) {
+                    const redactedEvent = await redactEvent(event, event.redactionFn);
+                    event.redactionFn = undefined;
+                    Object.assign(event, redactedEvent);
+                }
+                Object.assign(event, applyWithinPrivacy(event));
+                Object.assign(event, sanitizeEvent(event));
+                Object.assign(event, truncateEvent(event));
+            }
+            catch (error) {
+                writeToLog(`Failed to sanitize event: ${error}`);
+                continue;
+            }
+            event.id = event.id || (await KSUID.withPrefix("evt").random());
+            this.activeRequests++;
+            this.sendEvent(event).finally(() => {
+                this.activeRequests--;
+                this.process();
+            });
+        }
+        this.processing = false;
+    }
+    async sendEvent(event, retries = 0) {
+        const exportable = toExportableEvent(event);
+        if (this.telemetryManager) {
+            this.telemetryManager.export(exportable).catch((error) => {
+                writeToLog(`Telemetry export error: ${getMCPCompatibleErrorMessage(error)}`);
+            });
+        }
+        if (!event.vendorSlug || !event.apiKey || !event.ingestBaseUrl) {
+            writeToLog(`Within event ${event.id} not sent: vendor slug or API key missing`);
+            return;
+        }
+        try {
+            await postEvent(event);
+            writeToLog(`Successfully sent event ${event.id} | ${event.eventType} | session ${event.sessionId} | ${event.vendorSlug} | ${event.duration} ms | ${event.identifyActorGivenId || "anonymous"}`);
+        }
+        catch (error) {
+            writeToLog(`Failed to send event ${event.id}, retrying... [Error: ${getMCPCompatibleErrorMessage(error)}]`);
+            if (retries < this.maxRetries) {
+                await this.delay(Math.pow(2, retries) * 1000);
+                return this.sendEvent(event, retries + 1);
+            }
+        }
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    getStats() {
+        return {
+            queueLength: this.queue.length,
+            activeRequests: this.activeRequests,
+            isProcessing: this.processing,
+        };
+    }
+    async destroy() {
+        this.add = () => {
+            writeToLog("Queue is shutting down, event dropped");
+        };
+        const timeout = 5000;
+        const start = Date.now();
+        while ((this.queue.length > 0 || this.activeRequests > 0) &&
+            Date.now() - start < timeout) {
+            await this.delay(100);
+        }
+        if (this.queue.length > 0) {
+            writeToLog(`Shutting down with ${this.queue.length} events still in queue`);
+        }
+    }
+}
+export const eventQueue = new EventQueue();
+try {
+    if (typeof process !== "undefined" && typeof process.once === "function") {
+        const shutdown = () => {
+            void eventQueue.destroy();
+            void flushDiagnostics();
+        };
+        process.once("SIGINT", shutdown);
+        process.once("SIGTERM", shutdown);
+        process.once("beforeExit", shutdown);
+    }
+}
+catch {
+    // Signal hooks are unavailable in some edge runtimes.
+}
+export function setTelemetryManager(telemetryManager) {
+    eventQueue.setTelemetryManager(telemetryManager);
+}
+export function publishEvent(server, eventInput) {
+    const data = getServerTrackingData(server);
+    if (!data) {
+        writeToLog("Warning: Server tracking data not found. Event will not be published.");
+        return;
+    }
+    if (!data.options.enableTracing) {
+        return;
+    }
+    const sessionInfo = getSessionInfo(server, data);
+    const duration = eventInput.duration ||
+        (eventInput.timestamp
+            ? new Date().getTime() - eventInput.timestamp.getTime()
+            : undefined);
+    const fullEvent = {
+        id: eventInput.id || "",
+        sessionId: eventInput.sessionId || data.sessionId,
+        projectId: data.vendorSlug,
+        vendorSlug: data.vendorSlug,
+        apiKey: data.apiKey,
+        ingestBaseUrl: data.ingestBaseUrl,
+        fetchImpl: data.fetchImpl,
+        eventType: eventInput.eventType || "",
+        timestamp: eventInput.timestamp || new Date(),
+        duration,
+        ipAddress: sessionInfo.ipAddress,
+        sdkLanguage: sessionInfo.sdkLanguage,
+        sdkVersion: SDK_VERSION,
+        serverName: sessionInfo.serverName,
+        serverVersion: sessionInfo.serverVersion,
+        clientName: sessionInfo.clientName,
+        clientVersion: sessionInfo.clientVersion,
+        identifyActorGivenId: sessionInfo.identifyActorGivenId,
+        identifyActorData: sessionInfo.identifyActorData,
+        resourceName: eventInput.resourceName,
+        parameters: eventInput.parameters,
+        response: eventInput.response,
+        userIntent: eventInput.userIntent,
+        isError: eventInput.isError,
+        error: eventInput.error,
+        redactionFn: eventInput.redactionFn,
+        tags: eventInput.tags,
+        properties: eventInput.properties,
+    };
+    eventQueue.add(fullEvent);
+}
+function applyWithinPrivacy(event) {
+    const out = { ...event };
+    delete out.identifyActorName;
+    delete out.actorId;
+    delete out.identifyData;
+    if (out.identifyActorData) {
+        out.identifyActorData = redactWithinValue(out.identifyActorData);
+    }
+    if (out.parameters !== undefined)
+        out.parameters = redactWithinValue(out.parameters);
+    if (out.response !== undefined)
+        out.response = redactWithinValue(out.response);
+    if (out.error !== undefined)
+        out.error = redactWithinValue(out.error);
+    if (out.properties !== undefined)
+        out.properties = redactWithinValue(out.properties);
+    if (out.tags !== undefined)
+        out.tags = redactWithinValue(out.tags);
+    return stripForbiddenIdentityFields(out);
+}
+function toExportableEvent(event) {
+    const { apiKey: _apiKey, ingestBaseUrl: _ingestBaseUrl, fetchImpl: _fetchImpl, ...safe } = event;
+    return safe;
+}
+async function postEvent(event) {
+    const fetchImpl = event.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    const base = event.ingestBaseUrl.replace(/\/+$/, "");
+    const payloadEvent = toExportableEvent(event);
+    const res = await fetchImpl(`${base}/api/sdk/events`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${event.apiKey}`,
+            "x-within-sdk": "within-sdk",
+        },
+        body: JSON.stringify({
+            vendor_slug: event.vendorSlug,
+            sdk_version: SDK_VERSION,
+            events: [payloadEvent],
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status}: ${await safeText(res)}`);
+    }
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}

package/dist/modules/exceptions.d.ts

@@ -0,0 +1,13 @@
+import { ErrorData } from "../types.js";
+/**
+ * Captures detailed exception information including stack traces and cause chains.
+ *
+ * This function extracts error metadata (type, message, stack trace) and recursively
+ * unwraps Error.cause chains. It parses V8 stack traces into structured frames and
+ * detects whether each frame is user code (in_app: true) or library code (in_app: false).
+ *
+ * @param error - The error to capture (can be Error, string, object, or any value)
+ * @param contextStack - Optional Error object to use for stack context (for validation errors)
+ * @returns ErrorData object with structured error information
+ */
+export declare function captureException(error: unknown, contextStack?: Error): ErrorData;