import type { XOInvitationVariableValue, XOTemplate } from '@xo-cash/types';

/**
 * Supported decode modes for compiled CashAssembly evaluation bytes.
 */
export type CompiledCashAssemblyDecodeMode = 'utf8' | 'hex' | 'boolean' | 'bigint' | 'uint8array';

/**
 * Template script map passed into CashAssembly compilation so evaluations can resolve bare script ids.
 */
export type CashAssemblyTemplateScripts = NonNullable<XOTemplate['scripts']>;

/**
 * WalletData and template context shared by CashAssembly compilation.
 */
export type CompileCashAssemblyContext = {

    /**
     * Runtime WalletData keyed by variable name.
     * {@link compileCashAssemblySourceToBytes} collects required names with
     * {@link collectVariablesUsingParseScript} then looks them up here for
     * primitive method resolution and CashAssembly compilation. A collected name that is absent throws
     * {@link CashAssemblyRequiredVariableMissingError}. Missing keys are never replaced with defaults.
     */
    variables: Record<string, XOInvitationVariableValue | Uint8Array>;

    /**
     * Template variable definitions. When provided, each `<name.method>` push whose `hint` maps to
     * a supported primitive class is resolved to bytes before CashAssembly compilation.
     */
    templateVariables?: XOTemplate['variables'] | undefined;

    /**
     * Named CashAssembly scripts from {@link XOTemplate.scripts}.
     * Each key is a script id such as `scriptA`. Each value is that script's source.
     * Pass this when compilation refers to those ids, for example `$(scriptA)`, `scriptA`, or
     * `scriptA scriptB OP_ADD`. The compiler looks up those ids here. The visitor collects
     * WalletData from those sources and from nested ids.
     * When omitted, named scripts are not given to the compiler and only WalletData pushes in the
     * starting text are collected.
     */
    templateScripts?: CashAssemblyTemplateScripts | undefined;
};

/**
 * Parameters for compiling CashAssembly text.
 */
export type CompileCashAssemblyStringParameters = CompileCashAssemblyContext & {

    /**
     * Text to compile, which may contain `$()`.
     *
     * When this text contains `$()`, each CashAssembly evaluation is compiled and replaced with its
     * decoded payload. Surrounding text is kept.
     * When this text contains no `$()`, the entire string is compiled as CashAssembly so push
     * opcodes remain.
     */
    cashAssemblyText: string;

    /**
     * The mode to decode compiled bytecode into a string.
     */
    evaluationDecodeMode?: CompiledCashAssemblyDecodeMode;
};

/**
 * Parameters for compiling one CashAssembly source string to bytecode.
 */
export type CompileCashAssemblySourceToBytesParameters = CompileCashAssemblyContext & {

    /**
     * Evaluation or CashAssembly source passed to the compiler as a script id.
     */
    cashAssemblySource: string;
};

/**
 * Parameters for compiling one CashAssembly source string to decoded text.
 */
export type CompileCashAssemblySourceToDecodedTextParameters = CompileCashAssemblySourceToBytesParameters & {

    /**
     * The mode to decode compiled bytecode into a string.
     */
    evaluationDecodeMode: CompiledCashAssemblyDecodeMode;
};

/**
 * Parameters for preparing a Libauth compiler for CashAssembly source strings.
 */
export type CompileCashAssemblyEvaluationsParameters = {

    /**
     * CashAssembly source strings such as `$(<var1>)` or `scriptA`.
     */
    evaluations: string[];

    /**
     * Optional template scripts so nested ids compile to the template sources.
     */
    templateScripts?: CashAssemblyTemplateScripts | undefined;

    /**
     * WalletData names already collected with {@link collectVariablesUsingParseScript}.
     * This function does not collect again.
     */
    variableNames: string[];
};