@bytescale/sdk 3.0.0-alpha.2 → 3.0.0-alpha.21

package/dist/types/index.d.ts

@@ -1,2 +1,2 @@
 export * from "./public/shared";
-export * from "./public/node";
+export * from "./public/browser";

package/dist/types/private/AuthSessionState.d.ts

@@ -1,13 +1,30 @@
 import { AuthSession } from "./model/AuthSession";
+import { Mutex } from "./Mutex";
+/**
+ * Maintains a global session state, even across package versions.
+ *
+ * This is to allow users to start auth sessions via the Bytescale JavaScript SDK, where due to versioning or other
+ * bundling issues, the Bytescale Upload Widget has been bundled with a different Bytescale JavaScript SDK. In this
+ * scenario, the user wouldn't be able to start an auth session with the Bytescale Upload Widget. Therefore, we use
+ * global state (i.e. on the window) to ensure the session state can be shared between the user's instance of the
+ * Bytescale JavaScript SDK and the Upload Widget's version of the Bytescale JavaScript SDK.
+ *
+ * Users also frequently have problems caused by them not keeping track of *Api and *Manager instances correctly, so
+ * making this global prevents a lot of common mistakes.
+ */
 export declare class AuthSessionState {
+    private static readonly stateKey;
+    private static readonly mutexKey;
     /**
-     * Intentionally global:
-     *
-     * Users frequently have problems caused by them not keeping track of *Api and *Manager instances correctly, so we
-     * make this global as in 99.9% of cases, this is what users want, and it prevents lots of common mistakes.
-     *
-     * We only set this in the browser.
-     * Never in Node.js.
+     * Called in the browser only.
      */
-    static session: AuthSession | undefined;
+    static getMutex(): Mutex;
+    /**
+     * Called in the browser only.
+     */
+    static setSession(session: AuthSession | undefined): void;
+    /**
+     * Called in the browser and in Node.js (so we check the env before calling env-specific code).
+     */
+    static getSession(): AuthSession | undefined;
 }

package/dist/types/private/EnvChecker.d.ts

@@ -1,4 +1,4 @@
 export declare class EnvChecker {
-    static isNodeJs(): boolean;
+    static isBrowser(): boolean;
     static methodRequiresBrowser(methodName: string): Error;
 }

package/dist/types/private/Mutex.d.ts

@@ -1,5 +1,5 @@
 /**
- * A lightweight mutex. (Other libraries contain too many features and we want to keep the size upload-js down).
+ * A lightweight mutex. (Other libraries contain too many features and we want to keep size down).
  *
  * Characteristics:
  * - Non-reentrant.

package/dist/types/private/StreamUtils.d.ts

@@ -3,6 +3,7 @@ import type * as stream from "stream";
 export declare class StreamUtils {
     static create(): stream.Readable;
     static empty(): NodeJS.ReadableStream;
+    static fromArrayBuffer(buffer: ArrayBuffer): NodeJS.ReadableStream;
     static fromBuffer(buffer: Buffer): NodeJS.ReadableStream;
     static endStream(readable: stream.Readable): void;
 }

package/dist/types/private/UploadManagerBase.d.ts

@@ -11,6 +11,7 @@ import { UploadManagerParams, UploadSource } from "../public/shared/CommonTypes"
 export declare abstract class UploadManagerBase<TSource, TInit> implements UploadManagerInterface {
     protected readonly config: BytescaleApiClientConfig;
     protected readonly stringMimeType = "text/plain";
+    private readonly accountId;
     private readonly defaultMaxConcurrentUploadParts;
     private readonly intervalMs;
     private readonly uploadApi;
@@ -28,7 +29,11 @@ export declare abstract class UploadManagerBase<TSource, TInit> implements Uploa
     protected abstract doPutUploadPart(part: UploadPart, contentLength: number, source: TSource, onProgress: (bytesSentDelta: number) => void, addCancellationHandler: AddCancellationHandler): Promise<PutUploadPartResult>;
     private onIntervalTick;
     private makeCancellationMethods;
-    private makeProgressCallback;
+    /**
+     * Returns a callback, which when called, returns a callback that can be used by ONE specific part to report its progress.
+     */
+    private makeOnProgressForPartFactory;
+    private makeProgressEvent;
     private assertNotCancelled;
     private isCancelled;
     private beginUpload;

