@asgardeo/javascript 0.1.23 → 0.2.1

package/dist/models/config.d.ts

@@ -199,6 +199,11 @@ export interface WithPreferences {
 }
 export type Config<T = unknown> = BaseConfig<T>;
 export interface ThemePreferences {
+    /**
+     * The text direction for the UI.
+     * @default 'ltr'
+     */
+    direction?: 'ltr' | 'rtl';
     /**
      * Inherit from Branding from WSO2 Identity Server or Asgardeo.
      */

package/dist/models/embedded-flow.d.ts

@@ -60,8 +60,104 @@ export declare enum EmbeddedFlowComponentType {
     Select = "SELECT",
     Typography = "TYPOGRAPHY"
 }
+/**
+ * Request configuration for executing embedded flow operations.
+ *
+ * This interface extends standard HTTP request configuration with additional
+ * properties specific to embedded flow execution, such as base URL and payload data.
+ *
+ * @template T - Type of the payload data being sent with the request
+ */
 export interface EmbeddedFlowExecuteRequestConfig<T = any> extends Partial<Request> {
+    /**
+     * Base URL for the API endpoint.
+     * This is typically the Asgardeo organization URL.
+     */
     baseUrl?: string;
+    /**
+     * Payload data to be sent with the request.
+     * The structure depends on the specific flow operation being executed.
+     */
     payload?: T;
+    /**
+     * Full URL for the API endpoint.
+     * If provided, this overrides the baseUrl.
+     */
     url?: string;
 }
+/**
+ * Error response structure for AsgardeoV1 embedded flow operations.
+ *
+ * This interface defines the structure of error responses returned by AsgardeoV1 APIs
+ * when flow operations (such as sign-up or sign-in) fail. This format is distinct from
+ * AsgardeoV2's error format which uses `failureReason` instead of `code`/`description`.
+ *
+ * **Key Characteristics:**
+ * - Uses structured error codes (e.g., "FEE-60005") for programmatic error handling
+ * - Provides both a brief `message` and detailed `description` for context
+ * - Includes `flowType` to identify which flow operation failed
+ *
+ * **Comparison with AsgardeoV2:**
+ * - **AsgardeoV1**: Uses `code`, `message`, `description` fields
+ * - **AsgardeoV2**: Uses `flowStatus: "ERROR"` with `failureReason` field
+ *
+ * **Error Handling:**
+ * This error response format is automatically detected and processed by the
+ * `extractErrorMessage()` and `checkForErrorResponse()` functions in the React
+ * transformer to extract meaningful error messages for display to users.
+ *
+ * @example
+ * ```typescript
+ * // Typical AsgardeoV1 error response
+ * const errorResponse: EmbeddedFlowExecuteErrorResponse = {
+ *   code: "FEE-60005",
+ *   message: "Error while provisioning user.",
+ *   description: "Error occurred while provisioning user in the request of flow id: ac57315c-6ca6-49dc-8664-fcdcff354f46",
+ *   flowType: "REGISTRATION"
+ * };
+ *
+ * // The transformer will extract: "Error occurred while provisioning user in the request of flow id: ac57315c-6ca6-49dc-8664-fcdcff354f46"
+ * // (Prefers description over message as it's usually more detailed)
+ * ```
+ *
+ * @see {@link EmbeddedSignUpFlowErrorResponseV2} for the AsgardeoV2 equivalent error structure
+ */
+export interface EmbeddedFlowExecuteErrorResponse {
+    /**
+     * Structured error code identifying the type of error.
+     *
+     * Format typically follows pattern like "FEE-XXXXX" where:
+     * - "FEE" indicates Flow Execution Error
+     * - XXXXX is a numeric identifier for the specific error type
+     *
+     * @example "FEE-60005" - User provisioning error
+     */
+    code: string;
+    /**
+     * Brief error message describing what went wrong.
+     *
+     * This is typically a short, high-level description of the error.
+     * For more detailed information, refer to the `description` field.
+     *
+     * @example "Error while provisioning user."
+     */
+    message: string;
+    /**
+     * Detailed error description with contextual information.
+     *
+     * This field usually contains more specific information about the error,
+     * including flow IDs, operation details, and other debugging context.
+     * The transformer prefers this field over `message` when extracting
+     * error messages for display to users.
+     *
+     * @example "Error occurred while provisioning user in the request of flow id: ac57315c-6ca6-49dc-8664-fcdcff354f46"
+     */
+    description: string;
+    /**
+     * Type of flow operation that encountered the error.
+     *
+     * Currently only supports 'REGISTRATION' but may be extended to
+     * include other flow types (e.g., 'LOGIN', 'PASSWORD_RESET') in the future.
+     */
+    flowType: 'REGISTRATION';
+}

package/dist/models/v2/embedded-signup-flow-v2.d.ts

@@ -0,0 +1,226 @@
+/**
+ * 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 { EmbeddedFlowExecuteRequestConfig, EmbeddedFlowResponseType, EmbeddedFlowType } from '../embedded-flow';
+/**
+ * Status enumeration for AsgardeoV2 embedded sign-up flow responses.
+ *
+ * This enum defines the possible states of a sign-up flow operation,
+ * allowing client applications to determine the next appropriate action.
+ *
+ * @experimental Part of the new AsgardeoV2 API
+ */
+export declare enum EmbeddedSignUpFlowStatusV2 {
+    /**
+     * Sign-up flow has completed successfully.
+     *
+     * When this status is returned, the user has successfully registered
+     * and the flow can proceed to redirection or completion handling.
+     * The response will typically contain redirect information.
+     */
+    Complete = "COMPLETE",
+    /**
+     * Sign-up flow is in progress and requires additional user input.
+     *
+     * This status indicates that more steps are needed to complete the
+     * sign-up process. The response will contain form components or
+     * actions that need to be presented to the user.
+     */
+    Incomplete = "INCOMPLETE",
+    /**
+     * Sign-up flow encountered an error and cannot proceed.
+     *
+     * When this status is returned, the response will be of type
+     * `EmbeddedSignUpFlowErrorResponseV2` and will contain a `failureReason`
+     * field with details about what went wrong. This triggers error
+     * handling in the React components to display user-friendly messages.
+     *
+     * @see {@link EmbeddedSignUpFlowErrorResponseV2} for error response structure
+     */
+    Error = "ERROR"
+}
+export declare enum EmbeddedSignUpFlowTypeV2 {
+    Redirection = "REDIRECTION",
+    View = "VIEW"
+}
+/**
+ * Extended response structure for the embedded sign-up flow V2.
+ * @remarks This response is only done from the SDK level.
+ * @experimental
+ */
+export interface ExtendedEmbeddedSignUpFlowResponseV2 {
+    /**
+     * The URL to redirect the user after completing the sign-up flow.
+     */
+    redirectUrl?: string;
+}
+/**
+ * Response structure for the new Asgardeo V2 embedded sign-up flow.
+ *
+ * This interface defines the structure for successful sign-up flow responses
+ * from AsgardeoV2 APIs. For error responses, see `EmbeddedSignUpFlowErrorResponseV2`.
+ *
+ * **Flow States:**
+ * - `INCOMPLETE`: More user input required, `data` contains form components
+ * - `COMPLETE`: Sign-up finished, may contain redirect information
+ * - For `ERROR` status, a separate `EmbeddedSignUpFlowErrorResponseV2` structure is used
+ *
+ * **Component-Driven UI:**
+ * The `data.inputs` and `data.actions` are transformed by the React transformer
+ * into component-driven format for consistent UI rendering across different
+ * Asgardeo versions.
+ *
+ * @experimental Part of the new AsgardeoV2 API
+ * @see {@link EmbeddedSignUpFlowErrorResponseV2} for error response structure
+ * @see {@link EmbeddedSignUpFlowStatusV2} for available flow statuses
+ */
+export interface EmbeddedSignUpFlowResponseV2 extends ExtendedEmbeddedSignUpFlowResponseV2 {
+    /**
+     * Unique identifier for this sign-up flow instance.
+     */
+    flowId: string;
+    /**
+     * Current status of the sign-up flow.
+     * Determines whether more input is needed or the flow is complete.
+     */
+    flowStatus: EmbeddedSignUpFlowStatusV2;
+    /**
+     * Type of response, indicating the expected user interaction.
+     */
+    type: EmbeddedSignUpFlowTypeV2;
+    /**
+     * Flow data containing form inputs and available actions.
+     * This is transformed to component-driven format by the React transformer.
+     */
+    data: {
+        /**
+         * Available actions the user can take (e.g., form submission, social sign-up).
+         */
+        actions?: {
+            type: EmbeddedFlowResponseType;
+            id: string;
+        }[];
+        /**
+         * Input fields required for the current step of the sign-up flow.
+         */
+        inputs?: {
+            name: string;
+            type: string;
+            required: boolean;
+        }[];
+    };
+}
+/**
+ * Response structure for the new Asgardeo V2 embedded sign-up flow when the flow is complete.
+ * @experimental
+ */
+export interface EmbeddedSignUpFlowCompleteResponse {
+    redirect_uri: string;
+}
+/**
+ * Request payload for initiating the new Asgardeo V2 embedded sign-up flow.
+ * @experimental
+ */
+export type EmbeddedSignUpFlowInitiateRequestV2 = {
+    applicationId: string;
+    flowType: EmbeddedFlowType;
+};
+/**
+ * Request payload for executing steps in the new Asgardeo V2 embedded sign-up flow.
+ * @experimental
+ */
+export interface EmbeddedSignUpFlowRequestV2 extends Partial<EmbeddedSignUpFlowInitiateRequestV2> {
+    flowId?: string;
+    actionId?: string;
+    inputs?: Record<string, any>;
+}
+/**
+ * Request config for executing the new Asgardeo V2 embedded sign-up flow.
+ * @experimental
+ */
+export interface EmbeddedFlowExecuteRequestConfigV2<T = any> extends EmbeddedFlowExecuteRequestConfig<T> {
+    sessionDataKey?: string;
+}
+/**
+ * Error response structure for the new Asgardeo V2 embedded sign-up flow.
+ *
+ * This interface defines the structure of error responses returned by AsgardeoV2 APIs
+ * when sign-up operations fail. Unlike AsgardeoV1 which uses generic error codes and
+ * descriptions, AsgardeoV2 provides more specific failure reasons within the flow context.
+ *
+ * **Key Differences from AsgardeoV1:**
+ * - Uses `failureReason` instead of `message`/`description` for error details
+ * - Maintains flow context with `flowId` for tracking failed operations
+ * - Uses structured `flowStatus` enum instead of generic error codes
+ * - Provides empty `data` object for consistency with success responses
+ *
+ * **Error Handling:**
+ * This error response format is automatically detected and processed by the
+ * `extractErrorMessage()` and `checkForErrorResponse()` functions in the transformer
+ * to extract meaningful error messages for display to users.
+ *
+ * @example
+ * ```typescript
+ * // Typical AsgardeoV2 error response
+ * const errorResponse: EmbeddedSignUpFlowErrorResponseV2 = {
+ *   flowId: "0ccfeaf9-18b3-43a5-bcc1-07d863dcb2c0",
+ *   flowStatus: EmbeddedSignUpFlowStatusV2.Error,
+ *   data: {},
+ *   failureReason: "User already exists with the provided username."
+ * };
+ *
+ * // This will be automatically transformed to a user-friendly error message:
+ * // "User already exists with the provided username."
+ * ```
+ *
+ * @experimental This is part of the new AsgardeoV2 API and may change in future versions
+ * @see {@link EmbeddedSignUpFlowStatusV2.Error} for the error status enum value
+ * @see {@link EmbeddedSignUpFlowResponseV2} for the corresponding success response structure
+ */
+export interface EmbeddedSignUpFlowErrorResponseV2 {
+    /**
+     * Unique identifier for the sign-up flow instance.
+     * This ID is used to track the flow state and correlate error responses
+     * with the specific sign-up attempt that failed.
+     */
+    flowId: string;
+    /**
+     * Status of the sign-up flow, which will be `EmbeddedSignUpFlowStatusV2.Error`
+     * for error responses. This field is used by error detection logic to
+     * identify failed flow responses.
+     */
+    flowStatus: EmbeddedSignUpFlowStatusV2;
+    /**
+     * Additional response data, typically empty for error responses.
+     * Maintained for structural consistency with successful flow responses
+     * which contain components, actions, and other flow data.
+     */
+    data: Record<string, any>;
+    /**
+     * Human-readable explanation of why the sign-up operation failed.
+     *
+     * This field contains specific error details that can be directly displayed
+     * to users, such as:
+     * - "User already exists with the provided username."
+     * - "Invalid email address format."
+     * - "Password does not meet complexity requirements."
+     *
+     * Unlike generic error codes, this provides contextual information
+     * that helps users understand and resolve the issue.
+     */
+    failureReason: string;
+}

package/dist/theme/types.d.ts

@@ -142,6 +142,11 @@ export interface ThemeConfig {
         small: string;
     };
     colors: ThemeColors;
+    /**
+     * The text direction for the UI.
+     * @default 'ltr'
+     */
+    direction?: 'ltr' | 'rtl';
     shadows: {
         large: string;
         medium: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asgardeo/javascript",
-  "version": "0.1.23",
+  "version": "0.2.1",
   "description": "Framework agnostic JavaScript SDK for Asgardeo.",
   "keywords": [
     "asgardeo",
@@ -46,7 +46,7 @@
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@asgardeo/i18n": "^0.3.1"
+    "@asgardeo/i18n": "^0.3.2"
   },
   "publishConfig": {
     "access": "public"