or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdpublishing.mdunpublishing.md
tile.json

tessl/npm-libnpmpublish

Programmatic API for publishing and unpublishing npm packages with provenance support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/libnpmpublish@11.1.x

To install, run

npx @tessl/cli install tessl/npm-libnpmpublish@11.1.0

index.mddocs/

libnpmpublish

libnpmpublish is a Node.js library for programmatically publishing and unpublishing npm packages to registries. It provides comprehensive functionality for package publishing with manifest and tarball data, supports provenance attestation for supply chain security, OIDC authentication, and configurable access levels.

Package Information

  • Package Name: libnpmpublish
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install libnpmpublish

Core Imports

const { publish, unpublish } = require('libnpmpublish');

For ES modules:

import { publish, unpublish } from 'libnpmpublish';

Basic Usage

const { publish, unpublish } = require('libnpmpublish');

// Publishing a package
const manifest = {
  name: 'my-package',
  version: '1.0.0',
  description: 'My package description'
};

const tarballData = Buffer.from(/* tarball data */);

await publish(manifest, tarballData, {
  token: 'your-npm-token',
  registry: 'https://registry.npmjs.org/',
  access: 'public'
});

// Unpublishing a package
await unpublish('my-package@1.0.0', {
  token: 'your-npm-token'
});

Architecture

libnpmpublish is built around several key components:

  • Registry Communication: Uses npm-registry-fetch for all HTTP operations with the npm registry
  • Manifest Processing: Normalizes and validates package.json manifests using @npmcli/package-json
  • Integrity Generation: Creates SHA1 and SHA512 hashes for package tarballs using ssri
  • Provenance Support: Integrates with Sigstore for supply chain attestation in CI environments
  • Access Control: Handles public/restricted access for scoped packages
  • Error Handling: Provides specific error codes for different failure conditions

Capabilities

Package Publishing

Core functionality for publishing npm packages to registries with support for provenance attestation, custom tags, and access control.

/**
 * Publishes a package to the npm registry
 * @param manifest - Parsed package.json manifest for the package
 * @param tarballData - Buffer containing the tarball data
 * @param opts - Configuration options extending npm-registry-fetch options
 * @returns Promise resolving to response object with optional transparencyLogUrl
 */
function publish(manifest: Object, tarballData: Buffer, opts?: PublishOptions): Promise<PublishResult>;

interface PublishOptions {
  /** Access level for scoped packages: "public" or "restricted" (default: "public") */
  access?: 'public' | 'restricted';
  /** Tag to register the package with (default: "latest") */
  defaultTag?: string;
  /** Hashing algorithms for integrity generation (default: ["sha512"], always includes "sha1") */
  algorithms?: string[];
  /** Custom npm version string for _npmVersion field (identifies the publishing client) */
  npmVersion?: string;
  /** Enable automatic provenance generation in CI environments */
  provenance?: boolean;
  /** Path to external provenance statement file */
  provenanceFile?: string;
  /** Authentication token for registry */
  token?: string;
  /** Registry URL */
  registry?: string;
  /** Force publish even with validation warnings */
  force?: boolean;
}

interface PublishResult {
  /** Optional transparency log URL for provenance */
  transparencyLogUrl?: string;
}

Package Publishing

Package Unpublishing

Functionality for removing packages or specific versions from npm registries with proper dist-tag management.

/**
 * Unpublishes a package or specific version from the registry
 * @param spec - Package specification (name, name@version, or parsed object)
 * @param opts - Configuration options extending npm-registry-fetch options
 * @returns Promise resolving to boolean (true on success)
 */
function unpublish(spec: string | Object, opts?: UnpublishOptions): Promise<boolean>;

interface UnpublishOptions {
  /** Force unpublish operation (default: false) */
  force?: boolean;
  /** Authentication token for registry */
  token?: string;
  /** Registry URL */
  registry?: string;
}

Package Unpublishing

Error Handling

libnpmpublish throws specific error codes for different failure conditions:

  • EPRIVATE: Package marked as private (cannot publish)
  • EUNSCOPED: Cannot restrict access to unscoped packages
  • EBADSEMVER: Invalid semver version format
  • EUSAGE: Provenance generation configuration errors
  • E404: Package or version not found during unpublish operations

Types

/** Package manifest object (parsed package.json) */
interface PackageManifest {
  name: string;
  version: string;
  description?: string;
  private?: boolean;
  tag?: string;
  dist?: {
    integrity?: string;
    shasum?: string;
    tarball?: string;
  };
  [key: string]: any;
}

/** Error object with specific error codes */
interface LibnpmpublishError extends Error {
  code: 'EPRIVATE' | 'EUNSCOPED' | 'EBADSEMVER' | 'EUSAGE' | 'E404';
}