koishi-plugin-github-webhook-pusher 0.0.6 → 0.0.7

package/lib/commands/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 命令模块入口
+ */
+export { registerTrustCommands } from './trust';
+export { registerSubscriptionCommands } from './subscription';
+export { registerUtilCommands } from './utils';

package/lib/commands/subscription.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 订阅管理命令
+ * 需求: 3.1-3.7
+ */
+import { Context } from 'koishi';
+import { Config } from '../config';
+/**
+ * 注册订阅管理命令
+ * @param ctx Koishi 上下文
+ * @param config 插件配置
+ */
+export declare function registerSubscriptionCommands(ctx: Context, config: Config): void;

package/lib/commands/trust.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 信任仓库管理命令
+ * 需求: 2.1-2.5, 8.3
+ */
+import { Context } from 'koishi';
+/**
+ * 注册信任仓库管理命令
+ * @param ctx Koishi 上下文
+ */
+export declare function registerTrustCommands(ctx: Context): void;

package/lib/commands/utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 工具命令
+ * 需求: 8.1, 8.2
+ */
+import { Context } from 'koishi';
+import { Config } from '../config';
+/**
+ * 注册工具命令
+ * @param ctx Koishi 上下文
+ * @param config 插件配置
+ */
+export declare function registerUtilCommands(ctx: Context, config: Config): void;

package/lib/config.d.ts

@@ -0,0 +1,20 @@
+import { Schema } from 'koishi';
+import { EventType } from './types';
+export { EventType };
+export interface Config {
+    /** Webhook 接收路径 */
+    path: string;
+    /** GitHub Webhook Secret */
+    secret: string;
+    /** 显示用基础 URL */
+    baseUrl?: string;
+    /** 默认订阅事件 */
+    defaultEvents: EventType[];
+    /** 调试模式 */
+    debug: boolean;
+    /** 允许非信任仓库 */
+    allowUntrusted: boolean;
+    /** 推送并发数 */
+    concurrency: number;
+}
+export declare const Config: Schema<Config>;

package/lib/database.d.ts

