@descope/vue-sdk 0.0.0-next-fe60cdb6-20230614 → 0.0.0-next-46dc962a-20230629

package/README.md

@@ -1,6 +1,7 @@
-# Descope SDK for Vue
+# Descope Vue SDK
 
-The Descope SDK for Vue provides convenient access to the Descope for an application written on top of Vue. You can read more on the [Descope Website](https://descope.com).
+The Descope Vue SDK provides convenient access to the Descope for an application written on top of Vue.  
+You can read more on the [Descope Website](https://descope.com).
 
 ## Requirements
 
@@ -17,9 +18,7 @@ npm i --save @descope/vue-sdk
 
 ## Usage
 
-### Render it in your application
-
-#### Add Descope plugin to your application
+### Add Descope plugin to your application
 
 ```js
 import { createApp } from 'vue';
@@ -37,7 +36,7 @@ app.use(descope, {
 app.mount('#app');
 ```
 
-#### Use Descope to render specific flow
+### Use Descope to render specific flow
 
 ```js
 <template>
@@ -61,7 +60,7 @@ const handleSuccess = (e) => {
 </script>
 ```
 
-#### Use the `useDescope`, `useSession` and `useUser` functions in your components in order to get authentication state, user details and utilities
+### Use the `useDescope`, `useSession` and `useUser` functions in your components in order to get authentication state, user details and utilities
 
 This can be helpful to implement application-specific logic. Examples:
 
@@ -94,7 +93,100 @@ Note: `useSession` triggers a single request to the Descope backend to attempt t
 
 **For more SDK usage examples refer to [docs](https://docs.descope.com/build/guides/client_sdks/)**
 
-#### Refresh token lifecycle
+### 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/build/guides/gettingstarted/#session-validation) in Descope documentation.
+
+There are 2 ways to achieve that:
+
+1. Using `getSessionToken` to get the token, and pass it on the `Authorization` Header (Recommended)
+2. Passing `sessionTokenViaCookie` boolean option when initializing the plugin (Use cautiously, session token may grow, especially in cases of using authorization, or adding custom claim)
+
+#### 1. Using `getSessionToken` to get the token
+
+An example for api function, and passing the token on the `Authorization` header:
+
+```js
+import { getSessionToken } from '@descope/vue-sdk';
+
+// fetch data using back
+// Note: Descope backend SDKs support extracting session token from the Authorization header
+export const fetchData = async () => {
+	const sessionToken = getSessionToken();
+	const res = await fetch('/path/to/server/api', {
+		headers: {
+			Authorization: `Bearer ${sessionToken}`
+		}
+	});
+	// ... use res
+};
+```
+
+#### 2. Passing `sessionTokenViaCookie` option when initializing the plugin
+
+When doing so, Descope SDK will automatically store session token on the `DS` cookie.
+
+Note: Use this option if session token will stay small (less than 1k). Session token can grow, especially in cases of using authorization, or adding custom claims
+
+Example:
+
+```js
+import { createApp } from 'vue';
+import App from './components/App.vue';
+import descope from '@descope/vue-sdk';
+
+const app = createApp(App);
+
+app.use(descope, {
+	projectId: 'project-id',
+	sessionTokenViaCookie: true
+});
+```
+
+Now, whenever you call `fetch`, the cookie will automatically be sent with the request.  
+Descope backend SDKs also support extracting the token from the `DS` cookie.
+
+### Get the Descope SDK instance
+
+In case you need the SDK instance outside the Vue application, you can use the `getSdk` function
+
+**Make sure to call it only after initializing the descope plugin, this is where the SDK instance is actually created, otherwise you will no instance.**
+
+For example:
+
+```js
+import { createApp } from 'vue';
+import App from './components/App.vue';
+import descope, { getSdk } from '../src';
+
+const app = createApp(App);
+
+app.use(descope, {
+	projectId: 'project-id'
+});
+
+const sdk = getSdk();
+
+sdk?.onSessionTokenChange((newSession) => {
+	// here you can implement custom logic when the session is changing
+});
+```
+
+### Helper Functions
+
+You can also use the following functions to assist with various actions managing your JWT.
+
+`getSessionToken()` - Get current session token.
+`getRefreshToken()` - Get current refresh token.
+`refresh(token = getRefreshToken())` - Force a refresh on current session token using an existing valid refresh token.
+`getJwtRoles(token = getSessionToken(), tenant = '')` - Get current roles from an existing session token. Provide tenant id for specific tenant roles.
+`getJwtPermissions(token = getSessionToken(), tenant = '')` - Fet current permissions from an existing session token. Provide tenant id for specific tenant permissions.
+
+### Refresh token lifecycle
 
 Descope SDK is automatically refreshes the session token when it is about to expire. This is done in the background using the refresh token, without any additional configuration.
 
@@ -103,7 +195,7 @@ you must also configure a custom domain, and set it as the `baseUrl` to the `des
 
 ## Code Example
 
-You can find an example Vue app in the [examples folder](./example).
+You can find an example Vue app in the [example folder](./example).
 
 ### Setup
 
@@ -130,11 +222,10 @@ npm i && npm start
 
 See the following table for customization environment variables for the example app:
 
-| Env Variable | Description | Default value |
-| ------------ | ----------- | ------------- |
-
-| VUE_APP_DESCOPE_FLOW_ID | Which flow ID to use in the login page | **sign-up-or-in** |
-| VUE_APP_DESCOPE_BASE_URL | Custom Descope base URL | None |
+| Env Variable             | Description                            | Default value     |
+| ------------------------ | -------------------------------------- | ----------------- |
+| VUE_APP_DESCOPE_FLOW_ID  | Which flow ID to use in the login page | **sign-up-or-in** |
+| VUE_APP_DESCOPE_BASE_URL | Custom Descope base URL                | None              |
 
 Example for `.env.local` file template:
 

package/dist/index.cjs

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@descope/web-component"),s=require("vue"),o=require("@descope/web-js-sdk");function r(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}var t=r(e),n=r(o);const u=Symbol("$descope"),a={"x-descope-sdk-name":"vue","x-descope-sdk-version":"0.0.0-next-fe60cdb6-20230614"},i=()=>{const e=s.inject(u);if(!e)throw Error("Missing Descope context, make sure you are using the Descope plugin");return e},l=()=>i().sdk;t.default.sdkConfigOverrides={baseHeaders:a};var c={name:"Descope",props:{flowId:{type:String,required:!0},tenant:{type:String},theme:{type:String},debug:{type:Boolean},telemetryKey:{type:String},redirectUrl:{type:String},autoFocus:{type:Boolean}},emits:["success","error"],setup(e,{emit:s}){const{projectId:o,baseUrl:r,sessionTokenViaCookie:t}=i().options,n=l();return{projectId:o,baseUrl:r,sessionTokenViaCookie:t,onSuccess:async e=>{s("success",e),await(n.httpClient.hooks?.afterRequest?.({},new Response(JSON.stringify(e.detail))))},onError:e=>s("error",e)}}};const d=["project-id","base-url","flow-id","^theme","^tenant","^debug","^telemetryKey","redirect-url","auto-focus"];c.render=function(e,o,r,t,n,u){return s.openBlock(),s.createElementBlock("div",null,[s.createElementVNode("descope-wc",{"project-id":t.projectId,"base-url":t.baseUrl,"flow-id":r.flowId,"^theme":r.theme,"^tenant":r.tenant,"^debug":r.debug,"^telemetryKey":r.telemetryKey,"redirect-url":r.redirectUrl,"auto-focus":r.autoFocus,onSuccess:o[0]||(o[0]=(...e)=>t.onSuccess&&t.onSuccess(...e)),onError:o[1]||(o[1]=(...e)=>t.onError&&t.onError(...e))},null,40,d)])},c.__file="src/Descope.vue";const p=s.ref(null);var v={install:function(e,o){const r=n.default({persistTokens:!0,autoRefresh:!0,baseHeaders:a,...o}),t=s.ref(null),i=s.ref(""),l=s.ref(null),c=s.ref(null);r.onSessionTokenChange((e=>{i.value=e})),r.onUserChange((e=>{c.value=e}));const d=async()=>{t.value=!0,await r.refresh(),t.value=!1},v=s.computed((()=>null===t.value)),f=s.computed((()=>null===l.value));p.value=async()=>(!i.value&&v.value&&await d(),!!s.unref(i)),e.provide(u,{session:{fetchSession:d,isLoading:s.readonly(t),session:s.readonly(i),isFetchSessionWasNeverCalled:v},user:{fetchUser:async()=>{l.value=!0,await r.me(),l.value=!1},isLoading:s.readonly(l),user:s.readonly(c),isFetchUserWasNeverCalled:f},sdk:r,options:o})}};exports.Descope=c,exports.default=v,exports.routeGuard=()=>s.unref(p)?.(),exports.useDescope=l,exports.useSession=()=>{const{session:e}=i();return e.isFetchSessionWasNeverCalled.value&&e.fetchSession(),{isLoading:s.computed((()=>e.isLoading.value||e.isFetchSessionWasNeverCalled.value)),sessionToken:e.session,isAuthenticated:s.computed((()=>!!e.session.value))}},exports.useUser=()=>{const{user:e,session:o}=i(),r=()=>{!e.user.value&&o.session.value&&e.fetchUser()};return r(),s.watch(o.session,r),{isLoading:s.computed((()=>e.isLoading.value||e.isFetchUserWasNeverCalled.value)),user:e.user}};
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("@descope/web-component"),s=require("vue"),o=require("@descope/web-js-sdk");function t(e){return e&&"object"==typeof e&&"default"in e?e:{default:e}}var r=t(e),n=t(o);const i=Symbol("$descope"),u={"x-descope-sdk-name":"vue","x-descope-sdk-version":"0.0.0-next-46dc962a-20230629"},a="undefined"!=typeof window,l=()=>{const e=s.inject(i);if(!e)throw Error("Missing Descope context, make sure you are using the Descope plugin");return e},c=()=>l().sdk;r.default.sdkConfigOverrides={baseHeaders:u};var d={name:"Descope",props:{flowId:{type:String,required:!0},tenant:{type:String},theme:{type:String},debug:{type:Boolean},telemetryKey:{type:String},redirectUrl:{type:String},autoFocus:{type:Boolean}},emits:["success","error"],setup(e,{emit:s}){const{projectId:o,baseUrl:t,sessionTokenViaCookie:r}=l().options,n=c();return{projectId:o,baseUrl:t,sessionTokenViaCookie:r,onSuccess:async e=>{s("success",e),await(n.httpClient.hooks?.afterRequest?.({},new Response(JSON.stringify(e.detail))))},onError:e=>s("error",e)}}};const p=["project-id","base-url","flow-id","^theme","^tenant","^debug","^telemetryKey","redirect-url","auto-focus"];d.render=function(e,o,t,r,n,i){return s.openBlock(),s.createElementBlock("div",null,[s.createElementVNode("descope-wc",{"project-id":r.projectId,"base-url":r.baseUrl,"flow-id":t.flowId,"^theme":t.theme,"^tenant":t.tenant,"^debug":t.debug,"^telemetryKey":t.telemetryKey,"redirect-url":t.redirectUrl,"auto-focus":t.autoFocus,onSuccess:o[0]||(o[0]=(...e)=>r.onSuccess&&r.onSuccess(...e)),onError:o[1]||(o[1]=(...e)=>r.onError&&r.onError(...e))},null,40,p)])},d.__file="src/Descope.vue";const f=e=>(...s)=>{let o;try{o=e(...s)}catch(e){console.error(e)}return o};let v;const g=e=>{const s=n.default({...e,persistTokens:a,autoRefresh:a});return v=s,s};v=g({projectId:"temp pid"});const y=()=>a?v?.getSessionToken():(console.warn("Get session token is not supported in SSR"),""),h=f(((e=y(),s)=>v?.getJwtPermissions(e,s))),m=f(((e=y(),s)=>v?.getJwtRoles(e,s))),k=s.ref(null);let S;var w={install:function(e,o){const t=g({...o,persistTokens:!0,autoRefresh:!0,baseHeaders:u});S=t;const r=s.ref(null),n=s.ref(""),a=s.ref(null),l=s.ref(null);t.onSessionTokenChange((e=>{n.value=e})),t.onUserChange((e=>{l.value=e}));const c=async()=>{r.value=!0,await t.refresh(),r.value=!1},d=s.computed((()=>null===r.value)),p=s.computed((()=>null===a.value));k.value=async()=>(!n.value&&d.value&&await c(),!!s.unref(n)),e.provide(i,{session:{fetchSession:c,isLoading:s.readonly(r),session:s.readonly(n),isFetchSessionWasNeverCalled:d},user:{fetchUser:async()=>{a.value=!0,await t.me(),a.value=!1},isLoading:s.readonly(a),user:s.readonly(l),isFetchUserWasNeverCalled:p},sdk:t,options:o})}};exports.Descope=d,exports.default=w,exports.getJwtPermissions=h,exports.getJwtRoles=m,exports.getRefreshToken=()=>a?v?.getRefreshToken():(console.warn("Get refresh token is not supported in SSR"),""),exports.getSdk=()=>S,exports.getSessionToken=y,exports.routeGuard=()=>s.unref(k)?.(),exports.useDescope=c,exports.useSession=()=>{const{session:e}=l();return e.isFetchSessionWasNeverCalled.value&&e.fetchSession(),{isLoading:s.computed((()=>e.isLoading.value||e.isFetchSessionWasNeverCalled.value)),sessionToken:e.session,isAuthenticated:s.computed((()=>!!e.session.value))}},exports.useUser=()=>{const{user:e,session:o}=l(),t=()=>{!e.user.value&&o.session.value&&e.fetchUser()};return t(),s.watch(o.session,t),{isLoading:s.computed((()=>e.isLoading.value||e.isFetchUserWasNeverCalled.value)),user:e.user}};
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/Descope.vue?vue&type=template&id=8a031dec&lang.js"],"sourcesContent":["<template>\n\t<div>\n\t\t<descope-wc\n\t\t\t:project-id=\"projectId\"\n\t\t\t:base-url=\"baseUrl\"\n\t\t\t:flow-id=\"flowId\"\n\t\t\t:theme.attr=\"theme\"\n\t\t\t:tenant.attr=\"tenant\"\n\t\t\t:debug.attr=\"debug\"\n\t\t\t:telemetryKey.attr=\"telemetryKey\"\n\t\t\t:redirect-url=\"redirectUrl\"\n\t\t\t:auto-focus=\"autoFocus\"\n\t\t\t@success=\"onSuccess\"\n\t\t\t@error=\"onError\"\n\t\t/>\n\t</div>\n</template>\n\n<script lang=\"ts\">\nimport DescopeWc from '@descope/web-component';\nimport { useOptions, useDescope } from './hooks';\nimport { baseHeaders } from './constants';\nimport { RequestConfig } from '@descope/core-js-sdk';\nimport { SetupContext } from 'vue';\n\nDescopeWc.sdkConfigOverrides = { baseHeaders };\n\nexport default {\n\t// eslint-disable-next-line vue/multi-word-component-names\n\tname: 'Descope',\n\tprops: {\n\t\tflowId: {\n\t\t\ttype: String,\n\t\t\trequired: true\n\t\t},\n\t\ttenant: {\n\t\t\ttype: String\n\t\t},\n\t\ttheme: {\n\t\t\ttype: String\n\t\t},\n\t\tdebug: {\n\t\t\ttype: Boolean\n\t\t},\n\t\ttelemetryKey: {\n\t\t\ttype: String\n\t\t},\n\t\tredirectUrl: {\n\t\t\ttype: String\n\t\t},\n\t\tautoFocus: {\n\t\t\ttype: Boolean\n\t\t}\n\t},\n\temits: ['success', 'error'],\n\tsetup(_: unknown, { emit }: SetupContext) {\n\t\tconst { projectId, baseUrl, sessionTokenViaCookie } = useOptions();\n\t\tconst sdk = useDescope();\n\n\t\tconst onSuccess = async (e: CustomEvent) => {\n\t\t\t// Note: We need to emit AFTER the afterRequest hook has been called, but for\n\t\t\t// an unknown reason, the emit is not called if we await the hook.\n\t\t\temit('success', e);\n\t\t\tawait sdk.httpClient.hooks?.afterRequest?.(\n\t\t\t\t{} as RequestConfig,\n\t\t\t\tnew Response(JSON.stringify(e.detail))\n\t\t\t);\n\t\t};\n\t\tconst onError = (e: Event) => emit('error', e);\n\n\t\treturn {\n\t\t\tprojectId,\n\t\t\tbaseUrl,\n\t\t\tsessionTokenViaCookie,\n\t\t\tonSuccess,\n\t\t\tonError\n\t\t};\n\t}\n};\n</script>\n"],"names":["_createElementBlock","_createElementVNode","$setup","projectId","baseUrl","$props","flowId","theme","tenant","debug","telemetryKey","redirectUrl","autoFocus","onSuccess","args","onError"],"mappings":"itCACCA,qBAcK,MAAA,KAAA,CAbJC,EAAAA,mBAYC,aAAA,CAXC,aAAYC,EAASC,UACrB,WAAUD,EAAOE,QACjB,UAASC,EAAMC,OACf,SAAYD,EAAKE,MACjB,UAAaF,EAAMG,OACnB,SAAYH,EAAKI,MACjB,gBAAmBJ,EAAYK,aAC/B,eAAcL,EAAWM,YACzB,aAAYN,EAASO,UACrBC,8BAASX,EAASW,WAAAX,EAAAW,aAAAC,IAClBC,4BAAOb,EAAOa,SAAAb,EAAAa,WAAAD"}
+{"version":3,"file":"index.cjs","sources":["../src/Descope.vue?vue&type=template&id=8a031dec&lang.js"],"sourcesContent":["<template>\n\t<div>\n\t\t<descope-wc\n\t\t\t:project-id=\"projectId\"\n\t\t\t:base-url=\"baseUrl\"\n\t\t\t:flow-id=\"flowId\"\n\t\t\t:theme.attr=\"theme\"\n\t\t\t:tenant.attr=\"tenant\"\n\t\t\t:debug.attr=\"debug\"\n\t\t\t:telemetryKey.attr=\"telemetryKey\"\n\t\t\t:redirect-url=\"redirectUrl\"\n\t\t\t:auto-focus=\"autoFocus\"\n\t\t\t@success=\"onSuccess\"\n\t\t\t@error=\"onError\"\n\t\t/>\n\t</div>\n</template>\n\n<script lang=\"ts\">\nimport DescopeWc from '@descope/web-component';\nimport { useOptions, useDescope } from './hooks';\nimport { baseHeaders } from './constants';\nimport { RequestConfig } from '@descope/core-js-sdk';\nimport { SetupContext } from 'vue';\n\nDescopeWc.sdkConfigOverrides = { baseHeaders };\n\nexport default {\n\t// eslint-disable-next-line vue/multi-word-component-names\n\tname: 'Descope',\n\tprops: {\n\t\tflowId: {\n\t\t\ttype: String,\n\t\t\trequired: true\n\t\t},\n\t\ttenant: {\n\t\t\ttype: String\n\t\t},\n\t\ttheme: {\n\t\t\ttype: String\n\t\t},\n\t\tdebug: {\n\t\t\ttype: Boolean\n\t\t},\n\t\ttelemetryKey: {\n\t\t\ttype: String\n\t\t},\n\t\tredirectUrl: {\n\t\t\ttype: String\n\t\t},\n\t\tautoFocus: {\n\t\t\ttype: Boolean\n\t\t}\n\t},\n\temits: ['success', 'error'],\n\tsetup(_: unknown, { emit }: SetupContext) {\n\t\tconst { projectId, baseUrl, sessionTokenViaCookie } = useOptions();\n\t\tconst sdk = useDescope();\n\n\t\tconst onSuccess = async (e: CustomEvent) => {\n\t\t\t// Note: We need to emit AFTER the afterRequest hook has been called, but for\n\t\t\t// an unknown reason, the emit is not called if we await the hook.\n\t\t\temit('success', e);\n\t\t\tawait sdk.httpClient.hooks?.afterRequest?.(\n\t\t\t\t{} as RequestConfig,\n\t\t\t\tnew Response(JSON.stringify(e.detail))\n\t\t\t);\n\t\t};\n\t\tconst onError = (e: Event) => emit('error', e);\n\n\t\treturn {\n\t\t\tprojectId,\n\t\t\tbaseUrl,\n\t\t\tsessionTokenViaCookie,\n\t\t\tonSuccess,\n\t\t\tonError\n\t\t};\n\t}\n};\n</script>\n"],"names":["_createElementBlock","_createElementVNode","$setup","projectId","baseUrl","$props","flowId","theme","tenant","debug","telemetryKey","redirectUrl","autoFocus","onSuccess","args","onError"],"mappings":"8uCACCA,qBAcK,MAAA,KAAA,CAbJC,EAAAA,mBAYC,aAAA,CAXC,aAAYC,EAASC,UACrB,WAAUD,EAAOE,QACjB,UAASC,EAAMC,OACf,SAAYD,EAAKE,MACjB,UAAaF,EAAMG,OACnB,SAAYH,EAAKI,MACjB,gBAAmBJ,EAAYK,aAC/B,eAAcL,EAAWM,YACzB,aAAYN,EAASO,UACrBC,8BAASX,EAASW,WAAAX,EAAAW,aAAAC,IAClBC,4BAAOb,EAAOa,SAAAb,EAAAa,WAAAD"}