oauth-callback 0.0.1 → 0.1.0

package/README.md

@@ -1,16 +1,20 @@
 # OAuth Callback Server
 
-A lightweight local HTTP server for handling OAuth 2.0 authorization callbacks in Node.js/Bun applications. Perfect for CLI tools, desktop applications, and development environments that need to capture OAuth authorization codes.
+A lightweight local HTTP server for handling OAuth 2.0 authorization callbacks in Node.js, Deno, and Bun applications. Perfect for CLI tools, desktop applications, and development environments that need to capture OAuth authorization codes.
 
 ## Features
 
-- 🚀 Simple async/await API
-- 🔒 Secure local server for OAuth callbacks
-- ⚡ Zero dependencies (when using Bun)
-- 🎯 TypeScript support out of the box
-- 🛡️ Built-in error handling for OAuth errors
-- 🔄 Automatic server cleanup after callback
-- 📱 Cross-platform support (Windows, macOS, Linux)
+- 🚀 **Multi-runtime support** - Works with Node.js 18+, Deno, and Bun
+- 🔒 **Secure localhost-only server** for OAuth callbacks  
+- ⚡ **Minimal dependencies** - Only requires `open` package
+- 🎯 **TypeScript support** out of the box
+- 🛡️ **Comprehensive OAuth error handling** with detailed error classes
+- 🔄 **Automatic server cleanup** after callback
+- 🎪 **Auto-closing success pages** with countdown timer
+- 🎨 **Customizable HTML templates** with placeholder support
+- 🚦 **AbortSignal support** for programmatic cancellation
+- 📝 **Request logging and debugging** callbacks
+- 🌐 **Modern Web Standards APIs** (Request/Response/URL)
 
 ## Installation
 
