@oauth2-cli/qui-cli 0.7.15 → 1.0.0

package/CHANGELOG.md

@@ -2,27 +2,42 @@
 
 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.7.15](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.14...qui-cli-plugin/0.7.15) (2026-02-19)
+## [1.0.0](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.16...qui-cli-plugin/1.0.0) (2026-02-20)
 
+### ⚠ BREAKING CHANGES
 
-### Bug Fixes
+- dist/Unregistered.js -> extendable
+- rename WebServer -> Localhost, authorize.ejs -> launch.ejs
+- simplify access to client name by making it (only) a read-only property
 
-* further debugging log refinement ([26bad46](https://github.com/battis/oauth2-cli/commit/26bad46741fc0b2075099054e7127e90a1a4a002))
+### Features
 
-## [0.7.14](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.13...qui-cli-plugin/0.7.14) (2026-02-19)
+- dist/Unregistered.js -> extendable ([1734d05](https://github.com/battis/oauth2-cli/commit/1734d05845e2b5960a6636d591605973df38b696))
+- human-readable reason for authorizing access ([0cce8c2](https://github.com/battis/oauth2-cli/commit/0cce8c2e13213e92befc4f58c81e6d7f9637ea63))
+- rename WebServer -> Localhost, authorize.ejs -> launch.ejs ([09723a8](https://github.com/battis/oauth2-cli/commit/09723a81640cb8ad0e767584a81b9b56f5a617b2))
+- simplify access to client name by making it (only) a read-only property ([401c870](https://github.com/battis/oauth2-cli/commit/401c870071c0e9ffc65282e8c42270dff6e897a2))
 
+### Bug Fixes
+
+- improve client debug logging ([f53575d](https://github.com/battis/oauth2-cli/commit/f53575d855665a868f8a803ff3fb197faff9543d))
+
+## [0.7.16](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.15...qui-cli-plugin/0.7.16) (2026-02-19)
 
 ### Bug Fixes
 
-* further refinement in debug logging ([568e563](https://github.com/battis/oauth2-cli/commit/568e563bc0a918cd9741951654db685488f10330))
+- removing potential source of authorization failure ([15d7d89](https://github.com/battis/oauth2-cli/commit/15d7d8980337df3f66afa8398b3cccb1fc6b56b6))
 
-## [0.7.13](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.12...qui-cli-plugin/0.7.13) (2026-02-19)
+## [0.7.15](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.14...qui-cli-plugin/0.7.15) (2026-02-19)
 
-Incorporates oauth2-cli@0.8.8
+### Bug Fixes
+
+- further debugging log refinement ([26bad46](https://github.com/battis/oauth2-cli/commit/26bad46741fc0b2075099054e7127e90a1a4a002))
+
+## [0.7.14](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.13...qui-cli-plugin/0.7.14) (2026-02-19)
 
-## [0.7.10](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.9...qui-cli-plugin/0.7.10) (2026-02-19)
+### Bug Fixes
 
-Incorporates oauth2-cli@0.8.5 updates
+- further refinement in debug logging ([568e563](https://github.com/battis/oauth2-cli/commit/568e563bc0a918cd9741951654db685488f10330))
 
 ## [0.7.7](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.6...qui-cli-plugin/0.7.7) (2026-02-19)
 
@@ -42,12 +57,6 @@ Incorporates oauth2-cli@0.8.5 updates
 
 - improved debugging output ([a0e6cea](https://github.com/battis/oauth2-cli/commit/a0e6ceaf12dadd9b2bf1753c602165f7194cbf24))
 
-## [0.7.4](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.3...qui-cli-plugin/0.7.4) (2026-02-18)
-
-## [0.7.3](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.2...qui-cli-plugin/0.7.3) (2026-02-18)
-
-Incorporate fixes from oauth2-cli@0.8.2
-
 ## [0.7.2](https://github.com/battis/oauth2-cli/compare/qui-cli-plugin/0.7.1...qui-cli-plugin/0.7.2) (2026-02-18)
 
 ### Features

package/README.md

@@ -19,16 +19,45 @@ npm install @qui-cli/core @oauth2-cli/qui-cli
 import { OAuth2 } from '@oauth2-cli/qui-cli';
 import { Core } from '@qui-cli/core';
 
-// initialize the `qui-cli` framework, ideally loading
+// configure a client name and a reason for authorizing access (recommended)
+OAuth2.configure({
+  name: 'Example',
+  reason: 'the README example'
+});
+
+// initialize the `qui-cli` framework, loading credentials from the environment
 await Core.run();
 
-console.log(
-  await OAuth2.requestJSON('https://api.github.com/repos/battis/oauth2-cli')
-);
+// request an endpoint, triggering interactive authorization if necessary
+console.log(await OAuth2.requestJSON('https://example.com/api/endpoint'));
 ```
 
 Without additional configuration, `OAuth2` will look for `ISSUER`, `CLIENT_ID`, `CLIENT_SECRET`, `REDIRECT_URI`, `AUTHORIZATION_ENDPOINT`, and `TOKEN_ENDPOINT` values in the environment and will attempt to configure the client using whichever subset of those values are present.
 
+#### `name` and `reason`
+
+It is strongly recommended that you provide a human-readable `name` for the client that will be used in user messages explaining _what_ is being accessed (e.g. the name of the API or service) and a human-readable `reason` for the user to provide this access (e.g. the name of your app or script). Messages are structured in the manner:
+
+> ...to authorize access to `name` for `reason`, do this...
+
+## Extending `OAuth2Plugin`
+
+The default export of the package includes an instance of `OAuth2` which is self-registered within the [qui-cli](https://github.com/battis/qui-cli#readme) framework. This is convenient and normal, to facilitate rapidly agglomerating CLI apps out a a collection of plugins.
+
+But if you are creating a custom extension of the plugin to pre-configure it to connect to a particular service, you may want to avoid that self-registration by importing from the `extendable` namespace:
+
+```ts
+import { OAuth2Plugin } from '@oauth2-cli/qui-cli/extendable';
+
+export class MyService extends OAuth2Plugin {
+  // ...
+}
+```
+
+A detailed example of this strategy is found in the examples (see below): [api-plugin](https://github.com/battis/oauth2-cli/tree/main/examples/qui-cli/06%20api-plugin#readme).
+
+## Examples
+
 Refer to [`oauth2-cli`](https://www.npmjs.com/package/oauth2-cli) for more information about configuring that tool in more nuanced ways.
 
 Refer to [`qui-cli`](https://github.com/battis/qui-cli#readme) for more information about using those tools to build command line apps.

package/dist/Client.d.ts

@@ -1,14 +1,24 @@
 import { JSONValue } from '@battis/typescript-tricks';
 import { Request } from 'express';
 import * as OAuth2CLI from 'oauth2-cli';
-import { Session } from 'oauth2-cli/dist/Session.js';
 import type * as OpenIDClient from 'openid-client';
 import * as requestish from 'requestish';
+/**
+ * Wrap {@link https://www.npmjs.com/package/openid-client openid-client} in a
+ * class instance specific to a particular OAuth/OpenID server credential-set,
+ * abstracting away most flows into {@link getToken}
+ *
+ * Emits {@link Client.TokenEvent} whenever a new access token is received
+ *
+ * Provides optional debug logging output using
+ * {@link https://www.npmjs.com/package/@qui-cli/env @qui-cli/env}
+ */
 export declare class Client<C extends OAuth2CLI.Credentials = OAuth2CLI.Credentials> extends OAuth2CLI.Client<C> {
     getConfiguration(): Promise<OpenIDClient.Configuration>;
     authorize(): Promise<OAuth2CLI.Token.Response>;
-    handleAuthorizationCodeRedirect(request: Request, session: Session): Promise<void>;
+    handleAuthorizationCodeRedirect(request: Request, session: OAuth2CLI.Localhost.Server): Promise<OAuth2CLI.Token.Response>;
     protected refreshTokenGrant(token: OAuth2CLI.Token.Response): Promise<OAuth2CLI.Token.Response | undefined>;
+    protected save(response: OAuth2CLI.Token.Response): Promise<OAuth2CLI.Token.Response>;
     request(url: requestish.URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
     requestJSON<J extends JSONValue = JSONValue>(url: requestish.URL.ish, method?: string, body?: OpenIDClient.FetchBody, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
 }

package/dist/Client.js

@@ -1,11 +1,21 @@
 import { Log } from '@qui-cli/log';
 import * as OAuth2CLI from 'oauth2-cli';
+/**
+ * Wrap {@link https://www.npmjs.com/package/openid-client openid-client} in a
+ * class instance specific to a particular OAuth/OpenID server credential-set,
+ * abstracting away most flows into {@link getToken}
+ *
+ * Emits {@link Client.TokenEvent} whenever a new access token is received
+ *
+ * Provides optional debug logging output using
+ * {@link https://www.npmjs.com/package/@qui-cli/env @qui-cli/env}
+ */
 export class Client extends OAuth2CLI.Client {
     async getConfiguration() {
         const creating = !this.config;
         const config = await super.getConfiguration();
         if (creating) {
-            Log.debug(`${this.clientName()} OAuth 2.0 configuration created`, {
+            Log.debug(`${this.name} OAuth 2.0 configuration created`, {
                 credentials: this.credentials,
                 config: {
                     serverMetadata: config.serverMetadata(),
@@ -16,46 +26,46 @@ export class Client extends OAuth2CLI.Client {
         return config;
     }
     async authorize() {
-        Log.debug(`Authorizing ${this.clientName()} new access token`);
+        Log.debug(`Authorizing ${this.name} new access token`);
         const response = await super.authorize();
-        Log.debug(`Authorized ${this.clientName()} new access token`, { response });
+        Log.debug(`Authorized ${this.name} new access token`, { response });
         return response;
     }
     async handleAuthorizationCodeRedirect(request, session) {
-        Log.debug(`Handling ${this.clientName()} Authorization Code flow redirect`, {
-            request: {
-                url: request.url,
-                method: request.method,
-                headers: request.headers,
-                body: request.body
-            },
-            session: {
-                code_verifier: session.code_verifier,
-                state: session.state,
-                inject: session.inject
-            }
+        Log.debug(`Handling ${this.name} authorization code redirect`, { request });
+        const response = await super.handleAuthorizationCodeRedirect(request, session);
+        Log.debug(`Received ${this.name} authorization code response`, {
+            response
         });
-        return super.handleAuthorizationCodeRedirect(request, session);
+        return response;
     }
     async refreshTokenGrant(token) {
-        Log.debug(`Refreshing expired ${this.clientName()} access token`, {
+        Log.debug(`Refreshing expired ${this.name} access token`, {
             token
         });
         const refreshed = await super.refreshTokenGrant(token);
-        Log.debug(`Received refreshed ${this.clientName()} access token`, {
+        Log.debug(`Received refreshed ${this.name} access token`, {
             token: refreshed
         });
         return refreshed;
     }
+    async save(response) {
+        Log.debug(`Persisting ${this.name} refresh token, if present and storage configured`, {
+            response
+        });
+        return await super.save(response);
+    }
     async request(url, method, body, headers, dPoPOptions) {
-        Log.debug({ request: { method, url, headers, body, dPoPOptions } });
+        Log.debug(`Sending request to ${this.name}`, {
+            request: { method, url, headers, body, dPoPOptions }
+        });
         const response = await super.request(url, method, body, headers, dPoPOptions);
-        Log.debug({ response });
+        Log.debug(`Received response from ${this.name}`, { response });
         return response;
     }
     async requestJSON(url, method, body, headers, dPoPOptions) {
         const json = await super.requestJSON(url, method, body, headers, dPoPOptions);
-        Log.debug({ json });
+        Log.debug(`Parsed JSON from ${this.name} response`, { json });
         return json;
     }
 }

package/dist/OAuth2.d.ts

@@ -1,8 +1,48 @@
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.configure}
+ */
 export declare const configure: (proposal?: import("./OAuth2Plugin.js").Configuration<import("oauth2-cli").Credentials>) => void;
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.options}
+ */
 export declare const options: () => import("@qui-cli/plugin").Options;
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.init}
+ */
 export declare const init: () => import("@qui-cli/plugin").Options;
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.client}
+ */
 export declare const client: () => import("./Client.js").Client<import("oauth2-cli").Credentials>;
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.request}
+ */
 export declare const request: (url: import("requestish/dist/URL.js").ish, method?: string | undefined, body?: import("openid-client").FetchBody, headers?: import("requestish/dist/Headers.js").ish | undefined, dPoPOptions?: import("openid-client").DPoPOptions | undefined) => Promise<Response>;
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.requestJSON}
+ */
 export declare const requestJSON: <T extends import("@battis/typescript-tricks").JSONValue>(url: import("requestish/dist/URL.js").ish, method?: string | undefined, body?: import("openid-client").FetchBody, headers?: import("requestish/dist/Headers.js").ish | undefined, dPoPOptions?: import("openid-client").DPoPOptions | undefined) => Promise<T>;
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.fetch}
+ */
 export declare const fetch: (input: import("requestish/dist/URL.js").ish, init?: RequestInit | undefined, dPoPOptions?: import("openid-client").DPoPOptions | undefined) => Promise<Response>;
+/**
+ * Conveneince method
+ *
+ * @see {@link OAuth2Plugin.fetchJSON}
+ */
 export declare const fetchJSON: <T extends import("@battis/typescript-tricks").JSONValue>(input: import("requestish/dist/URL.js").ish, init?: RequestInit | undefined, dPoPOptions?: import("openid-client").DPoPOptions | undefined) => Promise<T>;

package/dist/OAuth2.js

@@ -1,14 +1,55 @@
 import { register } from '@qui-cli/plugin';
 import { OAuth2Plugin } from './OAuth2Plugin.js';
+/** Auto-registered @oauth2-clu/qui-cli plugin */
 const plugin = new OAuth2Plugin();
 // @qui-cli/plugin convenience methods
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.configure}
+ */
 export const configure = plugin.configure.bind(plugin);
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.options}
+ */
 export const options = plugin.options.bind(plugin);
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.init}
+ */
 export const init = plugin.options.bind(plugin);
 // oauth2-cli convenience methods
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.client}
+ */
 export const client = () => plugin.client;
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.request}
+ */
 export const request = plugin.request.bind(plugin);
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.requestJSON}
+ */
 export const requestJSON = plugin.requestJSON.bind(plugin);
+/**
+ * Convenience method
+ *
+ * @see {@link OAuth2Plugin.fetch}
+ */
 export const fetch = plugin.fetch.bind(plugin);
+/**
+ * Conveneince method
+ *
+ * @see {@link OAuth2Plugin.fetchJSON}
+ */
 export const fetchJSON = plugin.fetchJSON.bind(plugin);
 await register(plugin);

package/dist/OAuth2Plugin.d.ts

@@ -1,25 +1,37 @@
-import { PathString, URLString } from '@battis/descriptive-types';
+import { URLString } from '@battis/descriptive-types';
 import { JSONValue } from '@battis/typescript-tricks';
 import * as Plugin from '@qui-cli/plugin';
 import * as OAuth2CLI from 'oauth2-cli';
-import * as requestish from 'requestish';
+import { URL } from 'requestish';
 import { Client } from './Client.js';
-type CredentialKey = 'issuer' | 'client_id' | 'client_secret' | 'redirect_uri' | 'authorization_endpoint' | 'token_endpoint' | 'scope' | 'base_url';
-type EnvironmentVars = Record<CredentialKey, string>;
-type SupportUrls = Record<CredentialKey, URLString>;
-type Hints = Record<CredentialKey, string>;
-type EnvVarSuppression = Record<CredentialKey, boolean>;
+/** Key for value to be read from the local environment */
+type EnvironmentKey = 'issuer' | 'client_id' | 'client_secret' | 'redirect_uri' | 'authorization_endpoint' | 'token_endpoint' | 'scope' | 'base_url';
+/** Names of environment variables */
+type EnvironmentVars = Record<EnvironmentKey, string>;
+/** Reference URLs for environment variables */
+type SupportUrls = Record<EnvironmentKey, URLString>;
+/** Hint values for environment variables */
+type Hints = Record<EnvironmentKey, string>;
+/** Environment variables to ignore and supporess in usage documentation */
+type EnvVarSuppression = Record<EnvironmentKey, boolean>;
+/** Custom usage information to present to user */
 type Usage = {
     heading: string;
     text?: string[];
 };
+/** Plugin configuration */
 export type Configuration<C extends OAuth2CLI.Credentials = OAuth2CLI.Credentials> = Plugin.Configuration & {
-    /** Human-readable name for client in messages. */
+    /** Human-readable name for client in messages (e.g. the name of the API) */
     name?: string;
+    /**
+     * Human-readable for authorizing access in messages (e.g. the name of the
+     * app)
+     */
+    reason?: string;
     /** OAuth 2.0/OpenID Connect credential set */
     credentials?: Partial<C>;
     /** Base URL for all non-absolute requests */
-    base_url?: requestish.URL.ish;
+    base_url?: URL.ish;
     /** Request components to inject into server requests */
     inject?: OAuth2CLI.Injection;
     /** Refresh token storage service */
@@ -34,8 +46,7 @@ export type Configuration<C extends OAuth2CLI.Credentials = OAuth2CLI.Credential
     env?: Partial<EnvironmentVars>;
     /** Should a particular credential value _not_ be loaded from the environment? */
     suppress?: Partial<EnvVarSuppression>;
-    /** Optional absolute path to EJS view templates directory */
-    views?: PathString;
+    localhost?: OAuth2CLI.Options['localhost'];
 };
 export declare class OAuth2Plugin<C extends OAuth2CLI.Credentials = OAuth2CLI.Credentials, L extends Client<C> = Client<C>> {
     readonly name: string;
@@ -43,30 +54,101 @@ export declare class OAuth2Plugin<C extends OAuth2CLI.Credentials = OAuth2CLI.Cr
     private static names;
     private static registeredPorts;
     private overrideName?;
+    private reason?;
     /**
      * @param name Human-readable name for client in messages. Must also be a
      *   unique qui-cli plugin name.
      */
     constructor(name?: string);
+    /** Configured client credentials */
     private credentials?;
+    /** Configured client base_url */
     private base_url?;
+    /** Configured usage information */
     private man;
+    /** Configured reference URLs for credentials */
     private url?;
+    /** Configured hint values for credentials */
     private hint;
+    /** Configured environment variable names for credentials */
     private env;
+    /** Configured credentials to suppress in usage and init */
     private suppress?;
+    /** Configured request components for client to inject */
     private inject?;
-    private views?;
+    /** Configured {@link OAuth2CLI.Localhost.Options} to pass to client */
+    private localhost?;
+    /** Configured client refresh token storage strategy */
     private storage?;
     private _client?;
+    /**
+     * Configured oauth2-cli client
+     *
+     * Do _not_ access until intitialization is complete -- the client will be
+     * configured upon first access based on available configuration known at that
+     * time
+     */
+    get client(): L;
+    /**
+     * Configure plugin for use
+     *
+     * May be called repeatedly, overlaying different options as they become
+     * available
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     *
+     * @see {@link Configuration}
+     */
     configure(proposal?: Configuration<C>): void;
+    /**
+     * Provide usage options to
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} for display to user
+     * on command line
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     */
     options(): Plugin.Options;
+    /**
+     * Intialize plugin configuration from command line options and environment
+     *
+     * Invoked automatically by
+     * {@link https://github.com/battis/qui-cli#readme qui-cli} during
+     * initialization
+     */
     init(_: Plugin.ExpectedArguments<typeof this.options>): Promise<void>;
-    protected instantiateClient(options: OAuth2CLI.ClientOptions<C>): L;
-    get client(): L;
+    /**
+     * Instantiate the `oauth2-cli` client
+     *
+     * Available hook for custom configurations in plugin development
+     */
+    protected instantiateClient(options: OAuth2CLI.Options<C>): L;
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.request}
+     */
     request(...args: Parameters<OAuth2CLI.Client<C>['request']>): Promise<Response>;
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.requestJSON}
+     */
     requestJSON<T extends JSONValue>(...args: Parameters<OAuth2CLI.Client<C>['requestJSON']>): Promise<T>;
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.fetch}
+     */
     fetch(...args: Parameters<OAuth2CLI.Client<C>['fetch']>): Promise<Response>;
+    /**
+     * Convenience method
+     *
+     * @see {@link OAuth2CLI.Client.fetchJSON}
+     */
     fetchJSON<T extends JSONValue>(...args: Parameters<OAuth2CLI.Client<C>['fetchJSON']>): Promise<T>;
 }
 export {};