@bernierllc/github-parser

GitHub webhook payload parser and transformer

Installation

npm install @bernierllc/github-parser

Features

• Webhook parsing - Parse all GitHub webhook event types
• Commit extraction - Extract commit information from push events
• Repository metadata - Extract repository details
• Event normalization - Normalize different payload structures
• Type-safe - Full TypeScript support with interfaces
• Framework agnostic - Pure parsing logic

Usage

Basic Usage

import { GitHubParser } from '@bernierllc/github-parser';

const parser = new GitHubParser();

// Parse webhook payload
const event = parser.parse(webhookPayload);

console.log('Event type:', event.type);
console.log('Repository:', event.repository.fullName);
console.log('Commits:', event.commits);

Parse Push Webhook

const payload = {
  ref: 'refs/heads/main',
  repository: { /* ... */ },
  commits: [
    {
      id: 'abc123',
      message: 'Add feature',
      author: { name: 'Developer', email: '[email protected]' },
      // ...
    }
  ]
};

const event = parser.parse(payload);
console.log('Branch:', event.branch); // 'main'
console.log('Commits:', event.commits?.length);

Extract Commits

const commits = parser.extractCommits(payload);
commits.forEach(commit => {
  console.log('SHA:', commit.sha);
  console.log('Message:', commit.message);
  console.log('Files:', commit.files);
  console.log('Additions:', commit.additions);
  console.log('Deletions:', commit.deletions);
});

Extract Repository

const repo = parser.extractRepository(payload);
console.log('Name:', repo.name);
console.log('Full name:', repo.fullName);
console.log('Owner:', repo.owner.login);
console.log('Private:', repo.private);

Extract Single Commit

const commit = parser.extractCommit(payload);
if (commit) {
  console.log('Commit SHA:', commit.sha);
  console.log('Author:', commit.author.name);
}

API

new GitHubParser()

Creates a new GitHub parser instance.

parser.parse(payload: GitHubWebhookPayload): ParsedWebhookEvent

Parses a GitHub webhook payload into a normalized event structure.

parser.extractCommits(payload: GitHubWebhookPayload): ParsedCommit[]

Extracts all commits from a push webhook payload.

parser.extractCommit(payload: GitHubWebhookPayload): ParsedCommit | null

Extracts a single commit from a webhook payload.

parser.extractRepository(payload: GitHubWebhookPayload): ParsedRepository

Extracts repository information from a webhook payload.

parser.normalizeEventType(payload: GitHubWebhookPayload): string

Normalizes the event type from a webhook payload.

Integration Status

Logger Integration

Status: ✅ Integrated

Uses @bernierllc/logger for parsing events, errors, and webhook processing.

NeverHub Integration

Status: ⚠️ Optional

Can emit parsing events to NeverHub for distributed monitoring and observability. GitHub parser can publish events like github.webhook.parsed, github.commit.extracted, and github.repository.extracted to NeverHub when available.

Pattern: Optional service discovery integration - package can emit parsing events to NeverHub for distributed monitoring.

Example Integration:

// If NeverHub is available, emit events
if (typeof detectNeverHub === 'function') {
  const event = parser.parse(payload);
  neverhub.emit('github-parser.webhook.parsed', event);
}

Docs-Suite Integration

Status: ✅ Ready

TypeDoc-compatible JSDoc comments are included throughout the source code. All public APIs are documented with examples and type information.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.