Improve API reference of React Native SDK

ref DEV-2040

packages/authgear-core/src/error.ts

@@ -20,14 +20,50 @@ export class AuthgearError extends Error {
  * @public
  */
 export enum ErrorName {
+  /**
+   * Indicates that the server does not understand the request (i.e. syntactic error).
+   * Status code: 400
+   */
   BadRequest = "BadRequest",
+  /**
+   * Indicates that the server understands the request, but refuse to process it (i.e. semantic error).
+   * Status code: 400
+   */
   Invalid = "Invalid",
+  /**
+   * Indicates that the client does not have valid credentials (i.e. authentication error).
+   * Status code: 401
+   */
   Unauthorized = "Unauthorized",
+  /**
+   * Indicates that the client's credentials are not allowed for the request (i.e. authorization error).
+   * Status code: 403
+   */
   Forbidden = "Forbidden",
+  /**
+   * Indicates that the server cannot find the requested resource.
+   * Status code: 404
+   */
   NotFound = "NotFound",
+  /**
+   * Indicates that the resource is already exists on the server.
+   * Status code: 409
+   */
   AlreadyExists = "AlreadyExists",
+  /**
+   * Indicates that the client has sent too many requests in a given amount of time.
+   * Status code: 429
+   */
   TooManyRequest = "TooManyRequest",
+  /**
+   * Indicates that the server encountered an unexpected condition and unable to process the request.
+   * Status code: 500
+   */
   InternalError = "InternalError",
+  /**
+   * Indicates that the server is not ready to handle the request.
+   * Status code: 503
+   */
   ServiceUnavailable = "ServiceUnavailable",
 }
 
@@ -143,28 +179,31 @@ export function _decodeError(err: any): Error {
 }
 
 /**
- * PreAuthenticatedURLNotAllowedError
+ * PreAuthenticatedURLNotAllowedError is the root class of errors related to pre-authenticated URL.
  *
  * @public
  */
 export class PreAuthenticatedURLNotAllowedError extends AuthgearError {}
 
 /**
- * PreAuthenticatedURLInsufficientScopeError
+ * This may happen if the "Pre-authenticated URL" feature was not enabled when the user logged in during this session.
+ * Ask the user to log in again to enable this feature.
  *
  * @public
  */
 export class PreAuthenticatedURLInsufficientScopeError extends PreAuthenticatedURLNotAllowedError {}
 
 /**
- * PreAuthenticatedURLIDTokenNotFoundError
+ * The user logged in from an older SDK version that does not support the pre-authenticated URL.
+ * Ask the user to log in again to resolve the problem.
  *
  * @public
  */
 export class PreAuthenticatedURLIDTokenNotFoundError extends PreAuthenticatedURLNotAllowedError {}
 
 /**
- * PreAuthenticatedURLDeviceSecretNotFoundError
+ * The device secret is not found. This may happen if the "Pre-authenticated URL" feature was not enabled when the user logged in during this session.
+ * Ask the user to log in again to enable this feature.
  *
  * @public
  */

packages/authgear-core/src/types.ts

@@ -1,7 +1,11 @@
 /**
  * UserInfo is the result of fetchUserInfo.
  * It contains `sub` which is the User ID,
- * as well OIDC standard claims like `email`.
+ * as well as OIDC standard claims like `email`,
+ * see https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims.
+ *
+ * In addition to these standard claims, it may include custom claims
+ * defined by Authgear to support additional functionality like `isVerified`.
  *
  * @public
  */
@@ -49,7 +53,13 @@ export interface UserInfo {
  * @public
  */
 export enum ColorScheme {
+  /**
+   * Force to use the light color scheme in the AuthUI when the project config is "Auto".
+   */
   Light = "light",
+  /**
+   * Force to use the dark color scheme in the AuthUI when the project config is "Auto".
+   */
   Dark = "dark",
 }
 
@@ -59,9 +69,28 @@ export enum ColorScheme {
  * @public
  */
 export enum PromptOption {
+  /**
+   * The `none` prompt is used to sliently authenticate the user without prompting for any action.
+   * This prompt bypasses the need for `login` and `consent` prompts
+   * only when the user has previously given consent to the application and has an active session.
+   */
   None = "none",
+  /**
+   * The `login` prompt requires the user to log in to the authentication provider which forces the user to re-authenticate.
+   */
   Login = "login",
+  /**
+   * The `consent` prompt asks the user to consent to the scopes.
+   *
+   * @internal
+   */
   Consent = "consent",
+  /**
+   * The select_account prompt present a "Continue" screen to for the user to choose
+   * to continue with the session in the cookies or login to another account.
+   *
+   * @internal
+   */
   SelectAccount = "select_account",
 }
 
@@ -212,8 +241,17 @@ export interface _AnonymousUserPromotionCodeResponse {
  * @public
  */
 export interface TokenStorage {
+  /**
+   * Stores a refresh token for a give namespace to the storage.
+   */
   setRefreshToken(namespace: string, refreshToken: string): Promise<void>;
+  /**
+   * Retrieves the refresh token associated with a specific namespace in the storage.
+   */
   getRefreshToken(namespace: string): Promise<string | null>;
+  /**
+   * Deletes the refresh token for the specified namespace in the storage.
+   */
   delRefreshToken(namespace: string): Promise<void>;
 }
 
@@ -268,6 +306,11 @@ export interface _StorageDriver {
  * @public
  */
 export interface ContainerOptions {
+  /**
+   * The name of the container. The name is used as the namespace of `TokenStorage`.
+   * One use case is to use multiple containers with different names to support signing in multiple accounts.
+   * @defaultValue "default"
+   */
   name?: string;
 }
 
@@ -341,6 +384,8 @@ export interface _OIDCTokenResponse {
  * After a call to configure, the session state would become "AUTHENTICATED" if a previous session was found,
  * or "NO_SESSION" if such session was not found.
  *
+ * Please refer to {@link SessionStateChangeReason} for more information.
+ *
  * @public
  */
 export enum SessionState {
@@ -355,7 +400,7 @@ export enum SessionState {
  * These reasons can be thought of as the transition of a SessionState, which is described as follows:
  *
  * ```
- *                                                          LOGOUT / INVALID
+ *                                                      LOGOUT / INVALID / CLEAR
  *                                           +----------------------------------------------+
  *                                           v                                              |
  *    State: UNKNOWN ----- NO_TOKEN ----> State: NO_SESSION ---- AUTHENTICATED -----> State: AUTHENTICATED
@@ -375,18 +420,34 @@ export enum SessionStateChangeReason {
 }
 
 /**
+ * The path of the page in Authgear.
+ *
  * @public
  */
 export enum Page {
+  /**
+   * The path of the settings page in Authgear.
+   */
   Settings = "/settings",
+  /**
+   * The path of the indenties page in Authgear.
+   */
   Identities = "/settings/identities",
 }
 
 /**
+ * The actions that can be performed in Authgear settings page.
+ *
  * @public
  */
 export enum SettingsAction {
+  /**
+   * Change password in Authgear settings page.
+   */
   ChangePassword = "change_password",
+  /**
+   * Delete account in Authgear settings page.
+   */
   DeleteAccount = "delete_account",
 }