@asgardeo/javascript/dist/models/v2/embedded-flow-v2.d.ts

Framework agnostic JavaScript SDK for Asgardeo.

/**
 * 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",
    /** One-time password input field for multi-factor authentication */
    OtpInput = "OTP_INPUT",
    /** Phone number input field with country code support */
    PhoneInput = "PHONE_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",
    /** Divider component for visual separation of content */
    Divider = "DIVIDER"
}
/**
 * Action variant types for buttons and interactive elements.
 *
 * @experimental This API may change in future versions
 */
export declare enum EmbeddedFlowActionVariant {
    /** Primary action button with highest visual emphasis */
    Primary = "PRIMARY",
    /** Secondary action button with moderate visual emphasis */
    Secondary = "SECONDARY",
    /** Tertiary action button with minimal visual emphasis */
    Tertiary = "TERTIARY",
    /** Danger action button for destructive operations */
    Danger = "DANGER",
    /** Success action button for positive confirmations */
    Success = "SUCCESS",
    /** Info action button for informational purposes */
    Info = "INFO",
    /** Warning action button for cautionary actions */
    Warning = "WARNING",
    /** Link-styled action button */
    Link = "LINK",
    /** Social media action button (e.g., Google, Facebook) */
    Social = "SOCIAL"
}
/**
 * Text variant types for typography components.
 *
 * @experimental This API may change in future versions
 */
export declare enum EmbeddedFlowTextVariant {
    /** Largest heading level for main titles */
    Heading1 = "HEADING_1",
    /** Second level heading for major sections */
    Heading2 = "HEADING_2",
    /** Third level heading for subsections */
    Heading3 = "HEADING_3",
    /** Fourth level heading for minor sections */
    Heading4 = "HEADING_4",
    /** Fifth level heading for detailed sections */
    Heading5 = "HEADING_5",
    /** Smallest heading level for fine-grained sections */
    Heading6 = "HEADING_6",
    /** Primary subtitle text with larger emphasis */
    Subtitle1 = "SUBTITLE_1",
    /** Secondary subtitle text with moderate emphasis */
    Subtitle2 = "SUBTITLE_2",
    /** Primary body text for main content */
    Body1 = "BODY_1",
    /** Secondary body text for supplementary content */
    Body2 = "BODY_2",
    /** Small caption text for annotations and descriptions */
    Caption = "CAPTION",
    /** Overline text for labels and categories */
    Overline = "OVERLINE",
    /** Text styled for button labels */
    ButtonText = "BUTTON_TEXT"
}
/**
 * Event types for action components.
 *
 * @experimental This API may change in future versions
 */
export declare enum EmbeddedFlowEventType {
    /** Trigger an action or event */
    Trigger = "TRIGGER",
    /** Submit form data to the server */
    Submit = "SUBMIT",
    /** Navigate to a different flow step or page */
    Navigate = "NAVIGATE",
    /** Cancel the current operation */
    Cancel = "CANCEL",
    /** Reset form fields to initial state */
    Reset = "RESET",
    /** Navigate back to the previous step */
    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;
}