@asgardeo/react 0.2.4 → 0.4.0

package/README.md

@@ -1,7 +1,7 @@
 <p align="center" style="color: #343a40">
   <h1 align="center">@asgardeo/react</h1>
 </p>
-<p align="center" style="font-size: 1.2rem;">React Wrapper to build customizable login UIs for Asgardeo or Identity Server</p>
+<p align="center" style="font-size: 1.2rem;">React SDK for Asgardeo</p>
 <div align="center">
   <img alt="npm (scoped)" src="https://img.shields.io/npm/v/@asgardeo/react">
   <img alt="npm" src="https://img.shields.io/npm/dw/@asgardeo/react">
@@ -11,17 +11,123 @@
 ## Installation
 
 ```bash
-# With npm
+# Using npm
 npm install @asgardeo/react
 
-# With pnpm
+# or using pnpm
 pnpm add @asgardeo/react
 
-# With yarn
+# or using yarn
 yarn add @asgardeo/react
 ```
 
+## Quick Start
+
+1. Add `<AsgardeoProvider />` to your app
+
+```tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+import { AsgardeoProvider } from '@asgardeo/react'
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <AsgardeoProvider
+      baseUrl: '<your-organization-name>'
+      clientId: '<your-app-client-id>'
+    >
+      <App />
+    </AsgardeoProvider>
+  </StrictMode>
+)
+```
+
+2. Add signed-in and signed-out to your app
+
+```tsx
+import { SignedIn, SignedOut, SignInButton, SignOutButton } from '@asgardeo/react'
+import './App.css'
+
+function App() {
+  return (
+    <>
+      <SignedIn>
+        <SignOutButton />
+      </SignedIn>
+      <SignedOut>
+        <SignInButton />
+      </SignedOut>
+    </>
+  )
+}
+
+export default App
+```
+
+3. Start using other drop-in components like `User`, `UserProfile`, etc.
+
+```tsx
+import { User, UserProfile } from '@asgardeo/react'
+import './App.css'
+
+function App() {
+  return (
+    <>
+      <User>
+        {({ user }) => (
+          <div>
+            <h1>Welcome, {user.username}</h1>
+            <UserProfile />
+          </div>
+        )}
+      </User>
+      
+      <UserProfile />
+    </>
+  )
+}
+export default App
+```
+
+## Using the `useAsgardeo` Hook (For Programmatic Control)
+
+For more granular control, you can use the useAsgardeo hook. This hook provides direct access to SDK's functions and state:
+
+```tsx
+import { useAsgardeo } from '@asgardeo/react'
+import './App.css'
+
+function App() {
+  const { user, signIn, signOut, isSignedIn, isLoading } = useAsgardeo()
+
+  if (isLoading) {
+    return <div>Loading...</div>
+  }
+
+  return (
+    <div>
+      {isSignedIn ? (
+        <div>
+          <div>
+            <img src={user.photourl} alt={user.username} />
+            <p>Welcome back, {user.givenname}</p>
+          </div>
+          <button onClick={() => signOut()}>Sign Out</button>
+        </div>
+      ) : (
+        <button onClick={() => signIn()}>Sign In</button>
+      )}
+    </div>
+  )
+}
+```
+
+## Documentation
+
+For complete API documentation including all components, hooks, and customization options, see [API.md](./API.md).
+
 ## License
 
-Licenses this source under the Apache License, Version 2.0 [LICENSE](./LICENSE), You may not use this file except in
-compliance with the License.
+Licenses this source under the Apache License, Version 2.0 [LICENSE](../../LICENSE), You may not use this file except in compliance with the License.

