integrate-sdk 0.3.6 → 0.3.7

package/src/adapters/nextjs-callback.tsx

@@ -0,0 +1,160 @@
+/**
+ * Next.js OAuth Callback Handler
+ * Provides a pre-built OAuth callback page component for Next.js App Router
+ * 
+ * This eliminates the need for users to manually create callback pages.
+ */
+
+'use client';
+
+import { useEffect } from 'react';
+import type { OAuthCallbackHandlerConfig } from '../oauth/types.js';
+
+/**
+ * OAuth Callback Page Component
+ * 
+ * This component:
+ * 1. Extracts OAuth callback parameters (code, state, error) from URL
+ * 2. Sends them to the opener window (for popup mode) via postMessage
+ * 3. Stores them in sessionStorage (for redirect mode)
+ * 4. Redirects to the configured URL
+ * 
+ * @param config - Callback handler configuration
+ * 
+ * @example
+ * ```tsx
+ * // app/oauth/callback/page.tsx
+ * import { OAuthCallbackPage } from 'integrate-sdk/oauth-callback';
+ * 
+ * export default function CallbackPage() {
+ *   return <OAuthCallbackPage redirectUrl="/dashboard" />;
+ * }
+ * ```
+ */
+export function OAuthCallbackPage(config?: OAuthCallbackHandlerConfig) {
+  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');
+
+    // Handle error case
+    if (error) {
+      const errorMsg = errorDescription || error;
+      console.error('[OAuth Callback] Error:', errorMsg);
+      window.location.href = `${errorRedirectUrl}?error=${encodeURIComponent(errorMsg)}`;
+      return;
+    }
+
+    // Validate required params
+    if (!code || !state) {
+      console.error('[OAuth Callback] Missing code or state parameter');
+      window.location.href = `${errorRedirectUrl}?error=${encodeURIComponent('Invalid OAuth callback')}`;
+      return;
+    }
+
+    // For popup mode: send message to opener window
+    if (window.opener) {
+      // Send message immediately
+      window.opener.postMessage(
+        {
+          type: 'oauth_callback',
+          code,
+          state,
+        },
+        '*'
+      );
+
+      // Close popup after a brief delay to ensure message is received
+      setTimeout(() => {
+        window.close();
+      }, 100);
+    } else {
+      // For redirect mode: store in sessionStorage and redirect
+      try {
+        sessionStorage.setItem(
+          'oauth_callback_params',
+          JSON.stringify({ code, state })
+        );
+      } catch (e) {
+        console.error('Failed to store OAuth callback params:', e);
+      }
+
+      // Redirect to the configured URL
+      setTimeout(() => {
+        window.location.href = redirectUrl;
+      }, 500);
+    }
+  }, [redirectUrl, errorRedirectUrl]);
+
+  return (
+    <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',
+      }}
+    >
+      <div style={{ textAlign: 'center', padding: '2rem' }}>
+        <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',
+          }}
+        />
+        <h1
+          style={{
+            margin: '0 0 0.5rem',
+            fontSize: '1.5rem',
+            fontWeight: 600,
+          }}
+        >
+          Authorization Complete
+        </h1>
+        <p style={{ margin: 0, opacity: 0.9, fontSize: '0.875rem' }}>
+          This window will close automatically...
+        </p>
+        <style>{`
+          @keyframes spin {
+            0% { transform: rotate(0deg); }
+            100% { transform: rotate(360deg); }
+          }
+        `}</style>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Create a default export wrapper for easier usage
+ * 
+ * @example
+ * ```tsx
+ * // app/oauth/callback/page.tsx
+ * import { createOAuthCallbackPage } from 'integrate-sdk/oauth-callback';
+ * 
+ * export default createOAuthCallbackPage({
+ *   redirectUrl: '/dashboard',
+ * });
+ * ```
+ */
+export function createOAuthCallbackPage(config?: OAuthCallbackHandlerConfig) {
+  return function OAuthCallback() {
+    return <OAuthCallbackPage {...config} />;
+  };
+}

package/src/adapters/nextjs.ts

