within-sdk 1.0.0

package/LICENSE

@@ -0,0 +1 @@
+MIT

package/README.md

@@ -0,0 +1,77 @@
+# Within SDK
+
+MCP analytics and workflow-intelligence SDK for Within.
+
+```ts
+import { track } from "within-sdk";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+const server = new McpServer({ name: "acme-mcp", version: "1.0.0" });
+
+track(server, "acme", {
+  apiKey: process.env.WITHIN_SDK_API_KEY!,
+  identify: async (request) => {
+    const user = await lookupUser(request);
+    return {
+      userId: user.internalCustomerId,
+      userData: {
+        plan: user.plan,
+        segment: user.segment,
+      },
+    };
+  },
+});
+```
+
+`track(server, vendorSlug, options)` instruments MCP initialize, tools/list, and
+tools/call activity. The default instrumentation includes:
+
+- tracing is enabled
+- tool-call `context` capture is enabled
+- the `get_more_tools` feedback tool is enabled
+
+Events are posted only to Within. `options.apiBaseUrl` overrides the default
+ingestion host; otherwise the SDK checks `WITHIN_SDK_API_URL`, then
+`WITHIN_SDK_INGEST_BASE_URL`.
+
+## Privacy
+
+`identify()` keeps the existing public shape, while Within hashes `userId` locally
+with the vendor slug before enqueueing or posting telemetry. Raw `userId` and
+`userName` are not sent. `userData`, parameters, responses, tags, and properties
+are stripped of direct identity fields and redacted/truncated before they reach
+Within or vendor-configured exporters.
+
+Within ingestion also runs server-side Presidio redaction before SDK
+activity is stored. The first deployment is model-free: it uses Presidio
+rule/checksum/pattern recognizers for values such as emails, phones, SSNs,
+card-like values, URLs, IPs, bearer tokens, API keys, and secrets. It does not
+claim guaranteed detection of arbitrary names or locations without a later
+model-backed recognizer profile.
+
+## Conversion Reporting
+
+Report confirmed lead-to-subscriber conversion from trusted server-side code:
+
+```ts
+import { reportConversion } from "within-sdk";
+
+await reportConversion({
+  vendorSlug: "acme",
+  apiKey: process.env.WITHIN_SDK_API_KEY!,
+}, {
+  subject: user.internalCustomerId,
+  convertedAt: new Date(),
+  plan: {
+    id: "pro",
+    name: "Pro",
+    interval: "month",
+  },
+  metadata: {
+    source: "checkout_webhook",
+  },
+});
+```
+
+Conversion reporting hashes the subject locally and sends only the hash to
+Within.

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { CustomEventData, WithinConversionInput, WithinConversionResult, WithinOptions } from "./types.js";
+import { hashWithinSubject } from "./modules/privacy.js";
+export type { CustomEventData, Exporter, ExporterConfig, MCPServerLike, RedactFunction, UserIdentity, WithinConversionInput, WithinConversionPlan, WithinConversionResult, WithinOptions, } from "./types.js";
+export { hashWithinSubject };
+export interface ReportConversionConfig {
+    vendorSlug: string;
+    apiKey: string;
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+    privacy?: WithinOptions["privacy"];
+}
+declare function track(server: any, vendorSlug: string, options?: WithinOptions): any;
+export declare function publishCustomEvent(serverOrSessionId: any | string, vendorSlug: string, eventData?: CustomEventData): Promise<void>;
+export declare function reportConversion(config: ReportConversionConfig, input: WithinConversionInput): Promise<WithinConversionResult>;
+export type IdentifyFunction = WithinOptions["identify"];
+export { track };

package/dist/index.js

