gh-api-client 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1726 @@
+/**
+ * Common pagination parameters accepted by GitHub REST API list endpoints.
+ *
+ * GitHub uses page-based pagination. Pass `page` and `per_page` to control results.
+ */
+interface PaginationParams {
+    /**
+     * Maximum number of results per page.
+     * GitHub default is `30`, maximum is `100`.
+     */
+    per_page?: number;
+    /**
+     * Page number to retrieve (1-based).
+     * Use `nextPage` from the previous response to paginate forward.
+     */
+    page?: number;
+}
+/**
+ * Wrapper returned by GitHub paginated list endpoints.
+ *
+ * Use `values` for the items, `hasNextPage` and `nextPage` for pagination.
+ *
+ * @example
+ * ```typescript
+ * let page = 1;
+ * let hasMore = true;
+ * while (hasMore) {
+ *   const res = await gh.user('octocat').repos({ per_page: 100, page });
+ *   process(res.values);
+ *   hasMore = res.hasNextPage;
+ *   page = res.nextPage ?? page + 1;
+ * }
+ * ```
+ */
+interface GitHubPagedResponse<T> {
+    /** The items on the current page */
+    values: T[];
+    /** Whether there are more pages available */
+    hasNextPage: boolean;
+    /** The next page number, if `hasNextPage` is true */
+    nextPage?: number;
+    /** Total number of results (only available for search endpoints) */
+    totalCount?: number;
+}
+
+/**
+ * Represents a GitHub organization.
+ *
+ * @see {@link https://docs.github.com/en/rest/orgs/orgs#get-an-organization}
+ */
+interface GitHubOrganization {
+    /** Unique numeric organization ID */
+    id: number;
+    /** The organization's login name (e.g., `'github'`) */
+    login: string;
+    /** Display name */
+    name: string | null;
+    /** Organization description */
+    description: string | null;
+    /** URL to the organization's avatar image */
+    avatar_url: string;
+    /** URL to the organization's GitHub page */
+    html_url: string;
+    /** API URL for the organization's repositories */
+    repos_url: string;
+    /** Number of public repositories */
+    public_repos: number;
+    /** Number of public gists */
+    public_gists: number;
+    /** Number of followers */
+    followers: number;
+    /** Number of accounts the org follows */
+    following: number;
+    /** ISO 8601 timestamp of organization creation */
+    created_at: string;
+    /** ISO 8601 timestamp of last update */
+    updated_at: string;
+    /** Account type — always `'Organization'` */
+    type: 'Organization';
+    /** Whether this is a verified organization */
+    is_verified?: boolean;
+    /** Number of private repositories (requires admin scope) */
+    total_private_repos?: number;
+    /** Total number of members */
+    members_count?: number;
+}
+/**
+ * Query parameters for listing organization members.
+ *
+ * @see {@link https://docs.github.com/en/rest/orgs/members#list-organization-members}
+ */
+interface OrgMembersParams extends PaginationParams {
+    /** Filter members by role */
+    role?: 'all' | 'admin' | 'member';
+    /** Filter members by public visibility */
+    filter?: 'all' | '2fa_disabled';
+}
+
+/**
+ * Represents a GitHub user or bot.
+ * This is the minimal user object embedded in other responses (e.g., repository owner, PR author).
+ */
+interface GitHubUser {
+    /** Unique numeric user ID */
+    id: number;
+    /** The user's login name (e.g., `'octocat'`) */
+    login: string;
+    /** Display name, may be null for users who have not set one */
+    name: string | null;
+    /** Public email address, may be null */
+    email: string | null;
+    /** URL to the user's avatar image */
+    avatar_url: string;
+    /** URL to the user's GitHub profile page */
+    html_url: string;
+    /** Account type */
+    type: 'User' | 'Organization' | 'Bot';
+    /** Whether the user is a GitHub site administrator */
+    site_admin: boolean;
+    /** The user's company affiliation */
+    company?: string | null;
+    /** The user's biography */
+    bio?: string | null;
+    /** The user's location */
+    location?: string | null;
+    /** Number of public repositories */
+    public_repos?: number;
+    /** Number of public gists */
+    public_gists?: number;
+    /** Number of followers */
+    followers?: number;
+    /** Number of accounts the user follows */
+    following?: number;
+    /** ISO 8601 timestamp of account creation */
+    created_at?: string;
+    /** ISO 8601 timestamp of last profile update */
+    updated_at?: string;
+}
+/**
+ * Query parameters accepted by `GET /users` (list all users).
+ *
+ * @see {@link https://docs.github.com/en/rest/users/users#list-users}
+ */
+interface UsersParams {
+    /** The integer ID of the last user seen */
+    since?: number;
+    /** Results per page (max 100) */
+    per_page?: number;
+}
+/**
+ * Query parameters accepted by `GET /search/users`.
+ *
+ * @see {@link https://docs.github.com/en/rest/search/search#search-users}
+ */
+interface SearchUsersParams extends PaginationParams {
+    /** Search query (required) */
+    q: string;
+    /** Sort field */
+    sort?: 'followers' | 'repositories' | 'joined';
+    /** Sort direction */
+    order?: 'asc' | 'desc';
+}
+
+/**
+ * Represents a GitHub repository.
+ *
+ * @see {@link https://docs.github.com/en/rest/repos/repos#get-a-repository}
+ */
+interface GitHubRepository {
+    /** Unique numeric repository ID */
+    id: number;
+    /** Repository name (e.g., `'Hello-World'`) */
+    name: string;
+    /** Full name including owner (e.g., `'octocat/Hello-World'`) */
+    full_name: string;
+    /** Repository owner (user or organization) */
+    owner: GitHubUser;
+    /** Whether the repository is private */
+    private: boolean;
+    /** Repository description */
+    description: string | null;
+    /** Whether the repository is a fork */
+    fork: boolean;
+    /** URL to the repository on GitHub */
+    html_url: string;
+    /** HTTPS clone URL */
+    clone_url: string;
+    /** SSH clone URL */
+    ssh_url: string;
+    /** Default branch name (e.g., `'main'`) */
+    default_branch: string;
+    /** Primary language */
+    language: string | null;
+    /** Number of forks */
+    forks_count: number;
+    /** Number of stargazers */
+    stargazers_count: number;
+    /** Number of watchers */
+    watchers_count: number;
+    /** Number of open issues and pull requests */
+    open_issues_count: number;
+    /** Repository topics */
+    topics: string[];
+    /** Whether the repository is archived */
+    archived: boolean;
+    /** Whether the repository is disabled */
+    disabled: boolean;
+    /** Repository visibility */
+    visibility: 'public' | 'private' | 'internal';
+    /** ISO 8601 timestamp of the last push */
+    pushed_at: string | null;
+    /** ISO 8601 timestamp of repository creation */
+    created_at: string;
+    /** ISO 8601 timestamp of last update */
+    updated_at: string;
+    /** Repository size in kilobytes */
+    size?: number;
+    /** Whether the repository has issues enabled */
+    has_issues?: boolean;
+    /** Whether the repository has wiki enabled */
+    has_wiki?: boolean;
+    /** Whether the repository has projects enabled */
+    has_projects?: boolean;
+    /** Whether the repository has discussions enabled */
+    has_discussions?: boolean;
+    /** Parent repository, if this is a fork */
+    parent?: GitHubRepository;
+}
+/**
+ * Query parameters for listing user or organization repositories.
+ *
+ * @see {@link https://docs.github.com/en/rest/repos/repos#list-repositories-for-a-user}
+ */
+interface ReposParams extends PaginationParams {
+    /** Filter by repository type */
+    type?: 'all' | 'public' | 'private' | 'forks' | 'sources' | 'member';
+    /** Sort field */
+    sort?: 'created' | 'updated' | 'pushed' | 'full_name';
+    /** Sort direction */
+    direction?: 'asc' | 'desc';
+}
+/**
+ * Query parameters for listing forks of a repository.
+ *
+ * @see {@link https://docs.github.com/en/rest/repos/forks#list-forks}
+ */
+interface ForksParams extends PaginationParams {
+    /** Sort field */
+    sort?: 'newest' | 'oldest' | 'stargazers' | 'watchers';
+}
+/**
+ * Query parameters accepted by `GET /search/repositories`.
+ *
+ * @see {@link https://docs.github.com/en/rest/search/search#search-repositories}
+ */
+interface SearchReposParams extends PaginationParams {
+    /** Search query (required). Supports qualifiers like `user:octocat`, `language:typescript` */
+    q: string;
+    /** Sort field */
+    sort?: 'stars' | 'forks' | 'help-wanted-issues' | 'updated';
+    /** Sort direction */
+    order?: 'asc' | 'desc';
+}
+
+/**
+ * Represents a git reference in a pull request (head or base).
+ */
+interface GitHubRef {
+    /** Branch name (e.g., `'main'`, `'feature/my-feature'`) */
+    ref: string;
+    /** Commit SHA at the tip of this ref */
+    sha: string;
+    /** `owner:branch` label */
+    label: string;
+    /** The repository this ref belongs to */
+    repo: GitHubRepository;
+    /** The user who owns the ref's repository */
+    user: GitHubUser;
+}
+/**
+ * Represents a GitHub label on a pull request or issue.
+ */
+interface GitHubLabel {
+    /** Unique numeric label ID */
+    id: number;
+    /** Label name */
+    name: string;
+    /** Hex color code (without `#`) */
+    color: string;
+    /** Label description */
+    description: string | null;
+    /** Whether this is a default label */
+    default: boolean;
+}
+/**
+ * Represents a GitHub milestone.
+ */
+interface GitHubMilestone {
+    /** Unique numeric milestone ID */
+    id: number;
+    /** Milestone number within the repository */
+    number: number;
+    /** Milestone title */
+    title: string;
+    /** Milestone description */
+    description: string | null;
+    /** Milestone state */
+    state: 'open' | 'closed';
+    /** ISO 8601 due date, if set */
+    due_on: string | null;
+    /** ISO 8601 timestamp of creation */
+    created_at: string;
+    /** ISO 8601 timestamp of last update */
+    updated_at: string;
+    /** ISO 8601 timestamp of closing */
+    closed_at: string | null;
+    /** Number of open issues in this milestone */
+    open_issues: number;
+    /** Number of closed issues in this milestone */
+    closed_issues: number;
+}
+/**
+ * Represents a GitHub pull request.
+ *
+ * @see {@link https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request}
+ */
+interface GitHubPullRequest {
+    /** Unique numeric pull request ID (global across GitHub) */
+    id: number;
+    /** Pull request number within the repository */
+    number: number;
+    /** Pull request title */
+    title: string;
+    /** Pull request body / description */
+    body: string | null;
+    /** Current state */
+    state: 'open' | 'closed';
+    /** Whether the pull request is locked */
+    locked: boolean;
+    /** Whether the pull request has been merged */
+    merged: boolean;
+    /** Whether the pull request can be merged (null while GitHub computes it) */
+    mergeable: boolean | null;
+    /** Merge strategy used (only set when merged) */
+    merge_commit_sha: string | null;
+    /** ISO 8601 timestamp of merging */
+    merged_at: string | null;
+    /** ISO 8601 timestamp of closing */
+    closed_at: string | null;
+    /** ISO 8601 timestamp of creation */
+    created_at: string;
+    /** ISO 8601 timestamp of last update */
+    updated_at: string;
+    /** Pull request author */
+    user: GitHubUser;
+    /** Users assigned to this pull request */
+    assignees: GitHubUser[];
+    /** Requested reviewers */
+    requested_reviewers: GitHubUser[];
+    /** Labels applied to this pull request */
+    labels: GitHubLabel[];
+    /** Milestone, if any */
+    milestone: GitHubMilestone | null;
+    /** Source branch reference */
+    head: GitHubRef;
+    /** Target branch reference */
+    base: GitHubRef;
+    /** Whether this is a draft pull request */
+    draft: boolean;
+    /** URL to the pull request on GitHub */
+    html_url: string;
+    /** Number of commits in this pull request */
+    commits: number;
+    /** Number of line additions */
+    additions: number;
+    /** Number of line deletions */
+    deletions: number;
+    /** Number of changed files */
+    changed_files: number;
+    /** User who merged this pull request */
+    merged_by: GitHubUser | null;
+    /** Number of review comments */
+    review_comments: number;
+    /** Number of comments */
+    comments: number;
+}
+/**
+ * Query parameters for listing pull requests.
+ *
+ * @see {@link https://docs.github.com/en/rest/pulls/pulls#list-pull-requests}
+ */
+interface PullRequestsParams extends PaginationParams {
+    /** Filter by state */
+    state?: 'open' | 'closed' | 'all';
+    /** Filter by head branch (format: `user:branch-name`) */
+    head?: string;
+    /** Filter by base branch name */
+    base?: string;
+    /** Sort field */
+    sort?: 'created' | 'updated' | 'popularity' | 'long-running';
+    /** Sort direction */
+    direction?: 'asc' | 'desc';
+}
+
+/**
+ * Represents a file changed in a commit.
+ */
+interface GitHubCommitFile {
+    /** File SHA */
+    sha: string;
+    /** File path */
+    filename: string;
+    /** Change status */
+    status: 'added' | 'removed' | 'modified' | 'renamed' | 'copied' | 'changed' | 'unchanged';
+    /** Number of line additions */
+    additions: number;
+    /** Number of line deletions */
+    deletions: number;
+    /** Total number of changes */
+    changes: number;
+    /** URL to the blob on GitHub */
+    blob_url: string;
+    /** URL to the raw file */
+    raw_url: string;
+    /** API URL to file contents */
+    contents_url: string;
+    /** The unified diff patch */
+    patch?: string;
+}
+/**
+ * Represents a GitHub commit.
+ *
+ * @see {@link https://docs.github.com/en/rest/commits/commits#get-a-commit}
+ */
+interface GitHubCommit {
+    /** Full commit SHA */
+    sha: string;
+    /** Git commit data */
+    commit: {
+        /** Commit message */
+        message: string;
+        /** Git author */
+        author: {
+            /** Author name */
+            name: string;
+            /** Author email */
+            email: string;
+            /** ISO 8601 timestamp of authoring */
+            date: string;
+        };
+        /** Git committer */
+        committer: {
+            /** Committer name */
+            name: string;
+            /** Committer email */
+            email: string;
+            /** ISO 8601 timestamp of committing */
+            date: string;
+        };
+    };
+    /** GitHub user associated with the author (null if no matching account) */
+    author: GitHubUser | null;
+    /** GitHub user associated with the committer (null if no matching account) */
+    committer: GitHubUser | null;
+    /** Parent commits */
+    parents: {
+        sha: string;
+        url: string;
+    }[];
+    /** URL to the commit on GitHub */
+    html_url: string;
+    /** Commit stats (only present on single commit GET) */
+    stats?: {
+        /** Number of line additions */
+        additions: number;
+        /** Number of line deletions */
+        deletions: number;
+        /** Total number of changes */
+        total: number;
+    };
+    /** Changed files (only present on single commit GET) */
+    files?: GitHubCommitFile[];
+}
+/**
+ * Query parameters for listing repository commits.
+ *
+ * @see {@link https://docs.github.com/en/rest/commits/commits#list-commits}
+ */
+interface CommitsParams extends PaginationParams {
+    /** SHA or branch to start listing commits from */
+    sha?: string;
+    /** Only commits containing this file path */
+    path?: string;
+    /** Filter by author login or email */
+    author?: string;
+    /** Filter by committer login or email */
+    committer?: string;
+    /** Only commits after this ISO 8601 date */
+    since?: string;
+    /** Only commits before this ISO 8601 date */
+    until?: string;
+}
+
+/**
+ * Represents a GitHub branch.
+ *
+ * @see {@link https://docs.github.com/en/rest/branches/branches#get-a-branch}
+ */
+interface GitHubBranch {
+    /** Branch name (e.g., `'main'`, `'feature/my-feature'`) */
+    name: string;
+    /** Whether this branch is protected */
+    protected: boolean;
+    /** The latest commit on this branch */
+    commit: {
+        /** Commit SHA */
+        sha: string;
+        /** API URL to the commit */
+        url: string;
+    };
+    /** Branch protection details (only present when using authenticated requests) */
+    protection?: {
+        /** Whether protection is enabled */
+        enabled: boolean;
+        /** Required status checks */
+        required_status_checks: {
+            /** Enforcement level */
+            enforcement_level: string;
+            /** Required context names */
+            contexts: string[];
+        } | null;
+    };
+}
+/**
+ * Query parameters for listing repository branches.
+ *
+ * @see {@link https://docs.github.com/en/rest/branches/branches#list-branches}
+ */
+interface BranchesParams extends PaginationParams {
+    /** When `true`, only protected branches are returned */
+    protected?: boolean;
+}
+
+/**
+ * Represents a GitHub lightweight tag (list endpoint).
+ *
+ * @see {@link https://docs.github.com/en/rest/repos/repos#list-repository-tags}
+ */
+interface GitHubTag {
+    /** Tag name (e.g., `'v1.0.0'`) */
+    name: string;
+    /** Commit this tag points to */
+    commit: {
+        /** Commit SHA */
+        sha: string;
+        /** API URL to the commit */
+        url: string;
+    };
+    /** URL to download the repository at this tag as a zip archive */
+    zipball_url: string;
+    /** URL to download the repository at this tag as a tar.gz archive */
+    tarball_url: string;
+    /** Node ID */
+    node_id: string;
+}
+/**
+ * Query parameters for listing repository tags.
+ *
+ * @see {@link https://docs.github.com/en/rest/repos/repos#list-repository-tags}
+ */
+interface TagsParams extends PaginationParams {
+}
+
+/**
+ * Represents a release asset (a file attached to a GitHub release).
+ */
+interface GitHubReleaseAsset {
+    /** Unique numeric asset ID */
+    id: number;
+    /** Asset filename */
+    name: string;
+    /** Asset label */
+    label: string | null;
+    /** MIME content type */
+    content_type: string;
+    /** File size in bytes */
+    size: number;
+    /** Total number of downloads */
+    download_count: number;
+    /** ISO 8601 timestamp of creation */
+    created_at: string;
+    /** ISO 8601 timestamp of last update */
+    updated_at: string;
+    /** Browser download URL */
+    browser_download_url: string;
+    /** User who uploaded the asset */
+    uploader: GitHubUser;
+}
+/**
+ * Represents a GitHub release.
+ *
+ * @see {@link https://docs.github.com/en/rest/releases/releases#get-a-release}
+ */
+interface GitHubRelease {
+    /** Unique numeric release ID */
+    id: number;
+    /** The tag this release is associated with (e.g., `'v1.0.0'`) */
+    tag_name: string;
+    /** Release title */
+    name: string | null;
+    /** Release description / changelog */
+    body: string | null;
+    /** Whether this is a draft release */
+    draft: boolean;
+    /** Whether this is a pre-release */
+    prerelease: boolean;
+    /** ISO 8601 timestamp of creation */
+    created_at: string;
+    /** ISO 8601 timestamp of publishing (null for drafts) */
+    published_at: string | null;
+    /** User who created the release */
+    author: GitHubUser;
+    /** URL to the release on GitHub */
+    html_url: string;
+    /** URL to download the source as a tar archive */
+    tarball_url: string;
+    /** URL to download the source as a zip archive */
+    zipball_url: string;
+    /** Files attached to this release */
+    assets: GitHubReleaseAsset[];
+}
+/**
+ * Query parameters for listing releases.
+ *
+ * @see {@link https://docs.github.com/en/rest/releases/releases#list-releases}
+ */
+interface ReleasesParams extends PaginationParams {
+}
+
+/**
+ * Represents a GitHub repository webhook.
+ *
+ * @see {@link https://docs.github.com/en/rest/webhooks/repos#get-a-repository-webhook}
+ */
+interface GitHubWebhook {
+    /** Unique numeric webhook ID */
+    id: number;
+    /** Webhook name — always `'web'` for repository webhooks */
+    name: string;
+    /** Whether the webhook is active */
+    active: boolean;
+    /** List of events that trigger this webhook */
+    events: string[];
+    /** Webhook configuration */
+    config: {
+        /** Payload delivery URL */
+        url: string;
+        /** Payload format (`'json'` or `'form'`) */
+        content_type?: string;
+        /** Whether SSL verification is disabled (`'0'` = disabled, `'1'` = enabled) */
+        insecure_ssl?: string;
+        /** HMAC secret for payload verification */
+        secret?: string;
+    };
+    /** ISO 8601 timestamp of creation */
+    created_at: string;
+    /** ISO 8601 timestamp of last update */
+    updated_at: string;
+    /** URL to ping this webhook */
+    ping_url: string;
+    /** URL to list webhook deliveries */
+    deliveries_url: string;
+}
+/**
+ * Query parameters for listing webhooks.
+ *
+ * @see {@link https://docs.github.com/en/rest/webhooks/repos#list-repository-webhooks}
+ */
+interface WebhooksParams extends PaginationParams {
+}
+
+/**
+ * Represents a file or directory entry in a GitHub repository.
+ *
+ * @see {@link https://docs.github.com/en/rest/repos/contents#get-repository-content}
+ */
+interface GitHubContent {
+    /** Entry type */
+    type: 'file' | 'dir' | 'symlink' | 'submodule';
+    /** Content encoding (only for files — always `'base64'`) */
+    encoding?: string;
+    /** File size in bytes */
+    size: number;
+    /** Entry name (filename or directory name) */
+    name: string;
+    /** Path from repository root */
+    path: string;
+    /**
+     * Base64-encoded file content.
+     * Only present for files when type is `'file'`.
+     * Decode with `Buffer.from(content, 'base64').toString()` or `atob(content)`.
+     */
+    content?: string;
+    /** Blob SHA */
+    sha: string;
+    /** API URL to this content entry */
+    url: string;
+    /** URL to this file on GitHub */
+    html_url: string;
+    /** URL to the raw file content */
+    download_url: string | null;
+    /** HAL links */
+    _links: Record<string, string>;
+}
+/**
+ * Query parameters for fetching repository content.
+ *
+ * @see {@link https://docs.github.com/en/rest/repos/contents#get-repository-content}
+ */
+interface ContentParams {
+    /** Branch name, tag name, or commit SHA. Defaults to the repository's default branch. */
+    ref?: string;
+}
+
+/**
+ * Represents a pull request review submitted by a reviewer.
+ *
+ * @see {@link https://docs.github.com/en/rest/pulls/reviews#get-a-review-for-a-pull-request}
+ */
+interface GitHubReview {
+    /** Unique numeric review ID */
+    id: number;
+    /** User who submitted the review */
+    user: GitHubUser;
+    /** Review body text */
+    body: string;
+    /** Review state */
+    state: 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED' | 'PENDING';
+    /** URL to the review on GitHub */
+    html_url: string;
+    /** ISO 8601 timestamp of submission */
+    submitted_at: string;
+    /** The commit SHA this review was submitted against */
+    commit_id: string;
+}
+/**
+ * Represents a review comment on a specific line of a pull request diff.
+ *
+ * @see {@link https://docs.github.com/en/rest/pulls/comments#get-a-review-comment-for-a-pull-request}
+ */
+interface GitHubReviewComment {
+    /** Unique numeric comment ID */
+    id: number;
+    /** User who wrote the comment */
+    user: GitHubUser;
+    /** Comment body text */
+    body: string;
+    /** ISO 8601 timestamp of creation */
+    created_at: string;
+    /** ISO 8601 timestamp of last update */
+    updated_at: string;
+    /** URL to the comment on GitHub */
+    html_url: string;
+    /** Path to the file this comment is on */
+    path: string;
+    /** Line position in the diff */
+    position: number | null;
+    /** The diff hunk this comment refers to */
+    diff_hunk: string;
+    /** The commit SHA this comment was placed on */
+    commit_id: string;
+    /** ID of the parent comment if this is a reply */
+    in_reply_to_id?: number;
+    /** ID of the review this comment belongs to */
+    pull_request_review_id: number;
+    /** Line number in the file */
+    line?: number;
+    /** Side of the diff (`LEFT` for old file, `RIGHT` for new file) */
+    side?: 'LEFT' | 'RIGHT';
+}
+/**
+ * Query parameters for listing pull request reviews.
+ *
+ * @see {@link https://docs.github.com/en/rest/pulls/reviews#list-reviews-for-a-pull-request}
+ */
+interface ReviewsParams extends PaginationParams {
+}
+/**
+ * Query parameters for listing review comments.
+ *
+ * @see {@link https://docs.github.com/en/rest/pulls/comments#list-review-comments-on-a-pull-request}
+ */
+interface ReviewCommentsParams extends PaginationParams {
+    /** Sort field */
+    sort?: 'created' | 'updated';
+    /** Sort direction */
+    direction?: 'asc' | 'desc';
+    /** Only return comments after this ISO 8601 date */
+    since?: string;
+}
+
+/**
+ * Represents a file changed in a pull request.
+ *
+ * @see {@link https://docs.github.com/en/rest/pulls/pulls#list-pull-requests-files}
+ */
+interface GitHubPullRequestFile {
+    /** File SHA */
+    sha: string;
+    /** File path */
+    filename: string;
+    /** Change status */
+    status: 'added' | 'removed' | 'modified' | 'renamed' | 'copied' | 'changed' | 'unchanged';
+    /** Number of line additions */
+    additions: number;
+    /** Number of line deletions */
+    deletions: number;
+    /** Total number of changes */
+    changes: number;
+    /** URL to the blob on GitHub */
+    blob_url: string;
+    /** URL to the raw file */
+    raw_url: string;
+    /** API URL to file contents */
+    contents_url: string;
+    /** The unified diff patch for this file */
+    patch?: string;
+    /** Previous file path (for renamed or copied files) */
+    previous_filename?: string;
+}
+/**
+ * Query parameters for listing pull request files.
+ *
+ * @see {@link https://docs.github.com/en/rest/pulls/pulls#list-pull-requests-files}
+ */
+interface PullRequestFilesParams extends PaginationParams {
+}
+
+/**
+ * Represents a GitHub pull request resource with chainable async methods.
+ *
+ * Implements `PromiseLike<GitHubPullRequest>` so it can be awaited directly
+ * to fetch the pull request info, while also exposing sub-resource methods.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get pull request info
+ * const pr = await gh.org('github').repo('linguist').pullRequest(42);
+ *
+ * // Get commits in this pull request
+ * const commits = await gh.org('github').repo('linguist').pullRequest(42).commits();
+ *
+ * // Get changed files
+ * const files = await gh.org('github').repo('linguist').pullRequest(42).files();
+ *
+ * // Get reviews
+ * const reviews = await gh.org('github').repo('linguist').pullRequest(42).reviews();
+ *
+ * // Get review comments (inline diff comments)
+ * const comments = await gh.org('github').repo('linguist').pullRequest(42).reviewComments();
+ * ```
+ */
+declare class PullRequestResource implements PromiseLike<GitHubPullRequest> {
+    private readonly request;
+    private readonly requestList;
+    private readonly basePath;
+    /** @internal */
+    constructor(request: RequestFn, requestList: RequestListFn, owner: string, repo: string, pullNumber: number);
+    /**
+     * Allows the resource to be awaited directly, resolving with the pull request info.
+     * Delegates to {@link PullRequestResource.get}.
+     */
+    then<TResult1 = GitHubPullRequest, TResult2 = never>(onfulfilled?: ((value: GitHubPullRequest) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the pull request details.
+     *
+     * `GET /repos/{owner}/{repo}/pulls/{pull_number}`
+     *
+     * @returns The pull request object
+     */
+    get(): Promise<GitHubPullRequest>;
+    /**
+     * Fetches the commits included in this pull request.
+     *
+     * `GET /repos/{owner}/{repo}/pulls/{pull_number}/commits`
+     *
+     * @param params - Optional pagination: `per_page`, `page`
+     * @returns A paged response of commits
+     */
+    commits(params?: PaginationParams): Promise<GitHubPagedResponse<GitHubCommit>>;
+    /**
+     * Fetches the files changed by this pull request.
+     *
+     * `GET /repos/{owner}/{repo}/pulls/{pull_number}/files`
+     *
+     * @param params - Optional pagination: `per_page`, `page`
+     * @returns A paged response of changed files
+     */
+    files(params?: PullRequestFilesParams): Promise<GitHubPagedResponse<GitHubPullRequestFile>>;
+    /**
+     * Fetches the reviews submitted on this pull request.
+     *
+     * `GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews`
+     *
+     * @param params - Optional pagination: `per_page`, `page`
+     * @returns A paged response of reviews
+     */
+    reviews(params?: ReviewsParams): Promise<GitHubPagedResponse<GitHubReview>>;
+    /**
+     * Fetches the inline review comments on this pull request's diff.
+     *
+     * `GET /repos/{owner}/{repo}/pulls/{pull_number}/comments`
+     *
+     * @param params - Optional filters: `sort`, `direction`, `since`, `per_page`, `page`
+     * @returns A paged response of review comments
+     */
+    reviewComments(params?: ReviewCommentsParams): Promise<GitHubPagedResponse<GitHubReviewComment>>;
+    /**
+     * Checks whether the pull request has been merged.
+     *
+     * `GET /repos/{owner}/{repo}/pulls/{pull_number}/merge`
+     *
+     * @returns `true` if merged (HTTP 204), `false` if not merged (HTTP 404)
+     */
+    isMerged(): Promise<boolean>;
+}
+
+/**
+ * Represents an individual commit status set by a CI/CD system or external service.
+ *
+ * @see {@link https://docs.github.com/en/rest/commits/statuses#list-commit-statuses-for-a-reference}
+ */
+interface GitHubCommitStatus {
+    /** Unique numeric status ID */
+    id: number;
+    /** Status state */
+    state: 'error' | 'failure' | 'pending' | 'success';
+    /** Human-readable description */
+    description: string | null;
+    /** URL to the full details of the status */
+    target_url: string | null;
+    /** Context label identifying the source (e.g., `'ci/circleci'`) */
+    context: string;
+    /** ISO 8601 timestamp of creation */
+    created_at: string;
+    /** ISO 8601 timestamp of last update */
+    updated_at: string;
+    /** User who created the status */
+    creator: GitHubUser;
+}
+/**
+ * Represents the combined commit status — an aggregation of all statuses for a ref.
+ *
+ * @see {@link https://docs.github.com/en/rest/commits/statuses#get-the-combined-status-for-a-specific-reference}
+ */
+interface GitHubCombinedStatus {
+    /** Overall combined state */
+    state: 'error' | 'failure' | 'pending' | 'success';
+    /** Individual statuses that make up the combined status */
+    statuses: GitHubCommitStatus[];
+    /** The commit SHA this status refers to */
+    sha: string;
+    /** Total number of statuses */
+    total_count: number;
+    /** The repository this status belongs to */
+    repository: GitHubRepository;
+}
+/**
+ * Represents a GitHub Actions check run.
+ *
+ * @see {@link https://docs.github.com/en/rest/checks/runs#get-a-check-run}
+ */
+interface GitHubCheckRun {
+    /** Unique numeric check run ID */
+    id: number;
+    /** Check run name */
+    name: string;
+    /** Current status */
+    status: 'queued' | 'in_progress' | 'completed';
+    /** Conclusion (only set when `status` is `'completed'`) */
+    conclusion: 'action_required' | 'cancelled' | 'failure' | 'neutral' | 'success' | 'skipped' | 'stale' | 'timed_out' | null;
+    /** ISO 8601 timestamp of when the check started */
+    started_at: string | null;
+    /** ISO 8601 timestamp of when the check completed */
+    completed_at: string | null;
+    /** URL to the check run details on GitHub */
+    html_url: string;
+    /** The commit SHA this check run is for */
+    head_sha: string;
+    /** GitHub App that created the check run */
+    app: {
+        id: number;
+        name: string;
+        slug: string;
+    };
+}
+/**
+ * Query parameters for listing commit statuses.
+ *
+ * @see {@link https://docs.github.com/en/rest/commits/statuses#list-commit-statuses-for-a-reference}
+ */
+interface CommitStatusesParams extends PaginationParams {
+}
+/**
+ * Query parameters for listing check runs.
+ *
+ * @see {@link https://docs.github.com/en/rest/checks/runs#list-check-runs-for-a-git-reference}
+ */
+interface CheckRunsParams extends PaginationParams {
+    /** Filter by check name */
+    check_name?: string;
+    /** Filter by status */
+    status?: 'queued' | 'in_progress' | 'completed';
+    /** Filter by app slug */
+    app_id?: number;
+}
+
+/**
+ * Represents a GitHub commit resource with chainable async methods.
+ *
+ * Implements `PromiseLike<GitHubCommit>` so it can be awaited directly
+ * to fetch the commit info, while also exposing sub-resource methods.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get commit info (includes stats and files)
+ * const commit = await gh.org('github').repo('linguist').commit('abc123');
+ *
+ * // Get CI/CD statuses for this commit
+ * const statuses = await gh.org('github').repo('linguist').commit('abc123').statuses();
+ *
+ * // Get the combined (aggregated) status
+ * const combined = await gh.org('github').repo('linguist').commit('abc123').combinedStatus();
+ *
+ * // Get GitHub Actions check runs
+ * const checks = await gh.org('github').repo('linguist').commit('abc123').checkRuns();
+ * ```
+ */
+declare class CommitResource implements PromiseLike<GitHubCommit> {
+    private readonly request;
+    private readonly requestList;
+    private readonly basePath;
+    private readonly ref;
+    /** @internal */
+    constructor(request: RequestFn, requestList: RequestListFn, owner: string, repo: string, ref: string);
+    /**
+     * Allows the resource to be awaited directly, resolving with the commit info.
+     * Delegates to {@link CommitResource.get}.
+     */
+    then<TResult1 = GitHubCommit, TResult2 = never>(onfulfilled?: ((value: GitHubCommit) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the commit details, including stats and changed files.
+     *
+     * `GET /repos/{owner}/{repo}/commits/{ref}`
+     *
+     * @returns The commit object with stats and files
+     */
+    get(): Promise<GitHubCommit>;
+    /**
+     * Fetches the individual commit statuses (from CI/CD systems via the Statuses API).
+     *
+     * `GET /repos/{owner}/{repo}/statuses/{sha}`
+     *
+     * @param params - Optional pagination: `per_page`, `page`
+     * @returns A paged response of commit statuses
+     */
+    statuses(params?: CommitStatusesParams): Promise<GitHubPagedResponse<GitHubCommitStatus>>;
+    /**
+     * Fetches the combined commit status — an aggregation of all statuses for this ref.
+     *
+     * `GET /repos/{owner}/{repo}/commits/{ref}/status`
+     *
+     * @returns The combined status object
+     */
+    combinedStatus(): Promise<GitHubCombinedStatus>;
+    /**
+     * Fetches GitHub Actions check runs for this commit.
+     *
+     * `GET /repos/{owner}/{repo}/commits/{ref}/check-runs`
+     *
+     * @param params - Optional filters: `check_name`, `status`, `app_id`, `per_page`, `page`
+     * @returns A paged response of check runs
+     */
+    checkRuns(params?: CheckRunsParams): Promise<GitHubPagedResponse<GitHubCheckRun>>;
+}
+
+/**
+ * Represents a GitHub repository resource with chainable async methods.
+ *
+ * Implements `PromiseLike<GitHubRepository>` so it can be awaited directly
+ * to fetch repository info, while also exposing sub-resource methods.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get repository info
+ * const repo = await gh.org('github').repo('linguist');
+ *
+ * // Get pull requests
+ * const prs = await gh.org('github').repo('linguist').pullRequests({ state: 'open' });
+ *
+ * // Navigate into a specific pull request
+ * const files = await gh.org('github').repo('linguist').pullRequest(42).files();
+ *
+ * // Get commits
+ * const commits = await gh.org('github').repo('linguist').commits({ per_page: 10 });
+ *
+ * // Get raw file content
+ * const content = await gh.org('github').repo('linguist').raw('README.md');
+ * ```
+ */
+declare class RepositoryResource implements PromiseLike<GitHubRepository> {
+    private readonly request;
+    private readonly requestList;
+    private readonly requestText;
+    private readonly owner;
+    private readonly repo;
+    private readonly basePath;
+    /** @internal */
+    constructor(request: RequestFn, requestList: RequestListFn, requestText: RequestTextFn, owner: string, repo: string);
+    /**
+     * Allows the resource to be awaited directly, resolving with the repository info.
+     * Delegates to {@link RepositoryResource.get}.
+     */
+    then<TResult1 = GitHubRepository, TResult2 = never>(onfulfilled?: ((value: GitHubRepository) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the repository details.
+     *
+     * `GET /repos/{owner}/{repo}`
+     *
+     * @returns The repository object
+     */
+    get(): Promise<GitHubRepository>;
+    /**
+     * Fetches pull requests for this repository.
+     *
+     * `GET /repos/{owner}/{repo}/pulls`
+     *
+     * @param params - Optional filters: `state`, `head`, `base`, `sort`, `direction`, `per_page`, `page`
+     * @returns A paged response of pull requests
+     */
+    pullRequests(params?: PullRequestsParams): Promise<GitHubPagedResponse<GitHubPullRequest>>;
+    /**
+     * Returns a {@link PullRequestResource} for a given pull request number.
+     *
+     * The returned resource can be awaited directly to fetch pull request info,
+     * or chained to access nested resources.
+     *
+     * @param pullNumber - The pull request number (not the ID)
+     * @returns A chainable pull request resource
+     *
+     * @example
+     * ```typescript
+     * const pr      = await gh.org('github').repo('linguist').pullRequest(42);
+     * const files   = await gh.org('github').repo('linguist').pullRequest(42).files();
+     * const reviews = await gh.org('github').repo('linguist').pullRequest(42).reviews();
+     * ```
+     */
+    pullRequest(pullNumber: number): PullRequestResource;
+    /**
+     * Fetches commits for this repository.
+     *
+     * `GET /repos/{owner}/{repo}/commits`
+     *
+     * @param params - Optional filters: `sha`, `path`, `author`, `since`, `until`, `per_page`, `page`
+     * @returns A paged response of commits
+     */
+    commits(params?: CommitsParams): Promise<GitHubPagedResponse<GitHubCommit>>;
+    /**
+     * Returns a {@link CommitResource} for a given commit ref (SHA, branch, or tag).
+     *
+     * The returned resource can be awaited directly to fetch commit info,
+     * or chained to access nested resources.
+     *
+     * @param ref - Commit SHA, branch name, or tag name
+     * @returns A chainable commit resource
+     *
+     * @example
+     * ```typescript
+     * const commit   = await gh.org('github').repo('linguist').commit('abc123');
+     * const statuses = await gh.org('github').repo('linguist').commit('abc123').statuses();
+     * ```
+     */
+    commit(ref: string): CommitResource;
+    /**
+     * Fetches branches for this repository.
+     *
+     * `GET /repos/{owner}/{repo}/branches`
+     *
+     * @param params - Optional filters: `protected`, `per_page`, `page`
+     * @returns A paged response of branches
+     */
+    branches(params?: BranchesParams): Promise<GitHubPagedResponse<GitHubBranch>>;
+    /**
+     * Fetches a specific branch by name.
+     *
+     * `GET /repos/{owner}/{repo}/branches/{branch}`
+     *
+     * @param name - The branch name (e.g., `'main'`)
+     * @returns The branch object
+     */
+    branch(name: string): Promise<GitHubBranch>;
+    /**
+     * Fetches tags for this repository.
+     *
+     * `GET /repos/{owner}/{repo}/tags`
+     *
+     * @param params - Optional pagination: `per_page`, `page`
+     * @returns A paged response of tags
+     */
+    tags(params?: TagsParams): Promise<GitHubPagedResponse<GitHubTag>>;
+    /**
+     * Fetches releases for this repository.
+     *
+     * `GET /repos/{owner}/{repo}/releases`
+     *
+     * @param params - Optional pagination: `per_page`, `page`
+     * @returns A paged response of releases
+     */
+    releases(params?: ReleasesParams): Promise<GitHubPagedResponse<GitHubRelease>>;
+    /**
+     * Fetches the latest published release for this repository.
+     *
+     * `GET /repos/{owner}/{repo}/releases/latest`
+     *
+     * @returns The latest release object
+     */
+    latestRelease(): Promise<GitHubRelease>;
+    /**
+     * Fetches the forks of this repository.
+     *
+     * `GET /repos/{owner}/{repo}/forks`
+     *
+     * @param params - Optional filters: `sort`, `per_page`, `page`
+     * @returns A paged response of forked repositories
+     */
+    forks(params?: ForksParams): Promise<GitHubPagedResponse<GitHubRepository>>;
+    /**
+     * Fetches webhooks configured on this repository.
+     *
+     * `GET /repos/{owner}/{repo}/hooks`
+     *
+     * @param params - Optional pagination: `per_page`, `page`
+     * @returns A paged response of webhooks
+     */
+    webhooks(params?: WebhooksParams): Promise<GitHubPagedResponse<GitHubWebhook>>;
+    /**
+     * Fetches the contents of a file or directory in this repository.
+     *
+     * `GET /repos/{owner}/{repo}/contents/{path}`
+     *
+     * Returns a single {@link GitHubContent} for files, or an array for directories.
+     *
+     * @param path - Path to the file or directory (e.g., `'src/index.ts'` or `'src'`). Omit for root.
+     * @param params - Optional: `ref` (branch, tag, or commit SHA)
+     * @returns File content object or array of directory entries
+     */
+    contents(path?: string, params?: ContentParams): Promise<GitHubContent | GitHubContent[]>;
+    /**
+     * Fetches the raw text content of a file in this repository.
+     *
+     * Uses `Accept: application/vnd.github.raw+json` to retrieve the file directly
+     * without base64 encoding.
+     *
+     * `GET /repos/{owner}/{repo}/contents/{filePath}`
+     *
+     * @param filePath - Path to the file (e.g., `'src/index.ts'`)
+     * @param params - Optional: `ref` (branch, tag, or commit SHA)
+     * @returns The raw file content as a string
+     */
+    raw(filePath: string, params?: ContentParams): Promise<string>;
+    /**
+     * Fetches the repository topics.
+     *
+     * `GET /repos/{owner}/{repo}/topics`
+     *
+     * @returns An array of topic strings
+     */
+    topics(): Promise<string[]>;
+    /**
+     * Fetches contributors to this repository.
+     *
+     * `GET /repos/{owner}/{repo}/contributors`
+     *
+     * @param params - Optional filters: `anon` (include anonymous contributors), `per_page`, `page`
+     * @returns A paged response of contributors
+     */
+    contributors(params?: PaginationParams & {
+        anon?: boolean;
+    }): Promise<GitHubPagedResponse<{
+        login?: string;
+        id?: number;
+        contributions: number;
+        avatar_url?: string;
+        html_url?: string;
+    }>>;
+}
+
+/** @internal */
+type RequestFn = <T>(path: string, params?: Record<string, string | number | boolean>) => Promise<T>;
+/** @internal */
+type RequestListFn = <T>(path: string, params?: Record<string, string | number | boolean>) => Promise<GitHubPagedResponse<T>>;
+/** @internal */
+type RequestTextFn = (path: string, params?: Record<string, string | number | boolean>) => Promise<string>;
+/**
+ * Represents a GitHub organization resource with chainable async methods.
+ *
+ * Implements `PromiseLike<GitHubOrganization>` so it can be awaited directly
+ * to fetch the organization info, while also exposing sub-resource methods.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get organization info
+ * const org = await gh.org('github');
+ *
+ * // Get repositories
+ * const repos = await gh.org('github').repos({ type: 'public', per_page: 50 });
+ *
+ * // Navigate into a specific repository
+ * const prs = await gh.org('github').repo('linguist').pullRequests({ state: 'open' });
+ *
+ * // Get members
+ * const members = await gh.org('github').members({ role: 'admin' });
+ * ```
+ */
+declare class OrganizationResource implements PromiseLike<GitHubOrganization> {
+    private readonly request;
+    private readonly requestList;
+    private readonly requestText;
+    private readonly org;
+    /** @internal */
+    constructor(request: RequestFn, requestList: RequestListFn, requestText: RequestTextFn, org: string);
+    /**
+     * Allows the resource to be awaited directly, resolving with the organization info.
+     * Delegates to {@link OrganizationResource.get}.
+     */
+    then<TResult1 = GitHubOrganization, TResult2 = never>(onfulfilled?: ((value: GitHubOrganization) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the organization details.
+     *
+     * `GET /orgs/{org}`
+     *
+     * @returns The organization object
+     */
+    get(): Promise<GitHubOrganization>;
+    /**
+     * Fetches repositories belonging to this organization.
+     *
+     * `GET /orgs/{org}/repos`
+     *
+     * @param params - Optional filters: `type`, `sort`, `direction`, `per_page`, `page`
+     * @returns A paged response of repositories
+     */
+    repos(params?: ReposParams): Promise<GitHubPagedResponse<GitHubRepository>>;
+    /**
+     * Returns a {@link RepositoryResource} for a given repository name within this organization.
+     *
+     * The returned resource can be awaited directly to fetch repository info,
+     * or chained to access nested resources.
+     *
+     * @param name - The repository name (e.g., `'linguist'`)
+     * @returns A chainable repository resource
+     *
+     * @example
+     * ```typescript
+     * const repo    = await gh.org('github').repo('linguist');
+     * const prs     = await gh.org('github').repo('linguist').pullRequests({ state: 'open' });
+     * const commits = await gh.org('github').repo('linguist').commits({ per_page: 10 });
+     * ```
+     */
+    repo(name: string): RepositoryResource;
+    /**
+     * Fetches members of this organization.
+     *
+     * `GET /orgs/{org}/members`
+     *
+     * @param params - Optional filters: `role`, `filter`, `per_page`, `page`
+     * @returns A paged response of users
+     */
+    members(params?: OrgMembersParams): Promise<GitHubPagedResponse<GitHubUser>>;
+}
+
+/**
+ * Represents a GitHub user resource with chainable async methods.
+ *
+ * Implements `PromiseLike<GitHubUser>` so it can be awaited directly
+ * to fetch user info, while also exposing sub-resource methods.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get user info
+ * const user = await gh.user('octocat');
+ *
+ * // Get the user's public repositories
+ * const repos = await gh.user('octocat').repos({ sort: 'updated' });
+ *
+ * // Navigate into a specific repository
+ * const prs = await gh.user('octocat').repo('Hello-World').pullRequests();
+ * ```
+ */
+declare class UserResource implements PromiseLike<GitHubUser> {
+    private readonly request;
+    private readonly requestList;
+    private readonly requestText;
+    private readonly login;
+    private readonly basePath;
+    /** @internal */
+    constructor(request: RequestFn, requestList: RequestListFn, requestText: RequestTextFn, login: string);
+    /**
+     * Allows the resource to be awaited directly, resolving with the user info.
+     * Delegates to {@link UserResource.get}.
+     */
+    then<TResult1 = GitHubUser, TResult2 = never>(onfulfilled?: ((value: GitHubUser) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the user details.
+     *
+     * `GET /users/{username}`
+     *
+     * @returns The user object
+     */
+    get(): Promise<GitHubUser>;
+    /**
+     * Fetches public repositories for this user.
+     *
+     * `GET /users/{username}/repos`
+     *
+     * @param params - Optional filters: `type`, `sort`, `direction`, `per_page`, `page`
+     * @returns A paged response of repositories
+     */
+    repos(params?: ReposParams): Promise<GitHubPagedResponse<GitHubRepository>>;
+    /**
+     * Returns a {@link RepositoryResource} for a given repository under this user,
+     * providing access to all repository sub-resources.
+     *
+     * @param name - The repository name
+     * @returns A chainable repository resource
+     *
+     * @example
+     * ```typescript
+     * const repo    = await gh.user('octocat').repo('Hello-World');
+     * const content = await gh.user('octocat').repo('Hello-World').raw('README.md');
+     * ```
+     */
+    repo(name: string): RepositoryResource;
+    /**
+     * Fetches the users this user is following.
+     *
+     * `GET /users/{username}/following`
+     *
+     * @returns A paged response of users
+     */
+    following(params?: {
+        per_page?: number;
+        page?: number;
+    }): Promise<GitHubPagedResponse<GitHubUser>>;
+    /**
+     * Fetches the users following this user.
+     *
+     * `GET /users/{username}/followers`
+     *
+     * @returns A paged response of users
+     */
+    followers(params?: {
+        per_page?: number;
+        page?: number;
+    }): Promise<GitHubPagedResponse<GitHubUser>>;
+}
+
+/**
+ * Payload emitted on every HTTP request made by {@link GitHubClient}.
+ */
+interface RequestEvent {
+    /** Full URL that was requested */
+    url: string;
+    /** HTTP method used */
+    method: 'GET';
+    /** Timestamp when the request started */
+    startedAt: Date;
+    /** Timestamp when the request finished (success or error) */
+    finishedAt: Date;
+    /** Total duration in milliseconds */
+    durationMs: number;
+    /** HTTP status code returned by the server, if a response was received */
+    statusCode?: number;
+    /** Error thrown, if the request failed */
+    error?: Error;
+}
+/** Map of supported client events to their callback signatures */
+interface GitHubClientEvents {
+    request: (event: RequestEvent) => void;
+}
+/**
+ * Constructor options for {@link GitHubClient}.
+ */
+interface GitHubClientOptions {
+    /** A GitHub personal access token (`ghp_...`), OAuth token, or GitHub App installation token */
+    token: string;
+    /**
+     * The base URL of the GitHub API.
+     * Defaults to `'https://api.github.com'`.
+     * Override for GitHub Enterprise Server (e.g., `'https://github.mycompany.com/api/v3'`).
+     */
+    apiUrl?: string;
+}
+/**
+ * Main entry point for the GitHub REST API client.
+ *
+ * @example
+ * ```typescript
+ * const gh = new GitHubClient({ token: 'ghp_myPersonalAccessToken' });
+ *
+ * const me       = await gh.currentUser();
+ * const user     = await gh.user('octocat');
+ * const repos    = await gh.user('octocat').repos({ sort: 'updated' });
+ * const org      = await gh.org('github');
+ * const repo     = await gh.repo('octocat', 'Hello-World');
+ * const prs      = await gh.repo('octocat', 'Hello-World').pullRequests({ state: 'open' });
+ * const commits  = await gh.repo('octocat', 'Hello-World').commits({ per_page: 10 });
+ * const results  = await gh.searchRepos({ q: 'language:typescript stars:>1000' });
+ * ```
+ */
+declare class GitHubClient {
+    private readonly security;
+    private readonly listeners;
+    /**
+     * @param options - Authentication and connection options
+     * @throws {TypeError} If `apiUrl` is not a valid URL
+     */
+    constructor({ token, apiUrl }: GitHubClientOptions);
+    /**
+     * Subscribes to a client event.
+     *
+     * @example
+     * ```typescript
+     * gh.on('request', (event) => {
+     *   console.log(`${event.method} ${event.url} — ${event.durationMs}ms`);
+     *   if (event.error) console.error('Request failed:', event.error);
+     * });
+     * ```
+     */
+    on<K extends keyof GitHubClientEvents>(event: K, callback: GitHubClientEvents[K]): this;
+    private emit;
+    /**
+     * Performs an authenticated GET request returning a single JSON object.
+     * @internal
+     */
+    private request;
+    /**
+     * Performs an authenticated GET request returning a paginated list.
+     * Parses the `Link` response header to determine if more pages exist.
+     * @internal
+     */
+    private requestList;
+    /**
+     * Performs a GET request returning raw text content.
+     * Uses `Accept: application/vnd.github.raw+json` to retrieve file content directly.
+     * @internal
+     */
+    private requestText;
+    private makeRequestFn;
+    private makeRequestListFn;
+    private makeRequestTextFn;
+    /**
+     * Fetches the authenticated user's profile.
+     *
+     * `GET /user`
+     *
+     * @returns The authenticated user object
+     *
+     * @example
+     * ```typescript
+     * const me = await gh.currentUser();
+     * console.log(me.login); // 'octocat'
+     * ```
+     */
+    currentUser(): Promise<GitHubUser>;
+    /**
+     * Returns a {@link UserResource} for a given GitHub login, providing access
+     * to user data and their repositories.
+     *
+     * The returned resource can be awaited directly to fetch user info,
+     * or chained to access nested resources.
+     *
+     * @param login - The user's login name (e.g., `'octocat'`)
+     * @returns A chainable user resource
+     *
+     * @example
+     * ```typescript
+     * const user  = await gh.user('octocat');
+     * const repos = await gh.user('octocat').repos({ sort: 'updated' });
+     * const pr    = await gh.user('octocat').repo('Hello-World').pullRequest(1).files();
+     * ```
+     */
+    user(login: string): UserResource;
+    /**
+     * Returns an {@link OrganizationResource} for a given GitHub organization, providing
+     * access to organization data and its repositories.
+     *
+     * The returned resource can be awaited directly to fetch organization info,
+     * or chained to access nested resources.
+     *
+     * @param name - The organization's login name (e.g., `'github'`)
+     * @returns A chainable organization resource
+     *
+     * @example
+     * ```typescript
+     * const org   = await gh.org('github');
+     * const repos = await gh.org('github').repos({ type: 'public' });
+     * const prs   = await gh.org('github').repo('linguist').pullRequests({ state: 'open' });
+     * ```
+     */
+    org(name: string): OrganizationResource;
+    /**
+     * Returns a {@link RepositoryResource} for a given owner and repository name.
+     *
+     * Shortcut that works for both user repositories and organization repositories.
+     *
+     * @param owner - The owner login (user or organization)
+     * @param name - The repository name
+     * @returns A chainable repository resource
+     *
+     * @example
+     * ```typescript
+     * const repo  = await gh.repo('octocat', 'Hello-World');
+     * const prs   = await gh.repo('octocat', 'Hello-World').pullRequests();
+     * ```
+     */
+    repo(owner: string, name: string): RepositoryResource;
+    /**
+     * Searches for repositories using GitHub's search syntax.
+     *
+     * `GET /search/repositories`
+     *
+     * @param params - Search query and optional filters. `q` is required.
+     * @returns A paged response of repositories with `totalCount`
+     *
+     * @example
+     * ```typescript
+     * const results = await gh.searchRepos({ q: 'language:typescript stars:>1000', sort: 'stars' });
+     * console.log(`Found ${results.totalCount} repositories`);
+     * ```
+     */
+    searchRepos(params: SearchReposParams): Promise<GitHubPagedResponse<GitHubRepository>>;
+}
+
+/**
+ * Thrown when the GitHub REST API returns a non-2xx response.
+ *
+ * @example
+ * ```typescript
+ * import { GitHubApiError } from 'github-api-client';
+ *
+ * try {
+ *   await gh.user('nonexistent-user-xyz');
+ * } catch (err) {
+ *   if (err instanceof GitHubApiError) {
+ *     console.log(err.status);     // 404
+ *     console.log(err.statusText); // 'Not Found'
+ *     console.log(err.message);    // 'GitHub API error: 404 Not Found'
+ *   }
+ * }
+ * ```
+ */
+declare class GitHubApiError extends Error {
+    /** HTTP status code (e.g. `404`, `401`, `403`, `422`) */
+    readonly status: number;
+    /** HTTP status text (e.g. `'Not Found'`, `'Unauthorized'`) */
+    readonly statusText: string;
+    constructor(status: number, statusText: string);
+}
+
+/**
+ * Handles Bearer token authentication for GitHub REST API requests.
+ *
+ * @example
+ * ```typescript
+ * const security = new Security('ghp_myPersonalAccessToken');
+ *
+ * const headers = security.getHeaders();
+ * // {
+ * //   Authorization: 'Bearer ghp_myPersonalAccessToken',
+ * //   Accept: 'application/vnd.github+json',
+ * //   'Content-Type': 'application/json',
+ * //   'X-GitHub-Api-Version': '2022-11-28',
+ * // }
+ * ```
+ */
+declare class Security {
+    private readonly apiUrl;
+    private readonly token;
+    /**
+     * Creates a new Security instance with a GitHub personal access token.
+     *
+     * @param token - A GitHub personal access token (e.g., `ghp_...`) or OAuth token
+     * @param apiUrl - The base URL of the GitHub API. Defaults to `'https://api.github.com'`.
+     *   Must be a valid URL; throws if it cannot be parsed.
+     *
+     * @throws {TypeError} If `apiUrl` is not a valid URL
+     */
+    constructor(token: string, apiUrl?: string);
+    /**
+     * Returns the base URL of the GitHub API, without a trailing slash.
+     *
+     * @returns The API base URL
+     */
+    getApiUrl(): string;
+    /**
+     * Returns the value of the `Authorization` header for Bearer authentication.
+     *
+     * @returns The Authorization header value in the format `Bearer <token>`
+     */
+    getAuthorizationHeader(): string;
+    /**
+     * Returns the full set of HTTP headers required for authenticated GitHub API requests.
+     *
+     * @returns An object containing `Authorization`, `Accept`, `Content-Type`, and `X-GitHub-Api-Version` headers
+     */
+    getHeaders(): Record<string, string>;
+    /**
+     * Returns headers for raw file content requests.
+     *
+     * @returns Headers with `Accept: application/vnd.github.raw+json`
+     */
+    getRawHeaders(): Record<string, string>;
+}
+
+export { type BranchesParams, type CheckRunsParams, CommitResource, type CommitStatusesParams, type CommitsParams, type ContentParams, type ForksParams, GitHubApiError, type GitHubBranch, type GitHubCheckRun, GitHubClient, type GitHubClientEvents, type GitHubClientOptions, type GitHubCombinedStatus, type GitHubCommit, type GitHubCommitFile, type GitHubCommitStatus, type GitHubContent, type GitHubLabel, type GitHubMilestone, type GitHubOrganization, type GitHubPagedResponse, type GitHubPullRequest, type GitHubPullRequestFile, type GitHubRef, type GitHubRelease, type GitHubReleaseAsset, type GitHubRepository, type GitHubReview, type GitHubReviewComment, type GitHubTag, type GitHubUser, type GitHubWebhook, type OrgMembersParams, OrganizationResource, type PaginationParams, type PullRequestFilesParams, PullRequestResource, type PullRequestsParams, type ReleasesParams, type ReposParams, RepositoryResource, type RequestEvent, type ReviewCommentsParams, type ReviewsParams, type SearchReposParams, type SearchUsersParams, Security, type TagsParams, UserResource, type UsersParams, type WebhooksParams };