@tugudush/bitbucket-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bitbucket MCP Server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# Bitbucket MCP Server
+
+A **read-only** Model Context Protocol (MCP) server that provides secure access to Bitbucket repositories, pull requests, issues, and more. Integrates seamlessly with VS Code GitHub Copilot and Claude Desktop.
+
+## Requirements
+
+- **Code Search**: Enable at https://bitbucket.org/search for `bb_search_code` functionality
+- **Node.js**: Version 16+ with ES modules support
+- **Authentication**: API token + email or username + app password
+
+## Quick Start
+
+### 1. Install & Build
+```bash
+git clone <repository-url>
+cd bitbucket-mcp
+npm install
+npm run build
+```
+
+### 2. Authentication (Optional - for testing only)
+
+**⚠️ Note**: This step is only needed for manual testing. If you're going directly to step 3 (Integration), you can skip this step as authentication is configured in the integration files.
+
+For manual server testing, choose one authentication method:
+
+**API Tokens (Recommended)**
+```bash
+export BITBUCKET_API_TOKEN="your-api-token"
+export BITBUCKET_EMAIL="your-atlassian-email"
+```
+
+**App Passwords (Legacy - deprecated Sept 9, 2025)**
+```bash
+export BITBUCKET_USERNAME="your-username"  
+export BITBUCKET_APP_PASSWORD="your-app-password"
+```
+
+**Without Authentication**: The server will work with public repositories only.
+
+### 3. Integration (Authentication included here)
+
+**For most users, this is where you actually configure authentication credentials.**
+
+**VS Code GitHub Copilot**
+```json
+// .vscode/mcp.json
+{
+  "servers": {
+    "bitbucket-mcp": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/build/index.js"],
+      "env": {
+        "BITBUCKET_API_TOKEN": "your-token",
+        "BITBUCKET_EMAIL": "your@email.com"
+      }
+    }
+  }
+}
+```
+
+**Claude Desktop**
+```json
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "bitbucket": {
+      "command": "node",
+      "args": ["/path/to/build/index.js"],
+      "env": {
+        "BITBUCKET_API_TOKEN": "your-token",
+        "BITBUCKET_EMAIL": "your@email.com"
+      }
+    }
+  }
+}
+```
+
+**💡 Tip**: Replace `/path/to/build/index.js` with the absolute path to your built server, and add your actual Bitbucket credentials to access private repositories.
+
+## Features
+
+**Repository Management**
+- `bb_list_workspaces` - Discover accessible workspaces
+- `bb_list_repositories` - List repositories across workspaces
+- `bb_get_repository` - Get repository details
+- `bb_browse_repository` - Explore directory structure (supports branches with slashes like `feature/SSP-1024`)
+- `bb_get_file_content` - Read files with pagination (1-10,000 lines)
+
+**Pull Requests & Issues**
+- `bb_get_pull_requests`, `bb_get_pull_request` - Browse pull requests
+- `bb_get_pull_request_comments`, `bb_get_pull_request_activity` - Track reviews
+- `bb_get_issues`, `bb_get_issue` - Monitor issues
+
+**Version Control**
+- `bb_get_branches`, `bb_get_commits` - Explore repository history
+
+**Search & Discovery**
+- `bb_search_code` - Advanced code search with language filtering
+- `bb_search_repositories` - Find repositories
+
+**User & Workspace Info**
+- `bb_get_user`, `bb_get_current_user` - User information
+- `bb_get_workspace` - Workspace details
+
+## Usage Examples
+
+**Repository Discovery:**
+- "List all my accessible workspaces"
+- "Browse the root directory of myworkspace/myrepo"
+- "Browse the tests directory in feature/deployment-fixes branch"
+
+**Advanced File Operations:**
+- "Read lines 100-200 of src/app.py from myworkspace/myrepo"
+- "Get the first 50 lines of README.md"
+- "Show me the package.json file with pagination"
+
+**Code Search:**
+- "Search for 'authentication' code in myworkspace/myrepo"
+- "Find all functions containing 'validate' in myworkspace/myrepo"
+- "Search for TypeScript interfaces in myworkspace/myrepo"
+- "Look for 'TODO' comments in myworkspace/myrepo"
+
+**Pull Requests & Issues:**
+- "List repositories in myworkspace"
+- "Show open pull requests for myworkspace/myrepo"
+- "Get README.md from myworkspace/myrepo"
+- "Show recent commits on main branch of myworkspace/myrepo"
+
+## Development
+
+```bash
+npm run ltf     # Lint + Typecheck + Format
+npm run build   # Compile TypeScript  
+npm run watch   # Development mode
+node build/index.js  # Test server
+```
+
+**VS Code Integration:**
+- Install GitHub Copilot extensions
+- Use provided `.vscode/` configuration
+- Open Copilot Chat with `Ctrl+Alt+I`
+- Try: `using bitbucket, list repositories in myworkspace`
+
+## Security & Limitations
+
+- ✅ **Read-only by design**: No write/delete/modify operations possible
+- ✅ **Safe for production**: No destructive actions supported  
+- ✅ **Authenticated access**: Uses API tokens or App Passwords for private repos
+- ✅ **Branch support**: Handles branch names with special characters (e.g., `feature/SSP-1024`)
+- ✅ **Dynamic commit resolution**: Automatically resolves branch names to commit SHAs for subdirectory browsing
+- ⚠️ **Rate limiting**: Subject to Bitbucket API limits
+- ⚠️ **Code search**: Requires enablement in Bitbucket account settings
+- ⚠️ **File size limits**: Large files may be truncated
+
+## Development Status & Related Projects
+
+🚧 **This project is under active development** and may contain incomplete features or breaking changes. We welcome contributions and feedback!
+
+**Related MCP Servers for Reference:**
+- [bitbucket-server-mcp-server](https://github.com/garc33/bitbucket-server-mcp-server) - MCP server for Bitbucket Server (on-premises)
+- [mcp-server-atlassian-bitbucket](https://github.com/aashari/mcp-server-atlassian-bitbucket) - Alternative Atlassian Bitbucket MCP implementation
+
+These repositories provide excellent reference implementations and inspiration for Bitbucket API integration patterns.
+
+## API Coverage
+
+The server implements tools for the most commonly used Bitbucket API endpoints:
+
+- **Repositories API** (read-only operations)
+- **Pull Requests API** (read-only operations)
+  - Pull request details and listing
+  - Pull request comments (inline and general)
+  - Pull request activity (reviews, approvals, state changes)
+- **Issues API** (read-only operations)
+- **Source API** (file content access)
+- **Search API** (code search with language filtering and match highlighting)
+- **Users API** (user information)
+- **Workspaces API** (workspace information)
+- **Branches API** (branch listing and information)
+- **Commits API** (commit history and details)
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes (maintaining read-only nature)
+4. Add tests if applicable
+5. Submit a pull request
+
+## Roadmap
+
+Future enhancements (all read-only):
+
+- Repository statistics and analytics
+- Enhanced search capabilities with more filter options
+- Webhook information retrieval
+- Pipeline status (read-only)
+- More detailed branch and commit information
+- Repository comparison tools
+- Advanced code search filters and sorting

package/build/api.d.ts

@@ -0,0 +1,19 @@
+export declare const BITBUCKET_API_BASE = "https://api.bitbucket.org/2.0";
+/**
+ * Helper function to make authenticated requests to Bitbucket API
+ * Enforces read-only behavior by blocking non-GET requests
+ */
+export declare function makeRequest<T = unknown>(url: string, options?: RequestInit): Promise<T>;
+/**
+ * Build URL for Bitbucket API endpoints
+ */
+export declare function buildApiUrl(endpoint: string): string;
+/**
+ * Helper to build URL parameters for pagination and filtering
+ */
+export declare function buildUrlParams(params: Record<string, unknown>): URLSearchParams;
+/**
+ * Helper to add query parameters to URL
+ */
+export declare function addQueryParams(url: string, params: Record<string, unknown>): string;
+//# sourceMappingURL=api.d.ts.map

package/build/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,kBAAkB,kCAAkC,CAAC;AAElE;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,OAAO,EAC3C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,CAAC,CAAC,CA0DZ;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,eAAe,CAgBjB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAUR"}

package/build/api.js

@@ -0,0 +1,105 @@
+import { loadConfig } from './config.js';
+import { createApiError } from './errors.js';
+import { API_CONSTANTS } from './schemas.js';
+/**
+ * Bitbucket API configuration and request handling
+ */
+// Get config dynamically to handle environment changes
+function getConfig() {
+    return loadConfig();
+}
+// Bitbucket API base URL
+export const BITBUCKET_API_BASE = 'https://api.bitbucket.org/2.0';
+/**
+ * Helper function to make authenticated requests to Bitbucket API
+ * Enforces read-only behavior by blocking non-GET requests
+ */
+export async function makeRequest(url, options = {}) {
+    // Enforce read-only behavior: block any non-GET methods at runtime
+    const requestedMethod = (options.method || 'GET').toString().toUpperCase();
+    if (requestedMethod !== 'GET') {
+        throw new Error(`Only GET requests are allowed. Attempted: ${requestedMethod} ${url}`);
+    }
+    const headers = {
+        Accept: 'application/json',
+        'User-Agent': 'bitbucket-mcp-server/1.0.0',
+        ...(options.headers || {}),
+    };
+    // Add authentication if available
+    // Priority: API Token (Basic auth with email) > App Password (Basic auth with username)
+    const config = getConfig();
+    const apiToken = config.BITBUCKET_API_TOKEN;
+    const email = config.BITBUCKET_EMAIL;
+    const username = config.BITBUCKET_USERNAME;
+    const appPassword = config.BITBUCKET_APP_PASSWORD;
+    if (apiToken && email) {
+        // Use API Token with Basic authentication (recommended)
+        // Username should be your Atlassian email, password is the API token
+        const auth = Buffer.from(`${email}:${apiToken}`).toString('base64');
+        headers.Authorization = `Basic ${auth}`;
+    }
+    else if (username && appPassword) {
+        // Fallback to App Password with Basic authentication (legacy)
+        const auth = Buffer.from(`${username}:${appPassword}`).toString('base64');
+        headers.Authorization = `Basic ${auth}`;
+    }
+    const response = await fetch(url, {
+        ...options,
+        // Force GET to prevent accidental method overrides downstream
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        // Try to parse error details
+        let errorData;
+        try {
+            errorData = JSON.parse(errorText);
+        }
+        catch {
+            // If JSON parsing fails, use raw error text
+            errorData = { message: errorText };
+        }
+        // Create and throw appropriate error type
+        throw createApiError(response.status, response.statusText, errorData, url);
+    }
+    return await response.json();
+}
+/**
+ * Build URL for Bitbucket API endpoints
+ */
+export function buildApiUrl(endpoint) {
+    return `${BITBUCKET_API_BASE}${endpoint}`;
+}
+/**
+ * Helper to build URL parameters for pagination and filtering
+ */
+export function buildUrlParams(params) {
+    const urlParams = new URLSearchParams();
+    Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+            // Handle pagination limits
+            if ((key === 'pagelen' || key === 'limit') && typeof value === 'number') {
+                const limitedValue = Math.min(value, API_CONSTANTS.MAX_PAGE_SIZE);
+                urlParams.append(key, limitedValue.toString());
+            }
+            else {
+                urlParams.append(key, String(value));
+            }
+        }
+    });
+    return urlParams;
+}
+/**
+ * Helper to add query parameters to URL
+ */
+export function addQueryParams(url, params) {
+    const urlParams = buildUrlParams(params);
+    const paramString = urlParams.toString();
+    if (!paramString) {
+        return url;
+    }
+    const separator = url.includes('?') ? '&' : '?';
+    return `${url}${separator}${paramString}`;
+}
+//# sourceMappingURL=api.js.map

