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

package/spec/integration-and-security.spec.ts

@@ -53,12 +53,6 @@ describe("Integration and Security Tests", () => {
             webhookSecret: "test-webhook-secret",
             clientId: "test-client-id",
             clientSecret: "test-client-secret",
-            onInstallationSuccess: async ({ installationId, repositories, account }) => {
-                return {
-                    userId: "test-user-id",
-                    redirectUrl: "/dashboard",
-                };
-            },
             onWebhookEvent: async ({ event, action, payload, installationId }, ctx) => {
                 // Webhook event handler
             },
@@ -88,8 +82,8 @@ describe("Integration and Security Tests", () => {
     });
 
     describe("Integration Test: Full Installation Flow", () => {
-        it("should complete full installation flow using context methods", async () => {
-            // Step 1: Initiate installation using context method
+        it("should initiate installation and generate state", async () => {
+            // Test initiation only (callback must be implemented by host app)
             const { redirectUrl, state } = await app.ctx.plugins.githubApp.initiateInstallation({
                 userId: "test-user",
                 metadata: { source: "test" },
@@ -98,6 +92,14 @@ describe("Integration and Security Tests", () => {
             expect(redirectUrl).toContain("github.com/apps/test-app/installations/new");
             expect(redirectUrl).toContain("state=");
             expect(state).toBeTruthy();
+        });
+
+        it("should complete installation using completeInstallation method", async () => {
+            // Step 1: Initiate installation
+            const { state } = await app.ctx.plugins.githubApp.initiateInstallation({
+                userId: "test-user",
+                metadata: { source: "test" },
+            });
 
             // Step 2: Mock GitHub API responses
             global.fetch = jasmine.createSpy("fetch").and.returnValues(
@@ -140,17 +142,17 @@ describe("Integration and Security Tests", () => {
                 } as any)
             );
 
-            // Step 3: Complete callback
-            const callbackResponse = await http.get("/github-app/callback", {
-                qs: {
-                    installation_id: "12345",
-                    setup_action: "install",
-                    state: state!,
-                },
+            // Step 3: Complete installation using plugin method
+            const result = await app.ctx.plugins.githubApp.completeInstallation({
+                installationId: 12345,
+                state: state!,
+                userId: "test-user-id",
             });
 
-            expect(callbackResponse.status).toBe(302);
-            expect(callbackResponse.headers?.Location).toBe("/dashboard");
+            expect(result.success).toBe(true);
+            expect(result.installation).toBeDefined();
+            expect(result.installation?.installationId).toBe(12345);
+            expect(result.installation?.accountLogin).toBe("testuser");
 
             // Step 4: Verify installation was stored
             const installation = await app.ctx.plugins.githubApp.getInstallation("test-user-id");
@@ -161,20 +163,19 @@ describe("Integration and Security Tests", () => {
     });
 
     describe("Security Test: CSRF State Validation", () => {
-        it("should prevent replay attacks with invalid state", async () => {
+        it("should prevent replay attacks with invalid state via completeInstallation", async () => {
             const invalidState = generateState();
 
             global.fetch = jasmine.createSpy("fetch");
 
-            const response = await http.get("/github-app/callback", {
-                qs: {
-                    installation_id: "12345",
-                    setup_action: "install",
-                    state: invalidState,
-                },
+            const result = await app.ctx.plugins.githubApp.completeInstallation({
+                installationId: 12345,
+                state: invalidState,
+                userId: "test-user",
             });
 
-            expect(response.status).toBe(400);
+            expect(result.success).toBe(false);
+            expect(result.error?.code).toBe("session-expired");
             expect(global.fetch).not.toHaveBeenCalled();
         });
 
@@ -211,27 +212,24 @@ describe("Integration and Security Tests", () => {
                 } as any)
             );
 
-            // Step 2: Complete callback first time (should succeed)
-            const firstCallback = await http.get("/github-app/callback", {
-                qs: {
-                    installation_id: "12345",
-                    setup_action: "install",
-                    state: state!,
-                },
+            // Step 2: Complete installation first time (should succeed)
+            const firstResult = await app.ctx.plugins.githubApp.completeInstallation({
+                installationId: 12345,
+                state: state!,
+                userId: "test-user-id",
             });
 
-            expect(firstCallback.status).toBe(302);
+            expect(firstResult.success).toBe(true);
 
             // Step 3: Try to reuse same state (should fail)
-            const secondCallback = await http.get("/github-app/callback", {
-                qs: {
-                    installation_id: "12345",
-                    setup_action: "install",
-                    state: state!,
-                },
+            const secondResult = await app.ctx.plugins.githubApp.completeInstallation({
+                installationId: 12345,
+                state: state!,
+                userId: "test-user-id",
             });
 
-            expect(secondCallback.status).toBe(400);
+            expect(secondResult.success).toBe(false);
+            expect(secondResult.error?.code).toBe("session-expired");
         });
     });
 
@@ -399,16 +397,16 @@ describe("Integration and Security Tests", () => {
                 } as any)
             );
 
-            const callbackResponse = await http.get("/github-app/callback", {
-                qs: {
-                    installation_id: "12345",
-                    setup_action: "install",
-                    state: state!,
-                },
+            const result = await app.ctx.plugins.githubApp.completeInstallation({
+                installationId: 12345,
+                state: state!,
+                userId: "test-user-id",
             });
 
             // Should handle error gracefully
-            expect(callbackResponse.status).toBe(500);
+            expect(result.success).toBe(false);
+            expect(result.error).toBeDefined();
+            expect(result.error?.code).toBe("server-error");
         });
 
         it("should handle network errors when getting installation token", async () => {

package/spec/plugin-core.spec.ts

@@ -60,7 +60,6 @@ describe("Plugin Core", () => {
                 webhookSecret: "test-secret",
                 clientId: "test-client-id",
                 clientSecret: "test-client-secret",
-                onInstallationSuccess: async () => ({ userId: "test", redirectUrl: "/" }),
             } as any;
 
             expect(() => githubAppPlugin(invalidOptions)).toThrowError(/appId is required/);
@@ -72,14 +71,13 @@ describe("Plugin Core", () => {
                 webhookSecret: "test-secret",
                 clientId: "test-client-id",
                 clientSecret: "test-client-secret",
-                onInstallationSuccess: async () => ({ userId: "test", redirectUrl: "/" }),
             } as any;
 
             expect(() => githubAppPlugin(invalidOptions)).toThrowError(/privateKey is required/);
         });
 
-        it("should throw error if onInstallationSuccess callback is missing", () => {
-            const invalidOptions = {
+        it("should not throw error when onInstallationSuccess is omitted", () => {
+            const validOptions = {
                 appId: "12345",
                 privateKey: testPrivateKeyBase64,
                 webhookSecret: "test-secret",
@@ -87,7 +85,7 @@ describe("Plugin Core", () => {
                 clientSecret: "test-client-secret",
             } as any;
 
-            expect(() => githubAppPlugin(invalidOptions)).toThrowError(/onInstallationSuccess callback is required/);
+            expect(() => githubAppPlugin(validOptions)).not.toThrow();
         });
     });
 
@@ -102,7 +100,6 @@ describe("Plugin Core", () => {
                 webhookSecret: "test-webhook-secret",
                 clientId: "test-client-id",
                 clientSecret: "test-client-secret",
-                onInstallationSuccess: async () => ({ userId: "test-user", redirectUrl: "/dashboard" }),
             };
         });
 
@@ -125,12 +122,12 @@ describe("Plugin Core", () => {
             expect(mockApp.addRepo).toHaveBeenCalledWith("githubInstallationRepo", jasmine.any(Object));
         });
 
-        it("should register only callback and webhook handlers when registerRoutes is true (default)", async () => {
+        it("should register only webhook handler when registerRoutes is true (default)", async () => {
             const plugin = githubAppPlugin(validOptions);
             await plugin.init!(mockApp, mockDb);
 
-            // Verify only 2 handlers were registered (callback and webhook, NOT initiate and uninstall)
-            expect(mockApp.addHandler).toHaveBeenCalledTimes(2);
+            // Verify only 1 handler was registered (webhook only, NOT callback)
+            expect(mockApp.addHandler).toHaveBeenCalledTimes(1);
         });
 
         it("should NOT register handlers when registerRoutes is false", async () => {
@@ -187,7 +184,6 @@ describe("Plugin Core", () => {
                 webhookSecret: "test-webhook-secret",
                 clientId: "test-client-id",
                 clientSecret: "test-client-secret",
-                onInstallationSuccess: async () => ({ userId: "test-user", redirectUrl: "/dashboard" }),
             };
 
             plugin = githubAppPlugin(validOptions);

package/spec/project-setup.spec.ts

@@ -20,7 +20,6 @@ describe('GitHub App Plugin - Project Setup', () => {
         webhookSecret: 'test',
         clientId: 'test',
         clientSecret: 'test',
-        onInstallationSuccess: async () => ({ userId: 'test', redirectUrl: '/' }),
       };
       expect(options).toBeDefined();
     });
@@ -43,7 +42,6 @@ describe('GitHub App Plugin - Project Setup', () => {
         webhookSecret: 'test-webhook-secret',
         clientId: 'test-client-id',
         clientSecret: 'test-client-secret',
-        onInstallationSuccess: async () => ({ userId: 'test', redirectUrl: '/' }),
       });
 
       expect(plugin).toBeDefined();

package/src/GitHubAppInternalContext.ts

@@ -0,0 +1,16 @@
+import { FlinkContext } from "@flink-app/flink";
+import { GitHubAppPluginContext } from "./GitHubAppPluginContext";
+import GitHubAppSessionRepo from "./repos/GitHubAppSessionRepo";
+import GitHubInstallationRepo from "./repos/GitHubInstallationRepo";
+import GitHubWebhookEventRepo from "./repos/GitHubWebhookEventRepo";
+
+/**
+ * Internal context used for plugin handlers.
+ */
+export interface GitHubAppInternalContext extends FlinkContext<GitHubAppPluginContext> {
+    repos: {
+        githubAppSessionRepo: GitHubAppSessionRepo;
+        githubInstallationRepo: GitHubInstallationRepo;
+        githubWebhookEventRepo?: GitHubWebhookEventRepo;
+    };
+}

package/src/GitHubAppPlugin.ts

@@ -8,10 +8,10 @@ import GitHubWebhookEventRepo from "./repos/GitHubWebhookEventRepo";
 import { GitHubAuthService } from "./services/GitHubAuthService";
 import { GitHubAPIClient } from "./services/GitHubAPIClient";
 import { WebhookValidator } from "./services/WebhookValidator";
+import { InstallationService } from "./services/InstallationService";
 import GitHubInstallation from "./schemas/GitHubInstallation";
 import { createGitHubAppError, GitHubAppErrorCodes } from "./utils/error-utils";
 import { generateState, generateSessionId } from "./utils/state-utils";
-import * as InstallationCallback from "./handlers/InstallationCallback";
 import * as WebhookHandler from "./handlers/WebhookHandler";
 
 /**
@@ -73,9 +73,6 @@ export function githubAppPlugin(options: GitHubAppPluginOptions): FlinkPlugin {
     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";
@@ -87,6 +84,7 @@ export function githubAppPlugin(options: GitHubAppPluginOptions): FlinkPlugin {
     let flinkApp: FlinkApp<any>;
     let authService: GitHubAuthService;
     let webhookValidator: WebhookValidator;
+    let installationService: InstallationService;
     let sessionRepo: GitHubAppSessionRepo;
     let installationRepo: GitHubInstallationRepo;
     let webhookEventRepo: GitHubWebhookEventRepo | undefined;
@@ -129,6 +127,9 @@ export function githubAppPlugin(options: GitHubAppPluginOptions): FlinkPlugin {
             flinkApp.addRepo("githubAppSessionRepo", sessionRepo);
             flinkApp.addRepo("githubInstallationRepo", installationRepo);
 
+            // Initialize InstallationService
+            installationService = new InstallationService(authService, sessionRepo, installationRepo, baseUrl);
+
             // Conditionally initialize webhook event repo if logging is enabled
             if (logWebhookEvents) {
                 webhookEventRepo = new GitHubWebhookEventRepo(flinkApp.ctx, db, webhookEventsCollectionName);
@@ -149,11 +150,10 @@ export function githubAppPlugin(options: GitHubAppPluginOptions): FlinkPlugin {
                 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);
-                log.info("GitHub App Plugin: Registered handlers (callback and webhook)");
+                log.info("GitHub App Plugin: Registered webhook handler");
             } else {
                 log.info("GitHub App Plugin: Skipped handler registration (routes disabled)");
             }
@@ -217,6 +217,21 @@ export function githubAppPlugin(options: GitHubAppPluginOptions): FlinkPlugin {
         };
     }
 
+    /**
+     * Complete GitHub App installation
+     */
+    async function completeInstallation(params: {
+        installationId: number;
+        state: string;
+        userId: string;
+    }) {
+        if (!installationService) {
+            throw new Error("GitHub App Plugin: Plugin not initialized");
+        }
+
+        return installationService.completeInstallation(params);
+    }
+
     /**
      * Uninstalls GitHub App for a user
      */
@@ -387,6 +402,7 @@ export function githubAppPlugin(options: GitHubAppPluginOptions): FlinkPlugin {
      */
     const pluginCtx: GitHubAppPluginContext["githubApp"] = {
         initiateInstallation,
+        completeInstallation,
         uninstall,
         getClient,
         getInstallation,

package/src/GitHubAppPluginContext.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
@@ -52,6 +53,63 @@ export interface GitHubAppPluginContext {
             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/src/GitHubAppPluginOptions.ts

@@ -8,6 +8,9 @@ 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 */
@@ -149,8 +152,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
@@ -161,12 +167,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) => {
@@ -263,52 +264,6 @@ export interface GitHubAppPluginOptions {
 
     // Callbacks
 
-    /**
-     * 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)
      *
@@ -393,8 +348,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/src/handlers/WebhookHandler.ts

@@ -11,16 +11,8 @@
  * Route: POST /github-app/webhook
  */
 
-import { FlinkContext, HttpMethod, RouteProps, log } 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 { HttpMethod, RouteProps, log } from "@flink-app/flink";
+import { GitHubAppInternalContext } from "../GitHubAppInternalContext";
 
 /**
  * Route configuration
@@ -36,7 +28,7 @@ export const Route: RouteProps = {
  *
  * Validates webhook signatures and processes GitHub webhook events.
  */
-const WebhookHandler = async ({ ctx, req }: { ctx: WebhookHandlerContext; req: any }) => {
+const WebhookHandler = async ({ ctx, req }: { ctx: GitHubAppInternalContext; req: any }) => {
     try {
         // Extract headers
         const signature = req.headers["x-hub-signature-256"] as string;

package/src/index.ts

@@ -9,21 +9,25 @@
  */
 
 // Plugin factory
-export { githubAppPlugin } from './GitHubAppPlugin';
+export { githubAppPlugin } from "./GitHubAppPlugin";
 
 // Type exports
-export type { GitHubAppPluginOptions, InstallationSuccessParams, InstallationSuccessResponse, InstallationErrorParams, InstallationErrorResponse, WebhookEventParams } from './GitHubAppPluginOptions';
-export type { GitHubAppPluginContext } from './GitHubAppPluginContext';
+export type {
+    GitHubAppPluginOptions,
+    WebhookEventParams,
+} from "./GitHubAppPluginOptions";
+export type { GitHubAppPluginContext } from "./GitHubAppPluginContext";
 
 // Schema exports
-export type { default as GitHubInstallation } from './schemas/GitHubInstallation';
-export type { default as GitHubAppSession } from './schemas/GitHubAppSession';
-export type { default as WebhookEvent } from './schemas/WebhookEvent';
-export type { default as WebhookPayload } from './schemas/WebhookPayload';
+export type { default as GitHubInstallation } from "./schemas/GitHubInstallation";
+export type { default as GitHubAppSession } from "./schemas/GitHubAppSession";
+export type { default as WebhookEvent } from "./schemas/WebhookEvent";
+export type { default as WebhookPayload } from "./schemas/WebhookPayload";
 
 // Service exports (for advanced usage)
-export { GitHubAPIClient, type Repository, type Content, type Issue, type CreateIssueParams } from './services/GitHubAPIClient';
-export { GitHubAuthService } from './services/GitHubAuthService';
+export { GitHubAPIClient, type Repository, type Content, type Issue, type CreateIssueParams } from "./services/GitHubAPIClient";
+export { GitHubAuthService } from "./services/GitHubAuthService";
+export { InstallationService, type CompleteInstallationResult } from "./services/InstallationService";
 
 // Error utilities
-export { GitHubAppErrorCodes } from './utils/error-utils';
+export { GitHubAppErrorCodes } from "./utils/error-utils";