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

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,40 @@ 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.
+Because v4 receipts carry storage paths rather than provider IDs, direct admission
+uses bounded retries when ImageKit's asset listing has not yet caught up.
+
+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 +138,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, 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,34 @@ 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 instructions = await response.json();
+            if (instructions.type !== 'dispatch' || instructions.name !== 'imagekit') {
+                throw new Error('Expected ImageKit upload instructions.');
             }
-            const completion = await completionResponse.json();
-            return completion.clientUploadContext;
+            authorization = instructions.data;
+            uploadReference = instructions.file.uploadReference;
+            updateFilename(instructions.file.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 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.');
         }
-        throw new Error('Could not find an available filename. Rename the file and try again.');
+        // Payload retains the signed uploadReference supplied by /upload-instructions.
+        // Provider identity is resolved and verified on the server, never trusted from the browser.
+        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    file,\n    serverURL,\n    updateFilename,\n  }) => {\n    let authorization = data as {\n      token: string\n      uploadPayload: Record<string, string>\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    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    // Payload retains the signed uploadReference supplied by /upload-instructions.\n    // Provider identity is resolved and verified on the server, never trusted from the browser.\n    return uploadReference\n  },\n})\n"],"names":["createClientUploadHandler","formatAdminURL","getClientImageIdentity","ImageKitUploadHandler","name","handler","apiRoute","collectionSlug","data","docPrefix","file","serverURL","updateFilename","authorization","uploadReference","identity","filename","mimeType","type","response","fetch","path","body","JSON","stringify","filesize","size","credentials","headers","method","ok","Error","instructions","json","formData","FormData","set","token","key","value","Object","entries","uploadPayload","error","catch","message"],"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,IAAI,EACJC,SAAS,EACTC,cAAc,EACf;QACC,IAAIC,gBAAgBL;QAIpB,IAAIM;QACJ,MAAMC,WAAW,MAAMb,uBAAuBQ;QAC9C,2EAA2E;QAC3E,8EAA8E;QAC9E,IAAIK,SAASC,QAAQ,KAAKN,KAAKN,IAAI,IAAIW,SAASE,QAAQ,KAAKP,KAAKQ,IAAI,EAAE;YACtE,MAAMC,WAAW,MAAMC,MACrBnB,eAAe;gBAAEK;gBAAUe,MAAM;gBAAwBV;YAAU,IACnE;gBACEW,MAAMC,KAAKC,SAAS,CAAC;oBACnBjB;oBACAE;oBACAO,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,aAAa5B,IAAI,KAAK,YAAY;gBACxE,MAAM,IAAI2B,MAAM;YAClB;YACAlB,gBAAgBmB,aAAaxB,IAAI;YACjCM,kBAAkBkB,aAAatB,IAAI,CAACI,eAAe;YACnDF,eAAeoB,aAAatB,IAAI,CAACM,QAAQ;QAC3C;QACA,MAAMkB,WAAW,IAAIC;QACrBD,SAASE,GAAG,CAAC,QAAQ1B;QACrBwB,SAASE,GAAG,CAAC,SAASvB,cAAcwB,KAAK;QACzC,KAAK,MAAM,CAACC,KAAKC,MAAM,IAAIC,OAAOC,OAAO,CAAC5B,cAAc6B,aAAa,EAAG;YACtER,SAASE,GAAG,CAACE,KAAKC;QACpB;QACA,MAAMpB,WAAW,MAAMC,MAAM,kDAAkD;YAC7EE,MAAMY;YACNL,QAAQ;QACV;QACA,IAAI,CAACV,SAASW,EAAE,EAAE;YAChB,MAAMa,QAAS,MAAMxB,SAASc,IAAI,GAAGW,KAAK,CAAC,IAAM;YACjD,MAAM,IAAIb,MAAMY,OAAOE,WAAW;QACpC;QACA,+EAA+E;QAC/E,4FAA4F;QAC5F,OAAO/B;IACT;AACF,GAAE"}

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;

package/dist/endpoints/createImageKitUploadInstructions.js

@@ -0,0 +1,116 @@
+import { buildUploadStoragePathData } from '@payloadcms/plugin-cloud-storage/utilities';
+import { randomUUID } from 'node:crypto';
+import { posix } from 'node:path';
+import { Forbidden } from 'payload';
+import { assertClientUploadAccess, assertClientUploadAllowed, createClientUploadReceipt, getOriginalFilename, getSafeFileName, incrementName } from 'payload/internal';
+import { getSanitizedUploadFilename } from 'payload/shared';
+import { createImageKitUploadToken } from '../imageKitUploadToken.js';
+/** ImageKit enforces these constraints before accepting any provider-direct bytes. */ export const getUploadChecks = ({ allowedMimeTypes, allowRestrictedFileTypes, filesize })=>{
+    const checks = [
+        `"file.size" = ${filesize}`
+    ];
+    const prefixes = allowedMimeTypes.map((mimeType)=>mimeType.replace('*', '')).filter((prefix)=>!/["\\]/.test(prefix));
+    if (prefixes.length && !prefixes.includes('')) {
+        checks.push(`(${prefixes.map((prefix)=>`"file.mime" : "${prefix}"`).join(' OR ')})`);
+    }
+    if (!allowRestrictedFileTypes) {
+        checks.push('"file.mime" NOT IN ["application/atom+xml", "application/mathml+xml", "application/rdf+xml", "application/rss+xml", "application/xhtml+xml", "application/xml", "application/xslt+xml", "image/svg+xml", "text/xml"]');
+    }
+    return checks.join(' AND ');
+};
+export const createImageKitUploadInstructions = ({ access = ({ req })=>Boolean(req.user), isPrivate, prefix, privateKey, publicKey })=>async ({ collectionSlug, docPrefix, filename, filesize, mimeType, overrideAccess, req })=>{
+        if (!overrideAccess) {
+            await assertClientUploadAccess({
+                collectionSlug,
+                req
+            });
+            if (!await access({
+                collectionSlug,
+                req
+            })) {
+                throw new Forbidden(req.t);
+            }
+        }
+        const collection = req.payload.collections[collectionSlug].config;
+        assertClientUploadAllowed({
+            collection,
+            filename,
+            mimeType
+        });
+        let safeFilename = await getSafeFileName({
+            collectionSlug,
+            desiredFilename: getSanitizedUploadFilename(filename).replace(/[^\w.-]/g, '_'),
+            req
+        });
+        // Without a transformer, v4 exposes the retained original as the current file.
+        // Reserve both names so repeated uploads cannot violate filename uniqueness.
+        while(await getSafeFileName({
+            collectionSlug,
+            desiredFilename: getOriginalFilename({
+                filename: safeFilename
+            }),
+            req
+        }) !== getOriginalFilename({
+            filename: safeFilename
+        })){
+            safeFilename = incrementName(safeFilename);
+        }
+        const originalFilename = getOriginalFilename({
+            filename: safeFilename
+        });
+        const objectKey = randomUUID();
+        const resolved = buildUploadStoragePathData({
+            collectionPrefix: prefix,
+            docPrefix: docPrefix ?? prefix,
+            filename: originalFilename
+        });
+        // The admin sends an empty docPrefix for new files; the resolved destination retains the collection fallback.
+        const filePrefix = posix.dirname(resolved.storageFilePath);
+        const storageFilePath = posix.join(filePrefix, objectKey, originalFilename);
+        const uploadReference = {
+            _objectKey: objectKey,
+            prefix: filePrefix,
+            signedReceipt: createClientUploadReceipt({
+                _objectKey: objectKey,
+                collectionSlug,
+                filename: safeFilename,
+                filePrefix,
+                req,
+                storageFilePath
+            })
+        };
+        const upload = typeof collection.upload === 'object' ? collection.upload : undefined;
+        const uploadPayload = {
+            checks: getUploadChecks({
+                allowedMimeTypes: upload?.mimeTypes ?? [],
+                allowRestrictedFileTypes: upload?.allowRestrictedFileTypes ?? false,
+                filesize
+            }),
+            fileName: originalFilename,
+            folder: `/${posix.dirname(storageFilePath)}`,
+            isPrivateFile: isPrivate ? 'true' : 'false',
+            overwriteFile: 'false',
+            tags: `payload-upload-${objectKey}`,
+            useUniqueFileName: 'false'
+        };
+        return {
+            name: 'imagekit',
+            type: 'dispatch',
+            data: {
+                token: createImageKitUploadToken({
+                    privateKey,
+                    publicKey,
+                    uploadPayload
+                }),
+                uploadPayload
+            },
+            file: {
+                filename: safeFilename,
+                mimeType,
+                size: filesize,
+                uploadReference
+            }
+        };
+    };
+
+//# sourceMappingURL=createImageKitUploadInstructions.js.map

package/dist/endpoints/createImageKitUploadInstructions.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/endpoints/createImageKitUploadInstructions.ts"],"sourcesContent":["import type { GenerateUploadInstructions, UploadInstructionsAccess } from 'payload'\n\nimport { buildUploadStoragePathData } from '@payloadcms/plugin-cloud-storage/utilities'\nimport { randomUUID } from 'node:crypto'\nimport { posix } from 'node:path'\nimport { Forbidden } from 'payload'\nimport {\n  assertClientUploadAccess,\n  assertClientUploadAllowed,\n  createClientUploadReceipt,\n  getOriginalFilename,\n  getSafeFileName,\n  incrementName,\n} from 'payload/internal'\nimport { getSanitizedUploadFilename } from 'payload/shared'\n\nimport type { ImageKitUploadPayload } from '../clientUploads.js'\n\nimport { createImageKitUploadToken } from '../imageKitUploadToken.js'\n\n/** ImageKit enforces these constraints before accepting any provider-direct bytes. */\nexport const getUploadChecks = ({\n  allowedMimeTypes,\n  allowRestrictedFileTypes,\n  filesize,\n}: {\n  allowedMimeTypes: string[]\n  allowRestrictedFileTypes: boolean\n  filesize: number\n}): string => {\n  const checks = [`\"file.size\" = ${filesize}`]\n  const prefixes = allowedMimeTypes\n    .map((mimeType) => mimeType.replace('*', ''))\n    .filter((prefix) => !/[\"\\\\]/.test(prefix))\n\n  if (prefixes.length && !prefixes.includes('')) {\n    checks.push(`(${prefixes.map((prefix) => `\"file.mime\" : \"${prefix}\"`).join(' OR ')})`)\n  }\n  if (!allowRestrictedFileTypes) {\n    checks.push(\n      '\"file.mime\" NOT IN [\"application/atom+xml\", \"application/mathml+xml\", \"application/rdf+xml\", \"application/rss+xml\", \"application/xhtml+xml\", \"application/xml\", \"application/xslt+xml\", \"image/svg+xml\", \"text/xml\"]',\n    )\n  }\n  return checks.join(' AND ')\n}\n\nexport const createImageKitUploadInstructions =\n  ({\n    access = ({ req }) => Boolean(req.user),\n    isPrivate,\n    prefix,\n    privateKey,\n    publicKey,\n  }: {\n    access?: UploadInstructionsAccess\n    isPrivate: boolean\n    prefix: string\n    privateKey: string\n    publicKey: string\n  }): GenerateUploadInstructions =>\n  async ({ collectionSlug, docPrefix, filename, filesize, mimeType, overrideAccess, req }) => {\n    if (!overrideAccess) {\n      await assertClientUploadAccess({ collectionSlug, req })\n      if (!(await access({ collectionSlug, req }))) {\n        throw new Forbidden(req.t)\n      }\n    }\n    const collection = req.payload.collections[collectionSlug].config\n    assertClientUploadAllowed({ collection, filename, mimeType })\n    let safeFilename = await getSafeFileName({\n      collectionSlug,\n      desiredFilename: getSanitizedUploadFilename(filename).replace(/[^\\w.-]/g, '_'),\n      req,\n    })\n    // Without a transformer, v4 exposes the retained original as the current file.\n    // Reserve both names so repeated uploads cannot violate filename uniqueness.\n    while (\n      (await getSafeFileName({\n        collectionSlug,\n        desiredFilename: getOriginalFilename({ filename: safeFilename }),\n        req,\n      })) !== getOriginalFilename({ filename: safeFilename })\n    ) {\n      safeFilename = incrementName(safeFilename)\n    }\n    const originalFilename = getOriginalFilename({ filename: safeFilename })\n    const objectKey = randomUUID()\n    const resolved = buildUploadStoragePathData({\n      collectionPrefix: prefix,\n      docPrefix: docPrefix ?? prefix,\n      filename: originalFilename,\n    })\n    // The admin sends an empty docPrefix for new files; the resolved destination retains the collection fallback.\n    const filePrefix = posix.dirname(resolved.storageFilePath)\n    const storageFilePath = posix.join(filePrefix, objectKey, originalFilename)\n    const uploadReference = {\n      _objectKey: objectKey,\n      prefix: filePrefix,\n      signedReceipt: createClientUploadReceipt({\n        _objectKey: objectKey,\n        collectionSlug,\n        filename: safeFilename,\n        filePrefix,\n        req,\n        storageFilePath,\n      }),\n    }\n    const upload = typeof collection.upload === 'object' ? collection.upload : undefined\n    const uploadPayload: ImageKitUploadPayload = {\n      checks: getUploadChecks({\n        allowedMimeTypes: upload?.mimeTypes ?? [],\n        allowRestrictedFileTypes: upload?.allowRestrictedFileTypes ?? false,\n        filesize,\n      }),\n      fileName: originalFilename,\n      folder: `/${posix.dirname(storageFilePath)}`,\n      isPrivateFile: isPrivate ? 'true' : 'false',\n      overwriteFile: 'false',\n      tags: `payload-upload-${objectKey}`,\n      useUniqueFileName: 'false',\n    }\n    return {\n      name: 'imagekit',\n      type: 'dispatch',\n      data: {\n        token: createImageKitUploadToken({ privateKey, publicKey, uploadPayload }),\n        uploadPayload,\n      },\n      file: { filename: safeFilename, mimeType, size: filesize, uploadReference },\n    }\n  }\n"],"names":["buildUploadStoragePathData","randomUUID","posix","Forbidden","assertClientUploadAccess","assertClientUploadAllowed","createClientUploadReceipt","getOriginalFilename","getSafeFileName","incrementName","getSanitizedUploadFilename","createImageKitUploadToken","getUploadChecks","allowedMimeTypes","allowRestrictedFileTypes","filesize","checks","prefixes","map","mimeType","replace","filter","prefix","test","length","includes","push","join","createImageKitUploadInstructions","access","req","Boolean","user","isPrivate","privateKey","publicKey","collectionSlug","docPrefix","filename","overrideAccess","t","collection","payload","collections","config","safeFilename","desiredFilename","originalFilename","objectKey","resolved","collectionPrefix","filePrefix","dirname","storageFilePath","uploadReference","_objectKey","signedReceipt","upload","undefined","uploadPayload","mimeTypes","fileName","folder","isPrivateFile","overwriteFile","tags","useUniqueFileName","name","type","data","token","file","size"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,47 +1,25 @@
 import type { ClientUploadsConfig } from '@payloadcms/plugin-cloud-storage/types';
-import type { Config, UploadCollectionSlug } from 'payload';
+import type { StorageAdapter, UploadCollectionSlug } from 'payload';
 export type ImageKitCollectionOptions = {
-    /**
-     * Override Payload's native focal-point picker (`upload.focalPoint`) for this
-     * collection.
-     */
     focalPoint?: boolean;
-    /**
-     * Upload files in this collection as ImageKit private files (`isPrivateFile: true`)
-     * and deliver them only through short-lived signed URLs, behind Payload access control.
-     */
     private?: boolean;
 };
-type ImageKitCollectionConfig = ImageKitCollectionOptions | true;
-type ImageKitCollectionMap = Partial<Record<UploadCollectionSlug, ImageKitCollectionConfig>>;
 export type PayloadStorageImageKitConfig = {
-    alwaysInsertFields?: boolean;
     clientUploads?: ClientUploadsConfig;
-    collections: ImageKitCollectionMap;
+    collections: Partial<Record<UploadCollectionSlug, ImageKitCollectionOptions | true>>;
     disablePayloadAccessControl?: true;
     enabled?: boolean;
-    /**
-     * 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 collection-level `focalPoint: true` for
-     * image collections. A collection's own `upload.focalPoint` still takes
-     * precedence.
-     */
     focalPoint?: boolean;
     folder: string;
     privateKey: string;
     publicKey: string;
-    /**
-     * Expiry (in seconds) applied to signed URLs generated for private collections.
-     * Defaults to 900 (15 minutes). URLs are signed fresh on every request, so a short
-     * window is safe.
-     */
     signedUrlExpiresIn?: number;
     urlEndpoint: string;
 };
-export declare const imagekitStorage: (pluginOptions: PayloadStorageImageKitConfig) => (config: Config) => Config;
+/** Payload 4 storage capability. Register under config.storage, not config.plugins. */
+export declare const imagekitStorage: (options: PayloadStorageImageKitConfig) => StorageAdapter;
 export { migrateFolder } from './migrate.js';
 export type { MigrateFolderOptions, MigrationJobResult, MigrationLocation } from './migrate.js';
-export declare const payloadStorageImagekit: (pluginOptions: PayloadStorageImageKitConfig) => (config: Config) => Config;
-export declare const payloadStorageImageKit: (pluginOptions: PayloadStorageImageKitConfig) => (config: Config) => Config;
+export declare const payloadStorageImagekit: (options: PayloadStorageImageKitConfig) => StorageAdapter;
+export declare const payloadStorageImageKit: (options: PayloadStorageImageKitConfig) => StorageAdapter;
 export type PayloadStorageImagekitConfig = PayloadStorageImageKitConfig;