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

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * GitHub App Plugin for Flink Framework
+ *
+ * Provides GitHub App integration with:
+ * - Installation management
+ * - JWT-based authentication
+ * - Webhook handling with signature validation
+ * - API client wrapper
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubAppErrorCodes = 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; } });
+// Service exports (for advanced usage)
+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; } });
+// 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/repos/GitHubAppSessionRepo.d.ts

@@ -0,0 +1,24 @@
+import { FlinkRepo } from "@flink-app/flink";
+import { Db } from "mongodb";
+import GitHubAppSession from "../schemas/GitHubAppSession";
+/**
+ * Repository for managing temporary GitHub App installation sessions with TTL.
+ * Sessions are used during the installation flow to prevent CSRF attacks.
+ */
+declare class GitHubAppSessionRepo extends FlinkRepo<any, GitHubAppSession> {
+    constructor(ctx: any, db: Db, collectionName?: string);
+    /**
+     * Find a GitHub App session by its unique session ID.
+     * @param sessionId - The unique session identifier
+     * @returns The session if found, null otherwise
+     */
+    findBySessionId(sessionId: string): Promise<GitHubAppSession | null>;
+    /**
+     * Delete a GitHub App session by its unique session ID.
+     * Used after the installation callback is processed to prevent session reuse.
+     * @param sessionId - The unique session identifier
+     * @returns The number of deleted sessions (0 or 1)
+     */
+    deleteBySessionId(sessionId: string): Promise<number>;
+}
+export default GitHubAppSessionRepo;

package/dist/repos/GitHubAppSessionRepo.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const flink_1 = require("@flink-app/flink");
+/**
+ * Repository for managing temporary GitHub App installation sessions with TTL.
+ * Sessions are used during the installation flow to prevent CSRF attacks.
+ */
+class GitHubAppSessionRepo extends flink_1.FlinkRepo {
+    constructor(ctx, db, collectionName = "github_app_sessions") {
+        super(collectionName, db);
+        this.ctx = ctx;
+    }
+    /**
+     * Find a GitHub App session by its unique session ID.
+     * @param sessionId - The unique session identifier
+     * @returns The session if found, null otherwise
+     */
+    async findBySessionId(sessionId) {
+        return this.getOne({ sessionId });
+    }
+    /**
+     * Delete a GitHub App session by its unique session ID.
+     * Used after the installation callback is processed to prevent session reuse.
+     * @param sessionId - The unique session identifier
+     * @returns The number of deleted sessions (0 or 1)
+     */
+    async deleteBySessionId(sessionId) {
+        const { deletedCount } = await this.collection.deleteOne({ sessionId });
+        return deletedCount || 0;
+    }
+}
+exports.default = GitHubAppSessionRepo;

package/dist/repos/GitHubInstallationRepo.d.ts

@@ -0,0 +1,53 @@
+import { FlinkRepo } from "@flink-app/flink";
+import { Db } from "mongodb";
+import GitHubInstallation from "../schemas/GitHubInstallation";
+/**
+ * Repository for managing GitHub App installations.
+ * Stores installation-to-user mappings and repository access information.
+ */
+declare class GitHubInstallationRepo extends FlinkRepo<any, GitHubInstallation> {
+    constructor(ctx: any, db: Db, collectionName?: string);
+    /**
+     * Find an installation by user ID and installation ID.
+     * @param userId - The application user ID
+     * @param installationId - The GitHub installation ID
+     * @returns The installation if found, null otherwise
+     */
+    findByUserAndInstallationId(userId: string, installationId: number): Promise<GitHubInstallation | null>;
+    /**
+     * Find all installations for a specific user.
+     * @param userId - The application user ID
+     * @returns Array of installations for the user
+     */
+    findByUserId(userId: string): Promise<GitHubInstallation[]>;
+    /**
+     * Find an installation by its GitHub installation ID.
+     * @param installationId - The GitHub installation ID
+     * @returns The installation if found, null otherwise
+     */
+    findByInstallationId(installationId: number): Promise<GitHubInstallation | null>;
+    /**
+     * Update the repositories list for an installation.
+     * @param installationId - The GitHub installation ID
+     * @param repositories - The new repositories list
+     * @returns The updated installation
+     */
+    updateRepositories(installationId: number, repositories: GitHubInstallation["repositories"]): Promise<GitHubInstallation | null>;
+    /**
+     * Suspend an installation.
+     * @param installationId - The GitHub installation ID
+     * @param suspendedBy - Information about who suspended the installation
+     * @returns The updated installation
+     */
+    suspend(installationId: number, suspendedBy: {
+        id: number;
+        login: string;
+    }): Promise<GitHubInstallation | null>;
+    /**
+     * Delete an installation by its GitHub installation ID.
+     * @param installationId - The GitHub installation ID
+     * @returns The number of deleted installations (0 or 1)
+     */
+    deleteByInstallationId(installationId: number): Promise<number>;
+}
+export default GitHubInstallationRepo;

