oauth-callback 1.2.4 → 2.0.0

package/README.md

@@ -31,33 +31,38 @@ A lightweight OAuth 2.0 callback handler for Node.js, Deno, and Bun with built-i
 ## Installation
 
 ```bash
-bun add oauth-callback
+bun add oauth-callback open
 ```
 
 Or with npm:
 
 ```bash
-npm install oauth-callback
+npm install oauth-callback open
 ```
 
+> **Note:** The `open` package is optional but recommended for browser launching. If using pnpm, install it explicitly: `pnpm add open`
+
 ## Quick Start
 
 ```typescript
+import open from "open";
 import { getAuthCode, OAuthError } from "oauth-callback";
 
-// Simple usage
-const result = await getAuthCode(
-  "https://example.com/oauth/authorize?client_id=xxx&redirect_uri=http://localhost:3000/callback",
-);
+// Simple usage - pass `open` to launch browser
+const result = await getAuthCode({
+  authorizationUrl:
+    "https://example.com/oauth/authorize?client_id=xxx&redirect_uri=http://localhost:3000/callback",
+  launch: open,
+});
 console.log("Authorization code:", result.code);
 
 // MCP SDK integration - use specific import
 import { browserAuth, fileStore } from "oauth-callback/mcp";
-const authProvider = browserAuth({ store: fileStore() });
+const authProvider = browserAuth({ launch: open, store: fileStore() });
 
 // Or via namespace import
 import { mcp } from "oauth-callback";
-const authProvider = mcp.browserAuth({ store: mcp.fileStore() });
+const authProvider = mcp.browserAuth({ launch: open, store: mcp.fileStore() });
 ```
 
 ## Usage Examples
@@ -65,6 +70,7 @@ const authProvider = mcp.browserAuth({ store: mcp.fileStore() });
 ### Basic OAuth Flow
 
 ```typescript
+import open from "open";
 import { getAuthCode, OAuthError } from "oauth-callback";
 
 async function authenticate() {
@@ -78,7 +84,10 @@ async function authenticate() {
     });
 
   try {
-    const result = await getAuthCode(authUrl);
+    const result = await getAuthCode({
+      authorizationUrl: authUrl,
+      launch: open,
+    });
     console.log("Authorization code:", result.code);
     console.log("State:", result.state);
 
@@ -98,10 +107,12 @@ async function authenticate() {
 ### Custom Port Configuration
 
 ```typescript
+import open from "open";
 import { getAuthCode } from "oauth-callback";
 
 const result = await getAuthCode({
   authorizationUrl: authUrl,
+  launch: open,
   port: 8080, // Use custom port (default: 3000)
   timeout: 60000, // Custom timeout in ms (default: 30000)
 });
