Core Framework

/**
 * Main Probot class for building GitHub Apps
 */
class Probot {
  /**
   * Create a new Probot instance
   * @param options - Configuration options for the Probot instance
   */
  constructor(options: Options = {});
  
  /**
   * Create a new Probot class with default options
   * @param defaults - Default options to merge with constructor options
   * @returns Extended Probot constructor with defaults
   */
  static defaults<S extends Constructor>(
    this: S,
    defaults: Options
  ): ExtendedConstructor & S;
  
  /**
   * Get the Probot framework version
   * @returns Version string
   */
  static get version(): string;
}

import { Probot } from "probot";

// Basic initialization
const app = new Probot({
  appId: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
  secret: process.env.WEBHOOK_SECRET,
});

// Using defaults
const ProbotWithDefaults = Probot.defaults({
  logLevel: "debug",
  secret: "development",
});
const app = new ProbotWithDefaults({ appId: 123 });

/**
 * Pino logger instance scoped to this Probot instance
 */
get log(): Logger;

/**
 * Probot framework version string
 */
get version(): string;

/**
 * Webhooks event emitter instance for handling GitHub events
 */
get webhooks(): ProbotWebhooks;

/**
 * URL path where webhooks are received (e.g., "/api/github/webhooks")
 */
get webhookPath(): string;

/**
 * Get an authenticated Octokit instance for a specific installation
 * @param installationId - GitHub App installation ID (optional for app-level auth)
 * @returns Authenticated Octokit instance
 */
async auth(installationId?: number): Promise<ProbotOctokit>;

// App-level authentication (for app management)
const appOctokit = await app.auth();
const installations = await appOctokit.apps.listInstallations();

// Installation-level authentication (for repository access)
const installationOctokit = await app.auth(12345);
const repos = await installationOctokit.apps.listReposAccessibleToInstallation();

/**
 * Load one or more application functions
 * @param appFn - Application function(s) to load
 * @param options - Options passed to application functions
 */
async load(
  appFn: ApplicationFunction | ApplicationFunction[], 
  options?: ApplicationFunctionOptions
): Promise<void>;

/**
 * Wait for Probot initialization to complete
 * @returns Promise that resolves when Probot is ready
 */
async ready(): Promise<this>;

// Load a single app function
await app.load((app) => {
  app.on("issues.opened", async (context) => {
    // Handle issue opened
  });
});

// Load multiple app functions
await app.load([appFunction1, appFunction2], {
  cwd: process.cwd(),
  addHandler: (handler) => server.addHandler(handler),
});

// Ensure app is ready before proceeding
await app.ready();

/**
 * Register event handler(s) for specific GitHub webhook events
 * Supports single event name, array of event names, or wildcard patterns
 */
on: ProbotWebhooks["on"];

/**
 * Register handler for all GitHub webhook events
 * Useful for logging, analytics, or cross-cutting concerns
 */
onAny: ProbotWebhooks["onAny"];

/**
 * Register error handler for webhook processing errors
 * Called when event handlers throw exceptions
 */
onError: ProbotWebhooks["onError"];

// Single event handler
app.on("issues.opened", async (context) => {
  await context.octokit.issues.createComment(
    context.issue({ body: "Welcome!" })
  );
});

// Multiple event handler
app.on(["issues.opened", "issues.reopened"], async (context) => {
  // Handle both opened and reopened issues
});

// Wildcard event handler
app.on("issues", async (context) => {
  // Handle all issue events (opened, closed, edited, etc.)
});

// Global event handler
app.onAny(async (context) => {
  context.log.info(`Event: ${context.name}`);
});

// Error handler
app.onError(async (error) => {
  app.log.error("Webhook processing failed:", error);
});

/**
 * Manually receive and process a webhook event
 * @param event - GitHub webhook event object
 */
async receive(event: WebhookEvent): Promise<void>;

// Manually trigger event processing
const mockEvent = {
  name: "issues",
  id: "12345",
  payload: {
    action: "opened",
    issue: { /* issue data */ },
    repository: { /* repo data */ },
  },
};

await app.receive(mockEvent);

/**
 * Get Node.js middleware for handling webhooks and custom routes
 * @param options - Middleware configuration options
 * @returns Promise resolving to Express-compatible middleware function
 */
async getNodeMiddleware(options?: {
  log?: Logger;
  path?: string;
}): Promise<NodeMiddleware>;

import express from "express";

const server = express();
const middleware = await app.getNodeMiddleware();

// Mount Probot middleware
server.use(middleware);

// Custom middleware with options
const customMiddleware = await app.getNodeMiddleware({
  log: customLogger,
  path: "/github/webhooks",
});

server.use("/api", customMiddleware);
server.listen(3000);

interface Options {
  /** GitHub App private key (PEM format) */
  privateKey?: string;
  /** Personal access token (alternative to App auth) */
  githubToken?: string;
  /** GitHub App ID */
  appId?: number | string;
  /** Custom Octokit class */
  Octokit?: typeof ProbotOctokit;
  /** Custom logger instance */
  log?: Logger;
  /** Redis configuration for clustering */
  redisConfig?: RedisOptions | string;
  /** Webhook secret for payload verification */
  secret?: string;
  /** Log level verbosity */
  logLevel?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
  /** Log output format */
  logFormat?: "json" | "pretty";
  /** Use string log levels in JSON output */
  logLevelInString?: boolean;
  /** JSON log message key name */
  logMessageKey?: string;
  /** Sentry DSN for error reporting */
  sentryDsn?: string;
  /** HTTP server port */
  port?: number;
  /** HTTP server host */
  host?: string;
  /** Custom server instance */
  server?: Server;
  /** GitHub API base URL (for Enterprise) */
  baseUrl?: string;
  /** Octokit request options */
  request?: RequestRequestOptions;
  /** Webhook endpoint path */
  webhookPath?: string;
  /** Smee.io proxy URL for development */
  webhookProxy?: string;
}

type Constructor<T = any> = new (...args: any[]) => T;

type ProbotWebhooks = Webhooks<SimplifiedObject>;

interface ApplicationFunctionOptions {
  /** Current working directory */
  cwd: string;
  /** Function to add custom HTTP handlers */
  addHandler: (handler: Handler) => void;
  /** Additional custom options */
  [key: string]: unknown;
}

type ApplicationFunction = (
  app: Probot,
  options: ApplicationFunctionOptions
) => void | Promise<void>;

type NodeMiddleware = (
  req: IncomingMessage,
  res: ServerResponse,
  next?: (err?: Error) => void
) => Promise<boolean | void>;