/**
 * @module helpers.web
 *
 * helper functions specific to the web version.
 */
import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
import { MetaspaceService } from "@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs";
import { RawExportIbGib_V1 } from "@ibgib/core-gib/dist/common/import-export/import-export-types.mjs";
import { FlatIbGibGraph } from "@ibgib/core-gib/dist/common/other/graph-types.mjs";
import { IbGibSpaceAny } from "@ibgib/core-gib/dist/witness/space/space-base-v1.mjs";
/**
 * converts string to Uint8Array.
 * @param str to convert
 * @returns array
 */
export declare function stringToUint8Array(str: string): Uint8Array;
/**
 * converts Uint8Array to string.
 * @param array to convert
 * @returns string
 */
export declare function uint8ArrayToString(array: Uint8Array): string;
/**
 * I'm pulling out node from @ibgib/ibgib rcli code. This interface is just to
 * aid in that transition.
 */
export interface PathUtilsHelper {
    isAbsolute(path: string): boolean;
    isRelative(path: string): boolean;
    join(...paths: string[]): string;
    dirname(path: string): string;
    basename(path: string, ext?: string): string;
}
/**
 * Helper class that exposes pathUtils functions. Note that this is relative to
 * an individual space.
 */
export declare class PathUtilsHelper implements PathUtilsHelper {
    /** class-level log context */
    lc: string;
    /**
     *
     */
    /**
     *
     */
    constructor();
}
export declare function copyToClipboard({ data, logalot, }: {
    data: {
        title?: string;
        text?: string;
        url?: string;
    };
    logalot?: boolean;
}): Promise<void>;
/**
 * helper to trigger browser's share functionality (or fallback).
 */
export declare function shareContent({ data, logalot, }: {
    data: {
        title?: string;
        text?: string;
        url?: string;
    };
    logalot?: boolean;
}): Promise<void>;
/**
 * useful for knowing if we are executing in our website or within an iframe.
 *
 * ## driving use case
 *
 * When we are loading an embedded iframe for link-gib, it is trying to trigger
 * the router which is no bueno.
 *
 * This is causing a problem though when testing inside an iframe in Project
 * IDX...I guess I'll have to whitelist embedded sites like link-gib
 *
 * ## usage
 *
 * Put something like this in the html in <head>:
 * ```html
 * <meta name="ibgib-app-id-yo" content="0f73bca49d2856a446044768fbab8d25" />
 * ```
 * Then create constants like this (I put them in a constants file):
 *
 * ```typescript
 * export const HTML_META_APP_ID_NAME = "ibgib-app-id-yo";
 * export const HTML_META_APP_ID_CONTENT = "0f73bca49d2856a446044768fbab8d25";
 * ```
 *
 * Then you can call this like this:
 *
 * ```typescript
 * const isInWebAppProper = isExecutingInBlankGibWebAppProper({
 *   metaName_appId: HTML_META_APP_ID_NAME,
 *   metaContent_appId: HTML_META_APP_ID_CONTENT
 * });
 * ```
 *
 * @returns true if we are executing in an iframe, false otherwise.
 */
export declare function isExecutingInBlankGibWebAppProper({ metaName_appId, metaContent_appId }: {
    /**
     * this runs code:
     *
     * `const metaElement = document.querySelector(`meta[name=${metaName_appId}]`) as (HTMLMetaElement | null);`
     *
     * in the index, you should tag the meta tag with attribute of this.
     */
    metaName_appId: string;
    /**
     * this is an appId on the `metaElement.content`
     */
    metaContent_appId: string;
}): boolean;
/**
 * Low-level plumbing for prompting the user for some text.
 *
 * ## notes
 *
 * * if an empty string is entered, confirm is automatic/always happens.
 * * if confirm is true, will confirm on any entry
 * * can just hit ENTER to confirm anything
 *   * this should be parameterized
 *
 * @returns the text the user entered.
 */
export declare function promptForText({ msg, title, confirm, noNewLine, rl, defaultValue, dontCloseRl, cancelable, }: {
    msg: string;
    title?: string;
    confirm?: boolean;
    noNewLine?: boolean;
    /**
     * ignored in web version. used in node version. this is after all, a hack
     * port
     */
    rl?: any;
    defaultValue?: string;
    /**
     * ignored in web version. used in node version. this is after all, a hack
     * port
     */
    dontCloseRl?: boolean;
    /**
     * if true, cancel will show and an empty string will be returned
     */
    cancelable?: boolean;
}): Promise<string>;
import { KeystonePasskeyEntry } from "@ibgib/core-gib/dist/keystone/keystone-types.mjs";
export interface AuthoritySecretResult {
    secret: string;
    poolId: string;
}
/**
 * Prompts the user for a secret, supporting both master password and passkey/hardware authenticators.
 */
export declare function promptForSecret({ msg, confirm, passkeys, }: {
    msg?: string;
    confirm: boolean;
    passkeys?: Record<string, KeystonePasskeyEntry>;
}): Promise<string>;
/**
 * Unified authority prompt that inspects the candidate pools on a keystone and prompts the user
 * to authorize via either Master Password or a specific Passkey.
 * Returns both the verified secret and the exact signingPoolId to use for keystone operations.
 */
export declare function promptForAuthoritySecret({ keystone, aggregatedDetails, title, msg, verb, }: {
    keystone: any;
    aggregatedDetails?: any;
    title?: string;
    msg?: string;
    verb?: string;
}): Promise<AuthoritySecretResult>;
/**
 * prompt specifically looking to confirm something. if "cancelled", returns
 * false.
 */
