@hira-core/sdk 1.0.2 → 1.0.3

package/dist/index.d.ts

@@ -1,19 +1,37 @@
+import * as _packages_shared from '@packages/shared';
+import { ProfileOutputValue, IWorkerLogMessage, ProfileStatus, IWorkerOutputMessage } from '@packages/shared';
 import * as puppeteer from 'puppeteer-core';
 import { Browser, Page, Frame, ElementHandle } from 'puppeteer-core';
 import { EventEmitter } from 'events';
-import { IWorkerLogMessage, ProfileStatus } from '@packages/shared';
 
-interface IGpmProfile {
+/**
+ * Unified profile interface — provider-agnostic.
+ * Both GPM and Hidemium (and future providers) map their native profiles to this.
+ */
+interface IAntidetectProfile {
+    /** Unique ID (GPM: id, Hidemium: uuid) */
     id: string;
+    /** Human-readable profile name */
     name: string;
+    /** Which antidetect provider */
+    provider: "gpm" | "hidemium" | "genlogin";
+    /** Raw proxy string (format varies per provider) */
     raw_proxy?: string;
+    /** Browser engine */
     browser_type: "chromium" | "firefox";
+    /** Browser version string */
     browser_version: string;
+    /** Group/folder ID (if supported) */
     group_id?: string;
+    /** Local profile data path */
     profile_path: string;
+    /** User note */
     note: string;
+    /** ISO 8601 */
     created_at: string;
 }
+/** @deprecated Use IAntidetectProfile instead */
+type IGpmProfile = IAntidetectProfile;
 type IInputType = "text" | "number" | "boolean" | "select" | "textarea";
 type InputTypeMap = {
     text: string;
@@ -34,21 +52,178 @@ interface IInputField {
         value: string | number;
     }[];
 }
+interface IOutputField {
+    index: number;
+    key: string;
+    label: string;
+}
 interface IFlowConfig {
     globalInput: readonly IInputField[];
     profileInput: readonly IInputField[];
+    output?: readonly IOutputField[];
 }
+/**
+ * Generic duplicate finder cho string property — duyệt recursive qua array,
+ * extract giá trị của property `P` và check xem có xuất hiện > 1 lần không.
+ */
+type FindDuplicates<T extends readonly Record<string, any>[], P extends string, Seen extends string = never> = T extends readonly [
+    infer Head extends Record<string, any>,
+    ...infer Tail extends Record<string, any>[]
+] ? Head[P] extends string ? Head[P] extends Seen ? Head[P] | FindDuplicates<Tail, P, Seen> : FindDuplicates<Tail, P, Seen | Head[P]> : FindDuplicates<Tail, P, Seen> : never;
+/**
+ * Duplicate finder cho number property (dùng cho output index).
+ * Convert number → template literal string để so sánh.
+ */
+type FindDuplicateNumbers<T extends readonly Record<string, any>[], P extends string, Seen extends number = never> = T extends readonly [
+    infer Head extends Record<string, any>,
+    ...infer Tail extends Record<string, any>[]
+] ? Head[P] extends number ? Head[P] extends Seen ? Head[P] | FindDuplicateNumbers<Tail, P, Seen> : FindDuplicateNumbers<Tail, P, Seen | Head[P]> : FindDuplicateNumbers<Tail, P, Seen> : never;
+/**
+ * Duplicate finder cho string | number property (dùng cho options value).
+ */
+type FindDuplicateValues<T extends readonly Record<string, any>[], P extends string, Seen extends string | number = never> = T extends readonly [
+    infer Head extends Record<string, any>,
+    ...infer Tail extends Record<string, any>[]
+] ? Head[P] extends string | number ? Head[P] extends Seen ? Head[P] | FindDuplicateValues<Tail, P, Seen> : FindDuplicateValues<Tail, P, Seen | Head[P]> : FindDuplicateValues<Tail, P, Seen> : never;
+type AssertUniqueKeysAndLabels<T extends readonly {
+    key: string;
+    label: string;
+}[]> = FindDuplicates<T, "key"> extends never ? FindDuplicates<T, "label"> extends never ? T : readonly [
+    `❌ ERROR: Duplicate label(s) found: "${FindDuplicates<T, "label">}"`,
+    never
+] : FindDuplicates<T, "label"> extends never ? readonly [
+    `❌ ERROR: Duplicate key(s) found: "${FindDuplicates<T, "key">}"`,
+    never
+] : readonly [
+    `❌ ERROR: Duplicate key(s): "${FindDuplicates<T, "key">}" AND duplicate label(s): "${FindDuplicates<T, "label">}"`,
+    never
+];
+type AssertUniqueOutputFields<T extends readonly {
+    index: number;
+    key: string;
+    label: string;
+}[]> = FindDuplicateNumbers<T, "index"> extends never ? AssertUniqueKeysAndLabels<T> : readonly [
+    `❌ ERROR: Duplicate index(es) found: ${FindDuplicateNumbers<T, "index">}`,
+    never
+];
+/**
+ * Check 1 options array: label unique + value unique.
+ * Trả T nếu OK, error tuple nếu duplicate.
+ */
+type AssertUniqueOptions<T extends readonly {
+    label: string;
+    value: string | number;
+}[]> = FindDuplicates<T, "label"> extends never ? FindDuplicateValues<T, "value"> extends never ? T : readonly [
+    `❌ ERROR: Duplicate option value(s) found: "${FindDuplicateValues<T, "value">}"`,
+    never
+] : FindDuplicateValues<T, "value"> extends never ? readonly [
+    `❌ ERROR: Duplicate option label(s) found: "${FindDuplicates<T, "label">}"`,
+    never
+] : readonly [
+    `❌ ERROR: Duplicate option label(s): "${FindDuplicates<T, "label">}" AND duplicate option value(s): "${FindDuplicateValues<T, "value">}"`,
+    never
+];
+/**
+ * Map từng field trong input array — nếu field có `options`,
+ * validate options[].label + options[].value unique.
+ */
+type ValidateInputOptions<T extends readonly IInputField[]> = {
+    readonly [I in keyof T]: T[I] extends {
+        options: infer O extends readonly {
+            label: string;
+            value: string | number;
+        }[];
+    } ? Omit<T[I], "options"> & {
+        options: AssertUniqueOptions<O>;
+    } : T[I];
+};
+/**
+ * Validate unique key + label cho input array.
+ * Nếu key/label trùng → trả error tuple, ngược lại → validate options.
+ */
+type ValidateInputArray<T extends readonly IInputField[]> = FindDuplicates<T, "key"> extends never ? FindDuplicates<T, "label"> extends never ? ValidateInputOptions<T> : readonly [
+    `❌ ERROR: Duplicate label(s) found: "${FindDuplicates<T, "label">}"`,
+    never
+] : FindDuplicates<T, "label"> extends never ? readonly [
+    `❌ ERROR: Duplicate key(s) found: "${FindDuplicates<T, "key">}"`,
+    never
+] : readonly [
+    `❌ ERROR: Duplicate key(s): "${FindDuplicates<T, "key">}" AND duplicate label(s): "${FindDuplicates<T, "label">}"`,
+    never
+];
+/**
+ * StrictFlowConfig — kiểm tra tất cả constraints:
+ * - globalInput: unique key + label + options (label, value) per field
+ * - profileInput: unique key + label + options (label, value) per field
+ * - output: unique key + label + index
+ */
+type StrictFlowConfig<T extends IFlowConfig> = {
+    globalInput: ValidateInputArray<T["globalInput"]>;
+    profileInput: ValidateInputArray<T["profileInput"]>;
+    output: T["output"] extends readonly IOutputField[] ? AssertUniqueOutputFields<T["output"]> : T["output"];
+};
+/**
+ * Helper function — validate config at type level + return typed config.
+ * Dùng thay vì `as const satisfies IFlowConfig` để bắt duplicate key & label.
+ *
+ * @example
+ * ```ts
+ * // ✅ OK — không trùng
+ * const config = defineFlowConfig({
+ *   globalInput: [
+ *     { key: "url", label: "URL", type: "text" },
+ *   ],
+ *   profileInput: [
+ *     { key: "user", label: "User", type: "text" },
+ *   ],
+ *   output: [
+ *     { index: 0, key: "status", label: "Status" },
+ *     { index: 1, key: "title", label: "Title" },
+ *   ],
+ * });
+ *
+ * // ❌ TS Error — duplicate key "url" in globalInput
+ * const bad = defineFlowConfig({
+ *   globalInput: [
+ *     { key: "url", label: "URL 1", type: "text" },
+ *     { key: "url", label: "URL 2", type: "text" },
+ *   ],
+ *   ...
+ * });
+ *
+ * // ❌ TS Error — duplicate label "Status" in output
+ * const bad2 = defineFlowConfig({
+ *   output: [
+ *     { index: 0, key: "status1", label: "Status" },
+ *     { index: 1, key: "status2", label: "Status" },
+ *   ],
+ *   ...
+ * });
+ * ```
+ */
+declare function defineFlowConfig<const T extends IFlowConfig>(config: T & StrictFlowConfig<T>): T;
 type InferFields<T extends readonly IInputField[]> = {
     [K in T[number] as K["key"]]: K["type"] extends keyof InputTypeMap ? InputTypeMap[K["type"]] : unknown;
 };
 type InferGlobalInput<T extends IFlowConfig> = InferFields<T["globalInput"]>;
 type InferProfileInput<T extends IFlowConfig> = InferFields<T["profileInput"]>;
+/** Extract valid output keys từ config output[] — dùng cho type-safety writeOutput */
+type InferOutputKeys<T extends IFlowConfig> = T["output"] extends readonly IOutputField[] ? T["output"][number]["key"] : string;
+/** Extract valid profileInput keys từ config — dùng cho type-safety writeProfileInput */
+type InferProfileInputKeys<T extends IFlowConfig> = T["profileInput"] extends readonly IInputField[] ? T["profileInput"][number]["key"] : string;
+/**
+ * Infer output object type từ config output[].
+ * Map mỗi key → ProfileOutputValue | null (null nếu chưa ghi).
+ * Dùng cho context.output — truy cập trực tiếp output.isLogined, output.titlePage...
+ */
+type InferOutput<T extends IFlowConfig> = T["output"] extends readonly IOutputField[] ? {
+    [K in T["output"][number]["key"]]: _packages_shared.ProfileOutputValue | null;
+} : Record<string, _packages_shared.ProfileOutputValue | null>;
 interface IProfileSetting<TProfileInput = Record<string, unknown>> {
     profileName: string;
     data?: TProfileInput;
 }
 interface IAntidetectConfig<TProfileInput = Record<string, unknown>> {
-    name: string;
     profileSettings: IProfileSetting<TProfileInput>[];
 }
 interface IExecutionConfig {
@@ -56,6 +231,12 @@ interface IExecutionConfig {
     delayBetweenProfilesMs?: number;
     maxRetries?: number;
     keepOpenOnError?: boolean;
+    /**
+     * Which antidetect browser to use.
+     * ⚠️ Server/Agent only — Agent inject vào global trước khi chạy Worker.
+     * Dev mode: dùng constructor `super(AntidetectProvider.GPM, ...)` trong flow class.
+     */
+    antidetectProvider?: 'gpm' | 'hidemium' | 'genlogin' | 'adspower';
 }
 interface IBrowserWindowConfig {
     width: number;
@@ -67,6 +248,44 @@ interface IFlowRunParams<TConfig extends IFlowConfig = IFlowConfig> {
     execution: IExecutionConfig;
     window: IBrowserWindowConfig;
     globalInput?: InferGlobalInput<TConfig>;
+    /** Output definitions từ flow config — dùng để validate writeOutput key */
+    outputDefinitions?: IOutputField[];
+    /**
+     * Existing output entries từ lần chạy trước (lấy từ active output slot trên server).
+     * Mỗi entry = 1 profile, `data` chứa cipher/JSON của tất cả output keys.
+     * SDK nạp vào context.output để flow script đọc giá trị cũ trực tiếp.
+     */
+    existingOutputEntries?: _packages_shared.IOutputSlotEntry[];
+}
+interface IEncryptedProfileSetting {
+    profileName: string;
+    /** AES-256-GCM cipher (base64) chứa toàn bộ profile fields */
+    data?: string;
+}
+interface IEncryptedAntidetectConfig {
+    name: string;
+    profileSettings: IEncryptedProfileSetting[];
+}
+/**
+ * Params truyền từ Server → Agent khi dispatch flow.
+ * profiles[].data và globalInput đều ở dạng encrypted string.
+ * Agent decrypt trước khi chuyển thành IFlowRunParams để pass vào Worker.
+ */
+interface IEncryptedFlowRunParams {
+    antidetect: IEncryptedAntidetectConfig;
+    execution: IExecutionConfig;
+    window: IBrowserWindowConfig;
+    globalInput?: Record<string, unknown> | {
+        data: string;
+    };
+    /** Output definitions từ flow config — truyền nguyên (không encrypt) */
+    outputDefinitions?: IOutputField[];
+    /**
+     * Existing output entries từ active output slot.
+     * Server gửi nguyên bản — mỗi entry = { profileName, data (cipher/JSON) }.
+     * Agent decrypt `data` → parse JSON → build context.output.
+     */
+    existingOutputEntries?: _packages_shared.IOutputSlotEntry[];
 }
 type FlowLogLevel = "info" | "warn" | "error" | "debug" | "success";
 interface IFlowLogEntry {
@@ -85,21 +304,42 @@ interface ILogger {
     debug(message: string, context?: LogContext): void;
     success(message: string, context?: LogContext): void;
     logWithProfile(level: string, message: string, profileName: string, context?: LogContext): void;
+    postOutput(outputType: "output" | "profileInput", key: string, value: _packages_shared.ProfileOutputValue, profileName: string, opts?: {
+        outputIndex?: number;
+        outputLabel?: string;
+    }): void;
 }
 interface IScriptContext<TConfig extends IFlowConfig = IFlowConfig> {
     browser: Browser;
     page: Page;
-    profile: IGpmProfile;
+    profile: IAntidetectProfile;
     index: number;
     globalInput: InferGlobalInput<TConfig>;
     profileInput: InferProfileInput<TConfig>;
+    /**
+     * Output values cho profile hiện tại.
+     * Được pre-populate từ existing output entries (lần chạy trước).
+     * Truy cập trực tiếp: output.isLogined, output.titlePage...
+     * Giá trị null nếu key chưa được ghi.
+     * writeOutput() sẽ cập nhật object này real-time.
+     */
+    output: InferOutput<TConfig>;
     logger: ILogger;
 }
+/**
+ * Internal context — extends IScriptContext with SDK-internal fields.
+ * Flow developers KHÔNG cần biết fields này.
+ * Chỉ dùng nội bộ trong BrowserUtils, BaseFlow.
+ */
+interface IScriptContextInternal<TConfig extends IFlowConfig = IFlowConfig> extends IScriptContext<TConfig> {
+    /** Output definitions từ flow config — dùng để validate writeOutput key */
+    outputDefinitions?: IOutputField[];
+}
 interface IBrowserAdapter {
     open(profileName: string, index: number, windowConfig?: IBrowserWindowConfig): Promise<{
         browser: Browser;
         page: Page;
-        profile: IGpmProfile;
+        profile: IAntidetectProfile;
     }>;
     close(profileId: string): Promise<void>;
 }
@@ -141,6 +381,83 @@ interface IGpmListProfilesParams {
     search?: string[];
 }
 
+/**
+ * Config cho 1 file Excel — dùng cho cả inputFile và outputFile.
+ * @template TKeys — union of valid key strings (autocomplete từ flow config)
+ */
+interface IExcelFileConfig<TKeys extends string> {
+    /** Đường dẫn tuyệt đối hoặc relative (relative → resolve cùng cấp caller) */
+    filePath: string;
+    /** Sheet index (0-based), mặc định 0 */
+    sheetIndex?: number;
+    /** Cột chứa tên profile, mặc định "A" */
+    profileNameColumn?: string;
+    /** Mapping: column letter → key. VD: { "B": "fa2Code", "C": "email" } */
+    columns: Record<string, TKeys>;
+}
+/**
+ * Config tổng cho ExcelStorage.
+ * Có thể chỉ có inputFile, chỉ có outputFile, hoặc cả hai.
+ * Nếu 2 file trùng filePath → dùng chung 1 file Excel (chỉ khác cột).
+ */
+interface IExcelStorageConfig<TProfileInputKeys extends string = string, TOutputKeys extends string = string> {
+    /** File chứa profileInput — đọc bằng parseProfileSettings(), writeProfileInput ghi lại */
+    inputFile?: IExcelFileConfig<TProfileInputKeys>;
+    /** File chứa output — writeOutput ghi vào đây */
+    outputFile?: IExcelFileConfig<TOutputKeys>;
+}
+declare class ExcelStorage<TProfileInputKeys extends string = string, TOutputKeys extends string = string> {
+    private readonly config;
+    private readonly callerDir;
+    constructor(config: IExcelStorageConfig<TProfileInputKeys, TOutputKeys>, callerDir?: string);
+    /**
+     * Đọc Excel inputFile → trả về IProfileSetting[].
+     * Mỗi row = 1 profile, profileName lấy từ cột profileNameColumn,
+     * data lấy từ các cột đã mapping.
+     */
+    parseProfileSettings(): Promise<IProfileSetting[]>;
+    /**
+     * Ghi output value vào outputFile.
+     * Tìm row theo profileName, ghi value vào cột tương ứng với key.
+     */
+    writeOutputRow(profileName: string, key: TOutputKeys, value: ProfileOutputValue): Promise<void>;
+    /**
+     * Ghi profileInput value vào inputFile.
+     * Tìm row theo profileName, ghi value vào cột tương ứng với key.
+     */
+    writeProfileInputRow(profileName: string, key: TProfileInputKeys, value: string | number | boolean): Promise<void>;
+    /**
+     * Đọc tất cả output cho 1 profile → trả về JSON object.
+     * Mỗi key trong outputFile.columns → 1 field trong kết quả.
+     */
+    readOutputForProfile(profileName: string): Promise<Record<TOutputKeys, ProfileOutputValue | null>>;
+    get hasOutputFile(): boolean;
+    get hasInputFile(): boolean;
+    /**
+     * Ghi 1 giá trị vào cell Excel.
+     * Tìm row theo profileName, nếu không tìm thấy thì tạo row mới.
+     */
+    private writeCell;
+    /**
+     * Convert column mapping object → array of { colNumber, key } for easier iteration.
+     */
+    private buildColumnMap;
+    /**
+     * Lấy giá trị cell — handle các kiểu ExcelJS cell value.
+     */
+    private getCellValue;
+    /**
+     * Serialize ProfileOutputValue → cell value.
+     * Array / Object → JSON string, primitive → giữ nguyên.
+     */
+    private serializeValue;
+    /**
+     * Lazy load exceljs — tránh crash nếu không install.
+     * Handle CJS/ESM interop: dynamic import có thể trả { default: ExcelJS } hoặc ExcelJS trực tiếp.
+     */
+    private loadExcelJS;
+}
+
 declare abstract class BaseFlow<TConfig extends IFlowConfig = IFlowConfig> {
     protected logger: ILogger;
     protected browserAdapter: IBrowserAdapter;
@@ -152,9 +469,17 @@ declare abstract class BaseFlow<TConfig extends IFlowConfig = IFlowConfig> {
     run(params: IFlowRunParams<TConfig>): Promise<void>;
     protected processProfileWithRetry(setting: IProfileSetting<Partial<InferProfileInput<TConfig>>>, index: number, params: IFlowRunParams<TConfig>): Promise<void>;
     private processProfile;
-    abstract script(context: IScriptContext<TConfig>): Promise<unknown>;
+    abstract script(context: IScriptContext<TConfig>): Promise<undefined>;
     createProfileSetting(profileName: string, data?: Partial<InferProfileInput<TConfig>>): IProfileSetting<Partial<InferProfileInput<TConfig>>>;
     createRunParams(params: IFlowRunParams<TConfig>): IFlowRunParams<TConfig>;
+    /**
+     * Tạo ExcelStorage với type-safe column mapping.
+     * TS tự gợi ý key values từ config.profileInput và config.output.
+     *
+     * @param config — inputFile / outputFile config với column mapping
+     * @param callerDir — thư mục gốc để resolve relative path (mặc định: cwd)
+     */
+    createExcelStorage(config: IExcelStorageConfig<InferProfileInputKeys<TConfig>, InferOutputKeys<TConfig>>, callerDir?: string): ExcelStorage<InferProfileInputKeys<TConfig>, InferOutputKeys<TConfig>>;
 }
 type FlowRunParams<T extends BaseFlow<any>> = T extends BaseFlow<infer TConfig> ? IFlowRunParams<TConfig> : never;
 type FlowProfileSetting<T extends BaseFlow<any>> = T extends BaseFlow<infer TConfig> ? IProfileSetting<Partial<InferProfileInput<TConfig>>> : never;
@@ -162,7 +487,8 @@ type FlowProfileSetting<T extends BaseFlow<any>> = T extends BaseFlow<infer TCon
 declare enum AntidetectProvider {
     GPM = "gpm",
     HIDEMIUM = "hidemium",
-    GENLOGIN = "genlogin"
+    GENLOGIN = "genlogin",
+    ADSPOWER = "adspower"
 }
 declare abstract class AntidetectBaseFlow<TConfig extends IFlowConfig = IFlowConfig> extends BaseFlow<TConfig> {
     protected provider: AntidetectProvider;
@@ -197,16 +523,85 @@ declare class GpmStandaloneAdapter implements IBrowserAdapter {
     open(profileName: string, index: number, windowConfig: IBrowserWindowConfig): Promise<{
         browser: puppeteer.Browser;
         page: puppeteer.Page;
-        profile: IGpmProfile;
+        profile: IAntidetectProfile;
     }>;
     close(profileId: string): Promise<void>;
     closeAll(delayBetweenMs?: number): Promise<void>;
 }
 
-declare class BrowserUtils {
+interface IHidemiumProfile {
+    uuid: string;
+    name: string;
+    os: string;
+    browser: string;
+    version: string;
+    proxy: string;
+    resolution: string;
+    note: string;
+    created_at: string;
+}
+interface IHidemiumStartResult {
+    remote_port: number;
+    web_socket: string;
+    profile_path: string;
+    uuid: string;
+}
+interface IHidemiumListParams {
+    page?: number;
+    limit?: number;
+    search?: string;
+    orderName?: number;
+}
+interface IHidemiumCreateProfileParams {
+    name: string;
+    os?: "win" | "mac" | "lin" | "android";
+    browser?: "chrome" | "brave" | "edge" | "opera";
+    version?: string;
+    resolution?: string;
+    userAgent?: string;
+    language?: string;
+}
+declare class HidemiumService {
+    private api;
+    private apiUrl;
+    constructor(apiUrl?: string);
+    startProfile(uuid: string, command?: string, proxy?: string, maxRetries?: number, delayMs?: number): Promise<IHidemiumStartResult | null>;
+    stopProfile(uuid: string, maxRetries?: number, delayMs?: number): Promise<boolean>;
+    getProfiles(params?: IHidemiumListParams, isLocal?: boolean): Promise<IHidemiumProfile[]>;
+    createProfile(config: IHidemiumCreateProfileParams, isLocal?: boolean): Promise<any>;
+    deleteProfiles(uuids: string[]): Promise<boolean>;
+    updateProxy(uuid: string, proxy: string): Promise<boolean>;
+    checkHealth(): Promise<boolean>;
+    connectToBrowser(wsUrl: string, maxRetries?: number, delayMs?: number): Promise<Browser>;
+}
+
+declare class HidemiumStandaloneAdapter implements IBrowserAdapter {
+    private apiUrl;
+    private screenResolution;
+    readonly service: HidemiumService;
+    private readonly openedProfiles;
+    private readonly pendingProfiles;
+    private readonly logger;
+    private readonly boundLoggers;
+    constructor(logger: ILogger);
+    private getBoundLogger;
+    open(profileName: string, index: number, windowConfig: IBrowserWindowConfig): Promise<{
+        browser: puppeteer.Browser;
+        page: puppeteer.Page;
+        profile: IAntidetectProfile;
+    }>;
+    close(profileId: string): Promise<void>;
+    closeAll(delayBetweenMs?: number): Promise<void>;
+}
+
+declare class BrowserUtils<TConfig extends IFlowConfig = IFlowConfig> {
     private ctx;
     private logger;
-    constructor(context: IScriptContext);
+    /** Output definitions từ flow config — dùng để validate writeOutput key */
+    private readonly outputDefs;
+    /** Set chứa các key hợp lệ — build 1 lần từ outputDefs */
+    private readonly validOutputKeys;
+    constructor(context: IScriptContext<TConfig>);
     private checkAbort;
     sleep(ms: number): Promise<void>;
     waitForElement(selector: string, timeout?: number, scope?: Frame): Promise<ElementHandle | null>;
@@ -233,9 +628,45 @@ declare class BrowserUtils {
     switchToTabIndex(index: number): Promise<puppeteer.Page | null>;
     closeCurrentTab(): Promise<void>;
     closeOtherTabs(): Promise<void>;
+    /**
+     * Close ALL tabs (including the current one).
+     * Useful for full cleanup before flow ends.
+     */
+    closeAllTabs(): Promise<void>;
+    /**
+     * Switch back to the default (initial) page — the page stored in context.
+     * Typically used after switchToPopup() to return to the main tab.
+     */
+    switchToDefault(): Promise<puppeteer.Page>;
     logConfig(config: Record<string, unknown>, label?: string): Promise<void>;
     logProfileInput(): Promise<void>;
+    /**
+     * Log toàn bộ output hiện tại (bao gồm cả giá trị từ lần chạy trước và giá trị mới ghi).
+     * Dùng để debug — xem giá trị output hiện tại.
+     */
+    logProfileOutput(): Promise<void>;
     logGlobalInput(): Promise<void>;
+    /**
+     * Ghi kết quả tự do cho profile đang chạy.
+     * Gửi qua kênh riêng (type: "profile_output") — không lẫn log.
+     * Đồng thời log ra console/UI để flow dev dễ debug.
+     *
+     * ⚠️ Key phải được định nghĩa trong config.output[] — nếu không sẽ throw Error.
+     *
+     * value hợp lệ:
+     * - string | number | boolean
+     * - array tối đa 20 phần tử (primitive)
+     * - object 1 cấp tối đa 10 entry (value phải là primitive)
+     */
+    writeOutput(key: InferOutputKeys<TConfig>, value: ProfileOutputValue): Promise<void>;
+    /**
+     * Cập nhật lại một field trong profileInput của profile đang chạy.
+     * key phải là field đã được định nghĩa trong profileInput schema.
+     * Kết quả được gửi về server để update AgentFlowConfig sau khi execution xong.
+     */
+    writeProfileInput(key: InferProfileInputKeys<TConfig>, value: string | number | boolean): Promise<void>;
+    private sanitizeOutputValue;
+    private dispatchOutput;
     private shortSelector;
     private log;
     private actionDelay;
@@ -246,6 +677,7 @@ declare class FlowLogger extends EventEmitter implements ILogger {
     private _context?;
     private parentPort;
     private readonly isWorker;
+    private excelStorage;
     constructor(_context?: string | undefined);
     private serialize;
     private dispatch;
@@ -259,8 +691,19 @@ declare class FlowLogger extends EventEmitter implements ILogger {
     debug(message: string, context?: LogContext): void;
     custom(label: string, message: string, color?: string): void;
     logWithProfile(level: IWorkerLogMessage["level"], message: string, profileName: string, context?: LogContext): void;
-    createBoundLogger(profileName: string): ILogger;
+    createBoundLogger(profileName: string): ILogger & {
+        muted: boolean;
+    };
     profileEvent(profileName: string, message: string, status: ProfileStatus, context?: LogContext): void;
+    private buildOutputMsg;
+    postOutput(outputType: "output" | "profileInput", key: string, value: IWorkerOutputMessage["value"], profileName: string, opts?: {
+        outputIndex?: number;
+        outputLabel?: string;
+    }): void;
+    /**
+     * Attach ExcelStorage — FlowLogger sẽ tự ghi Excel khi postOutput (dev mode).
+     */
+    setExcelStorage(storage: ExcelStorage<any, any>): void;
 }
 
-export { AntidetectBaseFlow, AntidetectProvider, BaseFlow, BrowserUtils, type FlowLogLevel, FlowLogger, type FlowProfileSetting, type FlowRunParams, GpmStandaloneAdapter, type IAntidetectConfig, type IBrowserAdapter, type IBrowserWindowConfig, type IExecutionConfig, type IFlowConfig, type IFlowLogEntry, type IFlowRunParams, type IGpmListProfilesParams, type IGpmProfile, type IGpmRes, type IGpmResListProfile, type IGpmStartProfileParams, type IInputField, type ILogger, type IProfileSetting, type IResGpmStartProfileData, type IScriptContext, type InferGlobalInput, type InferProfileInput, type LogContext };
+export { AntidetectBaseFlow, AntidetectProvider, BaseFlow, BrowserUtils, ExcelStorage, type FlowLogLevel, FlowLogger, type FlowProfileSetting, type FlowRunParams, GpmStandaloneAdapter, HidemiumService, HidemiumStandaloneAdapter, type IAntidetectConfig, type IAntidetectProfile, type IBrowserAdapter, type IBrowserWindowConfig, type IEncryptedAntidetectConfig, type IEncryptedFlowRunParams, type IEncryptedProfileSetting, type IExcelFileConfig, type IExcelStorageConfig, type IExecutionConfig, type IFlowConfig, type IFlowLogEntry, type IFlowRunParams, type IGpmListProfilesParams, type IGpmProfile, type IGpmRes, type IGpmResListProfile, type IGpmStartProfileParams, type IHidemiumCreateProfileParams, type IHidemiumListParams, type IHidemiumProfile, type IHidemiumStartResult, type IInputField, type ILogger, type IOutputField, type IProfileSetting, type IResGpmStartProfileData, type IScriptContext, type IScriptContextInternal, type InferGlobalInput, type InferOutput, type InferOutputKeys, type InferProfileInput, type InferProfileInputKeys, type LogContext, type StrictFlowConfig, defineFlowConfig };