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

package/dist/index.js

@@ -1,691 +1,516 @@
 import ImageKit, { toFile } from '@imagekit/nodejs';
 import { cloudStoragePlugin } from '@payloadcms/plugin-cloud-storage';
-import { buildStoragePathData, buildUploadStoragePathData, getStorageFilePath, initClientUploads } from '@payloadcms/plugin-cloud-storage/utilities';
+import { buildStoragePathData } from '@payloadcms/plugin-cloud-storage/utilities';
 import { openAsBlob } from 'node:fs';
 import path from 'node:path';
 import { APIError } from 'payload';
-import { getRangeRequestInfo, isXmlMimeType, UPLOAD_CONTENT_SECURITY_POLICY } from 'payload/internal';
-import { validateMimeType } from 'payload/shared';
-import { imageKitUploadAuthPath, isImageKitReceiptContext } from './clientUploads.js';
-import { createImageKitClientUploadVerifier, getClientUploadStorageFilePath } from './clientUploadVerification.js';
-import { createImageKitUploadAuthHandler } from './endpoints/createImageKitUploadAuthHandler.js';
+import { assertClientUploadAllowed, getRangeRequestInfo, isXmlMimeType, uploadContentSecurityPolicy, verifyClientUploadReceipt } from 'payload/internal';
+import { completeImageKitUpload } from './endpoints/completeImageKitUpload.js';
+import { createImageKitUploadInstructions } from './endpoints/createImageKitUploadInstructions.js';
 import { getAdminThumbnailURL, getPrivateAdminThumbnailURL, isPdfMimeType, isVideoMimeType } from './getAdminThumbnailURL.js';
+import { createImageKitFileStore } from './imageKitFileStore.js';
 import { getImageKitThumbnailSrc, getVideoPosterSrc } from './imageTransforms.js';
