@descope/react-sdk 0.0.52-alpha.0 → 0.0.52-alpha.10

package/README.md

@@ -1,29 +1,56 @@
 # @descope/react-sdk
+
 This library lets you consume your login pages created by Descope console-app in your application
 Under the hood, it uses [web-js-sdk](https://github.com/descope/web-js-sdk)
 
 ## Usage
+
 ### Install the package
+
 ```bash
 npm install @descope/react-sdk
 ```
 
 ### Render it in your application
+
 #### Wrap your app with Auth Provider
+
 ```js
-import { AuthProvider } from '@descope/react-sdk'
+import { AuthProvider } from '@descope/react-sdk';
 
 const AppRoot = () => {
+	return (
+		<AuthProvider projectId="myProjectId">
+			<App />
+		</AuthProvider>
+	);
+};
+```
+
+#### Use Descope to render specific flow
+
+You can use **default flows** or **provide flow id** directly to the Descope component
+
+##### 1. Default flows
+
+```js
+import { SignInFlow } from '@descope/react-sdk'
+// you can choose flow to run from the following
+// import { SignUpFlow } from '@descope/react-sdk'
+// import { SignUpOrInFlow } from '@descope/react-sdk'
+
+const App = () => {
     return (
-        <AuthProvider 
-            projectId="myProjectId" 
-        >
-         <App />
-        </AuthProvider>
+        {...}
+        <SignInFlow
+            onSuccess={(e) => console.log('Logged in!')}
+            onError={(e) => console.log('Could not logged in!')}
+        />
     )
 }
 ```
-#### Use Descope to render specific flow
+
+##### 2. Provide flow id
 
 ```js
 import { Descope } from '@descope/react-sdk'
@@ -31,14 +58,103 @@ import { Descope } from '@descope/react-sdk'
 const App = () => {
     return (
         {...}
-        <Descope 
-            flowId="myFlowId" 
+        <Descope
+            flowId="myFlowId"
             onSuccess={(e) => console.log('Logged in!')}
             onError={(e) => console.log('Could not logged in!')}
-        >
+        />
+    )
+}
+```
+
+#### Use the `useAuth` hook in your components in order to access authentication state and utilities
+
+This can be helpful to implement application-specific logic. Examples:
+
+- Render different components if current session is authenticated
+- Render user's content
+- Logout button
+
+```js
+import { useAuth } from '@descope/react-sdk'
+
+const App = () => {
+    // NOTE - `useAuth` should be used inside `AuthProvider` context,
+    // and will throw an exception if this requirement is not met
+    const { authenticated, user, logout } = useAuth()
+    return (
+        {...}
+        {
+            // render different components if current session is authenticated
+            authenticated && <MyPrivateComponent />
+        }
+        {
+            // render user's content
+            authenticated && <div>Hello ${user.name}</div>
+        }
+        {
+            // logout button
+            authenticated && <button onClick={logout}>Logout</div>
+        }
     )
 }
 ```
 
-TODO:
-- decide about the callbacks event data & structure
+#### Session token server validation (pass session token to server API)
+
+When developing a full-stack application, it is common to have private server API which requires a valid session token:
+
+![session-token-validation-diagram](https://docs.descope.com/static/SessionValidation-cf7b2d5d26594f96421d894273a713d8.png)
+
+Note: Descope also provides server-side SDKs in various languages (NodeJS, Go, Python, etc). Descope's server SDKs have out-of-the-box session validation API that supports the options described bellow. To read more about session validation, Read [this section](https://docs.descope.com/guides/gettingstarted/#session-validation) in Descope documentation.
+
+The mechanism to pass session token depends on the Descope project's "Token response method" configuration.
+
+##### 1. Manage in cookies
+
+- Descope sets session token as cookie, which automatically sent each server api request. This option is more secure and is the recommended method for managing tokens, but for this option to work well with the browser - you must also configure a CNAME record for the custom domain listed, which will give a unified log in experience and securely restrict access to the session tokens that are stored in the cookies.
+
+When this option is configured, the browser will automatically add the session token cookie to the server in every request.
+
+##### 2. Manage in response body
+
+- Descope API returns session token in body. In this option, The React application should pass session cookie (`const { sessionToken } = useAuth()`) as Authorization header. This option never requires a custom domain, and is recommended for testing or while working in a sandbox environment.
+
+An example for using session token,
+
+```js
+import { useAuth } from '@descope/react-sdk'
+import { useCallback } from 'react'
+
+const App = () => {
+    const { sessionToken } = useAuth()
+
+    const onClick = useCallback(() => {
+        fetch('https://localhost:3002/api/some-path' {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${sessionToken}` }
+        })
+    },[sessionToken])
+    return (
+        {...}
+        {
+            // button that triggers an API that may use session token
+            <button onClick={onClick}>Click Me</div>
+        }
+    )
+}
+```
+
+## Contributing to this project
+
+In order to use this repo locally
+
+- Clone this repository
+- Navigate to repository directory
+- Run `npm i`
+- Edit `src/app/index.tsx` in the following way
+  - Set `projectId` prop - replace `<project-id>` with your project id
+  - Set `flowId` prop - Replace `<flow-id>` (for example - `sign-up-or-in`)
+  - Optional - set a different `baseUrl` (for example - `http://localhost:8000`)
+- Run `npm run start`
+- Go to `http://localhost:3000/` and start flow

