diff --git a/.github/workflows/create-documentation-pr.yml b/.github/workflows/create-documentation-pr.yml new file mode 100644 index 0000000..339e758 --- /dev/null +++ b/.github/workflows/create-documentation-pr.yml @@ -0,0 +1,27 @@ +name: Create documentation PR +on: + # Trigger the workflow on pull requests targeting the main branch + pull_request: + types: [assigned, unassigned, opened, reopened, synchronize, edited, labeled, unlabeled, edited, closed] + branches: + - main + +jobs: + create_documentation_pr: + if: github.event.action != 'closed' + + runs-on: ubuntu-latest + + steps: + - name: Check out current repository code + uses: actions/checkout@v2 + + - name: Create the documentation pull request + uses: apivideo/api.video-create-readme-file-pull-request-action@main + with: + source-file-path: "README.md" + destination-repository: apivideo/api.video-documentation + destination-path: sdks/vod + destination-filename: apivideo-typescript-uploader.md + pat: "${{ secrets.PAT }}" + \ No newline at end of file diff --git a/README.md b/README.md index 0aaaa1c..40f8e7e 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + [![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/api.video-typescript-uploader?style=social)](https://github.com/apivideo/api.video-typescript-uploader)   [![badge](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fcommunity.api.video)](https://community.api.video) ![](https://github.com/apivideo/.github/blob/main/assets/apivideo_banner.png)

api.video typescript video uploader

@@ -7,7 +8,7 @@ [api.video](https://api.video) is the video infrastructure for product builders. Lightning fast video APIs for integrating, scaling, and managing on-demand & low latency live streaming features in your app. -# Table of contents +## Table of contents - [Table of contents](#table-of-contents) - [Project description](#project-description) @@ -17,7 +18,7 @@ - [Installation method #2: typescript](#installation-method-2-typescript) - [Simple include in a javascript project](#simple-include-in-a-javascript-project) - [Documentation - Standard upload](#documentation---standard-upload) - - [Instanciation](#instanciation) + - [Instantiation](#instantiation) - [Options](#options) - [Using a delegated upload token (recommended):](#using-a-delegated-upload-token-recommended) - [Using an access token (discouraged):](#using-an-access-token-discouraged) @@ -30,7 +31,7 @@ - [`cancel()`](#cancel) - [`onPlayable()`](#onplayable) - [Documentation - Progressive upload](#documentation---progressive-upload) - - [Instanciation](#instanciation-1) + - [Instantiation](#instantiation-1) - [Options](#options-1) - [Using a delegated upload token (recommended):](#using-a-delegated-upload-token-recommended-1) - [Using an access token (discouraged):](#using-an-access-token-discouraged-1) @@ -44,7 +45,20 @@ - [`onPlayable()`](#onplayable-1) - [Static wrapper](#static-wrapper) -# Project description + + +## Project description Typescript library to upload videos to api.video using delegated upload token (or usual access token) from the front-end. @@ -52,11 +66,11 @@ 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 -# Getting started +## Getting started -## Installation +### Installation -### Installation method #1: requirejs +#### Installation method #1: requirejs If you use requirejs you can add the library as a dependency to your project with @@ -82,7 +96,7 @@ var uploader = new ProgressiveUploader({ }); ``` -### Installation method #2: typescript +#### Installation method #2: typescript If you use Typescript you can add the library as a dependency to your project with @@ -109,7 +123,7 @@ const uploader = new ProgressiveUploader({ ``` -### Simple include in a javascript project +#### Simple include in a javascript project Include the library in your HTML file like so: @@ -136,17 +150,17 @@ Then, once the `window.onload` event has been trigered, create your player using ``` -# Documentation - Standard upload +## Documentation - Standard upload -## Instanciation +### Instantiation -### 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. +The upload library is instantiated 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). +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 | @@ -155,7 +169,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 :). @@ -168,7 +182,7 @@ Using delegated upload tokens for authentication is best options when uploading | _common options (see bellow)_ | | | | -#### Using an API key (**strongly** discouraged): +##### Using an API key (**strongly** discouraged): **Warning**: be aware that exposing your API key client-side can lead to huge security issues. Use this method only if you know what you're doing :). @@ -180,7 +194,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 | @@ -194,7 +208,7 @@ Using delegated upload tokens for authentication is best options when uploading | maxVideoDuration | no | number | maximum duration allowed for the file (in seconds) | -### Example +#### Example ```javascript const uploader = new VideoUploader({ @@ -205,9 +219,9 @@ 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. @@ -216,14 +230,14 @@ On fail, the promise embeds the status code & error message returned by the API. **Example** ```javascript - // ... uploader instanciation + // ... uploader instantiation uploader.upload() .then((video) => console.log(video)) .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: @@ -234,7 +248,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 -### `cancel()` +#### `cancel()` The cancel() method cancels the upload. It takes no parameter. @@ -242,7 +256,7 @@ The cancel() method cancels the upload. It takes no parameter. **Example** ```javascript - // ... uploader instanciation + // ... uploader instantiation uploader.onProgress((event) => { console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`); @@ -255,7 +269,7 @@ The cancel() method cancels the upload. It takes no parameter. ``` -### `onPlayable()` +#### `onPlayable()` The onPlayable() method let you defined a listener that will be called when the video is playable. It takes a callback function with one parameter: the `video` object returned by the API. @@ -265,7 +279,7 @@ The onPlayable() method let you defined a listener that will be called when the
``` -# Documentation - Progressive upload +## Documentation - Progressive upload -## Instanciation +### Instantiation -### Options +#### 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. +The progressive upload object is instantiated 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). +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 | @@ -294,7 +308,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 :). @@ -306,7 +320,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 | @@ -318,7 +332,7 @@ Using delegated upload tokens for authentication is best options when uploading | mergeSmallPartsBeforeUpload | no | boolean | if false, parts smaller than 5MB will not be merged before upload, resulting in an error (default: true) | -### Example +#### Example ```javascript const uploader = new ProgressiveUploader({ @@ -327,9 +341,9 @@ Using delegated upload tokens for authentication is best options when uploading }); ``` -## Methods +### Methods -### `uploadPart(file: Blob)` +#### `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. @@ -338,13 +352,13 @@ On fail, the promise embeds the status code & error message returned by the API. **Example** ```javascript - // ... uploader instanciation + // ... uploader instantiation uploader.uploadPart(blob) .catch((error) => console.log(error.status, error.message)); ``` -### `uploadLastPart(file: Blob)` +#### `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. @@ -353,14 +367,14 @@ On fail, the promise embeds the status code & error message returned by the API. **Example** ```javascript - // ... uploader instanciation + // ... uploader instantiation uploader.uploadLastPart(blob) .then((video) => console.log(video)) .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: @@ -371,7 +385,7 @@ An onProgress event contains the following attributes: **Example** ```javascript - // ... uploader instanciation + // ... uploader instantiation uploader.onProgress((event) => { console.log(`total number of bytes uploaded for this upload: ${event.uploadedBytes}.`); @@ -380,11 +394,11 @@ An onProgress event contains the following attributes: }); ``` -### `cancel()` +#### `cancel()` The cancel() method cancels the upload. It takes no parameter. -### `onPlayable()` +#### `onPlayable()` The onPlayable() method let you defined a listener that will be called when the video is playable. It takes a callback function with one parameter: the `video` object returned by the API. @@ -394,7 +408,7 @@ The onPlayable() method let you defined a listener that will be called when the