hub / github.com/bytescale/bytescale-javascript-sdk

github.com/bytescale/bytescale-javascript-sdk @v3.53.0

Chat with this repo

repository ↗ · DeepWiki ↗ · release v3.53.0 ↗ · + Follow

379 symbols 630 edges 68 files 38 documented · 10%

What it actually does AI analysis from the code graph — generated when you open this

loading…

README

Use the Bytescale JavaScript SDK to upload, transform, and serve files at scale.

Full SDK Documentation • Upload Widget • Media Processing APIs • Storage • CDN

Bytescale JavaScript SDK Example

Installation

For Node.js:

npm install @bytescale/sdk node-fetch

For Browsers:

npm install @bytescale/sdk

If you'd prefer to use a script tag:

<script src="https://js.bytescale.com/sdk/v3"></script>

Uploading Files — Try on CodePen

This library is isomorphic, meaning you can upload files from Node.js, or the browser, or both.

From Node.js:

import * as Bytescale from "@bytescale/sdk";
import nodeFetch from "node-fetch";

const uploadManager = new Bytescale.UploadManager({
  fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
  apiKey: "free" // Get API keys from: www.bytescale.com
});

uploadManager
  .upload({
    // Supported types:
    // - String
    // - Blob
    // - ArrayBuffer
    // - Buffer
    // - ReadableStream (Node.js), e.g. fs.createReadStream("file.txt")
    data: "Hello World",

    // ---------
    // Optional:
    // ---------

    // Required if 'data' is a stream.
    // size: 5098, // e.g. fs.statSync("file.txt").size

    // Required if 'data' is a stream, buffer, or string.
    mime: "text/plain",

    // Required if 'data' is a stream, buffer, or string.
    originalFileName: "my_file.txt"

    // Reports progress: bytesTotal, bytesSent, progress.
    // onProgress: ({ progress }) => console.log(progress),

    // Controls multipart upload concurrency. Ignored if 'data' is a stream.
    // maxConcurrentUploadParts: 4,

    // Up to 2KB of arbitrary JSON.
    // metadata: {
    //   productId: 60891
    // },

    // Up to 25 tags per file.
    // tags: [
    //   "example_tag"
    // ],

    // About file paths:
    // - Your API key's "file upload path" is used by default, and can be changed by editing the API key's settings.
    // - You can override the API key's file upload path by specifying a path below.
    // - You may use path variables (e.g. "{UTC_DAY}"): http://localhost:3201/docs/path-variables
    // path: {
    //   folderPath: "/uploads/{UTC_YEAR}/{UTC_MONTH}/{UTC_DAY}",
    //   fileName: "{UTC_TIME_TOKEN_INVERSE}{UNIQUE_DIGITS_2}{ORIGINAL_FILE_EXT}"
    // },

    // Set to 'isCancelled = true' after invoking 'upload' to cancel the upload.
    // cancellationToken: {
    //   isCancelled: false
    // }
  })
  .then(
    ({ fileUrl, filePath }) => {
      // --------------------------------------------
      // File successfully uploaded!
      // --------------------------------------------
      // The 'filePath' uniquely identifies the file,
      // and is what you should save to your DB.
      // --------------------------------------------
      console.log(`File uploaded to: ${fileUrl}`);
    },
    error => console.error(`Error: ${error.message}`, error)
  );

From the Browser:

