@pepys/source-github 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@pepys/source-github</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@pepys/source-github"><img src="https://img.shields.io/npm/v/@pepys/source-github" alt="npm version"></a>
+    <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/README.md">Documentation</a> •
+    <a href="../../docs/design/v1-plug-ins.md">The plug-ins of v1</a>
+  </p>
+</div>
+
+The pepys GitHub plug-in, for Bun.
+
+The plug-in receives GitHub's webhook deliveries as facts, and builds pull request rows from them
+with its consumer.
+
+## Install
+
+```sh
+bun add @pepys/source-github
+```
+
+## Features
+
+- `githubPlugin`: the plug-in, to add to a deployment.
+- `githubPullRequestConsumer`: the consumer of pull request facts, with its SQL schema.
+
+## Documentation
+
+The [pepys docs](../../docs/README.md) hold the design of the plug-ins.

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@pepys/source-github",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "The pepys GitHub plug-in: pull requests, releases, commits and deploys",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/pepys.git",
+    "directory": "packages/source-github"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/test-utils"
+  ],
+  "type": "module",
+  "exports": "./src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pepys/api": "0.0.1",
+    "@pepys/ingest": "0.0.1",
+    "@pepys/kit": "0.0.1",
+    "@pepys/schema": "0.0.1",
+    "@zgeoff/std": "0.4.3",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "tiny-invariant": "1.3.3"
+  }
+}

package/src/api/serve-api.ts

@@ -0,0 +1,37 @@
+import { createApp, createStoreReader, openConsumerDatabase, readAPIConfig } from '@pepys/api';
+import { makeShutdownHandler } from '@pepys/schema';
+import { githubPullRequestConsumer } from '../github-pull-request-consumer.ts';
+
+const config = readAPIConfig(process.env);
+
+if (!config.ok) {
+  console.error(config.failure.join('\n'));
+  process.exit(1);
+}
+
+const store = createStoreReader({
+  storeDirectory: config.value.storeDirectory,
+  openDatabase: openConsumerDatabase,
+});
+
+const app = createApp({ store, consumers: [githubPullRequestConsumer] });
+
+app.listen({ hostname: '127.0.0.1', port: config.value.port });
+console.log(`api listening on ${app.server?.port}`);
+
+const shutdown = makeShutdownHandler({
+  stop: async () => {
+    await app.stop();
+    await store.close();
+  },
+  logError: (message, error) => {
+    console.error(message, error);
+  },
+  exit: (code) => process.exit(code),
+});
+
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.on(signal, () => {
+    void shutdown();
+  });
+}

package/src/consumers/github-pull-request.ts

