1 | [![version:@latest](https://img.shields.io/npm/v/bitbucket.svg?style=for-the-badge)](https://www.npmjs.com/package/bitbucket)
|
2 | [![Documentation](https://img.shields.io/badge/docs-bitbucket.js-blue.svg?style=for-the-badge)](https://bitbucketjs.netlify.com)
|
3 | [![License](https://img.shields.io/github/license/MunifTanjim/node-bitbucket.svg?style=for-the-badge)](https://github.com/MunifTanjim/node-bitbucket/blob/master/LICENSE)
|
4 |
|
5 | # Bitbucket.js
|
6 |
|
7 | Bitbucket API client for Browser and Node.js
|
8 |
|
9 | Bitbucket API docs: [https://api.bitbucket.org](https://api.bitbucket.org)
|
10 |
|
11 | ---
|
12 |
|
13 | **BITBUCKET CLOUD API CHANGING NOTICE**: [https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-gdpr)
|
14 | **BITBUCKET CLOUD API MIGRATION GUIDE**: [https://developer.atlassian.com/cloud/bitbucket/bbc-gdpr-api-migration-guide](https://developer.atlassian.com/cloud/bitbucket/bbc-gdpr-api-migration-guide)
|
15 | **BITBUCKET CLOUD API REPO URL CHANGE**: [https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-workspaces](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-changes-workspaces)
|
16 |
|
17 | [**BREAKING CHANGES FOR API NAME**](https://github.com/MunifTanjim/node-bitbucket/blob/master/v1_API_NAME_CHANGES.md): Unfortunately, API Name changes were published on the following minor version updates: `v1.8.0`, `v1.9.0`, `v1.10.0`. This type of changes won't happen again for minor version updates anymore.
|
18 |
|
19 | ---
|
20 |
|
21 | ## Installation
|
22 |
|
23 | via **npm**:
|
24 |
|
25 | ```sh
|
26 | $ npm install bitbucket --save
|
27 | ```
|
28 |
|
29 | via **yarn**:
|
30 |
|
31 | ```sh
|
32 | $ yarn add bitbucket
|
33 | ```
|
34 |
|
35 | ## Usage
|
36 |
|
37 | ### Browser
|
38 |
|
39 | ```html
|
40 | <script src="https://unpkg.com/bitbucket/dist/bitbucket.min.js"></script>
|
41 | <script>
|
42 | const bitbucket = new Bitbucket()
|
43 | </script>
|
44 | ```
|
45 |
|
46 | ### Node
|
47 |
|
48 | ```js
|
49 | const Bitbucket = require('bitbucket')
|
50 |
|
51 | const bitbucket = new Bitbucket()
|
52 | ```
|
53 |
|
54 | #### Client Options
|
55 |
|
56 | You can set the APIs' `baseUrl` and modify some behaviors (e.g. request timeout etc.) by passing a clientOptions object to the `Bitbucket` constructor.
|
57 |
|
58 | ```js
|
59 | const clientOptions = {
|
60 | baseUrl: 'https://api.bitbucket.org/2.0',
|
61 | headers: {},
|
62 | options: {
|
63 | timeout: 10
|
64 | }
|
65 | }
|
66 |
|
67 | const bitbucket = new Bitbucket(clientOptions)
|
68 | ```
|
69 |
|
70 | #### Authentication
|
71 |
|
72 | ```js
|
73 | bitbucket.authenticate({
|
74 | type: 'basic',
|
75 | username: 'username',
|
76 | password: 'password'
|
77 | })
|
78 | ```
|
79 |
|
80 | #### API Methods
|
81 |
|
82 | **async/await**
|
83 | ```js
|
84 | try {
|
85 | let { data, headers } = await bitbucket.<namespace>.<api>({ ...params })
|
86 | } catch (err) {}
|
87 | ```
|
88 |
|
89 | **Promise**
|
90 | ```js
|
91 | bitbucket.<namespace>
|
92 | .<api>({ ...params })
|
93 | .then(({ data, headers }) => {})
|
94 | .catch(err => {})
|
95 | ```
|
96 |
|
97 | **Callback**
|
98 | ```js
|
99 | bitbucket.<namespace>.<api>({ ...params }, (err, { data, headers }) => {})
|
100 | ```
|
101 |
|
102 | Notes:
|
103 |
|
104 | - `<namespace>` is one of the _Namespace Names_
|
105 | - `<api>` is one of the _API Names_
|
106 |
|
107 | #### Namespace Names
|
108 |
|
109 | `addon`, `hook_events`, `webhooks`, `repositories`, `branchrestrictions`, `commits`, `commitstatuses`, `issue_tracker`, `pullrequests`, `downloads`, `source`, `pipelines`, `refs`, `snippets`, `teams`, `projects`, `users`, `search`, `user`, `ssh`
|
110 |
|
111 | #### API Names
|
112 |
|
113 | Check API client docs: [https://bitbucketjs.netlify.com](https://bitbucketjs.netlify.com)
|
114 |
|
115 | ##### Examples
|
116 |
|
117 | ```js
|
118 | bitbucket.repositories
|
119 | .list({ username: 'MunifTanjim' })
|
120 | .then(({ data, headers }) => console.log(data.values))
|
121 | .catch(err => console.error(err))
|
122 | ```
|
123 |
|
124 | ## Acknowledgement
|
125 |
|
126 | This API client is heavily inspired by the **[`octokit/rest.js`](https://github.com/octokit/rest.js/)** and a lot of ideas are taken from there. So, thanks goes to the maintainer [Gregor Martynus](https://github.com/gr2m) and all the [awesome contributors](https://github.com/octokit/rest.js/graphs/contributors) of `octokit/rest.js`.
|
127 |
|
128 | ## License
|
129 |
|
130 | Licensed under the MIT License. Check the [LICENSE](https://github.com/MunifTanjim/node-bitbucket/blob/master/LICENSE) file for details.
|