@flink-app/github-app-plugin 0.12.1-alpha.38

package/examples/multi-event-webhook.ts

@@ -0,0 +1,367 @@
+/**
+ * Multi-Event Webhook Handling Example
+ *
+ * This example demonstrates:
+ * - Handling multiple webhook event types
+ * - Event filtering and routing
+ * - Webhook event logging
+ * - Async webhook processing
+ * - Event-driven workflows
+ */
+
+import { FlinkApp, FlinkContext } from "@flink-app/flink";
+import { githubAppPlugin } from "@flink-app/github-app-plugin";
+
+interface AppContext extends FlinkContext {
+  plugins: {
+    githubApp: any;
+  };
+  repos: {
+    githubWebhookEventRepo: any;
+  };
+}
+
+// Event processor interface
+interface EventProcessor {
+  event: string;
+  actions?: string[];
+  process: (payload: any, client: any, ctx: AppContext) => Promise<void>;
+}
+
+// Event processors registry
+const eventProcessors: EventProcessor[] = [
+  {
+    event: "push",
+    process: async (payload, client, ctx) => {
+      const repo = payload.repository;
+      const branch = payload.ref.replace("refs/heads/", "");
+      const commits = payload.commits || [];
+
+      console.log(`\n[PUSH] ${repo.full_name}:${branch} - ${commits.length} commits`);
+
+      // Auto-create issue for commits with [bug] tag
+      for (const commit of commits) {
+        if (commit.message.toLowerCase().includes("[bug]")) {
+          await client.createIssue(repo.owner.login, repo.name, {
+            title: `Bug fix needed: ${commit.message.split("\n")[0]}`,
+            body: `Commit ${commit.id.substring(0, 7)} contains a [bug] tag.\n\nMessage: ${commit.message}`,
+          });
+          console.log(`  Created issue for bug commit`);
+        }
+      }
+    },
+  },
+  {
+    event: "pull_request",
+    actions: ["opened", "closed", "reopened", "synchronize"],
+    process: async (payload, client, ctx) => {
+      const pr = payload.pull_request;
+      const action = payload.action;
+      const repo = payload.repository;
+
+      console.log(`\n[PR] ${repo.full_name}#${pr.number} - ${action}`);
+
+      if (action === "opened") {
+        // Welcome new contributors
+        await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${pr.number}/comments`, {
+          body: `Thanks for your pull request, @${pr.user.login}! We'll review it soon.`,
+        });
+        console.log(`  Added welcome comment`);
+      }
+
+      if (action === "closed" && pr.merged) {
+        // Thank for merged PR
+        await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${pr.number}/comments`, {
+          body: `Thanks for your contribution, @${pr.user.login}! Your changes have been merged.`,
+        });
+        console.log(`  Added thank you comment`);
+      }
+    },
+  },
+  {
+    event: "issues",
+    actions: ["opened", "edited", "closed"],
+    process: async (payload, client, ctx) => {
+      const issue = payload.issue;
+      const action = payload.action;
+      const repo = payload.repository;
+
+      console.log(`\n[ISSUE] ${repo.full_name}#${issue.number} - ${action}`);
+
+      if (action === "opened") {
+        // Auto-label based on title
+        const labels: string[] = [];
+
+        if (issue.title.toLowerCase().includes("bug")) labels.push("bug");
+        if (issue.title.toLowerCase().includes("feature")) labels.push("enhancement");
+        if (issue.title.toLowerCase().includes("question")) labels.push("question");
+        if (issue.title.toLowerCase().includes("urgent")) labels.push("priority: high");
+
+        if (labels.length > 0) {
+          await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${issue.number}/labels`, {
+            labels,
+          });
+          console.log(`  Added labels: ${labels.join(", ")}`);
+        }
+      }
+    },
+  },
+  {
+    event: "issue_comment",
+    actions: ["created"],
+    process: async (payload, client, ctx) => {
+      const comment = payload.comment;
+      const issue = payload.issue;
+      const repo = payload.repository;
+
+      console.log(`\n[COMMENT] ${repo.full_name}#${issue.number}`);
+
+      // Check for commands in comments (e.g., "/label bug")
+      const commandMatch = comment.body.match(/^\/(\w+)\s*(.*)$/m);
+
+      if (commandMatch) {
+        const [, command, args] = commandMatch;
+
+        console.log(`  Command detected: /${command} ${args}`);
+
+        switch (command) {
+          case "label":
+            const labels = args.split(/\s+/).filter(Boolean);
+            if (labels.length > 0) {
+              await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${issue.number}/labels`, {
+                labels,
+              });
+              console.log(`  Added labels: ${labels.join(", ")}`);
+            }
+            break;
+
+          case "close":
+            await client.request("PATCH", `/repos/${repo.owner.login}/${repo.name}/issues/${issue.number}`, {
+              state: "closed",
+            });
+            console.log(`  Closed issue`);
+            break;
+
+          case "assign":
+            const assignees = args.split(/\s+/).filter(Boolean);
+            if (assignees.length > 0) {
+              await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${issue.number}/assignees`, {
+                assignees,
+              });
+              console.log(`  Assigned: ${assignees.join(", ")}`);
+            }
+            break;
+        }
+      }
+    },
+  },
+  {
+    event: "pull_request_review",
+    actions: ["submitted"],
+    process: async (payload, client, ctx) => {
+      const review = payload.review;
+      const pr = payload.pull_request;
+      const repo = payload.repository;
+
+      console.log(`\n[PR REVIEW] ${repo.full_name}#${pr.number} - ${review.state}`);
+
+      if (review.state === "approved") {
+        // Thank reviewer
+        await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${pr.number}/comments`, {
+          body: `Thanks for the review, @${review.user.login}!`,
+        });
+        console.log(`  Thanked reviewer`);
+      }
+
+      if (review.state === "changes_requested") {
+        // Notify author
+        await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${pr.number}/comments`, {
+          body: `@${pr.user.login}, please address the requested changes.`,
+        });
+        console.log(`  Notified author of requested changes`);
+      }
+    },
+  },
+  {
+    event: "release",
+    actions: ["published"],
+    process: async (payload, client, ctx) => {
+      const release = payload.release;
+      const repo = payload.repository;
+
+      console.log(`\n[RELEASE] ${repo.full_name} - ${release.tag_name}`);
+
+      // Create announcement issue
+      await client.createIssue(repo.owner.login, repo.name, {
+        title: `Release ${release.tag_name} is now available`,
+        body: `A new release has been published!\n\n**${release.name}**\n\n${release.body}\n\n[View Release](${release.html_url})`,
+      });
+      console.log(`  Created announcement issue`);
+    },
+  },
+  {
+    event: "installation",
+    actions: ["created", "deleted", "suspend", "unsuspend"],
+    process: async (payload, client, ctx) => {
+      const installation = payload.installation;
+      const action = payload.action;
+
+      console.log(`\n[INSTALLATION] ${installation.account.login} - ${action}`);
+
+      if (action === "deleted") {
+        // Clean up installation data
+        const installations = await ctx.repos.githubInstallationRepo.findByInstallationId(installation.id);
+
+        for (const inst of installations) {
+          await ctx.plugins.githubApp.deleteInstallation(inst.userId, installation.id);
+          console.log(`  Cleaned up installation for user ${inst.userId}`);
+        }
+      }
+    },
+  },
+  {
+    event: "installation_repositories",
+    actions: ["added", "removed"],
+    process: async (payload, client, ctx) => {
+      const installation = payload.installation;
+      const added = payload.repositories_added || [];
+      const removed = payload.repositories_removed || [];
+
+      console.log(`\n[INSTALLATION REPOS] ${installation.account.login}`);
+
+      if (added.length > 0) {
+        console.log(`  Added: ${added.map((r: any) => r.full_name).join(", ")}`);
+      }
+
+      if (removed.length > 0) {
+        console.log(`  Removed: ${removed.map((r: any) => r.full_name).join(", ")}`);
+      }
+
+      // Update installation in database
+      // (Plugin handles this automatically, but you can add custom logic)
+    },
+  },
+  {
+    event: "check_suite",
+    actions: ["completed"],
+    process: async (payload, client, ctx) => {
+      const checkSuite = payload.check_suite;
+      const repo = payload.repository;
+
+      console.log(`\n[CHECK SUITE] ${repo.full_name} - ${checkSuite.conclusion}`);
+
+      if (checkSuite.conclusion === "failure") {
+        // Create issue for failed checks
+        const prs = checkSuite.pull_requests || [];
+        if (prs.length > 0) {
+          const pr = prs[0];
+          await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${pr.number}/comments`, {
+            body: `Check suite failed. Please review the errors and fix them.`,
+          });
+          console.log(`  Notified PR author of failed checks`);
+        }
+      }
+    },
+  },
+];
+
+async function start() {
+  const app = new FlinkApp<AppContext>({
+    name: "GitHub App Multi-Event Webhook Example",
+    port: 3333,
+
+    db: {
+      uri: process.env.MONGODB_URI || "mongodb://localhost:27017/github-app-multi-webhook",
+    },
+
+    plugins: [
+      githubAppPlugin({
+        appId: process.env.GITHUB_APP_ID!,
+        privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
+        webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+        clientId: process.env.GITHUB_APP_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
+
+        onInstallationSuccess: async ({ installationId, account }) => {
+          console.log(`Installation: ${installationId} on ${account.login}`);
+          return {
+            userId: "demo-user",
+            redirectUrl: "/dashboard",
+          };
+        },
+
+        // Multi-event webhook handler
+        onWebhookEvent: async ({ event, action, payload, installationId, deliveryId }, ctx) => {
+          console.log(`\n========================================`);
+          console.log(`Webhook Delivery: ${deliveryId}`);
+          console.log(`Event: ${event}${action ? ` (${action})` : ""}`);
+          console.log(`Installation: ${installationId}`);
+          console.log(`========================================`);
+
+          try {
+            // Find matching processor
+            const processor = eventProcessors.find((p) => {
+              if (p.event !== event) return false;
+              if (p.actions && action && !p.actions.includes(action)) return false;
+              return true;
+            });
+
+            if (processor) {
+              // Get API client
+              const client = await ctx.plugins.githubApp.getClient(installationId);
+
+              // Process event
+              await processor.process(payload, client, ctx);
+
+              console.log(`\n✅ Event processed successfully`);
+            } else {
+              console.log(`\n⚠️  No processor registered for ${event}${action ? ` (${action})` : ""}`);
+            }
+          } catch (error: any) {
+            console.error(`\n❌ Error processing webhook:`, error.message);
+            // Don't throw - return 200 to GitHub to prevent retries
+          }
+
+          console.log(`========================================\n`);
+        },
+
+        // Enable webhook event logging
+        logWebhookEvents: true,
+      }),
+    ],
+  });
+
+  await app.start();
+
+  console.log(`
+=================================
+Multi-Event Webhook Example
+=================================
+
+This example handles multiple webhook event types:
+
+✓ push - Create issues for [bug] commits
+✓ pull_request - Welcome contributors, thank for merges
+✓ issues - Auto-label based on title
+✓ issue_comment - Process commands (/label, /close, /assign)
+✓ pull_request_review - Thank reviewers, notify authors
+✓ release - Create announcement issues
+✓ installation - Clean up on deletion
+✓ installation_repositories - Track repo changes
+✓ check_suite - Notify on failed checks
+
+Webhook endpoint: /github-app/webhook
+
+Configure in GitHub App settings:
+- Webhook URL: https://your-domain.com/github-app/webhook
+- Subscribe to events you want to handle
+
+=================================
+  `);
+}
+
+// Start application
+start().catch((error) => {
+  console.error("Failed to start application:", error);
+  process.exit(1);
+});

package/examples/organization-installation.ts

@@ -0,0 +1,316 @@
+/**
+ * Organization-Level Installation Example
+ *
+ * This example demonstrates:
+ * - Installing GitHub App at organization level
+ * - Handling organization installations vs user installations
+ * - Managing multiple installations per user (personal + orgs)
+ * - Switching between organization contexts
+ */
+
+import { FlinkApp, FlinkContext, GetHandler } from "@flink-app/flink";
+import { githubAppPlugin } from "@flink-app/github-app-plugin";
+
+interface AppContext extends FlinkContext {
+  plugins: {
+    githubApp: any;
+  };
+  session?: {
+    userId?: string;
+  };
+}
+
+async function start() {
+  const app = new FlinkApp<AppContext>({
+    name: "GitHub App Organization Example",
+    port: 3333,
+
+    db: {
+      uri: process.env.MONGODB_URI || "mongodb://localhost:27017/github-app-org-example",
+    },
+
+    plugins: [
+      githubAppPlugin({
+        appId: process.env.GITHUB_APP_ID!,
+        privateKey: process.env.GITHUB_APP_PRIVATE_KEY!,
+        webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
+        clientId: process.env.GITHUB_APP_CLIENT_ID!,
+        clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
+
+        onInstallationSuccess: async ({ installationId, account, repositories }, ctx) => {
+          const userId = ctx.session?.userId || "demo-user";
+
+          console.log(`\n=== Installation Success ===`);
+          console.log(`Installation ID: ${installationId}`);
+          console.log(`Account Type: ${account.type}`);
+          console.log(`Account: ${account.login}`);
+
+          if (account.type === "Organization") {
+            console.log(`\nOrganization installation detected!`);
+            console.log(`Repositories in org: ${repositories.length}`);
+          } else {
+            console.log(`\nPersonal account installation`);
+          }
+
+          return {
+            userId,
+            redirectUrl: `/dashboard/installations?account=${account.login}`,
+          };
+        },
+      }),
+    ],
+  });
+
+  await app.start();
+
+  console.log(`
+=================================
+Organization Installation Example
+=================================
+
+Users can install the GitHub App on:
+1. Their personal account
+2. Organizations they belong to
+
+Install on personal account:
+http://localhost:3333/github-app/install?user_id=demo-user
+
+Install on organization:
+- Navigate to the install URL above
+- Select "Organization" instead of personal account
+- Choose which organization
+- Select repositories
+
+Available endpoints:
+- GET /installations/list - List all installations (personal + orgs)
+- GET /installations/:installationId - Get specific installation details
+- GET /installations/:installationId/repos - List repos for installation
+
+=================================
+  `);
+}
+
+// Handler: List all installations for user
+const ListAllInstallations: GetHandler = async ({ ctx }) => {
+  const userId = ctx.session?.userId || "demo-user";
+
+  try {
+    const installations = await ctx.plugins.githubApp.getInstallations(userId);
+
+    // Group by type
+    const personal = installations.filter((inst: any) => inst.accountType === "User");
+    const organizations = installations.filter((inst: any) => inst.accountType === "Organization");
+
+    return {
+      status: 200,
+      data: {
+        total: installations.length,
+        personal: personal.map((inst: any) => ({
+          installationId: inst.installationId,
+          account: inst.accountLogin,
+          repositoryCount: inst.repositories.length,
+          createdAt: inst.createdAt,
+        })),
+        organizations: organizations.map((inst: any) => ({
+          installationId: inst.installationId,
+          organization: inst.accountLogin,
+          repositoryCount: inst.repositories.length,
+          permissions: inst.permissions,
+          createdAt: inst.createdAt,
+        })),
+      },
+    };
+  } catch (error: any) {
+    return {
+      status: 500,
+      data: {
+        error: "failed-to-list-installations",
+        message: error.message,
+      },
+    };
+  }
+};
+
+export { ListAllInstallations };
+
+// Handler: Get installation details
+const GetInstallationDetails: GetHandler<any, any, { installationId: string }> = async ({ ctx, params }) => {
+  const userId = ctx.session?.userId || "demo-user";
+  const installationId = parseInt(params.installationId, 10);
+
+  try {
+    const installations = await ctx.plugins.githubApp.getInstallations(userId);
+    const installation = installations.find((inst: any) => inst.installationId === installationId);
+
+    if (!installation) {
+      return {
+        status: 404,
+        data: {
+          error: "installation-not-found",
+          message: "Installation not found or you do not have access",
+        },
+      };
+    }
+
+    return {
+      status: 200,
+      data: {
+        installationId: installation.installationId,
+        account: {
+          id: installation.accountId,
+          login: installation.accountLogin,
+          type: installation.accountType,
+          avatarUrl: installation.avatarUrl,
+        },
+        repositories: installation.repositories.map((repo: any) => ({
+          id: repo.id,
+          name: repo.name,
+          fullName: repo.fullName,
+          private: repo.private,
+        })),
+        permissions: installation.permissions,
+        events: installation.events,
+        createdAt: installation.createdAt,
+        updatedAt: installation.updatedAt,
+        suspended: !!installation.suspendedAt,
+        suspendedAt: installation.suspendedAt,
+        suspendedBy: installation.suspendedBy,
+      },
+    };
+  } catch (error: any) {
+    return {
+      status: 500,
+      data: {
+        error: "failed-to-get-installation",
+        message: error.message,
+      },
+    };
+  }
+};
+
+export { GetInstallationDetails };
+
+// Handler: List repositories for specific installation
+const ListInstallationRepos: GetHandler<any, any, { installationId: string }> = async ({ ctx, params }) => {
+  const userId = ctx.session?.userId || "demo-user";
+  const installationId = parseInt(params.installationId, 10);
+
+  try {
+    // Verify user owns this installation
+    const installations = await ctx.plugins.githubApp.getInstallations(userId);
+    const installation = installations.find((inst: any) => inst.installationId === installationId);
+
+    if (!installation) {
+      return {
+        status: 403,
+        data: {
+          error: "access-denied",
+          message: "You do not have access to this installation",
+        },
+      };
+    }
+
+    // Get API client for this installation
+    const client = await ctx.plugins.githubApp.getClient(installationId);
+
+    // Fetch repositories from GitHub
+    const repos = await client.getRepositories();
+
+    return {
+      status: 200,
+      data: {
+        installation: {
+          id: installationId,
+          account: installation.accountLogin,
+          type: installation.accountType,
+        },
+        repositories: repos.map((repo: any) => ({
+          id: repo.id,
+          name: repo.name,
+          fullName: repo.full_name,
+          private: repo.private,
+          description: repo.description,
+          url: repo.html_url,
+          language: repo.language,
+          stargazersCount: repo.stargazers_count,
+          defaultBranch: repo.default_branch,
+        })),
+        total: repos.length,
+      },
+    };
+  } catch (error: any) {
+    return {
+      status: 500,
+      data: {
+        error: "failed-to-list-repos",
+        message: error.message,
+      },
+    };
+  }
+};
+
+export { ListInstallationRepos };
+
+// Handler: Switch organization context
+const SwitchOrganization: GetHandler<any, any, any, { org: string }> = async ({ ctx, query }) => {
+  const userId = ctx.session?.userId || "demo-user";
+  const orgLogin = query.org;
+
+  if (!orgLogin) {
+    return {
+      status: 400,
+      data: {
+        error: "missing-org",
+        message: "org query parameter is required",
+      },
+    };
+  }
+
+  try {
+    const installations = await ctx.plugins.githubApp.getInstallations(userId);
+    const orgInstallation = installations.find(
+      (inst: any) => inst.accountType === "Organization" && inst.accountLogin === orgLogin
+    );
+
+    if (!orgInstallation) {
+      return {
+        status: 404,
+        data: {
+          error: "org-not-found",
+          message: `No installation found for organization ${orgLogin}`,
+          availableOrgs: installations
+            .filter((inst: any) => inst.accountType === "Organization")
+            .map((inst: any) => inst.accountLogin),
+        },
+      };
+    }
+
+    return {
+      status: 200,
+      data: {
+        message: `Switched to organization: ${orgLogin}`,
+        installation: {
+          installationId: orgInstallation.installationId,
+          organization: orgInstallation.accountLogin,
+          repositories: orgInstallation.repositories.length,
+        },
+      },
+    };
+  } catch (error: any) {
+    return {
+      status: 500,
+      data: {
+        error: "switch-org-failed",
+        message: error.message,
+      },
+    };
+  }
+};
+
+export { SwitchOrganization };
+
+// Start application
+start().catch((error) => {
+  console.error("Failed to start application:", error);
+  process.exit(1);
+});