npm - integrate-sdk - Versions diffs - 0.2.2 → 0.2.4 - Mend

integrate-sdk 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/README.md +181 -0
package/dist/client.d.ts +134 -6
package/dist/client.d.ts.map +1 -1
package/dist/config/types.d.ts +65 -0
package/dist/config/types.d.ts.map +1 -1
package/dist/index.d.ts +5 -1
package/dist/index.d.ts.map +1 -1
package/dist/index.js +533 -1
package/dist/oauth/manager.d.ts +91 -0
package/dist/oauth/manager.d.ts.map +1 -0
package/dist/oauth/pkce.d.ts +47 -0
package/dist/oauth/pkce.d.ts.map +1 -0
package/dist/oauth/types.d.ts +84 -0
package/dist/oauth/types.d.ts.map +1 -0
package/dist/oauth/window-manager.d.ts +103 -0
package/dist/oauth/window-manager.d.ts.map +1 -0
package/dist/transport/http-session.d.ts +23 -0
package/dist/transport/http-session.d.ts.map +1 -1
package/package.json +5 -5

package/README.md CHANGED Viewed

@@ -98,6 +98,187 @@ await client.server.listToolsByIntegration({ integration: "github" });
 await client._callToolByName("slack_send_message", { channel: "#general", text: "Hello" });
 ```
+## OAuth Authorization
+The SDK implements OAuth 2.0 Authorization Code Flow with PKCE for secure third-party service authorization. Users must authorize your application to access their GitHub, Gmail, or other accounts.
+### How It Works
+1. **Your App**: Creates client with OAuth configuration
+2. **SDK**: Initiates OAuth flow (popup or redirect)
+3. **User**: Authorizes permissions on provider's website
+4. **Provider**: Redirects back with authorization code
+5. **Your Server**: Exchanges code for tokens and stores them
+6. **SDK**: Includes session token in all API requests
+7. **Your Server**: Uses stored OAuth tokens for API calls
+### Quick Start
+```typescript
+import { createMCPClient, githubPlugin } from "integrate-sdk";
+// Create client with OAuth flow configuration
+const client = createMCPClient({
+  plugins: [
+    githubPlugin({
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+      scopes: ["repo", "user"],
+      redirectUri: "http://localhost:3000/oauth/callback",
+    }),
+  ],
+  oauthFlow: {
+    mode: 'popup', // or 'redirect'
+    popupOptions: { width: 600, height: 700 },
+  },
+});
+// Check if authorized
+const isAuthorized = await client.isAuthorized('github');
+if (!isAuthorized) {
+  // Initiate OAuth flow - opens popup or redirects
+  await client.authorize('github');
+}
+// Now you can use GitHub tools
+const repos = await client.github.listOwnRepos({});
+```
+### Popup Flow (Recommended for SPAs)
+Best for single-page applications - authorization happens in a popup without leaving your app.
+```typescript
+const client = createMCPClient({
+  plugins: [githubPlugin({ ... })],
+  oauthFlow: { mode: 'popup' },
+});
+// This opens a popup for authorization
+await client.authorize('github');
+// After user approves, continues automatically
+const repos = await client.github.listOwnRepos({});
+```
+**Callback Page**: Create `/oauth/callback.html`:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>OAuth Callback</title>
+  <script type="module">
+    import { sendCallbackToOpener } from 'integrate-sdk';
+    const params = new URLSearchParams(window.location.search);
+    sendCallbackToOpener({
+      code: params.get('code'),
+      state: params.get('state'),
+      error: params.get('error')
+    });
+  </script>
+</head>
+<body>
+  <p>Authorization successful! Closing...</p>
+</body>
+</html>
+```
+### Redirect Flow (Traditional Web Apps)
+Best for traditional server-rendered applications.
+```typescript
+// Main page
+const client = createMCPClient({
+  plugins: [githubPlugin({ ... })],
+  oauthFlow: { mode: 'redirect' },
+});
+if (!await client.isAuthorized('github')) {
+  await client.authorize('github'); // Redirects to GitHub
+}
+// Callback page (e.g., /oauth/callback)
+const params = new URLSearchParams(window.location.search);
+await client.handleOAuthCallback({
+  code: params.get('code')!,
+  state: params.get('state')!
+});
+// Save session token for future use
+const sessionToken = client.getSessionToken();
+localStorage.setItem('session_token', sessionToken);
+// Redirect back to main app
+```
+### Session Token Management
+Store and restore sessions to avoid re-authorization:
+```typescript
+// Restore previous session
+const client = createMCPClient({
+  plugins: [githubPlugin({ ... })],
+  sessionToken: localStorage.getItem('session_token'),
+});
+// Check if session is still valid
+if (!await client.isAuthorized('github')) {
+  await client.authorize('github');
+}
+// Store token after new authorization
+const token = client.getSessionToken();
+localStorage.setItem('session_token', token);
+```
+### Multiple Providers
+Authorize multiple services independently:
+```typescript
+const client = createMCPClient({
+  plugins: [
+    githubPlugin({ ... }),
+    gmailPlugin({ ... }),
+  ],
+  oauthFlow: { mode: 'popup' },
+});
+// Get list of all authorized providers
+const authorized = await client.authorizedProviders();
+console.log('Authorized:', authorized); // ['github', 'gmail']
+// Or check and authorize each provider individually
+if (!await client.isAuthorized('github')) {
+  await client.authorize('github');
+}
+if (!await client.isAuthorized('gmail')) {
+  await client.authorize('gmail');
+}
+// Use both services
+const repos = await client.github.listOwnRepos({});
+const messages = await client.gmail.listMessages({});
+```
+### Server Requirements
+Your MCP server must implement these OAuth endpoints:
+**GET `/oauth/authorize`** - Returns authorization URL
+**POST `/oauth/callback`** - Exchanges code for tokens, returns session token
+**GET `/oauth/status`** - Checks authorization status
+All tool endpoints must accept `X-Session-Token` header and use stored OAuth tokens for API calls.
+[→ View complete OAuth flow implementation guide](/docs/guides/oauth-flow.md)
 ## Built-in Plugins
 ### GitHub Plugin

