@teamhanko/hanko-frontend-sdk/dist/lib/flow-api/State.d.ts

A package for simplifying UI integration with the Hanko API. It is meant for use in browsers only.

import { Hanko } from "../../Hanko";
import { Actions, Payloads, StateName } from "./types/state";
import { Input } from "./types/input";
import { FlowError } from "./types/flowError";
import { Action as ActionType } from "./types/action";
import { AnyState, FlowName, FlowResponse } from "./types/flow";
import { autoSteps } from "./auto-steps";
import { passkeyAutofillActivationHandlers } from "./passkey-autofill-activation";
export type AutoSteppedStates = keyof typeof autoSteps;
export type PasskeyAutofillStates = keyof typeof passkeyAutofillActivationHandlers;
export type AutoStepExclusion = AutoSteppedStates[] | "all";
export type ActionMap<TState extends StateName> = {
    [K in keyof Actions[TState]]: Action<Actions[TState][K] extends ActionType<infer TInputs> ? TInputs : never>;
};
export type ActionInfo = {
    name: string;
    relatedStateName: StateName;
};
export interface StateInitConfig {
    dispatchAfterStateChangeEvent?: boolean;
    excludeAutoSteps?: AutoStepExclusion;
    previousAction?: ActionInfo;
    isCached?: boolean;
    cacheKey?: string;
}
export type StateCreateConfig = Pick<StateInitConfig, "dispatchAfterStateChangeEvent" | "excludeAutoSteps" | "cacheKey"> & {
    loadFromCache?: boolean;
};
export type ActionRunConfig = Pick<StateInitConfig, "dispatchAfterStateChangeEvent">;
type SerializedState = FlowResponse<any> & {
    flow_name: FlowName;
    previous_action?: ActionInfo;
    is_cached?: boolean;
};
type ExtractInputValues<TInputs> = {
    [K in keyof TInputs]: TInputs[K] extends Input<infer TValue> ? TValue : never;
};
/**
 * Represents a state in a flow with associated actions and properties.
 * @template TState - The specific state name type.
 * @constructor
 * @param {Hanko} hanko - The Hanko instance for API interactions.
 * @param {FlowName} flowName - The name of the flow this state belongs to.
 * @param {FlowResponse<TState>} response - The flow response containing state data.
 * @param {StateInitConfig} [options={}] - Configuration options for state initialization.
 * @category SDK
 * @subcategory FlowAPI
 */