@@ -0,0 +1,318 @@
+/**
+ * Next.js OAuth Route Adapter
+ * Provides OAuth route handlers for Next.js App Router
+ * 
+ * Note: This file uses type imports only to avoid requiring Next.js at build time.
+ * The actual Next.js types are used at runtime when available.
+ */
+
+import { OAuthHandler, type OAuthHandlerConfig } from './base-handler.js';
+
+// Type-only imports to avoid requiring Next.js at build time
+type NextRequest = any;
+type NextResponse = any;
+
+/**
+ * Create Next.js OAuth route handlers
+ * 
+ * Use this to create secure OAuth API routes in your Next.js application
+ * that handle authorization with server-side secrets.
+ * 
+ * @param config - OAuth handler configuration with provider credentials
+ * @returns Object with authorize, callback, and status route handlers, plus a unified handler
+ * 
+ * @example
+ * **Simple Setup (Recommended)** - One route file handles everything:
+ * 
+ * ```typescript
+ * // app/api/integrate/oauth/[action]/route.ts
+ * import { createNextOAuthHandler } from 'integrate-sdk';
+ * 
+ * const handler = createNextOAuthHandler({
+ *   providers: {
+ *     github: {
+ *       clientId: process.env.GITHUB_CLIENT_ID!,
+ *       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+ *     },
+ *   },
+ * });
+ * 
+ * export const { POST, GET } = handler.createRoutes();
+ * ```
+ * 
+ * @example
+ * **Advanced Setup** - Separate routes for each action:
+ * 
+ * ```typescript
+ * // app/api/integrate/oauth/authorize/route.ts
+ * export const POST = handler.authorize;
+ * 
+ * // app/api/integrate/oauth/callback/route.ts
+ * export const POST = handler.callback;
+ * 
+ * // app/api/integrate/oauth/status/route.ts
+ * export const GET = handler.status;
+ * ```
+ */
+export function createNextOAuthHandler(config: OAuthHandlerConfig) {
+  const handler = new OAuthHandler(config);
+
+  const handlers = {
+    /**
+     * POST /api/integrate/oauth/authorize
+     * 
+     * Request authorization URL from MCP server with server-side OAuth credentials
+     * 
+     * Request body:
+     * ```json
+     * {
+     *   "provider": "github",
+     *   "scopes": ["repo", "user"],
+     *   "state": "random-state-string",
+     *   "codeChallenge": "pkce-code-challenge",
+     *   "codeChallengeMethod": "S256",
+     *   "redirectUri": "https://yourapp.com/oauth/callback"
+     * }
+     * ```
+     * 
+     * Response:
+     * ```json
+     * {
+     *   "authorizationUrl": "https://github.com/login/oauth/authorize?..."
+     * }
+     * ```
+     * 
+     * @example
+     * ```typescript
+     * // app/api/integrate/oauth/authorize/route.ts
+     * import { createNextOAuthHandler } from 'integrate-sdk';
+     * 
+     * const handler = createNextOAuthHandler({
+     *        *   providers: {
+     *     github: {
+     *       clientId: process.env.GITHUB_CLIENT_ID!,
+     *       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+     *     },
+     *   },
+     * });
+     * 
+     * export const POST = handler.authorize;
+     * ```
+     */
+    async authorize(req: NextRequest): Promise<NextResponse> {
+      try {
+        const body = await req.json();
+        const result = await handler.handleAuthorize(body);
+        return Response.json(result);
+      } catch (error: any) {
+        console.error('[OAuth Authorize] Error:', error);
+        return Response.json(
+          { error: error.message || 'Failed to get authorization URL' },
+          { status: 500 }
+        );
+      }
+    },
+
+    /**
+     * POST /api/integrate/oauth/callback
+     * 
+     * Exchange authorization code for session token
+     * 
+     * Request body:
+     * ```json
+     * {
+     *   "provider": "github",
+     *   "code": "authorization-code",
+     *   "codeVerifier": "pkce-code-verifier",
+     *   "state": "state-from-authorize"
+     * }
+     * ```
+     * 
+     * Response:
+     * ```json
+     * {
+     *   "sessionToken": "session-token-123",
+     *   "provider": "github",
+     *   "scopes": ["repo", "user"],
+     *   "expiresAt": 1234567890
+     * }
+     * ```
+     * 
+     * @example
+     * ```typescript
+     * // app/api/integrate/oauth/callback/route.ts
+     * import { createNextOAuthHandler } from 'integrate-sdk';
+     * 
+     * const handler = createNextOAuthHandler({
+     *        *   providers: {
+     *     github: {
+     *       clientId: process.env.GITHUB_CLIENT_ID!,
+     *       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+     *     },
+     *   },
+     * });
+     * 
+     * export const POST = handler.callback;
+     * ```
+     */
+    async callback(req: NextRequest): Promise<NextResponse> {
+      try {
+        const body = await req.json();
+        const result = await handler.handleCallback(body);
+        return Response.json(result);
+      } catch (error: any) {
+        console.error('[OAuth Callback] Error:', error);
+        return Response.json(
+          { error: error.message || 'Failed to exchange authorization code' },
+          { status: 500 }
+        );
+      }
+    },
+
+    /**
+     * GET /api/integrate/oauth/status?provider=github
+     * 
+     * Check if a provider is currently authorized
+     * 
+     * Query parameters:
+     * - provider: Provider to check (e.g., "github")
+     * 
+     * Headers:
+     * - X-Session-Token: Session token from previous authorization
+     * 
+     * Response:
+     * ```json
+     * {
+     *   "authorized": true,
+     *   "provider": "github",
+     *   "scopes": ["repo", "user"],
+     *   "expiresAt": 1234567890
+     * }
+     * ```
+     * 
+     * @example
+     * ```typescript
+     * // app/api/integrate/oauth/status/route.ts
+     * import { createNextOAuthHandler } from 'integrate-sdk';
+     * 
+     * const handler = createNextOAuthHandler({
+     *        *   providers: {
+     *     github: {
+     *       clientId: process.env.GITHUB_CLIENT_ID!,
+     *       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+     *     },
+     *   },
+     * });
+     * 
+     * export const GET = handler.status;
+     * ```
+     */
+    async status(req: NextRequest): Promise<NextResponse> {
+      try {
+        const provider = req.nextUrl.searchParams.get('provider');
+        const sessionToken = req.headers.get('x-session-token');
+
+        if (!provider) {
+          return Response.json(
+            { error: 'Missing provider query parameter' },
+            { status: 400 }
+          );
+        }
+
+        if (!sessionToken) {
+          return Response.json(
+            { error: 'Missing X-Session-Token header' },
+            { status: 400 }
+          );
+        }
+
+        const result = await handler.handleStatus(provider, sessionToken);
+        return Response.json(result);
+      } catch (error: any) {
+        console.error('[OAuth Status] Error:', error);
+        return Response.json(
+          { error: error.message || 'Failed to check authorization status' },
+          { status: 500 }
+        );
+      }
+    },
+
+    /**
+     * Create unified route handlers for catch-all route
+     * 
+     * This is the simplest way to set up OAuth routes - create a single catch-all
+     * route file that handles all OAuth actions.
+     * 
+     * @returns Object with POST and GET handlers for Next.js dynamic routes
+     * 
+     * @example
+     * ```typescript
+     * // app/api/integrate/oauth/[action]/route.ts
+     * import { createNextOAuthHandler } from 'integrate-sdk';
+     * 
+     * const handler = createNextOAuthHandler({
+     *   providers: {
+     *     github: {
+     *       clientId: process.env.GITHUB_CLIENT_ID!,
+     *       clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+     *     },
+     *   },
+     * });
+     * 
+     * export const { POST, GET } = handler.createRoutes();
+     * ```
+     */
+    createRoutes() {
+      return {
+        /**
+         * POST handler for authorize and callback actions
+         */
+        async POST(
+          req: NextRequest,
+          context: { params: { action: string } | Promise<{ action: string }> }
+        ): Promise<NextResponse> {
+          // Handle both Next.js 14 (sync params) and Next.js 15+ (async params)
+          const params = context.params instanceof Promise ? await context.params : context.params;
+          const action = params.action;
+
+          if (action === 'authorize') {
+            return handlers.authorize(req);
+          }
+
+          if (action === 'callback') {
+            return handlers.callback(req);
+          }
+
+          return Response.json(
+            { error: `Unknown action: ${action}` },
+            { status: 404 }
+          );
+        },
+
+        /**
+         * GET handler for status action
+         */
+        async GET(
+          req: NextRequest,
+          context: { params: { action: string } | Promise<{ action: string }> }
+        ): Promise<NextResponse> {
+          // Handle both Next.js 14 (sync params) and Next.js 15+ (async params)
+          const params = context.params instanceof Promise ? await context.params : context.params;
+          const action = params.action;
+
+          if (action === 'status') {
+            return handlers.status(req);
+          }
+
+          return Response.json(
+            { error: `Unknown action: ${action}` },
+            { status: 404 }
+          );
+        },
+      };
+    },
+  };
+
+  return handlers;
+}
+