@vercel/blob/dist/index.d.ts

The Vercel Blob JavaScript API client

import { f as CommonCreateBlobOptions, W as WithUploadProgress, g as BlobError, a as BlobCommandOptions, B as BlobAccessType, b as Part, h as CompleteMultipartUploadCommandOptions, P as PutBlobResult, c as PutBody, U as UploadPartCommandOptions } from './create-folder-D-Qslm5_.js';
export { i as CreateFolderCommandOptions, j as CreateFolderResult, O as OnUploadProgressCallback, k as PartInput, l as UploadProgressEvent, e as createFolder, m as getDownloadUrl } from './create-folder-D-Qslm5_.js';
import { Headers } from 'undici';
import 'stream';

interface PutCommandOptions extends CommonCreateBlobOptions, WithUploadProgress {
    /**
     * Whether to use multipart upload. Use this when uploading large files. It will split the file into multiple parts, upload them in parallel and retry failed parts.
     * @defaultvalue false
     */
    multipart?: boolean;
}

declare class BlobAccessError extends BlobError {
    constructor();
}
declare class BlobContentTypeNotAllowedError extends BlobError {
    constructor(message: string);
}
declare class BlobPathnameMismatchError extends BlobError {
    constructor(message: string);
}
declare class BlobClientTokenExpiredError extends BlobError {
    constructor();
}
declare class BlobFileTooLargeError extends BlobError {
    constructor(message: string);
}
declare class BlobStoreNotFoundError extends BlobError {
    constructor();
}
declare class BlobStoreSuspendedError extends BlobError {
    constructor();
}
declare class BlobUnknownError extends BlobError {
    constructor();
}
declare class BlobNotFoundError extends BlobError {
    constructor();
}
declare class BlobServiceNotAvailable extends BlobError {
    constructor();
}
declare class BlobServiceRateLimited extends BlobError {
    readonly retryAfter: number;
    constructor(seconds?: number);
}
declare class BlobRequestAbortedError extends BlobError {
    constructor();
}
declare class BlobPreconditionFailedError extends BlobError {
    constructor();
}

interface DeleteCommandOptions extends BlobCommandOptions {
    /**
     * Only delete the blob if its current ETag matches this value.
     * Use this for optimistic concurrency control to prevent deleting a blob that has been modified since it was last read.
     * If the ETag doesn't match, a `BlobPreconditionFailedError` will be thrown.
     * Can only be used when deleting a single URL.
     */
    ifMatch?: string;
}
/**
 * Deletes one or multiple blobs from your store.
 * Detailed documentation can be found here: https://vercel.com/docs/vercel-blob/using-blob-sdk#delete-a-blob
 *
 * @param urlOrPathname - Blob url (or pathname) to delete. You can pass either a single value or an array of values. You can only delete blobs that are located in a store, that your 'BLOB_READ_WRITE_TOKEN' has access to.
 * @param options - Additional options for the request.
 */
declare function del(urlOrPathname: string[] | string, options?: DeleteCommandOptions): Promise<void>;

/**
 * Result of the head method containing metadata about a blob.
 */
interface HeadBlobResult {
    /**
     * The size of the blob in bytes.
     */
    size: number;
    /**
     * The date when the blob was uploaded.
     */
    uploadedAt: Date;
    /**
     * The pathname of the blob within the store.
     */
    pathname: string;
    /**
     * The content type of the blob.
     */
    contentType: string;
    /**
     * The content disposition header value.
     */
    contentDisposition: string;
    /**
     * The URL of the blob.
     */
    url: string;
    /**
     * A URL that will cause browsers to download the file instead of displaying it inline.
     */
    downloadUrl: string;
    /**
     * The cache control header value.
     */
    cacheControl: string;
    /**
     * The ETag of the blob. Can be used with `ifMatch` for conditional writes.
     */
    etag: string;
}
/**
 * Fetches metadata of a blob object.
 * Detailed documentation can be found here: https://vercel.com/docs/vercel-blob/using-blob-sdk#get-blob-metadata
 *
 * @param urlOrPathname - Blob url or pathname to lookup.
 * @param options - Additional options for the request.
 */
declare function head(urlOrPathname: string, options?: BlobCommandOptions): Promise<HeadBlobResult>;

/**
 * Options for the get method.
 */
