diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 636ec0993..3457b89a8 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,7 +15,34 @@ jobs: node-version: 12.x - run: npm ci - run: npm run build:schema + - run: cp payload-examples/index.{d.ts,json} ./ + - run: cp payload-schemas/schema.json ./schema.json + - run: cp payload-types/schema.d.ts ./schema.d.ts - run: npx semantic-release env: GITHUB_TOKEN: ${{ secrets.OCTOKITBOT_PAT }} NPM_TOKEN: ${{ secrets.OCTOKITBOT_NPM_TOKEN }} + - run: npm publish payload-examples + env: + NPM_TOKEN: ${{ secrets.OCTOKITBOT_NPM_TOKEN }} + if: ${{ github.ref == 'refs/head/master' }} + - run: npm publish payload-examples --tag beta + env: + NPM_TOKEN: ${{ secrets.OCTOKITBOT_NPM_TOKEN }} + if: ${{ github.ref == 'refs/head/beta' }} + - run: npm publish payload-schemas + env: + NPM_TOKEN: ${{ secrets.OCTOKITBOT_NPM_TOKEN }} + if: ${{ github.ref == 'refs/head/master' }} + - run: npm publish payload-schemas --tag beta + env: + NPM_TOKEN: ${{ secrets.OCTOKITBOT_NPM_TOKEN }} + if: ${{ github.ref == 'refs/head/beta' }} + - run: npm publish payload-types + env: + NPM_TOKEN: ${{ secrets.OCTOKITBOT_NPM_TOKEN }} + if: ${{ github.ref == 'refs/head/master' }} + - run: npm publish payload-types --tag beta + env: + NPM_TOKEN: ${{ secrets.OCTOKITBOT_NPM_TOKEN }} + if: ${{ github.ref == 'refs/head/beta' }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 46df8d876..eb3609c8b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,7 @@ for these scripts in `bin/docs`, which can also be accessed by passing `--help` ## Adding examples The -[`index.json` file](https://github.com/octokit/webhooks/blob/master/index.json) +[`index.json` file](https://github.com/octokit/webhooks/blob/master/payload-examples/index.json) is generated, please do not edit it. Instead, make changes in the [`payload-examples/api.github.com/` folder](https://github.com/octokit/webhooks/tree/master/payload-examples/api.github.com), then update `index.json` by running the following command @@ -42,7 +42,7 @@ tests will fail. ## Updating types The -[`schema.d.ts` file](https://github.com/octokit/webhooks/blob/master/schema.d.ts) +[`schema.d.ts` file](https://github.com/octokit/webhooks/blob/master/payload-types/schema.d.ts) is generated, please do not edit it. Instead, make changes to the schemas in the [`payload-schemas/schemas/` folder](https://github.com/octokit/webhooks/tree/master/payload-schemas/schemas), then generate the schema and update the types with the following commands: diff --git a/README.md b/README.md index 9943f45f9..e4d6fad37 100644 --- a/README.md +++ b/README.md @@ -229,31 +229,31 @@ Example webhook definition ## Download webhook definitions and webhook payloads schema You can download the latest `index.json` and `schema.json` files from -[unpkg](https://unpkg.com/browse/@octokit/webhooks-definitions@3.24.0/) +[unpkg](https://unpkg.com/) -- [`index.json`](https://unpkg.com/@octokit/webhooks-definitions/index.json) -- [`schema.json`](https://unpkg.com/@octokit/webhooks-definitions/schema.json) +- [`index.json`](https://unpkg.com/@octokit/webhooks-examples/index.json) +- [`schema.json`](https://unpkg.com/@octokit/webhooks-schemas/schema.json) ## Usage as Node module -To get an array of all webhook definition objects, require the `index.json` file +To get an array of all webhook definition objects, require the `@octokit/webhooks-examples` package. ```js // Use Node.js require: -const WEBHOOKS = require("@octokit/webhooks-definitions/index.json"); +const WEBHOOKS = require("@octokit/webhooks-examples/index.json"); // Or ESM/TypeScript import: -import WEBHOOKS from "@octokit/webhooks-definitions/index.json"; +import WEBHOOKS from "@octokit/webhooks-examples/index.json"; ``` -To get the JSON schema for webhook payloads, require the `schema.json` file +To get the JSON schema for webhook payloads, require the `@octokit/webhooks-schemas` package. ```js // Use Node.js require: -const SCHEMA = require("@octokit/webhooks-definitions/schema.json"); +const SCHEMA = require("@octokit/webhooks-schemas"); // Or ESM/TypeScript import: -import SCHEMA from "@octokit/webhooks-definitions/schema.json"; +import SCHEMA from "@octokit/webhooks-schemas"; ``` ### Usage with `ajv` in `strict` mode @@ -267,8 +267,8 @@ the custom keyword `tsAdditionalProperties`. Here is an example of how you can set this up: ```ts -import type { WebhookEvent } from "@octokit/webhooks-definitions/schema"; -import * as githubWebhookSchema from "@octokit/webhooks-definitions/schema.json"; +import type { WebhookEvent } from "@octokit/webhooks-types"; +import * as githubWebhookSchema from "@octokit/webhooks-schemas"; import Ajv from "ajv"; import addFormats from "ajv-formats"; @@ -286,10 +286,7 @@ This package ships with types for the webhook events generated from the respective json schemas, which you can use like so: ```typescript -import { - WebhookEvent, - IssuesOpenedEvent, -} from "@octokit/webhooks-definitions/schema"; +import { WebhookEvent, IssuesOpenedEvent } from "@octokit/webhooks-types"; const handleWebhookEvent = (event: WebhookEvent) => { if ("action" in event && event.action === "completed") { diff --git a/bin/docs/octokit-schema.md b/bin/docs/octokit-schema.md index ca855f2d0..fc7fae1a5 100644 --- a/bin/docs/octokit-schema.md +++ b/bin/docs/octokit-schema.md @@ -1,7 +1,7 @@ # bin/octokit-schema.ts Generates the singular `schema.json` made up of all the schemas found within -`payload-schemas/schemas`, and which is included in the package published from +`payload-schemas/schemas`, and which is included in the [@octokit/webhooks-schemas package](https://www.npmjs.com/package/@octokit/webhooks-schemas) published from this repo. ## Usage diff --git a/bin/docs/octokit-types.md b/bin/docs/octokit-types.md index 1fe00fe80..c321f872b 100644 --- a/bin/docs/octokit-types.md +++ b/bin/docs/octokit-types.md @@ -2,7 +2,7 @@ Generates the singular `schema.d.ts` that provide strict typings for TypeScript users, based off the `schema.json` generated by `bin/octokit-schema `, and which -is included in the package published from this repo. +is included in the [@octokit/webhooks-types package](https://www.npmjs.com/package/@octokit/webhooks-types) published from this repo. Note that this uses `schema.json`, _not_ the individual schemas stored in `payload-schemas/schemas` - this means you have to regenerate `schema.json` diff --git a/bin/octokit-schema.ts b/bin/octokit-schema.ts index 7c32f0df2..c25d9e9cb 100755 --- a/bin/octokit-schema.ts +++ b/bin/octokit-schema.ts @@ -122,7 +122,7 @@ async function run() { }; fs.writeFileSync( - "schema.json", + "./payload-schemas/schema.json", format( JSON.stringify(schema, (key, value: unknown) => { if (key === "$id") { diff --git a/bin/octokit-types.ts b/bin/octokit-types.ts index 195dcd101..7f4cba29e 100644 --- a/bin/octokit-types.ts +++ b/bin/octokit-types.ts @@ -43,7 +43,9 @@ const buildEventPayloadMap = (schema: Schema): string => { }; const getSchema = async () => - JSON.parse(await fs.readFile("./schema.json", "utf-8")) as Schema; + JSON.parse( + await fs.readFile("./payload-schemas/schema.json", "utf-8") + ) as Schema; declare module "json-schema" { interface JSONSchema7 { @@ -54,7 +56,7 @@ declare module "json-schema" { const compileSchema = async (): Promise => { // has to be 4 due to https://github.com/bcherny/json-schema-to-typescript/issues/359 const schema: JSONSchema4 = JSON.parse( - await fs.readFile("./schema.json", "utf-8"), + await fs.readFile("./payload-schemas/schema.json", "utf-8"), (key, value: unknown) => { if (isJsonSchemaObject(value)) { // $refs with a description result in a duplicate interface being made @@ -88,7 +90,10 @@ const run = async () => { "export type WebhookEventName = keyof EventPayloadMap;", ].join("\n"); - await fs.writeFile("./schema.d.ts", format(ts, { parser: "typescript" })); + await fs.writeFile( + "./payload-types/schema.d.ts", + format(ts, { parser: "typescript" }) + ); }; run(); diff --git a/bin/validate-payload-examples.ts b/bin/validate-payload-examples.ts index cb4db7951..bdbc69fb4 100755 --- a/bin/validate-payload-examples.ts +++ b/bin/validate-payload-examples.ts @@ -3,7 +3,7 @@ import { DefinedError, ErrorObject } from "ajv"; import path from "path"; import { inspect } from "util"; -import { ajv, validate } from "../payload-schemas"; +import { ajv, validate } from "../payload-schemas/index"; import { forEachJsonFile, parseArgv, pathToPayloads } from "./utils"; const [, { continueOnError = false }] = parseArgv( diff --git a/bin/validate-schema.ts b/bin/validate-schema.ts index 49158589e..2547d65fb 100644 --- a/bin/validate-schema.ts +++ b/bin/validate-schema.ts @@ -14,7 +14,7 @@ addFormats(ajv); ajv.addKeyword("tsAdditionalProperties"); const schema = JSON.parse( - readFileSync(resolve(__dirname, "../schema.json"), "utf-8") + readFileSync(resolve(__dirname, "../payload-schemas/schema.json"), "utf-8") ); // if this is invalid, an error will be thrown diff --git a/lib/check-or-update-webhooks.ts b/lib/check-or-update-webhooks.ts index fbd4dcf47..e3ed44634 100644 --- a/lib/check-or-update-webhooks.ts +++ b/lib/check-or-update-webhooks.ts @@ -10,7 +10,7 @@ import { getSections, toWebhook, } from "."; -import currentWebhooks from "../index.json"; +import currentWebhooks from "../payload-examples/index.json"; const isNotNull = (value: T | null): value is T => value !== null; @@ -63,7 +63,7 @@ export const checkOrUpdateWebhooks = async ({ } writeFileSync( - "index.json", + "./payload-examples/index.json", prettier.format(JSON.stringify(webhooks, null, 2), { parser: "json", }) diff --git a/package-lock.json b/package-lock.json index 91361a715..c16a1c015 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6492,6 +6492,16 @@ "yargs": "^16.2.0" } }, + "semantic-release-plugin-update-version-in-files": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/semantic-release-plugin-update-version-in-files/-/semantic-release-plugin-update-version-in-files-1.1.0.tgz", + "integrity": "sha512-OWBrved3Rr0w3YP4iID81MhG9qhGrG+XtxdO9VMhKJ9qte3yBdMz5cSxDiPE/uhnGJQF00fqQetY3yhHFGabWw==", + "dev": true, + "requires": { + "debug": "^4.1.1", + "glob": "^7.1.3" + } + }, "semver": { "version": "7.3.5", "resolved": "https://registry.npmjs.org/semver/-/semver-7.3.5.tgz", diff --git a/package.json b/package.json index ea9288299..439ea62b0 100644 --- a/package.json +++ b/package.json @@ -19,8 +19,8 @@ "build:schema": "ts-node -T bin/octokit-schema.ts", "build:types": "ts-node -T bin/octokit-types.ts", "build:webhooks": "ts-node -T bin/octokit-webhooks.ts update", - "lint": "prettier --check '{bin,lib}/*.ts' '*.{ts,md}' '{payload-examples,payload-schemas}/**/*.json' 'payload-schemas/*.ts' *.md package.json index.json", - "lint:fix": "prettier --write '{bin,lib}/*.ts' '*.{ts,md}' '{payload-examples,payload-schemas}/**/*.json' 'payload-schemas/*.ts' *.md package.json index.json", + "lint": "prettier --check '{bin,lib}/*.ts' '*.{ts,md}' '{payload-examples,payload-schemas,payload-types}/**/*.md' '{payload-examples,payload-schemas}/**/*.json' 'payload-schemas/*.ts' 'payload-types/*.d.ts' *.md package.json", + "lint:fix": "prettier --write '{bin,lib}/*.ts' '*.{ts,md}' '{payload-examples,payload-schemas,payload-types}/**/*.md' '{payload-examples,payload-schemas,payload-types}/**/*.json' 'payload-schemas/*.ts' 'payload-types/*.d.ts' *.md package.json", "octokit-schema": "ts-node -T bin/octokit-schema.ts", "octokit-webhooks": "ts-node -T bin/octokit-webhooks.ts", "pretest": "npm run -s lint", @@ -51,6 +51,7 @@ "prettier": "^2.0.5", "prettier-plugin-packagejson": "^2.2.9", "semantic-release": "^17.0.0", + "semantic-release-plugin-update-version-in-files": "^1.1.0", "ts-node": "^9.1.1", "turndown": "^7.0.0", "typescript": "^4.1.3", @@ -59,6 +60,23 @@ "publishConfig": { "access": "public" }, + "releases": { + "plugins": [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + "@semantic-release/github", + "@semantic-release/npm", + [ + "semantic-release-plugin-update-version-in-files", + { + "files": [ + "payload-*/package.json" + ], + "placeholder": "0.0.0-development" + } + ] + ] + }, "renovate": { "extends": [ "github>octokit/.github" diff --git a/payload-examples/README.md b/payload-examples/README.md index 1bacb8715..629cc054b 100644 --- a/payload-examples/README.md +++ b/payload-examples/README.md @@ -1,4 +1,266 @@ -# Payload examples +# Octokit Webhooks + +> machine-readable, always up-to-date GitHub Webhooks specifications + +![Update status](https://github.com/octokit/webhooks/workflows/Update/badge.svg) + +## Download + +Download the latest specification at +[octokit.github.io/webhooks/index.json](https://octokit.github.io/webhooks/index.json) + +## Example + +Example webhook definition + +```json +{ + "name": "issues", + "actions": [ + "opened", + "edited", + "deleted", + "transferred", + "closed", + "reopened", + "assigned", + "unassigned", + "labeled", + "unlabeled", + "milestoned", + "demilestoned" + ], + "examples": [ + { + "action": "edited", + "issue": { + "url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2", + "repository_url": "https://api.github.com/repos/Codertocat/Hello-World", + "labels_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/labels{/name}", + "comments_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/comments", + "events_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/2/events", + "html_url": "https://github.com/Codertocat/Hello-World/issues/2", + "id": 327883527, + "node_id": "MDU6SXNzdWUzMjc4ODM1Mjc=", + "number": 2, + "title": "Spelling error in the README file", + "user": { + "login": "Codertocat", + "id": 21031067, + "node_id": "MDQ6VXNlcjIxMDMxMDY3", + "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4", + "gravatar_id": "", + "url": "https://api.github.com/users/Codertocat", + "html_url": "https://github.com/Codertocat", + "followers_url": "https://api.github.com/users/Codertocat/followers", + "following_url": "https://api.github.com/users/Codertocat/following{/other_user}", + "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}", + "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions", + "organizations_url": "https://api.github.com/users/Codertocat/orgs", + "repos_url": "https://api.github.com/users/Codertocat/repos", + "events_url": "https://api.github.com/users/Codertocat/events{/privacy}", + "received_events_url": "https://api.github.com/users/Codertocat/received_events", + "type": "User", + "site_admin": false + }, + "labels": [ + { + "id": 949737505, + "node_id": "MDU6TGFiZWw5NDk3Mzc1MDU=", + "url": "https://api.github.com/repos/Codertocat/Hello-World/labels/bug", + "name": "bug", + "color": "d73a4a", + "default": true + } + ], + "state": "open", + "locked": false, + "assignee": null, + "assignees": [ + { + "login": "Codertocat", + "id": 21031067, + "node_id": "MDQ6VXNlcjIxMDMxMDY3", + "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4", + "gravatar_id": "", + "url": "https://api.github.com/users/Codertocat", + "html_url": "https://github.com/Codertocat", + "followers_url": "https://api.github.com/users/Codertocat/followers", + "following_url": "https://api.github.com/users/Codertocat/following{/other_user}", + "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}", + "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions", + "organizations_url": "https://api.github.com/users/Codertocat/orgs", + "repos_url": "https://api.github.com/users/Codertocat/repos", + "events_url": "https://api.github.com/users/Codertocat/events{/privacy}", + "received_events_url": "https://api.github.com/users/Codertocat/received_events", + "type": "User", + "site_admin": false + } + ], + "milestone": null, + "comments": 0, + "created_at": "2018-05-30T20:18:32Z", + "updated_at": "2018-05-30T20:18:32Z", + "closed_at": null, + "author_association": "OWNER", + "body": "It looks like you accidently spelled 'commit' with two 't's." + }, + "changes": {}, + "repository": { + "id": 135493233, + "node_id": "MDEwOlJlcG9zaXRvcnkxMzU0OTMyMzM=", + "name": "Hello-World", + "full_name": "Codertocat/Hello-World", + "owner": { + "login": "Codertocat", + "id": 21031067, + "node_id": "MDQ6VXNlcjIxMDMxMDY3", + "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4", + "gravatar_id": "", + "url": "https://api.github.com/users/Codertocat", + "html_url": "https://github.com/Codertocat", + "followers_url": "https://api.github.com/users/Codertocat/followers", + "following_url": "https://api.github.com/users/Codertocat/following{/other_user}", + "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}", + "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions", + "organizations_url": "https://api.github.com/users/Codertocat/orgs", + "repos_url": "https://api.github.com/users/Codertocat/repos", + "events_url": "https://api.github.com/users/Codertocat/events{/privacy}", + "received_events_url": "https://api.github.com/users/Codertocat/received_events", + "type": "User", + "site_admin": false + }, + "private": false, + "html_url": "https://github.com/Codertocat/Hello-World", + "description": null, + "fork": false, + "url": "https://api.github.com/repos/Codertocat/Hello-World", + "forks_url": "https://api.github.com/repos/Codertocat/Hello-World/forks", + "keys_url": "https://api.github.com/repos/Codertocat/Hello-World/keys{/key_id}", + "collaborators_url": "https://api.github.com/repos/Codertocat/Hello-World/collaborators{/collaborator}", + "teams_url": "https://api.github.com/repos/Codertocat/Hello-World/teams", + "hooks_url": "https://api.github.com/repos/Codertocat/Hello-World/hooks", + "issue_events_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/events{/number}", + "events_url": "https://api.github.com/repos/Codertocat/Hello-World/events", + "assignees_url": "https://api.github.com/repos/Codertocat/Hello-World/assignees{/user}", + "branches_url": "https://api.github.com/repos/Codertocat/Hello-World/branches{/branch}", + "tags_url": "https://api.github.com/repos/Codertocat/Hello-World/tags", + "blobs_url": "https://api.github.com/repos/Codertocat/Hello-World/git/blobs{/sha}", + "git_tags_url": "https://api.github.com/repos/Codertocat/Hello-World/git/tags{/sha}", + "git_refs_url": "https://api.github.com/repos/Codertocat/Hello-World/git/refs{/sha}", + "trees_url": "https://api.github.com/repos/Codertocat/Hello-World/git/trees{/sha}", + "statuses_url": "https://api.github.com/repos/Codertocat/Hello-World/statuses/{sha}", + "languages_url": "https://api.github.com/repos/Codertocat/Hello-World/languages", + "stargazers_url": "https://api.github.com/repos/Codertocat/Hello-World/stargazers", + "contributors_url": "https://api.github.com/repos/Codertocat/Hello-World/contributors", + "subscribers_url": "https://api.github.com/repos/Codertocat/Hello-World/subscribers", + "subscription_url": "https://api.github.com/repos/Codertocat/Hello-World/subscription", + "commits_url": "https://api.github.com/repos/Codertocat/Hello-World/commits{/sha}", + "git_commits_url": "https://api.github.com/repos/Codertocat/Hello-World/git/commits{/sha}", + "comments_url": "https://api.github.com/repos/Codertocat/Hello-World/comments{/number}", + "issue_comment_url": "https://api.github.com/repos/Codertocat/Hello-World/issues/comments{/number}", + "contents_url": "https://api.github.com/repos/Codertocat/Hello-World/contents/{+path}", + "compare_url": "https://api.github.com/repos/Codertocat/Hello-World/compare/{base}...{head}", + "merges_url": "https://api.github.com/repos/Codertocat/Hello-World/merges", + "archive_url": "https://api.github.com/repos/Codertocat/Hello-World/{archive_format}{/ref}", + "downloads_url": "https://api.github.com/repos/Codertocat/Hello-World/downloads", + "issues_url": "https://api.github.com/repos/Codertocat/Hello-World/issues{/number}", + "pulls_url": "https://api.github.com/repos/Codertocat/Hello-World/pulls{/number}", + "milestones_url": "https://api.github.com/repos/Codertocat/Hello-World/milestones{/number}", + "notifications_url": "https://api.github.com/repos/Codertocat/Hello-World/notifications{?since,all,participating}", + "labels_url": "https://api.github.com/repos/Codertocat/Hello-World/labels{/name}", + "releases_url": "https://api.github.com/repos/Codertocat/Hello-World/releases{/id}", + "deployments_url": "https://api.github.com/repos/Codertocat/Hello-World/deployments", + "created_at": "2018-05-30T20:18:04Z", + "updated_at": "2018-05-30T20:18:10Z", + "pushed_at": "2018-05-30T20:18:30Z", + "git_url": "git://github.com/Codertocat/Hello-World.git", + "ssh_url": "git@github.com:Codertocat/Hello-World.git", + "clone_url": "https://github.com/Codertocat/Hello-World.git", + "svn_url": "https://github.com/Codertocat/Hello-World", + "homepage": null, + "size": 0, + "stargazers_count": 0, + "watchers_count": 0, + "language": null, + "has_issues": true, + "has_projects": true, + "has_downloads": true, + "has_wiki": true, + "has_pages": true, + "forks_count": 0, + "mirror_url": null, + "archived": false, + "open_issues_count": 2, + "license": null, + "forks": 0, + "open_issues": 2, + "watchers": 0, + "default_branch": "master" + }, + "sender": { + "login": "Codertocat", + "id": 21031067, + "node_id": "MDQ6VXNlcjIxMDMxMDY3", + "avatar_url": "https://avatars1.githubusercontent.com/u/21031067?v=4", + "gravatar_id": "", + "url": "https://api.github.com/users/Codertocat", + "html_url": "https://github.com/Codertocat", + "followers_url": "https://api.github.com/users/Codertocat/followers", + "following_url": "https://api.github.com/users/Codertocat/following{/other_user}", + "gists_url": "https://api.github.com/users/Codertocat/gists{/gist_id}", + "starred_url": "https://api.github.com/users/Codertocat/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/Codertocat/subscriptions", + "organizations_url": "https://api.github.com/users/Codertocat/orgs", + "repos_url": "https://api.github.com/users/Codertocat/repos", + "events_url": "https://api.github.com/users/Codertocat/events{/privacy}", + "received_events_url": "https://api.github.com/users/Codertocat/received_events", + "type": "User", + "site_admin": false + } + } + ] +} +``` + +## Download webhook definitions and webhook payloads schema + +You can download the latest `index.json` file from +[unpkg](https://unpkg.com/@octokit/webhooks-examples/index.json) + +## Usage as Node module + +To get an array of all webhook definition objects, require the `@octokit/webhooks-examples` package. + +```js +// Use Node.js require: +const WEBHOOKS = require("@octokit/webhooks-examples/index.json"); + +// Or ESM/TypeScript import: +import WEBHOOKS from "@octokit/webhooks-examples/index.json"; +``` + +## How it works + +This package updates itself using a daily cronjob running on GitHub Actions. The +[`index.json`](index.json) file is generated by +[`bin/octokit-webhooks.ts`](bin/octokit-webhooks.ts). Run +`npm run octokit-webhooks -- --usage` for instructions. After the update is +complete, run `npm run build:webhooks` and `npm run build:schema` to update +`index.json` and `schema.json` files. + +The update script is scraping +[GitHub’s Webhooks Event Types & Payloads](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads) +documentation page and extracts the meta information using +[cheerio](https://www.npmjs.com/package/cheerio). + +For simpler local testing and tracking of changes all loaded pages are cached in +the [`cache/`](cache/) folder. + +## Adding examples - All payloads should end with `.payload.json`. - They should be placed in the folder whose name matches the event they're an @@ -17,3 +279,16 @@ E.g. After making any changes to example payloads, run `npm run build:webhooks -- --cached` to update the exported `index.json` file + +## See also + +- [octokit/graphql-schema](https://github.com/octokit/graphql-schema) – GitHub’s + GraphQL Schema with validation +- [octokit/openapi](https://github.com/octokit/openapi) – GitHub REST API route + specifications +- [octokit/app-permissions](https://github.com/octokit/app-permissions) – GitHub + App permission specifications + +## LICENSE + +[MIT](LICENSE.md) diff --git a/index.d.ts b/payload-examples/index.d.ts similarity index 100% rename from index.d.ts rename to payload-examples/index.d.ts diff --git a/index.json b/payload-examples/index.json similarity index 100% rename from index.json rename to payload-examples/index.json diff --git a/payload-examples/package.json b/payload-examples/package.json new file mode 100644 index 000000000..50a0ce9e1 --- /dev/null +++ b/payload-examples/package.json @@ -0,0 +1,20 @@ +{ + "name": "@octokit/webhooks-examples", + "version": "0.0.0-development", + "description": "Example webhook payloads contributed by the community", + "keywords": [], + "repository": "github:octokit/webhooks", + "license": "MIT", + "author": "Gregor Martynus (https://github.com/gr2m)", + "main": "index.json", + "files": [ + "index.d.ts", + "index.json" + ], + "scripts": {}, + "dependencies": {}, + "devDependencies": {}, + "publishConfig": { + "access": "public" + } +} diff --git a/payload-schemas/README.md b/payload-schemas/README.md new file mode 100644 index 000000000..6b3c221cf --- /dev/null +++ b/payload-schemas/README.md @@ -0,0 +1,59 @@ +# Octokit Webhooks + +> machine-readable, always up-to-date GitHub Webhooks specifications + +![Update status](https://github.com/octokit/webhooks/workflows/Update/badge.svg) + +## Download + +Download the latest specification at +[unpkg.com/@octokit/webhooks-schemas/schema.json](https://unpkg.com/@octokit/webhooks-schemas/schema.json) + +## Usage as Node module + +To get the JSON schema for webhook payloads, require the `@octokit/webhooks-schemas` package. + +```js +// Use Node.js require: +const SCHEMA = require("@octokit/webhooks-schemas"); + +// Or ESM/TypeScript import: +import SCHEMA from "@octokit/webhooks-schemas"; +``` + +### Usage with `ajv` in `strict` mode + +When running in `strict` mode, `ajv` will throw an "unknown keyword" error if it +encounters any keywords that have not been defined. + +This schema currently uses custom keywords provided by `ajv-formats`, along with +the custom keyword `tsAdditionalProperties`. + +Here is an example of how you can set this up: + +```ts +import type { WebhookEvent } from "@octokit/webhooks-types"; +import * as githubWebhookSchema from "@octokit/webhooks-schemas"; +import Ajv from "ajv"; +import addFormats from "ajv-formats"; + +const ajv = new Ajv({ strict: true }); + +addFormats(ajv); +ajv.addKeyword("tsAdditionalProperties"); + +const validate = ajv.compile(githubWebhookSchema); +``` + +## See also + +- [octokit/graphql-schema](https://github.com/octokit/graphql-schema) – GitHub’s + GraphQL Schema with validation +- [octokit/openapi](https://github.com/octokit/openapi) – GitHub REST API route + specifications +- [octokit/app-permissions](https://github.com/octokit/app-permissions) – GitHub + App permission specifications + +## LICENSE + +[MIT](LICENSE.md) diff --git a/payload-schemas/package.json b/payload-schemas/package.json new file mode 100644 index 000000000..4a2d37062 --- /dev/null +++ b/payload-schemas/package.json @@ -0,0 +1,19 @@ +{ + "name": "@octokit/webhooks-schemas", + "version": "0.0.0-development", + "description": "Community contributed webhook payload schemas in JSON schema format", + "keywords": [], + "repository": "github:octokit/webhooks", + "license": "MIT", + "author": "Gregor Martynus (https://github.com/gr2m)", + "main": "schema.json", + "files": [ + "schema.json" + ], + "scripts": {}, + "dependencies": {}, + "devDependencies": {}, + "publishConfig": { + "access": "public" + } +} diff --git a/payload-types/README.md b/payload-types/README.md new file mode 100644 index 000000000..6690b2842 --- /dev/null +++ b/payload-types/README.md @@ -0,0 +1,44 @@ +# Octokit Webhooks + +> machine-readable, always up-to-date GitHub Webhooks specifications + +![Update status](https://github.com/octokit/webhooks/workflows/Update/badge.svg) + +## Download + +Download the latest specification at +[octokit.github.io/webhooks/index.json](https://octokit.github.io/webhooks/index.json) + +## Usage + +This package ships with types for the webhook events generated from the +respective json schemas, which you can use like so: + +```typescript +import { WebhookEvent, IssuesOpenedEvent } from "@octokit/webhooks-types"; + +const handleWebhookEvent = (event: WebhookEvent) => { + if ("action" in event && event.action === "completed") { + console.log(`${event.sender.login} completed something!`); + } +}; + +const handleIssuesOpenedEvent = (event: IssuesOpenedEvent) => { + console.log( + `${event.sender.login} opened "${event.issue.title}" on ${event.repository.full_name}` + ); +}; +``` + +## See also + +- [octokit/graphql-schema](https://github.com/octokit/graphql-schema) – GitHub’s + GraphQL Schema with validation +- [octokit/openapi](https://github.com/octokit/openapi) – GitHub REST API route + specifications +- [octokit/app-permissions](https://github.com/octokit/app-permissions) – GitHub + App permission specifications + +## LICENSE + +[MIT](LICENSE.md) diff --git a/payload-types/package.json b/payload-types/package.json new file mode 100644 index 000000000..cd05b03bf --- /dev/null +++ b/payload-types/package.json @@ -0,0 +1,20 @@ +{ + "name": "@octokit/webhooks-types", + "version": "0.0.0-development", + "description": "Generated TypeScript definitions based on community contributed JSON Schemas", + "keywords": [], + "repository": "github:octokit/webhooks", + "license": "MIT", + "author": "Gregor Martynus (https://github.com/gr2m)", + "main": "", + "types": "schema.d.ts", + "files": [ + "schema.d.ts" + ], + "scripts": {}, + "dependencies": {}, + "devDependencies": {}, + "publishConfig": { + "access": "public" + } +} diff --git a/schema.d.ts b/payload-types/schema.d.ts similarity index 100% rename from schema.d.ts rename to payload-types/schema.d.ts diff --git a/test.ts b/test.ts index 798e369ed..16127d395 100644 --- a/test.ts +++ b/test.ts @@ -1,6 +1,6 @@ import Ajv, { ErrorObject } from "ajv"; import { JSONSchema7 } from "json-schema"; -import webhooks from "./index.json"; +import webhooks from "./payload-examples/index.json"; const ajv = new Ajv(); const schema: JSONSchema7 = {