@@ -0,0 +1,180 @@
+import {
+  initGithubPullRequestModel,
+  readGithubPullRequestRow,
+  toGithubPullRequestID,
+  updateGithubPullRequestModel,
+} from '../generated/github-pull-request-boundary.ts';
+import type {
+  EntityID,
+  GithubPullRequestMessage,
+  GithubPullRequestModel,
+  GithubPullRequestOperation,
+  GithubPullRequestRow,
+} from '../generated/github-pull-request-boundary.ts';
+
+export type {
+  GithubPullRequestMessage,
+  GithubPullRequestModel,
+} from '../generated/github-pull-request-boundary.ts';
+
+// scriptc takes the model and message types through a re-export, but not the two functions
+export function init(): GithubPullRequestModel {
+  return initGithubPullRequestModel();
+}
+
+export function update(
+  model: GithubPullRequestModel,
+  message: GithubPullRequestMessage,
+): GithubPullRequestModel {
+  return updateGithubPullRequestModel(model, message);
+}
+
+export function applyFact(factJSON: string): string {
+  return JSON.stringify(mapFact(factJSON));
+}
+
+function mapFact(factJSON: string): GithubPullRequestOperation[] {
+  const row = readRow(factJSON);
+
+  if (row === undefined) {
+    return [];
+  }
+
+  const stored = readGithubPullRequestRow(row.id);
+
+  if (stored !== undefined && isStale(stored, row)) {
+    return [];
+  }
+
+  return [{ upsert: { github_pull_request: row } }];
+}
+
+// Two updates can share one second. A repeat of the stored row changes nothing, and a different
+// row with the same update time is a distinct update, so the later fact in the stream wins. The
+// host skips a fact it has applied before, so a redelivery never reaches this check.
+function isStale(stored: GithubPullRequestRow, row: GithubPullRequestRow): boolean {
+  if (stored.updated_at !== row.updated_at) {
+    return stored.updated_at > row.updated_at;
+  }
+
+  return JSON.stringify(stored) === JSON.stringify(row);
+}
+
+function readRow(factJSON: string): GithubPullRequestRow | undefined {
+  const fact: unknown = JSON.parse(factJSON);
+
+  if (!isObject(fact) || !('payload' in fact) || !isObject(fact.payload)) {
+    return undefined;
+  }
+
+  if (!('pull_request' in fact.payload) || !isObject(fact.payload.pull_request)) {
+    return undefined;
+  }
+
+  const pullRequest = fact.payload.pull_request;
+
+  if (!('id' in pullRequest) || typeof pullRequest.id !== 'number') {
+    return undefined;
+  }
+
+  if (!('number' in pullRequest) || typeof pullRequest.number !== 'number') {
+    return undefined;
+  }
+
+  if (!('title' in pullRequest) || typeof pullRequest.title !== 'string') {
+    return undefined;
+  }
+
+  if (!('state' in pullRequest) || typeof pullRequest.state !== 'string') {
+    return undefined;
+  }
+
+  if (!('html_url' in pullRequest) || typeof pullRequest.html_url !== 'string') {
+    return undefined;
+  }
+
+  if (!('created_at' in pullRequest) || typeof pullRequest.created_at !== 'string') {
+    return undefined;
+  }
+
+  if (!('updated_at' in pullRequest) || typeof pullRequest.updated_at !== 'string') {
+    return undefined;
+  }
+
+  const repositoryID = readRepositoryID(pullRequest);
+
+  if (repositoryID === undefined) {
+    return undefined;
+  }
+
+  return {
+    id: toGithubPullRequestID(`${pullRequest.id}`),
+    number: pullRequest.number,
+    repository_id: toEntityID(`github:repo:${repositoryID}`),
+    title: pullRequest.title,
+    state: pullRequest.state,
+    is_draft: 'draft' in pullRequest && pullRequest.draft === true,
+    is_merged: 'merged' in pullRequest && pullRequest.merged === true,
+    author_id: readAuthorID(pullRequest),
+    url: pullRequest.html_url,
+    merge_commit_sha:
+      'merge_commit_sha' in pullRequest && typeof pullRequest.merge_commit_sha === 'string'
+        ? pullRequest.merge_commit_sha
+        : null,
+    created_at: pullRequest.created_at,
+    updated_at: pullRequest.updated_at,
+    closed_at:
+      'closed_at' in pullRequest && typeof pullRequest.closed_at === 'string'
+        ? pullRequest.closed_at
+        : null,
+    merged_at:
+      'merged_at' in pullRequest && typeof pullRequest.merged_at === 'string'
+        ? pullRequest.merged_at
+        : null,
+    payload: pullRequest,
+  };
+}
+
+function readRepositoryID(pullRequest: object): number | undefined {
+  if (!('base' in pullRequest) || !isObject(pullRequest.base)) {
+    return undefined;
+  }
+
+  if (!('repo' in pullRequest.base) || !isObject(pullRequest.base.repo)) {
+    return undefined;
+  }
+
+  if (!('id' in pullRequest.base.repo) || typeof pullRequest.base.repo.id !== 'number') {
+    return undefined;
+  }
+
+  return pullRequest.base.repo.id;
+}
+
+function readAuthorID(pullRequest: object): EntityID | null {
+  if (!('user' in pullRequest) || !isObject(pullRequest.user)) {
+    return null;
+  }
+
+  if (!('id' in pullRequest.user) || typeof pullRequest.user.id !== 'number') {
+    return null;
+  }
+
+  return toEntityID(`github:user:${pullRequest.user.id}`);
+}
+
+function isObject(value: unknown): value is object {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
+function toEntityID(text: string): EntityID {
+  if (!isEntityID(text)) {
+    throw new Error('an entity ID is never empty');
+  }
+
+  return text;
+}

package/src/generated/github-pull-request-boundary.ts

@@ -0,0 +1,268 @@
+// Generated by `pepys build`. Do not edit.
+
+declare const idTag: unique symbol;
+declare const kindTag: unique symbol;
+
+export type EntityID = string & { readonly [idTag]: 'EntityID' };
+
+type KindedID<Kind extends string> = EntityID & { readonly [kindTag]: Kind };
+
+export type GithubPullRequestID = KindedID<'github:pull_request'>;
+
+export function toGithubPullRequestID(id: string): GithubPullRequestID {
+  const text = 'github:pull_request:' + id;
+
+  if (!isGithubPullRequestID(text)) {
+    throw new Error('an ID of the kind github:pull_request is never empty');
+  }
+
+  return text;
+}
+
+export function parseGithubPullRequestID(text: string): GithubPullRequestID | undefined {
+  return isGithubPullRequestID(text) ? text : undefined;
+}
+
+function isGithubPullRequestID(text: string): text is GithubPullRequestID {
+  return text.length > 'github:pull_request:'.length && text.startsWith('github:pull_request:');
+}
+
+export interface GithubPullRequestModel {
+  input: string;
+}
+
+export type GithubPullRequestMessage = { kind: 'apply'; input: string } | { kind: 'reset' };
+
+export function initGithubPullRequestModel(): GithubPullRequestModel {
+  return { input: '' };
+}
+
+export function updateGithubPullRequestModel(model: GithubPullRequestModel, message: GithubPullRequestMessage): GithubPullRequestModel {
+  return message.kind === 'reset' ? initGithubPullRequestModel() : { ...model, input: message.input };
+}
+
+export interface GithubPullRequestPayload {
+  action: string;
+  pull_request: GithubPullRequestPayloadPullRequest;
+}
+
+export interface GithubPullRequestPayloadPullRequest {
+  id: number;
+  updated_at: string;
+}
+
+export type GithubPullRequestFact =
+  | { id: string; type: 'github.pull_request.assigned' | 'github.pull_request.auto_merge_disabled' | 'github.pull_request.auto_merge_enabled' | 'github.pull_request.closed' | 'github.pull_request.converted_to_draft' | 'github.pull_request.demilestoned' | 'github.pull_request.dequeued' | 'github.pull_request.edited' | 'github.pull_request.enqueued' | 'github.pull_request.labeled' | 'github.pull_request.locked' | 'github.pull_request.milestoned' | 'github.pull_request.opened' | 'github.pull_request.ready_for_review' | 'github.pull_request.reopened' | 'github.pull_request.review_request_removed' | 'github.pull_request.review_requested' | 'github.pull_request.synchronize' | 'github.pull_request.unassigned' | 'github.pull_request.unlabeled' | 'github.pull_request.unlocked'; entity: string; at: string; payload: GithubPullRequestPayload };
+
+export function parseGithubPullRequestFact(factJSON: string): GithubPullRequestFact | undefined {
+  const parsed: unknown = JSON.parse(factJSON);
+
+  return decodeGithubPullRequestFact(parsed);
+}
+
+function decodeGithubPullRequestFact(value: unknown): GithubPullRequestFact | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const id = 'id' in value ? value.id : undefined;
+  const type = 'type' in value ? value.type : undefined;
+  const entity = 'entity' in value ? value.entity : undefined;
+  const at = 'at' in value ? value.at : undefined;
+  const payload = 'payload' in value ? value.payload : undefined;
+
+  if (typeof id !== 'string' || typeof entity !== 'string' || typeof at !== 'string') {
+    return undefined;
+  }
+
+  if (type === 'github.pull_request.assigned' || type === 'github.pull_request.auto_merge_disabled' || type === 'github.pull_request.auto_merge_enabled' || type === 'github.pull_request.closed' || type === 'github.pull_request.converted_to_draft' || type === 'github.pull_request.demilestoned' || type === 'github.pull_request.dequeued' || type === 'github.pull_request.edited' || type === 'github.pull_request.enqueued' || type === 'github.pull_request.labeled' || type === 'github.pull_request.locked' || type === 'github.pull_request.milestoned' || type === 'github.pull_request.opened' || type === 'github.pull_request.ready_for_review' || type === 'github.pull_request.reopened' || type === 'github.pull_request.review_request_removed' || type === 'github.pull_request.review_requested' || type === 'github.pull_request.synchronize' || type === 'github.pull_request.unassigned' || type === 'github.pull_request.unlabeled' || type === 'github.pull_request.unlocked') {
+    const decoded = decodeGithubPullRequestPayload(payload);
+
+    if (decoded === undefined) {
+      return undefined;
+    }
+
+    return { id, type, entity, at, payload: decoded };
+  }
+
+  return undefined;
+}
+
+function decodeGithubPullRequestPayload(value: unknown): GithubPullRequestPayload | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const raw0 = 'action' in value ? value.action : undefined;
+  const field0 = typeof raw0 === 'string' ? raw0 : undefined;
+
+  if (field0 === undefined) {
+    return undefined;
+  }
+
+  const raw1 = 'pull_request' in value ? value.pull_request : undefined;
+  const field1 = decodeGithubPullRequestPayloadPullRequest(raw1);
+
+  if (field1 === undefined) {
+    return undefined;
+  }
+
+  return {
+    action: field0,
+    pull_request: field1,
+  };
+}
+
+function decodeGithubPullRequestPayloadPullRequest(value: unknown): GithubPullRequestPayloadPullRequest | undefined {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const raw0 = 'id' in value ? value.id : undefined;
+  const field0 = typeof raw0 === 'number' ? raw0 : undefined;
+
+  if (field0 === undefined) {
+    return undefined;
+  }
+
+  const raw1 = 'updated_at' in value ? value.updated_at : undefined;
+  const field1 = typeof raw1 === 'string' ? raw1 : undefined;
+
+  if (field1 === undefined) {
+    return undefined;
+  }
+
+  return {
+    id: field0,
+    updated_at: field1,
+  };
+}
+
+export interface GithubPullRequestRow {
+  id: GithubPullRequestID;
+  number: number;
+  repository_id: EntityID;
+  title: string;
+  state: string;
+  is_draft: boolean;
+  is_merged: boolean;
+  author_id: EntityID | null;
+  url: string;
+  merge_commit_sha: string | null;
+  created_at: string;
+  updated_at: string;
+  closed_at: string | null;
+  merged_at: string | null;
+  payload: unknown;
+}
+
+export interface GithubPullRequestKey {
+  id: GithubPullRequestID;
+}
+
+export type GithubPullRequestOperation =
+  | { upsert: { github_pull_request: GithubPullRequestRow } }
+  | { delete: { github_pull_request: GithubPullRequestKey } };
+
+declare function readGithubPullRequestLength(key: string): number;
+declare function readGithubPullRequestInto(key: string, row: Uint8Array): void;
+
+export function readGithubPullRequestRow(key: string): GithubPullRequestRow | undefined {
+  const length = readGithubPullRequestLength(key);
+
+  if (length < 0) {
+    return undefined;
+  }
+
+  const row = new Uint8Array(length);
+
+  readGithubPullRequestInto(key, row);
+
+  const parsed: unknown = JSON.parse(new TextDecoder().decode(row));
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return undefined;
+  }
+
+  if (!('id' in parsed) || (typeof parsed.id !== 'string' || !isGithubPullRequestID(parsed.id))) {
+    return undefined;
+  }
+
+  if (!('number' in parsed) || (typeof parsed.number !== 'number')) {
+    return undefined;
+  }
+
+  if (!('repository_id' in parsed) || (!isEntityID(parsed.repository_id))) {
+    return undefined;
+  }
+
+  if (!('title' in parsed) || (typeof parsed.title !== 'string')) {
+    return undefined;
+  }
+
+  if (!('state' in parsed) || (typeof parsed.state !== 'string')) {
+    return undefined;
+  }
+
+  if (!('is_draft' in parsed) || (typeof parsed.is_draft !== 'boolean')) {
+    return undefined;
+  }
+
+  if (!('is_merged' in parsed) || (typeof parsed.is_merged !== 'boolean')) {
+    return undefined;
+  }
+
+  if (!('author_id' in parsed) || (parsed.author_id !== null && (!isEntityID(parsed.author_id)))) {
+    return undefined;
+  }
+
+  if (!('url' in parsed) || (typeof parsed.url !== 'string')) {
+    return undefined;
+  }
+
+  if (!('merge_commit_sha' in parsed) || (parsed.merge_commit_sha !== null && (typeof parsed.merge_commit_sha !== 'string'))) {
+    return undefined;
+  }
+
+  if (!('created_at' in parsed) || (typeof parsed.created_at !== 'string')) {
+    return undefined;
+  }
+
+  if (!('updated_at' in parsed) || (typeof parsed.updated_at !== 'string')) {
+    return undefined;
+  }
+
+  if (!('closed_at' in parsed) || (parsed.closed_at !== null && (typeof parsed.closed_at !== 'string'))) {
+    return undefined;
+  }
+
+  if (!('merged_at' in parsed) || (parsed.merged_at !== null && (typeof parsed.merged_at !== 'string'))) {
+    return undefined;
+  }
+
+  if (!('payload' in parsed)) {
+    return undefined;
+  }
+
+  return {
+    id: parsed.id,
+    number: parsed.number,
+    repository_id: parsed.repository_id,
+    title: parsed.title,
+    state: parsed.state,
+    is_draft: parsed.is_draft,
+    is_merged: parsed.is_merged,
+    author_id: parsed.author_id,
+    url: parsed.url,
+    merge_commit_sha: parsed.merge_commit_sha,
+    created_at: parsed.created_at,
+    updated_at: parsed.updated_at,
+    closed_at: parsed.closed_at,
+    merged_at: parsed.merged_at,
+    payload: parsed.payload,
+  };
+}
+
+function isEntityID(value: unknown): value is EntityID {
+  return typeof value === 'string';
+}