interface GetCommandOptions extends BlobCommandOptions {
    /**
     * Whether the blob is publicly accessible or private.
     * - 'public': The blob is publicly accessible via its URL.
     * - 'private': The blob requires authentication to access.
     */
    access: BlobAccessType;
    /**
     * Whether to allow the blob to be served from CDN cache.
     * When false, fetches directly from origin storage.
     * Only effective for private blobs (ignored for public blobs).
     * @defaultValue true
     */
    useCache?: boolean;
    /**
     * Only return the full response if the blob's ETag does not match this value.
     * When the ETag matches (blob unchanged), returns statusCode 304 with stream: null.
     * Use this to avoid re-downloading blobs the client already has cached.
     */
    ifNoneMatch?: string;
    /**
     * Advanced: Additional headers to include in the fetch request.
     * You probably don't need this. The authorization header is automatically set.
     */
    headers?: HeadersInit;
}
interface GetBlobResultBlobBase {
    url: string;
    downloadUrl: string;
    pathname: string;
    contentDisposition: string;
    cacheControl: string;
    uploadedAt: Date;
    etag: string;
}
/**
 * Result of the get method containing the stream and blob metadata.
 * Discriminated union on `statusCode`:
 * - `200`: Full response with stream and complete metadata.
 * - `304`: Not Modified. Stream is null, contentType and size are null.
 */
type GetBlobResult = {
    /** HTTP 200: Full response with stream and complete metadata. */
    statusCode: 200;
    /** The readable stream from the fetch response. */
    stream: ReadableStream<Uint8Array>;
    /** The raw headers from the fetch response. */
    headers: Headers;
    /** The blob metadata. */
    blob: GetBlobResultBlobBase & {
        contentType: string;
        size: number;
    };
} | {
    /** HTTP 304: Not Modified. The blob hasn't changed since the conditional request. */
    statusCode: 304;
    /** Null for 304 responses — no body is returned. */
    stream: null;
    /** The raw headers from the fetch response. */
    headers: Headers;
    /** The blob metadata (contentType and size are null on 304 responses). */
    blob: GetBlobResultBlobBase & {
        contentType: null;
        size: null;
    };
};
/**
 * Fetches blob content by URL or pathname.
 * - If a URL is provided, fetches the blob directly.
 * - If a pathname is provided, constructs the URL from the token's store ID.
 *
 * Returns a stream (no automatic buffering) and blob metadata.
 *
 * @example
 * ```ts
 * // Basic usage
 * const { stream, headers, blob } = await get('user123/avatar.png', { access: 'private' });
 *
 * // Bypass cache for private blobs (always fetch fresh from storage)
 * const { stream, headers, blob } = await get('user123/data.json', { access: 'private', useCache: false });
 * ```
 *
 * Detailed documentation can be found here: https://vercel.com/docs/vercel-blob/using-blob-sdk
 *
 * @param urlOrPathname - The URL or pathname of the blob to fetch.
 * @param options - Configuration options including:
 *   - access - (Required) Must be 'public' or 'private'. Determines the access level of the blob.
 *   - useCache - (Optional) When false, fetches directly from origin storage instead of CDN cache. Only effective for private blobs. Defaults to true.
 *   - token - (Optional) A string specifying the token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel.
 *   - abortSignal - (Optional) AbortSignal to cancel the operation.
 *   - headers - (Optional, advanced) Additional headers to include in the fetch request. You probably don't need this.
 * @returns A promise that resolves to { stream, blob } or null if not found.
 */
declare function get(urlOrPathname: string, options: GetCommandOptions): Promise<GetBlobResult | null>;

/**
 * Basic blob object information returned by the list method.
 */
interface ListBlobResultBlob {
    /**
     * The URL of the blob.
     */
    url: string;
    /**
     * A URL that will cause browsers to download the file instead of displaying it inline.
     */
    downloadUrl: string;
    /**
     * The pathname of the blob within the store.
     */
    pathname: string;
    /**
     * The size of the blob in bytes.
     */
    size: number;
    /**
     * The date when the blob was uploaded.
     */
    uploadedAt: Date;
    /**
     * The ETag of the blob. Can be used with `ifMatch` for conditional writes.
     */
    etag: string;
}
/**
 * Result of the list method in expanded mode (default).
 */
interface ListBlobResult {
    /**
     * Array of blob objects in the store.
     */
    blobs: ListBlobResultBlob[];
    /**
     * Pagination cursor for the next set of results, if hasMore is true.
     */
    cursor?: string;
    /**
     * Indicates if there are more results available.
     */
    hasMore: boolean;
}
/**
 * Result of the list method in folded mode.
 */
