@okta/auth-foundation 0.6.0 → 0.9.0

package/dist/types/Token.d.ts

@@ -1,5 +1,6 @@
 import { type GrantType, type Expires, type TokenType, type RequestAuthorizer, type RequestAuthorizerInit, type Seconds, type JSONSerializable, type AcrValues, type TimeInterval, type JsonPrimitive, type JsonRecord } from './types/index.ts';
 import type { OAuth2Client } from './oauth2/client.ts';
+import type { OAuth2ClientOptions } from './oauth2/configuration.ts';
 import { JWT } from './jwt/index.ts';
 import { OAuth2Request } from './http/index.ts';
 /**
@@ -23,6 +24,7 @@ export type TokenResponse = {
 /**
  * Required and optional values to construct a {@link Token} instance
  * @group Types
+ * @useDeclaredType
  */
 export type TokenInit = Omit<TokenResponse, 'idToken'> & {
     idToken?: string | JWT;
@@ -36,11 +38,9 @@ export type TokenPrimitiveInit = TokenResponse;
  * Internal representation of a OAuth2/OIDC Token.
  * Contains `accessToken`, conditionally contains `idToken` and `refreshToken`
  *
- * @group Token
- *
  * @remarks
  * Most operations can be done by {@link Credential} methods. It's recommended
- * to use those instead before reaching for a {@link Token.Token | Token} method
+ * to use those instead before reaching for a {@link Token} method
  *
  * @see
  * - Okta Documentation: {@link https://developer.okta.com/docs/reference/api/oidc/#response-properties-4 | OIDC }
@@ -95,6 +95,9 @@ export declare class Token implements JSONSerializable, Expires, RequestAuthoriz
     protected static create<T extends Token>(this: new (init: TokenInit) => T, init: TokenInit): T;
     static serializer(t: object): string;
     static isEqual(lhs: Token, rhs: Token): boolean;
+    /**
+     * Performs a token refresh using the provided `refreshToken`
+     */
     static from(refreshToken: string, client: OAuth2Client): Promise<Token>;
     /**
      * When the Token will expire, represented as a `Date`
@@ -107,19 +110,19 @@ export declare class Token implements JSONSerializable, Expires, RequestAuthoriz
      */
     get isExpired(): boolean;
     /**
-     * Returns `true` if the {@link Token.Token | Token} is _not_ expired
+     * Returns `true` if the {@link Token:class | Token} is _not_ expired
      *
      * @see {@link Token.isExpired}
      */
     get isValid(): boolean;
     /**
-     * Returns `true` if the {@link Token.Token | Token} will expire after a duration (seconds)
+     * Returns `true` if the {@link Token:class | Token} will expire after a duration (seconds)
      *
      * @see {@link Token.willBeValidIn}
      */
     willBeExpiredIn(duration: Seconds): boolean;
     /**
-     * Returns `true` if the {@link Token.Token | Token} will _not_ expire after a duration (seconds)
+     * Returns `true` if the {@link Token:class | Token} will _not_ expire after a duration (seconds)
      *
      * @see {@link Token.willBeExpiredIn}
      */
@@ -129,15 +132,15 @@ export declare class Token implements JSONSerializable, Expires, RequestAuthoriz
      */
     get scopes(): string[];
     /**
-     * Converts a {@link Token.Token | Token} instance to an serializable object literal representation
+     * Converts a {@link Token:class | Token} instance to an serializable object literal representation
      */
     toJSON(): JsonRecord;
     /**
-     * Used to merge separate {@link Token.Token | Token} instances together. Useful when handling token refresh as
+     * Used to merge separate {@link Token:class | Token} instances together. Useful when handling token refresh as
      * not every value is returned in a refresh request compared to the initial token request
      *
      * @param token the "old" token instance to be merged into the "new" token
-     * @returns new {@link Token.Token | Token} instance
+     * @returns new {@link Token:class | Token} instance
      */
     merge(token: Token): Token;
     serialize(): string;
@@ -163,6 +166,7 @@ export declare namespace Token {
         dpopPairId?: string;
         acrValues?: AcrValues;
         maxAge?: TimeInterval;
+        clientSettings?: OAuth2ClientOptions;
     };
     /**
      * Utility function for extracting {@link Token.Context} from an union-type object like {@link Token.Metadata:TYPE | Token.Metadata}
@@ -171,8 +175,8 @@ export declare namespace Token {
         [key: string]: unknown;
     }): Token.Context;
     /**
-     * Non-sensitive metadata values associated with a {@link Token.Token | Token}. Used to store {@link Token.Context} and additional
-     * metadata for a given {@link Token.Token | Token}
+     * Non-sensitive metadata associated with a {@link Token:class | Token}. Used to store {@link Token.Context} and additional
+     * metadata for a given {@link Token:class | Token}
      * {@label TYPE}
      */
     type Metadata = Context & {
@@ -180,6 +184,9 @@ export declare namespace Token {
         tags: string[];
         claims?: JsonRecord;
     };
+    /**
+     * Returns {@link Metadata:type | Token.Metadata} for a given {@link Token:class | Token}
+     */
     function Metadata(token: Token, tags?: string[]): Metadata;
     /** @internal */
     interface TokenRequestParams extends OAuth2Request.RequestParams {
@@ -210,6 +217,10 @@ export declare namespace Token {
     }
     /**
      * Possible values provided to {@link OAuth2.OAuth2Client.revoke | OAuth2Client.revoke} to determine which tokens to revoke
+     * * `'ALL'` - revokes both the `access_token` and `refresh_token`.
+     * * `'ACCESS'` - revokes **only** the `access_token`.
+     * * `'REFRESH'` - revokes **only** the `refresh_token`.
+     * @inline
      */
     type RevokeType = 'ALL' | 'ACCESS' | 'REFRESH';
     /** @internal */
@@ -224,6 +235,7 @@ export declare namespace Token {
     }
     /**
      * Possible values provided to {@link OAuth2.OAuth2Client.introspect | OAuth2Client.introspect} to determine which token to introspect
+     * @inline
      */
     type Kind = 'access_token' | 'refresh_token' | 'id_token';
     /** @internal */

package/dist/types/TokenOrchestrator.d.ts

@@ -1,19 +1,50 @@
-import type { RequestAuthorizer, RequestAuthorizerInit, JsonRecord, AcrValues } from './types/index.ts';
-import { Token } from './Token.ts';
-import { EventEmitter } from './utils/EventEmitter.ts';
 /**
  * @module TokenOrchestrator
  */
+import type { RequestAuthorizerInit, JsonRecord, AcrValues } from './types/index.ts';
+import { Token } from './Token.ts';
+import { EventEmitter } from './utils/EventEmitter.ts';
 /**
- * @abstract
+ * An abstraction layer between {@link Token} consumers and an application's internal management of {@link Token}s.
+ * Implementations of {@link TokenOrchestrator} handle fetching, refreshing, and storing tokens. There is an expectation
+ * (but not enforced by code) that tokens provided by {@link TokenOrchestrator} methods are valid (not expired).
+ *
+ * Consumers simply call {@link TokenOrchestrator.getToken} (or {@link TokenOrchestrator.authorize}) to use tokens as needed.
  *
- * Defines how {@link Token | Tokens} are retrieved to be consumed within an application
+ * @typeParam E - Map of all events fired from {@link TokenOrchestrator.emitter}
  *
- * @see {@link FetchClient}
+ * @remarks
+ * // TODO
+ * Each [Platform Library](/docs/structure#tier-3) offers {@link TokenOrchestrator} implementations relevant to the corresponding platform.
+ *
+ * @see
+ * * Orchestrator Consumer Example: {@link FetchClient}
  */
-export declare abstract class TokenOrchestrator<E extends TokenOrchestrator.Events = TokenOrchestrator.Events> implements RequestAuthorizer {
+export declare abstract class TokenOrchestrator<E extends TokenOrchestrator.Events = TokenOrchestrator.Events> {
+    /**
+     * Possible events: {@link TokenOrchestrator.Events}
+     *
+     * @example
+     * To add a new event within a derived class, first extend {@link TokenOrchestrator.Events}, like so:
+     * ```ts
+     * type MyOrchestratorEvents = { 'no_token': { params: any } } & TokenOrchestrator.Events;
+     *
+     * class MyTokenOrchestrator<E extends MyOrchestratorEvents = MyOrchestratorEvents> extends TokenOrchestrator<E> {
+     *   protected async getToken (params: TokenOrchestrator.AuthorizeParams): Promise<Token | null> {
+     *     const token = this.findTokenInStorage(params);     // example method
+     *     if (token === null) {
+     *       // this `.emit` call will be properly typed
+     *       this.emitter.emit('no_token', params);
+     *     }
+     *     return token;
+     *   }
+     * }
+     * ```
+     */
     protected readonly emitter: EventEmitter<E>;
+    /** alias for `this.emitter.on` */
     on(...args: Parameters<EventEmitter<E>['on']>): EventEmitter<E>;
+    /** alias for `this.emitter.off` */
     off(...args: Parameters<EventEmitter<E>['off']>): EventEmitter<E>;
     /**
      * @abstract
@@ -22,15 +53,34 @@ export declare abstract class TokenOrchestrator<E extends TokenOrchestrator.Even
      */
     abstract getToken(params: TokenOrchestrator.AuthorizeParams): Promise<Token | null>;
     /**
-     * Signs an outgoing {@link !Request} with an `Authorization` header via {@link Token.Token | Token} retrieved from {@link getToken}
+     * @abstract
+     * Invalidates a {@link Token.Token | Token}, so subsequent {@link TokenOrchestrator.getToken | getToken} calls will result in the invalidated token
+     */
+    abstract invalidateToken(id: string): Promise<void>;
+    /**
+     * Signs an outgoing {@link !Request} with an `Authorization` header via {@link Token | Token} retrieved from {@link getToken}
      *
      * Optionally {@link TokenOrchestrator.AuthorizeParams | AuthorizeParams} can be provided to be passed along to {@link getToken}
-     *
-     * @see {@link FetchClient}
      */
-    authorize(input: string | URL | Request, init?: RequestAuthorizerInit & TokenOrchestrator.AuthorizeParams): Promise<Request>;
+    authorize(input: string | URL | Request, init?: RequestAuthorizerInit & TokenOrchestrator.AuthorizeParams): Promise<{
+        request: Request;
+        tokenId: string;
+    }>;
 }
 export declare namespace TokenOrchestrator {
+    /**
+     * @interface
+     * Map of events fired from {@link TokenOrchestrator.emitter}
+     *
+     * @example
+     * ```ts
+     * // key = Event name
+     * // value = Event Type
+     * client.emitter.on('error', ({ error }) => {
+     *   console.log(error);
+     * });
+     * ```
+     */
     type Events = {
         error: {
             error: Error | JsonRecord;

package/dist/types/http/APIClient.d.ts

@@ -10,85 +10,292 @@ import { APIClientError } from '../errors/index.ts';
 export * from './requests/APIRequest.ts';
 export * from './requests/OAuth2Request.ts';
 /**
- * @group APIClient
+ * Generic HTTP client with built in request retry
+ * @typeParam E - Map of all events fired from {@link APIClient.emitter}
+ *
+ * @example
+ * To add an event within a derived class, first extend {@link APIClient.Events}, like so:
+ * ```ts
+ * type MyAPIEvents = { 'foo': { bar: number } } & APIClient.Events;
+ *
+ * class MyAPIClient<E extends MyAPIEvents = MyAPIEvents> extends APIClient<E> {
+ *   protected async send (request: APIRequest): Promise<Response> {
+ *     // this will be properly type checked
+ *     this.emitter('foo', { bar: 1 });
+ *     return super.send(request);
+ *   }
+ * }
+ * ```
+ *
+ * @remarks Most application developers won't need to extend this class directly — reach for
+ * {@link OAuth2.OAuth2Client | OAuth2Client} or {@link FetchClient} instead
  */
 export declare abstract class APIClient<E extends APIClient.Events = APIClient.Events> {
     #private;
     readonly configuration: APIClient.Configuration;
+    /**
+     * Possible events: {@link APIClient.Events}
+     */
     readonly emitter: EventEmitter<E>;
+    /**
+     * A cache of `dpop-nonce` values returned by authorization or resource servers.
+     * The cached nonce values will be used when generating DPoP JWTs for outgoing requests.
+     * @remarks Only relevant if client is configured with `dpop: true`
+     */
     protected readonly dpopNonceCache: DPoPNonceCache;
+    /** @internal */
     protected readonly interceptors: APIClient.RequestInterceptor[];
+    /** Map of HTTP headers to apply to every request */
     defaultHeaders: Record<string, string>;
+    /** Default {@link APIClient.RequestOptions} to apply to every request */
     defaultRequestOptions: APIClient.RequestOptions;
     constructor(params?: APIClient.ConfigurationParams | APIClient.Configuration);
+    /**
+     * Returns a key for a giving request to store or retrieve nonce values from the {@link APIClient.dpopNonceCache}
+     * @group DPoP
+     */
     protected getDPoPNonceCacheKey(request: Request): string;
+    /**
+     * Retrieves a nonce value from the {@link APIClient.dpopNonceCache}
+     * @group DPoP
+     */
     protected getDPoPNonceFromCache(request: Request): Promise<string | undefined>;
+    /**
+     * Caches an incoming nonce value from the {@link APIClient.dpopNonceCache}
+     * @group DPoP
+     */
     protected cacheDPoPNonce(request: Request, nonce: string): Promise<void>;
+    /**
+     * Cleans up resources associated with the client instance, so that it may be garbage collected.
+     *
+     * > [!Warning]
+     * > **DO NOT** use this method on active clients.
+     *
+     * @internal
+     */
+    dispose(): void;
     /**
      * Registers an {@link APIClient.RequestInterceptor} on the {@link APIClient}
      *
      * @example
+     * ```ts
      * const interceptor = (request: Request) => {
      *   req.headers.append('foo', '1');
      *   return req;
      * };
      * client.addInterceptor(interceptor);
+     * ```
+     *  @group Interceptors
      */
     addInterceptor(interceptor: APIClient.RequestInterceptor): void;
     /**
      * Unregisters an {@link APIClient.RequestInterceptor} on the {@link APIClient}
      *
      * @example
+     * ```ts
      * const interceptor = (request: Request) => { ... };
      * client.addInterceptor(interceptor);
      * ...
      * client.removeInterceptor(interceptor);
+     * ```
+     * @group Interceptors
      */
     removeInterceptor(interceptor: APIClient.RequestInterceptor): void;
+    /**
+     * @group Interceptors
+     * @internal
+     */
     protected applyInterceptors(request: APIRequest): Promise<Request>;
+    /**
+     * Determines if a {@link !Response} indicates a DPoP nonce error. If error is present, returns
+     * the value of the `dpop-nonce` response header.
+     *
+     * @group DPoP
+     * @remarks
+     * * {@link OAuth2.OAuth2Client} provides an authorization server-provided nonce implementation
+     * * {@link FetchClient} provides an resource server-provided nonce implementation
+     *
+     * @see
+     * * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-11.3 | RFC 9449 - DPoP Nonce Downgrade}
+     * * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-8 | RFC 9449 - Authorization Server-Provided Nonce}
+     * * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-9 | RFC 9449 - Resource Server-Provided Nonce}
+     */
     protected abstract checkForDPoPNonceErrorResponse(response: Response): Promise<string | undefined>;
+    /**
+     * Prepares an {@link APIRequest} for a retry with a new `dpop-nonce` value
+     *
+     * @group DPoP
+     *
+     * @see
+     * * {@link APIClient.checkForDPoPNonceErrorResponse}
+     * * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-8 | RFC 9449 - Authorization Server-Provided Nonce}
+     * * {@link https://datatracker.ietf.org/doc/html/rfc9449#section-9 | RFC 9449 - Resource Server-Provided Nonce}
+     */
     protected abstract prepareDPoPNonceRetry(request: APIRequest, nonce: string): Promise<void>;
+    /**
+     * Called on every {@link !Response} received.
+     */
     protected processResponse(response: Response, request: APIRequest): Promise<void>;
+    /**
+     * Called on every {@link !Response} where `response.ok` is `false`
+     *
+     * @example
+     * When processing a {@link !Response}, `processErrorResponse` may invoke {@link APIClient.retry}. Therefore, when extending
+     * `APIClient` and calling `super.processErrorResponse` the same error condition could be handled twice erroneously.<br/>
+     * To prevent this, check if the parameter `response` and the return value of `super.processErrorResponse` are equal (the
+     * same {@link !Response} instance). If they are not equal, the `response` was already retried.
+     * ```ts
+     * class MyAPIClient extends APIClient {
+     *   protected async processErrorResponse (response: Response, request: APIRequest): Promise<Response> {
+     *     const res = await super.processErrorResponse(response, request);
+     *     if (response !== res) {
+     *       // response was already retried, return new `Response` instance.
+     *       return res;
+     *     }
+     *     response = res;
+     *
+     *     // handle other scenarios here
+     *
+     *     return response;
+     *   }
+     * }
+     * ```
+     */
     protected processErrorResponse(response: Response, request: APIRequest): Promise<Response>;
+    /**
+     * @abstract
+     * Signs an outgoing {@link APIRequest} with required authentication information.
+     *
+     * This method is marked as `abstract` since not every API requires authentication.
+     *
+     * @remarks
+     * Most implementations of this method usually invoke {@link Token.Token.authorize | Token.authorize}
+     */
     protected authorize(request: APIRequest): Promise<void>;
+    /**
+     * **Do not call directly** use {@link APIClient.send}.
+     *
+     * This method provides an alternative means to provide a custom {@link fetch} implementation. By default,
+     * this method invokes {@link APIClient.Configuration.fetchImpl | .fetchImpl} and falls back to `globalThis.fetch`
+     *
+     * @example
+     * ```ts
+     * class MyAPIClient extends APIClient {
+     *   protected sendRequest (request: Request): Promise<Response> {
+     *     return customFetch(request);
+     *   }
+     * }
+     * ```
+     */
     protected sendRequest(request: Request): Promise<Response>;
+    /**
+     * Sends an outgoing {@link APIRequest} and processes the {@link !Response}.
+     *
+     * @remarks
+     * It's **NOT** recommended to override this method, as it contains the majority of the business logic
+     */
     protected send(request: APIRequest): Promise<Response>;
+    /**
+     * Prepares a {@link APIRequest} for a retry attempt and sends the retry request. Usually invoked within
+     * {@link APIClient.processErrorResponse}
+     */
     protected retry(request: APIRequest): Promise<Response>;
+    /**
+     * Calculates a delay to wait before retrying a {@link APIRequest} which previously responded with `429`.
+     * Useful for rate limited APIs.
+     */
     protected getRetryDelay(response: Response, request: APIRequest): number;
+    /**
+     * A `public` method to expose {@link APIClient.send}
+     * @param args - matches call signature of {@link !fetch}
+     *
+     * @example
+     * ```ts
+     * class MyAPIClient extends APIClient {...}
+     * const client = new MyAPIClient();
+     *
+     * async function fetchData () {
+     *   return client.fetch('/foo');
+     * }
+     * ```
+     */
     fetch(...args: ConstructorParameters<typeof APIRequest>): Promise<Response>;
 }
-/**
- * @group APIClient
- */
 export declare namespace APIClient {
+    /**
+     * Options to provide to {@link Configuration} at instantiation
+     */
     type ConfigurationParams = {
         dpop?: boolean;
         fetchImpl?: typeof fetch;
     };
     class Configuration implements JSONSerializable {
+        /**
+         * When `true`, client will utilize DPoP-bound tokens.
+         *
+         * @remarks
+         * Highly recommended feature; greatly improves security posture.
+         *
+         * @see
+         * {@link https://datatracker.ietf.org/doc/html/rfc9449 | DPoP RFC}
+         */
         dpop: boolean;
+        /**
+         * Implementation of {@link !fetch} used by the client. Defaults to `globalThis.fetch`.
+         *
+         * @remarks
+         * Providing a custom {@link !fetch} implementation can enable greater HTTP request customizations.
+         */
         fetchImpl?: typeof fetch;
+        /**
+         * @defaultValue
+         * ```ts
+         * { dpop: false }
+         * ```
+         */
         static DefaultOptions: {
             dpop: boolean;
             fetchImpl?: typeof fetch;
         };
         constructor(params: APIClient.ConfigurationParams);
+        /**
+         * Returns JSON representiation of {@link Configuration:class | Configuration}
+         */
         toJSON(): JsonRecord;
     }
+    /**
+     * Options which control how an {@link APIClient} sends a request.
+     */
     type RequestOptions = {
         /**
-         * When `true`, utilizes the provided {@link TokenOrchestrator} to acquire an access token to sign the outgoing request with the proper
-         * `Authorization` and `Dpop` headers, depending on the {@link TokenType} of the acquired {@link Token}. Defaults to `true`
+         * Determines whether a {@link APIRequest} should invoke {@link APIClient.authorize} before sending. Defaults to `true`
          */
         authorizeRequest: boolean | ((request: APIRequest) => boolean);
     };
+    /**
+     * Function signature for {@link APIClient} request interceptors.
+     */
     type RequestInterceptor = (request: APIRequest) => (Promise<APIRequest> | APIRequest);
+    /**
+     * @interface
+     * Map of events fired from {@link APIClient.emitter}
+     *
+     * @example
+     * ```ts
+     * // key = Event name
+     * // value = Event Type
+     * client.emitter.on('will_send', ({ request }) => {
+     *   console.log(request.url.href);
+     * });
+     * ```
+     */
     type Events = {
         /**
          * Fired before a request is sent
          *
          * @remarks
-         * The `request` instance is `readonly`. For outgoing request customization see {@link APIClient.addInterceptor}
+         * The `request` instance is `readonly`. For outgoing request customization see
+         * {@link Networking.APIClient.addInterceptor | APIClient.addInterceptor}
          */
         'will_send': {
             request: Request;
@@ -101,7 +308,8 @@ export declare namespace APIClient {
             response: Response;
         };
         /**
-         * Fired after a {@link fetch} call fails to complete (`TypeError: Failed to fetch`)
+         * Fired after a {@link fetch} call fails to complete (no response is received).
+         * Usually indicated via `TypeError: Failed to fetch`
          */
         'network_failure': {
             request: Request;
@@ -109,5 +317,9 @@ export declare namespace APIClient {
             cause: Error;
         };
     };
+    /**
+     * Determines whether a value is an {@link !Error} indicating network connectivity problems when awaiting
+     * a {@link !fetch} request.
+     */
     function isNetworkError(err: unknown): boolean;
 }

package/dist/types/http/index.d.ts

@@ -1,5 +1,10 @@
 /**
  * @module Networking
+ *
+ * @groupDescription WWWAuthenticate
+ * A collection of utilities for parsing `www-autheticate` headers
+ * * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/WWW-Authenticate | MDN - WWW-Authenticate}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7235#section-4.1 | RFC 7235 - WWW-Authenticate}
  */
 export * from './requests/OAuth2Request.ts';
 export * from './APIClient.ts';

package/dist/types/http/requests/APIRequest.d.ts

@@ -1,19 +1,45 @@
 /**
- * @group APIClient
+ * @module
+ * @mergeModuleWith Networking
+ */
+/**
+ * Properties requried to construct an instance of {@link APIRequest}
  */
 export type APIRequestInit = RequestInit & {
     context?: object;
 };
 /**
- * @group APIClient
+ * An extension of {@link !Request} to be used within {@link APIClient}.
+ *
+ * Holds a request {@link APIRequest.context | context } and {@link APIRequest.retryAttempt | retry count}
+ *
+ * @noInheritDoc
  */
 export declare class APIRequest extends Request {
     #private;
+    /**
+     * Maximum number of retries which are allowed to be attempted for a given {@link APIRequest}.
+     * @defaultValue 2
+     *
+     * @remarks
+     * Changing this value will only effect `APIRequest`s created _afterwards_. It will have no effect
+     * on any prexisting instances.
+     */
     static MaxRetryAttempts: number;
+    /**
+     * A map to store contextual information about the `APIRequest`, meaningful to the specific {@link APIClient}
+     */
     readonly context: Record<string, any>;
     constructor(input: string | URL | Request, init?: APIRequestInit);
     get retryAttempt(): number;
+    /**
+     * Compares the retry counter to {@link APIRequest.MaxRetryAttempts}
+     */
     canRetry(): boolean;
+    /**
+     * Increments retry counter
+     */
     markRetry(): void;
+    /** @internal */
     clone(): APIRequest;
 }

package/dist/types/http/requests/OAuth2Request.d.ts

@@ -6,25 +6,35 @@ import type { OpenIdConfiguration } from '../../types/index.ts';
 import type { OAuth2Client } from '../../oauth2/client.ts';
 import { APIRequest } from './APIRequest.ts';
 /**
- * @group OAuth2Request
+ * A builder class for {@link !Request} instances representing a OAuth2 endpoint request
+ * @group OAuth2Client
  */
 export declare abstract class OAuth2Request {
+    /** HTTP headers for the outgoing request */
     headers: Headers;
+    /** HTTP body for the outgoing request */
     body: URLSearchParams;
+    /** Reference to the OAuth2 Metadata document from the authorization server */
     openIdConfiguration: OpenIdConfiguration;
+    /** Configuration of the {@link OAuth2Client} being used to send the request */
     clientConfiguration: OAuth2Client.Configuration;
+    /** Authentication setting for the authorization server. Only relevant to Confidental Clients */
     clientAuthentication: any;
     constructor(params: OAuth2Request.RequestParams);
+    /** Returns the URL of the request */
     abstract get url(): string;
     prepare(context?: object): APIRequest;
 }
 /**
- * @group OAuth2Request
+ * @group OAuth2Client
  */
 export declare namespace OAuth2Request {
     interface RequestParams {
+        /** Reference to the OAuth2 Metadata document from the authorization server */
         openIdConfiguration: OpenIdConfiguration;
+        /** Configuration of the {@link OAuth2Client} being used to send the request */
         clientConfiguration: OAuth2Client.Configuration;
+        /** Authentication setting for the authorization server. Only relevant to Confidental Clients */
         clientAuthentication?: any;
     }
 }

package/dist/types/http/wwwAuthenticate.d.ts

@@ -3,7 +3,11 @@
  * @mergeModuleWith Networking
  */
 /**
+ * Object representiation of a parsed `www-authenticate` header
  * @group WWWAuthenticate
+ * @see
+ * * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/WWW-Authenticate | MDN}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7235#section-4.1 | RFC 7235 - WWW-Authenticate}
  */
 export interface WWWAuthenticateError {
     readonly error: string;
@@ -12,17 +16,21 @@ export interface WWWAuthenticateError {
     [key: string]: string;
 }
 /**
+ * Type predicate for {@link WWWAuthenticateError}
  * @group WWWAuthenticate
  */
 export declare function isWWWAuthenticateError(input: unknown): input is WWWAuthenticateError;
 /**
- * parses a www-authenticate header and builds an object representation of the error condition
+ * Parses a `www-authenticate` header and returns an object representation of the error condition.
  *
  * @group WWWAuthenticate
+ * @see
+ * * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/WWW-Authenticate | MDN}
+ * * {@link https://datatracker.ietf.org/doc/html/rfc7235#section-4.1 | RFC 7235 - WWW-Authenticate}
  */
 export declare function parse(header: string | Headers | Response): WWWAuthenticateError | null;
 /**
- * Returns string value of a `www-authenticate` header
+ * Returns string value of a `www-authenticate` header.
  *
  * @remarks
  * `HeadersInit` allows for a few different representations of headers with different access patterns (.get vs [key])