bitbucket-data-center-client 1.4.0 → 1.4.2

package/README.md

@@ -1,13 +1,6 @@
 # Bitbucket Data Center Client
 
-A TypeScript client library for Bitbucket Server/Data Center REST API. This library provides a simple, type-safe interface for interacting with Bitbucket Server's REST API.
-
-## Features
-
-- 🔒 **Type-safe**: Full TypeScript support with comprehensive type definitions
-- 🚀 **Simple**: Clean, intuitive API design
-- 📦 **Lightweight**: Minimal dependencies (only axios)
-- 🎯 **Complete**: Covers users, projects, repositories, and pull requests operations
+TypeScript client for Bitbucket Server/Data Center REST API.
 
 ## Installation
 
@@ -15,552 +8,89 @@ A TypeScript client library for Bitbucket Server/Data Center REST API. This libr
 npm install bitbucket-data-center-client
 ```
 
-## Quick Start
+## Usage
 
 ```typescript
 import { BitbucketClient } from 'bitbucket-data-center-client';
 
-// Initialize the client
 const client = new BitbucketClient({
+  baseUrl: 'https://bitbucket.example.com',
   token: 'your-personal-access-token',
-  baseUrl: 'https://bitbucket.example.com'
 });
 
 // Get user profile
-const user = await client.getUserProfile({ username: 'john.doe' });
-console.log(user.displayName);
+const user = await client.users.getProfile({ username: 'john.doe' });
 
 // List projects
-const projects = await client.listProjects({ limit: 10 });
-projects.values.forEach(project => {
-  console.log(`${project.key}: ${project.name}`);
-});
-
-// Get pull requests in your inbox
-const prs = await client.getInboxPullRequests({ limit: 25 });
-prs.values.forEach(pr => {
-  console.log(`PR #${pr.id}: ${pr.title}`);
-});
-```
-
-## Authentication
-
-The client uses **Bearer token authentication** with Bitbucket Personal Access Tokens:
-
-1. Generate a Personal Access Token in Bitbucket Server:
-   - Navigate to **Profile → Manage account → Personal access tokens**
-   - Create a token with appropriate permissions (e.g., `REPO_READ`, `REPO_WRITE`)
-2. Pass the token and base URL to the client constructor
-
-```typescript
-// Simple configuration (most common)
-const client = new BitbucketClient({
-  token: process.env.BITBUCKET_TOKEN!,
-  baseUrl: process.env.BITBUCKET_URL! // e.g., 'https://bitbucket.example.com'
-});
+const projects = await client.projects.list();
 
