JSON::RepositoryEvent

Representation of a repository event

NAME

JSON::RepositoryEvent - representation of a repository event

SYNOPSIS

use JSON::RepositoryEvent;
my $io = "foo.json".IO;

# create from incoming request
my $new = JSON::RepositoryEvent.new(%data, request);
$io.spurt(to-json($new));

# create from existing file
my $saved = JSON::RepositoryEvent.new($io.slurp);

DESCRIPTION

The JSON::RepositoryEvent provides a distribution for mapping repository related events in JSON format (such as typically provided by collaborative services such as GitHub / Codeberg in a webhook) into Raku classes with an object oriented interface.

All classes can be instantiated with the .new method and providing a correctly structured Map (or Hash). This is specifically needed when processing JSON-files that have been previously saved with the JSON::Webhook module.

CREATION FROM A WEBHOOK

The JSON::RepositoryEvent object can (also) be created using the information that is available inside a Cro::HTTP::Router route.

# create from incoming request
my $new = JSON::RepositoryEvent.new(%data, request);

The first argument is the data structure (usually a Map or a Hash, the second argument is the Cro::HTTP::Request object which contains all of the information needed.

Using the JSON::Webhook this can be as simple as:

sub processor(\data, \request) {
    JSON::RepositoryEvent.new(data, request)
}
JSON::Webhook.new(:&processor);

JSON::RepositoryEvent

The JSON::RepositoryEvent class wraps the data from a request in the payload accessor: this then contains an instances of any of the other JSON::RepositoryEvent::xxx classes.

METHODS

class - the type-object of the type of the payload
created-at - DateTime or Nil
headers - "key: value" of each header in the request
irc - list of IRC channels (named argument "irc" in request)
nameds - named arguments in query
payload - data blessed as a JSON::RepositoryEvent::xxx class

STATUS

This is still very much in alpha state. Quite a number of payloads from GitHub have been implemented, not so many from Forgejo yet. Help in implementing this is very much welcomed.

NAMING LOGIC

The data structures in the GitHub and Forgejo (e.g. Codeberg) API's typically use underscores in their names. No underscores are used in the Raku classes. If a name is mapped to a class, then an underscore created camelcase class names. So "pull_request" becomes PullRequest as a class name. Other fields that have an underscore map the underscores to hyphens, so "created_at" as the name of a field in the data structure, becomes "created-at" as an accessor (method name).

Some exceptions: field names that start with an underscore are used verbatim in method names (as methods starting with a hyphen are illegal in Raku). If a field name starts with +, it is replaced by the string "plus" in the method name. If a field name starts with -, it is replaces by the string "minus" in the method name.

THEORY OF OPERATION

The underlying data structure is always a Map (or a Hash). All classes are subclasses of Map, so all the functionality that you can expect from a Map can be used on any of the classes in this distribution.

All classes could be considered to be "views" on the underlying data structure: all "accessors" are in fact accessing certain parts of that data structure by key. This approach allows for fast loading: only actual parts of the data structure that need to be accessed, will be fetched on demand.

GITHUB EVENT CLASSES

The full name of these classes is JSON::RepositoryEvent::GitHub::Eventxxx. The JSON::RepositoryEvent part is not mentioned here in the documentation for convenience.

GitHub::EventCheckRun

action - action performed
check-run - see GitHub::CheckRun::CheckRun
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventCheckSuite

action - action performed
check-suite - see GitHub::CheckSuite::CheckSuite
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventCommitComment

action
comment - see GitHub::Comment
created-at - DateTime
organization - see GitHub::Organization
repository - see GitHub::Repository
sender - see GitHub::Actor
updated-at - DateTime
GitHub::EventCreate
description
master-branch
pusher-type
ref
ref-type
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventDelete

organization - see GitHub::Organization
pusher-type
ref
ref-type
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventFork

forkee - see GitHub::Repository
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventGollum

organization - see GitHub::Organization
pages - List of GitHub::Page
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventIssueComment

action - the action performed on an issue comment
comment - see GitHub::Comment
created-at - DateTime
issue - see GitHub::Issue
organization - see GitHub::Organization
repository - see GitHub::Repository
sender - see GitHub::Actor
updated-at - DateTime

GitHub::EventIssues

action - the action performed on an issue
issue - see GitHub::Issue
repository - see Forgejo::Repository
sender - see GitHub::Actor

GitHub::EventLabel

action - the action performed on a label
label - see GitHub::Label::Label
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventPing

hook - see GitHub::Hook
hook-id
last-response - see GitHub::Response
repository - see GitHub::Repository
sender - see GitHub::Actor
zen - random string of GitHub zen

GitHub::EventPublic

repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventPullRequest

action - action performed
organization - see GitHub::Organization
number - pull request number
pull-request - see GitHub::PullRequest
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventPullRequestComment

action - the action performed on a Pull Request comment
comment - see GitHub::Comment
created-at - DateTime
organization - see GitHub::Organization
pull-request - see GitHub::PullRequest
repository - see GitHub::Repository
sender - see GitHub::Actor
updated-at - DateTime

GitHub::EventPullRequestReview

action - the action performed on a Pull Request review
organization - see GitHub::Organization
pull-request - see GitHub::PullRequest
repository - see GitHub::Repository
sender - see GitHub::Actor

EventPullRequestReviewComment

comment - see GitHub::PullRequestComment
organization - see GitHub::Organization
pull-request - see GitHub::PullRequest
repository - see GitHub::Repository
sender - see GitHub::Actor

EventPullRequestReviewThread

action - the action performed on a Pull Request comment review thread
organization - see GitHub::Organization
pull-request - see GitHub::PullRequest
repository - see GitHub::Repository
sender - see GitHub::Actor
thread - see GitHub::PullRequestCommentThread

GitHub::EventPush

after - SHA of previous commit
base-ref - SHA of base reference
before - SHA of next commit
commits - list of one or more GitHub::PushCommit object
compare - compare URL
created - list of files created
deleted - list of files deleted
forced - was the push forced?
ref - SHA of reference
head-commit - see GitHub::PushCommit
pusher - see GitHub::Person
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventRelease

action - the action performed on a release
organization - see GitHub::Organization
release - see GitHub::Release
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventRepository

action - the action performed on a repository
repository - See GitHub::Repository
sender - see GitHub::Actor

GitHub::EventStar

action - the action performed on the star
repository - See GitHub::Repository
sender - see GitHub::Actor
starred-at - DateTime

GitHub::EventStatus

avatar-url
brances - List
commit - see GitHub::TreeCommit
context
created-at - DateTime
description
id
name
organization - see GitHub::Organization
repository - see GitHub::Repository
sender - see GitHub::Actor
sha
state
target-url
updated-at - DateTime

GitHub::EventWatch

action - the action performed related to watchers
repository - see GitHub::Repository
sender - see GitHub::Actor

GitHub::EventWorkflowJob

action - action performed
repository - see GitHub::Repository
sender - see GitHub::Actor
workflow - see GitHub::Workflow
workflow-job - see GitHub::WorkflowJob::WorkflowJob

GitHub::EventWorkflowRun

action - action performed
repository - see GitHub::Repository
sender - see GitHub::Actor
workflow - see GitHub::Workflow
workflow-run - see GitHub::WorkflowRun::WorkflowRun

GITHUB CLASSES

These classes represent (common) parts of the actual payload classes for GitHub events. The JSON::RepositoryEvent part is not mentioned here in the documentation for convenience.

GitHub::Actor

avatar-url
email
events-url
followers-url
following-url
gists-url
gravatar-id
html-url
id
login
name
node-id
organizations-url
received-events-url
repos-url
site-admin
starred-url
subscriptions-url
type
url
user-view-type

GitHub::App

client-id
created-at - DateTime
description
events - List
external-url
html-url
id
name
node-id
owner - see GitHub::Actor
permissions - see GitHub::Permissions
slug
updated-at - DateTime

GitHub::Asset

browser-download-url
content-type
created-at - DateTime
digest
download-count
id
label
name
node-id
size
state
updated-at - DateTime
uploader - see GitHub::Actor
url

GitHub::CheckRun

app - see GitHub::App
completed-at - DateTime
check-suite - see GitHub::CheckSuite
conclusion
details-url
external-id
head-sha
html-url
id
name
node-id
output - see GitHub::Output
pull-requests - List
started-at - DateTime
status
url

GitHub::CheckSuite

app - see GitHub::App
after
before
check-runs-url
conclusion
created-at - DateTime
head-branch
head-commit - see GitHub::PushCommit
head-sha
id
latest-check-runs-count
node-id
pull-requests - List
rerequestable
runs-rerequestable
status
updated-at - DateTime
url

GitHub::Comment

author-association
body
commit-id
created-at - DateTime
html-url
id
line
node-id
path
position
reactions - see GitHub::Reactions
updated-at - DateTime
user - see GitHub::Actor

GitHub::Commit

author - see GitHub::Actor
comments-url
commit - see GitHub::PushCommit
committer - see GitHub::Actor
html-url
node-id
parents - see GitHub::Tree
sha
url

GitHub::DependenciesSummary

blocked-by
blocking
total-blocked-by
total-blocking

GitHub::Hook

active
created-at
deliveries-url
name
ping-url
test-url
type
updated-at
url

GitHub::HookConfig

content-type
insecure-ssl
url

GitHub::Issue

active-lock-reason
assignee - see GitHub::Actor
assignees - List
author-association
body
closed-at - DateTime
comments
comments-url
created-at - DateTime
events-url
html-url
id
issue-dependendencies-summary - see GitHub::DependenciesSummary
issue-field-values - List
labels - List
labels-url
locked
milestone
node-id
number
performed-via-github-app
pinned-comment
reactions - see GitHub::Reactions
repository-url
state
state-reason
timeline-url
updated-at - DateTime
url
user - see GitHub::Actor

GitHub::Label

color
default
description
id
name
node-id
url

GitHub::License

key
name
node-id
spdx-id
url

GitHub::Link

href

GitHub::Organization

avatar_url
description
events-url
hooks-url
id
issues-url
login
members-url
node-id
public-members-url
repos-url
url

GitHub::Output

annotations-count
annotations-url
summary
text
title

GitHub::Page

Description of a change made to a page in the wiki.

action
html-url
page-name
sha
summary
title

GitHub::Permissions

actions
administration
artifact-metadata
attestations
checks
code-quality
contents
copilot-requests
deployments
discussions
drives
issues
merge-queues
metadata
models
packages
pages
pull-requests
repository-hooks
repository-projects
security-events
statuses
vulnerabity-alerts

GitHub::Person

date - DateTime
email
name
username

GitHub::PullRequest

_links - List of GitHub::Link
active-lock-reason
additions
assignee
assignees - List
author-association
auto-merge
base - see GitHub::State
body
changed-files
closed-at - DateTime
comments
comments-url
commits - List of GitHub::Commit
commits-url
created-at - DateTime
deletions
diff-url
draft
head - see GitHub::State
html-url
id
issue-url
labels - List
locked
maintainer-can-modify
merge-commit-sha
merged-at - DateTime
merged-by - see GitHub::Actor
mergeable
mergeable-state
merged
milestone
node-id
number
patch-url
rebaseable
repository - see GitHub::Repository
requested-reviewers - List
requested-teams - List
review-comment-url
review-comments
review-comments-url
sender - see GitHub::Actor
state
statuses-url
title
updated-at - DateTime
url
user - see GitHub::Actor

GitHub::PullRequestComment

_links - List of GitHub::Link
author-association
body
commit-id
created-at - DateTime
diff-hunk
html-url
id
in-reply-to-id
line
node-id
orginal-commit-id
original-line
original-position
original-start-line
path
position
pull-request-review-id
pull-request-url
reactions - see GitHub::Reactions
side
start-line
start-side
subject-type
updated-at - DateTime
url
user - see GitHub::Actor

PullRequestCommentThread

comments - List of PullRequestComment
node-id

GitHub::PushCommit

added - List
author - see GitHub::Person
committer - see GitHub::Person
distinct
id
message
modified - List
removed - List
tree-id
timestamp - DateTime
url

GitHub::Reactions

confused
eyes
heart
hooray
laugh
plus1
minus1
rocket
total-count
url

GitHub::Review

_links - List of GitHub::Link
author-association
body
commit-id
html-url
id
node-id
pull-request-url
state
submitted-at
updated-at

GitHub::Release

assets - List of GitHub::Asset
assets-url
author - see GitHub::Actor
body
created-at - DateTime
draft
html-url
id
immutable
name
node-id
published-at - DateTime
tag-name
tarball-url
target-commitish
updated-at - DateTime
upload-url
url
zipball-url

GitHub::Repository

allow-forking
archive-url
archived
assignees-url
blobs-url
branches-url
clone-url
collaborators-url
comments-url
commits-url
compare-url
contents-url
contributors-url
created-at - DateTime
default-branch
deployment-url
description
disabled
downloads-url
events-url
fork
forks
forks-count
forks-url
full-name
git-commits-url
git-refs-url
git-tags-url
git-url
has-discussions
has-downloads
has-issues
has-pages
has-projects
has-pull-requests
has-wiki
homepage
hooks-url
html-url
id
is-template
issue-comment-url
issue-events-url
issues-url
keys-url
labels-url
language
languages-url
license - see GitHub::License
master-branch
merges-url
milestones-url
mirror-url
name
node-id
notifications-url
open-issues
open-issues-count
owner - see GitHub::Actor
private
pull-request-creation-policy
pulls-url
pushed-at - DateTime
releases-url
size
ssh-url
stargazers
stargazers-count
stargazers-url
statuses-url
subscribers-url
subscription-url
svn-url
tags-url
teams-url
topics - List
trees-url
updated-at - DateTime
visibility
watchers
watchers-count
web-commit-signoff-required

GitHub::Response

code
message
status

GitHub::State

label
ref
repo - see GitHub::Repository
sha
user - see GitHub::Actor

GitHub::SubIssuesSummary

complete
percent-completed
total

GitHub::Tree

html-url
sha
url

GitHub::TreeCommit

author - see GitHub::Actor
committer - see GitHub::Actor
comment-count
message
tree - see GitHub::Tree
url
verification - see GitHub::Verification

GitHub::Verification

payload
reason
signature
verified
verified-at - DateTime

GitHub::Workflow

badge-url
created-at - DateTime
html-url
id
name
node-id
path
state
updated-at - DateTime
url

GitHub::WorkflowJob

check-run-url
completed-at - DateTime
conclusion
created-at - DateTime
head-branch
head-sha
html-url
id
labels - List
name
node-id
run-attempt
run-id
run-url
runner-group-id
runner-group-name
runner-id
runner-name
started-at - DateTime
status
steps - List, see GitHub::WorkflowJob::Step
url
workflow-name

GitHub::WorkflowRun

actor - see GitHub::Actor
artifacts-url
cancel-url
check-suite-id
check-suite-node-id
check-suite-url
conclusion
created-at - DateTime
display-title
event
head-branch
head-commit - see GitHub::PushCommit
head-sha
html-url
id
jobs-url
logs-url
name
node-id
path
previous-attempt-url
pull-requests -List
references-workflows -List
repository - see GitHub::Repository
rerun-url
run-attempt
run-number
run-started-at - DateTime
status
triggering-actor - see GitHub::Actor
updated-at - DateTime
url
workflow-id
workflow-url

FORGEJO EVENTS CLASSES

The full name of these classes is JSON::RepositoryEvent::Forgejo::Eventxxx. The JSON::RepositoryEvent part is not mentioned here in the documentation for convenience.

Forgejo::EventCreate

ref
ref-type
repository - see Forgejo::Repository
sender - see Forgejo::Actor
sha

Forgejo::EventDelete

pusher-type
ref
ref-type
repository - see Forgejo::Repository
sender - see Forgejo::Actor

Forgejo::EventFork

forkee - see Forgejo::Repository
repository - see Forgejo::Repository
sender - see Forgejo::Actor

Forgejo::EventIssueComment

action - the action performed on an issue comment
comment - see Forgejo::Comment
created-at - DateTime
issue - see Forgejo::Issue
organization - see Forgejo::Organization
repository - see Forgejo::Repository
sender - see Forgejo::Actor
updated-at - DateTime

Forgejo::EventIssues

action - the action performed on an issue
commit-id - SHA of associated commit
issue - see Forgejo::Issue
number - the issue number
repository - see Forgejo::Repository
sender - see Forgejo::Actor

Forgejo::EventPullRequest

action - action performed
organization - see Forgejo::Organization
number - pull request number
pull-request - see Forgejo::PullRequest
repository - see Forgejo::Repository
sender - see Forgejo::Actor

Forgejo::EventPullRequestComment

action - the action performed on a Pull Request comment
comment - see Forgejo::Comment
created-at - DateTime
organization - see Forgejo::Organization
pull-request - see Forgejo::PullRequest
repository - see Forgejo::Repository
sender - see Forgejo::Actor
updated-at - DateTime

Forgejo::EventPush

after - SHA of previous commit
before - SHA of next commit
commits - List of Forgejo::Commit
compare-url - compare URL
head-commit - see Forgejo::Commit
pusher - see Forgejo::Actor
ref - SHA of reference
repository - see Forgejo::Repository
sender - see Forgejo::Actor
total-commits - number of commits in this push

FORGEJO CLASSES

These classes represent (common) parts of the actual payload classes for Forgejo (Codeberg) events. The JSON::RepositoryEvent part is not mentioned here in the documentation for convenience.

Forgejo::Actor

active
avatar-url
created - DateTime
description
email
followers-count
following-count
full-name
html-url
id
is-admin
language
last-login - DateTime
location
login
login-name
prohibit-login
pronouns
restricted
source-id
starred-repos-count
username
visibility
website

Forgejo::Commit

added - List
author - see Forgejo::Person
committer - see Forgejo::Person
id
message
modified - List
removed - List
timestamp - DateTime
url
verification

Forgejo::Issue

assets - List
assignee - see Forgejo::Actor
assignees - List of Forgejo::Actor
body
closed-at - DateTime
created-at - DateTime
comments
due-date
html-url
id
is-locked
labels - List
milestone
number
original-author
original-author-id
pin-orer
pull-request
ref
state
title
updated-at - DateTime
url

Forgejo::Permissions

admin
pull
push

Forgejo::Person

email
name
username

Forgejo::PullRequest

additions
allow-maintainer-edit
assignee
assignees - List
base - see Forgejo::State
body
changed-files
closed-at - DateTime
comments
created-at - DateTime
deletions
diff-url
draft
head - see GitHub::State
html-url
id
issue-url
is-locked
labels - List
merge-commit-sha
merged-at - DateTime
merged-by - see GitHub::Actor
mergeable
merged
milestone
number
patch-url
pin-order
rebaseable
repository - see GitHub::Repository
requested-reviewers - List
requested-teams - List
review-comments
state
title
updated-at - DateTime

Forgejo::Repository

allow-fast-forward-only-merge
allow-merge-commits
allow-rebase
allow-rebase-explicit
allow-rebase-update
allow-squash-merge
archived
archived-at - DateTime
avatar-url
clone-url
created-at - DateTime
default-allow-maintainer-edit
default-branch
default-delete-branch-after-merge
default-merge-style
default-update-style
description
empty
fork
forks-count
full-name
globally-editable-wiki
has-actions
has-issues
has-projects
has-pull-requests
has-releases
has-wiki
has-wiki-contents
html-url
id
ignore_whitespace_conflicts
internal
internal-tracker - see Forgejo::Tracker
language
languages-url
link
mirror
mirror-interval
mirror-updated - DateTime
name
object-format
open-issues-count
open-pr-counter
original-url
owner - see Forgejo::Actor
permissions - see Forgejo::Permissions
parent
private
release-counter
repo-transfer
size
ssh-url
stars-count
template
topics - List
updated-at - DateTime
url
watchers-count
website
wiki-branch
wiki-clone-url
wiki-ssh-url

Forgejo::State

label
ref
repo - see Forgejo::Repository
repo-id
sha
user - see Forgejo::Actor

Forgejo::Tracker

allow-only-contributors-to-track-time
enable-issue-dependencies
enable_time_tracker

AUTHOR

Elizabeth Mattijsen [email protected]

COPYRIGHT AND LICENSE

Source can be located at: https://codeberg.org/lizmat/JSON-RepositoryEvent . Comments and Pull Requests are welcome.

If you like this module, or what I'm doing more generally, committing to a small sponsorship would mean a great deal to me!

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.