integrate-sdk 0.3.6 → 0.3.7

package/src/config/types.ts

@@ -0,0 +1,180 @@
+/**
+ * Configuration Types
+ * Type-safe configuration with inference
+ */
+
+import type { MCPPlugin } from "../plugins/types.js";
+import type { AuthenticationError } from "../errors.js";
+
+/**
+ * Re-authentication context provided to the callback
+ */
+export interface ReauthContext {
+  /** The plugin/provider that needs re-authentication */
+  provider: string;
+  /** The error that triggered re-authentication */
+  error: AuthenticationError;
+  /** The tool name that was being called (if applicable) */
+  toolName?: string;
+}
+
+/**
+ * Re-authentication handler function
+ * Called when authentication fails and user needs to re-authenticate
+ * Should return true if re-authentication was successful, false otherwise
+ */
+export type ReauthHandler = (context: ReauthContext) => Promise<boolean> | boolean;
+
+/**
+ * Main client configuration
+ */
+export interface MCPClientConfig<TPlugins extends readonly MCPPlugin[]> {
+  /** Array of plugins to enable */
+  plugins: TPlugins;
+  
+  /** Optional HTTP headers to include in requests */
+  headers?: Record<string, string>;
+  
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  
+  /** Client information */
+  clientInfo?: {
+    name: string;
+    version: string;
+  };
+
+  /**
+   * Handler called when authentication fails and re-authentication is needed
+   * This is typically called when OAuth tokens expire or become invalid
+   * 
+   * @param context - Information about the authentication failure
+   * @returns Promise<boolean> - true if re-authentication was successful, false otherwise
+   * 
+   * @example
+   * ```typescript
+   * const client = createMCPClient({
+   *   plugins: [githubPlugin(...)],
+   *   onReauthRequired: async (context) => {
+   *     console.log(`Re-auth needed for ${context.provider}`);
+   *     // Trigger your OAuth flow here
+   *     // Return true if successful, false otherwise
+   *     return await triggerOAuthFlow(context.provider);
+   *   }
+   * });
+   * ```
+   */
+  onReauthRequired?: ReauthHandler;
+
+  /**
+   * Maximum number of automatic retry attempts when authentication fails
+   * Default: 1 (one retry after re-authentication)
+   * Set to 0 to disable automatic retries
+   */
+  maxReauthRetries?: number;
+
+  /**
+   * Connection behavior
+   * 
+   * - 'lazy' (default): Automatically connects on first method call
+   * - 'eager': Connects immediately when createMCPClient is called
+   * - 'manual': Requires manual connect() call (original behavior)
+   * 
+   * @default 'lazy'
+   */
+  connectionMode?: 'lazy' | 'eager' | 'manual';
+
+  /**
+   * Whether to use singleton pattern and reuse client instances
+   * 
+   * - true (default): Reuses client with same configuration
+   * - false: Always creates a new instance
+   * 
+   * @default true
+   */
+  singleton?: boolean;
+
+  /**
+   * Automatically cleanup (disconnect) on process exit
+   * 
+   * @default true
+   */
+  autoCleanup?: boolean;
+
+  /**
+   * OAuth flow configuration
+   * Controls how OAuth authorization is handled (popup vs redirect)
+   * 
+   * @example
+   * ```typescript
+   * const client = createMCPClient({
+   *   plugins: [githubPlugin({ ... })],
+   *   oauthFlow: {
+   *     mode: 'popup',
+   *     popupOptions: { width: 600, height: 700 }
+   *   }
+   * });
+   * ```
+   */
+  oauthFlow?: {
+    /** How to display OAuth authorization (default: 'redirect') */
+    mode?: 'popup' | 'redirect';
+    /** Popup window dimensions (only for popup mode) */
+    popupOptions?: {
+      width?: number;
+      height?: number;
+    };
+    /** Custom callback handler for receiving auth code */
+    onAuthCallback?: (provider: string, code: string, state: string) => Promise<void>;
+  };
+
+  /**
+   * Session token for authenticated requests
+   * Set automatically after OAuth flow completes
+   * Can be provided manually if you manage tokens externally
+   * 
+   * @example
+   * ```typescript
+   * const client = createMCPClient({
+   *   plugins: [githubPlugin({ ... })],
+   *   sessionToken: 'existing-session-token'
+   * });
+   * ```
+   */
+  sessionToken?: string;
+
+  /**
+   * Base URL for OAuth API routes
+   * These routes should be mounted in your application to handle OAuth securely
+   * 
+   * The SDK will call:
+   * - POST {oauthApiBase}/authorize - Get authorization URL
+   * - POST {oauthApiBase}/callback - Exchange code for token
+   * - GET {oauthApiBase}/status - Check authorization status
+   * 
+   * @default '/api/integrate/oauth'
+   * 
+   * @example
+   * ```typescript
+   * const client = createMCPClient({
+   *   plugins: [githubPlugin({ ... })],
+   *   oauthApiBase: '/api/integrate/oauth'
+   * });
+   * ```
+   */
+  oauthApiBase?: string;
+}
+
+/**
+ * Helper type to infer enabled tools from plugins
+ */
+export type InferEnabledTools<TPlugins extends readonly MCPPlugin[]> =
+  TPlugins[number]["tools"][number];
+
+/**
+ * Helper type to create a tools object type from plugin array
+ */
+export type InferToolsObject<TPlugins extends readonly MCPPlugin[]> = {
+  [K in TPlugins[number] as K["id"]]: K["tools"];
+};
+

