oauth2-cli 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 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.4.0](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.3.0...oauth2-cli/0.4.0) (2026-01-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* remove deprecated TokenManager
+
+### Features
+
+* provide fetch() and fetchJSON() methods to translate to openid-client requests ([3fe454f](https://github.com/battis/oauth2-cli/commit/3fe454f28497d704041ea4e599a4ad5b2b08b469))
+
+
+### Bug Fixes
+
+* remove deprecated TokenManager ([2dde67e](https://github.com/battis/oauth2-cli/commit/2dde67edd70b151bd1bab6de3845839a06957e65))
+
+## [0.3.0](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.2.3...oauth2-cli/0.3.0) (2025-12-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* resolve 1Password secret references successfully
+
+### Bug Fixes
+
+* resolve 1Password secret references successfully ([c4446e1](https://github.com/battis/oauth2-cli/commit/c4446e197a66271dac3ea8d58ff44725cc6be1db))
+
 ## [0.2.3](https://github.com/battis/oauth2-cli/compare/oauth2-cli/0.2.2...oauth2-cli/0.2.3) (2025-12-23)
 
 

package/dist/Client.d.ts

@@ -1,24 +1,57 @@
 import * as Configuration from '@battis/oauth2-configure';
+import { JSONValue } from '@battis/typescript-tricks';
 import * as OpenIDClient from 'openid-client';
 import { Token } from './Token.js';
 import { TokenStorage } from './TokenStorage.js';
-export type Options = Configuration.Options & {
+export type Credentials = Configuration.Options & {
     scope?: string;
     headers?: Record<string, string>;
     parameters?: Record<string, string>;
     store?: TokenStorage | string;
 };
+/** Wrap an OpenID configuration in an object-oriented API client. */
 export declare class Client {
-    private options;
+    private credentials;
     private tokenMutex;
     private config?;
     private token?;
     private store?;
-    constructor(options: Options);
+    constructor(credentials: Credentials);
+    /** Acquire a valid, unexpired API access token. */
     getToken(): Promise<Token | undefined>;
+    /** Refresh Token Grant */
     private refreshToken;
+    /** Acquire a valid OpenID configuration. */
     private getConfiguration;
+    /** Authorization Code Grant */
     private authorize;
-    request(url: URL | string, method?: string, body?: OpenIDClient.FetchBody, headers?: Record<string, string>, options?: OpenIDClient.DPoPOptions): Promise<Response>;
-    requestJSON(url: URL | string, method?: string, body?: OpenIDClient.FetchBody, headers?: Record<string, string>, options?: OpenIDClient.DPoPOptions): Promise<unknown>;
+    /**
+     * Make an authorized request to the API, acquiring an unexpired acess token
+     * if necessary.
+     */
+    request(url: URL | string, method?: string, body?: OpenIDClient.FetchBody, headers?: Headers, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
+    /**
+     * Make an authorized request to the API, acquiring an unexpired acess token
+     * if necessary.
+     *
+     * This converts the Fetch API request into an OpenID request. To directly
+     * make this request, use {@link request()}
+     */
+    fetch(endpoint: string | URL | Request, init?: RequestInit): Promise<Response>;
+    /**
+     * Make an authorized request to the API, acquiring an unexpired acess token
+     * if necessary and parse the JSON respomse.
+     *
+     * @param validator Optional validator function test that the JSON response is
+     *   the expected type.
+     */
+    requestJSON<T extends JSONValue = JSONValue>(url: URL | string, method?: string, body?: OpenIDClient.FetchBody, headers?: Headers, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<T>;
+    /**
+     * Make an authorized request to the API, acquiring an unexpired acess token
+     * if necessary and parse the JSON respomse.
+     *
+     * This converts the Fetch API request into an OpenID request. To directly
+     * make this request, use {@link requestJSON()}
+     */
+    fetchJSON<T extends JSONValue = JSONValue>(endpoint: string | URL | Request, init?: RequestInit): Promise<T>;
 }

package/dist/Client.js

@@ -4,23 +4,25 @@ import * as OpenIDClient from 'openid-client';
 import { FileStorage } from './FileStorage.js';
 import * as Localhost from './Localhost.js';
 import { Token } from './Token.js';
+/** Wrap an OpenID configuration in an object-oriented API client. */
 export class Client {
-    options;
+    credentials;
     tokenMutex = new Mutex();
     config;
     token;
     store;
-    constructor(options) {
-        this.options = options;
-        if (this.options.store) {
-            if (typeof this.options.store === 'string') {
-                this.store = new FileStorage(this.options.store);
+    constructor(credentials) {
+        this.credentials = credentials;
+        if (this.credentials.store) {
+            if (typeof this.credentials.store === 'string') {
+                this.store = new FileStorage(this.credentials.store);
             }
             else {
-                this.store = this.options.store;
+                this.store = this.credentials.store;
             }
         }
     }
+    /** Acquire a valid, unexpired API access token. */
     async getToken() {
         return await this.tokenMutex.runExclusive((async () => {
             if (!this.token) {
@@ -35,63 +37,104 @@ export class Client {
             return this.token;
         }).bind(this));
     }
+    /** Refresh Token Grant */
     async refreshToken(token) {
         if (token.refresh_token) {
-            const { headers, parameters } = this.options;
+            const { headers, parameters } = this.credentials;
             let freshTokens;
-            if ((freshTokens = Token.fromResponse(await OpenIDClient.refreshTokenGrant(await Configuration.acquire(this.options), token.refresh_token, parameters, 
+            if ((freshTokens = Token.fromResponse(await OpenIDClient.refreshTokenGrant(await Configuration.acquire(this.credentials), token.refresh_token, parameters, 
             // @ts-expect-error 2322 undocumented arg pass-through to oauth4webapi
             { headers }), token.refresh_token))) {
-                return this.store?.save(freshTokens) || freshTokens;
+                if (this.store) {
+                    await this.store.save(freshTokens);
+                }
+                return freshTokens;
             }
         }
         return this.authorize();
     }
+    /** Acquire a valid OpenID configuration. */
     async getConfiguration() {
         if (!this.config) {
-            this.config = await Configuration.acquire(this.options);
+            this.config = await Configuration.acquire(this.credentials);
         }
         return this.config;
     }
+    /** Authorization Code Grant */
     async authorize() {
-        const { scope, redirect_uri, parameters: additionalParameters } = this.options;
-        return new Promise(async (resolve, reject) => {
+        const { scope, redirect_uri, parameters: additionalParameters } = this.credentials;
+        return new Promise((resolve, reject) => {
             const code_verifier = OpenIDClient.randomPKCECodeVerifier();
-            const code_challenge = await OpenIDClient.calculatePKCECodeChallenge(code_verifier);
-            let state = undefined;
-            const parameters = {
-                ...additionalParameters,
-                redirect_uri,
-                code_challenge,
-                code_challenge_method: 'S256' // TODO make code challenge method configurable?
-            };
-            if (scope) {
-                parameters.scope = scope;
-            }
-            if (!(await this.getConfiguration()).serverMetadata().supportsPKCE()) {
-                state = OpenIDClient.randomState();
-                parameters.state = state;
-            }
-            await Localhost.redirectServer({
-                ...this.options,
-                authorization_url: OpenIDClient.buildAuthorizationUrl(await this.getConfiguration(), parameters).href,
-                code_verifier,
-                state,
-                resolve: (async (response) => {
-                    this.token = Token.fromResponse(response);
-                    if (this.token && this.store) {
-                        await this.store.save(this.token);
-                    }
-                    resolve(this.token);
-                }).bind(this),
-                reject
+            OpenIDClient.calculatePKCECodeChallenge(code_verifier).then(async (code_challenge) => {
+                let state = undefined;
+                const parameters = {
+                    ...additionalParameters,
+                    redirect_uri,
+                    code_challenge,
+                    code_challenge_method: 'S256' // TODO make code challenge method configurable?
+                };
+                if (scope) {
+                    parameters.scope = scope;
+                }
+                if (!(await this.getConfiguration()).serverMetadata().supportsPKCE()) {
+                    state = OpenIDClient.randomState();
+                    parameters.state = state;
+                }
+                await Localhost.redirectServer({
+                    ...this.credentials,
+                    authorization_url: OpenIDClient.buildAuthorizationUrl(await this.getConfiguration(), parameters).href,
+                    code_verifier,
+                    state,
+                    resolve: (async (response) => {
+                        this.token = Token.fromResponse(response);
+                        if (this.token && this.store) {
+                            await this.store.save(this.token);
+                        }
+                        resolve(this.token);
+                    }).bind(this),
+                    reject
+                });
             });
         });
     }
-    async request(url, method = 'GET', body, headers, options) {
-        return await OpenIDClient.fetchProtectedResource(await this.getConfiguration(), (await this.getToken()).access_token, new URL(url), method, body, new Headers({ ...this.options.headers, ...headers }), options);
+    /**
+     * Make an authorized request to the API, acquiring an unexpired acess token
+     * if necessary.
+     */
+    async request(url, method = 'GET', body, headers, dPoPOptions) {
+        for (const header in this.credentials.headers) {
+            headers?.append(header, this.credentials.headers[header]);
+        }
+        return await OpenIDClient.fetchProtectedResource(await this.getConfiguration(), (await this.getToken()).access_token, new URL(url), method, body, headers, dPoPOptions);
+    }
+    /**
+     * Make an authorized request to the API, acquiring an unexpired acess token
+     * if necessary.
+     *
+     * This converts the Fetch API request into an OpenID request. To directly
+     * make this request, use {@link request()}
+     */
+    async fetch(endpoint, init) {
+        return this.request(endpoint.toString(), init?.method, init?.body?.toString(), new Headers(init?.headers));
+    }
+    /**
+     * Make an authorized request to the API, acquiring an unexpired acess token
+     * if necessary and parse the JSON respomse.
+     *
+     * @param validator Optional validator function test that the JSON response is
+     *   the expected type.
+     */
+    async requestJSON(url, method = 'GET', body, headers, dPoPOptions) {
+        return (await (await this.request(url, method, body, headers, dPoPOptions)).json());
     }
-    async requestJSON(url, method = 'GET', body, headers, options) {
-        return await (await this.request(url, method, body, headers, options)).json();
+    /**
+     * Make an authorized request to the API, acquiring an unexpired acess token
+     * if necessary and parse the JSON respomse.
+     *
+     * This converts the Fetch API request into an OpenID request. To directly
+     * make this request, use {@link requestJSON()}
+     */
+    async fetchJSON(endpoint, init) {
+        return (await (await this.fetch(endpoint, init)).json());
     }
 }

package/dist/FileStorage.d.ts

@@ -5,5 +5,5 @@ export declare class FileStorage implements TokenStorage {
     private readonly filePath;
     constructor(filePath: string);
     load(): Promise<Token | undefined>;
-    save(tokens: Token): Promise<Token>;
+    save(tokens: Token): Promise<void>;
 }

package/dist/FileStorage.js

@@ -24,6 +24,5 @@ export class FileStorage {
             }
             fs.writeFileSync(this.filePath, JSON.stringify(tokens));
         }).bind(this));
-        return tokens;
     }
 }

package/dist/TokenStorage.d.ts

@@ -1,5 +1,5 @@
 import { Token } from './Token.js';
 export interface TokenStorage {
     load(): Promise<Token | undefined>;
-    save(tokens: Token): Promise<Token>;
+    save(tokens: Token): Promise<void>;
 }

package/dist/index.d.ts

@@ -1,8 +1,4 @@
-import { Client } from './Client.js';
-export { Client, Options as Credentials } from './Client.js';
-export { FileStorage } from './FileStorage.js';
-export { Token } from './Token.js';
-export { TokenStorage } from './TokenStorage.js';
-export { 
-/** @deprecated use Client */
-Client as TokenManager };
+export * from './Client.js';
+export * from './FileStorage.js';
+export * from './Token.js';
+export * from './TokenStorage.js';

package/dist/index.js

@@ -1,7 +1,4 @@
-import { Client } from './Client.js';
-export { Client } from './Client.js';
-export { FileStorage } from './FileStorage.js';
-export { Token } from './Token.js';
-export { 
-/** @deprecated use Client */
-Client as TokenManager };
+export * from './Client.js';
+export * from './FileStorage.js';
+export * from './Token.js';
+export * from './TokenStorage.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth2-cli",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "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,9 +20,10 @@
     "express": "^5.2.1",
     "open": "^11.0.0",
     "openid-client": "^6.8.1",
-    "@battis/oauth2-configure": "0.1.3"
+    "@battis/oauth2-configure": "0.1.4"
   },
   "devDependencies": {
+    "@battis/typescript-tricks": "^0.7.6",
     "@tsconfig/node20": "^20.1.8",
     "@types/ejs": "^3.1.5",
     "@types/express": "^5.0.6",