interface ListFoldedBlobResult extends ListBlobResult {
    /**
     * Array of folder paths in the store.
     */
    folders: string[];
}
/**
 * Options for the list method.
 */
interface ListCommandOptions<M extends 'expanded' | 'folded' | undefined = undefined> extends BlobCommandOptions {
    /**
     * The maximum number of blobs to return.
     * @defaultvalue 1000
     */
    limit?: number;
    /**
     * Filters the result to only include blobs that start with this prefix.
     * If used together with `mode: 'folded'`, make sure to include a trailing slash after the foldername.
     */
    prefix?: string;
    /**
     * The cursor to use for pagination. Can be obtained from the response of a previous `list` request.
     */
    cursor?: string;
    /**
     * Defines how the blobs are listed
     * - `expanded` the blobs property contains all blobs.
     * - `folded` the blobs property contains only the blobs at the root level of your store. Blobs that are located inside a folder get merged into a single entry in the folder response property.
     * @defaultvalue 'expanded'
     */
    mode?: M;
}
/**
 * @internal Type helper to determine the return type based on the mode parameter.
 */
type ListCommandResult<M extends 'expanded' | 'folded' | undefined = undefined> = M extends 'folded' ? ListFoldedBlobResult : ListBlobResult;
/**
 * Fetches a paginated list of blob objects from your store.
 *
 * @param options - Configuration options including:
 *   - token - (Optional) A string specifying the read-write token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel.
 *   - limit - (Optional) The maximum number of blobs to return. Defaults to 1000.
 *   - prefix - (Optional) Filters the result to only include blobs that start with this prefix. If used with mode: 'folded', include a trailing slash after the folder name.
 *   - cursor - (Optional) The cursor to use for pagination. Can be obtained from the response of a previous list request.
 *   - mode - (Optional) Defines how the blobs are listed. Can be 'expanded' (default) or 'folded'. In folded mode, blobs located inside a folder are merged into a single entry in the folders response property.
 *   - abortSignal - (Optional) AbortSignal to cancel the operation.
 * @returns A promise that resolves to an object containing:
 *   - blobs: An array of blob objects with size, uploadedAt, pathname, url, and downloadUrl properties
 *   - cursor: A string for pagination (if hasMore is true)
 *   - hasMore: A boolean indicating if there are more results available
 *   - folders: (Only in 'folded' mode) An array of folder paths
 */
declare function list<M extends 'expanded' | 'folded' | undefined = undefined>(options?: ListCommandOptions<M>): Promise<ListCommandResult<M>>;

type CopyCommandOptions = CommonCreateBlobOptions;
interface CopyBlobResult {
    url: string;
    downloadUrl: string;
    pathname: string;
    contentType: string;
    contentDisposition: string;
    /**
     * The ETag of the blob. Can be used with `ifMatch` for conditional writes.
     */
    etag: string;
}
/**
 * Copies a blob to another location in your store.
 * Detailed documentation can be found here: https://vercel.com/docs/vercel-blob/using-blob-sdk#copy-a-blob
 *
 * @param fromUrlOrPathname - The blob URL (or pathname) to copy. You can only copy blobs that are in the store, that your 'BLOB_READ_WRITE_TOKEN' has access to.
 * @param toPathname - The pathname to copy the blob to. This includes the filename.
 * @param options - Additional options. The copy method will not preserve any metadata configuration (e.g.: 'cacheControlMaxAge') of the source blob. If you want to copy the metadata, you need to define it here again.
 */
declare function copy(fromUrlOrPathname: string, toPathname: string, options: CopyCommandOptions): Promise<CopyBlobResult>;

