[Mehdi-SK]

Summary

Turns the TypeScript Action template on main into the contribution event
tracker. When a pull request is merged, the Action builds one CloudEvents 1.0
event describing who did what and sends it to APICURON, so contributors can be
credited. A backfill script produces the same events for past pull requests.

This is the first release. Partner repositories will reference the Action at
@main.

How it works

1. Trigger. The workflow runs on pull_request_target (types: [closed])
   for merged pull requests.
2. Snapshot. The PR object from the webhook payload is reused; reviews,
   conversation comments, review comments and closing issues are fetched
   through the GitHub API (REST and GraphQL).
3. Build. A pure builder turns the snapshot into one event. Live capture
   and backfill share it.
4. Send. The event is posted to APICURON, or only logged in dry-run.

The event

• CloudEvents 1.0 envelope, type
  it.unipd.biocomputingup.github.pull_request.merged.
• source github:repository:{numeric id}, subject
pull_request/{number}, dataschema a w3id URI.
• Deterministic UUIDv5 id derived from repository id, PR number, event type
  and closed_at, so re-sending or backfilling the same PR gives the same id.
• data contains:
  • repository and pull_request metadata;
  • activities[]: opened, reviewed (with state), commented (conversation or
    review thread, with review_object_id), merged;
  • relationships[]: issues the PR closes;
  • capture: tool, version, mode (live or backfill), observed time.
• Metadata only: no comment bodies, diffs or code.
• Bots are dropped, activity after closed_at is excluded, and activities,
  relationships and labels are sorted so output is reproducible.

Main parts

Area	Location
Entry point and input handling	src/main.ts
Event processors (strategy per GitHub event, handler per action)	src/processors/
GitHub client and snapshot fetching	src/client/github/
Event builder and id generation	src/builders/
APICURON client	src/client/apicuron-client/
Backfill script and batch sender	src/scripts/
Event and snapshot types	src/types/
Generated JSON Schemas	schemas/

Action inputs

Input	Default	Purpose
apicuron-token	none	Token of a user managing the linked resource. Required unless dry-run
apicuron-url	https://apicuron.org/api	API base URL
dry-run	false	Build and log the event without sending
github-token	workflow token	Reads the pull request

There is deliberately no resource id input: the repository-to-resource link
lives in APICURON.

Delivery

• POST /tracker-events for one event, /tracker-events/batch for several.
• A missing token fails the run unless dry-run is true.
• No retry logic. Maintainers re-run a failed job; re-sent events are
  recognised as duplicates.

Backfill

yarn backfill <owner> <repo> [outFile] walks all merged pull requests, writes
every event to backfill-{owner}-{repo}-{timestamp}.jsonl, and, when
APICURON_TOKEN is set, sends them in batches packed by size (about 900 KB,
max 500 events) with split-and-retry on 413.

Also in this branch

• JSON Schemas generated from the TypeScript types (yarn schema).
• Unit tests for the builder, including a pinned event id that protects events
  already stored in APICURON.
• Partner-facing README (setup, inputs, dry-run, backfill, troubleshooting,
  draft contributor notice) and an example workflow.
• Template material removed and project metadata set; CI switched to yarn.

Testing

• Type-check, lint and format check pass.
• Builder tests pass (9).
• dist/ is built from the final source.
• Backfill run against BioComputingUP/disprot.

Notes for reviewers

• pull_request_target is used so pull requests from forks can access the
  secret. It is safe here because the Action only reads PR metadata through
  the API and never checks out or runs PR code.
• The dataschema URI does not resolve yet; the w3id redirect will be
  requested after this merge.
• The contributor notice in the README is a draft pending data-protection
  review.
• Only merged pull requests are tracked. Closed-unmerged pull requests are a
  known follow-up.

After merging

• Open the w3id pull request for the schema URIs.
• Link the first partner repository in APICURON and verify one live event.

🤖 Generated with Claude Code