package/dist/repos/GitHubInstallationRepo.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const flink_1 = require("@flink-app/flink");
+/**
+ * Repository for managing GitHub App installations.
+ * Stores installation-to-user mappings and repository access information.
+ */
+class GitHubInstallationRepo extends flink_1.FlinkRepo {
+    constructor(ctx, db, collectionName = "github_installations") {
+        super(collectionName, db);
+        this.ctx = ctx;
+    }
+    /**
+     * Find an installation by user ID and installation ID.
+     * @param userId - The application user ID
+     * @param installationId - The GitHub installation ID
+     * @returns The installation if found, null otherwise
+     */
+    async findByUserAndInstallationId(userId, installationId) {
+        return this.getOne({ userId, installationId });
+    }
+    /**
+     * Find all installations for a specific user.
+     * @param userId - The application user ID
+     * @returns Array of installations for the user
+     */
+    async findByUserId(userId) {
+        return this.findAll({ userId });
+    }
+    /**
+     * Find an installation by its GitHub installation ID.
+     * @param installationId - The GitHub installation ID
+     * @returns The installation if found, null otherwise
+     */
+    async findByInstallationId(installationId) {
+        return this.getOne({ installationId });
+    }
+    /**
+     * Update the repositories list for an installation.
+     * @param installationId - The GitHub installation ID
+     * @param repositories - The new repositories list
+     * @returns The updated installation
+     */
+    async updateRepositories(installationId, repositories) {
+        const installation = await this.getOne({ installationId });
+        if (!installation) {
+            return null;
+        }
+        const updated = await this.updateOne(installation._id, {
+            repositories,
+            updatedAt: new Date(),
+        });
+        return updated;
+    }
+    /**
+     * Suspend an installation.
+     * @param installationId - The GitHub installation ID
+     * @param suspendedBy - Information about who suspended the installation
+     * @returns The updated installation
+     */
+    async suspend(installationId, suspendedBy) {
+        const installation = await this.getOne({ installationId });
+        if (!installation) {
+            return null;
+        }
+        const updated = await this.updateOne(installation._id, {
+            suspendedAt: new Date(),
+            suspendedBy,
+            updatedAt: new Date(),
+        });
+        return updated;
+    }
+    /**
+     * Delete an installation by its GitHub installation ID.
+     * @param installationId - The GitHub installation ID
+     * @returns The number of deleted installations (0 or 1)
+     */
+    async deleteByInstallationId(installationId) {
+        const { deletedCount } = await this.collection.deleteOne({ installationId });
+        return deletedCount || 0;
+    }
+}
+exports.default = GitHubInstallationRepo;

package/dist/repos/GitHubWebhookEventRepo.d.ts

@@ -0,0 +1,29 @@
+import { FlinkRepo } from "@flink-app/flink";
+import { Db } from "mongodb";
+import WebhookEvent from "../schemas/WebhookEvent";
+/**
+ * Repository for managing GitHub webhook events.
+ * Only used if logWebhookEvents config option is enabled.
+ * Provides webhook event logging for debugging and auditing.
+ */
+declare class GitHubWebhookEventRepo extends FlinkRepo<any, WebhookEvent> {
+    constructor(ctx: any, db: Db, collectionName?: string);
+    /**
+     * Find all unprocessed webhook events.
+     * @returns Array of unprocessed events
+     */
+    findUnprocessed(): Promise<WebhookEvent[]>;
+    /**
+     * Mark a webhook event as processed.
+     * @param eventId - The webhook event ID
+     * @returns The updated event
+     */
+    markProcessed(eventId: string): Promise<WebhookEvent | null>;
+    /**
+     * Find all webhook events for a specific installation.
+     * @param installationId - The GitHub installation ID
+     * @returns Array of webhook events for the installation
+     */
+    findByInstallationId(installationId: number): Promise<WebhookEvent[]>;
+}
+export default GitHubWebhookEventRepo;

