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

package/README.md

@@ -82,6 +82,8 @@ The plugin requires MongoDB to store installation data and sessions.
 
 ## Quick Start
 
+### 1. Configure the Plugin
+
 ```typescript
 import { FlinkApp } from "@flink-app/flink";
 import { githubAppPlugin } from "@flink-app/github-app-plugin";
@@ -102,45 +104,13 @@ const app = new FlinkApp<Context>({
             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",
 
-            // Required: Callback after successful installation
-            onInstallationSuccess: async ({ installationId, repositories, account }, ctx) => {
-                // Your app determines how to get userId
-                // This could come from session, custom auth, or any other source
-                const userId = getUserIdFromSession(); // Your implementation
-
-                console.log(`User ${userId} installed app on ${account.login}`);
-                console.log(`Granted access to ${repositories.length} repositories`);
-
-                return {
-                    userId, // Link installation to this user
-                    redirectUrl: "/dashboard/repos", // Where to redirect after installation
-                };
-            },
-
             // Optional: Handle webhook events
             onWebhookEvent: async ({ event, action, payload, installationId }, ctx) => {
-                console.log(`Received ${event} event for installation ${installationId}`);
-
-                // Handle specific events
                 if (event === "push") {
                     console.log(`Push to ${payload.repository.full_name}`);
                 }
-
-                if (event === "pull_request" && action === "opened") {
-                    console.log(`New PR #${payload.pull_request.number}`);
-                }
-            },
-
-            // Optional: Handle installation errors
-            onInstallationError: async ({ error, installationId }) => {
-                console.error(`Installation error:`, error);
-                return {
-                    redirectUrl: "/error?message=installation-failed",
-                };
             },
         }),
     ],
