Merge pull request #7 from apivideo/progressive-upload

feat: Progressive uploads

Author: olivier-lando

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 All changes to this project will be documented in this file.
 
+## [0.0.6] - 2021-11-10
+- Add progressive upload feature
+
 ## [0.0.5] - 2021-08-12
 - Fix chunk size (default 50MB, min 5MB, max 128MB)
 - Fix upload progress listener

README.md

@@ -1,19 +1,24 @@
 [![badge](https://img.shields.io/twitter/follow/api_video?style=social)](https://twitter.com/intent/follow?screen_name=api_video)
 
-[![badge](https://img.shields.io/github/stars/apivideo/typescript-video-uploader?style=social)](https://github.com/apivideo/typescript-video-uploader)
+[![badge](https://img.shields.io/github/stars/apivideo/php-api-client?style=social)](https://github.com/apivideo/php-api-client)
 
 [![badge](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fcommunity.api.video)](https://community.api.video)
 
 ![](https://github.com/apivideo/API_OAS_file/blob/master/apivideo_banner.png)
 
-api.video is an API that encodes on the go to facilitate immediate playback, enhancing viewer streaming experiences across multiple devices and platforms. You can stream live or on-demand online videos within minutes.
+[api.video](https://api.video) is an API that encodes on the go to facilitate immediate playback, enhancing viewer streaming experiences across multiple devices and platforms. You can stream live or on-demand online videos within minutes.
 
-# api.video video uploader
+# api.video typescript video uploader
 ![npm](https://img.shields.io/npm/v/@api.video/video-uploader) ![ts](https://badgen.net/badge/-/TypeScript/blue?icon=typescript&label)
 
-Typescript library to upload videos to api.video using delegated upload token (or usual access token) from the front-end.
+Typescript library to upload videos to api.video using delegated upload token (or usual access token) from the front-end. 
 
-# Usage
+It allows you to upload videos in two ways:
+- standard upload: to send a whole video file in one go
+- progressive upload: to send a video file by chunks, without needing to know the final size of the video file
+
+
+# Installation
 
 ## Installation method #1: requirejs
 
@@ -26,12 +31,18 @@ $ npm install --save @api.video/video-uploader
 You can then use the library in your script: 
 
 ```javascript
+// standard upload:
 var { VideoUploader } = require('@api.video/video-uploader');
 
 var uploader = new VideoUploader({
-    file: files[0],
-    uploadToken: "YOUR_DELEGATED_TOKEN"
-    // ... other optional options
+    // ... (see bellow)
+}); 
+
+// progressive upload:
+var { ProgressiveUploader } = require('@api.video/video-uploader');
+
+var uploader = new ProgressiveUploader({
+    // ... (see bellow)
 }); 
 ```
 
@@ -46,12 +57,18 @@ $ npm install --save @api.video/video-uploader
 You can then use the library in your script: 
 
 ```typescript
+// standard upload:
 import { VideoUploader } from '@api.video/video-uploader'
 
 const uploader = new VideoUploader({
-    file: files[0],
-    uploadToken: "YOUR_DELEGATED_TOKEN"
-    // ... other optional options
+    // ... (see bellow)
+});
+
+// progressive upload:
+import { ProgressiveUploader } from '@api.video/video-uploader'
+
+const uploader = new ProgressiveUploader({
+    // ... (see bellow)
 });
 ```
 
@@ -83,13 +100,15 @@ Then, once the `window.onload` event has been trigered, create your player using
 </script>
 ```
 
-# Instanciation
+# Usage - Standard upload
+
+## Instanciation
 
-## Options 
+### Options 
 
 The upload library is instanciated using an `options` object. Options to provide depend on the way you want to authenticate to the API: either using a delegated upload token (recommanded), or using a usual access token. 
 
-### Using a delegated upload token (recommended):
+#### Using a delegated upload token (recommended):
 
 Using delegated upload tokens for authentication is best options when uploading from the client side. To know more about delegated upload token, read the dedicated article on api.video's blog: [Delegated Uploads](https://api.video/blog/tutorials/delegated-uploads).
 
@@ -100,7 +119,7 @@ Using delegated upload tokens for authentication is best options when uploading
 |                       videoId | no        | string | id of an existing video |
 | _common options (see bellow)_ |           |        |                         |
 
-### Using an access token (discouraged):
+#### Using an access token (discouraged):
 
 **Warning**: be aware that exposing your access token client-side can lead to huge security issues. Use this method only if you know what you're doing :).
 
@@ -112,7 +131,7 @@ Using delegated upload tokens for authentication is best options when uploading
 | _common options (see bellow)_ |           |        |                         |
 
 
-### Common options
+#### Common options
 
 
 | Option name | Mandatory | Type   | Description                                                                |
@@ -123,7 +142,7 @@ Using delegated upload tokens for authentication is best options when uploading
 |     retries | no        | number | number of retries when an API call fails (default: 5)                      |
 
 
-## Example
+### Example
 
 ```javascript
     const uploader = new VideoUploader({
@@ -134,15 +153,15 @@ Using delegated upload tokens for authentication is best options when uploading
     });
 ```
 
-# Methods
+## Methods
 
-## `upload()`
+### `upload()`
 
 The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected.
 On success, the promise embeds the `video` object returned by the API.
 On fail, the promise embeds the status code & error message returned by the API.
 
-### Example
+#### Example
 
 ```javascript
     // ... uploader instanciation
@@ -152,7 +171,7 @@ On fail, the promise embeds the status code & error message returned by the API.
         .catch((error) => console.log(error.status, error.message));
 ```
 
-## `onProgress()`
+### `onProgress()`
 
 The onProgress() method let you defined an upload progress listener. It takes a callback function with one parameter: the onProgress events.
 An onProgress event contains the following attributes:
@@ -163,7 +182,7 @@ An onProgress event contains the following attributes:
 - currentChunk (number): index of the chunk being uploaded
 - currentChunkUploadedBytes (number): number of bytes uploaded for the current chunk
 
-### Example
+#### Example
 
 ```javascript
     // ... uploader instanciation
@@ -177,3 +196,104 @@ An onProgress event contains the following attributes:
         console.log(`number of bytes uploaded for the current chunk: ${event.currentChunkUploadedBytes}.`);
     });
 ```
+
+# Usage - Progressive upload
+
+
+## Instanciation
+
+### Options 
+
+The progressive upload object is instanciated using an `options` object. Options to provide depend on the way you want to authenticate to the API: either using a delegated upload token (recommanded), or using a usual access token. 
+
+#### Using a delegated upload token (recommended):
+
+Using delegated upload tokens for authentication is best options when uploading from the client side. To know more about delegated upload token, read the dedicated article on api.video's blog: [Delegated Uploads](https://api.video/blog/tutorials/delegated-uploads).
+
+
+|                   Option name | Mandatory | Type   | Description             |
+| ----------------------------: | --------- | ------ | ----------------------- |
+|                   uploadToken | **yes**   | string | your upload token       |
+|                       videoId | no        | string | id of an existing video |
+| _common options (see bellow)_ |           |        |                         |
+
+#### Using an access token (discouraged):
+
+**Warning**: be aware that exposing your access token client-side can lead to huge security issues. Use this method only if you know what you're doing :).
+
+
+|                   Option name | Mandatory | Type   | Description             |
+| ----------------------------: | --------- | ------ | ----------------------- |
+|                   accessToken | **yes**   | string | your access token       |
+|                       videoId | **yes**   | string | id of an existing video |
+| _common options (see bellow)_ |           |        |                         |
+
+
+#### Common options
+
+
+| Option name | Mandatory | Type   | Description                                                                |
+| ----------: | --------- | ------ | -------------------------------------------------------------------------- |
+|     apiHost | no        | string | api.video host (default: ws.api.video)                                     |
+|     retries | no        | number | number of retries when an API call fails (default: 5)                      |
+
+
+### Example
+
+```javascript
+    const uploader = new ProgressiveUploader({
+        uploadToken: "YOUR_DELEGATED_TOKEN",
+        retries: 10,
+    });
+```
+
+## Methods
+
+### `uploadPart(file: Blob)`
+
+The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected.
+On success, the promise embeds the `video` object returned by the API.
+On fail, the promise embeds the status code & error message returned by the API.
+
+#### Example
+
+```javascript
+    // ... uploader instanciation
+
+    uploader.uploadPart(blob)
+        .catch((error) => console.log(error.status, error.message));
+```
+
+### `uploadLastPart(file: Blob)`
+
+The upload() method starts the upload. It takes no parameter. It returns a Promise that resolves once the file is uploaded. If an API call fails more than the specified number of retries, then the promise is rejected.
+On success, the promise embeds the `video` object returned by the API.
+On fail, the promise embeds the status code & error message returned by the API.
+
+#### Example
+
+```javascript
+    // ... uploader instanciation
+
+    uploader.uploadLastPart(blob)
+        .then((video) => console.log(video))
+        .catch((error) => console.log(error.status, error.message));
+```
+
+### `onProgress()`
+
+The onProgress() method let you defined an upload progress listener. It takes a callback function with one parameter: the onProgress events.
+An onProgress event contains the following attributes:
+- uploadedBytes (number): total number of bytes uploaded for this upload
+- totalBytes (number): total size of the file
+
+#### Example
+
+```javascript
+    // ... uploader instanciation
+    
+    uploader.onProgress((event) => {
+        console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`);
+        console.log(`total size of the file: ${event.totalBytes}.`);
+    });
+```

dist/index.js

@@ -0,0 +1,5 @@
+export declare const MIN_CHUNK_SIZE: number;
+export declare const DEFAULT_CHUNK_SIZE: number;
+export declare const MAX_CHUNK_SIZE: number;
+export declare const DEFAULT_RETRIES = 5;
+export declare const DEFAULT_API_HOST = "ws.api.video";

dist/src/common.d.ts

@@ -1,42 +1,3 @@
-interface OptionsWithUploadToken extends Options {
-    uploadToken: string;
-    videoId?: string;
-}
-interface OptionsWithAccessToken extends Options {
-    accessToken: string;
-    videoId: string;
-}
-interface Options {
-    file: File;
-    chunkSize?: number;
-    apiHost?: string;
-    retries?: number;
-}
-export interface UploadProgressEvent {
-    uploadedBytes: number;
-    totalBytes: number;
-    chunksCount: number;
-    chunksBytes: number;
-    currentChunk: number;
-    currentChunkUploadedBytes: number;
-}
-export declare class VideoUploader {
-    private file;
-    private chunkSize;
-    private uploadEndpoint;
-    private currentChunk;
-    private chunksCount;
-    private fileSize;
-    private fileName;
-    private videoId?;
-    private retries;
-    private onProgressCallbacks;
-    private headers;
-    constructor(options: OptionsWithAccessToken | OptionsWithUploadToken);
-    onProgress(cb: (e: UploadProgressEvent) => void): void;
-    upload(): Promise<any>;
-    private sleep;
-    private createFormData;
-    private uploadCurrentChunk;
-}
-export {};
+export { UploadProgressEvent, VideoUploader, VideoUploaderOptionsWithAccessToken, VideoUploaderOptionsWithUploadToken } from "./video-uploader";
+export { ProgressiveUploadProgressEvent, ProgressiveUploader, ProgressiveUploaderOptionsWithAccessToken, ProgressiveUploaderOptionsWithUploadToken } from './progressive-video-uploader';
+export { MIN_CHUNK_SIZE, MAX_CHUNK_SIZE } from './common';

dist/src/index.d.ts

@@ -0,0 +1,38 @@
+export interface ProgressiveUploaderOptionsWithUploadToken extends Options {
+    uploadToken: string;
+    videoId?: string;
+}
+export interface ProgressiveUploaderOptionsWithAccessToken extends Options {
+    accessToken: string;
+    videoId: string;
+}
+interface Options {
+    apiHost?: string;
+    retries?: number;
+}
+export interface ProgressiveUploadProgressEvent {
+    uploadedBytes: number;
+    totalBytes: number;
+}
+export interface ProgressiveProgressEvent {
+    uploadedBytes: number;
+    totalBytes: number;
+}
+export declare class ProgressiveUploader {
+    private uploadEndpoint;
+    private videoId?;
+    private retries;
+    private onProgressCallbacks;
+    private headers;
+    private currentPartNum;
+    private currentPartBlobs;
+    private currentPartBlobsSize;
+    constructor(options: ProgressiveUploaderOptionsWithAccessToken | ProgressiveUploaderOptionsWithUploadToken);
+    onProgress(cb: (e: ProgressiveProgressEvent) => void): void;
+    uploadPart(file: Blob): Promise<void>;
+    uploadLastPart(file: Blob): Promise<any>;
+    private createFormData;
+    private sleep;
+    private upload;
+}
+export {};