import { RunEnvironment } from "./enums";

/**
 * ## Description
 * In the context of a job, extendTimeout will increase the timeout of the currently executing payload.
 * This is useful when the payload is expected to take a long time. For example, when running pagination code.
 *
 * @example
 * ```typescript Example
 * import { extendTimeout } from "@intuned/sdk/runtime"
 *
 * extendTimeout();
 * ```
 *
 */
export declare function extendTimeout(): void;

/**
 * ## Description
 * In the context of a job or queue execution, extendPayload appends new payloads to the end of the queue of job.
 * Calling extendPayload will also call extendTimeout.
 *
 * @param {Payload | Payload[]} payload - The payload or array of payloads to extend. you can specify the api name and what parameters you want to pass it, the new added apis will use the same proxy and auth-session settings as the api that extended them
 *
 * @example
 * ```typescript Single payload
 * import { extendPayload } from "@intuned/sdk/runtime"
 *
 * // this function will append the exampleApi to the end of the queue or job it's executing in.
 * extendPayload({ api: 'exampleApi', parameters: { key: 'value' } });
 * ```
 *
 * @example
 * ```typescript Array of payloads
 * import { extendPayload } from "@intuned/sdk/runtime"
 *
 * const payloadArray: Payload[] = [
 *   { api: 'exampleApi1', parameters: { key1: 'value1' } },
 *   { api: 'exampleApi2', parameters: { key2: 'value2' } }
 * ];
 *
 * // this function will append 2 apis to the end of the queue or job it's executing in.
 * extendPayload(payloadArray);
 * ```
 */
export declare function extendPayload(payload: Payload | Payload[]): void;

/**
 * @interface Payload
 * @property {string} api - The API path you want to extend.
 * @property {Record<string, any>} parameters - A record of key-value pairs representing the parameters to be sent to the API
 *
 * @example
 *
 * ```typescript payload
 * import { Payload } from "@intuned/sdk/runtime"
 *
 * const payload: Payload = {
 *   api: 'exampleApi',
 *   parameters: {
 *     key1: 'value1',
 *     key2: 'value2'
 *   }
 * };
 * ```
 */
export interface Payload {
  api: string;
  parameters: Record<string, any>;
}

/**
 * Retrieves information about the current run environment.
 *
 * @returns {RunInfo} An object containing details about the run environment and the run ID.
 *
 * @example
 * ```typescript runInfo
 * import { runInfo } from "@intuned/sdk/runtime"
 *
 * const info = runInfo();
 * console.log(info.runEnvironment); // Outputs the run environment, IDE or DEPLOYED
 * console.log(info.runId); // Outputs the run ID, if available, in IDE run id will be undefined
 * ```
 */
export declare function runInfo(): RunInfo;

/**
 * Represents information about the current run.
 *
 * @interface RunInfo
 * @property {RunEnvironment} runEnvironment - the run environment `IDE` or `DEPLOYED`
 * @property {string} [runId] - Optional. The ID of the current run, in IDE environment, run id will be undefined
 */
export interface RunInfo {
  runEnvironment: RunEnvironment;
  runId?: string;
  jobId?: string;
  jobRunId?: string;
  queueId?: string;
  proxy?: string;
  authSessionId?: string;
}

/**
 * @interface RunErrorOptions
 * @property {boolean} [retryable] - Optional. Indicates whether the error is retryable.
 * @property {number} [status_code] - Optional. The HTTP status code associated with the error.
 * @property {string} [error_code] - Optional. A specific error code to identify the type of error.
 *
 * @example
 * ```typescript RunErrorOptions
 * import { RunErrorOptions } from "@intuned/sdk/runtime"
 *
 * const options: RunErrorOptions = {
 *   retryable: true,
 *   status_code: 500,
 *   error_code: 'SERVER_ERROR'
 * };
 * ```
 */
export interface RunErrorOptions {
  retryable?: boolean;
  status_code?: number;
  error_code?: string;
}

