Node.js library to access the Bitbucket API v2
Check out bitbucket-server-nodejs
Most of the bitbucket API is covered. The few remaining functions are easy to add if you have the need.
Now has full test coverage of API. All tests pass :)
We use macros to generate tests based on data templates. The tests use nock to mock each HTTP requests to the server.
Take it for a spin :)
Authentication via Bitbucket OAuth2
Create an OAuth2 token under Account.
Add the Secret
and Key
to environment variables or similar.
Create a Callback URL such as: http://localhost/bitbucket/authenticated
You will need to create an endpoint on your server to receive the access token from bitbucket and then proceed.
const { createBitbucketAPI } = require('bitbucket-api-v2')
const bitbucketApi = createBitbucketAPI() //or: createBitbucketAPI({useXhr: true})
bitbucketApi.authenticateOAuth2(someAccessToken)
If you are unable to use ES 2015 modules directly, try using the pre-compiled dist
bundles:
const { createBitbucketAPI } = require('bitbucket-api-v2/dist/bitbucketAPI')
Minified:
const { createBitbucketAPI } = require('bitbucket-api-v2/dist/bitbucketAPI.min')
Note: You may also use createBitBucketAPI
(deprecated)
Get the user info (of authenticated user)
bitbucketApi.user.get((response) => {
console.log(response.username);
});
The library by default uses xhr to submit Ajax requests to the server.
Would be nice to switch to xhr2 or a higher level, more feature rich API such as request
Please see Request customization for details on how to customize how requests to the server are being made
Please see Authentication for how to authenticate and get an access token.
repositories
teams
user
users
addon
hookEvents
APIs acting on a user repository
commit
commits
components
issues
milestones
pipelines
pullRequests
refs
versions
hooks
pipelinesConfig
forks
downloads
branchRestrictions
Please see the API overview for a full list of available API methods.
See API usage for details on usage.
Callback API:
api.commit.approve(username, repoSlug, commitId, (result) => {
// ...
console.log(result)
})
Promise API
const commit = api.commit.promised
let result = await commit.approve(username, repoSlug, commitId)
Generate default promised
API
async function user() {
const bitbucketApi = createBitbucketAPI().promised
let response = await bitbucketApi.user.get();
console.log(response.username);
}
To generate customized promised
API, create a function with the signature createPromisedApi(api = {}, opts = {})
, which returns a promisified api
object the way you like it. See bitbucket/promised.js
for reference.
You can also pass you own promisify
function to be used in the default or custom factory function.
const createPromisedAPI = require('./my-own-create-promised')
const promisify = require('./my-promisify')
const bitbucketApi = createBitbucketAPI({
createPromisedAPI,
promisify
})
async function user() {
let response = await bitbucketApi.user.get();
console.log(response.username);
}
To disable generation of promised based API pass promised: false
option
const bitbucketApi = createBitbucketAPI({
promised: false
})
To enable logging on requests sent to the server, try adding logging: true
to the options argument when creating the API.
createBitbucketAPI({
logging: true
})
Tests will be written and run using ava the "Futuristic JavaScript test runner"
Intial skeleton tests have been started. Please contribute!
Please see Testing for best practices when writing tests for the API.
In short: use test generators via mocks made with nock
!
To run test suite:
$ npm install
// install all dependencies ...
$ npm test
// test output
To use this library in the browser, see the /dist
folder for dev
and prod
(ie. minified) pre-bundled versions.
To create your own bundles, see Testing
See more documentation in /docs
MIT 2017
(see LICENSE.txt)