Files
WebHooker/server/lib/types.ts
T

441 lines
14 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
export interface Env {
GITHUB_WEBHOOK_SECRET: string;
GITEA_WEBHOOK_SECRET?: string;
GITHUB_APP_ID?: string;
GITHUB_PRIVATE_KEY?: string;
GITHUB_CLIENT_ID?: string;
GITHUB_CLIENT_SECRET?: string;
DISCORD_TOKEN?: string;
BASE_URL?: string;
ADMIN_USER_IDS?: string;
DEBUG_MODE?: string;
DISCORD_PUBLIC_KEY?: string;
DISCORD_APPLICATION_ID?: string;
TELEGRAM_TOKEN?: string;
TELEGRAM_WEBHOOK_SECRET?: string;
TELEGRAM_RICH_HEADER_HOST?: string;
FEISHU_APP_ID?: string;
FEISHU_APP_SECRET?: string;
/**
* Feishu event "Encrypt Key": verifies `X-Lark-Signature` and decrypts
* encrypted callbacks. This or FEISHU_VERIFICATION_TOKEN is required for
* inbound Feishu commands and card buttons.
*/
FEISHU_ENCRYPT_KEY?: string;
/** Feishu event "Verification Token", checked against every callback payload. */
FEISHU_VERIFICATION_TOKEN?: string;
/**
* When enabled ("1"/"true"), GitHub users without any group access get a
* personal group on first login instead of being blocked.
*/
ALLOW_SELF_SIGNUP?: string;
/** Audit log retention in days (default 90). */
AUDIT_RETENTION_DAYS?: string;
/**
* Where webhook delivery state is kept: `d1` (default) or `kv`. D1 allows
* far more free writes but each one is a database round trip; KV answers at
* the edge and is best effort (no compare-and-set).
*/
DELIVERY_STATE_STORE?: string;
ASSETS?: Fetcher;
KV: KVNamespace;
DB: D1Database;
QUEUE?: Queue;
PAYLOAD?: R2Bucket;
}
export interface Config {
baseUrl: string;
github: {
webhookSecret: string;
appId: number;
privateKey: string;
clientId: string;
clientSecret: string;
};
discord: {
token: string;
};
routes: Route[];
/**
* Groups with a stored route that could not be read. Their events are
* reported as transient failures instead of passing for delivered while a
* route that might have matched was silently left out.
*/
unreadableGroups?: string[];
}
export interface RouteTarget {
platform?: "discord" | "telegram" | "feishu";
channelId?: string;
threadId?: string;
chatId?: string;
topicId?: string;
}
export interface Route {
id: string;
name: string;
enabled: boolean;
filters: Filter[];
targets: RouteTarget[];
groupId?: string;
/**
* Optional explicit filter expression tree. When present it replaces the
* flat `filters` array (which is equivalent to `{ all: filters }`). Omitted
* on routes stored without an AST — matching falls back to `filters`.
*/
ast?: FilterNode;
/**
* Fallback route: only fires when no other (non-fallback) route of the same
* group matched the event. Multiple fallback routes may exist; a group's are
* all skipped whenever one of its regular routes matches. Its own filters
* still apply.
*/
fallback?: boolean;
/**
* Stop: when true and this route matches, no further routes of the same
* group are evaluated for this event (other groups are unaffected). Useful
* for exclusive routing where a match should prevent fallthrough to the
* group's subsequent routes.
*/
stop?: boolean;
/**
* Discord role (身份组) ids to mention/notify when this route fires. Roles
* are only mentioned in Discord targets; Telegram targets ignore this field.
*/
discordRoleIds?: string[];
}
export type GroupRole = "owner" | "admin" | "viewer";
export interface GroupMember {
/**
* GitHub login (case-insensitive). An unbound all-digit entry (legacy
* `adminIds`) is read as a user id; see `memberMatches`.
*/
login: string;
role: GroupRole;
/**
* Immutable GitHub user id of the member, bound by the server (invite
* acceptance, the member's sign-in). Once bound, only that account matches.
*/
userId?: string;
}
export interface Group {
id: string;
name: string;
/**
* Deprecated legacy field: GitHub user ids or logins allowed to manage this
* group. Kept for backward compatibility — when `members` is absent, these
* are normalized to `members` with role "owner". New writes use `members`.
*/
adminIds: string[];
/**
* Group members with roles. Roles: owner (manage group + members + invites),
* admin (manage routes), viewer (read-only). Super admins always bypass.
*/
members?: GroupMember[];
/**
* GitHub organization/user logins (case-insensitive) whose webhook events are
* allowed into this group's routes. Empty/omitted = no owner restriction.
* Only super admins may edit this field.
*/
owners?: string[];
/**
* Webhook providers (source platforms) allowed into this group's routes
* (e.g. `["github"]`, `["gitea"]`). Empty/omitted = all providers.
*/
providers?: WebhookProvider[];
/**
* GitHub App installation id bound to this group. When set, only webhook
* events coming from that installation (org/user) are accepted into the
* group's routes — hard tenant isolation on top of (or instead of) the
* `owners` list. Empty/omitted = no installation restriction.
*/
installationId?: number;
/**
* Isolated groups (self-service personal groups) only receive events from
* their own `/webhook/{groupId}` ingress; the global endpoint dispatches to
* them only once a super admin binds a source (`installationId` or
* `owners`). Only super admins may edit this field.
*/
isolated?: boolean;
/**
* Immutable identity of this group, assigned by the server when the group is
* created and kept across renames. A group re-created under a former id gets
* a new one, so invites and delivery ledgers of the old group never apply to
* it. Clients cannot set it.
*/
instance?: string;
/**
* Set when the group got its `instance` from the one-time backfill, i.e. it
* existed before instances: only such a group may adopt state stored under
* its id (a pre-instance webhook secret or invite). Server-owned.
*/
instanceBackfilled?: boolean;
/**
* For a backfilled group: the id it had when it got its instance. State
* stored under a group id before instances (a webhook secret, an invite, a
* queued delivery) belongs to the group with that `legacyId` only — not to
* whichever group holds the id now (another one may have been renamed to
* it). Server-owned, kept across renames.
*/
legacyId?: string;
/**
* The group's webhook secret (per-group ingress). Server-owned, stored with
* the group so it changes only through a compare-and-swap that re-checks the
* writer's role; never sent to clients. `null` in a mutation removes it.
*/
webhookSecret?: string | null;
/**
* Opaque revision of the stored group, set on read by the admin API and
* echoed back on update so a stale edit is rejected instead of overwriting a
* newer one. Never persisted.
*/
revision?: string;
/**
* Whether to include emoji in messages sent through this group's routes.
* Defaults to true when omitted.
*/
emoji?: boolean;
/**
* Named forge sources shown in the footer of this group's messages. Each
* entry pairs a host (e.g. `git1.example.com`) with a source type
* (`github` / `gitea`) and an optional display `name`; an event is labeled
* with the first entry whose type matches its provider and whose host
* matches the repository URL's hostname (GitHub events match `github.com`).
* Empty/omitted = no forge label.
*/
forgeSources?: ForgeSource[];
/**
* Message language for every route in this group (e.g. "en", "zh"; custom
* via KV i18n:<lang>). Defaults to "en" when omitted.
*/
lang?: string;
/**
* Discord channel/thread or Telegram chat/topic that receives a summary of
* every webhook this group's routes dispatch (the group's webhook log).
*/
logTarget?: RouteTarget;
}
export type FilterType = "event" | "repo" | "actor" | "action" | "branch" | "keyword" | "field";
export type FilterOp =
| "eq"
| "ne"
| "contains"
| "startsWith"
| "endsWith"
| "regex"
| "gt"
| "gte"
| "lt"
| "lte"
| "in"
| "exists";
export interface Filter {
type: FilterType;
match?: string | string[];
exclude?: boolean;
/**
* JSONPath (dot notation, arrays expanded so any element matches) into
* `payload` used by `type: "field"` filters. E.g. `pull_request.user.login`.
*/
path?: string;
/**
* Comparison operator. Defaults to `eq`, which keeps the legacy glob/regex/
* case-insensitive-exact semantics. `exists` ignores `match`.
*/
op?: FilterOp;
}
/**
* A filter node matches an event when every child matches.
*/
export interface FilterAll {
all: FilterNode[];
}
/**
* A filter node matches an event when any child matches.
*/
export interface FilterAny {
any: FilterNode[];
}
/**
* A filter node matches an event when its child does not match.
*/
export interface FilterNot {
not: FilterNode;
}
/**
* A composable filter expression tree. Leaf nodes are `Filter`; the `all`,
* `any` and `not` nodes compose them. A route's `filters` array stays the
* flat AND-of-filters form (equivalent to `{ all: filters }`); `ast` optionally
* replaces it with an explicit tree.
*/
export type FilterNode = Filter | FilterAll | FilterAny | FilterNot;
export type WebhookProvider = "github" | "gitea" | "gitlab" | "custom";
export interface WebhookEvent {
event: string;
payload: Record<string, unknown>;
signature?: string;
deliveryId?: string;
provider?: WebhookProvider;
/**
* GitHub App installation id that produced this event (extracted from
* `payload.installation.id`). Gitea/custom events have none.
*/
installationId?: number;
}
/**
* A forge-agnostic webhook event after provider verification and
* normalization: the canonical shape every provider's `parse` output conforms
* to, plus the tenant scope (`groupId`) and receipt time carried through the
* delivery pipeline.
*/
export interface NormalizedWebhook {
provider: WebhookProvider;
deliveryId: string;
event: string;
groupId?: string;
payload: Record<string, unknown>;
installationId?: number;
receivedAt: number;
}
export interface NeutralAuthor {
name: string;
iconUrl?: string;
url?: string;
}
export type ForgeType = "github" | "gitea";
/**
* A forge host a group configures itself. When an event's repository host
* matches `host`, the message footer is labeled with `name` (when set) or the
* host itself — e.g. two self-hosted Gitea instances can be shown as
* "内网 Gitea" / "Git2 仓库" while matched by git1.example.com /
* git2.example.com. GitHub events match `github.com` (or a GitHub Enterprise
* host). Link/icon are derived from the repository URL (https, port preserved).
*/
export interface ForgeSource {
/** Hostname matched against the repository URL (case-insensitive). */
host: string;
type: ForgeType;
/** Optional display label shown in the message footer; falls back to `host`. */
name?: string;
}
/**
* The forge (source platform) that produced an event: shown in the message
* footer when the group defines a matching `Group.forgeSources` entry so
* recipients can tell GitHub and Gitea instances apart at a glance.
*/
export interface NeutralForge {
/** Display name: the source's `name` or its host (e.g. "内网 Gitea"). */
name: string;
/** Site URL for the hyperlink (Telegram) / brand context (Discord). */
url?: string;
/** Site favicon used as the Discord embed footer icon. */
iconUrl?: string;
}
export interface NeutralField {
name: string;
value: string;
inline?: boolean;
}
export type NeutralActionStyle = "primary" | "danger" | "secondary";
export interface NeutralAction {
id: string;
label: string;
style: NeutralActionStyle;
}
export interface NeutralMessage {
author?: NeutralAuthor;
title: string;
url?: string;
color?: number;
description?: string;
fields?: NeutralField[];
footer?: string;
timestamp?: string;
actions?: NeutralAction[];
/**
* Forge branding set by dispatch when `Group.forgeLabel` is enabled; drivers
* render it in the footer (Discord icon + name, Telegram linked name).
*/
forge?: NeutralForge;
/**
* Stable key identifying a message chain that should be updated in place
* (e.g. workflow run progress). When set, subsequent events edit the
* previously sent message instead of sending a new one.
*/
updateKey?: string;
/**
* The chain key this message had before `updateKey` changed shape, used
* only to find a message tracked under the old key (then re-keyed).
*/
legacyUpdateKey?: string;
/**
* Stable identity of this message for one target, the same in every
* attempt of a delivery (set by dispatch from delivery × route × target).
* Platforms with request idempotency (Discord `nonce`, Feishu `uuid`) use
* it, so a retry after a lost response never posts the message twice.
*/
sendKey?: string;
/**
* Discord role ids to mention in the message content (set by dispatch from
* the route's `discordRoleIds`). Only used by the Discord driver.
*/
mentionRoleIds?: string[];
/**
* False when the group turned emoji off: drivers must not add decorative
* emoji of their own (e.g. Telegram's author marker). Defaults to true.
*/
emoji?: boolean;
}
export interface FormattedMessage {
content?: string;
embeds?: Array<{
title?: string;
description?: string;
url?: string;
color?: number;
author?: {
name: string;
icon_url?: string;
url?: string;
};
fields?: Array<{ name: string; value: string; inline?: boolean }>;
footer?: { text: string; icon_url?: string };
timestamp?: string;
}>;
components?: Array<{
type: number;
components: Array<{
type: number;
style?: number;
label?: string;
custom_id?: string;
}>;
}>;
/** Which mentions in `content` may notify; set so only the route's roles ping. */
allowed_mentions?: { parse: string[]; roles?: string[] };
}