Merge pull request #46 from KnorpelSenf/master

Add TypeScript typings

Author: josiasmontag

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 .idea
 node_modules/
+built

README.md

@@ -137,24 +137,40 @@ const signingSecret = '...'; // You can find it in your webhook settings.
 const isValid = cloudConvert.webhooks.verify(payloadString, signature, signingSecret); // returns true or false
 ```
 
-## Unit Tests
+## Contributing
 
-Tests are based on mocha: 
+This section is intended for people how want to contribute to the development of this library.
 
-    npm run test
+### Getting started
+
+Begin with installing the necessary dependencies by running
+
+    npm install
+
+in the root directory of this repository.
+
+### Building
+
+This project is written in TypeScript so it needs to be compiled first:
+
+    npm run build
 
+This will compile the code in the `lib` directory and generate a `built` directory containing the JS files and the type declarations.
 
+### Unit Tests
 
-## Integration Tests
+Tests are based on mocha:
+
+    npm run test
+
+### Integration Tests
 
     npm run test-integration
-    
-    
+
 By default, this runs the integration tests against the Sandbox API with an official CloudConvert account. If you would like to use your own account, you can set your API key using the `CLOUDCONVERT_API_KEY` enviroment variable. In this case you need to whitelist the following MD5 hashes for Sandbox API (using the CloudConvert dashboard).
 
     53d6fe6b688c31c565907c81de625046  input.pdf
     99d4c165f77af02015aa647770286cf9  input.png
-    
 
 ## Resources
 

lib/CloudConvert.js

@@ -0,0 +1,83 @@
+import axios, { AxiosInstance } from "axios";
+import io from 'socket.io-client';
+import JobsResource, { JobEventData } from "./JobsResource";
+import TasksResource, { TaskEventData } from "./TasksResource";
+import UsersResource from "./UsersResource";
+import WebhooksResource from "./WebhooksResource";
+
+export default class CloudConvert {
+    private socket: SocketIOClient.Socket | undefined;
+    private subscribedChannels: Map<string, boolean> | undefined;
+    
+    public readonly apiKey: string;
+    public readonly useSandbox: boolean;
+    
+    public axios!: AxiosInstance;
+    public tasks!: TasksResource;
+    public jobs!: JobsResource;
+    public users!: UsersResource;
+    public webhooks!: WebhooksResource;
+
+    constructor(apiKey: string, useSandbox = false) {
+
+        this.apiKey = apiKey;
+        this.useSandbox = useSandbox;
+
+        this.createAxiosInstance();
+        this.createResources();
+
+    }
+
+
+    createAxiosInstance(): void {
+        this.axios = axios.create({
+            baseURL: this.useSandbox ? 'https://api.sandbox.cloudconvert.com/v2/' : 'https://api.cloudconvert.com/v2/',
+            headers: {
+                'Authorization': 'Bearer ' + this.apiKey,
+                'User-Agent': 'cloudconvert-node/v2 (https://github.com/cloudconvert/cloudconvert-node)'
+            }
+        });
+    }
+
+    createResources(): void {
+        this.tasks = new TasksResource(this);
+        this.jobs = new JobsResource(this);
+        this.users = new UsersResource(this);
+        this.webhooks = new WebhooksResource(this);
+    }
+
+
+    subscribe(channel: string, event: string, callback: ((event: JobEventData) => void) | ((event: TaskEventData) => void)): void {
+
+        if (!this.socket) {
+            this.socket = io.connect(this.useSandbox ? 'https://socketio.sandbox.cloudconvert.com' : 'https://socketio.cloudconvert.com', {
+                transports: ['websocket']
+            });
+            this.subscribedChannels = new Map<string, boolean>();
+        }
+
+        if (!this.subscribedChannels?.get(channel)) {
+            this.socket.emit('subscribe', {
+                channel,
+                auth: {
+                    headers: {
+                        'Authorization': 'Bearer ' + this.apiKey
+                    }
+                },
+            });
+            this.subscribedChannels?.set(channel, true);
+        }
+
+        this.socket.on(event, function (eventChannel: string, eventData: any): void {
+            if (channel !== eventChannel) {
+                return;
+            }
+            callback(eventData);
+        });
+
+    }
+
+
+}
+
+

lib/CloudConvert.ts

@@ -0,0 +1,95 @@
+import CloudConvert from './CloudConvert';
+import { Operation, Task, TaskEventData, TaskStatus } from './TasksResource';
+
+export type JobEvent = 'created' | 'updated' | 'finished' | 'failed';
+export type JobStatus = 'processing' | 'finished' | 'error';
+export type JobTaskStatus = Task['status'] | 'queued'
+export interface JobEventData { job: Job }
+
+export interface Job {
+    id: string;
+    tag: string | null;
+    status: TaskStatus;
+    created_at: string;
+    started_at: string | null;
+    ended_at: string | null;
+    tasks: JobTask[];
+}
+type NotPresentWhenInsideJob = 'job_id' | 'status'
+interface JobTask extends Omit<Task, NotPresentWhenInsideJob> {
+    name: string;
+    status: JobTaskStatus;
+}
+
+export default class JobsResource {
+    private readonly cloudConvert: CloudConvert;
+
+    constructor(cloudConvert: CloudConvert) {
+        this.cloudConvert = cloudConvert;
+    }
+
+    async get(id: string, query: null = null): Promise<Job> {
+        const response = await this.cloudConvert.axios.get('jobs/' + id, {
+            params: query || {}
+        });
+        return response.data.data;
+    }
+
+    async wait(id: string): Promise<Job> {
+        const response = await this.cloudConvert.axios.get('jobs/' + id + '/wait');
+        return response.data.data;
+    }
+
+    async all(query: { 'filter[status]'?: JobStatus; 'filter[tag]'?: string; include?: string; per_page?: number; page?: number; } | null = null): Promise<Job[]> {
+        const response = await this.cloudConvert.axios.get('jobs', {
+            params: query || {}
+        });
+        return response.data.data;
+    }
+
+    // See below for an explanation on how this type signature works
+    async create(data: JobTemplate | null = null): Promise<Job> {
+        const response = await this.cloudConvert.axios.post('jobs', data);
+        return response.data.data;
+    }
+
+    async delete(id: string): Promise<void> {
+        await this.cloudConvert.axios.delete('jobs/' + id);
+    }
+
+    async subscribeEvent(id: string, event: string, callback: (event: JobEventData) => void): Promise<void> {
+        this.cloudConvert.subscribe('private-job.' + id, 'job.' + event, callback);
+    }
+
+    async subscribeTaskEvent(id: string, event: string, callback: (event: TaskEventData) => void): Promise<void> {
+        this.cloudConvert.subscribe('private-job.' + id + '.tasks', 'task.' + event, callback);
+    }
+
+}
+
+// We need to map the types from the large Operation union type
+// to the template syntax from the API specs (confer the README)
+// that is used to create a job with a number of tasks. While this
+// is possible to write in just two lines of code, we divide this
+// up in many small steps in order to explain what's happening:
+
+// All possible operation strings ("import/url" etc)
+type PossibleOperationStrings = Operation['operation'];
+// Every argument in the tasks object should be assignable to this (for some operation string O)
+interface NamedOperation<O> { operation: O }
+// Given an operation string O, get the operation for it
+type OperationByName<O> = Extract<Operation, NamedOperation<O>>
+// Given an operation string O, get the operation data for it
+type OperationData<O> = OperationByName<O>['data'];
+// Add all properties to task that can only occur in tasks that are inside jobs
+interface TaskExtras<O> extends NamedOperation<O> { ignore_error?: boolean; }
+// Every argument in the tasks object is typed by this (for some operation string O)
+type TaskTemplate<O> = TaskExtras<O> & OperationData<O>;
+// Given a union type U of operation strings, turn each operation string into its TaskTemplate
+type Distribute<U> = U extends any ? TaskTemplate<U> : never;
+// Create a union of all possible tasks
+type PossibleOperations = Distribute<PossibleOperationStrings>;
+// Allow any number of names, each typed by a possible operation
+interface TaskContainer { [name: string]: PossibleOperations; }
+// Add the other properties that are required for job creation
+interface JobTemplate { tasks: TaskContainer; tag?: string; }