0
# Upload System
1

2
GitHub releases integration for uploading prebuilt binaries with automatic release creation, duplicate detection, and comprehensive error handling.
3

4
## Capabilities
5

6
### Upload Function
7

8
Main upload function that handles GitHub release creation and binary asset uploads.
9

10
```javascript { .api }
11
/**
12
 * Upload prebuilt binaries to GitHub releases
13
 * @param opts - Upload options including files, authentication, and release settings
14
 * @param cb - Callback function (err, result) => void
15
 */
16
function upload(opts, cb);
17

18
interface UploadOptions {
19
  /** Package.json object containing repository information */
20
  pkg: PackageJson;
21
  /** Array of file paths to upload */
22
  files: string[];
23
  /** GitHub personal access token for authentication */
24
  upload: string;
25
  /** Tag prefix for release tags (defaults to 'v') */
26
  'tag-prefix'?: string;
27
  /** Mark the release as a prerelease */
28
  prerelease?: boolean;
29
  /** Custom ghreleases instance (for testing) */
30
  gh?: object;
31
}
32

33
interface UploadResult {
34
  /** Newly uploaded files */
35
  new: string[];
36
  /** Previously uploaded files (skipped) */
37
  old: string[];
38
}
39

40
interface PackageJson {
41
  name: string;
42
  version: string;
43
  repository?: {
44
    type: string;
45
    url: string;
46
  };
47
}
48
```
49

50
**Usage Examples:**
51

52
```javascript
53
const upload = require('prebuild/upload');
54

55
// Upload prebuilt binaries
56
upload({
57
  pkg: require('./package.json'),
58
  files: [
59
    'prebuilds/mymodule-v1.0.0-node-v93-linux-x64.tar.gz',
60
    'prebuilds/mymodule-v1.0.0-node-v93-darwin-x64.tar.gz'
61
  ],
62
  upload: 'ghp_your_github_token_here'
63
}, (err, result) => {
64
  if (err) throw err;
65
  console.log('Uploaded:', result.new.length, 'files');
66
  console.log('Skipped:', result.old.length, 'existing files');
67
});
68

69
// Upload with custom tag prefix for monorepo
70
upload({
71
  pkg: require('./package.json'),
72
  files: ['prebuilds/module-v2.1.0-node-v93-win32-x64.tar.gz'],
73
  upload: 'ghp_token123',
74
  'tag-prefix': 'my-package@',
75
  prerelease: true
76
}, (err, result) => {
77
  if (err) throw err;
78
  console.log('Prerelease created and files uploaded');
79
});
80
```
81

82
### Release Management
83

84
Automatic GitHub release creation with tag generation and duplicate handling.
85

86
```javascript { .api }
87
/**
88
 * Release creation and management logic
89
 */
90
interface ReleaseManagement {
91
  /** Generated tag name format: {tag-prefix}{package.version} */
92
  tagFormat: string;
93
  /** GitHub repository user/owner extracted from package.json */
94
  repositoryUser: string;
95
  /** GitHub repository name extracted from package.json */
96
  repositoryName: string;
97
  /** OAuth authentication configuration */
98
  authConfig: GitHubAuth;
99
}
100

101
interface GitHubAuth {
102
  user: 'x-oauth';
103
  token: string;
104
}
105
```
106

107
**Tag Examples:**
108

109
```javascript
110
// Default tag prefix 'v'
111
// Package version: '1.2.3' → Tag: 'v1.2.3'
112

113
// Custom tag prefix for lerna/monorepo
114
// Tag prefix: 'my-package@', Version: '1.2.3' → Tag: 'my-package@1.2.3'
115
```
116

117
### Asset Management
118

119
Intelligent asset upload with duplicate detection and filtering.
120

121
```javascript { .api }
122
/**
123
 * Asset upload and duplicate detection
124
 */
125
interface AssetManagement {
126
  /** Existing assets on the release */
127
  existingAssets: string[];
128
  /** Files to upload (filtered for duplicates) */
129
  filesToUpload: string[];
130
  /** Upload operation results */
131
  uploadResults: UploadResult;
132
}
133
```
134

135
**Usage Examples:**
136

137
```javascript
138
// The upload system automatically:
139
// 1. Checks existing assets on the release
140
// 2. Filters out files that already exist
141
// 3. Uploads only new files
142
// 4. Returns summary of new vs existing files
143

144
upload({
145
  pkg: require('./package.json'),
146
  files: [
147
    'prebuilds/mod-v1.0.0-node-v93-linux-x64.tar.gz',  // New file
148
    'prebuilds/mod-v1.0.0-node-v93-darwin-x64.tar.gz'  // Already exists
149
  ],
150
  upload: 'token'
151
}, (err, result) => {
152
  // result.new: ['mod-v1.0.0-node-v93-linux-x64.tar.gz']
153
  // result.old: ['mod-v1.0.0-node-v93-darwin-x64.tar.gz']
154
});
155
```
156

