@sleavely/bitbucket/README.md

Client and utils for Bitbucket Cloud REST APIs

# @sleavely/bitbucket

API client and collection of common utility methods for managing Bitbucket Cloud via their REST API.

## Usage

```sh
npm install @sleavely/bitbucket
```

```typescript
import { BitbucketClient } from '@sleavely/bitbucket'

const bitbucket = new BitbucketClient({
  auth: {
    username: 'foobar',
    password: 'secret', // Create an app password: https://bitbucket.org/account/settings/app-passwords/
  },
})

console.log(await bitbucket.getCurrentUser())
```

## FAQ

### The response type for xyz is wrong

The initial types were handcrafted according to the [Bitbucket Cloud REST API reference](https://developer.atlassian.com/cloud/bitbucket/rest/intro/#authentication) which in turn are likely autogenerated from [their OpenAPI schema](https://api.bitbucket.org/swagger.json). Unfortunately their schema in many cases differs from reality, so discrepancies will occur from time to time. Let me know in an issue (or pull request) and I'll do my best to amend it.

### A feature I need is missing!

I've only added utility methods for things I've personally needed in the past, but I'd be happy to add more. In the meantime the public `client` property acts as an escape hatch to the [`got`](https://github.com/sindresorhus/got/tree/v11.8.6) instance:

```typescript
// List branches and tags without the need for helper utils.
await bitbucket.client('/repositories/{workspace}/{repo_slug}/refs')
  .json<unknown>()
  // or simply `.json()`
```