mirror of
https://github.com/Elysola/WebHooker.git
synced 2026-11-20 17:13:49 +00:00
Synchronize both language guides, API references and examples with the implemented authorization, storage and delivery behavior. Document migration requirements and accepted operational limits.
8.4 KiB
8.4 KiB
Contributing
Development Setup
git clone https://github.com/Elysola/WebHooker.git
cd WebHooker
bun install
cp .env.example .dev.vars # Fill in secrets
bun run dev # Start local dev server
Project Structure
app/ # Vue 3 UI (Nuxt app dir)
├── app.vue # Root component (NuxtPage)
├── assets/css/main.css # Tailwind CSS v4 entry: Elysola UI-compatible RGB aliases + bespoke layout classes
├── pages/ # index (landing), terms, privacy, admin/[...slug] (console SPA)
├── components/ # ConsolePage, RouteCard/Editor, GroupEditor, MembersPanel, WebhookPanel,
│ # SendLogs, AuditLog, AppToasts, LegalLayout
├── composables/ # useI18n, useToasts, useGroups, useGroupRoutes, useLogs, useAudit, useInvites, useWebhook
├── types.ts # Shared client types (Route, Group, Filter, ...)
└── utils/legal.ts # Terms/privacy HTML bodies (zh/en)
server/ # Nitro server (H3 handlers in server/routes/)
├── routes/ # /health, /webhook[/:groupId], /discord/interactions, /telegram/webhook,
│ # /auth/github*, /admin/{login,logout,invite,api/**}, /api/{comment,merge,close,react,richheader}
├── tasks/ # Scheduled (cron */5): discord-sync, telegram-sync, audit-prune, storage-prune
├── error-handler.ts # JSON error handler
└── lib/
├── types.ts # Env, Config, Route, Filter, Group, WebhookEvent, NeutralMessage
├── config.ts # Binds the D1 config store, loads routes/groups (fresh or cached), builds Config from env
├── core/
│ └── dispatch.ts # Platform-neutral dispatch: match routes → formatEvent → getDriver().send/edit
├── events/ # Provider-agnostic route matching
│ ├── match.ts # matchRoute, eventOwners
│ └── filter-ast.ts # filter evaluation (flat filters + all/any/not AST), extractBranch, keyword search, RE2 patterns
├── providers/ # Forge webhook providers (verify + parse/normalize)
│ ├── types.ts # Provider interface (matches/verify/parse)
│ ├── index.ts # detectProvider() registry (github, gitea, custom)
│ ├── github/ # X-GitHub-Event + X-Hub-Signature-256
│ └── gitea/ # X-Gitea-Event + X-Gitea-Signature (normalized payloads)
├── formatters/ # Platform-neutral formatters (produce NeutralMessage)
│ ├── index.ts # formatEvent: builds the context, finds the formatter in the registry → NeutralMessage
│ ├── registry.ts # eventFormatters[]: event names → formatter
│ ├── colors.ts # GITHUB_COLORS + WORKFLOW_CONCLUSION_EMOJI
│ ├── helpers.ts # emojiPrefix, T, buildMessage, commitLink/branchLink/tagLink
│ └── *.ts # push, pull-request, issues, comments, workflow, release, create, repo,
│ # check, review, commit-comment, deployment, member, label, milestone,
│ # discussion, repository, security, generic, ping, custom
├── drivers/ # Platform drivers (pluggable push targets)
│ ├── types.ts # PlatformDriver interface + SendResult (send + edit)
│ ├── index.ts # getDriver() registry (discord + telegram + feishu)
│ ├── discord/ # index.ts (driver), render.ts (NeutralMessage → embed),
│ │ # rest.ts, interactions.ts, commands.ts
│ └── telegram/ # index.ts (driver), render.ts (NeutralMessage → Telegram HTML),
│ # rest.ts (chat_id + message_thread_id), updates.ts (webhook verify),
│ # commands.ts (/gh login|logout|comment|merge|close + reply parsing)
├── github/ # GitHub OAuth + as-user actions
│ ├── oauth.ts # OAuth URL, callback token exchange, getUserOctokit, comment/merge/close actions
│ └── store.ts # KV token CRUD + D1 discord-link/telegram-link mapping
├── web/ # HTTP UI/API logic (called from server/routes)
│ ├── oauth.ts # GET /auth/github, callback (admin session / discord-link / telegram-link / install bind)
│ ├── actions.ts # POST /api/comment|merge|close|react (Bearer token auth via KV lookup)
│ ├── admin.ts # /admin API: routes, groups, me, logs, invites, audit (session + scope auth)
│ ├── auth.ts # Shared auth middleware + guards
│ ├── invites.ts # Invite CRUD + acceptInvite
│ ├── session.ts # Admin session CRUD (KV session:{id}), cookie helpers
│ ├── groups.ts # Group loading, group-admin access scoping
│ ├── tenants.ts # Per-group webhook secret CRUD
│ └── richheader.ts # GET /api/richheader (Telegram avatar card)
└── lib/ # Shared infrastructure
├── i18n.ts # Message language overrides (en/zh)
├── send-log.ts # Send logging (D1 send_logs)
├── audit.ts # Audit logging (D1 audit_logs)
├── log.ts # JSON console logger (info/warn/error/fatal)
└── locales/ # en.ts, zh.ts translation dictionaries
tests/ # Unit tests (bun test)
tests/fixtures/ # Provider payload fixtures (github/gitea/custom)
tests/__snapshots__/ # Formatter snapshot golden files
Continuous integration (.github/workflows/ci.yml) runs bun install --frozen-lockfile,
bun test, and bun run lint. CodeQL (codeql.yml) and Dependabot (dependabot.yml) are
configured under .github/.
Scripts
| Command | Description |
|---|---|
bun run dev |
Start Nuxt dev server (HMR) |
bun run typecheck |
TypeScript type checking |
bun run lint |
ESLint (TypeScript) |
bun run lint:md |
Markdownlint (Markdown) |
bun test |
Run unit tests (bun test) |
bun run format |
Format all files with Prettier |
bun run format:check |
Check Prettier formatting |
bun run docs:dev |
Start VitePress docs dev server |
bun run docs:build |
Build docs site |
Code Style
- TypeScript with strict mode
- Double quotes for strings
- Semicolons required
- Trailing commas in all positions
- 100 char print width
- ESLint with
@typescript-eslintrecommended rules - Prettier for formatting
- Markdownlint for markdown files
Testing
# Run the unit test suite (bun test)
bun test
# Or manually check the health endpoint
curl http://localhost:8787/health
Beyond the per-module unit tests, the suite includes provider fixtures
(tests/fixtures/ + tests/provider-fixtures.test.ts), formatter snapshots
(tests/formatter-snapshot.test.ts), and platform contract tests
(tests/platform-contract.test.ts) that assert the Discord/Telegram renderers clamp to their
platform limits.
Adding a New Event Formatter
- Add the event type to
GITHUB_COLORSinserver/lib/formatters/colors.ts(if new color needed) - Add action labels to the locale dictionaries in
server/lib/lib/locales/en.tsandserver/lib/lib/locales/zh.ts(if new actions) - Create a
formatEventTypefunction inserver/lib/formatters/ - Register it in
eventFormattersinserver/lib/formatters/registry.ts({ events: ["your_event"], format: (c) => … }) - Update
extractBranchinserver/lib/events/filter-ast.tsif the event has branch info - Add the event to the documentation in
docs/events/supported.mdanddocs/zh/events/supported.md - Add the event to the README (
README.mdandREADME.zh.md) event tables and the GitHub App event subscription list - Subscribe to the event in your GitHub App settings
Pull Request Guidelines
- Keep changes focused and atomic
- Include type annotations for all function returns
- Run
bun run typecheck && bun run lint && bun run format:checkbefore submitting - Update documentation if adding features (see the checklist in
AGENTS.md→ Documentation): README (README.md/README.zh.md), VitePress docs (docs/anddocs/zh/), and example config files