@elizaos/plugin-github 2.0.3-beta.5 → 2.0.3-beta.7

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+import { IAgentRuntime, Action, ConnectorAccountProvider, Service, Plugin } from '@elizaos/core';
+import { Octokit } from '@octokit/rest';
+
+/**
+ * @module types
+ * @description Shared types for the GitHub plugin
+ */
+
+type OctokitEndpoint<T, Data> = T extends (...args: infer Args) => unknown ? (...args: Args) => Promise<{
+    data: Data;
+}> : never;
+/**
+ * Identifies which configured token (user-acting or agent-acting) an action
+ * should execute under. The plugin loads two independent PATs so the user
+ * and agent personas can act separately on the same repo.
+ */
+type GitHubIdentity = "user" | "agent";
+type GitHubUserSummary = {
+    login?: string | null;
+};
+type GitHubPullRequestSummary = {
+    number: number;
+    title: string;
+    state: string;
+    html_url: string;
+    user?: GitHubUserSummary | null;
+};
+type GitHubSearchIssueSummary = {
+    repository_url: string;
+    number: number;
+    title: string;
+    state: string;
+    html_url: string;
+    user?: GitHubUserSummary | null;
+};
+type GitHubReviewResult = {
+    id: number;
+};
+type GitHubIssueResult = {
+    number: number;
+    html_url: string;
+};
+type GitHubAssigneesResult = {
+    assignees?: Array<GitHubUserSummary | null> | null;
+};
+type GitHubLabelSummary = string | {
+    name?: string | null;
+};
+type GitHubIssueDetail = {
+    number: number;
+    title: string;
+    state: string;
+    html_url: string;
+    body?: string | null;
+    labels?: Array<GitHubLabelSummary | null> | null;
+    user?: GitHubUserSummary | null;
+};
+type GitHubIssueCommentResult = {
+    id: number;
+    html_url: string;
+};
+type GitHubAddLabelsResult = Array<GitHubLabelSummary | null>;
+type GitHubNotificationSummary = {
+    id: string;
+    reason?: string | null;
+    repository?: {
+        full_name?: string | null;
+        pushed_at?: string | null;
+    };
+    subject?: {
+        title?: string | null;
+        type?: string | null;
+        url?: string | null;
+    };
+    updated_at: string;
+};
+/**
+ * Narrow Octokit surface used by this plugin's actions. Keeping the service
+ * contract structural makes tests and local API mocks straightforward without
+ * depending on the full Octokit class shape.
+ */
+interface GitHubOctokitClient {
+    activity: {
+        listNotificationsForAuthenticatedUser: OctokitEndpoint<Octokit["activity"]["listNotificationsForAuthenticatedUser"], GitHubNotificationSummary[]>;
+    };
+    issues: {
+        addAssignees: OctokitEndpoint<Octokit["issues"]["addAssignees"], GitHubAssigneesResult>;
+        addLabels: OctokitEndpoint<Octokit["issues"]["addLabels"], GitHubAddLabelsResult>;
+        create: OctokitEndpoint<Octokit["issues"]["create"], GitHubIssueResult>;
+        createComment: OctokitEndpoint<Octokit["issues"]["createComment"], GitHubIssueCommentResult>;
+        get: OctokitEndpoint<Octokit["issues"]["get"], GitHubIssueDetail>;
+        listForRepo: OctokitEndpoint<Octokit["issues"]["listForRepo"], GitHubIssueDetail[]>;
+        update: OctokitEndpoint<Octokit["issues"]["update"], GitHubIssueDetail>;
+    };
+    pulls: {
+        createReview: OctokitEndpoint<Octokit["pulls"]["createReview"], GitHubReviewResult>;
+        list: OctokitEndpoint<Octokit["pulls"]["list"], GitHubPullRequestSummary[]>;
+    };
+    search: {
+        issuesAndPullRequests: OctokitEndpoint<Octokit["search"]["issuesAndPullRequests"], {
+            items: GitHubSearchIssueSummary[];
+        }>;
+    };
+}
+/**
+ * Service contract exposed to actions. Actions resolve their Octokit client
+ * via this interface and never read environment variables directly.
+ */
+interface IGitHubService {
+    getOctokit(selector: GitHubIdentity | {
+        as?: GitHubIdentity;
+        role?: GitHubIdentity;
+        accountId?: string;
+    }): GitHubOctokitClient | null;
+}
+declare const GITHUB_SERVICE_TYPE = "github";
+declare const GitHubActions: {
+    readonly GITHUB_ISSUE_OP: "GITHUB_ISSUE";
+    readonly GITHUB_PR_OP: "GITHUB_PR";
+    readonly GITHUB_NOTIFICATION_TRIAGE: "GITHUB_NOTIFICATION_TRIAGE";
+};
+/** Issue ops accepted by GITHUB_ISSUE_OP. */
+type GitHubIssueOp = "create" | "assign" | "close" | "reopen" | "comment" | "label";
+/** PR ops accepted by GITHUB_PR_OP. */
+type GitHubPrOp = "list" | "review";
+/**
+ * Structured result returned by action handlers. Actions never throw —
+ * recoverable problems are surfaced as `{ success: false }` with a reason,
+ * and destructive actions surface a confirmation request distinctly.
+ */
+type GitHubActionResult<T = unknown> = {
+    success: true;
+    data: T;
+    text?: string;
+} | {
+    success: false;
+    error: string;
+} | {
+    success: false;
+    requiresConfirmation: true;
+    preview: string;
+};
+interface RateLimitError {
+    kind: "rate-limit";
+    resetAtMs: number | null;
+    message: string;
+}
+/** Parameters shared by every action invocation. */
+interface BaseActionOptions {
+    as?: GitHubIdentity;
+    accountId?: string;
+    confirmed?: boolean;
+}
+
+declare const DEFAULT_GITHUB_USER_ACCOUNT_ID = "user";
+declare const DEFAULT_GITHUB_AGENT_ACCOUNT_ID = "agent";
+interface GitHubAccountConfig {
+    accountId: string;
+    role: GitHubIdentity;
+    token: string;
+    label?: string;
+}
+interface GitHubAccountSelection {
+    accountId?: string;
+    role: GitHubIdentity;
+}
+declare function defaultGitHubAccountIdForRole(role: GitHubIdentity): string;
+declare function normalizeGitHubAccountId(value: unknown): string | undefined;
+declare function resolveGitHubAccountSelection(options: Record<string, unknown> | undefined, defaultRole: GitHubIdentity): GitHubAccountSelection;
+declare function readGitHubAccounts(runtime: IAgentRuntime): GitHubAccountConfig[];
+declare function readGitHubAccountsWithConnectorCredentials(runtime: IAgentRuntime): Promise<GitHubAccountConfig[]>;
+declare function resolveGitHubAccount(accounts: readonly GitHubAccountConfig[], selection: GitHubAccountSelection): GitHubAccountConfig | null;
+
+declare const githubAction: Action;
+
+/**
+ * @module issue-op
+ * @description Single router action covering GitHub issue lifecycle ops:
+ * create, assign, close, reopen, comment, label. Replaces the old
+ * CREATE_ISSUE / ASSIGN_ISSUE actions and absorbs the issue-management ops
+ * previously implemented in plugin-agent-orchestrator's MANAGE_ISSUES.
+ *
+ * All ops are write ops gated on `confirmed: true`.
+ */
+
+declare const issueOpAction: Action;
+
+/**
+ * @module notification-triage
+ * @description Fetches unread GitHub notifications and returns them sorted
+ * by a composite priority score derived from `reason`, subject type, and
+ * the notifying repo's `pushed_at` freshness.
+ *
+ * Read-only — no confirmation gate.
+ */
+
+interface TriagedNotification {
+    id: string;
+    reason: string;
+    repo: string;
+    title: string;
+    subjectType: string;
+    url: string | null;
+    updatedAt: string;
+    score: number;
+}
+declare function scoreNotification(params: {
+    reason: string;
+    subjectType: string;
+    repoPushedAtMs: number | null;
+    nowMs: number;
+}): number;
+
+declare const notificationTriageAction: Action;
+
+/**
+ * @module pr-op
+ * @description Single router action covering GitHub pull request ops:
+ * list and review.
+ */
+
+declare const prOpAction: Action;
+
+/**
+ * GitHub ConnectorAccountManager provider.
+ *
+ * Bridges plugin-github to the @elizaos/core ConnectorAccountManager so the
+ * generic HTTP CRUD + OAuth surface can list, create, patch, delete, and run
+ * the OAuth flow for GitHub accounts. PATs remain supported as a legacy code
+ * path; OAuth-app installations are exposed via startOAuth/completeOAuth.
+ *
+ * Account model:
+ *   - role "OWNER" — the user persona acting on their own behalf (legacy GITHUB_USER_PAT)
+ *   - role "AGENT" — the agent persona acting on its own behalf (legacy GITHUB_AGENT_PAT)
+ * accountKey = GitHub username (login).
+ */
+
+/**
+ * Build the GitHub ConnectorAccountManager provider.
+ */
+declare function createGitHubConnectorAccountProvider(runtime: IAgentRuntime): ConnectorAccountProvider;
+
+/**
+ * @module github-service
+ * @description Service that owns GitHub REST clients for the plugin.
+ *
+ * Role-tagged account records are supported, with the legacy user/agent PAT
+ * split preserved as the default account set. Actions request an Octokit
+ * client by role and optionally by accountId; the service returns `null` when
+ * the requested account has no token configured.
+ */
+
+declare class GitHubService extends Service implements IGitHubService {
+    private readonly createClient;
+    static serviceType: string;
+    capabilityDescription: string;
+    private clients;
+    constructor(runtime?: IAgentRuntime, createClient?: (auth: string) => GitHubOctokitClient);
+    static start(runtime: IAgentRuntime, createClient?: (auth: string) => GitHubOctokitClient): Promise<Service>;
+    private initialize;
+    getOctokit(selector: GitHubIdentity | {
+        as?: GitHubIdentity;
+        role?: GitHubIdentity;
+        accountId?: string;
+    }): GitHubOctokitClient | null;
+    /**
+     * Allows tests to inject an Octokit-shaped mock without going through
+     * environment variables. Not part of the public runtime contract.
+     */
+    setClientForTesting(as: GitHubIdentity, client: GitHubOctokitClient | null, accountId?: string): void;
+    stop(): Promise<void>;
+}
+
+/**
+ * @module plugin-github
+ * @description elizaOS plugin for GitHub integration.
+ *
+ * Actions:
+ *   - GITHUB (PR, issue, and notification operations)
+ *
+ * Auth: role-tagged account records with legacy PAT fallback.
+ *   - GITHUB_ACCOUNTS   — JSON account records ({accountId, role, token})
+ *   - GITHUB_USER_PAT   — legacy user acting on their own behalf
+ *   - GITHUB_AGENT_PAT  — legacy agent acting on its own behalf
+ *   E2E fallbacks: ELIZA_E2E_GITHUB_USER_PAT / ELIZA_E2E_GITHUB_AGENT_PAT.
+ *
+ * Each action takes an `as: "user" | "agent"` option and may take accountId
+ * to select a specific account. GITHUB_PR_OP review and
+ * GITHUB_NOTIFICATION_TRIAGE default to `"user"`; the other ops default to
+ * `"agent"`.
+ */
+
+declare const githubPlugin: Plugin;
+
+export { type BaseActionOptions, DEFAULT_GITHUB_AGENT_ACCOUNT_ID, DEFAULT_GITHUB_USER_ACCOUNT_ID, GITHUB_SERVICE_TYPE, type GitHubAccountConfig, type GitHubAccountSelection, type GitHubActionResult, GitHubActions, type GitHubIdentity, type GitHubIssueOp, type GitHubOctokitClient, type GitHubPrOp, GitHubService, type IGitHubService, type RateLimitError, type TriagedNotification, createGitHubConnectorAccountProvider, githubPlugin as default, defaultGitHubAccountIdForRole, githubAction, githubPlugin, issueOpAction, normalizeGitHubAccountId, notificationTriageAction, prOpAction, readGitHubAccounts, readGitHubAccountsWithConnectorCredentials, resolveGitHubAccount, resolveGitHubAccountSelection, scoreNotification };