@asgardeo/javascript 0.2.8 → 0.2.10

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

@@ -120,7 +120,7 @@ export interface EmbeddedFlowExecuteRequestConfig<T = any> extends Partial<Reque
  * // (Prefers description over message as it's usually more detailed)
  * ```
  *
- * @see {@link EmbeddedSignUpFlowErrorResponseV2} for the AsgardeoV2 equivalent error structure
+ * @see {@link EmbeddedSignUpFlowErrorResponse} for the AsgardeoV2 equivalent error structure
  */
 export interface EmbeddedFlowExecuteErrorResponse {
     /**

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

@@ -0,0 +1,307 @@
+/**
+ * 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 as EmbeddedFlowExecuteRequestConfigV1 } from '../embedded-flow';
+/**
+ * Component types supported by the Asgardeo embedded flow API.
+ *
+ * These types define the different UI components that can be rendered
+ * as part of the embedded authentication flows. Each type corresponds
+ * to a specific UI element with its own behavior and properties.
+ *
+ * @example
+ * ```typescript
+ * // Check component type to render appropriate UI
+ * if (component.type === EmbeddedFlowComponentType.TextInput) {
+ *   // Render text input field
+ * } else if (component.type === EmbeddedFlowComponentType.Action) {
+ *   // Render button/action
+ * }
+ * ```
+ *
+ * @experimental This API may change in future versions
+ */
+export declare enum EmbeddedFlowComponentType {
+    /** Standard text input field for user data entry */
+    TextInput = "TEXT_INPUT",
+    /** Password input field with masking for sensitive data */
+    PasswordInput = "PASSWORD_INPUT",
+    /**
+     * Email input field with validation for email addresses.
+     */
+    EmailInput = "EMAIL_INPUT",
+    /** Text display component for labels, headings, and messages */
+    Text = "TEXT",
+    /** Interactive action component (buttons, links) for user interactions */
+    Action = "ACTION",
+    /** Container block component that groups other components */
+    Block = "BLOCK"
+}
+/**
+ * Action variant types for buttons and interactive elements.
+ *
+ * @experimental This API may change in future versions
+ */
+export declare enum EmbeddedFlowActionVariant {
+    Primary = "PRIMARY",
+    Secondary = "SECONDARY",
+    Tertiary = "TERTIARY",
+    Danger = "DANGER",
+    Success = "SUCCESS",
+    Info = "INFO",
+    Warning = "WARNING",
+    Link = "LINK"
+}
+/**
+ * Text variant types for typography components.
+ *
+ * @experimental This API may change in future versions
+ */
+export declare enum EmbeddedFlowTextVariant {
+    Heading1 = "HEADING_1",
+    Heading2 = "HEADING_2",
+    Heading3 = "HEADING_3",
+    Heading4 = "HEADING_4",
+    Heading5 = "HEADING_5",
+    Heading6 = "HEADING_6",
+    Subtitle1 = "SUBTITLE_1",
+    Subtitle2 = "SUBTITLE_2",
+    Body1 = "BODY_1",
+    Body2 = "BODY_2",
+    Caption = "CAPTION",
+    Overline = "OVERLINE",
+    ButtonText = "BUTTON_TEXT"
+}
+/**
+ * Event types for action components.
+ *
+ * @experimental This API may change in future versions
+ */
+export declare enum EmbeddedFlowEventType {
+    Trigger = "TRIGGER",
+    Submit = "SUBMIT",
+    Navigate = "NAVIGATE",
+    Cancel = "CANCEL",
+    Reset = "RESET",
+    Back = "BACK"
+}
+/**
+ * Enhanced component interface for embedded flow components.
+ *
+ * This interface provides better support for modern form handling and user experience.
+ * It includes properties for labels, placeholders, and required field validation
+ * that are directly provided by the API response.
+ *
+ * @example
+ * ```typescript
+ * const component: EmbeddedFlowComponent = {
+ *   id: 'username_field',
+ *   type: EmbeddedFlowComponentType.TextInput,
+ *   label: 'Username',
+ *   placeholder: 'Enter your username',
+ *   required: true,
+ *   variant: 'TEXT',
+ *   eventType: 'SUBMIT',
+ *   components: []
+ * };
+ * ```
+ *
+ * @experimental This interface may change in future versions
+ */
+export interface EmbeddedFlowComponent {
+    /**
+     * Unique identifier for the component
+     */
+    id: string;
+    /**
+     * Reference identifier for the component (e.g., field name, action ref)
+     */
+    ref?: string;
+    /**
+     * Component type that determines rendering behavior
+     */
+    type: EmbeddedFlowComponentType | string;
+    /**
+     * Display label for the component (e.g., field label, button text).
+     * Supports internationalization and may contain template strings.
+     */
+    label?: string;
+    /**
+     * Placeholder text for input components.
+     * Provides helpful hints to users about expected input format.
+     */
+    placeholder?: string;
+    /**
+     * Indicates whether this component represents a required field.
+     * Used for form validation and UI indicators.
+     */
+    required?: boolean;
+    /**
+     * Component variant that affects visual styling and behavior.
+     * The value depends on the component type (e.g., button variants, text variants).
+     */
+    variant?: EmbeddedFlowActionVariant | EmbeddedFlowTextVariant | string;
+    /**
+     * Event type for action components that defines the interaction behavior.
+     * Only relevant for Action components.
+     */
+    eventType?: EmbeddedFlowEventType | string;
+    /**
+     * Nested child components for container components like Block.
+     */
+    components?: EmbeddedFlowComponent[];
+}
+/**
+ * Response data structure for embedded flow API.
+ *
+ * This interface defines the structure of data returned by the API,
+ * which includes both legacy input/action arrays for backward compatibility
+ * and the new meta.components structure for modern component-driven UIs.
+ *
+ * The key improvement is the meta.components field, which provides
+ * a rich component tree with proper labels, placeholders, and hierarchy
+ * that can be directly rendered without additional transformation.
+ *
+ * @example
+ * ```typescript
+ * const response: EmbeddedFlowResponseData = {
+ *   // Legacy format (for backward compatibility)
+ *   inputs: [
+ *     { ref: 'input_001', identifier: 'username', type: 'TEXT_INPUT', required: true }
+ *   ],
+ *   actions: [
+ *     { ref: 'action_001', nextNode: 'basic_auth', eventType: 'SUBMIT' }
+ *   ],
+ *   // Modern format (recommended)
+ *   meta: {
+ *     components: [
+ *       {
+ *         id: 'text_001',
+ *         type: 'TEXT',
+ *         label: '{{ t(signin:heading.label) }}',
+ *         variant: 'HEADING_1'
+ *       },
+ *       {
+ *         id: 'block_001',
+ *         type: 'BLOCK',
+ *         components: [
+ *           {
+ *             id: 'input_001',
+ *             type: 'TEXT_INPUT',
+ *             label: '{{ t(signin:fields.username.label) }}',
+ *             placeholder: '{{ t(signin:fields.username.placeholder) }}',
+ *             required: true
+ *           },
+ *           {
+ *             id: 'action_001',
+ *             type: 'ACTION',
+ *             label: '{{ t(signin:buttons.submit.label) }}',
+ *             variant: 'PRIMARY',
+ *             eventType: 'ACTIVATE'
+ *           }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * };
+ * ```
+ *
+ * @experimental This structure may change in future versions
+ */
+export interface EmbeddedFlowResponseData {
+    /**
+     * Legacy input definitions for backward compatibility.
+     * @deprecated Use meta.components for new implementations
+     */
+    inputs?: {
+        /** Reference identifier for the input */
+        ref: string;
+        /** Field identifier used in form submission */
+        identifier: string;
+        /** Input type (TEXT_INPUT, PASSWORD_INPUT, etc.) */
+        type: string;
+        /** Whether this input is required for form submission */
+        required: boolean;
+    }[];
+    /**
+     * Legacy action definitions for backward compatibility.
+     * @deprecated Use meta.components for new implementations
+     */
+    actions?: {
+        /** Reference identifier for the action */
+        ref: string;
+        /** Next flow node to navigate to (optional) */
+        nextNode?: string;
+        /** Event type for the action (SUBMIT, ACTIVATE, etc.) */
+        eventType?: string;
+    }[];
+    /**
+     * Modern component-driven metadata structure.
+     * This contains the complete UI component tree with proper
+     * hierarchy, labels, and configuration that can be directly rendered.
+     *
+     * **This is the primary data source for implementations.**
+     * The legacy inputs/actions arrays are maintained only for backward compatibility.
+     */
+    meta?: {
+        /** Array of components that define the complete UI structure */
+        components: EmbeddedFlowComponent[];
+    };
+    /**
+     * Optional redirect URL for flow completion or external authentication.
+     */
+    redirectURL?: string;
+}
+/**
+ * Extended request configuration for Asgardeo V2 embedded flow operations.
+ *
+ * This interface extends the base request configuration with V2-specific
+ * properties required for the enhanced embedded flow API. The authId parameter
+ * is particularly important for the V2 OAuth2 flow completion process.
+ *
+ * @template T The type of the payload data being sent with the request
+ *
+ * @example
+ * ```typescript
+ * const config: EmbeddedFlowExecuteRequestConfigV2 = {
+ *   baseUrl: 'https://api.asgardeo.io/t/myorg',
+ *   payload: {
+ *     flowType: 'AUTHENTICATION',
+ *     inputs: { username: 'user@example.com' }
+ *   },
+ *   authId: 'auth_12345', // V2-specific for OAuth completion
+ *   headers: {
+ *     'Authorization': 'Bearer token'
+ *   }
+ * };
+ * ```
+ *
+ * @experimental This configuration is part of the new Asgardeo V2 platform
+ */
+export interface EmbeddedFlowExecuteRequestConfig<T = any> extends EmbeddedFlowExecuteRequestConfigV1<T> {
+    /**
+     * Authentication ID used for OAuth2 flow completion in V2 API.
+     *
+     * When the embedded flow completes successfully and returns an assertion,
+     * this authId is used to complete the OAuth2 authorization flow by calling
+     * the `/oauth2/authorize` endpoint. This enables seamless transition from
+     * embedded flow to traditional OAuth2 flow completion.
+     *
+     * @example "auth_abc123def456"
+     */
+    authId?: string;
+}

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

@@ -15,75 +15,305 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { EmbeddedFlowExecuteRequestConfig, EmbeddedFlowResponseType, EmbeddedFlowType } from '../embedded-flow';
-export declare enum EmbeddedSignInFlowStatusV2 {
+import { EmbeddedFlowResponseType as EmbeddedFlowResponseTypeV1, EmbeddedFlowType as EmbeddedFlowTypeV1 } from '../embedded-flow';
+import { EmbeddedFlowResponseData as EmbeddedFlowResponseDataV2 } from './embedded-flow-v2';
+/**
+ * Status enumeration for Asgardeo embedded sign-in flow operations.
+ *
+ * These statuses indicate the current state of the sign-in flow and determine
+ * the next action required by the client application. Each status provides
+ * specific guidance on how to proceed with the authentication process.
+ *
+ * @example
+ * ```typescript
+ * switch (response.flowStatus) {
+ *   case EmbeddedSignInFlowStatus.Incomplete:
+ *     // More user input needed - render form components
+ *     break;
+ *   case EmbeddedSignInFlowStatus.Complete:
+ *     // Authentication successful - handle completion
+ *     break;
+ *   case EmbeddedSignInFlowStatus.Error:
+ *     // Authentication failed - show error message
+ *     break;
+ * }
+ * ```
+ *
+ * @experimental Part of the new Asgardeo API
+ */
+export declare enum EmbeddedSignInFlowStatus {
+    /**
+     * Sign-in flow completed successfully.
+     *
+     * The user has been authenticated and the flow can proceed to
+     * OAuth2 completion or redirection. Check for redirectUrl or
+     * assertion data in the response.
+     */
     Complete = "COMPLETE",
+    /**
+     * Sign-in flow requires additional user input.
+     *
+     * More authentication steps are needed. The response will contain
+     * components in data.meta.components that should be rendered to
+     * collect additional user input (e.g., MFA, password, etc.).
+     */
     Incomplete = "INCOMPLETE",
+    /**
+     * Sign-in flow encountered an error.
+     *
+     * Authentication failed due to invalid credentials, system error,
+     * or other issues. Check error details in the response and handle
+     * appropriately (retry, show error message, etc.).
+     */
     Error = "ERROR"
 }
-export declare enum EmbeddedSignInFlowTypeV2 {
+/**
+ * Type enumeration for Asgardeo embedded sign-in flow responses.
+ *
+ * Determines the nature of the flow response and how the client should
+ * handle the returned data. This affects both UI rendering and flow
+ * continuation logic.
+ *
+ * @experimental Part of the new Asgardeo API
+ */
+export declare enum EmbeddedSignInFlowType {
+    /**
+     * Response requires external redirection.
+     *
+     * Used for social login providers, external identity providers,
+     * or other flows that require navigating to an external URL.
+     * The response will contain redirection information.
+     */
     Redirection = "REDIRECTION",
+    /**
+     * Response contains view components for rendering.
+     *
+     * Standard embedded flow response containing UI components
+     * that should be rendered within the current application
+     * context. Most common type for embedded authentication.
+     */
     View = "VIEW"
 }
 /**
- * Extended response structure for the embedded sign-in flow V2.
- * @remarks This response is only done from the SDK level.
- * @experimental
+ * Extended response structure for Asgardeo embedded sign-in flow.
+ *
+ * This interface defines additional properties that are added at the SDK level
+ * to enhance the basic API response with client-side computed values. These
+ * properties provide convenience for common post-authentication operations.
+ *
+ * @remarks This response structure is enhanced by the SDK and contains
+ * properties beyond the raw API response. It's designed to simplify
+ * post-authentication handling for client applications.
+ *
+ * @experimental This interface is part of the new Asgardeo platform
  */
-export interface ExtendedEmbeddedSignInFlowResponseV2 {
+export interface ExtendedEmbeddedSignInFlowResponse {
     /**
-     * The URL to redirect the user after completing the sign-in flow.
+     * Computed redirect URL for post-authentication navigation.
+     *
+     * This URL is determined by the SDK based on the flow completion result
+     * and configured redirect settings. When present, the client application
+     * should navigate to this URL to complete the authentication process.
+     *
+     * @example "https://myapp.com/dashboard?session=abc123"
      */
     redirectUrl?: string;
 }
 /**
- * Response structure for the new Asgardeo V2 embedded sign-in flow.
- * @experimental
+ * Primary response structure for Asgardeo embedded sign-in flow operations.
+ *
+ * This is the main response interface returned by the sign-in API, combining
+ * the enhanced SDK properties with the core API response data. It provides all
+ * information needed to handle the current state of the authentication flow.
+ *
+ * The response structure adapts based on the flow status:
+ * - INCOMPLETE: Contains components for user interaction
+ * - COMPLETE: Contains completion data and potential redirection info
+ * - ERROR: Contains error information for troubleshooting
+ *
+ * @example
+ * ```typescript
+ * const response: EmbeddedSignInFlowResponse = {
+ *   flowId: "flow_12345",
+ *   flowStatus: EmbeddedSignInFlowStatus.Incomplete,
+ *   type: EmbeddedSignInFlowType.View,
+ *   data: {
+ *     meta: {
+ *       components: [
+ *         {
+ *           id: "username_field",
+ *           type: EmbeddedFlowComponentType.TextInput,
+ *           label: "Username",
+ *           required: true
+ *         }
+ *       ]
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @experimental This interface is part of the new Asgardeo platform
  */
-export interface EmbeddedSignInFlowResponseV2 extends ExtendedEmbeddedSignInFlowResponseV2 {
+export interface EmbeddedSignInFlowResponse extends ExtendedEmbeddedSignInFlowResponse {
+    /**
+     * Unique identifier for this specific flow instance.
+     * Used to maintain state across multiple API calls during the authentication process.
+     */
     flowId: string;
-    flowStatus: EmbeddedSignInFlowStatusV2;
-    type: EmbeddedSignInFlowTypeV2;
-    data: {
+    /**
+     * Current status of the sign-in flow.
+     * Determines the next action required by the client application.
+     */
+    flowStatus: EmbeddedSignInFlowStatus;
+    /**
+     * Type of response indicating how to handle the returned data.
+     * Affects both UI rendering and navigation logic.
+     */
+    type: EmbeddedSignInFlowType;
+    /**
+     * Core response data containing UI components and flow metadata.
+     * Includes both modern meta.components structure and legacy fields for compatibility.
+     */
+    data: EmbeddedFlowResponseDataV2 & {
+        /**
+         * Legacy action definitions for backward compatibility.
+         * @deprecated Use data.meta.components for new implementations
+         */
         actions?: {
-            type: EmbeddedFlowResponseType;
+            /** Action type identifier */
+            type: EmbeddedFlowResponseTypeV1;
+            /** Unique action identifier */
             id: string;
         }[];
+        /**
+         * Legacy input field definitions for backward compatibility.
+         * @deprecated Use data.meta.components for new implementations
+         */
         inputs?: {
+            /** Field name identifier */
             name: string;
+            /** Input field type */
             type: string;
+            /** Whether the field is required */
             required: boolean;
         }[];
     };
 }
 /**
- * Response structure for the new Asgardeo V2 embedded sign-in flow when the flow is complete.
- * @experimental
+ * Response structure for completed Asgardeo embedded sign-in flows.
+ *
+ * This interface defines the response format when the embedded sign-in flow
+ * reaches the COMPLETE status and requires OAuth2 flow completion. It contains
+ * the redirect URI that should be used for the final authentication step.
+ *
+ * @example
+ * ```typescript
+ * const completeResponse: EmbeddedSignInFlowCompleteResponse = {
+ *   redirect_uri: "https://myapp.com/callback?code=abc123&state=xyz789"
+ * };
+ *
+ * // Typically handled automatically by the SDK
+ * window.location.href = completeResponse.redirect_uri;
+ * ```
+ *
+ * @experimental This interface is part of the new Asgardeo platform
  */
 export interface EmbeddedSignInFlowCompleteResponse {
+    /**
+     * OAuth2 redirect URI for completing the authentication flow.
+     *
+     * Contains the final redirect URL with authorization code, state,
+     * and other OAuth2 parameters needed to complete the authentication
+     * process. This URL should be navigated to automatically or manually
+     * depending on the application's requirements.
+     */
     redirect_uri: string;
 }
 /**
- * Request payload for initiating the new Asgardeo V2 embedded sign-in flow.
- * @experimental
+ * Request payload for initiating Asgardeo embedded sign-in flows.
+ *
+ * This type defines the minimum required information to start a new
+ * embedded sign-in flow. The flow type determines the kind of authentication
+ * process that will be initiated (e.g., standard login, MFA, etc.).
+ *
+ * @example
+ * ```typescript
+ * const initRequest: EmbeddedSignInFlowInitiateRequest = {
+ *   applicationId: "app_12345",
+ *   flowType: EmbeddedFlowType.Authentication
+ * };
+ *
+ * const response = await executeEmbeddedSignInFlow({
+ *   baseUrl: "https://api.asgardeo.io/t/myorg",
+ *   payload: initRequest
+ * });
+ * ```
+ *
+ * @experimental This type is part of the new Asgardeo platform
  */
-export type EmbeddedSignInFlowInitiateRequestV2 = {
+export type EmbeddedSignInFlowInitiateRequest = {
+    /**
+     * Unique identifier of the application initiating the sign-in flow.
+     * Must be a valid application ID registered in the Asgardeo organization.
+     */
     applicationId: string;
-    flowType: EmbeddedFlowType;
+    /**
+     * Type of embedded flow to initiate.
+     * Determines the authentication process and available options.
+     */
+    flowType: EmbeddedFlowTypeV1;
 };
 /**
- * Request payload for executing steps in the new Asgardeo V2 embedded sign-in flow.
- * @experimental
+ * Request payload for executing steps in Asgardeo embedded sign-in flows.
+ *
+ * This interface defines the structure for subsequent requests after flow initiation.
+ * It supports both continuing existing flows (with flowId) and submitting user
+ * input data collected from the rendered components.
+ *
+ * @example
+ * ```typescript
+ * // Continue existing flow with user input
+ * const stepRequest: EmbeddedSignInFlowRequest = {
+ *   flowId: "flow_12345",
+ *   actionId: "action_001",
+ *   inputs: {
+ *     username: "user@example.com",
+ *     password: "securePassword123"
+ *   }
+ * };
+ *
+ * // Submit to continue the flow
+ * const response = await executeEmbeddedSignInFlow({
+ *   baseUrl: "https://api.asgardeo.io/t/myorg",
+ *   payload: stepRequest
+ * });
+ * ```
+ *
+ * @experimental This interface is part of the new Asgardeo platform
  */
-export interface EmbeddedSignInFlowRequestV2 extends Partial<EmbeddedSignInFlowInitiateRequestV2> {
+export interface EmbeddedSignInFlowRequest extends Partial<EmbeddedSignInFlowInitiateRequest> {
+    /**
+     * Identifier of the flow instance to continue.
+     * Required when submitting data for an existing flow.
+     */
     flowId?: string;
+    /**
+     * Identifier of the specific action being triggered.
+     * Corresponds to action components in the UI (e.g., submit button, social login).
+     */
     actionId?: string;
+    /**
+     * User input data collected from the form components.
+     * Keys should match the component identifiers from the response.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   "username": "john.doe@example.com",
+     *   "password": "mySecurePassword",
+     *   "rememberMe": true
+     * }
+     * ```
+     */
     inputs?: Record<string, any>;
 }
-/**
- * Request config for executing the new Asgardeo V2 embedded sign-in flow.
- * @experimental
- */
-export interface EmbeddedFlowExecuteRequestConfigV2<T = any> extends EmbeddedFlowExecuteRequestConfig<T> {
-    authId?: string;
-}