Merge branch 'feature/signed-urls'

Author: josiasmontag

README.md

@@ -140,7 +140,39 @@ const isValid = cloudConvert.webhooks.verify(
 ); // returns true or false
 ```
 
-## Using Sandbox
+## Signed URLs
+
+Signed URLs allow converting files on demand only using URL query parameters. The node.js SDK allows to generate such URLs. Therefore, you need to obtain a signed URL base and a signing secret on the [CloudConvert Dashboard](https://cloudconvert.com/dashboard/api/v2/signed-urls).
+
+```js
+const signedUrlBase = 'https://s.cloudconvert.com/...'; // You can find it in your signed URL settings.
+const signingSecret = '...'; // You can find it in your signed URL settings.
+const cacheKey = 'cache-key'; // Allows caching of the result file for 24h
+
+const job = {
+    tasks: {
+        'import-it': {
+            operation: 'import/url',
+            url: 'https://some.url',
+            filename: 'logo.png'
+        },
+        'export-it': {
+            operation: 'export/url',
+            input: 'import-it',
+            inline: true
+        }
+    }
+};
+
+const url = cloudConvert.signedUrls.sign(
+    signedUrlBase,
+    signingSecret,
+    job,
+    cacheKey
+); // returns the generated URL
+```
+
+## Using the Sandbox
 
 You can use the Sandbox to avoid consuming your quota while testing your application. The node SDK allows you to do that.
 

lib/CloudConvert.ts

@@ -5,6 +5,7 @@ import TasksResource, { TaskEventData } from './TasksResource';
 import UsersResource from './UsersResource';
 import WebhooksResource from './WebhooksResource';
 import { version } from '../package.json';
+import SignedUrlResource from './SignedUrlResource';
 
 export default class CloudConvert {
     private socket: SocketIOClient.Socket | undefined;
@@ -18,6 +19,7 @@ export default class CloudConvert {
     public jobs!: JobsResource;
     public users!: UsersResource;
     public webhooks!: WebhooksResource;
+    public signedUrls!: SignedUrlResource;
 
     constructor(apiKey: string, useSandbox = false) {
         this.apiKey = apiKey;
@@ -47,6 +49,7 @@ export default class CloudConvert {
         this.jobs = new JobsResource(this);
         this.users = new UsersResource(this);
         this.webhooks = new WebhooksResource(this);
+        this.signedUrls = new SignedUrlResource(this);
     }
 
     subscribe(

lib/JobsResource.ts

@@ -127,7 +127,7 @@ interface TaskContainer {
     [name: string]: PossibleOperations;
 }
 // Add the other properties that are required for job creation
-interface JobTemplate {
+export interface JobTemplate {
     tasks: TaskContainer;
     tag?: string;
 }

lib/SignedUrlResource.ts

@@ -0,0 +1,38 @@
+import * as crypto from 'crypto';
+import CloudConvert from './CloudConvert';
+import { JobTemplate } from './JobsResource';
+
+export default class SignedUrlResource {
+    private readonly cloudConvert: CloudConvert;
+
+    constructor(cloudConvert: CloudConvert) {
+        this.cloudConvert = cloudConvert;
+    }
+
+    sign(
+        base: string,
+        signingSecret: string,
+        job: JobTemplate,
+        cacheKey: string | null
+    ): string {
+        const json = JSON.stringify(job);
+        const base64 = new Buffer(json || '').toString('base64');
+        const base64UrlSafe = base64
+            .replace('+', '-')
+            .replace('/', '_')
+            .replace(/=+$/, '');
+
+        let url = base + '?job=' + base64UrlSafe;
+
+        if (cacheKey) {
+            url += '&cache_key=' + cacheKey;
+        }
+
+        const hmac = crypto.createHmac('sha256', signingSecret);
+        const signature = hmac.update(Buffer.from(url, 'utf-8')).digest('hex');
+
+        url += '&s=' + signature;
+
+        return url;
+    }
+}

tests/unit/SignedUrlResourceTest.js

@@ -0,0 +1,46 @@
+import CloudConvert from '../../built/lib/CloudConvert.js';
+import { assert } from 'chai';
+
+describe('SignedUrlResource', () => {
+    beforeEach(() => {
+        this.cloudConvert = new CloudConvert('test');
+    });
+
+    describe('create()', () => {
+        it('should create a signed URL', async () => {
+            const base =
+                'https://s.cloudconvert.com/b3d85428-584e-4639-bc11-76b7dee9c109';
+            const signingSecret = 'NT8dpJkttEyfSk3qlRgUJtvTkx64vhyX';
+
+            const job = {
+                tasks: {
+                    'import-it': {
+                        operation: 'import/url',
+                        url: 'https://some.url',
+                        filename: 'logo.png'
+                    },
+                    'export-it': {
+                        operation: 'export/url',
+                        input: 'import-it',
+                        inline: true
+                    }
+                }
+            };
+
+            const url = this.cloudConvert.signedUrls.sign(
+                base,
+                signingSecret,
+                job,
+                'mykey'
+            );
+
+            assert.include(url, base);
+            assert.include(url, '?job=');
+            assert.include(url, '&cache_key=mykey');
+            assert.include(
+                url,
+                '&s=209d54e4454a407de71a07e6e500f45155fecf58a4e53d68329fbf358efcd823'
+            );
+        });
+    });
+});