integrate-sdk 0.2.3 → 0.3.1

package/README.md

@@ -12,8 +12,9 @@ A type-safe TypeScript SDK for connecting to the Integrate MCP (Model Context Pr
 - 🔌 **Plugin-Based Architecture** - Enable only the integrations you need
 - 🔒 **Fully Typed API** - Type-safe methods with autocomplete (e.g., `client.github.createIssue()`)
 - 💡 **IntelliSense Support** - Full TypeScript support with parameter hints
-- 🌊 **Real-time Communication** - HTTP streaming with NDJSON
-- 🔐 **OAuth Ready** - Configure OAuth credentials for each provider
+- ⚡ **Automatic Connection Management** - Lazy connection, auto-cleanup, singleton pattern
+- 🔐 **Complete OAuth Flow** - Built-in OAuth 2.0 with PKCE (popup/redirect modes)
+- 🌍 **Universal** - Works in browser and Node.js environments
 - 🛠️ **Extensible** - Configure plugins for any server-supported integration
 - 📦 **Zero Dependencies** - Lightweight implementation
 
@@ -27,44 +28,135 @@ bun add integrate-sdk
 
 ## Quick Start
 
+### Server-Side Setup
+
+First, create your server configuration with OAuth secrets:
+
+```typescript
+// lib/integrate-server.ts (server-side only!)
+import { createMCPServer, githubPlugin, gmailPlugin } from 'integrate-sdk/server';
+
+export const { client: serverClient, handlers } = createMCPServer({
+  plugins: [
+    githubPlugin({
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+      scopes: ['repo', 'user'],
+    }),
+    gmailPlugin({
+      clientId: process.env.GMAIL_CLIENT_ID,
+      clientSecret: process.env.GMAIL_CLIENT_SECRET,
+      scopes: ['gmail.readonly'],
+    }),
+  ],
+});
+```
+
+Create OAuth route (handles authorization automatically):
+
 ```typescript
-import { createMCPClient, githubPlugin } from "integrate-sdk";
+// app/api/integrate/oauth/[action]/route.ts
+export * from 'integrate-sdk/oauth';
+```
+
+Use the server client in API routes or server components:
+
+```typescript
+// app/api/repos/route.ts
+import { serverClient } from '@/lib/integrate-server';
+
+export async function GET() {
+  // Automatically connects on first call - no manual setup needed!
+  const repos = await serverClient.github.listOwnRepos({ per_page: 10 });
+  return Response.json({ repos });
+}
+```
+
+### Client-Side Setup
+
+Use in your client components (no secrets needed):
+
+```typescript
+'use client';
+import { createMCPClient, githubPlugin } from 'integrate-sdk';
 
-// Create a client with plugins
 const client = createMCPClient({
   plugins: [
     githubPlugin({
-      clientId: process.env.GITHUB_CLIENT_ID!,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-      scopes: ["repo", "user"],
+      scopes: ['repo', 'user'],
+      // No clientId or clientSecret needed!
     }),
   ],
+  oauthFlow: { mode: 'popup' },
 });
 
-// Connect to the server
-await client.connect();
+// Authorize user (opens popup)
+await client.authorize('github');
 
-// Call GitHub methods with full type safety
+// Use the client - automatically connects!
 const result = await client.github.createIssue({
-  owner: "owner",
-  repo: "repo",
-  title: "Bug report",
-  body: "Description of the bug",
+  owner: 'owner',
+  repo: 'repo',
+  title: 'Bug report',
+  body: 'Description of the bug',
+});
+
+console.log('Issue created:', result);
+```
+
+**That's it!** The SDK automatically:
+- ✅ Connects on first method call (no manual `connect()` needed)
+- ✅ Cleans up on exit (no manual `disconnect()` needed)
+- ✅ Manages OAuth tokens securely through your API routes
+- ✅ Provides full type safety with autocomplete
+
+### Connection Management
+
+The SDK automatically manages connections for you - no manual `connect()` or `disconnect()` calls needed!
+
+**Features:**
+- **Lazy Connection**: Automatically connects on first method call
+- **Auto-Cleanup**: Cleans up on process exit
+- **Singleton Pattern**: Reuses connections efficiently (configurable)
+
+```typescript
+// ✅ Default behavior - automatic connection
+const client = createMCPClient({
+  plugins: [
+    githubPlugin({
+      scopes: ['repo', 'user'],
+    }),
+  ],
 });
 
-console.log("Issue created:", result);
+// Use immediately - no connect() needed!
+await client.authorize('github');
+await client.github.listRepos({ username: 'octocat' });
 
-// Call server-level tools with typed methods
-const tools = await client.server.listToolsByIntegration({
-  integration: "github",
+// ✅ Want manual control? Use manual mode
+const manualClient = createMCPClient({
+  plugins: [githubPlugin({ scopes: ['repo'] })],
+  connectionMode: 'manual',
+  singleton: false,
 });
 
-// Disconnect when done
-await client.disconnect();
+await manualClient.connect();
+await manualClient.authorize('github');
+await manualClient.github.listRepos({ username: 'octocat' });
+await manualClient.disconnect();
 ```
 
 **Need help?** Check out the [complete documentation](https://integrate.dev) for detailed guides, examples, and API reference.
 
+## Browser & Server Support
+
+The SDK works in both environments:
+
+- **Browser**: Use `createMCPClient()` from `'integrate-sdk'` - handles OAuth UI (popup/redirect)
+- **Server**: Use `createMCPServer()` from `'integrate-sdk/server'` - includes OAuth secrets for API routes
+
+See [Quick Start](#quick-start) above for complete examples.
+
 ## Why Use Integrate SDK?
 
 ### Typed Plugin Methods
@@ -98,88 +190,82 @@ await client.server.listToolsByIntegration({ integration: "github" });
 await client._callToolByName("slack_send_message", { channel: "#general", text: "Hello" });
 ```
 
-## Built-in Plugins
+## OAuth Authorization
 
-### GitHub Plugin
+The SDK implements OAuth 2.0 Authorization Code Flow with PKCE for secure authorization.
 
-Access GitHub repositories, issues, pull requests, and more.
+**Key Features:**
+- ✅ Popup or redirect flow modes
+- ✅ Session token management
+- ✅ Multiple provider support
+- ✅ PKCE security
 
+**Basic Usage:**
 ```typescript
-const client = createMCPClient({
-  plugins: [
-    githubPlugin({
-      clientId: process.env.GITHUB_CLIENT_ID!,
-      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-      scopes: ["repo", "user"],
-    }),
-  ],
-});
+// Check authorization
+if (!await client.isAuthorized('github')) {
+  await client.authorize('github'); // Opens popup or redirects
+}
 
-await client.connect();
-
-// Use typed methods
-await client.github.getRepo({ owner: "facebook", repo: "react" });
-await client.github.createIssue({ owner: "user", repo: "repo", title: "Bug" });
-await client.github.listPullRequests({ owner: "user", repo: "repo", state: "open" });
+// Use authorized client
+const repos = await client.github.listOwnRepos({});
 ```
 
-[→ View GitHub plugin documentation](https://integrate.dev/docs/plugins/github)
+For complete OAuth setup including:
+- Popup vs redirect flows
+- Session token management
+- Multiple providers
+- Callback page setup
 
-### Gmail Plugin
+See the [`/examples`](/examples) directory or [OAuth documentation](https://integrate.dev/docs/guides/oauth-flow).
 
-Send emails, manage labels, and search messages.
+## Built-in Plugins
 
-```typescript
-const client = createMCPClient({
-  plugins: [
-    gmailPlugin({
-      clientId: process.env.GMAIL_CLIENT_ID!,
-      clientSecret: process.env.GMAIL_CLIENT_SECRET!,
-    }),
-  ],
-});
+### GitHub Plugin
 
-await client.connect();
+Access GitHub repositories, issues, pull requests, and more with type-safe methods.
 
-// Use typed methods
-await client.gmail.sendEmail({ to: "user@example.com", subject: "Hello", body: "Hi!" });
-await client.gmail.listEmails({ maxResults: 10, q: "is:unread" });
-await client.gmail.searchEmails({ query: "from:notifications@github.com" });
+```typescript
+// Available methods
+await client.github.getRepo({ owner: 'facebook', repo: 'react' });
+await client.github.createIssue({ owner: 'user', repo: 'repo', title: 'Bug' });
+await client.github.listPullRequests({ owner: 'user', repo: 'repo', state: 'open' });
+await client.github.listOwnRepos({});
 ```
 
-[→ View Gmail plugin documentation](https://integrate.dev/docs/plugins/gmail)
+[→ GitHub plugin documentation](https://integrate.dev/docs/plugins/github)
 
-### Configure Additional Integrations
+### Gmail Plugin
 
-The server may support additional integrations beyond GitHub and Gmail. You can configure OAuth and enable these tools using `genericOAuthPlugin`:
+Send emails, manage labels, and search messages with type-safe methods.
 
 ```typescript
-import { genericOAuthPlugin } from "integrate-sdk";
+// Available methods
+await client.gmail.sendEmail({ to: 'user@example.com', subject: 'Hello', body: 'Hi!' });
+await client.gmail.listEmails({ maxResults: 10, q: 'is:unread' });
+await client.gmail.searchEmails({ query: 'from:notifications@github.com' });
+```
 
-// Configure a plugin for any server-supported integration
-const slackPlugin = genericOAuthPlugin({
-  id: "slack",
-  provider: "slack",
-  clientId: process.env.SLACK_CLIENT_ID!,
-  clientSecret: process.env.SLACK_CLIENT_SECRET!,
-  scopes: ["chat:write", "channels:read"],
-  tools: ["slack_send_message", "slack_list_channels"], // Must exist on server
-});
+[→ Gmail plugin documentation](https://integrate.dev/docs/plugins/gmail)
 
-const client = createMCPClient({
-  plugins: [slackPlugin],
-});
+### Additional Integrations
+
+Use `genericOAuthPlugin` to configure any server-supported integration:
 
-await client.connect();
+```typescript
+import { genericOAuthPlugin } from 'integrate-sdk/server';
 
-// Use _callToolByName to call the tools
-await client._callToolByName("slack_send_message", { 
-  channel: "#general", 
-  text: "Hello!" 
+const slackPlugin = genericOAuthPlugin({
+  id: 'slack',
+  provider: 'slack',
+  clientId: process.env.SLACK_CLIENT_ID,
+  clientSecret: process.env.SLACK_CLIENT_SECRET,
+  scopes: ['chat:write', 'channels:read'],
+  tools: ['slack_send_message', 'slack_list_channels'],
 });
 ```
 
-**Note**: Plugins configure access to server-provided tools - they don't create new tools. All tool implementations must exist on the Integrate MCP server.
+See [`/examples`](/examples) for complete setup patterns.
 
 ## Vercel AI SDK Integration
 
@@ -209,6 +295,7 @@ const result = await generateText({
 For detailed guides, API reference, and examples, visit the [complete documentation](https://integrate.dev):
 
 - **[Getting Started](https://integrate.dev/docs/getting-started/installation)** - Installation and quick start
+- **[OAuth Flow](https://integrate.dev/docs/guides/oauth-flow)** - OAuth 2.0 authorization guide
 - **[Plugins](https://integrate.dev/docs/plugins)** - Built-in plugins and configuration
 - **[Vercel AI SDK](https://integrate.dev/docs/integrations/vercel-ai)** - AI model integration
 - **[Advanced Usage](https://integrate.dev/docs/guides/advanced-usage)** - Error handling, retries, and more

package/dist/adapters/auto-routes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Auto-generated OAuth Routes
+ * Automatically creates the correct route handlers based on framework detection
+ */
+import { type OAuthHandlerConfig } from './base-handler.js';
+/**
+ * Set the global OAuth configuration
+ * Called internally by createMCPClient
+ */
+export declare function setGlobalOAuthConfig(config: OAuthHandlerConfig): void;
+/**
+ * Get the global OAuth configuration
+ */
+export declare function getGlobalOAuthConfig(): OAuthHandlerConfig | null;
+/**
+ * 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';
+ * ```
+ */
+/**
+ * Universal POST handler
+ * Handles authorize and callback actions
+ */
+export declare function POST(req: any, context?: {
+    params: {
+        action: string;
+    };
+}): Promise<any>;
+/**
+ * Universal GET handler
+ * Handles status action
+ */
+export declare function GET(req: any, context?: {
+    params: {
+        action: string;
+    };
+}): Promise<any>;
+//# sourceMappingURL=auto-routes.d.ts.map

package/dist/adapters/auto-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-routes.d.ts","sourceRoot":"","sources":["../../src/adapters/auto-routes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAgB,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAQ1E;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAErE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,GAAG,IAAI,CAEhE;AAED;;;;;;;;;;;;;;;;;GAiBG;AAkBH;;;GAGG;AACH,wBAAsB,IAAI,CACxB,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE;IAAE,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACvC,OAAO,CAAC,GAAG,CAAC,CAgCd;AAED;;;GAGG;AACH,wBAAsB,GAAG,CACvB,GAAG,EAAE,GAAG,EACR,OAAO,CAAC,EAAE;IAAE,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACvC,OAAO,CAAC,GAAG,CAAC,CAkCd"}

package/dist/adapters/base-handler.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Base OAuth Handler
+ * Framework-agnostic OAuth route logic for secure server-side token management
+ */
+/**
+ * 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 declare class OAuthHandler {
+    private config;
+    private readonly serverUrl;
+    constructor(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
+     */
+    handleAuthorize(request: AuthorizeRequest): Promise<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
+     */
+    handleCallback(request: CallbackRequest): Promise<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
+     */
+    handleStatus(provider: string, sessionToken: string): Promise<StatusResponse>;
+}
+//# sourceMappingURL=base-handler.d.ts.map

package/dist/adapters/base-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-handler.d.ts","sourceRoot":"","sources":["../../src/adapters/base-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QACxB,iDAAiD;QACjD,QAAQ,EAAE,MAAM,CAAC;QACjB,qDAAqD;QACrD,YAAY,EAAE,MAAM,CAAC;QACrB,qCAAqC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAExB,MAAM,EAAE,kBAAkB;IAE9C;;;;;;;;;OASG;IACG,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA0C5E;;;;;;;;OAQG;IACG,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA0BzE;;;;;;;;;OASG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CA4BpF"}