package/dist/AsgardeoReactClient.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { AsgardeoBrowserClient, UserProfile, SignInOptions, SignOutOptions, User } from '@asgardeo/browser';
+import { AsgardeoReactConfig } from './models/config';
+/**
+ * Client for mplementing Asgardeo in React applications.
+ * This class provides the core functionality for managing user authentication and sessions.
+ *
+ * @typeParam T - Configuration type that extends AsgardeoReactConfig.
+ */
+declare class AsgardeoReactClient<T extends AsgardeoReactConfig = AsgardeoReactConfig> extends AsgardeoBrowserClient<T> {
+    private asgardeo;
+    constructor();
+    initialize(config: T): Promise<boolean>;
+    getUser(): Promise<User>;
+    getUserProfile(): Promise<UserProfile>;
+    isLoading(): boolean;
+    isSignedIn(): Promise<boolean>;
+    signIn(options?: SignInOptions): Promise<User>;
+    signOut(options?: SignOutOptions, afterSignOut?: (redirectUrl: string) => void): Promise<string>;
+    signOut(options?: SignOutOptions, sessionId?: string, afterSignOut?: (redirectUrl: string) => void): Promise<string>;
+}
+export default AsgardeoReactClient;

package/dist/__temp__/api.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Copyright (c) 2025, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
+ *
+ * WSO2 Inc. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { AsgardeoSPAClient, AuthClientConfig, User, LegacyConfig as Config, IdTokenPayload, Hooks, HttpClientInstance, HttpRequestConfig, HttpResponse, OIDCEndpoints, SignInConfig, SPACustomGrantConfig } from '@asgardeo/browser';
+import { AuthStateInterface } from './models';
+declare class AuthAPI {
+    static DEFAULT_STATE: AuthStateInterface;
+    private _authState;
+    private _client;
+    private _isLoading;
+    constructor(spaClient?: AsgardeoSPAClient);
+    _setIsLoading(isLoading: boolean): void;
+    _getIsLoading(): boolean;
+    isLoading(): boolean;
+    /**
+     * Method to return Auth Client instance authentication state.
+     *
+     * @return {AuthStateInterface} Authentication State.
+     */
+    getState(): AuthStateInterface;
+    /**
+     * Method to initialize the AuthClient instance.
+     *
+     * @param {Config} config - `dispatch` function from React Auth Context.
+     */
+    init(config: AuthClientConfig<Config>): Promise<boolean>;
+    /**
+     * Method to get the configuration data.
+     *
+     * @returns {Promise<AuthClientConfig<Config>>} - A promise that resolves with the configuration data.
+     */
+    getConfigData(): Promise<AuthClientConfig<Config>>;
+    /**
+     * Method to handle user Sign In requests.
+     *
+     * @param {any} dispatch - `dispatch` function from React Auth Context.
+     * @param {AuthStateInterface} state - Current authentication state in React Auth Context.
+     * @param {any} callback - Action to trigger on successful sign in.
+     */
+    signIn(config: SignInConfig, authorizationCode?: string, sessionState?: string, authState?: string, callback?: (response: User) => void, tokenRequestConfig?: {
+        params: Record<string, unknown>;
+    }): Promise<any>;
+    /**
+     * Method to handle user Sign Out requests.
+     *
+     * @param {any} dispatch - `dispatch` function from React Auth Context.
+     * @param {AuthStateInterface} state - Current authentication state in React Auth Context.
+     * @param {any} callback - Action to trigger on successful sign out.
+     */
+    signOut(callback?: (response?: boolean) => void): Promise<boolean>;
+    /**
+     * Method to update Auth Client instance authentication state.
+     *
+     * @param {AuthStateInterface} state - State values to update in authentication state.
+     */
+    updateState(state: AuthStateInterface): void;
+    /**
+     * This method returns a Promise that resolves with the basic user information obtained from the ID token.
+     *
+     * @return {Promise<User>} - A promise that resolves with the user information.
+     */
+    getUser(): Promise<User>;
+    /**
+     * This method sends an API request to a protected endpoint.
+     * The access token is automatically attached to the header of the request.
+     * This is the only way by which protected endpoints can be accessed
+     * when the web worker is used to store session information.
+     *
+     * @param {HttpRequestConfig} config -  The config object containing attributes necessary to send a request.
+     *
+     * @return {Promise<Response>} - Returns a Promise that resolves with the response to the request.
+     */
+    httpRequest(config: HttpRequestConfig): Promise<HttpResponse<any>>;
+    /**
+     * This method sends multiple API requests to a protected endpoint.
+     * The access token is automatically attached to the header of the request.
+     * This is the only way by which multiple requests can be sent to protected endpoints
+     * when the web worker is used to store session information.
+     *
+     * @param {HttpRequestConfig[]} config -  The config object containing attributes necessary to send a request.
+     *
+     * @return {Promise<Response>} - Returns a Promise that resolves with the responses to the requests.
+     */
+    httpRequestAll(configs: HttpRequestConfig[]): Promise<HttpResponse<any>[]>;
+    /**
+     * This method allows you to send a request with a custom grant.
+     *
+     * @param {CustomGrantRequestParams} config - The request parameters.
+     *
+     * @return {Promise<Response | SignInResponse>} - A Promise that resolves with
+     * the value returned by the custom grant request.
+     */
+    exchangeToken(config: SPACustomGrantConfig, callback: (response: User | Response) => void, dispatch: (state: AuthStateInterface) => void): Promise<User | Response>;
+    /**
+     * This method ends a user session. The access token is revoked and the session information is destroyed.
+     *
+     * @return {Promise<boolean>} - A promise that resolves with `true` if the process is successful.
+     */
+    revokeAccessToken(dispatch: (state: AuthStateInterface) => void): Promise<boolean>;
+    /**
+     * This method returns a Promise that resolves with an object containing the service endpoints.
+     *
+     * @return {Promise<ServiceResourcesType} - A Promise that resolves with an object containing the service endpoints.
+     */
+    getOpenIDProviderEndpoints(): Promise<OIDCEndpoints>;
+    /**
+     * This methods returns the Axios http client.
+     *
+     * @return {HttpClientInstance} - The Axios HTTP client.
+     */
+    getHttpClient(): Promise<HttpClientInstance>;
+    /**
+     * This method decodes the payload of the id token and returns it.
+     *
+     * @return {Promise<DecodedIDTokenPayloadInterface>} - A Promise that resolves with
+     * the decoded payload of the id token.
+     */
+    getDecodedIdToken(): Promise<IdTokenPayload>;
+    /**
+     * This method decodes the payload of the idp id token and returns it.
+     *
+     * @return {Promise<DecodedIDTokenPayloadInterface>} - A Promise that resolves with
+     * the decoded payload of the idp id token.
+     */
+    getDecodedIDPIDToken(): Promise<IdTokenPayload>;
+    /**
+     * This method returns the ID token.
+     *
+     * @return {Promise<string>} - A Promise that resolves with the id token.
+     */
+    getIdToken(): Promise<string>;
+    /**
+     * This method return a Promise that resolves with the access token.
+     *
+     * **This method will not return the access token if the storage type is set to `webWorker`.**
+     *
+     * @return {Promise<string>} - A Promise that resolves with the access token.
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * This method return a Promise that resolves with the idp access token.
+     *
+     * **This method will not return the idp access token if the storage type is set to `webWorker`.**
+     * **This can be used to access the IDP access token when custom auth grant functionalities are used**
+     *
+     * @return {Promise<string>} - A Promise that resolves with the idp access token.
+     */
+    getIDPAccessToken(): Promise<string>;
+    /**
+     * This method refreshes the access token.
+     *
+     * @return {TokenResponseInterface} - A Promise that resolves with an object containing
+     * information about the refreshed access token.
+     */
+    refreshAccessToken(): Promise<User>;
+    /**
+     * This method specifies if the user is authenticated or not.
+     *
+     * @return {Promise<boolean>} - A Promise that resolves with `true` if teh user is authenticated.
+     */
+    isSignedIn(): Promise<boolean>;
+    /**
+     * This method specifies if the session is active or not.
+     *
+     * @return {Promise<boolean>} - A Promise that resolves with `true` if there is an active session.
+     */
+    isSessionActive(): Promise<boolean>;
+    /**
+     * This method enables callback functions attached to the http client.
+     *
+     * @return {Promise<boolean>} - A promise that resolves with True.
+     *
+     */
+    enableHttpHandler(): Promise<boolean>;
+    /**
+     * This method disables callback functions attached to the http client.
+     *
+     * @return {Promise<boolean>} - A promise that resolves with True.
+     */
+    disableHttpHandler(): Promise<boolean>;
+    /**
+     * This method updates the configuration that was passed into the constructor when instantiating this class.
+     *
+     * @param {Partial<AuthClientConfig<T>>} config - A config object to update the SDK configurations with.
+     */
+    reInitialize(config: Partial<AuthClientConfig<Config>>): Promise<void>;
+    /**
+     * This method attaches a callback function to an event hook that fires the callback when the event happens.
+     *
+     * @param {Hooks.CustomGrant} hook - The name of the hook.
+     * @param {(response?: any) => void} callback - The callback function.
+     * @param {string} id (optional) - The id of the hook. This is used when multiple custom grants are used.
+     *
+     */
+    on(hook: Hooks.CustomGrant, callback: (response?: any) => void, id: string): Promise<void>;
+    on(hook: Exclude<Hooks, Hooks.CustomGrant>, callback: (response?: any) => void): Promise<void>;
+    /**
+     * This method allows you to sign in silently.
+     * First, this method sends a prompt none request to see if there is an active user session in the identity server.
+     * If there is one, then it requests the access token and stores it. Else, it returns false.
+     *
+     * @return {Promise<User | boolean>} - A Promise that resolves with the user information after signing in
+     * or with `false` if the user is not signed in.
+     *
+     * @example
+     *```
+     * client.trySignInSilently()
+     *```
+     */
+    trySignInSilently(state: AuthStateInterface, dispatch: (state: AuthStateInterface) => void, additionalParams?: Record<string, string | boolean>, tokenRequestConfig?: {
+        params: Record<string, unknown>;
+    }): Promise<User | boolean | undefined>;
+}
+export default AuthAPI;

