bitbucket-datacenter-api-client 1.0.0 → 1.2.0

package/dist/index.d.mts

@@ -85,6 +85,48 @@ interface ReposParams extends PaginationParams {
     permission?: string;
 }
 
+/**
+ * Represents a Bitbucket Data Center user.
+ */
+interface BitbucketUser {
+    name: string;
+    emailAddress: string;
+    id: number;
+    displayName: string;
+    active: boolean;
+    slug: string;
+    type: 'NORMAL' | 'SERVICE';
+    links: Record<string, unknown>;
+}
+/**
+ * A user with an explicit permission on a project.
+ */
+interface BitbucketUserPermission {
+    user: BitbucketUser;
+    permission: 'PROJECT_READ' | 'PROJECT_WRITE' | 'PROJECT_ADMIN';
+}
+/**
+ * Query parameters accepted by `GET /rest/api/latest/users`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-users/#api-api-latest-users-get}
+ */
+interface UsersParams extends PaginationParams {
+    /** Filter results by display name or username (prefix match) */
+    filter?: string;
+}
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/permissions/users`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-project/#api-api-latest-projects-projectkey-permissions-users-get}
+ */
+interface ProjectUsersParams extends PaginationParams {
+    /** Filter results by display name or username (prefix match) */
+    filter?: string;
+    /** Filter by the permission level on the project */
+    permission?: 'PROJECT_READ' | 'PROJECT_WRITE' | 'PROJECT_ADMIN';
+}
+
 /** A git ref (branch or tag) as referenced in a pull request. */
 interface BitbucketRef {
     id: string;
@@ -205,6 +247,463 @@ interface CommitsParams extends PaginationParams {
     ignoreMissing?: boolean;
 }
 
+/**
+ * Represents a git branch in a Bitbucket Data Center repository.
+ */
+interface BitbucketBranch {
+    /** Full ref name (e.g., `'refs/heads/main'`) */
+    id: string;
+    /** Short branch name (e.g., `'main'`) */
+    displayId: string;
+    type: 'BRANCH';
+    /** SHA of the latest commit on this branch */
+    latestCommit: string;
+    latestChangeset: string;
+    /** Whether this is the repository's default branch */
+    isDefault: boolean;
+}
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/branches`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-branches-get}
+ */
+interface BranchesParams extends PaginationParams {
+    /** Filter branches by name (prefix match) */
+    filterText?: string;
+    /** Sort order of results */
+    orderBy?: 'ALPHABETICAL' | 'MODIFICATION';
+    /** Include branch metadata such as ahead/behind counts relative to `base` */
+    details?: boolean;
+    /**
+     * Base branch or commit to use for ahead/behind comparisons
+     * when `details` is `true`
+     */
+    base?: string;
+    /** Boost exact matches to the top of the results when filtering */
+    boostMatches?: boolean;
+}
+
+/**
+ * Size information for a Bitbucket repository.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-sizes-get}
+ */
+interface BitbucketRepositorySize {
+    /** Size of the repository in bytes */
+    repository: number;
+    /** Size of attachments in bytes */
+    attachments: number;
+}
+
+/** The type of change applied to a file in a pull request. */
+type ChangeType = 'ADD' | 'COPY' | 'DELETE' | 'MODIFY' | 'MOVE' | 'RENAME' | 'UNKNOWN';
+/** The node type of the changed entry. */
+type ChangeNodeType = 'FILE' | 'DIRECTORY' | 'SUBMODULE';
+/** Represents a file path in a Bitbucket change entry. */
+interface BitbucketChangePath {
+    /** Path segments (e.g., `['src', 'index.ts']`) */
+    components: string[];
+    /** Parent directory (e.g., `'src'`) */
+    parent: string;
+    /** File name (e.g., `'index.ts'`) */
+    name: string;
+    /** File extension (e.g., `'ts'`) */
+    extension: string;
+    /** Full path string (e.g., `'src/index.ts'`) */
+    toString: string;
+}
+/**
+ * Represents a single file change within a Bitbucket Data Center pull request.
+ */
+interface BitbucketChange {
+    /** Content ID (SHA) of the file in the destination ref */
+    contentId?: string;
+    /** Content ID (SHA) of the file in the source ref */
+    fromContentId?: string;
+    /** Path of the changed file in the destination ref */
+    path: BitbucketChangePath;
+    /** Original path before a rename or move (only present for `RENAME` and `MOVE`) */
+    srcPath?: BitbucketChangePath;
+    /** Whether the file has the executable bit set in the destination ref */
+    executable: boolean;
+    /** Whether the file had the executable bit set in the source ref */
+    srcExecutable: boolean;
+    percentUnchanged: number;
+    type: ChangeType;
+    nodeType: ChangeNodeType;
+    links: Record<string, unknown>;
+}
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/changes`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-pull-requests/#api-api-latest-projects-projectkey-repos-repositoryslug-pull-requests-pullrequestid-changes-get}
+ */
+interface ChangesParams extends PaginationParams {
+    /**
+     * When `true`, includes the number of comments for each changed file.
+     * @default false
+     */
+    withComments?: boolean;
+}
+
+/**
+ * Represents a file entry returned by the last-modified endpoint,
+ * showing the path and the commit that last touched it.
+ */
+interface BitbucketLastModifiedEntry {
+    /** The file path */
+    path: BitbucketChangePath;
+    /** The commit that last modified this file */
+    latestCommit: BitbucketCommit;
+}
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/last-modified`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-last-modified-get}
+ */
+interface LastModifiedParams extends PaginationParams {
+    /** Branch, tag, or commit SHA to use as the base ref */
+    at?: string;
+}
+
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/raw/{path}`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-raw-path-get}
+ */
+interface RawFileParams {
+    /** Branch, tag, or commit SHA to retrieve the file at */
+    at?: string;
+}
+
+/** Minimal user shape used inside activity records. */
+interface BitbucketActivityUser {
+    name: string;
+    emailAddress: string;
+    id: number;
+    displayName: string;
+    active: boolean;
+    slug: string;
+    type: string;
+}
+/** A comment posted on a pull request. */
+interface BitbucketPullRequestComment {
+    id: number;
+    version: number;
+    text: string;
+    author: BitbucketActivityUser;
+    createdDate: number;
+    updatedDate: number;
+    comments: BitbucketPullRequestComment[];
+    tasks: unknown[];
+    links: Record<string, unknown>;
+}
+/**
+ * All possible action types for a pull request activity.
+ *
+ * - `OPENED`     — PR was opened
+ * - `APPROVED`   — a reviewer approved
+ * - `UNAPPROVED` — a reviewer removed their approval
+ * - `NEEDS_WORK` — a reviewer requested changes
+ * - `COMMENTED`  — a comment was posted
+ * - `RESCOPED`   — commits were added or removed from the PR
+ * - `MERGED`     — PR was merged
+ * - `DECLINED`   — PR was declined
+ * - `REVIEWED`   — PR was reviewed without an explicit vote
+ */
+type PullRequestActivityAction = 'OPENED' | 'APPROVED' | 'UNAPPROVED' | 'NEEDS_WORK' | 'COMMENTED' | 'RESCOPED' | 'MERGED' | 'DECLINED' | 'REVIEWED';
+/**
+ * Represents a single activity entry on a Bitbucket Data Center pull request.
+ *
+ * The optional fields are populated depending on `action`:
+ * - `COMMENTED`  → `comment` is present
+ * - `RESCOPED`   → `addedCommits`, `removedCommits`, `fromHash`, `toHash`, etc. are present
+ * - `APPROVED` / `UNAPPROVED` / `NEEDS_WORK` → `participant` is present
+ */
+interface BitbucketPullRequestActivity {
+    id: number;
+    createdDate: number;
+    user: BitbucketActivityUser;
+    action: PullRequestActivityAction;
+    /** Present when `action` is `'COMMENTED'` */
+    comment?: BitbucketPullRequestComment;
+    /** Present when `action` is `'APPROVED'`, `'UNAPPROVED'`, or `'NEEDS_WORK'` */
+    participant?: BitbucketParticipant;
+    /** Present when `action` is `'RESCOPED'` — commits added to the PR */
+    addedCommits?: BitbucketCommit[];
+    /** Present when `action` is `'RESCOPED'` — commits removed from the PR */
+    removedCommits?: BitbucketCommit[];
+    fromHash?: string;
+    previousFromHash?: string;
+    previousToHash?: string;
+    toHash?: string;
+}
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/activities`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-pull-requests/#api-api-latest-projects-projectkey-repos-repositoryslug-pull-requests-pullrequestid-activities-get}
+ */
+interface ActivitiesParams extends PaginationParams {
+    /**
+     * Filter the results to contain only activities with the supplied `id`
+     * as the anchor, starting from the supplied activity.
+     */
+    fromId?: number;
+    /**
+     * When `fromId` is set, filter by activity type:
+     * - `'COMMENT'`  — start from a comment
+     * - `'ACTIVITY'` — start from a generic activity
+     */
+    fromType?: 'COMMENT' | 'ACTIVITY';
+}
+
+/** The state of a pull request task. */
+type PullRequestTaskState = 'OPEN' | 'RESOLVED';
+/** Operations the authenticated user is permitted to perform on a task. */
+interface PullRequestTaskPermittedOperations {
+    editable: boolean;
+    deletable: boolean;
+    transitionable: boolean;
+}
+/** The comment anchor to which a task is attached. */
+interface PullRequestTaskAnchor {
+    id: number;
+    type: {
+        id: 'COMMENT';
+    };
+}
+/**
+ * Represents a task (review to-do item) on a Bitbucket Data Center pull request.
+ *
+ * Tasks are created by reviewers on specific comments and can be either `OPEN` or `RESOLVED`.
+ */
+interface BitbucketPullRequestTask {
+    id: number;
+    createdDate: number;
+    author: BitbucketActivityUser;
+    text: string;
+    state: PullRequestTaskState;
+    permittedOperations: PullRequestTaskPermittedOperations;
+    /** The comment the task is anchored to */
+    anchor: PullRequestTaskAnchor;
+}
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/tasks`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-pull-requests/#api-api-latest-projects-projectkey-repos-repositoryslug-pull-requests-pullrequestid-tasks-get}
+ */
+interface TasksParams extends PaginationParams {
+}
+
+/** The overall result of a Code Insights report. */
+type ReportResult = 'PASS' | 'FAIL';
+/** The data types supported for report data items. */
+type ReportDataType = 'BOOLEAN' | 'DATE' | 'DURATION' | 'LINK' | 'NUMBER' | 'PERCENTAGE' | 'TEXT';
+/** A single data point included in a Code Insights report. */
+interface BitbucketReportData {
+    title: string;
+    type: ReportDataType;
+    value: string | number | boolean | {
+        href: string;
+        text?: string;
+    };
+}
+/**
+ * Represents a Code Insights report attached to a pull request in Bitbucket Data Center.
+ *
+ * Reports are created by external tools (CI, static analysis, coverage) and
+ * displayed in the pull request overview.
+ */
+interface BitbucketReport {
+    /** Unique key identifying the report */
+    key: string;
+    title: string;
+    details?: string;
+    /** Overall result of the report */
+    result?: ReportResult;
+    /** Name of the tool or service that created the report */
+    reporter?: string;
+    /** Link to the full external report */
+    link?: string;
+    /** URL of the logo shown in the Bitbucket UI */
+    logoUrl?: string;
+    /** Structured data points displayed in the report */
+    data?: BitbucketReportData[];
+    createdDate: number;
+    updatedDate: number;
+}
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/reports`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-code-insights/#api-insights-latest-projects-projectkey-repos-repositoryslug-pull-requests-pullrequestid-reports-get}
+ */
+interface ReportsParams extends PaginationParams {
+}
+
+/**
+ * Aggregated build counts for a single commit hash.
+ */
+interface BitbucketBuildCount {
+    successful: number;
+    failed: number;
+    inProgress: number;
+    cancelled: number;
+    unknown: number;
+}
+/**
+ * Response from the build-summaries endpoint: a map of commit hash → build counts.
+ *
+ * Each key is a full commit SHA and the value contains the aggregated count of
+ * builds in each state for that commit.
+ *
+ * @example
+ * ```ts
+ * {
+ *   "abc123def456": { successful: 2, failed: 0, inProgress: 0, cancelled: 0, unknown: 0 },
+ *   "def456abc123": { successful: 0, failed: 1, inProgress: 1, cancelled: 0, unknown: 0 }
+ * }
+ * ```
+ */
+type BitbucketBuildSummaries = Record<string, BitbucketBuildCount>;
+
+/**
+ * Represents a Jira issue linked to a Bitbucket Data Center pull request.
+ */
+interface BitbucketIssue {
+    /** The Jira issue key (e.g., `'ABC-123'`) */
+    key: string;
+    /** The URL to the issue in Jira */
+    url: string;
+}
+
+/**
+ * Represents a Bitbucket pull request resource with chainable async methods.
+ *
+ * Implements `PromiseLike<BitbucketPullRequest>` 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 bbClient.project('PROJ').repo('my-repo').pullRequest(42);
+ *
+ * // Get activities
+ * const activities = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).activities();
+ *
+ * // Get tasks
+ * const tasks = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).tasks();
+ *
+ * // Get commits
+ * const commits = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).commits();
+ *
+ * // Get changes
+ * const changes = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).changes();
+ *
+ * // Get reports
+ * const reports = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).reports();
+ *
+ * // Get build summaries
+ * const builds = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).buildSummaries();
+ *
+ * // Get linked Jira issues
+ * const issues = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).issues();
+ * ```
+ */
+declare class PullRequestResource implements PromiseLike<BitbucketPullRequest> {
+    private readonly request;
+    private readonly basePath;
+    /** @internal */
+    constructor(request: RequestFn, projectKey: string, repoSlug: string, pullRequestId: number);
+    /**
+     * Allows the resource to be awaited directly, resolving with the pull request info.
+     * Delegates to {@link PullRequestResource.get}.
+     */
+    then<TResult1 = BitbucketPullRequest, TResult2 = never>(onfulfilled?: ((value: BitbucketPullRequest) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the pull request details.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}`
+     *
+     * @returns The pull request object
+     */
+    get(): Promise<BitbucketPullRequest>;
+    /**
+     * Fetches the activity feed for this pull request.
+     *
+     * Activities include comments, approvals, reviews, rescopes, merges, and declines.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/activities`
+     *
+     * @param params - Optional filters: `limit`, `start`, `fromId`, `fromType`
+     * @returns An array of pull request activities, ordered from most recent to oldest
+     */
+    activities(params?: ActivitiesParams): Promise<BitbucketPullRequestActivity[]>;
+    /**
+     * Fetches the tasks (review to-do items) for this pull request.
+     *
+     * Tasks are created by reviewers on specific comments and can be `OPEN` or `RESOLVED`.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/tasks`
+     *
+     * @param params - Optional filters: `limit`, `start`
+     * @returns An array of pull request tasks
+     */
+    tasks(params?: TasksParams): Promise<BitbucketPullRequestTask[]>;
+    /**
+     * Fetches the commits included in this pull request.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/commits`
+     *
+     * @param params - Optional pagination: `limit`, `start`
+     * @returns An array of commits
+     */
+    commits(params?: PaginationParams): Promise<BitbucketCommit[]>;
+    /**
+     * Fetches the file changes included in this pull request.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/changes`
+     *
+     * @param params - Optional filters: `limit`, `start`, `withComments`
+     * @returns An array of file changes
+     */
+    changes(params?: ChangesParams): Promise<BitbucketChange[]>;
+    /**
+     * Fetches the Code Insights reports for this pull request.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/reports`
+     *
+     * @param params - Optional pagination: `limit`, `start`
+     * @returns An array of Code Insights reports
+     */
+    reports(params?: ReportsParams): Promise<BitbucketReport[]>;
+    /**
+     * Fetches the aggregated build summaries for this pull request.
+     *
+     * Returns a map of commit hash → build counts per state
+     * (`successful`, `failed`, `inProgress`, `cancelled`, `unknown`).
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/build-summaries`
+     *
+     * @returns A record keyed by commit SHA with aggregated build counts
+     */
+    buildSummaries(): Promise<BitbucketBuildSummaries>;
+    /**
+     * Fetches the Jira issues linked to this pull request.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/issues`
+     *
+     * @returns An array of linked Jira issues
+     */
+    issues(): Promise<BitbucketIssue[]>;
+}
+
 /**
  * Represents a Bitbucket repository resource with chainable async methods.
  *
@@ -219,15 +718,21 @@ interface CommitsParams extends PaginationParams {
  * // Get pull requests
  * const prs = await bbClient.project('PROJ').repo('my-repo').pullRequests({ state: 'OPEN' });
  *
+ * // Navigate into a specific pull request
+ * const activities = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).activities();
+ *
  * // Get commits
  * const commits = await bbClient.project('PROJ').repo('my-repo').commits({ limit: 10 });
  * ```
  */
 declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
     private readonly request;
+    private readonly requestText;
+    private readonly projectKey;
+    private readonly repoSlug;
     private readonly basePath;
     /** @internal */
-    constructor(request: RequestFn, projectKey: string, repoSlug: string);
+    constructor(request: RequestFn, requestText: RequestTextFn, projectKey: string, repoSlug: string);
     /**
      * Allows the resource to be awaited directly, resolving with the repository info.
      * Delegates to {@link RepositoryResource.get}.
@@ -259,10 +764,65 @@ declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
      * @returns An array of commits
      */
     commits(params?: CommitsParams): Promise<BitbucketCommit[]>;
+    /**
+     * Fetches the files last modified in this repository along with the commit that last touched each.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/last-modified`
+     *
+     * @param params - Optional filters: `limit`, `start`, `at`
+     * @returns An array of last-modified entries
+     */
+    lastModified(params?: LastModifiedParams): Promise<BitbucketLastModifiedEntry[]>;
+    /**
+     * Fetches the size of this repository.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/sizes`
+     *
+     * @returns The repository size object
+     */
+    size(): Promise<BitbucketRepositorySize>;
+    /**
+     * Fetches branches for this repository.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/branches`
+     *
+     * @param params - Optional filters: `limit`, `start`, `filterText`, `orderBy`, `details`, `base`, `boostMatches`
+     * @returns An array of branches
+     */
+    branches(params?: BranchesParams): Promise<BitbucketBranch[]>;
+    /**
+     * Returns a {@link PullRequestResource} for a given pull request ID, providing
+     * access to pull request data and sub-resources (activities, etc.).
+     *
+     * The returned resource can be awaited directly to fetch pull request info,
+     * or chained to access nested resources.
+     *
+     * @param pullRequestId - The numeric pull request ID
+     * @returns A chainable pull request resource
+     *
+     * @example
+     * ```typescript
+     * const pr         = await bbClient.project('PROJ').repo('my-repo').pullRequest(42);
+     * const activities = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).activities();
+     * ```
+     */
+    /**
+     * Fetches the raw content of a file in this repository.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/raw/{path}`
+     *
+     * @param filePath - Path to the file (e.g., `'src/index.ts'`)
+     * @param params - Optional: `at` (branch, tag, or commit SHA)
+     * @returns The raw file content as a string
+     */
+    raw(filePath: string, params?: RawFileParams): Promise<string>;
+    pullRequest(pullRequestId: number): PullRequestResource;
 }
 
 /** @internal */
 type RequestFn = <T>(path: string, params?: Record<string, string | number | boolean>) => Promise<T>;