<html>
  <head>
    <script src="https://js.bytescale.com/sdk/v3"></script>
    <script>
      // import * as Bytescale from "@bytescale/sdk"
      const uploadManager = new Bytescale.UploadManager({
        apiKey: "free" // Get API keys from: www.bytescale.com
      });

      const onFileSelected = async event => {
        const file = event.target.files[0];

        try {
          const { fileUrl, filePath } = await uploadManager.upload({
            // Supported types:
            // - String
            // - Blob
            // - ArrayBuffer
            // - File (i.e. from a DOM file input element)
            data: file

            // ---------
            // Optional:
            // ---------

            // Required if 'data' is a stream. Node.js only. (Not required when uploading files from the browser.)
            // size: 5098, // e.g. fs.statSync("file.txt").size

            // Required if 'data' is a stream, buffer, or string. (Not required for DOM file inputs or blobs.)
            // mime: "application/octet-stream",

            // Required if 'data' is a stream, buffer, or string. (Not required for DOM file inputs or blobs.)
            // originalFileName: "my_file.txt",

            // Reports progress: bytesTotal, bytesSent, progress.
            // onProgress: ({ progress }) => console.log(progress),

            // Controls multipart upload concurrency. Ignored if 'data' is a stream.
            // maxConcurrentUploadParts: 4,

            // Up to 2KB of arbitrary JSON.
            // metadata: {
            //   productId: 60891
            // },

            // Up to 25 tags per file.
            // tags: [
            //   "example_tag"
            // ],

            // About file paths:
            // - Your API key's "file upload path" is used by default, and can be changed by editing the API key's settings.
            // - You can override the API key's file upload path by specifying a path below.
            // - You may use path variables (e.g. "{UTC_DAY}"): http://localhost:3201/docs/path-variables
            // path: {
            //   folderPath: "/uploads/{UTC_YEAR}/{UTC_MONTH}/{UTC_DAY}",
            //   fileName: "{UTC_TIME_TOKEN_INVERSE}{UNIQUE_DIGITS_2}{ORIGINAL_FILE_EXT}"
            // },

            // Set to 'isCancelled = true' after invoking 'upload' to cancel the upload.
            // cancellationToken: {
            //   isCancelled: false
            // }
          });

          // --------------------------------------------
          // File successfully uploaded!
          // --------------------------------------------
          // The 'filePath' uniquely identifies the file,
          // and is what you should save to your API.
          // --------------------------------------------
          alert(`File uploaded:\n${fileUrl}`);
        } catch (e) {
          alert(`Error:\n${e.message}`);
        }
      };
    </script>
  </head>
  <body>
    <input type="file" onchange="onFileSelected(event)" />
  </body>
</html>

Downloading Files

import * as Bytescale from "@bytescale/sdk";
import nodeFetch from "node-fetch"; // Only required for Node.js

const fileApi = new Bytescale.FileApi({
  fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
  apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});

fileApi
  .downloadFile({
    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
    filePath: "/uploads/2022/12/25/hello_world.txt"
  })
  .then(response => response.text()) // .text() | .json() | .blob() | .stream()
  .then(
    fileContents => console.log(fileContents),
    error => console.error(error)
  );

Use the UrlBuilder to get a URL instead (if you need a file URL instead of a binary stream).

Processing Files

import * as Bytescale from "@bytescale/sdk";
import fetch from "node-fetch"; // Only required for Node.js
import fs from "fs";

const fileApi = new Bytescale.FileApi({
  fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
  apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});

fileApi
  .processFile({
    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
    filePath: "/uploads/2022/12/25/image.jpg",

    // See: https://www.bytescale.com/docs/image-processing-api
    transformation: "image",
    transformationParams: {
      w: 800,
      h: 600
    }
  })
  .then(response => response.stream()) // .text() | .json() | .blob() | .stream()
  .then(
    imageByteStream =>
      new Promise((resolve, reject) => {
        const writer = fs.createWriteStream("image-thumbnail.jpg");
        writer.on("close", resolve);
        writer.on("error", reject);
        imageByteStream.pipe(writer);
      })
  )
  .then(
    () => console.log("Thumbnail saved to 'image-thumbnail.jpg'"),
    error => console.error(error)
  );

Use the UrlBuilder to get a URL instead (if you need a file URL instead of a binary stream).

Get File Details

import * as Bytescale from "@bytescale/sdk";
import fetch from "node-fetch"; // Only required for Node.js

const fileApi = new Bytescale.FileApi({
  fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
  apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});

fileApi
  .getFileDetails({
    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
    filePath: "/uploads/2022/12/25/image.jpg"
  })
  .then(
    fileDetails => console.log(fileDetails),
    error => console.error(error)
  );

Listing Folders

import * as Bytescale from "@bytescale/sdk";
import fetch from "node-fetch"; // Only required for Node.js

const folderApi = new Bytescale.FolderApi({
  fetchApi: nodeFetch, // import nodeFetch from "node-fetch"; // Only required for Node.js. TypeScript: 'nodeFetch as any' may be necessary.
  apiKey: "YOUR_API_KEY" // e.g. "secret_xxxxx"
});

