0
# libnpmpublish
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: libnpmpublish
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install libnpmpublish`
10

11
## Core Imports
12

13
```javascript
14
const { publish, unpublish } = require('libnpmpublish');
15
```
16

17
For ES modules:
18

19
```javascript
20
import { publish, unpublish } from 'libnpmpublish';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { publish, unpublish } = require('libnpmpublish');
27

28
// Publishing a package
29
const manifest = {
30
  name: 'my-package',
31
  version: '1.0.0',
32
  description: 'My package description'
33
};
34

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

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

43
// Unpublishing a package
44
await unpublish('my-package@1.0.0', {
45
  token: 'your-npm-token'
46
});
47
```
48

49
## Architecture
50

51
libnpmpublish is built around several key components:
52

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

60
## Capabilities
61

62
### Package Publishing
63

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

66
```javascript { .api }
67
/**
68
 * Publishes a package to the npm registry
69
 * @param manifest - Parsed package.json manifest for the package
70
 * @param tarballData - Buffer containing the tarball data
71
 * @param opts - Configuration options extending npm-registry-fetch options
72
 * @returns Promise resolving to response object with optional transparencyLogUrl
73
 */
74
function publish(manifest: Object, tarballData: Buffer, opts?: PublishOptions): Promise<PublishResult>;
75

76
interface PublishOptions {
77
  /** Access level for scoped packages: "public" or "restricted" (default: "public") */
78
  access?: 'public' | 'restricted';
79
  /** Tag to register the package with (default: "latest") */
80
  defaultTag?: string;
81
  /** Hashing algorithms for integrity generation (default: ["sha512"], always includes "sha1") */
82
  algorithms?: string[];
83
  /** Custom npm version string for _npmVersion field (identifies the publishing client) */
84
  npmVersion?: string;
85
  /** Enable automatic provenance generation in CI environments */
86
  provenance?: boolean;
87
  /** Path to external provenance statement file */
88
  provenanceFile?: string;
89
  /** Authentication token for registry */
90
  token?: string;
91
  /** Registry URL */
92
  registry?: string;
93
  /** Force publish even with validation warnings */
94
  force?: boolean;
95
}
96

97
interface PublishResult {
98
  /** Optional transparency log URL for provenance */
99
  transparencyLogUrl?: string;
100
}
101
```
102

103
[Package Publishing](./publishing.md)
104

105
### Package Unpublishing
106

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

109
```javascript { .api }
110
/**
111
 * Unpublishes a package or specific version from the registry
112
 * @param spec - Package specification (name, name@version, or parsed object)
113
 * @param opts - Configuration options extending npm-registry-fetch options
114
 * @returns Promise resolving to boolean (true on success)
115
 */
116
function unpublish(spec: string | Object, opts?: UnpublishOptions): Promise<boolean>;
117

118
interface UnpublishOptions {
119
  /** Force unpublish operation (default: false) */
120
  force?: boolean;
121
  /** Authentication token for registry */
122
  token?: string;
123
  /** Registry URL */
124
  registry?: string;
125
}
126
```
127

128
[Package Unpublishing](./unpublishing.md)
129

130
## Error Handling
131

132
libnpmpublish throws specific error codes for different failure conditions:
133

134
- **EPRIVATE**: Package marked as private (cannot publish)
135
- **EUNSCOPED**: Cannot restrict access to unscoped packages
136
- **EBADSEMVER**: Invalid semver version format
137
- **EUSAGE**: Provenance generation configuration errors
138
- **E404**: Package or version not found during unpublish operations
139

140
## Types
141

142
```javascript { .api }
143
/** Package manifest object (parsed package.json) */
144
interface PackageManifest {
145
  name: string;
146
  version: string;
147
  description?: string;
148
  private?: boolean;
149
  tag?: string;
150
  dist?: {
151
    integrity?: string;
152
    shasum?: string;
153
    tarball?: string;
154
  };
155
  [key: string]: any;
156
}
157

158
/** Error object with specific error codes */
159
interface LibnpmpublishError extends Error {
160
  code: 'EPRIVATE' | 'EUNSCOPED' | 'EBADSEMVER' | 'EUSAGE' | 'E404';
161
}
162
```