package/dist/__temp__/models.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Copyright (c) 2020, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
+ *
+ * WSO2 Inc. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { AsgardeoAuthException, AuthClientConfig, AuthSPAClientConfig, Config, TokenExchangeRequestConfig, IdTokenPayload, Hooks, HttpClientInstance, HttpRequestConfig, HttpResponse, OIDCEndpoints, SignInConfig, User } from '@asgardeo/browser';
+export interface ReactConfig {
+    /**
+     * The SDK's `AuthProvider` by default is listening to the URL changes to see
+     * if `code` & `session_state` search params are available so that it could perform
+     * token exchange. This option could be used to override that behaviour.
+     */
+    skipRedirectCallback?: boolean;
+    /**
+     * The `AuthProvider`, by default, looks for an active session in the server and updates the session information
+     * with the latest session information from the server. This option could be used to disable that behaviour.
+     */
+    disableTrySignInSilently?: boolean;
+    disableAutoSignIn?: boolean;
+}
+export type AuthReactConfig = AuthSPAClientConfig & ReactConfig;
+/**
+ * Interface for the Authenticated state of the user which is exposed
+ * via `state` object from `useAuthContext` hook.
+ */
+export interface AuthStateInterface {
+    /**
+     * The display name of the user.
+     */
+    displayName?: string;
+    /**
+     * The email address of the user.
+     */
+    email?: string;
+    /**
+     * Specifies if the user is authenticated or not.
+     */
+    isSignedIn: boolean;
+    /**
+     * Are the Auth requests loading.
+     */
+    isLoading: boolean;
+    /**
+     * The username of the user.
+     */
+    username?: string;
+}
+export interface AuthContextInterface {
+    signIn: (config?: SignInConfig, authorizationCode?: string, sessionState?: string, state?: string, callback?: (response: User) => void, tokenRequestConfig?: {
+        params: Record<string, unknown>;
+    }) => Promise<User>;
+    signOut: (callback?: (response: boolean) => void) => Promise<boolean>;
+    getUser(): Promise<User>;
+    httpRequest(config: HttpRequestConfig): Promise<HttpResponse<any>>;
+    httpRequestAll(configs: HttpRequestConfig[]): Promise<HttpResponse<any>[]>;
+    exchangeToken(config: TokenExchangeRequestConfig, callback?: (response: User | Response) => void): void;
+    revokeAccessToken(): Promise<boolean>;
+    getOpenIDProviderEndpoints(): Promise<OIDCEndpoints>;
+    getHttpClient(): Promise<HttpClientInstance>;
+    getDecodedIDPIDToken(): Promise<IdTokenPayload>;
+    getDecodedIdToken(): Promise<IdTokenPayload>;
+    getIdToken(): Promise<string>;
+    getAccessToken(): Promise<string>;
+    refreshAccessToken(): Promise<User>;
+    isSignedIn(): Promise<boolean>;
+    enableHttpHandler(): Promise<boolean>;
+    disableHttpHandler(): Promise<boolean>;
+    reInitialize(config: Partial<AuthClientConfig<Config>>): Promise<void>;
+    trySignInSilently: (additionalParams?: Record<string, string | boolean>, tokenRequestConfig?: {
+        params: Record<string, unknown>;
+    }) => Promise<boolean | User>;
+    on(hook: Hooks.CustomGrant, callback: (response?: any) => void, id: string): void;
+    on(hook: Exclude<Hooks, Hooks.CustomGrant>, callback: (response?: any) => void): void;
+    on(hook: Hooks, callback: (response?: any) => void, id?: string): void;
+    state: AuthStateInterface;
+    error: AsgardeoAuthException;
+}
+/**
+ * The model of the object returned by the `getAuthParams` prop method of the `AuthProvider`.
+ */
+export interface AuthParams {
+    authorizationCode?: string;
+    sessionState?: string;
+    state?: string;
+}

