# NpmRegistryInterface

> Provides access to an npm registry: package metadata, verified tarballs, and security advisories.

[API reference](/docs/api/index.md) › [Foxy](/docs/extensions/foxy/reference/index.md) › [Native](/docs/extensions/foxy/reference/native/index.md) › NpmRegistryInterface

| interface | `Foxy\Native\NpmRegistryInterface` |
| --- | --- |
| Source | [`src/Native/NpmRegistryInterface.php`](https://github.com/php-forge/foxy/blob/main/src/Native/NpmRegistryInterface.php#L12) |

Implemented by 1 type:

- [`NpmRegistry`](/docs/extensions/foxy/reference/native/npmregistry/index.md)

Provides access to an npm registry: package metadata, verified tarballs, and security advisories.

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| [`fetchTarball()`](#method-fetchTarball) abstract | Returns the path of a verified `.tgz` written inside the directory. | `NpmRegistryInterface` |
| [`getAdvisories()`](#method-getAdvisories) abstract | Returns the registry's bulk advisories document for the given versions, as the registry wrote it. | `NpmRegistryInterface` |
| [`getMetadata()`](#method-getMetadata) abstract | Returns the abbreviated metadata of a package. | `NpmRegistryInterface` |
| [`prefetchTarballs()`](#method-prefetchTarballs) abstract | Downloads the tarballs missing from the cache in parallel, verifying each before it is cached. | `NpmRegistryInterface` |

## Method details

### fetchTarball() <span id="method-fetchTarball"></span>

```php
abstract public function fetchTarball(Foxy\Native\ResolvedPackage $package, string $directory): string
```

Returns the path of a verified `.tgz` written inside the directory.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$package` | [`ResolvedPackage`](/docs/extensions/foxy/reference/native/resolvedpackage/index.md) | Registry package whose tarball URL and integrity are used. |
| `$directory` | `string` | Existing directory that receives the tarball. |

**Returns**

`string`

**Throws**

- [`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md): if the request fails or the tarball does not match its integrity value.

### getAdvisories() <span id="method-getAdvisories"></span>

```php
abstract public function getAdvisories(array<string, non-empty-list<string>> $versions): string
```

Returns the registry's bulk advisories document for the given versions, as the registry wrote it.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$versions` | `array<string, non-empty-list<string>>` | Locked versions keyed by package name. |

**Returns**

`string`

**Throws**

- [`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md): if the request fails.

### getMetadata() <span id="method-getMetadata"></span>

```php
abstract public function getMetadata(string $name): Foxy\Native\PackageMetadata
```

Returns the abbreviated metadata of a package.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$name` | `string` | Package name, scoped names included (`@scope/name`). |

**Returns**

[`PackageMetadata`](/docs/extensions/foxy/reference/native/packagemetadata/index.md)

**Throws**

- [`Foxy\Exception\RuntimeException`](/docs/extensions/foxy/reference/exception/runtimeexception/index.md): if the package is unknown, the request fails, or the metadata is malformed.

### prefetchTarballs() <span id="method-prefetchTarballs"></span>

```php
abstract public function prefetchTarballs(list<Foxy\Native\ResolvedPackage> $packages, string $directory): void
```

Downloads the tarballs missing from the cache in parallel, verifying each before it is cached.

The prefetch is best-effort: a tarball that fails to download or to verify is left out of the cache, and the
later [`fetchTarball()`](/docs/extensions/foxy/reference/native/npmregistryinterface/index.md#method-fetchTarball) downloads it again and reports the error. Each download lands in the given
directory until it is verified, never in a shared temporary directory.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$packages` | `list<`[`ResolvedPackage`](/docs/extensions/foxy/reference/native/resolvedpackage/index.md)`>` | Registry packages whose tarballs are wanted. |
| `$directory` | `string` | Existing directory that holds each tarball while it is verified. |