/*!
Copyright (c) the purl authors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/
/**
 * @fileoverview Builder pattern implementation for PackageURL construction with fluent API.
 */
import { PackageURL } from './package-url.js';
/**
 * Known Limitation: instanceof checks with ESM/CommonJS interop
 * ==============================================================
 *
 * When using PurlBuilder in environments that mix ESM and CommonJS modules
 * (such as Vitest tests importing CommonJS-compiled code as ESM), the instanceof
 * operator may not work reliably for checking if the built objects are instances
 * of PackageURL.
 *
 * This occurs because:
 * - PurlBuilder internally imports PackageURL using CommonJS require()
 * - External code may import PackageURL using ESM import
 * - Node.js creates different wrapper objects for the same class
 * - The instanceof check fails due to different object identities
 *
 * Workaround:
 * Instead of: `purl instanceof PackageURL`
 * Use: `purl.constructor.name === 'PackageURL'` or check for expected properties/methods
 *
 * This limitation only affects instanceof checks, not the actual functionality
 * of the created PackageURL objects.
 */
/**
 * Builder class for constructing PackageURL instances using a fluent API.
 *
 * This class provides a convenient way to build PackageURL objects step by step
 * with method chaining. Each method returns the builder instance, allowing for
 * fluent construction patterns.
 *
 * @example
 * ```typescript
 * const purl = PurlBuilder
 *   .npm()
 *   .name('lodash')
 *   .version('4.17.21')
 *   .build()
 * ```
 */
