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 |
|
16 | [**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.
|
17 |
|
18 | ---
|
19 |
|
20 | ## Installation
|
21 |
|
22 | via **npm**:
|
23 |
|
24 | ```sh
|
25 | $ npm install bitbucket --save
|
26 | ```
|
27 |
|
28 | via **yarn**:
|
29 |
|
30 | ```sh
|
31 | $ yarn add bitbucket
|
32 | ```
|
33 |
|
34 | ## Usage
|
35 |
|
36 | ### Browser
|
37 |
|
38 | ```html
|
39 | <script src="https://unpkg.com/bitbucket/dist/bitbucket.min.js"></script>
|
40 | <script>
|
41 | const bitbucket = new Bitbucket()
|
42 | </script>
|
43 | ```
|
44 |
|
45 | ### Node
|
46 |
|
47 | ```js
|
48 | const Bitbucket = require('bitbucket')
|
49 |
|
50 | const bitbucket = new Bitbucket()
|
51 | ```
|
52 |
|
53 | #### Client Options
|
54 |
|
55 | You can set the APIs' `baseUrl` and modify some behaviors (e.g. request timeout etc.) by passing a clientOptions object to the `Bitbucket` constructor.
|
56 |
|
57 | ```js
|
58 | const clientOptions = {
|
59 | baseUrl: 'https://api.bitbucket.org/2.0',
|
60 | headers: {},
|
61 | options: {
|
62 | timeout: 10
|
63 | }
|
64 | }
|
65 |
|
66 | const bitbucket = new Bitbucket(clientOptions)
|
67 | ```
|
68 |
|
69 | This enables you to use `bitbucket` with both Bitbucket Cloud and Bitbucket Server.
|
70 |
|
71 | #### Authentication
|
72 |
|
73 | ```js
|
74 | bitbucket.authenticate({
|
75 | type: 'basic',
|
76 | username: 'username',
|
77 | password: 'password'
|
78 | })
|
79 | ```
|
80 |
|
81 | #### API Methods
|
82 |
|
83 | **async/await**
|
84 | ```js
|
85 | try {
|
86 | let { data, headers } = await bitbucket.<namespace>.<api>({ ...params })
|
87 | } catch (err) {}
|
88 | ```
|
89 |
|
90 | **Promise**
|
91 | ```js
|
92 | bitbucket.<namespace>
|
93 | .<api>({ ...params })
|
94 | .then(({ data, headers }) => {})
|
95 | .catch(err => {})
|
96 | ```
|
97 |
|
98 | **Callback**
|
99 | ```js
|
100 | bitbucket.<namespace>.<api>({ ...params }, (err, { data, headers }) => {})
|
101 | ```
|
102 |
|
103 | Notes:
|
104 |
|
105 | - `<namespace>` is one of the _Namespace Names_
|
106 | - `<api>` is one of the _API Names_
|
107 |
|
108 | #### Namespace Names
|
109 |
|
110 | `addon`, `hook_events`, `webhooks`, `repositories`, `branchrestrictions`, `commits`, `commitstatuses`, `issue_tracker`, `pullrequests`, `downloads`, `source`, `pipelines`, `refs`, `snippets`, `teams`, `projects`, `users`, `search`, `user`, `ssh`
|
111 |
|
112 | #### API Names
|
113 |
|
114 | Check API client docs: [https://bitbucketjs.netlify.com](https://bitbucketjs.netlify.com)
|
115 |
|
116 | ##### Examples
|
117 |
|
118 | ```js
|
119 | bitbucket.repositories
|
120 | .list({ username: 'MunifTanjim' })
|
121 | .then(({ data, headers }) => console.log(data.values))
|
122 | .catch(err => console.error(err))
|
123 | ```
|
124 |
|
125 | ## Acknowledgement
|
126 |
|
127 | 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`.
|
128 |
|
129 | ## License
|
130 |
|
131 | Licensed under the MIT License. Check the [LICENSE](https://github.com/MunifTanjim/node-bitbucket/blob/master/LICENSE) file for details.
|