import type { URL } from 'url';

export interface EventSdk {
  config: typeof config;
  get: typeof get;
  set: typeof set;
  /** Flush event delivery for calls that have completed. Await operations first. */
  flushEvents(): Promise<void>;
}

/**
 * Create an explicitly instrumented SDK client using connected Armor. config() remains synchronous;
 * get()/set() preserve their results and errors. Plain SDK calls are unchanged.
 */
export function withEvents(): EventSdk;

export interface DotenvParseOptions {
  /**
   * Override any environment variables that have already been set on your machine with values from your .env file.
   * @default false
   * @example require('@dotenvx/dotenvx').config({ overload: true })
   * @alias overload
   */
  overload?: boolean;

  /**
   * @default false
   * @alias override
   */
  override?: boolean;

  /**
   * Specify an object to read existing environment variables from. Defaults to process.env environment variables.
   *
   * @default process.env
   * @example const processEnv = {}; require('@dotenvx/dotenvx').parse('HELLO=World', { processEnv: processEnv })
   */
  processEnv?: DotenvPopulateInput;

  /**
   * Specify a privateKey to decrypt any encrypted contents with.
   *
   * @default undefined
   * @example require('@dotenvx/dotenvx').parse('HELLO="encrypted:BE9Y7LKANx77X1pv1HnEoil93fPa5c9rpL/1ps48uaRT9zM8VR6mHx9yM+HktKdsPGIZELuZ7rr2mn1gScsmWitppAgE/1lVprNYBCqiYeaTcKXjDUXU5LfsEsflnAsDhT/kWG1l"', { privateKey: 'a4547dcd9d3429615a3649bb79e87edb62ee6a74b007075e9141ae44f5fb412c' })
   */
  privateKey?: string;
}

export interface DotenvParseOutput {
  [name: string]: string;
}

/**
 * Parses a string or buffer in the .env file format into an object.
 *
 * @see https://dotenvx.com/docs
 * @param src - contents to be parsed. example: `'DB_HOST=localhost'`
 * @param options - additional options. example: `{ processEnv: {}, privateKey: '<privateKey>', overload: false }`
 * @returns an object with keys and values based on `src`. example: `{ DB_HOST : 'localhost' }`
 */
export function parse<T extends DotenvParseOutput = DotenvParseOutput>(
  src: string | Buffer,
  options?: DotenvParseOptions
): T;

export interface DotenvConfigOptions {

  /**
   * Specify explicit env sources. When set, `path` and `convention` are ignored.
   *
   * @default undefined
   * @example require('@dotenvx/dotenvx').config({ envs: [{ type: 'envFile', value: '.env' }] })
   * @example require('@dotenvx/dotenvx').config({ envs: [{ type: 'env', value: 'HELLO=World', privateKeyName: 'DOTENV_PRIVATE_KEY' }] })
   */
  envs?: DotenvConfigEnv[];

  /**
   * Specify a custom path if your file containing environment variables is located elsewhere.
   * Can also be an array of strings, specifying multiple paths.
   *
   * @default require('path').resolve(process.cwd(), '.env')
   * @example require('@dotenvx/dotenvx').config({ path: '/custom/path/to/.env' })
   * @example require('@dotenvx/dotenvx').config({ path: ['/path/to/first.env', '/path/to/second.env'] })
   */
  path?: string | string[] | URL;

  /** Select a named Envfile profile when no explicit paths are supplied. */
  profile?: string;

  /**
   * Specify the encoding of your file containing environment variables.
   *
   * @default 'utf8'
   * @example require('@dotenvx/dotenvx').config({ encoding: 'latin1' })
   */
  encoding?: string;

  /**
   * Override any environment variables that have already been set on your machine with values from your .env file.
   * @default false
   * @example require('@dotenvx/dotenvx').config({ overload: true })
   * @alias overload
   */
  overload?: boolean;

  /**
   * @default false
   * @alias override
   */
  override?: boolean;

  /**
   * Throw immediately if an error is encountered - like a missing .env file.
   * Includes Envfile validation failures. Envfile strict settings also enforce throwing.
   * @default false
   * @example require('@dotenvx/dotenvx').config({ strict: true })
   */
  strict?: boolean;

  /**
   * Suppress specific errors like MISSING_ENV_FILE. The error keys can be found
   * in src/lib/helpers/errors.js
   * @default []
   * @example require('@dotenvx/dotenvx').config({ ignore: ['MISSING_ENV_FILE'] })
   */
  ignore?: string[];

  /**
   * Specify an object to write your secrets to. Defaults to process.env environment variables.
   *
   * @default process.env
   * @example const processEnv = {}; require('@dotenvx/dotenvx').config({ processEnv: processEnv })
   */
  processEnv?: DotenvPopulateInput;