package/src/generated/github-pull-request.sql

@@ -0,0 +1,32 @@
+-- Generated by `pepys build`. Do not edit.
+
+CREATE TABLE "github_pull_request" (
+  "id" TEXT NOT NULL,
+  "number" INTEGER NOT NULL,
+  "repository_id" TEXT NOT NULL,
+  "title" TEXT NOT NULL,
+  "state" TEXT NOT NULL,
+  "is_draft" INTEGER NOT NULL,
+  "is_merged" INTEGER NOT NULL,
+  "author_id" TEXT,
+  "url" TEXT NOT NULL,
+  "merge_commit_sha" TEXT,
+  "created_at" TEXT NOT NULL,
+  "updated_at" TEXT NOT NULL,
+  "closed_at" TEXT,
+  "merged_at" TEXT,
+  "payload" TEXT NOT NULL,
+  PRIMARY KEY ("id")
+);
+
+CREATE INDEX "github_pull_request_repository_id_idx" ON "github_pull_request" ("repository_id");
+
+CREATE VIEW "entity" AS
+SELECT
+  "id" AS "id",
+  'github:pull_request' AS "kind",
+  "title" AS "title",
+  "url" AS "url",
+  "author_id" AS "actor",
+  "updated_at" AS "updated_at"
+FROM "github_pull_request";

