import type { TtlCache } from '@socketsecurity/lib/cache-with-ttl';
interface PurlObject {
    name: string;
    namespace?: string | undefined;
    qualifiers?: Record<string, string> | undefined;
    subpath?: string | undefined;
    type?: string | undefined;
    version?: string | undefined;
}
/**
 * Result of package existence check.
 */
export type ExistsResult = {
    exists: boolean;
    latestVersion?: string;
    error?: string;
};
/**
 * Options for registry existence checks.
 */
export type ExistsOptions = {
    /**
     * Optional TTL cache instance for caching registry responses.
     * If provided, responses will be cached with configured TTL.
     *
     * @example
     * ```typescript
     * import { createTtlCache } from '@socketsecurity/lib/cache-with-ttl'
     * import { npmExists } from '@socketregistry/packageurl-js'
     *
     * const cache = createTtlCache({ ttl: 5 * 60 * 1000, prefix: 'npm-registry' })
     * const result = await npmExists('lodash', undefined, undefined, { cache })
     * ```
     */
    cache?: TtlCache;
};
/**
 * Components parsed from npm package specifier.
 * Includes namespace (for scoped packages), name, and version.
 */
export type NpmPackageComponents = {
    namespace: string | undefined;
    name: string;
    version: string | undefined;
};
/**
 * Normalize npm package URL.
 * https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst#npm
 */
export declare function normalize(purl: PurlObject): PurlObject;
/**
 * Check if an npm package exists in the registry.
 *
 * Queries the npm registry at https://registry.npmjs.org to verify package
 * existence and optionally validate a specific version. Returns the latest
 * version from dist-tags.
 *
 * **Caching:** Responses can be cached using a TTL cache to reduce registry
 * requests. Pass `{ cache }` option with a cache instance from `createTtlCache()`.
 *
 * @param name - Package name (e.g., 'lodash', 'core' for scoped packages)
 * @param namespace - Optional namespace/scope (e.g., '@babel')
 * @param version - Optional version to validate (e.g., '4.17.21')
 * @param options - Optional configuration including cache
 * @returns Promise resolving to existence result with latest version
 *
 * @example
 * ```typescript
 * // Check if package exists
 * const result = await npmExists('lodash')
 * // -> { exists: true, latestVersion: '4.17.21' }
 *
 * // Check scoped package
 * const result = await npmExists('core', '@babel')
 * // -> { exists: true, latestVersion: '7.23.0' }
 *
 * // Validate specific version
 * const result = await npmExists('lodash', undefined, '4.17.21')
 * // -> { exists: true, latestVersion: '4.17.21' }
 *
 * // With caching
 * import { createTtlCache } from '@socketsecurity/lib/cache-with-ttl'
 * const cache = createTtlCache({ ttl: 5 * 60 * 1000, prefix: 'npm' })
 * const result = await npmExists('lodash', undefined, undefined, { cache })
 *
 * // Non-existent package
 * const result = await npmExists('this-package-does-not-exist')
 * // -> { exists: false, error: 'Package not found' }
 * ```
 */
export declare function npmExists(name: string, namespace?: string, version?: string, options?: ExistsOptions): Promise<ExistsResult>;
/**
 * Parse npm package specifier into component data.
 *
 * Parses npm package specifiers into namespace, name, and version components.
 * Handles scoped packages, version ranges, and normalizes version strings.
 *
 * **Supported formats:**
 * - Basic packages: `lodash`, `lodash@4.17.21`
 * - Scoped packages: `@babel/core`, `@babel/core@7.0.0`
 * - Version ranges: `^4.17.21`, `~1.2.3`, `>=1.0.0` (prefixes stripped)
 * - Dist-tags: `latest`, `next`, `beta` (passed through as version)
 *
 * **Not supported:**
 * - Git URLs: `git+https://...`
 * - File paths: `file:../package.tgz`
 * - GitHub shortcuts: `user/repo#branch`
 * - Aliases: `npm:package@version`
 *
 * **Note:** Dist-tags like `latest` are mutable and should be resolved to
 * concrete versions for reproducible builds. This method passes them through
 * as-is for convenience.
 *
 * @param specifier - npm package specifier (e.g., 'lodash@4.17.21', '@babel/core@^7.0.0')
 * @returns Object with namespace, name, and version components
 * @throws {Error} If specifier is not a string or is empty
 *
 * @example
 * ```typescript
 * // Basic packages
 * parseNpmSpecifier('lodash@4.17.21')
 * // -> { namespace: undefined, name: 'lodash', version: '4.17.21' }
 *
 * // Scoped packages
 * parseNpmSpecifier('@babel/core@^7.0.0')
 * // -> { namespace: '@babel', name: 'core', version: '7.0.0' }
 *
 * // Dist-tags (passed through)
 * parseNpmSpecifier('react@latest')
 * // -> { namespace: undefined, name: 'react', version: 'latest' }
 *
 * // No version
 * parseNpmSpecifier('express')
 * // -> { namespace: undefined, name: 'express', version: undefined }
 * ```
 */
export declare function parseNpmSpecifier(specifier: unknown): NpmPackageComponents;
/**
 * Validate npm package URL.
 * Validation based on https://github.com/npm/validate-npm-package-name/tree/v6.0.0
 * ISC License
 * Copyright (c) 2015, npm, Inc
 */
export declare function validate(purl: PurlObject, throws: boolean): boolean;
export {};