feat: add some more typedoc comments

README.md

@@ -11,19 +11,18 @@ been archived and is no longer maintained. This version has been refactored from
 
 **Contributions and help is much appreciated!**
 
-
-## Table of Contents
-
--   [Documentation](#documentation)
--   [Installation](#installation)
--   [Building the Source](#building-the-source)
--   [Contributing](#contributing)
--   [License](#license)
+Implements the following OAuth 2.0 protocols and supports [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html):
+- [Authorization Code Grant](https://oauth.net/2/grant-types/authorization-code/) with [PKCE](https://oauth.net/2/pkce/)
+- [Refresh Token Grant](https://oauth.net/2/grant-types/refresh-token/)
 
 
-## Documentation
+## Table of Contents
 
-Additional documentation can be found [here](https://authts.github.io/oidc-client-ts/).
+- [Documentation](https://authts.github.io/oidc-client-ts/)
+- [Installation](#installation)
+- [Building the Source](#building-the-source)
+- [Contributing](#contributing)
+- [License](#license)
 
 
 ## Installation
@@ -69,6 +68,7 @@ $ npm test
 
 We appreciate feedback and contribution to this repo!
 
+
 ## License
 
 This project is licensed under the Apache-2.0 license. See the [LICENSE](https://github.com/authts/oidc-client-ts/blob/main/LICENSE) file for more info.

docs/oidc-client-ts.api.md

@@ -85,6 +85,24 @@ export type CreateSignoutRequestArgs = Omit<SignoutRequestArgs, "url" | "state_d
     state?: unknown;
 };
 
+// @public
+export class ErrorResponse extends Error {
+    constructor(args: {
+        error?: string;
+        error_description?: string;
+        error_uri?: string;
+        state?: unknown;
+        session_state?: string;
+    });
+    readonly error: string;
+    readonly error_description: string | undefined;
+    readonly error_uri: string | undefined;
+    readonly name: string;
+    // (undocumented)
+    readonly session_state: string | undefined;
+    state: unknown | undefined;
+}
+
 // @public (undocumented)
 export type ExtraSigninRequestArgs = Pick<CreateSigninRequestArgs, "extraQueryParams" | "extraTokenParams" | "state">;
 
@@ -212,7 +230,7 @@ export class OidcClient {
     protected readonly _validator: ResponseValidator;
 }
 
-// @public (undocumented)
+// @public
 export interface OidcClientSettings {
     acr_values?: string;
     authority: string;
@@ -248,7 +266,7 @@ export interface OidcClientSettings {
     userInfoJwtIssuer?: "ANY" | "OP" | string;
 }
 
-// @public (undocumented)
+// @public
 export class OidcClientSettingsStore {
     constructor({ authority, metadataUrl, metadata, signingKeys, metadataSeed, client_id, client_secret, response_type, scope, redirect_uri, post_logout_redirect_uri, client_authentication, prompt, display, max_age, ui_locales, acr_values, resource, response_mode, filterProtocolClaims, loadUserInfo, staleStateAgeInSeconds, clockSkewInSeconds, userInfoJwtIssuer, mergeClaims, stateStore, extraQueryParams, extraTokenParams }: OidcClientSettings);
     // (undocumented)
@@ -550,9 +568,7 @@ export class SigninState extends State {
     readonly client_id: string;
     // (undocumented)
     readonly client_secret: string | undefined;
-    // (undocumented)
     readonly code_challenge: string | undefined;
-    // (undocumented)
     readonly code_verifier: string | undefined;
     // (undocumented)
     readonly extraTokenParams: Record<string, unknown> | undefined;
@@ -682,16 +698,13 @@ export class User {
     set expires_in(value: number | undefined);
     // (undocumented)
     static fromStorageString(storageString: string): User;
-    // (undocumented)
     id_token: string | undefined;
     profile: UserProfile;
-    // (undocumented)
     refresh_token: string | undefined;
     scope: string | undefined;
     get scopes(): string[];
     session_state: string | undefined;
     readonly state: unknown | undefined;
-    // (undocumented)
     token_type: string;
     // (undocumented)
     toStorageString(): string;
@@ -821,7 +834,7 @@ export class UserManagerEvents extends AccessTokenEvents {
     unload(): void;
 }
 
-// @public (undocumented)
+// @public
 export interface UserManagerSettings extends OidcClientSettings {
     accessTokenExpiringNotificationTimeInSeconds?: number;
     automaticSilentRenew?: boolean;
@@ -847,7 +860,7 @@ export interface UserManagerSettings extends OidcClientSettings {
     validateSubOnSilentRenew?: boolean;
 }
 
-// @public (undocumented)
+// @public
 export class UserManagerSettingsStore extends OidcClientSettingsStore {
     constructor(args: UserManagerSettings);
     // (undocumented)

src/ErrorResponse.ts

@@ -4,22 +4,32 @@
 import { Logger } from "./utils";
 
 /**
- * @internal
+ * Error class thrown in case of an authentication error.
+ *
+ * @public
  */
 export class ErrorResponse extends Error {
+    /** Marker to detect class: "ErrorResponse" */
     public readonly name: string;
 
+    /** An error code string that can be used to classify the types of errors that occur and to respond to errors. */
     public readonly error: string;
+    /** additional information that can help a developer identify the cause of the error.*/
     public readonly error_description: string | undefined;
+    /**
+     * URI identifying a human-readable web page with information about the error, used to provide the client
+       developer with additional information about the error.
+    */
     public readonly error_uri: string | undefined;
 
-    public readonly session_state: string | undefined;
-
     /** custom "state", which can be used by a caller to have "data" round tripped */
     public state: unknown | undefined;
 
+    public readonly session_state: string | undefined;
+
     public constructor(args: {
-        error?: string; error_description?: string; error_uri?: string; state?: unknown; session_state?: string;
+        error?: string; error_description?: string; error_uri?: string;
+        state?: unknown; session_state?: string;
     }) {
         super(args.error_description || args.error);
 

src/OidcClientSettings.ts

@@ -18,6 +18,8 @@ const DefaultClockSkewInSeconds = 60 * 5;
 export type SigningKey = Record<string, string | string[]>;
 
 /**
+ * The settings used to configure the {@link OidcClient}.
+ *
  * @public
  */
 export interface OidcClientSettings {
@@ -100,6 +102,9 @@ export interface OidcClientSettings {
 }
 
 /**
+ * The settings with defaults applied of the {@link OidcClient}.
+ * @see {@link OidcClientSettings}
+ *
  * @public
  */
 export class OidcClientSettingsStore {

src/SigninResponse.ts

@@ -14,24 +14,35 @@ export class SigninResponse {
     public readonly state_id: string | undefined;
 
     // updated by ResponseValidator
+    /** @see {@link ErrorResponse.error} */
     public error: string | undefined;
+    /** @see {@link ErrorResponse.error_description} */
     public error_description: string | undefined;
+    /** @see {@link ErrorResponse.error_uri} */
     public error_uri: string | undefined;
 
     // updated by ResponseValidator
+    /** @see {@link User.id_token} */
     public id_token: string | undefined;
+    /** @see {@link User.session_state} */
     public session_state: string | undefined;
+    /** @see {@link User.access_token} */
     public access_token: string;
+    /** @see {@link User.refresh_token} */
     public refresh_token: string | undefined;
+    /** @see {@link User.token_type} */
     public token_type: string;
+    /** @see {@link User.scope} */
     public scope: string | undefined;
+    /** @see {@link User.expires_at} */
     public expires_at: number | undefined;
 
     // set by ResponseValidator
     /** custom "state", which can be used by a caller to have "data" round tripped */
     public state: unknown;
 
     // set by ResponseValidator
+    /** @see {@link User.profile} */
     public profile: UserProfile = {};
 
     public constructor(params: URLSearchParams) {

src/SigninState.ts

@@ -9,18 +9,27 @@ import { State } from "./State";
  */
 export class SigninState extends State {
     // isCode
+    /** The same code_verifier that was used to obtain the authorization_code via PKCE. */
     public readonly code_verifier: string | undefined;
+    /** Used to secure authorization code grants via Proof Key for Code Exchange (PKCE). */
     public readonly code_challenge: string | undefined;
 
     // to ensure state still matches settings
+    /** @see {@link OidcClientSettings.authority} */
     public readonly authority: string;
+    /** @see {@link OidcClientSettings.client_id} */
     public readonly client_id: string;
+    /** @see {@link OidcClientSettings.redirect_uri} */
     public readonly redirect_uri: string;
+    /** @see {@link OidcClientSettings.scope} */
     public readonly scope: string;
+    /** @see {@link OidcClientSettings.client_secret} */
     public readonly client_secret: string | undefined;
+    /** @see {@link OidcClientSettings.extraTokenParams} */
     public readonly extraTokenParams: Record<string, unknown> | undefined;
-
+    /** @see {@link OidcClientSettings.response_mode} */
     public readonly response_mode: "query" | "fragment" | undefined;
+
     public readonly skipUserInfo: boolean | undefined;
 
     public constructor(args: {

src/SignoutResponse.ts

@@ -8,8 +8,11 @@ export class SignoutResponse {
     public readonly state_id: string | undefined;
 
     // updated by ResponseValidator
+    /** @see {@link ErrorResponse.error} */
     public error: string | undefined;
+    /** @see {@link ErrorResponse.error_description} */
     public error_description: string | undefined;
+    /** @see {@link ErrorResponse.error_uri} */
     public error_uri: string | undefined;
 
     // set by ResponseValidator

src/User.ts

@@ -18,19 +18,32 @@ export interface UserProfile {
  * @public
  */
 export class User {
+    /**
+     * A JSON Web Token (JWT). Only provided if `openid` scope was requested.
+     * The application can access the data decoded by using the `profile` property.
+     */
     public id_token: string | undefined;
 
     /** The session state value returned from the OIDC provider. */
     public session_state: string | undefined;
 
-    /** The access token returned from the OIDC provider. */
+    /**
+     * The requested access token returned from the OIDC provider. The application can use this token to
+     * authenticate itself to the secured resource.
+     */
     public access_token: string;
 
+    /**
+     * An OAuth 2.0 refresh token. The app can use this token to acquire additional access tokens after the
+     * current access token expires. Refresh tokens are long-lived and can be used to maintain access to resources
+     * for extended periods of time.
+     */
     public refresh_token: string | undefined;
 
+    /** Typically "Bearer" */
     public token_type: string;
 
-    /** The scope returned from the OIDC provider. */
+    /** The scopes that the requested access token is valid for. */
     public scope: string | undefined;
 
     /** The claims represented by a combination of the `id_token` and the user info endpoint. */

src/UserManagerSettings.ts

@@ -8,6 +8,8 @@ const DefaultAccessTokenExpiringNotificationTimeInSeconds = 60;
 const DefaultCheckSessionIntervalInSeconds = 2;
 
 /**
+ * The settings used to configure the {@link UserManager}.
+ *
  * @public
  */
 export interface UserManagerSettings extends OidcClientSettings {
@@ -56,6 +58,9 @@ export interface UserManagerSettings extends OidcClientSettings {
 }
 
 /**
+ * The settings with defaults applied of the {@link UserManager}.
+ * @see {@link UserManagerSettings}
+ *
  * @public
  */
 export class UserManagerSettingsStore extends OidcClientSettingsStore {

src/index.ts

@@ -8,6 +8,7 @@ export type { ILogger } from "./utils";
 export { AccessTokenEvents } from "./AccessTokenEvents";
 export type { AccessTokenCallback } from "./AccessTokenEvents";
 export { CheckSessionIFrame } from "./CheckSessionIFrame";
+export { ErrorResponse } from "./ErrorResponse";
 export { InMemoryWebStorage } from "./InMemoryWebStorage";
 export { MetadataService } from "./MetadataService";
 export * from "./OidcClient";