package/src/github-plugin.ts

@@ -0,0 +1,26 @@
+import { definePlugin, defineSource } from '@pepys/kit';
+import { githubPullRequestConsumer } from './github-pull-request-consumer.ts';
+import { readPullRequestDelivery } from './ingest/read-pull-request-delivery.ts';
+import { pullRequestFamily } from './pull-request-family.ts';
+
+export const githubPlugin = definePlugin({
+  name: 'github',
+  sources: [
+    defineSource({
+      name: 'github',
+      families: [pullRequestFamily],
+      live: {
+        kind: 'receive',
+        route: '/webhook',
+        check: {
+          kind: 'hmac-sha256',
+          header: 'x-hub-signature-256',
+          secretEnv: 'PEPYS_GITHUB_WEBHOOK_SECRET',
+        },
+        reach: 'public',
+        read: readPullRequestDelivery,
+      },
+    }),
+  ],
+  consumers: [githubPullRequestConsumer],
+});

package/src/github-pull-request-consumer.ts

@@ -0,0 +1,44 @@
+import { defineConsumer, defineTable } from '@pepys/kit';
+import { pullRequestFamily } from './pull-request-family.ts';
+
+export const githubPullRequestConsumer = defineConsumer({
+  name: 'github_pull_request',
+  entry: new URL('consumers/github-pull-request.ts', import.meta.url),
+  input: { mode: 'fact', streams: [pullRequestFamily.stream] },
+  tables: {
+    github_pull_request: defineTable({
+      columns: {
+        id: { kind: 'entityID' },
+        number: { kind: 'integer' },
+        repository_id: { kind: 'entityID' },
+        title: { kind: 'text' },
+        state: { kind: 'text' },
+        is_draft: { kind: 'boolean' },
+        is_merged: { kind: 'boolean' },
+        author_id: { kind: 'entityID', nullable: true },
+        url: { kind: 'text' },
+        merge_commit_sha: { kind: 'text', nullable: true },
+        created_at: { kind: 'timestamp' },
+        updated_at: { kind: 'timestamp' },
+        closed_at: { kind: 'timestamp', nullable: true },
+        merged_at: { kind: 'timestamp', nullable: true },
+        payload: { kind: 'json' },
+      },
+      primaryKey: ['id'],
+      indexes: [{ columns: ['repository_id'] }],
+    }),
+  },
+  entityViews: [
+    {
+      table: 'github_pull_request',
+      kind: pullRequestFamily.entityKind,
+      id: 'id',
+      title: 'title',
+      url: 'url',
+      actor: 'author_id',
+      updatedAt: 'updated_at',
+    },
+  ],
+  reads: ['github_pull_request'],
+  links: [],
+});