package/build/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/build/config.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Configuration management with validation and type safety
+ */
+import { z } from 'zod';
+declare const ConfigSchema: z.ZodObject<{
+    BITBUCKET_API_TOKEN: z.ZodOptional<z.ZodString>;
+    BITBUCKET_EMAIL: z.ZodOptional<z.ZodString>;
+    BITBUCKET_USERNAME: z.ZodOptional<z.ZodString>;
+    BITBUCKET_APP_PASSWORD: z.ZodOptional<z.ZodString>;
+    BITBUCKET_API_BASE: z.ZodDefault<z.ZodString>;
+    BITBUCKET_REQUEST_TIMEOUT: z.ZodDefault<z.ZodEffects<z.ZodString, number, string>>;
+    BITBUCKET_DEBUG: z.ZodDefault<z.ZodEffects<z.ZodString, boolean, string>>;
+}, "strip", z.ZodTypeAny, {
+    BITBUCKET_API_BASE: string;
+    BITBUCKET_REQUEST_TIMEOUT: number;
+    BITBUCKET_DEBUG: boolean;
+    BITBUCKET_API_TOKEN?: string | undefined;
+    BITBUCKET_EMAIL?: string | undefined;
+    BITBUCKET_USERNAME?: string | undefined;
+    BITBUCKET_APP_PASSWORD?: string | undefined;
+}, {
+    BITBUCKET_API_TOKEN?: string | undefined;
+    BITBUCKET_EMAIL?: string | undefined;
+    BITBUCKET_USERNAME?: string | undefined;
+    BITBUCKET_APP_PASSWORD?: string | undefined;
+    BITBUCKET_API_BASE?: string | undefined;
+    BITBUCKET_REQUEST_TIMEOUT?: string | undefined;
+    BITBUCKET_DEBUG?: string | undefined;
+}>;
+export type Config = z.infer<typeof ConfigSchema>;
+export declare function loadConfig(): Config;
+export interface AuthMethod {
+    method: 'api-token' | 'app-password' | 'none';
+    isValid: boolean;
+    warning?: string;
+}
+export declare function validateAuthentication(config: Config): AuthMethod;
+/**
+ * Initialize and validate configuration, logging warnings as needed
+ */
+export declare function initializeConfig(): {
+    config: Config;
+    auth: AuthMethod;
+};
+export {};
+//# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;EAgBhB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,wBAAgB,UAAU,IAAI,MAAM,CAanC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,GAAG,cAAc,GAAG,MAAM,CAAC;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAoBjE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAoCvE"}

