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

package/dist/index.d.ts

@@ -7,13 +7,14 @@
  * - Webhook handling with signature validation
  * - API client wrapper
  */
-export { githubAppPlugin } from './GitHubAppPlugin';
-export type { GitHubAppPluginOptions, InstallationSuccessParams, InstallationSuccessResponse, InstallationErrorParams, InstallationErrorResponse, WebhookEventParams } from './GitHubAppPluginOptions';
-export type { GitHubAppPluginContext } from './GitHubAppPluginContext';
-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 { GitHubAPIClient, type Repository, type Content, type Issue, type CreateIssueParams } from './services/GitHubAPIClient';
-export { GitHubAuthService } from './services/GitHubAuthService';
-export { GitHubAppErrorCodes } from './utils/error-utils';
+export { githubAppPlugin } from "./GitHubAppPlugin";
+export type { GitHubAppPluginOptions, WebhookEventParams, } from "./GitHubAppPluginOptions";
+export type { GitHubAppPluginContext } from "./GitHubAppPluginContext";
+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 { GitHubAPIClient, type Repository, type Content, type Issue, type CreateIssueParams } from "./services/GitHubAPIClient";
+export { GitHubAuthService } from "./services/GitHubAuthService";
+export { InstallationService, type CompleteInstallationResult } from "./services/InstallationService";
+export { GitHubAppErrorCodes } from "./utils/error-utils";

package/dist/index.js

@@ -9,7 +9,7 @@
  * - API client wrapper
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GitHubAppErrorCodes = exports.GitHubAuthService = exports.GitHubAPIClient = exports.githubAppPlugin = void 0;
+exports.GitHubAppErrorCodes = exports.InstallationService = exports.GitHubAuthService = exports.GitHubAPIClient = exports.githubAppPlugin = void 0;
 // Plugin factory
 var GitHubAppPlugin_1 = require("./GitHubAppPlugin");
 Object.defineProperty(exports, "githubAppPlugin", { enumerable: true, get: function () { return GitHubAppPlugin_1.githubAppPlugin; } });
@@ -18,6 +18,8 @@ var GitHubAPIClient_1 = require("./services/GitHubAPIClient");
 Object.defineProperty(exports, "GitHubAPIClient", { enumerable: true, get: function () { return GitHubAPIClient_1.GitHubAPIClient; } });
 var GitHubAuthService_1 = require("./services/GitHubAuthService");
 Object.defineProperty(exports, "GitHubAuthService", { enumerable: true, get: function () { return GitHubAuthService_1.GitHubAuthService; } });
+var InstallationService_1 = require("./services/InstallationService");
+Object.defineProperty(exports, "InstallationService", { enumerable: true, get: function () { return InstallationService_1.InstallationService; } });
 // Error utilities
 var error_utils_1 = require("./utils/error-utils");
 Object.defineProperty(exports, "GitHubAppErrorCodes", { enumerable: true, get: function () { return error_utils_1.GitHubAppErrorCodes; } });

package/dist/services/InstallationService.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Installation Service
+ *
+ * Handles GitHub App installation completion flow including:
+ * - State validation (CSRF protection)
+ * - Fetching installation details from GitHub API
+ * - Storing installation in database
+ */
+import { GitHubAuthService } from "./GitHubAuthService";
+import GitHubAppSessionRepo from "../repos/GitHubAppSessionRepo";
+import GitHubInstallationRepo from "../repos/GitHubInstallationRepo";
+import GitHubInstallation from "../schemas/GitHubInstallation";
+/**
+ * Result of completing installation
+ */
+export interface CompleteInstallationResult {
+    success: boolean;
+    installation?: GitHubInstallation;
+    error?: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+}
+/**
+ * Installation Service
+ *
+ * Provides methods for completing GitHub App installation flow.
+ * Host applications call these methods from their own handlers with
+ * their own authentication and authorization logic.
+ */
+export declare class InstallationService {
+    private authService;
+    private sessionRepo;
+    private installationRepo;
+    private baseUrl;
+    constructor(authService: GitHubAuthService, sessionRepo: GitHubAppSessionRepo, installationRepo: GitHubInstallationRepo, baseUrl?: string);
+    /**
+     * Complete GitHub App installation
+     *
+     * This method handles all the boilerplate of:
+     * 1. Validating the state parameter (CSRF protection)
+     * 2. Fetching installation details from GitHub API
+     * 3. Storing 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 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;
+     *
+     *   // 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>;
+    /**
+     * Fetch installation details from GitHub API
+     *
+     * @param installationId - GitHub installation ID
+     * @param jwt - GitHub App JWT
+     * @returns Installation details
+     * @private
+     */
+    private fetchInstallationDetails;
+    /**
+     * Fetch repositories accessible by installation
+     *
+     * @param installationId - GitHub installation ID
+     * @param jwt - GitHub App JWT
+     * @returns Array of repositories
+     * @private
+     */
+    private fetchInstallationRepositories;
+}

