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

package/examples/webhook-handling.ts

@@ -0,0 +1,343 @@
+/**
+ * Webhook Handling Example
+ *
+ * This example demonstrates:
+ * - Processing webhook events (push, pull request, installation)
+ * - Webhook signature validation (automatic)
+ * - Accessing webhook payload data
+ * - Using GitHub API client in webhook handlers
+ * - Responding to different event types
+ */
+
+import { FlinkApp, FlinkContext } from "@flink-app/flink";
+import { githubAppPlugin } from "@flink-app/github-app-plugin";
+
+interface AppContext extends FlinkContext {
+  plugins: {
+    githubApp: any;
+  };
+}
+
+async function start() {
+  const app = new FlinkApp<AppContext>({
+    name: "GitHub App Webhook Example",
+    port: 3333,
+
+    db: {
+      uri: process.env.MONGODB_URI || "mongodb://localhost:27017/github-app-webhook-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 }) => {
+          console.log(`Installation ${installationId} created for ${account.login}`);
+          return {
+            userId: "demo-user",
+            redirectUrl: "/dashboard",
+          };
+        },
+
+        // Webhook event handler
+        onWebhookEvent: async ({ event, action, payload, installationId, deliveryId }, ctx) => {
+          console.log(`\n=== Webhook Received ===`);
+          console.log(`Event: ${event}`);
+          console.log(`Action: ${action || "N/A"}`);
+          console.log(`Installation ID: ${installationId}`);
+          console.log(`Delivery ID: ${deliveryId}`);
+
+          try {
+            // Get API client for this installation
+            const client = await ctx.plugins.githubApp.getClient(installationId);
+
+            // Handle different event types
+            switch (event) {
+              case "push":
+                await handlePushEvent(payload, client);
+                break;
+
+              case "pull_request":
+                await handlePullRequestEvent(payload, action, client);
+                break;
+
+              case "issues":
+                await handleIssuesEvent(payload, action, client);
+                break;
+
+              case "installation":
+                await handleInstallationEvent(payload, action, ctx);
+                break;
+
+              case "installation_repositories":
+                await handleRepositoriesEvent(payload, action, ctx);
+                break;
+
+              case "pull_request_review":
+                await handlePullRequestReviewEvent(payload, action, client);
+                break;
+
+              case "issue_comment":
+                await handleIssueCommentEvent(payload, action, client);
+                break;
+
+              default:
+                console.log(`Unhandled event type: ${event}`);
+            }
+
+            console.log(`Webhook processed successfully`);
+          } catch (error) {
+            console.error(`Error processing webhook:`, error);
+            // Don't throw - return 200 to GitHub to prevent retries
+          }
+        },
+
+        // Optional: Log webhook events to MongoDB for debugging
+        logWebhookEvents: true,
+      }),
+    ],
+  });
+
+  await app.start();
+
+  console.log(`
+=================================
+Webhook Handling Example Started
+=================================
+
+Webhook endpoint: http://localhost:3333/github-app/webhook
+
+For local development, use ngrok to create HTTPS tunnel:
+  ngrok http 3333
+
+Then configure webhook URL in GitHub App settings:
+  https://your-ngrok-url.ngrok.io/github-app/webhook
+
+Events will be logged to console when received.
+
+=================================
+  `);
+}
+
+// Handle push events
+async function handlePushEvent(payload: any, client: any) {
+  const repo = payload.repository;
+  const pusher = payload.pusher;
+  const commits = payload.commits || [];
+  const branch = payload.ref.replace("refs/heads/", "");
+
+  console.log(`\n📦 Push Event:`);
+  console.log(`  Repository: ${repo.full_name}`);
+  console.log(`  Branch: ${branch}`);
+  console.log(`  Pusher: ${pusher.name}`);
+  console.log(`  Commits: ${commits.length}`);
+
+  // Log commit messages
+  commits.forEach((commit: any) => {
+    console.log(`    - ${commit.message.split("\n")[0]} (${commit.id.substring(0, 7)})`);
+  });
+
+  // Example: Create issue if commit message contains "[bug]"
+  const hasBugCommit = commits.some((commit: any) => commit.message.toLowerCase().includes("[bug]"));
+
+  if (hasBugCommit) {
+    console.log(`  🐛 Bug commit detected, creating issue...`);
+
+    try {
+      const issue = await client.createIssue(repo.owner.login, repo.name, {
+        title: `Bug fix needed in ${branch}`,
+        body: `A commit with [bug] tag was pushed to ${branch}.\n\nCommits:\n${commits
+          .map((c: any) => `- ${c.message.split("\n")[0]}`)
+          .join("\n")}`,
+      });
+
+      console.log(`  ✅ Issue created: #${issue.number}`);
+    } catch (error) {
+      console.error(`  ❌ Failed to create issue:`, error);
+    }
+  }
+}
+
+// Handle pull request events
+async function handlePullRequestEvent(payload: any, action: string | undefined, client: any) {
+  const pr = payload.pull_request;
+  const repo = payload.repository;
+
+  console.log(`\n🔀 Pull Request Event:`);
+  console.log(`  Action: ${action}`);
+  console.log(`  Repository: ${repo.full_name}`);
+  console.log(`  PR: #${pr.number} - ${pr.title}`);
+  console.log(`  Author: ${pr.user.login}`);
+  console.log(`  Base: ${pr.base.ref} <- Head: ${pr.head.ref}`);
+
+  if (action === "opened") {
+    // Thank contributor for opening PR
+    console.log(`  💬 Welcoming new contributor...`);
+
+    try {
+      await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${pr.number}/comments`, {
+        body: `Thanks for opening this pull request, @${pr.user.login}! We'll review it soon.`,
+      });
+
+      console.log(`  ✅ Comment added to PR`);
+    } catch (error) {
+      console.error(`  ❌ Failed to add comment:`, error);
+    }
+  }
+
+  if (action === "closed" && pr.merged) {
+    console.log(`  ✅ PR merged!`);
+  }
+}
+
+// Handle issues events
+async function handleIssuesEvent(payload: any, action: string | undefined, client: any) {
+  const issue = payload.issue;
+  const repo = payload.repository;
+
+  console.log(`\n🐛 Issue Event:`);
+  console.log(`  Action: ${action}`);
+  console.log(`  Repository: ${repo.full_name}`);
+  console.log(`  Issue: #${issue.number} - ${issue.title}`);
+  console.log(`  Author: ${issue.user.login}`);
+
+  if (action === "opened") {
+    // Auto-label issues based on content
+    const labels: string[] = [];
+
+    if (issue.title.toLowerCase().includes("bug")) {
+      labels.push("bug");
+    }
+
+    if (issue.title.toLowerCase().includes("feature")) {
+      labels.push("enhancement");
+    }
+
+    if (labels.length > 0) {
+      console.log(`  🏷️  Auto-labeling issue with: ${labels.join(", ")}`);
+
+      try {
+        await client.request("POST", `/repos/${repo.owner.login}/${repo.name}/issues/${issue.number}/labels`, {
+          labels,
+        });
+
+        console.log(`  ✅ Labels added`);
+      } catch (error) {
+        console.error(`  ❌ Failed to add labels:`, error);
+      }
+    }
+  }
+}
+
+// Handle installation events
+async function handleInstallationEvent(payload: any, action: string | undefined, ctx: any) {
+  const installation = payload.installation;
+  const account = installation.account;
+
+  console.log(`\n⚙️  Installation Event:`);
+  console.log(`  Action: ${action}`);
+  console.log(`  Installation ID: ${installation.id}`);
+  console.log(`  Account: ${account.login} (${account.type})`);
+
+  if (action === "created") {
+    console.log(`  ✅ New installation created`);
+  }
+
+  if (action === "deleted") {
+    console.log(`  ❌ Installation deleted`);
+
+    // Clean up installation data
+    const installations = await ctx.repos.githubInstallationRepo.findByInstallationId(installation.id);
+
+    if (installations.length > 0) {
+      const inst = installations[0];
+      console.log(`  🗑️  Cleaning up installation data for user ${inst.userId}`);
+
+      try {
+        await ctx.plugins.githubApp.deleteInstallation(inst.userId, installation.id);
+        console.log(`  ✅ Installation data cleaned up`);
+      } catch (error) {
+        console.error(`  ❌ Failed to clean up:`, error);
+      }
+    }
+  }
+
+  if (action === "suspend") {
+    console.log(`  ⏸️  Installation suspended`);
+  }
+
+  if (action === "unsuspend") {
+    console.log(`  ▶️  Installation unsuspended`);
+  }
+}
+
+// Handle installation repositories events
+async function handleRepositoriesEvent(payload: any, action: string | undefined, ctx: any) {
+  const installation = payload.installation;
+  const addedRepos = payload.repositories_added || [];
+  const removedRepos = payload.repositories_removed || [];
+
+  console.log(`\n📚 Installation Repositories Event:`);
+  console.log(`  Action: ${action}`);
+  console.log(`  Installation ID: ${installation.id}`);
+
+  if (addedRepos.length > 0) {
+    console.log(`  ➕ Added repositories:`);
+    addedRepos.forEach((repo: any) => {
+      console.log(`    - ${repo.full_name}`);
+    });
+  }
+
+  if (removedRepos.length > 0) {
+    console.log(`  ➖ Removed repositories:`);
+    removedRepos.forEach((repo: any) => {
+      console.log(`    - ${repo.full_name}`);
+    });
+  }
+}
+
+// Handle pull request review events
+async function handlePullRequestReviewEvent(payload: any, action: string | undefined, client: any) {
+  const review = payload.review;
+  const pr = payload.pull_request;
+  const repo = payload.repository;
+
+  console.log(`\n👀 Pull Request Review Event:`);
+  console.log(`  Action: ${action}`);
+  console.log(`  Repository: ${repo.full_name}`);
+  console.log(`  PR: #${pr.number}`);
+  console.log(`  Reviewer: ${review.user.login}`);
+  console.log(`  State: ${review.state}`);
+
+  if (review.state === "approved") {
+    console.log(`  ✅ PR approved!`);
+  }
+
+  if (review.state === "changes_requested") {
+    console.log(`  📝 Changes requested`);
+  }
+}
+
+// Handle issue comment events
+async function handleIssueCommentEvent(payload: any, action: string | undefined, client: any) {
+  const comment = payload.comment;
+  const issue = payload.issue;
+  const repo = payload.repository;
+
+  console.log(`\n💬 Issue Comment Event:`);
+  console.log(`  Action: ${action}`);
+  console.log(`  Repository: ${repo.full_name}`);
+  console.log(`  Issue: #${issue.number}`);
+  console.log(`  Commenter: ${comment.user.login}`);
+  console.log(`  Comment: ${comment.body.substring(0, 100)}...`);
+}
+
+// Handle errors
+start().catch((error) => {
+  console.error("Failed to start application:", error);
+  process.exit(1);
+});

