integrate-sdk 0.3.6 → 0.3.7

package/dist/index.js

@@ -1356,106 +1356,6 @@ async function clearClientCache() {
 // src/index.ts
 init_nextjs();
 
-// src/adapters/nextjs-callback.tsx
-import { useEffect } from "react";
-import { jsxDEV } from "react/jsx-dev-runtime";
-"use client";
-function OAuthCallbackPage(config) {
-  const redirectUrl = config?.redirectUrl || "/";
-  const errorRedirectUrl = config?.errorRedirectUrl || "/auth-error";
-  useEffect(() => {
-    const params = new URLSearchParams(window.location.search);
-    const code = params.get("code");
-    const state = params.get("state");
-    const error = params.get("error");
-    const errorDescription = params.get("error_description");
-    if (error) {
-      const errorMsg = errorDescription || error;
-      console.error("[OAuth Callback] Error:", errorMsg);
-      window.location.href = `${errorRedirectUrl}?error=${encodeURIComponent(errorMsg)}`;
-      return;
-    }
-    if (!code || !state) {
-      console.error("[OAuth Callback] Missing code or state parameter");
-      window.location.href = `${errorRedirectUrl}?error=${encodeURIComponent("Invalid OAuth callback")}`;
-      return;
-    }
-    if (window.opener) {
-      window.opener.postMessage({
-        type: "oauth_callback",
-        code,
-        state
-      }, "*");
-      setTimeout(() => {
-        window.close();
-      }, 100);
-    } else {
-      try {
-        sessionStorage.setItem("oauth_callback_params", JSON.stringify({ code, state }));
-      } catch (e) {
-        console.error("Failed to store OAuth callback params:", e);
-      }
-      setTimeout(() => {
-        window.location.href = redirectUrl;
-      }, 500);
-    }
-  }, [redirectUrl, errorRedirectUrl]);
-  return /* @__PURE__ */ jsxDEV("div", {
-    style: {
-      fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
-      display: "flex",
-      alignItems: "center",
-      justifyContent: "center",
-      minHeight: "100vh",
-      margin: 0,
-      background: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
-      color: "white"
-    },
-    children: /* @__PURE__ */ jsxDEV("div", {
-      style: { textAlign: "center", padding: "2rem" },
-      children: [
-        /* @__PURE__ */ jsxDEV("div", {
-          style: {
-            border: "3px solid rgba(255, 255, 255, 0.3)",
-            borderRadius: "50%",
-            borderTop: "3px solid white",
-            width: "40px",
-            height: "40px",
-            animation: "spin 1s linear infinite",
-            margin: "0 auto 1rem"
-          }
-        }, undefined, false, undefined, this),
-        /* @__PURE__ */ jsxDEV("h1", {
-          style: {
-            margin: "0 0 0.5rem",
-            fontSize: "1.5rem",
-            fontWeight: 600
-          },
-          children: "Authorization Complete"
-        }, undefined, false, undefined, this),
-        /* @__PURE__ */ jsxDEV("p", {
-          style: { margin: 0, opacity: 0.9, fontSize: "0.875rem" },
-          children: "This window will close automatically..."
-        }, undefined, false, undefined, this),
-        /* @__PURE__ */ jsxDEV("style", {
-          children: `
-          @keyframes spin {
-            0% { transform: rotate(0deg); }
-            100% { transform: rotate(360deg); }
-          }
-        `
-        }, undefined, false, undefined, this)
-      ]
-    }, undefined, true, undefined, this)
-  }, undefined, false, undefined, this);
-}
-function createOAuthCallbackPage(config) {
-  return function OAuthCallback() {
-    return /* @__PURE__ */ jsxDEV(OAuthCallbackPage, {
-      ...config
-    }, undefined, false, undefined, this);
-  };
-}
 // src/adapters/tanstack-start.ts
 function createTanStackOAuthHandler(config) {
   const handler = new OAuthHandler(config);
@@ -1690,7 +1590,6 @@ export {
   generateCodeChallenge,
   createTanStackOAuthHandler,
   createSimplePlugin,
-  createOAuthCallbackPage,
   createNextOAuthHandler,
   createMCPClient,
   convertMCPToolsToVercelAI,
@@ -1701,7 +1600,6 @@ export {
   OAuthWindowManager,
   OAuthManager,
   OAuthHandler,
-  OAuthCallbackPage,
   MCPMethod,
   MCPClient,
   IntegrateSDKError,

package/dist/src/adapters/nextjs-callback.d.ts

@@ -19,7 +19,7 @@ import type { OAuthCallbackHandlerConfig } from '../oauth/types.js';
  * @example
  * ```tsx
  * // app/oauth/callback/page.tsx
- * import { OAuthCallbackPage } from 'integrate-sdk';
+ * import { OAuthCallbackPage } from 'integrate-sdk/oauth-callback';
  *
  * export default function CallbackPage() {
  *   return <OAuthCallbackPage redirectUrl="/dashboard" />;
@@ -33,7 +33,11 @@ export declare function OAuthCallbackPage(config?: OAuthCallbackHandlerConfig):
  * @example
  * ```tsx
  * // app/oauth/callback/page.tsx
- * export { default } from 'integrate-sdk/oauth-callback';
+ * import { createOAuthCallbackPage } from 'integrate-sdk/oauth-callback';
+ *
+ * export default createOAuthCallbackPage({
+ *   redirectUrl: '/dashboard',
+ * });
  * ```
  */
 export declare function createOAuthCallbackPage(config?: OAuthCallbackHandlerConfig): () => import("react/jsx-runtime").JSX.Element;

package/dist/src/adapters/nextjs-callback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nextjs-callback.d.ts","sourceRoot":"","sources":["../../../src/adapters/nextjs-callback.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,0BAA0B,2CA2GpE;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,0BAA0B,iDAI1E"}
+{"version":3,"file":"nextjs-callback.d.ts","sourceRoot":"","sources":["../../../src/adapters/nextjs-callback.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,0BAA0B,2CA2GpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,0BAA0B,iDAI1E"}

package/dist/src/index.d.ts

@@ -11,7 +11,6 @@ export type { OAuthFlowConfig, PopupOptions, AuthStatus, PendingAuth, Authorizat
 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 { OAuthCallbackPage, createOAuthCallbackPage } from "./adapters/nextjs-callback.js";
 export { createTanStackOAuthHandler } from "./adapters/tanstack-start.js";
 export type { MCPClientConfig, ReauthContext, ReauthHandler } from "./config/types.js";
 export { IntegrateSDKError, AuthenticationError, AuthorizationError, TokenExpiredError, ConnectionError, ToolCallError, isAuthError, isTokenExpiredError, isAuthorizationError, parseServerError, } from "./errors.js";

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7F,YAAY,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,WAAW,EACX,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAC3F,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAG1E,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvF,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE/F,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG3F,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAGrE,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,YAAY,EACV,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,OAAO,EACP,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EACV,cAAc,EACd,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC3E,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACrF,OAAO,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7F,YAAY,EACV,eAAe,EACf,YAAY,EACZ,UAAU,EACV,WAAW,EACX,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,cAAc,GACf,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAG1E,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvF,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE/F,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG3F,YAAY,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAGrE,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,GACjB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAGhE,YAAY,EACV,cAAc,EACd,eAAe,EACf,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,OAAO,EACP,oBAAoB,EACpB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,YAAY,EACV,cAAc,EACd,2BAA2B,GAC5B,MAAM,6BAA6B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "integrate-sdk",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Type-safe TypeScript SDK for MCP Client with plugin-based OAuth provider configuration",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,10 +26,15 @@
     "./oauth": {
       "import": "./dist/oauth.js",
       "types": "./dist/oauth.d.ts"
+    },
+    "./oauth-callback": {
+      "import": "./src/adapters/nextjs-callback.tsx",
+      "types": "./dist/adapters/nextjs-callback.d.ts"
     }
   },
   "files": [
     "dist",
+    "src",
     "index.ts",
     "server.ts",
     "oauth.ts"

package/src/adapters/auto-routes.ts

@@ -0,0 +1,217 @@
+/**
+ * Auto-generated OAuth Routes
+ * Automatically creates the correct route handlers based on framework detection
+ */
+
+import { OAuthHandler, type OAuthHandlerConfig } from './base-handler.js';
+
+/**
+ * Global OAuth configuration
+ * Set by createMCPClient when oauthConfig is provided
+ */
+let globalOAuthConfig: OAuthHandlerConfig | null = null;
+
+/**
+ * Set the global OAuth configuration
+ * Called internally by createMCPClient
+ */
+export function setGlobalOAuthConfig(config: OAuthHandlerConfig): void {
+  globalOAuthConfig = config;
+}
+
+/**
+ * Get the global OAuth configuration
+ */
+export function getGlobalOAuthConfig(): OAuthHandlerConfig | null {
+  return globalOAuthConfig;
+}
+
+/**
+ * Universal OAuth route handler
+ * Automatically detects framework and handles all OAuth actions
+ * 
+ * This is the magic function that makes everything "just work"
+ * 
+ * @example
+ * ```typescript
+ * // app/api/integrate/oauth/[action]/route.ts (Next.js)
+ * export * from 'integrate-sdk/oauth';
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // app/routes/api/integrate/oauth/[action].ts (TanStack Start)
+ * export * from 'integrate-sdk/oauth';
+ * ```
+ */
+
+// Framework detection helpers (unused but kept for future enhancements)
+// function isNextJS(request: any): boolean {
+//   return (
+//     request?.constructor?.name === 'NextRequest' ||
+//     typeof request?.nextUrl !== 'undefined' ||
+//     typeof (globalThis as any).NextResponse !== 'undefined'
+//   );
+// }
+
+// function isTanStackStart(request: any): boolean {
+//   return (
+//     request instanceof Request &&
+//     !isNextJS(request)
+//   );
+// }
+
+/**
+ * Universal POST handler
+ * Handles authorize and callback actions
+ */
+export async function POST(
+  req: any,
+  context?: { params: { action: string } }
+): Promise<any> {
+  if (!globalOAuthConfig) {
+    throw new Error(
+      'OAuth configuration not found. Did you configure oauthProviders in createMCPClient?'
+    );
+  }
+
+  const handler = new OAuthHandler(globalOAuthConfig);
+  const action = context?.params?.action;
+
+  if (!action) {
+    return createErrorResponse('Missing action parameter', 400);
+  }
+
+  try {
+    if (action === 'authorize') {
+      const body = await parseRequestBody(req);
+      const result = await handler.handleAuthorize(body);
+      return createSuccessResponse(result);
+    }
+
+    if (action === 'callback') {
+      const body = await parseRequestBody(req);
+      const result = await handler.handleCallback(body);
+      return createSuccessResponse(result);
+    }
+
+    return createErrorResponse(`Unknown action: ${action}`, 404);
+  } catch (error: any) {
+    console.error(`[OAuth ${action}] Error:`, error);
+    return createErrorResponse(error.message, 500);
+  }
+}
+
+/**
+ * Universal GET handler
+ * Handles status action
+ */
+export async function GET(
+  req: any,
+  context?: { params: { action: string } }
+): Promise<any> {
+  if (!globalOAuthConfig) {
+    throw new Error(
+      'OAuth configuration not found. Did you configure oauthProviders in createMCPClient?'
+    );
+  }
+
+  const handler = new OAuthHandler(globalOAuthConfig);
+  const action = context?.params?.action;
+
+  if (!action) {
+    return createErrorResponse('Missing action parameter', 400);
+  }
+
+  try {
+    if (action === 'status') {
+      const { provider, sessionToken } = parseQueryParams(req);
+
+      if (!provider || !sessionToken) {
+        return createErrorResponse(
+          'Missing provider or session token',
+          400
+        );
+      }
+
+      const result = await handler.handleStatus(provider, sessionToken);
+      return createSuccessResponse(result);
+    }
+
+    return createErrorResponse(`Unknown action: ${action}`, 404);
+  } catch (error: any) {
+    console.error(`[OAuth ${action}] Error:`, error);
+    return createErrorResponse(error.message, 500);
+  }
+}
+
+/**
+ * Parse request body (works for both Next.js and standard Request)
+ */
+async function parseRequestBody(req: any): Promise<any> {
+  if (typeof req.json === 'function') {
+    return await req.json();
+  }
+  throw new Error('Unable to parse request body');
+}
+
+/**
+ * Parse query parameters (works for both Next.js and standard Request)
+ */
+function parseQueryParams(req: any): { provider?: string; sessionToken?: string } {
+  let url: URL;
+
+  // Next.js
+  if (req.nextUrl) {
+    url = new URL(req.nextUrl);
+  }
+  // Standard Request
+  else if (req.url) {
+    url = new URL(req.url);
+  } else {
+    return {};
+  }
+
+  const provider = url.searchParams.get('provider') || undefined;
+  const sessionToken = req.headers?.get?.('x-session-token') || undefined;
+
+  return { provider, sessionToken };
+}
+
+/**
+ * Create success response (works for both frameworks)
+ */
+function createSuccessResponse(data: any): any {
+  // Try Next.js first
+  if (typeof (globalThis as any).NextResponse !== 'undefined') {
+    const NextResponse = (globalThis as any).NextResponse;
+    return NextResponse.json(data);
+  }
+
+  // Fallback to standard Response
+  return new Response(JSON.stringify(data), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+/**
+ * Create error response (works for both frameworks)
+ */
+function createErrorResponse(message: string, status: number): any {
+  // Try Next.js first
+  if (typeof (globalThis as any).NextResponse !== 'undefined') {
+    const NextResponse = (globalThis as any).NextResponse;
+    return NextResponse.json({ error: message }, { status });
+  }
+
+  // Fallback to standard Response
+  return new Response(
+    JSON.stringify({ error: message }),
+    {
+      status,
+      headers: { 'Content-Type': 'application/json' },
+    }
+  );
+}
+

package/src/adapters/base-handler.ts

@@ -0,0 +1,212 @@
+/**
+ * Base OAuth Handler
+ * Framework-agnostic OAuth route logic for secure server-side token management
+ */
+
+/**
+ * MCP Server URL - managed by Integrate
+ */
+const MCP_SERVER_URL = 'https://mcp.integrate.dev/api/v1/mcp';
+
+/**
+ * OAuth handler configuration
+ * OAuth credentials for each provider
+ */
+export interface OAuthHandlerConfig {
+  /** OAuth configurations by provider */
+  providers: Record<string, {
+    /** OAuth client ID from environment variables */
+    clientId: string;
+    /** OAuth client secret from environment variables */
+    clientSecret: string;
+    /** Optional redirect URI override */
+    redirectUri?: string;
+  }>;
+}
+
+/**
+ * Request body for authorize endpoint
+ */
+export interface AuthorizeRequest {
+  provider: string;
+  scopes: string[];
+  state: string;
+  codeChallenge: string;
+  codeChallengeMethod: string;
+  redirectUri?: string;
+}
+
+/**
+ * Response from authorize endpoint
+ */
+export interface AuthorizeResponse {
+  authorizationUrl: string;
+}
+
+/**
+ * Request body for callback endpoint
+ */
+export interface CallbackRequest {
+  provider: string;
+  code: string;
+  codeVerifier: string;
+  state: string;
+}
+
+/**
+ * Response from callback endpoint
+ */
+export interface CallbackResponse {
+  sessionToken: string;
+  provider: string;
+  scopes: string[];
+  expiresAt?: number;
+}
+
+/**
+ * Response from status endpoint
+ */
+export interface StatusResponse {
+  authorized: boolean;
+  provider: string;
+  scopes?: string[];
+  expiresAt?: number;
+}
+
+/**
+ * OAuth Handler
+ * Handles OAuth authorization flows by proxying requests to MCP server
+ * with server-side OAuth credentials from environment variables
+ */
+export class OAuthHandler {
+  private readonly serverUrl = MCP_SERVER_URL;
+  
+  constructor(private config: OAuthHandlerConfig) {}
+
+  /**
+   * Handle authorization URL request
+   * Gets authorization URL from MCP server with full OAuth credentials
+   * 
+   * @param request - Authorization request from client
+   * @returns Authorization URL to redirect/open for user
+   * 
+   * @throws Error if provider is not configured
+   * @throws Error if MCP server request fails
+   */
+  async handleAuthorize(request: AuthorizeRequest): Promise<AuthorizeResponse> {
+    // Get OAuth config from environment (server-side)
+    const providerConfig = this.config.providers[request.provider];
+    if (!providerConfig) {
+      throw new Error(`Provider ${request.provider} not configured. Add OAuth credentials to your API route configuration.`);
+    }
+
+    // Validate required fields
+    if (!providerConfig.clientId || !providerConfig.clientSecret) {
+      throw new Error(`Missing OAuth credentials for ${request.provider}. Check your environment variables.`);
+    }
+
+    // Build URL to MCP server
+    const url = new URL('/oauth/authorize', this.serverUrl);
+    url.searchParams.set('provider', request.provider);
+    url.searchParams.set('client_id', providerConfig.clientId);
+    url.searchParams.set('client_secret', providerConfig.clientSecret);
+    url.searchParams.set('scope', request.scopes.join(','));
+    url.searchParams.set('state', request.state);
+    url.searchParams.set('code_challenge', request.codeChallenge);
+    url.searchParams.set('code_challenge_method', request.codeChallengeMethod);
+    
+    // Use request redirect URI or fallback to provider config
+    const redirectUri = request.redirectUri || providerConfig.redirectUri;
+    if (redirectUri) {
+      url.searchParams.set('redirect_uri', redirectUri);
+    }
+
+    // Forward to MCP server
+    const response = await fetch(url.toString(), {
+      method: 'GET',
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`MCP server failed to generate authorization URL: ${error}`);
+    }
+
+    const data = await response.json();
+    return data as AuthorizeResponse;
+  }
+
+  /**
+   * Handle OAuth callback
+   * Exchanges authorization code for session token
+   * 
+   * @param request - Callback request with authorization code
+   * @returns Session token and authorization details
+   * 
+   * @throws Error if MCP server request fails
+   */
+  async handleCallback(request: CallbackRequest): Promise<CallbackResponse> {
+    // Forward to MCP server for token exchange
+    const url = new URL('/oauth/callback', this.serverUrl);
+
+    const response = await fetch(url.toString(), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        provider: request.provider,
+        code: request.code,
+        code_verifier: request.codeVerifier,
+        state: request.state,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`MCP server failed to exchange authorization code: ${error}`);
+    }
+
+    const data = await response.json();
+    return data as CallbackResponse;
+  }
+
+  /**
+   * Handle authorization status check
+   * Checks if a provider is currently authorized
+   * 
+   * @param provider - Provider to check
+   * @param sessionToken - Session token from client
+   * @returns Authorization status
+   * 
+   * @throws Error if MCP server request fails
+   */
+  async handleStatus(provider: string, sessionToken: string): Promise<StatusResponse> {
+    // Forward to MCP server
+    const url = new URL('/oauth/status', this.serverUrl);
+    url.searchParams.set('provider', provider);
+
+    const response = await fetch(url.toString(), {
+      method: 'GET',
+      headers: {
+        'X-Session-Token': sessionToken,
+      },
+    });
+
+    if (!response.ok) {
+      // If unauthorized, return not authorized status
+      if (response.status === 401) {
+        return {
+          authorized: false,
+          provider,
+        };
+      }
+
+      const error = await response.text();
+      throw new Error(`MCP server failed to check authorization status: ${error}`);
+    }
+
+    const data = await response.json();
+    return data as StatusResponse;
+  }
+}
+