bitbucket-datacenter-api-client 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -85,6 +85,48 @@ interface ReposParams extends PaginationParams {
85
85
  permission?: string;
86
86
  }
87
87
 
88
+ /**
89
+ * Represents a Bitbucket Data Center user.
90
+ */
91
+ interface BitbucketUser {
92
+ name: string;
93
+ emailAddress: string;
94
+ id: number;
95
+ displayName: string;
96
+ active: boolean;
97
+ slug: string;
98
+ type: 'NORMAL' | 'SERVICE';
99
+ links: Record<string, unknown>;
100
+ }
101
+ /**
102
+ * A user with an explicit permission on a project.
103
+ */
104
+ interface BitbucketUserPermission {
105
+ user: BitbucketUser;
106
+ permission: 'PROJECT_READ' | 'PROJECT_WRITE' | 'PROJECT_ADMIN';
107
+ }
108
+ /**
109
+ * Query parameters accepted by `GET /rest/api/latest/users`.
110
+ *
111
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-users/#api-api-latest-users-get}
112
+ */
113
+ interface UsersParams extends PaginationParams {
114
+ /** Filter results by display name or username (prefix match) */
115
+ filter?: string;
116
+ }
117
+ /**
118
+ * Query parameters accepted by
119
+ * `GET /rest/api/latest/projects/{key}/permissions/users`.
120
+ *
121
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-project/#api-api-latest-projects-projectkey-permissions-users-get}
122
+ */
123
+ interface ProjectUsersParams extends PaginationParams {
124
+ /** Filter results by display name or username (prefix match) */
125
+ filter?: string;
126
+ /** Filter by the permission level on the project */
127
+ permission?: 'PROJECT_READ' | 'PROJECT_WRITE' | 'PROJECT_ADMIN';
128
+ }
129
+
88
130
  /** A git ref (branch or tag) as referenced in a pull request. */