package/examples/with-jwt-auth.ts

@@ -0,0 +1,319 @@
+/**
+ * GitHub App with JWT Auth Plugin Integration (Optional)
+ *
+ * This example demonstrates:
+ * - Optional integration with JWT Auth Plugin
+ * - Using JWT-based authentication with GitHub App
+ * - Protecting endpoints with JWT authentication
+ * - Accessing GitHub App context with authenticated user
+ *
+ * Note: This integration is OPTIONAL. The GitHub App Plugin works standalone
+ * without JWT Auth Plugin.
+ */
+
+import { FlinkApp, FlinkContext, GetHandler, FlinkRepo } from "@flink-app/flink";
+import { githubAppPlugin } from "@flink-app/github-app-plugin";
+// Note: jwtAuthPlugin is optional - install separately if needed
+// import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
+
+interface User {
+  _id?: string;
+  email: string;
+  name: string;
+  roles: string[];
+  githubInstallations: number[];
+  createdAt: Date;
+}
+
+class UserRepo extends FlinkRepo<AppContext, User> {
+  async findByEmail(email: string) {
+    return this.getOne({ email });
+  }
+}
+
+interface AppContext extends FlinkContext {
+  repos: {
+    userRepo: UserRepo;
+  };
+  plugins: {
+    githubApp: any;
+    // jwtAuth would be available if JWT Auth Plugin is installed
+    jwtAuth?: any;
+  };
+  // JWT Auth Plugin adds this to context
+  auth?: {
+    tokenData?: {
+      userId: string;
+      email: string;
+      roles: string[];
+    };
+    user?: User;
+  };
+}
+
+async function start() {
+  const app = new FlinkApp<AppContext>({
+    name: "GitHub App with JWT Auth Example",
+    port: 3333,
+
+    db: {
+      uri: process.env.MONGODB_URI || "mongodb://localhost:27017/github-app-jwt-example",
+    },
+
+    // OPTIONAL: Configure JWT Auth Plugin
+    // Uncomment if you want to use JWT authentication
+    /*
+    auth: jwtAuthPlugin({
+      secret: process.env.JWT_SECRET || "your-jwt-secret",
+
+      getUser: async (tokenData) => {
+        const user = await app.ctx.repos.userRepo.getById(tokenData.userId);
+        if (!user) {
+          throw new Error("User not found");
+        }
+        return user;
+      },
+
+      rolePermissions: {
+        user: ["read:own", "write:own"],
+        admin: ["read:all", "write:all"],
+      },
+
+      expiresIn: "7d",
+    }),
+    */
+
+    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, repositories, account }, ctx) => {
+          // If JWT Auth Plugin is available, get userId from JWT token
+          // Otherwise, get userId from your custom auth system
+          const userId = ctx.auth?.tokenData?.userId || ctx.session?.userId || "demo-user";
+
+          console.log(`\nInstallation successful for user: ${userId}`);
+          console.log(`Account: ${account.login}`);
+          console.log(`Repositories: ${repositories.length}`);
+
+          // Update user's GitHub installations
+          try {
+            const user = await ctx.repos.userRepo.getById(userId);
+            if (user) {
+              const installations = user.githubInstallations || [];
+              if (!installations.includes(installationId)) {
+                await ctx.repos.userRepo.updateOne(userId, {
+                  githubInstallations: [...installations, installationId],
+                });
+              }
+            }
+          } catch (error) {
+            console.error("Failed to update user installations:", error);
+          }
+
+          return {
+            userId,
+            redirectUrl: "/dashboard/github",
+          };
+        },
+      }),
+    ],
+  });
+
+  await app.start();
+
+  console.log(`
+=================================
+JWT Auth Integration Example
+=================================
+
+This example shows OPTIONAL integration with JWT Auth Plugin.
+
+The GitHub App Plugin works standalone without JWT Auth Plugin.
+
+If JWT Auth Plugin is installed:
+- Installation links to authenticated JWT user
+- Endpoints can be protected with JWT authentication
+- User context available via ctx.auth
+
+If JWT Auth Plugin is NOT installed:
+- Use your own authentication system
+- Get userId from session, custom tokens, etc.
+- Plugin works exactly the same
+
+Available endpoints:
+- GET /github/repos (protected if JWT Auth enabled)
+- GET /github/installations (protected if JWT Auth enabled)
+
+=================================
+  `);
+}
+
+// Handler: List user's GitHub repositories
+// This handler works with or without JWT Auth Plugin
+const GetUserGitHubRepos: GetHandler = async ({ ctx }) => {
+  // Get userId from JWT Auth context if available,
+  // otherwise from your custom auth system
+  const userId = ctx.auth?.tokenData?.userId || ctx.session?.userId || "demo-user";
+
+  try {
+    // Get user's GitHub installation
+    const installation = await ctx.plugins.githubApp.getInstallation(userId);
+
+    if (!installation) {
+      return {
+        status: 404,
+        data: {
+          error: "github-app-not-installed",
+          message: "GitHub App is not installed",
+          hint: "Install the GitHub App to access your repositories",
+        },
+      };
+    }
+
+    // Get API client
+    const client = await ctx.plugins.githubApp.getClient(installation.installationId);
+
+    // Fetch repositories
+    const repos = await client.getRepositories();
+
+    return {
+      status: 200,
+      data: {
+        user: {
+          id: userId,
+          // Include user data if JWT Auth is available
+          email: ctx.auth?.user?.email,
+          name: ctx.auth?.user?.name,
+        },
+        installation: {
+          id: installation.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,
+          url: repo.html_url,
+        })),
+      },
+    };
+  } catch (error: any) {
+    console.error("Failed to list repositories:", error);
+    return {
+      status: 500,
+      data: {
+        error: "repository-access-failed",
+        message: error.message,
+      },
+    };
+  }
+};
+
+export { GetUserGitHubRepos };
+
+// Handler: Get user's GitHub installations
+const GetUserInstallations: GetHandler = async ({ ctx }) => {
+  const userId = ctx.auth?.tokenData?.userId || ctx.session?.userId || "demo-user";
+
+  try {
+    // Get all installations for user
+    const installations = await ctx.plugins.githubApp.getInstallations(userId);
+
+    return {
+      status: 200,
+      data: {
+        user: {
+          id: userId,
+          email: ctx.auth?.user?.email,
+        },
+        installations: installations.map((inst) => ({
+          installationId: inst.installationId,
+          account: {
+            id: inst.accountId,
+            login: inst.accountLogin,
+            type: inst.accountType,
+            avatarUrl: inst.avatarUrl,
+          },
+          repositories: inst.repositories,
+          permissions: inst.permissions,
+          events: inst.events,
+          createdAt: inst.createdAt,
+          suspendedAt: inst.suspendedAt,
+        })),
+        total: installations.length,
+      },
+    };
+  } catch (error: any) {
+    console.error("Failed to get installations:", error);
+    return {
+      status: 500,
+      data: {
+        error: "installations-access-failed",
+        message: error.message,
+      },
+    };
+  }
+};
+
+export { GetUserInstallations };
+
+// Example: Protected handler (if JWT Auth Plugin is enabled)
+// If JWT Auth is not enabled, this will work without authentication
+const GetProtectedResource: GetHandler = async ({ ctx }) => {
+  // This check only applies if JWT Auth Plugin is installed
+  if (!ctx.auth?.tokenData) {
+    // If no JWT Auth Plugin, allow access anyway
+    // Or implement your own authentication check
+    console.log("No JWT authentication, allowing access");
+  }
+
+  const userId = ctx.auth?.tokenData?.userId || "anonymous";
+
+  // Check if user has GitHub App installed
+  const installation = await ctx.plugins.githubApp.getInstallation(userId);
+
+  return {
+    status: 200,
+    data: {
+      message: "Protected resource accessed",
+      authenticated: !!ctx.auth?.tokenData,
+      userId,
+      hasGitHubApp: !!installation,
+    },
+  };
+};
+
+export { GetProtectedResource };
+
+// Start application
+start().catch((error) => {
+  console.error("Failed to start application:", error);
+  process.exit(1);
+});
+
+/*
+ * SUMMARY:
+ *
+ * The GitHub App Plugin is STANDALONE and does NOT require JWT Auth Plugin.
+ *
+ * Benefits of using with JWT Auth Plugin:
+ * - Automatic user context from JWT tokens
+ * - Protected endpoints with JWT authentication
+ * - Consistent authentication across all features
+ * - User data available via ctx.auth
+ *
+ * Benefits of using standalone:
+ * - No dependency on specific auth system
+ * - Works with any authentication mechanism
+ * - Simpler setup for custom auth systems
+ * - More flexibility in user management
+ *
+ * Choose the approach that fits your application architecture.
+ */

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@flink-app/github-app-plugin",
+    "version": "0.12.1-alpha.38",
+    "description": "Flink plugin for GitHub App integration with installation management and webhook handling",
+    "scripts": {
+        "test": "node --preserve-symlinks -r ts-node/register -- node_modules/jasmine/bin/jasmine --config=./spec/support/jasmine.json",
+        "test:watch": "nodemon --ext ts --exec 'jasmine-ts --config=./spec/support/jasmine.json'",
+        "prepare": "tsc --project tsconfig.dist.json",
+        "build": "tsc --project tsconfig.dist.json",
+        "watch": "tsc-watch --project tsconfig.dist.json"
+    },
+    "author": "joel@frost.se",
+    "license": "MIT",
+    "types": "dist/index.d.ts",
+    "main": "dist/index.js",
+    "publishConfig": {
+        "access": "public"
+    },
+    "peerDependencies": {
+        "mongodb": "^6.15.0"
+    },
+    "dependencies": {
+        "jsonwebtoken": "^9.0.2"
+    },
+    "devDependencies": {
+        "@flink-app/flink": "^0.12.1-alpha.35",
+        "@flink-app/test-utils": "^0.12.1-alpha.38",
+        "@types/jasmine": "^3.7.1",
+        "@types/jsonwebtoken": "^9.0.5",
+        "@types/node": "22.13.10",
+        "jasmine": "^3.7.0",
+        "jasmine-spec-reporter": "^7.0.0",
+        "mongodb": "6.15.0",
+        "mongodb-memory-server": "^10.2.3",
+        "nodemon": "^2.0.7",
+        "ts-node": "^9.1.1",
+        "tsc-watch": "^4.2.9",
+        "typescript": "5.4.5"
+    },
+    "gitHead": "bba579788683fe0729399a56152eba4974f29bb6"
+}