/**
 * Maintainer information.
 */
interface Maintainer {
    /** Maintainer name */
    readonly name: string;
    /** Maintainer email */
    readonly email?: string;
}
/**
 * Version-specific information from a registry.
 */
interface VersionInfo {
    /** Version string */
    readonly version: string;
    /** ISO date when published */
    readonly publishedAt: string;
    /** Tarball URL */
    readonly tarball: string;
    /** Subresource integrity hash */
    readonly integrity?: string;
    /** Runtime dependencies */
    readonly dependencies?: Record<string, string>;
    /** Development dependencies */
    readonly devDependencies?: Record<string, string>;
    /** Peer dependencies */
    readonly peerDependencies?: Record<string, string>;
    /** Optional peer dependencies */
    readonly optionalDependencies?: Record<string, string>;
    /** Engine requirements */
    readonly engines?: Record<string, string>;
    /** Node.js version range */
    readonly nodeVersion?: string;
    /** npm version used to publish */
    readonly npmVersion?: string;
    /**
     * Git commit hash at publish time.
     * Used to determine commit range for changelog generation.
     *
     * NOTE: This value comes from npm registry, making it immutable
     * and independent of local git state.
     */
    readonly gitHead?: string;
}
/**
 * Inputs for {@link createVersionInfo}.
 */
interface CreateVersionInfoOptions {
    /** Semver version string (e.g., '1.2.3') */
    version: string;
    /** ISO 8601 timestamp of publication */
    publishedAt: string;
    /** URL to the package tarball */
    tarball: string;
    /** Subresource integrity hash */
    integrity?: string;
    /** Production dependencies map */
    dependencies?: Record<string, string>;
    /** Development dependencies map */
    devDependencies?: Record<string, string>;
    /** Peer dependencies map */
    peerDependencies?: Record<string, string>;
    /** Optional dependencies map */
    optionalDependencies?: Record<string, string>;
    /** Engine requirements (Node/npm) */
    engines?: Record<string, string>;
    /** Node.js version used during publish */
    nodeVersion?: string;
    /** npm version used during publish */
    npmVersion?: string;
    /** Git commit hash at publish time */
    gitHead?: string;
}
/**
 * Creates a new VersionInfo object.
 *
 * @param options - Configuration for the release info
 * @param options.version - e.g., '1.2.3' or '2.0.0-beta.1'
 * @param options.publishedAt - ISO 8601 timestamp of publication
 * @param options.tarball - URL to the package tarball
 * @param options.integrity - Subresource integrity hash
 * @param options.dependencies - Production dependencies map
 * @param options.devDependencies - Development dependencies map
 * @param options.peerDependencies - Peer dependencies map
 * @param options.optionalDependencies - Optional dependencies map
 * @param options.engines - Node/npm engine requirements
 * @param options.nodeVersion - Node.js version used during publish
 * @param options.npmVersion - npm version used during publish
 * @param options.gitHead - Git commit hash at publish time
 * @returns A new VersionInfo object
 *
 * @example Creating version info from registry data
 * ```typescript
 * const release = createVersionInfo({
 *   version: '1.2.3',
 *   publishedAt: '2024-01-15T10:30:00Z',
 *   tarball: 'https://registry.npmjs.org/pkg/-/pkg-1.2.3.tgz'
 * })
 * ```
 */
declare function createVersionInfo(options: CreateVersionInfoOptions): VersionInfo;

/**
 * Package information from a registry.
 */
interface PackageInfo {
    /** Package name */
    readonly name: string;
    /** Package description */
    readonly description?: string;
    /** Latest version */
    readonly latestVersion: string;
    /** All published versions */
    readonly versions: readonly string[];
    /** SPDX license identifier */
    readonly license?: string;
    /** Repository URL */
    readonly repository?: string;
    /** Homepage URL */
    readonly homepage?: string;
    /** Package maintainers */
    readonly maintainers: readonly Maintainer[];
    /** Keywords */
    readonly keywords?: readonly string[];
    /** Time of last modification */
    readonly lastModified?: string;
}
/**
 * Inputs for {@link createPackageInfo}.
 */
interface CreatePackageInfoOptions {
    /** Package name, e.g., 'lodash' or '@scope/pkg' */
    name: string;
    /** The most recently published semver string */
    latestVersion: string;
    /** All published semver strings in chronological order */
    versions: readonly string[];
    /** Brief summary of package functionality */
    description?: string;
    /** SPDX license identifier */
    license?: string;
    /** URL to source code repository */
    repository?: string;
    /** URL to project homepage or documentation site */
    homepage?: string;
    /** List of maintainers with name and email */
    maintainers?: readonly Maintainer[];
    /** Search terms for npm registry discovery */
    keywords?: readonly string[];
    /** Time of last modification */
    lastModified?: string;
}
/**
 * Creates a new PackageInfo object.
 *
 * @param options - Configuration for the package info
 * @param options.name - e.g., 'lodash' or '@scope/pkg'
 * @param options.latestVersion - The most recently published semver string
 * @param options.versions - All published semver strings in chronological order
 * @param options.description - Brief summary of package functionality
 * @param options.license - SPDX license identifier
 * @param options.repository - URL to source code repository
 * @param options.homepage - URL to project homepage or documentation site
 * @param options.maintainers - List of maintainers with name and email
 * @param options.keywords - Search terms for npm registry discovery
 * @param options.lastModified - Time of last modification
 * @returns A new PackageInfo object
 *
 * @example Creating package info from registry data
 * ```typescript
 * const info = createPackageInfo({
 *   name: '@scope/my-package',
 *   latestVersion: '2.0.0',
 *   versions: ['1.0.0', '1.1.0', '2.0.0'],
 *   license: 'MIT'
 * })
 * ```
 */
