within-sdk 1.0.0

package/dist/proxy.js

@@ -0,0 +1,158 @@
+/**
+ * Remote MCP tool-call proxy — Streamable HTTP.
+ *
+ * Used by within__use to invoke a tool on another vendor's MCP server.
+ *
+ * The MCP Streamable HTTP transport requires a handshake before tool calls:
+ *   1. POST /mcp  { method: "initialize", ... }        → 200 with mcp-session-id header
+ *   2. POST /mcp  { method: "notifications/initialized" } (with that session id)
+ *   3. POST /mcp  { method: "tools/call", ... }        (with that session id) → result
+ *
+ * Skipping steps 1+2 yields "Server not initialized" on the target server,
+ * which is what killed within__use against the real Beacon CRM deployment.
+ *
+ * Response bodies come back as either application/json (a single JSON-RPC
+ * response) or text/event-stream (SSE with one or more `event: message \n
+ * data: {...}` blocks). We accept both and extract the first JSON-RPC
+ * response message we see.
+ *
+ * Session reuse: we cache the session id per (url, token) so a subsequent
+ * within__use to the same target doesn't re-handshake. Cache keyed on access
+ * token which itself has a short TTL, so there's no long-lived drift risk.
+ */
+const sessionCache = new Map();
+const SESSION_TTL_MS = 9 * 60_000; // generous buffer under the 10-min access-token TTL
+const PROTOCOL_VERSION = '2025-11-25';
+export async function callRemoteMcpTool(mcpServerUrl, accessToken, toolName, toolArguments, options) {
+    const timeoutMs = options?.timeoutMs ?? 30_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const sessionId = await ensureSession(mcpServerUrl, accessToken, controller.signal);
+        const res = await fetch(mcpServerUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json, text/event-stream',
+                Authorization: `Bearer ${accessToken}`,
+                'mcp-session-id': sessionId,
+            },
+            body: JSON.stringify({
+                jsonrpc: '2.0',
+                id: options?.requestId ?? 1,
+                method: 'tools/call',
+                params: { name: toolName, arguments: toolArguments },
+            }),
+            signal: controller.signal,
+        });
+        const text = await res.text();
+        const parsed = parseJsonRpcResponse(text, res.headers.get('content-type') ?? '');
+        // If the target says our session has vanished (container recycled,
+        // memory eviction, etc.) drop our cache entry and retry exactly once.
+        if (!res.ok && looksLikeStaleSession(text)) {
+            sessionCache.delete(cacheKey(mcpServerUrl, accessToken));
+            return callRemoteMcpTool(mcpServerUrl, accessToken, toolName, toolArguments, options);
+        }
+        return { ok: res.ok, status: res.status, body: parsed ?? text };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function cacheKey(url, token) {
+    return `${url}::${token}`;
+}
+function looksLikeStaleSession(body) {
+    return /session\s+(expired|not\s+found|invalid)/i.test(body) || body.includes('Session expired');
+}
+async function ensureSession(url, accessToken, signal) {
+    const key = cacheKey(url, accessToken);
+    const cached = sessionCache.get(key);
+    if (cached && Date.now() - cached.createdAt < SESSION_TTL_MS) {
+        return cached.sessionId;
+    }
+    const initRes = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            Authorization: `Bearer ${accessToken}`,
+        },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 0,
+            method: 'initialize',
+            params: {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: { name: 'within-mcp-auth/proxy', version: '0.1.0' },
+            },
+        }),
+        signal,
+    });
+    if (!initRes.ok) {
+        const errText = await initRes.text();
+        throw new Error(`Remote MCP initialize failed (${initRes.status}): ${errText.slice(0, 240)}`);
+    }
+    const sessionId = initRes.headers.get('mcp-session-id');
+    if (!sessionId) {
+        throw new Error('Remote MCP server did not return an mcp-session-id header on initialize');
+    }
+    // Consume init response body to free the socket before the next POST.
+    await initRes.text().catch(() => undefined);
+    // Fire-and-forget the initialized notification. The spec wants it, and
+    // some servers block tools/call until they've seen it.
+    const notifRes = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json, text/event-stream',
+            Authorization: `Bearer ${accessToken}`,
+            'mcp-session-id': sessionId,
+        },
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            method: 'notifications/initialized',
+        }),
+        signal,
+    });
+    // 202 Accepted is the expected response for notifications; anything else
+    // we tolerate (target may acknowledge with 200 or drop it). We do NOT
+    // throw here because some implementations don't require this step.
+    await notifRes.text().catch(() => undefined);
+    sessionCache.set(key, { sessionId, createdAt: Date.now() });
+    return sessionId;
+}
+/**
+ * The MCP StreamableHTTP transport can respond with either raw JSON or SSE.
+ * This function peels off the SSE framing (if present) and returns the
+ * first JSON-RPC response object it finds, or null if the body is neither.
+ */
+function parseJsonRpcResponse(text, contentType) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    if (contentType.includes('text/event-stream') || trimmed.startsWith('event:')) {
+        // SSE frame format: event: message\ndata: {...}\n\n
+        for (const line of trimmed.split(/\r?\n/)) {
+            if (line.startsWith('data:')) {
+                const payload = line.slice(5).trim();
+                if (!payload)
+                    continue;
+                try {
+                    return JSON.parse(payload);
+                }
+                catch {
+                    // Not JSON, try next line
+                }
+            }
+        }
+        return null;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/thirdparty/ksuid/base-convert-int-array.js

@@ -0,0 +1,49 @@
+"use strict";
+
+const maxLength = (array, from, to) =>
+  Math.ceil((array.length * Math.log2(from)) / Math.log2(to));
+
+function baseConvertIntArray(array, { from, to, fixedLength = null }) {
+  const length =
+    fixedLength === null ? maxLength(array, from, to) : fixedLength;
+  const result = new Array(length);
+
+  // Each iteration prepends the resulting value, so start the offset at the end.
+  let offset = length;
+  let input = array;
+  while (input.length > 0) {
+    if (offset === 0) {
+      throw new RangeError(
+        `Fixed length of ${fixedLength} is too small, expected at least ${maxLength(array, from, to)}`,
+      );
+    }
+
+    const quotients = [];
+    let remainder = 0;
+
+    for (const digit of input) {
+      const acc = digit + remainder * from;
+      const q = Math.floor(acc / to);
+      remainder = acc % to;
+
+      if (quotients.length > 0 || q > 0) {
+        quotients.push(q);
+      }
+    }
+
+    result[--offset] = remainder;
+    input = quotients;
+  }
+
+  // Trim leading padding, unless length is fixed.
+  if (fixedLength === null) {
+    return offset > 0 ? result.slice(offset) : result;
+  }
+
+  // Fill in any holes in the result array.
+  while (offset > 0) {
+    result[--offset] = 0;
+  }
+  return result;
+}
+export default baseConvertIntArray;

package/dist/thirdparty/ksuid/base62.js

@@ -0,0 +1,24 @@
+"use strict";
+import baseConvertIntArray from "./base-convert-int-array.js";
+
+const CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+function encode(buffer, fixedLength) {
+  return baseConvertIntArray(buffer, { from: 256, to: 62, fixedLength })
+    .map((value) => CHARS[value])
+    .join("");
+}
+
+function decode(string, fixedLength) {
+  // Optimization from https://github.com/andrew/base62.js/pull/31.
+  const input = Array.from(string, (char) => {
+    const charCode = char.charCodeAt(0);
+    if (charCode < 58) return charCode - 48;
+    if (charCode < 91) return charCode - 55;
+    return charCode - 61;
+  });
+  return Buffer.from(
+    baseConvertIntArray(input, { from: 62, to: 256, fixedLength }),
+  );
+}
+export { encode, decode };

package/dist/thirdparty/ksuid/index.d.ts

@@ -0,0 +1,30 @@
+/// <reference types="node" />
+declare class KSUID {
+  constructor(buffer: Buffer);
+  readonly raw: Buffer;
+  readonly date: Date;
+  readonly timestamp: number;
+  readonly payload: Buffer;
+  readonly string: string;
+  compare(other: KSUID): number;
+  equals(other: KSUID): boolean;
+  toString(): string;
+  toJSON(): string;
+  static random(): Promise<KSUID>;
+  static random(timeInMs: number): Promise<KSUID>;
+  static random(date: Date): Promise<KSUID>;
+  static randomSync(): KSUID;
+  static randomSync(timeInMs: number): KSUID;
+  static randomSync(date: Date): KSUID;
+  static fromParts(timeInMs: number, payload: Buffer): KSUID;
+  static isValid(buffer: Buffer): boolean;
+  static parse(str: string): KSUID;
+  static withPrefix(prefix: string): {
+    random(timeInMs?: number): Promise<string>;
+    random(date?: Date): Promise<string>;
+    randomSync(timeInMs?: number): string;
+    randomSync(date?: Date): string;
+    fromParts(timeInMs: number, payload: Buffer): string;
+  };
+}
+export default KSUID;

package/dist/thirdparty/ksuid/index.js

@@ -0,0 +1,201 @@
+"use strict";
+import { randomBytes } from "node:crypto";
+import { inspect } from "node:util";
+import { promisify } from "node:util";
+import * as base62 from "./base62.js";
+
+const customInspectSymbol = inspect.custom;
+
+const asyncRandomBytes = promisify(randomBytes);
+
+// KSUID's epoch starts more recently so that the 32-bit number space gives a
+// significantly higher useful lifetime of around 136 years from March 2014.
+// This number (14e11) was picked to be easy to remember.
+const EPOCH_IN_MS = 14e11;
+
+const MAX_TIME_IN_MS = 1e3 * (2 ** 32 - 1) + EPOCH_IN_MS;
+
+// Timestamp is a uint32
+const TIMESTAMP_BYTE_LENGTH = 4;
+
+// Payload is 16-bytes
+const PAYLOAD_BYTE_LENGTH = 16;
+
+// KSUIDs are 20 bytes when binary encoded
+const BYTE_LENGTH = TIMESTAMP_BYTE_LENGTH + PAYLOAD_BYTE_LENGTH;
+
+// The length of a KSUID when string (base62) encoded
+const STRING_ENCODED_LENGTH = 27;
+
+const TIME_IN_MS_ASSERTION =
+  `Valid KSUID timestamps must be in milliseconds since ${new Date(0).toISOString()},
+  no earlier than ${new Date(EPOCH_IN_MS).toISOString()} and no later than ${new Date(MAX_TIME_IN_MS).toISOString()}
+`
+    .trim()
+    .replace(/(\n|\s)+/g, " ")
+    .replace(/\.000Z/g, "Z");
+
+const VALID_ENCODING_ASSERTION = `Valid encoded KSUIDs are ${STRING_ENCODED_LENGTH} characters`;
+
+const VALID_BUFFER_ASSERTION = `Valid KSUID buffers are ${BYTE_LENGTH} bytes`;
+
+const VALID_PAYLOAD_ASSERTION = `Valid KSUID payloads are ${PAYLOAD_BYTE_LENGTH} bytes`;
+
+function fromParts(timeInMs, payload) {
+  const timestamp = Math.floor((timeInMs - EPOCH_IN_MS) / 1e3);
+  const timestampBuffer = Buffer.allocUnsafe(TIMESTAMP_BYTE_LENGTH);
+  timestampBuffer.writeUInt32BE(timestamp, 0);
+
+  return Buffer.concat([timestampBuffer, payload], BYTE_LENGTH);
+}
+
+const bufferLookup = new WeakMap();
+
+class KSUID {
+  constructor(buffer) {
+    if (!KSUID.isValid(buffer)) {
+      throw new TypeError(VALID_BUFFER_ASSERTION);
+    }
+
+    bufferLookup.set(this, buffer);
+    Object.defineProperty(this, "buffer", {
+      enumerable: true,
+      get() {
+        return Buffer.from(buffer);
+      },
+    });
+  }
+
+  get raw() {
+    return Buffer.from(bufferLookup.get(this).slice(0));
+  }
+
+  get date() {
+    return new Date(1e3 * this.timestamp + EPOCH_IN_MS);
+  }
+
+  get timestamp() {
+    return bufferLookup.get(this).readUInt32BE(0);
+  }
+
+  get payload() {
+    const payload = bufferLookup
+      .get(this)
+      .slice(TIMESTAMP_BYTE_LENGTH, BYTE_LENGTH);
+    return Buffer.from(payload);
+  }
+
+  get string() {
+    const encoded = base62.encode(
+      bufferLookup.get(this),
+      STRING_ENCODED_LENGTH,
+    );
+    return encoded.padStart(STRING_ENCODED_LENGTH, "0");
+  }
+
+  compare(other) {
+    if (!bufferLookup.has(other)) {
+      return 0;
+    }
+
+    return bufferLookup
+      .get(this)
+      .compare(bufferLookup.get(other), 0, BYTE_LENGTH);
+  }
+
+  equals(other) {
+    return (
+      this === other || (bufferLookup.has(other) && this.compare(other) === 0)
+    );
+  }
+
+  toString() {
+    return `${this[Symbol.toStringTag]} { ${this.string} }`;
+  }
+
+  toJSON() {
+    return this.string;
+  }
+
+  [customInspectSymbol]() {
+    return this.toString();
+  }
+
+  static async random(time = Date.now()) {
+    const payload = await asyncRandomBytes(PAYLOAD_BYTE_LENGTH);
+    return new KSUID(fromParts(Number(time), payload));
+  }
+
+  static randomSync(time = Date.now()) {
+    const payload = randomBytes(PAYLOAD_BYTE_LENGTH);
+    return new KSUID(fromParts(Number(time), payload));
+  }
+
+  static fromParts(timeInMs, payload) {
+    if (
+      !Number.isInteger(timeInMs) ||
+      timeInMs < EPOCH_IN_MS ||
+      timeInMs > MAX_TIME_IN_MS
+    ) {
+      throw new TypeError(TIME_IN_MS_ASSERTION);
+    }
+    if (
+      !Buffer.isBuffer(payload) ||
+      payload.byteLength !== PAYLOAD_BYTE_LENGTH
+    ) {
+      throw new TypeError(VALID_PAYLOAD_ASSERTION);
+    }
+
+    return new KSUID(fromParts(timeInMs, payload));
+  }
+
+  static isValid(buffer) {
+    return Buffer.isBuffer(buffer) && buffer.byteLength === BYTE_LENGTH;
+  }
+
+  static parse(string) {
+    if (string.length !== STRING_ENCODED_LENGTH) {
+      throw new TypeError(VALID_ENCODING_ASSERTION);
+    }
+
+    const decoded = base62.decode(string, BYTE_LENGTH);
+    if (decoded.byteLength === BYTE_LENGTH) {
+      return new KSUID(decoded);
+    }
+
+    const buffer = Buffer.allocUnsafe(BYTE_LENGTH);
+    const padEnd = BYTE_LENGTH - decoded.byteLength;
+    buffer.fill(0, 0, padEnd);
+    decoded.copy(buffer, padEnd);
+    return new KSUID(buffer);
+  }
+}
+Object.defineProperty(KSUID.prototype, Symbol.toStringTag, { value: "KSUID" });
+// A string-encoded maximum value for a KSUID
+Object.defineProperty(KSUID, "MAX_STRING_ENCODED", {
+  value: "aWgEPTl1tmebfsQzFP4bxwgy80V",
+});
+// A string-encoded minimum value for a KSUID
+Object.defineProperty(KSUID, "MIN_STRING_ENCODED", {
+  value: "000000000000000000000000000",
+});
+
+// Add prefix functionality
+KSUID.withPrefix = function (prefix) {
+  return {
+    random: async (time = Date.now()) => {
+      const ksuid = await KSUID.random(time);
+      return `${prefix}_${ksuid.string}`;
+    },
+    randomSync: (time = Date.now()) => {
+      const ksuid = KSUID.randomSync(time);
+      return `${prefix}_${ksuid.string}`;
+    },
+    fromParts: (timeInMs, payload) => {
+      const ksuid = KSUID.fromParts(timeInMs, payload);
+      return `${prefix}_${ksuid.string}`;
+    },
+  };
+};
+
+export default KSUID;

package/dist/types.d.ts

@@ -0,0 +1,197 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export interface WithinOptions {
+    apiKey?: string;
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+    log?: (line: string) => void;
+    enableReportMissing?: boolean;
+    enableTracing?: boolean;
+    enableToolCallContext?: boolean;
+    customContextDescription?: string;
+    identify?: (request: any, extra?: CompatibleRequestHandlerExtra) => Promise<UserIdentity | null>;
+    redactSensitiveInformation?: RedactFunction;
+    exporters?: Record<string, ExporterConfig>;
+    disableDiagnostics?: boolean;
+    eventTags?: (request: any, extra?: CompatibleRequestHandlerExtra) => Record<string, string> | null | Promise<Record<string, string> | null>;
+    eventProperties?: (request: any, extra?: CompatibleRequestHandlerExtra) => Record<string, any> | null | Promise<Record<string, any> | null>;
+    privacy?: {
+        maxFieldBytes?: number;
+        maxEventBytes?: number;
+        redactKeys?: string[];
+    };
+}
+export type ToolCallback = ((args: any, extra: CompatibleRequestHandlerExtra) => CallToolResult | Promise<CallToolResult>) | ((extra: CompatibleRequestHandlerExtra) => CallToolResult | Promise<CallToolResult>);
+export type RegisteredTool = {
+    description?: string;
+    inputSchema?: any;
+    update?: (...args: any[]) => any;
+} & ({
+    callback: ToolCallback;
+    handler?: never;
+} | {
+    handler: ToolCallback;
+    callback?: never;
+});
+export type RedactFunction = (text: string) => Promise<string> | string;
+export interface ExporterConfig {
+    type: string;
+    [key: string]: any;
+}
+export interface Exporter {
+    export(event: Event): Promise<void>;
+}
+export declare enum WithinIDPrefixes {
+    Session = "ses",
+    Event = "evt"
+}
+export interface Event {
+    id: string;
+    sessionId: string;
+    projectId?: string;
+    vendorSlug?: string;
+    apiKey?: string;
+    ingestBaseUrl?: string;
+    fetchImpl?: typeof fetch;
+    eventType: string;
+    timestamp: Date;
+    duration?: number;
+    ipAddress?: string;
+    sdkLanguage?: string;
+    sdkVersion?: string;
+    serverName?: string;
+    serverVersion?: string;
+    clientName?: string;
+    clientVersion?: string;
+    identifyActorGivenId?: string;
+    identifyActorName?: string;
+    identifyActorData?: object;
+    resourceName?: string;
+    parameters?: any;
+    response?: any;
+    userIntent?: string;
+    isError?: boolean;
+    error?: ErrorData;
+    tags?: Record<string, string> | null;
+    properties?: Record<string, any> | null;
+    actorId?: string;
+    eventId?: string;
+    identifyData?: object;
+}
+export interface UnredactedEvent extends Partial<Event> {
+    redactionFn?: RedactFunction;
+}
+export interface CompatibleRequestHandlerExtra {
+    sessionId?: string;
+    headers?: Record<string, string | string[]>;
+    [key: string]: any;
+}
+export interface ServerClientInfoLike {
+    name?: string;
+    version?: string;
+}
+export interface HighLevelMCPServerLike {
+    _registeredTools: {
+        [name: string]: RegisteredTool;
+    };
+    server: MCPServerLike;
+    tool?(name: string, cb: ToolCallback): void;
+    tool?(name: string, description: string, cb: ToolCallback): void;
+    tool?(name: string, paramsSchema: any, cb: ToolCallback): void;
+    tool?(name: string, description: string, paramsSchema: any, cb: ToolCallback): void;
+    registerTool?(name: string, config: {
+        description?: string;
+        inputSchema?: any;
+    }, handler: ToolCallback): void;
+}
+export interface MCPServerLike {
+    setRequestHandler(schema: any, handler: (request: any, extra?: CompatibleRequestHandlerExtra) => Promise<any>): void;
+    _requestHandlers: Map<string, (request: any, extra?: CompatibleRequestHandlerExtra) => Promise<any>>;
+    _serverInfo?: ServerClientInfoLike;
+    getClientVersion(): ServerClientInfoLike | undefined;
+}
+export interface UserIdentity {
+    userId: string;
+    userName?: string;
+    userData?: Record<string, any>;
+}
+export interface SessionInfo {
+    ipAddress?: string;
+    sdkLanguage?: string;
+    sdkVersion?: string;
+    serverName?: string;
+    serverVersion?: string;
+    clientName?: string;
+    clientVersion?: string;
+    identifyActorGivenId?: string;
+    identifyActorName?: string;
+    identifyActorData?: object;
+}
+export interface WithinTrackingData {
+    projectId: string;
+    vendorSlug: string;
+    apiKey?: string;
+    ingestBaseUrl: string;
+    fetchImpl: typeof fetch;
+    sessionId: string;
+    lastActivity: Date;
+    identifiedSessions: Map<string, UserIdentity>;
+    sessionInfo: SessionInfo;
+    options: WithinOptions;
+    lastMcpSessionId?: string;
+    sessionSource: "mcp" | "within";
+}
+export interface StackFrame {
+    filename: string;
+    function: string;
+    lineno?: number;
+    colno?: number;
+    in_app: boolean;
+    abs_path?: string;
+    context_line?: string;
+}
+export interface ChainedErrorData {
+    message: string;
+    type?: string;
+    stack?: string;
+    frames?: StackFrame[];
+}
+export interface ErrorData {
+    message: string;
+    type?: string;
+    stack?: string;
+    frames?: StackFrame[];
+    chained_errors?: ChainedErrorData[];
+    platform?: string;
+}
+export interface CustomEventData {
+    resourceName?: string;
+    parameters?: any;
+    response?: any;
+    message?: string;
+    duration?: number;
+    isError?: boolean;
+    error?: any;
+    tags?: Record<string, string>;
+    properties?: Record<string, any>;
+    apiKey?: string;
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}
+export interface WithinConversionPlan {
+    id?: string;
+    name?: string;
+    interval?: string;
+}
+export interface WithinConversionInput {
+    subject: string;
+    convertedAt?: string | Date;
+    plan?: WithinConversionPlan;
+    metadata?: Record<string, unknown>;
+}
+export interface WithinConversionResult {
+    ok: boolean;
+    inserted: boolean;
+    status: "subscriber";
+    identityKey: string;
+    conversionUtcDate: string;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+export var WithinIDPrefixes;
+(function (WithinIDPrefixes) {
+    WithinIDPrefixes["Session"] = "ses";
+    WithinIDPrefixes["Event"] = "evt";
+})(WithinIDPrefixes || (WithinIDPrefixes = {}));