|
2 | 2 |
|
3 | 3 | [](https://www.npmjs.com/package/gitevents-fetch) |
4 | 4 | [](https://opensource.org/licenses/MIT) |
| 5 | +[](https://docs.npmjs.com/generating-provenance-statements) |
5 | 6 |
|
6 | 7 | A Node.js library for fetching events and talks from GitEvents-based GitHub repositories using GitHub's GraphQL API. GitEvents uses GitHub Issues as a data source for managing community events and talk submissions. |
7 | 8 |
|
| 9 | +> **Security**: This package is published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) attestation, ensuring verifiable supply chain security. |
| 10 | +
|
8 | 11 | ## Features |
9 | 12 |
|
10 | 13 | - 🚀 Fetch upcoming and past events from GitHub Issues |
11 | 14 | - 🎤 Retrieve event talks and speaker submissions (via sub-issues) |
12 | 15 | - 🏢 Fetch organization statistics and metadata |
| 16 | +- 📍 Fetch and validate location data with consistent schema |
| 17 | +- 👤 Fetch user profiles and speaker information |
| 18 | +- 📄 Fetch file contents from repositories (text files, JSON, etc.) |
13 | 19 | - 👥 Fetch GitHub Teams and team members |
14 | 20 | - 🔐 Support for both GitHub Personal Access Tokens (PAT) and GitHub App authentication |
15 | 21 | - 📊 Parse structured event data using issue forms |
@@ -250,6 +256,190 @@ console.log(org) |
250 | 256 | // } |
251 | 257 | ``` |
252 | 258 |
|
| 259 | +### `getUser(login)` |
| 260 | + |
| 261 | +Fetch a GitHub user profile (useful for speaker information). |
| 262 | + |
| 263 | +**Parameters:** |
| 264 | + |
| 265 | +- `login` (string) - GitHub username |
| 266 | + |
| 267 | +**Returns:** `Promise<User | null>` |
| 268 | + |
| 269 | +Returns user data or `null` if not found. |
| 270 | + |
| 271 | +**Example:** |
| 272 | + |
| 273 | +```javascript |
| 274 | +import { getUser } from 'gitevents-fetch' |
| 275 | + |
| 276 | +const user = await getUser('octocat') |
| 277 | + |
| 278 | +console.log(user) |
| 279 | +// { |
| 280 | +// login: 'octocat', |
| 281 | +// name: 'The Octocat', |
| 282 | +// bio: 'GitHub mascot', |
| 283 | +// avatarUrl: 'https://github.com/octocat.png', |
| 284 | +// url: 'https://github.com/octocat', |
| 285 | +// websiteUrl: 'https://octocat.com', |
| 286 | +// company: 'GitHub', |
| 287 | +// location: 'San Francisco', |
| 288 | +// email: 'octocat@github.com', |
| 289 | +// createdAt: Date('2011-01-25T18:44:36.000Z'), |
| 290 | +// updatedAt: Date('2024-01-01T00:00:00.000Z'), |
| 291 | +// followerCount: 1000, |
| 292 | +// followingCount: 10, |
| 293 | +// publicRepoCount: 8, |
| 294 | +// socialAccounts: [ |
| 295 | +// { provider: 'LINKEDIN', url: 'https://linkedin.com/in/octocat' } |
| 296 | +// ] |
| 297 | +// } |
| 298 | +``` |
| 299 | + |
| 300 | +### `getFile(org, repo, filePath, options?)` |
| 301 | + |
| 302 | +Fetch file contents from a repository. |
| 303 | + |
| 304 | +**Parameters:** |
| 305 | + |
| 306 | +- `org` (string) - GitHub organization or user name |
| 307 | +- `repo` (string) - Repository name |
| 308 | +- `filePath` (string) - Path to the file in the repository |
| 309 | +- `options` (object, optional) - Options |
| 310 | + - `branch` (string) - Branch name (default: 'HEAD') |
| 311 | + - `parse` (boolean) - Auto-parse JSON files (default: false) |
| 312 | + |
| 313 | +**Returns:** `Promise<string | object>` |
| 314 | + |
| 315 | +Returns string content by default, or parsed object if `parse: true` is used with JSON files. |
| 316 | + |
| 317 | +**Example:** |
| 318 | + |
| 319 | +```javascript |
| 320 | +import { getFile } from 'gitevents-fetch' |
| 321 | + |
| 322 | +// Fetch text file |
| 323 | +const readme = await getFile('myorg', 'myrepo', 'README.md') |
| 324 | +console.log(readme) // "# My Project\n..." |
| 325 | + |
| 326 | +// Fetch JSON file with auto-parsing |
| 327 | +const data = await getFile('myorg', 'myrepo', 'data.json', { parse: true }) |
| 328 | +console.log(data) // { key: 'value', ... } |
| 329 | + |
| 330 | +// Fetch from specific branch |
| 331 | +const config = await getFile('myorg', 'myrepo', 'config.json', { |
| 332 | + branch: 'develop', |
| 333 | + parse: true |
| 334 | +}) |
| 335 | +``` |
| 336 | + |
| 337 | +**Error Handling:** |
| 338 | + |
| 339 | +- Throws `File not found` error if file doesn't exist |
| 340 | +- Throws `Binary files are not supported` error for binary files |
| 341 | +- Throws `Failed to parse JSON` error if parse: true but content is invalid JSON |
| 342 | + |
| 343 | +### `getLocations(org, repo, options?)` |
| 344 | + |
| 345 | +Fetch and validate location data from a repository with consistent schema. |
| 346 | + |
| 347 | +**Parameters:** |
| 348 | + |
| 349 | +- `org` (string) - GitHub organization or user name |
| 350 | +- `repo` (string) - Repository name |
| 351 | +- `options` (object, optional) - Options |
| 352 | + - `fileName` (string) - File name (default: 'locations.json') |
| 353 | + - `branch` (string) - Branch name (default: 'HEAD') |
| 354 | + |
| 355 | +**Returns:** `Promise<{ locations: Location[], errors: Error[] | null }>` |
| 356 | + |
| 357 | +Returns validated locations and any validation errors. |
| 358 | + |
| 359 | +**Example:** |
| 360 | + |
| 361 | +```javascript |
| 362 | +import { getLocations } from 'gitevents-fetch' |
| 363 | + |
| 364 | +const result = await getLocations('myorg', 'events') |
| 365 | + |
| 366 | +console.log(result.locations) |
| 367 | +// [ |
| 368 | +// { |
| 369 | +// id: 'venue-1', |
| 370 | +// name: 'Tech Hub', |
| 371 | +// address: '123 Main St, City', |
| 372 | +// coordinates: { lat: 40.7128, lng: -74.006 }, |
| 373 | +// url: 'https://techhub.com', |
| 374 | +// what3words: 'filled.count.soap', |
| 375 | +// description: 'A modern tech venue', |
| 376 | +// capacity: 100, |
| 377 | +// accessibility: 'Wheelchair accessible' |
| 378 | +// } |
| 379 | +// ] |
| 380 | + |
| 381 | +// Check for validation errors |
| 382 | +if (result.errors) { |
| 383 | + console.log('Invalid locations:', result.errors) |
| 384 | +} |
| 385 | + |
| 386 | +// Use custom file name |
| 387 | +const venues = await getLocations('myorg', 'events', { |
| 388 | + fileName: 'venues.json' |
| 389 | +}) |
| 390 | +``` |
| 391 | + |
| 392 | +**Location Schema:** |
| 393 | + |
| 394 | +Required fields: |
| 395 | + |
| 396 | +- `id` (string) - Unique identifier |
| 397 | +- `name` (string) - Location name |
| 398 | + |
| 399 | +Optional fields (null if not provided): |
| 400 | + |
| 401 | +- `address` (string) - Physical address |
| 402 | +- `coordinates` (object) - { lat: number, lng: number } |
| 403 | +- `url` (string) - Location website |
| 404 | +- `what3words` (string) - what3words address |
| 405 | +- `description` (string) - Location description |
| 406 | +- `capacity` (number) - Venue capacity |
| 407 | +- `accessibility` (string) - Accessibility information |
| 408 | +- Custom fields are preserved |
| 409 | + |
| 410 | +**Validation:** |
| 411 | + |
| 412 | +The function validates each location and returns: |
| 413 | + |
| 414 | +- `locations` - Array of valid, normalized locations |
| 415 | +- `errors` - Array of validation errors (null if all valid) |
| 416 | + |
| 417 | +Each error includes: |
| 418 | + |
| 419 | +- `index` - Array index of invalid location |
| 420 | +- `id` - Location ID (if available) |
| 421 | +- `errors` - Array of validation error messages |
| 422 | + |
| 423 | +### Fetching Talks from a Dedicated Repository |
| 424 | + |
| 425 | +Talks stored as issues in a dedicated repository can be fetched using the existing event functions: |
| 426 | + |
| 427 | +```javascript |
| 428 | +import { upcomingEvents, event } from 'gitevents-fetch' |
| 429 | + |
| 430 | +// Fetch all talks (using different label if needed) |
| 431 | +const talks = await upcomingEvents('myorg', 'talks-repo') |
| 432 | + |
| 433 | +// Fetch specific talk by issue number |
| 434 | +const talk = await event('myorg', 'talks-repo', 42) |
| 435 | +``` |
| 436 | + |
| 437 | +Configure a custom label in your environment if talks use a different label: |
| 438 | + |
| 439 | +```bash |
| 440 | +export DEFAULT_APPROVED_EVENT_LABEL="Approved Talk" |
| 441 | +``` |
| 442 | + |
253 | 443 | ### Event Object Structure |
254 | 444 |
|
255 | 445 | ```typescript |
|
0 commit comments