export declare class PurlBuilder {
    /** The package type (e.g., 'npm', 'pypi', 'maven'). */
    private _type?;
    /** The package namespace (organization, group, or scope). */
    private _namespace?;
    /** The package name (required for valid PackageURLs). */
    private _name?;
    /** The package version string. */
    private _version?;
    /** Key-value pairs of additional package qualifiers. */
    private _qualifiers?;
    /** Optional subpath within the package. */
    private _subpath?;
    /**
     * Build and return the final PackageURL instance.
     *
     * This method creates a new PackageURL instance using all the properties
     * set on this builder. The PackageURL constructor will handle validation
     * and normalization of the provided values.
     *
     * @throws {Error} If the configuration results in an invalid PackageURL
     */
    build(): PackageURL;
    /**
     * Set the package name for the PackageURL.
     *
     * This is the core identifier for the package and is required for all valid
     * PackageURLs. The name should be the canonical package name as it appears
     * in the package repository.
     */
    name(name: string): this;
    /**
     * Set the package namespace for the PackageURL.
     *
     * The namespace represents different concepts depending on the package type:
     * - npm: organization or scope (e.g., '@angular' for '@angular/core')
     * - maven: groupId (e.g., 'org.apache.commons')
     * - pypi: typically unused
     */
    namespace(namespace: string): this;
    /**
     * Add a single qualifier key-value pair.
     *
     * This method allows adding qualifiers incrementally. If the qualifier key
     * already exists, its value will be overwritten.
     */
    qualifier(key: string, value: string): this;
    /**
     * Set all qualifiers at once, replacing any existing qualifiers.
     *
     * Qualifiers provide additional metadata about the package such as:
     * - arch: target architecture
     * - os: target operating system
     * - classifier: additional classifier for the package
     */
    qualifiers(qualifiers: Record<string, string>): this;
    /**
     * Set the subpath for the PackageURL.
     *
     * The subpath represents a path within the package, useful for referencing
     * specific files or directories within a package. It should not start with
     * a forward slash.
     */
    subpath(subpath: string): this;
    /**
     * Set the package type for the PackageURL.
     */
    type(type: string): this;
    /**
     * Set the package version for the PackageURL.
     *
     * The version string should match the format used by the package repository.
     * Some package types may normalize version formats (e.g., removing leading 'v').
     */
    version(version: string): this;
    /**
     * Create a builder with the bitbucket package type preset.
     *
     * @example `PurlBuilder.bitbucket().namespace('owner').name('repo').build()`
     */
    static bitbucket(): PurlBuilder;
    /**
     * Create a builder with the cargo package type preset.
     *
     * @example `PurlBuilder.cargo().name('serde').version('1.0.0').build()`
     */
    static cargo(): PurlBuilder;
    /**
     * Create a builder with the cocoapods package type preset.
     *
     * @example `PurlBuilder.cocoapods().name('Alamofire').version('5.9.1').build()`
     */
    static cocoapods(): PurlBuilder;
    /**
     * Create a builder with the composer package type preset.
     *
     * @example `PurlBuilder.composer().namespace('laravel').name('framework').build()`
     */
    static composer(): PurlBuilder;
    /**
     * Create a builder with the conan package type preset.
     *
     * @example `PurlBuilder.conan().name('zlib').version('1.3.1').build()`
     */
    static conan(): PurlBuilder;
    /**
     * Create a builder with the conda package type preset.
     *
     * @example `PurlBuilder.conda().name('numpy').version('1.26.4').build()`
     */
    static conda(): PurlBuilder;
    /**
     * Create a builder with the cran package type preset.
     *
     * @example `PurlBuilder.cran().name('ggplot2').version('3.5.0').build()`
     */
    static cran(): PurlBuilder;
    /**
     * Create a new empty builder instance.
     *
     * This is a convenience factory method that returns a new PurlBuilder
     * instance ready for configuration.
     */
    static create(): PurlBuilder;
    /**
     * Create a builder with the deb package type preset.
     *
     * @example `PurlBuilder.deb().namespace('debian').name('curl').version('8.5.0').build()`
     */
    static deb(): PurlBuilder;
    /**
     * Create a builder with the docker package type preset.
     *
     * @example `PurlBuilder.docker().namespace('library').name('nginx').version('latest').build()`
     */
    static docker(): PurlBuilder;
    /**
     * Create a builder from an existing PackageURL instance.
     *
     * This factory method copies all properties from an existing PackageURL
     * into a new builder, allowing for modification of existing URLs.
     */
    static from(purl: PackageURL): PurlBuilder;
    /**
     * Create a builder with the gem package type preset.
     *
     * @example `PurlBuilder.gem().name('rails').version('7.0.0').build()`
     */
    static gem(): PurlBuilder;
    /**
     * Create a builder with the github package type preset.
     *
     * @example `PurlBuilder.github().namespace('socketdev').name('socket-cli').build()`
     */
    static github(): PurlBuilder;
    /**
     * Create a builder with the gitlab package type preset.
     *
     * @example `PurlBuilder.gitlab().namespace('owner').name('project').build()`
     */
    static gitlab(): PurlBuilder;
    /**
     * Create a builder with the golang package type preset.
     *
     * @example `PurlBuilder.golang().namespace('github.com/go').name('text').build()`
     */
    static golang(): PurlBuilder;
    /**
     * Create a builder with the hackage package type preset.
     *
     * @example `PurlBuilder.hackage().name('aeson').version('2.2.1.0').build()`
     */
    static hackage(): PurlBuilder;
    /**
     * Create a builder with the hex package type preset.
     *
     * @example `PurlBuilder.hex().name('phoenix').version('1.7.12').build()`
     */
    static hex(): PurlBuilder;
    /**
     * Create a builder with the huggingface package type preset.
     *
     * @example `PurlBuilder.huggingface().name('bert-base-uncased').build()`
     */
    static huggingface(): PurlBuilder;
    /**
     * Create a builder with the luarocks package type preset.
     *
     * @example `PurlBuilder.luarocks().name('luasocket').version('3.1.0').build()`
     */
    static luarocks(): PurlBuilder;
    /**
     * Create a builder with the maven package type preset.
     *
     * @example `PurlBuilder.maven().namespace('org.apache').name('commons-lang3').build()`
     */
    static maven(): PurlBuilder;
    /**
     * Create a builder with the npm package type preset.
     *
     * @example `PurlBuilder.npm().name('lodash').version('4.17.21').build()`
     */
    static npm(): PurlBuilder;
    /**
     * Create a builder with the nuget package type preset.
     *
     * @example `PurlBuilder.nuget().name('Newtonsoft.Json').version('13.0.3').build()`
     */
    static nuget(): PurlBuilder;
    /**
     * Create a builder with the oci package type preset.
     *
     * @example `PurlBuilder.oci().name('nginx').version('sha256:abc123').build()`
     */
    static oci(): PurlBuilder;
    /**
     * Create a builder with the pub package type preset.
     *
     * @example `PurlBuilder.pub().name('flutter').version('3.19.0').build()`
     */
    static pub(): PurlBuilder;
    /**
     * Create a builder with the pypi package type preset.
     *
     * @example `PurlBuilder.pypi().name('requests').version('2.31.0').build()`
     */
    static pypi(): PurlBuilder;
    /**
     * Create a builder with the rpm package type preset.
     *
     * @example `PurlBuilder.rpm().namespace('fedora').name('curl').version('8.5.0').build()`
     */
    static rpm(): PurlBuilder;
    /**
     * Create a builder with the swift package type preset.
     *
     * @example `PurlBuilder.swift().namespace('apple').name('swift-nio').version('2.64.0').build()`
     */
    static swift(): PurlBuilder;
}