import { LoadedNpmrcConfig } from './npmrc.js';
/**
 * Joins up to 8 items, appending `<overflow>N more` for the rest — the
 * uniform truncation for user-facing lists of packages, versions and
 * reasons.
 */
export declare function capList(items: string[], separator: string, overflow: string): string;
/** Quotes and joins a list of names for a message. */
export declare function quotedList(names: string[]): string;
/** Stand-in for a URL that cannot be shown without risking a credential. */
export declare const UNPRINTABLE_URL = "(withheld: unparseable and may contain credentials)";
/**
 * Rebuilds a URL from the parts that cannot carry a credential, so it can
 * safely appear in error messages and logs.
 *
 * Only scheme and host survive. Userinfo, path, query and fragment are
 * dropped by construction rather than stripped: a registry URL may embed a
 * token in its userinfo, a pre-signed CDN URL puts its signature in the
 * query, and some registries take a token as a PATH segment
 * (`https://host/<token>/npm/`). The path is the component least worth
 * keeping anyway — every message that shows a URL already names the
 * package and version separately, which is what the path encodes.
 *
 * A string that does not parse, parses without a host, or names a scheme
 * nothing here fetches over yields the placeholder instead — deliberately
 * the same rule as what may be requested, so a URL is echoable exactly when
 * it was fetchable. Earlier revisions tried to redact such strings with
 * a regex and leaked a credential four times over as many review rounds —
 * through the first `@` only, through an empty userinfo, through a
 * host-less parse, and through an authority that did not start at offset
 * zero. Nothing short of a parser can tell userinfo from a path in a
 * malformed string, so this follows the precedent already set for proxy
 * URLs in `rest/errors.ts` and declines to echo it at all. Callers name the
 * configuration key and file that produced the value instead, which is
 * where the reader would go to look anyway.
 */
export declare function redactUrl(url: string): string;
/**
 * Where the credentials sent with a request came from: a nerf-darted
 * config entry, or userinfo embedded in the URL itself.
 *
 * The `url` case carries a whole `UrlOrigin` rather than mirroring its
 * members, because the two must agree on every variant and a hand-kept
 * copy did not: a variant added to `UrlOrigin` alone once reported
 * registry-issued credentials as coming from a config line that contained
 * none. Reusing the type makes the compiler enforce what review had to.
 */
export type SentCredentials = {
    from: 'config';
    keys: string[];
} | {
    from: 'url';
    origin: UrlOrigin;
};
/**
 * Where a tarball URL came from: the lockfile recorded it verbatim, the
 * registry returned it in this package's metadata, or the CLI built it from
 * a registry. `registryKey` is absent when nothing configured one and the
 * public npm registry was assumed.
 *
 * Read both to attribute credentials the URL itself carries and to say
 * which setting produced a URL nothing can be fetched from — and the two
 * answers differ, so the variants are not interchangeable: a metadata URL
 * is the registry's to fix, not the project's.
 */
export type UrlOrigin = RecordedUrlOrigin | {
    registryKey?: string;
};
/**
 * A URL this CLI did not compose: something else handed it over already
 * formed, so it can be unusable however it likes.
 *
 * A URL the CLI builds itself cannot be. The registry it is built from is
 * checked first, and appending a path to a URL that parses with a host
 * leaves both intact — so those origins never reach a message about an
 * unusable URL, and are not in this type.
 */
export type RecordedUrlOrigin = {
    lockfile: string;
} | {
    metadata: {
        registryKey?: string;
    };
};
/**
 * Says where an unusable URL came from, and therefore whose it is to fix.
 * The advice has to match the branch: telling someone to correct their
 * registry setting when the bad value came out of the lockfile sends them
 * to a setting that is already correct.
 */
export declare function describeUnusableUrlOrigin(origin: RecordedUrlOrigin, npmrc: LoadedNpmrcConfig): string;
/** What a redirect did to the credentials on a request. */
export interface RedirectOutcome {
    /** The host the request was last redirected to. */
    host?: string;
    /** True when credentials were sent but did not survive the hop. */
    credentialsDropped?: boolean;
}
/**
 * Names config keys and where they came from, for a hint sentence. Keys are
 * listed individually because precedence is per key: the halves of a
 * `username`/`_password` pair can come from different sources.
 */
export declare function describeConfigKeys(keys: string[], npmrc: LoadedNpmrcConfig): string;
/**
 * Explains an HTTP failure that authentication could account for.
 *
 * 404 gets the same treatment as 401/403 because registries routinely hide
 * packages the caller is not authorized to see behind a 404 — npmjs does —
 * which otherwise reads as "this package does not exist" and sends people
 * looking in entirely the wrong place. The wording stays hedged for 404,
 * where a genuinely missing package is equally likely.
 *
 * Whenever credentials were sent, the message names where they came from.
 * They can come from any of several files or an environment variable, so
 * "your credentials were rejected" without saying which source supplied
 * them leaves the reader exactly as stuck as a bare 404.
 */
export declare function downloadFailureHint(status: number | undefined, sent: SentCredentials | undefined, npmrc: LoadedNpmrcConfig, redirect?: RedirectOutcome): string;
/**
 * Names any config file that existed but could not be read, as a sentence
 * with a leading space or the empty string.
 *
 * Worth saying on any failure a credential could explain, not only the ones
 * that got as far as a status code: a skipped `auth.ini` is invisible
 * otherwise, and it is the likeliest thing to be missing when a private
 * package cannot be resolved at all.
 */
export declare function describeUnreadableConfig(npmrc: LoadedNpmrcConfig): string;