Merge pull request #7 from AR-js-org/feature/6-github-provider

Feature/6 GitHub provider

.gitignore

@@ -6,105 +6,11 @@ yarn-debug.log*
 yarn-error.log*
 lerna-debug.log*
 
-# Diagnostic reports (https://nodejs.org/api/report.html)
-report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
-
-# Runtime data
-pids
-*.pid
-*.seed
-*.pid.lock
-
-# Directory for instrumented libs generated by jscoverage/JSCover
-lib-cov
-
-# Coverage directory used by tools like istanbul
-coverage
-*.lcov
-
-# nyc test coverage
-.nyc_output
-
-# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
-.grunt
-
-# Bower dependency directory (https://bower.io/)
-bower_components
-
-# node-waf configuration
-.lock-wscript
-
-# Compiled binary addons (https://nodejs.org/api/addons.html)
-build/Release
-
 # Dependency directories
-node_modules/
-jspm_packages/
-
-# TypeScript v1 declaration files
-typings/
-
-# TypeScript cache
-*.tsbuildinfo
-
-# Optional npm cache directory
-.npm
-
-# Optional eslint cache
-.eslintcache
-
-# Microbundle cache
-.rpt2_cache/
-.rts2_cache_cjs/
-.rts2_cache_es/
-.rts2_cache_umd/
-
-# Optional REPL history
-.node_repl_history
-
-# Output of 'npm pack'
-*.tgz
-
-# Yarn Integrity file
-.yarn-integrity
-
-# dotenv environment variables file
-.env
-.env.test
-
-# parcel-bundler cache (https://parceljs.org/)
-.cache
-
-# Next.js build output
-.next
-
-# Nuxt.js build / generate output
-.nuxt
-dist
-
-# Gatsby files
-.cache/
-# Comment in the public line in if your project uses Gatsby and *not* Next.js
-# https://nextjs.org/blog/next-9-1#public-directory-support
-# public
-
-# vuepress build output
-.vuepress/dist
-
-# Serverless directories
-.serverless/
-
-# FuseBox cache
-.fusebox/
-
-# DynamoDB Local files
-.dynamodb/
-
-# TernJS port file
-.tern-port
+/node_modules
 
 # VS Code settings
 .vscode
 
-# PhpStorm settings
+# IntelliJ settings
 .idea

README.md

@@ -35,3 +35,90 @@ more to add
 For maintaining a consistent code style while developing, please use Visual Studio Code.
 
 To run the internal test suite, execute `npm run test`.
+
+## Usage
+
+For browser usage, download the library from the `dist` directory and import in your page:
+
+```html
+<script src="js/arjs-studio-backend.min.js"></script>
+```
+
+## Providers
+
+Providers are used to gather together the project assets and serve them in different formats.
+A base `Provider` class can be found in `src/providers/Provider.js`, you can extend directly from it or use
+others this library provides.
+
+### Base
+
+**new Provider(config)**
+
+The constructor accepts a configuration object.
+
+**addFile(path, content, encoding)**
+
+To add a file you need to provide its path in the file hierarchy, content and encoding.
+Accepted encodings are `utf-8` for textual files and `base64` for text representing images.
+
+**clearFiles()**
+
+Helper method to clear stored files.
+
+**serveFiles(config)**
+
+This method processes the files and serves them depending on the Provider implementation.
+
+### GitHub Pages
+
+**new Provider(config)**
+
+Accepts the following configuration:
+
+```js
+new GithubProvider({
+    token: 'authorization token', // required, can be a PAT or OAuth token
+    owner: 'username', // automatically retrieved by default
+    repo: 'name of the repository', // defaults to 'arjs-studio-NUMBERS'
+    branch: 'gh-pages' // automatically deploy to Pages by default
+})
+```
+
+**serveFiles(config)**
+
+Commits files to the user's repository and returns a `Promise<string>` with the URL of the deployed Pages.
+
+```js
+provider.serveFiles({
+    message: 'custom commit message',
+    owner: 'custom owner',
+    repo: 'custom repo',
+    branch: 'custom branch'
+})
+```
+
+**Example**
+
+First, create a Personal Access Token from [GitHub Developer Settings](https://github.com/settings/tokens)
+with scope `repo:publis_repo`.
+
+Then use it to serve the project:
+
+```js
+const { GithubProvider, ENC_BASE64 } = ARjsStudioBackend;
+
+const github = new GithubProvider({
+   token: 'YOUR-TOKEN'
+});
+github.addFile('index.html', 'Hello World!');
+github.addFile('img/example.jpg', 'base64 encoded image ...', ENC_BASE64);
+const pagesUrl = await github.serveFiles({
+   message: 'my awesome AR experience'
+});
+const branchName = github.branch; // store this
+```
+
+The provider will use the PAT to create repo, branch, set up Pages, commit all the files and trigger
+a Pages build.
+
+**TODO**: storage service for saving token, repo and branch name