oauth-callback 2.0.0 → 2.1.0

package/README.md

@@ -131,6 +131,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 const authProvider = browserAuth({
   port: 3000,
   scope: "read write",
+  launch: open, // Opens browser for OAuth consent
   store: inMemoryStore(), // Or fileStore() for persistence
 });
 
@@ -155,17 +156,20 @@ import { browserAuth, inMemoryStore, fileStore } from "oauth-callback/mcp";
 
 // Ephemeral storage (tokens lost on restart)
 const ephemeralAuth = browserAuth({
+  launch: open,
   store: inMemoryStore(),
 });
 
 // Persistent file storage (default: ~/.mcp/tokens.json)
 const persistentAuth = browserAuth({
+  launch: open,
   store: fileStore(),
   storeKey: "my-app-tokens", // Namespace for multiple apps
 });
 
 // Custom file location
 const customAuth = browserAuth({
+  launch: open,
   store: fileStore("/path/to/tokens.json"),
 });
 ```
@@ -179,6 +183,7 @@ const authProvider = browserAuth({
   clientId: "your-client-id",
   clientSecret: "your-client-secret",
   scope: "read write",
+  launch: open, // Opens browser for OAuth consent
   store: fileStore(), // Persist tokens across sessions
 });
 ```
@@ -283,6 +288,7 @@ Available from `oauth-callback/mcp`. Creates an MCP SDK-compatible OAuth provide
   - `clientSecret` (string): Pre-registered client secret (optional)
   - `store` (TokenStore): Token storage implementation (default: inMemoryStore())
   - `storeKey` (string): Storage key for tokens (default: "mcp-tokens")
+  - `launch` (function): Callback to launch auth URL (e.g., `open`)
   - `authTimeout` (number): Authorization timeout in ms (default: 300000)
   - `successHtml` (string): Custom success page HTML
   - `errorHtml` (string): Custom error page HTML

package/dist/index.d.ts

@@ -7,11 +7,34 @@ export { inMemoryStore } from "./storage/memory";
 export { fileStore } from "./storage/file";
 import * as mcp from "./mcp";
 export { mcp };
+/**
+ * Builds the redirect URI for OAuth configuration.
+ * Use this to construct the redirect_uri parameter for your authorization URL.
+ *
+ * @example
+ * ```typescript
+ * const redirectUri = getRedirectUrl({ port: 3000 });
+ * // => "http://localhost:3000/callback"
+ *
+ * const authUrl = `https://oauth.example.com/authorize?redirect_uri=${encodeURIComponent(redirectUri)}`;
+ * console.log('Open:', authUrl);
+ * await getAuthCode({ port: 3000 });
+ * ```
+ */
+export declare function getRedirectUrl(options?: {
+    port?: number;
+    hostname?: string;
+    callbackPath?: string;
+}): string;
 /**
  * Captures OAuth authorization code via localhost callback.
  * Starts a temporary server, optionally launches auth URL, waits for redirect.
  *
- * @param input - Auth URL string or GetAuthCodeOptions with config
+ * Two modes:
+ * - **Managed**: Pass both `authorizationUrl` and `launch` — library opens browser
+ * - **Headless**: Pass neither — caller handles URL display (CI/SSH/custom UI)
+ *
+ * @param input - Auth URL string (auto-launches browser) or GetAuthCodeOptions
  * @returns Promise<CallbackResult> with code and params
  * @throws {OAuthError} Provider errors (access_denied, invalid_scope)
  * @throws {Error} Timeout, network failures, port conflicts
@@ -20,16 +43,16 @@ export { mcp };
  * ```typescript
  * import open from "open";
  *
- * // With browser launch
+ * // Managed mode: library launches browser
  * const result = await getAuthCode({
  *   authorizationUrl: 'https://oauth.example.com/authorize?...',
  *   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 });
+ * // Headless mode: caller handles URL display
+ * const authUrl = 'https://oauth.example.com/authorize?...';
+ * console.log('Open this URL:', authUrl);
+ * const result = await getAuthCode({ port: 3000, timeout: 60000 });
  * ```
  */
 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":"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"}
+{"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;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE;IACP,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CAClB,GACL,MAAM,CAOR;AASD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,kBAAkB,GAAG,MAAM,GACjC,OAAO,CAAC,cAAc,CAAC,CAmDzB"}