-const DEFAULT_SIGNED_URL_EXPIRES_IN = 900;
-/**
- * ImageKit re-encodes some uploads and serves the smaller derivative from the plain
- * delivery URL — a 1.9 MB MP4 can come back as 868 KB. That is exactly what we want
- * for visitors, but not when reading the file back to verify a client upload: the
- * bytes and the byte count would both belong to a file ImageKit's API never reported.
- * `orig-true` asks for the untouched original and does not disable optimisation for
- * anyone else.
- */ const ORIGINAL_FILE_TRANSFORMATION = 'orig-true';
-const PRIVATE_COLLECTION_DESCRIPTION = 'Files in this collection are uploaded to ImageKit as private files and delivered through short-lived signed URLs.';
-const isPrivateCollectionConfig = (value)=>value !== true && typeof value === 'object' && value?.private === true;
-const XML_FAMILY_MIME_TYPES = [
-    'application/xml',
-    'image/svg+xml',
-    'text/xml'
-];
-const collectionCanStoreXml = (collection)=>{
-    const upload = collection.upload;
-    if (!upload || upload === true) {
-        return Boolean(upload);
-    }
-    // Payload skips MIME and content restrictions when this escape hatch is enabled.
-    if (upload.allowRestrictedFileTypes) {
-        return true;
-    }
-    const allowedMimeTypes = upload.mimeTypes;
-    return !allowedMimeTypes?.length || allowedMimeTypes.some((mimeType)=>mimeType.includes('*') || isXmlMimeType(mimeType)) || XML_FAMILY_MIME_TYPES.some((mimeType)=>validateMimeType(mimeType, allowedMimeTypes));
-};
-/**
- * Whether a specific document is private. The flag stored on the document at upload time
- * (`imagekit.isPrivate`) is the source of truth — a file's privacy on ImageKit is fixed
- * when it is uploaded and does not change if the collection's `private` setting changes
- * later. Falls back to the collection setting for documents uploaded before this flag existed.
- */ const isDocumentPrivate = (doc, collectionIsPrivate)=>{
-    const stored = doc?.imagekit?.isPrivate;
-    return typeof stored === 'boolean' ? stored : collectionIsPrivate;
-};
-const normalizeFolder = (folder)=>{
-    const normalized = folder.trim().replace(/^\/+|\/+$/g, '');
-    if (!normalized) {
-        throw new Error('imagekitStorage: `folder` is required.');
-    }
-    return `/${normalized}`;
-};
-const getCollectionFolder = (rootFolder, collectionSlug)=>path.posix.join(rootFolder, collectionSlug);
-const findImageKitFileId = async (imagekit, filePath)=>{
-    const parentPath = path.posix.dirname(filePath);
-    const name = path.posix.basename(filePath);
-    const limit = 100;
-    for(let skip = 0;; skip += limit){
-        const assets = await imagekit.assets.list({
-            type: 'file',
-            limit,
-            path: parentPath === '/' ? '/' : `${parentPath}/`,
-            skip
-        });
-        const found = assets.find((asset)=>'fileId' in asset && asset.filePath === filePath && asset.name === name);
-        if (found && 'fileId' in found) {
-            return found.fileId;
-        }
-        if (assets.length < limit) {
-            break;
+/** Payload 4 storage capability. Register under config.storage, not config.plugins. */ export const imagekitStorage = (options)=>({
+        name: 'imagekit',
+        collections: Object.keys(options.collections),
+        init: (config)=>initializeStorage(config, options)
+    });
+export { migrateFolder } from './migrate.js';
+export const payloadStorageImagekit = imagekitStorage;
+export const payloadStorageImageKit = imagekitStorage;
+function initializeStorage(config, options) {
+    for (const key of [
+        'privateKey',
+        'publicKey',
+        'urlEndpoint',
+        'folder'
+    ]){
+        if (!options[key]?.trim()) {
+            throw new Error(`imagekitStorage: \`${key}\` is required.`);
         }
     }
-    return undefined;
-};
-const isRecord = (value)=>!!value && typeof value === 'object';
-const getStoredImageKitURL = (doc)=>{
-    const storedURL = doc?.imagekit?.url;
-    return typeof storedURL === 'string' && storedURL.trim().length > 0 ? storedURL : undefined;
-};
-const hasStoredImageKitURL = (doc)=>!!getStoredImageKitURL(doc);
-const findUploadDocumentByFilename = async ({ collection, filename, prefix, req })=>{
-    const constraints = [
-        {
-            filename: {
-                equals: filename
-            }
-        }
-    ];
-    if (typeof prefix === 'string') {
-        constraints.push({
-            prefix: {
-                equals: prefix
-            }
-        });
+    const folder = options.folder.trim().replace(/^\/+|\/+$/g, '');
+    if (folder.split('/').some((segment)=>!segment || segment === '.' || segment === '..')) {
+        throw new Error('imagekitStorage: `folder` must not contain empty or dot segments.');
     }
-    return req.payload.db.findOne({
-        collection,
-        req,
-        where: {
-            and: constraints
-        }
+    const client = new ImageKit({
+        privateKey: options.privateKey
     });
-};
-const applyVerifiedClientUploadToData = (data, uploaded, buildThumbnailURL = getAdminThumbnailURL, isPrivate)=>{
-    data.imagekit = {
-        fileId: uploaded.fileId,
-        isPrivate,
-        thumbnailUrl: uploaded.thumbnailUrl,
-        url: uploaded.url
+    const collections = options.collections;
+    if (!Object.keys(collections).length) {
+        throw new Error('imagekitStorage: `collections` must not be empty.');
+    }
+    const configured = new Set(Object.keys(collections));
+    const apiRoute = config.routes?.api ?? '/api';
+    const expiresIn = options.signedUrlExpiresIn ?? 900;
+    const prefixFor = (slug)=>path.posix.join(folder, slug);
+    const collectionIsPrivate = (slug)=>{
+        const value = collections[slug];
+        return value !== true && value?.private === true;
     };
-    // Preserve the admin preview when the original file was already uploaded client-side.
-    data.thumbnailURL = buildThumbnailURL(data);
-    return data;
-};
-const imagekitAdapter = ({ apiRoute, client, clientUploads, privateSlugs, rootFolder, signedUrlExpiresIn, urlEndpoint, verifyClientUpload })=>{
-    const fetchUploadedFile = async ({ fileSize, fileURL, mimeType, range })=>{
-        const rangeResult = getRangeRequestInfo({
-            fileSize,
-            rangeHeader: range ?? null
-        });
-        if (rangeResult.type === 'invalid') {
-            return new Response(null, {
-                headers: new Headers(rangeResult.headers),
-                status: rangeResult.status
-            });
-        }
-        const normalizedRange = rangeResult.type === 'partial' ? `bytes=${rangeResult.rangeStart}-${rangeResult.rangeEnd}` : undefined;
-        // Payload cancels image probes after reading a bounded prefix. Next.js memoizes
-        // GET responses by teeing their streams; cancelling one branch can then wait
-        // forever for its unread cached sibling. An explicit signal opts out of that
-        // memoization, while no-store also excludes these reads from the data cache.
-        const response = await fetch(fileURL, {
-            cache: 'no-store',
-            ...normalizedRange ? {
-                headers: {
-                    Range: normalizedRange
+    const files = createImageKitFileStore(client, options.urlEndpoint);
+    const completeUpload = completeImageKitUpload({
+        access: typeof options.clientUploads === 'object' ? options.clientUploads.access : undefined,
+        collections: Object.fromEntries(Object.keys(collections).map((slug)=>[
+                slug,
+                {
+                    isPrivate: collectionIsPrivate(slug),
+                    prefix: prefixFor(slug)
                 }
-            } : {},
-            signal: new AbortController().signal
-        });
-        if (!response.ok || response.status !== rangeResult.status) {
-            void response.body?.cancel().catch(()=>undefined);
-            throw new Error(`imagekitStorage: ImageKit returned an unexpected file response (${response.status}).`);
-        }
-        const upstreamLength = response.headers.get('Content-Length');
-        const expectedLength = rangeResult.headers['Content-Length'];
-        const upstreamRange = response.headers.get('Content-Range');
-        const expectedRange = rangeResult.type === 'partial' ? rangeResult.headers['Content-Range'] : undefined;
-        if (upstreamLength !== null && upstreamLength !== expectedLength || expectedRange && upstreamRange !== expectedRange) {
-            void response.body?.cancel().catch(()=>undefined);
-            throw new Error('imagekitStorage: ImageKit returned mismatched file content metadata.');
-        }
-        const headers = new Headers(rangeResult.headers);
-        headers.set('Content-Type', mimeType);
-        if (isXmlMimeType(mimeType)) {
-            headers.set('Content-Security-Policy', UPLOAD_CONTENT_SECURITY_POLICY);
-        }
-        return new Response(response.body, {
-            headers,
-            status: response.status
-        });
+            ])),
+        files
+    });
+    const sourceConfig = {
+        ...config,
+        collections: (config.collections ?? []).map((collection)=>{
+            if (!configured.has(collection.slug)) {
+                return collection;
+            }
+            const isPrivate = collectionIsPrivate(collection.slug);
+            if (options.disablePayloadAccessControl && (isPrivate || canStoreXml(collection))) {
+                throw new Error('imagekitStorage: private and XML-capable collections require Payload access control.');
+            }
+            const setting = collections[collection.slug];
+            const focalPoint = setting !== true ? setting?.focalPoint : undefined;
+            const description = collection.admin?.description;
+            return {
+                ...collection,
+                admin: isPrivate ? {
+                    ...collection.admin,
+                    description: typeof description === 'string' ? `${description} Files in this collection are uploaded to ImageKit as private files and delivered through short-lived signed URLs.` : description ?? 'Files in this collection are uploaded to ImageKit as private files and delivered through short-lived signed URLs.'
+                } : collection.admin,
+                hooks: {
+                    ...collection.hooks,
+                    beforeChange: [
+                        ...collection.hooks?.beforeChange ?? [],
+                        async ({ data, operation, originalDoc, req })=>{
+                            if (operation === 'validate') {
+                                return data;
+                            }
+                            const verified = req.context.imagekitVerifiedUpload;
+                            if (!verified) {
+                                return data;
+                            }
+                            const existing = await req.payload.db.findOne({
+                                // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- Generated consumer configs narrow CollectionSlug, unlike the standalone package build.
+                                collection: collection.slug,
+                                req,
+                                where: {
+                                    'imagekit.fileId': {
+                                        equals: verified.fileId
+                                    }
+                                }
+                            });
+                            if (existing && existing.id !== originalDoc?.id) {
+                                throw new APIError('This ImageKit upload reference has already been used.', 400);
+                            }
+                            return applyMetadata(data, verified, isPrivate, collection.slug, apiRoute);
+                        }
+                    ]
+                },
+                upload: {
+                    focalPoint: focalPoint ?? options.focalPoint ?? false,
+                    ...typeof collection.upload === 'object' ? collection.upload : {},
+                    adminThumbnail: ({ doc })=>isPrivateDocument(doc, isPrivate) ? getPrivateAdminThumbnailURL(doc, collection.slug, apiRoute) : getAdminThumbnailURL(doc),
+                    crop: false
+                }
+            };
+        })
     };
-    return ({ collection, prefix = getCollectionFolder(rootFolder, collection.slug) })=>{
-        const isPrivate = privateSlugs.has(collection.slug);
-        // Sign a relative ImageKit path against the configured urlEndpoint. We always sign
-        // a computed path (never a stored absolute URL) because ImageKit's signature is
-        // derived from the path after stripping urlEndpoint, so the host must match.
-        const buildSignedURL = (src, tr)=>client.helper.buildSrc({
-                expiresIn: signedUrlExpiresIn,
-                signed: true,
-                src,
-                transformation: tr ? [
+    const adapter = ({ collection, prefix = prefixFor(collection.slug) })=>{
+        const isPrivate = collectionIsPrivate(collection.slug);
+        const buildURL = (key, signed, transformation)=>client.helper.buildSrc({
+                expiresIn: signed ? expiresIn : undefined,
+                signed,
+                src: `/${key.replace(/^\/+/, '')}`,
+                transformation: transformation ? [
                     {
-                        raw: tr
+                        raw: transformation
                     }
                 ] : undefined,
-                urlEndpoint
+                urlEndpoint: options.urlEndpoint
+            });
+        const deleteFile = ({ req, storageFilePath })=>files.remove({
+                key: storageFilePath,
+                req
             });
-        const buildThumbnailURL = (doc)=>isDocumentPrivate(doc, isPrivate) ? getPrivateAdminThumbnailURL(doc, collection.slug, apiRoute) : getAdminThumbnailURL(doc);
         return {
             name: 'imagekit',
-            clientUploads,
-            fields: [
-                {
-                    // Presentational wrapper: tucks the ImageKit details into a closed panel without
-                    // changing the `imagekit.*` data paths.
-                    type: 'collapsible',
-                    admin: {
-                        condition: (data)=>hasStoredImageKitURL(data),
-                        initCollapsed: true
-                    },
-                    fields: [
-                        {
-                            name: 'imagekit',
-                            type: 'group',
-                            admin: {
-                                disableListColumn: true,
-                                disableListFilter: true
-                            },
-                            fields: [
-                                {
-                                    name: 'fileId',
-                                    type: 'text',
-                                    admin: {
-                                        hidden: true
-                                    }
-                                },
-                                {
-                                    name: 'url',
-                                    type: 'text',
-                                    admin: {
-                                        readOnly: true
-                                    },
-                                    label: 'URL'
-                                },
-                                {
-                                    name: 'isPrivate',
-                                    type: 'checkbox',
-                                    admin: {
-                                        condition: (_data, siblingData)=>isDocumentPrivate({
-                                                imagekit: siblingData
-                                            }, isPrivate),
-                                        description: "Indicates whether this file was uploaded to ImageKit as private. Private files are delivered through signed URLs. Changes to this collection's private option in payload.config only affect future uploads.",
-                                        readOnly: true
-                                    },
-                                    label: 'Private file'
-                                },
-                                {
-                                    name: 'signedUrl',
-                                    type: 'text',
-                                    admin: {
-                                        // Only relevant for private files; the plain `url` works directly for public ones.
-                                        condition: (_data, siblingData)=>isDocumentPrivate({
-                                                imagekit: siblingData
-                                            }, isPrivate),
-                                        description: `Temporary signed URL for reaching this private file directly on ImageKit. Expires ${signedUrlExpiresIn} seconds after load and is regenerated on every read. Note: anyone with this URL can access the file until it expires — it is not gated by Payload access control.`,
-                                        readOnly: true
-                                    },
-                                    hooks: {
-                                        // Computed server-side on read so it is always freshly signed and never persisted.
-                                        afterRead: [
-                                            ({ data, siblingData })=>{
-                                                if (!isDocumentPrivate({
-                                                    imagekit: siblingData
-                                                }, isPrivate)) {
-                                                    return undefined;
-                                                }
-                                                const filename = data?.filename;
-                                                if (!filename) {
-                                                    return undefined;
-                                                }
-                                                const source = data || {};
-                                                const documentPrefix = path.posix.join(source.prefix || prefix, source._objectKey || '');
-                                                const storageFilePath = buildStoragePathData({
-                                                    collectionPrefix: prefix,
-                                                    docPrefix: documentPrefix,
-                                                    filename
-                                                }).storageFilePath;
-                                                return buildSignedURL(`/${storageFilePath}`);
-                                            }
-                                        ]
-                                    },
-                                    label: 'Signed URL',
-                                    virtual: true
-                                },
-                                {
-                                    name: 'thumbnailUrl',
-                                    type: 'text',
-                                    admin: {
-                                        hidden: true
-                                    }
-                                }
-                            ],
-                            interfaceName: 'imagekitFields',
-                            label: false
-                        }
-                    ],
-                    label: 'Storage: ImageKit'
+            copyFile: async ({ from, req, to })=>{
+                if (await files.find({
+                    key: to,
+                    req
+                })) {
+                    throw new Error(`ImageKit destination already exists: ${to}`);
                 }
-            ],
-            generateURL: ({ filename, prefix: documentPrefix = '' })=>client.helper.buildSrc({
-                    src: `/${buildStoragePathData({
-                        collectionPrefix: prefix,
-                        docPrefix: documentPrefix,
-                        filename
-                    }).storageFilePath}`,
-                    urlEndpoint
-                }),
-            handleDelete: async ({ doc, storageFilePath })=>{
-                const storedFileId = doc.imagekit?.fileId;
-                const fileId = storedFileId || await findImageKitFileId(client, `/${storageFilePath.replace(/^\/+/, '')}`);
-                if (!fileId) {
-                    return;
+                const source = await files.find({
+                    key: from,
+                    req
+                });
+                if (!source) {
+                    throw new Error(`ImageKit source not found: ${from}`);
                 }
-                await client.files.delete(fileId);
+                // Upload by URL copies the exact original without buffering it in the app process.
+                // overwriteFile:false protects a destination created concurrently with the lookup.
+                await files.upload({
+                    body: {
+                        customMetadata: source.customMetadata ?? undefined,
+                        file: buildURL(from, Boolean(source.isPrivateFile), 'orig-true'),
+                        fileName: path.posix.basename(to),
+                        folder: `/${path.posix.dirname(to)}`,
+                        isPrivateFile: source.isPrivateFile ?? false,
+                        overwriteFile: false,
+                        tags: source.tags ?? undefined,
+                        useUniqueFileName: false
+                    },
+                    key: to,
+                    req
+                });
             },
-            handleUpload: async ({ clientUploadContext, data, file, storageFilePath })=>{
-                if (clientUploadContext) {
-                    const uploaded = await verifyClientUpload({
-                        collectionSlug: collection.slug,
-                        context: clientUploadContext
-                    });
-                    return applyVerifiedClientUploadToData(data, uploaded, buildThumbnailURL, isPrivate);
-                }
-                // ImageKit's `toFile()` consumes async iterables before starting the request. A file-backed
-                // Blob keeps temporary-file uploads lazy so FormData can stream them from disk instead.
+            deleteFile,
+            fields: storageFields({
+                buildURL,
+                expiresIn,
+                isPrivate,
+                prefix
+            }),
+            generateURL: ({ filename, prefix: docPrefix })=>buildURL(buildStoragePathData({
+                    collectionPrefix: prefix,
+                    docPrefix,
+                    filename
+                }).storageFilePath, false),
+            handleDelete: deleteFile,
+            handleUpload: async ({ data, file, req, storageFilePath })=>{
                 const uploadSource = file.tempFilePath ? await openAsBlob(file.tempFilePath, {
                     type: file.mimeType
                 }) : file.buffer;
-                const uploadFile = await toFile(uploadSource, file.filename, {
-                    type: file.mimeType
-                });
-                const uploadFolder = path.posix.dirname(`/${storageFilePath.replace(/^\/+/, '')}`);
-                const uploadFilename = path.posix.basename(storageFilePath);
-                const uploaded = await client.files.upload({
-                    file: uploadFile,
-                    fileName: uploadFilename,
-                    folder: uploadFolder,
-                    useUniqueFileName: false,
-                    ...isPrivate ? {
-                        isPrivateFile: true
-                    } : {}
+                const uploaded = await files.upload({
+                    body: {
+                        file: await toFile(uploadSource, file.filename, {
+                            type: file.mimeType
+                        }),
+                        fileName: path.posix.basename(storageFilePath),
+                        folder: `/${path.posix.dirname(storageFilePath)}`,
+                        isPrivateFile: isPrivate,
+                        overwriteFile: false,
+                        useUniqueFileName: false
+                    },
+                    key: storageFilePath,
+                    req
                 });
-                data.imagekit = {
+                return applyMetadata(data, {
+                    name: path.posix.basename(storageFilePath),
                     fileId: uploaded.fileId,
-                    isPrivate,
-                    thumbnailUrl: uploaded.thumbnailUrl,
+                    isPrivateFile: isPrivate,
+                    mime: file.mimeType,
+                    size: file.filesize,
+                    thumbnail: uploaded.thumbnailUrl,
                     url: uploaded.url
-                };
-                // Set the root-level thumbnailURL that Payload's admin interface expects.
-                // `buildThumbnailURL` needs the filename, which Payload may not have copied onto
-                // `data` yet at this point, so fall back to the uploaded file's name.
-                data.thumbnailURL = buildThumbnailURL({
-                    ...data,
-                    filename: data.filename || uploadFilename
-                });
-                return data;
+                }, isPrivate, collection.slug, apiRoute);
             },
-            requiresClientUploadReceipt: true,
-            staticHandler: async (req, args)=>{
-                const requestURL = new URL(req.url || 'http://localhost');
-                const tr = requestURL.searchParams.get('tr');
-                const hasClientUploadContext = 'clientUploadContext' in args.params;
-                if (hasClientUploadContext) {
-                    const clientUploadContext = args.params.clientUploadContext;
-                    if (!isImageKitReceiptContext(clientUploadContext)) {
-                        throw new APIError('Invalid ImageKit client upload context.', 400);
+            staticHandler: async (req, { doc, params })=>{
+                if (params.uploadReference) {
+                    try {
+                        const reference = params.uploadReference;
+                        const receipt = verifyClientUploadReceipt({
+                            collectionSlug: collection.slug,
+                            req,
+                            signedReceipt: reference.signedReceipt
+                        });
+                        const expectedPath = buildStoragePathData({
+                            collectionPrefix: prefix,
+                            docPrefix: path.posix.join(receipt.filePrefix, receipt._objectKey ?? ''),
+                            filename: params.filename
+                        }).storageFilePath;
+                        if (!receipt._objectKey || expectedPath !== receipt.storageFilePath || !expectedPath.startsWith(`${prefix.replace(/^\/+/, '')}/`)) {
+                            throw new APIError('Invalid ImageKit upload reference.', 400);
+                        }
+                        const uploaded = await findUploadedFile(files, expectedPath, req);
+                        if (!uploaded || !uploaded.mime || Boolean(uploaded.isPrivateFile) !== isPrivate) {
+                            throw new APIError('ImageKit upload did not match its authorization.', 400);
+                        }
+                        assertClientUploadAllowed({
+                            collection,
+                            filename: uploaded.name,
+                            mimeType: uploaded.mime
+                        });
+                        req.context.imagekitVerifiedUpload = uploaded;
+                        return await fetchOriginal({
+                            file: uploaded,
+                            req,
+                            url: buildURL(expectedPath, isPrivate, 'orig-true')
+                        });
+                    } catch (error) {
+                        if (error instanceof APIError) {
+                            return Response.json({
+                                message: error.message
+                            }, {
+                                status: error.status
+                            });
+                        }
+                        throw error;
                     }
-                    const uploadedFile = await verifyClientUpload({
-                        collectionSlug: collection.slug,
-                        context: clientUploadContext
-                    });
-                    const expectedFilePath = getClientUploadStorageFilePath({
-                        collectionPrefix: prefix,
-                        context: clientUploadContext
-                    });
-                    const verifiedFileURL = isPrivate ? buildSignedURL(`/${expectedFilePath}`, ORIGINAL_FILE_TRANSFORMATION) : client.helper.buildSrc({
-                        src: `/${expectedFilePath}`,
-                        transformation: [
-                            {
-                                raw: ORIGINAL_FILE_TRANSFORMATION
-                            }
-                        ],
-                        urlEndpoint
-                    });
-                    return fetchUploadedFile({
-                        fileSize: uploadedFile.size,
-                        fileURL: verifiedFileURL,
-                        mimeType: uploadedFile.mimeType,
-                        range: req.headers.get('Range')
-                    });
                 }
-                const doc = args.doc || await findUploadDocumentByFilename({
-                    collection: args.params.collection,
-                    filename: args.params.filename,
-                    prefix: args.params.prefix,
-                    req
+                const document = doc ?? await req.payload.db.findOne({
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- Generated consumer configs narrow CollectionSlug, unlike the standalone package build.
+                    collection: collection.slug,
+                    req,
+                    where: {
+                        filename: {
+                            equals: params.filename
+                        }
+                    }
                 });
-                const storageFilePath = await getStorageFilePath({
-                    collection,
+                const source = getFileLocation(document, params.filename);
+                const key = buildStoragePathData({
                     collectionPrefix: prefix,
-                    doc: doc || undefined,
-                    filename: args.params.filename,
-                    prefixQueryParam: args.params.prefix,
-                    req
-                });
-                const imageKitPath = `/${storageFilePath.replace(/^\/+/, '')}`;
-                const mimeType = doc?.mimeType;
-                // XML-family uploads (including SVG) must pass through Payload so its CSP is
-                // present even when ImageKit uses a custom, same-origin delivery domain.
-                if (typeof mimeType === 'string' && isXmlMimeType(mimeType)) {
-                    const filesize = doc?.filesize;
-                    if (typeof filesize !== 'number' || !Number.isSafeInteger(filesize) || filesize < 0) {
-                        throw new APIError('Stored ImageKit file metadata is incomplete.', 500);
-                    }
-                    const fileURL = isDocumentPrivate(doc, isPrivate) ? buildSignedURL(imageKitPath, ORIGINAL_FILE_TRANSFORMATION) : client.helper.buildSrc({
-                        src: imageKitPath,
-                        transformation: [
-                            {
-                                raw: ORIGINAL_FILE_TRANSFORMATION
-                            }
-                        ],
-                        urlEndpoint
+                    docPrefix: path.posix.join(params.prefix ?? source.prefix ?? prefix, source._objectKey ?? ''),
+                    filename: params.filename
+                }).storageFilePath;
+                const privateFile = isPrivateDocument(document, isPrivate);
+                if (params.operation === 'transform' || isXmlMimeType(source.mimeType ?? '')) {
+                    const file = await files.find({
+                        key,
+                        req
                     });
-                    return fetchUploadedFile({
-                        fileSize: filesize,
-                        fileURL,
-                        mimeType,
-                        range: req.headers.get('Range')
+                    if (!file?.mime) {
+                        throw new APIError('ImageKit source not found.', 404);
+                    }
+                    return fetchOriginal({
+                        file,
+                        req,
+                        url: buildURL(key, privateFile, 'orig-true')
                     });
                 }
-                // Sign based on the document's stored status, not the collection's current
-                // setting, so files keep working if the collection's privacy is changed later.
-                if (isDocumentPrivate(doc, isPrivate)) {
-                    let signSrc = imageKitPath;
-                    // A `tr` request for a video/PDF is a thumbnail request (the plain transform
-                    // can't render a preview); serve ImageKit's generated thumbnail instead.
-                    if (tr && isVideoMimeType(mimeType)) {
-                        signSrc = getVideoPosterSrc(signSrc);
-                    } else if (tr && isPdfMimeType(mimeType)) {
-                        signSrc = getImageKitThumbnailSrc(signSrc);
-                    }
-                    return Response.redirect(buildSignedURL(signSrc, tr), 302);
+                const tr = new URL(req.url ?? 'http://localhost').searchParams.get('tr');
+                let src = key;
+                if (tr && isVideoMimeType(source.mimeType)) {
+                    src = getVideoPosterSrc(src);
+                } else if (tr && isPdfMimeType(source.mimeType)) {
+                    src = getImageKitThumbnailSrc(src);
                 }
-                const imageKitURL = client.helper.buildSrc({
-                    src: getStoredImageKitURL(doc) || imageKitPath,
-                    transformation: tr ? [
-                        {
-                            raw: tr
-                        }
-                    ] : undefined,
-                    urlEndpoint
-                });
-                return Response.redirect(imageKitURL, 302);
+                // Existing v3 files may live under an earlier folder or delivery endpoint.
+                const storedURL = document?.imagekit?.url;
+                if (!privateFile && !tr && !(document && 'original' in document && document.original) && storedURL) {
+                    return Response.redirect(storedURL, 302);
+                }
+                return Response.redirect(buildURL(src, privateFile, tr), 302);
+            },
+            supportsTempFiles: true,
+            uploadInstructions: {
+                adminHandler: {
+                    path: '@humaan/payload-storage-imagekit/client#ImageKitUploadHandler'
+                },
+                enabled: options.enabled !== false && Boolean(options.clientUploads),
+                endpoint: {
+                    handler: completeUpload,
+                    path: '/imagekit-upload-complete'
+                },
+                generate: createImageKitUploadInstructions({
+                    access: typeof options.clientUploads === 'object' ? options.clientUploads.access : undefined,
+                    isPrivate,
+                    prefix,
+                    privateKey: options.privateKey,
+                    publicKey: options.publicKey
+                }),
+                requiresUploadReceipt: true,
+                useInAdmin: true
             }
         };
     };
-};
-const toCloudStorageCollections = (collections, adapter, privateSlugs, rootFolder, disablePayloadAccessControl)=>{
-    const mappedCollections = {};
-    for (const collectionSlug of Object.keys(collections)){
-        mappedCollections[collectionSlug] = {
-            adapter,
-            disableLocalStorage: true,
-            // Private files require Payload access control so URLs can be signed at serve time.
-            disablePayloadAccessControl: privateSlugs.has(collectionSlug) ? undefined : disablePayloadAccessControl,
-            prefix: getCollectionFolder(rootFolder, collectionSlug)
-        };
-    }
-    return mappedCollections;
-};
-export const imagekitStorage = (pluginOptions)=>(config)=>{
-        const { alwaysInsertFields, clientUploads, collections, disablePayloadAccessControl, enabled, focalPoint, folder, privateKey, publicKey, signedUrlExpiresIn: signedUrlExpiresInOption, urlEndpoint } = pluginOptions;
-        if (!privateKey?.trim()) {
-            throw new Error('imagekitStorage: `privateKey` is required.');
-        }
-        if (!publicKey?.trim()) {
-            throw new Error('imagekitStorage: `publicKey` is required.');
-        }
-        if (!urlEndpoint?.trim()) {
-            throw new Error('imagekitStorage: `urlEndpoint` is required.');
-        }
-        if (!collections || Object.keys(collections).length === 0) {
-            throw new Error('imagekitStorage: `collections` must include at least one upload collection.');
-        }
-        const privateSlugs = new Set(Object.entries(collections).filter(([, value])=>isPrivateCollectionConfig(value)).map(([slug])=>slug));
-        const configuredSlugs = new Set(Object.keys(collections));
-        if (disablePayloadAccessControl && privateSlugs.size > 0) {
-            throw new Error('imagekitStorage: `disablePayloadAccessControl` cannot be used with private collections. Private files require Payload access control to remain enabled so URLs can be signed at serve time.');
-        }
-        if (disablePayloadAccessControl) {
-            const xmlCollectionSlugs = (config.collections || []).filter((collection)=>configuredSlugs.has(collection.slug) && collectionCanStoreXml(collection)).map((collection)=>collection.slug);
-            if (xmlCollectionSlugs.length > 0) {
-                throw new Error(`imagekitStorage: \`disablePayloadAccessControl\` cannot be used with collections that can store XML-family files (${xmlCollectionSlugs.join(', ')}). XML-family files require Payload's file route so its Content Security Policy is applied. Configure a MIME allow list that excludes SVG/XML, or keep Payload access control enabled.`);
-            }
-        }
-        const signedUrlExpiresIn = typeof signedUrlExpiresInOption === 'number' && signedUrlExpiresInOption > 0 ? signedUrlExpiresInOption : DEFAULT_SIGNED_URL_EXPIRES_IN;
-        const apiRoute = config.routes?.api ?? '/api';
-        const rootFolder = normalizeFolder(folder);
-        const imageKitClient = new ImageKit({
-            privateKey
-        });
-        const collectionSecurity = Object.fromEntries((config.collections || []).filter((collection)=>configuredSlugs.has(collection.slug)).map((collection)=>[
-                collection.slug,
+    const output = cloudStoragePlugin({
+        collections: Object.fromEntries(Object.keys(collections).map((slug)=>[
+                slug,
                 {
-                    collection,
-                    isPrivate: privateSlugs.has(collection.slug),
-                    prefix: getCollectionFolder(rootFolder, collection.slug)
+                    adapter,
+                    disableLocalStorage: true,
+                    disablePayloadAccessControl: options.disablePayloadAccessControl,
+                    prefix: prefixFor(slug)
                 }
-            ]));
-        const verifyClientUpload = createImageKitClientUploadVerifier({
-            client: imageKitClient,
-            collections: collectionSecurity
+            ])),
+        enabled: options.enabled
+    })(sourceConfig);
+    // Do not invent a prefix on reads of legacy documents. A stored prefix is retained;
+    // new uploads get their normalized destination from the file-operation pipeline.
+    output.collections = output.collections?.map((collection)=>!configured.has(collection.slug) ? collection : {
+            ...collection,
+            fields: collection.fields.map((field)=>field.type === 'text' && field.name === 'prefix' ? {
+                    ...field,
+                    defaultValue: ({ req })=>req.file && typeof field.defaultValue === 'string' ? field.defaultValue : ''
+                } : field)
         });
-        const adapter = imagekitAdapter({
-            apiRoute,
-            client: imageKitClient,
-            clientUploads,
-            privateSlugs,
-            rootFolder,
-            signedUrlExpiresIn,
-            urlEndpoint,
-            verifyClientUpload
+    return output;
+}
+async function findUploadedFile(files, key, req) {
+    // ImageKit asset listings can lag a successful upload. Only admission retries;
+    // ordinary missing reads/deletes and collision lookups must stay immediate.
+    let file = await files.find({
+        key,
+        req
+    });
+    for (const delay of [
+        250,
+        500,
+        1000,
+        2000
+    ]){
+        if (file) {
+            break;
+        }
+        await new Promise((resolve)=>setTimeout(resolve, delay));
+        file = await files.find({
+            key,
+            req
         });
-        const configWithCropDisabled = {
-            ...config,
-            collections: (config.collections || []).map((collection)=>{
-                if (!configuredSlugs.has(collection.slug)) {
-                    return collection;
-                }
-                const isCollectionPrivate = privateSlugs.has(collection.slug);
-                const buildThumbnailURL = (doc)=>isDocumentPrivate(doc, isCollectionPrivate) ? getPrivateAdminThumbnailURL(doc, collection.slug, apiRoute) : getAdminThumbnailURL(doc);
-                const collectionOptions = collections[collection.slug];
-                const collectionFocalPoint = collectionOptions !== true && typeof collectionOptions === 'object' && typeof collectionOptions.focalPoint === 'boolean' ? collectionOptions.focalPoint : undefined;
-                // Surface a "this is a private collection" note in the list and edit views.
-                // Preserve an existing string description by appending; leave custom
-                // component descriptions untouched.
-                const existingDescription = collection.admin?.description;
-                const baseAdmin = isCollectionPrivate ? {
-                    ...collection.admin || {},
-                    description: typeof existingDescription === 'string' && existingDescription.trim().length > 0 ? `${existingDescription} ${PRIVATE_COLLECTION_DESCRIPTION}` : existingDescription ?? PRIVATE_COLLECTION_DESCRIPTION
-                } : collection.admin;
-                return {
-                    ...collection,
-                    admin: baseAdmin,
-                    hooks: {
-                        ...collection.hooks || {},
-                        beforeChange: [
-                            ...collection.hooks?.beforeChange || [],
-                            async ({ data, req })=>{
-                                if (!isRecord(data) || !req.file?.clientUploadContext) {
-                                    return data;
-                                }
-                                const context = req.file.clientUploadContext;
-                                const requestMimeType = req.file.mimetype.split(';', 1)[0]?.trim().toLowerCase();
-                                if (!isImageKitReceiptContext(context) || context.filename !== data.filename || context.filename !== req.file.name || // Payload can clear req.file.size when preparing an in-memory image.
-                                // generateFileData preserves the original size on the document.
-                                context.expectedSize !== data.filesize) {
-                                    throw new APIError('ImageKit client upload reference does not match this request.', 400);
-                                }
-                                const uploaded = await verifyClientUpload({
-                                    collectionSlug: collection.slug,
-                                    context
-                                });
-                                // Payload keeps the browser's MIME unless it fetched the file content, in which
-                                // case it uses the verified ImageKit-detected type the static handler served.
-                                if (requestMimeType !== context.expectedMimeType && requestMimeType !== uploaded.mimeType) {
-                                    throw new APIError('ImageKit client upload reference does not match this request.', 400);
-                                }
-                                // A provider file can only be claimed once, including through legacy receipts.
-                                // The unique file ID index also rejects concurrent claims.
-                                const existing = await req.payload.db.findOne({
-                                    collection: collection.slug,
-                                    req,
-                                    where: {
-                                        'imagekit.fileId': {
-                                            equals: uploaded.fileId
+    }
+    return file;
+}
+function isPrivateDocument(doc, fallback) {
+    const value = doc?.imagekit?.isPrivate;
+    return typeof value === 'boolean' ? value : fallback;
+}
+function getFileLocation(doc, filename) {
+    const value = doc ?? {};
+    return [
+        value,
+        value.original,
+        ...Object.values(value.variants ?? {})
+    ].find((file)=>file?.filename === filename) ?? value;
+}
+function applyMetadata(data, file, isPrivate, slug, apiRoute) {
+    data.imagekit = {
+        fileId: file.fileId,
+        isPrivate,
+        thumbnailUrl: file.thumbnail,
+        url: file.url
+    };
+    data.thumbnailURL = isPrivate ? getPrivateAdminThumbnailURL(data, slug, apiRoute) : getAdminThumbnailURL(data);
+    return data;
+}
+async function fetchOriginal({ file, req, url }) {
+    const range = getRangeRequestInfo({
+        fileSize: file.size,
+        rangeHeader: req.headers.get('Range')
+    });
+    if (range.type === 'invalid') {
+        return new Response(null, {
+            headers: range.headers,
+            status: range.status
+        });
+    }
+    const response = await fetch(url, {
+        cache: 'no-store',
+        headers: range.type === 'partial' ? {
+            Range: `bytes=${range.rangeStart}-${range.rangeEnd}`
+        } : undefined,
+        signal: new AbortController().signal
+    });
+    if (response.status !== range.status || response.headers.get('Content-Length') !== range.headers['Content-Length'] || range.type === 'partial' && response.headers.get('Content-Range') !== range.headers['Content-Range']) {
+        void response.body?.cancel().catch(()=>undefined);
+        throw new APIError('ImageKit returned mismatched file content metadata.', 502);
+    }
+    const headers = new Headers(range.headers);
+    headers.set('Content-Type', file.mime ?? 'application/octet-stream');
+    if (isXmlMimeType(file.mime ?? '')) {
+        headers.set('Content-Security-Policy', uploadContentSecurityPolicy);
+    }
+    return new Response(response.body, {
+        headers,
+        status: range.status
+    });
+}
+function canStoreXml(collection) {
+    const upload = typeof collection.upload === 'object' ? collection.upload : undefined;
+    return Boolean(upload?.allowRestrictedFileTypes) || !upload?.mimeTypes?.length || upload.mimeTypes.some((mime)=>mime.includes('*') || isXmlMimeType(mime));
+}
+function storageFields({ buildURL, expiresIn, isPrivate, prefix }) {
+    return [
+        {
+            type: 'collapsible',
+            admin: {
+                condition: (data)=>Boolean(data?.imagekit?.url),
+                initCollapsed: true
+            },
+            fields: [
+                {
+                    name: 'imagekit',
+                    type: 'group',
+                    admin: {
+                        disabled: {
+                            column: true,
+                            filter: true
+                        }
+                    },
+                    fields: [
+                        {
+                            name: 'fileId',
+                            type: 'text',
+                            admin: {
+                                hidden: true
+                            },
+                            unique: true
+                        },
+                        {
+                            name: 'url',
+                            type: 'text',
+                            admin: {
+                                readOnly: true
+                            },
+                            label: 'URL'
+                        },
+                        {
+                            name: 'isPrivate',
+                            type: 'checkbox',
+                            admin: {
+                                readOnly: true
+                            },
+                            label: 'Private file'
+                        },
+                        {
+                            name: 'signedUrl',
+                            type: 'text',
+                            admin: {
+                                condition: (_data, siblingData)=>isPrivateDocument({
+                                        imagekit: siblingData
+                                    }, isPrivate),
+                                description: `Temporary signed URL. Expires ${expiresIn} seconds after load. Anyone with this URL can access the file until it expires.`,
+                                readOnly: true
+                            },
+                            hooks: {
+                                afterRead: [
+                                    ({ data, siblingData })=>{
+                                        if (!data?.filename || !isPrivateDocument({
+                                            imagekit: siblingData
+                                        }, isPrivate)) {
+                                            return undefined;
                                         }
+                                        const key = buildStoragePathData({
+                                            collectionPrefix: prefix,
+                                            docPrefix: path.posix.join(data.prefix || prefix, data._objectKey || ''),
+                                            filename: data.filename
+                                        }).storageFilePath;
+                                        return buildURL(key, true);
                                     }
-                                });
-                                if (existing) {
-                                    throw new APIError('This ImageKit client upload receipt has already been used.', 400);
-                                }
-                                data.filename = uploaded.name;
-                                data.filesize = uploaded.size;
-                                data.mimeType = uploaded.mimeType;
-                                return applyVerifiedClientUploadToData(data, uploaded, buildThumbnailURL, isCollectionPrivate);
-                            }
-                        ],
-                        beforeOperation: [
-                            ...collection.hooks?.beforeOperation || [],
-                            ({ args, operation, req })=>{
-                                if (operation !== 'create' && operation !== 'update' || req.context?.skipCloudStorage || !req.file || req.file.clientUploadContext || !('data' in args) || !isRecord(args.data) || typeof args.data.prefix !== 'string') {
-                                    return args;
-                                }
-                                // Payload checks filename uniqueness before cloud storage's beforeChange
-                                // normalizes the prefix. Use the persisted form during that lookup too.
-                                args.data.prefix = buildUploadStoragePathData({
-                                    collectionPrefix: getCollectionFolder(rootFolder, collection.slug),
-                                    docPrefix: args.data.prefix,
-                                    filename: req.file.name
-                                }).sanitizedDocPrefix;
-                                return args;
+                                ]
+                            },
+                            label: 'Signed URL',
+                            virtual: true
+                        },
+                        {
+                            name: 'thumbnailUrl',
+                            type: 'text',
+                            admin: {
+                                hidden: true
                             }
-                        ]
-                    },
-                    upload: {
-                        // Focal points are opt-in for configured collections. Plugin-level
-                        // and collection-level options can override this default; a
-                        // collection's own `upload.focalPoint` still wins because it is
-                        // spread in afterwards.
-                        focalPoint: false,
-                        ...typeof focalPoint === 'boolean' ? {
-                            focalPoint
-                        } : {},
-                        ...typeof collectionFocalPoint === 'boolean' ? {
-                            focalPoint: collectionFocalPoint
-                        } : {},
-                        ...typeof collection.upload === 'object' ? collection.upload : {},
-                        adminThumbnail: ({ doc })=>buildThumbnailURL(doc),
-                        crop: false
-                    }
-                };
-            })
-        };
-        const uploadCollections = Object.fromEntries(Object.keys(collections).map((collectionSlug)=>[
-                collectionSlug,
-                {
-                    isPrivate: privateSlugs.has(collectionSlug),
-                    prefix: getCollectionFolder(rootFolder, collectionSlug)
-                }
-            ]));
-        initClientUploads({
-            clientHandler: '@humaan/payload-storage-imagekit/client#ImageKitUploadHandler',
-            collections: uploadCollections,
-            config: configWithCropDisabled,
-            enabled: enabled !== false && Boolean(clientUploads),
-            serverHandler: createImageKitUploadAuthHandler({
-                access: typeof clientUploads === 'object' ? clientUploads.access : undefined,
-                collections: uploadCollections,
-                privateKey,
-                publicKey,
-                verifyClientUpload
-            }),
-            serverHandlerPath: imageKitUploadAuthPath
-        });
-        const output = cloudStoragePlugin({
-            alwaysInsertFields,
-            collections: toCloudStorageCollections(collections, adapter, privateSlugs, rootFolder, disablePayloadAccessControl),
-            enabled
-        })(configWithCropDisabled);
-        // Make the provider identity unique at persistence time to reject concurrent receipt replays.
-        // Keep the legacy object key index for existing uploads.
-        output.collections = (output.collections || []).map((collection)=>{
-            if (!configuredSlugs.has(collection.slug)) {
-                return collection;
-            }
-            const originalPrefixField = (config.collections || []).find((original)=>original.slug === collection.slug)?.fields.find((field)=>'name' in field && field.name === 'prefix');
-            const withUniqueIdentity = (field)=>{
-                if (field.type === 'text' && 'name' in field && field.name === 'prefix' && (!originalPrefixField || !('defaultValue' in originalPrefixField) || originalPrefixField.defaultValue == null)) {
-                    // Cloud storage's collection-prefix default is applied on reads of old
-                    // documents that have no stored prefix. Its URL hook then appends that
-                    // prefix, but Payload's file access check cannot find it in the DB.
-                    // Upload hooks still persist the collection prefix for new files.
-                    return {
-                        ...field,
-                        defaultValue: ({ req })=>req.file && typeof field.defaultValue === 'string' ? field.defaultValue : ''
-                    };
-                }
-                if ('name' in field && field.name === '_objectKey') {
-                    return {
-                        ...field,
-                        unique: true
-                    };
-                }
-                if (field.type === 'group' && 'name' in field && field.name === 'imagekit') {
-                    return {
-                        ...field,
-                        fields: field.fields.map((metadataField)=>'name' in metadataField && metadataField.name === 'fileId' ? {
-                                ...metadataField,
-                                unique: true
-                            } : metadataField)
-                    };
-                }
-                // The imagekit group sits inside the adapter's presentational "Storage: ImageKit" panel.
-                if (field.type === 'collapsible') {
-                    return {
-                        ...field,
-                        fields: field.fields.map(withUniqueIdentity)
-                    };
+                        }
+                    ],
+                    interfaceName: 'imagekitFields',
+                    label: false
                 }
-                return field;
-            };
-            return {
-                ...collection,
-                fields: collection.fields.map(withUniqueIdentity)
-            };
-        });
-        return output;
-    };
-export { migrateFolder } from './migrate.js';
-// Backward-compatible alias
-export const payloadStorageImagekit = imagekitStorage;
-export const payloadStorageImageKit = imagekitStorage;
+            ],
+            label: 'Storage: ImageKit'
+        }
+    ];
+}
 
 //# sourceMappingURL=index.js.map