  /**
   * Mask resolved values, optionally setting the number of visible characters.
   * @default false
   * @example require('@dotenvx/dotenvx').config({ mask: true })
   * @example require('@dotenvx/dotenvx').config({ mask: 0 })
   */
  mask?: boolean | number;

  /**
   * Customize the path to your .env.keys file. This is useful with monorepos.
   * @default []
   * @example require('@dotenvx/dotenvx').config({ envKeysFile: '../../.env.keys'} })
   */
  envKeysFile?: string;

  /**
   * Legacy option retained for compatibility.
   *
   * @default undefined
   * @example require('@dotenvx/dotenvx').config({ DOTENV_KEY: 'dotenv://:key_1234…' })
   */
  DOTENV_KEY?: string;

  /**
   * Load a .env convention (available conventions: 'nextjs, flow')
   */
  convention?: string;

  /**
   * Turn on logging to help debug why certain keys or values are not being set as you expect.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').config({ debug: process.env.DEBUG })
   */
  debug?: boolean;

  verbose?: boolean;

  quiet?: boolean;

  /**
   * Disable spinner output from child Dotenvx Armor commands.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').config({ noSpinner: true })
   */
  noSpinner?: boolean;

  /**
   * Set Armor token.
   *
   * @example require('@dotenvx/dotenvx').config({ token: process.env.DOTENVX_ARMOR_TOKEN })
   */
  token?: string;

  logLevel?:
    | 'error'
    | 'warn'
    | 'success'
    | 'info'
    | 'help'
    | 'verbose'
    | 'debug';

  /**
   * Turn off Dotenvx Armor features.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').config({ noArmor: true })
   */
  noArmor?: boolean;

  /**
   * Turn off OS secret store features.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').config({ noNative: true })
   */
  noNative?: boolean;

  /**
   * Turn off 1Password secret reference resolution.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').config({ no1Password: true })
   */
  no1Password?: boolean;

  /**
   * Turn off Bitwarden secret reference resolution.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').config({ noBitwarden: true })
   */
  noBitwarden?: boolean;

}

export type DotenvConfigEnv =
  | DotenvConfigEnvFile
  | DotenvConfigEnvSrc;

export interface DotenvConfigEnvFile {
  type: 'envFile';
  value: string | URL;
}

export interface DotenvConfigEnvSrc {
  type: 'env';
  value: string | Buffer;
  privateKeyName?: string;
}

export interface DotenvConfigOutput {
  error?: Error;
  parsed?: DotenvParseOutput;
}

export interface DotenvPopulateInput {
  [name: string]: string;
}

/**
 * Loads `.env` file contents into process.env by default.
 * Reads Envfile from the current directory and validates the final resolved environment.
 * Validation failures warn and return an error, or throw when strictness is enabled.
 * Invalid Envfile syntax always throws.
 * With an Envfile, subsequent Node stdout/stderr writes are automatically redacted.
 * Environment and returned values remain unchanged; native writes and inherited child output bypass redaction.
 *
 * @see https://dotenvx.com/docs
 *
 * @param options - additional options. example: `{ path: './custom/path', encoding: 'latin1', debug: true, overload: false }`
 * @returns an object with a `parsed` key if successful or `error` key if an error occurred. example: { parsed: { KEY: 'value' } }
 *
 */
export function config(options?: DotenvConfigOptions): DotenvConfigOutput;

export interface SetOptions {
  /**
   * Specify a custom path if your file containing environment variables is located elsewhere.
   * Can also be an array of strings, specifying multiple paths.
   *
   * @default require('path').resolve(process.cwd(), '.env')
   * @example require('@dotenvx/dotenvx').set(key, value, { path: '/custom/path/to/.env' })
   * @example require('@dotenvx/dotenvx').set(key, value, { path: ['/path/to/first.env', '/path/to/second.env'] })
   */
  path?: string | string[] | URL;

  /** Select a named Envfile profile when no explicit paths are supplied. */
  profile?: string;

  /**
   * Customize the path to your .env.keys file. This is useful with monorepos.
   * @default []
   * @example require('@dotenvx/dotenvx').config(key, value, { envKeysFile: '../../.env.keys'} })
   */
  envKeysFile?: string;

  /**
   * Set a .env convention (available conventions: 'nextjs, flow')
   */
  convention?: string;

  /**
   * Specify whether the variable has to be encrypted
   * @default true
   * @example require('@dotenvx/dotenvx').config(key, value, { encrypt: false } })
   */
  encrypt?: boolean;

  /**
   * Turn off Dotenvx Armor features.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').set(key, value, { noArmor: true })
   */
  noArmor?: boolean;

  /**
   * Turn off OS secret store features.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').set(key, value, { noNative: true })
   */
  noNative?: boolean;

  /** Disable 1Password custody and secret-reference resolution. */
  no1Password?: boolean;

  /** Disable Bitwarden custody and secret-reference resolution. */
  noBitwarden?: boolean;

}