package/build/config.js

@@ -0,0 +1,80 @@
+/**
+ * Configuration management with validation and type safety
+ */
+import { z } from 'zod';
+// Configuration schema with validation
+const ConfigSchema = z.object({
+    // Authentication (prioritized order)
+    BITBUCKET_API_TOKEN: z.string().optional(),
+    BITBUCKET_EMAIL: z.string().email().optional(),
+    BITBUCKET_USERNAME: z.string().optional(),
+    BITBUCKET_APP_PASSWORD: z.string().optional(),
+    // API Configuration
+    BITBUCKET_API_BASE: z.string().url().default('https://api.bitbucket.org/2.0'),
+    BITBUCKET_REQUEST_TIMEOUT: z.string().transform(Number).default('30000'),
+    // Debugging
+    BITBUCKET_DEBUG: z
+        .string()
+        .transform(val => val === 'true')
+        .default('false'),
+});
+export function loadConfig() {
+    try {
+        return ConfigSchema.parse(process.env);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const missingFields = error.errors
+                .map(err => `${err.path.join('.')}: ${err.message}`)
+                .join('\n');
+            throw new Error(`Configuration validation failed:\n${missingFields}`);
+        }
+        throw error;
+    }
+}
+export function validateAuthentication(config) {
+    if (config.BITBUCKET_API_TOKEN && config.BITBUCKET_EMAIL) {
+        return { method: 'api-token', isValid: true };
+    }
+    if (config.BITBUCKET_USERNAME && config.BITBUCKET_APP_PASSWORD) {
+        return {
+            method: 'app-password',
+            isValid: true,
+            warning: 'App Passwords are deprecated (Sept 9, 2025). Consider migrating to API tokens.',
+        };
+    }
+    return {
+        method: 'none',
+        isValid: false,
+        warning: 'No authentication configured. Only public repositories will be accessible.',
+    };
+}
+/**
+ * Initialize and validate configuration, logging warnings as needed
+ */
+export function initializeConfig() {
+    const config = loadConfig();
+    const auth = validateAuthentication(config);
+    // Log authentication status
+    if (!auth.isValid) {
+        console.error('⚠️', auth.warning);
+    }
+    else if (auth.warning) {
+        console.error('⚠️', auth.warning);
+    }
+    // Log operational mode
+    console.error('🔒 Mode: READ-ONLY (by design)');
+    console.error(`🔐 Auth: ${auth.method.toUpperCase()}`);
+    if (config.BITBUCKET_DEBUG) {
+        console.error('🐛 Debug mode enabled');
+        console.error('Debug - Environment variables:');
+        console.error('  BITBUCKET_API_TOKEN:', config.BITBUCKET_API_TOKEN
+            ? `SET (length: ${config.BITBUCKET_API_TOKEN.length})`
+            : 'NOT SET');
+        console.error('  BITBUCKET_EMAIL:', config.BITBUCKET_EMAIL || 'NOT SET');
+        console.error('  BITBUCKET_USERNAME:', config.BITBUCKET_USERNAME || 'NOT SET');
+        console.error('  BITBUCKET_APP_PASSWORD:', config.BITBUCKET_APP_PASSWORD ? 'SET' : 'NOT SET');
+    }
+    return { config, auth };
+}
+//# sourceMappingURL=config.js.map

