From 539f400e8b0dca0871bef118d85a6dec073cf1cc Mon Sep 17 00:00:00 2001 From: himanshuchawla009 Date: Tue, 13 Jul 2021 18:41:47 +0530 Subject: [PATCH] ts docs added --- .eslintrc.json | 3 +- .vscode/settings.json | 3 +- package.json | 1 + packages/core/src/constants.ts | 207 +++++++++++++++++++------ packages/core/types/src/constants.d.ts | 143 ++++++++++++++++- yarn.lock | 45 +++++- 6 files changed, 353 insertions(+), 49 deletions(-) diff --git a/.eslintrc.json b/.eslintrc.json index 7e6d5b4b..52655919 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -13,7 +13,7 @@ "plugin:mocha/recommended", "prettier" ], - "plugins": ["prettier", "promise", "import", "simple-import-sort", "mocha", "@typescript-eslint"], + "plugins": ["prettier", "promise", "import", "simple-import-sort", "mocha", "@typescript-eslint","eslint-plugin-tsdoc"], "parser": "@typescript-eslint/parser", "parserOptions": { "sourceType": "module", @@ -67,6 +67,7 @@ "props": false } ], + "tsdoc/syntax": "warn", "prettier/prettier": [ "error", { diff --git a/.vscode/settings.json b/.vscode/settings.json index 9d5f76d1..f302abf3 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -20,7 +20,7 @@ "plugin:mocha/recommended", "prettier" ], - "plugins": ["prettier", "promise", "import", "simple-import-sort", "mocha", "@typescript-eslint"], + "plugins": ["prettier", "promise", "import", "simple-import-sort", "mocha", "@typescript-eslint", "eslint-plugin-tsdoc"], "parser": "@typescript-eslint/parser", "parserOptions": { "sourceType": "module", @@ -87,6 +87,7 @@ "props": false } ], + "tsdoc/syntax": "warn", "prettier/prettier": [ "error", { diff --git a/package.json b/package.json index b1d291b0..4b3a9799 100644 --- a/package.json +++ b/package.json @@ -46,6 +46,7 @@ "eslint-plugin-prettier": "^3.4.0", "eslint-plugin-promise": "^5.1.0", "eslint-plugin-simple-import-sort": "^7.0.0", + "eslint-plugin-tsdoc": "^0.2.14", "eslint-webpack-plugin": "^2.5.4", "husky": "^7.0.1", "jsdom": "^16.6.0", diff --git a/packages/core/src/constants.ts b/packages/core/src/constants.ts index 01e18db4..3c56cfe8 100644 --- a/packages/core/src/constants.ts +++ b/packages/core/src/constants.ts @@ -68,17 +68,111 @@ export const OPENLOGIN_NETWORK = { export type OPENLOGIN_NETWORK_TYPE = typeof OPENLOGIN_NETWORK[keyof typeof OPENLOGIN_NETWORK]; export 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; + + /** + * 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; + + /** + * 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; }; @@ -100,57 +194,80 @@ export const LOGIN_PROVIDER = { WEBAUTHN: "webauthn", } as const; +/** + * {@label loginProviderType} + */ export type LOGIN_PROVIDER_TYPE = typeof LOGIN_PROVIDER[keyof typeof LOGIN_PROVIDER]; // autocomplete workaround https://github.com/microsoft/TypeScript/issues/29729 export type CUSTOM_LOGIN_PROVIDER_TYPE = string & { toString?: (radix?: number) => string }; export type LoginParams = BaseRedirectParams & { - /** - * loginProvider sets the oauth login method to be used. - * You can use any of the valid loginProvider from this list. - * - * If this param is not passed then it will show all the available - * login methods to user in a modal. - * - */ - loginProvider: LOGIN_PROVIDER_TYPE | CUSTOM_LOGIN_PROVIDER_TYPE; - - /** - * Setting fastLogin to `true` will force user to login with webauthn if - * webauthn is available on device. - * - * Defaults to false - * @default false - * - * @remarks - * Use this option with caution only when you are sure about that user has enabled - * webauthn while registeration, else don't use this option. Openlogin will itself - * take care of detecting and handling webauthn. In general you may not need to use - * this option. - */ - fastLogin?: boolean; - - /** - * Setting relogin to `true` will force user to relogin when login - * method is called even if user is already logged in. By default login - * method call skips login process if user is already logged in. - * - * * Defaults to false - * @default false - */ - relogin?: boolean; - - /** - * Skips TKey onboarding for new users, whereas old users will be - * presented with an option to skip tKey in UI if this option is enabled. - * - * Defaults to false - * @default false - */ - skipTKey?: boolean; - getWalletKey?: boolean; - extraLoginOptions?: ExtraLoginOptions; + /** + * loginProvider sets the oauth login method to be used. + * You can use any of the valid loginProvider from the supported list. + * + * If this param is not passed then it will show all the available + * login methods to user in a modal. + * + */ + loginProvider?: LOGIN_PROVIDER_TYPE | CUSTOM_LOGIN_PROVIDER_TYPE; + + /** + * Setting fastLogin to `true` will force user to login with webauthn if + * webauthn is available on device. + * + * Defaults to false + * @defaultValue false + * @experimental + * + * @remarks + * Use this option with caution only when you are sure about that user has + * enabled webauthn while registeration, else don't use this option. + * Openlogin will itself take care of detecting and handling webauthn. + * In general you may not need to use this option. + */ + fastLogin?: boolean; + + /** + * Setting relogin to `true` will force user to relogin when login + * method is called even if user is already logged in. By default login + * method call skips login process if user is already logged in. + * + * * Defaults to false + * @defaultValue false + */ + relogin?: boolean; + + /** + * setting skipTKey to `true` will skip TKey onboarding for new users, + * whereas old users will be presented with an option to skip tKey in UI + * if this option is enabled. + * + * Defaults to false + * @defaultValue false + */ + skipTKey?: boolean; + + /** + * This option is for internal use only in torus wallet and has not effect + * on user's login on other dapps. + * + * Defaults to false + * @defaultValue false + * @internal + */ + getWalletKey?: boolean; + + /** + * extraLoginOptions can be used to pass standard oauth login options to + * loginProvider. + * + * For ex: you will have to pass `login_hint` as user's email and `domain` + * as your app domain in `extraLoginOptions` while using `email_passwordless` + * loginProvider + */ + extraLoginOptions?: ExtraLoginOptions; }; export type OpenloginUserInfo = { diff --git a/packages/core/types/src/constants.d.ts b/packages/core/types/src/constants.d.ts index dc9344e5..b870147a 100644 --- a/packages/core/types/src/constants.d.ts +++ b/packages/core/types/src/constants.d.ts @@ -52,17 +52,101 @@ export declare const OPENLOGIN_NETWORK: { }; export declare type OPENLOGIN_NETWORK_TYPE = typeof OPENLOGIN_NETWORK[keyof typeof OPENLOGIN_NETWORK]; export declare 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; + /** + * 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; + /** + * 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; }; export declare const LOGIN_PROVIDER: { @@ -82,16 +166,73 @@ export declare const LOGIN_PROVIDER: { readonly EMAIL_PASSWORDLESS: "email_passwordless"; readonly WEBAUTHN: "webauthn"; }; +/** + * {@label loginProviderType} + */ export declare type LOGIN_PROVIDER_TYPE = typeof LOGIN_PROVIDER[keyof typeof LOGIN_PROVIDER]; export declare type CUSTOM_LOGIN_PROVIDER_TYPE = string & { toString?: (radix?: number) => string; }; export declare type LoginParams = BaseRedirectParams & { - loginProvider: LOGIN_PROVIDER_TYPE | CUSTOM_LOGIN_PROVIDER_TYPE; + /** + * loginProvider sets the oauth login method to be used. + * You can use any of the valid loginProvider from the supported list. + * + * If this param is not passed then it will show all the available + * login methods to user in a modal. + * + */ + loginProvider?: LOGIN_PROVIDER_TYPE | CUSTOM_LOGIN_PROVIDER_TYPE; + /** + * Setting fastLogin to `true` will force user to login with webauthn if + * webauthn is available on device. + * + * Defaults to false + * @defaultValue false + * @experimental + * + * @remarks + * Use this option with caution only when you are sure about that user has + * enabled webauthn while registeration, else don't use this option. + * Openlogin will itself take care of detecting and handling webauthn. + * In general you may not need to use this option. + */ fastLogin?: boolean; + /** + * Setting relogin to `true` will force user to relogin when login + * method is called even if user is already logged in. By default login + * method call skips login process if user is already logged in. + * + * * Defaults to false + * @defaultValue false + */ relogin?: boolean; + /** + * setting skipTKey to `true` will skip TKey onboarding for new users, + * whereas old users will be presented with an option to skip tKey in UI + * if this option is enabled. + * + * Defaults to false + * @defaultValue false + */ skipTKey?: boolean; + /** + * This option is for internal use only in torus wallet and has not effect + * on user's login on other dapps. + * + * Defaults to false + * @defaultValue false + * @internal + */ getWalletKey?: boolean; + /** + * extraLoginOptions can be used to pass standard oauth login options to + * loginProvider. + * + * For ex: you will have to pass `login_hint` as user's email and `domain` + * as your app domain in `extraLoginOptions` while using `email_passwordless` + * loginProvider + */ extraLoginOptions?: ExtraLoginOptions; }; export declare type OpenloginUserInfo = { diff --git a/yarn.lock b/yarn.lock index a27008f9..1dc8308b 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1811,6 +1811,21 @@ npmlog "^4.1.2" write-file-atomic "^3.0.3" +"@microsoft/tsdoc-config@0.15.2": + version "0.15.2" + resolved "https://registry.yarnpkg.com/@microsoft/tsdoc-config/-/tsdoc-config-0.15.2.tgz#eb353c93f3b62ab74bdc9ab6f4a82bcf80140f14" + integrity sha512-mK19b2wJHSdNf8znXSMYVShAHktVr/ib0Ck2FA3lsVBSEhSI/TfXT7DJQkAYgcztTuwazGcg58ZjYdk0hTCVrA== + dependencies: + "@microsoft/tsdoc" "0.13.2" + ajv "~6.12.6" + jju "~1.4.0" + resolve "~1.19.0" + +"@microsoft/tsdoc@0.13.2": + version "0.13.2" + resolved "https://registry.yarnpkg.com/@microsoft/tsdoc/-/tsdoc-0.13.2.tgz#3b0efb6d3903bd49edb073696f60e90df08efb26" + integrity sha512-WrHvO8PDL8wd8T2+zBGKrMwVL5IyzR3ryWUsl0PXgEV0QHup4mTLi0QcATefGI6Gx9Anu7vthPyyyLpY0EpiQg== + "@nicolo-ribaudo/chokidar-2@2.1.8-no-fsevents.2": version "2.1.8-no-fsevents.2" resolved "https://registry.yarnpkg.com/@nicolo-ribaudo/chokidar-2/-/chokidar-2-2.1.8-no-fsevents.2.tgz#e324c0a247a5567192dd7180647709d7e2faf94b" @@ -2491,7 +2506,7 @@ ajv@^4.9.2: co "^4.6.0" json-stable-stringify "^1.0.1" -ajv@^6.1.0, ajv@^6.10.0, ajv@^6.10.2, ajv@^6.12.3, ajv@^6.12.4, ajv@^6.12.5: +ajv@^6.1.0, ajv@^6.10.0, ajv@^6.10.2, ajv@^6.12.3, ajv@^6.12.4, ajv@^6.12.5, ajv@~6.12.6: version "6.12.6" resolved "https://registry.yarnpkg.com/ajv/-/ajv-6.12.6.tgz#baf5a62e802b07d977034586f8c3baf5adf26df4" integrity sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g== @@ -4239,6 +4254,14 @@ eslint-plugin-simple-import-sort@^7.0.0: resolved "https://registry.yarnpkg.com/eslint-plugin-simple-import-sort/-/eslint-plugin-simple-import-sort-7.0.0.tgz#a1dad262f46d2184a90095a60c66fef74727f0f8" integrity sha512-U3vEDB5zhYPNfxT5TYR7u01dboFZp+HNpnGhkDB2g/2E4wZ/g1Q9Ton8UwCLfRV9yAKyYqDh62oHOamvkFxsvw== +eslint-plugin-tsdoc@^0.2.14: + version "0.2.14" + resolved "https://registry.yarnpkg.com/eslint-plugin-tsdoc/-/eslint-plugin-tsdoc-0.2.14.tgz#e32e7c1df8af7b3009c252590bec07a1030afbf2" + integrity sha512-fJ3fnZRsdIoBZgzkQjv8vAj6NeeOoFkTfgosj6mKsFjX70QV256sA/wq+y/R2+OL4L8E79VVaVWrPeZnKNe8Ng== + dependencies: + "@microsoft/tsdoc" "0.13.2" + "@microsoft/tsdoc-config" "0.15.2" + eslint-scope@^4.0.3: version "4.0.3" resolved "https://registry.yarnpkg.com/eslint-scope/-/eslint-scope-4.0.3.tgz#ca03833310f6889a3264781aa82e63eb9cfe7848" @@ -5377,6 +5400,13 @@ is-ci@^2.0.0: dependencies: ci-info "^2.0.0" +is-core-module@^2.1.0: + version "2.5.0" + resolved "https://registry.yarnpkg.com/is-core-module/-/is-core-module-2.5.0.tgz#f754843617c70bfd29b7bd87327400cda5c18491" + integrity sha512-TXCMSDsEHMEEZ6eCA8rwRDbLu55MRGmrctljsBX/2v1d9/GzqHOxW5c5oPSgrUt2vBFXebu9rGqckXGPWOlYpg== + dependencies: + has "^1.0.3" + is-core-module@^2.2.0, is-core-module@^2.4.0: version "2.4.0" resolved "https://registry.yarnpkg.com/is-core-module/-/is-core-module-2.4.0.tgz#8e9fc8e15027b011418026e98f0e6f4d86305cc1" @@ -5643,6 +5673,11 @@ jest-worker@^26.6.2: merge-stream "^2.0.0" supports-color "^7.0.0" +jju@~1.4.0: + version "1.4.0" + resolved "https://registry.yarnpkg.com/jju/-/jju-1.4.0.tgz#a3abe2718af241a2b2904f84a625970f389ae32a" + integrity sha1-o6vicYryQaKykE+EpiWXDzia4yo= + js-message@1.0.7: version "1.0.7" resolved "https://registry.yarnpkg.com/js-message/-/js-message-1.0.7.tgz#fbddd053c7a47021871bb8b2c95397cc17c20e47" @@ -7943,6 +7978,14 @@ resolve@^1.1.6, resolve@^1.10.0, resolve@^1.10.1, resolve@^1.13.1, resolve@^1.14 is-core-module "^2.2.0" path-parse "^1.0.6" +resolve@~1.19.0: + version "1.19.0" + resolved "https://registry.yarnpkg.com/resolve/-/resolve-1.19.0.tgz#1af5bf630409734a067cae29318aac7fa29a267c" + integrity sha512-rArEXAgsBG4UgRGcynxWIWKFvh/XZCcS8UJdHhwy91zwAvCZIbcs+vAbflgBnNjYMs/i/i+/Ux6IZhML1yPvxg== + dependencies: + is-core-module "^2.1.0" + path-parse "^1.0.6" + restore-cursor@^3.1.0: version "3.1.0" resolved "https://registry.yarnpkg.com/restore-cursor/-/restore-cursor-3.1.0.tgz#39f67c54b3a7a58cea5236d95cf0034239631f7e"