export declare class State<TState extends StateName = StateName> {
    readonly name: TState;
    readonly flowName: FlowName;
    error?: FlowError;
    readonly payload?: Payloads[TState];
    readonly actions: ActionMap<TState>;
    readonly csrfToken: string;
    readonly status: number;
    readonly previousAction?: ActionInfo;
    readonly isCached: boolean;
    readonly cacheKey: string;
    readonly hanko: Hanko;
    invokedAction?: ActionInfo;
    readonly excludeAutoSteps: AutoStepExclusion;
    readonly autoStep?: TState extends AutoSteppedStates ? () => Promise<AnyState> : never;
    readonly passkeyAutofillActivation: TState extends PasskeyAutofillStates ? () => Promise<void> : never;
    /**
     * Constructs a new State instance.
     * @param {Hanko} hanko - The Hanko instance for API interactions.
     * @param {FlowName} flowName - The name of the flow this state belongs to.
     * @param {FlowResponse<TState>} response - The flow response containing state data.
     * @param {StateInitConfig} [options={}] - Configuration options for state initialization.
     */
    constructor(hanko: Hanko, flowName: FlowName, response: FlowResponse<TState>, options?: StateInitConfig);
    /**
     * Builds the action map for this state, wrapping it in a Proxy to handle undefined actions.
     * @param {Actions} actions - The actions available in this state.
     * @returns {ActionMap<TState>} The action map for the state.
     * @private
     */
    private buildActionMap;
    /**
     * Dispatches an event after the state has changed.
     */
    dispatchAfterStateChangeEvent(): void;
    /**
     * Serializes the current state into a storable format.
     * @returns {SerializedState} The serialized state object.
     */
    serialize(): SerializedState;
    /**
     * Saves the current state to localStorage.
     * @returns {void}
     */
    saveToLocalStorage(): void;
    /**
     * Removes the current state from localStorage.
     * @returns {void}
     */
    removeFromLocalStorage(): void;
    /**
     * Initializes a flow state, processing auto-steps if applicable.
     * @param {Hanko} hanko - The Hanko instance for API interactions.
     * @param {FlowName} flowName - The name of the flow.
     * @param {FlowResponse<any>} response - The initial flow response.
     * @param {StateInitConfig} [options={}] - Configuration options.
     * @param {boolean} [options.dispatchAfterStateChangeEvent=true] - Whether to dispatch an event after state change.
     * @param {AutoStepExclusion} [options.excludeAutoSteps=null] - States to exclude from auto-step processing, or "all".
     * @param {ActionInfo} [options.previousAction=null] - Information about the previous action.
     * @param {boolean} [options.isCached=false] - Whether the state is loaded from cache.
     * @param {string} [options.cacheKey="hanko-flow-state"] - Key for localStorage caching.
     * @returns {Promise<AnyState>} A promise resolving to the initialized state.
     */
    static initializeFlowState(hanko: Hanko, flowName: FlowName, response: FlowResponse<any>, options?: StateInitConfig): Promise<AnyState>;
    /**
     * Retrieves and parses state data from localStorage.
     * @param {string} cacheKey - The key used to store the state in localStorage.
     * @returns {SerializedState | undefined} The parsed serialized state, or undefined if not found or invalid.
     */
    static readFromLocalStorage(cacheKey: string): SerializedState | undefined;
    /**
     * Creates a new state instance, using cached or fetched data.
     * @param {Hanko} hanko - The Hanko instance for API interactions.
     * @param {FlowName} flowName - The name of the flow.
     * @param {StateCreateConfig} [config={}] - Configuration options.
     * @param {boolean} [config.dispatchAfterStateChangeEvent=true] - Whether to dispatch an event after state change.
     * @param {AutoStepExclusion} [config.excludeAutoSteps=null] - States to exclude from auto-step processing, or "all".
     * @param {string} [config.cacheKey="hanko-flow-state"] - Key for localStorage caching.
     * @param {boolean} [config.loadFromCache=true] - Whether to attempt loading from cache.
     * @returns {Promise<AnyState>} A promise resolving to the created state.
     */
    static create(hanko: Hanko, flowName: FlowName, config?: StateCreateConfig): Promise<AnyState>;
    /**
     * Deserializes a state from a serialized state object.
     * @param {Hanko} hanko - The Hanko instance for API interactions.
     * @param {SerializedState} serializedState - The serialized state data.
     * @param {StateCreateConfig} [config={}] - Configuration options.
     * @param {boolean} [config.dispatchAfterStateChangeEvent=true] - Whether to dispatch an event after state change.
     * @param {AutoStepExclusion} [config.excludeAutoSteps=null] - States to exclude from auto-step processing, or "all".
     * @param {string} [config.cacheKey="hanko-flow-state"] - Key for localStorage caching.
     * @param {boolean} [config.loadFromCache=true] - Whether to attempt loading from cache.
     * @returns {Promise<AnyState>} A promise resolving to the deserialized state.
     */
    static deserialize(hanko: Hanko, serializedState: SerializedState, config?: StateCreateConfig): Promise<AnyState>;
    /**
     * Fetches state data from the server.
     * @param {Hanko} hanko - The Hanko instance for API interactions.
     * @param {string} href - The endpoint to fetch from.
     * @param {any} [body] - Optional request body.
     * @returns {Promise<FlowResponse<any>>} A promise resolving to the flow response.
     */
    static fetchState(hanko: Hanko, href: string, body?: any): Promise<FlowResponse<any>>;
    /**
     * Creates an error flow response.
     * @param {FlowError} error - The error to include in the response.
     * @returns {FlowResponse<"error">} A flow response with error details.
     * @private
     */
    private static createErrorResponse;
}
/**
 * Represents an actionable operation within a state.
 * @template TInputs - The type of inputs required for the action.
 * @param {ActionType<TInputs>} action - The action type definition.
 * @param {State} parentState - The state this action belongs to.
 * @param {boolean} [enabled=true] - Whether the action is enabled.
 * @category SDK
 * @subcategory FlowAPI
 */
export declare class Action<TInputs> {
    readonly enabled: boolean;
    readonly href: string;
    readonly name: string;
    readonly inputs: TInputs;
    private readonly parentState;
    /**
     * Constructs a new Action instance.
     * @param {ActionType<TInputs>} action - The action type definition.
     * @param {State} parentState - The state this action belongs to.
     * @param {boolean} [enabled=true] - Whether the action is enabled.
     */
    constructor(action: ActionType<TInputs>, parentState: State, enabled?: boolean);
    /**
     * Creates a disabled action instance.
     * @template TInputs - The type of inputs (inferred as empty).
     * @param {string} name - The name of the action.
     * @param {State} parentState - The state this action belongs to.
     * @returns {Action<TInputs>} A disabled action instance.
     */
    static createDisabled<TInputs>(name: string, parentState: State): Action<TInputs>;
    /**
     * Executes the action, transitioning to a new state.
     * @param {ExtractInputValues<TInputs>} [inputValues=null] - Values for the action's inputs.
     * @param {ActionRunConfig} [config={}] - Configuration options.
     * @param {boolean} [config.dispatchAfterStateChangeEvent=true] - Whether to dispatch an event after state change.
     * @returns {Promise<AnyState>} A promise resolving to the next state.
     * @throws {FlowError} If the action is disabled or already invoked.
     */
    run(inputValues?: ExtractInputValues<TInputs>, config?: ActionRunConfig): Promise<AnyState>;
}
export {};