@@ -0,0 +1,243 @@
+import { isCompatibleServerType, isHighLevelServer, } from "./modules/compatibility.js";
+import { writeToLog } from "./modules/logging.js";
+import { setupWithinFeedbackTools } from "./modules/tools.js";
+import { setupToolCallTracing } from "./modules/tracing.js";
+import { getSessionInfo, newSessionId, deriveSessionIdFromMCPSession, } from "./modules/session.js";
+import { setServerTrackingData, getServerTrackingData, } from "./modules/internal.js";
+import { setupTracking } from "./modules/tracingV2.js";
+import { TelemetryManager } from "./modules/telemetry.js";
+import { setTelemetryManager, eventQueue, } from "./modules/eventQueue.js";
+import { DEFAULT_WITHIN_INGEST_URL, SDK_VERSION, WITHIN_CUSTOM_EVENT_TYPE, } from "./modules/constants.js";
+import { validateTags } from "./modules/validation.js";
+import { initDiagnostics } from "./modules/diagnostics.js";
+import { hashWithinSubject, redactWithinValue } from "./modules/privacy.js";
+export { hashWithinSubject };
+function track(server, vendorSlug, options = {}) {
+    try {
+        if (!vendorSlug || typeof vendorSlug !== "string") {
+            throw new Error("vendorSlug is required");
+        }
+        initDiagnostics({
+            projectId: vendorSlug,
+            disabled: true,
+        });
+        const validatedServer = isCompatibleServerType(server);
+        const isHighLevel = isHighLevelServer(validatedServer);
+        const lowLevelServer = (isHighLevel ? validatedServer.server : validatedServer);
+        writeToLog(`Within SDK setup started | vendor ${vendorSlug} | server ${isHighLevel ? "high-level" : "low-level"}`);
+        const existingData = getServerTrackingData(lowLevelServer);
+        if (existingData) {
+            writeToLog("[SESSION DEBUG] track() - Server already being tracked, skipping initialization");
+            return validatedServer;
+        }
+        if (options.exporters) {
+            const telemetryManager = new TelemetryManager(options.exporters);
+            setTelemetryManager(telemetryManager);
+            writeToLog(`Initialized telemetry with ${Object.keys(options.exporters).length} exporters`);
+        }
+        const apiKey = options.apiKey ?? readEnv("WITHIN_SDK_API_KEY") ?? readEnv("WITHIN_SDK_INGEST_KEY");
+        if (!apiKey && !options.exporters) {
+            writeToLog("Warning: No Within apiKey provided and no exporters configured. Events will not be sent anywhere.");
+        }
+        eventQueue.configure();
+        const sessionInfo = getSessionInfo(lowLevelServer, undefined);
+        const withinData = {
+            projectId: vendorSlug,
+            vendorSlug,
+            apiKey,
+            ingestBaseUrl: resolveIngestBaseUrl(options.apiBaseUrl),
+            fetchImpl: options.fetch ?? globalThis.fetch.bind(globalThis),
+            sessionId: newSessionId(),
+            lastActivity: new Date(),
+            identifiedSessions: new Map(),
+            sessionInfo,
+            options: {
+                ...options,
+                apiKey,
+                enableReportMissing: options.enableReportMissing ?? true,
+                enableTracing: options.enableTracing ?? true,
+                enableToolCallContext: options.enableToolCallContext ?? true,
+                customContextDescription: options.customContextDescription,
+                identify: options.identify,
+                redactSensitiveInformation: options.redactSensitiveInformation,
+                eventTags: options.eventTags,
+                eventProperties: options.eventProperties,
+            },
+            sessionSource: "within",
+        };
+        setServerTrackingData(lowLevelServer, withinData);
+        if (isHighLevel) {
+            setupTracking(validatedServer);
+        }
+        else {
+            if (withinData.options.enableReportMissing) {
+                try {
+                    setupWithinFeedbackTools(lowLevelServer);
+                }
+                catch (error) {
+                    writeToLog(`Warning: Failed to setup report missing tool - ${error}`);
+                }
+            }
+            if (withinData.options.enableTracing) {
+                try {
+                    setupToolCallTracing(lowLevelServer);
+                }
+                catch (error) {
+                    writeToLog(`Warning: Failed to setup tool call tracing - ${error}`);
+                }
+            }
+        }
+        const exporterCount = options.exporters
+            ? Object.keys(options.exporters).length
+            : 0;
+        writeToLog(`Within SDK setup complete | vendor ${vendorSlug} | tracing=${withinData.options.enableTracing} context=${withinData.options.enableToolCallContext} reportMissing=${withinData.options.enableReportMissing} exporters=${exporterCount}`);
+        return validatedServer;
+    }
+    catch (error) {
+        writeToLog(`Warning: Failed to track server - ${error}`);
+        return server;
+    }
+}
+export async function publishCustomEvent(serverOrSessionId, vendorSlug, eventData) {
+    if (!vendorSlug) {
+        throw new Error("vendorSlug is required for publishCustomEvent");
+    }
+    let sessionId;
+    let data;
+    const isServer = typeof serverOrSessionId === "object" && serverOrSessionId !== null;
+    if (isServer) {
+        const lowLevelServer = serverOrSessionId.server
+            ? serverOrSessionId.server
+            : serverOrSessionId;
+        data = getServerTrackingData(lowLevelServer);
+        if (!data) {
+            throw new Error("Server is not tracked. Please call track() first or provide a session ID string with eventData.apiKey.");
+        }
+        sessionId = data.sessionId;
+    }
+    else if (typeof serverOrSessionId === "string") {
+        sessionId = deriveSessionIdFromMCPSession(serverOrSessionId, vendorSlug);
+    }
+    else {
+        throw new Error("First parameter must be either an MCP server object or a session ID string");
+    }
+    const event = {
+        sessionId,
+        projectId: vendorSlug,
+        vendorSlug: data?.vendorSlug ?? vendorSlug,
+        apiKey: data?.apiKey ?? eventData?.apiKey,
+        ingestBaseUrl: data?.ingestBaseUrl ?? resolveIngestBaseUrl(eventData?.apiBaseUrl),
+        fetchImpl: data?.fetchImpl ?? eventData?.fetch ?? globalThis.fetch.bind(globalThis),
+        eventType: WITHIN_CUSTOM_EVENT_TYPE,
+        timestamp: new Date(),
+        resourceName: eventData?.resourceName,
+        parameters: eventData?.parameters,
+        response: eventData?.response,
+        userIntent: eventData?.message,
+        duration: eventData?.duration,
+        isError: eventData?.isError,
+        error: eventData?.error,
+    };
+    if (eventData?.tags) {
+        event.tags = validateTags(eventData.tags);
+    }
+    if (eventData?.properties && Object.keys(eventData.properties).length > 0) {
+        event.properties = eventData.properties;
+    }
+    eventQueue.add(event);
+    writeToLog(`Published custom event for session ${sessionId} with type '${WITHIN_CUSTOM_EVENT_TYPE}'`);
+}
+export async function reportConversion(config, input) {
+    const subject = normalizeSubject(input.subject);
+    if (!subject) {
+        throw new Error("within-sdk conversion subject is required");
+    }
+    const convertedAt = normalizeConversionTimestamp(input.convertedAt);
+    const conversionUtcDate = convertedAt.slice(0, 10);
+    const fetchImpl = config.fetch ?? globalThis.fetch.bind(globalThis);
+    const body = {
+        vendor_slug: config.vendorSlug,
+        subject_hash: hashWithinSubject(config.vendorSlug, subject),
+        converted_at: convertedAt,
+        conversion_utc_date: conversionUtcDate,
+        plan: normalizeConversionPlan(input.plan),
+        metadata: redactWithinValue(input.metadata, config.privacy),
+        sdk_version: SDK_VERSION,
+    };
+    const res = await fetchImpl(`${resolveIngestBaseUrl(config.apiBaseUrl)}/api/sdk/conversions`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${config.apiKey}`,
+            "x-within-sdk": "within-sdk",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status}: ${await safeText(res)}`);
+    }
+    return await safeJson(res);
+}
+function resolveIngestBaseUrl(explicit) {
+    return trimTrailingSlash(explicit
+        ?? readEnv("WITHIN_SDK_API_URL")
+        ?? readEnv("WITHIN_SDK_INGEST_BASE_URL")
+        ?? DEFAULT_WITHIN_INGEST_URL);
+}
+function readEnv(name) {
+    try {
+        const value = globalThis.process?.env?.[name]?.trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function normalizeConversionTimestamp(value) {
+    if (!value)
+        return new Date().toISOString();
+    const date = value instanceof Date ? value : new Date(value);
+    if (!Number.isFinite(date.getTime())) {
+        throw new Error("within-sdk conversion convertedAt must be a valid date");
+    }
+    return date.toISOString();
+}
+function normalizeConversionPlan(plan) {
+    if (!plan || typeof plan !== "object")
+        return undefined;
+    const out = {
+        id: normalizePlanField(plan.id),
+        name: normalizePlanField(plan.name),
+        interval: normalizePlanField(plan.interval),
+    };
+    return out.id || out.name || out.interval ? out : undefined;
+}
+function normalizePlanField(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim().slice(0, 200)
+        : undefined;
+}
+function normalizeSubject(subject) {
+    const normalized = subject?.trim();
+    return normalized ? normalized : null;
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+async function safeJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return undefined;
+    }
+}
+export { track };

package/dist/middleware.d.ts

@@ -0,0 +1,40 @@
+/**
+ * With.in MCP Auth SDK — sealed request handler.
+ *
+ * Exposes ONE function, `createWithinHandler`, that returns a handler with:
+ *   - `mcpHandler(req, res)`   — node HTTP handler for the MCP endpoint
+ *   - `subscribeHandler(req,res)` — node HTTP handler for the /subscribe route
+ *   - `vendorSlug`, `authServerUrl` — readonly fields for logging
+ *
+ * Everything else — token validation, tool-call reporting, trial-exhausted
+ * gating, subscriber cross-check + auto conversion, transport construction
+ * and session caching, network-tool injection, auth propagation into tool
+ * handlers — is hidden inside `mcpHandler`. Vendors cannot accidentally
+ * skip a step.
+ */
+export interface WithinRequestLike {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    on(event: 'data', listener: (chunk: any) => void): unknown;
+    on(event: 'end', listener: () => void): unknown;
+}
+export interface WithinResponseLike {
+    writeHead(status: number, headers?: Record<string, string>): unknown;
+    write(chunk: any): unknown;
+    end(body?: string): unknown;
+}
+import type { WithinConfig } from './types.js';
+export interface WithinHandler {
+    mcpHandler: (req: WithinRequestLike, res: WithinResponseLike) => Promise<void>;
+    subscribeHandler: (req: WithinRequestLike, res: WithinResponseLike) => Promise<void>;
+    /** Serves RFC 9728 Protected Resource Metadata at the vendor's well-known
+     *  path. Derives `resource` from the incoming Host + X-Forwarded-Proto so
+     *  the byte-equality check in §3.3 passes no matter what hostname the
+     *  vendor runs under. Vendors route GET /.well-known/oauth-protected-resource
+     *  through this handler instead of hand-rolling their own JSON. */
+    prmHandler: (req: WithinRequestLike, res: WithinResponseLike) => void;
+    readonly vendorSlug: string;
+    readonly authServerUrl: string;
+}
+export declare function createWithinHandler(config: WithinConfig): WithinHandler;