doc(sdk) fix typos and inconsistencies

mt-dfrey · mt-dfrey · commit a926047b8509 · 2023-10-06T12:04:20.000+09:00
diff --git a/src/index.ts b/src/index.ts
@@ -55,7 +55,7 @@ export class MtLinkSdk {
    * Call `init` to initialize the SDK and set default options for API calls.
    *
    * Some LINK APIs can be used without calling `init`.
-   * Calls related to OAuth require a client id which can only be set via the `init` function.
+   * Calls related to OAuth require a client ID which can only be set via the `init` function.
    * These APIs include:
    * - {@link authorize}
    * - {@link onboard}
@@ -91,7 +91,7 @@ export class MtLinkSdk {
     };
   }
   /**
-   * Use this method to send a guest identifier to Moneytree so that Moneytree can forward it as `saml_subject_id` parameter
+   * Use this method to send a user identifier to Moneytree so that Moneytree can forward it as `saml_subject_id` parameter
    * to the Identity Provider (IdP) via the SAMLRequest during SAML SSO flows. See the [SAML SSO documentation for details](https://docs.link.getmoneytree.com/docs/saml-introduction#saml-subject-identifier).
    *
    * This parameter can be set during {@link init} or changed on a request-by-request basis with this method.
@@ -102,19 +102,19 @@ export class MtLinkSdk {
   }
 
   /**
-   * OAuth authorization method to request guest consent to access data via the [Link API](https://getmoneytree.com/jp/link/about).
+   * OAuth authorization method to request user consent to access data via the [Link API](https://getmoneytree.com/jp/link/about).
    *
    * The only supported flow is authorization code grant with PKCE [PKCE](https://auth0.com/docs/flows/concepts/auth-code-pkce)
-   * If the user is not logged in yet this will show the login screen and redirect the guest to the consent screen after they log in.
-   * After the guest consents, they will be redirected to the redirect URI with an authorization code.
-   * If the user is already logged and has granted consent in the redirection happens immediately.
+   * If the user is not logged in yet this will show the login screen and redirect the user to the consent screen after they log in.
+   * After the user consents, they will be redirected to the redirect URI with an authorization code.
+   * If the user is already logged in and has granted consent in the redirection happens immediately.
    *
-   * You can pass the {@link AuthorizeOptions.forceLogout} option to force the guest to log in, even if they have an active session.
+   * You can pass the {@link AuthorizeOptions.forceLogout} option to force the user to log in, even if they have an active session.
    *
    * You can also choose to display the sign up form when the user is not logged in yet by setting the {@link AuthorizeOptions.authAction} option.
    *
    * @remark
-   * You must initialize the SDK via the {@link init} before calling this API.
+   * You must initialize the SDK via {@link init} before calling this API.
    *
    * @example
    * ```javascript
@@ -126,26 +126,26 @@ export class MtLinkSdk {
   }
 
   /**
-   * This method generates an URL for OAuth authorization that requires guest consent to access data via [Link API](https://getmoneytree.com/jp/link/about).
+   * This method generates a URL for OAuth authorization that requires user consent to access data via [Link API](https://getmoneytree.com/jp/link/about).
    *
    * See {@link authorize} API for authorization details. This API has exactly the same parameters as {@link authorize},
-   * the only difference is that it returns an URL instead of opening immediately with `window.open`.
+   * the only difference is that it returns a URL instead of opening immediately with `window.open`.
    */
   public authorizeUrl(options?: AuthorizeUrlOptions): string {
     return authorizeUrl(this.storedOptions, options);
   }
 
   /**
-   * The onboard API allows a new guest to get onboard faster without having to go through the registration process.
-   * All you have to do is provide an emai address and pass the same options parameter as the {@link authorize} function.
-   * We will display a consent screen explaining the access requests and applicable scopes.
-   * Once the guest consents, a new Moneytree account will be created on their behalf and authorization is completed.
+   * The onboard API allows a new user to get onboard faster without having to go through the registration process.
+   * All you have to do is provide an email address and pass the same options parameter as the {@link authorize} function.
+   * Moneytree LINK will display a consent screen explaining the access requests and applicable scopes.
+   * Once the user consents, a new Moneytree account will be created on their behalf and authorization is completed.
    * Resulting behavior will be the same as the {@link authorize} redirection flow.
    *
-   * Onboard will force any current guest session to logout, hence you do not have to call {@link logout} manually to
+   * Onboard will force any current user session to logout, hence you do not have to call {@link logout} manually to
    * ensure a clean state.
    *
-   * If an account with this email address already exists we will redirect the guest to the login screen.
+   * If an account with this email address already exists we will redirect the user to the login screen.
    *
    * @remark
    * ⚠️ You must initialize the SDK via the {@link init} before calling this API.
@@ -160,9 +160,9 @@ export class MtLinkSdk {
   }
 
   /**
-   * This method generates a URL for guest onboarding.
+   * This method generates a URL for user onboarding.
    *
-   * This API has exactly the same parameters as {@link onboard}, the only difference being that it returns an URL
+   * This API has exactly the same parameters as {@link onboard}, the only difference being that it returns a URL
    * instead of opening immediately with `window.open`.
    */
   public onboardUrl(options?: OnboardUrlOptions): string {
@@ -177,9 +177,9 @@ export class MtLinkSdk {
   }
 
   /**
-   * This method generates a URL to log out the guest.
+   * This method generates a URL to log out the user.
    *
-   * This API has exactly the same parameters as {@link logout}, the only difference being that it returns an URL
+   * This API has exactly the same parameters as {@link logout}, the only difference being that it returns a URL
    * instead of opening immediately with `window.open`.
    */
   public logoutUrl(options?: LogoutUrlOptions): string {
@@ -206,10 +206,10 @@ export class MtLinkSdk {
    * Pass `serviceId: 'vault'` to open the Vault service.
    *
    * Depending on the Vault sub-page you want to open, you can pass the following options:
-   * - `serviceList`: opens the vault service list page, pass {@link VaultOpenServiceViewServiceList} as options.
-   * - `serviceConnection`: opens the vault service connection page, pass {@link VaultOpenServiceViewServiceConnection} as options.
-   * - `connectionSetting`: opens the vault connection setting page, pass {@link VaultOpenServiceViewConnectionSetting} as options.
-   * - `customerSupport`: opens the vault customer support page, pass {@link VaultOpenServiceViewCustomerSupport} as options.
+   * - `serviceList`: opens the Vault service list page, pass {@link VaultOpenServiceViewServiceList} as options.
+   * - `serviceConnection`: opens the Vault service connection page, pass {@link VaultOpenServiceViewServiceConnection} as options.
+   * - `connectionSetting`: opens the Vault connection setting page, pass {@link VaultOpenServiceViewConnectionSetting} as options.
+   * - `customerSupport`: opens the Vault customer support page, pass {@link VaultOpenServiceViewCustomerSupport} as options.
    *
    * @remark ⚠️ calling this API before calling {@link init} will open the services view without branding (company logo etc.)
    */
@@ -237,7 +237,7 @@ export class MtLinkSdk {
   /**
    * This method can generate URLs for various services provided by Moneytree, such as Moneytree Account Settings and Vault.
    *
-   * This API has exactly the same parameters as {@link openService}, the only difference being that it returns an URL
+   * This API has exactly the same parameters as {@link openService}, the only difference being that it returns a URL
    * instead of opening immediately with `window.open`.
    */
   public openServiceUrl(serviceId: 'link-kit', options?: LinkKitOpenServiceUrlOptions): string;
@@ -261,9 +261,9 @@ export class MtLinkSdk {
   }
 
   /**
-   * Request for a password-less login link to be sent to the guest's email address.
+   * Request for a password-less login link to be sent to the user's email address.
    *
-   * Clicking on the link in the email will log a guest in directly to the screen specified by the
+   * Clicking on the link in the email will log a user in directly to the screen specified by the
    * {@link RequestLoginLinkOptions.loginLinkTo} parameter.
    */
   public requestLoginLink(options?: RequestLoginLinkOptions): Promise<void> {
diff --git a/src/typings.ts b/src/typings.ts
@@ -10,7 +10,7 @@ export interface PrivateParams {
    */
   cobrandClientId?: string;
   /**
-   * Sets subject Id for saml session version.
+   * Sets the subject ID for SAML AuthnRequest.
    */
   samlSubjectId?: string;
 }
@@ -26,33 +26,33 @@ export type AuthnMethod = typeof supportedAuthnMethod[number];
 
 export interface ConfigsOptions extends PrivateConfigsOptions {
   /**
-   * Email used to pre-fill the email field in login or sign up or form.
+   * Email address to pre-fill the email field in login or sign up or form.
    *
    * Set the default value via {@link MtLinkSdk.init}
    */
   email?: string;
   /**
-   * A redirection URL for redirecting a guest back to in the following condition:
-   * - Guest clicks on `Back to [App Name]` button in any Moneytree screen.
-   * - Guest refuses to give consent to access permission in the consent screen.
-   * - Guest logs out from Moneytree via an app with this client id
-   * - Revoke an app's consent from settings screen opened via an app with this client id
+   * A redirection URL for redirecting a user back to in one of the following conditions:
+   * - User clicks on `Back to [App Name]` button in any Moneytree screen.
+   * - User refuses to give consent to access permission in the consent screen.
+   * - User logs out from Moneytree via an app with this client ID
+   * - User revokes consent from settings screen opened via an app with this client ID
    *
-   * ⚠️ No `Back to [App Name]` button will be shown if this value is not set, and any of the actions mentioned above will redirect the guest back to login screen by default.
+   * ⚠️ No `Back to [App Name]` button will be shown if this value is not set, and any of the actions mentioned above will redirect the user back to the login screen by default.
    *
    * Set the default value via {@link MtLinkSdk.init}
    */
   backTo?: string;
   /**
-   * Show login or sign up screen when a session does not exist during an {@link MtLinkSdk.authorize} call.
+   * Show the login or sign up screen when a session does not exist during an {@link MtLinkSdk.authorize} call.
    *
    * Set default value via {@link MtLinkSdk.init}
    *
    * @defaultValue 'login'
    */
   authAction?: AuthAction;
   /**
-   * If you wish to disable the login to sign up form toggle button and vice-versa in the auth screen, set this to `false`.
+   * If you wish to disable the `Login to Sign up` form toggle button and vice-versa in the auth screen, set this to `false`.
    *
    * Set default value via {@link MtLinkSdk.init}
    *
@@ -68,15 +68,15 @@ export interface ConfigsOptions extends PrivateConfigsOptions {
    */
   showRememberMe?: boolean;
   /**
-   * Call method and open/render in a new browser tab, by default all views open in the same tab.
+   * Call method and open/render in a new browser tab. By default all views open in the same tab.
    *
    * Set default value via {@link MtLinkSdk.init}
    *
    * @defaultValue false
    */
   isNewTab?: boolean;
   /**
-   * Force existing guest session to logout and call authorize with a clean state.
+   * Force existing user session to logout and call authorize with a clean state.
    * @defaultValue false
    */
   forceLogout?: boolean;
@@ -194,8 +194,8 @@ export interface OAuthSharedParams {
   /**
    * The state parameter for OAuth flows, see [here](https://auth0.com/docs/protocols/oauth2/oauth-state) for more details.
    *
-   * If you generates an identifier for the OAuth authorization on your server make sure to set this value explicitly so
-   * that you can use to acquire the access token after the OAuth redirect occurs.
+   * If you generate an identifier for the OAuth authorization on your server make sure to set this value explicitly so
+   * that you can use it to acquire the access token after the OAuth redirect occurs.
    *
    * The default value is a randomly generated [uuid](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random)), or set via {@link MtLinkSdk.init}
    */
@@ -227,7 +227,7 @@ export interface AuthorizeOptions extends OAuthSharedParams, ConfigsOptions, Aut
    * - request_refresh
    * - life_insurance_read
    *
-   * See the [LINK Platform documenation](https://docs.link.getmoneytree.com/docs/api-scopes) for more details
+   * See the [LINK Platform documentation](https://docs.link.getmoneytree.com/docs/api-scopes) for more details
    *
    * @defaultValue `'guest_read'`, or set via {@link MtLinkSdk.init}
    */
@@ -254,12 +254,13 @@ export type InitOptions = Omit<Omit<Omit<AuthorizeOptions, 'forceLogout'>, 'code
     /**
      * Environment for the SDK to connect to, the SDK will connect to the Moneytree production server by default.
      * - Moneytree clients should use `staging` for development as `develop` may contain unstable features.
-     * - `local` is only for SDK development as it has local dependencies.
+     * - `local` is only for SDK development by Moneytree engineers.
      */
     mode?: Mode;
     /**
-     * Force Moneytree to load content in this specific locale. A default value will be auto detected based on guest
-     * languages configurations and location if available.
+     * Force Moneytree to load content in this specific locale.
+     *
+     * A default value will be auto detected based on the user's language configuration and location if available.
      * Check this [spec](https://www.w3.org/TR/html401/struct/dirlang.html#h-8.1.1) for more information.
      *
      * Currently supported values are:`'en'`, `'en-AU'`, `'ja'`.
@@ -312,9 +313,9 @@ export type ServiceId = 'vault' | 'myaccount' | 'link-kit';
 
 /**
  * - `settings` - Main Moneytree account settings screen.
- * - `settings/authorized-applications` - List of apps currently connected to Moneytree.
+ * - `settings/authorized-applications` - List of apps currently connected to the Moneytree account.
  * - `settings/change-language` - Change Moneytree account language screen.
- * - `settings/email-preferences` - Change Moneytree email preferences screen
+ * - `settings/email-preferences` - Change Moneytree account email preferences screen.
  * - `settings/delete-account` - Delete Moneytree account screen.
  * - `settings/update-email` - Change Moneytree account email screen.
  * - `settings/update-password` - Change Moneytree account password screen.
@@ -335,13 +336,13 @@ export interface RequestLoginLinkOptions extends ConfigsOptions {
 export interface TokenInfo {
   /** token issuer */
   iss: string;
-  /** token cretaion time */
+  /** token creation time */
   iat: number;
   /** token expiry */
   exp: number;
   /** token audience(s) */
   aud: string[];
-  /** token subject - the moneytree ide fo the user */
+  /** token subject - the Moneytree ID of the user */
   sub: null | string;
   scope: string;
   client_id: null | string;
@@ -361,13 +362,17 @@ export interface TokenInfo {
   };
 }
 
+/** OAuth Access Token Response described in [RFC 6749 section 5.1](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1) */
 export interface Token {
   access_token: string;
   refresh_token: string;
   token_type: string;
-  /** created at in seconds */
+  /** Creation time of the token, unix timpstamp in seconds */
   created_at: number;
-  /** expiry in seconds */
+  /**
+   * The lifetime in seconds of the access token.
+   * For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
+   */
   expires_in: number;
   scope: string;
   resource_server: string;
