feat(storage-vercel-blob): add allowOverwrite option (re-open of #16078)

[joeliomartini]

⚠️ This is a re-open of #16078. The original PR was auto-closed when I accidentally deleted my fork during a cleanup. GitHub's deleted-repos page indicates fork restoration requires support intervention (which I can't access on a free plan), so I've re-forked and re-pushed the same two commits to a new fork. cc @denolfe @rchlfryn

Summary

Adds a new allowOverwrite option to VercelBlobStorageOptions that passes through to all @vercel/blob put() calls — both server-side uploads (uploadFile.ts) and client upload token generation (getClientUploadRoute.ts).

Problem

When using clientUploads: true with addRandomSuffix: false, failed uploads leave orphan blobs in Vercel Blob storage. The blob is created successfully, but Payload's server-side processing (image size generation, generateFileData) can fail with a 400 error — leaving a blob without a corresponding Payload media record.

Subsequent uploads of the same filename then fail with:

Vercel Blob: This blob already exists, use allowOverwrite: true if you want to overwrite it.

This is particularly frustrating because the user has no way to clean up the orphan blob through the Payload admin — the media record was never created, so there's nothing to delete.

Related: #14709

Solution

The @vercel/blob SDK already supports allowOverwrite: true on put() calls, but the Payload adapter didn't expose this option. This PR adds it as a top-level config option:

vercelBlobStorage({
  token: process.env.BLOB_READ_WRITE_TOKEN,
  collections: { media: true },
  allowOverwrite: true, // new option
})

Changes

This is ported from #16078 to the current package structure (the storage-vercel-blob package was refactored in #16231 — handleUpload.ts is now uploadFile.ts, with a new adapter.ts wiring layer):

• index.ts: Added allowOverwrite to VercelBlobStorageOptions type with JSDoc, included in defaultUploadOptions, passed to both createVercelBlobAdapter and getClientUploadRoute, included in extraClientHandlerProps.
• uploadFile.ts: Added allowOverwrite to UploadFileArgs and passed it to the put() call for server-side uploads.
• adapter.ts: Added allowOverwrite to CreateVercelBlobAdapterArgs and passed it through to uploadFile.
• getClientUploadRoute.ts: Added allowOverwrite to Args and the onBeforeGenerateToken return value, so it flows through to the client upload token.
• client/VercelBlobClientUploadHandler.ts: Added allowOverwrite to VercelBlobClientUploadHandlerExtra for type consistency with addRandomSuffix.

Default behavior

allowOverwrite defaults to false, preserving the current behavior. No breaking changes.

Commits

The two commits mirror the original PR (the second was added in response to @rchlfryn's review feedback on #16078):

1. feat(storage-vercel-blob): add allowOverwrite option — main change
2. fix: pass allowOverwrite through to client handler — adds it to extraClientHandlerProps and the client handler's extra type for consistency