Bitbucket.js API Client

Common errors

• ReferenceError: Bitbucket is not defined

  cause Incorrectly importing or referencing the Bitbucket class, often when mixing CommonJS `require` syntax with an ESM-only context, or when using the UMD build without global access.
  fix For Node.js ESM projects, use `import { Bitbucket } from 'bitbucket'`. For CommonJS Node.js, use `const { Bitbucket } = require('bitbucket')`. In a browser with the UMD build, ensure the `Bitbucket` global is available after script loading.

• TypeError: bitbucket.repositories.listGlobal is not a function

  cause Attempting to call an API method with incorrect arguments or on a non-existent namespace/method. This can also happen if the API client instance is not correctly initialized.
  fix Verify the method name and namespace against the official documentation (e.g., `bitbucketjs.netlify.app`). Ensure all required parameters are passed as an object to the API method.

• Error: Request failed with status code 400

  cause A `400 Bad Request` status indicates that the API request itself was malformed, missing required parameters, or contained invalid data.
  fix Review the `err.error` object in the catch block for specific details from the Bitbucket API about what caused the bad request. Ensure all required parameters for the specific API method are correctly formatted and provided.

Warnings

• breaking Major version updates, particularly from v1 to v2, often introduce breaking changes in API method signatures, response structures, or authentication mechanisms. Always review the official changelog or migration guide when upgrading across major versions to avoid unexpected issues. Specific changes may include renaming methods, altering parameter requirements, or updating the base URL.
  Fix: Consult the release notes and migration guides (if available) on the package's GitHub repository or documentation site when upgrading to a new major version. Test your application thoroughly after any major version upgrade.
• gotcha Bitbucket API enforces rate limits on requests. Exceeding these limits will result in `429 Too Many Requests` errors. The client library does not inherently handle retry logic or backoff strategies out-of-the-box, which must be implemented by the consumer.
  Fix: Implement custom retry logic with exponential backoff for `429` status codes. Monitor `Retry-After` headers in API responses if provided. Design your application to minimize unnecessary API calls.
• gotcha Authentication failures often manifest as `401 Unauthorized` or `403 Forbidden` errors. This can be due to incorrect tokens, expired credentials, or insufficient permissions granted to the authenticated user or token.
  Fix: Verify that your `username`/`password` or `token` is correct and current. Ensure the Bitbucket user or app associated with the token has the necessary scopes/permissions for the API operations being attempted.
• gotcha When using the client in a browser environment, be mindful of cross-origin resource sharing (CORS) policies. Direct API calls from a browser to Bitbucket's API might be blocked if the response does not include appropriate CORS headers, especially for non-simple requests.
  Fix: Proxy Bitbucket API requests through your backend server to avoid CORS issues, or ensure your Bitbucket App/configuration is set up to allow CORS from your specific frontend origin if applicable.

Install

• npm install bitbucket npm
• yarn add bitbucket yarn
• pnpm add bitbucket pnpm

Imports

• Bitbucket
  wrong:

  const { Bitbucket } = require('bitbucket')

  correct:

  import { Bitbucket } from 'bitbucket'

  ESM is preferred for modern Node.js and all browser environments. While CommonJS `require` still works, `import` offers better tree-shaking and future compatibility.
• Bitbucket
  wrong:

  import { Bitbucket } from 'bitbucket'

  correct:

  const { Bitbucket } = require('bitbucket')

  This is the correct CommonJS syntax for Node.js environments. Do not mix with ESM `import` in the same file without proper transpilation.
• ClientOptions
  wrong:

  import type { ClientOptions } from 'bitbucket'

  correct:

  import { ClientOptions } from 'bitbucket'

  The `bitbucket` package ships with TypeScript types. `ClientOptions` is an interface for configuring the API client. `import type` is explicitly for type imports but `import` works too if not ambiguous.

Quickstart

This quickstart demonstrates how to initialize the Bitbucket client with token authentication and list repositories for the authenticated user ('me'). It includes error handling for common API issues like authentication failures.

import { Bitbucket } from 'bitbucket';

const BITBUCKET_ACCESS_TOKEN = process.env.BITBUCKET_ACCESS_TOKEN ?? '';

if (!BITBUCKET_ACCESS_TOKEN) {
  console.error('Error: BITBUCKET_ACCESS_TOKEN environment variable is not set.');
  process.exit(1);
}

const clientOptions = {
  baseUrl: 'https://api.bitbucket.org/2.0',
  auth: {
    token: BITBUCKET_ACCESS_TOKEN,
  },
  request: {
    timeout: 10000, // 10 seconds
  },
};

const bitbucket = new Bitbucket(clientOptions);

async function listMyRepositories() {
  try {
    console.log('Fetching repositories...');
    const { data } = await bitbucket.repositories.listForUser({ username: 'me' });
    if (data && data.values) {
      console.log('Found the following repositories:');
      data.values.forEach(repo => console.log(`- ${repo.name} (${repo.full_name})`));
    } else {
      console.log('No repositories found or unexpected response format.');
    }
  } catch (err) {
    if (err.status === 401 || err.status === 403) {
      console.error('Authentication failed. Check your BITBUCKET_ACCESS_TOKEN and permissions.');
    } else {
      console.error(`Error listing repositories: ${err.message}`);
      if (err.error) {
        console.error('API Error details:', err.error);
      }
    }
  }
}

listMyRepositories();