+/** @internal */
+type RequestTextFn = (path: string, params?: Record<string, string | number | boolean>) => Promise<string>;
 /**
  * Represents a Bitbucket project resource with chainable async methods.
  *
@@ -279,13 +839,17 @@ type RequestFn = <T>(path: string, params?: Record<string, string | number | boo
  *
  * // Navigate into a specific repository
  * const prs = await bbClient.project('PROJ').repo('my-repo').pullRequests();
+ *
+ * // Get users with access to the project
+ * const users = await bbClient.project('PROJ').users({ permission: 'PROJECT_WRITE' });
  * ```
  */
 declare class ProjectResource implements PromiseLike<BitbucketProject> {
     private readonly request;
+    private readonly requestText;
     private readonly key;
     /** @internal */
-    constructor(request: RequestFn, key: string);
+    constructor(request: RequestFn, requestText: RequestTextFn, key: string);
     /**
      * Allows the resource to be awaited directly, resolving with the project info.
      * Delegates to {@link ProjectResource.get}.
@@ -326,14 +890,57 @@ declare class ProjectResource implements PromiseLike<BitbucketProject> {
      * ```
      */
     repo(repoSlug: string): RepositoryResource;
+    /**
+     * Fetches users with explicit permissions on this project.
+     *
+     * `GET /rest/api/latest/projects/{key}/permissions/users`
+     *
+     * @param params - Optional filters: `limit`, `start`, `filter`, `permission`
+     * @returns An array of user–permission pairs
+     */
+    users(params?: ProjectUsersParams): Promise<BitbucketUserPermission[]>;
+}
+
+/**
+ * Represents a Bitbucket user resource.
+ *
+ * Implements `PromiseLike<BitbucketUser>` so it can be awaited directly
+ * to fetch user info.
+ *
+ * @example
+ * ```typescript
+ * // Await directly to get user info
+ * const user = await bbClient.user('pilmee');
+ * ```
+ */
+declare class UserResource implements PromiseLike<BitbucketUser> {
+    private readonly request;
+    private readonly basePath;
+    /** @internal */
+    constructor(request: RequestFn, slug: string);
+    /**
+     * Allows the resource to be awaited directly, resolving with the user info.
+     * Delegates to {@link UserResource.get}.
+     */
+    then<TResult1 = BitbucketUser, TResult2 = never>(onfulfilled?: ((value: BitbucketUser) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /**
+     * Fetches the user details.
+     *
+     * `GET /rest/api/latest/users/{slug}`
+     *
+     * @returns The user object
+     */
+    get(): Promise<BitbucketUser>;
 }
 
 /**
  * Constructor options for {@link BitbucketClient}.
  */
 interface BitbucketClientOptions {
-    /** The base URL of the Bitbucket Data Center instance (e.g., `https://bitbucket.example.com`) */
+    /** The host URL of the Bitbucket Data Center instance (e.g., `https://bitbucket.example.com`) */
     apiUrl: string;
+    /** The API path to prepend to every request (e.g., `'rest/api/latest'`) */
+    apiPath: string;
     /** The username to authenticate with */
     user: string;
     /** The personal access token or password to authenticate with */
@@ -346,7 +953,8 @@ interface BitbucketClientOptions {
  * ```typescript
  * const bbClient = new BitbucketClient({
  *   apiUrl: 'https://bitbucket.example.com',
- *   user: 'john.doe',
+ *   apiPath: 'rest/api/latest',
+ *   user: 'pilmee',
  *   token: 'my-token',
  * });
  *
@@ -356,24 +964,28 @@ interface BitbucketClientOptions {
  * const repo     = await bbClient.project('PROJ').repo('my-repo');
  * const prs      = await bbClient.project('PROJ').repo('my-repo').pullRequests({ state: 'OPEN' });
  * const commits  = await bbClient.project('PROJ').repo('my-repo').commits({ limit: 10 });
+ * const users    = await bbClient.users({ filter: 'john' });
+ * const user     = await bbClient.user('pilmee');
  * ```
  */
 declare class BitbucketClient {
     private readonly security;
+    private readonly apiPath;
     /**
      * @param options - Connection and authentication options
      * @throws {TypeError} If `apiUrl` is not a valid URL
      */
-    constructor({ apiUrl, user, token }: BitbucketClientOptions);
+    constructor({ apiUrl, apiPath, user, token }: BitbucketClientOptions);
     /**
      * Performs an authenticated GET request to the Bitbucket REST API.
      *
-     * @param path - API path relative to `/rest/api/latest` (e.g., `'/projects'`)
+     * @param path - API path appended directly to `apiUrl` (e.g., `'/projects'`)
      * @param params - Optional query parameters to append to the URL
      * @throws {Error} If the HTTP response is not OK
      * @internal
      */
     private request;
+    private requestText;
     /**
      * Fetches all projects accessible to the authenticated user.
      *
@@ -401,6 +1013,30 @@ declare class BitbucketClient {
      * ```
      */
     project(projectKey: string): ProjectResource;
+    /**
+     * Fetches all users accessible to the authenticated user.
+     *
+     * `GET /rest/api/latest/users`
+     *
+     * @param params - Optional filters: `limit`, `start`, `filter`
+     * @returns An array of users
+     */
+    users(params?: UsersParams): Promise<BitbucketUser[]>;
+    /**
+     * Returns a {@link UserResource} for a given user slug, providing access
+     * to user data.
+     *
+     * The returned resource can be awaited directly to fetch user info.
+     *
+     * @param slug - The user slug (e.g., `'pilmee'`)
+     * @returns A chainable user resource
+     *
+     * @example
+     * ```typescript
+     * const user = await bbClient.user('pilmee');
+     * ```
+     */
+    user(slug: string): UserResource;
 }
 
 /**
@@ -452,4 +1088,4 @@ declare class Security {
     getHeaders(): Record<string, string>;
 }
 
-export { BitbucketClient, type BitbucketClientOptions, type BitbucketCommit, type BitbucketCommitAuthor, type BitbucketParticipant, type BitbucketProject, type BitbucketPullRequest, type BitbucketRef, type BitbucketRepository, type CommitsParams, type PagedResponse, type PaginationParams, ProjectResource, type ProjectsParams, type PullRequestsParams, type ReposParams, RepositoryResource, Security };
+export { type ActivitiesParams, type BitbucketActivityUser, type BitbucketBranch, type BitbucketBuildCount, type BitbucketBuildSummaries, type BitbucketChange, type BitbucketChangePath, BitbucketClient, type BitbucketClientOptions, type BitbucketCommit, type BitbucketCommitAuthor, type BitbucketIssue, type BitbucketLastModifiedEntry, type BitbucketParticipant, type BitbucketProject, type BitbucketPullRequest, type BitbucketPullRequestActivity, type BitbucketPullRequestComment, type BitbucketPullRequestTask, type BitbucketRef, type BitbucketReport, type BitbucketReportData, type BitbucketRepository, type BitbucketRepositorySize, type BitbucketUser, type BitbucketUserPermission, type BranchesParams, type ChangeNodeType, type ChangeType, type ChangesParams, type CommitsParams, type LastModifiedParams, type PagedResponse, type PaginationParams, ProjectResource, type ProjectUsersParams, type ProjectsParams, type PullRequestActivityAction, PullRequestResource, type PullRequestTaskAnchor, type PullRequestTaskPermittedOperations, type PullRequestTaskState, type PullRequestsParams, type RawFileParams, type ReportDataType, type ReportResult, type ReportsParams, type ReposParams, RepositoryResource, Security, type TasksParams, UserResource, type UsersParams };