Merge pull request #73 from torusresearch/docs/custom-jwt

custom login config docs updated and cognito example docs updated

docs/open-login/api-reference/initialization.mdx

@@ -27,14 +27,22 @@ The OpenLogin constructor takes an object with `OpenLoginOptions` as input.
 
 - `options` - `OpenLoginOptions`: The options of the constructor
   - `clientId` - `string` : Your project id which you can get from [developer dashboard](https://developer.tor.us/)
+
   - `network` - `enum`: Environment to run openlogin (testnet, mainnet, development)
+
   - `_iframeUrl`- `string`: Url of openlogin iframe, you can pass custom iframe url here else
   it will be added based on network value.For testnet iframe url is `https://beta.openlogin.com`  and
   for mainnet it is `https://app.openlogin.com`. If you are passing valid  `network` value then network value
   will be given precedence over iframe url.
 
   - `uxMode` - `enum`(optional): `popup` and `redirect` uxmode are supported. By default it is set to `redirect`
 
+  - `loginConfig` -`LoginConfig`(optional):  LoginConfig allows you to specify custom loginConfig to customize visiblity of login modal
+  options and to specify your custom verifier for each login option.
+
+  - `whiteLabel`: `WhiteLabelData` (optional): Options for whitelabling default openlogin modal.
+  You can toggle theme and primary colors of login modal and openlogin verification screens by using WhiteLabelData.
+
 **Returns**
 
 - `Object`: The openlogin instance with all its methods and events.
@@ -43,16 +51,147 @@ The OpenLogin constructor takes an object with `OpenLoginOptions` as input.
 
 ```javascript
 type OpenLoginOptions = {
+  /**
+   * You can get your clientId/projectId by registering your
+   * dapp on {@link "https://developer.tor.us"| developer dashbaord}
+   */
   clientId: string;
+
+  /**
+   * network specifies the openlogin iframe url url to be used.
+   *
+   * - `'mainnet'`: https://app.openlogin.com will be used which is the production version.
+   * - `'testnet'`: https://beta.openlogin.com will be used which is the beta version.
+   * - `'development'`: http://localhost:3000 will be used for development purpose.
+   */
   network: OPENLOGIN_NETWORK_TYPE;
-  _iframeUrl?: string;
+
+  /**
+   * Setting no3PC forces openlogin to assume that third party cookies are blocked
+   * in the browser.
+   *
+   * @defaultValue false
+   * @remarks
+   * Only pass no3PC to `true` when you are sure that third party cookies are not
+   * supported. By default openlogin will self check third party cookies and proceed
+   * accordingly.
+   */
+  no3PC?: boolean;
+
+  /**
+   * redirectUrl is the dapp's url where user will be redirected after login.
+   *
+   * @remarks
+   * Register this url at {@link "https://developer.tor.us"| developer dashbaord}
+   * else initialization will give error.
+   */
   redirectUrl?: string;
-  loginUrl?: string;
-  webAuthnUrl?: string;
-  logoutUrl?: string;
+
+  /**
+   * two uxModes are supported:-
+   * - `'POPUP'`: In this uxMode, a popup will be shown to user for login.
+   * - `'REDIRECT'`: In this uxMode, user will be redirected to a new window tab for login.
+   *
+   * @defaultValue `'POPUP'`
+   * @remarks
+   *
+   * Use of `'REDIRECT'` mode is recommended in browsers where popups might get blocked.
+   */
   uxMode?: UX_MODE_TYPE;
+
+  /**
+   * replaceUrlOnRedirect removes the params from the redirected url after login
+   *
+   * @defaultValue true
+   */
   replaceUrlOnRedirect?: boolean;
+
+  /**
+   * originData is used to verify the origin of dapp by iframe.
+   *
+   * @internal
+   * @remarks
+   * You don't have to pass originData explicitly if you have registered your dapp at
+   * {@link "https://developer.tor.us"| developer dashbaord}.
+   *
+   * originData contains a signature of dapp's origin url which is generated using
+   * project's secret.
+   */
   originData?: OriginData;
+
+  /**
+   * loginConfig enables you to pass your own login verifiers configuration for various
+   * loginProviders.
+   *
+   * loginConfig is key value map where each key should be a valid loginProvider and value
+   * should be custom configuration for that loginProvider
+   *
+   * @remarks
+   * You can deploy your own verifiers from {@link "https://developer.tor.us"| developer dashbaord}
+   * to use here.
+   *
+   */
+  loginConfig?: LoginConfig;
+
+  /**
+   * _iframeUrl is for internal development use only and is used to override the
+   * `network` parameter.
+   * @internal
+   */
+  _iframeUrl?: string;
+  /**
+   * _startUrl is for internal development use only and is used specify authentication
+   * start url of iframe.
+   * @internal
+   */
+  _startUrl?: string;
+
+  /**
+   * _popupUrl is for internal development use only and is used specify url of popup window
+   * for popup uxMode.
+   * @internal
+   */
+  _popupUrl?: string;
+
+  /**
+   * options for whitelabling default openlogin modal.
+   */
+  whiteLabel?: WhiteLabelData;
+};
+
+type WhiteLabelData = {
+  /**
+   * App name to display in the UI
+   */
+  name?: string;
+  /**
+   * App logo to use in light mode
+   */
+  logoLight?: string;
+  /**
+   * App logo to use in dark mode
+   */
+  logoDark?: string;
+  /**
+   * Default language to use
+   *
+   * @defaultValue en
+   */
+  defaultLanguage?: string;
+  /**
+   * Whether to enable dark mode
+   *
+   * @defaultValue false
+   */
+  dark?: boolean;
+
+  /**
+   * Used to customize theme of the login modal with following options
+   * `'primary'` - To customize primary color of modal's content.
+   */
+  theme?: {
+    [P in string]: string;
+  };
 };
 
 const OPENLOGIN_NETWORK = {
@@ -85,6 +224,118 @@ const openlogin = new OpenLogin({
 });
 ```
 
+## Using Custom login configuration
+
+
+By default , openlogin will use verifiers deployed by torus and will show all default available login options in login modal.
+If you want to customize the login modal or want to use your own login verifiers then you can use custom login configuration
+with openlogin.
+
+For ex: In code snippet below, we are customizing loginConfig to show only google and facebook as login options in default
+openlogin modal. Also you can pass your own verifiers in the configuration for any of the login providers.
+
+```javascript
+const openlogin = new OpenLogin({
+  // your clientId aka projectId , get it from https://developer.tor.us
+  // clientId is not required for localhost, you can set it to any string
+  // for development
+  clientId: YOUR_PROJECT_ID,
+  network: "testnet",
+  // you can pass login config to modify default
+  // login options in login modal, also you can pass
+  // your own verifiers.
+  loginConfig: {
+    google: {
+      verifier: "tkey-google-lrc",
+      name: "google",
+      typeOfLogin: "google",
+      showOnModal: true,
+      showOnDesktop: true,
+      showOnMobile: true,
+    },
+    facebook: {
+      verifier: "tkey-facebook-lrc",
+      name: "facebook",
+      typeOfLogin: "facebook",
+      showOnModal: true,
+      showOnDesktop: false,
+      showOnMobile: true,
+      mainOption: true,
+      description: "facebook social login",
+    },
+  },
+});
+```
+
+**Reference**
+```javascript
+
+type LoginConfig = Record<
+  string,
+  {
+    verifier: string;
+
+    /**
+     * The type of login. Refer to enum `LOGIN_TYPE`
+     */
+    typeOfLogin: TypeOfLogin;
+
+    /**
+     * Display Name. If not provided, we use the default for openlogin app
+     */
+    name: string;
+
+    /**
+     * Description for button. If provided, it renders as a full length button. else, icon button
+     */
+    description?: string;
+
+    /**
+     * Custom client_id. If not provided, we use the default for openlogin app
+     */
+    clientId?: string;
+
+    verifierSubIdentifier?: string;
+
+    /**
+     * Logo to be shown on mouse hover. If not provided, we use the default for openlogin app
+     */
+    logoHover?: string;
+
+    /**
+     * Logo to be shown on dark background (dark theme). If not provided, we use the default for openlogin app
+     */
+    logoLight?: string;
+
+    /**
+     * Logo to be shown on light background (light theme). If not provided, we use the default for openlogin app
+     */
+    logoDark?: string;
+
+    /**
+     * Show login button on the main list
+     */
+    mainOption?: boolean;
+
+    /**
+     * Whether to show the login button on modal or not
+     */
+    showOnModal?: boolean;
+
+    /**
+     * Whether to show the login button on desktop
+     */
+    showOnDesktop?: boolean;
+
+    /**
+     * Whether to show the login button on mobile
+     */
+    showOnMobile?: boolean;
+  }
+>;
+
+```
+
 ## `init`
 
 Initialize the OpenLogin object after creation. Init sync up the state of user login session in

docs/open-login/api-reference/usage.mdx

@@ -16,6 +16,7 @@ await openlogin.login(params);
 
 - `params` - `LoginParams` \(optional\) : The login options. Used to specify a
   type of login.
+
   - `loginProvider` - `LOGIN_PROVIDER` : The loginProvider name. Supported loginProviders are can be of any value given in
   LOGIN_PROVIDER. In future versions you  can pass custom loginProvider apart from options given LOGIN_PROVIDER.
 
@@ -190,11 +191,11 @@ const privKey = await openlogin.login();
 
 ```javascript
 const privKey = await openlogin.login({
-      extraLoginOptions: {
-        login_hint: email,
-      },
-      loginProvider: "email_passwordless",
-      redirectUrl: `https://example.com/redirect`,
+    extraLoginOptions: {
+      login_hint: email,
+    },
+    loginProvider: "email_passwordless",
+    redirectUrl: `https://example.com/redirect`,
 });
 ```