fix(@vercel/blob): Ensure all exported methods are correctly documented (#851)

* fix(@vercel/blob): Ensure all exported methods are correctly documented

* Update packages/blob/src/client.ts

Author: vvo

.changeset/giant-hoops-peel.md

@@ -0,0 +1,5 @@
+---
+'@vercel/blob': patch
+---
+
+Add correct documentation to all exported methods

packages/blob/src/client.ts

@@ -1,14 +1,48 @@
 import { requestApi } from './api';
 import type { BlobCommandOptions } from './helpers';
 
+/**
+ * Result of the head method containing metadata about a blob.
+ */
 export interface HeadBlobResult {
-  url: string;
-  downloadUrl: string;
+  /**
+   * 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;
 }
 

packages/blob/src/head.ts

@@ -21,10 +21,10 @@ export interface BlobCommandOptions {
   abortSignal?: AbortSignal;
 }
 
-// shared interface for put, copy and multipartUpload
+// shared interface for put, copy and multipart upload
 export interface CommonCreateBlobOptions extends BlobCommandOptions {
   /**
-   * Whether the blob should be publicly accessible.
+   * Whether the blob should be publicly accessible. The only currently allowed value is `public`.
    */
   access: 'public';
   /**
@@ -49,12 +49,29 @@ export interface CommonCreateBlobOptions extends BlobCommandOptions {
   cacheControlMaxAge?: number;
 }
 
+/**
+ * Event object passed to the onUploadProgress callback.
+ */
 export interface UploadProgressEvent {
+  /**
+   * The number of bytes uploaded.
+   */
   loaded: number;
+
+  /**
+   * The total number of bytes to upload.
+   */
   total: number;
+
+  /**
+   * The percentage of the upload that has been completed.
+   */
   percentage: number;
 }
 
+/**
+ * Callback type for tracking upload progress.
+ */
 export type OnUploadProgressCallback = (
   progressEvent: UploadProgressEvent,
 ) => void;
@@ -73,6 +90,9 @@ export type BlobRequest = ({
   onUploadProgress?: InternalOnUploadProgressCallback;
 }) => Promise<Response>;
 
+/**
+ * Interface for including upload progress tracking capabilities.
+ */
 export interface WithUploadProgress {
   /**
    * Callback to track the upload progress. You will receive an object with the following properties:
@@ -103,6 +123,14 @@ export class BlobError extends Error {
   }
 }
 
+/**
+ * Generates a download URL for a blob.
+ * The download URL includes a ?download=1 parameter which causes browsers to download
+ * the file instead of displaying it inline.
+ *
+ * @param blobUrl - The URL of the blob to generate a download URL for
+ * @returns A string containing the download URL with the download parameter appended
+ */
 export function getDownloadUrl(blobUrl: string): string {
   const url = new URL(blobUrl);
 

packages/blob/src/helpers.ts

@@ -41,11 +41,21 @@ export type { PutCommandOptions };
  * 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, check out the documentation forAclient uploads: https://vercel.com/docs/vercel-blob/using-blob-sdk#client-uploads
+ * 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 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 - Additional options like `token` or `contentType`.
+ * @param options - Configuration options including:
+ *   - access - (Required) Must be 'public' as blobs are publicly accessible.
+ *   - 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.
  */
 export const put = createPutMethod<PutCommandOptions>({
   allowedOptions: [
@@ -85,6 +95,22 @@ export { copy } from './copy';
 // vercelBlob. completeMultipartUpload()
 // vercelBlob. createMultipartUploader()
 
+/**
+ * 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' as blobs are publicly accessible.
+ *   - 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 year.
+ *   - 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.
+ */
 export const createMultipartUpload =
   createCreateMultipartUploadMethod<CommonCreateBlobOptions>({
     allowedOptions: [
@@ -95,6 +121,25 @@ export const createMultipartUpload =
     ],
   });
 
+/**
+ * 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' as blobs are publicly accessible.
+ *   - 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 year.
+ *   - 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.
+ */
 export const createMultipartUploader =
   createCreateMultipartUploaderMethod<CommonCreateBlobOptions>({
     allowedOptions: [
@@ -106,6 +151,27 @@ export const createMultipartUploader =
   });
 
 export type { UploadPartCommandOptions };
+
+/**
+ * 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' as blobs are publicly accessible.
+ *   - 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.
+ */
 export const uploadPart = createUploadPartMethod<UploadPartCommandOptions>({
   allowedOptions: [
     'cacheControlMaxAge',
@@ -116,6 +182,25 @@ export const uploadPart = createUploadPartMethod<UploadPartCommandOptions>({
 });
 
 export type { CompleteMultipartUploadCommandOptions };
+
+/**
+ * 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' as blobs are publicly accessible.
+ *   - 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 year.
+ *   - abortSignal - (Optional) AbortSignal to cancel the operation.
+ * @returns A promise that resolves to the finalized blob information, including pathname, contentType, contentDisposition, url, and downloadUrl.
+ */
 export const completeMultipartUpload =
   createCompleteMultipartUploadMethod<CompleteMultipartUploadCommandOptions>({
     allowedOptions: [