@humaan/payload-storage-imagekit 2.9.1 → 3.0.0-canary.1

package/README.md

@@ -21,8 +21,26 @@ This plugin integrates `@payloadcms/plugin-cloud-storage` with ImageKit and prov
 pnpm add @humaan/payload-storage-imagekit
 ```
 
-Payload `3.90.1` or newer is required. Use matching versions of `payload` and
-`@payloadcms/plugin-cloud-storage`.
+This branch targets Payload `4.0.0-beta.1`. Use that exact version of `payload` and
+`@payloadcms/plugin-cloud-storage`. Node.js >=24.15.0 is required.
+
+### Maintainer releases
+
+In **Actions → Start release**, set `release_branch` to the branch to release from
+(default: `main`). The version/changelog PR targets that branch. Stable `2.x`
+releases continue from `main`; for Payload v4, select `feat/payload-v4-beta`,
+`release_type: custom`, and `custom_version: 3.0.0-canary.0` (increment the canary
+number for subsequent releases). The v4 feature PR does not need to merge.
+
+Non-main releases must be prereleases. `canary` versions publish under the npm
+`canary` tag without changing `latest`, after the release commit passes push CI.
+For a publication dry run or receipt-based recovery, choose the same branch in
+**Publish release (automatic)**. Recovery still requires the original receipt run
+ID and the `publish` confirmation.
+
+The shared `humaan/actions@v2` update must be deployed first, and these caller
+workflow changes must be present on the selected branch. The `release` environment
+must permit that branch under its deployment policy.
 
 ## Usage
 
@@ -38,7 +56,7 @@ export default buildConfig({
       fields: [],
     },
   ],
-  plugins: [
+  storage: [
     imagekitStorage({
       clientUploads: true,
       folder: '/payload-uploads',
@@ -67,9 +85,59 @@ export default buildConfig({
 - `signedUrlExpiresIn` (optional): expiry in seconds for the signed URLs generated for [private](#private-files) collections. Defaults to `900` (15 minutes). Signed URLs are generated fresh on every request, so a short window is safe.
 - `enabled` (optional): enable / disable plugin
 - `focalPoint` (optional): broad default for Payload's native focal-point picker (`upload.focalPoint`) on every configured collection. Focal points are disabled by default for configured collections, so prefer the per-collection `collections.<slug>.focalPoint` option for mixed upload collections, e.g. enable it for `media` and leave it off for `documents`. When `true`, editors can place a focal point and `focalX`/`focalY` (0–100) are stored on each doc for focal-aware cropping at render time. A collection's own `upload.focalPoint` still takes precedence.
-- `alwaysInsertFields` (optional): pass-through to cloud storage plugin
 - `disablePayloadAccessControl` (optional): pass-through to cloud storage plugin. It cannot be enabled for private collections or collections that can store SVG/XML, because those files require Payload's file route for signing or Content Security Policy headers. To use this option, every configured collection must have a MIME allow list that excludes XML-family types.
 
+## Payload 4 migration / local development
+
+These compatibility changes do not bump the package version or publish a release.
+A custom canary can be released separately. Build a local snapshot with
+`pnpm pack --out local-canary.tgz`, then reference that archive from the consuming
+app with a `file:` dependency. Repack and update the dependency after edits.
+
+Adapters are now registered in `config.storage`. Direct uploads use the shared
+`POST /api/upload-instructions`, the `imagekit` dispatch handler, and Payload's
+signed `uploadReference`. The old `/imagekit-upload-auth` endpoint and
+`clientUploadContext` completion protocol are removed.
+
+Each new source file is stored as `<prefix>/<objectKey>/<name>-original.ext`.
+Payload manages originals, current representations, archived revisions, and
+rollback cleanup through the adapter's copy/delete capabilities. XML-family files
+remain server-mediated. Existing v3 records without `original`/`_objectKey`,
+including records with missing or slash-prefixed prefixes, remain readable.
+
+The browser still reauthorizes mislabeled raster images using content-detected
+filename/MIME hints; the server independently validates provider metadata and bytes.
+
+After a provider-direct upload, the browser calls the adapter's completion endpoint
+(normally `POST /api/imagekit-upload-complete`) with the collection slug, ImageKit's
+returned `fileId`, and the original `signedReceipt`. The server checks access and
+the user-bound receipt, then verifies the provider's exact path, name, upload tag,
+privacy and MIME policy before recording the ID. Document admission retrieves the
+file by that ID and rechecks provider state and file contents. It does not depend
+on ImageKit's asset listing becoming visible immediately after upload.
+
+Verified path-to-ID mappings use Payload's existing KV store (`payload-kv` with the
+default database adapter), remain available while the provider object exists, and
+are removed when the adapter deletes that object. Server uploads and managed copies
+also record their returned IDs, so immediate rollback/deletion does not depend on
+listing visibility. A failed registry write triggers cleanup by the returned ID.
+If you configure a custom KV
+adapter, it must persist and share entries across the instances handling completion
+and document-save requests; a process-local cache is not sufficient for serverless
+or multi-instance deployments. No new credentials, custom collections, storage-path
+changes or content migration are required. Existing files and older/in-flight
+clients without a mapping retain the path-listing fallback. Custom direct-upload
+clients should call completion before saving their original Payload reference.
+
+Run `pnpm exec vitest run` for mock-provider REST/MongoDB, client transport, and
+folder-migration coverage. Live provider tests require explicitly configured
+`IMAGEKIT_INTEGRATION_*` credentials and are otherwise skipped. The integration
+suite was migrated from the removed v3 endpoint/receipt protocol to the v4 REST
+boundary; the obsolete context-only verification helper is no longer shipped.
+
+The folder migration utility covers current/legacy records; migrating every
+archived v4 representation between accounts needs a separate history-aware plan.
+
 ## Exports
 
 - `imagekitStorage` (primary)
@@ -89,9 +157,7 @@ export default buildConfig({
 Use the browser-safe `image` export in app image components to build ImageKit URLs from Payload upload data without importing the server plugin entry.
 
 ```ts
