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

package/dist/GitHubAppPluginOptions.d.ts

@@ -0,0 +1,369 @@
+/**
+ * Installation success callback parameters
+ *
+ * Provided to the onInstallationSuccess callback when a user successfully
+ * installs the GitHub App and grants access to repositories.
+ */
+export interface InstallationSuccessParams {
+    /** GitHub installation ID */
+    installationId: number;
+    /** GitHub account (user or organization) where app was installed */
+    account: {
+        /** Account ID on GitHub */
+        id: number;
+        /** Account username or organization name */
+        login: string;
+        /** Account type */
+        type: "User" | "Organization";
+        /** Profile picture URL */
+        avatarUrl?: string;
+    };
+    /** Repositories the user granted access to */
+    repositories: {
+        /** Repository ID on GitHub */
+        id: number;
+        /** Repository name (without owner) */
+        name: string;
+        /** Full repository name (owner/repo) */
+        fullName: string;
+        /** Whether repository is private */
+        private: boolean;
+    }[];
+    /** Permissions granted to the app (e.g., { contents: 'read', issues: 'write' }) */
+    permissions: Record<string, string>;
+    /** Webhook events the app is subscribed to */
+    events: string[];
+}
+/**
+ * Installation success callback response
+ *
+ * Return this from onInstallationSuccess to link the installation
+ * to a user in your application and redirect the user.
+ */
+export interface InstallationSuccessResponse {
+    /**
+     * User ID in your application to link this installation to
+     *
+     * The plugin stores this mapping to enable repository access checks.
+     * Get this from your authentication system (session, JWT, etc.)
+     */
+    userId: string;
+    /**
+     * Optional URL to redirect user after installation
+     *
+     * If not provided, a default success page will be shown.
+     * Use this to redirect users to your dashboard or specific page.
+     *
+     * @example "/dashboard/github"
+     * @example "/repos?installation=success"
+     */
+    redirectUrl?: string;
+}
+/**
+ * Installation error callback parameters
+ *
+ * Provided to the onInstallationError callback when installation fails.
+ */
+export interface InstallationErrorParams {
+    /** Error information */
+    error: {
+        /** Error code in kebab-case (e.g., 'invalid-state', 'session-expired') */
+        code: string;
+        /** User-friendly error message */
+        message: string;
+        /** Additional error details for debugging */
+        details?: any;
+    };
+    /** Installation ID if available (may be undefined if error occurred before installation) */
+    installationId?: number;
+}
+/**
+ * Installation error callback response
+ *
+ * Return this from onInstallationError to redirect the user
+ * to an error page or retry flow.
+ */
+export interface InstallationErrorResponse {
+    /**
+     * Optional URL to redirect user after error
+     *
+     * Use this to show error messages or allow retry.
+     *
+     * @example "/error?message=installation-failed"
+     * @example "/github/install?retry=true"
+     */
+    redirectUrl?: string;
+}
+/**
+ * Webhook event callback parameters
+ *
+ * Provided to the onWebhookEvent callback when a webhook event is received
+ * from GitHub. The plugin validates the webhook signature before calling this.
+ */
+export interface WebhookEventParams {
+    /**
+     * GitHub event type
+     *
+     * Common events: 'push', 'pull_request', 'issues', 'installation',
+     * 'pull_request_review', 'issue_comment', 'release', etc.
+     */
+    event: string;
+    /**
+     * Event action (if applicable)
+     *
+     * Examples: 'opened', 'closed', 'reopened', 'created', 'deleted', etc.
+     * Not all events have actions.
+     */
+    action?: string;
+    /**
+     * Full webhook payload from GitHub
+     *
+     * Structure varies by event type. See GitHub webhook documentation
+     * for payload schemas.
+     */
+    payload: Record<string, any>;
+    /** Installation ID that triggered the webhook */
+    installationId: number;
+    /**
+     * Unique delivery ID from GitHub (X-GitHub-Delivery header)
+     *
+     * Use this for debugging and tracking webhook deliveries.
+     */
+    deliveryId: string;
+}
+/**
+ * Configuration options for GitHub App Plugin
+ *
+ * Configure the plugin with your GitHub App credentials, callbacks,
+ * and optional settings for database, caching, and features.
+ *
+ * @example
+ * ```typescript
+ * githubAppPlugin({
+ *   // Required: GitHub App credentials
+ *   appId: process.env.GITHUB_APP_ID!,
+ *   privateKey: process.env.GITHUB_APP_PRIVATE_KEY_BASE64!, // Base64 encoded
+ *   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' };
+ *   },
+ *
+ *   // Optional: Handle webhook events
+ *   onWebhookEvent: async ({ event, payload }, ctx) => {
+ *     if (event === 'push') {
+ *       console.log('Push event received');
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export interface GitHubAppPluginOptions {
+    /**
+     * GitHub App ID
+     *
+     * Found in your GitHub App settings page.
+     *
+     * @example "123456"
+     */
+    appId: string;
+    /**
+     * GitHub App private key (Base64 encoded PEM format)
+     *
+     * Download the private key from GitHub App settings, then base64 encode it.
+     * This format plays nicely with environment variables (no line break issues).
+     * Supports both PKCS#1 and PKCS#8 formats (auto-detected after decoding).
+     *
+     * To encode your private key:
+     * ```bash
+     * # On macOS/Linux:
+     * base64 -i private-key.pem | tr -d '\n'
+     *
+     * # On Windows (PowerShell):
+     * [Convert]::ToBase64String([IO.File]::ReadAllBytes("private-key.pem"))
+     * ```
+     *
+     * @example "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFcEFJQkFBS0..."
+     */
+    privateKey: string;
+    /**
+     * Webhook secret for signature validation
+     *
+     * Set in GitHub App settings. Used to validate webhook signatures
+     * using HMAC-SHA256. Generate a strong random string.
+     *
+     * @example "your-webhook-secret-here"
+     */
+    webhookSecret: string;
+    /**
+     * GitHub App client ID
+     *
+     * Found in your GitHub App settings page.
+     *
+     * @example "Iv1.abc123def456"
+     */
+    clientId: string;
+    /**
+     * GitHub App client secret
+     *
+     * Generate in GitHub App settings. Store in environment variables.
+     *
+     * @example "your-client-secret-here"
+     */
+    clientSecret: string;
+    /**
+     * GitHub App slug (optional)
+     *
+     * Used in installation URL. Auto-detected if not provided.
+     * Found in your GitHub App settings page.
+     *
+     * @default Auto-detected from GitHub API
+     * @example "my-flink-app"
+     */
+    appSlug?: string;
+    /**
+     * GitHub API base URL (optional)
+     *
+     * Use for GitHub Enterprise Server installations.
+     * For github.com, use the default.
+     *
+     * @default "https://api.github.com"
+     * @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)
+     *
+     * Called for each webhook event after signature validation.
+     * Process events asynchronously. Don't throw errors to prevent
+     * GitHub from retrying.
+     *
+     * @param params - Webhook event data
+     * @param ctx - Flink context with repos and plugins
+     *
+     * @example
+     * ```typescript
+     * async ({ event, action, payload, installationId }, ctx) => {
+     *   if (event === 'push') {
+     *     console.log('Push to', payload.repository.full_name);
+     *   }
+     *   if (event === 'pull_request' && action === 'opened') {
+     *     const client = await ctx.plugins.githubApp.getClient(installationId);
+     *     await client.createIssue(...);
+     *   }
+     * }
+     * ```
+     */
+    onWebhookEvent?: (params: WebhookEventParams, ctx: any) => Promise<void>;
+    /**
+     * MongoDB collection name for sessions (optional)
+     *
+     * Used for CSRF protection during installation flow.
+     *
+     * @default "github_app_sessions"
+     */
+    sessionsCollectionName?: string;
+    /**
+     * MongoDB collection name for installations (optional)
+     *
+     * Stores installation-to-user mappings and repository access info.
+     *
+     * @default "github_installations"
+     */
+    installationsCollectionName?: string;
+    /**
+     * MongoDB collection name for webhook events (optional)
+     *
+     * Only used if logWebhookEvents is enabled.
+     *
+     * @default "github_webhook_events"
+     */
+    webhookEventsCollectionName?: string;
+    /**
+     * Installation token cache TTL in seconds (optional)
+     *
+     * How long to cache installation access tokens in memory.
+     * Tokens expire after 60 minutes. Set to 55 minutes (3300 seconds)
+     * for 5-minute safety margin.
+     *
+     * @default 3300 (55 minutes)
+     * @example 3000 (50 minutes)
+     */
+    tokenCacheTTL?: number;
+    /**
+     * Session TTL in seconds (optional)
+     *
+     * How long CSRF protection sessions are valid.
+     * Sessions are automatically deleted via MongoDB TTL index.
+     *
+     * @default 600 (10 minutes)
+     * @example 300 (5 minutes)
+     */
+    sessionTTL?: number;
+    /**
+     * Register HTTP handlers automatically (optional)
+     *
+     * If true, registers installation and webhook handlers.
+     * Set to false if you want to implement custom handlers.
+     *
+     * @default true
+     */
+    registerRoutes?: boolean;
+    /**
+     * Log webhook events to MongoDB (optional)
+     *
+     * If true, stores all webhook events in database for debugging.
+     * Useful for development but may consume storage in production.
+     *
+     * @default false
+     */
+    logWebhookEvents?: boolean;
+}