/**
 * @deprecated This error is deprecated. it will be treated like any normal error
 *
 * Represents an error that occurs during a run.
 *
 * @class
 * @extends Error
 *
 * @param {string} message - The error message.
 * @param {RunErrorOptions} [options] - Optional. Additional options for the error.
 *
 * @property {RunErrorOptions} options - The options associated with the error.
 *
 * @example
 * ```typescript RunError
 * import { RunError } from "@intuned/sdk/runtime"
 *
 * throw new RunError('An error occurred', {
 *   retryable: true,
 *   status_code: 500,
 *   error_code: 'SERVER_ERROR'
 * });
 *
 * ```
 */
export declare class RunError extends Error {
  constructor(message: string, options?: RunErrorOptions);
  options: RunErrorOptions;
}

/**
 * Retrieves the parameters for the authentication session currently being used.
 *
 * @returns {AuthSessionParameters} An object containing the parameters for the current authentication session.
 *
 * @example
 * ```typescript getAuthSessionParameters
 * import { getAuthSessionParameters } from "@intuned/sdk/runtime"
 *
 * const authSessionParams = getAuthSessionParameters();
 * console.log(authSessionParams);
 * ```
 */
export declare function getAuthSessionParameters(): Promise<any>;

/**
 * @interface AttemptStore
 * @property {function} get - Retrieves a value from the store by key
 * @property {function} set - Sets a value in the store by key
 *
 * @example
 * ```typescript AttemptStore usage
 * import { attemptStore } from "@intuned/sdk/runtime"
 *
 * // Set a value in the store
 * attemptStore.set('openAiClient', openaiClient);
 *
 * // Get a value from the store
 * const openAiClient = attemptStore.get('openAiClient');
 * ```
 */
export interface AttemptStore {
  /**
   * Retrieves a value from the store by key.
   *
   * @param {string} key - The key to retrieve the value for
   * @returns {any} The value associated with the key, or undefined if not found
   */
  get(key: string): any;

  /**
   * Sets a value in the store by key.
   *
   * @param {string} key - The key to set the value for
   * @param {any} value - The value to store
   * @throws {Error} Throws an error if the store operation fails
   */
  set(key: string, value: any): void;
}

/**
 * ## Description
 * A persistent key-value store that maintains data within the execution context.
 * This store allows you to share data between different parts of your API execution.
 *
 * @example
 * ```typescript AttemptStore usage
 * import { attemptStore } from "@intuned/sdk/runtime"
 *
 * // Set a value in the store
 * store.set('openAiClient', openaiClient);
 *
 * // Get a value from the store
 * const openAiClient = attemptStore.get('openAiClient');
 * openAiClient.doSomething();
 *
 * // Handle missing values
 * const missingData = attemptStore.get('nonexistent'); // undefined
 * ```
 */
export declare const attemptStore: AttemptStore;

/**
 * @interface PersistentStore
 * @property {function} get - Retrieves a value from the store by key
 * @property {function} set - Sets a value in the store by key
 *
 * @example
 * ```typescript PersistentStore usage
 * import { persistentStore } from "@intuned/sdk/runtime"
 *
 * // Set a value in the store
 * persistentStore.set('data', { foo: 'bar' });
 *
 * // Get a value from the store
 * await persistentStore.get('data');
 * ```
 */
export interface PersistentStore {
  /**
   * Retrieves a value from the store by key.
   *
   * @param {string} key - The key to retrieve the value for
   * @returns {any} The value associated with the key, or undefined if not found
   */
  get(key: string): Promise<any>;

  /**
   * Sets a value in the store by key.
   *
   * @param {string} key - The key to set the value for
   * @param {any} value - The value to store
   * @throws {Error} Throws an error if the store operation fails
   */
  set(key: string, value: any): Promise<void>;
}

/**
 * ## Description
 * A persistent key-value store that maintains data within the execution context.
 * This store allows you to share data between different API executions.
 *
 * @example
 * ```typescript PersistentStore usage
 * import { persistentStore } from "@intuned/sdk/runtime"
 *
 * // Set a value in the store
 * persistentStore.set('data', { foo: 'bar' });
 *
 * // Get a value from the store
 * await persistentStore.get('data');
 *
 * // Handle missing values
 * const missingData = await persistentStore.get('nonexistent'); // undefined
 * ```
 */
export declare const persistentStore: PersistentStore;