@payloadcms/figma 0.0.1-alpha.9 → 0.1.0-alpha.0

package/dist/db-content-api/index.js

@@ -0,0 +1,938 @@
+import createClient from 'openapi-fetch';
+import { APIError, createDatabaseAdapter } from 'payload';
+import { v4 as uuid } from 'uuid';
+import { FigmaApiError } from '../api/figma-api.js';
+import { CONTENT_SYSTEM_NOT_FOUND_MESSAGE } from '../constants.js';
+import { getGlobalSlug } from './temp-utilities/slug.js';
+import { addFallbackSort } from './temp-utilities/sorting.js';
+import { unwrapDocument, unwrapFindResponse } from './temp-utilities/unwrapDocument.js';
+import { createAuthMiddleware, createErrorMiddleware } from './utilities/auth.js';
+import { dataToContentAPI, resolveVersionContent } from './utilities/data/index.js';
+import { validateRelationshipIds } from './utilities/data/validateRelationships.js';
+import { convertPayloadJoinsToContentAPI } from './utilities/joins.js';
+import { addFallbackLocale } from './utilities/locale/index.js';
+import { buildMeta } from './utilities/meta/buildMeta.js';
+import { normalizeLocaleInWhere } from './utilities/meta/normalizeLocaleInWhere.js';
+import { convertPayloadWhereToContentAPI } from './utilities/where.js';
+/**
+ * Heads-up logged locally whenever a job is queued. Queued jobs are executed by Figma's deployed runner, so
+ * if a deployed environment exists its runner can pick up anything in the queue. The developer
+ * needs to know that a job they just created locally may run on their deployed app instead of their machine.
+ */ export const LOCAL_JOB_QUEUE_NOTICE = "A job was queued locally. Queued jobs may be run by Figma's deployed runner, not your local " + 'dev server. If this app has a deployed environment, your deployed app may pick this ' + 'job up and run it against deployed code. If this app has no deployed ' + 'environment, the job will not run automatically. To test job logic against your local ' + 'code, call the function your task runs directly instead of queueing a job. ';
+/**
+ * Logs {@link LOCAL_JOB_QUEUE_NOTICE} for every job queued locally: if a deployed
+ * environment exists, its runner can pick up anything in the queue. No-op when
+ * `notifyLocalJobQueue` is false (i.e. not a local runtime).
+ */ export function maybeNotifyLocalJobQueue(adapter, args) {
+    if (!adapter.notifyLocalJobQueue) {
+        return;
+    }
+    if (args.collection !== 'payload-jobs') {
+        return;
+    }
+    adapter.payload.logger.warn(LOCAL_JOB_QUEUE_NOTICE);
+}
+async function syncCollections() {
+    let existingIds;
+    try {
+        const { data: response, error, response: httpResponse } = await this.client.GET('/api/v0/content_systems/{contentSystemId}/collections', {
+            params: {
+                path: {
+                    contentSystemId: this.contentSystemId
+                }
+            }
+        });
+        if (httpResponse.status === 404 || httpResponse.status === 410) {
+            throw new Error(CONTENT_SYSTEM_NOT_FOUND_MESSAGE);
+        }
+        if (error) {
+            throw createContentAPIError('syncCollections', error, httpResponse.status);
+        }
+        if (!response) {
+            throw new Error('No response from collections endpoint');
+        }
+        existingIds = new Set(response.data.map((c)=>c.id));
+        this.payload.logger.info(`Found ${existingIds.size} existing collections`);
+    } catch (error) {
+        if (error instanceof Error && error.message === CONTENT_SYSTEM_NOT_FOUND_MESSAGE) {
+            throw error;
+        }
+        if (error instanceof FigmaApiError && (error.statusCode === 404 || error.statusCode === 410)) {
+            throw new Error(CONTENT_SYSTEM_NOT_FOUND_MESSAGE);
+        }
+        this.payload.logger.warn(`Failed to fetch collections, will attempt to create all: ${error.message}`);
+        existingIds = new Set();
+    }
+    for (const collection of this.payload.config.collections){
+        if (!existingIds.has(collection.slug)) {
+            await createCollection.call(this, collection.slug);
+        }
+    }
+    for (const global of this.payload.config.globals || []){
+        const globalId = `_global-${global.slug}`;
+        if (!existingIds.has(globalId)) {
+            await createCollection.call(this, globalId);
+        }
+    }
+}
+function init() {
+    if (this.auth.mode === 'apiKey') {
+        this.payload.logger.info('Using API Key authentication');
+    } else if (this.auth.mode === 'tokenStore') {
+        this.payload.logger.info('Using TokenStore authentication (local dev)');
+    } else {
+        this.payload.logger.info('Using Dev JWT authentication (testing)');
+    }
+}
+// connect is called after init — once on first startup (hotReload=false) and again on HMR
+// (hotReload=true). Only clear the database on the first startup, never on hot reload.
+async function connect(args) {
+    const hotReload = args?.hotReload ?? false;
+    if (!hotReload && process.env.PAYLOAD_DROP_DATABASE === 'true') {
+        // clearDatabase already calls syncCollections internally after clearing
+        await this.clearDatabase();
+        return;
+    }
+    await syncCollections.call(this);
+}
+async function createCollection(collectionId) {
+    try {
+        const { error, response: httpResponse } = await this.client.POST('/api/v0/content_systems/{contentSystemId}/collections', {
+            body: {
+                id: collectionId
+            },
+            params: {
+                path: {
+                    contentSystemId: this.contentSystemId
+                }
+            }
+        });
+        if (error) {
+            throw createContentAPIError('createCollection', error, httpResponse.status);
+        }
+        this.payload.logger.info(`Created collection: ${collectionId}`);
+    } catch (error) {
+        const errorMessage = error.message;
+        if (!errorMessage.includes('already exists') && !errorMessage.includes('409')) {
+            this.payload.logger.warn(`Failed to create collection ${collectionId}: ${errorMessage}`);
+        }
+    }
+}
+async function findMany({ collection, joins, limit, locale: localeArg, page, pagination: _pagination, sort, where }) {
+    const locale = addFallbackLocale(localeArg, this.payload);
+    const normalizedWhere = normalizeLocaleInWhere(where, this.payload, collection, locale);
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/documents:find', {
+        body: {
+            collection,
+            contentSystemId: this.contentSystemId,
+            join: convertPayloadJoinsToContentAPI(this.payload, collection, joins, locale),
+            limit,
+            locale,
+            page: page ?? 1,
+            sort: addFallbackSort(sort, this.payload, collection),
+            where: convertPayloadWhereToContentAPI(normalizedWhere ?? {}),
+            ...buildMeta(this.payload, {
+                collection,
+                locale,
+                where: normalizedWhere
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('findMany', error, httpResponse.status);
+    }
+    if (!response) {
+        throw new Error('No response from findMany');
+    }
+    return unwrapFindResponse(this.payload, response.result, collection, localeArg);
+}
+async function find(args) {
+    const collectionConfig = this.payload.config.collections.find((c)=>c.slug === args.collection);
+    return findMany.call(this, {
+        collection: args.collection,
+        joins: args.joins,
+        // TODO: FindArgs.limit should be 'number' not 'number | undefined'
+        // Payload Core sanitizes limit before calling the adapter when going through findOperation
+        // (defaults to 10 or 0 based on pagination), but some callers (e.g. deleteOperation) call
+        // db.find() directly without a limit. Default to 0 (unlimited) to avoid the Content API
+        // falling back to its own default of 10.
+        limit: args.limit ?? 0,
+        locale: args.locale,
+        page: args.page ?? 1,
+        pagination: args.pagination,
+        sort: args.sort || collectionConfig?.defaultSort,
+        where: args.where
+    });
+}
+// TODO: remove Omit when this PR is released: https://github.com/payloadcms/payload/pull/15183
+async function findVersions(args) {
+    const sortWithFallback = addFallbackSort(args.sort || '-updatedAt', this.payload, args.collection);
+    const whereClause = convertPayloadWhereToContentAPI(args.where ?? {}, {
+        parentToDocumentId: true,
+        stripVersionPrefix: true
+    });
+    const locale = addFallbackLocale(args.locale, this.payload);
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/document_versions:find', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            // TODO: FindVersionsArgs.limit should be 'number' not 'number | undefined'
+            // is sanitized by Payload Core before calling the adapter (defaults to 10 or 0 based on pagination)
+            limit: args.limit,
+            locale,
+            page: args.page ?? 1,
+            sort: sortWithFallback,
+            where: whereClause,
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('findVersions', error, httpResponse.status);
+    }
+    if (!response) {
+        throw new Error('No response from findVersions');
+    }
+    return unwrapFindResponse(this.payload, response.result, args.collection, args.locale);
+}
+async function queryDrafts(args) {
+    const versionsResult = await this.findVersions({
+        collection: args.collection,
+        limit: args.limit,
+        locale: args.locale,
+        page: args.page,
+        pagination: args.pagination,
+        sort: args.sort,
+        where: {
+            ...args.where,
+            latest: {
+                equals: true
+            }
+        }
+    });
+    // queryDrafts returns documents at root level, not nested in 'version'.
+    // Only spread version content; version metadata (latest, parent) must not leak.
+    const docs = versionsResult.docs.map((versionDoc)=>({
+            ...versionDoc.version,
+            id: versionDoc.parent
+        }));
+    return {
+        ...versionsResult,
+        docs
+    };
+}
+async function createVersion(args) {
+    const versionContent = dataToContentAPI(this.payload, args.collectionSlug, args.versionData, {
+        applyDefaults: true,
+        publishedLocale: args.publishedLocale
+    });
+    if (args.autosave) {
+        versionContent._payloadAutosave = true;
+    }
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/document_versions:create', {
+        body: {
+            collection: args.collectionSlug,
+            contentSystemId: this.contentSystemId,
+            versionDoc: {
+                createdAt: args.createdAt,
+                latest: true,
+                parent: String(args.parent),
+                updatedAt: args.updatedAt,
+                version: versionContent
+            }
+        }
+    });
+    if (error) {
+        throw createContentAPIError('createVersion', error, httpResponse.status);
+    }
+    if (!response) {
+        throw new Error('No response from createVersion');
+    }
+    return unwrapDocument({
+        collectionSlug: args.collectionSlug,
+        doc: response.result,
+        payload: this.payload
+    });
+}
+async function updateVersion(args) {
+    const where = args.where ?? {
+        id: {
+            equals: args.id
+        }
+    };
+    const locale = addFallbackLocale(args.locale, this.payload);
+    const { publishedLocale, version, ...versionMeta } = args.versionData;
+    const resolvedVersion = resolveVersionContent(version, versionMeta);
+    const versionContent = dataToContentAPI(this.payload, args.collection, resolvedVersion, {
+        publishedLocale
+    });
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/document_versions:update', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            createOnMissing: false,
+            locale,
+            versionDoc: {
+                createdAt: versionMeta.createdAt,
+                latest: versionMeta.latest,
+                parent: versionMeta.parent != null ? String(versionMeta.parent) : undefined,
+                updatedAt: versionMeta.updatedAt,
+                version: versionContent
+            },
+            where: convertPayloadWhereToContentAPI(where, {
+                stripVersionPrefix: true
+            }),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('updateVersion', error, httpResponse.status);
+    }
+    if (!response?.result || !('data' in response.result)) {
+        throw new Error('No document data in updateVersion response');
+    }
+    const doc = response.result.data[0];
+    if (!doc) {
+        return null;
+    }
+    return unwrapDocument({
+        collectionSlug: args.collection,
+        doc,
+        locale: args.locale,
+        payload: this.payload
+    });
+}
+async function deleteVersions(args) {
+    if (!args.collection) {
+        throw new Error('deleteVersions requires a collection');
+    }
+    const locale = addFallbackLocale(args.locale, this.payload);
+    const { error, response: httpResponse } = await this.client.POST('/api/v0/document_versions:delete', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            locale,
+            where: convertPayloadWhereToContentAPI(args.where, {
+                stripVersionPrefix: true
+            }),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('deleteVersions', error, httpResponse.status);
+    }
+}
+async function findOne(args) {
+    const { docs } = await this.find({
+        collection: args.collection,
+        joins: args.joins,
+        limit: 1,
+        locale: args.locale,
+        pagination: false,
+        where: args.where
+    });
+    return docs[0] ?? null;
+}
+async function findDistinct(args) {
+    const locale = addFallbackLocale(args.locale, this.payload);
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/documents:findDistinct', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            distinctBy: args.field,
+            limit: args.limit,
+            locale,
+            page: args.page ?? 1,
+            sort: addFallbackSort(args.sort, this.payload, args.collection),
+            where: convertPayloadWhereToContentAPI(args.where ?? {}),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('findDistinct', error, httpResponse.status);
+    }
+    const { data, ...pagination } = response.result;
+    return {
+        ...pagination,
+        // Content API returns flat values; Payload expects objects keyed by field name.
+        values: data.map((value)=>({
+                [args.field]: value
+            }))
+    };
+}
+async function updateMany(args) {
+    const locale = addFallbackLocale(args.locale, this.payload);
+    validateRelationshipIds({
+        collectionSlug: args.collection,
+        data: args.data,
+        payload: this.payload
+    });
+    const { data: contentAPIResponse, error, response: httpResponse } = await this.client.POST('/api/v0/documents:update', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            createOnMissing: false,
+            doc: dataToContentAPI(this.payload, args.collection, args.data),
+            environmentName: this.environmentName,
+            limit: args.limit,
+            locale,
+            returning: {},
+            sort: addFallbackSort(args.sort || '-updatedAt', this.payload, args.collection),
+            where: convertPayloadWhereToContentAPI(args.where),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('updateMany', error, httpResponse.status);
+    }
+    if (!contentAPIResponse) {
+        throw new Error('No response from updateMany');
+    }
+    if (contentAPIResponse.result && 'data' in contentAPIResponse.result) {
+        return contentAPIResponse.result.data.map((doc)=>unwrapDocument({
+                collectionSlug: args.collection,
+                doc,
+                locale: args.locale,
+                payload: this.payload
+            }));
+    }
+    return null;
+}
+async function updateOne(args) {
+    const locale = addFallbackLocale(args.locale, this.payload);
+    const where = args.where ?? {
+        id: {
+            equals: args.id
+        }
+    };
+    validateRelationshipIds({
+        collectionSlug: args.collection,
+        data: args.data,
+        payload: this.payload
+    });
+    const { data: contentAPIResponse, error, response: httpResponse } = await this.client.POST('/api/v0/documents:update', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            createOnMissing: false,
+            doc: dataToContentAPI(this.payload, args.collection, args.data),
+            environmentName: this.environmentName,
+            locale,
+            returning: {},
+            where: convertPayloadWhereToContentAPI(where),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('updateOne', error, httpResponse.status);
+    }
+    if (!contentAPIResponse) {
+        throw new Error('No response from updateOne');
+    }
+    if (!contentAPIResponse.result || !('data' in contentAPIResponse.result)) {
+        throw new Error('Unexpected response format from updateOne');
+    }
+    const doc = contentAPIResponse.result.data[0];
+    if (!doc) {
+        return null;
+    }
+    return unwrapDocument({
+        collectionSlug: args.collection,
+        doc,
+        locale: args.locale,
+        payload: this.payload
+    });
+}
+async function deleteMany(args) {
+    const locale = addFallbackLocale(args.req?.locale, this.payload);
+    const { error, response: httpResponse } = await this.client.POST('/api/v0/documents:delete', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            environmentName: this.environmentName,
+            locale,
+            where: convertPayloadWhereToContentAPI(args.where),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('deleteMany', error, httpResponse.status);
+    }
+}
+async function deleteOne(args) {
+    const locale = addFallbackLocale(args.req?.locale, this.payload);
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/documents:delete', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            environmentName: this.environmentName,
+            locale,
+            returning: {},
+            where: convertPayloadWhereToContentAPI(args.where),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('deleteOne', error, httpResponse.status);
+    }
+    if (!response?.result || !('data' in response.result)) {
+        throw new Error('No document data in deleteOne response');
+    }
+    const doc = response.result.data[0];
+    if (!doc) {
+        return null;
+    }
+    return unwrapDocument({
+        collectionSlug: args.collection,
+        doc,
+        locale: args.req?.locale === null ? undefined : args.req?.locale,
+        payload: this.payload
+    });
+}
+async function create(args) {
+    const isGlobalCollection = args.collection.startsWith('_global-');
+    const customIDType = this.payload.collections[args.collection]?.customIDType;
+    // See test: "should allow creating docs with payload.db.create with custom ID".
+    // TODO: customID is not yet in our installed types. Remove this when it is.
+    // When provided (e.g. from payload.db.create), it takes priority over data.id.
+    const customID = args.customID;
+    let id;
+    if (customID != null) {
+        id = String(customID);
+    } else if ((isGlobalCollection || customIDType || this.allowIDOnCreate) && args.data.id != null && (typeof args.data.id === 'string' || typeof args.data.id === 'number')) {
+        id = String(args.data.id);
+    } else {
+        id = uuid();
+    }
+    const locale = addFallbackLocale(args.locale, this.payload);
+    validateRelationshipIds({
+        collectionSlug: args.collection,
+        data: args.data,
+        payload: this.payload
+    });
+    const { data: contentAPIResponse, error, response: httpResponse } = await this.client.POST('/api/v0/documents:create', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            doc: {
+                ...dataToContentAPI(this.payload, args.collection, args.data, {
+                    applyDefaults: true,
+                    createdAt: true
+                }),
+                id
+            },
+            environmentName: this.environmentName,
+            locale,
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                data: args.data,
+                locale
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('create', error, httpResponse.status);
+    }
+    if (!contentAPIResponse) {
+        throw new Error('No response from create');
+    }
+    maybeNotifyLocalJobQueue(this, args);
+    return unwrapDocument({
+        collectionSlug: args.collection,
+        doc: contentAPIResponse.result,
+        locale: args.locale,
+        payload: this.payload
+    });
+}
+async function clearDatabase() {
+    this.payload.logger.info(`---- CLEARING CONTENT API DATABASE ----`);
+    try {
+        const response = await fetch(getClearDatabaseUrl(this.url, process.env.FIGMA_CONTENT_API_CUTOVER_STATE), {
+            headers: {
+                'Content-Type': 'application/json'
+            },
+            method: 'POST'
+        });
+        if (!response.ok) {
+            throw new Error(`Content API database reset failed: ${response.status} ${response.statusText}`);
+        }
+        this.payload.logger.info('---- CONTENT API DATABASE CLEARED ----');
+        // Re-sync collections after clearing
+        await syncCollections.call(this);
+    } catch (error) {
+        this.payload.logger.error(`Failed to clear database: ${error.message}`);
+        throw error;
+    }
+}
+export function getClearDatabaseUrl(url, cutoverState) {
+    const clearDatabaseUrl = new URL('/dev/clear-db', url);
+    if (cutoverState != null) {
+        clearDatabaseUrl.searchParams.set('cutoverState', cutoverState);
+    }
+    return clearDatabaseUrl.toString();
+}
+async function count(args) {
+    const locale = addFallbackLocale(args.locale, this.payload);
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/documents:count', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            locale,
+            where: convertPayloadWhereToContentAPI(args.where),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('count', error, httpResponse.status);
+    }
+    if (!response) {
+        throw new Error('No response from count');
+    }
+    return {
+        totalDocs: response.result.count
+    };
+}
+async function countVersions(args) {
+    const locale = addFallbackLocale(args.locale, this.payload);
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/document_versions:count', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            locale,
+            where: convertPayloadWhereToContentAPI(args.where, {
+                parentToDocumentId: true,
+                stripVersionPrefix: true
+            }),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('countVersions', error, httpResponse.status);
+    }
+    if (!response) {
+        throw new Error('No response from countVersions');
+    }
+    return {
+        totalDocs: response.result.count
+    };
+}
+async function upsert(args) {
+    let documentId = args.data.id;
+    if (!documentId && args.where && 'id' in args.where) {
+        const idClause = args.where.id;
+        if (idClause && 'equals' in idClause) {
+            documentId = idClause.equals;
+        }
+    }
+    if (!documentId) {
+        documentId = uuid();
+    }
+    const locale = addFallbackLocale(args.locale, this.payload);
+    validateRelationshipIds({
+        collectionSlug: args.collection,
+        data: args.data,
+        payload: this.payload
+    });
+    const { data: contentAPIResponse, error, response: httpResponse } = await this.client.POST('/api/v0/documents:update', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            createOnMissing: {
+                id: documentId
+            },
+            doc: dataToContentAPI(this.payload, args.collection, args.data, {
+                applyDefaults: true,
+                createdAt: true
+            }),
+            environmentName: this.environmentName,
+            locale,
+            where: convertPayloadWhereToContentAPI(args.where),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                data: args.data,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw createContentAPIError('upsert', error, httpResponse.status);
+    }
+    if (!contentAPIResponse) {
+        throw new Error('No response from upsert');
+    }
+    if (!contentAPIResponse.result || !('data' in contentAPIResponse.result)) {
+        throw new Error('Unexpected response format from upsert');
+    }
+    const doc = contentAPIResponse.result.data[0];
+    if (!doc) {
+        throw new Error('No document data in upsert response');
+    }
+    return unwrapDocument({
+        collectionSlug: args.collection,
+        doc,
+        locale: args.locale,
+        payload: this.payload
+    });
+}
+async function updateJobs(args) {
+    const { id, limit, returning, sort, where } = args;
+    if (id == null && where == null) {
+        throw new Error('updateJobs requires either id or a where clause');
+    }
+    // Copy data to avoid mutating the caller's object.
+    const data = {
+        ...args.data
+    };
+    // Strip log if empty/absent. The content API's deep merge replaces arrays entirely
+    // (it does not concatenate), so sending log: [] would wipe existing log entries.
+    // Only include log when it carries new content: a non-empty array or a $push operation.
+    const log = data.log;
+    if (!(Array.isArray(log) && log.length > 0) && !(log && typeof log === 'object' && '$push' in log)) {
+        delete data.log;
+    }
+    const whereClause = id != null ? {
+        id: {
+            equals: String(id)
+        }
+    } : where;
+    const docData = dataToContentAPI(this.payload, 'payload-jobs', data);
+    const sortClause = addFallbackSort(sort || '-updatedAt', this.payload, 'payload-jobs');
+    const whereQuery = convertPayloadWhereToContentAPI(whereClause);
+    const meta = buildMeta(this.payload, {
+        collection: 'payload-jobs',
+        locale: undefined,
+        where: whereClause
+    });
+    const { data: response, error, response: httpResponse } = await this.client.POST('/api/v0/documents:update', {
+        body: {
+            collection: 'payload-jobs',
+            contentSystemId: this.contentSystemId,
+            createOnMissing: false,
+            doc: docData,
+            environmentName: this.environmentName,
+            ...limit != null && {
+                limit
+            },
+            returning: {},
+            sort: sortClause,
+            where: whereQuery,
+            ...meta
+        }
+    });
+    if (error) {
+        throw createContentAPIError('updateJobs', error, httpResponse.status);
+    }
+    if (!response) {
+        throw new Error('No response from updateJobs');
+    }
+    if (returning === false) {
+        return null;
+    }
+    if (!response.result || !('data' in response.result)) {
+        return [];
+    }
+    return response.result.data.map((doc)=>unwrapDocument({
+            collectionSlug: 'payload-jobs',
+            doc,
+            payload: this.payload
+        }));
+}
+function createGlobal(args) {
+    // Globals are singletons identified by their slug. Use upsert so concurrent calls
+    // (e.g. handleSchedules processing multiple queueables with the same null jobStats)
+    // don't fail with "A record with this field already exists". The deep-merge semantics
+    // of the update path are safe here: callers that want a fresh create (first run) get
+    // an effective create, and callers that race a prior create get a merge instead.
+    return this.upsert({
+        collection: getGlobalSlug(args.slug),
+        data: {
+            ...args.data,
+            id: args.slug,
+            globalType: args.slug
+        },
+        where: {
+            id: {
+                equals: args.slug
+            }
+        }
+    });
+}
+function findGlobal(args) {
+    return this.findOne({
+        collection: getGlobalSlug(args.slug),
+        locale: args.locale,
+        where: args.where ?? {}
+    });
+}
+async function updateGlobal(args) {
+    // TODO: upsert's `createOnMissing` path generates a new `createdAt` on every call,
+    // which overwrites the original timestamp on updates. The fix belongs in the Content API:
+    // `createOnMissing` should preserve `createdAt` on updates and only set it on creates.
+    return this.upsert({
+        collection: getGlobalSlug(args.slug),
+        data: args.data,
+        where: {
+            id: {
+                equals: args.slug
+            }
+        }
+    });
+}
+// TODO: remove Omit when this PR is released: https://github.com/payloadcms/payload/pull/15183
+function findGlobalVersions(args) {
+    return this.findVersions({
+        collection: getGlobalSlug(args.global),
+        limit: args.limit,
+        locale: args.locale,
+        page: args.page,
+        pagination: args.pagination,
+        sort: args.sort,
+        where: args.where
+    });
+}
+function createGlobalVersion(args) {
+    // For globals, use the globalSlug as the consistent document ID
+    // This matches what we do in updateGlobal
+    return this.createVersion({
+        autosave: args.autosave,
+        collectionSlug: getGlobalSlug(args.globalSlug),
+        createdAt: args.createdAt,
+        parent: args.globalSlug,
+        publishedLocale: args.publishedLocale,
+        updatedAt: args.updatedAt,
+        versionData: args.versionData
+    });
+}
+function updateGlobalVersion(args) {
+    // UpdateVersion requires either id OR where, not both
+    if (args.id !== undefined) {
+        return this.updateVersion({
+            id: args.id,
+            collection: getGlobalSlug(args.global),
+            locale: args.locale,
+            versionData: args.versionData
+        });
+    }
+    // args.where is guaranteed by Payload when args.id is undefined
+    return this.updateVersion({
+        collection: getGlobalSlug(args.global),
+        locale: args.locale,
+        versionData: args.versionData,
+        where: args.where
+    });
+}
+function countGlobalVersions(args) {
+    return this.countVersions({
+        collection: getGlobalSlug(args.global),
+        locale: args.locale,
+        where: args.where
+    });
+}
+function createContentAPIError(operation, error, status) {
+    return new APIError(`Content API ${operation} error: ${error.message}`, status, {
+        code: error.code,
+        constraint: error.constraint,
+        field: error.field
+    });
+}
+export const contentAPIAdapter = (opts)=>({
+        name: 'content-api',
+        defaultIDType: 'text',
+        init: ({ payload })=>{
+            const client = createClient({
+                baseUrl: opts.url
+            });
+            const middlewareOpts = {
+                auth: opts.auth,
+                contentSystemId: opts.contentSystemId,
+                logger: payload.logger,
+                url: opts.url
+            };
+            client.use(createAuthMiddleware(middlewareOpts));
+            client.use(createErrorMiddleware(middlewareOpts));
+            return createDatabaseAdapter({
+                name: 'content-api',
+                allowIDOnCreate: opts.allowIDOnCreate ?? false,
+                auth: opts.auth,
+                beginTransaction: ()=>Promise.resolve(null),
+                clearDatabase: clearDatabase,
+                client,
+                commitTransaction: async ()=>{},
+                connect: connect,
+                contentSystemId: opts.contentSystemId,
+                count: count,
+                countGlobalVersions: countGlobalVersions,
+                countVersions: countVersions,
+                create: create,
+                createGlobal: createGlobal,
+                createGlobalVersion: createGlobalVersion,
+                createVersion: createVersion,
+                defaultIDType: 'text',
+                deleteMany: deleteMany,
+                deleteOne: deleteOne,
+                deleteVersions: deleteVersions,
+                environmentName: opts.environmentName,
+                find: find,
+                findDistinct: findDistinct,
+                findGlobal: findGlobal,
+                findGlobalVersions: findGlobalVersions,
+                findOne: findOne,
+                findVersions: findVersions,
+                idType: 'uuid',
+                init,
+                notifyLocalJobQueue: opts.notifyLocalJobQueue,
+                packageName: '@payloadcms/db-content-api',
+                payload,
+                queryDrafts: queryDrafts,
+                rollbackTransaction: async ()=>{},
+                updateGlobal: updateGlobal,
+                updateGlobalVersion: updateGlobalVersion,
+                updateJobs: updateJobs,
+                updateMany: updateMany,
+                updateOne: updateOne,
+                updateVersion: updateVersion,
+                upsert: upsert,
+                url: opts.url
+            });
+        }
+    });