@@ -76,7 +80,8 @@ async function authenticate() {
 ```typescript
 import { getAuthCode } from "oauth-callback";
 
-const result = await getAuthCode(authUrl, {
+const result = await getAuthCode({
+  authorizationUrl: authUrl,
   port: 8080, // Use custom port (default: 3000)
   timeout: 60000, // Custom timeout in ms (default: 30000)
 });
@@ -110,21 +115,58 @@ const microsoftAuth = await getAuthCode(
 );
 ```
 
+### Advanced Usage
+
+```typescript
+// With custom HTML templates and logging
+const result = await getAuthCode({
+  authorizationUrl: authUrl,
+  port: 3000,
+  hostname: "127.0.0.1", // Bind to specific IP
+  successHtml: "<h1>Success! You can close this window.</h1>",
+  errorHtml: "<h1>Error: {{error_description}}</h1>",
+  onRequest: (req) => {
+    console.log(`Received request: ${req.method} ${req.url}`);
+  },
+});
+
+// With cancellation support
+const controller = new AbortController();
+
+// Cancel after 10 seconds
+setTimeout(() => controller.abort(), 10000);
+
+try {
+  const result = await getAuthCode({
+    authorizationUrl: authUrl,
+    signal: controller.signal,
+  });
+} catch (error) {
+  if (error.message === "Operation aborted") {
+    console.log("Authorization was cancelled");
+  }
+}
+```
+
 ## API Reference
 
-### `getAuthCode(authUrl, options?)`
+### `getAuthCode(input)`
 
 Starts a local HTTP server and opens the authorization URL in the user's browser.
 
 #### Parameters
 
-- `authUrl` (string): The OAuth authorization URL
-- `options` (object, optional):
+- `input` (string | GetAuthCodeOptions): Either a string containing the OAuth authorization URL, or an options object with:
+  - `authorizationUrl` (string): The OAuth authorization URL
   - `port` (number): Port for the local server (default: 3000)
+  - `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)
-  - `callbackPath` (string): Callback path (default: "/callback")
-  - `successMessage` (string): Message shown on successful authorization
-  - `errorMessage` (string): Message shown on authorization error
+  - `openBrowser` (boolean): Whether to open browser automatically (default: true)
+  - `successHtml` (string): Custom HTML to display on successful authorization
+  - `errorHtml` (string): Custom HTML to display on authorization error
+  - `signal` (AbortSignal): AbortSignal for cancellation support
+  - `onRequest` (function): Callback fired when a request is received (for logging/debugging)
 
 #### Returns
 
@@ -140,9 +182,8 @@ Promise that resolves to:
 
 #### Throws
 
-- `OAuthError`: When the OAuth provider returns an error
-- `TimeoutError`: When the authorization times out
-- `Error`: For other unexpected errors
+- `OAuthError`: When the OAuth provider returns an error (always thrown for OAuth errors)
+- `Error`: For timeout or other unexpected errors
 
 ### `OAuthError`
 
@@ -167,10 +208,9 @@ class OAuthError extends Error {
 ## Security Considerations
 
 - The server only accepts connections from localhost
-- Automatically validates the state parameter if provided
 - Server is closed immediately after receiving the callback
-- Supports PKCE (Proof Key for Code Exchange) flow
 - No data is stored persistently
+- State parameter validation should be implemented by the application
 
 ## Development
 
@@ -190,7 +230,7 @@ bun run example.ts
 
 ## Requirements
 
-- Node.js 14+ or Bun 1.0+
+- Node.js 18+ (for native Request/Response support), Deno, or Bun 1.0+
 - A registered OAuth application with a provider
 - Redirect URI configured as `http://localhost:[port]/callback`
 
@@ -201,7 +241,7 @@ bun run example.ts
 If port 3000 is already in use, specify a different port:
 
 ```typescript
-const result = await getAuthCode(authUrl, { port: 8080 });
+const result = await getAuthCode({ authorizationUrl: authUrl, port: 8080 });
 ```
 
 ### Firewall Warnings

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Custom error class for OAuth-specific errors
+ *
+ * This error is thrown when the OAuth provider returns an error response
+ * (e.g., user denies access, invalid client, etc.). It preserves the
+ * original OAuth error details for proper error handling.
+ */
+export declare class OAuthError extends Error {
+    /** OAuth error code (e.g., 'access_denied', 'invalid_request') */
+    error: string;
+    /** Human-readable error description provided by OAuth provider */
+    error_description?: string;
+    /** URI with additional information about the error */
+    error_uri?: string;
+    /**
+     * Create a new OAuthError
+     * @param error - OAuth error code
+     * @param description - Human-readable error description
+     * @param uri - URI with additional error information
+     */
+    constructor(error: string, description?: string, uri?: string);
+}
+/**
+ * Error thrown when OAuth callback times out
+ *
+ * This error indicates that no OAuth callback was received within the
+ * specified timeout period. This could happen if the user doesn't complete
+ * the authorization flow or if there are network connectivity issues.
+ */
+export declare class TimeoutError extends Error {
+    /**
+     * Create a new TimeoutError
+     * @param message - Custom error message (optional)
+     */
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;OAKG;gBACS,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM;CAO9D;AAED;;;;;;GAMG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC;;;OAGG;gBACS,OAAO,GAAE,MAAmC;CAIzD"}

package/dist/index.d.ts

@@ -1,15 +1,36 @@
+import { type CallbackResult } from "./server";
+import type { GetAuthCodeOptions } from "./types";
+export type { CallbackResult, CallbackServer, ServerOptions } from "./server";
+export { OAuthError } from "./errors";
+export type { GetAuthCodeOptions } from "./types";
 /**
  * Get the OAuth authorization code from the authorization URL.
  *
- * @param input Authorization URL or authorization options.
+ * Creates a temporary local HTTP server to handle the OAuth callback,
+ * opens the authorization URL in the user's browser, and waits for the
+ * OAuth provider to redirect back with an authorization code.
+ *
+ * @param input - Either a string containing the OAuth authorization URL,
+ *                or a GetAuthCodeOptions object with detailed configuration
+ * @returns Promise that resolves to CallbackResult containing the authorization code
+ *          and other parameters, or rejects with OAuthError if authorization fails
+ * @throws {OAuthError} When OAuth provider returns an error (e.g., access_denied)
+ * @throws {Error} For timeout, network errors, or other unexpected failures
+ *
+ * @example
+ * ```typescript
+ * // Simple usage with URL string
+ * const result = await getAuthCode('https://oauth.example.com/authorize?...');
+ * console.log('Code:', result.code);
+ *
+ * // Advanced usage with options
+ * const result = await getAuthCode({
+ *   authorizationUrl: 'https://oauth.example.com/authorize?...',
+ *   port: 8080,
+ *   timeout: 60000,
+ *   onRequest: (req) => console.log('Request:', req.url)
+ * });
+ * ```
  */
-export declare function getAuthCode(input: {
-    /** OAuth authorization URL */
-    authorizeUrl: string;
-    /** @default 3000 */
-    port?: number;
-    /** @default true  */
-    throwOnError?: boolean;
-    /** @default true */
-    openBrowser?: boolean;
-} | string): Promise<void>;
+export declare function getAuthCode(input: GetAuthCodeOptions | string): Promise<CallbackResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGlD,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;AAElD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,kBAAkB,GAAG,MAAM,GACjC,OAAO,CAAC,cAAc,CAAC,CAsEzB"}