@@ -175,9 +186,12 @@ const authProvider = browserAuth({
 ### Advanced Usage
 
 ```typescript
+import open from "open";
+
 // With custom HTML templates and logging
 const result = await getAuthCode({
   authorizationUrl: authUrl,
+  launch: open,
   port: 3000,
   hostname: "127.0.0.1", // Bind to specific IP
   successHtml: "<h1>Success! You can close this window.</h1>",
@@ -209,7 +223,7 @@ try {
 
 ### `getAuthCode(input)`
 
-Starts a local HTTP server and opens the authorization URL in the user's browser.
+Starts a local HTTP server to capture OAuth callbacks. Optionally launches the authorization URL via the `launch` callback.
 
 #### Parameters
 
@@ -219,7 +233,7 @@ Starts a local HTTP server and opens the authorization URL in the user's browser
   - `hostname` (string): Hostname to bind the server to (default: "localhost")
   - `callbackPath` (string): URL path for the OAuth callback (default: "/callback")
   - `timeout` (number): Timeout in milliseconds (default: 30000)
-  - `openBrowser` (boolean): Whether to open browser automatically (default: true)
+  - `launch` (function): Optional callback to launch the authorization URL (e.g., `open`)
   - `successHtml` (string): Custom HTML to display on successful authorization
   - `errorHtml` (string): Custom HTML to display on authorization error
   - `signal` (AbortSignal): AbortSignal for cancellation support
@@ -311,7 +325,7 @@ TokenStore implementation for persistent token storage.
 ```
 
 1. **Server Creation** — Spins up a temporary localhost HTTP server
-2. **Browser Launch** — Opens the authorization URL in the default browser
+2. **Browser Launch** — Opens the authorization URL (if `launch` callback provided)
 3. **User Authorization** — User grants permission on the OAuth provider's page
 4. **Callback Capture** — Provider redirects to localhost with the authorization code
 5. **Cleanup** — Server closes automatically, code is returned to your app
@@ -420,7 +434,11 @@ bun run example:notion  # Notion MCP example with Dynamic Client Registration
 If port 3000 is already in use, specify a different port:
 
 ```typescript
-const result = await getAuthCode({ authorizationUrl: authUrl, port: 8080 });
+const result = await getAuthCode({
+  authorizationUrl: authUrl,
+  launch: open,
+  port: 8080,
+});
 ```
 
 ### Firewall Warnings
@@ -433,13 +451,9 @@ If the browser doesn't open automatically, manually navigate to the authorizatio
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for setup instructions.
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+**Maintainers wanted** — we're looking for people to help maintain this project. If interested, reach out on [Discord](https://discord.gg/bSsv7XM) or open an issue.
 
 ## License
 

package/dist/auth/browser-auth.d.ts

@@ -8,9 +8,11 @@ import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.
  *
  * @example
  * ```typescript
+ * import open from "open";
+ *
  * const transport = new StreamableHTTPClientTransport(
  *   new URL("https://mcp.notion.com/mcp"),
- *   { authProvider: browserAuth() }
+ *   { authProvider: browserAuth({ launch: open }) }
  * );
  * ```
  */

package/dist/auth/browser-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-auth.d.ts","sourceRoot":"","sources":["../../src/auth/browser-auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAMnB,MAAM,cAAc,CAAC;AAKtB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAQpF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,OAAO,GAAE,kBAAuB,GAC/B,mBAAmB,CAErB"}
+{"version":3,"file":"browser-auth.d.ts","sourceRoot":"","sources":["../../src/auth/browser-auth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,kBAAkB,EAMnB,MAAM,cAAc,CAAC;AAItB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAC;AAQpF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,OAAO,GAAE,kBAAuB,GAC/B,mBAAmB,CAErB"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { type CallbackResult } from "./server";
 import type { GetAuthCodeOptions } from "./types";
 export type { CallbackResult, CallbackServer, ServerOptions } from "./server";
-export { OAuthError } from "./errors";
+export { OAuthError, TimeoutError } from "./errors";
 export type { GetAuthCodeOptions } from "./types";
 export { inMemoryStore } from "./storage/memory";
 export { fileStore } from "./storage/file";
@@ -9,7 +9,7 @@ import * as mcp from "./mcp";
 export { mcp };
 /**
  * Captures OAuth authorization code via localhost callback.
- * Opens browser to auth URL, waits for provider redirect to localhost.
+ * Starts a temporary server, optionally launches auth URL, waits for redirect.
  *
  * @param input - Auth URL string or GetAuthCodeOptions with config
  * @returns Promise<CallbackResult> with code and params
@@ -18,17 +18,18 @@ export { mcp };
  *
  * @example
  * ```typescript
- * // Simple
- * const result = await getAuthCode('https://oauth.example.com/authorize?...');
- * console.log('Code:', result.code);
+ * import open from "open";
  *
- * // Custom port/timeout
+ * // With browser launch
  * const result = await getAuthCode({
  *   authorizationUrl: 'https://oauth.example.com/authorize?...',
- *   port: 8080,
- *   timeout: 60000,
- *   onRequest: (req) => console.log('Request:', req.url)
+ *   launch: open,
  * });
+ *
+ * // Headless (print URL, let user open manually)
+ * const url = 'https://oauth.example.com/authorize?...';
+ * console.log('Open:', url);
+ * const result = await getAuthCode({ authorizationUrl: url });
  * ```
  */
 export declare function getAuthCode(input: GetAuthCodeOptions | string): Promise<CallbackResult>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,kBAAkB,GAAG,MAAM,GACjC,OAAO,CAAC,cAAc,CAAC,CA8DzB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,KAAK,GAAG,MAAM,OAAO,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,CAAC;AAEf;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,kBAAkB,GAAG,MAAM,GACjC,OAAO,CAAC,cAAc,CAAC,CA+CzB"}