{"id":21008029,"url":"https://github.com/caged/octo","last_synced_at":"2025-05-15T02:31:41.356Z","repository":{"id":2961254,"uuid":"3975795","full_name":"caged/octo","owner":"caged","description":"octo.js - A small JavaScript library for GitHub's API that works in nodejs and the browser.","archived":false,"fork":false,"pushed_at":"2015-11-26T22:10:42.000Z","size":220,"stargazers_count":20,"open_issues_count":3,"forks_count":9,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-19T17:10:57.600Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://labratrevenge.com/octo","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caged.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-04-09T20:43:44.000Z","updated_at":"2019-08-13T15:00:32.000Z","dependencies_parsed_at":"2022-08-06T13:00:39.024Z","dependency_job_id":null,"html_url":"https://github.com/caged/octo","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caged%2Focto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caged%2Focto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caged%2Focto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caged%2Focto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caged","download_url":"https://codeload.github.com/caged/octo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254262267,"owners_count":22041375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T09:11:13.591Z","updated_at":"2025-05-15T02:31:41.051Z","avatar_url":"https://github.com/caged.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Octo.js\n\nOcto.js is a simple, flexible, functional JavaScript library for interacting with [GitHub's v3 API](http://developer.github.com/v3).  It runs in node.js apps and the browser.  It supports Basic Auth, OAuth 2, pagination and more.\n\n**Requires [superagent](https://github.com/visionmedia/superagent)** \u0026mdash; A lightweight library for supporting Ajax in the browser and HTTP in node.js.\n\nAll examples are written in [CoffeeScript](http://coffeescript.org), but Octo.js itself is written in JavaScript.\n\n## Quick Example\n\n```coffeescript\napi = octo.api()\ndo api.get('/events').on 'success', (res) -\u003e\n  pubevents = res.body\n```\n\n`api.get` sets up a closure, so you'll need to invoke it before the request is sent.\n\n```coffeescript\nevents = api.get('/events').perpage(50)\n  .on 'end', (res) -\u003e\n    console.log api.limit()\n    console.log events.page() #1\n\ndo events\n```\n\n## Using in the browser\n\nDownload both [superagent](https://github.com/visionmedia/superagent) and octo.js and include them in the `\u003chead\u003e` of your document.\n\n```html\n  \u003cscript src=\"superagent.js\"\u003e\u003c/script\u003e\n  \u003cscript src=\"octo.js\"\u003e\u003c/script\u003e\n```\n\n## Using in node.js\nInstall using `npm`.\n\n```shell\nnpm install octo\n```\nRequire octo in your node.js script\n\n```coffeescript\nocto = require 'octo'\n```\n\n## Paging\nOne goal of octo.js was to make paging very simple.  Paging is built right into the library.\n\n```coffeescript\nevents = api.get('/events').on 'success', (res) -\u003e\n  # the current page\n  events.page()\n\n  # requests the next page\n  events.next()\n\n  # requests the previous page\n  events.prev()\n\ndo events\n```\n\nWhat if you want to start on a different page and limit the number of results per page?\n\n```coffeescript\n# Start on page 5 only returning 10 results per page\ndo api.get('/events').page(5).perpage(10)\n```\n\n## Events\nOcto.js supports three events: `\"success\"`, `\"error\"` and `\"end\"`.  These callbacks are registered per pager.  This makes it easy to use the same callbacks for each page you request.\n\n* *`success`* - Response status was in the 200 range\n* *`error`* - Response wasn't in the 200 range\n* *`end`* - Fired at the end of every request, regarldess of status.\n\n```coffeescript\ndo api.get('/events')\n  .on('success', (res) -\u003e console.log(res.body))\n  .on('error', (res) -\u003e console.log(res.body))\n  .on('end', (res) -\u003e console.log(res.body))\n```\n\n## Basic Auth\n``` coffeescript\napi = octo.api().username('foo').password('bar')\ndo api.get('/user').on 'success', (res) -\u003e console.log res.body\n```\n\n## OAuth2\nIf you've [registered your script or app](https://github.com/settings/applications/new) as an OAuth app, you can use your token to authenticate with the api.\n\n```coffeescript\napi = octo.api().token('MY APP TOKEN')\ndo api.get('/user').on 'success', (res) -\u003e console.log res.body\n```\n\nThis will work with any registered OAuth application, but will return *unauthorized* if you've not registered your application with GitHub.\n\n### Getting an OAuth 2 token from the API\nGitHub APIv3 allows you to programmatically fetch a token for use in scripts that might not be websites.  Grabbing an OAuth token **requires a username and password**.  Once you have a token, you can use it without a need for your username and password.\n\n```coffeescript\napi = octo.api().username('foo').password('bar')\ndo api.post('/authorizations', {note: 'my script', scopes: ['public_repo']})\n   .on 'success', (res) -\u003e console.log res.body\n```\n\n## Checking Rate limits\nThe GitHub API has a rate limit that's returned with the headers of every request.  You can easily access this info to see your limit and how many requests you have left\n\n```coffeescript\ndo api.get('/users/caged/repos').on 'success', -\u003e\n  # Your limit per hour\n  console.log api.limit()\n\n  # Amount you have remaining in that hour\n  console.log api.remaining()\n```\n\n### More examples\n\nThere are some interactive examples in ./examples.  You can fire up the server to play with these:\n\n```shell\nnode examples.js\nExamples available at http://localhost:9292\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaged%2Focto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaged%2Focto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaged%2Focto/lists"}