package/dist/api/scim2/getMeProfile.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { User } from '@asgardeo/browser';
+/**
+ * Retrieves the user profile information from the specified selfcare profile endpoint.
+ *
+ * @param requestConfig - Request configuration object.
+ * @returns A promise that resolves with the user profile information.
+ * @example
+ * ```typescript
+ * try {
+ *   const userProfile = await getUserProfile({
+ *     url: "https://api.asgardeo.io/t/<ORGANIZATION>/scim2/Me",
+ *   });
+ *   console.log(userProfile);
+ * } catch (error) {
+ *   if (error instanceof AsgardeoAPIError) {
+ *     console.error('Failed to get user profile:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare const getMeProfile: ({ url, ...requestConfig }: Partial<Request>) => Promise<User>;
+export default getMeProfile;

package/dist/api/scim2/getSchemas.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { Schema } from '@asgardeo/browser';
+/**
+ * Retrieves the SCIM2 schemas from the specified endpoint.
+ *
+ * @param requestConfig - Request configuration object.
+ * @returns A promise that resolves with the SCIM2 schemas information.
+ * @example
+ * ```typescript
+ * try {
+ *   const schemas = await getSchemas({
+ *     url: "https://api.asgardeo.io/t/<ORGANIZATION>/scim2/Schemas",
+ *   });
+ *   console.log(schemas);
+ * } catch (error) {
+ *   if (error instanceof AsgardeoAPIError) {
+ *     console.error('Failed to get schemas:', error.message);
+ *   }
+ * }
+ * ```
+ */
+declare const getSchemas: ({ url }: Partial<Request>) => Promise<Schema[]>;
+export default getSchemas;

package/dist/api/scim2/updateMeProfile.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2025, WSO2 LLC. (https://www.wso2.com).
+ *
+ * WSO2 LLC. licenses this file to you under the Apache License,
+ * Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+import { User } from '@asgardeo/browser';
+/**
+ * Updates the user profile information at the specified SCIM2 Me endpoint.
+ *
+ * @param url - The SCIM2 Me endpoint URL.
+ * @param value - The value object to patch (SCIM2 PATCH value).
+ * @param requestConfig - Additional request config if needed.
+ * @returns A promise that resolves with the updated user profile information.
+ * @example
+ * ```typescript
+ * await updateMeProfile({
+ *   url: "https://api.asgardeo.io/t/<ORG>/scim2/Me",
+ *   value: { "urn:scim:wso2:schema": { mobileNumbers: ["0777933830"] } }
+ * });
+ * ```
+ */
+declare const updateMeProfile: ({ url, payload, ...requestConfig }: {
+    url: string;
+    payload: any;
+} & Partial<Request>) => Promise<User>;
+export default updateMeProfile;