declare function createPackageInfo(options: CreatePackageInfoOptions): PackageInfo;

/**
 * Abstract interface for package registries.
 */
interface Registry {
    /** Registry name (e.g., "npm", "yarn") */
    readonly name: string;
    /** Registry URL */
    readonly url: string;
    /**
     * Get the latest published version of a package.
     *
     * @param packageName - The package name to look up
     * @returns The latest version string, or null if not published
     */
    getLatestVersion(packageName: string): Promise<string | null>;
    /**
     * Check if a specific version is published.
     *
     * @param packageName - Name of the package to check (e.g., '@hyperfrontend/versioning')
     * @param version - Semver version string to verify (e.g., '1.2.3')
     * @returns True if the version is published
     */
    isVersionPublished(packageName: string, version: string): Promise<boolean>;
    /**
     * Get full package information.
     *
     * @param packageName - Name of the package to query (e.g., '@hyperfrontend/versioning')
     * @returns Package info, or null if not found
     */
    getPackageInfo(packageName: string): Promise<PackageInfo | null>;
    /**
     * Get version-specific information including publish time.
     *
     * @param packageName - Name of the package to query (e.g., '@hyperfrontend/versioning')
     * @param version - Semver version string to look up (e.g., '1.2.3')
     * @returns Version info, or null if not found
     */
    getVersionInfo(packageName: string, version: string): Promise<VersionInfo | null>;
    /**
     * List all published versions.
     *
     * @param packageName - Name of the package to query (e.g., '@hyperfrontend/versioning')
     * @returns Array of version strings
     */
    listVersions(packageName: string): Promise<readonly string[]>;
}
/**
 * Registry configuration options.
 */
interface RegistryConfig {
    /** Registry URL */
    readonly url?: string;
    /** Request timeout in milliseconds */
    readonly timeout?: number;
    /** Cache TTL in milliseconds */
    readonly cacheTtl?: number;
    /** Authentication token */
    readonly authToken?: string;
}

/**
 * Why a registry could not answer a lookup.
 *
 * Every value here means the answer is unknown, never that the package or
 * version is absent. An absent package is a successful lookup with a negative
 * answer, and is reported through the normal return value instead.
 */
type RegistryFailureReason = 'network' | 'authentication' | 'rate-limit' | 'server' | 'timeout' | 'unknown';
/** Name carried by every error this module raises, used to identify it across module boundaries. */
declare const REGISTRY_UNAVAILABLE_ERROR = "RegistryUnavailableError";
/**
 * Error raised when a registry lookup could not be completed.
 *
 * Distinct from a lookup that completed and found nothing: this means the
 * registry did not give an answer, so no release decision may be derived from
 * it.
 */
interface RegistryUnavailableError extends Error {
    /** Always {@link REGISTRY_UNAVAILABLE_ERROR}. */
    readonly name: string;
    /** Registry that was queried, for example `npm`. */
    readonly registry: string;
    /** Package the lookup was for. */
    readonly packageName: string;
    /** Client operation that failed, for example `getLatestVersion`. */
    readonly operation: string;
    /** Why the registry could not answer. */
    readonly reason: RegistryFailureReason;
}
/** Details identifying the failed lookup. */
interface RegistryUnavailableDetails {
    /** Registry that was queried, for example `npm`. */
    readonly registry: string;
    /** Package the lookup was for. */
    readonly packageName: string;
    /** Client operation that failed, for example `getLatestVersion`. */
    readonly operation: string;
    /** Why the registry could not answer. */
    readonly reason: RegistryFailureReason;
    /** Diagnostic text from the underlying client, included in the message. */
    readonly detail?: string;
}
/**
 * Creates an error describing a registry that could not answer a lookup.
 *
 * @param details - Which lookup failed, against which registry, and why
 * @returns An error carrying the failure details
 *
 * @example Reporting an unreachable registry
 * ```typescript
 * throw createRegistryUnavailableError({
 *   registry: 'npm',
 *   packageName: '@scope/pkg',
 *   operation: 'getLatestVersion',
 *   reason: 'network',
 *   detail: 'ECONNREFUSED',
 * })
 * ```
 */
declare function createRegistryUnavailableError(details: RegistryUnavailableDetails): RegistryUnavailableError;
/**
 * Checks whether a value is a {@link RegistryUnavailableError}.
 *
 * @param value - Value to test, typically a caught error
 * @returns True when the value reports a registry that could not answer
 *
 * @example Distinguishing an unreachable registry from other failures
 * ```typescript
 * try {
 *   await registry.getLatestVersion('@scope/pkg')
 * } catch (error) {
 *   if (isRegistryUnavailableError(error)) {
 *     logger.error(error.message)
 *   }
 * }
 * ```
 */
declare function isRegistryUnavailableError(value: unknown): value is RegistryUnavailableError;

export { REGISTRY_UNAVAILABLE_ERROR, createPackageInfo, createRegistryUnavailableError, createVersionInfo, isRegistryUnavailableError };
export type { Maintainer, PackageInfo, Registry, RegistryConfig, RegistryFailureReason, RegistryUnavailableDetails, RegistryUnavailableError, VersionInfo };