package/build/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/build/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Custom error classes for better error handling and user feedback
+ */
+export declare class BitbucketApiError extends Error {
+    status: number;
+    statusText: string;
+    details?: string | undefined;
+    suggestion?: string | undefined;
+    constructor(status: number, statusText: string, details?: string | undefined, suggestion?: string | undefined);
+}
+export declare class AuthenticationError extends BitbucketApiError {
+    constructor(details?: string);
+}
+export declare class NotFoundError extends BitbucketApiError {
+    constructor(resource: string);
+}
+export declare class ForbiddenError extends BitbucketApiError {
+    constructor(resource?: string);
+}
+export declare class RateLimitError extends BitbucketApiError {
+    constructor();
+}
+/**
+ * Creates appropriate error instance based on HTTP status code
+ */
+export declare function createApiError(status: number, statusText: string, errorData?: {
+    error?: {
+        message?: string;
+        detail?: string;
+    };
+    message?: string;
+}, url?: string): BitbucketApiError;
+//# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;IAEjC,MAAM,EAAE,MAAM;IACd,UAAU,EAAE,MAAM;IAClB,OAAO,CAAC,EAAE,MAAM;IAChB,UAAU,CAAC,EAAE,MAAM;gBAHnB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,YAAA,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;CAO7B;AAED,qBAAa,mBAAoB,SAAQ,iBAAiB;gBAC5C,OAAO,CAAC,EAAE,MAAM;CAS7B;AAED,qBAAa,aAAc,SAAQ,iBAAiB;gBACtC,QAAQ,EAAE,MAAM;CAS7B;AAED,qBAAa,cAAe,SAAQ,iBAAiB;gBACvC,QAAQ,CAAC,EAAE,MAAM;CAS9B;AAED,qBAAa,cAAe,SAAQ,iBAAiB;;CAUpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE;IACV,KAAK,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,EACD,GAAG,CAAC,EAAE,MAAM,GACX,iBAAiB,CAmCnB"}

