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

package/examples/basic-installation.ts

@@ -0,0 +1,246 @@
+/**
+ * Basic GitHub App Installation Example
+ *
+ * This example demonstrates:
+ * - Setting up GitHub App Plugin with standalone authentication
+ * - Initiating GitHub App installation
+ * - Handling installation success callback
+ * - Linking installation to user account
+ * - Accessing user's GitHub repositories
+ *
+ * Note: This example uses standalone authentication (no JWT Auth Plugin required)
+ */
+
+import { FlinkApp, FlinkContext, FlinkRepo } from "@flink-app/flink";
+import { githubAppPlugin } from "@flink-app/github-app-plugin";
+
+// Define User schema
+interface User {
+  _id?: string;
+  email: string;
+  name: string;
+  githubInstallations: number[]; // Array of installation IDs
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// User repository
+class UserRepo extends FlinkRepo<AppContext, User> {
+  async findByEmail(email: string) {
+    return this.getOne({ email });
+  }
+
+  async addGitHubInstallation(userId: string, installationId: number) {
+    const user = await this.getById(userId);
+    if (!user) {
+      throw new Error("User not found");
+    }
+
+    const installations = user.githubInstallations || [];
+    if (!installations.includes(installationId)) {
+      await this.updateOne(userId, {
+        githubInstallations: [...installations, installationId],
+      });
+    }
+  }
+}
+
+// Application context
+interface AppContext extends FlinkContext {
+  repos: {
+    userRepo: UserRepo;
+  };
+  plugins: {
+    githubApp: any;
+  };
+  // Custom session property for this example
+  session?: {
+    userId?: string;
+    email?: string;
+  };
+}
+
+async function start() {
+  const app = new FlinkApp<AppContext>({
+    name: "GitHub App Basic Installation Example",
+    port: 3333,
+
+    db: {
+      uri: process.env.MONGODB_URI || "mongodb://localhost:27017/github-app-example",
+    },
+
+    plugins: [
+      githubAppPlugin({
+        // GitHub App credentials (required)
+        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!,
+
+        // Optional: App slug for installation URL
+        appSlug: "my-flink-app",
+
+        // Optional: Base URL (default: https://api.github.com)
+        baseUrl: process.env.GITHUB_API_URL || "https://api.github.com",
+
+        // Callback after successful installation
+        onInstallationSuccess: async ({ installationId, repositories, account, permissions, events }, ctx) => {
+          console.log(`\n=== Installation Success ===`);
+          console.log(`Installation ID: ${installationId}`);
+          console.log(`Account: ${account.login} (${account.type})`);
+          console.log(`Repositories: ${repositories.length}`);
+          console.log(`Permissions:`, permissions);
+          console.log(`Events subscribed:`, events);
+
+          // Get userId from your authentication system
+          // In this example, we use a mock session
+          const userId = ctx.session?.userId || "demo-user-123";
+
+          // Link installation to user in your database
+          try {
+            await ctx.repos.userRepo.addGitHubInstallation(userId, installationId);
+            console.log(`Installation ${installationId} linked to user ${userId}`);
+          } catch (error) {
+            console.error("Failed to link installation:", error);
+          }
+
+          // List repositories the user granted access to
+          console.log("\nRepositories granted access:");
+          repositories.forEach((repo) => {
+            console.log(`  - ${repo.fullName} (${repo.private ? "private" : "public"})`);
+          });
+
+          // Redirect user back to dashboard
+          return {
+            userId,
+            redirectUrl: "/dashboard?installation=success",
+          };
+        },
+
+        // Optional: Handle installation errors
+        onInstallationError: async ({ error, installationId }) => {
+          console.error(`\n=== Installation Error ===`);
+          console.error(`Error Code: ${error.code}`);
+          console.error(`Message: ${error.message}`);
+          if (installationId) {
+            console.error(`Installation ID: ${installationId}`);
+          }
+
+          return {
+            redirectUrl: "/error?message=installation-failed",
+          };
+        },
+
+        // Optional: Log webhook events for debugging
+        logWebhookEvents: false,
+      }),
+    ],
+  });
+
+  // Create demo user if doesn't exist
+  await app.onReady(async () => {
+    const demoUser = await app.ctx.repos.userRepo.findByEmail("demo@example.com");
+
+    if (!demoUser) {
+      await app.ctx.repos.userRepo.create({
+        email: "demo@example.com",
+        name: "Demo User",
+        githubInstallations: [],
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      });
+      console.log("Demo user created");
+    }
+  });
+
+  await app.start();
+
+  console.log(`
+=================================
+GitHub App Basic Example Started
+=================================
+
+To install the GitHub App:
+
+1. Navigate to: http://localhost:3333/github-app/install?user_id=demo-user-123
+2. Authorize the app on GitHub
+3. Select repositories to grant access
+4. Complete installation
+
+To access user's repositories via API:
+
+Use the context API in your handlers:
+
+  const installation = await ctx.plugins.githubApp.getInstallation('demo-user-123');
+  if (installation) {
+    const client = await ctx.plugins.githubApp.getClient(installation.installationId);
+    const repos = await client.getRepositories();
+    console.log('User repositories:', repos);
+  }
+
+=================================
+  `);
+}
+
+// Handle errors
+start().catch((error) => {
+  console.error("Failed to start application:", error);
+  process.exit(1);
+});
+
+// Example handler to list user's GitHub repositories
+// Save this in src/handlers/github/GetUserRepos.ts
+
+/*
+import { GetHandler } from "@flink-app/flink";
+
+const GetUserRepos: GetHandler = async ({ ctx }) => {
+  // Get userId from your auth system
+  const userId = ctx.session?.userId || 'demo-user-123';
+
+  // Get user's installation
+  const installation = await ctx.plugins.githubApp.getInstallation(userId);
+
+  if (!installation) {
+    return {
+      status: 404,
+      data: {
+        error: 'GitHub App not installed',
+        message: 'Please install the GitHub App first'
+      }
+    };
+  }
+
+  // Get API client
+  const client = await ctx.plugins.githubApp.getClient(installation.installationId);
+
+  // Fetch repositories
+  const repos = await client.getRepositories();
+
+  return {
+    status: 200,
+    data: {
+      installation: {
+        account: installation.accountLogin,
+        type: installation.accountType,
+        installedAt: installation.createdAt
+      },
+      repositories: repos.map(repo => ({
+        id: repo.id,
+        name: repo.name,
+        fullName: repo.full_name,
+        private: repo.private,
+        url: repo.html_url,
+        description: repo.description
+      }))
+    }
+  };
+};
+
+export default GetUserRepos;
+
+export const Route = {
+  path: '/github/repos'
+};
+*/

package/examples/create-issue.ts

@@ -0,0 +1,392 @@
+/**
+ * Create GitHub Issue Example
+ *
+ * This example demonstrates:
+ * - Creating GitHub issues with permission checks
+ * - Using the GitHub API client
+ * - Verifying repository access before operations
+ * - Adding labels and assignees to issues
+ * - Error handling for permission failures
+ */
+
+import { FlinkApp, FlinkContext, PostHandler } from "@flink-app/flink";
+import { githubAppPlugin } from "@flink-app/github-app-plugin";
+
+interface AppContext extends FlinkContext {
+  plugins: {
+    githubApp: any;
+  };
+  session?: {
+    userId?: string;
+  };
+}
+
+interface CreateIssueRequest {
+  owner: string;
+  repo: string;
+  title: string;
+  body?: string;
+  labels?: string[];
+  assignees?: string[];
+}
+
+async function start() {
+  const app = new FlinkApp<AppContext>({
+    name: "GitHub App Create Issue Example",
+    port: 3333,
+
+    db: {
+      uri: process.env.MONGODB_URI || "mongodb://localhost:27017/github-app-issue-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, repositories, account, permissions }) => {
+          const userId = "demo-user-123";
+
+          console.log(`\nInstallation successful!`);
+          console.log(`Account: ${account.login}`);
+          console.log(`Repositories: ${repositories.length}`);
+          console.log(`Permissions:`, permissions);
+
+          // Check if we have issues permission
+          if (permissions.issues !== "write") {
+            console.warn(`Warning: Issues permission is ${permissions.issues}, may not be able to create issues`);
+          }
+
+          return { userId, redirectUrl: "/dashboard" };
+        },
+      }),
+    ],
+  });
+
+  await app.start();
+
+  console.log(`
+=================================
+Create Issue Example Started
+=================================
+
+Available endpoints:
+
+POST /issues/create
+Body: {
+  "owner": "owner-name",
+  "repo": "repo-name",
+  "title": "Issue title",
+  "body": "Issue description",
+  "labels": ["bug", "help wanted"],
+  "assignees": ["username"]
+}
+
+Example curl:
+curl -X POST http://localhost:3333/issues/create \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "owner": "facebook",
+    "repo": "react",
+    "title": "Bug Report",
+    "body": "Found a bug...",
+    "labels": ["bug"]
+  }'
+
+Install the GitHub App first:
+http://localhost:3333/github-app/install?user_id=demo-user-123
+
+=================================
+  `);
+}
+
+// Handler: Create GitHub issue
+const CreateIssue: PostHandler<CreateIssueRequest> = async ({ ctx, body }) => {
+  const userId = ctx.session?.userId || "demo-user-123";
+
+  // Validate request body
+  if (!body.owner || !body.repo || !body.title) {
+    return {
+      status: 400,
+      data: {
+        error: "invalid-request",
+        message: "owner, repo, and title are required",
+      },
+    };
+  }
+
+  const { owner, repo, title, body: issueBody, labels, assignees } = body;
+
+  try {
+    // Step 1: Check if user has access to repository
+    console.log(`Checking access to ${owner}/${repo}...`);
+    const hasAccess = await ctx.plugins.githubApp.hasRepositoryAccess(userId, owner, repo);
+
+    if (!hasAccess) {
+      return {
+        status: 403,
+        data: {
+          error: "access-denied",
+          message: `You do not have access to repository ${owner}/${repo}`,
+          hint: "Install the GitHub App and grant access to this repository",
+        },
+      };
+    }
+
+    // Step 2: Get user's installation
+    const installation = await ctx.plugins.githubApp.getInstallation(userId);
+
+    if (!installation) {
+      return {
+        status: 404,
+        data: {
+          error: "installation-not-found",
+          message: "GitHub App is not installed for your account",
+          hint: "Install the GitHub App first",
+        },
+      };
+    }
+
+    // Step 3: Get API client
+    console.log(`Getting API client for installation ${installation.installationId}...`);
+    const client = await ctx.plugins.githubApp.getClient(installation.installationId);
+
+    // Step 4: Create the issue
+    console.log(`Creating issue in ${owner}/${repo}...`);
+    const issue = await client.createIssue(owner, repo, {
+      title,
+      body: issueBody || "",
+    });
+
+    console.log(`Issue created: #${issue.number}`);
+
+    // Step 5: Add labels if provided
+    if (labels && labels.length > 0) {
+      console.log(`Adding labels: ${labels.join(", ")}`);
+      try {
+        await client.request("POST", `/repos/${owner}/${repo}/issues/${issue.number}/labels`, {
+          labels,
+        });
+      } catch (error) {
+        console.warn(`Failed to add labels:`, error);
+        // Continue anyway
+      }
+    }
+
+    // Step 6: Add assignees if provided
+    if (assignees && assignees.length > 0) {
+      console.log(`Adding assignees: ${assignees.join(", ")}`);
+      try {
+        await client.request("POST", `/repos/${owner}/${repo}/issues/${issue.number}/assignees`, {
+          assignees,
+        });
+      } catch (error) {
+        console.warn(`Failed to add assignees:`, error);
+        // Continue anyway
+      }
+    }
+
+    // Return success response
+    return {
+      status: 201,
+      data: {
+        success: true,
+        issue: {
+          id: issue.id,
+          number: issue.number,
+          title: issue.title,
+          body: issue.body,
+          state: issue.state,
+          url: issue.html_url,
+          createdAt: issue.created_at,
+          labels: issue.labels,
+          assignees: issue.assignees,
+        },
+        message: `Issue #${issue.number} created successfully`,
+      },
+    };
+  } catch (error: any) {
+    console.error("Failed to create issue:", error);
+
+    // Handle specific GitHub API errors
+    if (error.response?.status === 403) {
+      return {
+        status: 403,
+        data: {
+          error: "permission-denied",
+          message: "GitHub App does not have permission to create issues in this repository",
+          hint: "Check that the GitHub App has 'issues: write' permission",
+        },
+      };
+    }
+
+    if (error.response?.status === 404) {
+      return {
+        status: 404,
+        data: {
+          error: "repository-not-found",
+          message: `Repository ${owner}/${repo} not found or not accessible`,
+        },
+      };
+    }
+
+    if (error.response?.status === 410) {
+      return {
+        status: 410,
+        data: {
+          error: "issues-disabled",
+          message: "Issues are disabled for this repository",
+        },
+      };
+    }
+
+    // Generic error
+    return {
+      status: 500,
+      data: {
+        error: "issue-creation-failed",
+        message: error.message || "Failed to create issue",
+        details: error.response?.data,
+      },
+    };
+  }
+};
+
+export { CreateIssue };
+
+// Handler: Create issue from template
+const CreateIssueFromTemplate: PostHandler<{
+  owner: string;
+  repo: string;
+  template: "bug" | "feature" | "question";
+  additionalInfo?: Record<string, any>;
+}> = async ({ ctx, body }) => {
+  const userId = ctx.session?.userId || "demo-user-123";
+  const { owner, repo, template, additionalInfo = {} } = body;
+
+  // Define issue templates
+  const templates = {
+    bug: {
+      title: `[BUG] ${additionalInfo.summary || "Issue summary"}`,
+      body: `## Bug Description
+${additionalInfo.description || "Describe the bug..."}
+
+## Steps to Reproduce
+${additionalInfo.steps || "1. ...\\n2. ...\\n3. ..."}
+
+## Expected Behavior
+${additionalInfo.expected || "What should happen..."}
+
+## Actual Behavior
+${additionalInfo.actual || "What actually happens..."}
+
+## Environment
+${additionalInfo.environment || "- OS: ...\\n- Browser: ...\\n- Version: ..."}`,
+      labels: ["bug"],
+    },
+    feature: {
+      title: `[FEATURE] ${additionalInfo.summary || "Feature request"}`,
+      body: `## Feature Description
+${additionalInfo.description || "Describe the feature..."}
+
+## Use Case
+${additionalInfo.useCase || "Why is this feature needed?"}
+
+## Proposed Solution
+${additionalInfo.solution || "How should it work?"}
+
+## Alternatives Considered
+${additionalInfo.alternatives || "What alternatives have been considered?"}`,
+      labels: ["enhancement"],
+    },
+    question: {
+      title: `[QUESTION] ${additionalInfo.summary || "Question"}`,
+      body: `## Question
+${additionalInfo.question || "Your question..."}
+
+## Context
+${additionalInfo.context || "Additional context..."}`,
+      labels: ["question"],
+    },
+  };
+
+  const issueTemplate = templates[template];
+
+  if (!issueTemplate) {
+    return {
+      status: 400,
+      data: {
+        error: "invalid-template",
+        message: "Template must be one of: bug, feature, question",
+      },
+    };
+  }
+
+  try {
+    // Check access
+    const hasAccess = await ctx.plugins.githubApp.hasRepositoryAccess(userId, owner, repo);
+    if (!hasAccess) {
+      return {
+        status: 403,
+        data: { error: "access-denied" },
+      };
+    }
+
+    // Get installation and client
+    const installation = await ctx.plugins.githubApp.getInstallation(userId);
+    if (!installation) {
+      return {
+        status: 404,
+        data: { error: "installation-not-found" },
+      };
+    }
+
+    const client = await ctx.plugins.githubApp.getClient(installation.installationId);
+
+    // Create issue
+    const issue = await client.createIssue(owner, repo, {
+      title: issueTemplate.title,
+      body: issueTemplate.body,
+    });
+
+    // Add labels
+    if (issueTemplate.labels.length > 0) {
+      await client.request("POST", `/repos/${owner}/${repo}/issues/${issue.number}/labels`, {
+        labels: issueTemplate.labels,
+      });
+    }
+
+    return {
+      status: 201,
+      data: {
+        success: true,
+        issue: {
+          number: issue.number,
+          title: issue.title,
+          url: issue.html_url,
+          template,
+        },
+      },
+    };
+  } catch (error: any) {
+    console.error("Failed to create issue from template:", error);
+    return {
+      status: 500,
+      data: {
+        error: "issue-creation-failed",
+        message: error.message,
+      },
+    };
+  }
+};
+
+export { CreateIssueFromTemplate };
+
+// Start application
+start().catch((error) => {
+  console.error("Failed to start application:", error);
+  process.exit(1);
+});