oauth2-cli 1.2.8 → 2.0.1

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.
 
+## [2.0.1](https://github.com/battis/oauth2-cli/compare/oauth2-cli/2.0.0...oauth2-cli/2.0.1) (2026-03-27)
+
+
+### Bug Fixes
+
+* more detail on bad response ([8a38bd5](https://github.com/battis/oauth2-cli/commit/8a38bd5b86802e0640592117a21d69323a265d8f))
+
+## [2.0.0](https://github.com/battis/oauth2-cli/compare/oauth2-cli/1.2.8...oauth2-cli/2.0.0) (2026-03-22)
+
+
+### ⚠ BREAKING CHANGES
+
+* detect and automate traversing paginated collections
+
+### Features
+
+* detect and automate traversing paginated collections ([28d6c6a](https://github.com/battis/oauth2-cli/commit/28d6c6ad90deb01059804d11ee692ec413a03345))
+
 ## [1.2.8](https://github.com/battis/oauth2-cli/compare/oauth2-cli/1.2.7...oauth2-cli/1.2.8) (2026-03-17)
 
 ### Bug Fixes

package/README.md

@@ -33,7 +33,7 @@ const client = new Client({
   storage: new FileStorage('/path/to/token/file.json');
 });
 console.log(
-  client.fetchJSON<ExpectedResponse>('https://example.com/path/to/api/endpoint')
+  client.fetch<ExpectedResponse>('https://example.com/path/to/api/endpoint')
 );
 ```
 
@@ -69,7 +69,7 @@ If you would prefer an `https` connection to localhost, you have to roll your ow
 
 ### Request an endpoint
 
-#### `request()`
+#### `requestRaw()`
 
 As noted above, `oauth2-cli` is built on top of [openid-client](https://www.npmjs.com/package/openid-client). The `request()` method is a pass-through to the `openid-client` [fetchProtectedResource()](https://github.com/panva/openid-client/blob/b77d87c1e2f5fef6fab501de615fb83a74a0251f/docs/functions/fetchProtectedResource.md) function, with the configuration and accessToken managed by the Client.
 
@@ -77,7 +77,7 @@ As noted above, `oauth2-cli` is built on top of [openid-client](https://www.npmj
 class Client {
   // ...
 
-  public async request(
+  public async requestRaw(
     url: requestish.URL.ish,
     method = 'GET',
     body?: requestish.Body.ish,
@@ -95,7 +95,7 @@ class Client {
 
 If you would prefer to make requests to relative paths, rather than absolute paths, either configure a `base_url` or include an `issuer` in the `credentials` when instantiating the client. A `base_url` will preempt an `issuer`, if both are defined (handy for when the `issuer` is a different subdomain than the API endpoints).
 
-### `requestJSON<J>()`
+### `request<T>()`
 
 Given that many APIs return JSON-formatted responses, it is convenient to just get that JSON (optionally pre-typed based on what you expect to receive) rather than having to process the response yourself.
 
@@ -103,9 +103,7 @@ Given that many APIs return JSON-formatted responses, it is convenient to just g
 class Client {
   // ...
 
-  public async requestJSON<
-    J extends OpenIDClient.JsonValue = OpenIDClient.JsonValue
-  >(
+  public async request<T extends JSONValue = JSONValue>(
     url: requestish.URL.ish,
     method = 'GET',
     body?: requestish.Body.ish,
@@ -117,9 +115,9 @@ class Client {
 }
 ```
 
-### `fetch()` and `fetchJSON<J>()`
+### `fetchRaw()` and `fetch<T>()`
 
-Aliases for `request()` and `requestJSON<J>()` that use [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-style arguments.
+Aliases for `requestRaw()` and `request<T>()` that use [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-style arguments.
 
 ## Examples
 

package/dist/Client.d.ts

@@ -7,6 +7,7 @@ import { Credentials } from './Credentials.js';
 import { Injection } from './Injection.js';
 import * as Localhost from './Localhost/index.js';
 import * as Options from './Options.js';
+import { PaginatedCollection } from './PaginatedCollection.js';
 import * as Token from './Token/index.js';
 export type PreparedRequest = Parameters<(typeof OpenIDClient)['fetchProtectedResource']>;
 /**
@@ -117,7 +118,7 @@ export declare class Client<C extends Credentials = Credentials> extends EventEm
      * @param body Optional
      * @param dPoPOptions Optional, see {@link OpenIDClient.DPoPOptions}
      */
-    request(url: requestish.URL.ish, method?: string, body?: requestish.Body.ish, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
+    requestRaw(url: requestish.URL.ish, method?: string, body?: requestish.Body.ish, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
     /**
      * Available hook to manipulate a fully-prepared request before sending to the
      * server
@@ -128,13 +129,27 @@ export declare class Client<C extends Credentials = Credentials> extends EventEm
      * processing it
      */
     protected prepareResponse(response: Response): Promise<Response>;
-    /** Parse a fetch response as JSON, typing it as J */
-    private toJSON;
     /**
-     * Returns the result of {@link request} as a parsed JSON object, optionally
-     * typed as `J`
+     * Available hook to check for a paginated response and return an interable
+     * PaginatedCollection
      */
-    requestJSON<J extends JSONValue = JSONValue>(url: requestish.URL.ish, method?: string, body?: requestish.Body.ish, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
+    protected checkForPagination<T extends JSONValue = JSONValue>(_response: Response, _data: JSONValue): PaginatedCollection<T> | undefined;
+    /**
+     * Process a raw response int JSON, typing it as `T` or as a
+     * `PaginatedCollection<T>`
+     *
+     * @param response Raw response
+     */
+    processResponse<T extends JSONValue = JSONValue>(response: Response, paginationCheck: false): Promise<T>;
+    processResponse<T extends JSONValue = JSONValue>(response: Response, paginationCheck?: true): Promise<T | PaginatedCollection<T>>;
+    /**
+     * Returns the result of {@link requestRaw} as a parsed JSON object, optionally
+     * typed as `T`
+     *
+     * @param pagination Optional function to test conversion of response into a
+     *   `PaginatedCollection<T>`
+     */
+    request<T extends JSONValue = JSONValue>(url: requestish.URL.ish, method?: string, body?: requestish.Body.ish, headers?: requestish.Headers.ish, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<T | PaginatedCollection<T>>;
     /**
      * Request a protected resource using the client's access token.
      *
@@ -145,12 +160,12 @@ export declare class Client<C extends Credentials = Credentials> extends EventEm
      *   paths relative to the `issuer` URL as well as absolute URLs
      * @param init Optional
      * @param dPoPOptions Optional, see {@link OpenIDClient.DPoPOptions}
-     * @see {@link request} for which this is an alias for {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API}-style requests
+     * @see {@link requestRaw} for which this is an alias for {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API}-style requests
      */
-    fetch(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
+    fetchRaw(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<Response>;
     /**
      * Returns the result of {@link fetch} as a parsed JSON object, optionally
-     * typed as `J`
+     * typed as `T`
      */
-    fetchJSON<J extends JSONValue = JSONValue>(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<J>;
+    fetch<T extends JSONValue = JSONValue>(input: requestish.URL.ish, init?: RequestInit, dPoPOptions?: OpenIDClient.DPoPOptions): Promise<T | PaginatedCollection<T>>;
 }

package/dist/Client.js

@@ -253,7 +253,7 @@ export class Client extends EventEmitter {
      * @param body Optional
      * @param dPoPOptions Optional, see {@link OpenIDClient.DPoPOptions}
      */
-    async request(url, method = 'GET', body, headers = {}, dPoPOptions) {
+    async requestRaw(url, method = 'GET', body, headers = {}, dPoPOptions) {
         url = new URL(url, this.base_url || this.credentials.issuer);
         url = requestish.URL.from(requestish.URLSearchParams.appendTo(url, requestish.URLSearchParams.merge(this.inject?.search, url.searchParams)));
         const request = async () => await OpenIDClient.fetchProtectedResource(...(await this.prepareRequest(await this.getConfiguration(), (await this.getToken()).access_token, url, method, await requestish.Body.from(body), requestish.Headers.merge(this.inject?.headers, headers), dPoPOptions)));
@@ -284,12 +284,24 @@ export class Client extends EventEmitter {
     async prepareResponse(response) {
         return response;
     }
-    /** Parse a fetch response as JSON, typing it as J */
-    async toJSON(response) {
+    /**
+     * Available hook to check for a paginated response and return an interable
+     * PaginatedCollection
+     */
+    checkForPagination(_response, _data) {
+        return undefined;
+    }
+    async processResponse(response, paginationCheck = true) {
         if (response.ok) {
             const body = await response.text();
             try {
-                return JSON.parse(body);
+                const data = JSON.parse(body);
+                let paginatedCollection;
+                if (paginationCheck &&
+                    (paginatedCollection = this.checkForPagination(response, data))) {
+                    return paginatedCollection;
+                }
+                return data;
             }
             catch (error) {
                 throw new Error(`${this.name} response could not be parsed as JSON`, {
@@ -312,11 +324,30 @@ export class Client extends EventEmitter {
         }
     }
     /**
-     * Returns the result of {@link request} as a parsed JSON object, optionally
-     * typed as `J`
+     * Returns the result of {@link requestRaw} as a parsed JSON object, optionally
+     * typed as `T`
+     *
+     * @param pagination Optional function to test conversion of response into a
+     *   `PaginatedCollection<T>`
      */
-    async requestJSON(url, method = 'GET', body, headers = {}, dPoPOptions) {
-        return await this.toJSON(await this.request(url, method, body, headers, dPoPOptions));
+    async request(url, method = 'GET', body, headers = {}, dPoPOptions) {
+        try {
+            const response = await this.requestRaw(url, method, body, headers, dPoPOptions);
+            return await this.processResponse(response);
+        }
+        catch (error) {
+            throw new Error(`Bad response from ${this.name}`, {
+                cause: {
+                    request: {
+                        method,
+                        url: requestish.URL.toString(url),
+                        headers: Object.fromEntries(requestish.Headers.from(headers).entries()),
+                        body
+                    },
+                    error
+                }
+            });
+        }
     }
     /**
      * Request a protected resource using the client's access token.
@@ -328,16 +359,16 @@ export class Client extends EventEmitter {
      *   paths relative to the `issuer` URL as well as absolute URLs
      * @param init Optional
      * @param dPoPOptions Optional, see {@link OpenIDClient.DPoPOptions}
-     * @see {@link request} for which this is an alias for {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API}-style requests
+     * @see {@link requestRaw} for which this is an alias for {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API Fetch API}-style requests
      */
-    async fetch(input, init, dPoPOptions) {
-        return await this.request(input, init?.method, await requestish.Body.from(init?.body), requestish.Headers.from(init?.headers), dPoPOptions);
+    async fetchRaw(input, init, dPoPOptions) {
+        return await this.requestRaw(input, init?.method, await requestish.Body.from(init?.body), requestish.Headers.from(init?.headers), dPoPOptions);
     }
     /**
      * Returns the result of {@link fetch} as a parsed JSON object, optionally
-     * typed as `J`
+     * typed as `T`
      */
-    async fetchJSON(input, init, dPoPOptions) {
-        return await this.toJSON(await this.fetch(input, init, dPoPOptions));
+    async fetch(input, init, dPoPOptions) {
+        return await this.request(input, init?.method, await requestish.Body.from(init?.body), requestish.Headers.from(init?.headers), dPoPOptions);
     }
 }

package/dist/PaginatedCollection.d.ts

@@ -0,0 +1,18 @@
+import { JSONValue } from '@battis/typescript-tricks';
+import { Client } from './Client.js';
+type Options<T extends JSONValue = JSONValue> = {
+    page: T[];
+    response: Response;
+    client: Client;
+};
+export declare abstract class PaginatedCollection<T extends JSONValue> implements AsyncIterable<T>, AsyncIterableIterator<T> {
+    protected currentResponse: Response;
+    protected currentElt: number;
+    protected currentPage: T[];
+    protected client: Client;
+    constructor({ page, response, client }: Options<T>);
+    [Symbol.asyncIterator](): this;
+    protected abstract nextPage(): Promise<T[] | undefined>;
+    next(): Promise<IteratorResult<T>>;
+}
+export {};

package/dist/PaginatedCollection.js

@@ -0,0 +1,34 @@
+export class PaginatedCollection {
+    currentResponse;
+    currentElt = 0;
+    currentPage;
+    client;
+    constructor({ page, response, client }) {
+        this.currentResponse = response;
+        this.currentPage = page;
+        this.client = client;
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    async next() {
+        return new Promise((resolve) => {
+            const value = this.currentPage[this.currentElt++];
+            if (this.currentElt === this.currentPage.length) {
+                this.nextPage().then((page) => {
+                    if (page) {
+                        this.currentPage = page;
+                        this.currentElt = 0;
+                        resolve({ value, done: this.currentPage.length === 0 });
+                    }
+                    else {
+                        resolve({ value, done: true });
+                    }
+                });
+            }
+            else {
+                resolve({ value, done: false });
+            }
+        });
+    }
+}

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './Credentials.js';
 export * from './Injection.js';
 export * as Localhost from './Localhost/index.js';
 export { Client as Options } from './Options.js';
+export * from './PaginatedCollection.js';
 export * as Token from './Token/index.js';

package/dist/index.js

@@ -2,4 +2,5 @@ export * from './Client.js';
 export * from './Credentials.js';
 export * from './Injection.js';
 export * as Localhost from './Localhost/index.js';
+export * from './PaginatedCollection.js';
 export * as Token from './Token/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oauth2-cli",
-  "version": "1.2.8",
+  "version": "2.0.1",
   "description": "Acquire API access tokens via OAuth 2.0 / OpenID Connect within CLI tools",
   "homepage": "https://github.com/battis/oauth2-cli/tree/main/packages/oauth2-cli#readme",
   "repository": {
@@ -23,8 +23,8 @@
     "open": "^11.0.0",
     "openid-client": "^6.8.2",
     "ora": "^9.3.0",
-    "requestish": "0.1.12",
-    "gcrtl": "0.1.12"
+    "gcrtl": "0.1.12",
+    "requestish": "0.1.12"
   },
   "devDependencies": {
     "@battis/typescript-tricks": "^0.8.1",