@@ -0,0 +1,35 @@
+import { Context } from 'koishi';
+import { EventType } from './types';
+declare module 'koishi' {
+    interface Tables {
+        github_trusted_repos: TrustedRepo;
+        github_subscriptions: Subscription;
+        github_deliveries: Delivery;
+    }
+}
+export interface TrustedRepo {
+    id: number;
+    repo: string;
+    enabled: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Subscription {
+    id: number;
+    platform: string;
+    channelId: string;
+    guildId: string;
+    userId: string;
+    repo: string;
+    events: EventType[];
+    enabled: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface Delivery {
+    deliveryId: string;
+    repo: string;
+    event: string;
+    receivedAt: Date;
+}
+export declare function extendDatabase(ctx: Context): void;

package/lib/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Koishi GitHub Webhook 推送插件入口
+ * 需求: 1.1, 7.1-7.7
+ */
+import { Context } from 'koishi';
+import { Config } from './config';
+/** 插件名称 */
+export declare const name = "github-webhook-pusher";
+/** 声明服务依赖 - 需要 server 服务提供 router 和 database 服务 */
+export declare const inject: string[];
+/** 导出配置 Schema */
+export { Config };
+/**
+ * 插件入口函数
+ * @param ctx Koishi 上下文
+ * @param config 插件配置
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/message.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 消息构建器
+ * 需求: 5.3, 5.4, 5.5
+ */
+import { Element } from 'koishi';
+import { ParsedEvent } from './types';
+/**
+ * 构建推送消息
+ * @param event 解析后的事件
+ * @returns Koishi Element 消息数组
+ */
+export declare function buildMessage(event: ParsedEvent): Element[];

package/lib/parser.d.ts

@@ -0,0 +1,65 @@
+/**
+ * GitHub Webhook 事件解析器
+ * 需求: 4.1-4.7
+ */
+import { ParsedEvent } from './types';
+/**
+ * 解析 Issues 事件
+ * 需求 4.1: 提取 issue 标题、编号、操作者和链接
+ */
+export declare function parseIssuesEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Issue Comment 事件
+ */
+export declare function parseIssueCommentEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Release 事件
+ * 需求 4.2: 提取版本号、发布者和下载链接
+ */
+export declare function parseReleaseEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Push 事件
+ * 需求 4.3, 4.6: 提取分支名、提交列表（最多5条）和推送者信息
+ */
+export declare function parsePushEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Pull Request 事件
+ * 需求 4.4: 提取 PR 标题、编号、操作者和链接
+ */
+export declare function parsePullRequestEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Pull Request Review 事件
+ */
+export declare function parsePullRequestReviewEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Pull Request Review Comment 事件
+ */
+export declare function parsePullRequestReviewCommentEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Star 事件
+ * 需求 4.5: 提取操作者和当前 star 数量
+ */
+export declare function parseStarEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Fork 事件
+ */
+export declare function parseForkEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Create 事件
+ */
+export declare function parseCreateEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Delete 事件
+ */
+export declare function parseDeleteEvent(payload: any): ParsedEvent | null;
+/**
+ * 解析 Workflow Run 事件
+ */
+export declare function parseWorkflowRunEvent(payload: any): ParsedEvent | null;
+/**
+ * 统一的事件解析入口函数
+ * @param eventName X-GitHub-Event 头的值
+ * @param payload 解析后的 JSON 负载
+ * @returns 解析后的事件数据，不支持的事件返回 null
+ */
+export declare function parseEvent(eventName: string, payload: any): ParsedEvent | null;

package/lib/pusher.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 消息推送器
+ * 需求: 5.1, 5.2, 5.6, 5.7
+ */
+import { Context, Element } from 'koishi';
+import { EventType, ParsedEvent } from './types';
+import { PushTarget } from './repository/subscription';
+/** 推送结果 */
+export interface PushResult {
+    target: PushTarget;
+    success: boolean;
+    error?: Error;
+}
+/**
+ * 查询订阅目标
+ * 需求 5.1: 查询所有订阅该仓库的目标会话
+ * 需求 5.2: 根据订阅的事件类型过滤目标
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @param eventType 事件类型
+ * @returns 推送目标列表
+ */
+export declare function queryTargets(ctx: Context, repo: string, eventType: EventType): Promise<PushTarget[]>;
+/**
+ * 并发推送消息到多个目标
+ * 需求 5.6: 使用 Promise.allSettled 并发推送并限制并发数
+ * 需求 5.7: 推送失败记录错误日志但不影响其他目标的推送
+ * @param ctx Koishi 上下文
+ * @param targets 推送目标列表
+ * @param message 消息内容
+ * @param concurrency 并发数限制
+ * @returns 推送结果列表
+ */
+export declare function pushWithConcurrency(ctx: Context, targets: PushTarget[], message: Element[], concurrency: number): Promise<PushResult[]>;
+/**
+ * 推送消息到所有订阅目标
+ * @param ctx Koishi 上下文
+ * @param event 解析后的事件
+ * @param concurrency 并发数限制
+ * @returns 推送结果列表
+ */
+export declare function pushMessage(ctx: Context, event: ParsedEvent, concurrency?: number): Promise<PushResult[]>;
+/**
+ * 推送事件（完整流程）
+ * 整合事件解析、消息构建和推送
+ * @param ctx Koishi 上下文
+ * @param event 解析后的事件
+ * @param concurrency 并发数限制
+ * @returns 推送结果
+ */
+export declare function pushEvent(ctx: Context, event: ParsedEvent, concurrency?: number): Promise<{
+    pushed: number;
+    failed: number;
+    results: PushResult[];
+}>;

package/lib/repository/delivery.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 投递记录数据访问层
+ * 需求: 1.6
+ */
+import { Context } from 'koishi';
+import { Delivery } from '../database';
+/**
+ * 记录投递
+ * 需求 1.6: 记录 Delivery ID 用于去重
+ * @param ctx Koishi 上下文
+ * @param deliveryId GitHub Delivery ID
+ * @param repo 仓库名 (owner/repo)
+ * @param event 事件类型
+ * @returns 创建的投递记录
+ */
+export declare function recordDelivery(ctx: Context, deliveryId: string, repo: string, event: string): Promise<Delivery>;
+/**
+ * 检查是否已投递
+ * 需求 1.6: 检查 Delivery ID 是否已处理过，用于去重
+ * @param ctx Koishi 上下文
+ * @param deliveryId GitHub Delivery ID
+ * @returns 是否已投递
+ */
+export declare function isDelivered(ctx: Context, deliveryId: string): Promise<boolean>;
+/**
+ * 获取投递记录
+ * @param ctx Koishi 上下文
+ * @param deliveryId GitHub Delivery ID
+ * @returns 投递记录，不存在返回 null
+ */
+export declare function getDelivery(ctx: Context, deliveryId: string): Promise<Delivery | null>;
+/**
+ * 清理旧的投递记录
+ * @param ctx Koishi 上下文
+ * @param beforeDate 清理此日期之前的记录
+ * @returns 清理的记录数
+ */
+export declare function cleanupDeliveries(ctx: Context, beforeDate: Date): Promise<number>;

package/lib/repository/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 数据访问层导出
+ */
+export * from './trust';
+export * from './subscription';
+export * from './delivery';

package/lib/repository/subscription.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 订阅数据访问层
+ * 需求: 3.1-3.7, 5.1, 5.2
+ */
+import { Context } from 'koishi';
+import { Subscription } from '../database';
+import { EventType } from '../types';
+/** 推送目标信息 */
+export interface PushTarget {
+    platform: string;
+    channelId: string;
+    guildId?: string;
+    userId?: string;
+}
+/** 会话标识 */
+export interface SessionIdentifier {
+    platform: string;
+    channelId: string;
+    guildId?: string;
+    userId?: string;
+}
+/**
+ * 创建订阅
+ * 需求 3.1: 为当前会话创建订阅记录
+ * @param ctx Koishi 上下文
+ * @param session 会话标识
+ * @param repo 仓库名 (owner/repo)
+ * @param defaultEvents 默认事件列表
+ * @returns 创建的订阅记录
+ */
+export declare function createSubscription(ctx: Context, session: SessionIdentifier, repo: string, defaultEvents: EventType[]): Promise<Subscription>;
+/**
+ * 移除订阅
+ * 需求 3.3: 移除当前会话对该仓库的订阅
+ * @param ctx Koishi 上下文
+ * @param session 会话标识
+ * @param repo 仓库名 (owner/repo)
+ * @returns 是否成功移除
+ */
+export declare function removeSubscription(ctx: Context, session: SessionIdentifier, repo: string): Promise<boolean>;
+/**
+ * 列出会话的所有订阅
+ * 需求 3.4: 显示当前会话的所有订阅及其事件设置
+ * @param ctx Koishi 上下文
+ * @param session 会话标识
+ * @returns 订阅列表
+ */
+export declare function listSubscriptions(ctx: Context, session: SessionIdentifier): Promise<Subscription[]>;
+/**
+ * 获取单个订阅
+ * 需求 3.5: 显示该仓库订阅的事件类型列表
+ * @param ctx Koishi 上下文
+ * @param session 会话标识
+ * @param repo 仓库名 (owner/repo)
+ * @returns 订阅记录，不存在返回 null
+ */
+export declare function getSubscription(ctx: Context, session: SessionIdentifier, repo: string): Promise<Subscription | null>;
+/**
+ * 更新订阅的事件类型
+ * 需求 3.6: 根据 +/- 前缀启用或禁用对应事件类型
+ * @param ctx Koishi 上下文
+ * @param session 会话标识
+ * @param repo 仓库名 (owner/repo)
+ * @param events 新的事件列表
+ * @returns 是否成功更新
+ */
+export declare function updateEvents(ctx: Context, session: SessionIdentifier, repo: string, events: EventType[]): Promise<boolean>;
+/**
+ * 查询订阅目标
+ * 需求 5.1, 5.2: 查询所有订阅该仓库的目标会话，并根据事件类型过滤
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @param eventType 事件类型
+ * @returns 推送目标列表
+ */
+export declare function queryTargets(ctx: Context, repo: string, eventType: EventType): Promise<PushTarget[]>;
+/**
+ * 获取仓库的所有订阅
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @returns 订阅列表
+ */
+export declare function getRepoSubscriptions(ctx: Context, repo: string): Promise<Subscription[]>;
+/**
+ * 启用订阅
+ * @param ctx Koishi 上下文
+ * @param session 会话标识
+ * @param repo 仓库名 (owner/repo)
+ * @returns 是否成功启用
+ */
+export declare function enableSubscription(ctx: Context, session: SessionIdentifier, repo: string): Promise<boolean>;
+/**
+ * 禁用订阅
+ * @param ctx Koishi 上下文
+ * @param session 会话标识
+ * @param repo 仓库名 (owner/repo)
+ * @returns 是否成功禁用
+ */
+export declare function disableSubscription(ctx: Context, session: SessionIdentifier, repo: string): Promise<boolean>;

package/lib/repository/trust.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 信任仓库数据访问层
+ * 需求: 2.1-2.7
+ */
+import { Context } from 'koishi';
+import { TrustedRepo } from '../database';
+/**
+ * 验证仓库名格式是否符合 owner/repo 格式
+ * @param repo 仓库名
+ * @returns 是否有效
+ */
+export declare function isValidRepoFormat(repo: string): boolean;
+/**
+ * 添加信任仓库
+ * 需求 2.1: 将仓库添加到信任列表并持久化到数据库
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @returns 添加的仓库记录，如果格式错误返回 null
+ */
+export declare function addTrustedRepo(ctx: Context, repo: string): Promise<TrustedRepo | null>;
+/**
+ * 移除信任仓库
+ * 需求 2.2: 从信任列表中移除该仓库
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @returns 是否成功移除
+ */
+export declare function removeTrustedRepo(ctx: Context, repo: string): Promise<boolean>;
+/**
+ * 列出所有信任仓库
+ * 需求 2.3: 显示所有信任仓库及其启用状态
+ * @param ctx Koishi 上下文
+ * @returns 信任仓库列表
+ */
+export declare function listTrustedRepos(ctx: Context): Promise<TrustedRepo[]>;
+/**
+ * 检查仓库是否在信任列表中且已启用
+ * 需求 2.6: 验证仓库是否可以处理事件
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @returns 是否信任且启用
+ */
+export declare function isTrusted(ctx: Context, repo: string): Promise<boolean>;
+/**
+ * 检查仓库是否在信任列表中（不考虑启用状态）
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @returns 是否在信任列表中
+ */
+export declare function isInTrustList(ctx: Context, repo: string): Promise<boolean>;
+/**
+ * 启用信任仓库
+ * 需求 2.4: 启用该仓库的事件处理
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @returns 是否成功启用
+ */
+export declare function enableRepo(ctx: Context, repo: string): Promise<boolean>;
+/**
+ * 禁用信任仓库
+ * 需求 2.5: 禁用该仓库的事件处理
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @returns 是否成功禁用
+ */
+export declare function disableRepo(ctx: Context, repo: string): Promise<boolean>;
+/**
+ * 获取单个信任仓库信息
+ * @param ctx Koishi 上下文
+ * @param repo 仓库名 (owner/repo)
+ * @returns 仓库信息，不存在返回 null
+ */
+export declare function getTrustedRepo(ctx: Context, repo: string): Promise<TrustedRepo | null>;

package/lib/signature.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 创建 GitHub Webhook 签名
+ * @param payload 原始请求体
+ * @param secret Webhook Secret
+ * @returns 签名字符串，格式为 sha256=<hex_digest>
+ */
+export declare function createSignature(payload: string, secret: string): string;
+/**
+ * 验证 GitHub Webhook 签名
+ * @param payload 原始请求体
+ * @param signature X-Hub-Signature-256 头的值
+ * @param secret 配置的 Webhook Secret
+ * @returns 签名是否有效
+ */
+export declare function verifySignature(payload: string, signature: string, secret: string): boolean;

package/lib/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 事件类型和接口定义
+ * 需求: 4.1-4.7
+ */
+/** 支持的事件类型 */
+export type EventType = 'issues' | 'issue_comment' | 'pull_request' | 'pull_request_review' | 'pull_request_review_comment' | 'release' | 'push' | 'star' | 'fork' | 'create' | 'delete' | 'workflow_run';
+/** 提交信息 */
+export interface CommitInfo {
+    sha: string;
+    message: string;
+    author: string;
+    url: string;
+}
+/** 解析后的事件数据 */
+export interface ParsedEvent {
+    type: EventType;
+    displayType: string;
+    repo: string;
+    actor: string;
+    action?: string;
+    title?: string;
+    number?: number;
+    url: string;
+    body?: string;
+    commits?: CommitInfo[];
+    totalCommits?: number;
+    ref?: string;
+    tagName?: string;
+    starCount?: number;
+}
+/** 事件类型显示信息 */
+export interface EventDisplayInfo {
+    name: string;
+    emoji: string;
+}
+/** 事件类型到显示名称和 emoji 的映射 */
+export declare const EVENT_DISPLAY_MAP: Record<EventType, EventDisplayInfo>;
+/**
+ * 获取事件类型的显示名称
+ * @param type 事件类型
+ * @returns 显示名称
+ */
+export declare function getDisplayType(type: EventType): string;
+/**
+ * 获取事件类型的 emoji
+ * @param type 事件类型
+ * @returns emoji 字符
+ */
+export declare function getEventEmoji(type: EventType): string;

package/lib/webhook.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Webhook 处理器
+ * 需求: 1.1-1.6, 2.6, 9.1-9.6
+ */
+import { Context } from 'koishi';
+import type { Context as KoaContext } from 'koa';
+import { Config } from './config';
+declare module 'koishi' {
+    interface Context {
+        server: {
+            post(path: string, handler: (ctx: KoaContext) => Promise<void>): void;
+        };
+    }
+}
+/**
+ * 注册 Webhook 处理器
+ * 需求 1.1: 在配置的路径上监听 HTTP POST 请求
+ * @param ctx Koishi 上下文
+ * @param config 插件配置
+ */
+export declare function registerWebhook(ctx: Context, config: Config): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-github-webhook-pusher",
   "description": "GitHub Webhook 事件推送插件",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "contributors": [
     "ClozyA <aoxuan233@gmail.com>"
   ],
@@ -19,7 +19,10 @@
   "license": "MIT",
   "scripts": {
     "test": "vitest --run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "build": "tsc -p tsconfig.json",
+    "build:ci": "tsc -p tsconfig.github.json",
+    "prepublishOnly": "npm run build:ci"
   },
   "keywords": [
     "chatbot",