-import {
-  withImageKitTransformation,
-} from '@humaan/payload-storage-imagekit/image'
+import { withImageKitTransformation } from '@humaan/payload-storage-imagekit/image'
 
 const src = withImageKitTransformation(media.imagekit.url, {
   focalX: media.focalX,

package/dist/clientUploads.d.ts

@@ -1,20 +1,7 @@
-import type { ClientUploadContext } from '@payloadcms/plugin-cloud-storage/types';
-export declare const imageKitUploadAuthPath = "/imagekit-upload-auth";
-/**
- * @deprecated Provider metadata is verified server-side and is no longer accepted as upload
- * proof. This backwards-compatible shape remains exported for existing type consumers.
- */
-export type ImageKitClientUploadContext = {
-    fileId?: string;
-    filePath?: string;
-    fileType?: string;
-    mimeType?: string;
-    name?: string;
-    size?: number;
-    thumbnailUrl?: string;
-    url?: string;
-} & Partial<ClientUploadContext>;
-/** @deprecated The upload handler is configured internally by Payload 3.90.1. */
+import type { UploadReference } from '@payloadcms/plugin-cloud-storage/types';
+/** @deprecated Use Payload 4's UploadReference and UploadInstructions types. */
+export type ImageKitClientUploadContext = Partial<UploadReference>;
+/** @deprecated The upload handler is configured by the storage capability. */
 export type ImageKitUploadHandlerProps = {
     authPath: `/${string}`;
     collectionSlug: string;
@@ -22,20 +9,6 @@ export type ImageKitUploadHandlerProps = {
     isPrivate?: boolean;
     publicKey: string;
 };
-export type ImageKitReceiptContext = {
-    /** Legacy uploads stored beneath a per-upload folder. */
-    _objectKey?: string;
-    collectionSlug: string;
-    expectedMimeType: string;
-    expectedSize: number;
-    /** Present only after the server verifies the completed upload. */
-    fileId?: string;
-    filename: string;
-    isPrivate: boolean;
-    prefix: string;
-    /** Binds a pending authorization to the newly uploaded provider object. */
-    uploadTag?: string;
-};
 export type ImageKitUploadPayload = {
     checks: string;
     fileName: string;
@@ -45,13 +18,3 @@ export type ImageKitUploadPayload = {
     tags: string;
     useUniqueFileName: 'false';
 };
-export type ImageKitUploadAuthorization = {
-    clientUploadContext: ClientUploadContext;
-    filename: string;
-    token: string;
-    uploadPayload: ImageKitUploadPayload;
-};
-export type ImageKitUploadCompletion = {
-    clientUploadContext: ClientUploadContext;
-};
-export declare const isImageKitReceiptContext: (value: unknown) => value is ImageKitReceiptContext;

package/dist/clientUploads.js

@@ -1,10 +1,3 @@
-export const imageKitUploadAuthPath = '/imagekit-upload-auth';
-export const isImageKitReceiptContext = (value)=>{
-    if (!value || typeof value !== 'object') {
-        return false;
-    }
-    const context = value;
-    return (context._objectKey === undefined || typeof context._objectKey === 'string' && context._objectKey.length > 0) && (context.uploadTag === undefined || typeof context.uploadTag === 'string' && context.uploadTag.length > 0) && Boolean(context._objectKey || context.uploadTag || context.fileId) && typeof context.collectionSlug === 'string' && context.collectionSlug.length > 0 && typeof context.expectedMimeType === 'string' && context.expectedMimeType.length > 0 && typeof context.expectedSize === 'number' && Number.isSafeInteger(context.expectedSize) && context.expectedSize >= 0 && (context.fileId === undefined || typeof context.fileId === 'string' && context.fileId.length > 0) && typeof context.filename === 'string' && context.filename.length > 0 && typeof context.isPrivate === 'boolean' && typeof context.prefix === 'string';
-};
+export { };
 
 //# sourceMappingURL=clientUploads.js.map

package/dist/clientUploads.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/clientUploads.ts"],"sourcesContent":["import type { ClientUploadContext } from '@payloadcms/plugin-cloud-storage/types'\n\nexport const imageKitUploadAuthPath = '/imagekit-upload-auth'\n\n/**\n * @deprecated Provider metadata is verified server-side and is no longer accepted as upload\n * proof. This backwards-compatible shape remains exported for existing type consumers.\n */\nexport type ImageKitClientUploadContext = {\n  fileId?: string\n  filePath?: string\n  fileType?: string\n  mimeType?: string\n  name?: string\n  size?: number\n  thumbnailUrl?: string\n  url?: string\n} & Partial<ClientUploadContext>\n\n/** @deprecated The upload handler is configured internally by Payload 3.90.1. */\nexport type ImageKitUploadHandlerProps = {\n  authPath: `/${string}`\n  collectionSlug: string\n  folder: string\n  isPrivate?: boolean\n  publicKey: string\n}\n\nexport type ImageKitReceiptContext = {\n  /** Legacy uploads stored beneath a per-upload folder. */\n  _objectKey?: string\n  collectionSlug: string\n  expectedMimeType: string\n  expectedSize: number\n  /** Present only after the server verifies the completed upload. */\n  fileId?: string\n  filename: string\n  isPrivate: boolean\n  prefix: string\n  /** Binds a pending authorization to the newly uploaded provider object. */\n  uploadTag?: string\n}\n\nexport type ImageKitUploadPayload = {\n  checks: string\n  fileName: string\n  folder: string\n  isPrivateFile: 'false' | 'true'\n  overwriteFile: 'false'\n  tags: string\n  useUniqueFileName: 'false'\n}\n\nexport type ImageKitUploadAuthorization = {\n  clientUploadContext: ClientUploadContext\n  filename: string\n  token: string\n  uploadPayload: ImageKitUploadPayload\n}\n\nexport type ImageKitUploadCompletion = {\n  clientUploadContext: ClientUploadContext\n}\n\nexport const isImageKitReceiptContext = (value: unknown): value is ImageKitReceiptContext => {\n  if (!value || typeof value !== 'object') {\n    return false\n  }\n\n  const context = value as Partial<ImageKitReceiptContext>\n\n  return (\n    (context._objectKey === undefined ||\n      (typeof context._objectKey === 'string' && context._objectKey.length > 0)) &&\n    (context.uploadTag === undefined ||\n      (typeof context.uploadTag === 'string' && context.uploadTag.length > 0)) &&\n    Boolean(context._objectKey || context.uploadTag || context.fileId) &&\n    typeof context.collectionSlug === 'string' &&\n    context.collectionSlug.length > 0 &&\n    typeof context.expectedMimeType === 'string' &&\n    context.expectedMimeType.length > 0 &&\n    typeof context.expectedSize === 'number' &&\n    Number.isSafeInteger(context.expectedSize) &&\n    context.expectedSize >= 0 &&\n    (context.fileId === undefined ||\n      (typeof context.fileId === 'string' && context.fileId.length > 0)) &&\n    typeof context.filename === 'string' &&\n    context.filename.length > 0 &&\n    typeof context.isPrivate === 'boolean' &&\n    typeof context.prefix === 'string'\n  )\n}\n"],"names":["imageKitUploadAuthPath","isImageKitReceiptContext","value","context","_objectKey","undefined","length","uploadTag","Boolean","fileId","collectionSlug","expectedMimeType","expectedSize","Number","isSafeInteger","filename","isPrivate","prefix"],"mappings":"AAEA,OAAO,MAAMA,yBAAyB,wBAAuB;AA8D7D,OAAO,MAAMC,2BAA2B,CAACC;IACvC,IAAI,CAACA,SAAS,OAAOA,UAAU,UAAU;QACvC,OAAO;IACT;IAEA,MAAMC,UAAUD;IAEhB,OACE,AAACC,CAAAA,QAAQC,UAAU,KAAKC,aACrB,OAAOF,QAAQC,UAAU,KAAK,YAAYD,QAAQC,UAAU,CAACE,MAAM,GAAG,CAAC,KACzEH,CAAAA,QAAQI,SAAS,KAAKF,aACpB,OAAOF,QAAQI,SAAS,KAAK,YAAYJ,QAAQI,SAAS,CAACD,MAAM,GAAG,CAAC,KACxEE,QAAQL,QAAQC,UAAU,IAAID,QAAQI,SAAS,IAAIJ,QAAQM,MAAM,KACjE,OAAON,QAAQO,cAAc,KAAK,YAClCP,QAAQO,cAAc,CAACJ,MAAM,GAAG,KAChC,OAAOH,QAAQQ,gBAAgB,KAAK,YACpCR,QAAQQ,gBAAgB,CAACL,MAAM,GAAG,KAClC,OAAOH,QAAQS,YAAY,KAAK,YAChCC,OAAOC,aAAa,CAACX,QAAQS,YAAY,KACzCT,QAAQS,YAAY,IAAI,KACvBT,CAAAA,QAAQM,MAAM,KAAKJ,aACjB,OAAOF,QAAQM,MAAM,KAAK,YAAYN,QAAQM,MAAM,CAACH,MAAM,GAAG,CAAC,KAClE,OAAOH,QAAQY,QAAQ,KAAK,YAC5BZ,QAAQY,QAAQ,CAACT,MAAM,GAAG,KAC1B,OAAOH,QAAQa,SAAS,KAAK,aAC7B,OAAOb,QAAQc,MAAM,KAAK;AAE9B,EAAC"}
+{"version":3,"sources":["../src/clientUploads.ts"],"sourcesContent":["import type { UploadReference } from '@payloadcms/plugin-cloud-storage/types'\n\n/** @deprecated Use Payload 4's UploadReference and UploadInstructions types. */\nexport type ImageKitClientUploadContext = Partial<UploadReference>\n\n/** @deprecated The upload handler is configured by the storage capability. */\nexport type ImageKitUploadHandlerProps = {\n  authPath: `/${string}`\n  collectionSlug: string\n  folder: string\n  isPrivate?: boolean\n  publicKey: string\n}\n\nexport type ImageKitUploadPayload = {\n  checks: string\n  fileName: string\n  folder: string\n  isPrivateFile: 'false' | 'true'\n  overwriteFile: 'false'\n  tags: string\n  useUniqueFileName: 'false'\n}\n"],"names":[],"mappings":"AAcA,WAQC"}

package/dist/components/BeforeDashboardServer.d.ts

@@ -1,2 +1,2 @@
 import type { ServerComponentProps } from 'payload';
-export declare const BeforeDashboardServer: (props: ServerComponentProps) => Promise<import("react").JSX.Element>;
+export declare const BeforeDashboardServer: (props: ServerComponentProps) => Promise<import("react").JSX.Element | null>;

package/dist/components/BeforeDashboardServer.js

@@ -2,8 +2,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import styles from './BeforeDashboardServer.module.css';
 export const BeforeDashboardServer = async (props)=>{
     const { payload } = props;
+    const collection = payload.config.collections.find((collection)=>String(collection.slug) === 'plugin-collection');
+    if (!collection) {
+        return null;
+    }
     const { docs } = await payload.find({
-        collection: 'plugin-collection'
+        collection: collection.slug,
+        overrideAccess: true
     });
     return /*#__PURE__*/ _jsxs("div", {
         className: styles.wrapper,

package/dist/components/BeforeDashboardServer.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/BeforeDashboardServer.tsx"],"sourcesContent":["import type { ServerComponentProps } from 'payload'\n\nimport styles from './BeforeDashboardServer.module.css'\n\nexport const BeforeDashboardServer = async (props: ServerComponentProps) => {\n  const { payload } = props\n\n  const { docs } = await payload.find({ collection: 'plugin-collection' })\n\n  return (\n    <div className={styles.wrapper}>\n      <h1>Added by the plugin: Before Dashboard Server</h1>\n      Docs from Local API:\n      {docs.map((doc) => (\n        <div key={doc.id}>{doc.id}</div>\n      ))}\n    </div>\n  )\n}\n"],"names":["styles","BeforeDashboardServer","props","payload","docs","find","collection","div","className","wrapper","h1","map","doc","id"],"mappings":";AAEA,OAAOA,YAAY,qCAAoC;AAEvD,OAAO,MAAMC,wBAAwB,OAAOC;IAC1C,MAAM,EAAEC,OAAO,EAAE,GAAGD;IAEpB,MAAM,EAAEE,IAAI,EAAE,GAAG,MAAMD,QAAQE,IAAI,CAAC;QAAEC,YAAY;IAAoB;IAEtE,qBACE,MAACC;QAAIC,WAAWR,OAAOS,OAAO;;0BAC5B,KAACC;0BAAG;;YAAiD;YAEpDN,KAAKO,GAAG,CAAC,CAACC,oBACT,KAACL;8BAAkBK,IAAIC,EAAE;mBAAfD,IAAIC,EAAE;;;AAIxB,EAAC"}
+{"version":3,"sources":["../../src/components/BeforeDashboardServer.tsx"],"sourcesContent":["import type { ServerComponentProps } from 'payload'\n\nimport styles from './BeforeDashboardServer.module.css'\n\nexport const BeforeDashboardServer = async (props: ServerComponentProps) => {\n  const { payload } = props\n\n  const collection = payload.config.collections.find(\n    (collection) => String(collection.slug) === 'plugin-collection',\n  )\n  if (!collection) {\n    return null\n  }\n  const { docs } = await payload.find({ collection: collection.slug, overrideAccess: true })\n\n  return (\n    <div className={styles.wrapper}>\n      <h1>Added by the plugin: Before Dashboard Server</h1>\n      Docs from Local API:\n      {docs.map((doc) => (\n        <div key={doc.id}>{doc.id}</div>\n      ))}\n    </div>\n  )\n}\n"],"names":["styles","BeforeDashboardServer","props","payload","collection","config","collections","find","String","slug","docs","overrideAccess","div","className","wrapper","h1","map","doc","id"],"mappings":";AAEA,OAAOA,YAAY,qCAAoC;AAEvD,OAAO,MAAMC,wBAAwB,OAAOC;IAC1C,MAAM,EAAEC,OAAO,EAAE,GAAGD;IAEpB,MAAME,aAAaD,QAAQE,MAAM,CAACC,WAAW,CAACC,IAAI,CAChD,CAACH,aAAeI,OAAOJ,WAAWK,IAAI,MAAM;IAE9C,IAAI,CAACL,YAAY;QACf,OAAO;IACT;IACA,MAAM,EAAEM,IAAI,EAAE,GAAG,MAAMP,QAAQI,IAAI,CAAC;QAAEH,YAAYA,WAAWK,IAAI;QAAEE,gBAAgB;IAAK;IAExF,qBACE,MAACC;QAAIC,WAAWb,OAAOc,OAAO;;0BAC5B,KAACC;0BAAG;;YAAiD;YAEpDL,KAAKM,GAAG,CAAC,CAACC,oBACT,KAACL;8BAAkBK,IAAIC,EAAE;mBAAfD,IAAIC,EAAE;;;AAIxB,EAAC"}

package/dist/components/ImageKitUploadHandler.d.ts

@@ -1,8 +1,7 @@
-export declare const ImageKitUploadHandler: ({ children, collectionSlug, enabled, extra, prefix, serverHandlerPath, }: {
+export declare const ImageKitUploadHandler: ({ children, collectionSlug, endpointPath, prefix, props, }: {
     children: import("react").ReactNode;
     collectionSlug: import("payload").UploadCollectionSlug;
-    enabled?: boolean;
-    extra: Record<string, unknown>;
+    endpointPath?: `/${string}`;
     prefix?: string;
-    serverHandlerPath: `/${string}`;
+    props: Record<string, unknown>;
 }) => import("react").JSX.Element;

package/dist/components/ImageKitUploadHandler.js

@@ -2,85 +2,26 @@
 import { createClientUploadHandler } from '@payloadcms/plugin-cloud-storage/client';
 import { formatAdminURL } from 'payload/shared';
 import { getClientImageIdentity } from '../clientImageIdentity.js';
-const uploadAPIURL = 'https://upload.imagekit.io/api/v2/files/upload';
-const readErrorMessage = async (response, fallback)=>{
-    try {
-        const result = await response.json();
-        if (typeof result.message === 'string' && result.message.trim().length > 0) {
-            return result.message;
-        }
-        const messages = result.errors?.map((error)=>error.message).filter((message)=>Boolean(message));
-        if (messages?.length) {
-            return messages.join(', ');
-        }
-    } catch  {
-    // Ignore non-JSON responses and fall back to the default message.
-    }
-    return fallback;
-};
 export const ImageKitUploadHandler = createClientUploadHandler({
-    handler: async ({ apiRoute, collectionSlug, file, serverHandlerPath, serverURL, updateFilename })=>{
-        const authURL = formatAdminURL({
-            apiRoute,
-            path: serverHandlerPath,
-            serverURL
-        });
+    name: 'imagekit',
+    handler: async ({ apiRoute, collectionSlug, data, docPrefix, endpointPath, file, serverURL, updateFilename })=>{
+        let authorization = data;
+        let uploadReference;
         const identity = await getClientImageIdentity(file);
-        let authBody = {
-            collectionSlug,
-            filename: identity.filename,
-            filesize: file.size,
-            mimeType: identity.mimeType
-        };
-        for(let attempt = 0; attempt < 10; attempt++){
-            const authResponse = await fetch(authURL, {
-                body: JSON.stringify(authBody),
-                credentials: 'include',
-                headers: {
-                    'Content-Type': 'application/json'
-                },
-                method: 'POST'
-            });
-            if (!authResponse.ok) {
-                throw new Error(await readErrorMessage(authResponse, 'Failed to authorize direct ImageKit upload.'));
-            }
-            const authorization = await authResponse.json();
-            if (authorization.filename !== file.name) {
-                updateFilename(authorization.filename);
-            }
-            const formData = new FormData();
-            formData.set('file', file);
-            formData.set('token', authorization.token);
-            for (const [key, value] of Object.entries(authorization.uploadPayload)){
-                formData.set(key, value);
-            }
-            const uploadResponse = await fetch(uploadAPIURL, {
-                body: formData,
-                method: 'POST'
-            });
-            if (!uploadResponse.ok) {
-                const message = await readErrorMessage(uploadResponse, 'Failed to upload file to ImageKit.');
-                const isFilenameConflict = (uploadResponse.status === 400 || uploadResponse.status === 409) && message.includes('A file with the same name already exists at the exact location');
-                if (isFilenameConflict) {
-                    authBody = {
-                        action: 'retry',
-                        collectionSlug,
-                        signedReceipt: authorization.clientUploadContext.signedReceipt
-                    };
-                    continue;
-                }
-                throw new Error(message);
-            }
-            const uploaded = await uploadResponse.json();
-            if (typeof uploaded.fileId !== 'string' || !uploaded.fileId.trim()) {
-                throw new Error('ImageKit did not return an uploaded file ID.');
-            }
-            const completionResponse = await fetch(authURL, {
+        // Payload's initial instructions use the browser's MIME hint. Re-authorize
+        // mislabeled image bytes through the same shared endpoint, not a private API.
+        if (identity.filename !== file.name || identity.mimeType !== file.type) {
+            const response = await fetch(formatAdminURL({
+                apiRoute,
+                path: '/upload-instructions',
+                serverURL
+            }), {
                 body: JSON.stringify({
-                    action: 'complete',
                     collectionSlug,
-                    fileId: uploaded.fileId,
-                    signedReceipt: authorization.clientUploadContext.signedReceipt
+                    docPrefix,
+                    filename: identity.filename,
+                    filesize: file.size,
+                    mimeType: identity.mimeType
                 }),
                 credentials: 'include',
                 headers: {
@@ -88,13 +29,61 @@ export const ImageKitUploadHandler = createClientUploadHandler({
                 },
                 method: 'POST'
             });
-            if (!completionResponse.ok) {
-                throw new Error(await readErrorMessage(completionResponse, 'Failed to verify ImageKit upload.'));
+            if (!response.ok) {
+                throw new Error('Failed to authorize detected image content.');
             }
-            const completion = await completionResponse.json();
-            return completion.clientUploadContext;
+            const instructions = await response.json();
+            if (instructions.type !== 'dispatch' || instructions.name !== 'imagekit') {
+                throw new Error('Expected ImageKit upload instructions.');
+            }
+            authorization = instructions.data;
+            uploadReference = instructions.file.uploadReference;
+            updateFilename(instructions.file.filename);
+        }
+        if (!endpointPath || typeof authorization.uploadReference?.signedReceipt !== 'string') {
+            throw new Error('ImageKit upload configuration changed. Refresh the page and try again.');
+        }
+        const formData = new FormData();
+        formData.set('file', file);
+        formData.set('token', authorization.token);
+        for (const [key, value] of Object.entries(authorization.uploadPayload)){
+            formData.set(key, value);
+        }
+        const response = await fetch('https://upload.imagekit.io/api/v2/files/upload', {
+            body: formData,
+            method: 'POST'
+        });
+        if (!response.ok) {
+            const error = await response.json().catch(()=>null);
+            throw new Error(error?.message || 'Failed to upload file to ImageKit.');
+        }
+        const uploaded = await response.json().catch(()=>null);
+        if (typeof uploaded?.fileId !== 'string' || !uploaded.fileId) {
+            throw new Error('ImageKit returned incomplete upload metadata.');
+        }
+        const completed = await fetch(formatAdminURL({
+            apiRoute,
+            path: endpointPath,
+            serverURL
+        }), {
+            body: JSON.stringify({
+                collectionSlug,
+                fileId: uploaded.fileId,
+                signedReceipt: authorization.uploadReference.signedReceipt
+            }),
+            credentials: 'include',
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            method: 'POST'
+        });
+        if (!completed.ok) {
+            const error = await completed.json().catch(()=>null);
+            throw new Error(error?.errors?.[0]?.message || 'Failed to verify the ImageKit upload.');
         }
-        throw new Error('Could not find an available filename. Rename the file and try again.');
+        // The completion callback remembers a server-verified ID, not a browser-supplied proof.
+        // Payload keeps its original signed reference and owns the original/history lifecycle.
+        return uploadReference;
     }
 });
 

package/dist/components/ImageKitUploadHandler.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/ImageKitUploadHandler.tsx"],"sourcesContent":["'use client'\n\nimport { createClientUploadHandler } from '@payloadcms/plugin-cloud-storage/client'\nimport { formatAdminURL } from 'payload/shared'\n\nimport type { ImageKitUploadAuthorization, ImageKitUploadCompletion } from '../clientUploads.js'\n\nimport { getClientImageIdentity } from '../clientImageIdentity.js'\n\nconst uploadAPIURL = 'https://upload.imagekit.io/api/v2/files/upload'\n\nconst readErrorMessage = async (response: Response, fallback: string): Promise<string> => {\n  try {\n    const result = (await response.json()) as {\n      errors?: Array<{ message?: string }>\n      message?: string\n    }\n\n    if (typeof result.message === 'string' && result.message.trim().length > 0) {\n      return result.message\n    }\n\n    const messages = result.errors\n      ?.map((error) => error.message)\n      .filter((message): message is string => Boolean(message))\n\n    if (messages?.length) {\n      return messages.join(', ')\n    }\n  } catch {\n    // Ignore non-JSON responses and fall back to the default message.\n  }\n\n  return fallback\n}\n\nexport const ImageKitUploadHandler = createClientUploadHandler({\n  handler: async ({\n    apiRoute,\n    collectionSlug,\n    file,\n    serverHandlerPath,\n    serverURL,\n    updateFilename,\n  }) => {\n    const authURL = formatAdminURL({\n      apiRoute,\n      path: serverHandlerPath,\n      serverURL,\n    })\n    const identity = await getClientImageIdentity(file)\n    let authBody: Record<string, unknown> = {\n      collectionSlug,\n      filename: identity.filename,\n      filesize: file.size,\n      mimeType: identity.mimeType,\n    }\n\n    for (let attempt = 0; attempt < 10; attempt++) {\n      const authResponse = await fetch(authURL, {\n        body: JSON.stringify(authBody),\n        credentials: 'include',\n        headers: {\n          'Content-Type': 'application/json',\n        },\n        method: 'POST',\n      })\n\n      if (!authResponse.ok) {\n        throw new Error(\n          await readErrorMessage(authResponse, 'Failed to authorize direct ImageKit upload.'),\n        )\n      }\n\n      const authorization = (await authResponse.json()) as ImageKitUploadAuthorization\n\n      if (authorization.filename !== file.name) {\n        updateFilename(authorization.filename)\n      }\n\n      const formData = new FormData()\n\n      formData.set('file', file)\n      formData.set('token', authorization.token)\n      for (const [key, value] of Object.entries(authorization.uploadPayload)) {\n        formData.set(key, value)\n      }\n\n      const uploadResponse = await fetch(uploadAPIURL, {\n        body: formData,\n        method: 'POST',\n      })\n\n      if (!uploadResponse.ok) {\n        const message = await readErrorMessage(uploadResponse, 'Failed to upload file to ImageKit.')\n        const isFilenameConflict =\n          (uploadResponse.status === 400 || uploadResponse.status === 409) &&\n          message.includes('A file with the same name already exists at the exact location')\n        if (isFilenameConflict) {\n          authBody = {\n            action: 'retry',\n            collectionSlug,\n            signedReceipt: authorization.clientUploadContext.signedReceipt,\n          }\n          continue\n        }\n        throw new Error(message)\n      }\n\n      const uploaded = (await uploadResponse.json()) as { fileId?: unknown }\n      if (typeof uploaded.fileId !== 'string' || !uploaded.fileId.trim()) {\n        throw new Error('ImageKit did not return an uploaded file ID.')\n      }\n\n      const completionResponse = await fetch(authURL, {\n        body: JSON.stringify({\n          action: 'complete',\n          collectionSlug,\n          fileId: uploaded.fileId,\n          signedReceipt: authorization.clientUploadContext.signedReceipt,\n        }),\n        credentials: 'include',\n        headers: { 'Content-Type': 'application/json' },\n        method: 'POST',\n      })\n      if (!completionResponse.ok) {\n        throw new Error(\n          await readErrorMessage(completionResponse, 'Failed to verify ImageKit upload.'),\n        )\n      }\n      const completion = (await completionResponse.json()) as ImageKitUploadCompletion\n      return completion.clientUploadContext\n    }\n    throw new Error('Could not find an available filename. Rename the file and try again.')\n  },\n})\n"],"names":["createClientUploadHandler","formatAdminURL","getClientImageIdentity","uploadAPIURL","readErrorMessage","response","fallback","result","json","message","trim","length","messages","errors","map","error","filter","Boolean","join","ImageKitUploadHandler","handler","apiRoute","collectionSlug","file","serverHandlerPath","serverURL","updateFilename","authURL","path","identity","authBody","filename","filesize","size","mimeType","attempt","authResponse","fetch","body","JSON","stringify","credentials","headers","method","ok","Error","authorization","name","formData","FormData","set","token","key","value","Object","entries","uploadPayload","uploadResponse","isFilenameConflict","status","includes","action","signedReceipt","clientUploadContext","uploaded","fileId","completionResponse","completion"],"mappings":"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"}
+{"version":3,"sources":["../../src/components/ImageKitUploadHandler.tsx"],"sourcesContent":["'use client'\n\nimport type { UploadInstructions } from 'payload'\n\nimport { createClientUploadHandler } from '@payloadcms/plugin-cloud-storage/client'\nimport { formatAdminURL } from 'payload/shared'\n\nimport { getClientImageIdentity } from '../clientImageIdentity.js'\n\nexport const ImageKitUploadHandler = createClientUploadHandler({\n  name: 'imagekit',\n  handler: async ({\n    apiRoute,\n    collectionSlug,\n    data,\n    docPrefix,\n    endpointPath,\n    file,\n    serverURL,\n    updateFilename,\n  }) => {\n    let authorization = data as {\n      token: string\n      uploadPayload: Record<string, string>\n      uploadReference: Record<string, unknown>\n    }\n    let uploadReference: Record<string, unknown> | undefined\n    const identity = await getClientImageIdentity(file)\n    // Payload's initial instructions use the browser's MIME hint. Re-authorize\n    // mislabeled image bytes through the same shared endpoint, not a private API.\n    if (identity.filename !== file.name || identity.mimeType !== file.type) {\n      const response = await fetch(\n        formatAdminURL({ apiRoute, path: '/upload-instructions', serverURL }),\n        {\n          body: JSON.stringify({\n            collectionSlug,\n            docPrefix,\n            filename: identity.filename,\n            filesize: file.size,\n            mimeType: identity.mimeType,\n          }),\n          credentials: 'include',\n          headers: { 'Content-Type': 'application/json' },\n          method: 'POST',\n        },\n      )\n      if (!response.ok) {\n        throw new Error('Failed to authorize detected image content.')\n      }\n      const instructions = (await response.json()) as UploadInstructions\n      if (instructions.type !== 'dispatch' || instructions.name !== 'imagekit') {\n        throw new Error('Expected ImageKit upload instructions.')\n      }\n      authorization = instructions.data as typeof authorization\n      uploadReference = instructions.file.uploadReference\n      updateFilename(instructions.file.filename)\n    }\n    if (!endpointPath || typeof authorization.uploadReference?.signedReceipt !== 'string') {\n      throw new Error('ImageKit upload configuration changed. Refresh the page and try again.')\n    }\n    const formData = new FormData()\n    formData.set('file', file)\n    formData.set('token', authorization.token)\n    for (const [key, value] of Object.entries(authorization.uploadPayload)) {\n      formData.set(key, value)\n    }\n    const response = await fetch('https://upload.imagekit.io/api/v2/files/upload', {\n      body: formData,\n      method: 'POST',\n    })\n    if (!response.ok) {\n      const error = (await response.json().catch(() => null)) as { message?: string } | null\n      throw new Error(error?.message || 'Failed to upload file to ImageKit.')\n    }\n    const uploaded = (await response.json().catch(() => null)) as { fileId?: unknown } | null\n    if (typeof uploaded?.fileId !== 'string' || !uploaded.fileId) {\n      throw new Error('ImageKit returned incomplete upload metadata.')\n    }\n    const completed = await fetch(formatAdminURL({ apiRoute, path: endpointPath, serverURL }), {\n      body: JSON.stringify({\n        collectionSlug,\n        fileId: uploaded.fileId,\n        signedReceipt: authorization.uploadReference.signedReceipt,\n      }),\n      credentials: 'include',\n      headers: { 'Content-Type': 'application/json' },\n      method: 'POST',\n    })\n    if (!completed.ok) {\n      const error = (await completed.json().catch(() => null)) as {\n        errors?: { message?: string }[]\n      } | null\n      throw new Error(error?.errors?.[0]?.message || 'Failed to verify the ImageKit upload.')\n    }\n    // The completion callback remembers a server-verified ID, not a browser-supplied proof.\n    // Payload keeps its original signed reference and owns the original/history lifecycle.\n    return uploadReference\n  },\n})\n"],"names":["createClientUploadHandler","formatAdminURL","getClientImageIdentity","ImageKitUploadHandler","name","handler","apiRoute","collectionSlug","data","docPrefix","endpointPath","file","serverURL","updateFilename","authorization","uploadReference","identity","filename","mimeType","type","response","fetch","path","body","JSON","stringify","filesize","size","credentials","headers","method","ok","Error","instructions","json","signedReceipt","formData","FormData","set","token","key","value","Object","entries","uploadPayload","error","catch","message","uploaded","fileId","completed","errors"],"mappings":"AAAA;AAIA,SAASA,yBAAyB,QAAQ,0CAAyC;AACnF,SAASC,cAAc,QAAQ,iBAAgB;AAE/C,SAASC,sBAAsB,QAAQ,4BAA2B;AAElE,OAAO,MAAMC,wBAAwBH,0BAA0B;IAC7DI,MAAM;IACNC,SAAS,OAAO,EACdC,QAAQ,EACRC,cAAc,EACdC,IAAI,EACJC,SAAS,EACTC,YAAY,EACZC,IAAI,EACJC,SAAS,EACTC,cAAc,EACf;QACC,IAAIC,gBAAgBN;QAKpB,IAAIO;QACJ,MAAMC,WAAW,MAAMd,uBAAuBS;QAC9C,2EAA2E;QAC3E,8EAA8E;QAC9E,IAAIK,SAASC,QAAQ,KAAKN,KAAKP,IAAI,IAAIY,SAASE,QAAQ,KAAKP,KAAKQ,IAAI,EAAE;YACtE,MAAMC,WAAW,MAAMC,MACrBpB,eAAe;gBAAEK;gBAAUgB,MAAM;gBAAwBV;YAAU,IACnE;gBACEW,MAAMC,KAAKC,SAAS,CAAC;oBACnBlB;oBACAE;oBACAQ,UAAUD,SAASC,QAAQ;oBAC3BS,UAAUf,KAAKgB,IAAI;oBACnBT,UAAUF,SAASE,QAAQ;gBAC7B;gBACAU,aAAa;gBACbC,SAAS;oBAAE,gBAAgB;gBAAmB;gBAC9CC,QAAQ;YACV;YAEF,IAAI,CAACV,SAASW,EAAE,EAAE;gBAChB,MAAM,IAAIC,MAAM;YAClB;YACA,MAAMC,eAAgB,MAAMb,SAASc,IAAI;YACzC,IAAID,aAAad,IAAI,KAAK,cAAcc,aAAa7B,IAAI,KAAK,YAAY;gBACxE,MAAM,IAAI4B,MAAM;YAClB;YACAlB,gBAAgBmB,aAAazB,IAAI;YACjCO,kBAAkBkB,aAAatB,IAAI,CAACI,eAAe;YACnDF,eAAeoB,aAAatB,IAAI,CAACM,QAAQ;QAC3C;QACA,IAAI,CAACP,gBAAgB,OAAOI,cAAcC,eAAe,EAAEoB,kBAAkB,UAAU;YACrF,MAAM,IAAIH,MAAM;QAClB;QACA,MAAMI,WAAW,IAAIC;QACrBD,SAASE,GAAG,CAAC,QAAQ3B;QACrByB,SAASE,GAAG,CAAC,SAASxB,cAAcyB,KAAK;QACzC,KAAK,MAAM,CAACC,KAAKC,MAAM,IAAIC,OAAOC,OAAO,CAAC7B,cAAc8B,aAAa,EAAG;YACtER,SAASE,GAAG,CAACE,KAAKC;QACpB;QACA,MAAMrB,WAAW,MAAMC,MAAM,kDAAkD;YAC7EE,MAAMa;YACNN,QAAQ;QACV;QACA,IAAI,CAACV,SAASW,EAAE,EAAE;YAChB,MAAMc,QAAS,MAAMzB,SAASc,IAAI,GAAGY,KAAK,CAAC,IAAM;YACjD,MAAM,IAAId,MAAMa,OAAOE,WAAW;QACpC;QACA,MAAMC,WAAY,MAAM5B,SAASc,IAAI,GAAGY,KAAK,CAAC,IAAM;QACpD,IAAI,OAAOE,UAAUC,WAAW,YAAY,CAACD,SAASC,MAAM,EAAE;YAC5D,MAAM,IAAIjB,MAAM;QAClB;QACA,MAAMkB,YAAY,MAAM7B,MAAMpB,eAAe;YAAEK;YAAUgB,MAAMZ;YAAcE;QAAU,IAAI;YACzFW,MAAMC,KAAKC,SAAS,CAAC;gBACnBlB;gBACA0C,QAAQD,SAASC,MAAM;gBACvBd,eAAerB,cAAcC,eAAe,CAACoB,aAAa;YAC5D;YACAP,aAAa;YACbC,SAAS;gBAAE,gBAAgB;YAAmB;YAC9CC,QAAQ;QACV;QACA,IAAI,CAACoB,UAAUnB,EAAE,EAAE;YACjB,MAAMc,QAAS,MAAMK,UAAUhB,IAAI,GAAGY,KAAK,CAAC,IAAM;YAGlD,MAAM,IAAId,MAAMa,OAAOM,QAAQ,CAAC,EAAE,EAAEJ,WAAW;QACjD;QACA,wFAAwF;QACxF,uFAAuF;QACvF,OAAOhC;IACT;AACF,GAAE"}

package/dist/endpoints/completeImageKitUpload.d.ts

@@ -0,0 +1,10 @@
+import type { PayloadHandler, UploadInstructionsAccess } from 'payload';
+import type { createImageKitFileStore } from '../imageKitFileStore.js';
+export declare const completeImageKitUpload: ({ access, collections, files, }: {
+    access?: UploadInstructionsAccess;
+    collections: Record<string, {
+        isPrivate: boolean;
+        prefix: string;
+    }>;
+    files: ReturnType<typeof createImageKitFileStore>;
+}) => PayloadHandler;

package/dist/endpoints/completeImageKitUpload.js

@@ -0,0 +1,84 @@
+import { NotFoundError } from '@imagekit/nodejs';
+import { buildStoragePathData } from '@payloadcms/plugin-cloud-storage/utilities';
+import path from 'node:path';
+import { APIError, Forbidden } from 'payload';
+import { assertClientUploadAccess, assertClientUploadAllowed, getOriginalFilename, verifyClientUploadReceipt } from 'payload/internal';
+import { validateMimeType } from 'payload/shared';
+export const completeImageKitUpload = ({ access = ({ req })=>Boolean(req.user), collections, files })=>async (req)=>{
+        if (!req.json) {
+            throw new APIError('Expected an ImageKit upload completion payload.', 400);
+        }
+        const body = await req.json().catch(()=>{
+            throw new APIError('Invalid ImageKit upload completion.', 400);
+        });
+        if (!body || typeof body.collectionSlug !== 'string' || !Object.hasOwn(collections, body.collectionSlug) || typeof body.fileId !== 'string' || !body.fileId.trim()) {
+            throw new APIError('Invalid ImageKit upload completion.', 400);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- Consumer-generated configs narrow UploadCollectionSlug.
+        const collectionSlug = body.collectionSlug;
+        await assertClientUploadAccess({
+            collectionSlug,
+            req
+        });
+        if (!await access({
+            collectionSlug,
+            req
+        })) {
+            throw new Forbidden(req.t);
+        }
+        const receipt = verifyClientUploadReceipt({
+            collectionSlug,
+            req,
+            signedReceipt: body.signedReceipt
+        });
+        const { isPrivate, prefix } = collections[collectionSlug];
+        const expectedPath = buildStoragePathData({
+            collectionPrefix: prefix,
+            docPrefix: path.posix.join(receipt.filePrefix, receipt._objectKey ?? ''),
+            filename: getOriginalFilename({
+                filename: receipt.filename
+            })
+        }).storageFilePath;
+        if (!receipt._objectKey || receipt.allowOverwrite || expectedPath !== receipt.storageFilePath || !expectedPath.startsWith(`${prefix}/`)) {
+            throw new APIError('Invalid ImageKit upload reference.', 400);
+        }
+        let file;
+        try {
+            file = await files.getByID({
+                fileId: body.fileId,
+                key: expectedPath
+            });
+        } catch (error) {
+            if (error instanceof NotFoundError) {
+                throw new APIError('ImageKit upload was not found.', 400);
+            }
+            throw error;
+        }
+        if (!file.mime || Boolean(file.isPrivateFile) !== isPrivate || !file.tags?.includes(`payload-upload-${receipt._objectKey}`)) {
+            throw new APIError('ImageKit upload did not match its authorization.', 400);
+        }
+        const collection = req.payload.collections[collectionSlug].config;
+        assertClientUploadAllowed({
+            collection,
+            filename: file.name,
+            mimeType: file.mime
+        });
+        if (typeof collection.upload === 'object' && !validateMimeType(file.mime, collection.upload.mimeTypes ?? [])) {
+            throw new APIError('ImageKit file type is not allowed for this collection.', 400);
+        }
+        // The browser's ID is only a lookup hint. Persist it only after checking authoritative state
+        // against the user-bound receipt. Save-time admission rechecks both the receipt and provider.
+        await files.remember({
+            fileId: file.fileId,
+            key: expectedPath,
+            req
+        });
+        return new Response(null, {
+            headers: {
+                'Cache-Control': 'no-store'
+            },
+            status: 204
+        });
+    };
+
+//# sourceMappingURL=completeImageKitUpload.js.map

package/dist/endpoints/completeImageKitUpload.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/endpoints/completeImageKitUpload.ts"],"sourcesContent":["import type { PayloadHandler, UploadCollectionSlug, UploadInstructionsAccess } from 'payload'\n\nimport { NotFoundError } from '@imagekit/nodejs'\nimport { buildStoragePathData } from '@payloadcms/plugin-cloud-storage/utilities'\nimport path from 'node:path'\nimport { APIError, Forbidden } from 'payload'\nimport {\n  assertClientUploadAccess,\n  assertClientUploadAllowed,\n  getOriginalFilename,\n  verifyClientUploadReceipt,\n} from 'payload/internal'\nimport { validateMimeType } from 'payload/shared'\n\nimport type { createImageKitFileStore } from '../imageKitFileStore.js'\n\nexport const completeImageKitUpload =\n  ({\n    access = ({ req }) => Boolean(req.user),\n    collections,\n    files,\n  }: {\n    access?: UploadInstructionsAccess\n    collections: Record<string, { isPrivate: boolean; prefix: string }>\n    files: ReturnType<typeof createImageKitFileStore>\n  }): PayloadHandler =>\n  async (req) => {\n    if (!req.json) {\n      throw new APIError('Expected an ImageKit upload completion payload.', 400)\n    }\n    const body = (await req.json().catch(() => {\n      throw new APIError('Invalid ImageKit upload completion.', 400)\n    })) as {\n      collectionSlug?: unknown\n      fileId?: unknown\n      signedReceipt?: unknown\n    }\n    if (\n      !body ||\n      typeof body.collectionSlug !== 'string' ||\n      !Object.hasOwn(collections, body.collectionSlug) ||\n      typeof body.fileId !== 'string' ||\n      !body.fileId.trim()\n    ) {\n      throw new APIError('Invalid ImageKit upload completion.', 400)\n    }\n    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- Consumer-generated configs narrow UploadCollectionSlug.\n    const collectionSlug = body.collectionSlug as UploadCollectionSlug\n    await assertClientUploadAccess({ collectionSlug, req })\n    if (!(await access({ collectionSlug, req }))) {\n      throw new Forbidden(req.t)\n    }\n    const receipt = verifyClientUploadReceipt({\n      collectionSlug,\n      req,\n      signedReceipt: body.signedReceipt,\n    })\n    const { isPrivate, prefix } = collections[collectionSlug]\n    const expectedPath = buildStoragePathData({\n      collectionPrefix: prefix,\n      docPrefix: path.posix.join(receipt.filePrefix, receipt._objectKey ?? ''),\n      filename: getOriginalFilename({ filename: receipt.filename }),\n    }).storageFilePath\n    if (\n      !receipt._objectKey ||\n      receipt.allowOverwrite ||\n      expectedPath !== receipt.storageFilePath ||\n      !expectedPath.startsWith(`${prefix}/`)\n    ) {\n      throw new APIError('Invalid ImageKit upload reference.', 400)\n    }\n    let file: Awaited<ReturnType<typeof files.getByID>>\n    try {\n      file = await files.getByID({ fileId: body.fileId, key: expectedPath })\n    } catch (error) {\n      if (error instanceof NotFoundError) {\n        throw new APIError('ImageKit upload was not found.', 400)\n      }\n      throw error\n    }\n    if (\n      !file.mime ||\n      Boolean(file.isPrivateFile) !== isPrivate ||\n      !file.tags?.includes(`payload-upload-${receipt._objectKey}`)\n    ) {\n      throw new APIError('ImageKit upload did not match its authorization.', 400)\n    }\n    const collection = req.payload.collections[collectionSlug].config\n    assertClientUploadAllowed({\n      collection,\n      filename: file.name,\n      mimeType: file.mime,\n    })\n    if (\n      typeof collection.upload === 'object' &&\n      !validateMimeType(file.mime, collection.upload.mimeTypes ?? [])\n    ) {\n      throw new APIError('ImageKit file type is not allowed for this collection.', 400)\n    }\n    // The browser's ID is only a lookup hint. Persist it only after checking authoritative state\n    // against the user-bound receipt. Save-time admission rechecks both the receipt and provider.\n    await files.remember({ fileId: file.fileId, key: expectedPath, req })\n    return new Response(null, { headers: { 'Cache-Control': 'no-store' }, status: 204 })\n  }\n"],"names":["NotFoundError","buildStoragePathData","path","APIError","Forbidden","assertClientUploadAccess","assertClientUploadAllowed","getOriginalFilename","verifyClientUploadReceipt","validateMimeType","completeImageKitUpload","access","req","Boolean","user","collections","files","json","body","catch","collectionSlug","Object","hasOwn","fileId","trim","t","receipt","signedReceipt","isPrivate","prefix","expectedPath","collectionPrefix","docPrefix","posix","join","filePrefix","_objectKey","filename","storageFilePath","allowOverwrite","startsWith","file","getByID","key","error","mime","isPrivateFile","tags","includes","collection","payload","config","name","mimeType","upload","mimeTypes","remember","Response","headers","status"],"mappings":"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"}

package/dist/endpoints/createImageKitUploadInstructions.d.ts

@@ -0,0 +1,14 @@
+import type { GenerateUploadInstructions, UploadInstructionsAccess } from 'payload';
+/** ImageKit enforces these constraints before accepting any provider-direct bytes. */
+export declare const getUploadChecks: ({ allowedMimeTypes, allowRestrictedFileTypes, filesize, }: {
+    allowedMimeTypes: string[];
+    allowRestrictedFileTypes: boolean;
+    filesize: number;
+}) => string;
+export declare const createImageKitUploadInstructions: ({ access, isPrivate, prefix, privateKey, publicKey, }: {
+    access?: UploadInstructionsAccess;
+    isPrivate: boolean;
+    prefix: string;
+    privateKey: string;
+    publicKey: string;
+}) => GenerateUploadInstructions;