folderApi
  .listFolder({
    accountId: "YOUR_ACCOUNT_ID", // e.g. "W142hJk"
    folderPath: "/",
    recursive: false
  })
  .then(
    // Note: operation is paginated, see 'result.cursor' and 'params.cursor'.
    result => console.log(`Items in folder: ${result.items.length}`),
    error => console.error(error)
  );

📙 Bytescale SDK API Reference

For a complete list of operations, please see:

Bytescale JavaScript SDK Docs »

🌐 Media Processing APIs (Image/Video/Audio)

Bytescale provides several real-time Media Processing APIs:

Image Processing APIs (resize, crop, convert, compress & watermark)
Video Processing APIs (transcode, optimize, resize & extract metadata)
Audio Processing APIs (transcode, optimize, trim & extract metadata)

Image Processing API (Original Image)

Here's an example using a photo of Chicago:

https://upcdn.io/W142hJk/raw/example/city-landscape.jpg

Image Processing API (Transformed Image)

Using the Image Processing API, you can produce [this image](https://upcdn.io/W142hJk/image/example/city-landscape.jpg?w=900&h=600&fit=crop&f=webp&q=80&blur=4&text=WATERMARK&layer-opacity=80&blend=overlay&layer-rotate=315&font-size=100&padding=10&font-

Extension points exported contracts — how you extend this code

AuthManagerInterface (Interface)

(no doc) [2 implementers]

src/private/model/AuthManagerInterface.ts

UrlBuilderParams (Interface)

(no doc)

src/public/shared/UrlBuilderTypes.ts

Consumer (Interface)

(no doc)

src/private/NodeChunkedStream.ts

UrlBuilderOptionsBase (Interface)

(no doc)

src/public/shared/UrlBuilderTypes.ts

ServiceWorkerInitStatus (Interface)

(no doc)

src/private/model/ServiceWorkerInitStatus.ts

NonDeprecatedCommonQueryParams (Interface)

(no doc)

src/public/shared/UrlBuilderTypes.ts

PutUploadPartResult (Interface)

(no doc)

src/private/model/PutUploadPartResult.ts

DeprecatedCommonQueryParams (Interface)

(no doc)

src/public/shared/UrlBuilderTypes.ts

Core symbols most depended-on inside this repo

url

called by 12

src/public/shared/UrlBuilder.ts

streamToBuffer

called by 6

tests/utils/StreamToBuffer.ts

getSession

called by 4

src/private/AuthSessionState.ts

debug

called by 4

src/private/ConsoleUtils.ts

warn

called by 4

src/private/ConsoleUtils.ts

assertUnreachable

called by 4

src/private/TypeUtils.ts

error

called by 3

src/private/ConsoleUtils.ts

prefix

called by 3

src/private/ConsoleUtils.ts

Shape

Interface 145

Method 128

Class 62

Function 44

Languages

TypeScript100%

Modules by API surface

src/public/shared/generated/models/index.ts81 symbols

src/public/shared/generated/runtime.ts46 symbols

src/public/shared/generated/apis/FileApi.ts18 symbols

src/private/UploadManagerBase.ts18 symbols

src/public/shared/generated/apis/FolderApi.ts16 symbols

src/public/browser/AuthManagerBrowser.ts14 symbols

src/public/shared/UrlBuilderTypes.ts13 symbols

src/private/NodeChunkedStream.ts13 symbols

src/public/shared/generated/apis/UploadApi.ts12 symbols

src/public/shared/UrlBuilder.ts12 symbols

src/private/ServiceWorkerUtils.ts11 symbols

src/public/node/UploadManagerNode.ts9 symbols

For agents

$ claude mcp add bytescale-javascript-sdk \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

github.com/bytescale/bytescale-javascript-sdk @v3.53.0

Installation

For Node.js:

For Browsers:

Uploading Files — Try on CodePen

From Node.js:

From the Browser:

Downloading Files

Processing Files

Get File Details

Listing Folders

📙 Bytescale SDK API Reference

🌐 Media Processing APIs (Image/Video/Audio)

Image Processing API (Original Image)

Image Processing API (Transformed Image)

Extension points exported contracts — how you extend this code

Core symbols most depended-on inside this repo

Shape

Languages

Modules by API surface

For agents

Ask about this repo answers extend the page