Metadata-Version: 2.4
Name: npm-status
Version: 0.0.1
Summary: Report packages and versions published in an npm organization.
Author: Kaizten Analytics
License-Expression: LicenseRef-Proprietary
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# npm Status

`npm-status` lists the packages and current versions published in an npm
organization. The organization defaults to `kaiztendevelopment`, the scope used
by the packages in this repository.

The report includes package creation and modification dates, latest version,
visibility, description, license, maintainers, dist-tags, current versions, and
weekly downloads. Version details include publication date, weekly downloads,
deprecation status, unpacked size, file count, dependency count, Node engine,
and tarball URL.

## Requirements

- Python 3.10 or newer
- Network access to `registry.npmjs.org` and `api.npmjs.org`

The package has no third-party runtime dependencies.

## Usage

Run the source-tree script with the default organization:

```bash
./npm-status.py
```

Select another npm organization, with or without the leading `@`:

```bash
./npm-status.py --organization kaizten
./npm-status.py --organization @kaiztendevelopment
```

Print structured JSON:

```bash
./npm-status.py --format json
```

After installing the package, the same options are available through:

```bash
npm-status --organization kaiztendevelopment
```

## Authentication

Anonymous requests report public packages. To include private packages that an
npm token is allowed to read, either set `NPM_TOKEN` or pass it explicitly:

```bash
export NPM_TOKEN='your-token'
npm-status
```

```bash
npm-status --token 'your-token'
```

The token is sent only to `registry.npmjs.org`. It is never sent to the
separate public downloads service at `api.npmjs.org`. Download statistics may
therefore be unavailable for private packages even when their registry metadata
is accessible.

## Download counts

npm's per-version download endpoint provides last-week statistics, so both the
package and version columns use the `last-week` period. Package-level and
per-version counts come from separate npm endpoints and are displayed as
independent values. The command does not sum or reconcile them because npm may
report different totals from the two services.

Only versions present in the package's current registry metadata are reported.
Historical or unpublished versions that remain in timestamps or download data
are excluded.

## Build and publish

Build the wheel and source distribution and validate their metadata:

```bash
./build-package.sh
```

Publish an already built version to PyPI:

```bash
./publish-pypi.sh
```

PyPI does not allow an existing filename/version to be uploaded again. Increase
the version in `pyproject.toml` before publishing a replacement release.
