gitea v0.0.1
gitea
Low-level methods for working with the Gitea API in node.js/JavaScript.
Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your :heart: and support.
Table of Contents
(TOC generated by verb using markdown-toc)
Install
Install with npm:
$ npm install --save gitea
Heads up!
As of v1.0, the API is 100% promise based, callbacks are no longer supported. Please see the API documentation and release history for more details.
Why gitea, instead of...?
Every other Gitea API library we found either had a huge dependency tree, tries to be everything to everyone, was too bloated with boilerplace code, was too opinionated, or was not maintained.
We created gitea to provide low-level support for a handful of HTTP verbs for creating higher-level libraries:
- .request: the base handler all of the Gitea HTTP verbs:
GET
,PUT
,POST
,DELETE
,PATCH
- .get: proxy for
.request('GET', path, options, cb)
- .delete: proxy for
.request('DELETE', path, options, cb)
- .patch: proxy for
.request('PATCH', path, options, cb)
- .post: proxy for
.request('POST', path, options, cb)
- .put: proxy for
.request('PUT', path, options, cb)
- .paged: recursively makes
GET
requests until all pages have been retrieved.
Jump to the API section for more details.
Usage
Add gitea to your node.js/JavaScript project with the following line of code:
const Gitea = require('gitea');
Example usage
Recursively GET
all pages of gists for a user:
const gitea = new Gitea({ /* options */ });
const owner = 'jonschlinkert';
gitea.paged(`/users/${owner}/gists`)
.then(res => console.log(res))
.catch(console.error);
API
(All request methods take a callback, or return a promise if a callback isn't passed as the last argument).
Gitea
Create an instance of Gitea
with the given options.
Params
options
{Object}
Example
const Gitea = require('gitea');
const gitea = new Gitea([options]);
.request
Uses needle to make a request to the Gitea API. Supports the following verbs: GET
, PUT
, POST
, PATCH
, and DELETE
. Takes a callback or returns a promise.
Params
method
{String}: The http VERB to usepath
{String}: The path to append to the base Gitea API URL.options
{Options}: Request options.
Example
// list all orgs for the authenticated user
const auth = require('./local-private-auth-info');
const gitea = new Gitea(auth);
gitea.request('GET', '/user/orgs')
.then(res => console.log(res.body));
.get
Make a GET
request to the Gitea API.
Params
path
{String}: The path to append to the base Gitea API URL.options
{Options}: Request options.
Example
// get a list of orgs for the authenticated user
gitea.get('/user/orgs')
.then(res => console.log(res.body));
// get gists for the authenticated user
gitea.get('/gists')
.then(res => console.log(res.body));
.delete
Make a DELETE
request to the Gitea API.
Params
path
{String}: The path to append to the base Gitea API URL.options
{Options}: Request options.
Example
// un-follow someone
gitea.delete('/user/following/:some_username', { some_username: 'whatever' })
.then(res => {
console.log('RESPONSE:', res);
});
.patch
Make a PATCH
request to the Gitea API.
Params
path
{String}: The path to append to the base Gitea API URL.options
{Options}: Request options.
Example
// update a gist
const fs = require('fs');
const options = { files: { 'readme.md': { content: fs.readFileSync('README.md', 'utf8') } } };
gitea.patch('/gists/bd139161a425896f35f8', options)
.then(res => {
console.log('RESPONSE:', res);
});
.post
Make a POST
request to the Gitea API.
Params
path
{String}: The path to append to the base Gitea API URL.options
{Options}: Request options.
Example
// create a new repository
gitea.post('/user/repos', { name: 'new-repo-name' })
.then(res => {
console.log('RESPONSE:', res);
});
.put
Make a PUT
request to the Gitea API.
Params
path
{String}: The path to append to the base Gitea API URL.options
{Options}: Request options.
Example
// follow someone
gitea.put('/user/following/jonschlinkert')
.then(res => {
console.log('RESPONSE:', res);
});
.paged
Recursively make GET requests until all pages of records are returned.
Params
path
{String}: The path to append to the base Gitea API URL.options
{Options}: Request options.
Example
// get all repos for the authenticated user
gitea.paged('/user/repos?type=all&per_page=1000&sort=updated')
.then(res => console.log(res.pages))
.catch(console.error)
.use
Register plugins with use.
const gitea = new Gitea();
gitea.use(function() {
// do stuff with the gitea instance
});
Authentication
There are a few ways to authenticate, all of them require info to be passed on the options.
const gitea = new Gitea({
username: YOUR_USERNAME,
password: YOUR_PASSWORD,
});
// or
const gitea = new Gitea({
token: YOUR_TOKEN
});
// or
const gitea = new Gitea({
bearer: YOUR_JSON_WEB_TOKEN
});
Paths and placeholders
Deprecated: Since es2015 templates make this feature less useful, we plan to remove it in a future release.
Paths are similar to router paths, where placeholders in the given string are replaced with values from the options. For instance, the path in the following example:
const gitea = new Gitea();
const options = { user: 'jonschlinkert', repo: 'gitea', subscribed: true };
gitea.put('/repos/:user/:repo/subscription', options);
Expands to:
'/repos/jonschlinkert/gitea/subscription'
Placeholder names are also arbitrary, you can make them whatever you want as long as all placeholder names can be resolved using values defined on the options.
Options
Options may be passed to the constructor when instantiating, and/or set on the instance directly, and/or passed to any of the methods.
Examples
// pass to constructor
const gitea = new Gitea({ user: 'doowb' });
// and/or directly set on instance options
gitea.options.user = 'doowb';
// and/or pass to a method
gitea.get('/users/:user/gists', { user: 'doowb' })
options.query
Type: object
Default: { per_page: 100 }
for get and paged requests, undefined
for all other requests.
Pass an object to stringify and append to the URL using the .stringify
method from qs.
Examples
gitea.paged('/users/:user/gists', { user: 'doowb', query: { per_page: 30 } })
.then(res => {
console.log(res.pages);
});
You can also manually append the query string:
gitea.paged('/users/:user/gists?per_page=30', { user: 'doowb' })
.then(res => {
console.log(res.pages);
});
About
Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.
Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:
$ npm install && npm test
(This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)
To generate the readme, run the following command:
$ npm install -g verbose/verb#dev verb-generate-readme && verb
Related projects
You might also be interested in these projects:
- gists: Methods for working with the Gitea Gist API. Node.js/JavaScript | homepage
- gitea-contributors: Generate a markdown or JSON list of contributors for a project using the Gitea API. | homepage
- repos: List all repositories for one or more users or orgs. | homepage
- topics: Get and update Gitea repository topics. | homepage
Contributors
Commits | Contributor |
---|---|
40 | jonschlinkert |
10 | doowb |
7 | olstenlarck |
Author
Jon Schlinkert
License
Copyright © 2018, Jon Schlinkert. Released under the MIT License.
This file was generated by verb-generate-readme, v0.6.0, on August 14, 2018.
4 years ago