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 --save bitbucket
|
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/lib/index.umd.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 | request: {
|
62 | timeout: 10
|
63 | }
|
64 | }
|
65 |
|
66 | const bitbucket = new Bitbucket(clientOptions)
|
67 | ```
|
68 |
|
69 | #### Authentication
|
70 |
|
71 | ```js
|
72 | const clientOptions = {
|
73 | auth: {
|
74 | username: 'username',
|
75 | password: 'password'
|
76 | }
|
77 | }
|
78 |
|
79 | const bitbucket = new Bitbucket(clientOptions)
|
80 | ```
|
81 |
|
82 | #### API Methods
|
83 |
|
84 | **async/await**
|
85 | ```js
|
86 | try {
|
87 | const { data, headers, status, url } = await bitbucket.<namespace>.<api>({ ...params })
|
88 | } catch (err) {
|
89 | const { message, error, headers, request, status } = err
|
90 | }
|
91 | ```
|
92 |
|
93 | **Promise**
|
94 | ```js
|
95 | bitbucket.<namespace>
|
96 | .<api>({ ...params })
|
97 | .then(({ data, headers, status, url }) => {})
|
98 | .catch(({ message, error, headers, request, status }) => {})
|
99 | ```
|
100 |
|
101 | Notes:
|
102 |
|
103 | - `<namespace>` is one of the _Namespace Names_
|
104 | - `<api>` is one of the _API Names_
|
105 |
|
106 | #### Namespace Names
|
107 |
|
108 | `branching_model`, `branchrestrictions`, `commits`, `commitstatuses`, `deploy`, `deployments`, `downloads`, `hook_events`, `issue_tracker`, `pipelines`, `projects`, `pullrequests`, `refs`, `repositories`, `search`, `snippet`, `snippets`, `source`, `ssh`, `teams`, `user`, `users`, `webhooks`
|
109 |
|
110 | #### API Names
|
111 |
|
112 | Check API client docs: [https://bitbucketjs.netlify.com](https://bitbucketjs.netlify.com)
|
113 |
|
114 | ##### Examples
|
115 |
|
116 | ```js
|
117 | bitbucket.repositories
|
118 | .list({ username: 'MunifTanjim' })
|
119 | .then(({ data }) => console.log(data.values))
|
120 | .catch(err => console.error(err))
|
121 | ```
|
122 |
|
123 | ## Acknowledgement
|
124 |
|
125 | 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`.
|
126 |
|
127 | ## License
|
128 |
|
129 | Licensed under the MIT License. Check the [LICENSE](https://github.com/MunifTanjim/node-bitbucket/blob/master/LICENSE) file for details.
|