package/dist/types/private/UploadManagerBrowserWorkerBase.d.ts

@@ -0,0 +1,19 @@
+import { UploadManagerBase } from "./UploadManagerBase";
+import { UploadSourceProcessedBrowser, UploadSourceProcessedWorker } from "./model/UploadSourceProcessed";
+import { PreUploadInfo } from "./model/PreUploadInfo";
+import { UploadPart } from "../public/shared/generated";
+import { UploadManagerParams, UploadSource } from "../public/shared/CommonTypes";
+declare type BrowserOrWorkerUploadSource = UploadSourceProcessedBrowser | UploadSourceProcessedWorker;
+/**
+ * The "browser" and "worker" runtimes support the same input types, but the former uses XHR and the latter uses Fetch.
+ */
+export declare abstract class UploadManagerBrowserWorkerBase extends UploadManagerBase<BrowserOrWorkerUploadSource, undefined> {
+    protected processUploadSource(data: UploadSource): BrowserOrWorkerUploadSource;
+    protected getPreUploadInfoPartial(_request: UploadManagerParams, data: BrowserOrWorkerUploadSource): Partial<PreUploadInfo> & {
+        size: number;
+    };
+    protected preUpload(_source: BrowserOrWorkerUploadSource): undefined;
+    protected postUpload(_init: undefined): Promise<void>;
+    protected getRequestBody(part: UploadPart, blob: BrowserOrWorkerUploadSource): Blob | ArrayBuffer;
+}
+export {};

package/dist/types/private/UploadManagerFetchUtils.d.ts

@@ -0,0 +1,8 @@
+import { BytescaleApiClientConfig, UploadPart } from "../public/shared";
+import { AddCancellationHandler } from "./model/AddCancellationHandler";
+export declare class UploadManagerFetchUtils {
+    static doPutUploadPart(config: BytescaleApiClientConfig, part: UploadPart, content: BodyInit, contentLength: number, addCancellationHandler: AddCancellationHandler): Promise<{
+        etag: string | undefined;
+        status: number;
+    }>;
+}

package/dist/types/private/model/AuthManagerInterface.d.ts