89
131
  interface BitbucketRef {
90
132
  id: string;
@@ -205,6 +247,139 @@ interface CommitsParams extends PaginationParams {
205
247
  ignoreMissing?: boolean;
206
248
  }
207
249
 
250
+ /**
251
+ * Represents a git branch in a Bitbucket Data Center repository.
252
+ */
253
+ interface BitbucketBranch {
254
+ /** Full ref name (e.g., `'refs/heads/main'`) */
255
+ id: string;
256
+ /** Short branch name (e.g., `'main'`) */
257
+ displayId: string;
258
+ type: 'BRANCH';
259
+ /** SHA of the latest commit on this branch */
260
+ latestCommit: string;
261
+ latestChangeset: string;
262
+ /** Whether this is the repository's default branch */
263
+ isDefault: boolean;
264
+ }
265
+ /**
266
+ * Query parameters accepted by
267
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/branches`.
268
+ *
269
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-branches-get}
270
+ */
271
+ interface BranchesParams extends PaginationParams {
272
+ /** Filter branches by name (prefix match) */
273
+ filterText?: string;
274
+ /** Sort order of results */
275
+ orderBy?: 'ALPHABETICAL' | 'MODIFICATION';
276
+ /** Include branch metadata such as ahead/behind counts relative to `base` */
277
+ details?: boolean;
278
+ /**
279
+ * Base branch or commit to use for ahead/behind comparisons
280
+ * when `details` is `true`
281
+ */
282
+ base?: string;
283
+ /** Boost exact matches to the top of the results when filtering */
284
+ boostMatches?: boolean;
285
+ }
286
+
287
+ /**
288
+ * Size information for a Bitbucket repository.
289
+ *
290
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-sizes-get}
291
+ */
292
+ interface BitbucketRepositorySize {
293
+ /** Size of the repository in bytes */
294
+ repository: number;
295
+ /** Size of attachments in bytes */
296
+ attachments: number;
297
+ }
298
+
299
+ /** The type of change applied to a file in a pull request. */
300
+ type ChangeType = 'ADD' | 'COPY' | 'DELETE' | 'MODIFY' | 'MOVE' | 'RENAME' | 'UNKNOWN';
301
+ /** The node type of the changed entry. */
302
+ type ChangeNodeType = 'FILE' | 'DIRECTORY' | 'SUBMODULE';
303
+ /** Represents a file path in a Bitbucket change entry. */
304
+ interface BitbucketChangePath {
305
+ /** Path segments (e.g., `['src', 'index.ts']`) */
306
+ components: string[];
307
+ /** Parent directory (e.g., `'src'`) */
308
+ parent: string;
309
+ /** File name (e.g., `'index.ts'`) */
310
+ name: string;
311
+ /** File extension (e.g., `'ts'`) */
312
+ extension: string;
313
+ /** Full path string (e.g., `'src/index.ts'`) */
314
+ toString: string;
315
+ }
316
+ /**
317
+ * Represents a single file change within a Bitbucket Data Center pull request.
318
+ */
319
+ interface BitbucketChange {
320
+ /** Content ID (SHA) of the file in the destination ref */
321
+ contentId?: string;
322
+ /** Content ID (SHA) of the file in the source ref */
323
+ fromContentId?: string;
324
+ /** Path of the changed file in the destination ref */
325
+ path: BitbucketChangePath;
326
+ /** Original path before a rename or move (only present for `RENAME` and `MOVE`) */
327
+ srcPath?: BitbucketChangePath;
328
+ /** Whether the file has the executable bit set in the destination ref */
329
+ executable: boolean;
330
+ /** Whether the file had the executable bit set in the source ref */
331
+ srcExecutable: boolean;
332
+ percentUnchanged: number;
333
+ type: ChangeType;
334
+ nodeType: ChangeNodeType;
335
+ links: Record<string, unknown>;
336
+ }
337
+ /**
338
+ * Query parameters accepted by
339
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/changes`.
340
+ *
341
+ * @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}
342
+ */
343
+ interface ChangesParams extends PaginationParams {
344
+ /**
345
+ * When `true`, includes the number of comments for each changed file.
346
+ * @default false
347
+ */
348
+ withComments?: boolean;
349
+ }
350
+
351
+ /**
352
+ * Represents a file entry returned by the last-modified endpoint,
353
+ * showing the path and the commit that last touched it.
354
+ */
355
+ interface BitbucketLastModifiedEntry {
356
+ /** The file path */
357
+ path: BitbucketChangePath;
358
+ /** The commit that last modified this file */
359
+ latestCommit: BitbucketCommit;
360
+ }
361
+ /**
362
+ * Query parameters accepted by
363
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/last-modified`.
364
+ *
365
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-last-modified-get}
366
+ */
367
+ interface LastModifiedParams extends PaginationParams {
368
+ /** Branch, tag, or commit SHA to use as the base ref */
369
+ at?: string;
370
+ }
371
+
372
+ /**
373
+ * Query parameters accepted by
374
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/raw/{path}`.
375
+ *
376
+ * @see {@link https://developer.atlassian.com/server/bitbucket/rest/v819/api-group-repository/#api-api-latest-projects-projectkey-repos-repositoryslug-raw-path-get}
377
+ */
378
+ interface RawFileParams {
379
+ /** Branch, tag, or commit SHA to retrieve the file at */
380
+ at?: string;
381
+ }
382
+
208
383
  /** Minimal user shape used inside activity records. */
209
384
  interface BitbucketActivityUser {
210
385
  name: string;
@@ -287,6 +462,127 @@ interface ActivitiesParams extends PaginationParams {
287
462
  fromType?: 'COMMENT' | 'ACTIVITY';
288
463
  }
289
464
 
465
+ /** The state of a pull request task. */
466
+ type PullRequestTaskState = 'OPEN' | 'RESOLVED';
467
+ /** Operations the authenticated user is permitted to perform on a task. */
468
+ interface PullRequestTaskPermittedOperations {
469
+ editable: boolean;
470
+ deletable: boolean;
471
+ transitionable: boolean;
472
+ }
473
+ /** The comment anchor to which a task is attached. */
474
+ interface PullRequestTaskAnchor {
475
+ id: number;
476
+ type: {
477
+ id: 'COMMENT';
478
+ };
479
+ }
480
+ /**
481
+ * Represents a task (review to-do item) on a Bitbucket Data Center pull request.
482
+ *
483
+ * Tasks are created by reviewers on specific comments and can be either `OPEN` or `RESOLVED`.
484
+ */
485
+ interface BitbucketPullRequestTask {
486
+ id: number;
487
+ createdDate: number;
488
+ author: BitbucketActivityUser;
489
+ text: string;
490
+ state: PullRequestTaskState;
491
+ permittedOperations: PullRequestTaskPermittedOperations;
492
+ /** The comment the task is anchored to */
493
+ anchor: PullRequestTaskAnchor;
494
+ }
495
+ /**
496
+ * Query parameters accepted by
497
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/tasks`.
498
+ *
499
+ * @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}
500
+ */
501
+ interface TasksParams extends PaginationParams {
502
+ }
503
+
504
+ /** The overall result of a Code Insights report. */
505
+ type ReportResult = 'PASS' | 'FAIL';
506
+ /** The data types supported for report data items. */
507
+ type ReportDataType = 'BOOLEAN' | 'DATE' | 'DURATION' | 'LINK' | 'NUMBER' | 'PERCENTAGE' | 'TEXT';
508
+ /** A single data point included in a Code Insights report. */
509
+ interface BitbucketReportData {
510
+ title: string;
511
+ type: ReportDataType;
512
+ value: string | number | boolean | {
513
+ href: string;
514
+ text?: string;
515
+ };
516
+ }
517
+ /**
518
+ * Represents a Code Insights report attached to a pull request in Bitbucket Data Center.
519
+ *
520
+ * Reports are created by external tools (CI, static analysis, coverage) and
521
+ * displayed in the pull request overview.
522
+ */
523
+ interface BitbucketReport {
524
+ /** Unique key identifying the report */
525
+ key: string;
526
+ title: string;
527
+ details?: string;
528
+ /** Overall result of the report */
529
+ result?: ReportResult;
530
+ /** Name of the tool or service that created the report */
531
+ reporter?: string;
532
+ /** Link to the full external report */
533
+ link?: string;
534
+ /** URL of the logo shown in the Bitbucket UI */
535
+ logoUrl?: string;
536
+ /** Structured data points displayed in the report */
537
+ data?: BitbucketReportData[];
538
+ createdDate: number;
539
+ updatedDate: number;
540
+ }
541
+ /**
542
+ * Query parameters accepted by
543
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/reports`.
544
+ *
545
+ * @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}
546
+ */
547
+ interface ReportsParams extends PaginationParams {
548
+ }
549
+
550
+ /**
551
+ * Aggregated build counts for a single commit hash.
552
+ */
553
+ interface BitbucketBuildCount {
554
+ successful: number;
555
+ failed: number;
556
+ inProgress: number;
557
+ cancelled: number;
558
+ unknown: number;
559
+ }
560
+ /**
561
+ * Response from the build-summaries endpoint: a map of commit hash → build counts.
562
+ *
563
+ * Each key is a full commit SHA and the value contains the aggregated count of
564
+ * builds in each state for that commit.
565
+ *
566
+ * @example
567
+ * ```ts
568
+ * {
569
+ * "abc123def456": { successful: 2, failed: 0, inProgress: 0, cancelled: 0, unknown: 0 },
570
+ * "def456abc123": { successful: 0, failed: 1, inProgress: 1, cancelled: 0, unknown: 0 }
571
+ * }
572
+ * ```
573
+ */
574
+ type BitbucketBuildSummaries = Record<string, BitbucketBuildCount>;
575
+
576
+ /**
577
+ * Represents a Jira issue linked to a Bitbucket Data Center pull request.
578
+ */
579
+ interface BitbucketIssue {
580
+ /** The Jira issue key (e.g., `'ABC-123'`) */
581
+ key: string;
582
+ /** The URL to the issue in Jira */
583
+ url: string;
584
+ }
585
+
290
586
  /**
291
587
  * Represents a Bitbucket pull request resource with chainable async methods.
292
588
  *
@@ -301,12 +597,23 @@ interface ActivitiesParams extends PaginationParams {
301
597
  * // Get activities
302
598
  * const activities = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).activities();
303
599
  *
304
- * // With filters
305
- * const comments = await bbClient
306
- * .project('PROJ')
307
- * .repo('my-repo')
308
- * .pullRequest(42)
309
- * .activities({ fromId: 10, fromType: 'COMMENT' });
600
+ * // Get tasks
601
+ * const tasks = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).tasks();
602
+ *
603
+ * // Get commits
604
+ * const commits = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).commits();
605
+ *
606
+ * // Get changes
607
+ * const changes = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).changes();
608
+ *
609
+ * // Get reports
610
+ * const reports = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).reports();
611
+ *
612
+ * // Get build summaries
613
+ * const builds = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).buildSummaries();
614
+ *
615
+ * // Get linked Jira issues
616
+ * const issues = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).issues();
310
617
  * ```
311
618
  */
312
619
  declare class PullRequestResource implements PromiseLike<BitbucketPullRequest> {
@@ -338,6 +645,63 @@ declare class PullRequestResource implements PromiseLike<BitbucketPullRequest> {
338
645
  * @returns An array of pull request activities, ordered from most recent to oldest
339
646
  */
340
647
  activities(params?: ActivitiesParams): Promise<BitbucketPullRequestActivity[]>;
648
+ /**
649
+ * Fetches the tasks (review to-do items) for this pull request.
650
+ *
651
+ * Tasks are created by reviewers on specific comments and can be `OPEN` or `RESOLVED`.
652
+ *
653
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/tasks`
654
+ *
655
+ * @param params - Optional filters: `limit`, `start`
656
+ * @returns An array of pull request tasks
657
+ */
658
+ tasks(params?: TasksParams): Promise<BitbucketPullRequestTask[]>;
659
+ /**
660
+ * Fetches the commits included in this pull request.
661
+ *
662
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/commits`
663
+ *
664
+ * @param params - Optional pagination: `limit`, `start`
665
+ * @returns An array of commits
666
+ */
667
+ commits(params?: PaginationParams): Promise<BitbucketCommit[]>;
668
+ /**
669
+ * Fetches the file changes included in this pull request.
670
+ *
671
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/changes`
672
+ *
673
+ * @param params - Optional filters: `limit`, `start`, `withComments`
674
+ * @returns An array of file changes
675
+ */
676
+ changes(params?: ChangesParams): Promise<BitbucketChange[]>;
677
+ /**
678
+ * Fetches the Code Insights reports for this pull request.
679
+ *
680
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/reports`
681
+ *
682
+ * @param params - Optional pagination: `limit`, `start`
683
+ * @returns An array of Code Insights reports
684
+ */
685
+ reports(params?: ReportsParams): Promise<BitbucketReport[]>;
686
+ /**
687
+ * Fetches the aggregated build summaries for this pull request.
688
+ *
689
+ * Returns a map of commit hash → build counts per state
690
+ * (`successful`, `failed`, `inProgress`, `cancelled`, `unknown`).
691
+ *
692
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/build-summaries`
693
+ *
694
+ * @returns A record keyed by commit SHA with aggregated build counts
695
+ */
696
+ buildSummaries(): Promise<BitbucketBuildSummaries>;
697
+ /**
698
+ * Fetches the Jira issues linked to this pull request.
699
+ *
700
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/pull-requests/{id}/issues`
701
+ *
702
+ * @returns An array of linked Jira issues
703
+ */
704
+ issues(): Promise<BitbucketIssue[]>;
341
705
  }
342
706
 
343
707
  /**
@@ -363,11 +727,12 @@ declare class PullRequestResource implements PromiseLike<BitbucketPullRequest> {
363
727
  */
364
728
  declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
365
729
  private readonly request;
730
+ private readonly requestText;
366
731
  private readonly projectKey;
367
732
  private readonly repoSlug;
368
733
  private readonly basePath;
369
734
  /** @internal */
370
- constructor(request: RequestFn, projectKey: string, repoSlug: string);
735
+ constructor(request: RequestFn, requestText: RequestTextFn, projectKey: string, repoSlug: string);
371
736
  /**
372
737
  * Allows the resource to be awaited directly, resolving with the repository info.
373
738
  * Delegates to {@link RepositoryResource.get}.
@@ -399,6 +764,32 @@ declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
399
764
  * @returns An array of commits
400
765
  */
401
766
  commits(params?: CommitsParams): Promise<BitbucketCommit[]>;
767
+ /**
768
+ * Fetches the files last modified in this repository along with the commit that last touched each.
769
+ *
770
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/last-modified`
771
+ *
772
+ * @param params - Optional filters: `limit`, `start`, `at`
773
+ * @returns An array of last-modified entries
774
+ */
775
+ lastModified(params?: LastModifiedParams): Promise<BitbucketLastModifiedEntry[]>;
776
+ /**
777
+ * Fetches the size of this repository.
778
+ *
779
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/sizes`
780
+ *
781
+ * @returns The repository size object
782
+ */
783
+ size(): Promise<BitbucketRepositorySize>;
784
+ /**
785
+ * Fetches branches for this repository.
786
+ *
787
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/branches`
788
+ *
789
+ * @param params - Optional filters: `limit`, `start`, `filterText`, `orderBy`, `details`, `base`, `boostMatches`
790
+ * @returns An array of branches
791
+ */
792
+ branches(params?: BranchesParams): Promise<BitbucketBranch[]>;
402
793
  /**
403
794
  * Returns a {@link PullRequestResource} for a given pull request ID, providing
404
795
  * access to pull request data and sub-resources (activities, etc.).
@@ -415,11 +806,23 @@ declare class RepositoryResource implements PromiseLike<BitbucketRepository> {
415
806
  * const activities = await bbClient.project('PROJ').repo('my-repo').pullRequest(42).activities();
416
807
  * ```
417
808
  */
809
+ /**
810
+ * Fetches the raw content of a file in this repository.
811
+ *
812
+ * `GET /rest/api/latest/projects/{key}/repos/{slug}/raw/{path}`
813
+ *
814
+ * @param filePath - Path to the file (e.g., `'src/index.ts'`)
815
+ * @param params - Optional: `at` (branch, tag, or commit SHA)
816
+ * @returns The raw file content as a string
817
+ */
818
+ raw(filePath: string, params?: RawFileParams): Promise<string>;
418
819
  pullRequest(pullRequestId: number): PullRequestResource;
419
820
  }
420
821
 
421
822
  /** @internal */
422
823
  type RequestFn = <T>(path: string, params?: Record<string, string | number | boolean>) => Promise<T>;
824
+ /** @internal */
825
+ type RequestTextFn = (path: string, params?: Record<string, string | number | boolean>) => Promise<string>;
423
826
  /**
424
827
  * Represents a Bitbucket project resource with chainable async methods.
425
828
  *
@@ -436,13 +839,17 @@ type RequestFn = <T>(path: string, params?: Record<string, string | number | boo
436
839
  *
437
840
  * // Navigate into a specific repository
438
841
  * const prs = await bbClient.project('PROJ').repo('my-repo').pullRequests();
842
+ *
843
+ * // Get users with access to the project
844
+ * const users = await bbClient.project('PROJ').users({ permission: 'PROJECT_WRITE' });
439
845
  * ```
440
846
  */
441
847
  declare class ProjectResource implements PromiseLike<BitbucketProject> {
442
848
  private readonly request;
849
+ private readonly requestText;
443
850
  private readonly key;
444
851
  /** @internal */
445
- constructor(request: RequestFn, key: string);
852
+ constructor(request: RequestFn, requestText: RequestTextFn, key: string);
446
853
  /**
447
854
  * Allows the resource to be awaited directly, resolving with the project info.
448
855
  * Delegates to {@link ProjectResource.get}.
@@ -483,14 +890,57 @@ declare class ProjectResource implements PromiseLike<BitbucketProject> {
483
890
  * ```
484
891
  */
485
892
  repo(repoSlug: string): RepositoryResource;
893
+ /**
894
+ * Fetches users with explicit permissions on this project.
895
+ *
896
+ * `GET /rest/api/latest/projects/{key}/permissions/users`
897
+ *
898
+ * @param params - Optional filters: `limit`, `start`, `filter`, `permission`
899
+ * @returns An array of user–permission pairs
900
+ */
901
+ users(params?: ProjectUsersParams): Promise<BitbucketUserPermission[]>;
902
+ }
903
+
904
+ /**
905
+ * Represents a Bitbucket user resource.
906
+ *
907
+ * Implements `PromiseLike<BitbucketUser>` so it can be awaited directly
908
+ * to fetch user info.
909
+ *
910
+ * @example
911
+ * ```typescript
912
+ * // Await directly to get user info
913
+ * const user = await bbClient.user('pilmee');
914
+ * ```
915
+ */
916
+ declare class UserResource implements PromiseLike<BitbucketUser> {
917
+ private readonly request;
918
+ private readonly basePath;
919
+ /** @internal */
920
+ constructor(request: RequestFn, slug: string);
921
+ /**
922
+ * Allows the resource to be awaited directly, resolving with the user info.
923
+ * Delegates to {@link UserResource.get}.
924
+ */
925
+ then<TResult1 = BitbucketUser, TResult2 = never>(onfulfilled?: ((value: BitbucketUser) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
926
+ /**
927
+ * Fetches the user details.
928
+ *
929
+ * `GET /rest/api/latest/users/{slug}`
930
+ *
931
+ * @returns The user object
932
+ */
933
+ get(): Promise<BitbucketUser>;
486
934
  }
487
935
 
488
936
  /**
489
937
  * Constructor options for {@link BitbucketClient}.
490
938
  */
491
939
  interface BitbucketClientOptions {
492
- /** The base URL of the Bitbucket Data Center instance (e.g., `https://bitbucket.example.com`) */
940
+ /** The host URL of the Bitbucket Data Center instance (e.g., `https://bitbucket.example.com`) */
493
941
  apiUrl: string;
942
+ /** The API path to prepend to every request (e.g., `'rest/api/latest'`) */
943
+ apiPath: string;
494
944
  /** The username to authenticate with */
495
945
  user: string;
496
946
  /** The personal access token or password to authenticate with */
@@ -502,8 +952,9 @@ interface BitbucketClientOptions {
502
952
  * @example
503
953
  * ```typescript
504
954
  * const bbClient = new BitbucketClient({
505
- * apiUrl: 'https://bitbucket.example.com/rest/api/latest',
506
- * user: 'john.doe',
955
+ * apiUrl: 'https://bitbucket.example.com',
956
+ * apiPath: 'rest/api/latest',
957
+ * user: 'pilmee',
507
958
  * token: 'my-token',
508
959
  * });
509
960
  *
@@ -513,15 +964,18 @@ interface BitbucketClientOptions {
513
964
  * const repo = await bbClient.project('PROJ').repo('my-repo');
514
965
  * const prs = await bbClient.project('PROJ').repo('my-repo').pullRequests({ state: 'OPEN' });
515
966
  * const commits = await bbClient.project('PROJ').repo('my-repo').commits({ limit: 10 });
967
+ * const users = await bbClient.users({ filter: 'john' });
968
+ * const user = await bbClient.user('pilmee');
516
969
  * ```
517
970
  */
518
971
  declare class BitbucketClient {
519
972
  private readonly security;
973
+ private readonly apiPath;
520
974
  /**
521
975
  * @param options - Connection and authentication options
522
976
  * @throws {TypeError} If `apiUrl` is not a valid URL
523
977
  */
524
- constructor({ apiUrl, user, token }: BitbucketClientOptions);
978
+ constructor({ apiUrl, apiPath, user, token }: BitbucketClientOptions);
525
979
  /**
526
980
  * Performs an authenticated GET request to the Bitbucket REST API.
527
981
  *
@@ -531,6 +985,7 @@ declare class BitbucketClient {
531
985
  * @internal
532
986
  */
533
987
  private request;
988
+ private requestText;
534
989
  /**
535
990
  * Fetches all projects accessible to the authenticated user.
536
991
  *
@@ -558,6 +1013,30 @@ declare class BitbucketClient {
558
1013
  * ```
559
1014
  */
560
1015
  project(projectKey: string): ProjectResource;
1016
+ /**
1017
+ * Fetches all users accessible to the authenticated user.
1018
+ *
1019
+ * `GET /rest/api/latest/users`
1020
+ *
1021
+ * @param params - Optional filters: `limit`, `start`, `filter`
1022
+ * @returns An array of users
1023
+ */
1024
+ users(params?: UsersParams): Promise<BitbucketUser[]>;
1025
+ /**
1026
+ * Returns a {@link UserResource} for a given user slug, providing access
1027
+ * to user data.
1028
+ *
1029
+ * The returned resource can be awaited directly to fetch user info.
1030
+ *
1031
+ * @param slug - The user slug (e.g., `'pilmee'`)
1032
+ * @returns A chainable user resource
1033
+ *
1034
+ * @example
1035
+ * ```typescript
1036
+ * const user = await bbClient.user('pilmee');
1037
+ * ```
1038
+ */
1039
+ user(slug: string): UserResource;
561
1040
  }
562
1041
 
563
1042
  /**
@@ -609,4 +1088,4 @@ declare class Security {
609
1088
  getHeaders(): Record<string, string>;
610
1089
  }
611
1090
 
612
- 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 };
1091
+ 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 };