@happyvertical/repos 0.83.0 → 0.85.0

package/dist/index.d.ts

@@ -4,6 +4,27 @@ export declare interface Branch {
     protected: boolean;
 }
 
+/** Normalized provider check run. */
+export declare interface CheckRun {
+    id: string;
+    name: string;
+    headSha: string;
+    status: ForgeCheckStatus;
+    conclusion?: ForgeCheckConclusion;
+    detailsUrl?: string;
+    externalId?: string;
+    startedAt?: Date;
+    completedAt?: Date;
+    raw?: unknown;
+}
+
+/** Human-readable check-run output published by a forge. */
+export declare interface CheckRunOutput {
+    title: string;
+    summary: string;
+    text?: string;
+}
+
 declare interface Comment_2 {
     id: string;
     body: string;
@@ -14,6 +35,40 @@ declare interface Comment_2 {
 }
 export { Comment_2 as Comment }
 
+/** Normalized provider commit status. */
+export declare interface CommitStatus {
+    id: string;
+    sha: string;
+    state: string;
+    context: string;
+    description?: string;
+    targetUrl?: string;
+    createdAt?: Date;
+    raw?: unknown;
+}
+
+/** Input for publishing a provider check run. */
+export declare interface CreateCheckRunInput {
+    name: string;
+    headSha: string;
+    status?: ForgeCheckStatus;
+    conclusion?: ForgeCheckConclusion;
+    detailsUrl?: string;
+    externalId?: string;
+    startedAt?: Date | string;
+    completedAt?: Date | string;
+    output?: CheckRunOutput;
+}
+
+/** Input for publishing a provider commit status. */
+export declare interface CreateCommitStatusInput {
+    sha: string;
+    state: 'error' | 'failure' | 'pending' | 'success';
+    context: string;
+    description?: string;
+    targetUrl?: string;
+}
+
 /**
  * Options for creating a repository from a template
  */
@@ -30,6 +85,29 @@ export declare interface CreateFromTemplateOptions {
     includeAllBranches?: boolean;
 }
 
+/**
+ * Creates a short-lived GitHub App JWT without mutating process credentials.
+ * @param credentials GitHub App ID and RSA private key.
+ * @param now Clock value used for issued-at and expiry claims.
+ * @returns Signed RS256 GitHub App JWT.
+ * @throws {ForgeError} When credentials are missing or the key cannot sign.
+ */
+export declare function createGitHubAppJwt(credentials: GitHubAppCredentials, now?: Date): string;
+
+/**
+ * Produces exact, repeatable webhook bytes and headers for integration suites.
+ * Pass the same delivery id for duplicates, or a new id with the same payload
+ * for a provider redelivery.
+ * @param options Secret, delivery identity, event name, and payload.
+ * @returns Exact bytes and matching GitHub delivery headers.
+ */
+export declare function createGitHubWebhookFixture(options: {
+    secret: string;
+    deliveryId: string;
+    event: string;
+    payload: unknown;
+}): GitHubWebhookFixture;
+
 export declare interface CreateIssueInput {
     title: string;
     body?: string;
@@ -81,6 +159,272 @@ export declare function detectTemplateFromLabels(labels: string[], templates: Is
  */
 export declare function fetchIssueTemplates(repo: IRepository): Promise<IssueTemplate[]>;
 
+/** Actor identity supplied by a forge event. */
+export declare interface ForgeActor {
+    id?: string;
+    login: string;
+    type?: string;
+}
+
+/** Provider health or webhook availability observation. */
+export declare interface ForgeAvailabilityObservation extends ForgeObservationBase {
+    kind: 'availability';
+    available: boolean;
+    message?: string;
+}
+
+export declare type ForgeCheckConclusion = 'action_required' | 'cancelled' | 'failure' | 'neutral' | 'skipped' | 'stale' | 'startup_failure' | 'success' | 'timed_out';
+
+/** Check-run or check-suite observation. */
+export declare interface ForgeCheckObservation extends ForgeObservationBase {
+    kind: 'check';
+    check: CheckRun;
+}
+
+export declare type ForgeCheckStatus = 'queued' | 'in_progress' | 'completed';
+
+/** Deployment or deployment-status observation. */
+export declare interface ForgeDeploymentObservation extends ForgeObservationBase {
+    kind: 'deployment';
+    deployment: {
+        id: string;
+        sha?: string;
+        ref?: string;
+        environment?: string;
+        state?: string;
+        url?: string;
+    };
+}
+
+export declare class ForgeError extends Error {
+    readonly provider?: ForgeProvider;
+    readonly code: ForgeErrorCode;
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly rateLimit?: ForgeRateLimit;
+    readonly details?: unknown;
+    readonly retryable: boolean;
+    constructor(message: string, code: ForgeErrorCode, options?: {
+        cause?: unknown;
+        provider?: ForgeProvider;
+        status?: number;
+        requestId?: string;
+        rateLimit?: ForgeRateLimit;
+        details?: unknown;
+        retryable?: boolean;
+    });
+}
+
+export declare type ForgeErrorCode = 'AUTHENTICATION_FAILED' | 'AUTHORITY_MISMATCH' | 'CONFIGURATION_ERROR' | 'INVALID_INPUT' | 'NOT_FOUND' | 'PROVIDER_ERROR' | 'RATE_LIMITED' | 'SIGNATURE_INVALID' | 'TRANSPORT_ERROR';
+
+/** Verified delivery envelope retaining the parsed provider payload. */
+export declare interface ForgeEventEnvelope<TObservation extends ForgeObservation = ForgeObservation> {
+    provider: ForgeProvider;
+    deliveryId: string;
+    event: string;
+    action?: string;
+    occurredAt?: Date;
+    receivedAt: Date;
+    installation?: ForgeInstallationRef;
+    repository?: ForgeRepositoryRef;
+    actor?: ForgeActor;
+    observation: TObservation;
+    /** Original parsed provider payload. Raw request bytes remain caller-owned. */
+    raw: unknown;
+}
+
+/** Installation lifecycle or repository-scope observation. */
+export declare interface ForgeInstallationObservation extends ForgeObservationBase {
+    kind: 'installation';
+    installation: ForgeInstallationRef;
+    repositories?: readonly ForgeRepositoryRef[];
+}
+
+/** Installation identity associated with provider authority. */
+export declare interface ForgeInstallationRef {
+    id: string;
+    account?: string;
+    repositorySelection?: 'all' | 'selected';
+}
+
+/** Merge-queue group observation tied to its synthetic head revision. */
+export declare interface ForgeMergeGroupObservation extends ForgeObservationBase {
+    kind: 'merge_group';
+    headSha: string;
+    headRef?: string;
+    baseSha?: string;
+    baseRef?: string;
+}
+
+/** Completed pull-request merge observation. */
+export declare interface ForgeMergeObservation extends ForgeObservationBase {
+    kind: 'merge';
+    pullRequest: ForgePullRequestRef;
+    mergeCommitSha?: string;
+}
+
+export declare type ForgeObservation = ForgeAvailabilityObservation | ForgeCheckObservation | ForgeDeploymentObservation | ForgeInstallationObservation | ForgeMergeGroupObservation | ForgeMergeObservation | ForgePullRequestObservation | ForgePushObservation | ForgeRepositoryObservation | ForgeReviewObservation | ForgeStatusObservation | ForgeUnknownObservation;
+
+/** Shared discriminator implemented by every normalized observation. */
+declare interface ForgeObservationBase {
+    kind: 'availability' | 'check' | 'deployment' | 'installation' | 'merge' | 'merge_group' | 'pull_request' | 'push' | 'repository' | 'review' | 'status' | 'unknown';
+}
+
+/** Provider-neutral forge reconciliation and check-publishing operations. */
+export declare interface ForgeOperations {
+    /** Returns the configured repository. */
+    getRepository(): Promise<ForgeResponse<ForgeRepositoryRef>>;
+    /** Returns one pull request by repository-local number. */
+    getPullRequest(number: number): Promise<ForgeResponse<ForgePullRequestRef>>;
+    /** Returns provider review payloads for one pull request. */
+    listPullRequestReviews(number: number): Promise<ForgeResponse<readonly unknown[]>>;
+    /** Returns one commit payload by SHA. */
+    getCommit(sha: string): Promise<ForgeResponse<unknown>>;
+    /** Returns complete commit-status history across provider pages. */
+    listCommitStatuses(sha: string): Promise<ForgeResponse<readonly CommitStatus[]>>;
+    /** Publishes one commit status. */
+    createCommitStatus(input: CreateCommitStatusInput): Promise<ForgeResponse<CommitStatus>>;
+    /** Returns complete check history, including reruns, across provider pages. */
+    listCheckRuns(sha: string): Promise<ForgeResponse<readonly CheckRun[]>>;
+    /** Publishes one check run. */
+    createCheckRun(input: CreateCheckRunInput): Promise<ForgeResponse<CheckRun>>;
+    /** Changes one check run by provider ID. */
+    updateCheckRun(id: string, input: UpdateCheckRunInput): Promise<ForgeResponse<CheckRun>>;
+    /** Lists deployments using narrow optional filters. */
+    listDeployments(options?: {
+        sha?: string;
+        environment?: string;
+        limit?: number;
+    }): Promise<ForgeResponse<unknown[]>>;
+    /** Returns one deployment by provider ID. */
+    getDeployment(id: string): Promise<ForgeResponse<unknown>>;
+}
+
+export declare type ForgeProvider = 'github' | (string & {});
+
+/** Pull-request lifecycle or revision observation. */
+export declare interface ForgePullRequestObservation extends ForgeObservationBase {
+    kind: 'pull_request';
+    pullRequest: ForgePullRequestRef;
+}
+
+/** Pull-request identity and exact revision references. */
+export declare interface ForgePullRequestRef {
+    id?: string;
+    number: number;
+    state: 'open' | 'closed';
+    draft?: boolean;
+    headSha: string;
+    headRef?: string;
+    baseSha?: string;
+    baseRef?: string;
+    merged?: boolean;
+    mergeCommitSha?: string;
+    url?: string;
+}
+
+/** Git reference update observation. */
+export declare interface ForgePushObservation extends ForgeObservationBase {
+    kind: 'push';
+    ref: string;
+    beforeSha?: string;
+    afterSha: string;
+    forced?: boolean;
+    created?: boolean;
+    deleted?: boolean;
+}
+
+/** Provider quota information captured from one forge response. */
+export declare interface ForgeRateLimit {
+    limit?: number;
+    remaining?: number;
+    used?: number;
+    resetAt?: Date;
+    retryAfterMs?: number;
+}
+
+/** Repository lifecycle or metadata observation. */
+export declare interface ForgeRepositoryObservation extends ForgeObservationBase {
+    kind: 'repository';
+    repository: ForgeRepositoryRef;
+}
+
+/** Provider-neutral repository identity and reconciled attributes. */
+export declare interface ForgeRepositoryRef {
+    id?: string;
+    owner: string;
+    name: string;
+    fullName: string;
+    defaultBranch?: string;
+    private?: boolean;
+    url?: string;
+}
+
+/** Provider data paired with concurrency-safe request metadata. */
+export declare interface ForgeResponse<T> {
+    data: T;
+    metadata: ForgeResponseMetadata;
+}
+
+/** Metadata for the same provider request that produced a response. */
+export declare interface ForgeResponseMetadata {
+    provider: ForgeProvider;
+    requestId?: string;
+    status: number;
+    rateLimit?: ForgeRateLimit;
+    pagination?: {
+        pages: number;
+        totalCount?: number;
+    };
+}
+
+/** Pull-request review observation tied to an exact commit when available. */
+export declare interface ForgeReviewObservation extends ForgeObservationBase {
+    kind: 'review';
+    pullRequest: ForgePullRequestRef;
+    review: {
+        id: string;
+        state: string;
+        body?: string;
+        commitSha?: string;
+        submittedAt?: Date;
+        author?: ForgeActor;
+    };
+}
+
+export declare class ForgeSignatureError extends ForgeError {
+    constructor(message?: string);
+}
+
+/** Commit-status observation. */
+export declare interface ForgeStatusObservation extends ForgeObservationBase {
+    kind: 'status';
+    status: CommitStatus;
+}
+
+/** Executes authenticated provider requests and normalizes their metadata. */
+export declare interface ForgeTransport {
+    /**
+     * Executes one provider request.
+     * @throws {ForgeError} When transport or provider processing fails.
+     */
+    request<T>(request: ForgeTransportRequest): Promise<ForgeResponse<T>>;
+}
+
+/** Provider-neutral HTTP request accepted by a forge transport. */
+export declare interface ForgeTransportRequest {
+    method: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';
+    path: string;
+    body?: unknown;
+    headers?: Readonly<Record<string, string>>;
+    signal?: AbortSignal;
+}
+
+/** Forward-compatible observation for an unsupported provider event. */
+export declare interface ForgeUnknownObservation extends ForgeObservationBase {
+    kind: 'unknown';
+}
+
 /**
  * Get a specific field value from an issue body
  *
@@ -122,6 +466,172 @@ export declare function getIssueField(body: string, fieldIdOrLabel: string, temp
  */
 export declare function getRepository(options: RepositoryConfig | IRepository): Promise<IRepository>;
 
+/**
+ * Request/job-scoped GitHub App authority.
+ *
+ * Keep this object inside a single request or job. Its token cache and in-flight
+ * acquisitions are instance fields, so installations cannot share credentials.
+ */
+export declare class GitHubAppAuth {
+    private readonly credentials;
+    private readonly baseUrl?;
+    private readonly fetchImplementation?;
+    private readonly now;
+    private readonly expirySkewMs;
+    private readonly tokens;
+    private readonly issuedTokens;
+    private readonly tokenRequests;
+    private readonly authorizationRequests;
+    private readonly revokedInstallations;
+    private nextTokenGeneration;
+    /**
+     * Creates isolated GitHub App authority from credentials and dependencies.
+     * @param options Credentials, clock, provider URL, and fetch override.
+     */
+    constructor(options: GitHubAppAuthOptions);
+    /**
+     * Clears locally cached credentials without remote revocation.
+     * @param installationId Optional installation to clear; omitted clears all.
+     * @returns Nothing.
+     */
+    clear(installationId?: string | number): void;
+    /**
+     * Acquires and verifies one installation/repository boundary.
+     * @param scope Installation ID and exact repository coordinates.
+     * @returns An isolated forge provider and revocation handle.
+     * @throws {ForgeError} When authentication, provider access, or scope fails.
+     */
+    createInstallationContext(scope: GitHubInstallationScope): Promise<GitHubInstallationContext>;
+    private getAuthorizedToken;
+    private getInstallationToken;
+    private acquireInstallationToken;
+    private verifyRepositoryScope;
+    private revokeInstallationTokens;
+    private revokeToken;
+    private clearCachedInstallation;
+}
+
+/** Construction options for one request/job-scoped GitHub App authority. */
+export declare interface GitHubAppAuthOptions extends GitHubAppCredentials {
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    now?: () => Date;
+    /** Refresh before provider expiry. Defaults to 60 seconds. */
+    expirySkewMs?: number;
+}
+
+/** Credentials required to sign GitHub App JSON Web Tokens. */
+export declare interface GitHubAppCredentials {
+    appId: string | number;
+    privateKey: string;
+}
+
+/**
+ * Repository-scoped GitHub implementation of provider-neutral forge operations.
+ * Every operation may throw `ForgeError` for transport or provider failures.
+ */
+export declare class GitHubForgeProvider implements ForgeOperations {
+    private readonly transport;
+    private readonly path;
+    /**
+     * Creates a repository-scoped GitHub forge provider.
+     * @param options Repository coordinates and authenticated transport.
+     */
+    constructor(options: GitHubForgeProviderOptions);
+    /** @returns Normalized repository data and request metadata. */
+    getRepository(): Promise<ForgeResponse<ForgeRepositoryRef>>;
+    /**
+     * Returns one normalized pull request.
+     * @param number Repository-local pull-request number.
+     * @returns Pull-request data and request metadata.
+     * @throws {ForgeError} When GitHub rejects the request.
+     */
+    getPullRequest(number: number): Promise<ForgeResponse<ForgePullRequestRef>>;
+    /**
+     * Lists every raw provider review for one pull request.
+     * @param number Repository-local pull-request number.
+     * @returns All reviews and final-page request metadata.
+     */
+    listPullRequestReviews(number: number): Promise<ForgeResponse<readonly unknown[]>>;
+    /**
+     * Returns one raw provider commit payload.
+     * @param sha Exact commit SHA.
+     * @returns Commit payload and request metadata.
+     */
+    getCommit(sha: string): Promise<ForgeResponse<unknown>>;
+    /**
+     * Returns complete normalized commit-status history.
+     * @param sha Exact commit SHA.
+     * @returns All status pages and final-page request metadata.
+     */
+    listCommitStatuses(sha: string): Promise<ForgeResponse<readonly CommitStatus[]>>;
+    /**
+     * Publishes one commit status.
+     * @param input Exact SHA and status attributes.
+     * @returns Published status and request metadata.
+     */
+    createCommitStatus(input: CreateCommitStatusInput): Promise<ForgeResponse<CommitStatus>>;
+    /**
+     * Returns all normalized check runs, including reruns.
+     * @param sha Exact commit SHA.
+     * @returns All check pages and final-page request metadata.
+     */
+    listCheckRuns(sha: string): Promise<ForgeResponse<readonly CheckRun[]>>;
+    /**
+     * Publishes one check run.
+     * @param input Check identity, exact head SHA, state, and output.
+     * @returns Published check and request metadata.
+     */
+    createCheckRun(input: CreateCheckRunInput): Promise<ForgeResponse<CheckRun>>;
+    /**
+     * Changes one check run by provider ID.
+     * @param id GitHub check-run ID.
+     * @param input Attributes to change.
+     * @returns Updated check and request metadata.
+     */
+    updateCheckRun(id: string, input: UpdateCheckRunInput): Promise<ForgeResponse<CheckRun>>;
+    /**
+     * Lists raw deployment payloads using narrow filters.
+     * @param options Optional SHA, environment, and result limit.
+     * @returns Matching deployments and request metadata.
+     */
+    listDeployments(options?: {
+        sha?: string;
+        environment?: string;
+        limit?: number;
+    }): Promise<ForgeResponse<unknown[]>>;
+    /**
+     * Returns one raw deployment payload.
+     * @param id GitHub deployment ID.
+     * @returns Deployment payload and request metadata.
+     */
+    getDeployment(id: string): Promise<ForgeResponse<unknown>>;
+    private paginate;
+}
+
+/** Repository coordinates and transport for a GitHub forge provider. */
+export declare interface GitHubForgeProviderOptions {
+    owner: string;
+    repo: string;
+    transport: ForgeTransport;
+}
+
+/** Authorized repository client and explicit token-revocation handle. */
+export declare interface GitHubInstallationContext {
+    installation: ForgeInstallationRef;
+    repository: ForgeRepositoryRef;
+    forge: GitHubForgeProvider;
+    /** Revokes issued tokens remotely and closes this local context. */
+    revoke(): Promise<void>;
+}
+
+/** Installation and repository boundary requested by a caller. */
+export declare interface GitHubInstallationScope {
+    installationId: string | number;
+    owner: string;
+    repo: string;
+}
+
 /**
  * GitHub repository implementation
  */
@@ -164,6 +674,40 @@ export declare class GitHubRepository implements IRepository {
     findIssueForPR(prNumber: number): Promise<Issue | null>;
     getFileContent(path: string, ref?: string): Promise<string | null>;
     listDirectoryFiles(path: string, ref?: string): Promise<string[]>;
+    /**
+     * Publishes one GitHub commit status.
+     * @param input Exact commit SHA and status attributes.
+     * @returns Normalized published status.
+     */
+    createCommitStatus(input: CreateCommitStatusInput): Promise<CommitStatus>;
+    /**
+     * Returns complete commit-status history across GitHub pages.
+     * @param sha Exact commit SHA.
+     * @returns Every normalized status for the commit.
+     */
+    listCommitStatuses(sha: string): Promise<readonly CommitStatus[]>;
+    /**
+     * Publishes one GitHub check run.
+     * @param input Check identity, exact head SHA, state, and output.
+     * @returns Normalized published check run.
+     */
+    createCheckRun(input: CreateCheckRunInput): Promise<CheckRun>;
+    /**
+     * Changes one GitHub check run.
+     * @param id GitHub check-run ID.
+     * @param input Attributes to change.
+     * @returns Normalized updated check run.
+     */
+    updateCheckRun(id: string, input: UpdateCheckRunInput): Promise<CheckRun>;
+    /**
+     * Returns complete GitHub check history, including reruns.
+     * @param sha Exact commit SHA.
+     * @returns Every normalized check run for the commit.
+     */
+    listCheckRuns(sha: string): Promise<readonly CheckRun[]>;
+    private mapCommitStatus;
+    private mapCheckRunInput;
+    private mapCheckRun;
     /**
      * Create a new repository from this repository as a template.
      *
@@ -173,6 +717,75 @@ export declare class GitHubRepository implements IRepository {
     createRepositoryFromTemplate(options: CreateFromTemplateOptions): Promise<Repository>;
 }
 
+export declare type GitHubTokenSource = string | (() => string | Promise<string>);
+
+export declare class GitHubTransport implements ForgeTransport {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly fetchImplementation;
+    /**
+     * Creates a GitHub REST transport with fixed or lazy credentials.
+     * @param options Token source, provider URL, and fetch override.
+     */
+    constructor(options: GitHubTransportOptions);
+    /**
+     * Executes one GitHub REST request.
+     * @param request Method, provider-relative path, body, headers, and signal.
+     * @returns Parsed data and metadata for this exact request.
+     * @throws {ForgeError} For transport, authentication, rate, or provider failures.
+     */
+    request<T>(request: ForgeTransportRequest): Promise<ForgeResponse<T>>;
+}
+
+/** Construction options for an authenticated GitHub REST transport. */
+export declare interface GitHubTransportOptions {
+    token: GitHubTokenSource;
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}
+
+/** Exact webhook bytes and headers suitable for deterministic tests. */
+export declare interface GitHubWebhookFixture {
+    rawBody: Uint8Array;
+    headers: GitHubWebhookHeaders;
+}
+
+export declare type GitHubWebhookHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+
+export declare class GitHubWebhookVerifier {
+    private readonly secrets;
+    private readonly now;
+    /**
+     * Creates a verifier with a current secret and optional rotation secrets.
+     * @param options Current/rotation secrets and optional clock.
+     * @throws {ForgeError} When no non-empty secret is configured.
+     */
+    constructor(options: GitHubWebhookVerifierOptions);
+    /**
+     * Verifies unchanged provider bytes with constant-time comparisons.
+     * @param rawBody Exact bytes received from the HTTP server.
+     * @param signature GitHub SHA-256 signature header.
+     * @returns Index of the configured secret that matched.
+     * @throws {ForgeSignatureError} When the signature is missing or invalid.
+     */
+    verify(rawBody: Uint8Array, signature: string | undefined): number;
+    /**
+     * Verifies raw bytes before decoding and normalizes the delivery.
+     * @param rawBody Exact bytes received from the HTTP server.
+     * @param headers Case-insensitive GitHub delivery headers.
+     * @returns Verified normalized delivery.
+     * @throws {ForgeError} For invalid signatures, headers, UTF-8, or JSON.
+     */
+    verifyAndNormalize(rawBody: Uint8Array, headers: GitHubWebhookHeaders): ForgeEventEnvelope;
+}
+
+/** Construction options for raw GitHub webhook verification. */
+export declare interface GitHubWebhookVerifierOptions {
+    /** Current secret first, followed by still-valid rotation secrets. */
+    secrets: string | readonly string[];
+    now?: () => Date;
+}
+
 /**
  * Repository interface - all repository implementations must implement this
  */
@@ -210,6 +823,16 @@ export declare interface IRepository {
     findIssueForPR(prNumber: number): Promise<Issue | null>;
     getFileContent(path: string, ref?: string): Promise<string | null>;
     listDirectoryFiles(path: string, ref?: string): Promise<string[]>;
+    /** Publishes one provider commit status. */
+    createCommitStatus?(input: CreateCommitStatusInput): Promise<CommitStatus>;
+    /** Returns complete commit-status history across provider pages. */
+    listCommitStatuses?(sha: string): Promise<readonly CommitStatus[]>;
+    /** Publishes one provider check run. */
+    createCheckRun?(input: CreateCheckRunInput): Promise<CheckRun>;
+    /** Changes one provider check run. */
+    updateCheckRun?(id: string, input: UpdateCheckRunInput): Promise<CheckRun>;
+    /** Returns complete check history, including reruns, across provider pages. */
+    listCheckRuns?(sha: string): Promise<readonly CheckRun[]>;
 }
 
 export declare interface Issue {
@@ -261,6 +884,16 @@ export declare function loadIssueTemplate(yamlPath: string): Promise<IssueTempla
 
 export declare type MergeMethod = 'merge' | 'squash' | 'rebase';
 
+/**
+ * Normalizes one already-verified GitHub payload.
+ * @param deliveryId Stable provider delivery identity.
+ * @param event GitHub event header value.
+ * @param raw Parsed provider payload.
+ * @param receivedAt Local receipt timestamp.
+ * @returns A provider-neutral event envelope preserving the parsed payload.
+ */
+export declare function normalizeGitHubWebhook(deliveryId: string, event: string, raw: unknown, receivedAt?: Date): ForgeEventEnvelope;
+
 /**
  * Parse an issue body into field values
  *
@@ -422,6 +1055,11 @@ export declare interface TemplateField {
     };
 }
 
+/** Input for changing an existing provider check run. */
+export declare interface UpdateCheckRunInput extends Omit<CreateCheckRunInput, 'name' | 'headSha'> {
+    name?: string;
+}
+
 /**
  * Update a specific field in an issue body
  *