package/build/errors.js

@@ -0,0 +1,100 @@
+/**
+ * Custom error classes for better error handling and user feedback
+ */
+export class BitbucketApiError extends Error {
+    status;
+    statusText;
+    details;
+    suggestion;
+    constructor(status, statusText, details, suggestion) {
+        super(`Bitbucket API error: ${status} ${statusText}${details ? ` - ${details}` : ''}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.details = details;
+        this.suggestion = suggestion;
+        this.name = 'BitbucketApiError';
+    }
+}
+export class AuthenticationError extends BitbucketApiError {
+    constructor(details) {
+        super(401, 'Unauthorized', details, 'Check your authentication credentials (BITBUCKET_API_TOKEN + BITBUCKET_EMAIL or BITBUCKET_USERNAME + BITBUCKET_APP_PASSWORD)');
+        this.name = 'AuthenticationError';
+    }
+}
+export class NotFoundError extends BitbucketApiError {
+    constructor(resource) {
+        super(404, 'Not Found', `The requested ${resource} was not found`, 'Check the workspace/repository names and ensure you have access');
+        this.name = 'NotFoundError';
+    }
+}
+export class ForbiddenError extends BitbucketApiError {
+    constructor(resource) {
+        super(403, 'Forbidden', resource ? `Access denied to ${resource}` : 'Access denied', 'Your credentials may not have sufficient permissions for this resource');
+        this.name = 'ForbiddenError';
+    }
+}
+export class RateLimitError extends BitbucketApiError {
+    constructor() {
+        super(429, 'Too Many Requests', 'Rate limit exceeded', 'Please wait before retrying');
+        this.name = 'RateLimitError';
+    }
+}
+/**
+ * Creates appropriate error instance based on HTTP status code
+ */
+export function createApiError(status, statusText, errorData, url) {
+    let details = '';
+    // Try to extract error details from response
+    if (errorData) {
+        if (errorData.error?.message) {
+            details = errorData.error.message;
+            if (errorData.error.detail) {
+                details += ` (${errorData.error.detail})`;
+            }
+        }
+        else if (errorData.message) {
+            details = errorData.message;
+        }
+    }
+    // Extract resource type from URL for better error messages
+    const resource = extractResourceFromUrl(url);
+    switch (status) {
+        case 401:
+            return new AuthenticationError(details);
+        case 403:
+            return new ForbiddenError(resource);
+        case 404:
+            return new BitbucketApiError(404, 'Not Found', details || `The requested ${resource || 'resource'} was not found`, 'Check the workspace/repository names and ensure you have access');
+        case 429:
+            return new RateLimitError();
+        default:
+            return new BitbucketApiError(status, statusText, details);
+    }
+}
+/**
+ * Extracts resource type from Bitbucket API URL for better error messages
+ */
+function extractResourceFromUrl(url) {
+    if (!url)
+        return undefined;
+    const patterns = [
+        { pattern: /\/repositories\/[^/]+\/[^/]+$/, resource: 'repository' },
+        {
+            pattern: /\/repositories\/[^/]+\/[^/]+\/pullrequests/,
+            resource: 'pull request',
+        },
+        { pattern: /\/repositories\/[^/]+\/[^/]+\/issues/, resource: 'issue' },
+        { pattern: /\/repositories\/[^/]+\/[^/]+\/src/, resource: 'file' },
+        { pattern: /\/repositories\/[^/]+\/[^/]+\/commits/, resource: 'commit' },
+        { pattern: /\/repositories\/[^/]+\/[^/]+\/refs/, resource: 'branch' },
+        { pattern: /\/workspaces\/[^/]+$/, resource: 'workspace' },
+        { pattern: /\/user/, resource: 'user' },
+    ];
+    for (const { pattern, resource } of patterns) {
+        if (pattern.test(url)) {
+            return resource;
+        }
+    }
+    return 'resource';
+}
+//# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/build/index-new.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index-new.d.ts.map

package/build/index-new.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-new.d.ts","sourceRoot":"","sources":["../src/index-new.ts"],"names":[],"mappings":""}