oauth2-cli 0.8.0 → 0.8.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.8.2](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.8.1...oauth2-cli/0.8.2) (2026-02-18)
+
+
+### Features
+
+* isAuthorized() ([56b0436](https://github.com/battis/oauth2-cli/commit/56b0436d98b9d9f213518e806ead846321180a63))
+
+
+### Bug Fixes
+
+* block thread until interactive authorization complete ([fb9987e](https://github.com/battis/oauth2-cli/commit/fb9987e41a5a8f129955bc3e88ab17994860091b)), closes [#22](https://github.com/battis/oauth2-cli/issues/22)
+
+## [0.8.1](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.8.0...oauth2-cli/0.8.1) (2026-02-18)
+
+
+### Features
+
+* provide parameterized credentials with simplified typing ([5a92c67](https://github.com/battis/oauth2-cli/commit/5a92c67dbd4ab52fa4f0b02a910e788f5ae67adb))
+
 ## [0.8.0](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.7.3...oauth2-cli/0.8.0) (2026-02-17)
 
 ### ⚠ BREAKING CHANGES

package/dist/Client.d.ts

@@ -1,4 +1,5 @@
 import { PathString } from '@battis/descriptive-types';
+import { JSONValue } from '@battis/typescript-tricks';
 import { Request } from 'express';
 import { EventEmitter } from 'node:events';
 import * as OpenIDClient from 'openid-client';
@@ -12,9 +13,9 @@ import * as Token from './Token/index.js';
  * `redirect_uri` values
  */
 export declare const DEFAULT_REDIRECT_URI = "http://localhost:3000/oauth2-cli/redirect";
-export type ClientOptions = {
+export type ClientOptions<C extends Credentials = Credentials> = {
     /** Credentials for server access */
-    credentials: Credentials;
+    credentials: C;
     /** Optional request components to inject */
     inject?: {
         search?: requestish.URLSearchParams.ish;
@@ -63,9 +64,9 @@ type GetTokenOptions = {
  *
  * Emits {@link Client.TokenEvent} whenever a new access token is received
  */
-export declare class Client extends EventEmitter {
+export declare class Client<C extends Credentials = Credentials> extends EventEmitter {
     static readonly TokenEvent = "token";
-    protected credentials: Credentials;
+    protected credentials: C;
     protected base_url?: requestish.URL.ish;
     protected config?: OpenIDClient.Configuration;
     protected inject?: Injection;
@@ -73,7 +74,7 @@ export declare class Client extends EventEmitter {
     private token?;
     private tokenLock;
     private storage?;
-    constructor({ credentials, base_url, views, inject, storage }: ClientOptions);
+    constructor({ credentials, base_url, views, inject, storage }: ClientOptions<C>);
     get redirect_uri(): requestish.URL.ish;
     /**
      * @throws IndeterminateConfiguration if provided credentials combined with
@@ -83,6 +84,7 @@ export declare class Client extends EventEmitter {
     protected getParameters(session: Session): Promise<URLSearchParams>;
     getAuthorizationUrl(session: Session): Promise<URL>;
     createSession({ views, ...options }: Omit<SessionOptions, 'client'>): Session;
+    isAuthorized(): Promise<boolean>;
     authorize(options?: Omit<SessionOptions, 'client'>): Promise<Token.Response>;
     handleAuthorizationCodeRedirect(req: Request, session: Session): Promise<void>;
     protected refreshTokenGrant({ refresh_token, inject: request }?: RefreshOptions): Promise<Token.Response | undefined>;
@@ -107,10 +109,10 @@ export declare class Client extends EventEmitter {
     private toJSON;
     /**
      * Returns the result of {@link request} as a parsed JSON object, optionally
-     * typed as `T`
+     * typed as `J`
      */
-    requestJSON<T extends OpenIDClient.JsonValue = OpenIDClient.JsonValue>(url: requestish.URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<T>;
+    requestJSON<J extends JSONValue = JSONValue>(url: requestish.URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
     fetch(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
-    fetchJSON<T extends OpenIDClient.JsonValue = OpenIDClient.JsonValue>(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<T>;
+    fetchJSON<J extends JSONValue = JSONValue>(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
 }
 export {};

package/dist/Client.js

@@ -91,6 +91,16 @@ export class Client extends EventEmitter {
             ...options
         });
     }
+    async isAuthorized() {
+        if (this.token?.expiresIn()) {
+            return true;
+        }
+        else {
+            return await this.tokenLock.runExclusive(async () => {
+                return !!(await this.refreshTokenGrant());
+            });
+        }
+    }
     async authorize(options = {}) {
         const session = this.createSession(options);
         const token = await this.save(await session.authorizationCodeGrant());
@@ -98,16 +108,20 @@ export class Client extends EventEmitter {
     }
     async handleAuthorizationCodeRedirect(req, session) {
         try {
-            const response = await OpenIDClient.authorizationCodeGrant(await this.getConfiguration(), new URL(req.url, this.redirect_uri), {
+            /**
+             * Do _NOT_ await this promise: the WebServer needs to send the
+             * authorization complete response asynchronously before this can resolve,
+             * and awaiting session.resolve() will block that response.
+             */
+            session.resolve(await OpenIDClient.authorizationCodeGrant(await this.getConfiguration(), new URL(req.url, this.redirect_uri), {
                 pkceCodeVerifier: session.code_verifier,
                 expectedState: session.state
             }, this.inject?.search
                 ? requestish.URLSearchParams.from(this.inject.search)
-                : undefined);
-            await session.resolve(response);
+                : undefined));
         }
-        catch (error) {
-            await session.resolve(undefined, error);
+        catch (cause) {
+            session.reject(new Error('Error making Authorization Code Grant request', { cause }));
         }
     }
     async refreshTokenGrant({ refresh_token = this.token?.refresh_token, inject: request } = {}) {
@@ -214,7 +228,7 @@ export class Client extends EventEmitter {
     }
     /**
      * Returns the result of {@link request} as a parsed JSON object, optionally
-     * typed as `T`
+     * typed as `J`
      */
     async requestJSON(url, method = 'GET', body, headers = {}, dPoPOptions) {
         return await this.toJSON(await this.request(url, method, body, headers, dPoPOptions));

package/dist/Session.d.ts

@@ -11,7 +11,7 @@ export type SessionOptions = {
     /** Additional request injection for authorization code grant flow */
     inject?: Injection;
 };
-export type Resolver = (response?: Token.Response, error?: Error) => void | Promise<void>;
+export type SessionResolver = (response: Token.Response) => void | Promise<void>;
 export declare class Session {
     private readonly client;
     private readonly outOfBandRedirectServer;
@@ -21,19 +21,21 @@ export declare class Session {
     readonly state: string;
     /** Additional request injection for Authorization Code Grant request */
     readonly inject?: Injection;
+    private spinner;
     private _resolve?;
-    private spinner?;
     /**
      * Method that resolves or rejects the promise returned from the
      * {@link authorizationCodeGrant}
      */
-    get resolve(): Resolver;
+    get resolve(): SessionResolver;
+    reject(error: Error): void;
     constructor({ client, views, inject: request }: SessionOptions);
     /** Instantiate the web server that will listen for the out-of-band redirect */
-    createWebServer(options: Omit<WebServer.WebServerOptions, 'session'>): WebServer.WebServerInterface;
+    protected instantiateWebServer(options: Omit<WebServer.WebServerOptions, 'session'>): WebServer.WebServerInterface;
     /**
      * Trigger the start of the Authorization Code Grant flow, returnig a Promise
-     * that will resolve into the eventual token
+     * that will resolve into the eventual token. This will close the out-of-band
+     * redirect server that creating the session started.
      */
     authorizationCodeGrant(): Promise<Token.Response>;
     /** OAuth 2.0 redirect_uri that this session is handling */

package/dist/Session.js

@@ -1,6 +1,5 @@
 import { Colors } from '@qui-cli/colors';
 import * as gcrtl from 'gcrtl';
-import open from 'open';
 import * as OpenIDClient from 'openid-client';
 import ora from 'ora';
 import * as WebServer from './WebServer.js';
@@ -13,8 +12,8 @@ export class Session {
     state = OpenIDClient.randomState();
     /** Additional request injection for Authorization Code Grant request */
     inject;
-    _resolve;
     spinner;
+    _resolve;
     /**
      * Method that resolves or rejects the promise returned from the
      * {@link authorizationCodeGrant}
@@ -25,37 +24,61 @@ export class Session {
         }
         return this._resolve;
     }
+    reject(error) {
+        throw error;
+    }
     constructor({ client, views, inject: request }) {
+        this.spinner = ora('Awaiting interactive authorization').start();
         this.client = client;
         this.inject = request;
-        this.outOfBandRedirectServer = this.createWebServer({ views });
+        this.outOfBandRedirectServer = this.instantiateWebServer({ views });
     }
     /** Instantiate the web server that will listen for the out-of-band redirect */
-    createWebServer(options) {
+    instantiateWebServer(options) {
         return new WebServer.WebServer({ session: this, ...options });
     }
     /**
      * Trigger the start of the Authorization Code Grant flow, returnig a Promise
-     * that will resolve into the eventual token
+     * that will resolve into the eventual token. This will close the out-of-band
+     * redirect server that creating the session started.
      */
-    authorizationCodeGrant() {
-        return new Promise((resolve, reject) => {
-            this._resolve = async (response, error) => {
-                if (error) {
-                    reject(error);
-                }
-                if (response) {
-                    resolve(response);
-                }
-                else {
-                    reject(new Error('Authorization Code Grant response undefined.'));
-                }
-            };
-            const url = gcrtl
-                .expand(this.outOfBandRedirectServer.authorization_endpoint, this.client.redirect_uri)
-                .toString();
-            this.spinner = ora(`Waiting for interactive authorization at ${Colors.url(url)}`).start();
-            open(url);
+    async authorizationCodeGrant() {
+        return await new Promise((resolve, reject) => {
+            try {
+                this._resolve = (response) => {
+                    let closed = false;
+                    this.spinner.text =
+                        'Waiting for out-of-band redirect server to shut down';
+                    this.outOfBandRedirectServer.close().then(() => {
+                        closed = true;
+                        this.spinner.succeed('Interactive authorization complete');
+                        resolve(response);
+                    });
+                    setTimeout(() => {
+                        if (!closed) {
+                            this.spinner.text =
+                                'Still waiting for out-of-band redirect server to shut down.\n' +
+                                    '  Your browser may be holding the connection to the server open.\n' +
+                                    '  Please close the "Authorization Complete" tab in your browser.\n\n' +
+                                    '    If you are browsing in Chrome, close the window.\n' +
+                                    '    If you are browsing in Opera, quit the browser.';
+                        }
+                    }, 10000);
+                };
+                const url = gcrtl
+                    .expand(this.outOfBandRedirectServer.authorization_endpoint, this.client.redirect_uri)
+                    .toString();
+                //open(url);
+                this.spinner.text = `Please continue interactive authorization at ${Colors.url(url)} in your browser`;
+            }
+            catch (cause) {
+                this.spinner.text =
+                    'Waiting for out-of-band redirect server to shut down';
+                this.outOfBandRedirectServer.close().then(() => {
+                    this.spinner.fail('Interactive authorization failed');
+                    reject(new Error('Error in Authorization Code flow', { cause }));
+                });
+            }
         });
     }
     /** OAuth 2.0 redirect_uri that this session is handling */
@@ -70,7 +93,8 @@ export class Session {
      * Code Grant flow
      */
     async handleAuthorizationCodeRedirect(req) {
-        this.spinner?.succeed('Interactive authorization begun');
+        this.spinner.text =
+            'Completing access token request with provided authorization code';
         return await this.client.handleAuthorizationCodeRedirect(req, this);
     }
 }

package/dist/WebServer.d.ts

@@ -20,6 +20,8 @@ export declare const DEFAULT_AUTHORIZE_ENDPOINT = "/oauth2-cli/authorize";
 export interface WebServerInterface {
     /** See {@link WebServerOptions} */
     readonly authorization_endpoint: PathString;
+    /** Shut down web server */
+    close(): Promise<void>;
 }
 /**
  * Minimal HTTP server running on localhost to handle the redirect step of
@@ -59,6 +61,6 @@ export declare class WebServer implements WebServerInterface {
     protected handleAuthorizationEndpoint(req: Request, res: Response): Promise<void>;
     /** Handles request to `redirect_uri` */
     protected handleRedirect(req: Request, res: Response): Promise<void>;
-    /** Close server */
+    /** Shut down web server */
     close(): Promise<void>;
 }

package/dist/WebServer.js

@@ -79,6 +79,7 @@ export class WebServer {
         const authorization_url = await this.session.getAuthorizationUrl();
         if (!(await this.render(res, 'authorize.ejs', { authorization_url }))) {
             res.redirect(authorization_url);
+            res.end();
         }
     }
     /** Handles request to `redirect_uri` */
@@ -94,16 +95,15 @@ export class WebServer {
                 res.send(error);
             }
         }
-        finally {
-            this.close();
-        }
     }
-    /** Close server */
+    /** Shut down web server */
     async close() {
         return new Promise((resolve, reject) => {
-            this.server.close((err) => {
-                if (err) {
-                    reject(err);
+            this.server.close((cause) => {
+                if (cause) {
+                    reject(new Error('Error shutting down out-of-band redirect web server', {
+                        cause
+                    }));
                 }
                 else {
                     WebServer.activePorts.splice(WebServer.activePorts.indexOf(this.port), 1);

package/dist/index.d.ts

@@ -1,2 +1,6 @@
-export * from './Export.js';
-export * from './Extend.js';
+export * from './Client.js';
+export * from './Credentials.js';
+export * from './Injection.js';
+export * as Scope from './Scope.js';
+export * as Token from './Token/index.js';
+export * from './WebServer.js';

package/dist/index.js

@@ -1,2 +1,6 @@
-export * from './Export.js';
-export * from './Extend.js';
+export * from './Client.js';
+export * from './Credentials.js';
+export * from './Injection.js';
+export * as Scope from './Scope.js';
+export * as Token from './Token/index.js';
+export * from './WebServer.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth2-cli",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Acquire API access tokens via OAuth 2.0 within CLI tools",
   "homepage": "https://github.com/battis/oauth2-cli/tree/main/packages/oauth2-cli#readme",
   "repository": {
@@ -20,7 +20,6 @@
     "async-mutex": "^0.5.0",
     "express": "^5.2.1",
     "oauth4webapi": "^3.8.5",
-    "open": "^11.0.0",
     "openid-client": "^6.8.2",
     "ora": "^9.3.0",
     "gcrtl": "0.1.7",

package/dist/Export.d.ts

@@ -1,4 +0,0 @@
-export * from './Credentials.js';
-export * from './Injection.js';
-export * as Scope from './Scope.js';
-export * from './WebServer.js';

package/dist/Export.js

@@ -1,4 +0,0 @@
-export * from './Credentials.js';
-export * from './Injection.js';
-export * as Scope from './Scope.js';
-export * from './WebServer.js';

package/dist/Extend.d.ts

@@ -1,2 +0,0 @@
-export * from './Client.js';
-export * as Token from './Token/index.js';

package/dist/Extend.js

@@ -1,2 +0,0 @@
-export * from './Client.js';
-export * as Token from './Token/index.js';