bitbucket-datacenter-api-client 1.1.0 → 1.3.0

package/dist/index.d.mts

@@ -15,7 +15,8 @@ interface PaginationParams {
 }
 /**
  * Wrapper returned by Bitbucket paginated list endpoints.
- * @internal
+ *
+ * Use `values` for the items, `isLastPage` and `nextPageStart` for pagination.
  */
 interface PagedResponse<T> {
     values: T[];
@@ -85,6 +86,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 +248,167 @@ 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;
+}
+
+/**
+ * Represents a git tag in a Bitbucket Data Center repository.
+ */
+interface BitbucketTag {
+    /** Full ref name (e.g., `'refs/tags/v1.0.0'`) */
+    id: string;
+    /** Short tag name (e.g., `'v1.0.0'`) */
+    displayId: string;
+    type: 'TAG';
+    /** SHA of the commit this tag points to */
+    latestCommit: string;
+    latestChangeset: string;
+    /** Tag object SHA (only present for annotated tags) */
+    hash?: string;
+}
+/**
+ * Query parameters accepted by
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/tags`.
+ *
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-tags-get}
+ */
+interface TagsParams extends PaginationParams {
+    /** Filter tags by name (prefix match) */
+    filterText?: string;
+    /** Sort order of results */
+    orderBy?: 'ALPHABETICAL' | 'MODIFICATION';
+}
+
+/**
+ * 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;
@@ -287,6 +491,127 @@ interface ActivitiesParams extends PaginationParams {
     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.
  *
@@ -301,12 +626,23 @@ interface ActivitiesParams extends PaginationParams {
  * // Get activities
  * const activities = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).activities();
  *
- * // With filters
- * const comments = await bbClient
- *   .project('PROJ')
- *   .repo('my-repo')
- *   .pullRequest(42)
- *   .activities({ fromId: 10, fromType: 'COMMENT' });
+ * // 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> {
@@ -337,7 +673,64 @@ declare class PullRequestResource implements PromiseLike<BitbucketPullRequest> {
      * @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[]>;
+    activities(params?: ActivitiesParams): Promise<PagedResponse<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<PagedResponse<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<PagedResponse<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<PagedResponse<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<PagedResponse<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[]>;
 }
 
 /**
@@ -363,11 +756,12 @@ declare class PullRequestResource implements PromiseLike<BitbucketPullRequest> {
  */
 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}.
@@ -389,7 +783,7 @@ declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
      * @param params - Optional filters: `limit`, `start`, `state`, `direction`, `at`, `order`
      * @returns An array of pull requests
      */
-    pullRequests(params?: PullRequestsParams): Promise<BitbucketPullRequest[]>;
+    pullRequests(params?: PullRequestsParams): Promise<PagedResponse<BitbucketPullRequest>>;
     /**
      * Fetches commits for this repository.
      *
@@ -398,7 +792,51 @@ declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
      * @param params - Optional filters: `limit`, `start`, `until`, `since`, `path`, `merges`, `followRenames`, `ignoreMissing`
      * @returns An array of commits
      */
-    commits(params?: CommitsParams): Promise<BitbucketCommit[]>;
+    commits(params?: CommitsParams): Promise<PagedResponse<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<PagedResponse<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<PagedResponse<BitbucketBranch>>;
+    /**
+     * Fetches the forks of this repository.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/forks`
+     *
+     * @param params - Optional pagination: `limit`, `start`
+     * @returns A paged response of forked repositories
+     */
+    forks(params?: PaginationParams): Promise<PagedResponse<BitbucketRepository>>;
+    /**
+     * Fetches tags for this repository.
+     *
+     * `GET /rest/api/latest/projects/{key}/repos/{slug}/tags`
+     *
+     * @param params - Optional filters: `limit`, `start`, `filterText`, `orderBy`
+     * @returns A paged response of tags
+     */
+    tags(params?: TagsParams): Promise<PagedResponse<BitbucketTag>>;
     /**
      * Returns a {@link PullRequestResource} for a given pull request ID, providing
      * access to pull request data and sub-resources (activities, etc.).
@@ -415,11 +853,23 @@ declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
      * 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.
  *
@@ -436,13 +886,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}.
@@ -464,7 +918,7 @@ declare class ProjectResource implements PromiseLike<BitbucketProject> {
      * @param params - Optional filters: `limit`, `start`, `slug`, `name`, `permission`
      * @returns An array of repositories
      */
-    repos(params?: ReposParams): Promise<BitbucketRepository[]>;
+    repos(params?: ReposParams): Promise<PagedResponse<BitbucketRepository>>;
     /**
      * Returns a {@link RepositoryResource} for a given repository slug, providing
      * access to repository-level data and sub-resources (pull requests, commits, etc.).
@@ -483,14 +937,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<PagedResponse<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 */
@@ -502,8 +999,9 @@ interface BitbucketClientOptions {
  * @example
  * ```typescript
  * const bbClient = new BitbucketClient({
- *   apiUrl: 'https://bitbucket.example.com/rest/api/latest',
- *   user: 'john.doe',
+ *   apiUrl: 'https://bitbucket.example.com',
+ *   apiPath: 'rest/api/latest',
+ *   user: 'pilmee',
  *   token: 'my-token',
  * });
  *
@@ -513,15 +1011,18 @@ 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.
      *
@@ -531,6 +1032,7 @@ declare class BitbucketClient {
      * @internal
      */
     private request;
+    private requestText;
     /**
      * Fetches all projects accessible to the authenticated user.
      *
@@ -539,7 +1041,7 @@ declare class BitbucketClient {
      * @param params - Optional filters: `limit`, `start`, `name`, `permission`
      * @returns An array of projects
      */
-    projects(params?: ProjectsParams): Promise<BitbucketProject[]>;
+    projects(params?: ProjectsParams): Promise<PagedResponse<BitbucketProject>>;
     /**
      * Returns a {@link ProjectResource} for a given project key, providing access
      * to project-level data and sub-resources.
@@ -558,6 +1060,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<PagedResponse<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;
 }
 
 /**
@@ -609,4 +1135,4 @@ declare class Security {
     getHeaders(): Record<string, string>;
 }
 
-export { type ActivitiesParams, type BitbucketActivityUser, BitbucketClient, type BitbucketClientOptions, type BitbucketCommit, type BitbucketCommitAuthor, type BitbucketParticipant, type BitbucketProject, type BitbucketPullRequest, type BitbucketPullRequestActivity, type BitbucketPullRequestComment, type BitbucketRef, type BitbucketRepository, type CommitsParams, type PagedResponse, type PaginationParams, ProjectResource, type ProjectsParams, type PullRequestActivityAction, PullRequestResource, 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 BitbucketTag, 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 TagsParams, type TasksParams, UserResource, type UsersParams };