@@ -149,6 +119,54 @@ const app = new FlinkApp<Context>({
 await app.start();
 ```
 
+### 2. Implement Installation Callback Handler
+
+The plugin does NOT include an opinionated installation callback handler. You must implement your own handler with your own authentication and authorization logic.
+
+```typescript
+// src/handlers/github/GetGitHubInstallCallback.ts
+import { GetHandler, unauthorized, badRequest, redirect } from "@flink-app/flink";
+import { Context } from "../../Context";
+
+export const Route = {
+    path: "/github/callback",
+};
+
+const GetGitHubInstallCallback: GetHandler<{}, {}, {}, { installation_id: string; state: string }> = async ({
+    ctx,
+    req,
+}) => {
+    // 1. Check authentication (your way)
+    if (!ctx.auth?.tokenData?.userId) {
+        return unauthorized("Please log in to connect GitHub");
+    }
+
+    // 2. Parse query params
+    const { installation_id, state } = req.query;
+    if (!installation_id || !state) {
+        return badRequest("Missing required parameters");
+    }
+
+    // 3. Complete installation using plugin
+    const result = await ctx.plugins.githubApp.completeInstallation({
+        installationId: parseInt(installation_id, 10),
+        state,
+        userId: ctx.auth.tokenData.userId,
+    });
+
+    // 4. Handle response (your way)
+    if (!result.success) {
+        console.error("Installation failed:", result.error);
+        return redirect(`/settings/github?error=${result.error.code}`);
+    }
+
+    console.log("GitHub App installed:", result.installation);
+    return redirect("/settings/github?success=true");
+};
+
+export default GetGitHubInstallCallback;
+```
+
 ## Configuration
 
 ### GitHubAppPluginOptions
@@ -162,8 +180,6 @@ await app.start();
 | `clientSecret`                | `string`   | Yes      | -                        | GitHub App client secret                          |
 | `appSlug`                     | `string`   | No       | Auto-detected            | GitHub App slug (used in installation URL)        |
 | `baseUrl`                     | `string`   | No       | `https://api.github.com` | GitHub API base URL (for GitHub Enterprise)       |
-| `onInstallationSuccess`       | `Function` | Yes      | -                        | Callback after successful installation            |
-| `onInstallationError`         | `Function` | No       | -                        | Callback on installation errors                   |
 | `onWebhookEvent`              | `Function` | No       | -                        | Callback for webhook events                       |
 | `sessionsCollectionName`      | `string`   | No       | `github_app_sessions`    | MongoDB collection for sessions                   |
 | `installationsCollectionName` | `string`   | No       | `github_installations`   | MongoDB collection for installations              |
@@ -175,73 +191,6 @@ await app.start();
 
 ### Callback Functions
 
-#### onInstallationSuccess (Required)
-
-Called when a user successfully installs the GitHub App.
-
-```typescript
-onInstallationSuccess: async (
-    params: {
-        installationId: number;
-        account: {
-            id: number;
-            login: string;
-            type: "User" | "Organization";
-            avatarUrl?: string;
-        };
-        repositories: {
-            id: number;
-            name: string;
-            fullName: string;
-            private: boolean;
-        }[];
-        permissions: Record<string, string>;
-        events: string[];
-    },
-    ctx: Context
-) =>
-    Promise<{
-        userId: string;
-        redirectUrl?: string;
-    }>;
-```
-
-**Example:**
-
-```typescript
-onInstallationSuccess: async ({ installationId, repositories, account }, ctx) => {
-    // Get userId from your authentication system
-    const userId = ctx.session?.userId || "anonymous";
-
-    // Optionally notify user
-    console.log(`Installation ${installationId} linked to user ${userId}`);
-    console.log(`Access granted to ${repositories.length} repositories`);
-
-    return {
-        userId, // Required: Link installation to this user
-        redirectUrl: "/dashboard", // Optional: Redirect after installation
-    };
-};
-```
-
-#### onInstallationError (Optional)
-
-Called when installation fails.
-
-```typescript
-onInstallationError: async (params: {
-    error: {
-        code: string;
-        message: string;
-        details?: any;
-    };
-    installationId?: number;
-}) =>
-    Promise<{
-        redirectUrl?: string;
-    }>;
-```
-
 #### onWebhookEvent (Optional)
 
 Called when a webhook event is received.
@@ -411,6 +360,24 @@ if (!hasAccess) {
 }
 ```
 
+### completeInstallation(params)
+
+Complete GitHub App installation after callback from GitHub.
+
+```typescript
+const result = await ctx.plugins.githubApp.completeInstallation({
+    installationId: 12345,
+    state: "csrf-state-token",
+    userId: "user-123",
+});
+
+if (result.success) {
+    console.log("Installation completed:", result.installation);
+} else {
+    console.error("Installation failed:", result.error);
+}
+```
+
 ### getInstallationToken(installationId)
 
 Get raw installation access token (for advanced usage).
@@ -454,80 +421,56 @@ const issue = await client.createIssue("facebook", "react", {
 const response = await client.request("GET", "/rate_limit");
 ```
 
-## Standalone Usage (No JWT Auth Plugin)
+## Authentication Integration
 
-This plugin is **standalone** and does NOT require the JWT Auth Plugin. It works with any authentication system.
+This plugin is **auth-agnostic** and works with any authentication system. You implement your own installation callback handler with your own auth logic.
 
-### Example with Custom Session-Based Auth
+### Example with Session-Based Auth
 
 ```typescript
-githubAppPlugin({
-    // ... config
-
-    onInstallationSuccess: async ({ installationId, repositories }, ctx) => {
-        // Get userId from your custom session system
-        const userId = ctx.req.session?.userId;
-
-        if (!userId) {
-            throw new Error("User not authenticated");
-        }
-
-        return {
-            userId,
-            redirectUrl: "/dashboard",
-        };
-    },
-});
-```
+// In your handler
+const GetGitHubCallback: GetHandler = async ({ ctx, req }) => {
+    // Check session-based auth
+    const userId = ctx.req.session?.userId;
+    if (!userId) {
+        return unauthorized("Please log in");
+    }
 
-### Example with Custom Token-Based Auth
+    const { installation_id, state } = req.query;
+    const result = await ctx.plugins.githubApp.completeInstallation({
+        installationId: parseInt(installation_id),
+        state,
+        userId,
+    });
 
-```typescript
-githubAppPlugin({
-    // ... config
-
-    onInstallationSuccess: async ({ installationId, repositories }, ctx) => {
-        // Get userId from your custom auth token
-        const authHeader = ctx.req.headers.authorization;
-        const userId = parseAuthToken(authHeader); // Your function
-
-        return {
-            userId,
-            redirectUrl: "/dashboard",
-        };
-    },
-});
+    return result.success
+        ? redirect("/dashboard")
+        : redirect(`/error?code=${result.error.code}`);
+};
 ```
 
-## Integration with JWT Auth Plugin (Optional)
-
-While the plugin works standalone, you can optionally use it with the JWT Auth Plugin:
+### Example with JWT Auth Plugin
 
 ```typescript
-import { jwtAuthPlugin } from "@flink-app/jwt-auth-plugin";
-
-const app = new FlinkApp<Context>({
-    auth: jwtAuthPlugin({
-        secret: process.env.JWT_SECRET!,
-        // ... JWT config
-    }),
-
-    plugins: [
-        githubAppPlugin({
-            // ... config
+// In your handler with @flink-app/jwt-auth-plugin
+const GetGitHubCallback: GetHandler = async ({ ctx, req }) => {
+    // Check JWT auth
+    const userId = ctx.auth?.tokenData?.userId;
+    if (!userId) {
+        return unauthorized("Please log in");
+    }
 
-            onInstallationSuccess: async ({ installationId, repositories }, ctx) => {
-                // Access JWT Auth Plugin context (if available)
-                const userId = ctx.auth?.tokenData?.userId || "anonymous";
+    const { installation_id, state } = req.query;
+    const result = await ctx.plugins.githubApp.completeInstallation({
+        installationId: parseInt(installation_id),
+        state,
+        userId,
+    });
 
-                return {
-                    userId,
-                    redirectUrl: "/dashboard",
-                };
-            },
-        }),
-    ],
-});
+    return result.success
+        ? redirect("/dashboard/github")
+        : redirect(`/error?code=${result.error.code}`);
+};
 ```
 
 ## Security Considerations

package/dist/GitHubAppInternalContext.d.ts

@@ -1,44 +1,15 @@
 import { FlinkContext } from "@flink-app/flink";
-import { GitHubAuthService } from "./services/GitHubAuthService";
-import { WebhookValidator } from "./services/WebhookValidator";
+import { GitHubAppPluginContext } from "./GitHubAppPluginContext";
 import GitHubAppSessionRepo from "./repos/GitHubAppSessionRepo";
 import GitHubInstallationRepo from "./repos/GitHubInstallationRepo";
 import GitHubWebhookEventRepo from "./repos/GitHubWebhookEventRepo";
-import { GitHubAppPluginOptions } from "./GitHubAppPluginOptions";
 /**
- * Internal context interface with private methods and services
- *
- * This interface extends the base FlinkContext with GitHub App Plugin-specific
- * repositories, services, and configuration. It's used internally by handlers,
- * services, and the plugin itself.
+ * Internal context used for plugin handlers.
  */
-export interface GitHubAppInternalContext extends FlinkContext {
-    /**
-     * GitHub App Session Repository
-     * Manages temporary installation sessions for CSRF protection
-     */
-    repos: FlinkContext['repos'] & {
+export interface GitHubAppInternalContext extends FlinkContext<GitHubAppPluginContext> {
+    repos: {
         githubAppSessionRepo: GitHubAppSessionRepo;
         githubInstallationRepo: GitHubInstallationRepo;
         githubWebhookEventRepo?: GitHubWebhookEventRepo;
     };
-    /**
-     * Internal plugin state and services
-     */
-    _githubAppInternal: {
-        /**
-         * GitHub Authentication Service
-         * Handles JWT generation and installation token management
-         */
-        authService: GitHubAuthService;
-        /**
-         * Webhook Validator
-         * Validates webhook signatures and parses payloads
-         */
-        webhookValidator: WebhookValidator;
-        /**
-         * Plugin configuration options
-         */
-        options: GitHubAppPluginOptions;
-    };
 }

package/dist/GitHubAppPlugin.js

@@ -34,9 +34,9 @@ const GitHubWebhookEventRepo_1 = __importDefault(require("./repos/GitHubWebhookE
 const GitHubAuthService_1 = require("./services/GitHubAuthService");
 const GitHubAPIClient_1 = require("./services/GitHubAPIClient");
 const WebhookValidator_1 = require("./services/WebhookValidator");
+const InstallationService_1 = require("./services/InstallationService");
 const error_utils_1 = require("./utils/error-utils");
 const state_utils_1 = require("./utils/state-utils");
-const InstallationCallback = __importStar(require("./handlers/InstallationCallback"));
 const WebhookHandler = __importStar(require("./handlers/WebhookHandler"));
 /**
  * GitHub App Plugin Factory Function
@@ -97,9 +97,6 @@ function githubAppPlugin(options) {
     if (!options.clientSecret) {
         throw new Error("GitHub App Plugin: clientSecret is required");
     }
-    if (!options.onInstallationSuccess) {
-        throw new Error("GitHub App Plugin: onInstallationSuccess callback is required");
-    }
     // Determine configuration defaults
     const baseUrl = options.baseUrl || "https://api.github.com";
     const tokenCacheTTL = options.tokenCacheTTL || 3300; // 55 minutes
@@ -109,6 +106,7 @@ function githubAppPlugin(options) {
     let flinkApp;
     let authService;
     let webhookValidator;
+    let installationService;
     let sessionRepo;
     let installationRepo;
     let webhookEventRepo;
@@ -143,6 +141,8 @@ function githubAppPlugin(options) {
             // Add repositories to FlinkApp
             flinkApp.addRepo("githubAppSessionRepo", sessionRepo);
             flinkApp.addRepo("githubInstallationRepo", installationRepo);
+            // Initialize InstallationService
+            installationService = new InstallationService_1.InstallationService(authService, sessionRepo, installationRepo, baseUrl);
             // Conditionally initialize webhook event repo if logging is enabled
             if (logWebhookEvents) {
                 webhookEventRepo = new GitHubWebhookEventRepo_1.default(flinkApp.ctx, db, webhookEventsCollectionName);
@@ -160,11 +160,10 @@ function githubAppPlugin(options) {
                 await db.collection(webhookEventsCollectionName).createIndex({ createdAt: 1 }, { expireAfterSeconds: webhookEventTTL });
                 flink_1.log.info(`GitHub App Plugin: Created TTL index on ${webhookEventsCollectionName} with ${webhookEventTTL}s expiration`);
             }
-            // Conditionally register handlers (only GitHub-required handlers)
+            // Conditionally register handlers (only webhook handler)
             if (registerRoutes) {
-                flinkApp.addHandler(InstallationCallback);
                 flinkApp.addHandler(WebhookHandler);
-                flink_1.log.info("GitHub App Plugin: Registered handlers (callback and webhook)");
+                flink_1.log.info("GitHub App Plugin: Registered webhook handler");
             }
             else {
                 flink_1.log.info("GitHub App Plugin: Skipped handler registration (routes disabled)");
@@ -213,6 +212,15 @@ function githubAppPlugin(options) {
             sessionId,
         };
     }
+    /**
+     * Complete GitHub App installation
+     */
+    async function completeInstallation(params) {
+        if (!installationService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+        return installationService.completeInstallation(params);
+    }
     /**
      * Uninstalls GitHub App for a user
      */
@@ -343,6 +351,7 @@ function githubAppPlugin(options) {
      */
     const pluginCtx = {
         initiateInstallation,
+        completeInstallation,
         uninstall,
         getClient,
         getInstallation,

package/dist/GitHubAppPluginContext.d.ts

@@ -3,6 +3,7 @@ import GitHubInstallation from "./schemas/GitHubInstallation";
 import { GitHubAppPluginOptions } from "./GitHubAppPluginOptions";
 import { GitHubAuthService } from "./services/GitHubAuthService";
 import { WebhookValidator } from "./services/WebhookValidator";
+import { CompleteInstallationResult } from "./services/InstallationService";
 /**
  * Public context interface exposed via ctx.plugins.githubApp
  *
@@ -50,6 +51,62 @@ export interface GitHubAppPluginContext {
             state: string;
             sessionId: string;
         }>;
+        /**
+         * Complete GitHub App installation
+         *
+         * Handles all the boilerplate of completing a GitHub App installation:
+         * 1. Validates the state parameter (CSRF protection)
+         * 2. Fetches installation details from GitHub API
+         * 3. Stores the installation in database
+         *
+         * The host application should:
+         * - Check if user is authenticated
+         * - Parse query parameters from the callback URL
+         * - Call this method with userId
+         * - Handle the response and redirect
+         *
+         * @param params - Installation completion parameters
+         * @param params.installationId - GitHub installation ID from query params
+         * @param params.state - State parameter from query params (CSRF protection)
+         * @param params.userId - Application user ID (from auth system)
+         * @returns Result with installation details or error
+         *
+         * @example
+         * ```typescript
+         * // In your custom callback handler
+         * export default async function GitHubCallback({ ctx, req }: GetHandlerParams) {
+         *   // 1. Check authentication (your way)
+         *   if (!ctx.auth?.tokenData?.userId) {
+         *     return unauthorized('Please log in first');
+         *   }
+         *
+         *   // 2. Parse query params
+         *   const { installation_id, state } = req.query;
+         *   if (!installation_id || !state) {
+         *     return badRequest('Missing required parameters');
+         *   }
+         *
+         *   // 3. Complete installation
+         *   const result = await ctx.plugins.githubApp.completeInstallation({
+         *     installationId: parseInt(installation_id),
+         *     state,
+         *     userId: ctx.auth.tokenData.userId
+         *   });
+         *
+         *   // 4. Handle response (your way)
+         *   if (!result.success) {
+         *     return redirect(`/error?code=${result.error.code}`);
+         *   }
+         *
+         *   return redirect('/dashboard/github');
+         * }
+         * ```
+         */
+        completeInstallation(params: {
+            installationId: number;
+            state: string;
+            userId: string;
+        }): Promise<CompleteInstallationResult>;
         /**
          * Uninstalls GitHub App for a user
          *

package/dist/GitHubAppPluginOptions.d.ts

@@ -7,6 +7,8 @@
 export interface InstallationSuccessParams {
     /** GitHub installation ID */
     installationId: number;
+    /** Setup action type: 'install' for new installations, 'update' for repository selection updates */
+    setupAction: string;
     /** GitHub account (user or organization) where app was installed */
     account: {
         /** Account ID on GitHub */
@@ -134,8 +136,11 @@ export interface WebhookEventParams {
 /**
  * Configuration options for GitHub App Plugin
  *
- * Configure the plugin with your GitHub App credentials, callbacks,
- * and optional settings for database, caching, and features.
+ * Configure the plugin with your GitHub App credentials and optional settings
+ * for database, caching, and features.
+ *
+ * Note: Installation callback handler must be implemented by the host app.
+ * Use ctx.plugins.githubApp.completeInstallation() in your own handler.
  *
  * @example
  * ```typescript
@@ -146,12 +151,7 @@ export interface WebhookEventParams {
  *   webhookSecret: process.env.GITHUB_WEBHOOK_SECRET!,
  *   clientId: process.env.GITHUB_APP_CLIENT_ID!,
  *   clientSecret: process.env.GITHUB_APP_CLIENT_SECRET!,
- *
- *   // Required: Installation success callback
- *   onInstallationSuccess: async ({ installationId, repositories }, ctx) => {
- *     const userId = getUserId(ctx); // Your auth system
- *     return { userId, redirectUrl: '/dashboard' };
- *   },
+ *   appSlug: 'my-app',
  *
  *   // Optional: Handle webhook events
  *   onWebhookEvent: async ({ event, payload }, ctx) => {
@@ -235,50 +235,6 @@ export interface GitHubAppPluginOptions {
      * @example "https://github.mycompany.com/api/v3"
      */
     baseUrl?: string;
-    /**
-     * Callback invoked after successful installation
-     *
-     * REQUIRED. Called when user completes GitHub App installation.
-     * Return userId to link installation and optional redirectUrl.
-     *
-     * @param params - Installation data from GitHub
-     * @param ctx - Flink context with repos and plugins
-     * @returns Object with userId and optional redirectUrl
-     *
-     * @throws Should not throw - errors are caught and passed to onInstallationError
-     *
-     * @example
-     * ```typescript
-     * async ({ installationId, repositories, account }, ctx) => {
-     *   const userId = ctx.auth?.tokenData?.userId || 'anonymous';
-     *   return {
-     *     userId,
-     *     redirectUrl: '/dashboard/github'
-     *   };
-     * }
-     * ```
-     */
-    onInstallationSuccess: (params: InstallationSuccessParams, ctx: any) => Promise<InstallationSuccessResponse>;
-    /**
-     * Callback invoked when installation fails (optional)
-     *
-     * Called when installation encounters an error (invalid state,
-     * expired session, GitHub API failure, etc.)
-     *
-     * @param params - Error information
-     * @returns Object with optional redirectUrl
-     *
-     * @example
-     * ```typescript
-     * async ({ error, installationId }) => {
-     *   console.error('Installation error:', error);
-     *   return {
-     *     redirectUrl: `/error?code=${error.code}`
-     *   };
-     * }
-     * ```
-     */
-    onInstallationError?: (params: InstallationErrorParams) => Promise<InstallationErrorResponse>;
     /**
      * Callback invoked when webhook event is received (optional)
      *
@@ -351,8 +307,9 @@ export interface GitHubAppPluginOptions {
     /**
      * Register HTTP handlers automatically (optional)
      *
-     * If true, registers installation and webhook handlers.
+     * If true, registers the webhook handler.
      * Set to false if you want to implement custom handlers.
+     * Note: Installation callback handler must be implemented by the host app.
      *
      * @default true
      */

package/dist/handlers/InstallationCallback.d.ts

@@ -11,13 +11,7 @@
  * Route: GET /github-app/callback?installation_id=...&setup_action=...&state=...
  */
 import { RouteProps } from "@flink-app/flink";
-/**
- * Context with GitHub App Plugin
- *
- * Note: Using 'any' for simplicity. In a real-world scenario, you'd want to properly
- * type the context with both FlinkContext and GitHubAppPluginContext including the repos.
- */
-type InstallationCallbackContext = any;
+import { GitHubAppInternalContext } from "../GitHubAppInternalContext";
 /**
  * Route configuration
  * Registered programmatically by the plugin if registerRoutes is enabled
@@ -30,12 +24,12 @@ export declare const Route: RouteProps;
  * details, calling the app's callback, and storing the installation.
  */
 declare const InstallationCallback: ({ ctx, req }: {
-    ctx: InstallationCallbackContext;
+    ctx: GitHubAppInternalContext;
     req: any;
 }) => Promise<import("@flink-app/flink").FlinkResponse<undefined> | {
     status: number;
     headers: {
-        Location: any;
+        Location: string;
     };
     data: {};
 }>;

package/dist/handlers/WebhookHandler.d.ts

@@ -10,15 +10,8 @@
  *
  * Route: POST /github-app/webhook
  */
-import { FlinkContext, RouteProps } from "@flink-app/flink";
-import { GitHubAppPluginContext } from "../GitHubAppPluginContext";
-/**
- * Context with GitHub App Plugin
- *
- * Note: Using 'any' for simplicity. In a real-world scenario, you'd want to properly
- * type the context with both FlinkContext and GitHubAppPluginContext including the repos.
- */
-type WebhookHandlerContext = FlinkContext<GitHubAppPluginContext>;
+import { RouteProps } from "@flink-app/flink";
+import { GitHubAppInternalContext } from "../GitHubAppInternalContext";
 /**
  * Route configuration
  * Registered programmatically by the plugin if registerRoutes is enabled
@@ -30,7 +23,7 @@ export declare const Route: RouteProps;
  * Validates webhook signatures and processes GitHub webhook events.
  */
 declare const WebhookHandler: ({ ctx, req }: {
-    ctx: WebhookHandlerContext;
+    ctx: GitHubAppInternalContext;
     req: any;
 }) => Promise<{
     status: number;