package/dist/index.d.ts

@@ -1,5 +1,14 @@
-import React, { DOMAttributes, FC } from 'react';
+/// <reference types="react" />
+import React, { FC, DOMAttributes } from 'react';
 import DescopeWc from '@descope/web-component';
+import createSdk from '@descope/web-js-sdk';
+
+interface IAuthProviderProps {
+    projectId: string;
+    baseUrl?: string;
+    children?: JSX.Element;
+}
+declare const AuthProvider: FC<IAuthProviderProps>;
 
 declare global {
     namespace JSX {
@@ -8,6 +17,7 @@ declare global {
         }
     }
 }
+declare type Sdk = ReturnType<typeof createSdk>;
 declare type CustomEvents<K extends string> = {
     [key in K]: (event: CustomEvent) => void;
 };
@@ -39,26 +49,26 @@ interface User {
     verifiedPhone?: boolean;
     tenants?: string[];
 }
-
-declare const useAuth: () => {
-    projectId: string;
-    baseUrl: string;
+interface IAuth {
     authenticated: boolean;
-    user: User;
-};
-
-interface PropsType {
+    user?: User;
+    sessionToken?: string;
+    logout: Sdk['logout'];
+    me: Sdk['me'];
+}
+interface DescopeProps {
     flowId: string;
     onSuccess?: DescopeCustomElement['onsuccess'];
     onError?: DescopeCustomElement['onerror'];
 }
-declare const Descope: React.ForwardRefExoticComponent<PropsType & React.RefAttributes<HTMLElement>>;
+declare type DefaultFlowProps = Omit<DescopeProps, 'flowId'>;
 
-interface IAuthProviderProps {
-    projectId: string;
-    baseUrl?: string;
-    children?: JSX.Element;
-}
-declare const AuthProvider: FC<IAuthProviderProps>;
+declare const SignInFlow: (props: DefaultFlowProps) => JSX.Element;
+declare const SignUpFlow: (props: DefaultFlowProps) => JSX.Element;
+declare const SignUpOrInFlow: (props: DefaultFlowProps) => JSX.Element;
+
+declare const Descope: React.ForwardRefExoticComponent<DescopeProps & React.RefAttributes<HTMLElement>>;
+
+declare const useAuth: () => IAuth;
 
-export { AuthProvider, Descope, useAuth };
+export { AuthProvider, Descope, SignInFlow, SignUpFlow, SignUpOrInFlow, useAuth };

package/dist/index.js

@@ -1 +1 @@
-import e,{useMemo as r,useRef as t,useImperativeHandle as o,useCallback as s,useEffect as n,useState as c}from"react";import"@descope/web-component";const d=e.createContext(void 0),u=()=>{const t=e.useContext(d);if(!t)throw Error("You can only use useAuth in the context of <AuthProvider />");const{authenticated:o,user:s,projectId:n,baseUrl:c}=t;return r((()=>({projectId:n,baseUrl:c,authenticated:o,user:s})),[n,c,o,s])},a=e.forwardRef((({flowId:r,onSuccess:c,onError:u},a)=>{const i=t();o(a,(()=>i.current));const{projectId:l,baseUrl:p,setAuthenticated:v,setUser:h}=e.useContext(d),f=s((e=>{h(e?.detail?.user),v(!0),c&&c(e)}),[h,v,c]);return n((()=>{const e=i.current;return e?.addEventListener("success",f),u&&e?.addEventListener("error",u),()=>{u&&e?.removeEventListener("error",u),e?.removeEventListener("success",f)}}),[i,u,f]),e.createElement("descope-wc",{"project-id":l,"flow-id":r,"base-url":p,ref:i})}));a.defaultProps={onError:void 0,onSuccess:void 0};const i=({projectId:t,baseUrl:o,children:s})=>{const[n,u]=c(!1),[a,i]=c({}),l=r((()=>({user:a,authenticated:n,projectId:t,baseUrl:o,setUser:i,setAuthenticated:u})),[n,a,t,o]);return e.createElement(d.Provider,{value:l},s)};i.defaultProps={baseUrl:"",children:void 0};export{i as AuthProvider,a as Descope,u as useAuth};
+import e from"@descope/web-js-sdk";import o,{useState as r,useMemo as t,useEffect as s,useRef as n,useImperativeHandle as c,useCallback as i}from"react";import"@descope/web-component";const u=o.createContext(void 0),d=({projectId:n,baseUrl:c,children:i})=>{const[d,a]=r({}),[l,p]=r(""),f=t((()=>{if(n)return e({projectId:n,baseUrl:c,hooks:{beforeRequest:e=>{const o=e;return o.headers={...o.headers,"x-descope-sdk-name":"react","x-descope-sdk-version":"0.0.52-alpha.10"},o}}})}),[n,c]);s((()=>{if(!f)return;const e=f.onSessionTokenChange(p),o=f.onUserChange(a);return()=>{e?.(),o?.()}}),[f]);const m=t((()=>({sdk:f,projectId:n,baseUrl:c,user:d,sessionToken:l,setUser:a,setSessionToken:p})),[l,d,n,c]);return o.createElement(u.Provider,{value:m},i)};d.defaultProps={baseUrl:"",children:void 0};const a=o.forwardRef((({flowId:e,onSuccess:r,onError:t},d)=>{const a=n();c(d,(()=>a.current));const{projectId:l,baseUrl:p,setUser:f,setSessionToken:m}=o.useContext(u),h=i((e=>{f(e.detail?.user);const o=e.detail?.sessionJwt;m(o),r&&r(e)}),[f,m,r]);return s((()=>{const e=a.current;return e?.addEventListener("success",h),t&&e?.addEventListener("error",t),()=>{t&&e?.removeEventListener("error",t),e?.removeEventListener("success",h)}}),[a,t,h]),o.createElement("descope-wc",{"project-id":l,"flow-id":e,"base-url":p,ref:a})}));a.defaultProps={onError:void 0,onSuccess:void 0};const l=e=>o.createElement(a,{...e,flowId:"sign-in"}),p=e=>o.createElement(a,{...e,flowId:"sign-up"}),f=e=>o.createElement(a,{...e,flowId:"sign-up-or-in"}),m=()=>{const e=o.useContext(u);if(!e)throw Error("You can only use 'useAuth' in the context of <AuthProvider />");const{user:r,sessionToken:s,sdk:n}=e,c=i(((...e)=>{if(!n)throw Error("You can only use 'logout' after sdk initialization. Make sure to supply 'projectId' to <AuthProvider /> component");return n.logout(...e)}),[n]),d=i(((...e)=>{if(!n)throw Error("You can only use 'me' after sdk initialization. Make sure to supply 'projectId' to <AuthProvider /> component");return n.me(...e)}),[n]);return t((()=>({authenticated:!!s,user:r,sessionToken:s,logout:c,me:d})),[r,s,n])};export{d as AuthProvider,a as Descope,l as SignInFlow,p as SignUpFlow,f as SignUpOrInFlow,m as useAuth};

package/package.json

@@ -1,80 +1,93 @@
 {
-  "name": "@descope/react-sdk",
-  "version": "0.0.52-alpha.0",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "description": "Descope React SDK",
-  "license": "ISC",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/descope/react-sdk.git"
-  },
-  "files": [
-    "dist"
-  ],
-  "dependencies": {
-    "@descope/web-component": "^0.0.26-alpha.1"
-  },
-  "devDependencies": {
-    "@babel/core": "7.18.9",
-    "@babel/preset-env": "7.18.9",
-    "@babel/preset-react": "7.18.6",
-    "@babel/preset-typescript": "7.18.6",
-    "@open-wc/rollup-plugin-html": "^1.2.5",
-    "@rollup/plugin-commonjs": "^21.0.1",
-    "@rollup/plugin-node-resolve": "^13.1.1",
-    "@rollup/plugin-replace": "^3.0.0",
-    "@rollup/plugin-typescript": "^8.3.0",
-    "@testing-library/jest-dom": "5.16.5",
-    "@testing-library/react": "13.3.0",
-    "@testing-library/user-event": "14.4.3",
-    "@types/jest": "^27.0.2",
-    "@types/react": "18.0.17",
-    "@types/react-dom": "18.0.5",
-    "babel-jest": "27.5.1",
-    "eslint": "8.20.0",
-    "eslint-config-airbnb": "19.0.4",
-    "eslint-config-airbnb-typescript": "17.0.0",
-    "eslint-config-prettier": "8.5.0",
-    "eslint-config-standard": "17.0.0",
-    "eslint-import-resolver-typescript": "2.7.1",
-    "eslint-plugin-import": "2.26.0",
-    "eslint-plugin-jest": "26.7.0",
-    "eslint-plugin-jest-dom": "4.0.2",
-    "eslint-plugin-jest-formatting": "3.1.0",
-    "eslint-plugin-jsx-a11y": "6.6.1",
-    "eslint-plugin-n": "15.2.4",
-    "eslint-plugin-no-only-tests": "2.6.0",
-    "eslint-plugin-prefer-arrow": "1.2.3",
-    "eslint-plugin-prettier": "4.2.1",
-    "eslint-plugin-promise": "6.0.0",
-    "eslint-plugin-react": "7.30.1",
-    "eslint-plugin-react-hooks": "4.6.0",
-    "eslint-plugin-testing-library": "5.6.0",
-    "jest": "^27.3.1",
-    "react": "18.2.0",
-    "react-dom": "18.2.0",
-    "rollup": "^2.62.0",
-    "rollup-plugin-auto-external": "^2.0.0",
-    "rollup-plugin-browsersync": "^1.3.3",
-    "rollup-plugin-delete": "^2.0.0",
-    "rollup-plugin-dts": "^4.2.2",
-    "rollup-plugin-livereload": "^2.0.5",
-    "rollup-plugin-serve": "^1.1.0",
-    "rollup-plugin-terser": "^7.0.2",
-    "ts-jest": "^27.0.7",
-    "ts-node": "10.9.1",
-    "typescript": "^4.5.3"
-  },
-  "peerDependencies": {
-    "@types/react": ">=16",
-    "react": ">=16"
-  },
-  "scripts": {
-    "start": "npm run build && rollup -c rollup.config.app.js -w",
-    "build": "rollup -c",
-    "test": "jest",
-    "lint": "eslint ./src",
-    "prepublishOnly": "npm run build"
-  }
+	"name": "@descope/react-sdk",
+	"version": "0.0.52-alpha.10",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"description": "Descope React SDK",
+	"license": "ISC",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/descope/react-sdk.git"
+	},
+	"files": [
+		"dist"
+	],
+	"dependencies": {
+		"@descope/web-component": "0.1.0-alpha.1"
+	},
+	"devDependencies": {
+		"@babel/core": "7.19.6",
+		"@babel/preset-env": "7.19.4",
+		"@babel/preset-react": "7.18.6",
+		"@babel/preset-typescript": "7.18.6",
+		"@open-wc/rollup-plugin-html": "^1.2.5",
+		"@rollup/plugin-commonjs": "^21.0.1",
+		"@rollup/plugin-node-resolve": "^13.1.1",
+		"@rollup/plugin-replace": "^3.0.0",
+		"@rollup/plugin-typescript": "^8.3.0",
+		"@testing-library/jest-dom": "5.16.5",
+		"@testing-library/react": "13.4.0",
+		"@testing-library/user-event": "14.4.3",
+		"@types/jest": "^27.0.2",
+		"@types/react": "18.0.17",
+		"@types/react-dom": "18.0.7",
+		"babel-jest": "27.5.1",
+		"eslint": "8.20.0",
+		"eslint-config-airbnb": "19.0.4",
+		"eslint-config-airbnb-typescript": "17.0.0",
+		"eslint-config-prettier": "8.5.0",
+		"eslint-config-standard": "17.0.0",
+		"eslint-import-resolver-typescript": "2.7.1",
+		"eslint-plugin-import": "2.26.0",
+		"eslint-plugin-jest": "26.9.0",
+		"eslint-plugin-jest-dom": "4.0.2",
+		"eslint-plugin-jest-formatting": "3.1.0",
+		"eslint-plugin-jsx-a11y": "6.6.1",
+		"eslint-plugin-n": "15.3.0",
+		"eslint-plugin-no-only-tests": "2.6.0",
+		"eslint-plugin-prefer-arrow": "1.2.3",
+		"eslint-plugin-prettier": "4.2.1",
+		"eslint-plugin-promise": "6.1.1",
+		"eslint-plugin-react": "7.31.10",
+		"eslint-plugin-react-hooks": "4.6.0",
+		"eslint-plugin-testing-library": "5.6.0",
+		"husky": "^8.0.1",
+		"jest": "^27.3.1",
+		"lint-staged": "^13.0.3",
+		"pretty-quick": "^3.1.3",
+		"react": "18.2.0",
+		"react-dom": "18.2.0",
+		"rollup": "^2.62.0",
+		"rollup-plugin-auto-external": "^2.0.0",
+		"rollup-plugin-browsersync": "^1.3.3",
+		"rollup-plugin-define": "^1.0.1",
+		"rollup-plugin-delete": "^2.0.0",
+		"rollup-plugin-dts": "^4.2.2",
+		"rollup-plugin-livereload": "^2.0.5",
+		"rollup-plugin-serve": "^1.1.0",
+		"rollup-plugin-terser": "^7.0.2",
+		"ts-jest": "^27.0.7",
+		"ts-node": "10.9.1",
+		"typescript": "^4.5.3"
+	},
+	"peerDependencies": {
+		"@types/react": ">=16",
+		"react": ">=16"
+	},
+	"scripts": {
+		"start": "npm run build && rollup -c rollup.config.app.js -w",
+		"build": "rollup -c",
+		"prepare": "husky install",
+		"test": "jest",
+		"lint": "eslint '+(src|test|testUtils)/**/*.ts' --fix",
+		"format": "prettier . -w --ignore-path .gitignore",
+		"format-check": "prettier . --check --ignore-path .gitignore",
+		"format-lint": "pretty-quick --staged --ignore-path .gitignore && lint-staged",
+		"prepublishOnly": "npm run build"
+	},
+	"lint-staged": {
+		"+(src|test|examples)/**/*.{js,ts,jsx,tsx}": [
+			"npm run lint"
+		]
+	}
 }