package/dist/client.d.ts CHANGED Viewed

@@ -9,6 +9,7 @@ import { type AuthenticationError } from "./errors.js";
 import type { GitHubPluginClient } from "./plugins/github-client.js";
 import type { GmailPluginClient } from "./plugins/gmail-client.js";
 import type { ServerPluginClient } from "./plugins/server-client.js";
+import type { AuthStatus, OAuthCallbackParams } from "./oauth/types.js";
 /**
  * Tool invocation options
  */
@@ -52,6 +53,9 @@ export declare class MCPClient<TPlugins extends readonly MCPPlugin[] = readonly
     private onReauthRequired?;
     private maxReauthRetries;
     private authState;
+    private connectionMode;
+    private connecting;
+    private oauthManager;
     readonly github: PluginNamespaces<TPlugins> extends {
         github: GitHubPluginClient;
     } ? GitHubPluginClient : never;
@@ -60,6 +64,10 @@ export declare class MCPClient<TPlugins extends readonly MCPPlugin[] = readonly
     } ? GmailPluginClient : never;
     readonly server: ServerPluginClient;
     constructor(config: MCPClientConfig<TPlugins>);
+    /**
+     * Ensure the client is connected (for lazy connection mode)
+     */
+    private ensureConnected;
     /**
      * Create a proxy for a plugin namespace that intercepts method calls
      * and routes them to the appropriate tool
@@ -163,6 +171,97 @@ export declare class MCPClient<TPlugins extends readonly MCPPlugin[] = readonly
      * Check if a specific provider is authenticated
      */
     isProviderAuthenticated(provider: string): boolean;
