From 1834f135eb0bfbc96f1aeb6d25f7ca04ce7ea797 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86ndrew=20Rininsland?= Date: Thu, 29 Sep 2016 12:00:06 +0100 Subject: [PATCH] :star: New: Adds TypeScript definition generation --- .jsdoc-ts.json | 23 + github-api.d.ts | 1420 +++++++++++++++++++++++++++++++++++++++++++ lib/Gist.js | 26 +- lib/GitHub.js | 2 +- lib/Issue.js | 32 +- lib/Markdown.js | 4 +- lib/Organization.js | 12 +- lib/RateLimit.js | 4 +- lib/Repository.js | 119 ++-- lib/Requestable.js | 25 +- lib/Search.js | 21 +- lib/Team.js | 20 +- lib/User.js | 18 +- package.json | 6 +- tsconfig.json | 6 + 15 files changed, 1600 insertions(+), 138 deletions(-) create mode 100644 .jsdoc-ts.json create mode 100644 github-api.d.ts create mode 100644 tsconfig.json diff --git a/.jsdoc-ts.json b/.jsdoc-ts.json new file mode 100644 index 00000000..b6650398 --- /dev/null +++ b/.jsdoc-ts.json @@ -0,0 +1,23 @@ +{ + "tags": { + "dictionaries": ["jsdoc"] + }, + "source": { + "include": ["lib/", "package.json", "README.md"], + "includePattern": ".js$", + "excludePattern": "(node_modules/|docs)" + }, + "templates": { + "cleverLinks": false, + "monospaceLinks": true, + "jsdoc2tsd": { + "interfacePrefix": "" + } + }, + "opts": { + "destination": "./", + "encoding": "utf8", + "recurse": true, + "template": "./node_modules/tsd-jsdoc" + } +} diff --git a/github-api.d.ts b/github-api.d.ts new file mode 100644 index 00000000..a0ff22ca --- /dev/null +++ b/github-api.d.ts @@ -0,0 +1,1420 @@ +/** + * A Gist can retrieve and modify gists. + */ +declare class Gist { + /** + * A Gist can retrieve and modify gists. + */ + constructor(id: string, auth?: Requestable.auth, apiBase?: string); + + /** + * Fetch a gist. + * @see https://developer.github.com/v3/gists/#get-a-single-gist + * @param {Requestable.callback} [cb] - will receive the gist + * @return {axios.Promise} - the Promise for the http request + */ + read(cb?: Requestable.callback): axios.Promise; + + /** + * Create a new gist. + * @see https://developer.github.com/v3/gists/#create-a-gist + * @param {Object} gist - the data for the new gist + * @param {Requestable.callback} [cb] - will receive the new gist upon creation + * @return {axios.Promise} - the Promise for the http request + */ + create(gist: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Delete a gist. + * @see https://developer.github.com/v3/gists/#delete-a-gist + * @param {Requestable.callback} [cb] - will receive true if the request succeeds + * @return {axios.Promise} - the Promise for the http request + */ + delete(cb?: Requestable.callback): axios.Promise; + + /** + * Fork a gist. + * @see https://developer.github.com/v3/gists/#fork-a-gist + * @param {Requestable.callback} [cb] - the function that will receive the gist + * @return {axios.Promise} - the Promise for the http request + */ + fork(cb?: Requestable.callback): axios.Promise; + + /** + * Update a gist. + * @see https://developer.github.com/v3/gists/#edit-a-gist + * @param {Object} gist - the new data for the gist + * @param {Requestable.callback} [cb] - the function that receives the API result + * @return {axios.Promise} - the Promise for the http request + */ + update(gist: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Star a gist. + * @see https://developer.github.com/v3/gists/#star-a-gist + * @param {Requestable.callback} [cb] - will receive true if the request is successful + * @return {axios.Promise} - the Promise for the http request + */ + star(cb?: Requestable.callback): axios.Promise; + + /** + * Unstar a gist. + * @see https://developer.github.com/v3/gists/#unstar-a-gist + * @param {Requestable.callback} [cb] - will receive true if the request is successful + * @return {axios.Promise} - the Promise for the http request + */ + unstar(cb?: Requestable.callback): axios.Promise; + + /** + * Check if a gist is starred by the user. + * @see https://developer.github.com/v3/gists/#check-if-a-gist-is-starred + * @param {Requestable.callback} [cb] - will receive true if the gist is starred and false if the gist is not starred + * @return {axios.Promise} - the Promise for the http request + */ + isStarred(cb?: Requestable.callback): axios.Promise; + + /** + * List the gist's comments + * @see https://developer.github.com/v3/gists/comments/#list-comments-on-a-gist + * @param {Requestable.callback} [cb] - will receive the array of comments + * @return {axios.Promise} - the promise for the http request + */ + listComments(cb?: Requestable.callback): axios.Promise; + + /** + * Fetch one of the gist's comments + * @see https://developer.github.com/v3/gists/comments/#get-a-single-comment + * @param {number} comment - the id of the comment + * @param {Requestable.callback} [cb] - will receive the comment + * @return {axios.Promise} - the Promise for the http request + */ + getComment(comment: number, cb?: Requestable.callback): axios.Promise; + + /** + * Comment on a gist + * @see https://developer.github.com/v3/gists/comments/#create-a-comment + * @param {string} comment - the comment to add + * @param {Requestable.callback} [cb] - the function that receives the API result + * @return {axios.Promise} - the Promise for the http request + */ + createComment(comment: string, cb?: Requestable.callback): axios.Promise; + + /** + * Edit a comment on the gist + * @see https://developer.github.com/v3/gists/comments/#edit-a-comment + * @param {number} comment - the id of the comment + * @param {string} body - the new comment + * @param {Requestable.callback} [cb] - will receive the modified comment + * @return {axios.Promise} - the promise for the http request + */ + editComment(comment: number, body: string, cb?: Requestable.callback): axios.Promise; + + /** + * Delete a comment on the gist. + * @see https://developer.github.com/v3/gists/comments/#delete-a-comment + * @param {number} comment - the id of the comment + * @param {Requestable.callback} [cb] - will receive true if the request succeeds + * @return {axios.Promise} - the Promise for the http request + */ + deleteComment(comment: number, cb?: Requestable.callback): axios.Promise; + +} + +/** + * GitHub encapsulates the functionality to create various API wrapper objects. + */ +declare class GitHub { + /** + * GitHub encapsulates the functionality to create various API wrapper objects. + */ + constructor(auth?: Requestable.auth, apiBase?: string); + + /** + * Create a new Gist wrapper + * @param {number} [id] - the id for the gist, leave undefined when creating a new gist + * @return {Gist} + */ + getGist(id?: number): Gist; + + /** + * Create a new User wrapper + * @param {string} [user] - the name of the user to get information about + * leave undefined for the authenticated user + * @return {User} + */ + getUser(user?: string): User; + + /** + * Create a new Organization wrapper + * @param {string} organization - the name of the organization + * @return {Organization} + */ + getOrganization(organization: string): Organization; + + /** + * create a new Team wrapper + * @param {string} teamId - the name of the team + * @return {Team} + */ + getTeam(teamId: string): Team; + + /** + * Create a new Repository wrapper + * @param {string} user - the user who owns the respository + * @param {string} repo - the name of the repository + * @return {Repository} + */ + getRepo(user: string, repo: string): Repository; + + /** + * Create a new Issue wrapper + * @param {string} user - the user who owns the respository + * @param {string} repo - the name of the repository + * @return {Issue} + */ + getIssues(user: string, repo: string): Issue; + + /** + * Create a new Search wrapper + * @param {string} query - the query to search for + * @return {Search} + */ + search(query: string): Search; + + /** + * Create a new RateLimit wrapper + * @return {RateLimit} + */ + getRateLimit(): RateLimit; + + /** + * Create a new Markdown wrapper + * @return {Markdown} + */ + getMarkdown(): Markdown; + + /** + * Computes the full repository name + * @param {string} user - the username (or the full name) + * @param {string} repo - the repository name, must not be passed if `user` is the full name + * @return {string} the repository's full name + */ + _getFullName(user: string, repo: string): string; + +} + +/** + * Issue wraps the functionality to get issues for repositories + */ +declare class Issue { + /** + * Issue wraps the functionality to get issues for repositories + */ + constructor(repository: string, auth?: Requestable.auth, apiBase?: string); + + /** + * Create a new issue + * @see https://developer.github.com/v3/issues/#create-an-issue + * @param {Object} issueData - the issue to create + * @param {Requestable.callback} [cb] - will receive the created issue + * @return {axios.Promise} - the promise for the http request + */ + createIssue(issueData: Object, cb?: Requestable.callback): axios.Promise; + + /** + * List the issues for the repository + * @see https://developer.github.com/v3/issues/#list-issues-for-a-repository + * @param {Object} options - filtering options + * @param {Requestable.callback} [cb] - will receive the array of issues + * @return {axios.Promise} - the promise for the http request + */ + listIssues(options: Object, cb?: Requestable.callback): axios.Promise; + + /** + * List the events for an issue + * @see https://developer.github.com/v3/issues/events/#list-events-for-an-issue + * @param {number} issue - the issue to get events for + * @param {Requestable.callback} [cb] - will receive the list of events + * @return {axios.Promise} - the promise for the http request + */ + listIssueEvents(issue: number, cb?: Requestable.callback): axios.Promise; + + /** + * List comments on an issue + * @see https://developer.github.com/v3/issues/comments/#list-comments-on-an-issue + * @param {number} issue - the id of the issue to get comments from + * @param {Requestable.callback} [cb] - will receive the comments + * @return {axios.Promise} - the promise for the http request + */ + listIssueComments(issue: number, cb?: Requestable.callback): axios.Promise; + + /** + * Get a single comment on an issue + * @see https://developer.github.com/v3/issues/comments/#get-a-single-comment + * @param {number} id - the comment id to get + * @param {Requestable.callback} [cb] - will receive the comment + * @return {axios.Promise} - the promise for the http request + */ + getIssueComment(id: number, cb?: Requestable.callback): axios.Promise; + + /** + * Comment on an issue + * @see https://developer.github.com/v3/issues/comments/#create-a-comment + * @param {number} issue - the id of the issue to comment on + * @param {string} comment - the comment to add + * @param {Requestable.callback} [cb] - will receive the created comment + * @return {axios.Promise} - the promise for the http request + */ + createIssueComment(issue: number, comment: string, cb?: Requestable.callback): axios.Promise; + + /** + * Edit a comment on an issue + * @see https://developer.github.com/v3/issues/comments/#edit-a-comment + * @param {number} id - the comment id to edit + * @param {string} comment - the comment to edit + * @param {Requestable.callback} [cb] - will receive the edited comment + * @return {axios.Promise} - the promise for the http request + */ + editIssueComment(id: number, comment: string, cb?: Requestable.callback): axios.Promise; + + /** + * Delete a comment on an issue + * @see https://developer.github.com/v3/issues/comments/#delete-a-comment + * @param {number} id - the comment id to delete + * @param {Requestable.callback} [cb] - will receive true if the request is successful + * @return {axios.Promise} - the promise for the http request + */ + deleteIssueComment(id: number, cb?: Requestable.callback): axios.Promise; + + /** + * Edit an issue + * @see https://developer.github.com/v3/issues/#edit-an-issue + * @param {number} issue - the issue number to edit + * @param {Object} issueData - the new issue data + * @param {Requestable.callback} [cb] - will receive the modified issue + * @return {axios.Promise} - the promise for the http request + */ + editIssue(issue: number, issueData: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Get a particular issue + * @see https://developer.github.com/v3/issues/#get-a-single-issue + * @param {number} issue - the issue number to fetch + * @param {Requestable.callback} [cb] - will receive the issue + * @return {axios.Promise} - the promise for the http request + */ + getIssue(issue: number, cb?: Requestable.callback): axios.Promise; + + /** + * List the milestones for the repository + * @see https://developer.github.com/v3/issues/milestones/#list-milestones-for-a-repository + * @param {Object} options - filtering options + * @param {Requestable.callback} [cb] - will receive the array of milestones + * @return {axios.Promise} - the promise for the http request + */ + listMilestones(options: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Get a milestone + * @see https://developer.github.com/v3/issues/milestones/#get-a-single-milestone + * @param {string} milestone - the id of the milestone to fetch + * @param {Requestable.callback} [cb] - will receive the array of milestones + * @return {axios.Promise} - the promise for the http request + */ + getMilestone(milestone: string, cb?: Requestable.callback): axios.Promise; + + /** + * Create a new milestone + * @see https://developer.github.com/v3/issues/milestones/#create-a-milestone + * @param {Object} milestoneData - the milestone definition + * @param {Requestable.callback} [cb] - will receive the array of milestones + * @return {axios.Promise} - the promise for the http request + */ + createMilestone(milestoneData: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Edit a milestone + * @see https://developer.github.com/v3/issues/milestones/#update-a-milestone + * @param {string} milestone - the id of the milestone to edit + * @param {Object} milestoneData - the updates to make to the milestone + * @param {Requestable.callback} [cb] - will receive the array of milestones + * @return {axios.Promise} - the promise for the http request + */ + editMilestone(milestone: string, milestoneData: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Delete a milestone (this is distinct from closing a milestone) + * @see https://developer.github.com/v3/issues/milestones/#delete-a-milestone + * @param {string} milestone - the id of the milestone to delete + * @param {Requestable.callback} [cb] - will receive the array of milestones + * @return {axios.Promise} - the promise for the http request + */ + deleteMilestone(milestone: string, cb?: Requestable.callback): axios.Promise; + + /** + * Create a new label + * @see https://developer.github.com/v3/issues/labels/#create-a-label + * @param {Object} labelData - the label definition + * @param {Requestable.callback} [cb] - will receive the object representing the label + * @return {axios.Promise} - the promise for the http request + */ + createLabel(labelData: Object, cb?: Requestable.callback): axios.Promise; + +} + +/** + * RateLimit allows users to query their rate-limit status + */ +declare class Markdown { + /** + * RateLimit allows users to query their rate-limit status + */ + constructor(auth: Requestable.auth, apiBase?: string); + + /** + * Render html from Markdown text. + * @see https://developer.github.com/v3/markdown/#render-an-arbitrary-markdown-document + * @param {Object} options - conversion options + * @param {string} [options.text] - the markdown text to convert + * @param {string} [options.mode=markdown] - can be either `markdown` or `gfm` + * @param {string} [options.context] - repository name if mode is gfm + * @param {Requestable.callback} [cb] - will receive the converted html + * @return {axios.Promise} - the promise for the http request + */ + render(options: { text: string, mode: string, context: string }, cb?: Requestable.callback): axios.Promise; + +} + +/** + * Organization encapsulates the functionality to create repositories in organizations + */ +declare class Organization { + /** + * Organization encapsulates the functionality to create repositories in organizations + */ + constructor(organization: string, auth?: Requestable.auth, apiBase?: string); + + /** + * Create a repository in an organization + * @see https://developer.github.com/v3/repos/#create + * @param {Object} options - the repository definition + * @param {Requestable.callback} [cb] - will receive the created repository + * @return {axios.Promise} - the promise for the http request + */ + createRepo(options: Object, cb?: Requestable.callback): axios.Promise; + + /** + * List the repositories in an organization + * @see https://developer.github.com/v3/repos/#list-organization-repositories + * @param {Requestable.callback} [cb] - will receive the list of repositories + * @return {axios.Promise} - the promise for the http request + */ + getRepos(cb?: Requestable.callback): axios.Promise; + + /** + * Query if the user is a member or not + * @param {string} username - the user in question + * @param {Requestable.callback} [cb] - will receive true if the user is a member + * @return {axios.Promise} - the promise for the http request + */ + isMember(username: string, cb?: Requestable.callback): axios.Promise; + + /** + * List the users who are members of the company + * @see https://developer.github.com/v3/orgs/members/#members-list + * @param {object} options - filtering options + * @param {string} [options.filter=all] - can be either `2fa_disabled` or `all` + * @param {string} [options.role=all] - can be one of: `all`, `admin`, or `member` + * @param {Requestable.callback} [cb] - will receive the list of users + * @return {axios.Promise} - the promise for the http request + */ + listMembers(options: { filter: string, role: string }, cb?: Requestable.callback): axios.Promise; + + /** + * List the Teams in the Organization + * @see https://developer.github.com/v3/orgs/teams/#list-teams + * @param {Requestable.callback} [cb] - will receive the list of teams + * @return {axios.Promise} - the promise for the http request + */ + getTeams(cb?: Requestable.callback): axios.Promise; + + /** + * Create a team + * @see https://developer.github.com/v3/orgs/teams/#create-team + * @param {object} options - Team creation parameters + * @param {string} options.name - The name of the team + * @param {string} [options.description] - Team description + * @param {string} [options.repo_names] - Repos to add the team to + * @param {string} [options.privacy=secret] - The level of privacy the team should have. Can be either one + * of: `secret`, or `closed` + * @param {Requestable.callback} [cb] - will receive the created team + * @return {axios.Promise} - the promise for the http request + */ + createTeam(options: { name: string, description: string, repo_names: string, privacy: string }, cb?: Requestable.callback): axios.Promise; + +} + +/** + * RateLimit allows users to query their rate-limit status + */ +declare class RateLimit { + /** + * RateLimit allows users to query their rate-limit status + */ + constructor(auth: Requestable.auth, apiBase?: string); + + /** + * Query the current rate limit + * @see https://developer.github.com/v3/rate_limit/ + * @param {Requestable.callback} [cb] - will receive the rate-limit data + * @return {axios.Promise} - the promise for the http request + */ + getRateLimit(cb?: Requestable.callback): axios.Promise; + +} + +/** + * Respository encapsulates the functionality to create, query, and modify files. + * @class Repository + */ +declare class Repository { + /** + * Respository encapsulates the functionality to create, query, and modify files. + * @class Repository + */ + constructor(); + + /** + * Get a reference + * @see https://developer.github.com/v3/git/refs/#get-a-reference + * @param {string} ref - the reference to get + * @param {Requestable.callback} [cb] - will receive the reference's refSpec or a list of refSpecs that match `ref` + * @return {axios.Promise} - the promise for the http request + */ + getRef(ref: string, cb?: Requestable.callback): axios.Promise; + + /** + * Create a reference + * @see https://developer.github.com/v3/git/refs/#create-a-reference + * @param {Object} options - the object describing the ref + * @param {Requestable.callback} [cb] - will receive the ref + * @return {axios.Promise} - the promise for the http request + */ + createRef(options: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Delete a reference + * @see https://developer.github.com/v3/git/refs/#delete-a-reference + * @param {string} ref - the name of the ref to delte + * @param {Requestable.callback} [cb] - will receive true if the request is successful + * @return {axios.Promise} - the promise for the http request + */ + deleteRef(ref: string, cb?: Requestable.callback): axios.Promise; + + /** + * Delete a repository + * @see https://developer.github.com/v3/repos/#delete-a-repository + * @param {Requestable.callback} [cb] - will receive true if the request is successful + * @return {axios.Promise} - the promise for the http request + */ + deleteRepo(cb?: Requestable.callback): axios.Promise; + + /** + * List the tags on a repository + * @see https://developer.github.com/v3/repos/#list-tags + * @param {Requestable.callback} [cb] - will receive the tag data + * @return {axios.Promise} - the promise for the http request + */ + listTags(cb?: Requestable.callback): axios.Promise; + + /** + * List the open pull requests on the repository + * @see https://developer.github.com/v3/pulls/#list-pull-requests + * @param {Object} options - options to filter the search + * @param {Requestable.callback} [cb] - will receive the list of PRs + * @return {axios.Promise} - the promise for the http request + */ + listPullRequests(options: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Get information about a specific pull request + * @see https://developer.github.com/v3/pulls/#get-a-single-pull-request + * @param {number} number - the PR you wish to fetch + * @param {Requestable.callback} [cb] - will receive the PR from the API + * @return {axios.Promise} - the promise for the http request + */ + getPullRequest(number: number, cb?: Requestable.callback): axios.Promise; + + /** + * List the files of a specific pull request + * @see https://developer.github.com/v3/pulls/#list-pull-requests-files + * @param {number|string} number - the PR you wish to fetch + * @param {Requestable.callback} [cb] - will receive the list of files from the API + * @return {axios.Promise} - the promise for the http request + */ + listPullRequestFiles(number: (number|string), cb?: Requestable.callback): axios.Promise; + + /** + * Compare two branches/commits/repositories + * @see https://developer.github.com/v3/repos/commits/#compare-two-commits + * @param {string} base - the base commit + * @param {string} head - the head commit + * @param {Requestable.callback} cb - will receive the comparison + * @return {axios.Promise} - the promise for the http request + */ + compareBranches(base: string, head: string, cb: Requestable.callback): axios.Promise; + + /** + * List all the branches for the repository + * @see https://developer.github.com/v3/repos/#list-branches + * @param {Requestable.callback} cb - will receive the list of branches + * @return {axios.Promise} - the promise for the http request + */ + listBranches(cb: Requestable.callback): axios.Promise; + + /** + * Get a raw blob from the repository + * @see https://developer.github.com/v3/git/blobs/#get-a-blob + * @param {string} sha - the sha of the blob to fetch + * @param {Requestable.callback} cb - will receive the blob from the API + * @return {axios.Promise} - the promise for the http request + */ + getBlob(sha: string, cb: Requestable.callback): axios.Promise; + + /** + * Get a single branch + * @see https://developer.github.com/v3/repos/branches/#get-branch + * @param {string} branch - the name of the branch to fetch + * @param {Requestable.callback} cb - will receive the branch from the API + * @returns {axios.Promise} - the promise for the http request + */ + getBranch(branch: string, cb: Requestable.callback): axios.Promise; + + /** + * Get a commit from the repository + * @see https://developer.github.com/v3/repos/commits/#get-a-single-commit + * @param {string} sha - the sha for the commit to fetch + * @param {Requestable.callback} cb - will receive the commit data + * @return {axios.Promise} - the promise for the http request + */ + getCommit(sha: string, cb: Requestable.callback): axios.Promise; + + /** + * List the commits on a repository, optionally filtering by path, author or time range + * @see https://developer.github.com/v3/repos/commits/#list-commits-on-a-repository + * @param {Object} [options] - the filtering options for commits + * @param {string} [options.sha] - the SHA or branch to start from + * @param {string} [options.path] - the path to search on + * @param {string} [options.author] - the commit author + * @param {(Date|string)} [options.since] - only commits after this date will be returned + * @param {(Date|string)} [options.until] - only commits before this date will be returned + * @param {Requestable.callback} cb - will receive the list of commits found matching the criteria + * @return {axios.Promise} - the promise for the http request + */ + listCommits(options?: { sha: string, path: string, author: string, since: (Date|string), until: (Date|string) }, cb?: Requestable.callback): axios.Promise; + + /** + * Gets a single commit information for a repository + * @see https://developer.github.com/v3/repos/commits/#get-a-single-commit + * @param {string} ref - the reference for the commit-ish + * @param {Requestable.callback} cb - will receive the commit information + * @return {axios.Promise} - the promise for the http request + */ + getSingleCommit(ref: string, cb: Requestable.callback): axios.Promise; + + /** + * Get tha sha for a particular object in the repository. This is a convenience function + * @see https://developer.github.com/v3/repos/contents/#get-contents + * @param {string} [branch] - the branch to look in, or the repository's default branch if omitted + * @param {string} path - the path of the file or directory + * @param {Requestable.callback} cb - will receive a description of the requested object, including a `SHA` property + * @return {axios.Promise} - the promise for the http request + */ + getSha(branch?: string, path?: string, cb?: Requestable.callback): axios.Promise; + + /** + * List the commit statuses for a particular sha, branch, or tag + * @see https://developer.github.com/v3/repos/statuses/#list-statuses-for-a-specific-ref + * @param {string} sha - the sha, branch, or tag to get statuses for + * @param {Requestable.callback} cb - will receive the list of statuses + * @return {axios.Promise} - the promise for the http request + */ + listStatuses(sha: string, cb: Requestable.callback): axios.Promise; + + /** + * Get a description of a git tree + * @see https://developer.github.com/v3/git/trees/#get-a-tree + * @param {string} treeSHA - the SHA of the tree to fetch + * @param {Requestable.callback} cb - will receive the callback data + * @return {axios.Promise} - the promise for the http request + */ + getTree(treeSHA: string, cb: Requestable.callback): axios.Promise; + + /** + * Create a blob + * @see https://developer.github.com/v3/git/blobs/#create-a-blob + * @param {string|Buffer|Blob} content - the content to add to the repository + * @param {Requestable.callback} cb - will receive the details of the created blob + * @return {axios.Promise} - the promise for the http request + */ + createBlob(content: (string|Buffer|Blob), cb: Requestable.callback): axios.Promise; + + /** + * Get the object that represents the provided content + * @param {string|Buffer|Blob} content - the content to send to the server + * @return {Object} the representation of `content` for the GitHub API + */ + _getContentObject(content: (string|Buffer|Blob)): Object; + + /** + * Update a tree in Git + * @see https://developer.github.com/v3/git/trees/#create-a-tree + * @param {string} baseTreeSHA - the SHA of the tree to update + * @param {string} path - the path for the new file + * @param {string} blobSHA - the SHA for the blob to put at `path` + * @param {Requestable.callback} cb - will receive the new tree that is created + * @return {axios.Promise} - the promise for the http request + * @deprecated use {@link Repository#createTree} instead + */ + updateTree(baseTreeSHA: string, path: string, blobSHA: string, cb: Requestable.callback): axios.Promise; + + /** + * Create a new tree in git + * @see https://developer.github.com/v3/git/trees/#create-a-tree + * @param {Object} tree - the tree to create + * @param {string} baseSHA - the root sha of the tree + * @param {Requestable.callback} cb - will receive the new tree that is created + * @return {axios.Promise} - the promise for the http request + */ + createTree(tree: Object, baseSHA: string, cb: Requestable.callback): axios.Promise; + + /** + * Add a commit to the repository + * @see https://developer.github.com/v3/git/commits/#create-a-commit + * @param {string} parent - the SHA of the parent commit + * @param {string} tree - the SHA of the tree for this commit + * @param {string} message - the commit message + * @param {Requestable.callback} cb - will receive the commit that is created + * @return {axios.Promise} - the promise for the http request + */ + commit(parent: string, tree: string, message: string, cb: Requestable.callback): axios.Promise; + + /** + * Update a ref + * @see https://developer.github.com/v3/git/refs/#update-a-reference + * @param {string} ref - the ref to update + * @param {string} commitSHA - the SHA to point the reference to + * @param {boolean} force - indicates whether to force or ensure a fast-forward update + * @param {Requestable.callback} cb - will receive the updated ref back + * @return {axios.Promise} - the promise for the http request + */ + updateHead(ref: string, commitSHA: string, force: boolean, cb: Requestable.callback): axios.Promise; + + /** + * Get information about the repository + * @see https://developer.github.com/v3/repos/#get + * @param {Requestable.callback} cb - will receive the information about the repository + * @return {axios.Promise} - the promise for the http request + */ + getDetails(cb: Requestable.callback): axios.Promise; + + /** + * List the contributors to the repository + * @see https://developer.github.com/v3/repos/#list-contributors + * @param {Requestable.callback} cb - will receive the list of contributors + * @return {axios.Promise} - the promise for the http request + */ + getContributors(cb: Requestable.callback): axios.Promise; + + /** + * List the users who are collaborators on the repository. The currently authenticated user must have + * push access to use this method + * @see https://developer.github.com/v3/repos/collaborators/#list-collaborators + * @param {Requestable.callback} cb - will receive the list of collaborators + * @return {axios.Promise} - the promise for the http request + */ + getCollaborators(cb: Requestable.callback): axios.Promise; + + /** + * Check if a user is a collaborator on the repository + * @see https://developer.github.com/v3/repos/collaborators/#check-if-a-user-is-a-collaborator + * @param {string} username - the user to check + * @param {Requestable.callback} cb - will receive true if the user is a collaborator and false if they are not + * @return {axios.Promise} - the promise for the http request {Boolean} [description] + */ + isCollaborator(username: string, cb: Requestable.callback): axios.Promise; + + /** + * Get the contents of a repository + * @see https://developer.github.com/v3/repos/contents/#get-contents + * @param {string} ref - the ref to check + * @param {string} path - the path containing the content to fetch + * @param {boolean} raw - `true` if the results should be returned raw instead of GitHub's normalized format + * @param {Requestable.callback} cb - will receive the fetched data + * @return {axios.Promise} - the promise for the http request + */ + getContents(ref: string, path: string, raw: boolean, cb: Requestable.callback): axios.Promise; + + /** + * Get the README of a repository + * @see https://developer.github.com/v3/repos/contents/#get-the-readme + * @param {string} ref - the ref to check + * @param {boolean} raw - `true` if the results should be returned raw instead of GitHub's normalized format + * @param {Requestable.callback} cb - will receive the fetched data + * @return {axios.Promise} - the promise for the http request + */ + getReadme(ref: string, raw: boolean, cb: Requestable.callback): axios.Promise; + + /** + * Fork a repository + * @see https://developer.github.com/v3/repos/forks/#create-a-fork + * @param {Requestable.callback} cb - will receive the information about the newly created fork + * @return {axios.Promise} - the promise for the http request + */ + fork(cb: Requestable.callback): axios.Promise; + + /** + * List a repository's forks + * @see https://developer.github.com/v3/repos/forks/#list-forks + * @param {Requestable.callback} cb - will receive the list of repositories forked from this one + * @return {axios.Promise} - the promise for the http request + */ + listForks(cb: Requestable.callback): axios.Promise; + + /** + * Create a new branch from an existing branch. + * @param {string} [oldBranch=master] - the name of the existing branch + * @param {string} newBranch - the name of the new branch + * @param {Requestable.callback} cb - will receive the commit data for the head of the new branch + * @return {axios.Promise} - the promise for the http request + */ + createBranch(oldBranch?: string, newBranch?: string, cb?: Requestable.callback): axios.Promise; + + /** + * Create a new pull request + * @see https://developer.github.com/v3/pulls/#create-a-pull-request + * @param {Object} options - the pull request description + * @param {Requestable.callback} cb - will receive the new pull request + * @return {axios.Promise} - the promise for the http request + */ + createPullRequest(options: Object, cb: Requestable.callback): axios.Promise; + + /** + * Update a pull request + * @deprecated since version 2.4.0 + * @see https://developer.github.com/v3/pulls/#update-a-pull-request + * @param {number|string} number - the number of the pull request to update + * @param {Object} options - the pull request description + * @param {Requestable.callback} [cb] - will receive the pull request information + * @return {axios.Promise} - the promise for the http request + */ + updatePullRequst(number: (number|string), options: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Update a pull request + * @see https://developer.github.com/v3/pulls/#update-a-pull-request + * @param {number|string} number - the number of the pull request to update + * @param {Object} options - the pull request description + * @param {Requestable.callback} [cb] - will receive the pull request information + * @return {axios.Promise} - the promise for the http request + */ + updatePullRequest(number: (number|string), options: Object, cb?: Requestable.callback): axios.Promise; + + /** + * List the hooks for the repository + * @see https://developer.github.com/v3/repos/hooks/#list-hooks + * @param {Requestable.callback} cb - will receive the list of hooks + * @return {axios.Promise} - the promise for the http request + */ + listHooks(cb: Requestable.callback): axios.Promise; + + /** + * Get a hook for the repository + * @see https://developer.github.com/v3/repos/hooks/#get-single-hook + * @param {number} id - the id of the webook + * @param {Requestable.callback} cb - will receive the details of the webook + * @return {axios.Promise} - the promise for the http request + */ + getHook(id: number, cb: Requestable.callback): axios.Promise; + + /** + * Add a new hook to the repository + * @see https://developer.github.com/v3/repos/hooks/#create-a-hook + * @param {Object} options - the configuration describing the new hook + * @param {Requestable.callback} cb - will receive the new webhook + * @return {axios.Promise} - the promise for the http request + */ + createHook(options: Object, cb: Requestable.callback): axios.Promise; + + /** + * Edit an existing webhook + * @see https://developer.github.com/v3/repos/hooks/#edit-a-hook + * @param {number} id - the id of the webhook + * @param {Object} options - the new description of the webhook + * @param {Requestable.callback} cb - will receive the updated webhook + * @return {axios.Promise} - the promise for the http request + */ + updateHook(id: number, options: Object, cb: Requestable.callback): axios.Promise; + + /** + * Delete a webhook + * @see https://developer.github.com/v3/repos/hooks/#delete-a-hook + * @param {number} id - the id of the webhook to be deleted + * @param {Requestable.callback} cb - will receive true if the call is successful + * @return {axios.Promise} - the promise for the http request + */ + deleteHook(id: number, cb: Requestable.callback): axios.Promise; + + /** + * List the deploy keys for the repository + * @see https://developer.github.com/v3/repos/keys/#list-deploy-keys + * @param {Requestable.callback} cb - will receive the list of deploy keys + * @return {axios.Promise} - the promise for the http request + */ + listKeys(cb: Requestable.callback): axios.Promise; + + /** + * Get a deploy key for the repository + * @see https://developer.github.com/v3/repos/keys/#get-a-deploy-key + * @param {number} id - the id of the deploy key + * @param {Requestable.callback} cb - will receive the details of the deploy key + * @return {axios.Promise} - the promise for the http request + */ + getKey(id: number, cb: Requestable.callback): axios.Promise; + + /** + * Add a new deploy key to the repository + * @see https://developer.github.com/v3/repos/keys/#add-a-new-deploy-key + * @param {Object} options - the configuration describing the new deploy key + * @param {Requestable.callback} cb - will receive the new deploy key + * @return {axios.Promise} - the promise for the http request + */ + createKey(options: Object, cb: Requestable.callback): axios.Promise; + + /** + * Delete a deploy key + * @see https://developer.github.com/v3/repos/keys/#remove-a-deploy-key + * @param {number} id - the id of the deploy key to be deleted + * @param {Requestable.callback} cb - will receive true if the call is successful + * @return {axios.Promise} - the promise for the http request + */ + deleteKey(id: number, cb: Requestable.callback): axios.Promise; + + /** + * Delete a file from a branch + * @see https://developer.github.com/v3/repos/contents/#delete-a-file + * @param {string} branch - the branch to delete from, or the default branch if not specified + * @param {string} path - the path of the file to remove + * @param {Requestable.callback} cb - will receive the commit in which the delete occurred + * @return {axios.Promise} - the promise for the http request + */ + deleteFile(branch: string, path: string, cb: Requestable.callback): axios.Promise; + + /** + * Change all references in a repo from oldPath to new_path + * @param {string} branch - the branch to carry out the reference change, or the default branch if not specified + * @param {string} oldPath - original path + * @param {string} newPath - new reference path + * @param {Requestable.callback} cb - will receive the commit in which the move occurred + * @return {axios.Promise} - the promise for the http request + */ + move(branch: string, oldPath: string, newPath: string, cb: Requestable.callback): axios.Promise; + + /** + * Write a file to the repository + * @see https://developer.github.com/v3/repos/contents/#update-a-file + * @param {string} branch - the name of the branch + * @param {string} path - the path for the file + * @param {string} content - the contents of the file + * @param {string} message - the commit message + * @param {Object} [options] - commit options + * @param {Object} [options.author] - the author of the commit + * @param {Object} [options.commiter] - the committer + * @param {boolean} [options.encode] - true if the content should be base64 encoded + * @param {Requestable.callback} cb - will receive the new commit + * @return {axios.Promise} - the promise for the http request + */ + writeFile(branch: string, path: string, content: string, message: string, options?: { author: Object, commiter: Object, encode: boolean }, cb?: Requestable.callback): axios.Promise; + + /** + * Check if a repository is starred by you + * @see https://developer.github.com/v3/activity/starring/#check-if-you-are-starring-a-repository + * @param {Requestable.callback} cb - will receive true if the repository is starred and false if the repository + * is not starred + * @return {axios.Promise} - the promise for the http request {Boolean} [description] + */ + isStarred(cb: Requestable.callback): axios.Promise; + + /** + * Star a repository + * @see https://developer.github.com/v3/activity/starring/#star-a-repository + * @param {Requestable.callback} cb - will receive true if the repository is starred + * @return {axios.Promise} - the promise for the http request + */ + star(cb: Requestable.callback): axios.Promise; + + /** + * Unstar a repository + * @see https://developer.github.com/v3/activity/starring/#unstar-a-repository + * @param {Requestable.callback} cb - will receive true if the repository is unstarred + * @return {axios.Promise} - the promise for the http request + */ + unstar(cb: Requestable.callback): axios.Promise; + + /** + * Create a new release + * @see https://developer.github.com/v3/repos/releases/#create-a-release + * @param {Object} options - the description of the release + * @param {Requestable.callback} cb - will receive the newly created release + * @return {axios.Promise} - the promise for the http request + */ + createRelease(options: Object, cb: Requestable.callback): axios.Promise; + + /** + * Edit a release + * @see https://developer.github.com/v3/repos/releases/#edit-a-release + * @param {string} id - the id of the release + * @param {Object} options - the description of the release + * @param {Requestable.callback} cb - will receive the modified release + * @return {axios.Promise} - the promise for the http request + */ + updateRelease(id: string, options: Object, cb: Requestable.callback): axios.Promise; + + /** + * Get information about all releases + * @see https://developer.github.com/v3/repos/releases/#list-releases-for-a-repository + * @param {Requestable.callback} cb - will receive the release information + * @return {axios.Promise} - the promise for the http request + */ + listReleases(cb: Requestable.callback): axios.Promise; + + /** + * Get information about a release + * @see https://developer.github.com/v3/repos/releases/#get-a-single-release + * @param {string} id - the id of the release + * @param {Requestable.callback} cb - will receive the release information + * @return {axios.Promise} - the promise for the http request + */ + getRelease(id: string, cb: Requestable.callback): axios.Promise; + + /** + * Delete a release + * @see https://developer.github.com/v3/repos/releases/#delete-a-release + * @param {string} id - the release to be deleted + * @param {Requestable.callback} cb - will receive true if the operation is successful + * @return {axios.Promise} - the promise for the http request + */ + deleteRelease(id: string, cb: Requestable.callback): axios.Promise; + + /** + * Merge a pull request + * @see https://developer.github.com/v3/pulls/#merge-a-pull-request-merge-button + * @param {number|string} number - the number of the pull request to merge + * @param {Object} options - the merge options for the pull request + * @param {Requestable.callback} [cb] - will receive the merge information if the operation is successful + * @return {axios.Promise} - the promise for the http request + */ + mergePullRequest(number: (number|string), options: Object, cb?: Requestable.callback): axios.Promise; + +} + +/** + * @todo Define a better type for Blob + * @typedef Blob + */ +type Blob = any; + +/** + * The error structure returned when a network call fails + */ +declare class ResponseError { + /** + * The error structure returned when a network call fails + */ + constructor(); + +} + +declare namespace Requestable { + /** + * A function that receives the result of the API request. + * @callback Requestable.callback + * @param {Requestable.Error} error - the error returned by the API or `null` + * @param {axios.Response | boolean} result - the data returned by the API or `true` if the API returns `204 No Content` + * @param {axios.RequestOptions} request - the raw {@linkcode https://github.com/mzabriskie/axios#response-schema Response} + */ + type callback = (error: Requestable.Error, result: (axios.Response|boolean), request: axios.RequestOptions) => void; + /** + * @typedef {ResponseError} Requestable.Error + * @param {string} message - an message to return instead of the the default error message + * @param {string} path - the requested path + * @param {Object} response - the object returned by Axios + */ + type Error = ResponseError; + + type auth = any; +} + +/** + * Requestable wraps the logic for making http requests to the API + * @class Requestable + */ +declare class Requestable { + /** + * Requestable wraps the logic for making http requests to the API + * @class Requestable + */ + constructor(); + + /** + * Compute the URL to use to make a request. + * @private + * @param {string} path - either a URL relative to the API base or an absolute URL + * @return {string} - the URL to use + */ + private __getURL(path: string): string; + + /** + * Compute the headers required for an API request. + * @private + * @param {boolean} raw - if the request should be treated as JSON or as a raw request + * @return {Object} - the headers to use in the request + */ + private __getRequestHeaders(raw: boolean): Object; + + /** + * Sets the default options for API requests + * @protected + * @param {Object} [requestOptions={}] - the current options for the request + * @return {Object} - the options to pass to the request + */ + protected _getOptionsWithDefaults(requestOptions?: Object): Object; + + /** + * if a `Date` is passed to this function it will be converted to an ISO string + * @param {Date} date - the object to attempt to cooerce into an ISO date string + * @return {string} - the ISO representation of `date` or whatever was passed in if it was not a date + */ + _dateToISO(date: Date): string; + + /** + * Make a request. + * @param {string} method - the method for the request (GET, PUT, POST, DELETE) + * @param {string} path - the path for the request + * @param {any} [data] - the data to send to the server. For HTTP methods that don't have a body the data + * will be sent as query parameters + * @param {Requestable.callback} [cb] - the callback for the request + * @param {boolean} [raw=false] - if the request should be sent as raw. If this is a falsy value then the + * request will be made as JSON + * @return {axios.Promise} - the Promise for the http request + */ + _request(method: string, path: string, data?: any, cb?: Requestable.callback, raw?: boolean): axios.Promise; + + /** + * Make a request to an endpoint the returns 204 when true and 404 when false + * @param {string} path - the path to request + * @param {Object} data - any query parameters for the request + * @param {Requestable.callback} cb - the callback that will receive `true` or `false` + * @param {method} [method=GET] - HTTP Method to use + * @return {axios.Promise} - the promise for the http request + */ + _request204or404(path: string, data: Object, cb: Requestable.callback, method?: string): axios.Promise; + + /** + * Make a request and fetch all the available data. Github will paginate responses so for queries + * that might span multiple pages this method is preferred to {@link Requestable#request} + * @param {string} path - the path to request + * @param {Object} options - the query parameters to include + * @param {Requestable.callback} [cb] - the function to receive the data. The returned data will always be an array. + * @param [_results] - the partial results. This argument is intended for interal use only. + * @return {axios.Promise} - a promise which will resolve when all pages have been fetched + * @deprecated This will be folded into {@link Requestable#_request} in the 2.0 release. + */ + _requestAllPages(path: string, options: Object, cb?: Requestable.callback, results?: any): axios.Promise; + +} + +declare namespace Search { + type Params = any; +} + +/** + * Wrap the Search API + * @class Search + * @extends Requestable + */ +declare class Search extends Requestable { + /** + * Wrap the Search API + * @class Search + * @extends Requestable + */ + constructor(); + + /** + * Available search options + * @see https://developer.github.com/v3/search/#parameters + * @member Search.Params + * @property {string} q - the query to make + * @property {string} sort - the sort field, one of `stars`, `forks`, or `updated`. + * Default is [best match](https://developer.github.com/v3/search/#ranking-search-results) + * @property {string} order - the ordering, either `asc` or `desc` + */ + static Params: any; + + /** + * Perform a search on the GitHub API + * @private + * @param {string} path - the scope of the search + * @param {Search.Params} [withOptions] - additional parameters for the search + * @param {Requestable.callback} [cb] - will receive the results of the search + * @return {axios.Promise} - the promise for the http request + */ + private _search(path: string, withOptions?: Search.Params, cb?: Requestable.callback): axios.Promise; + + /** + * Search for repositories + * @see https://developer.github.com/v3/search/#search-repositories + * @param {Search.Params} [options] - additional parameters for the search + * @param {Requestable.callback} [cb] - will receive the results of the search + * @return {axios.Promise} - the promise for the http request + */ + forRepositories(options?: Search.Params, cb?: Requestable.callback): axios.Promise; + + /** + * Search for code + * @see https://developer.github.com/v3/search/#search-code + * @param {Search.Params} [options] - additional parameters for the search + * @param {Requestable.callback} [cb] - will receive the results of the search + * @return {axios.Promise} - the promise for the http request + */ + forCode(options?: Search.Params, cb?: Requestable.callback): axios.Promise; + + /** + * Search for issues + * @see https://developer.github.com/v3/search/#search-issues + * @param {Search.Params} [options] - additional parameters for the search + * @param {Requestable.callback} [cb] - will receive the results of the search + * @return {axios.Promise} - the promise for the http request + */ + forIssues(options?: Search.Params, cb?: Requestable.callback): axios.Promise; + + /** + * Search for users + * @see https://developer.github.com/v3/search/#search-users + * @param {Search.Params} [options] - additional parameters for the search + * @param {Requestable.callback} [cb] - will receive the results of the search + * @return {axios.Promise} - the promise for the http request + */ + forUsers(options?: Search.Params, cb?: Requestable.callback): axios.Promise; + +} + +/** + * A Team allows scoping of API requests to a particular Github Organization Team. + */ +declare class Team { + /** + * A Team allows scoping of API requests to a particular Github Organization Team. + */ + constructor(teamId?: string, auth?: Requestable.auth, apiBase?: string); + + /** + * Get Team information + * @see https://developer.github.com/v3/orgs/teams/#get-team + * @param {Requestable.callback} [cb] - will receive the team + * @return {axios.Promise} - the promise for the http request + */ + getTeam(cb?: Requestable.callback): axios.Promise; + + /** + * List the Team's repositories + * @see https://developer.github.com/v3/orgs/teams/#list-team-repos + * @param {Requestable.callback} [cb] - will receive the list of repositories + * @return {axios.Promise} - the promise for the http request + */ + listRepos(cb?: Requestable.callback): axios.Promise; + + /** + * Edit Team information + * @see https://developer.github.com/v3/orgs/teams/#edit-team + * @param {object} options - Parameters for team edit + * @param {string} options.name - The name of the team + * @param {string} [options.description] - Team description + * @param {string} [options.repo_names] - Repos to add the team to + * @param {string} [options.privacy=secret] - The level of privacy the team should have. Can be either one + * of: `secret`, or `closed` + * @param {Requestable.callback} [cb] - will receive the updated team + * @return {axios.Promise} - the promise for the http request + */ + editTeam(options: { name: string, description: string, repo_names: string, privacy: string }, cb?: Requestable.callback): axios.Promise; + + /** + * List the users who are members of the Team + * @see https://developer.github.com/v3/orgs/teams/#list-team-members + * @param {object} options - Parameters for listing team users + * @param {string} [options.role=all] - can be one of: `all`, `maintainer`, or `member` + * @param {Requestable.callback} [cb] - will receive the list of users + * @return {axios.Promise} - the promise for the http request + */ + listMembers(options: { role: string }, cb?: Requestable.callback): axios.Promise; + + /** + * Get Team membership status for a user + * @see https://developer.github.com/v3/orgs/teams/#get-team-membership + * @param {string} username - can be one of: `all`, `maintainer`, or `member` + * @param {Requestable.callback} [cb] - will receive the membership status of a user + * @return {axios.Promise} - the promise for the http request + */ + getMembership(username: string, cb?: Requestable.callback): axios.Promise; + + /** + * Add a member to the Team + * @see https://developer.github.com/v3/orgs/teams/#add-team-membership + * @param {string} username - can be one of: `all`, `maintainer`, or `member` + * @param {object} options - Parameters for adding a team member + * @param {string} [options.role=member] - The role that this user should have in the team. Can be one + * of: `member`, or `maintainer` + * @param {Requestable.callback} [cb] - will receive the membership status of added user + * @return {axios.Promise} - the promise for the http request + */ + addMembership(username: string, options: { role: string }, cb?: Requestable.callback): axios.Promise; + + /** + * Get repo management status for team + * @see https://developer.github.com/v3/orgs/teams/#remove-team-membership + * @param {string} owner - Organization name + * @param {string} repo - Repo name + * @param {Requestable.callback} [cb] - will receive the membership status of added user + * @return {axios.Promise} - the promise for the http request + */ + isManagedRepo(owner: string, repo: string, cb?: Requestable.callback): axios.Promise; + + /** + * Add or Update repo management status for team + * @see https://developer.github.com/v3/orgs/teams/#add-or-update-team-repository + * @param {string} owner - Organization name + * @param {string} repo - Repo name + * @param {object} options - Parameters for adding or updating repo management for the team + * @param {string} [options.permission] - The permission to grant the team on this repository. Can be one + * of: `pull`, `push`, or `admin` + * @param {Requestable.callback} [cb] - will receive the membership status of added user + * @return {axios.Promise} - the promise for the http request + */ + manageRepo(owner: string, repo: string, options: { permission: string }, cb?: Requestable.callback): axios.Promise; + + /** + * Remove repo management status for team + * @see https://developer.github.com/v3/orgs/teams/#remove-team-repository + * @param {string} owner - Organization name + * @param {string} repo - Repo name + * @param {Requestable.callback} [cb] - will receive the membership status of added user + * @return {axios.Promise} - the promise for the http request + */ + unmanageRepo(owner: string, repo: string, cb?: Requestable.callback): axios.Promise; + + /** + * Delete Team + * @see https://developer.github.com/v3/orgs/teams/#delete-team + * @param {Requestable.callback} [cb] - will receive the list of repositories + * @return {axios.Promise} - the promise for the http request + */ + deleteTeam(cb?: Requestable.callback): axios.Promise; + +} + +/** + * A User allows scoping of API requests to a particular Github user. + */ +declare class User { + /** + * A User allows scoping of API requests to a particular Github user. + */ + constructor(username?: string, auth?: Requestable.auth, apiBase?: string); + + /** + * Get the url for the request. (dependent on if we're requesting for the authenticated user or not) + * @private + * @param {string} endpoint - the endpoint being requested + * @return {string} - the resolved endpoint + */ + private __getScopedUrl(endpoint: string): string; + + /** + * List the user's repositories + * @see https://developer.github.com/v3/repos/#list-user-repositories + * @param {Object} [options={}] - any options to refine the search + * @param {Requestable.callback} [cb] - will receive the list of repositories + * @return {axios.Promise} - the promise for the http request + */ + listRepos(options?: Object, cb?: Requestable.callback): axios.Promise; + + /** + * List the orgs that the user belongs to + * @see https://developer.github.com/v3/orgs/#list-user-organizations + * @param {Requestable.callback} [cb] - will receive the list of organizations + * @return {axios.Promise} - the promise for the http request + */ + listOrgs(cb?: Requestable.callback): axios.Promise; + + /** + * List the user's gists + * @see https://developer.github.com/v3/gists/#list-a-users-gists + * @param {Requestable.callback} [cb] - will receive the list of gists + * @return {axios.Promise} - the promise for the http request + */ + listGists(cb?: Requestable.callback): axios.Promise; + + /** + * List the user's notifications + * @see https://developer.github.com/v3/activity/notifications/#list-your-notifications + * @param {Object} [options={}] - any options to refine the search + * @param {Requestable.callback} [cb] - will receive the list of repositories + * @return {axios.Promise} - the promise for the http request + */ + listNotifications(options?: Object, cb?: Requestable.callback): axios.Promise; + + /** + * Show the user's profile + * @see https://developer.github.com/v3/users/#get-a-single-user + * @param {Requestable.callback} [cb] - will receive the user's information + * @return {axios.Promise} - the promise for the http request + */ + getProfile(cb?: Requestable.callback): axios.Promise; + + /** + * Gets the list of starred repositories for the user + * @see https://developer.github.com/v3/activity/starring/#list-repositories-being-starred + * @param {Requestable.callback} [cb] - will receive the list of starred repositories + * @return {axios.Promise} - the promise for the http request + */ + listStarredRepos(cb?: Requestable.callback): axios.Promise; + + /** + * Have the authenticated user follow this user + * @see https://developer.github.com/v3/users/followers/#follow-a-user + * @param {string} username - the user to follow + * @param {Requestable.callback} [cb] - will receive true if the request succeeds + * @return {axios.Promise} - the promise for the http request + */ + follow(username: string, cb?: Requestable.callback): axios.Promise; + + /** + * Have the currently authenticated user unfollow this user + * @see https://developer.github.com/v3/users/followers/#follow-a-user + * @param {string} username - the user to unfollow + * @param {Requestable.callback} [cb] - receives true if the request succeeds + * @return {axios.Promise} - the promise for the http request + */ + unfollow(username: string, cb?: Requestable.callback): axios.Promise; + + /** + * Create a new repository for the currently authenticated user + * @see https://developer.github.com/v3/repos/#create + * @param {object} options - the repository definition + * @param {Requestable.callback} [cb] - will receive the API response + * @return {axios.Promise} - the promise for the http request + */ + createRepo(options: Object, cb?: Requestable.callback): axios.Promise; + +} diff --git a/lib/Gist.js b/lib/Gist.js index 14b71322..19ed0826 100644 --- a/lib/Gist.js +++ b/lib/Gist.js @@ -26,7 +26,7 @@ class Gist extends Requestable { * Fetch a gist. * @see https://developer.github.com/v3/gists/#get-a-single-gist * @param {Requestable.callback} [cb] - will receive the gist - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ read(cb) { return this._request('GET', `/gists/${this.__id}`, null, cb); @@ -37,7 +37,7 @@ class Gist extends Requestable { * @see https://developer.github.com/v3/gists/#create-a-gist * @param {Object} gist - the data for the new gist * @param {Requestable.callback} [cb] - will receive the new gist upon creation - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ create(gist, cb) { return this._request('POST', '/gists', gist, cb) @@ -51,7 +51,7 @@ class Gist extends Requestable { * Delete a gist. * @see https://developer.github.com/v3/gists/#delete-a-gist * @param {Requestable.callback} [cb] - will receive true if the request succeeds - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ delete(cb) { return this._request('DELETE', `/gists/${this.__id}`, null, cb); @@ -61,7 +61,7 @@ class Gist extends Requestable { * Fork a gist. * @see https://developer.github.com/v3/gists/#fork-a-gist * @param {Requestable.callback} [cb] - the function that will receive the gist - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ fork(cb) { return this._request('POST', `/gists/${this.__id}/forks`, null, cb); @@ -72,7 +72,7 @@ class Gist extends Requestable { * @see https://developer.github.com/v3/gists/#edit-a-gist * @param {Object} gist - the new data for the gist * @param {Requestable.callback} [cb] - the function that receives the API result - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ update(gist, cb) { return this._request('PATCH', `/gists/${this.__id}`, gist, cb); @@ -82,7 +82,7 @@ class Gist extends Requestable { * Star a gist. * @see https://developer.github.com/v3/gists/#star-a-gist * @param {Requestable.callback} [cb] - will receive true if the request is successful - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ star(cb) { return this._request('PUT', `/gists/${this.__id}/star`, null, cb); @@ -92,7 +92,7 @@ class Gist extends Requestable { * Unstar a gist. * @see https://developer.github.com/v3/gists/#unstar-a-gist * @param {Requestable.callback} [cb] - will receive true if the request is successful - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ unstar(cb) { return this._request('DELETE', `/gists/${this.__id}/star`, null, cb); @@ -102,7 +102,7 @@ class Gist extends Requestable { * Check if a gist is starred by the user. * @see https://developer.github.com/v3/gists/#check-if-a-gist-is-starred * @param {Requestable.callback} [cb] - will receive true if the gist is starred and false if the gist is not starred - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ isStarred(cb) { return this._request204or404(`/gists/${this.__id}/star`, null, cb); @@ -112,7 +112,7 @@ class Gist extends Requestable { * List the gist's comments * @see https://developer.github.com/v3/gists/comments/#list-comments-on-a-gist * @param {Requestable.callback} [cb] - will receive the array of comments - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listComments(cb) { return this._requestAllPages(`/gists/${this.__id}/comments`, null, cb); @@ -123,7 +123,7 @@ class Gist extends Requestable { * @see https://developer.github.com/v3/gists/comments/#get-a-single-comment * @param {number} comment - the id of the comment * @param {Requestable.callback} [cb] - will receive the comment - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ getComment(comment, cb) { return this._request('GET', `/gists/${this.__id}/comments/${comment}`, null, cb); @@ -134,7 +134,7 @@ class Gist extends Requestable { * @see https://developer.github.com/v3/gists/comments/#create-a-comment * @param {string} comment - the comment to add * @param {Requestable.callback} [cb] - the function that receives the API result - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ createComment(comment, cb) { return this._request('POST', `/gists/${this.__id}/comments`, {body: comment}, cb); @@ -146,7 +146,7 @@ class Gist extends Requestable { * @param {number} comment - the id of the comment * @param {string} body - the new comment * @param {Requestable.callback} [cb] - will receive the modified comment - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ editComment(comment, body, cb) { return this._request('PATCH', `/gists/${this.__id}/comments/${comment}`, {body: body}, cb); @@ -157,7 +157,7 @@ class Gist extends Requestable { * @see https://developer.github.com/v3/gists/comments/#delete-a-comment * @param {number} comment - the id of the comment * @param {Requestable.callback} [cb] - will receive true if the request succeeds - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ deleteComment(comment, cb) { return this._request('DELETE', `/gists/${this.__id}/comments/${comment}`, null, cb); diff --git a/lib/GitHub.js b/lib/GitHub.js index 944fc868..1bf689fd 100644 --- a/lib/GitHub.js +++ b/lib/GitHub.js @@ -62,7 +62,7 @@ class GitHub { /** * create a new Team wrapper * @param {string} teamId - the name of the team - * @return {team} + * @return {Team} */ getTeam(teamId) { return new Team(teamId, this.__auth, this.__apiBase); diff --git a/lib/Issue.js b/lib/Issue.js index 07fa2b1a..d6939034 100644 --- a/lib/Issue.js +++ b/lib/Issue.js @@ -27,7 +27,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/#create-an-issue * @param {Object} issueData - the issue to create * @param {Requestable.callback} [cb] - will receive the created issue - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createIssue(issueData, cb) { return this._request('POST', `/repos/${this.__repository}/issues`, issueData, cb); @@ -38,7 +38,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/#list-issues-for-a-repository * @param {Object} options - filtering options * @param {Requestable.callback} [cb] - will receive the array of issues - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listIssues(options, cb) { return this._requestAllPages(`/repos/${this.__repository}/issues`, options, cb); @@ -49,7 +49,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/events/#list-events-for-an-issue * @param {number} issue - the issue to get events for * @param {Requestable.callback} [cb] - will receive the list of events - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listIssueEvents(issue, cb) { return this._request('GET', `/repos/${this.__repository}/issues/${issue}/events`, null, cb); @@ -60,7 +60,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/comments/#list-comments-on-an-issue * @param {number} issue - the id of the issue to get comments from * @param {Requestable.callback} [cb] - will receive the comments - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listIssueComments(issue, cb) { return this._request('GET', `/repos/${this.__repository}/issues/${issue}/comments`, null, cb); @@ -71,7 +71,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/comments/#get-a-single-comment * @param {number} id - the comment id to get * @param {Requestable.callback} [cb] - will receive the comment - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getIssueComment(id, cb) { return this._request('GET', `/repos/${this.__repository}/issues/comments/${id}`, null, cb); @@ -83,7 +83,7 @@ class Issue extends Requestable { * @param {number} issue - the id of the issue to comment on * @param {string} comment - the comment to add * @param {Requestable.callback} [cb] - will receive the created comment - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createIssueComment(issue, comment, cb) { return this._request('POST', `/repos/${this.__repository}/issues/${issue}/comments`, {body: comment}, cb); @@ -95,7 +95,7 @@ class Issue extends Requestable { * @param {number} id - the comment id to edit * @param {string} comment - the comment to edit * @param {Requestable.callback} [cb] - will receive the edited comment - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ editIssueComment(id, comment, cb) { return this._request('PATCH', `/repos/${this.__repository}/issues/comments/${id}`, {body: comment}, cb); @@ -106,7 +106,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/comments/#delete-a-comment * @param {number} id - the comment id to delete * @param {Requestable.callback} [cb] - will receive true if the request is successful - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteIssueComment(id, cb) { return this._request('DELETE', `/repos/${this.__repository}/issues/comments/${id}`, null, cb); @@ -118,7 +118,7 @@ class Issue extends Requestable { * @param {number} issue - the issue number to edit * @param {Object} issueData - the new issue data * @param {Requestable.callback} [cb] - will receive the modified issue - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ editIssue(issue, issueData, cb) { return this._request('PATCH', `/repos/${this.__repository}/issues/${issue}`, issueData, cb); @@ -129,7 +129,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/#get-a-single-issue * @param {number} issue - the issue number to fetch * @param {Requestable.callback} [cb] - will receive the issue - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getIssue(issue, cb) { return this._request('GET', `/repos/${this.__repository}/issues/${issue}`, null, cb); @@ -140,7 +140,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/milestones/#list-milestones-for-a-repository * @param {Object} options - filtering options * @param {Requestable.callback} [cb] - will receive the array of milestones - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listMilestones(options, cb) { return this._request('GET', `/repos/${this.__repository}/milestones`, options, cb); @@ -151,7 +151,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/milestones/#get-a-single-milestone * @param {string} milestone - the id of the milestone to fetch * @param {Requestable.callback} [cb] - will receive the array of milestones - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getMilestone(milestone, cb) { return this._request('GET', `/repos/${this.__repository}/milestones/${milestone}`, null, cb); @@ -162,7 +162,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/milestones/#create-a-milestone * @param {Object} milestoneData - the milestone definition * @param {Requestable.callback} [cb] - will receive the array of milestones - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createMilestone(milestoneData, cb) { return this._request('POST', `/repos/${this.__repository}/milestones`, milestoneData, cb); @@ -174,7 +174,7 @@ class Issue extends Requestable { * @param {string} milestone - the id of the milestone to edit * @param {Object} milestoneData - the updates to make to the milestone * @param {Requestable.callback} [cb] - will receive the array of milestones - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ editMilestone(milestone, milestoneData, cb) { return this._request('PATCH', `/repos/${this.__repository}/milestones/${milestone}`, milestoneData, cb); @@ -185,7 +185,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/milestones/#delete-a-milestone * @param {string} milestone - the id of the milestone to delete * @param {Requestable.callback} [cb] - will receive the array of milestones - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteMilestone(milestone, cb) { return this._request('DELETE', `/repos/${this.__repository}/milestones/${milestone}`, null, cb); @@ -196,7 +196,7 @@ class Issue extends Requestable { * @see https://developer.github.com/v3/issues/labels/#create-a-label * @param {Object} labelData - the label definition * @param {Requestable.callback} [cb] - will receive the object representing the label - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createLabel(labelData, cb) { return this._request('POST', `/repos/${this.__repository}/labels`, labelData, cb); diff --git a/lib/Markdown.js b/lib/Markdown.js index cb84851d..5890c017 100644 --- a/lib/Markdown.js +++ b/lib/Markdown.js @@ -15,7 +15,7 @@ class Markdown extends Requestable { * construct a RateLimit * @param {Requestable.auth} auth - the credentials to authenticate to GitHub * @param {string} [apiBase] - the base Github API URL - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ constructor(auth, apiBase) { super(auth, apiBase); @@ -29,7 +29,7 @@ class Markdown extends Requestable { * @param {string} [options.mode=markdown] - can be either `markdown` or `gfm` * @param {string} [options.context] - repository name if mode is gfm * @param {Requestable.callback} [cb] - will receive the converted html - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ render(options, cb) { return this._request('POST', '/markdown', options, cb); diff --git a/lib/Organization.js b/lib/Organization.js index 78354a8c..aad98d8e 100644 --- a/lib/Organization.js +++ b/lib/Organization.js @@ -27,7 +27,7 @@ class Organization extends Requestable { * @see https://developer.github.com/v3/repos/#create * @param {Object} options - the repository definition * @param {Requestable.callback} [cb] - will receive the created repository - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createRepo(options, cb) { return this._request('POST', `/orgs/${this.__name}/repos`, options, cb); @@ -37,7 +37,7 @@ class Organization extends Requestable { * List the repositories in an organization * @see https://developer.github.com/v3/repos/#list-organization-repositories * @param {Requestable.callback} [cb] - will receive the list of repositories - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getRepos(cb) { let requestOptions = this._getOptionsWithDefaults({direction: 'desc'}); @@ -49,7 +49,7 @@ class Organization extends Requestable { * Query if the user is a member or not * @param {string} username - the user in question * @param {Requestable.callback} [cb] - will receive true if the user is a member - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ isMember(username, cb) { return this._request204or404(`/orgs/${this.__name}/members/${username}`, null, cb); @@ -62,7 +62,7 @@ class Organization extends Requestable { * @param {string} [options.filter=all] - can be either `2fa_disabled` or `all` * @param {string} [options.role=all] - can be one of: `all`, `admin`, or `member` * @param {Requestable.callback} [cb] - will receive the list of users - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listMembers(options, cb) { return this._request('GET', `/orgs/${this.__name}/members`, options, cb); @@ -72,7 +72,7 @@ class Organization extends Requestable { * List the Teams in the Organization * @see https://developer.github.com/v3/orgs/teams/#list-teams * @param {Requestable.callback} [cb] - will receive the list of teams - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getTeams(cb) { return this._requestAllPages(`/orgs/${this.__name}/teams`, undefined, cb); @@ -88,7 +88,7 @@ class Organization extends Requestable { * @param {string} [options.privacy=secret] - The level of privacy the team should have. Can be either one * of: `secret`, or `closed` * @param {Requestable.callback} [cb] - will receive the created team - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createTeam(options, cb) { return this._request('POST', `/orgs/${this.__name}/teams`, options, cb); diff --git a/lib/RateLimit.js b/lib/RateLimit.js index cdc1fd24..4e08fe2a 100644 --- a/lib/RateLimit.js +++ b/lib/RateLimit.js @@ -15,7 +15,7 @@ class RateLimit extends Requestable { * construct a RateLimit * @param {Requestable.auth} auth - the credentials to authenticate to GitHub * @param {string} [apiBase] - the base Github API URL - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ constructor(auth, apiBase) { super(auth, apiBase); @@ -25,7 +25,7 @@ class RateLimit extends Requestable { * Query the current rate limit * @see https://developer.github.com/v3/rate_limit/ * @param {Requestable.callback} [cb] - will receive the rate-limit data - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getRateLimit(cb) { return this._request('GET', '/rate_limit', null, cb); diff --git a/lib/Repository.js b/lib/Repository.js index 301e1230..e619aedb 100644 --- a/lib/Repository.js +++ b/lib/Repository.js @@ -15,6 +15,7 @@ const log = debug('github:repository'); /** * Respository encapsulates the functionality to create, query, and modify files. + * @class Repository */ class Repository extends Requestable { /** @@ -37,7 +38,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/git/refs/#get-a-reference * @param {string} ref - the reference to get * @param {Requestable.callback} [cb] - will receive the reference's refSpec or a list of refSpecs that match `ref` - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getRef(ref, cb) { return this._request('GET', `/repos/${this.__fullname}/git/refs/${ref}`, null, cb); @@ -48,7 +49,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/git/refs/#create-a-reference * @param {Object} options - the object describing the ref * @param {Requestable.callback} [cb] - will receive the ref - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createRef(options, cb) { return this._request('POST', `/repos/${this.__fullname}/git/refs`, options, cb); @@ -59,7 +60,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/git/refs/#delete-a-reference * @param {string} ref - the name of the ref to delte * @param {Requestable.callback} [cb] - will receive true if the request is successful - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteRef(ref, cb) { return this._request('DELETE', `/repos/${this.__fullname}/git/refs/${ref}`, null, cb); @@ -69,7 +70,7 @@ class Repository extends Requestable { * Delete a repository * @see https://developer.github.com/v3/repos/#delete-a-repository * @param {Requestable.callback} [cb] - will receive true if the request is successful - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteRepo(cb) { return this._request('DELETE', `/repos/${this.__fullname}`, null, cb); @@ -79,7 +80,7 @@ class Repository extends Requestable { * List the tags on a repository * @see https://developer.github.com/v3/repos/#list-tags * @param {Requestable.callback} [cb] - will receive the tag data - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listTags(cb) { return this._request('GET', `/repos/${this.__fullname}/tags`, null, cb); @@ -90,7 +91,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/pulls/#list-pull-requests * @param {Object} options - options to filter the search * @param {Requestable.callback} [cb] - will receive the list of PRs - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listPullRequests(options, cb) { options = options || {}; @@ -102,7 +103,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/pulls/#get-a-single-pull-request * @param {number} number - the PR you wish to fetch * @param {Requestable.callback} [cb] - will receive the PR from the API - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getPullRequest(number, cb) { return this._request('GET', `/repos/${this.__fullname}/pulls/${number}`, null, cb); @@ -113,7 +114,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/pulls/#list-pull-requests-files * @param {number|string} number - the PR you wish to fetch * @param {Requestable.callback} [cb] - will receive the list of files from the API - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listPullRequestFiles(number, cb) { return this._request('GET', `/repos/${this.__fullname}/pulls/${number}/files`, null, cb); @@ -125,7 +126,7 @@ class Repository extends Requestable { * @param {string} base - the base commit * @param {string} head - the head commit * @param {Requestable.callback} cb - will receive the comparison - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ compareBranches(base, head, cb) { return this._request('GET', `/repos/${this.__fullname}/compare/${base}...${head}`, null, cb); @@ -135,7 +136,7 @@ class Repository extends Requestable { * List all the branches for the repository * @see https://developer.github.com/v3/repos/#list-branches * @param {Requestable.callback} cb - will receive the list of branches - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listBranches(cb) { return this._request('GET', `/repos/${this.__fullname}/branches`, null, cb); @@ -146,7 +147,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/git/blobs/#get-a-blob * @param {string} sha - the sha of the blob to fetch * @param {Requestable.callback} cb - will receive the blob from the API - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getBlob(sha, cb) { return this._request('GET', `/repos/${this.__fullname}/git/blobs/${sha}`, null, cb, 'raw'); @@ -157,7 +158,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/branches/#get-branch * @param {string} branch - the name of the branch to fetch * @param {Requestable.callback} cb - will receive the branch from the API - * @returns {Promise} - the promise for the http request + * @returns {axios.Promise} - the promise for the http request */ getBranch(branch, cb) { return this._request('GET', `/repos/${this.__fullname}/branches/${branch}`, null, cb); @@ -168,7 +169,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/commits/#get-a-single-commit * @param {string} sha - the sha for the commit to fetch * @param {Requestable.callback} cb - will receive the commit data - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getCommit(sha, cb) { return this._request('GET', `/repos/${this.__fullname}/git/commits/${sha}`, null, cb); @@ -184,7 +185,7 @@ class Repository extends Requestable { * @param {(Date|string)} [options.since] - only commits after this date will be returned * @param {(Date|string)} [options.until] - only commits before this date will be returned * @param {Requestable.callback} cb - will receive the list of commits found matching the criteria - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listCommits(options, cb) { options = options || {}; @@ -200,7 +201,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/commits/#get-a-single-commit * @param {string} ref - the reference for the commit-ish * @param {Requestable.callback} cb - will receive the commit information - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getSingleCommit(ref, cb) { ref = ref || ''; @@ -213,7 +214,7 @@ class Repository extends Requestable { * @param {string} [branch] - the branch to look in, or the repository's default branch if omitted * @param {string} path - the path of the file or directory * @param {Requestable.callback} cb - will receive a description of the requested object, including a `SHA` property - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getSha(branch, path, cb) { branch = branch ? `?ref=${branch}` : ''; @@ -225,7 +226,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/statuses/#list-statuses-for-a-specific-ref * @param {string} sha - the sha, branch, or tag to get statuses for * @param {Requestable.callback} cb - will receive the list of statuses - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listStatuses(sha, cb) { return this._request('GET', `/repos/${this.__fullname}/commits/${sha}/statuses`, null, cb); @@ -236,18 +237,22 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/git/trees/#get-a-tree * @param {string} treeSHA - the SHA of the tree to fetch * @param {Requestable.callback} cb - will receive the callback data - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getTree(treeSHA, cb) { return this._request('GET', `/repos/${this.__fullname}/git/trees/${treeSHA}`, null, cb); } + /** + * @todo Define a better type for Blob + * @typedef Blob + */ /** * Create a blob * @see https://developer.github.com/v3/git/blobs/#create-a-blob - * @param {(string|Buffer|Blob)} content - the content to add to the repository + * @param {string|Buffer|Blob} content - the content to add to the repository * @param {Requestable.callback} cb - will receive the details of the created blob - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createBlob(content, cb) { let postBody = this._getContentObject(content); @@ -296,7 +301,7 @@ class Repository extends Requestable { * @param {string} path - the path for the new file * @param {string} blobSHA - the SHA for the blob to put at `path` * @param {Requestable.callback} cb - will receive the new tree that is created - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request * @deprecated use {@link Repository#createTree} instead */ updateTree(baseTreeSHA, path, blobSHA, cb) { @@ -319,7 +324,7 @@ class Repository extends Requestable { * @param {Object} tree - the tree to create * @param {string} baseSHA - the root sha of the tree * @param {Requestable.callback} cb - will receive the new tree that is created - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createTree(tree, baseSHA, cb) { return this._request('POST', `/repos/${this.__fullname}/git/trees`, { @@ -335,7 +340,7 @@ class Repository extends Requestable { * @param {string} tree - the SHA of the tree for this commit * @param {string} message - the commit message * @param {Requestable.callback} cb - will receive the commit that is created - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ commit(parent, tree, message, cb) { let data = { @@ -358,7 +363,7 @@ class Repository extends Requestable { * @param {string} commitSHA - the SHA to point the reference to * @param {boolean} force - indicates whether to force or ensure a fast-forward update * @param {Requestable.callback} cb - will receive the updated ref back - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ updateHead(ref, commitSHA, force, cb) { return this._request('PATCH', `/repos/${this.__fullname}/git/refs/${ref}`, { @@ -371,7 +376,7 @@ class Repository extends Requestable { * Get information about the repository * @see https://developer.github.com/v3/repos/#get * @param {Requestable.callback} cb - will receive the information about the repository - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getDetails(cb) { return this._request('GET', `/repos/${this.__fullname}`, null, cb); @@ -381,7 +386,7 @@ class Repository extends Requestable { * List the contributors to the repository * @see https://developer.github.com/v3/repos/#list-contributors * @param {Requestable.callback} cb - will receive the list of contributors - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getContributors(cb) { return this._request('GET', `/repos/${this.__fullname}/stats/contributors`, null, cb); @@ -392,7 +397,7 @@ class Repository extends Requestable { * push access to use this method * @see https://developer.github.com/v3/repos/collaborators/#list-collaborators * @param {Requestable.callback} cb - will receive the list of collaborators - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getCollaborators(cb) { return this._request('GET', `/repos/${this.__fullname}/collaborators`, null, cb); @@ -403,7 +408,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/collaborators/#check-if-a-user-is-a-collaborator * @param {string} username - the user to check * @param {Requestable.callback} cb - will receive true if the user is a collaborator and false if they are not - * @return {Promise} - the promise for the http request {Boolean} [description] + * @return {axios.Promise} - the promise for the http request {Boolean} [description] */ isCollaborator(username, cb) { return this._request('GET', `/repos/${this.__fullname}/collaborators/${username}`, null, cb); @@ -416,7 +421,7 @@ class Repository extends Requestable { * @param {string} path - the path containing the content to fetch * @param {boolean} raw - `true` if the results should be returned raw instead of GitHub's normalized format * @param {Requestable.callback} cb - will receive the fetched data - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getContents(ref, path, raw, cb) { path = path ? `${encodeURI(path)}` : ''; @@ -431,7 +436,7 @@ class Repository extends Requestable { * @param {string} ref - the ref to check * @param {boolean} raw - `true` if the results should be returned raw instead of GitHub's normalized format * @param {Requestable.callback} cb - will receive the fetched data - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getReadme(ref, raw, cb) { return this._request('GET', `/repos/${this.__fullname}/readme`, { @@ -443,7 +448,7 @@ class Repository extends Requestable { * Fork a repository * @see https://developer.github.com/v3/repos/forks/#create-a-fork * @param {Requestable.callback} cb - will receive the information about the newly created fork - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ fork(cb) { return this._request('POST', `/repos/${this.__fullname}/forks`, null, cb); @@ -453,7 +458,7 @@ class Repository extends Requestable { * List a repository's forks * @see https://developer.github.com/v3/repos/forks/#list-forks * @param {Requestable.callback} cb - will receive the list of repositories forked from this one - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listForks(cb) { return this._request('GET', `/repos/${this.__fullname}/forks`, null, cb); @@ -464,7 +469,7 @@ class Repository extends Requestable { * @param {string} [oldBranch=master] - the name of the existing branch * @param {string} newBranch - the name of the new branch * @param {Requestable.callback} cb - will receive the commit data for the head of the new branch - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createBranch(oldBranch, newBranch, cb) { if (typeof newBranch === 'function') { @@ -488,7 +493,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/pulls/#create-a-pull-request * @param {Object} options - the pull request description * @param {Requestable.callback} cb - will receive the new pull request - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createPullRequest(options, cb) { return this._request('POST', `/repos/${this.__fullname}/pulls`, options, cb); @@ -501,7 +506,7 @@ class Repository extends Requestable { * @param {number|string} number - the number of the pull request to update * @param {Object} options - the pull request description * @param {Requestable.callback} [cb] - will receive the pull request information - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ updatePullRequst(number, options, cb) { log('Deprecated: This method contains a typo and it has been deprecated. It will be removed in next major version. Use updatePullRequest() instead.'); @@ -515,7 +520,7 @@ class Repository extends Requestable { * @param {number|string} number - the number of the pull request to update * @param {Object} options - the pull request description * @param {Requestable.callback} [cb] - will receive the pull request information - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ updatePullRequest(number, options, cb) { return this._request('PATCH', `/repos/${this.__fullname}/pulls/${number}`, options, cb); @@ -525,7 +530,7 @@ class Repository extends Requestable { * List the hooks for the repository * @see https://developer.github.com/v3/repos/hooks/#list-hooks * @param {Requestable.callback} cb - will receive the list of hooks - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listHooks(cb) { return this._request('GET', `/repos/${this.__fullname}/hooks`, null, cb); @@ -536,7 +541,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/hooks/#get-single-hook * @param {number} id - the id of the webook * @param {Requestable.callback} cb - will receive the details of the webook - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getHook(id, cb) { return this._request('GET', `/repos/${this.__fullname}/hooks/${id}`, null, cb); @@ -547,7 +552,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/hooks/#create-a-hook * @param {Object} options - the configuration describing the new hook * @param {Requestable.callback} cb - will receive the new webhook - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createHook(options, cb) { return this._request('POST', `/repos/${this.__fullname}/hooks`, options, cb); @@ -559,7 +564,7 @@ class Repository extends Requestable { * @param {number} id - the id of the webhook * @param {Object} options - the new description of the webhook * @param {Requestable.callback} cb - will receive the updated webhook - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ updateHook(id, options, cb) { return this._request('PATCH', `/repos/${this.__fullname}/hooks/${id}`, options, cb); @@ -570,7 +575,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/hooks/#delete-a-hook * @param {number} id - the id of the webhook to be deleted * @param {Requestable.callback} cb - will receive true if the call is successful - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteHook(id, cb) { return this._request('DELETE', `${this.__fullname}/hooks/${id}`, null, cb); @@ -580,7 +585,7 @@ class Repository extends Requestable { * List the deploy keys for the repository * @see https://developer.github.com/v3/repos/keys/#list-deploy-keys * @param {Requestable.callback} cb - will receive the list of deploy keys - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listKeys(cb) { return this._request('GET', `/repos/${this.__fullname}/keys`, null, cb); @@ -591,7 +596,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/keys/#get-a-deploy-key * @param {number} id - the id of the deploy key * @param {Requestable.callback} cb - will receive the details of the deploy key - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getKey(id, cb) { return this._request('GET', `/repos/${this.__fullname}/keys/${id}`, null, cb); @@ -602,7 +607,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/keys/#add-a-new-deploy-key * @param {Object} options - the configuration describing the new deploy key * @param {Requestable.callback} cb - will receive the new deploy key - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createKey(options, cb) { return this._request('POST', `/repos/${this.__fullname}/keys`, options, cb); @@ -613,7 +618,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/keys/#remove-a-deploy-key * @param {number} id - the id of the deploy key to be deleted * @param {Requestable.callback} cb - will receive true if the call is successful - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteKey(id, cb) { return this._request('DELETE', `/repos/${this.__fullname}/keys/${id}`, null, cb); @@ -625,7 +630,7 @@ class Repository extends Requestable { * @param {string} branch - the branch to delete from, or the default branch if not specified * @param {string} path - the path of the file to remove * @param {Requestable.callback} cb - will receive the commit in which the delete occurred - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteFile(branch, path, cb) { return this.getSha(branch, path) @@ -645,7 +650,7 @@ class Repository extends Requestable { * @param {string} oldPath - original path * @param {string} newPath - new reference path * @param {Requestable.callback} cb - will receive the commit in which the move occurred - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ move(branch, oldPath, newPath, cb) { let oldSha; @@ -680,7 +685,7 @@ class Repository extends Requestable { * @param {Object} [options.commiter] - the committer * @param {boolean} [options.encode] - true if the content should be base64 encoded * @param {Requestable.callback} cb - will receive the new commit - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ writeFile(branch, path, content, message, options, cb) { if (typeof options === 'function') { @@ -711,7 +716,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/activity/starring/#check-if-you-are-starring-a-repository * @param {Requestable.callback} cb - will receive true if the repository is starred and false if the repository * is not starred - * @return {Promise} - the promise for the http request {Boolean} [description] + * @return {axios.Promise} - the promise for the http request {Boolean} [description] */ isStarred(cb) { return this._request204or404(`/user/starred/${this.__fullname}`, null, cb); @@ -721,7 +726,7 @@ class Repository extends Requestable { * Star a repository * @see https://developer.github.com/v3/activity/starring/#star-a-repository * @param {Requestable.callback} cb - will receive true if the repository is starred - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ star(cb) { return this._request('PUT', `/user/starred/${this.__fullname}`, null, cb); @@ -731,7 +736,7 @@ class Repository extends Requestable { * Unstar a repository * @see https://developer.github.com/v3/activity/starring/#unstar-a-repository * @param {Requestable.callback} cb - will receive true if the repository is unstarred - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ unstar(cb) { return this._request('DELETE', `/user/starred/${this.__fullname}`, null, cb); @@ -742,7 +747,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/releases/#create-a-release * @param {Object} options - the description of the release * @param {Requestable.callback} cb - will receive the newly created release - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createRelease(options, cb) { return this._request('POST', `/repos/${this.__fullname}/releases`, options, cb); @@ -754,7 +759,7 @@ class Repository extends Requestable { * @param {string} id - the id of the release * @param {Object} options - the description of the release * @param {Requestable.callback} cb - will receive the modified release - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ updateRelease(id, options, cb) { return this._request('PATCH', `/repos/${this.__fullname}/releases/${id}`, options, cb); @@ -764,7 +769,7 @@ class Repository extends Requestable { * Get information about all releases * @see https://developer.github.com/v3/repos/releases/#list-releases-for-a-repository * @param {Requestable.callback} cb - will receive the release information - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listReleases(cb) { return this._request('GET', `/repos/${this.__fullname}/releases`, null, cb); @@ -775,7 +780,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/releases/#get-a-single-release * @param {string} id - the id of the release * @param {Requestable.callback} cb - will receive the release information - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getRelease(id, cb) { return this._request('GET', `/repos/${this.__fullname}/releases/${id}`, null, cb); @@ -786,7 +791,7 @@ class Repository extends Requestable { * @see https://developer.github.com/v3/repos/releases/#delete-a-release * @param {string} id - the release to be deleted * @param {Requestable.callback} cb - will receive true if the operation is successful - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteRelease(id, cb) { return this._request('DELETE', `/repos/${this.__fullname}/releases/${id}`, null, cb); @@ -798,7 +803,7 @@ class Repository extends Requestable { * @param {number|string} number - the number of the pull request to merge * @param {Object} options - the merge options for the pull request * @param {Requestable.callback} [cb] - will receive the merge information if the operation is successful - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ mergePullRequest(number, options, cb) { return this._request('PUT', `/repos/${this.__fullname}/pulls/${number}/merge`, options, cb); diff --git a/lib/Requestable.js b/lib/Requestable.js index 95c23bbd..c31e4239 100644 --- a/lib/Requestable.js +++ b/lib/Requestable.js @@ -21,7 +21,7 @@ if (typeof Promise === 'undefined') { */ class ResponseError extends Error { /** - * Construct a new ResponseError + * @typedef {ResponseError} Requestable.Error * @param {string} message - an message to return instead of the the default error message * @param {string} path - the requested path * @param {Object} response - the object returned by Axios @@ -37,14 +37,15 @@ class ResponseError extends Error { /** * Requestable wraps the logic for making http requests to the API + * @class Requestable */ class Requestable { /** * Either a username and password or an oauth token for Github - * @typedef {Object} Requestable.auth - * @prop {string} [username] - the Github username - * @prop {string} [password] - the user's password - * @prop {token} [token] - an OAuth token + * @typedef Requestable.auth + * @property {string} [username] - the Github username + * @property {string} [password] - the user's password + * @property {string} [token] - an OAuth token */ /** * Initialize the http internals. @@ -121,7 +122,7 @@ class Requestable { /** * if a `Date` is passed to this function it will be converted to an ISO string - * @param {*} date - the object to attempt to cooerce into an ISO date string + * @param {Date} date - the object to attempt to cooerce into an ISO date string * @return {string} - the ISO representation of `date` or whatever was passed in if it was not a date */ _dateToISO(date) { @@ -136,19 +137,19 @@ class Requestable { * A function that receives the result of the API request. * @callback Requestable.callback * @param {Requestable.Error} error - the error returned by the API or `null` - * @param {(Object|true)} result - the data returned by the API or `true` if the API returns `204 No Content` - * @param {Object} request - the raw {@linkcode https://github.com/mzabriskie/axios#response-schema Response} + * @param {axios.Response | boolean} result - the data returned by the API or `true` if the API returns `204 No Content` + * @param {axios.RequestOptions} request - the raw {@linkcode https://github.com/mzabriskie/axios#response-schema Response} */ /** * Make a request. * @param {string} method - the method for the request (GET, PUT, POST, DELETE) * @param {string} path - the path for the request - * @param {*} [data] - the data to send to the server. For HTTP methods that don't have a body the data + * @param {any} [data] - the data to send to the server. For HTTP methods that don't have a body the data * will be sent as query parameters * @param {Requestable.callback} [cb] - the callback for the request * @param {boolean} [raw=false] - if the request should be sent as raw. If this is a falsy value then the * request will be made as JSON - * @return {Promise} - the Promise for the http request + * @return {axios.Promise} - the Promise for the http request */ _request(method, path, data, cb, raw) { const url = this.__getURL(path); @@ -188,7 +189,7 @@ class Requestable { * @param {Object} data - any query parameters for the request * @param {Requestable.callback} cb - the callback that will receive `true` or `false` * @param {method} [method=GET] - HTTP Method to use - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ _request204or404(path, data, cb, method = 'GET') { return this._request(method, path, data) @@ -219,7 +220,7 @@ class Requestable { * @param {Object} options - the query parameters to include * @param {Requestable.callback} [cb] - the function to receive the data. The returned data will always be an array. * @param {Object[]} results - the partial results. This argument is intended for interal use only. - * @return {Promise} - a promise which will resolve when all pages have been fetched + * @return {axios.Promise} - a promise which will resolve when all pages have been fetched * @deprecated This will be folded into {@link Requestable#_request} in the 2.0 release. */ _requestAllPages(path, options, cb, results) { diff --git a/lib/Search.js b/lib/Search.js index e0bde4fb..c1a34c00 100644 --- a/lib/Search.js +++ b/lib/Search.js @@ -11,6 +11,8 @@ const log = debug('github:search'); /** * Wrap the Search API + * @class Search + * @extends Requestable */ class Search extends Requestable { /** @@ -27,19 +29,20 @@ class Search extends Requestable { /** * Available search options * @see https://developer.github.com/v3/search/#parameters - * @typedef {Object} Search.Params - * @param {string} q - the query to make - * @param {string} sort - the sort field, one of `stars`, `forks`, or `updated`. + * @member Search.Params + * @property {string} q - the query to make + * @property {string} sort - the sort field, one of `stars`, `forks`, or `updated`. * Default is [best match](https://developer.github.com/v3/search/#ranking-search-results) - * @param {string} order - the ordering, either `asc` or `desc` + * @property {string} order - the ordering, either `asc` or `desc` */ + /** * Perform a search on the GitHub API * @private * @param {string} path - the scope of the search * @param {Search.Params} [withOptions] - additional parameters for the search * @param {Requestable.callback} [cb] - will receive the results of the search - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ _search(path, withOptions = {}, cb = undefined) { let requestOptions = {}; @@ -59,7 +62,7 @@ class Search extends Requestable { * @see https://developer.github.com/v3/search/#search-repositories * @param {Search.Params} [options] - additional parameters for the search * @param {Requestable.callback} [cb] - will receive the results of the search - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ forRepositories(options, cb) { return this._search('repositories', options, cb); @@ -70,7 +73,7 @@ class Search extends Requestable { * @see https://developer.github.com/v3/search/#search-code * @param {Search.Params} [options] - additional parameters for the search * @param {Requestable.callback} [cb] - will receive the results of the search - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ forCode(options, cb) { return this._search('code', options, cb); @@ -81,7 +84,7 @@ class Search extends Requestable { * @see https://developer.github.com/v3/search/#search-issues * @param {Search.Params} [options] - additional parameters for the search * @param {Requestable.callback} [cb] - will receive the results of the search - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ forIssues(options, cb) { return this._search('issues', options, cb); @@ -92,7 +95,7 @@ class Search extends Requestable { * @see https://developer.github.com/v3/search/#search-users * @param {Search.Params} [options] - additional parameters for the search * @param {Requestable.callback} [cb] - will receive the results of the search - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ forUsers(options, cb) { return this._search('users', options, cb); diff --git a/lib/Team.js b/lib/Team.js index f91c9173..d47a926b 100644 --- a/lib/Team.js +++ b/lib/Team.js @@ -28,7 +28,7 @@ class Team extends Requestable { * Get Team information * @see https://developer.github.com/v3/orgs/teams/#get-team * @param {Requestable.callback} [cb] - will receive the team - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getTeam(cb) { log(`Fetching Team ${this.__teamId}`); @@ -39,7 +39,7 @@ class Team extends Requestable { * List the Team's repositories * @see https://developer.github.com/v3/orgs/teams/#list-team-repos * @param {Requestable.callback} [cb] - will receive the list of repositories - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listRepos(cb) { log(`Fetching repositories for Team ${this.__teamId}`); @@ -56,7 +56,7 @@ class Team extends Requestable { * @param {string} [options.privacy=secret] - The level of privacy the team should have. Can be either one * of: `secret`, or `closed` * @param {Requestable.callback} [cb] - will receive the updated team - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ editTeam(options, cb) { log(`Editing Team ${this.__teamId}`); @@ -69,7 +69,7 @@ class Team extends Requestable { * @param {object} options - Parameters for listing team users * @param {string} [options.role=all] - can be one of: `all`, `maintainer`, or `member` * @param {Requestable.callback} [cb] - will receive the list of users - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listMembers(options, cb) { log(`Getting members of Team ${this.__teamId}`); @@ -81,7 +81,7 @@ class Team extends Requestable { * @see https://developer.github.com/v3/orgs/teams/#get-team-membership * @param {string} username - can be one of: `all`, `maintainer`, or `member` * @param {Requestable.callback} [cb] - will receive the membership status of a user - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getMembership(username, cb) { log(`Getting membership of user ${username} in Team ${this.__teamId}`); @@ -96,7 +96,7 @@ class Team extends Requestable { * @param {string} [options.role=member] - The role that this user should have in the team. Can be one * of: `member`, or `maintainer` * @param {Requestable.callback} [cb] - will receive the membership status of added user - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ addMembership(username, options, cb) { log(`Adding user ${username} to Team ${this.__teamId}`); @@ -109,7 +109,7 @@ class Team extends Requestable { * @param {string} owner - Organization name * @param {string} repo - Repo name * @param {Requestable.callback} [cb] - will receive the membership status of added user - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ isManagedRepo(owner, repo, cb) { log(`Getting repo management by Team ${this.__teamId} for repo ${owner}/${repo}`); @@ -125,7 +125,7 @@ class Team extends Requestable { * @param {string} [options.permission] - The permission to grant the team on this repository. Can be one * of: `pull`, `push`, or `admin` * @param {Requestable.callback} [cb] - will receive the membership status of added user - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ manageRepo(owner, repo, options, cb) { log(`Adding or Updating repo management by Team ${this.__teamId} for repo ${owner}/${repo}`); @@ -138,7 +138,7 @@ class Team extends Requestable { * @param {string} owner - Organization name * @param {string} repo - Repo name * @param {Requestable.callback} [cb] - will receive the membership status of added user - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ unmanageRepo(owner, repo, cb) { log(`Remove repo management by Team ${this.__teamId} for repo ${owner}/${repo}`); @@ -149,7 +149,7 @@ class Team extends Requestable { * Delete Team * @see https://developer.github.com/v3/orgs/teams/#delete-team * @param {Requestable.callback} [cb] - will receive the list of repositories - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ deleteTeam(cb) { log(`Deleting Team ${this.__teamId}`); diff --git a/lib/User.js b/lib/User.js index be86c4fc..e8d99e41 100644 --- a/lib/User.js +++ b/lib/User.js @@ -57,7 +57,7 @@ class User extends Requestable { * @see https://developer.github.com/v3/repos/#list-user-repositories * @param {Object} [options={}] - any options to refine the search * @param {Requestable.callback} [cb] - will receive the list of repositories - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listRepos(options, cb) { if (typeof options === 'function') { @@ -75,7 +75,7 @@ class User extends Requestable { * List the orgs that the user belongs to * @see https://developer.github.com/v3/orgs/#list-user-organizations * @param {Requestable.callback} [cb] - will receive the list of organizations - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listOrgs(cb) { return this._request('GET', this.__getScopedUrl('orgs'), null, cb); @@ -85,7 +85,7 @@ class User extends Requestable { * List the user's gists * @see https://developer.github.com/v3/gists/#list-a-users-gists * @param {Requestable.callback} [cb] - will receive the list of gists - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listGists(cb) { return this._request('GET', this.__getScopedUrl('gists'), null, cb); @@ -96,7 +96,7 @@ class User extends Requestable { * @see https://developer.github.com/v3/activity/notifications/#list-your-notifications * @param {Object} [options={}] - any options to refine the search * @param {Requestable.callback} [cb] - will receive the list of repositories - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listNotifications(options, cb) { options = options || {}; @@ -115,7 +115,7 @@ class User extends Requestable { * Show the user's profile * @see https://developer.github.com/v3/users/#get-a-single-user * @param {Requestable.callback} [cb] - will receive the user's information - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ getProfile(cb) { return this._request('GET', this.__getScopedUrl(''), null, cb); @@ -125,7 +125,7 @@ class User extends Requestable { * Gets the list of starred repositories for the user * @see https://developer.github.com/v3/activity/starring/#list-repositories-being-starred * @param {Requestable.callback} [cb] - will receive the list of starred repositories - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ listStarredRepos(cb) { let requestOptions = this._getOptionsWithDefaults(); @@ -137,7 +137,7 @@ class User extends Requestable { * @see https://developer.github.com/v3/users/followers/#follow-a-user * @param {string} username - the user to follow * @param {Requestable.callback} [cb] - will receive true if the request succeeds - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ follow(username, cb) { return this._request('PUT', `/user/following/${this.__user}`, null, cb); @@ -148,7 +148,7 @@ class User extends Requestable { * @see https://developer.github.com/v3/users/followers/#follow-a-user * @param {string} username - the user to unfollow * @param {Requestable.callback} [cb] - receives true if the request succeeds - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ unfollow(username, cb) { return this._request('DELETE', `/user/following/${this.__user}`, null, cb); @@ -159,7 +159,7 @@ class User extends Requestable { * @see https://developer.github.com/v3/repos/#create * @param {object} options - the repository definition * @param {Requestable.callback} [cb] - will receive the API response - * @return {Promise} - the promise for the http request + * @return {axios.Promise} - the promise for the http request */ createRepo(options, cb) { return this._request('POST', '/user/repos', options, cb); diff --git a/package.json b/package.json index c942525d..21aed734 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,7 @@ "license": "BSD-3-Clause-Clear", "description": "A higher-level wrapper around the Github API.", "main": "dist/components/GitHub.js", + "types": "github-api.d.ts", "contributors": [ "Ændrew Rininsland (http://www.aendrew.com)", "Aurelio De Rosa (http://www.audero.it/)", @@ -17,7 +18,8 @@ "test": "mocha --opts ./mocha.opts test/*.spec.js", "test-verbose": "DEBUG=github* npm test", "lint": "gulp lint", - "make-docs": "node_modules/.bin/jsdoc -c .jsdoc.json --verbose", + "make-docs": "jsdoc -c .jsdoc.json --verbose", + "make-ts-def": "jsdoc -c .jsdoc-ts.json --verbose", "release": "./release.sh" }, "babel": { @@ -52,6 +54,7 @@ "utf8": "^2.1.1" }, "devDependencies": { + "@types/node": "^6.0.41", "babel-core": "^6.7.7", "babel-plugin-transform-es2015-modules-umd": "^6.5.0", "babel-preset-es2015": "^6.5.0", @@ -75,6 +78,7 @@ "mocha": "^2.3.4", "must": "^0.13.1", "nock": "^8.0.0", + "tsd-jsdoc": "^1.0.1", "vinyl-buffer": "^1.0.0", "vinyl-source-stream": "^1.1.0" }, diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 00000000..9abcfd55 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,6 @@ +{ + "compilerOptions": { + "lib": [ "es2015.promise", "es2015"] + }, + "types": ["node"] +}