@@ -1,3 +1,24 @@
+import { BytescaleApiClientConfig } from "../../public/shared";
+export interface BeginAuthSessionParams {
+    /**
+     * The account ID to authorize requests for.
+     */
+    accountId: string;
+    /**
+     * Headers to send to your backend API.
+     *
+     * IMPORTANT: do not call 'AuthManager.beginAuthSession' or 'AuthManager.endAuthSession' inside this callback, as this will cause a deadlock.
+     */
+    authHeaders: () => Promise<Record<string, string>>;
+    /**
+     * The fully-qualified URL for your backend API's auth endpoint.
+     */
+    authUrl: string;
+    /**
+     * Optional configuration.
+     */
+    options?: Pick<BytescaleApiClientConfig, "fetchApi" | "cdnUrl">;
+}
 export interface AuthManagerInterface {
     /**
      * Begins an authenticated Bytescale API and Bytescale CDN session.
@@ -21,12 +42,8 @@ export interface AuthManagerInterface {
      * 2) The JWT will be saved to a cookie scoped to the Bytescale CDN. This allows the user to view private files via the URL in the browser, including <img> elements on the page that reference private images, etc.
      *
      * 3) The JWT will also be added as a request header via 'authorization-token' to all Bytescale API requests made via this SDK. This allows the user to upload private files and perform administrative operations permitted by the JWT, such as deleting files, etc.
-     *
-     * @param authUrl The fully-qualified URL for your backend API's auth endpoint.
-     * @param authHeaders Headers to send to your backend API.
-     *                    IMPORTANT: do not call '*AuthSession' inside this callback, as this will cause a deadlock.
      */
-    beginAuthSession: (authUrl: string, authHeaders: () => Promise<Record<string, string>>) => Promise<void>;
+    beginAuthSession: (params: BeginAuthSessionParams) => Promise<void>;
     /**
      * Ends an authenticated Bytescale API and Bytescale CDN session.
      *

package/dist/types/private/model/AuthSession.d.ts

@@ -1,7 +1,7 @@
+import { BeginAuthSessionParams } from "./AuthManagerInterface";
 export interface AuthSession {
     accessToken: string | undefined;
     accessTokenRefreshHandle: number | undefined;
-    authHeaders: () => Promise<Record<string, string>>;
-    authUrl: string;
     isActive: boolean;
+    params: BeginAuthSessionParams;
 }

package/dist/types/private/model/OnPartProgress.d.ts

@@ -1 +1 @@
-export declare type OnPartProgress = (bytesSentDelta: number) => void;
+export declare type OnPartProgress = (bytesSentTotalForPart: number) => void;

package/dist/types/private/model/UploadSourceProcessed.d.ts

@@ -9,10 +9,15 @@ export interface UploadSourceBuffer {
     type: "Buffer";
     value: Buffer;
 }
+export interface UploadSourceArrayBuffer {
+    type: "ArrayBuffer";
+    value: ArrayBuffer;
+}
 export interface UploadSourceStream {
     type: "Stream";
     value: NodeChunkedStream;
 }
-export declare type UploadSourceProcessedIsomorphic = UploadSourceBlob;
+export declare type UploadSourceProcessedIsomorphic = UploadSourceBlob | UploadSourceArrayBuffer;
 export declare type UploadSourceProcessedBrowser = UploadSourceProcessedIsomorphic;
+export declare type UploadSourceProcessedWorker = UploadSourceProcessedIsomorphic;
 export declare type UploadSourceProcessedNode = UploadSourceStream | UploadSourceBuffer | UploadSourceProcessedIsomorphic;

package/dist/types/public/browser/AuthManagerBrowser.d.ts

@@ -1,20 +1,25 @@
-import { AuthManagerInterface } from "../../private/model/AuthManagerInterface";
-import { BaseAPI, BytescaleApiClientConfig } from "../shared/generated";
-export declare class AuthManager extends BaseAPI implements AuthManagerInterface {
-    private readonly accessTokenUrl;
+import { AuthManagerInterface, BeginAuthSessionParams } from "../../private/model/AuthManagerInterface";
+declare class AuthManagerImpl implements AuthManagerInterface {
     private readonly authSessionMutex;
     private readonly contentType;
     private readonly contentTypeJson;
     private readonly contentTypeText;
     private readonly minJwtTtlSeconds;
+    private readonly maxJwtTtlSeconds;
     private readonly retryAuthAfterErrorSeconds;
     private readonly refreshBeforeExpirySeconds;
-    constructor(config: BytescaleApiClientConfig);
+    constructor();
     isAuthSessionActive(): boolean;
-    beginAuthSession(authUrl: string, authHeaders: () => Promise<Record<string, string>>): Promise<void>;
+    beginAuthSession(params: BeginAuthSessionParams): Promise<void>;
     endAuthSession(): Promise<void>;
     private refreshAccessToken;
+    private getAccessTokenUrl;
     private deleteAccessToken;
     private setAccessToken;
     private getAccessToken;
 }
+/**
+ * Alternative way of implementing a static class (i.e. all methods static). We do this so we can use a interface on the class (interfaces can't define static methods).
+ */
+export declare const AuthManager: AuthManagerImpl;
+export {};

package/dist/types/public/browser/UploadManagerBrowser.d.ts

@@ -1,17 +1,8 @@
-import { UploadManagerBase } from "../../private/UploadManagerBase";
 import { UploadSourceProcessedBrowser } from "../../private/model/UploadSourceProcessed";
-import { PreUploadInfo } from "../../private/model/PreUploadInfo";
 import { UploadPart } from "../shared/generated";
 import { PutUploadPartResult } from "../../private/model/PutUploadPartResult";
 import { AddCancellationHandler } from "../../private/model/AddCancellationHandler";
-import { UploadManagerParams, UploadSource } from "../shared/CommonTypes";
-export declare class UploadManager extends UploadManagerBase<UploadSourceProcessedBrowser, undefined> {
-    protected processUploadSource(data: UploadSource): UploadSourceProcessedBrowser;
-    protected getPreUploadInfoPartial(_request: UploadManagerParams, data: UploadSourceProcessedBrowser): Partial<PreUploadInfo> & {
-        size: number;
-    };
-    protected preUpload(_source: UploadSourceProcessedBrowser): undefined;
-    protected postUpload(_init: undefined): Promise<void>;
-    protected doPutUploadPart(part: UploadPart, contentLength: number, source: UploadSourceProcessedBrowser, onProgress: (bytesSentDelta: number) => void, addCancellationHandler: AddCancellationHandler): Promise<PutUploadPartResult>;
-    private getRequestBody;
+import { UploadManagerBrowserWorkerBase } from "../../private/UploadManagerBrowserWorkerBase";
+export declare class UploadManager extends UploadManagerBrowserWorkerBase {
+    protected doPutUploadPart(part: UploadPart, _contentLength: number, source: UploadSourceProcessedBrowser, onProgress: (bytesSentDelta: number) => void, addCancellationHandler: AddCancellationHandler): Promise<PutUploadPartResult>;
 }

package/dist/types/public/node/AuthManagerNode.d.ts

@@ -1,6 +1,11 @@
-import { AuthManagerInterface } from "../../private/model/AuthManagerInterface";
-export declare class AuthManager implements AuthManagerInterface {
-    beginAuthSession(_authUrl: string, _authHeaders: () => Promise<Record<string, string>>): Promise<void>;
+import { AuthManagerInterface, BeginAuthSessionParams } from "../../private/model/AuthManagerInterface";
+declare class AuthManagerImpl implements AuthManagerInterface {
+    beginAuthSession(_params: BeginAuthSessionParams): Promise<void>;
     endAuthSession(): Promise<void>;
     isAuthSessionActive(): boolean;
 }
+/**
+ * Alternative way of implementing a static class (i.e. all methods static). We do this so we can use a interface on the class (interfaces can't define static methods).
+ */
+export declare const AuthManager: AuthManagerImpl;
+export {};

package/dist/types/public/shared/CommonTypes.d.ts

@@ -20,7 +20,6 @@ export interface UploadProgress {
 }
 export declare type UploadSource = NodeJS.ReadableStream | BlobLike | Buffer | string;
 export interface UploadManagerParams extends Omit<BeginMultipartUploadRequest, "size" | "protocol"> {
-    accountId: string;
     cancellationToken?: CancellationToken;
     data: UploadSource;
     maxConcurrentUploadParts?: number;

package/dist/types/public/shared/UrlBuilder.d.ts

@@ -1,7 +1,5 @@
-import { UrlBuilderConfig, UrlBuilderParams } from "./UrlBuilderTypes";
+import { UrlBuilderParams } from "./UrlBuilderTypes";
 export declare class UrlBuilder {
-    private readonly cdnUrl;
-    constructor(config?: UrlBuilderConfig);
     /**
      * Builds a URL to either a raw file or a transformed file.
      *
@@ -21,12 +19,13 @@ export declare class UrlBuilder {
      *
      *   new UrlBuilder().url({ accountId: "1234abc", filePath: "/example.jpg", options: { transformation: { type: "preset", preset: "thumbnail" } } })
      */
-    url(params: UrlBuilderParams): string;
-    private raw;
-    private transformation;
-    private getBaseUrl;
-    private getCommonQueryParams;
-    private makeQueryParams;
-    private getTransformationParams;
-    private addQueryParams;
+    static url(params: UrlBuilderParams): string;
+    private static raw;
+    private static transformation;
+    private static getBaseUrl;
+    private static getCommonTransformationQueryParams;
+    private static getCommonQueryParams;
+    private static makeQueryParams;
+    private static getTransformationParams;
+    private static addQueryParams;
 }

package/dist/types/public/shared/UrlBuilderTypes.d.ts

@@ -4,12 +4,6 @@
 export declare const UrlBuilderTypesNoOp = false;
 export declare type ParameterGroup = Record<string, string | number | boolean | undefined | null>;
 export declare type KeyValuePair = [string, string];
-export interface UrlBuilderConfig {
-    /**
-     * The base URL of the Bytescale CDN.
-     */
-    cdnUrl?: string;
-}
 export interface UrlBuilderParams {
     /**
      * The account that manages the file.
@@ -26,7 +20,10 @@ export interface UrlBuilderParams {
      */
     options?: UrlBuilderOptions;
 }
-export interface UrlBuilderOptions {
+export declare type UrlBuilderOptions = UrlBuilderOptionsRaw | UrlBuilderTransformationOptions;
+export declare type UrlBuilderTransformationOptions = UrlBuilderTransformationApiOptions | UrlBuilderOptionsPreset;
+export declare type UrlBuilderTransformationApiOptions = UrlBuilderOptionsImage | UrlBuilderOptionsVideo | UrlBuilderOptionsAudio | UrlBuilderOptionsArchive;
+export interface UrlBuilderOptionsBase {
     /**
      * Set to 'true' to download a private file. Requires an active auth session. See AuthManager.beginAuthSession.
      *
@@ -57,7 +54,6 @@ export interface UrlBuilderOptions {
      * Default: false
      */
     forceDownloadPrompt?: boolean;
-    transformation?: UrlBuilderParamsTransformation;
     /**
      * Downloads the latest version of your file (if you have overwritten it) when added to the URL with a unique value.
      *
@@ -67,48 +63,55 @@ export interface UrlBuilderOptions {
      */
     version?: string;
 }
-export declare type UrlBuilderParamsTransformation = UrlBuilderParamsTransformationPreset | UrlBuilderParamsImageTransformation | UrlBuilderParamsVideoTransformation | UrlBuilderParamsAudioTransformation | UrlBuilderParamsArchiveTransformation;
-export interface UrlBuilderParamsTransformationOptions {
+export interface UrlBuilderOptionsRaw extends UrlBuilderOptionsBase {
+    transformation?: undefined;
+}
+export interface UrlBuilderOptionsImage extends UrlBuilderOptionsTransformationApi<ParameterGroup> {
     /**
-     * The transformation artifact to download.
-     *
-     * Some transformations produce multiple files. The 'artifact' parameter is used to select which file to download.
-     *
-     * Must begin with: "/"
+     * Set to "image" to use Bytescale's Image Processing API:
      *
-     * Default: "/"
+     * https://www.bytescale.com/docs/image-processing-api
      */
-    artifact?: string;
+    transformation: "image";
+}
+export interface UrlBuilderOptionsVideo extends UrlBuilderOptionsTransformationApi<ParameterGroup> {
     /**
-     * Specifies whether to permanently cache the transformed result in the Bytescale CDN.
-     *
-     * Permanently cached files can be deleted via a manual action in the Bytescale Dashboard.
-     *
-     * When cache=false this parameter is automatically set to false.
-     *
-     * When cachePermanently="auto" the permanent cache will only be used for files that take more than 1000ms to process.
-     *
-     * When the permanent cache is used, approximately 200ms of latency is added to the initial request. Thereafter, files will be served from the Bytescale CDN's edge cache or permanent cache, so will have minimal latency.
+     * Set to "video" to use Bytescale's Video Processing API:
      *
-     * Default: Please refer to your account's default cache settings in the Bytescale Dashboard.
+     * https://www.bytescale.com/docs/video-processing-api
      */
-    cachePermanently?: "auto" | boolean;
+    transformation: "video";
+}
+export interface UrlBuilderOptionsAudio extends UrlBuilderOptionsTransformationApi<ParameterGroup> {
     /**
-     * Set to true to return transformed files over 6MB in the initial HTTP response.
+     * Set to "audio" to use Bytescale's Audio Processing API:
      *
-     * By default, transformations that produce files larger than 6MB require a subsequent HTTP request to return the result: the initial HTTP request will process the file and return a JSON result instructing the requester the transformation has been performed. All subsequent requests will return the transformed file. Enable this flag to ensure the transformed file is always returned in the initial response.
+     * https://www.bytescale.com/docs/audio-processing-api
+     */
+    transformation: "audio";
+}
+export interface UrlBuilderOptionsArchive extends UrlBuilderOptionsTransformationApi<ParameterGroup> {
+    /**
+     * Set to "archive" to use Bytescale's Archive Processing API:
      *
-     * Recommendation: set large=true only if you require transformation results over 6MB. A small amount of latency is incurred on edge cache misses when this flag is enabled. In general, we recommend adjusting your transformation parameters to keep files below this size, instead of enabling this flag.
+     * https://www.bytescale.com/docs/archive-processing-api
+     */
+    transformation: "archive";
+}
+export interface UrlBuilderOptionsPreset extends UrlBuilderOptionsTransformation {
+    transformation: "preset";
+    /**
+     * The name of the transformation preset, as displayed in the Bytescale Dashboard.
      *
-     * Default: false
+     * To specify transformation parameters on-the-fly, set "transformation" to a File Processing API (e.g. "image", "video", "audio"), and then use the "transformationParams" field to pass parameters to the File Processing API.
      */
-    large?: boolean;
+    transformationPreset: string;
 }
-export interface UrlBuilderParamsTransformationApiBase<T> {
+export interface UrlBuilderOptionsTransformationApi<T> extends UrlBuilderOptionsTransformation {
     /**
-     * Use the "params" field to pass parameters to the File Processing API.
+     * Use the "transformationParams" field to pass parameters to the File Processing API.
      *
-     * Use the "type" field to specify which File Processing API to use:
+     * Use the "transformation" field to specify which File Processing API to use:
      *
      * - https://www.bytescale.com/docs/image-processing-api
      * - https://www.bytescale.com/docs/video-processing-api
@@ -122,52 +125,43 @@ export interface UrlBuilderParamsTransformationApiBase<T> {
      * Order is sensitive both within and across parameter groups for certain transformation operations, please consult
      * the documentation for the File Processing API you are using (see links above).
      */
-    params?: (T & UrlBuilderParamsTransformationOptions) | Array<T & UrlBuilderParamsTransformationOptions>;
+    transformationParams?: T | T[];
 }
-export interface UrlBuilderParamsTransformationPreset {
-    params?: UrlBuilderParamsTransformationOptions;
+export interface UrlBuilderOptionsTransformation extends UrlBuilderOptionsBase {
     /**
-     * The name of the transformation preset, as displayed in the Bytescale Dashboard.
+     * The transformation artifact to download.
      *
-     * To specify transformation parameters on-the-fly, set "type" to a File Processing API (e.g. "image", "video", "audio"), and then use the "params" field to pass parameters to the File Processing API.
-     */
-    preset: string;
-    /**
-     * Use a transformation preset that was created in the Bytescale Dashboard.
+     * Some transformations produce multiple files. The 'artifact' parameter is used to select which file to download.
      *
-     * To specify transformation parameters on-the-fly, set "type" to a File Processing API (e.g. "image", "video", "audio"), and then use the "params" field to pass parameters to the File Processing API.
-     */
-    type: "preset";
-}
-export interface UrlBuilderParamsImageTransformation extends UrlBuilderParamsTransformationApiBase<ParameterGroup> {
-    /**
-     * Set to "image" to use Bytescale's Image Processing API:
+     * Must begin with: "/"
      *
-     * https://www.bytescale.com/docs/image-processing-api
+     * Default: "/"
      */
-    type: "image";
-}
-export interface UrlBuilderParamsVideoTransformation extends UrlBuilderParamsTransformationApiBase<ParameterGroup> {
+    artifact?: string;
     /**
-     * Set to "video" to use Bytescale's Video Processing API:
+     * Specifies whether to permanently cache the transformed result in the Bytescale CDN.
      *
-     * https://www.bytescale.com/docs/video-processing-api
-     */
-    type: "video";
-}
-export interface UrlBuilderParamsAudioTransformation extends UrlBuilderParamsTransformationApiBase<ParameterGroup> {
-    /**
-     * Set to "audio" to use Bytescale's Audio Processing API:
+     * Permanently cached files can be deleted via a manual action in the Bytescale Dashboard.
      *
-     * https://www.bytescale.com/docs/audio-processing-api
+     * When cache=false this parameter is automatically set to false.
+     *
+     * When cachePermanently="auto" the permanent cache will only be used for files that take more than 1000ms to process.
+     *
+     * When the permanent cache is used, approximately 200ms of latency is added to the initial request. Thereafter, files will be served from the Bytescale CDN's edge cache or permanent cache, so will have minimal latency.
+     *
+     * Default: Please refer to your account's default cache settings in the Bytescale Dashboard.
      */
-    type: "audio";
-}
-export interface UrlBuilderParamsArchiveTransformation extends UrlBuilderParamsTransformationApiBase<ParameterGroup> {
+    cachePermanently?: "auto" | boolean;
     /**
-     * Set to "archive" to use Bytescale's Archive Processing API:
+     * Only set this parameter to `true` if you expect the HTTP response body for the transformation request to be over 6MB.
      *
-     * https://www.bytescale.com/docs/archive-processing-api
+     * We recommend leaving this parameter unset (so it defaults to `false`) and controlling the HTTP response body size via transformation parameters. E.g. for Image Processing API requests, you can shrink the HTTP response body by reducing the output image's dimensions and/or quality.
+     *
+     * Setting this parameter to `true` will route the request via an alternative CDN path, which allows responses over 6MB, but incurs a ~200ms latency on all CDN edge cache misses for the URL.
+     *
+     * Setting this parameter to `false` (default) results in faster routing. If a response over 6MB is returned, the initial response will be a JSON error indicating the response was too large to return. All subsequent requests to the same URL will successfully return the transformed file (forever).
+     *
+     * Default: false
      */
-    type: "archive";
+    large?: boolean;
 }

package/dist/types/public/shared/generated/apis/FileApi.d.ts

@@ -30,8 +30,25 @@ export interface DeleteFileBatchOperationParams {
 export interface DownloadFileParams {
     accountId: string;
     filePath: string;
+    /**
+     * Specifies whether to cache the raw file in the Bytescale CDN.
+     *
+     * Default: true
+     */
     cache?: boolean;
+    /**
+     * Specifies the maximum amount of time, in seconds, the file will be cached on the user's device and in the Bytescale CDN's edge cache.
+     *
+     * Default: Please refer to your account's default cache settings in the Bytescale Dashboard.
+     */
     cacheTtl?: number;
+    /**
+     * Downloads the latest version of your file (if you have overwritten it) when added to the URL with a unique value.
+     *
+     *   The value of the `version` parameter can be anything, e.g. an incremental number, a timestamp, etc.
+     *
+     *   You only need to provide and update this value if/when you overwrite your file.
+     */
     version?: string;
 }
 export interface GetFileDetailsParams {
@@ -41,29 +58,113 @@ export interface GetFileDetailsParams {
 export interface ProcessFileParams {
     accountId: string;
     filePath: string;
+    /**
+     * The name of the File Processing API (e.g. "image", "video", "audio") or transformation preset (created in the Bytescale Dashboard) to use when processing the file.
+     */
     transformation: string;
+    /**
+     * Some transformations output multiple files, called artifacts.
+     *
+     * You can download each individual transformation artifact by specifying its path with this parameter
+     */
     artifact?: string;
+    /**
+     * Specifies whether to cache the transformed result.
+     *
+     * If set to `false` the transformation will be executed on every request.
+     *
+     * *Recommendation:* instead of disabling the cache, a more performant solution is to use the `version` parameter and to increment it each time you require an updated result.
+     *
+     * Default: true
+     */
     cache?: boolean;
+    /**
+     * Specifies whether to cache the transformed result in the Bytescale CDN perma-cache.
+     *
+     * Perma-caching works by storing your file permanently, or until a manual cache purge is performed.
+     *
+     * When `cache=false` this parameter is automatically set to `false`.
+     *
+     * When `cache_perm=auto` the perma-cache will only be used for files that take more than 1000ms to process.
+     *
+     * When the perma-cache is used, approximately 200ms of latency is added to the initial request. Thereafter, files will be served from the Bytescale CDN's edge cache or perma-cache, so will have minimal latency.
+     *
+     * Default: Please refer to your account's default cache settings in the Bytescale Dashboard.
+     */
     cachePerm?: ProcessFileCachePermEnum;
+    /**
+     * Specifies the maximum amount of time, in seconds, the transformed result will be cached on the user's device and in the Bytescale CDN's edge cache.
+     *
+     * If the file is perma-cached, then the file will not be reprocessed on edge cache misses.
+     *
+     * If the file is not perma-cached, then the file will be reprocessed on edge cache misses.
+     *
+     * For more information on perma-caching, see: `cache_perm`
+     *
+     * Default: Please refer to your account's default cache settings in the Bytescale Dashboard.
+     */
     cacheTtl?: number;
+    /**
+     * Only set this parameter to `true` if you expect the HTTP response body for the transformation request to be over 6MB.
+     *
+     * We recommend leaving this parameter unset (so it defaults to `false`) and controlling the HTTP response body size via transformation parameters. E.g. for Image Processing API requests, you can shrink the HTTP response body by reducing the output image's dimensions and/or quality.
+     *
+     * Setting this parameter to `true` will route the request via an alternative CDN path, which allows responses over 6MB, but incurs a ~200ms latency on all CDN edge cache misses for the URL.
+     *
+     * Setting this parameter to `false` (default) results in faster routing. If a response over 6MB is returned, the initial response will be a JSON error indicating the response was too large to return. All subsequent requests to the same URL will successfully return the transformed file (forever).
+     *
+     * Default: `false`
+     */
     large?: boolean;
+    /**
+     * Parameters to submit to the File Processing API (e.g. the Image Processing API).
+     *
+     * Please see the documentation for each File Processing API to determine which values can appear here:
+     *
+     * - https://www.bytescale.com/docs/image-processing-api
+     * - https://www.bytescale.com/docs/video-processing-api
+     * - https://www.bytescale.com/docs/audio-processing-api
+     * - https://www.bytescale.com/docs/archive-processing-api
+     */
     transformationParams?: {
         [key: string]: ProcessFileTransformationParamsParameterValue;
     };
+    /**
+     * Add this parameter and increment its value to force the file to be reprocessed.
+     *
+     * The Bytescale CDN caches files based on the full URL (including the querystring), meaning this parameter is useful when dealing with changes made to transformation presets. By contrast, File Processing APIs (like the Image Processing API) shouldn't ever require this parameter, since the URL/querystring naturally changes each time you adjust a parameter, causing a cache miss and the file to be reprocessed with the new querystring parameters.
+     *
+     * The value of the `version` parameter can be anything, e.g. an incremental number, a timestamp, etc.
+     *
+     * You only need to provide and update this value if/when you make changes to a transformation preset's settings.
+     */
     version?: string;
 }
 export interface ProcessFileAndSaveOperationParams {
     accountId: string;
     filePath: string;
+    /**
+     * The name of the File Processing API (e.g. "image", "video", "audio") or transformation preset (created in the Bytescale Dashboard) to use when processing the file.
+     */
     transformation: string;
+    /**
+     *
+     */
     processFileAndSaveRequest: ProcessFileAndSaveRequest;
+    /**
+     * Parameters to submit to the File Processing API (e.g. the Image Processing API).
+     *
+     * Please see the documentation for each File Processing API to determine which values can appear here:
+     *
+     * - https://www.bytescale.com/docs/image-processing-api
+     * - https://www.bytescale.com/docs/video-processing-api
+     * - https://www.bytescale.com/docs/audio-processing-api
+     * - https://www.bytescale.com/docs/archive-processing-api
+     */
     transformationParams?: {
         [key: string]: ProcessFileTransformationParamsParameterValue;
     };
 }
-/**
- *
- */
 export declare class FileApi extends runtime.BaseAPI {
     /**
      * Copies a file synchronously.