+    /**
+     * Check if a provider is authorized via OAuth
+     * Queries the MCP server to verify OAuth token validity
+     *
+     * @param provider - Provider name (github, gmail, etc.)
+     * @returns Authorization status
+     *
+     * @example
+     * ```typescript
+     * const isAuthorized = await client.isAuthorized('github');
+     * if (!isAuthorized) {
+     *   await client.authorize('github');
+     * }
+     * ```
+     */
+    isAuthorized(provider: string): Promise<boolean>;
+    /**
+     * Get list of all authorized providers
+     * Checks all configured OAuth providers and returns names of authorized ones
+     *
+     * @returns Array of authorized provider names
+     *
+     * @example
+     * ```typescript
+     * const authorized = await client.authorizedProviders();
+     * console.log('Authorized services:', authorized); // ['github', 'gmail']
+     *
+     * // Check if specific service is in the list
+     * if (authorized.includes('github')) {
+     *   const repos = await client.github.listOwnRepos({});
+     * }
+     * ```
+     */
+    authorizedProviders(): Promise<string[]>;
+    /**
+     * Get detailed authorization status for a provider
+     *
+     * @param provider - Provider name
+     * @returns Full authorization status including scopes and expiration
+     */
+    getAuthorizationStatus(provider: string): Promise<AuthStatus>;
+    /**
+     * Initiate OAuth authorization flow for a provider
+     * Opens authorization URL in popup or redirects based on configuration
+     *
+     * @param provider - Provider name (github, gmail, etc.)
+     *
+     * @example
+     * ```typescript
+     * // Popup flow
+     * await client.authorize('github');
+     *
+     * // Redirect flow
+     * await client.authorize('github'); // User is redirected away
+     * ```
+     */
+    authorize(provider: string): Promise<void>;
+    /**
+     * Handle OAuth callback after user authorization
+     * Call this from your OAuth callback page with code and state from URL
+     *
+     * @param params - Callback parameters containing code and state
+     *
+     * @example
+     * ```typescript
+     * // In your callback route (e.g., /oauth/callback)
+     * const params = new URLSearchParams(window.location.search);
+     * await client.handleOAuthCallback({
+     *   code: params.get('code')!,
+     *   state: params.get('state')!
+     * });
+     *
+     * // Now you can use the client
+     * const repos = await client.github.listOwnRepos({});
+     * ```
+     */
+    handleOAuthCallback(params: OAuthCallbackParams): Promise<void>;
+    /**
+     * Get the current session token
+     * Useful for storing and restoring sessions
+     *
+     * @returns Session token or undefined if not authorized
+     */
+    getSessionToken(): string | undefined;
+    /**
+     * Set session token manually
+     * Use this if you have an existing session token
+     *
+     * @param token - Session token
+     */
+    setSessionToken(token: string): void;
     /**
      * Manually trigger re-authentication for a specific provider
      * Useful if you want to proactively refresh tokens
@@ -172,24 +271,53 @@ export declare class MCPClient<TPlugins extends readonly MCPPlugin[] = readonly
 /**
  * Create a new MCP Client instance
  *
- * Connects to the Integrate MCP server at https://mcp.integrate.dev/api/v1/mcp
+ * By default, uses singleton pattern and lazy connection:
+ * - Returns cached instance if one exists with same configuration
+ * - Automatically connects on first method call
+ * - Automatically cleans up on process exit
  *
  * @example
  * ```typescript
+ * // Lazy connection (default) - connects automatically on first use
  * const client = createMCPClient({
  *   plugins: [
  *     githubPlugin({ clientId: '...', clientSecret: '...' }),
- *     gmailPlugin({ clientId: '...', clientSecret: '...' }),
  *   ],
  * });
  *
- * await client.connect();
- * const result = await client.callTool('github_create_issue', {
- *   repo: 'owner/repo',
- *   title: 'Bug report',
+ * // No need to call connect()!
+ * const repos = await client.github.listOwnRepos({});
+ *
+ * // No need to call disconnect()! (auto-cleanup on exit)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Manual connection mode (original behavior)
+ * const client = createMCPClient({
+ *   plugins: [githubPlugin({ ... })],
+ *   connectionMode: 'manual',
+ *   singleton: false,
  * });
+ *
+ * await client.connect();
+ * const repos = await client.github.listOwnRepos({});
+ * await client.disconnect();
  * ```
  */
 export declare function createMCPClient<TPlugins extends readonly MCPPlugin[]>(config: MCPClientConfig<TPlugins>): MCPClient<TPlugins>;