/**
 * Uploads a blob into your store from your server.
 * Detailed documentation can be found here: https://vercel.com/docs/vercel-blob/using-blob-sdk#upload-a-blob
 *
 * If you want to upload from the browser directly, or if you're hitting Vercel upload limits, check out the documentation for client uploads: https://vercel.com/docs/vercel-blob/using-blob-sdk#client-uploads
 *
 * @param pathname - The pathname to upload the blob to, including the extension. This will influence the URL of your blob like https://$storeId.public.blob.vercel-storage.com/$pathname.
 * @param body - The content of your blob, can be a: string, File, Blob, Buffer or Stream. We support almost everything fetch supports: https://developer.mozilla.org/en-US/docs/Web/API/RequestInit#body.
 * @param options - Configuration options including:
 *   - access - (Required) Must be 'public' or 'private'. Public blobs are accessible via URL, private blobs require authentication.
 *   - addRandomSuffix - (Optional) A boolean specifying whether to add a random suffix to the pathname. It defaults to false. We recommend using this option to ensure there are no conflicts in your blob filenames.
 *   - allowOverwrite - (Optional) A boolean to allow overwriting blobs. By default an error will be thrown if you try to overwrite a blob by using the same pathname for multiple blobs.
 *   - contentType - (Optional) A string indicating the media type. By default, it's extracted from the pathname's extension.
 *   - cacheControlMaxAge - (Optional) A number in seconds to configure how long Blobs are cached. Defaults to one month. Cannot be set to a value lower than 1 minute.
 *   - token - (Optional) A string specifying the token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel.
 *   - multipart - (Optional) Whether to use multipart upload for large files. It will split the file into multiple parts, upload them in parallel and retry failed parts.
 *   - abortSignal - (Optional) AbortSignal to cancel the operation.
 *   - onUploadProgress - (Optional) Callback to track upload progress: onUploadProgress(\{loaded: number, total: number, percentage: number\})
 * @returns A promise that resolves to the blob information, including pathname, contentType, contentDisposition, url, and downloadUrl.
 */
declare const put: (pathname: string, body: PutBody, optionsInput: PutCommandOptions) => Promise<PutBlobResult>;

/**
 * Creates a multipart upload. This is the first step in the manual multipart upload process.
 *
 * @param pathname - A string specifying the path inside the blob store. This will be the base value of the return URL and includes the filename and extension.
 * @param options - Configuration options including:
 *   - access - (Required) Must be 'public' or 'private'. Public blobs are accessible via URL, private blobs require authentication.
 *   - addRandomSuffix - (Optional) A boolean specifying whether to add a random suffix to the pathname. It defaults to true.
 *   - allowOverwrite - (Optional) A boolean to allow overwriting blobs. By default an error will be thrown if you try to overwrite a blob by using the same pathname for multiple blobs.
 *   - contentType - (Optional) The media type for the file. If not specified, it's derived from the file extension. Falls back to application/octet-stream when no extension exists or can't be matched.
 *   - cacheControlMaxAge - (Optional) A number in seconds to configure the edge and browser cache. Defaults to one month.
 *   - token - (Optional) A string specifying the token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel.
 *   - abortSignal - (Optional) AbortSignal to cancel the operation.
 * @returns A promise that resolves to an object containing:
 *   - key: A string that identifies the blob object.
 *   - uploadId: A string that identifies the multipart upload. Both are needed for subsequent uploadPart calls.
 */
declare const createMultipartUpload: (pathname: string, optionsInput: CommonCreateBlobOptions) => Promise<{
    key: string;
    uploadId: string;
}>;
/**
 * Creates a multipart uploader that simplifies the multipart upload process.
 * This is a wrapper around the manual multipart upload process that provides a more convenient API.
 *
 * @param pathname - A string specifying the path inside the blob store. This will be the base value of the return URL and includes the filename and extension.
 * @param options - Configuration options including:
 *   - access - (Required) Must be 'public' or 'private'. Public blobs are accessible via URL, private blobs require authentication.
 *   - addRandomSuffix - (Optional) A boolean specifying whether to add a random suffix to the pathname. It defaults to true.
 *   - allowOverwrite - (Optional) A boolean to allow overwriting blobs. By default an error will be thrown if you try to overwrite a blob by using the same pathname for multiple blobs.
 *   - contentType - (Optional) The media type for the file. If not specified, it's derived from the file extension. Falls back to application/octet-stream when no extension exists or can't be matched.
 *   - cacheControlMaxAge - (Optional) A number in seconds to configure the edge and browser cache. Defaults to one month.
 *   - token - (Optional) A string specifying the token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel.
 *   - abortSignal - (Optional) AbortSignal to cancel the operation.
 * @returns A promise that resolves to an uploader object with the following properties and methods:
 *   - key: A string that identifies the blob object.
 *   - uploadId: A string that identifies the multipart upload.
 *   - uploadPart: A method to upload a part of the file.
 *   - complete: A method to complete the multipart upload process.
 */