package/src/github-pull-request-schema-path.ts

@@ -0,0 +1,6 @@
+import { join } from 'node:path';
+
+export const githubPullRequestSchemaPath = join(
+  import.meta.dir,
+  'generated/github-pull-request.sql',
+);

package/src/index.ts

@@ -0,0 +1,3 @@
+export { githubPlugin } from './github-plugin.ts';
+export { githubPullRequestConsumer } from './github-pull-request-consumer.ts';
+export { githubPullRequestSchemaPath } from './github-pull-request-schema-path.ts';

package/src/ingest/build-pull-request-fact.ts

@@ -0,0 +1,38 @@
+import { buildWebhookFactID, parseFactEnvelope } from '@pepys/kit';
+import type { FactEnvelope, Result } from '@pepys/kit';
+import { z } from 'zod';
+import type { ZodError } from 'zod';
+
+interface PullRequestFactParameters {
+  deliveryID: string;
+  body: unknown;
+}
+
+const pullRequestBodySchema = z.looseObject({
+  action: z.string().min(1),
+  pull_request: z.looseObject({ id: z.number().int(), updated_at: z.string() }),
+  sender: z.looseObject({ id: z.number().int() }).optional(),
+});
+
+export function buildPullRequestFact(
+  parameters: PullRequestFactParameters,
+): Result<FactEnvelope<unknown>, ZodError> {
+  const parsed = pullRequestBodySchema.safeParse(parameters.body);
+
+  if (!parsed.success) {
+    return { ok: false, failure: parsed.error };
+  }
+
+  const body = parsed.data;
+
+  return parseFactEnvelope({
+    id: buildWebhookFactID({ source: 'github', deliveryID: parameters.deliveryID }),
+    type: `github.pull_request.${body.action}`,
+    v: 1,
+    api: 'github/2022-11-28',
+    entity: `github:pull_request:${body.pull_request.id}`,
+    ...(body.sender === undefined ? {} : { actor: `github:user:${body.sender.id}` }),
+    at: body.pull_request.updated_at,
+    payload: parameters.body,
+  });
+}