+/**
+ * Clear the client cache and disconnect all cached clients
+ * Useful for testing or when you need to force recreation of clients
+ *
+ * @example
+ * ```typescript
+ * // In test teardown
+ * afterAll(async () => {
+ *   await clearClientCache();
+ * });
+ * ```
+ */
+export declare function clearClientCache(): Promise<void>;
 export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EACV,OAAO,EAEP,mBAAmB,EAIpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,mBAAmB,CAAC;AACxE,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;~~AAOrE~~;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gBAAgB;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,EAAE,GAAG,KAAK,CAAC;AAClE,KAAK,SAAS,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,IAAI,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAE1F;;GAEG;AACH,KAAK,WAAW,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,EAAE,EAAE,SAAS,MAAM,IACvE,EAAE,SAAS,SAAS,CAAC,QAAQ,CAAC,GAAG,IAAI,GAAG,KAAK,CAAC;AAEhD;;GAEG;AACH,KAAK,gBAAgB,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,IACzD,CAAC,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,SAAS,IAAI,GAAG;IAAE,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAAG,EAAE,CAAC,GACpF,CAAC,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,IAAI,GAAG;IAAE,KAAK,EAAE,iBAAiB,CAAA;CAAE,GAAG,EAAE,CAAC,CAAC;AAEpF;;;;GAIG;AACH,qBAAa,SAAS,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,GAAG,SAAS,SAAS,EAAE;IACjF,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,OAAO,CAAW;IAC1B,OAAO,CAAC,cAAc,CAAmC;IACzD,OAAO,CAAC,gBAAgB,CAA0B;IAClD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAoC;IACtD,OAAO,CAAC,gBAAgB,CAAC,CAAgB;IACzC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,SAAS,CAAuF;~~IAGxG~~,SAAgB,MAAM,EAAG,gBAAgB,CAAC,QAAQ,CAAC,SAAS;QAAE,MAAM,EAAE,kBAAkB,CAAA;KAAE,GACtF,kBAAkB,GAClB,KAAK,CAAC;IACV,SAAgB,KAAK,EAAG,gBAAgB,CAAC,QAAQ,CAAC,SAAS;QAAE,KAAK,EAAE,iBAAiB,CAAA;KAAE,GACnF,iBAAiB,GACjB,KAAK,CAAC;IAGV,SAAgB,MAAM,EAAG,kBAAkB,CAAC;gBAEhC,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC;~~IAoC7C~~;;;OAGG;IACH,OAAO,CAAC,iBAAiB;~~IAYzB~~;;OAEG;IACH,OAAO,CAAC,iBAAiB;~~IAczB~~;;OAEG;YACW,sBAAsB;IAmCpC;;OAEG;YACW,iBAAiB;IAQ/B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB9B;;OAEG;YACW,UAAU;IAkBxB;;OAEG;YACW,aAAa;IAoB3B;;;;OAIG;IACG,eAAe,CACnB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAI/B;;;;;;;;;;;OAWG;IACG,cAAc,CAClB,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAgC/B;;OAEG;YACW,iBAAiB;IA4E/B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI1C;;OAEG;IACH,iBAAiB,IAAI,OAAO,EAAE;IAI9B;;OAEG;IACH,eAAe,IAAI,OAAO,EAAE;IAM5B;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAKzD;;OAEG;IACH,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC;IAU9C;;OAEG;IACH,SAAS,CACP,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAClC,MAAM,IAAI;IAIb;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAYjC;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG;QAAE,aAAa,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,mBAAmB,CAAA;KAAE,GAAG,SAAS;IAIvG;;OAEG;IACH,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIlD;;;OAGG;IACG,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CA2BzD;~~AAED;;;;;;;;;;;;;;;;;;;;GAoBG~~;AACH,wBAAgB,eAAe,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,EACnE,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,GAChC,SAAS,CAAC,QAAQ,CAAC,~~CAErB~~"}
1	+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/config/types.d.ts CHANGED Viewed

@@ -63,6 +63,71 @@ export interface MCPClientConfig<TPlugins extends readonly MCPPlugin[]> {
      * 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;
 }
 /**
  * Helper type to infer enabled tools from plugins

package/dist/config/types.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,EAAE,mBAAmB,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE;IACpE,iCAAiC;IACjC,OAAO,EAAE,QAAQ,CAAC;IAElB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yBAAyB;IACzB,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CAAC,EAAE,aAAa,CAAC;IAEjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;~~CAC3B~~;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,IACjE,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpC;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,IAAI;KACnE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;CAC/C,CAAC"}
1	+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,EAAE,mBAAmB,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;AAEnF;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE;IACpE,iCAAiC;IACjC,OAAO,EAAE,QAAQ,CAAC;IAElB,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjC,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yBAAyB;IACzB,UAAU,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,CAAC,EAAE,aAAa,CAAC;IAEjC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAE7C;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,EAAE;QACV,+DAA+D;QAC/D,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;QAC5B,oDAAoD;QACpD,YAAY,CAAC,EAAE;YACb,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,MAAM,CAAC,EAAE,MAAM,CAAC;SACjB,CAAC;QACF,sDAAsD;QACtD,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACnF,CAAC;IAEF;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,IACjE,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpC;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,QAAQ,SAAS,SAAS,SAAS,EAAE,IAAI;KACnE,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC;CAC/C,CAAC"}

package/dist/index.d.ts CHANGED Viewed

@@ -2,8 +2,12 @@
  * Integrate SDK
  * Type-safe TypeScript SDK for MCP Client
  */
-export { MCPClient, createMCPClient } from "./client.js";
+export { MCPClient, createMCPClient, clearClientCache } from "./client.js";
 export type { ToolInvocationOptions } from "./client.js";
+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, } from "./oauth/types.js";
 export type { MCPClientConfig, ReauthContext, ReauthHandler } from "./config/types.js";
 export { IntegrateSDKError, AuthenticationError, AuthorizationError, TokenExpiredError, ConnectionError, ToolCallError, isAuthError, isTokenExpiredError, isAuthorizationError, parseServerError, } from "./errors.js";
 export type { MCPPlugin, OAuthConfig, ExtractPluginIds, ExtractPluginTools, } from "./plugins/types.js";

package/dist/index.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;~~AACzD~~,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGzD,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"}
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,GACpB,MAAM,kBAAkB,CAAC;AAG1B,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"}