declare const createMultipartUploader: (pathname: string, optionsInput: CommonCreateBlobOptions) => Promise<{
    key: string;
    uploadId: string;
    uploadPart(partNumber: number, body: PutBody): Promise<{
        etag: string;
        partNumber: number;
    }>;
    complete(parts: Part[]): Promise<PutBlobResult>;
}>;

/**
 * Uploads a part of a multipart upload.
 * Used as part of the manual multipart upload process.
 *
 * @param pathname - Same value as the pathname parameter passed to createMultipartUpload. This will influence the final URL of your blob.
 * @param body - A blob object as ReadableStream, String, ArrayBuffer or Blob based on these supported body types. Each part must be a minimum of 5MB, except the last one which can be smaller.
 * @param options - Configuration options including:
 *   - access - (Required) Must be 'public' or 'private'. Public blobs are accessible via URL, private blobs require authentication.
 *   - uploadId - (Required) A string returned from createMultipartUpload which identifies the multipart upload.
 *   - key - (Required) A string returned from createMultipartUpload which identifies the blob object.
 *   - partNumber - (Required) A number identifying which part is uploaded (1-based index).
 *   - contentType - (Optional) The media type for the blob. By default, it's derived from the pathname.
 *   - token - (Optional) A string specifying the token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel.
 *   - addRandomSuffix - (Optional) A boolean specifying whether to add a random suffix to the pathname.
 *   - allowOverwrite - (Optional) A boolean to allow overwriting blobs.
 *   - cacheControlMaxAge - (Optional) A number in seconds to configure how long Blobs are cached.
 *   - abortSignal - (Optional) AbortSignal to cancel the running request.
 *   - onUploadProgress - (Optional) Callback to track upload progress: onUploadProgress(\{loaded: number, total: number, percentage: number\})
 * @returns A promise that resolves to the uploaded part information containing etag and partNumber, which will be needed for the completeMultipartUpload call.
 */
declare const uploadPart: (pathname: string, body: PutBody, optionsInput: UploadPartCommandOptions) => Promise<Part>;

/**
 * Completes a multipart upload by combining all uploaded parts.
 * This is the final step in the manual multipart upload process.
 *
 * @param pathname - Same value as the pathname parameter passed to createMultipartUpload.
 * @param parts - An array containing all the uploaded parts information from previous uploadPart calls. Each part must have properties etag and partNumber.
 * @param options - Configuration options including:
 *   - access - (Required) Must be 'public' or 'private'. Public blobs are accessible via URL, private blobs require authentication.
 *   - uploadId - (Required) A string returned from createMultipartUpload which identifies the multipart upload.
 *   - key - (Required) A string returned from createMultipartUpload which identifies the blob object.
 *   - contentType - (Optional) The media type for the file. If not specified, it's derived from the file extension.
 *   - token - (Optional) A string specifying the token to use when making requests. It defaults to process.env.BLOB_READ_WRITE_TOKEN when deployed on Vercel.
 *   - addRandomSuffix - (Optional) A boolean specifying whether to add a random suffix to the pathname. It defaults to true.
 *   - allowOverwrite - (Optional) A boolean to allow overwriting blobs.
 *   - cacheControlMaxAge - (Optional) A number in seconds to configure the edge and browser cache. Defaults to one month.
 *   - abortSignal - (Optional) AbortSignal to cancel the operation.
 * @returns A promise that resolves to the finalized blob information, including pathname, contentType, contentDisposition, url, and downloadUrl.
 */
declare const completeMultipartUpload: (pathname: string, parts: Part[], optionsInput: CompleteMultipartUploadCommandOptions) => Promise<PutBlobResult>;

export { BlobAccessError, BlobAccessType, BlobClientTokenExpiredError, BlobContentTypeNotAllowedError, BlobError, BlobFileTooLargeError, BlobNotFoundError, BlobPathnameMismatchError, BlobPreconditionFailedError, BlobRequestAbortedError, BlobServiceNotAvailable, BlobServiceRateLimited, BlobStoreNotFoundError, BlobStoreSuspendedError, BlobUnknownError, CompleteMultipartUploadCommandOptions, type CopyBlobResult, type CopyCommandOptions, type DeleteCommandOptions, type GetBlobResult, type GetCommandOptions, type HeadBlobResult, type ListBlobResult, type ListBlobResultBlob, type ListCommandOptions, type ListFoldedBlobResult, Part, PutBlobResult, type PutCommandOptions, UploadPartCommandOptions, completeMultipartUpload, copy, createMultipartUpload, createMultipartUploader, del, get, head, list, put, uploadPart };