package/dist/services/InstallationService.js

@@ -0,0 +1,224 @@
+"use strict";
+/**
+ * Installation Service
+ *
+ * Handles GitHub App installation completion flow including:
+ * - State validation (CSRF protection)
+ * - Fetching installation details from GitHub API
+ * - Storing installation in database
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstallationService = void 0;
+const flink_1 = require("@flink-app/flink");
+const error_utils_1 = require("../utils/error-utils");
+const state_utils_1 = require("../utils/state-utils");
+/**
+ * Installation Service
+ *
+ * Provides methods for completing GitHub App installation flow.
+ * Host applications call these methods from their own handlers with
+ * their own authentication and authorization logic.
+ */
+class InstallationService {
+    constructor(authService, sessionRepo, installationRepo, baseUrl = "https://api.github.com") {
+        this.authService = authService;
+        this.sessionRepo = sessionRepo;
+        this.installationRepo = installationRepo;
+        this.baseUrl = baseUrl;
+    }
+    /**
+     * Complete GitHub App installation
+     *
+     * This method handles all the boilerplate of:
+     * 1. Validating the state parameter (CSRF protection)
+     * 2. Fetching installation details from GitHub API
+     * 3. Storing 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 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;
+     *
+     *   // 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');
+     * }
+     * ```
+     */
+    async completeInstallation(params) {
+        const { installationId, state, userId } = params;
+        try {
+            // 1. Find session by state
+            const session = await this.sessionRepo.getOne({ state });
+            if (!session) {
+                return {
+                    success: false,
+                    error: {
+                        code: error_utils_1.GitHubAppErrorCodes.SESSION_EXPIRED,
+                        message: "Installation session not found or expired. Please try again.",
+                        details: { state: state.substring(0, 10) + "..." },
+                    },
+                };
+            }
+            // 2. Validate state parameter (CSRF protection)
+            if (!(0, state_utils_1.validateState)(state, session.state)) {
+                return {
+                    success: false,
+                    error: {
+                        code: error_utils_1.GitHubAppErrorCodes.INVALID_STATE,
+                        message: "Invalid state parameter. Possible CSRF attack detected.",
+                        details: { providedState: state.substring(0, 10) + "..." },
+                    },
+                };
+            }
+            // 3. Delete session immediately after validation (one-time use)
+            await this.sessionRepo.deleteBySessionId(session.sessionId);
+            // 4. Generate GitHub App JWT
+            const jwt = this.authService.generateAppJWT();
+            // 5. Fetch installation details from GitHub API
+            const installationDetails = await this.fetchInstallationDetails(installationId, jwt);
+            // 6. Fetch repositories accessible by this installation
+            const repositories = await this.fetchInstallationRepositories(installationId, jwt);
+            // 7. Store installation in database
+            const installation = await this.installationRepo.create({
+                userId,
+                installationId,
+                accountId: installationDetails.account.id,
+                accountLogin: installationDetails.account.login,
+                accountType: installationDetails.account.type,
+                avatarUrl: installationDetails.account.avatar_url,
+                repositories: repositories.map((repo) => ({
+                    id: repo.id,
+                    name: repo.name,
+                    fullName: repo.full_name,
+                    private: repo.private,
+                })),
+                permissions: installationDetails.permissions || {},
+                events: installationDetails.events || [],
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            });
+            flink_1.log.info("GitHub App installation completed", {
+                userId,
+                installationId,
+                accountLogin: installationDetails.account.login,
+                repositoryCount: repositories.length,
+            });
+            return {
+                success: true,
+                installation,
+            };
+        }
+        catch (error) {
+            flink_1.log.error("GitHub App installation completion failed", {
+                userId,
+                installationId,
+                error: error.message,
+            });
+            return {
+                success: false,
+                error: {
+                    code: error.code || error_utils_1.GitHubAppErrorCodes.SERVER_ERROR,
+                    message: error.message || "Installation completion failed. Please try again.",
+                    details: error.details,
+                },
+            };
+        }
+    }
+    /**
+     * Fetch installation details from GitHub API
+     *
+     * @param installationId - GitHub installation ID
+     * @param jwt - GitHub App JWT
+     * @returns Installation details
+     * @private
+     */
+    async fetchInstallationDetails(installationId, jwt) {
+        const url = `${this.baseUrl}/app/installations/${installationId}`;
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${jwt}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "Flink-GitHub-App-Plugin",
+            },
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            throw (0, error_utils_1.createGitHubAppError)(error_utils_1.GitHubAppErrorCodes.SERVER_ERROR, `Failed to fetch installation details: ${response.statusText}`, { status: response.status, body: errorBody });
+        }
+        return (await response.json());
+    }
+    /**
+     * Fetch repositories accessible by installation
+     *
+     * @param installationId - GitHub installation ID
+     * @param jwt - GitHub App JWT
+     * @returns Array of repositories
+     * @private
+     */
+    async fetchInstallationRepositories(installationId, jwt) {
+        const url = `${this.baseUrl}/installation/repositories`;
+        // First get an installation token
+        const tokenUrl = `${this.baseUrl}/app/installations/${installationId}/access_tokens`;
+        const tokenResponse = await fetch(tokenUrl, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${jwt}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "Flink-GitHub-App-Plugin",
+            },
+        });
+        if (!tokenResponse.ok) {
+            const errorBody = await tokenResponse.text();
+            throw (0, error_utils_1.createGitHubAppError)(error_utils_1.GitHubAppErrorCodes.TOKEN_EXCHANGE_FAILED, `Failed to get installation token: ${tokenResponse.statusText}`, { status: tokenResponse.status, body: errorBody });
+        }
+        const tokenData = await tokenResponse.json();
+        const token = tokenData.token;
+        // Now fetch repositories with the installation token
+        const reposResponse = await fetch(url, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.github+json",
+                "User-Agent": "Flink-GitHub-App-Plugin",
+            },
+        });
+        if (!reposResponse.ok) {
+            const errorBody = await reposResponse.text();
+            throw (0, error_utils_1.createGitHubAppError)(error_utils_1.GitHubAppErrorCodes.SERVER_ERROR, `Failed to fetch repositories: ${reposResponse.statusText}`, { status: reposResponse.status, body: errorBody });
+        }
+        const data = await reposResponse.json();
+        return data.repositories || [];
+    }
+}
+exports.InstallationService = InstallationService;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@flink-app/github-app-plugin",
-    "version": "0.12.1-alpha.38",
+    "version": "0.12.1-alpha.40",
     "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",