package/src/ingest/pull-request-stream.ts

@@ -0,0 +1,4 @@
+import type { StreamName } from '@pepys/kit';
+import { toTagged } from '@zgeoff/std';
+
+export const pullRequestStream = toTagged<StreamName>('facts.github.pull_request');

package/src/ingest/read-pull-request-delivery.ts

@@ -0,0 +1,44 @@
+import type { Delivery, Received } from '@pepys/kit';
+import { buildPullRequestFact } from './build-pull-request-fact.ts';
+import { pullRequestStream } from './pull-request-stream.ts';
+
+// The read of a checked webhook delivery: a pull request event becomes one fact, and any other event
+// is ignored.
+export function readPullRequestDelivery(delivery: Delivery): Received {
+  if (delivery.headers.get('x-github-event') !== 'pull_request') {
+    return { kind: 'ignored' };
+  }
+
+  const deliveryID = delivery.headers.get('x-github-delivery');
+
+  if (deliveryID === null || deliveryID === '') {
+    return { kind: 'refused', status: 400, reason: 'no delivery ID' };
+  }
+
+  const body = parseJSON(new TextDecoder().decode(delivery.body));
+
+  if (!body.ok) {
+    return { kind: 'refused', status: 400, reason: 'the body is not JSON' };
+  }
+
+  const fact = buildPullRequestFact({ deliveryID, body: body.value });
+
+  if (!fact.ok) {
+    return { kind: 'refused', status: 422, reason: 'not a pull request delivery' };
+  }
+
+  return {
+    kind: 'batch',
+    batch: { facts: [{ stream: pullRequestStream, fact: fact.value, blobs: [] }] },
+  };
+}
+
+function parseJSON(text: string): { ok: true; value: unknown } | { ok: false } {
+  try {
+    const value: unknown = JSON.parse(text);
+
+    return { ok: true, value };
+  } catch {
+    return { ok: false };
+  }
+}

