Merge pull request #964 from authts/improve-doc

Improve doc and simplify interface

docs/oidc-client-ts.api.md

@@ -46,48 +46,14 @@ export class CheckSessionIFrame {
 }
 
 // @public (undocumented)
-export interface CreateSigninRequestArgs {
-    // (undocumented)
-    acr_values?: string;
-    // (undocumented)
-    client_secret?: string;
-    // (undocumented)
-    display?: string;
-    // (undocumented)
-    extraQueryParams?: Record<string, string | number | boolean>;
-    // (undocumented)
-    extraTokenParams?: Record<string, unknown>;
-    // (undocumented)
-    id_token_hint?: string;
-    // (undocumented)
-    login_hint?: string;
-    // (undocumented)
-    max_age?: number;
-    // (undocumented)
-    nonce?: string;
-    // (undocumented)
-    prompt?: string;
+export interface CreateSigninRequestArgs extends Omit<SigninRequestArgs, "url" | "authority" | "client_id" | "redirect_uri" | "response_type" | "scope" | "state_data"> {
     // (undocumented)
     redirect_uri?: string;
     // (undocumented)
-    request?: string;
-    // (undocumented)
-    request_type?: string;
-    // (undocumented)
-    request_uri?: string;
-    // (undocumented)
-    resource?: string | string[];
-    // (undocumented)
-    response_mode?: "query" | "fragment";
-    // (undocumented)
     response_type?: string;
     // (undocumented)
     scope?: string;
-    // (undocumented)
-    skipUserInfo?: boolean;
     state?: unknown;
-    // (undocumented)
-    ui_locales?: string;
 }
 
 // @public (undocumented)
@@ -771,7 +737,6 @@ export interface SignoutRequestArgs {
     post_logout_redirect_uri?: string;
     // (undocumented)
     request_type?: string;
-    // (undocumented)
     state_data?: unknown;
     // (undocumented)
     url: string;

src/MetadataService.ts

@@ -8,6 +8,7 @@ import type { OidcMetadata } from "./OidcMetadata";
 
 /**
  * @public
+ * @see https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata
  */
 export class MetadataService {
     private readonly _logger = new Logger("MetadataService");

src/OidcClient.ts

@@ -7,7 +7,7 @@ import { OidcClientSettings, OidcClientSettingsStore } from "./OidcClientSetting
 import { ResponseValidator } from "./ResponseValidator";
 import { MetadataService } from "./MetadataService";
 import type { RefreshState } from "./RefreshState";
-import { SigninRequest } from "./SigninRequest";
+import { SigninRequest, SigninRequestArgs } from "./SigninRequest";
 import { SigninResponse } from "./SigninResponse";
 import { SignoutRequest, SignoutRequestArgs } from "./SignoutRequest";
 import { SignoutResponse } from "./SignoutResponse";
@@ -19,31 +19,14 @@ import { ClaimsService } from "./ClaimsService";
 /**
  * @public
  */
-export interface CreateSigninRequestArgs {
+export interface CreateSigninRequestArgs
+    extends Omit<SigninRequestArgs, "url" | "authority" | "client_id" | "redirect_uri" | "response_type" | "scope" | "state_data"> {
     redirect_uri?: string;
     response_type?: string;
     scope?: string;
-    nonce?: string;
 
     /** custom "state", which can be used by a caller to have "data" round tripped */
     state?: unknown;
-
-    prompt?: string;
-    display?: string;
-    max_age?: number;
-    ui_locales?: string;
-    id_token_hint?: string;
-    login_hint?: string;
-    acr_values?: string;
-    resource?: string | string[];
-    response_mode?: "query" | "fragment";
-    request?: string;
-    request_uri?: string;
-    extraQueryParams?: Record<string, string | number | boolean>;
-    request_type?: string;
-    client_secret?: string;
-    extraTokenParams?: Record<string, unknown>;
-    skipUserInfo?: boolean;
 }
 
 /**
@@ -57,7 +40,10 @@ export interface UseRefreshTokenArgs {
 /**
  * @public
  */
-export type CreateSignoutRequestArgs = Omit<SignoutRequestArgs, "url" | "state_data"> & { state?: unknown };
+export type CreateSignoutRequestArgs = Omit<SignoutRequestArgs, "url" | "state_data"> & {
+    /** custom "state", which can be used by a caller to have "data" round tripped */
+    state?: unknown;
+};
 
 /**
  * @public

src/SigninRequest.ts

@@ -6,6 +6,7 @@ import { SigninState } from "./SigninState";
 
 /**
  * @public
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
  */
 export interface SigninRequestArgs {
     // mandatory
@@ -17,23 +18,27 @@ export interface SigninRequestArgs {
     scope: string;
 
     // optional
-    prompt?: string;
+    response_mode?: "query" | "fragment";
+    nonce?: string;
     display?: string;
+    prompt?: string;
     max_age?: number;
     ui_locales?: string;
     id_token_hint?: string;
     login_hint?: string;
     acr_values?: string;
+
+    // other
     resource?: string | string[];
-    response_mode?: "query" | "fragment" ;
     request?: string;
     request_uri?: string;
-    extraQueryParams?: Record<string, string | number | boolean>;
     request_type?: string;
-    client_secret?: string;
+    extraQueryParams?: Record<string, string | number | boolean>;
+
+    // special
     extraTokenParams?: Record<string, unknown>;
+    client_secret?: string;
     skipUserInfo?: boolean;
-    nonce?: string;
     disablePKCE?: boolean;
     /** custom "state", which can be used by a caller to have "data" round tripped */
     state_data?: unknown;

src/SigninResponse.ts

@@ -8,6 +8,8 @@ const OidcScope = "openid";
 
 /**
  * @public
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthResponse
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
  */
 export class SigninResponse {
     // props present in the initial callback response regardless of success

src/SignoutRequest.ts

@@ -6,17 +6,21 @@ import { State } from "./State";
 
 /**
  * @public
+ * @see https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout
  */
 export interface SignoutRequestArgs {
     // mandatory
     url: string;
 
     // optional
-    state_data?: unknown;
     id_token_hint?: string;
     post_logout_redirect_uri?: string;
     extraQueryParams?: Record<string, string | number | boolean>;
+
+    // special
     request_type?: string;
+    /** custom "state", which can be used by a caller to have "data" round tripped */
+    state_data?: unknown;
 }
 
 /**

src/SignoutResponse.ts

@@ -3,6 +3,7 @@
 
 /**
  * @public
+ * @see https://openid.net/specs/openid-connect-core-1_0.html#AuthError
  */
 export class SignoutResponse {
     public readonly state: string | null;

src/TokenClient.ts

@@ -73,6 +73,11 @@ export class TokenClient {
         );
     }
 
+    /**
+     * Exchange code.
+     *
+     * @see https://www.rfc-editor.org/rfc/rfc6749#section-4.1.3
+     */
     public async exchangeCode({
         grant_type = "authorization_code",
         redirect_uri = this._settings.redirect_uri,
@@ -123,6 +128,11 @@ export class TokenClient {
         return response;
     }
 
+    /**
+     * Exchange credentials.
+     *
+     * @see https://www.rfc-editor.org/rfc/rfc6749#section-4.3.2
+     */
     public async exchangeCredentials({
         grant_type = "password",
         client_id = this._settings.client_id,
@@ -169,6 +179,11 @@ export class TokenClient {
         return response;
     }
 
+    /**
+     * Exchange a refresh token.
+     *
+     * @see https://www.rfc-editor.org/rfc/rfc6749#section-6
+     */
     public async exchangeRefreshToken({
         grant_type = "refresh_token",
         client_id = this._settings.client_id,