export declare function promptForConfirm({ msg, yesLabel, noLabel, }: {
    /**
     * if provided, this is the message displayed when confirming.
     */
    msg?: string;
    yesLabel?: string;
    noLabel?: string;
}): Promise<boolean>;
export declare function alertUser({ msg, title, skipHitEnterToContinue, }: {
    msg: string;
    title?: string;
    /**
     * ignored in web version atow (12/2024)
     */
    skipHitEnterToContinue?: boolean;
}): Promise<void>;
export declare function getUserPreferredColorScheme(): 'light' | 'dark';
/**
 * helper function to get a query param in the current url.
 *
 * # ONLY IN BROWSER
 *
 * not for use in node.js
 *
 * @returns raw
 */
export declare function getQueryParam<TValue>({ paramName, parseJSON, logalot, }: {
    paramName: string;
    parseJSON?: boolean;
    logalot?: boolean;
}): TValue | undefined;
/**
 * helper function to set a query param in the current url.
 *
 * # ONLY IN BROWSER
 *
 * not for use in node.js
 */
export declare function setQueryParam<TValue>({ paramName, paramValue, rmParam, logalot, }: {
    paramName: string;
    paramValue?: TValue;
    /**
     * if true, we will remove the param from the URL.
     */
    rmParam?: boolean;
    logalot?: boolean;
}): void;
/**
 * helper to highlight an element with border/background.
 *
 * ## requires
 *
 * .highlight and .unhighlight classes
 *
 * The unhighlight is for correctly showing the transition/animation.
 *
 * ## intent
 *
 * Just making this to make highlighting things (drawing the user's eye)
 * easier and more consistent.
 *
 * @see {@link unhighlightElement}
 */
export declare function highlightElement({ el, magicHighlightTimingMs, scrollIntoView, }: {
    el: HTMLElement;
    /**
     * if provided, will unhighlight the element after this delay in ms
     */
    magicHighlightTimingMs?: number;
    scrollIntoView?: boolean;
}): Promise<void>;
/**
 * @see {@link highlightElement}
 */
export declare function unhighlightElement({ el, }: {
    el: HTMLElement;
}): Promise<void>;
/**
 * Takes an incoming string. Assumes it's invalid. Does best effort at validating this.
 * Gets the raw export ibgib if it can. If so, and if it is compressed, decompresses the
 * compressed graph contained in the export ibgib.
 *
 * @returns RawExportIbGib_V1 and its decompressed graph
 */
export declare function getRawExportIbGibAndGraphFromJsonString({ exportIbGibJsonString, metaspace, }: {
    exportIbGibJsonString: string;
    metaspace: MetaspaceService;
}): Promise<[RawExportIbGib_V1, FlatIbGibGraph]>;
/**
 * exports a given ibgib to the default local userspace in the metaspace.
 */
export declare function exportIbGib({ ibGib, compress, metaspace, space, }: {
    ibGib: IbGib_V1;
    compress: boolean;
    metaspace: MetaspaceService;
    space: IbGibSpaceAny;
}): Promise<void>;
export declare function promptForAPIKey({ msg, }: {
    /**
     * msg to tell the user when prompting for the API key (secret)
     *
     * originally in blankgib, this is CHAT_WITH_AGENT_NEED_API_KEY
     */
    msg: string;
}): Promise<string | undefined>;
/**
 * updates the given {@link apiKey}. if {@link force} is true and `apiKey` is
 * empty, then this will set an empty string for the apiKey, effectively
 * deleting it.
 */
export declare function updateAPIKeyInStorage({ dbName, storeName, key, apiKey, force, }: {
    dbName: string;
    storeName: string;
    key: string;
    apiKey: string;
    force: boolean;
}): Promise<void>;
/**
 * wrapper for simplifying/asserting an element that is expected to exist.
 *
 * ## intent
 *
 * This avoids using TypeScript truthy assertions (!) or excessive
 * falsy/exception checks.
 */
export declare function getElementById_throwsIfFalsy<TElement extends Element>({ id, shadowRoot, }: {
    id: string;
    /**
     * If set, will get element here, else will use document
     */
    shadowRoot?: ShadowRoot;
}): TElement;
/**
 * wrapper that throws if element not found.
 * @param id of Element
 * @returns Element of type TElement or throws.
 * @see {@link shadowRoot_getElementById}
 *
 * ## intent
 *
 * This avoids using TypeScript truthy assertions (!) or excessive
 * falsy/exception checks.
 */
export declare function document_getElementById<TElement extends Element = HTMLElement>(id: string): TElement;
/**
 * wrapper that throws if element not found.
 * @param shadowRoot in which the element MUST be truthy or throws
 * @param id of Element
 * @returns Element of type TElement or throws.
 * @see {@link document_getElementById}
 *
 * ## intent
 *
 * This avoids using TypeScript truthy assertions (!) or excessive
 * falsy/exception checks.
 */
export declare function shadowRoot_getElementById<TElement extends Element = HTMLElement>(shadowRoot: ShadowRoot, id: string): TElement;
export declare function getGlobalStoreName(): string;
export declare function getGlobalDbName(): string;
export declare function getGlobalIndexedDbKey_APIKey(): string;
/**
 * helper info for {@link initAppStorage}
 */
interface AppStorageInfo {
    dbName: string;
    storeNames: string[];
}
/**
 * ensures db and stores are created and can be used.
 */
export declare function initAppStorage({ infos, }: {
    infos: AppStorageInfo[];
}): Promise<void>;
export {};
//# sourceMappingURL=helpers.web.d.mts.map