/**
 * @module api-function-info.template is a template for implementing api function infos (obviously).
 *
 * ## notes
 *
 * ### ordering imports
 *
 * import sections always go:
 * 1. non-ibgib deps first (rare)
 * 2. @ibgib/helper-gib, @ibgib/encrypt-gib, @ibgib/ts-gib, @ibgib/core-gib packages (in that order)
 * 3. import GLOBAL_LOG_A_LOT then remaining project imports
 * 4. code proper starts with the definition of `const logalot` (if applicable)
 *
 * There is a blank line between these sections.
 *
 */


import { extractErrorMsg, pretty } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
// import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
// import { rel8 } from "@ibgib/ts-gib/dist/V1/transforms/rel8.mjs";
// import { getIbAndGib, getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
// import { IbGibAddr, TransformResult } from "@ibgib/ts-gib/dist/types.mjs";
// import { isPrimitive } from "@ibgib/ts-gib/dist/V1/index.mjs";
// import { toDto } from "@ibgib/core-gib/dist/common/other/ibgib-helper.mjs";

import { GLOBAL_LOG_A_LOT } from "../../../constants.mjs";
import { APIFunctionInfo } from "../../api-types.mjs";
import { COMMAND_BASE_SCHEMA_PROPERTIES } from "../command-constants.mjs";
import { getCommandService } from "../command-service-v1.mjs";
import { CommandDataBase } from "../command-types.mjs";
import { FUNCTION_CALL_EXAMPLES_HEADER } from "../../api-constants.mjs";
// import { getGlobalMetaspace_waitIfNeeded } from "../../../helpers.mjs";

const logalot = GLOBAL_LOG_A_LOT;

// #region constants

/**
 * camelCased name of the command itself.
 */
const FUNCTION_NAME = 'fooBar';

/**
 * fooCategory could be 'agent', 'renderable', etc. It's the broad command which
 * basically acts like a category of commands at this point.
 *
 * If an agent is generating this, ask me what this should be before going forward.
 */
const CMD_CATEGORY = 'fooCategory';
/**
 * fooBar here is the specific command modifier which narrows down to a command
 * instance, similar to a fully curried function.
 *
 * This should be camelCased actual name of the function.
 */
const CMD_MODIFIERS: string[] = [FUNCTION_NAME];

const EXAMPLE_INPUT_FOOBAR: Partial<FooBarOpts> = {
    fooArgString: 'This is an example string',
    fooArgArray: 'This is an example string',
    notesToSelf: `Example of a ${FUNCTION_NAME} function call.`,
    repromptWithResult: false,
};
const EXAMPLES = [
    // `\`\`\`typescript\n${FUNCTION_CALL_EXAMPLES_HEADER}\n${pretty(EXAMPLE_INPUT_FOOBAR)}\n\`\`\``,
    FUNCTION_CALL_EXAMPLES_HEADER,
    pretty(EXAMPLE_INPUT_FOOBAR),
].join('\n');
const FUNCTION_DESCRIPTION = [
    `Enter the description here.`,
    '',
    EXAMPLES,
].join('\n');
// #endregion constants

/**
 * @interface FooBarOpts - Options for the fooBar command.
 *
 * @extends CommandDataBase
 */
export interface FooBarOpts extends CommandDataBase<typeof CMD_CATEGORY, typeof CMD_MODIFIERS> {
    /**
     * @property fooArgString - always include the docs here in the opts interface
     */
    fooArgString: string;
    /**
     * @property fooArgArray - always include the docs here in the opts interface
     */
    fooArgArray: string;
}

/**
 * @interface FooBarCommandData - Command data for the fooBar command.
 * @extends CommandDataBase
 */
export interface FooBarCommandData extends CommandDataBase<'agent', ['fooBar']> {
    /**
     * @see {@link FooBarOpts.fooArgString}
     */
    fooArgString: string;
    /**
     * @see {@link FooBarOpts.fooArgArray}
     */
    fooArgArray: string;
}

/**
 * Wrapper function to enqueue the fooBar command.
 * @param {FooBarOpts} opts - @see {@link FooBarOpts}
 * @returns {Promise<void>} A promise that resolves when the command finishes execution.
 */
function fooBarViaCmd(opts: FooBarOpts): Promise<void> {
    const commandService = getCommandService();
    const command: FooBarCommandData = {
        cmd: CMD_CATEGORY,
        cmdModifiers: CMD_MODIFIERS,
        fooArgString: opts.fooArgString,
        fooArgArray: opts.fooArgArray,
        repromptWithResult: opts.repromptWithResult,
        notesToSelf: opts.notesToSelf,
    };
    return new Promise<void>((resolve, reject) => {
        commandService.enqueueCommand({ command, resolve, reject });
    });
}

/**
 * Implementation function for the fooBar command.
 *
 * @param {FooBarOpts} opts - @see {@link FooBarOpts}
 * @returns {Promise<void>} A promise that resolves when the command is executed.
 */
async function fooBarImpl(opts: FooBarOpts): Promise<void> {
    const lc = `[${fooBarImpl.name}]`;
    try {
        if (logalot) { console.log(`${lc} starting... (I: 0d2c484b8141cc0b52c0f69213791826)`); }

        console.log(`${lc} ${CMD_CATEGORY} ${CMD_MODIFIERS} opts: ${pretty(opts)}`);

        // actual implementation goes here

    } catch (error) {
        console.error(`${lc} ${extractErrorMsg(error)}`);
        throw error;
    } finally {
        if (logalot) { console.log(`${lc} complete.`); }
    }
}

/**
 * example of OpenAPI shape of a string declaration
 */
const GEMINI_SCHEMA_FOO_ARG_STRING = {
    type: 'string',
    description: 'fooArgString is a prop that...',
}

function getGeminiArraySchemaOfItem({
    itemSchema,
    description,
}: {
    itemSchema: any,
    description: string,
}): any {
    return {
        type: 'array',
        description,
        items: itemSchema,
    };
}

const GEMINI_SCHEMA_FOO_ARG_ARRAY_ITEM = {
    type: 'object',
    description: 'fooArgArray item is an item that...',
    properties: {
        someString: GEMINI_SCHEMA_FOO_ARG_STRING,
    },
    required: ['someString'],
}

const GEMINI_SCHEMA_FOO_ARG_ARRAY = getGeminiArraySchemaOfItem({
    itemSchema: GEMINI_SCHEMA_FOO_ARG_ARRAY_ITEM,
    description: 'fooArgArray is a prop that...',
});

/**
 * API function info for the fooBar command.
 */
export const fooBarFunctionInfo: APIFunctionInfo<typeof fooBarViaCmd> = {
    nameOrId: FUNCTION_NAME,
    fnViaCmd: fooBarViaCmd,
    functionImpl: fooBarImpl,
    cmd: CMD_CATEGORY,
    cmdModifiers: CMD_MODIFIERS,
    schema: {
        name: FUNCTION_NAME,
        description: FUNCTION_DESCRIPTION,
        parameters: {
            type: 'object',
            properties: {
                ...COMMAND_BASE_SCHEMA_PROPERTIES,
                fooArgString: GEMINI_SCHEMA_FOO_ARG_STRING,
                fooArgArray: GEMINI_SCHEMA_FOO_ARG_ARRAY,
            },
            required: [
                'fooArgString', // comment out/remove if optional
                'fooArgArray', // comment out/remove if optional
            ],
        },
    },
};