Merge branch 'release/v0.1.0'

Author: petrbroz

.jsdoc.json

@@ -20,6 +20,7 @@
         "encoding": "utf8",
         "private": true,
         "recurse": true,
-        "template": "./node_modules/jsdoc-template"
+        "template": "./node_modules/jsdoc-template",
+        "tutorials": "docs/tutorials"
     }
 }

.travis.yml

@@ -8,10 +8,3 @@ deploy:
   api_key: $NPM_AUTH_TOKEN
   on:
     tags: true
-
-notifications:
-  email:
-    recipients:
-    - ipetrbroz@gmail.com
-    on_success: change
-    on_failure: always

README.md

@@ -10,26 +10,24 @@ or [generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Referenc
 ### Authentication
 
 ```js
+const { AuthenticationClient } = require('autodesk-forge-tools');
 const auth = new AuthenticationClient(); // If no params, gets credentials from env. vars FORGE_CLIENT_ID and FORGE_CLIENT_SECRET
-const token = await auth.authenticate(['bucket:read', 'data:read']);
-console.log('2-legged Token', token);
+const authentication = await auth.authenticate(['bucket:read', 'data:read']);
+console.log('2-legged Token', authentication.access_token);
 ```
 
 ### Data Management
 
 ```js
+const { DataManagementClient, AuthenticationClient } = require('autodesk-forge-tools');
 const data = new DataManagementClient(new AuthenticationClient());
 // List buckets
 for await (const buckets of await data.buckets()) {
-    for (const bucket of buckets) {
-        console.log('Bucket', bucket.bucketKey);
-    }
+    console.log('Buckets', buckets.map(bucket => bucket.bucketKey).join(','));
 }
 // List objects in bucket
 for await (const objects of data.objects("foo-bucket")) {
-    for (const object of objects) {
-        console.log('Object', object.objectId);
-    }
+    console.log('Objects', objects.map(object => object.objectId).join(','));
 }
 ```
 

docs/tutorials/auth-basic.md

@@ -0,0 +1,8 @@
+# Basic usage of authentication APIs
+
+```js
+const { AuthenticationClient } = require('autodesk-forge-tools');
+const auth = new AuthenticationClient(); // If no params, gets credentials from env. vars FORGE_CLIENT_ID and FORGE_CLIENT_SECRET
+const authentication = await auth.authenticate(['bucket:read', 'data:read']);
+console.log('2-legged Token', authentication.access_token);
+```

docs/tutorials/data-basic.md

@@ -0,0 +1,14 @@
+# Basic usage of data APIs
+
+```js
+const { DataManagementClient, AuthenticationClient } = require('autodesk-forge-tools');
+const data = new DataManagementClient(new AuthenticationClient());
+// List buckets
+for await (const buckets of await data.buckets()) {
+    console.log('Buckets', buckets.map(bucket => bucket.bucketKey).join(','));
+}
+// List objects in bucket
+for await (const objects of data.objects("foo-bucket")) {
+    console.log('Objects', objects.map(object => object.objectId).join(','));
+}
+```

docs/tutorials/index.json

@@ -0,0 +1,8 @@
+{
+    "auth-basic": {
+        "title": "Basic Authentication"
+    },
+    "data-basic": {
+        "title": "Basic Data Management"
+    }
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "autodesk-forge-tools",
-  "version": "0.0.6",
+  "version": "0.1.0",
   "description": "Tools for accessing Autodesk Forge APIs from Node.js apps.",
   "main": "src/index.js",
   "scripts": {

src/auth.js

@@ -4,6 +4,7 @@ const RootPath = '/authentication/v1';
 
 /**
  * Client providing access to Autodesk Forge {@link https://forge.autodesk.com/en/docs/oauth/v2|authentication APIs}.
+ * @tutorial auth-basic
  */
 class AuthenticationClient {
     /**
@@ -26,15 +27,19 @@ class AuthenticationClient {
      * based on their scopes and the 'expires_in' field in the response.
      * @param {string[]} scopes List of requested {@link https://forge.autodesk.com/en/docs/oauth/v2/developers_guide/scopes|scopes}.
      * @param {boolean} [force] Skip cache, if there is any, and retrieve a new token.
-     * @returns {Promise<string>} 2-legged auth access token.
+     * @returns {Promise<object>} Promise of 2-legged authentication object containing two fields,
+     * 'access_token' with the actual token, and 'expires_in' with expiration time (in seconds).
      */
     authenticate(scopes, force = false) {
         // Check if there's a cached token, unexpired, and with the same scopes
         const key = 'two-legged/' + scopes.join('/');
         if (!force && key in this._cached) {
             const cache = this._cached[key];
             if (cache.expires_at > Date.now()) {
-                return cache.promise;
+                return cache.promise.then((token) => ({
+                    access_token: token,
+                    expires_in: Math.floor((cache.expires_at - Date.now()) / 1000)
+                }));
             }
         }
 
@@ -45,14 +50,17 @@ class AuthenticationClient {
             'grant_type': 'client_credentials',
             'scope': scopes.join(' ')
         };
-        this._cached[key] = {
+        const cache = this._cached[key] = {
             expires_at: Number.MAX_VALUE,
             promise: post(`${RootPath}/authenticate`, { urlencoded: params }).then((resp) => {
                 this._cached[key].expires_at = Date.now() + resp.expires_in * 1000;
                 return resp.access_token;
             })
         };
-        return this._cached[key].promise;
+        return cache.promise.then((token) => ({
+            access_token: token,
+            expires_in: Math.floor((cache.expires_at - Date.now()) / 1000)
+        }));
     }
 }
 

src/data.js

@@ -32,15 +32,15 @@ class DataManagementClient {
      * @throws Error when the request fails, for example, due to insufficient rights, or incorrect scopes.
      */
     async *buckets(page = 16) {
-        let access_token = await this.auth.authenticate(ReadTokenScopes);
-        let response = await get(`${RootPath}/buckets?limit=${page}`, { 'Authorization': 'Bearer ' + access_token });
+        let authentication = await this.auth.authenticate(ReadTokenScopes);
+        let response = await get(`${RootPath}/buckets?limit=${page}`, { 'Authorization': 'Bearer ' + authentication.access_token });
         yield response.items;
 
         while (response.next) {
             const next = new URL(response.next);
             const startAt = querystring.escape(next.searchParams.get('startAt'));
-            access_token = await this.auth.authenticate(ReadTokenScopes);
-            response = await get(`${RootPath}/buckets?startAt=${startAt}&limit=${page}`, { 'Authorization': 'Bearer ' + access_token });
+            authentication = await this.auth.authenticate(ReadTokenScopes);
+            response = await get(`${RootPath}/buckets?startAt=${startAt}&limit=${page}`, { 'Authorization': 'Bearer ' + authentication.access_token });
             yield response.items;
         }
     }
@@ -56,8 +56,8 @@ class DataManagementClient {
      * with this name does not exist.
      */
     async bucketDetails(bucket) {
-        const access_token = await this.auth.authenticate(ReadTokenScopes);
-        const response = await get(`${RootPath}/buckets/${bucket}/details`, { 'Authorization': 'Bearer ' + access_token });
+        const authentication = await this.auth.authenticate(ReadTokenScopes);
+        const response = await get(`${RootPath}/buckets/${bucket}/details`, { 'Authorization': 'Bearer ' + authentication.access_token });
         return response;
     }
 
@@ -73,12 +73,12 @@ class DataManagementClient {
      * or when a bucket with this name already exists.
      */
     async createBucket(bucket, dataRetention) {
-        const access_token = await this.auth.authenticate(WriteTokenScopes);
+        const authentication = await this.auth.authenticate(WriteTokenScopes);
         const params = {
             bucketKey: bucket,
             policyKey: dataRetention
         };
-        const response = await post(`${RootPath}/buckets`, { json: params }, { 'Authorization': 'Bearer ' + access_token });
+        const response = await post(`${RootPath}/buckets`, { json: params }, { 'Authorization': 'Bearer ' + authentication.access_token });
         return response;
     }
 
@@ -95,14 +95,15 @@ class DataManagementClient {
      * @throws Error when the request fails, for example, due to insufficient rights, or incorrect scopes.
      */
     async *objects(bucket, page = 16) {
-        const access_token = await this.auth.authenticate(ReadTokenScopes);
-        let response = await get(`${RootPath}/buckets/${bucket}/objects?limit=${page}`, { 'Authorization': 'Bearer ' + access_token });
+        let authentication = await this.auth.authenticate(ReadTokenScopes);
+        let response = await get(`${RootPath}/buckets/${bucket}/objects?limit=${page}`, { 'Authorization': 'Bearer ' + authentication.access_token });
         yield response.items;
 
         while (response.next) {
             const next = new URL(response.next);
             const startAt = querystring.escape(next.searchParams.get('startAt'));
-            response = await get(`${RootPath}/buckets/${bucket}/objects?startAt=${startAt}&limit=${page}`, { 'Authorization': 'Bearer ' + access_token });
+            authentication = await this.auth.authenticate(ReadTokenScopes);
+            response = await get(`${RootPath}/buckets/${bucket}/objects?startAt=${startAt}&limit=${page}`, { 'Authorization': 'Bearer ' + authentication.access_token });
             yield response.items;
         }
     }
@@ -121,9 +122,9 @@ class DataManagementClient {
      */
     async uploadObject(bucket, name, contentType, data) {
         // TODO: add support for large file uploads using "PUT buckets/:bucketKey/objects/:objectName/resumable"
-        const access_token = await this.auth.authenticate(WriteTokenScopes);
+        const authentication = await this.auth.authenticate(WriteTokenScopes);
         const response = await put(`${RootPath}/buckets/${bucket}/objects/${name}`, data, {
-            'Authorization': 'Bearer ' + access_token,
+            'Authorization': 'Bearer ' + authentication.access_token,
             'Content-Type': contentType
         });
         return response;
@@ -139,9 +140,9 @@ class DataManagementClient {
      * @throws Error when the request fails, for example, due to insufficient rights, or incorrect scopes.
      */
     async downloadObject(bucket, object) {
-        const access_token = await this.auth.authenticate(ReadTokenScopes);
+        const authentication = await this.auth.authenticate(ReadTokenScopes);
         const response = await get(`${RootPath}/buckets/${bucket}/objects/${object}`, {
-            'Authorization': 'Bearer ' + access_token,
+            'Authorization': 'Bearer ' + authentication.access_token,
         }, false);
         return response;
     }
@@ -158,8 +159,8 @@ class DataManagementClient {
      * with this name does not exist.
      */
     async objectDetails(bucket, object) {
-        const access_token = await this.auth.authenticate(ReadTokenScopes);
-        const response = await get(`${RootPath}/buckets/${bucket}/objects/${object}/details`, { 'Authorization': 'Bearer ' + access_token });
+        const authentication = await this.auth.authenticate(ReadTokenScopes);
+        const response = await get(`${RootPath}/buckets/${bucket}/objects/${object}/details`, { 'Authorization': 'Bearer ' + authentication.access_token });
         return response;
     }
 }

test/auth.js

@@ -12,8 +12,9 @@ describe('AuthenticationClient', function() {
 
     describe('authenticate()', function() {
         it('should return a token for valid scopes', async function() {
-            const token = await this.client.authenticate(['viewables:read']);
-            assert(token.length > 0);
+            const authentication = await this.client.authenticate(['viewables:read']);
+            assert(authentication.access_token);
+            assert(authentication.expires_in > 0);
         });
 
         it('should reject promise for invalid scopes', function(done) {