package/src/errors.ts

@@ -0,0 +1,207 @@
+/**
+ * Custom error types for the Integrate SDK
+ */
+
+/**
+ * Base error class for all SDK errors
+ */
+export class IntegrateSDKError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "IntegrateSDKError";
+  }
+}
+
+/**
+ * Error thrown when authentication fails or tokens are invalid
+ */
+export class AuthenticationError extends IntegrateSDKError {
+  public readonly statusCode?: number;
+  public readonly provider?: string;
+
+  constructor(message: string, statusCode?: number, provider?: string) {
+    super(message);
+    this.name = "AuthenticationError";
+    this.statusCode = statusCode;
+    this.provider = provider;
+  }
+}
+
+/**
+ * Error thrown when access is forbidden (insufficient permissions)
+ */
+export class AuthorizationError extends IntegrateSDKError {
+  public readonly statusCode?: number;
+  public readonly requiredScopes?: string[];
+
+  constructor(message: string, statusCode?: number, requiredScopes?: string[]) {
+    super(message);
+    this.name = "AuthorizationError";
+    this.statusCode = statusCode;
+    this.requiredScopes = requiredScopes;
+  }
+}
+
+/**
+ * Error thrown when OAuth tokens have expired and need to be refreshed
+ */
+export class TokenExpiredError extends AuthenticationError {
+  constructor(message: string, provider?: string) {
+    super(message, 401, provider);
+    this.name = "TokenExpiredError";
+  }
+}
+
+/**
+ * Error thrown when a connection to the server fails
+ */
+export class ConnectionError extends IntegrateSDKError {
+  public readonly statusCode?: number;
+
+  constructor(message: string, statusCode?: number) {
+    super(message);
+    this.name = "ConnectionError";
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Error thrown when a tool call fails
+ */
+export class ToolCallError extends IntegrateSDKError {
+  public readonly toolName: string;
+  public readonly originalError?: unknown;
+
+  constructor(message: string, toolName: string, originalError?: unknown) {
+    super(message);
+    this.name = "ToolCallError";
+    this.toolName = toolName;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Helper function to determine if an error is an authentication error
+ */
+export function isAuthError(error: unknown): error is AuthenticationError {
+  return error instanceof AuthenticationError;
+}
+
+/**
+ * Helper function to determine if an error is a token expired error
+ */
+export function isTokenExpiredError(error: unknown): error is TokenExpiredError {
+  return error instanceof TokenExpiredError;
+}
+
+/**
+ * Helper function to determine if an error is an authorization error
+ */
+export function isAuthorizationError(error: unknown): error is AuthorizationError {
+  return error instanceof AuthorizationError;
+}
+
+/**
+ * Helper function to parse error responses from the MCP server
+ * and convert them to appropriate error types
+ */
+export function parseServerError(
+  error: any,
+  context?: { toolName?: string; provider?: string }
+): IntegrateSDKError {
+  // Check if the error has an attached JSON-RPC error (from transport layer)
+  if (error && typeof error === "object" && "jsonrpcError" in error) {
+    const jsonrpcError = error.jsonrpcError;
+    if (jsonrpcError && typeof jsonrpcError === "object") {
+      return parseServerError(jsonrpcError, context);
+    }
+  }
+
+  // Check for JSON-RPC error format
+  if (error && typeof error === "object" && "code" in error && "message" in error) {
+    const code = error.code;
+    const message = error.message || "Unknown error";
+
+    // Standard JSON-RPC error codes
+    if (code === -32600) {
+      return new IntegrateSDKError(`Invalid request: ${message}`);
+    }
+    if (code === -32601) {
+      return new IntegrateSDKError(`Method not found: ${message}`);
+    }
+    if (code === -32602) {
+      return new IntegrateSDKError(`Invalid params: ${message}`);
+    }
+
+    // Custom authentication error codes
+    if (code === 401 || code === -32001) {
+      // Check if it's a token expiry
+      if (
+        message.toLowerCase().includes("expired") ||
+        message.toLowerCase().includes("token")
+      ) {
+        return new TokenExpiredError(message, context?.provider);
+      }
+      return new AuthenticationError(message, 401, context?.provider);
+    }
+
+    // Authorization errors
+    if (code === 403 || code === -32002) {
+      return new AuthorizationError(message, 403);
+    }
+
+    // Tool-specific errors
+    if (context?.toolName) {
+      return new ToolCallError(message, context.toolName, error);
+    }
+
+    return new IntegrateSDKError(message);
+  }
+
+  // Handle regular Error objects
+  if (error instanceof Error) {
+    const message = error.message;
+    
+    // Check for HTTP status code attached to error
+    const statusCode = (error as any).statusCode;
+    if (statusCode === 401) {
+      if (message.toLowerCase().includes("expired") || message.toLowerCase().includes("token")) {
+        return new TokenExpiredError(message, context?.provider);
+      }
+      return new AuthenticationError(message, 401, context?.provider);
+    }
+    if (statusCode === 403) {
+      return new AuthorizationError(message, 403);
+    }
+
+    // Check for common auth error patterns in message
+    if (
+      message.includes("401") ||
+      message.includes("Unauthorized") ||
+      message.includes("unauthenticated")
+    ) {
+      if (message.toLowerCase().includes("expired") || message.toLowerCase().includes("token")) {
+        return new TokenExpiredError(message, context?.provider);
+      }
+      return new AuthenticationError(message, 401, context?.provider);
+    }
+
+    if (
+      message.includes("403") ||
+      message.includes("Forbidden") ||
+      message.includes("unauthorized")
+    ) {
+      return new AuthorizationError(message, 403);
+    }
+
+    if (context?.toolName) {
+      return new ToolCallError(message, context.toolName, error);
+    }
+
+    return new IntegrateSDKError(message);
+  }
+
+  // Fallback
+  return new IntegrateSDKError(String(error));
+}
+

package/src/index.ts

@@ -0,0 +1,110 @@
+/**
+ * Integrate SDK
+ * Type-safe TypeScript SDK for MCP Client
+ */
+
+// Core client
+export { MCPClient, createMCPClient, clearClientCache } from "./client.js";
+export type { ToolInvocationOptions } from "./client.js";
+
+// OAuth utilities
+export { OAuthManager } from "./oauth/manager.js";
+export { OAuthWindowManager, sendCallbackToOpener } from "./oauth/window-manager.js";
+export { generateCodeVerifier, generateCodeChallenge, generateState } from "./oauth/pkce.js";
+export type {
+  OAuthFlowConfig,
+  PopupOptions,
+  AuthStatus,
+  PendingAuth,
+  AuthorizationUrlResponse,
+  OAuthCallbackResponse,
+  OAuthCallbackParams,
+  OAuthCallbackHandlerConfig,
+} from "./oauth/types.js";
+
+// OAuth route adapters
+export { OAuthHandler } from "./adapters/base-handler.js";
+export type {
+  OAuthHandlerConfig,
+  AuthorizeRequest,
+  AuthorizeResponse,
+  CallbackRequest,
+  CallbackResponse,
+  StatusResponse,
+} from "./adapters/base-handler.js";
+export { createNextOAuthHandler } from "./adapters/nextjs.js";
+export { createTanStackOAuthHandler } from "./adapters/tanstack-start.js";
+
+// Configuration
+export type { MCPClientConfig, ReauthContext, ReauthHandler } from "./config/types.js";
+
+// Errors
+export {
+  IntegrateSDKError,
+  AuthenticationError,
+  AuthorizationError,
+  TokenExpiredError,
+  ConnectionError,
+  ToolCallError,
+  isAuthError,
+  isTokenExpiredError,
+  isAuthorizationError,
+  parseServerError,
+} from "./errors.js";
+
+// Plugin system
+export type {
+  MCPPlugin,
+  OAuthConfig,
+  ExtractPluginIds,
+  ExtractPluginTools,
+} from "./plugins/types.js";
+
+// Built-in plugins
+export { githubPlugin } from "./plugins/github.js";
+export type { GitHubPluginConfig, GitHubTools, GitHubPluginClient } from "./plugins/github.js";
+
+export { gmailPlugin } from "./plugins/gmail.js";
+export type { GmailPluginConfig, GmailTools, GmailPluginClient } from "./plugins/gmail.js";
+
+// Server client
+export type { ServerPluginClient } from "./plugins/server-client.js";
+
+export {
+  genericOAuthPlugin,
+  createSimplePlugin,
+} from "./plugins/generic.js";
+export type { GenericOAuthPluginConfig } from "./plugins/generic.js";
+
+// Integrations
+export {
+  convertMCPToolToVercelAI,
+  convertMCPToolsToVercelAI,
+  getVercelAITools,
+} from "./integrations/vercel-ai.js";
+export type { VercelAITool } from "./integrations/vercel-ai.js";
+
+// Protocol types
+export type {
+  JSONRPCRequest,
+  JSONRPCResponse,
+  JSONRPCSuccessResponse,
+  JSONRPCErrorResponse,
+  JSONRPCNotification,
+  MCPTool,
+  MCPToolsListResponse,
+  MCPToolCallParams,
+  MCPToolCallResponse,
+  MCPInitializeParams,
+  MCPInitializeResponse,
+} from "./protocol/messages.js";
+
+export { MCPMethod } from "./protocol/messages.js";
+
+// Transport
+export { HttpSessionTransport } from "./transport/http-session.js";
+export type {
+  MessageHandler,
+  HttpSessionTransportOptions,
+} from "./transport/http-session.js";
+

package/src/integrations/vercel-ai.ts

@@ -0,0 +1,104 @@
+/**
+ * Vercel AI SDK Integration
+ * 
+ * Helper functions to convert MCP tools to Vercel AI SDK format
+ */
+
+import type { MCPClient } from "../client.js";
+import type { MCPTool } from "../protocol/messages.js";
+
+/**
+ * Tool definition for Vercel AI SDK
+ */
+export interface VercelAITool {
+  description: string;
+  parameters: Record<string, unknown>;
+  execute: (args: Record<string, unknown>) => Promise<unknown>;
+}
+
+/**
+ * Convert MCP JSON Schema to Vercel AI SDK parameters format
+ * 
+ * Note: Vercel AI SDK typically uses Zod, but we return plain JSON Schema
+ * which is compatible with the AI SDK's schema parameter
+ */
+function convertMCPSchemaToParameters(inputSchema: Record<string, unknown>): Record<string, unknown> {
+  // MCP tools already use JSON Schema format
+  // Vercel AI SDK accepts JSON Schema or Zod schemas
+  return inputSchema;
+}
+
+/**
+ * Convert a single MCP tool to Vercel AI SDK format
+ * 
+ * @param mcpTool - The MCP tool definition
+ * @param client - The MCP client instance (used for executing the tool)
+ * @returns Vercel AI SDK compatible tool definition
+ */
+export function convertMCPToolToVercelAI(
+  mcpTool: MCPTool,
+  client: MCPClient
+): VercelAITool {
+  return {
+    description: mcpTool.description || `Execute ${mcpTool.name}`,
+    parameters: convertMCPSchemaToParameters(mcpTool.inputSchema),
+    execute: async (args: Record<string, unknown>) => {
+      // Use internal method to call tools by name for integration purposes
+      const result = await client._callToolByName(mcpTool.name, args);
+      return result;
+    },
+  };
+}
+
+/**
+ * Convert all enabled MCP tools to Vercel AI SDK format
+ * 
+ * @param client - The MCP client instance (must be connected)
+ * @returns Object mapping tool names to Vercel AI SDK tool definitions
+ * 
+ * @example
+ * ```typescript
+ * import { createMCPClient, githubPlugin } from 'integrate-sdk';
+ * import { convertMCPToolsToVercelAI } from 'integrate-sdk/vercel-ai';
+ * import { generateText } from 'ai';
+ * 
+ * const mcpClient = createMCPClient({
+ *   plugins: [githubPlugin({ clientId: '...', clientSecret: '...' })],
+ * });
+ * 
+ * await mcpClient.connect();
+ * 
+ * const tools = convertMCPToolsToVercelAI(mcpClient);
+ * 
+ * const result = await generateText({
+ *   model: openai('gpt-5'),
+ *   prompt: 'Create a GitHub issue in my repo',
+ *   tools,
+ * });
+ * ```
+ */
+export function convertMCPToolsToVercelAI(
+  client: MCPClient
+): Record<string, VercelAITool> {
+  const mcpTools = client.getEnabledTools();
+  const vercelTools: Record<string, VercelAITool> = {};
+
+  for (const mcpTool of mcpTools) {
+    vercelTools[mcpTool.name] = convertMCPToolToVercelAI(mcpTool, client);
+  }
+
+  return vercelTools;
+}
+
+/**
+ * Get tools in a format compatible with Vercel AI SDK's tools parameter
+ * 
+ * This is an alternative that returns the tools in the exact format expected by ai.generateText()
+ * 
+ * @param client - The MCP client instance (must be connected)
+ * @returns Tools object ready to pass to generateText({ tools: ... })
+ */
+export function getVercelAITools(client: MCPClient) {
+  return convertMCPToolsToVercelAI(client);
+}
+