wip: add docs

.gitignore

@@ -0,0 +1,18 @@
+# node.js
+node_modules/
+build/
+npm-debug.log
+yarn-error.log
+
+# BUCK
+buck-out/
+\.buckd/
+*.keystore
+
+# build outputs
+*/build
+
+#vscode
+.vscode/
+
+docs_dev_server/app/docs/

CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+## Folder structure
+
+1. The documentation for each recipe and sdk lives in it's own folder e.g `auth-react` for auth-react sdk.
+2. Each of these folders is a [docusaurus v1](https://v1.docusaurus.io/l) project containing two important folders: 
+    1. `docs` - contains markdown files where we write the content of our documentation
+    2. `website` - contains following important files and folders:
+        1. `build` - this is where final docs build is stored
+        2. `static` - static assets for the docs
+        3. `versioned_docs` - contains `.md` files which contain versioned info (more on this in **versioning** section)
+        4. `versioned_sidebars` - configuration file for sidebar in resulting docs build which link to a particular docs version
+        5. `createVersion`, `initVersions` - shell scripts for creating versioned docs
+        6. `sidebars.json` - here we define the contents of sidebar menu
+        7. `siteConfig.js` - config for the docusaurus build
+        8. `versions.json` - contains an array of versions being used in that particular docs folder 
+3. You can ignore the docker files
+
+## Modification and seeing your changes
+
+1. Install the npm deps in the folder you are going to work e.g for **auth-react**: `cd auth-react/website && npm i -d`
+2. run `./buildDocs FOLDER_NAME` from the root of docs repo.
+3. Run the local server which resides in `docs_dev_server`: `cd docs_dev_server/app` followed by `npm run build-dev`. This will start the server on `http://localhost:9001/`
+4. Every time you make changes to a particular docs folder you have to run `./buildDocs FOLDER_NAME` from the root of docs repo and reload the browser page to see your changes.
+5. To build the docs for all folders, first install npm deps for each and then run `./buildAllDocs` from the root of the repo
+
+## Versioning
+TODO
+
+## Code snippets
+
+- For other cosmetics modification, bugs etc please create an issue on github

android/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:8.11.4
+
+WORKDIR /app/website
+
+EXPOSE 3000 35729
+COPY ./docs /app/docs
+COPY ./website /app/website
+RUN yarn install
+
+CMD ["yarn", "start"]

android/docker-compose.yml

@@ -0,0 +1,18 @@
+version: "3"
+
+services:
+  docusaurus:
+    build: .
+    ports:
+      - 3000:3000
+      - 35729:35729
+    volumes:
+      - ./docs:/app/docs
+      - ./website/blog:/app/website/blog
+      - ./website/core:/app/website/core
+      - ./website/i18n:/app/website/i18n
+      - ./website/pages:/app/website/pages
+      - ./website/static:/app/website/static
+      - ./website/sidebars.json:/app/website/sidebars.json
+      - ./website/siteConfig.js:/app/website/siteConfig.js
+    working_dir: /app/website

android/docs/api-reference/httpurlconnection.md

@@ -0,0 +1,61 @@
+---
+id: httpurlconnection
+title: HttpURLConnection
+hide_title: true
+---
+
+# API Reference for HttpURLConnection
+
+<div class="divider"></div>
+
+## ```SuperTokens.init(Application applicationContext, String refreshTokenEndpoint, Integer sessionExpiryStatusCode, Map<String, String> refreshAPICustomHeaders)```
+#### Parameters
+- ```applicationContext```
+    - The application context for your app.
+- ```refreshTokenEndpoint```
+    - Should be the full request URL for your refresh session API endpoint.
+- ```sessionExpiryStatusCode``` (Nullable)
+    - Default: ```401```
+    - HTTP status code that indicates session expiry - as sent by your APIs.
+- ```refreshAPICustomHeaders``` (Nullable)
+    - Default: Empty ```Map```
+    - If your refresh API requires any custom headers (for example a version number), then you can provide that in this ```Map```.
+
+#### Returns
+- ```void```
+
+#### Throws
+- ```MalformedURLException``` if the refreshTokenEndpoint does not start with ```http``` or ```https```, or if it has an invalid format.
+
+<div class="divider"></div>
+
+## ```SuperTokensHttpURLConnection.newRequest(URL url, PreConnectCallback preConnectCallback)```
+#### Parameters
+- ```url```
+    - ```URL``` object used to create the ```HttpURLConnection```
+- ```preConnectCallback``` (Nullable)
+    - Callback that takes as a parameter the ```HttpURLConnection connection``` object. It will be called just before making a request, so it is a suitable place to add custom headers.
+
+#### Returns
+- ```HttpURLConnection``` object after a connection has been made.
+- You can use the return value to check the status code, and to read the output if relevant.
+- Please be sure to close the connection as you normally would.
+
+#### Throws
+- ```IllegalAccessException``` if ```SuperTokens.init``` has not been called or if the ```Application``` object provided to the init function is ```null```.
+- ```IOException``` if any of the operations on the connection fail.
+
+<div class="divider"></div>
+
+## ```SuperTokens.doesSessionExist(Application applicationContext)```
+
+#### Parameters
+- ```applicationContext```
+    - The application context for your app.
+
+#### Returns
+- ```boolean```
+- ```true``` if there is an existing session, else ```false```
+
+#### Throws
+- Nothing

android/docs/api-reference/okhttp.md

@@ -0,0 +1,43 @@
+---
+id: okhttp
+title: OkHttp
+hide_title: true
+---
+
+# API Reference for OkHttp
+
+<div class="divider"></div>
+
+## ```SuperTokens.init(Application applicationContext, String refreshTokenEndpoint, Integer sessionExpiryStatusCode, Map<String, String> refreshAPICustomHeaders)```
+#### Parameters
+- ```applicationContext```
+    - The application context for your app.
+- ```refreshTokenEndpoint```
+    - Should be the full request URL for your refresh session API endpoint.
+- ```sessionExpiryStatusCode``` (Nullable)
+    - Default: ```401```
+    - HTTP status code that indicates session expiry - as sent by your APIs.
+- ```refreshAPICustomHeaders``` (Nullable)
+    - Default: Empty ```Map```
+    - If your refresh API requires any custom headers (for example a version number), then you can provide that in this ```Map```.
+
+#### Returns
+- ```void```
+
+#### Throws
+- ```MalformedURLException``` if the refreshTokenEndpoint does not start with ```http``` or ```https```, or if it has an invalid format.
+
+<div class="divider"></div>
+
+## ```SuperTokens.doesSessionExist(Application applicationContext)```
+
+#### Parameters
+- ```applicationContext```
+    - The application context for your app.
+
+#### Returns
+- ```boolean```
+- ```true``` if there is an existing session, else ```false```
+
+#### Throws
+- Nothing

android/docs/httpurlconnection/checking-for-active-session.md

@@ -0,0 +1,25 @@
+---
+id: checking-for-active-session
+title: Checking if a session exists
+hide_title: true
+---
+
+# Checking if a session exists
+
+### The ```doesSessionExist``` function: [API Reference](../api-reference/httpurlconnection#supertokensdoessessionexistapplication-applicationcontext)
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Java-->
+```java
+SuperTokens.sessionPossiblyExists(getApplicationContext());
+```
+<!--Kotlin-->
+```java
+SuperTokens.sessionPossiblyExists(application);
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+- Returns a ```boolean```
+- If ```true```: There is an active session.
+- If ```false```: There is no active session.
+

android/docs/httpurlconnection/init.md

@@ -0,0 +1,44 @@
+---
+id: init
+title: Initialisation
+hide_title: true
+---
+
+# Initialisation
+
+### The ```SuperTokens.init``` function: [API Reference](../api-reference/httpurlconnection#supertokensinitapplication-applicationcontext-string-refreshtokenendpoint-integer-sessionexpirystatuscode-map-string-string-refreshapicustomheaders)
+- To be called at least once before any http request is made to any of your APIs that require authentication.
+- You only need to call this once in your app.
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Java-->
+```java
+import io.supertokens.session.SuperTokens
+
+try {
+    SuperTokens.init(getApplication(), "https://api.example.com/session/refresh", 401, null);
+} catch (MalformedURLException e) {
+    // Refresh URL was invalid
+}
+```
+<!--Kotlin-->
+```java
+import io.supertokens.session.SuperTokens
+
+try {
+    SuperTokens.init(application, "https://api.example.com/session/refresh", 401, null);
+} catch (MalformedURLException e) {
+    // Refresh URL was invalid
+}
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+- To understand the various parameters, please visit the API reference link above.
+
+
+## Persisting cookies
+SuperTokens does not persist cookies across app launches by default, and relies on you to set a persistent cookie manager for your app. SuperTokens provides a ```SuperTokensPersistentCookieStore``` class which can be used to persist cookies. To enable this cookie store simply use the following code before making any HTTP API calls that require authentication:
+
+```java
+CookieManager.setDefault(new CookieManager(new SuperTokensPersistentCookieStore(getApplication()), null));
+```

android/docs/httpurlconnection/sending-requests.md

@@ -0,0 +1,54 @@
+---
+id: sending-requests
+title: Sending Requests
+hide_title: true
+---
+
+# Sending Requests
+
+## The ```SuperTokensHttpURLConnection.newRequest``` function: [API Reference](../api-reference/httpurlconnection#supertokenshttpurlconnectionnewrequesturl-url-preconnectcallback-preconnectcallback)
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Java-->
+```java
+URL url = new URL("https://api.example.com/api/getUerInfo");
+HttpURLConnection connection;
+try {
+    connection = SuperTokensHttpURLConnection.newRequest(url, new SuperTokensHttpURLConnection.PreConnectCallback() {
+        @Override
+        public void doAction(HttpURLConnection con) throws IOException {
+            con.setRequestMethod("POST");
+            // set some custom headers..
+        }
+    });
+    if ( connection.getResponseCode() == 200 ) {
+        // handle response..
+    }
+} catch (IOException e) {
+    // Something went wrong making the API call
+} finally {
+    connection.disconnect();
+}
+```
+<!--Kotlin-->
+```java
+val url = new URL("https://api.example.com/api/getUerInfo");
+val connection;
+try {
+    connection = SuperTokensHttpURLConnection.newRequest(url, SuperTokensHttpURLConnection.PreConnectCallback {
+        it.setRequestMethod("POST");
+    })
+    if ( connection.responseCode == 200 ) {
+        // handle response..
+    }
+} catch (IOException e) {
+    // Something went wrong making the API call
+} finally {
+    connection.disconnect();
+}
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+- If the status code of the returned ```connection``` object is session expired, then you should ask the user to login again.
+- The callback may be called multiple times if the access token has expired.
+

android/docs/installation.md

@@ -0,0 +1,25 @@
+---
+id: installation
+title: Installation
+hide_title: true
+---
+
+# Android SDK Installation
+
+## Add the Android package dependency
+```
+implementation 'io.supertokens:session:1.2.+'
+```
+Add this to your app level ```build.gradle```.
+
+<div class="specialNote" style="margin-bottom: 40px">
+This package uses AndroidX artifacts and will break your build if your app does not use them.
+</div>
+
+## Additional packages
+For SuperTokens to work correctly you need to use cookies in your application:
+- When using ```HttpURLConnection``` the library provides a persistent cookie store that you can use. 
+- If you use ```OkHttp``` or ```Retrofit``` the library relies on you to set a cookie jar when creating an instance of the ```OkHttpClient```. An example of a library that provides persistent cookie jar is:
+    ```
+    implementation 'com.github.franmontiel:PersistentCookieJar:+'
+    ```

android/docs/okhttp/checking-for-active-session.md

@@ -0,0 +1,25 @@
+---
+id: checking-for-active-session
+title: Checking if a session exists
+hide_title: true
+---
+
+# Checking if a session exists
+
+### The ```doesSessionExist``` function: [API Reference](../api-reference/okhttp#supertokensdoessessionexistapplication-applicationcontext)
+
+<!--DOCUSAURUS_CODE_TABS-->
+<!--Java-->
+```java
+SuperTokens.sessionPossiblyExists(getApplicationContext());
+```
+<!--Kotlin-->
+```java
+SuperTokens.sessionPossiblyExists(application);
+```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
+- Returns a ```boolean```
+- If ```true```: There is an active session.
+- If ```false```: There is no active session.
+