@@ -23,8 +23,8 @@
         "jsonwebtoken": "^9.0.2"
     },
     "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.35",
-        "@flink-app/test-utils": "^0.12.1-alpha.38",
+        "@flink-app/flink": "^0.12.1-alpha.40",
+        "@flink-app/test-utils": "^0.12.1-alpha.40",
         "@types/jasmine": "^3.7.1",
         "@types/jsonwebtoken": "^9.0.5",
         "@types/node": "22.13.10",
@@ -37,5 +37,5 @@
         "tsc-watch": "^4.2.9",
         "typescript": "5.4.5"
     },
-    "gitHead": "bba579788683fe0729399a56152eba4974f29bb6"
+    "gitHead": "456502f273fe9473df05b71a803f3eda1a2f8931"
 }

package/spec/handlers.spec.ts

@@ -1,142 +1,13 @@
 /**
  * Handler Tests for GitHub App Plugin
  *
- * Tests for installation callback and webhook handlers.
+ * Tests for webhook handler.
  * Focused tests covering critical paths only.
  */
 
-import InstallationCallback from "../src/handlers/InstallationCallback";
 import WebhookHandler from "../src/handlers/WebhookHandler";
-import { generateSessionId, generateState } from "../src/utils/state-utils";
 
 describe("GitHub App Handlers", () => {
-    describe("InstallationCallback", () => {
-        it("should validate state and store installation", async () => {
-            const state = generateState();
-            const mockSession = {
-                sessionId: generateSessionId(),
-                state,
-                userId: "user123",
-                createdAt: new Date(),
-            };
-
-            const mockInstallation = {
-                id: 12345,
-                account: {
-                    id: 67890,
-                    login: "testuser",
-                    type: "User" as const,
-                    avatar_url: "https://example.com/avatar.png",
-                },
-                repository_selection: "selected",
-                permissions: {
-                    contents: "read",
-                    issues: "write",
-                },
-                events: ["push", "pull_request"],
-            };
-
-            const mockRepositories = [
-                {
-                    id: 1,
-                    name: "repo1",
-                    full_name: "testuser/repo1",
-                    private: false,
-                },
-            ];
-
-            const mockCtx: any = {
-                repos: {
-                    githubAppSessionRepo: {
-                        getOne: jasmine.createSpy("getOne").and.returnValue(Promise.resolve(mockSession)),
-                        deleteBySessionId: jasmine.createSpy("deleteBySessionId").and.returnValue(Promise.resolve(1)),
-                    },
-                    githubInstallationRepo: {
-                        create: jasmine.createSpy("create").and.returnValue(Promise.resolve({})),
-                    },
-                },
-                plugins: {
-                    githubApp: {
-                        authService: {
-                            generateAppJWT: jasmine.createSpy("generateAppJWT").and.returnValue("mock-jwt"),
-                        },
-                        options: {
-                            baseUrl: "https://api.github.com",
-                            onInstallationSuccess: jasmine.createSpy("onInstallationSuccess").and.returnValue(
-                                Promise.resolve({
-                                    userId: "user123",
-                                    redirectUrl: "/dashboard",
-                                })
-                            ),
-                        },
-                    },
-                },
-            };
-
-            // Mock fetch for installation details and repositories
-            global.fetch = jasmine.createSpy("fetch").and.returnValues(
-                // First call: get installation details
-                Promise.resolve({
-                    ok: true,
-                    json: () => Promise.resolve(mockInstallation),
-                } as any),
-                // Second call: get installation token
-                Promise.resolve({
-                    ok: true,
-                    json: () => Promise.resolve({ token: "mock-token" }),
-                } as any),
-                // Third call: get repositories
-                Promise.resolve({
-                    ok: true,
-                    json: () => Promise.resolve({ repositories: mockRepositories }),
-                } as any)
-            );
-
-            const mockReq: any = {
-                query: {
-                    installation_id: "12345",
-                    setup_action: "install",
-                    state,
-                },
-            };
-
-            const result = await InstallationCallback({ ctx: mockCtx, req: mockReq } as any);
-
-            expect(result.status).toBe(302);
-            expect(mockCtx.repos.githubAppSessionRepo.getOne).toHaveBeenCalledWith({ state });
-            expect(mockCtx.repos.githubAppSessionRepo.deleteBySessionId).toHaveBeenCalledWith(mockSession.sessionId);
-            expect(mockCtx.plugins.githubApp.options.onInstallationSuccess).toHaveBeenCalled();
-            expect(mockCtx.repos.githubInstallationRepo.create).toHaveBeenCalled();
-        });
-
-        it("should reject invalid state", async () => {
-            const mockCtx: any = {
-                repos: {
-                    githubAppSessionRepo: {
-                        getOne: jasmine.createSpy("getOne").and.returnValue(Promise.resolve(null)),
-                    },
-                },
-                plugins: {
-                    githubApp: {
-                        options: {},
-                    },
-                },
-            };
-
-            const mockReq: any = {
-                query: {
-                    installation_id: "12345",
-                    setup_action: "install",
-                    state: "invalid-state",
-                },
-            };
-
-            const result = await InstallationCallback({ ctx: mockCtx, req: mockReq } as any);
-
-            expect(result.status).toBe(400);
-        });
-    });
-
     describe("WebhookHandler", () => {
         it("should validate signature and call webhook callback", async () => {
             const secret = "test-secret";