package/dist/repos/GitHubWebhookEventRepo.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const flink_1 = require("@flink-app/flink");
+/**
+ * Repository for managing GitHub webhook events.
+ * Only used if logWebhookEvents config option is enabled.
+ * Provides webhook event logging for debugging and auditing.
+ */
+class GitHubWebhookEventRepo extends flink_1.FlinkRepo {
+    constructor(ctx, db, collectionName = "github_webhook_events") {
+        super(collectionName, db);
+        this.ctx = ctx;
+    }
+    /**
+     * Find all unprocessed webhook events.
+     * @returns Array of unprocessed events
+     */
+    async findUnprocessed() {
+        return this.findAll({ processed: false });
+    }
+    /**
+     * Mark a webhook event as processed.
+     * @param eventId - The webhook event ID
+     * @returns The updated event
+     */
+    async markProcessed(eventId) {
+        const updated = await this.updateOne(eventId, {
+            processed: true,
+            processedAt: new Date(),
+        });
+        return updated;
+    }
+    /**
+     * Find all webhook events for a specific installation.
+     * @param installationId - The GitHub installation ID
+     * @returns Array of webhook events for the installation
+     */
+    async findByInstallationId(installationId) {
+        return this.findAll({ installationId });
+    }
+}
+exports.default = GitHubWebhookEventRepo;

package/dist/schemas/GitHubAppSession.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Temporary session storage for GitHub App installation flow.
+ * Used for CSRF protection via state parameter.
+ * Sessions automatically expire after TTL (default 10 minutes).
+ */
+export default interface GitHubAppSession {
+    _id?: string;
+    sessionId: string;
+    state: string;
+    userId?: string;
+    metadata?: Record<string, any>;
+    createdAt: Date;
+}

package/dist/schemas/GitHubAppSession.js

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

package/dist/schemas/GitHubInstallation.d.ts

@@ -0,0 +1,28 @@
+/**
+ * GitHub App installation data linked to a user.
+ * Stores which repositories the user granted access to and installation metadata.
+ */
+export default interface GitHubInstallation {
+    _id?: string;
+    userId: string;
+    installationId: number;
+    accountId: number;
+    accountLogin: string;
+    accountType: 'User' | 'Organization';
+    avatarUrl?: string;
+    repositories: {
+        id: number;
+        name: string;
+        fullName: string;
+        private: boolean;
+    }[];
+    permissions: Record<string, string>;
+    events: string[];
+    suspendedAt?: Date;
+    suspendedBy?: {
+        id: number;
+        login: string;
+    };
+    createdAt: Date;
+    updatedAt: Date;
+}

package/dist/schemas/GitHubInstallation.js

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

package/dist/schemas/InstallationCallbackRequest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Query parameters received from GitHub after app installation.
+ */
+export default interface InstallationCallbackRequest {
+    installation_id: string;
+    setup_action: 'install' | 'update' | 'request';
+    state: string;
+    code?: string;
+    [key: string]: string | undefined;
+}

package/dist/schemas/InstallationCallbackRequest.js

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

package/dist/schemas/WebhookEvent.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Optional webhook event logging for debugging and auditing.
+ * Only stored if logWebhookEvents config option is enabled.
+ */
+export default interface WebhookEvent {
+    _id?: string;
+    installationId: number;
+    event: string;
+    action?: string;
+    deliveryId: string;
+    payload: Record<string, any>;
+    processed: boolean;
+    processedAt?: Date;
+    error?: string;
+    createdAt: Date;
+}

package/dist/schemas/WebhookEvent.js

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

package/dist/schemas/WebhookPayload.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Generic webhook event payload structure from GitHub.
+ * Contains common fields; specific events may have additional fields.
+ */
+export default interface WebhookPayload {
+    action?: string;
+    installation?: {
+        id: number;
+        account: {
+            id: number;
+            login: string;
+            type: 'User' | 'Organization';
+            avatar_url?: string;
+        };
+    };
+    repositories?: {
+        id: number;
+        name: string;
+        full_name: string;
+        private: boolean;
+    }[];
+    repository?: {
+        id: number;
+        name: string;
+        full_name: string;
+        private: boolean;
+        owner: {
+            login: string;
+        };
+    };
+    sender?: {
+        id: number;
+        login: string;
+    };
+}