157
### Repository Detection
158

159
Automatic repository information extraction from package.json.
160

161
```javascript { .api }
162
/**
163
 * Repository information extraction
164
 * @param pkg - Package.json object
165
 * @returns GitHub repository URL or null
166
 */
167
function extractRepositoryInfo(pkg: PackageJson): string | null;
168

169
/**
170
 * Repository URL formats supported:
171
 * - https://github.com/user/repo
172
 * - https://github.com/user/repo.git  
173
 * - git+https://github.com/user/repo.git
174
 * - git@github.com:user/repo.git
175
 */
176
interface RepositoryFormats {
177
  https: 'https://github.com/user/repo';
178
  httpsGit: 'https://github.com/user/repo.git';
179
  gitHttps: 'git+https://github.com/user/repo.git';
180
  ssh: 'git@github.com:user/repo.git';
181
}
182
```
183

184
**Package.json Examples:**
185

186
```json
187
{
188
  "name": "my-module",
189
  "version": "1.0.0",
190
  "repository": {
191
    "type": "git",
192
    "url": "https://github.com/user/my-module.git"
193
  }
194
}
195
```
196

197
```json
198
{
199
  "name": "my-module", 
200
  "version": "1.0.0",
201
  "repository": "github:user/my-module"
202
}
203
```
204

205
### Error Handling
206

207
Comprehensive error handling for common upload scenarios.
208

209
```javascript { .api }
210
/**
211
 * Upload error types and handling
212
 */
213
interface UploadErrors {
214
  /** Missing repository field in package.json */
215
  NoRepositoryError: Error;
216
  /** GitHub API authentication failure */
217
  AuthenticationError: Error;
218
  /** Network/connectivity issues */
219
  NetworkError: Error;
220
  /** File not found or access issues */
221
  FileError: Error;
222
  /** GitHub rate limiting */
223
  RateLimitError: Error;
224
}
225

226
/**
227
 * Error factory functions
228
 */
229
interface ErrorFactories {
230
  noRepository(): Error;
231
  spawnFailed(cmd: string, args: string[], code: number): Error;
232
}
233
```
234

235
**Error Examples:**
236

237
```javascript
238
const upload = require('prebuild/upload');
239

240
upload({
241
  pkg: { name: 'test', version: '1.0.0' }, // Missing repository
242
  files: ['test.tar.gz'],
243
  upload: 'token'
244
}, (err, result) => {
245
  if (err) {
246
    console.error('Upload failed:', err.message);
247
    // "package.json is missing a repository field"
248
  }
249
});
250
```
251

252
### GitHub Integration
253

254
Integration with ghreleases library for GitHub API operations.
255

256
```javascript { .api }
257
/**
258
 * GitHub API operations through ghreleases
259
 */
260
interface GitHubOperations {
261
  /** Create release if it doesn't exist */
262
  createRelease(auth: GitHubAuth, user: string, repo: string, options: ReleaseOptions): void;
263
  /** Get existing release by tag */
264
  getByTag(auth: GitHubAuth, user: string, repo: string, tag: string): Promise<Release>;
265
  /** Upload assets to release */
266
  uploadAssets(auth: GitHubAuth, user: string, repo: string, releaseId: string, files: string[]): void;
267
}
268

269
interface ReleaseOptions {
270
  tag_name: string;
271
  prerelease?: boolean;
272
}
273

274
interface Release {
275
  id: string;
276
  tag_name: string;
277
  assets: Asset[];
278
}
279

280
interface Asset {
281
  name: string;
282
  id: string;
283
  download_count: number;
284
}
285
```
286

287
## Upload Workflow
288

289
1. **Repository Validation**: Extract and validate GitHub repository URL from package.json
290
2. **Authentication Setup**: Configure OAuth token for GitHub API access  
291
3. **Release Creation**: Create release with generated tag if it doesn't exist
292
4. **Asset Discovery**: Fetch existing assets from the release
293
5. **Duplicate Detection**: Filter out files that already exist as assets
294
6. **File Upload**: Upload new files as release assets
295
7. **Result Reporting**: Return summary of uploaded vs existing files
296

297
## Types
298

299
```javascript { .api }
300
interface PackageJson {
301
  name: string;
302
  version: string;
303
  repository?: {
304
    type: string;
305
    url: string;
306
  } | string;
307
}
308

309
interface GitHubAuth {
310
  user: 'x-oauth';
311
  token: string;
312
}
313

314
interface UploadResult {
315
  new: string[];
316
  old: string[];
317
}
318
```