@sesamy/sesamy-js 1.12.1 → 1.13.1

package/README.md

@@ -61,6 +61,7 @@ The following methods are available on the `sesamy` object:
   - autoOnboard: trigger the auto-onboarding process for a product by sku
 - getVersion: returns the version of the sesamy-js library
 - getPaymentIssues: returns a list of failed payments and cards that will expire
+- generateLink: creates a link to a sesamy hosted service such as account or consume. If the user is authenticated, the link will be signed so that the user can access the service without logging in again.
 - clearCache: clears the cache for the sesamy-js library
 
 ## Events
@@ -119,3 +120,131 @@ These are the available configuration options, with their default values:
   },
 }
 ```
+
+# Auth API
+
+## `isAuthenticated()`
+
+Checks if the user is currently authenticated. This function verifies the existence of a valid session by checking both the local storage for an access token and the state of the Auth0 client.
+
+### Returns
+
+- **boolean**: Returns `true` if the user is authenticated either via local storage tokens or the Auth0 client; otherwise, it returns `false`.
+
+### Example
+
+The following example demonstrates how to check if a user is currently authenticated:
+
+```javascript
+import { isAuthenticated } from '@sesamy/sesamy-js';
+
+isAuthenticated()
+  .then(isAuth => {
+    if (isAuth) {
+      console.log('User is authenticated.');
+    } else {
+      console.log('User is not authenticated.');
+    }
+  })
+  .catch(error => {
+    console.error('Error checking authentication status:', error);
+  });
+```
+
+## `loginWithRedirect(options?: LoginWithRedirectOptions)`
+
+Initiates a login flow that redirects the user to an Auth0 hosted login page. Once the user authenticates, they will be redirected back to the specified `redirect_uri` within your application.
+
+### Parameters
+
+- `options` (optional): An object containing customization options for the login flow.
+  - `appState`: (optional, object) Used to store state before doing the redirect.
+  - `authorizationParams`: (optional, object) Additional parameters to include in the authorization request.
+    - `audience`: (optional, string) The audience to request access to.
+    - `scope`: (optional, string) The scope of the access request.
+    - `login_hint`: (optional, string) A hint to pre-fill the username on the login page.
+    - `organization`: (optional, string) The organization to authenticate with.
+    - `redirect_uri`: (optional, string) The URL to redirect the user to after login.
+
+### Returns
+
+This function returns a `Promise` that resolves when the redirect is successfully initiated.
+
+### Example
+
+The following example demonstrates how to use `loginWithRedirect` to initiate a login flow with an email address pre-filled:
+
+```javascript
+import { loginWithRedirect } from '@sesamy/sesamy-js';
+
+// Optionally pass the user's email to pre-fill on the login form
+const loginOptions = {
+  authorizationParams: {
+    login_hint: 'user@example.com',
+  },
+};
+
+// Redirect the user to the login page
+loginWithRedirect(loginOptions);
+```
+
+## `logout(options?: LogoutOptions)`
+
+Terminates the user's session and optionally redirects the user to a specified URL after logout. This function clears any local session tokens and interacts with the Auth0 API to end the session.
+
+### Parameters
+
+- `options` (optional): An object containing customization options for the logout process.
+  - `returnTo`: (optional, string) The URL to redirect users to after logging out. Defaults to the current page URL if not provided.
+
+### Returns
+
+This function does not return a value. It causes a redirect to the specified `returnTo` URL or performs a page refresh if no URL is provided.
+
+### Example
+
+The following example demonstrates how to log out a user and redirect them to the homepage:
+
+```javascript
+import { logout } from '@sesamy/sesamy-js';
+
+// Specify the URL to redirect to after logout
+const logoutOptions = {
+  returnTo: 'https://www.yourdomain.com',
+};
+// Redirects the user to the auth server to log out
+logout(logoutOptions);
+```
+
+## `setToken(accessToken: string, expiresIn?: number)`
+
+Stores the provided access token in local storage and optionally sets an expiration time for it. Additionally, this function parses the access token to extract user information and triggers an authentication event.
+
+### Parameters
+
+- `accessToken` (string): The access token to store and use for session management.
+- `expiresIn` (optional, number): The time in seconds from now when the token should expire.
+
+### Returns
+
+This function does not return a value but triggers an event indicating that a user has been authenticated with the new token.
+
+### Example
+
+The following example demonstrates how to store an access token and set an expiration time:
+
+```javascript
+import { setToken } from '@sesamy/sesamy-js';
+
+// Example access token and expiration period
+const accessToken = 'your.access.token';
+const expiresIn = 3600; // 1 hour in seconds
+
+setToken(accessToken, expiresIn)
+  .then(() => {
+    console.log('Token set successfully and user authenticated.');
+  })
+  .catch(error => {
+    console.error('Failed to set token:', error);
+  });
+```