package/dist/schemas/WebhookPayload.js

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

package/dist/services/GitHubAPIClient.d.ts

@@ -0,0 +1,143 @@
+/**
+ * GitHub API Client
+ *
+ * Wrapper for GitHub API calls with automatic token injection,
+ * retry logic, and error handling.
+ */
+import { GitHubAuthService } from "./GitHubAuthService";
+/**
+ * Repository data structure
+ */
+export interface Repository {
+    id: number;
+    name: string;
+    full_name: string;
+    private: boolean;
+    owner: {
+        login: string;
+        id: number;
+    };
+    html_url: string;
+    description?: string;
+}
+/**
+ * Content data structure
+ */
+export interface Content {
+    name: string;
+    path: string;
+    sha: string;
+    size: number;
+    url: string;
+    html_url: string;
+    git_url: string;
+    download_url?: string;
+    type: "file" | "dir" | "symlink" | "submodule";
+}
+/**
+ * Issue data structure
+ */
+export interface Issue {
+    id: number;
+    number: number;
+    title: string;
+    body?: string;
+    state: "open" | "closed";
+    html_url: string;
+    user: {
+        login: string;
+        id: number;
+    };
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Create issue parameters
+ */
+export interface CreateIssueParams {
+    title: string;
+    body?: string;
+    assignees?: string[];
+    labels?: string[];
+}
+/**
+ * GitHub API Client
+ *
+ * Provides wrapper methods for common GitHub API operations with:
+ * - Automatic token injection
+ * - Retry logic with exponential backoff for rate limits
+ * - Error handling and transformation
+ */
+export declare class GitHubAPIClient {
+    private installationId;
+    private authService;
+    private baseUrl;
+    private maxRetries;
+    private retryDelayMs;
+    /**
+     * Create GitHub API Client
+     *
+     * @param installationId - GitHub installation ID
+     * @param authService - GitHub Auth Service instance
+     * @param baseUrl - GitHub API base URL (default: https://api.github.com)
+     */
+    constructor(installationId: number, authService: GitHubAuthService, baseUrl?: string);
+    /**
+     * Generic API request method with automatic token injection
+     *
+     * @param method - HTTP method (GET, POST, PUT, DELETE)
+     * @param endpoint - API endpoint (e.g., "/repos/owner/repo")
+     * @param data - Request body data (for POST, PUT)
+     * @param retryCount - Current retry attempt (internal use)
+     * @returns Response data
+     * @throws Error if request fails after retries
+     */
+    request<T = any>(method: "GET" | "POST" | "PUT" | "DELETE", endpoint: string, data?: any, retryCount?: number): Promise<T>;
+    /**
+     * Get repositories accessible by this installation
+     *
+     * @returns Array of repositories
+     */
+    getRepositories(): Promise<Repository[]>;
+    /**
+     * Get repository details
+     *
+     * @param owner - Repository owner (user or org)
+     * @param repo - Repository name
+     * @returns Repository details
+     */
+    getRepository(owner: string, repo: string): Promise<Repository>;
+    /**
+     * Get repository contents
+     *
+     * @param owner - Repository owner
+     * @param repo - Repository name
+     * @param path - File or directory path
+     * @returns Content array (for directories) or single content (for files)
+     */
+    getContents(owner: string, repo: string, path: string): Promise<Content | Content[]>;
+    /**
+     * Create an issue
+     *
+     * @param owner - Repository owner
+     * @param repo - Repository name
+     * @param params - Issue creation parameters
+     * @returns Created issue
+     */
+    createIssue(owner: string, repo: string, params: CreateIssueParams): Promise<Issue>;
+    /**
+     * Sleep utility for retry delays
+     *
+     * @param ms - Milliseconds to sleep
+     * @private
+     */
+    private sleep;
+    /**
+     * Determine if error should trigger retry
+     *
+     * @param error - Error to check
+     * @returns true if should retry
+     * @private
+     */
+    private shouldRetry;
+}