@npm-safe/core-dsh 1.0.5

package/dist/registry/client.js

@@ -0,0 +1,378 @@
+/**
+ * HTTP client for the npm registry API v2.
+ *
+ * This module provides {@link NpmRegistryClient}, a thin wrapper around the
+ * global `fetch` (available in Node 18+) that adds:
+ *
+ * - **Timeout**: each request is aborted after 10 seconds via an
+ *   `AbortController`.
+ * - **Retry with exponential backoff**: failed requests (network errors or
+ *   non-2xx responses) are retried up to 3 times with delays of 1s, 2s, and
+ *   4s between attempts.
+ * - **Compression**: the `Accept-Encoding` header advertises gzip and
+ *   deflate support.
+ * - **User-Agent**: a customisable UA header is sent on every request.
+ * - **Typed errors**: non-success responses and unrecoverable failures are
+ *   surfaced as {@link NpmRegistryError} carrying the HTTP status code and
+ *   status text.
+ *
+ * The client intentionally contains **no caching** and **no rate limiting**
+ * — those concerns are delegated to dedicated modules layered on top.
+ *
+ * @module registry/client
+ */
+import { NpmRegistryError } from './types.js';
+import { ProxyAgent } from 'undici';
+/**
+ * Default registry base URL used when no `baseUrl` is supplied to the
+ * constructor.
+ */
+const DEFAULT_BASE_URL = 'https://registry.npmjs.org';
+/**
+ * Default User-Agent string sent when no `userAgent` is supplied. Includes
+ * the package name and a Node version hint so the registry can identify the
+ * client.
+ */
+const DEFAULT_USER_AGENT = '@npm-safe/core (https://npmjs.org)';
+/**
+ * Per-request timeout in milliseconds. Each fetch attempt is aborted if it
+ * does not complete within this window.
+ */
+const REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * Number of attempts made before giving up. The first attempt plus
+ * {@link RETRY_BACKOFF_MS}.length - 1 retries equals this value.
+ */
+const MAX_ATTEMPTS = 3;
+/**
+ * Exponential backoff delays (in milliseconds) applied between retry
+ * attempts. The first attempt is immediate; subsequent attempts wait for the
+ * corresponding entry in this array before retrying.
+ */
+const RETRY_BACKOFF_MS = [1_000, 2_000, 4_000];
+/**
+ * Resolve a proxy URL from the environment. Conventional proxy variables
+ * are checked in a case-insensitive manner. Returns `undefined` when no
+ * proxy is configured.
+ */
+function envProxyUrl() {
+    const candidates = [
+        process.env.HTTPS_PROXY,
+        process.env.https_proxy,
+        process.env.HTTP_PROXY,
+        process.env.http_proxy,
+        process.env.ALL_PROXY,
+        process.env.all_proxy,
+    ];
+    for (const candidate of candidates) {
+        if (candidate && candidate.trim().length > 0)
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * Parse the `NO_PROXY` environment variable into a set of lowercased
+ * hostnames (and optional `*` wildcard). Empty entries are ignored.
+ */
+function parseNoProxy() {
+    const raw = process.env.NO_PROXY ?? process.env.no_proxy ?? '';
+    return new Set(raw
+        .split(',')
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0));
+}
+/**
+ * Determine whether a hostname should bypass the configured proxy per the
+ * `NO_PROXY` list. Exact matches, suffix matches (`.example.com` covers
+ * `api.example.com`), and the `*` wildcard all bypass.
+ */
+function isNoProxyHost(host, noProxy) {
+    if (noProxy.has('*'))
+        return true;
+    for (const entry of noProxy) {
+        const normalized = entry.startsWith('.') ? entry.slice(1) : entry;
+        if (host === normalized)
+            return true;
+        if (host.endsWith(`.${normalized}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Sleep for the given number of milliseconds. Resolves once the timer
+ * elapses; never rejects.
+ *
+ * @param ms - Duration to sleep in milliseconds.
+ * @returns A promise that resolves after the delay.
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * HTTP client for the npm registry.
+ *
+ * Construct an instance once and reuse it across calls — the client holds no
+ * per-request mutable state beyond the configured base URL and User-Agent.
+ * All public methods are async and return parsed, typed JSON payloads.
+ *
+ * @example
+ * ```ts
+ * const client = new NpmRegistryClient();
+ * const meta = await client.getPackageMetadata('lodash');
+ * const manifest = await client.getVersionManifest('lodash', '4.17.21');
+ * const hits = await client.searchPackages('security', 10);
+ * ```
+ */
+export class NpmRegistryClient {
+    /** Base URL (no trailing slash) prepended to every request path. */
+    baseUrl;
+    /** User-Agent header value sent on every request. */
+    userAgent;
+    /** Explicit proxy URL from constructor options (highest priority). */
+    proxyUrl;
+    /** Proxy dispatchers keyed by proxy URL, lazily created. */
+    proxyAgents = new Map();
+    /** Hosts that must bypass the proxy. */
+    noProxyHosts;
+    /**
+     * @param options - Optional configuration overriding the defaults.
+     * @param options.baseUrl - Registry base URL. Defaults to
+     *   `https://registry.npmjs.org`. A trailing slash is stripped.
+     * @param options.userAgent - User-Agent header value. Defaults to a
+     *   string identifying `@npm-safe/core`.
+     * @param options.proxy - Proxy URL (e.g. `http://127.0.0.1:7897`). When
+     *   omitted, the conventional environment variables are consulted.
+     */
+    constructor(options) {
+        const baseUrl = options?.baseUrl ?? DEFAULT_BASE_URL;
+        // Strip a single trailing slash so callers may pass either form.
+        this.baseUrl =
+            baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        this.userAgent = options?.userAgent ?? DEFAULT_USER_AGENT;
+        this.proxyUrl = options?.proxy ?? envProxyUrl();
+        this.noProxyHosts = parseNoProxy();
+    }
+    /**
+     * Resolve the fetch `dispatcher` to use for a request URL.
+     *
+     * Returns `undefined` when no proxy is configured or the hostname is in
+     * the `NO_PROXY` list; otherwise returns a lazily created
+     * {@link Dispatcher} for the active proxy.
+     *
+     * @param url - Fully-qualified request URL.
+     * @returns A proxy dispatcher, or `undefined` to use the default fetch.
+     */
+    getDispatcher(url) {
+        let host = '';
+        try {
+            host = new URL(url).hostname.toLowerCase();
+        }
+        catch {
+            return undefined;
+        }
+        if (isNoProxyHost(host, this.noProxyHosts))
+            return undefined;
+        const proxy = this.proxyUrl;
+        if (!proxy)
+            return undefined;
+        let agent = this.proxyAgents.get(proxy);
+        if (!agent) {
+            agent = new ProxyAgent(proxy);
+            this.proxyAgents.set(proxy, agent);
+        }
+        return agent;
+    }
+    /**
+     * Fetch the full packument (metadata) for a package.
+     *
+     * Issues `GET {baseUrl}/{name}` and returns the parsed
+     * {@link PackageMetadata} document, which includes all published versions,
+     * dist-tags, and the readme.
+     *
+     * @param name - Package name (scoped names include the leading `@`).
+     * @param options - Optional request options. `options.signal` is forwarded
+     *   to the underlying fetch as part of a combined abort signal; an external
+     *   abort settles the promise promptly with an `AbortError` `DOMException`
+     *   (no retry).
+     * @returns The full package metadata document.
+     * @throws {NpmRegistryError} When the request fails after all retries or
+     *   the registry returns a non-2xx status.
+     * @throws {DOMException} With name `AbortError` when `options.signal` is
+     *   aborted.
+     */
+    async getPackageMetadata(name, options) {
+        return this.request(`${this.baseUrl}/${encodeName(name)}`, options);
+    }
+    /**
+     * Fetch the abbreviated packument for a single published version.
+     *
+     * Issues `GET {baseUrl}/{name}/{version}` and returns the parsed
+     * {@link AbbreviatedVersion} manifest.
+     *
+     * @param name - Package name (scoped names include the leading `@`).
+     * @param version - Semver version string (e.g. `4.17.21`).
+     * @returns The abbreviated version manifest.
+     * @throws {NpmRegistryError} When the request fails after all retries or
+     *   the registry returns a non-2xx status.
+     */
+    async getVersionManifest(name, version) {
+        return this.request(`${this.baseUrl}/${encodeName(name)}/${encodeURIComponent(version)}`);
+    }
+    /**
+     * Search the registry for packages matching a text query.
+     *
+     * Issues `GET {baseUrl}/-/v1/search?text={query}&size={size}` and returns
+     * the array of {@link SearchResult} hits. The `size` parameter caps the
+     * number of results (the registry imposes its own upper bound).
+     *
+     * @param query - Free-text search query.
+     * @param options - Optional search options. `options.size` caps the number
+     *   of results (defaults to 20); `options.signal` is forwarded to the
+     *   underlying fetch as part of a combined abort signal.
+     * @returns An array of search-result hits, ordered by relevance.
+     * @throws {NpmRegistryError} When the request fails after all retries or
+     *   the registry returns a non-2xx status.
+     * @throws {DOMException} With name `AbortError` when `options.signal` is
+     *   aborted.
+     */
+    async searchPackages(query, options) {
+        const size = options?.size ?? 20;
+        const url = `${this.baseUrl}/-/v1/search?text=${encodeURIComponent(query)}&size=${encodeURIComponent(String(size))}`;
+        const body = await this.request(url, options);
+        // Normalise the raw response into the public SearchResult shape. The
+        // registry omits `searchScore` on some responses, so default to the
+        // final score when absent.
+        return body.objects.map((hit) => ({
+            package: hit.package,
+            score: hit.score,
+            searchScore: hit.searchScore ?? hit.score.final,
+        }));
+    }
+    /**
+     * Perform a single HTTP GET against `url` with timeout and retry.
+     *
+     * The request is retried up to {@link MAX_ATTEMPTS} times with exponential
+     * backoff (1s, 2s, 4s). A retry is attempted when:
+     *
+     * - The fetch rejects (network error, DNS failure, abort due to the owned
+     *   timeout controller).
+     * - The response status is not in the 2xx range.
+     *
+     * On the final attempt the underlying error (or a new
+     * {@link NpmRegistryError} for non-2xx responses) is rethrown.
+     *
+     * **Cooperative cancellation**: when `options.signal` is supplied it is
+     * combined with the per-request timeout controller via `AbortSignal.any`.
+     * An external abort (`options.signal` aborted) breaks the retry loop
+     * immediately and rethrows `DOMException('The operation was aborted.',
+     * 'AbortError')` with NO retry — the abort is never swallowed as a
+     * retryable timeout. Only the owned timeout controller keeps the existing
+     * wrap-as-`NpmRegistryError` + retry behaviour.
+     *
+     * @typeParam T - Expected shape of the parsed JSON response.
+     * @param url - Fully-qualified URL to fetch.
+     * @param options - Optional request options. `options.signal` is an
+     *   external abort signal forwarded by callers.
+     * @returns The parsed JSON response body typed as `T`.
+     * @throws {NpmRegistryError} When all attempts are exhausted or the
+     *   registry returns a non-2xx status on the final attempt.
+     * @throws {DOMException} With name `AbortError` when `options.signal` is
+     *   aborted.
+     */
+    async request(url, options) {
+        let lastError = null;
+        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+            // An already-aborted external signal short-circuits before any
+            // backoff sleep or fetch attempt: the abort must settle promptly
+            // with AbortError and must NOT be retried.
+            if (options?.signal?.aborted) {
+                throw new DOMException('The operation was aborted.', 'AbortError');
+            }
+            // Back off before every retry (skip on the first attempt).
+            if (attempt > 1) {
+                await sleep(RETRY_BACKOFF_MS[attempt - 2]);
+            }
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+            try {
+                const dispatcher = this.getDispatcher(url);
+                // Combine the owned timeout controller with the external abort
+                // signal so either one aborts the fetch. When no external signal
+                // is supplied the owned controller is used directly.
+                const combinedSignal = options?.signal
+                    ? AbortSignal.any([controller.signal, options.signal])
+                    : controller.signal;
+                const init = {
+                    method: 'GET',
+                    headers: {
+                        Accept: 'application/json',
+                        'Accept-Encoding': 'gzip, deflate',
+                        'User-Agent': this.userAgent,
+                    },
+                    signal: combinedSignal,
+                };
+                if (dispatcher) {
+                    // undici's fetch accepts a `dispatcher` option to route the request
+                    // through a custom agent (e.g. a proxy).
+                    init.dispatcher = dispatcher;
+                }
+                const response = await fetch(url, init);
+                if (!response.ok) {
+                    const statusText = response.statusText;
+                    const message = `Registry request to ${url} failed: ${response.status} ${statusText}`;
+                    const error = new NpmRegistryError(message, response.status, statusText);
+                    lastError = error;
+                    // Non-2xx is retryable: continue to the next attempt.
+                    continue;
+                }
+                return (await response.json());
+            }
+            catch (error) {
+                // An abort triggered by the EXTERNAL signal must break the retry
+                // loop and propagate as AbortError — it is never a retryable
+                // timeout. This is the cooperative-cancellation contract.
+                if (options?.signal?.aborted) {
+                    throw new DOMException('The operation was aborted.', 'AbortError');
+                }
+                // An abort triggered by our OWN timeout controller is surfaced as
+                // an NpmRegistryError so callers see a consistent error type, and
+                // remains retryable.
+                if (error instanceof Error && error.name === 'AbortError') {
+                    lastError = new NpmRegistryError(`Registry request to ${url} timed out after ${REQUEST_TIMEOUT_MS}ms.`);
+                }
+                else {
+                    lastError = error;
+                }
+                // Network/parse errors are retryable: continue to the next attempt.
+                continue;
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+        }
+        // All attempts exhausted. Rethrow the last captured error, wrapping
+        // non-NpmRegistryError values so callers always see a typed error.
+        if (lastError instanceof NpmRegistryError) {
+            throw lastError;
+        }
+        if (lastError instanceof Error) {
+            throw new NpmRegistryError(`Registry request to ${url} failed after ${MAX_ATTEMPTS} attempts: ${lastError.message}`);
+        }
+        throw new NpmRegistryError(`Registry request to ${url} failed after ${MAX_ATTEMPTS} attempts.`);
+    }
+}
+/**
+ * Percent-encode a package name for use in a registry URL path segment.
+ *
+ * Scoped names (`@scope/name`) are encoded so the embedded `/` becomes
+ * `%2F`, producing a single path segment. The npm registry accepts both the
+ * raw and percent-encoded forms; the encoded form is used here to avoid any
+ * ambiguity with path separators.
+ *
+ * @param name - Package name (scoped names include the leading `@`).
+ * @returns The percent-encoded name safe for use in a URL path.
+ */
+function encodeName(name) {
+    return encodeURIComponent(name);
+}
+//# sourceMappingURL=client.js.map

package/dist/registry/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/registry/client.ts"],"names":[],"mappings":"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"}

package/dist/registry/types.d.ts

@@ -0,0 +1,226 @@
+/**
+ * TypeScript type definitions for the npm registry API v2.
+ *
+ * This file is the foundational types module for the registry package. It
+ * contains no runtime code and no local imports — only type declarations
+ * describing the shapes returned by the npm registry's JSON endpoints
+ * (package metadata, abbreviated packuments, search results) plus the
+ * utility types used across the registry layer.
+ *
+ * @see https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md
+ */
+/**
+ * A person or entity associated with a package, either as an author or a
+ * maintainer. npm accepts both the structured form and a free-form string.
+ */
+export type PackagePerson = {
+    readonly name: string;
+    readonly email?: string;
+    readonly url?: string;
+} | string;
+/**
+ * Repository descriptor for a package. May be a structured object with a
+ * type and url, or a shorthand string (e.g. `github:user/repo`).
+ */
+export type PackageRepository = {
+    readonly type: string;
+    readonly url: string;
+} | string;
+/**
+ * Distribution metadata attached to a published package version. Returned
+ * by the registry under the `dist` key of each version entry.
+ */
+export interface DistMetadata {
+    /** Subresource Integrity (SRI) hash, e.g. `sha512-...`. */
+    readonly integrity?: string;
+    /** Legacy SHA-1 hex digest of the tarball. */
+    readonly shasum?: string;
+    /** Absolute URL to the downloadable `.tgz` tarball. */
+    readonly tarball: string;
+    /** Number of files contained in the tarball. */
+    readonly fileCount?: number;
+    /** Unpacked size of the tarball contents in bytes. */
+    readonly unpackedSize?: number;
+    /** Cryptographic signatures attached to the tarball. */
+    readonly signatures?: ReadonlyArray<{
+        readonly keyid: string;
+        readonly sig: string;
+    }>;
+}
+/**
+ * Abbreviated packument for a single published version. This is the shape
+ * used by the registry's abbreviated metadata endpoint and by the `versions`
+ * map inside {@link PackageMetadata}.
+ */
+export interface AbbreviatedVersion {
+    /** Package name (scoped names include the leading `@`). */
+    readonly name: string;
+    /** Semver version string. */
+    readonly version: string;
+    /** Legacy SHA-1 hex digest (mirrored from `dist.shasum`). */
+    readonly shasum?: string;
+    /** Subresource Integrity hash (mirrored from `dist.integrity`). */
+    readonly integrity?: string;
+    /** Runtime dependency ranges keyed by package name. */
+    readonly dependencies?: Readonly<Record<string, string>>;
+    /** Development-only dependency ranges keyed by package name. */
+    readonly devDependencies?: Readonly<Record<string, string>>;
+    /** Optional dependency ranges keyed by package name. */
+    readonly optionalDependencies?: Readonly<Record<string, string>>;
+    /** Peer dependency ranges keyed by package name. */
+    readonly peerDependencies?: Readonly<Record<string, string>>;
+    /** Names of bundled dependencies. */
+    readonly bundleDependencies?: ReadonlyArray<string>;
+    /** Deprecation message; presence marks the version as deprecated. */
+    readonly deprecated?: string;
+    /** Whether the version ships an install lifecycle script. */
+    readonly hasInstallScript?: boolean;
+    /** Whether the version ships an npm-shrinkwrap.json. */
+    readonly hasShrinkwrap?: boolean;
+    /** Distribution metadata for the tarball. */
+    readonly dist: DistMetadata;
+    /** Engine constraints keyed by engine name (e.g. `node`, `npm`). */
+    readonly engines?: Readonly<Record<string, string>>;
+    /** Internal flag mirroring {@link hasShrinkwrap}. */
+    readonly _hasShrinkwrap?: boolean;
+    /** Lifecycle scripts keyed by script name. */
+    readonly scripts?: Readonly<Record<string, string>>;
+    /** Executable binaries exposed by the package, keyed by bin name. */
+    readonly bin?: Readonly<Record<string, string>>;
+    /** Legacy directory layout descriptors. */
+    readonly directories?: Readonly<Record<string, string>>;
+}
+/**
+ * Full package metadata (packument) as returned by the registry's
+ * `GET /{package}` endpoint. The `versions` map is keyed by semver version
+ * string and contains abbreviated version entries.
+ */
+export interface PackageMetadata {
+    /** Package name (scoped names include the leading `@`). */
+    readonly name: string;
+    /** ISO-8601 timestamp of the most recent modification. */
+    readonly modified: string;
+    /** Distribution tags keyed by tag name (e.g. `latest`) pointing to versions. */
+    readonly 'dist-tags': Readonly<Record<string, string>>;
+    /** All published versions keyed by semver version string. */
+    readonly versions: Readonly<Record<string, AbbreviatedVersion>>;
+    /** Short human-readable description. */
+    readonly description?: string;
+    /** URL to the package's homepage. */
+    readonly homepage?: string;
+    /** Source repository descriptor. */
+    readonly repository?: PackageRepository;
+    /** Search/discoverability keywords. */
+    readonly keywords?: ReadonlyArray<string>;
+    /** Original package author. */
+    readonly author?: PackagePerson;
+    /** Current maintainers of the package. */
+    readonly maintainers?: ReadonlyArray<{
+        readonly name: string;
+        readonly email: string;
+    }>;
+    /** SPDX license identifier or license text. */
+    readonly license?: string;
+    /** Full readme contents. */
+    readonly readme?: string;
+    /** Filename of the readme (e.g. `README.md`). */
+    readonly readmeFilename?: string;
+    /** Publication timestamps keyed by version (plus `created`/`modified`). */
+    readonly time?: Readonly<Record<string, string>>;
+}
+/**
+ * A single hit from the registry's `GET /-/v1/search` endpoint.
+ */
+export interface SearchResult {
+    /** The package document portion of the search hit. */
+    readonly package: {
+        /** Package name (scoped names include the leading `@`). */
+        readonly name: string;
+        /** Scope of the package without the `@`, or empty string if unscoped. */
+        readonly scope: string;
+        /** Semver version of the hit (typically the latest). */
+        readonly version: string;
+        /** Short human-readable description. */
+        readonly description?: string;
+        /** Search/discoverability keywords. */
+        readonly keywords?: ReadonlyArray<string>;
+        /** ISO-8601 publication timestamp of the version. */
+        readonly date: string;
+        /** Canonical links for the package. */
+        readonly links: {
+            /** URL to the package page on the registry. */
+            readonly npm: string;
+            /** URL to the package's homepage. */
+            readonly homepage?: string;
+            /** URL to the source repository. */
+            readonly repository?: string;
+            /** URL to the issue tracker. */
+            readonly bugs?: string;
+        };
+        /** Publisher of the version. */
+        readonly publisher: {
+            readonly username: string;
+            readonly email: string;
+        };
+        /** Maintainers of the package. */
+        readonly maintainers: ReadonlyArray<{
+            readonly username: string;
+            readonly email: string;
+        }>;
+    };
+    /** Search relevance and quality scores. */
+    readonly score: {
+        /** Aggregated final score in the range [0, 1]. */
+        readonly final: number;
+        /** Breakdown of the final score into sub-scores. */
+        readonly detail: {
+            /** Quality sub-score in the range [0, 1]. */
+            readonly quality: number;
+            /** Popularity sub-score in the range [0, 1]. */
+            readonly popularity: number;
+            /** Maintenance sub-score in the range [0, 1]. */
+            readonly maintenance: number;
+        };
+    };
+    /** Internal search score used for ranking; may differ from `score.final`. */
+    readonly searchScore: number;
+}
+/**
+ * Error thrown by registry clients when a request fails or returns a
+ * non-success status. Carries the HTTP status code and status text when
+ * available so callers can branch on specific failure modes.
+ */
+export declare class NpmRegistryError extends Error {
+    readonly statusCode?: number | undefined;
+    readonly statusText?: string | undefined;
+    /**
+     * @param message - Human-readable error message.
+     * @param statusCode - HTTP status code from the response, if any.
+     * @param statusText - HTTP status text from the response, if any.
+     */
+    constructor(message: string, statusCode?: number | undefined, statusText?: string | undefined);
+}
+/**
+ * Outcome of validating a package identifier or version string.
+ */
+export interface ValidationResult {
+    /** `true` when the validated value is acceptable. */
+    readonly valid: boolean;
+    /** Human-readable explanation when {@link valid} is `false`. */
+    readonly reason?: string;
+}
+/**
+ * A parsed package identifier combining name, optional scope, and optional
+ * version into a single immutable value.
+ */
+export interface PackageIdentifier {
+    /** Package name without scope prefix. */
+    readonly name: string;
+    /** Semver version string, if specified. */
+    readonly version?: string;
+    /** Scope without the leading `@`, if the package is scoped. */
+    readonly scope?: string;
+    /** Fully-qualified name: `@scope/name` when scoped, otherwise `name`. */
+    readonly fullName: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/registry/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"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"}

package/dist/registry/types.js

@@ -0,0 +1,32 @@
+/**
+ * TypeScript type definitions for the npm registry API v2.
+ *
+ * This file is the foundational types module for the registry package. It
+ * contains no runtime code and no local imports — only type declarations
+ * describing the shapes returned by the npm registry's JSON endpoints
+ * (package metadata, abbreviated packuments, search results) plus the
+ * utility types used across the registry layer.
+ *
+ * @see https://github.com/npm/registry/blob/main/docs/REGISTRY-API.md
+ */
+/**
+ * Error thrown by registry clients when a request fails or returns a
+ * non-success status. Carries the HTTP status code and status text when
+ * available so callers can branch on specific failure modes.
+ */
+export class NpmRegistryError extends Error {
+    statusCode;
+    statusText;
+    /**
+     * @param message - Human-readable error message.
+     * @param statusCode - HTTP status code from the response, if any.
+     * @param statusText - HTTP status text from the response, if any.
+     */
+    constructor(message, statusCode, statusText) {
+        super(message);
+        this.statusCode = statusCode;
+        this.statusText = statusText;
+        this.name = 'NpmRegistryError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/registry/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/registry/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA4LH;;;;GAIG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAQvB;IACA;IARlB;;;;OAIG;IACH,YACE,OAAe,EACC,UAAmB,EACnB,UAAmB;QAEnC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,eAAU,GAAV,UAAU,CAAS;QACnB,eAAU,GAAV,UAAU,CAAS;QAGnC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}