package/src/ingest/serve-ingest.ts

@@ -0,0 +1,8 @@
+import { serveIngest } from '@pepys/ingest';
+import { defineDeployment } from '@pepys/kit';
+import { githubPlugin } from '../github-plugin.ts';
+
+await serveIngest({
+  deployment: defineDeployment({ name: 'github', plugins: [githubPlugin] }),
+  environment: process.env,
+});

package/src/pull-request-family.ts

@@ -0,0 +1,41 @@
+import { defineFactFamily } from '@pepys/kit';
+import { z } from 'zod';
+
+// The `action` values of GitHub's `pull_request` webhook event.
+const actions = [
+  'assigned',
+  'auto_merge_disabled',
+  'auto_merge_enabled',
+  'closed',
+  'converted_to_draft',
+  'demilestoned',
+  'dequeued',
+  'edited',
+  'enqueued',
+  'labeled',
+  'locked',
+  'milestoned',
+  'opened',
+  'ready_for_review',
+  'reopened',
+  'review_request_removed',
+  'review_requested',
+  'synchronize',
+  'unassigned',
+  'unlabeled',
+  'unlocked',
+] as const;
+
+const deliverySchema = z.looseObject({
+  action: z.string(),
+  pull_request: z.looseObject({ id: z.number().int(), updated_at: z.string() }),
+});
+
+export const pullRequestFamily = defineFactFamily({
+  stream: 'facts.github.pull_request',
+  api: 'github/2022-11-28',
+  entityKind: 'github:pull_request',
+  types: Object.fromEntries(
+    actions.map((action) => [`github.pull_request.${action}`, deliverySchema]),
+  ),
+});