@cavi-ai/api-client/core/env

export declare const GLOBAL_REPO_ROOT_KEY: "__CAVI_REPO_ROOT__";

export type HttpApiEnvSource = Record<string, string | undefined>;

export type HttpApiSurfaceConfig = {
    baseUrl: string;
    authToken: string | null;
    clientId: string;
};

/** Fallback env-var names checked (in order) when the primary key is unset. */
export type HttpSurfaceEnvAliases = {
    baseUrl?: readonly string[];
    authToken?: readonly string[];
    clientId?: readonly string[];
};

/** Last-resort values used when neither the primary nor any alias env var is set. */
export type HttpSurfaceEnvFallback = {
    baseUrl: string;
    authToken?: string | null;
    clientId: string;
};

/** Primary env-var names for one HTTP surface. */
export type HttpSurfaceEnvKeys = {
    baseUrl: string;
    authToken: string;
    clientId: string;
};

export type HttpSurfaceEnvSpec = {
    keys: HttpSurfaceEnvKeys;
    aliases?: HttpSurfaceEnvAliases;
    fallback: HttpSurfaceEnvFallback;
};

export declare const REPO_ROOT_ENV_KEY: "REPO_ROOT";

export type RepoRootEnv = Record<string, string | undefined>;

export declare function requireRepoRoot(options?: ResolveRepoRootOptions): string;

/**
 * Resolve a single HTTP surface's config from an env bag.
 * Precedence per field: primary key → aliases → caller `defaults` → spec `fallback`.
 */
export declare function resolveHttpSurfaceConfigFromEnv(env: HttpApiEnvSource, spec: HttpSurfaceEnvSpec, options?: ResolveHttpSurfaceConfigOptions): HttpApiSurfaceConfig;

export type ResolveHttpSurfaceConfigOptions = {
    defaults?: Partial<HttpApiSurfaceConfig>;
    trimValues?: boolean;
    includeAliases?: boolean;
};

export declare function resolveRepoRoot(options?: ResolveRepoRootOptions): string | null;

export type ResolveRepoRootOptions = {
    repoRoot?: string | null;
    env?: RepoRootEnv;
    globalRepoRoot?: string | null;
};