package/dist/GitHubAppPluginOptions.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/handlers/InitiateInstallation.d.ts

@@ -0,0 +1,32 @@
+/**
+ * GitHub App Installation Initiation Handler
+ *
+ * Initiates the GitHub App installation flow by:
+ * 1. Generating a cryptographically secure state parameter for CSRF protection
+ * 2. Creating an installation session to track the flow
+ * 3. Building GitHub's installation URL with state parameter
+ * 4. Redirecting the user to GitHub for app installation
+ *
+ * Route: GET /github-app/install?user_id={optional_user_id}
+ */
+import { GetHandler, RouteProps } from "@flink-app/flink";
+/**
+ * Query parameters for the handler
+ */
+interface QueryParams {
+    user_id?: string;
+    [key: string]: any;
+}
+/**
+ * Route configuration
+ * Registered programmatically by the plugin if registerRoutes is enabled
+ */
+export declare const Route: RouteProps;
+/**
+ * GitHub App Installation Initiation Handler
+ *
+ * Starts the installation flow by generating CSRF state, creating a session,
+ * and redirecting to GitHub's app installation page.
+ */
+declare const InitiateInstallation: GetHandler<any, any, any, QueryParams>;
+export default InitiateInstallation;

package/dist/handlers/InitiateInstallation.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * GitHub App Installation Initiation Handler
+ *
+ * Initiates the GitHub App installation flow by:
+ * 1. Generating a cryptographically secure state parameter for CSRF protection
+ * 2. Creating an installation session to track the flow
+ * 3. Building GitHub's installation URL with state parameter
+ * 4. Redirecting the user to GitHub for app installation
+ *
+ * Route: GET /github-app/install?user_id={optional_user_id}
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Route = void 0;
+const flink_1 = require("@flink-app/flink");
+const state_utils_1 = require("../utils/state-utils");
+/**
+ * Route configuration
+ * Registered programmatically by the plugin if registerRoutes is enabled
+ */
+exports.Route = {
+    path: "/github-app/install",
+    method: flink_1.HttpMethod.get,
+};
+/**
+ * GitHub App Installation Initiation Handler
+ *
+ * Starts the installation flow by generating CSRF state, creating a session,
+ * and redirecting to GitHub's app installation page.
+ */
+const InitiateInstallation = async ({ ctx, req }) => {
+    const { user_id } = req.query;
+    try {
+        // Get plugin options
+        const { options } = ctx.plugins.githubApp;
+        // Validate that appSlug is configured
+        if (!options.appSlug) {
+            return (0, flink_1.badRequest)("GitHub App slug is not configured. Please set appSlug in plugin options.");
+        }
+        // Generate cryptographically secure state and session ID
+        const state = (0, state_utils_1.generateState)();
+        const sessionId = (0, state_utils_1.generateSessionId)();
+        // Store session for state validation in callback
+        await ctx.repos.githubAppSessionRepo.create({
+            sessionId,
+            state,
+            userId: user_id,
+            createdAt: new Date(),
+        });
+        // Build GitHub installation URL
+        const installationUrl = `https://github.com/apps/${options.appSlug}/installations/new?state=${state}`;
+        // Redirect user to GitHub's app installation page
+        return {
+            status: 302,
+            headers: {
+                Location: installationUrl,
+            },
+            data: {},
+        };
+    }
+    catch (error) {
+        // Handle unexpected errors
+        return (0, flink_1.internalServerError)(error.message || "Failed to initiate GitHub App installation");
+    }
+};
+exports.default = InitiateInstallation;

package/dist/handlers/InstallationCallback.d.ts

@@ -0,0 +1,42 @@
+/**
+ * GitHub App Installation Callback Handler
+ *
+ * Handles the callback from GitHub after app installation by:
+ * 1. Validating the state parameter to prevent CSRF attacks
+ * 2. Fetching installation details from GitHub API
+ * 3. Calling the onInstallationSuccess callback to link installation to user
+ * 4. Storing the installation in the database
+ * 5. Redirecting to the application
+ *
+ * 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;
+/**
+ * Route configuration
+ * Registered programmatically by the plugin if registerRoutes is enabled
+ */
+export declare const Route: RouteProps;
+/**
+ * GitHub App Installation Callback Handler
+ *
+ * Completes the installation flow by validating state, fetching installation
+ * details, calling the app's callback, and storing the installation.
+ */
+declare const InstallationCallback: ({ ctx, req }: {
+    ctx: InstallationCallbackContext;
+    req: any;
+}) => Promise<import("@flink-app/flink").FlinkResponse<undefined> | {
+    status: number;
+    headers: {
+        Location: any;
+    };
+    data: {};
+}>;
+export default InstallationCallback;