Files
Superalgos/node_modules/octokit/octokit.coffee
T

1546 lines
52 KiB
CoffeeScript

# Github Promise API
# ======
#
# This class provides a Promise API for accessing GitHub.
# Most methods return a Promise object whose value is resolved when `.then(doneFn, failFn)`
# is called.
#
# Based on Github.js 0.7.0
#
# (c) 2012 Michael Aufreiter, Development Seed
# Github.js is freely distributable under the MIT license.
# For all details and documentation:
# http://substance.io/michael/github
# Underscore shim
# =========
#
# The following code is a shim for the underscore.js functions this code relise on
_ = {}
_.isEmpty = (object) ->
Object.keys(object).length == 0
_.isArray = Array.isArray or (obj) ->
toString.call(obj) is'[object Array]'
_.defaults = (object, values) ->
for key in Object.keys(values)
do (key) ->
object[key] ?= values[key]
_.each = (object, fn) ->
return if not object
if _.isArray(object)
object.forEach(fn)
arr = []
for key in Object.keys(object)
do (key) ->
fn(object[key])
_.pairs = (object) ->
arr = []
for key in Object.keys(object)
do (key) ->
arr.push([key, object[key]])
return arr
_.map = (object, fn) ->
if _.isArray(object)
return object.map(fn)
arr = []
for key in Object.keys(object)
do (key) ->
arr.push(fn(object[key]))
arr
_.last = (object, n) ->
len = object.length
object.slice(len - n, len)
_.select = (object, fn) ->
object.filter(fn)
_.extend = (object, template) ->
for key in Object.keys(template)
do (key) ->
object[key] = template[key]
object
_.toArray = (object) ->
return Array.prototype.slice.call(object)
# Generate a Github class
# =========
#
# Depending on how this is loaded (nodejs, requirejs, globals)
# the actual underscore, jQuery.ajax/Deferred, and base64 encode functions may differ.
makeOctokit = (newPromise, allPromises, XMLHttpRequest, base64encode, userAgent) =>
# Simple jQuery.ajax() shim that returns a promise for a xhr object
ajax = (options) ->
return newPromise (resolve, reject) ->
xhr = new XMLHttpRequest()
xhr.dataType = options.dataType
xhr.overrideMimeType?(options.mimeType)
xhr.open(options.type, options.url)
if options.data and 'GET' != options.type
xhr.setRequestHeader('Content-Type', options.contentType)
for name, value of options.headers
xhr.setRequestHeader(name, value)
xhr.onreadystatechange = () ->
if 4 == xhr.readyState
options.statusCode?[xhr.status]?()
if xhr.status >= 200 and xhr.status < 300 or xhr.status == 304
resolve(xhr)
else
reject(xhr)
xhr.send(options.data)
# Returns an always-resolved promise (like `Promise.resolve(val)` )
resolvedPromise = (val) ->
return newPromise (resolve, reject) -> resolve(val)
# Returns an always-rejected promise (like `Promise.reject(err)` )
rejectedPromise = (err) ->
return newPromise (resolve, reject) -> reject(err)
class Octokit
constructor: (clientOptions={}) ->
# Provide an option to override the default URL
_.defaults clientOptions,
rootURL: 'https://api.github.com'
useETags: true
usePostInsteadOfPatch: false
_client = @ # Useful for other classes (like Repo) to get the current Client object
# These are updated whenever a request is made
_listeners = []
# To support ETag caching cache the responses.
class ETagResponse
constructor: (@eTag, @data, @status) ->
# Cached responses are stored in this object keyed by `path`
_cachedETags = {}
# Send simple progress notifications
notifyStart = (promise, path) -> promise.notify? {type:'start', path:path}
notifyEnd = (promise, path) -> promise.notify? {type:'end', path:path}
# HTTP Request Abstraction
# =======
#
_request = (method, path, data, options={raw:false, isBase64:false, isBoolean:false}) ->
if 'PATCH' == method and clientOptions.usePostInsteadOfPatch
method = 'POST'
# Only prefix the path when it does not begin with http.
# This is so pagination works (which provides absolute URLs).
path = "#{clientOptions.rootURL}#{path}" if not /^http/.test(path)
# Support binary data by overriding the response mimeType
mimeType = undefined
mimeType = 'text/plain; charset=x-user-defined' if options.isBase64
headers = {
'Accept': 'application/vnd.github.raw'
}
# Set the `User-Agent` because it is required and NodeJS
# does not send one by default.
# See http://developer.github.com/v3/#user-agent-required
headers['User-Agent'] = userAgent if userAgent
# Send the ETag if re-requesting a URL
if path of _cachedETags
headers['If-None-Match'] = _cachedETags[path].eTag
else
# The browser will sneak in a 'If-Modified-Since' header if the GET has been requested before
# but for some reason the cached response does not seem to be available
# in the jqXHR object.
# So, the first time a URL is requested set this date to 0 so we always get a response the 1st time
# a URL is requested.
headers['If-Modified-Since'] = 'Thu, 01 Jan 1970 00:00:00 GMT'
if (clientOptions.token) or (clientOptions.username and clientOptions.password)
if clientOptions.token
auth = "token #{clientOptions.token}"
else
auth = 'Basic ' + base64encode("#{clientOptions.username}:#{clientOptions.password}")
headers['Authorization'] = auth
promise = newPromise (resolve, reject) ->
ajaxConfig =
# Be sure to **not** blow the cache with a random number
# (GitHub will respond with 5xx or CORS errors)
url: path
type: method
contentType: 'application/json'
mimeType: mimeType
headers: headers
processData: false # Don't convert to QueryString
data: !options.raw and data and JSON.stringify(data) or data
dataType: 'json' unless options.raw
# If the request is a boolean yes/no question GitHub will indicate
# via the HTTP Status of 204 (No Content) or 404 instead of a 200.
if options.isBoolean
ajaxConfig.statusCode =
# a Boolean 'yes'
204: () => resolve(true)
# a Boolean 'no'
404: () => resolve(false)
xhrPromise = ajax(ajaxConfig)
always = (jqXHR) =>
notifyEnd(@, path)
# Fire listeners when the request completes or fails
rateLimit = parseFloat(jqXHR.getResponseHeader 'X-RateLimit-Limit')
rateLimitRemaining = parseFloat(jqXHR.getResponseHeader 'X-RateLimit-Remaining')
for listener in _listeners
listener(rateLimitRemaining, rateLimit, method, path, data, options)
# Return the result and Base64 encode it if `options.isBase64` flag is set.
xhrPromise.then (jqXHR) ->
always(jqXHR)
# If the response was a 304 then return the cached version
if 304 == jqXHR.status
if clientOptions.useETags and _cachedETags[path]
eTagResponse = _cachedETags[path]
resolve(eTagResponse.data, eTagResponse.status, jqXHR)
else
resolve(jqXHR.responseText, status, jqXHR)
# If it was a boolean question and the server responded with 204
# return true.
else if 204 == jqXHR.status and options.isBoolean
resolve(true, status, jqXHR)
else
if jqXHR.responseText and 'json' == ajaxConfig.dataType
data = JSON.parse(jqXHR.responseText)
# Only JSON responses have next/prev/first/last link headers
# Add them to data so the resolved value is iterable
valOptions = {}
# Parse the Link headers
# of the form `<http://a.com>; rel="next", <https://b.com?a=b&c=d>; rel="previous"`
links = jqXHR.getResponseHeader('Link')
_.each links?.split(','), (part) ->
[discard, href, rel] = part.match(/<([^>]+)>;\ rel="([^"]+)"/)
# Name the functions `nextPage`, `previousPage`, `firstPage`, `lastPage`
valOptions["#{rel}Page"] = () -> _request('GET', href, null, options)
# Add the pagination functions on the JSON since Promises resolve one value
_.extend(data, valOptions)
else
data = jqXHR.responseText
# Convert the response to a Base64 encoded string
if 'GET' == method and options.isBase64
# Convert raw data to binary chopping off the higher-order bytes in each char.
# Useful for Base64 encoding.
converted = ''
for i in [0..data.length]
converted += String.fromCharCode(data.charCodeAt(i) & 0xff)
data = converted
# Cache the response to reuse later
if 'GET' == method and jqXHR.getResponseHeader('ETag') and clientOptions.useETags
eTag = jqXHR.getResponseHeader('ETag')
_cachedETags[path] = new ETagResponse(eTag, data, jqXHR.status)
resolve(data, jqXHR.status, jqXHR)
# Parse the error if one occurs
onError = (jqXHR) ->
always(jqXHR)
# If the request was for a Boolean then a 404 should be treated as a "false"
if options.isBoolean and 404 == jqXHR.status
resolve(false)
else
if jqXHR.getResponseHeader('Content-Type') != 'application/json; charset=utf-8'
err = new Error(jqXHR.responseText)
err['status'] = jqXHR.status
err['__jqXHR'] = jqXHR
reject(err)
else
err = new Error("Github error: #{jqXHR.responseText}")
if jqXHR.responseText
json = JSON.parse(jqXHR.responseText)
else
# In the case of 404 errors, `responseText` is an empty string
json = ''
# XXX: should be body or something else probably
err['error'] = json
err['status'] = jqXHR.status
err['__jqXHR'] = jqXHR
reject(err)
# Depending on the Promise implementation, the `catch` method may be `.catch` or `.fail`
xhrPromise.catch?(onError) or xhrPromise.fail(onError)
notifyStart(promise, path)
# Return the promise
return promise
# Converts a dictionary to a query string.
# Internal helper method
toQueryString = (options) ->
# Returns '' if `options` is empty so this string can always be appended to a URL
return '' if _.isEmpty(options)
params = []
_.each _.pairs(options), ([key, value]) ->
params.push "#{key}=#{encodeURIComponent(value)}"
return "?#{params.join('&')}"
# Clear the local cache
# -------
@clearCache = clearCache = () -> _cachedETags = {}
## Get the local cache
# -------
@getCache = getCache = () -> _cachedETags
## Set the local cache
# -------
@setCache = setCache = (cachedETags) ->
# check if argument is valid.
unless cachedETags != null and typeof cachedETags == 'object'
throw new Error 'BUG: argument of method "setCache" should be an object'
else
_cachedETags = cachedETags
# Add a listener that fires when the `rateLimitRemaining` changes as a result of
# communicating with github.
@onRateLimitChanged = (listener) ->
_listeners.push listener
# Random zen quote (test the API)
# -------
@getZen = () ->
# Send `data` to `null` and the `raw` flag to `true`
_request 'GET', '/zen', null, {raw:true}
# Get all users
# -------
@getAllUsers = (since=null) ->
options = {}
options.since = since if since
_request 'GET', '/users', options
# List public repositories for an Organization
# -------
@getOrgRepos = (orgName, type='all') ->
_request 'GET', "/orgs/#{orgName}/repos?type=#{type}&per_page=1000&sort=updated&direction=desc", null
# Get public Gists on all of GitHub
# -------
@getPublicGists = (since=null) ->
options = null
# Converts a Date object to a string
getDate = (time) ->
return time.toISOString() if Date == time.constructor
return time
options = {since: getDate(since)} if since
_request 'GET', '/gists/public', options
# List Public Events on all of GitHub
# -------
@getPublicEvents = () ->
_request 'GET', '/events', null
# List unread notifications for authenticated user
# -------
# Optional arguments:
#
# - `all`: `true` to show notifications marked as read.
# - `participating`: `true` to show only notifications in which the user is directly participating or mentioned.
# - `since`: Optional time.
@getNotifications = (options={}) ->
# Converts a Date object to a string
getDate = (time) ->
return time.toISOString() if Date == time.constructor
return time
options.since = getDate(options.since) if options.since
queryString = toQueryString(options)
_request 'GET', "/notifications#{queryString}", null
# Github Users API
# =======
class User
# Store the username
constructor: (_username=null) ->
# Private var that stores the root path.
# Use a different URL if this user is the authenticated user
if _username
_rootPath = "/users/#{_username}"
else
_rootPath = "/user"
# Retrieve user information
# -------
_cachedInfo = null
@getInfo = (force=false) ->
_cachedInfo = null if force
if _cachedInfo
return resolvedPromise(_cachedInfo)
_request('GET', "#{_rootPath}", null)
# Squirrel away the user info
.then (info) -> _cachedInfo = info
# List user repositories
# -------
@getRepos = (type='all', sort='pushed', direction='desc') ->
_request 'GET', "#{_rootPath}/repos?type=#{type}&per_page=1000&sort=#{sort}&direction=#{direction}", null
# List user organizations
# -------
@getOrgs = () ->
_request 'GET', "#{_rootPath}/orgs", null
# List a user's gists
# -------
@getGists = () ->
_request 'GET', "#{_rootPath}/gists", null
# List followers of a user
# -------
@getFollowers = () ->
_request 'GET', "#{_rootPath}/followers", null
# List who this user is following
# -------
@getFollowing = () ->
_request 'GET', "#{_rootPath}/following", null
# Check if this user is following another user
# -------
@isFollowing = (user) ->
_request 'GET', "#{_rootPath}/following/#{user}", null, {isBoolean:true}
# List public keys for a user
# -------
@getPublicKeys = () ->
_request 'GET', "#{_rootPath}/keys", null
# Get Received events for this user
# -------
@getReceivedEvents = (onlyPublic) ->
throw new Error 'BUG: This does not work for authenticated users yet!' if not _username
isPublic = ''
isPublic = '/public' if onlyPublic
_request 'GET', "/users/#{_username}/received_events#{isPublic}", null
# Get all events for this user
# -------
@getEvents = (onlyPublic) ->
throw new Error 'BUG: This does not work for authenticated users yet!' if not _username
isPublic = ''
isPublic = '/public' if onlyPublic
_request 'GET', "/users/#{_username}/events#{isPublic}", null
# Authenticated User API
# =======
class AuthenticatedUser extends User
constructor: () ->
super()
# Update the authenticated user
# -------
#
# Valid options:
# - `name`: String
# - `email` : Publicly visible email address
# - `blog`: String
# - `company`: String
# - `location`: String
# - `hireable`: Boolean
# - `bio`: String
@updateInfo = (options) ->
_request 'PATCH', '/user', options
# List authenticated user's gists
# -------
@getGists = () ->
_request 'GET', '/gists', null
# Follow a user
# -------
@follow = (username) ->
_request 'PUT', "/user/following/#{username}", null
# Unfollow user
# -------
@unfollow = (username) ->
_request 'DELETE', "/user/following/#{username}", null
# Get Emails associated with this user
# -------
@getEmails = () ->
_request 'GET', '/user/emails', null
# Add Emails associated with this user
# -------
@addEmail = (emails) ->
emails = [emails] if !_.isArray(emails)
_request 'POST', '/user/emails', emails
# Remove Emails associated with this user
# -------
@addEmail = (emails) ->
emails = [emails] if !_.isArray(emails)
_request 'DELETE', '/user/emails', emails
# Get a single public key
# -------
@getPublicKey = (id) ->
_request 'GET', "/user/keys/#{id}", null
# Add a public key
# -------
@addPublicKey = (title, key) ->
_request 'POST', "/user/keys", {title: title, key: key}
# Update a public key
# -------
@updatePublicKey = (id, options) ->
_request 'PATCH', "/user/keys/#{id}", options
# Create a repository
# -------
#
# Optional parameters:
# - `description`: String
# - `homepage`: String
# - `private`: boolean (Default `false`)
# - `has_issues`: boolean (Default `true`)
# - `has_wiki`: boolean (Default `true`)
# - `has_downloads`: boolean (Default `true`)
# - `auto_init`: boolean (Default `false`)
@createRepo = (name, options={}) ->
options.name = name
_request 'POST', "/user/repos", options
# Get Received events for this authenticated user
# -------
@getReceivedEvents = (username, page = 1) ->
currentPage = '?page=' + page
_request 'GET', '/users/' + username + '/received_events' + currentPage, null
@getStars = () ->
_request 'GET', "/user/starred"
@putStar = (owner, repo) ->
_request 'PUT', "/user/starred/#{owner}/#{repo}"
@deleteStar = (owner, repo) ->
_request 'DELETE', "/user/starred/#{owner}/#{repo}"
# Organization API
# =======
class Team
constructor: (@id) ->
@getInfo = () ->
_request 'GET', "/teams/#{@id}", null
# - `name`
# - `permission`
@updateTeam = (options) ->
_request 'PATCH', "/teams/#{@id}", options
@remove = () ->
_request 'DELETE', "/teams/#{@id}"
@getMembers = () ->
_request 'GET', "/teams/#{@id}/members"
@isMember = (user) ->
_request 'GET', "/teams/#{@id}/members/#{user}", null, {isBoolean:true}
@addMember = (user) ->
_request 'PUT', "/teams/#{@id}/members/#{user}"
@removeMember = (user) ->
_request 'DELETE', "/teams/#{@id}/members/#{user}"
@getRepos = () ->
_request 'GET', "/teams/#{@id}/repos"
@addRepo = (orgName, repoName) ->
_request 'PUT', "/teams/#{@id}/repos/#{orgName}/#{repoName}"
@removeRepo = (orgName, repoName) ->
_request 'DELETE', "/teams/#{@id}/repos/#{orgName}/#{repoName}"
class Organization
constructor: (@name) ->
@getInfo = () ->
_request 'GET', "/orgs/#{@name}", null
# - `billing_email`: Billing email address. This address is not publicized.
# - `company`
# - `email`
# - `location`
# - `name`
@updateInfo = (options) ->
_request 'PATCH', "/orgs/#{@name}", options
@getTeams = () ->
_request 'GET', "/orgs/#{@name}/teams", null
# `permission` can be one of `pull`, `push`, or `admin`
@createTeam = (name, repoNames=null, permission='pull') ->
options = {name: name, permission: permission}
options.repo_names = repoNames if repoNames
_request 'POST', "/orgs/#{@name}/teams", options
@getMembers = () ->
_request 'GET', "/orgs/#{@name}/members", null
@isMember = (user) ->
_request 'GET', "/orgs/#{@name}/members/#{user}", null, {isBoolean:true}
@removeMember = (user) ->
_request 'DELETE', "/orgs/#{@name}/members/#{user}", null
# Create a repository
# -------
#
# Optional parameters are the same as `.getUser().createRepo()` with one addition:
# - `team_id`: number
@createRepo = (name, options={}) ->
options.name = name
_request 'POST', "/orgs/#{@name}/repos", options
# List repos for an organisation
# -------
@getRepos = () ->
_request 'GET', "/orgs/#{@name}/repos?type=all", null
# Repository API
# =======
# Low-level class for manipulating a Git Repository
# -------
class GitRepo
constructor: (@repoUser, @repoName) ->
_repoPath = "/repos/#{@repoUser}/#{@repoName}"
# Delete this Repository
# -------
# **Note:** This is here instead of on the `Repository` object
# so it is less likely to accidentally be used.
@deleteRepo = () ->
_request 'DELETE', "#{_repoPath}"
# Uses the cache if branch has not been changed
# -------
@_updateTree = (branch) ->
@getRef("heads/#{branch}")
# Get a particular reference
# -------
@getRef = (ref) ->
_request('GET', "#{_repoPath}/git/refs/#{ref}", null)
.then (res) =>
return res.object.sha
# Create a new reference
# --------
#
# {
# "ref": "refs/heads/my-new-branch-name",
# "sha": "827efc6d56897b048c772eb4087f854f46256132"
# }
@createRef = (options) ->
_request 'POST', "#{_repoPath}/git/refs", options
# Delete a reference
# --------
#
# repo.deleteRef('heads/gh-pages')
# repo.deleteRef('tags/v1.0')
@deleteRef = (ref) ->
_request 'DELETE', "#{_repoPath}/git/refs/#{ref}", @options
# List all branches of a repository
# -------
@getBranches = () ->
_request('GET', "#{_repoPath}/git/refs/heads", null)
.then (heads) =>
return _.map(heads, (head) ->
_.last head.ref.split("/")
)
# Retrieve the contents of a blob
# -------
@getBlob = (sha, isBase64) ->
_request 'GET', "#{_repoPath}/git/blobs/#{sha}", null, {raw:true, isBase64:isBase64}
# For a given file path, get the corresponding sha (blob for files, tree for dirs)
# -------
@getSha = (branch, path) ->
# Just use head if path is empty
return @getRef("heads/#{branch}") if path is ''
@getTree(branch, {recursive:true})
.then (tree) =>
file = _.select(tree, (file) ->
file.path is path
)[0]
return file?.sha if file?.sha
# Return a promise that has failed if no sha was found
return rejectedPromise {message: 'SHA_NOT_FOUND'}
# Get contents (file/dir)
# -------
@getContents = (path, sha=null) ->
queryString = ''
if sha != null
queryString = toQueryString({ref:sha})
_request('GET', "#{_repoPath}/contents/#{path}#{queryString}", null, {raw:true})
.then (contents) =>
return contents
# Remove a file from the tree
# -------
@removeFile = (path, message, sha, branch) ->
params =
message: message
sha: sha
branch: branch
_request 'DELETE', "#{_repoPath}/contents/#{path}", params, null
# Retrieve the tree a commit points to
# -------
# Optionally set recursive to true
@getTree = (tree, options=null) ->
queryString = toQueryString(options)
_request('GET', "#{_repoPath}/git/trees/#{tree}#{queryString}", null)
.then (res) =>
return res.tree
# Post a new blob object, getting a blob SHA back
# -------
@postBlob = (content, isBase64) ->
if typeof (content) is 'string'
# Base64 encode the content if it is binary (isBase64)
content = base64encode(content) if isBase64
content =
content: content
encoding: 'utf-8'
content.encoding = 'base64' if isBase64
_request('POST', "#{_repoPath}/git/blobs", content)
.then (res) =>
return res.sha
# Update an existing tree adding a new blob object getting a tree SHA back
# -------
# `newTree` is of the form:
#
# [ {
# path: path
# mode: '100644'
# type: 'blob'
# sha: blob
# } ]
@updateTreeMany = (baseTree, newTree) ->
data =
base_tree: baseTree
tree: newTree
_request('POST', "#{_repoPath}/git/trees", data)
.then (res) =>
return res.sha
# Post a new tree object having a file path pointer replaced
# with a new blob SHA getting a tree SHA back
# -------
@postTree = (tree) ->
_request('POST', "#{_repoPath}/git/trees", {tree: tree})
.then (res) =>
return res.sha
# Create a new commit object with the current commit SHA as the parent
# and the new tree SHA, getting a commit SHA back
# -------
@commit = (parents, tree, message) ->
parents = [parents] if not _.isArray(parents)
data =
message: message
parents: parents
tree: tree
_request('POST', "#{_repoPath}/git/commits", data)
.then((commit) -> return commit.sha)
# Update the reference of your head to point to the new commit SHA
# -------
@updateHead = (head, commit, force=false) ->
options = {sha:commit}
options.force = true if force
_request 'PATCH', "#{_repoPath}/git/refs/heads/#{head}", options
# Get a single commit
# --------------------
@getCommit = (sha) ->
_request('GET', "#{_repoPath}/commits/#{sha}", null)
# List commits on a repository.
# -------
# Takes an object of optional paramaters:
#
# - `sha`: SHA or branch to start listing commits from
# - `path`: Only commits containing this file path will be returned
# - `author`: GitHub login, name, or email by which to filter by commit author
# - `since`: ISO 8601 date - only commits after this date will be returned
# - `until`: ISO 8601 date - only commits before this date will be returned
@getCommits = (options={}) ->
options = _.extend {}, options
# Converts a Date object to a string
getDate = (time) ->
return time.toISOString() if Date == time.constructor
return time
options.since = getDate(options.since) if options.since
options.until = getDate(options.until) if options.until
queryString = toQueryString(options)
_request('GET', "#{_repoPath}/commits#{queryString}", null)
# Branch Class
# -------
# Provides common methods that may require several git operations.
class Branch
constructor: (git, getRef) ->
# Private variables
_git = git
_getRef = getRef or -> throw new Error 'BUG: No way to fetch branch ref!'
# Get a single commit
# --------------------
@getCommit = (sha) -> _git.getCommit(sha)
# List commits on a branch.
# -------
# Takes an object of optional paramaters:
#
# - `path`: Only commits containing this file path will be returned
# - `author`: GitHub login, name, or email by which to filter by commit author
# - `since`: ISO 8601 date - only commits after this date will be returned
# - `until`: ISO 8601 date - only commits before this date will be returned
@getCommits = (options={}) ->
options = _.extend {}, options
# Limit to the current branch
_getRef()
.then (branch) ->
options.sha = branch
_git.getCommits(options)
# Creates a new branch based on the current reference of this branch
# -------
@createBranch = (newBranchName) ->
_getRef()
.then (branch) =>
_git.getSha(branch, '')
.then (sha) =>
_git.createRef({sha:sha, ref:"refs/heads/#{newBranchName}"})
# Read file at given path
# -------
# Set `isBase64=true` to get back a base64 encoded binary file
@read = (path, isBase64) ->
_getRef()
.then (branch) =>
_git.getSha(branch, path)
.then (sha) =>
_git.getBlob(sha, isBase64)
# Return both the commit hash and the content
.then (bytes) =>
return {sha:sha, content:bytes}
# Get contents at given path
# -------
@contents = (path) ->
_getRef()
.then (branch) =>
_git.getSha(branch, '')
.then (sha) =>
_git.getContents(path, sha)
.then (contents) =>
return contents
# Remove a file from the tree
# -------
# Optionally provide the sha of the file so it is not accidentally
# deleted if the repo has changed in the meantime.
@remove = (path, message="Removed #{path}", sha=null) ->
_getRef()
.then (branch) =>
if sha
_git.removeFile(path, message, sha, branch)
else
_git.getSha(branch, path)
.then (sha) =>
_git.removeFile(path, message, sha, branch)
# Move a file to a new location
# -------
@move = (path, newPath, message="Moved #{path}") ->
_getRef()
.then (branch) =>
_git._updateTree(branch)
.then (latestCommit) =>
_git.getTree(latestCommit, {recursive:true})
.then (tree) => # Update Tree
_.each tree, (ref) ->
ref.path = newPath if ref.path is path
delete ref.sha if ref.type is 'tree'
_git.postTree(tree)
.then (rootTree) =>
_git.commit(latestCommit, rootTree, message)
.then (commit) =>
_git.updateHead(branch, commit)
.then (res) =>
return res # Finally, return the result
# Write file contents to a given branch and path
# -------
# To write base64 encoded data set `isBase64==true`
#
# Optionally takes a `parentCommitSha` which will be used as the
# parent of this commit
@write = (path, content, message="Changed #{path}", isBase64, parentCommitSha=null) ->
contents = {}
contents[path] =
content: content
isBase64: isBase64
@writeMany(contents, message, parentCommitSha)
# Write the contents of multiple files to a given branch
# -------
# Each file can also be binary.
#
# In general `contents` is a map where the key is the path and the value is `{content:'Hello World!', isBase64:false}`.
# In the case of non-base64 encoded files the value may be a string instead.
#
# Example:
#
# contents = {
# 'hello.txt': 'Hello World!',
# 'path/to/hello2.txt': { content: 'Ahoy!', isBase64: false}
# }
#
# Optionally takes an array of `parentCommitShas` which will be used as the
# parents of this commit.
@writeMany = (contents, message="Changed Multiple", parentCommitShas=null) ->
# This method:
#
# 0. Finds the latest commit if one is not provided
# 1. Asynchronously send new blobs for each file
# 2. Use the return of the new Blob Post to return an entry in the new Commit Tree
# 3. Wait on all the new blobs to finish
# 4. Commit and update the branch
_getRef()
.then (branch) => # See below for Step 0.
afterParentCommitShas = (parentCommitShas) => # 1. Asynchronously send all the files as new blobs.
promises = _.map _.pairs(contents), ([path, data]) ->
# `data` can be an object or a string.
# If it is a string assume isBase64 is false and the string is the content
content = data.content or data
isBase64 = data.isBase64 or false
_git.postBlob(content, isBase64)
.then (blob) => # 2. return an entry in the new Commit Tree
return {
path: path
mode: '100644'
type: 'blob'
sha: blob
}
# 3. Wait on all the new blobs to finish
# Different Promise APIs implement this differently. For example:
# - Promise uses `Promise.all([...])`
# - jQuery uses `jQuery.when(p1, p2, p3, ...)`
allPromises(promises)
.then (newTrees) =>
_git.updateTreeMany(parentCommitShas, newTrees)
.then (tree) => # 4. Commit and update the branch
_git.commit(parentCommitShas, tree, message)
.then (commitSha) =>
_git.updateHead(branch, commitSha)
.then (res) => # Finally, return the result
return res.object # Return something that has a `.sha` to match the signature for read
# 0. Finds the latest commit if one is not provided
if parentCommitShas
return afterParentCommitShas(parentCommitShas)
else
return _git._updateTree(branch).then(afterParentCommitShas)
# Repository Class
# -------
# Provides methods for operating on the entire repository
# and ways to operate on a `Branch`.
class Repository
constructor: (@options) ->
# Private fields
_user = @options.user
_repo = @options.name
# Set the `git` instance variable
@git = new GitRepo(_user, _repo)
@repoPath = "/repos/#{_user}/#{_repo}"
@currentTree =
branch: null
sha: null
@updateInfo = (options) ->
_request 'PATCH', @repoPath, options
# List all branches of a repository
# -------
@getBranches = () -> @git.getBranches()
# Get a branch of a repository
# -------
@getBranch = (branchName=null) ->
if branchName
getRef = () =>
return resolvedPromise(branchName)
return new Branch(@git, getRef)
else
return @getDefaultBranch()
# Get the default branch of a repository
# -------
@getDefaultBranch = () ->
# Calls getInfo() to get the default branch name
getRef = =>
@getInfo()
.then (info) =>
return info.default_branch
new Branch(@git, getRef)
@setDefaultBranch = (branchName) ->
@updateInfo {name: _repo, default_branch: branchName}
# Get repository information
# -------
@getInfo = () ->
_request 'GET', @repoPath, null
# Get contents
# --------
@getContents = (branch, path) ->
_request 'GET', "#{@repoPath}/contents?ref=#{branch}", {path: path}
# Fork repository
# -------
@fork = (organization) ->
if organization
_request 'POST', "#{@repoPath}/forks",
organization: organization
else
_request 'POST', "#{@repoPath}/forks", null
# Create pull request
# --------
@createPullRequest = (options) ->
_request 'POST', "#{@repoPath}/pulls", options
# Get recent commits to the repository
# --------
# Takes an object of optional paramaters:
#
# - `path`: Only commits containing this file path will be returned
# - `author`: GitHub login, name, or email by which to filter by commit author
# - `since`: ISO 8601 date - only commits after this date will be returned
# - `until`: ISO 8601 date - only commits before this date will be returned
@getCommits = (options) ->
@git.getCommits(options)
# List repository events
# -------
@getEvents = () ->
_request 'GET', "#{@repoPath}/events", null
# List Issue events for a Repository
# -------
@getIssueEvents = () ->
_request 'GET', "#{@repoPath}/issues/events", null
# List events for a network of Repositories
# -------
@getNetworkEvents = () ->
_request 'GET', "/networks/#{_user}/#{_repo}/events", null
# List unread notifications for authenticated user
# -------
# Optional arguments:
#
# - `all`: `true` to show notifications marked as read.
# - `participating`: `true` to show only notifications in which
# the user is directly participating or mentioned.
# - `since`: Optional time.
@getNotifications = (options={}) ->
# Converts a Date object to a string
getDate = (time) ->
return time.toISOString() if Date == time.constructor
return time
options.since = getDate(options.since) if options.since
queryString = toQueryString(options)
_request 'GET', "#{@repoPath}/notifications#{queryString}", null
# List Collaborators
# -------
# When authenticating as an organization owner of an
# organization-owned repository, all organization owners
# are included in the list of collaborators.
# Otherwise, only users with access to the repository are
# returned in the collaborators list.
@getCollaborators = () ->
_request 'GET', "#{@repoPath}/collaborators", null
@addCollaborator = (username) ->
throw new Error 'BUG: username is required' if not username
_request 'PUT', "#{@repoPath}/collaborators/#{username}", null, {isBoolean:true}
@removeCollaborator = (username) ->
throw new Error 'BUG: username is required' if not username
_request 'DELETE', "#{@repoPath}/collaborators/#{username}", null, {isBoolean:true}
@isCollaborator = (username=null) ->
throw new Error 'BUG: username is required' if not username
_request 'GET', "#{@repoPath}/collaborators/#{username}", null, {isBoolean:true}
# Can Collaborate
# -------
# True if the authenticated user has permission
# to commit to this repository.
@canCollaborate = () ->
# Short-circuit if no credentials provided
if not (clientOptions.password or clientOptions.token)
return resolvedPromise(false)
_client.getLogin()
.then (login) =>
if not login
return false
else
return @isCollaborator(login)
.then null, (err) =>
# Problem logging in (maybe bad username/password)
return false
# List all hooks
# -------
@getHooks = () ->
_request 'GET', "#{@repoPath}/hooks", null
# Get single hook
# -------
@getHook = (id) ->
_request 'GET', "#{@repoPath}/hooks/#{id}", null
# Create a new hook
# -------
#
# - `name` (Required string) : The name of the service that is being called.
# (See /hooks for the list of valid hook names.)
# - `config` (Required hash) : A Hash containing key/value pairs to provide settings for this hook.
# These settings vary between the services and are defined in the github-services repo.
# - `events` (Optional array) : Determines what events the hook is triggered for. Default: ["push"].
# - `active` (Optional boolean) : Determines whether the hook is actually triggered on pushes.
@createHook = (name, config, events=['push'], active=true) ->
data =
name: name
config: config
events: events
active: active
_request 'POST', "#{@repoPath}/hooks", data
# Edit a hook
# -------
#
# - `config` (Optional hash) : A Hash containing key/value pairs to provide settings for this hook.
# Modifying this will replace the entire config object.
# These settings vary between the services and are defined in the github-services repo.
# - `events` (Optional array) : Determines what events the hook is triggered for.
# This replaces the entire array of events. Default: ["push"].
# - `addEvents` (Optional array) : Determines a list of events to be added to the list of events that the Hook triggers for.
# - `removeEvents` (Optional array) : Determines a list of events to be removed from the list of events that the Hook triggers for.
# - `active` (Optional boolean) : Determines whether the hook is actually triggered on pushes.
@editHook = (id, config=null, events=null, addEvents=null, removeEvents=null, active=null) ->
data = {}
data.config = config if config != null
data.events = events if events != null
data.add_events = addEvents if addEvents != null
data.remove_events = removeEvents if removeEvents != null
data.active = active if active != null
_request 'PATCH', "#{@repoPath}/hooks/#{id}", data
# Test a `push` hook
# -------
# This will trigger the hook with the latest push to the current
# repository if the hook is subscribed to push events.
# If the hook is not subscribed to push events, the server will
# respond with 204 but no test POST will be generated.
@testHook = (id) ->
_request 'POST', "#{@repoPath}/hooks/#{id}/tests", null
# Delete a hook
# -------
@deleteHook = (id) ->
_request 'DELETE', "#{@repoPath}/hooks/#{id}", null
# List all Languages
# -------
@getLanguages = ->
_request 'GET', "#{@repoPath}/languages", null
# List all releases
# -------
@getReleases = () ->
_request 'GET', "#{@repoPath}/releases", null
# Gist API
# -------
class Gist
constructor: (@options) ->
id = @options.id
_gistPath = "/gists/#{id}"
# Read the gist
# --------
@read = () ->
_request 'GET', _gistPath, null
# Create the gist
# --------
#
# Files contains a hash with the filename as the key and
# `{content: 'File Contents Here'}` as the value.
#
# Example:
#
# { "file1.txt": {
# "content": "String file contents"
# }
# }
@create = (files, isPublic=false, description=null) ->
options =
isPublic: isPublic
files: files
options.description = description if description?
_request 'POST', "/gists", options
# Delete the gist
# --------
@delete = () ->
_request 'DELETE', _gistPath, null
# Fork a gist
# --------
@fork = () ->
_request 'POST', "#{_gistPath}/forks", null
# Update a gist with the new stuff
# --------
# `files` are files that make up this gist.
# The key of which should be an optional string filename
# and the value another optional hash with parameters:
#
# - `content`: Optional string - Updated file contents
# - `filename`: Optional string - New name for this file.
#
# **NOTE:** All files from the previous version of the gist are carried
# over by default if not included in the hash. Deletes can be performed
# by including the filename with a null hash.
@update = (files, description=null) ->
options = {files: files}
options.description = description if description?
_request 'PATCH', _gistPath, options
# Star a gist
# -------
@star = () ->
_request 'PUT', "#{_gistPath}/star"
# Unstar a gist
# -------
@unstar = () ->
_request 'DELETE', "#{_gistPath}/star"
# Check if a gist is starred
# -------
@isStarred = () ->
_request 'GET', "#{_gistPath}", null, {isBoolean:true}
# Top Level API
# -------
@getRepo = (user, repo) ->
throw new Error('BUG! user argument is required') if not user
throw new Error('BUG! repo argument is required') if not repo
new Repository(
user: user
name: repo
)
@getOrg = (name) ->
new Organization(name)
# API for viewing info for arbitrary users or the current user
# if no arguments are provided.
@getUser = (login=null) ->
if login
return new User(login)
else if clientOptions.password or clientOptions.token
return new AuthenticatedUser()
else
return null
@getGist = (id) ->
new Gist(id: id)
# Returns the login of the current user.
# When using OAuth this is unknown but is necessary to
# determine if the current user has commit access to a
# repository
@getLogin = () ->
# 3 cases:
# 1. No authentication provided
# 2. Username (and password) provided
# 3. OAuth token provided
if clientOptions.password or clientOptions.token
return new User().getInfo()
.then (info) ->
return info.login
else
return resolvedPromise(null)
# Return the class for assignment
return Octokit
# Register with nodejs, requirejs, or as a global
# -------
# Depending on the context this file is called, register it appropriately
if exports?
# Use native promises if Harmony is on
Promise = @Promise or require('es6-promise').Promise
XMLHttpRequest = @XMLHttpRequest or require('xmlhttprequest').XMLHttpRequest
newPromise = (fn) -> return new Promise(fn)
allPromises = (promises) -> return Promise.all.call(Promise, promises)
# Encode using native Base64
encode = @btoa or (str) ->
buffer = new Buffer(str, 'binary')
return buffer.toString('base64')
Octokit = makeOctokit(newPromise, allPromises, XMLHttpRequest, encode, 'octokit') # `User-Agent` (for nodejs)
exports.new = (options) -> new Octokit(options)
else
# Octokit is being used in the browser.
# Find a Promise API and register with `define` (if available)
# Register Octokit once a Promise API is loaded.
# In the case of angular, this may be async.
createGlobalAndAMD = (newPromise, allPromises) =>
if @define?
@define 'octokit', [], () =>
return makeOctokit(newPromise, allPromises, @XMLHttpRequest, @btoa)
else
Octokit = makeOctokit(newPromise, allPromises, @XMLHttpRequest, @btoa)
# Assign to a global `Octokit`
@Octokit = Octokit
@Github = Octokit
# Determine the correct Promise factory.
# Try to use libraries before native Promises since most Promise users
# are already using a library.
#
# Try in the following order:
# - Q Promise
# - angularjs Promise
# - jQuery Promise
# - native Promise or a polyfill
if @Q
newPromise = (fn) =>
deferred = @Q.defer()
resolve = (val) -> deferred.resolve(val)
reject = (err) -> deferred.reject(err)
fn(resolve, reject)
return deferred.promise
allPromises = (promises) -> @Q.all(promises)
createGlobalAndAMD(newPromise, allPromises)
else if @angular
# Details on Angular Promises: http://docs.angularjs.org/api/ng/service/$q
injector = angular.injector(['ng'])
injector.invoke ($q) ->
newPromise = (fn) ->
deferred = $q.defer()
resolve = (val) -> deferred.resolve(val)
reject = (err) -> deferred.reject(err)
fn(resolve, reject)
return deferred.promise
allPromises = (promises) -> $q.all(promises)
createGlobalAndAMD(newPromise, allPromises)
else if @jQuery?.Deferred
newPromise = (fn) =>
promise = @jQuery.Deferred()
resolve = (val) -> promise.resolve(val)
reject = (val) -> promise.reject(val)
fn(resolve, reject)
return promise.promise()
allPromises = (promises) =>
# `jQuery.when` is a little odd.
# - It accepts each promise as an argument (instead of an array of promises)
# - Each resolved value is an argument (instead of an array of values)
#
# So, convert the array of promises to args and then the resolved args to an array
return @jQuery.when(promises...).then((promises...) -> return promises)
createGlobalAndAMD(newPromise, allPromises)
else if @Promise
newPromise = (fn) => return new @Promise (resolve, reject) ->
# Some browsers (like node-webkit 0.8.6) contain an older implementation
# of Promises that provide 1 argument (a `PromiseResolver`).
if resolve.fulfill
fn(resolve.resolve.bind(resolve), resolve.reject.bind(resolve))
else
fn(arguments...)
allPromises = (promises) => @Promise.all.call(@Promise, promises)
createGlobalAndAMD(newPromise, allPromises)
else
# Otherwise, throw an error
err = (msg) ->
console?.error?(msg)
throw new Error(msg)
err('A Promise API was not found. Supported libraries that have Promises are jQuery, angularjs, and https://github.com/jakearchibald/es6-promise')