export type SetProcessedEnv = {
  key: string;
  value: string;
  filepath: string;
  envFilepath: string;
  envSrc: string;
  changed: boolean;
  encryptedValue?: string;
  publicKey?: string;
  privateKey?: string;
  localPrivateKeyAdded?: boolean;
  nativePrivateKeyAdded?: boolean;
  remotePrivateKeyAdded?: boolean;
  privateKeyName?: string;
  error?: Error;
};

export type SetOutput = {
  processedEnvs: SetProcessedEnv[];
  changedFilepaths: string[];
  unchangedFilepaths: string[];
};

/**
 * Set a single environment variable.
 *
 * @see https://dotenvx.com/docs
 * @param key - KEY 
 * @param value - value
 * @param options - additional options. example: `{ encrypt: false }`
 */
export function set(
  key: string,
  value: string,
  options?: SetOptions
): Promise<SetOutput>;

export interface GetOptions {

  /** Include all process environment variables when no key is supplied. */
  all?: boolean;

  /** Format the returned values when no key is supplied. */
  format?: 'eval' | 'eval-export' | 'shell' | 'colon';

  /**
   * Specify a custom path if your file containing environment variables is located elsewhere.
   * Can also be an array of strings, specifying multiple paths.
   *
   * @default require('path').resolve(process.cwd(), '.env')
   * @example require('@dotenvx/dotenvx').get('KEY', { path: '/custom/path/to/.env' })
   * @example require('@dotenvx/dotenvx').get('KEY', { path: ['/path/to/first.env', '/path/to/second.env'] })
   */
  path?: string | string[] | URL;

  /** Select a named Envfile profile when no explicit paths are supplied. */
  profile?: string;

  /**
   * Mask returned values, optionally setting the number of visible characters.
   * @default false
   * @example require('@dotenvx/dotenvx').get('KEY', { mask: true })
   * @example require('@dotenvx/dotenvx').get('KEY', { mask: 0 })
   */
  mask?: boolean | number;

  /**
   * Suppress specific errors like MISSING_ENV_FILE. The error keys can be found
   * in src/lib/helpers/errors.js
   * @default []
   * @example require('@dotenvx/dotenvx').get('KEY', { ignore: ['MISSING_ENV_FILE'] })
   */
  ignore?: string[];

  /**
   * Override any environment variables that have already been set on your machine with values from your .env file.
   * @default false
   * @example require('@dotenvx/dotenvx').get('KEY', { overload: true })
   * @alias overload
   */
  overload?: boolean;

  /**
   * Customize the path to your .env.keys file. This is useful with monorepos.
   * @default []
   * @example require('@dotenvx/dotenvx').get('KEY', { envKeysFile: '../../.env.keys'} })
   */
  envKeysFile?: string;

  /**
   * Throw immediately if an error is encountered - like a missing .env file.
   * @default false
   * @example require('@dotenvx/dotenvx').get('KEY', { strict: true })
   */
  strict?: boolean;

  /**
   * Turn off Dotenvx Armor features.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').get('KEY', { noArmor: true })
   */
  noArmor?: boolean;

  /**
   * Turn off OS secret store features.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').get('KEY', { noNative: true })
   */
  noNative?: boolean;

  /**
   * Turn off 1Password secret reference resolution.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').get('KEY', { no1Password: true })
   */
  no1Password?: boolean;

  /**
   * Turn off Bitwarden secret reference resolution.
   *
   * @default false
   * @example require('@dotenvx/dotenvx').get('KEY', { noBitwarden: true })
   */
  noBitwarden?: boolean;

}

/**
 * Get a single environment variable.
 *
 * @see https://dotenvx.com/docs
 * @param key - KEY 
 * @param options - additional options. example: `{ overload: true }`
 */
export function get(
  key: string,
  options?: GetOptions
): Promise<string>;

/**
 * Synchronously resolve an environment variable without modifying process.env.
 * Blocks while files and providers are resolved. Uses the same options as get().
 *
 * @example require('@dotenvx/dotenvx').getSync('KEY', { path: '.env.credentials' })
 */
export function getSync(
  key: string,
  options?: GetOptions
): string | undefined;
export function getSync(
  key: undefined,
  options: GetOptions & { format: NonNullable<GetOptions['format']> }
): string;
export function getSync(
  key?: undefined,
  options?: GetOptions & { format?: undefined }
): Record<string, string>;
export function getSync(
  key: string | undefined,
  options?: GetOptions
): string | Record<string, string> | undefined;

/**
 * List all env files in the current working directory
 *
 * @param directory - current working directory
 * @param envFile - glob pattern to match env files
 * @param excludeEnvFile - glob pattern to exclude env files
 * @param onDirectory - called as each directory is traversed
 */
export function ls(
  directory: string,
  envFile: string | string[],
  excludeEnvFile: string | string[],
  onDirectory?: (directory: string) => void
): Promise<string[]>;