-// Advanced: with custom axios configuration
-const client = new BitbucketClient({
-  token: process.env.BITBUCKET_TOKEN!,
-  baseUrl: process.env.BITBUCKET_URL!,
-  axiosConfig: {
-    timeout: 10000,
-    headers: {
-      'X-Custom-Header': 'value'
-    }
-  }
-});
-```
-
-## API Reference
-
-### User Operations
-
-#### Get User Profile
-
-```typescript
-const user = await client.getUserProfile({
-  username: 'john.doe'
-});
-console.log(user.displayName, user.emailAddress);
-```
-
-#### Get All Users
+// List repositories in a project
+const repos = await client.repositories.list({ projectKey: 'PROJ' });
 
-```typescript
-const users = await client.getAllUsers({
-  filter: 'john' // Optional: filter by username, name, or email
-});
-```
-
-### Project Operations
-
-#### List Projects
-
-```typescript
-const projects = await client.listProjects({
-  name: 'MyProject',           // Optional: filter by name
-  permission: 'PROJECT_WRITE', // Optional: filter by permission
-  start: 0,                    // Optional: pagination start
-  limit: 25                    // Optional: page size
-});
-```
-
-### Repository Operations
-
-#### List Repositories
-
-```typescript
-const repos = await client.listRepositories({
-  projectKey: 'PROJ'
-});
-repos.values.forEach(repo => {
-  console.log(`${repo.slug}: ${repo.name}`);
-});
-```
-
-#### Get Repository
-
-```typescript
-const repo = await client.getRepository({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo'
-});
-console.log(`ID: ${repo.id}, Name: ${repo.name}`);
-```
-
-### Pull Request Operations
-
-#### Get Inbox Pull Requests
-
-Get all PRs where you're assigned as a reviewer:
-
-```typescript
-const prs = await client.getInboxPullRequests({
-  start: 0,
-  limit: 25
-});
-```
-
-#### Get Pull Request Details
-
-```typescript
-const pr = await client.getPullRequest({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123
-});
-console.log(pr.title, pr.author?.user.displayName);
-```
-
-#### Create Pull Request
-
-Create a new pull request. Branch names are automatically converted to full refs:
-
-```typescript
-// Simple same-repo PR
-const pr = await client.createPullRequest({
+// Browse repository contents
+const contents = await client.repositories.browse({
   projectKey: 'PROJ',
   repositorySlug: 'my-repo',
-  title: 'Add new feature',
-  description: 'This PR adds the new feature as discussed',
-  fromBranch: 'feature-branch',  // Just the branch name
-  toBranch: 'main'
+  path: 'src',
 });
 
-// PR with reviewers
-const prWithReviewers = await client.createPullRequest({
+// Get raw file content
+const file = await client.repositories.getRawContent({
   projectKey: 'PROJ',
   repositorySlug: 'my-repo',
-  title: 'Fix critical bug',
-  description: 'Fixes issue #123',
-  fromBranch: 'bugfix/critical-issue',
-  toBranch: 'develop',
-  reviewers: ['john.doe', 'jane.smith']
-});
-
-// Draft PR
-const draftPr = await client.createPullRequest({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  title: 'WIP: Refactor authentication',
-  fromBranch: 'wip/auth-refactor',
-  toBranch: 'main',
-  draft: true
-});
-
-// Cross-repo PR (from fork to upstream)
-const crossRepoPr = await client.createPullRequest({
-  projectKey: 'UPSTREAM',
-  repositorySlug: 'upstream-repo',
-  title: 'Contribution from fork',
-  fromBranch: 'feature',
-  toBranch: 'main',
-  fromRepositorySlug: 'my-fork',
-  fromProjectKey: 'MYPROJ'
-});
-```
-
-#### Get Required/Default Reviewers
-
-Get the list of default reviewers for a PR before creating it. **Important:** Default reviewers are NOT automatically added when creating PRs via API - you must fetch them and pass them explicitly.
-
-Use `getRepository()` to obtain the repository ID:
-
-```typescript
-// First get the repository to obtain its ID
-const repo = await client.getRepository({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo'
+  path: 'package.json',
 });
 
-// Get default reviewers for a specific source/target branch combination
-const reviewers = await client.getRequiredReviewers({
+// Get pull request details
+const pr = await client.pullRequests.get({
   projectKey: 'PROJ',
   repositorySlug: 'my-repo',
-  repositoryId: repo.id,
-  sourceBranch: 'feature-branch',
-  targetBranch: 'main'
+  pullRequestId: 123,
 });
 
-console.log('Required reviewers:', reviewers.map(r => r.displayName));
-
-// Create PR with default reviewers
-const pr = await client.createPullRequest({
+// Create a pull request
+const newPr = await client.pullRequests.create({
   projectKey: 'PROJ',
   repositorySlug: 'my-repo',
-  title: 'My feature',
   fromBranch: 'feature-branch',
   toBranch: 'main',
-  reviewers: reviewers.map(r => r.name)
-});
-```
-
-#### Get Pull Request Changes
-
-Get list of changed files:
-
-```typescript
-const changes = await client.getPullRequestChanges({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123
-});
-changes.values.forEach(change => {
-  console.log(`${change.type}: ${change.path?.toString}`);
-});
-```
-
-#### Get Pull Request Diff
-
-Get diff for entire PR or specific file:
-
-```typescript
-// Full PR diff (text format)
-const textDiff = await client.getPullRequestDiff({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  format: 'text'
-});
-
-// Structured diff for specific file
-const structuredDiff = await client.getPullRequestDiff({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  path: 'src/index.ts',
-  format: 'json',
-  contextLines: 3
-});
-```
-
-#### Get File Diff with Line Numbers
-
-Get structured line-by-line diff for a specific file:
-
-```typescript
-const diff = await client.getPullRequestFileDiff({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  path: 'src/main.ts',
-  contextLines: 10
-});
-
-// Access hunks and segments
-diff.diffs[0]?.hunks?.forEach(hunk => {
-  hunk.segments.forEach(segment => {
-    segment.lines.forEach(line => {
-      console.log(`Line ${line.destination}: ${line.line}`);
-    });
-  });
-});
-```
-
-#### Get Pull Request Activities
-
-Get PR activity (comments, approvals, etc.):
-
-```typescript
-const activities = await client.getPullRequestActivities({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  activityTypes: ['COMMENTED', 'REVIEW_COMMENTED'], // Optional filter
-  start: 0,
-  limit: 25
-});
-
-activities.values.forEach(activity => {
-  console.log(`${activity.action}: ${activity.comment?.text}`);
-});
-```
-
-#### Add Pull Request Comment
-
-Add general, file, or line comment:
-
-```typescript
-// General comment
-await client.addPullRequestComment({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  text: 'Looks good to me!'
-});
-
-// File-level comment
-await client.addPullRequestComment({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  text: 'This file needs refactoring',
-  path: 'src/main.ts'
-});
-
-// Inline comment on specific line
-await client.addPullRequestComment({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  text: 'Consider using const here',
-  path: 'src/main.ts',
-  line: 42,
-  lineType: 'ADDED',
-  fileType: 'TO'
-});
-
-// Reply to a comment
-await client.addPullRequestComment({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  text: 'Good catch!',
-  parentId: 456
-});
-```
-
-#### Delete Pull Request Comment
-
-```typescript
-await client.deletePullRequestComment({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  commentId: 456,
-  version: 1 // Get from comment object
-});
-```
-
-#### Update Review Status
-
-Approve, request changes, or remove approval:
-
-```typescript
-// Approve PR
-await client.updateReviewStatus({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  status: 'APPROVED'
-});
-
-// Request changes
-await client.updateReviewStatus({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  status: 'NEEDS_WORK'
-});
-
-// Remove approval
-await client.updateReviewStatus({
-  projectKey: 'PROJ',
-  repositorySlug: 'my-repo',
-  pullRequestId: 123,
-  status: 'UNAPPROVED'
+  title: 'Add new feature',
+  reviewers: ['reviewer1', 'reviewer2'],
 });
-```
-
-#### Add/Remove Comment Reactions
 
-```typescript
-// Add reaction
-await client.addPullRequestCommentReaction({
+// Add a comment to a PR
+await client.pullRequests.addComment({
   projectKey: 'PROJ',
   repositorySlug: 'my-repo',
   pullRequestId: 123,
-  commentId: 456,
-  emoticon: 'thumbsup' // thumbsup, thumbsdown, heart, thinking_face, laughing
+  text: 'Looks good!',
 });
 
-// Remove reaction
-await client.removePullRequestCommentReaction({
+// Approve a PR
+await client.pullRequests.updateReviewStatus({
   projectKey: 'PROJ',
   repositorySlug: 'my-repo',
   pullRequestId: 123,
-  commentId: 456,
-  emoticon: 'thumbsup'
-});
-```
-
-## Complete Example: PR Review Workflow
-
-```typescript
-import { BitbucketClient } from 'bitbucket-data-center-client';
-
-const client = new BitbucketClient({
-  token: process.env.BITBUCKET_TOKEN!,
-  baseUrl: process.env.BITBUCKET_URL!
+  status: 'APPROVED',
 });
-
-async function reviewPullRequest() {
-  // 1. Get PRs in your inbox
-  const inbox = await client.getInboxPullRequests({ limit: 10 });
-  const pr = inbox.values[0];
-
-  if (!pr) {
-    console.log('No PRs to review');
-    return;
-  }
-
-  console.log(`Reviewing: ${pr.title}`);
-
-  // 2. Get PR details
-  const projectKey = pr.toRef.repository.project.key;
-  const repositorySlug = pr.toRef.repository.slug;
-  const pullRequestId = pr.id;
-
-  // 3. Get changed files
-  const changes = await client.getPullRequestChanges({
-    projectKey,
-    repositorySlug,
-    pullRequestId
-  });
-
-  console.log(`Changed files: ${changes.values.length}`);
-
-  // 4. Review each file
-  for (const change of changes.values) {
-    const path = change.path?.toString;
-    if (!path) continue;
-
-    // Get file diff
-    const diff = await client.getPullRequestFileDiff({
-      projectKey,
-      repositorySlug,
-      pullRequestId,
-      path
-    });
-
-    // Check for issues and add comments
-    diff.diffs[0]?.hunks?.forEach(hunk => {
-      hunk.segments.forEach(segment => {
-        if (segment.type === 'ADDED') {
-          segment.lines.forEach(line => {
-            if (line.line?.includes('console.log')) {
-              // Add inline comment
-              client.addPullRequestComment({
-                projectKey,
-                repositorySlug,
-                pullRequestId,
-                text: 'Please remove console.log before merging',
-                path,
-                line: line.destination!,
-                lineType: 'ADDED',
-                fileType: 'TO'
-              });
-            }
-          });
-        }
-      });
-    });
-  }
-
-  // 5. Approve or request changes
-  await client.updateReviewStatus({
-    projectKey,
-    repositorySlug,
-    pullRequestId,
-    status: 'NEEDS_WORK'
-  });
-
-  console.log('Review complete!');
-}
-
-reviewPullRequest().catch(console.error);
 ```
 
-## Type Definitions
+## API Structure
 
-This library exports comprehensive TypeScript types for all API entities:
+| Domain | Methods |
+|--------|---------|
+| `client.users` | `getProfile`, `getAll` |
+| `client.projects` | `list` |
+| `client.repositories` | `list`, `get`, `browse`, `getRawContent`, `checkPermissions` |
+| `client.pullRequests` | `getInbox`, `getDashboard`, `get`, `create`, `getChanges`, `getDiff`, `getFileDiff`, `getActivities`, `addComment`, `deleteComment`, `updateReviewStatus`, `addReaction`, `removeReaction`, `getRequiredReviewers` |
 
-```typescript
-import type {
-  // Common
-  PaginatedResponse,
-  // User & Project
-  RestUser,
-  RestProject,
-  RestRepository,
-  // Pull Request
-  RestPullRequest,
-  InboxPullRequest,
-  RestComment,
-  RestChange,
-  DiffResponse,
-  RestPullRequestActivity,
-  // Method parameters
-  GetPullRequestParams,
-  AddPullRequestCommentParams,
-  UpdateReviewStatusParams,
-  // ... and many more
-} from 'bitbucket-data-center-client';
-```
-
-See [types.ts](./src/types.ts) for the complete list of exported types.
-
-## API Documentation
-
-This library is based on the official Bitbucket Server REST API. See `BitbucketServerSwagger.json` in this package for the complete API specification.
-
-## Error Handling
+## Authentication
 
-The client throws axios errors for failed requests:
+Generate a Personal Access Token in Bitbucket: **Profile > Manage account > Personal access tokens**
 
-```typescript
-try {
-  const pr = await client.getPullRequest({
-    projectKey: 'PROJ',
-    repositorySlug: 'my-repo',
-    pullRequestId: 999
-  });
-} catch (error) {
-  if (axios.isAxiosError(error)) {
-    console.error('API Error:', error.response?.data);
-  }
-}
+```bash
+export BITBUCKET_URL=https://bitbucket.example.com
+export BITBUCKET_TOKEN=your-personal-access-token
 ```
 
 ## Requirements
@@ -571,13 +101,3 @@ try {
 ## License
 
 MIT
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request.
-
-## Support
-
-For issues and questions:
-- GitHub Issues: [your-repo-url]
-- Documentation: See inline JSDoc comments in the source code

package/dist/api/base.d.ts

@@ -0,0 +1,11 @@
+import { type AxiosInstance } from 'axios';
+import type { BitbucketClientConfig } from '../types/common.js';
+/**
+ * Base API class providing shared axios configuration for all domain APIs.
+ */
+export declare class BaseApi {
+    protected client: AxiosInstance;
+    protected baseUrl: string;
+    constructor(config: BitbucketClientConfig);
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/api/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/api/base.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAClD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE;;GAEG;AACH,qBAAa,OAAO;IAClB,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAChC,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEP,MAAM,EAAE,qBAAqB;CAcjD"}

package/dist/api/base.js

@@ -0,0 +1,22 @@
+import axios from 'axios';
+/**
+ * Base API class providing shared axios configuration for all domain APIs.
+ */
+export class BaseApi {
+    client;
+    baseUrl;
+    constructor(config) {
+        const { token, baseUrl, axiosConfig = {} } = config;
+        this.baseUrl = baseUrl;
+        this.client = axios.create({
+            ...axiosConfig,
+            baseURL: `${baseUrl}/rest/api/latest`,
+            headers: {
+                ...axiosConfig.headers,
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+        });
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/api/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/api/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAA6B,MAAM,OAAO,CAAC;AAGlD;;GAEG;AACH,MAAM,OAAO,OAAO;IACR,MAAM,CAAgB;IACtB,OAAO,CAAS;IAE1B,YAAmB,MAA6B;QAC9C,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,GAAG,EAAE,EAAE,GAAG,MAAM,CAAC;QACpD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEvB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YACzB,GAAG,WAAW;YACd,OAAO,EAAE,GAAG,OAAO,kBAAkB;YACrC,OAAO,EAAE;gBACP,GAAG,WAAW,CAAC,OAAO;gBACtB,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,cAAc,EAAE,kBAAkB;aACnC;SACF,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/api/index.d.ts

@@ -0,0 +1,6 @@
+export { BaseApi } from './base.js';
+export { ProjectsApi } from './projects.js';
+export { PullRequestsApi } from './pull-requests.js';
+export { RepositoriesApi } from './repositories.js';
+export { UsersApi } from './users.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,6 @@
+export { BaseApi } from './base.js';
+export { ProjectsApi } from './projects.js';
+export { PullRequestsApi } from './pull-requests.js';
+export { RepositoriesApi } from './repositories.js';
+export { UsersApi } from './users.js';
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/api/projects.d.ts

@@ -0,0 +1,14 @@
+import { BaseApi } from './base.js';
+import type { PaginatedResponse } from '../types/common.js';
+import type { ListProjectsParams, RestProject } from '../types/project.js';
+/**
+ * Projects API for Bitbucket Server.
+ * Provides methods for project-related operations.
+ */
+export declare class ProjectsApi extends BaseApi {
+    /**
+     * List projects, optionally filtered by name or permission
+     */
+    list(params?: ListProjectsParams): Promise<PaginatedResponse<RestProject>>;
+}
+//# sourceMappingURL=projects.d.ts.map

package/dist/api/projects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/api/projects.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE3E;;;GAGG;AACH,qBAAa,WAAY,SAAQ,OAAO;IACtC;;OAEG;IACU,IAAI,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;CAMxF"}