@seshuk/payload-plugin-openapi 0.1.0 → 0.2.1

package/dist/options.js

@@ -37,6 +37,7 @@ const resolveOptions = (options)=>{
         filters: resolveFilters(options.filters),
         interactiveAuth: resolveInteractiveAuth(options.interactiveAuth),
         nestedTags: options.nestedTags ?? false,
+        securityWhen: options.securityWhen,
         cache: options.cache ?? true,
         extensions: options.extensions ?? []
     };

package/dist/spec/buildDocument.js

@@ -7,6 +7,7 @@ import { buildBlockSchema, buildEntitySchemas } from "./entitySchemas.js";
 import { filterOperations, shouldIncludeCollection, shouldIncludeGlobal } from "./filters.js";
 import { blockSchemaName, createSchemaName, globalSchemaName, joinsSchemaName, listSchemaName, populateSchemaName, querySchemaName, schemaName, selectSchemaName, updateSchemaName } from "./names.js";
 import { buildParamSchemas, buildQueryOperationsSchema, collectionHasFilters } from "./params.js";
+import { applySecurityWhen, resolveEntitySecurity } from "./security.js";
 import { buildTagHierarchy } from "./tags.js";
 import { buildAuthPaths } from "./paths/auth.js";
 import { buildCollectionPaths } from "./paths/collections.js";
@@ -66,10 +67,21 @@ const buildDocument = async (input)=>{
             ctx
         });
         registerParamSchemas(schemas, base, collection.fields, ctx);
+        const security = await resolveEntitySecurity({
+            entity: collection,
+            operations: [
+                'read',
+                'create',
+                'update',
+                'delete'
+            ],
+            locale: ctx.locales[0]
+        });
         const collectionPaths = {
             ...buildCollectionPaths({
                 collection,
-                ctx
+                ctx,
+                security
             })
         };
         if (filters.includeAuth) Object.assign(collectionPaths, buildAuthPaths({
@@ -94,11 +106,17 @@ const buildDocument = async (input)=>{
                 nestedTags: options.nestedTags
             }));
         }
-        Object.assign(paths, filterOperations({
+        const filteredCollectionPaths = filterOperations({
             paths: collectionPaths,
             slug: collection.slug,
             kind: 'collection',
             filters
+        });
+        Object.assign(paths, applySecurityWhen({
+            paths: filteredCollectionPaths,
+            slug: collection.slug,
+            kind: 'collection',
+            securityWhen: options.securityWhen
         }));
     } catch (error) {
         logger.warn(`${PLUGIN_NAME}: skipped collection "${collection.slug}": ${error.message}`);
@@ -118,10 +136,19 @@ const buildDocument = async (input)=>{
         schemas[gbase] = read;
         schemas[updateSchemaName(gbase)] = update;
         registerParamSchemas(schemas, gbase, global.fields, ctx);
+        const security = await resolveEntitySecurity({
+            entity: global,
+            operations: [
+                'read',
+                'update'
+            ],
+            locale: ctx.locales[0]
+        });
         const globalPaths = {
             ...buildGlobalPaths({
                 global,
-                ctx
+                ctx,
+                security
             })
         };
         if (filters.includeVersions && global.versions) {
@@ -137,14 +164,21 @@ const buildDocument = async (input)=>{
                 pathBase: `${ctx.apiRoute}/globals/${global.slug}`,
                 ctx,
                 schemaBase: gbase,
-                nestedTags: options.nestedTags
+                nestedTags: options.nestedTags,
+                global: true
             }));
         }
-        Object.assign(paths, filterOperations({
+        const filteredGlobalPaths = filterOperations({
             paths: globalPaths,
             slug: global.slug,
             kind: 'global',
             filters
+        });
+        Object.assign(paths, applySecurityWhen({
+            paths: filteredGlobalPaths,
+            slug: global.slug,
+            kind: 'global',
+            securityWhen: options.securityWhen
         }));
     } catch (error) {
         logger.warn(`${PLUGIN_NAME}: skipped global "${global.slug}": ${error.message}`);

package/dist/spec/components.d.ts

@@ -1,4 +1,3 @@
-import type { Access } from 'payload';
 import type { ReferenceObject, RequestBodyObject, ResponseObject, ResponsesObject, SchemaObject, SecuritySchemeObject } from '@scalar/openapi-types/3.2';
 import type { Translate } from '../translations/types.js';
 type SchemaOrRef = SchemaObject | ReferenceObject;
@@ -42,5 +41,4 @@ export declare const securityScheme: ({ cookiePrefix, t }: {
     cookiePrefix: string;
     t: Translate;
 }) => SecuritySchemeObject;
-export declare const isOpenToPublic: (access: Access | undefined) => boolean;
 export {};

package/dist/spec/components.js

@@ -262,19 +262,4 @@ const securityScheme = ({ cookiePrefix, t })=>({
             cookiePrefix
         })
     });
-const isOpenToPublic = (access)=>{
-    if (!access) return true;
-    const trap = new Proxy({}, {
-        get () {
-            throw new Error('req accessed');
-        }
-    });
-    try {
-        return true === access({
-            req: trap
-        });
-    } catch  {
-        return false;
-    }
-};
-export { ERRORS, ERROR_SCHEMA_NAME, INTERACTIVE_SCHEME_NAME, SECURITY_SCHEME_NAME, buildErrorResponseSchema, buildListEnvelopeSchema, errorResponses, interactiveSecurityScheme, isOpenToPublic, jsonBody, jsonOk, jsonResponse, messageResponse, nullableType, securityScheme, uploadRequestBody };
+export { ERRORS, ERROR_SCHEMA_NAME, INTERACTIVE_SCHEME_NAME, SECURITY_SCHEME_NAME, buildErrorResponseSchema, buildListEnvelopeSchema, errorResponses, interactiveSecurityScheme, jsonBody, jsonOk, jsonResponse, messageResponse, nullableType, securityScheme, uploadRequestBody };

package/dist/spec/downconvert.d.ts

@@ -1,3 +1,3 @@
 import type { Document } from '@scalar/openapi-types/3.2';
-export declare const toOpenApi30: (doc: Document) => Document;
 export declare const toOpenApi31: (doc: Document) => Document;
+export declare const toOpenApi30: (doc: Document) => Document;

package/dist/spec/downconvert.js

@@ -23,9 +23,27 @@ const downconvertTo30 = (node)=>{
     }
     if (Array.isArray(out.type)) {
         const types = out.type;
-        if (types.includes(NULL)) out.nullable = true;
+        const nullable = types.includes(NULL);
         const rest = types.filter((t)=>t !== NULL);
-        out.type = 1 === rest.length ? rest[0] : rest;
+        if (1 === rest.length) {
+            out.type = rest[0];
+            if (nullable) out.nullable = true;
+        } else if (rest.length > 1) {
+            delete out.type;
+            const union = rest.map((type)=>nullable ? {
+                    type,
+                    nullable: true
+                } : {
+                    type
+                });
+            if (out.anyOf) out.allOf = [
+                ...out.allOf ?? [],
+                {
+                    anyOf: union
+                }
+            ];
+            else out.anyOf = union;
+        }
     }
     if ('const' in out) {
         out.enum = [
@@ -39,17 +57,18 @@ const downconvertTo30 = (node)=>{
         if (examples.length > 1) out['x-examples'] = examples;
         delete out.examples;
     }
+    if (Array.isArray(out.required) && 0 === out.required.length) delete out.required;
     for (const keyword of UNSUPPORTED_KEYWORDS)delete out[keyword];
     return out;
 };
-const toOpenApi30 = (doc)=>{
-    const converted = downconvertTo30(doc);
-    converted.openapi = '3.0.4';
-    return converted;
-};
 const toOpenApi31 = (doc)=>({
         ...doc,
         openapi: '3.1.2',
-        tags: doc.tags?.map(({ kind: _kind, parent: _parent, ...rest })=>rest)
+        tags: doc.tags?.map(({ kind: _kind, parent: _parent, summary: _summary, ...rest })=>rest)
     });
+const toOpenApi30 = (doc)=>{
+    const converted = downconvertTo30(toOpenApi31(doc));
+    converted.openapi = '3.0.4';
+    return converted;
+};
 export { toOpenApi30, toOpenApi31 };

package/dist/spec/entitySchemas.js

@@ -3,7 +3,7 @@ import { getTranslation } from "@payloadcms/translations";
 import { deepMerge, isPlainObject } from "../utils.js";
 import { makeT } from "../translations/index.js";
 import { AUTH_FIELDS, flattenFields } from "./fields.js";
-import { rewriteRefs } from "./names.js";
+import { refTo, rewriteRefs, schemaName } from "./names.js";
 const READ_HIDDEN_FIELDS = new Set([
     ...AUTH_FIELDS,
     'collection'
@@ -17,8 +17,10 @@ const stripInterfaceName = (entity)=>{
     const { interfaceName: _omit, ...rest } = entity;
     return rest;
 };
-const toComponentSchema = ({ config, source, idType })=>{
-    const jsonSchema = entityToJSONSchema(config, source, new Map(), idType);
+const toComponentSchema = ({ config, source, idType, write = false })=>{
+    const jsonSchema = entityToJSONSchema(config, source, new Map(), idType, void 0, void 0, {
+        forceInlineBlocks: write
+    });
     const blockSlugs = new Set((config.blocks ?? []).map((b)=>b.slug));
     const schema = rewriteRefs(jsonSchema, blockSlugs);
     delete schema.title;
@@ -124,12 +126,33 @@ const removeProps = (schema, names)=>{
         schema.required = schema.required.filter((r)=>!drop.has(r));
     }
 };
-const buildBaseSchema = ({ entity, config, ctx })=>{
+const toIdType = (type)=>Array.isArray(type) ? type.map(toIdType) : 'number' === type ? 'integer' : type;
+const writeRelationshipsAsIds = (node, refs)=>{
+    if (Array.isArray(node)) {
+        for (const item of node)writeRelationshipsAsIds(item, refs);
+        return;
+    }
+    if (!isPlainObject(node)) return;
+    const oneOf = node.oneOf;
+    if (Array.isArray(oneOf) && 2 === oneOf.length && isRef(oneOf[1]) && refs.has(oneOf[1].$ref)) {
+        delete node.oneOf;
+        node.type = toIdType(oneOf[0].type);
+        return;
+    }
+    for (const value of Object.values(node))writeRelationshipsAsIds(value, refs);
+};
+const buildBaseSchema = ({ entity, config, ctx, write = false })=>{
+    const idType = ctx.defaultIDType;
     const schema = toComponentSchema({
         config,
         source: stripInterfaceName(entity),
-        idType: ctx.defaultIDType
+        idType,
+        write
     });
+    if (write) {
+        const refs = new Set((config.collections ?? []).map((c)=>refTo(schemaName(c.slug))));
+        writeRelationshipsAsIds(schema, refs);
+    }
     const isAuth = 'auth' in entity && Boolean(entity.auth);
     if (isAuth) removeProps(schema, READ_HIDDEN_FIELDS);
     applyFieldOverrides({
@@ -149,38 +172,24 @@ const cloneSchema = (schema)=>({
             ...schema.required
         ] : schema.required
     });
-const flattenRelationships = ({ schema, fields, idType })=>{
-    if (!schema.properties) return;
-    const idSchema = {
-        type: 'number' === idType ? 'integer' : 'string'
-    };
-    for (const field of flattenFields(fields)){
-        if ('relationship' !== field.type && 'upload' !== field.type) continue;
-        const name = 'name' in field ? field.name : void 0;
-        if (name && name in schema.properties) schema.properties[name] = 'hasMany' in field && field.hasMany ? {
-            type: 'array',
-            items: idSchema
-        } : idSchema;
-    }
-};
 const buildEntitySchemas = async ({ entity, config, ctx })=>{
     const read = buildBaseSchema({
         entity,
         config,
         ctx
     });
+    const write = buildBaseSchema({
+        entity,
+        config,
+        ctx,
+        write: true
+    });
     const isAuth = 'auth' in entity && Boolean(entity.auth);
-    const idType = ctx.defaultIDType;
-    const create = cloneSchema(read);
+    const create = cloneSchema(write);
     if (Array.isArray(create.required)) {
         const optional = new Set(SERVER_FIELDS);
         create.required = create.required.filter((r)=>!optional.has(r));
     }
-    flattenRelationships({
-        schema: create,
-        fields: entity.fields,
-        idType
-    });
     if (isAuth && create.properties) {
         create.properties.password = {
             type: 'string'
@@ -192,14 +201,9 @@ const buildEntitySchemas = async ({ entity, config, ctx })=>{
             ])
         ];
     }
-    const update = cloneSchema(read);
+    const update = cloneSchema(write);
     delete update.required;
     if (update.properties) delete update.properties.id;
-    flattenRelationships({
-        schema: update,
-        fields: entity.fields,
-        idType
-    });
     if (isAuth && update.properties) update.properties.password = {
         type: 'string'
     };

package/dist/spec/filters.js

@@ -3,7 +3,9 @@ const SYSTEM_COLLECTIONS = new Set([
     'payload-locked-documents',
     'payload-preferences',
     'payload-migrations',
-    'payload-folders'
+    'payload-folders',
+    'payload-kv',
+    'payload-query-presets'
 ]);
 const HTTP_METHODS = [
     'get',
@@ -20,8 +22,15 @@ const matchesEntity = (matcher, { slug, kind })=>{
 const anyMatch = (matchers, entity)=>matchers.some((m)=>matchesEntity(m, entity));
 const isHiddenCollection = (collection)=>{
     if (true === collection.hidden) return true;
-    const adminHidden = collection.admin?.hidden;
-    return true === adminHidden || 'function' == typeof adminHidden;
+    const hidden = collection.admin?.hidden;
+    if ('function' == typeof hidden) try {
+        return true === hidden({
+            user: null
+        });
+    } catch  {
+        return false;
+    }
+    return true === hidden;
 };
 const passesIncludeExclude = (entity, filters)=>{
     if (filters.include.length > 0 && !anyMatch(filters.include, entity)) return false;

package/dist/spec/params.d.ts

@@ -1,6 +1,6 @@
 import type { Field } from 'payload';
 import type { ParameterObject, SchemaObject } from '@scalar/openapi-types/3.2';
-import type { BuildContext } from '../types.js';
+import type { BuildContext, Entity } from '../types.js';
 export declare const buildSelectSchema: ({ fields, ctx }: {
     fields: Field[];
     ctx: BuildContext;
@@ -38,6 +38,14 @@ export declare const commonReadParams: ({ base, ctx, refs, }: {
     ctx: BuildContext;
     refs: ReadParamRefs;
 }) => ParameterObject[];
+export type WriteOperation = 'create' | 'update' | 'updateByID' | 'delete' | 'duplicate' | 'globalUpdate';
+export declare const writeParams: ({ base, entity, ctx, refs, operation, }: {
+    base: string;
+    entity: Entity;
+    ctx: BuildContext;
+    refs: ReadParamRefs;
+    operation: WriteOperation;
+}) => ParameterObject[];
 export declare const whereParam: (base: string) => ParameterObject;
 export declare const buildListParams: ({ base, fields, ctx, refs, }: {
     base: string;

package/dist/spec/params.js

@@ -300,6 +300,98 @@ const commonReadParams = ({ base, ctx, refs })=>{
     if (refs.joins) params.push(objectParam('joins', refTo(joinsSchemaName(base))));
     return params;
 };
+const SHARED = [
+    'depth',
+    'locale',
+    'fallback-locale',
+    'select',
+    'populate'
+];
+const ALL_LOCALES = [
+    'publishAllLocales',
+    'unpublishAllLocales'
+];
+const WRITE_PARAMS = {
+    create: new Set([
+        ...SHARED,
+        'draft',
+        'autosave',
+        'publishAllLocales'
+    ]),
+    update: new Set([
+        ...SHARED,
+        'draft',
+        'trash',
+        'overrideLock',
+        ...ALL_LOCALES
+    ]),
+    updateByID: new Set([
+        ...SHARED,
+        'draft',
+        'trash',
+        'autosave',
+        'overrideLock',
+        ...ALL_LOCALES
+    ]),
+    delete: new Set([
+        ...SHARED,
+        'trash',
+        'overrideLock'
+    ]),
+    duplicate: new Set([
+        ...SHARED,
+        'draft',
+        'selectedLocales[]'
+    ]),
+    globalUpdate: new Set([
+        ...SHARED,
+        'draft',
+        'autosave',
+        ...ALL_LOCALES
+    ])
+};
+const entityWriteParams = (entity, ctx)=>{
+    const t = makeT(ctx.i18n);
+    const flag = (name, key)=>({
+            name,
+            in: 'query',
+            description: t(key),
+            schema: {
+                type: 'boolean'
+            }
+        });
+    const drafts = entity.versions ? entity.versions.drafts : false;
+    const params = [];
+    if (drafts && drafts.autosave) params.push(flag('autosave', 'paramAutosave'));
+    if (drafts && drafts.localizeStatus) {
+        params.push(flag('publishAllLocales', 'paramPublishAllLocales'));
+        params.push(flag('unpublishAllLocales', 'paramUnpublishAllLocales'));
+    }
+    if (false !== entity.lockDocuments) params.push(flag('overrideLock', 'paramOverrideLock'));
+    if (ctx.locales.length > 0) params.push({
+        name: 'selectedLocales[]',
+        in: 'query',
+        description: t('paramSelectedLocales'),
+        style: 'form',
+        explode: true,
+        schema: {
+            type: 'array',
+            items: {
+                type: 'string',
+                enum: ctx.locales
+            }
+        }
+    });
+    return params;
+};
+const writeParams = ({ base, entity, ctx, refs, operation })=>[
+        ...commonReadParams({
+            base,
+            ctx,
+            refs
+        }),
+        ...entityWriteParams(entity, ctx)
+    ].filter((p)=>WRITE_PARAMS[operation].has(p.name));
 const whereParam = (base)=>objectParam('where', refTo(querySchemaName(base)));
 const buildListParams = ({ base, fields, ctx, refs })=>{
     const params = [
@@ -341,4 +433,4 @@ const buildListParams = ({ base, fields, ctx, refs })=>{
     if (collectionHasFilters(fields)) params.push(whereParam(base));
     return params;
 };
-export { buildJoinsSchema, buildListParams, buildParamSchemas, buildPopulateSchema, buildQueryOperationsSchema, buildSelectSchema, collectionHasFilters, commonReadParams, whereParam };
+export { buildJoinsSchema, buildListParams, buildParamSchemas, buildPopulateSchema, buildQueryOperationsSchema, buildSelectSchema, collectionHasFilters, commonReadParams, whereParam, writeParams };

package/dist/spec/paths/auth.js

@@ -2,40 +2,63 @@ import { makeT } from "../../translations/index.js";
 import { ERRORS, errorResponses, jsonBody, jsonResponse, messageResponse } from "../components.js";
 import { refTo, schemaName } from "../names.js";
 import { authTagName } from "../tags.js";
-const identifierProps = (auth)=>{
-    const loginWithUsername = Boolean(auth?.loginWithUsername);
-    const usernameOnly = 'object' == typeof auth?.loginWithUsername && false === auth.loginWithUsername.requireEmail;
-    if (loginWithUsername && usernameOnly) return {
+const identifierBody = (auth, extra = {})=>{
+    const email = {
+        type: 'string',
+        format: 'email'
+    };
+    const username = {
+        type: 'string'
+    };
+    const extraRequired = Object.keys(extra);
+    const loginWithUsername = auth?.loginWithUsername;
+    const base = {
+        type: 'object',
+        additionalProperties: false
+    };
+    if (!loginWithUsername) return {
+        ...base,
         properties: {
-            username: {
-                type: 'string'
-            }
+            email,
+            ...extra
         },
         required: [
-            'username'
+            'email',
+            ...extraRequired
         ]
     };
-    if (loginWithUsername) return {
+    if ('object' == typeof loginWithUsername && loginWithUsername.allowEmailLogin) return {
+        ...base,
         properties: {
-            email: {
-                type: 'string',
-                format: 'email'
+            email,
+            username,
+            ...extra
+        },
+        ...extraRequired.length > 0 ? {
+            required: extraRequired
+        } : {},
+        anyOf: [
+            {
+                required: [
+                    'email'
+                ]
             },
-            username: {
-                type: 'string'
+            {
+                required: [
+                    'username'
+                ]
             }
-        },
-        required: []
+        ]
     };
     return {
+        ...base,
         properties: {
-            email: {
-                type: 'string',
-                format: 'email'
-            }
+            username,
+            ...extra
         },
         required: [
-            'email'
+            'username',
+            ...extraRequired
         ]
     };
 };
@@ -48,7 +71,6 @@ const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
     const tag = [
         nestedTags ? authTagName(name) : name
     ];
-    const ident = identifierProps(auth);
     const userRef = {
         $ref: refTo(name)
     };
@@ -64,20 +86,11 @@ const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
     const paths = {
         [`${base}/login`]: {
             post: op(`login${name}`, ERRORS.login, {
-                requestBody: jsonBody({
-                    type: 'object',
-                    additionalProperties: false,
-                    properties: {
-                        ...ident.properties,
-                        password: {
-                            type: 'string'
-                        }
-                    },
-                    required: [
-                        ...ident.required,
-                        'password'
-                    ]
-                }),
+                requestBody: jsonBody(identifierBody(auth, {
+                    password: {
+                        type: 'string'
+                    }
+                })),
                 responses: {
                     200: jsonResponse(t('authLogin'), {
                         type: 'object',
@@ -146,19 +159,7 @@ const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
         },
         [`${base}/forgot-password`]: {
             post: op(`forgotPassword${name}`, ERRORS.authAction, {
-                requestBody: jsonBody({
-                    type: 'object',
-                    additionalProperties: false,
-                    properties: {
-                        email: {
-                            type: 'string',
-                            format: 'email'
-                        }
-                    },
-                    required: [
-                        'email'
-                    ]
-                }),
+                requestBody: jsonBody(identifierBody(auth)),
                 responses: messageResponse(t('authForgotPassword'))
             })
         },
@@ -247,21 +248,9 @@ const buildAuthPaths = ({ collection, ctx, includeAdmin, nestedTags })=>{
             })
         };
     }
-    if (auth.maxLoginAttempts && auth.maxLoginAttempts > 0) paths[`${base}/unlock`] = {
+    paths[`${base}/unlock`] = {
         post: op(`unlock${name}`, ERRORS.authAction, {
-            requestBody: jsonBody({
-                type: 'object',
-                additionalProperties: false,
-                properties: {
-                    email: {
-                        type: 'string',
-                        format: 'email'
-                    }
-                },
-                required: [
-                    'email'
-                ]
-            }),
+            requestBody: jsonBody(identifierBody(auth)),
             responses: messageResponse(t('authUnlock'))
         })
     };

package/dist/spec/paths/collections.d.ts

@@ -1,7 +1,9 @@
 import type { SanitizedCollectionConfig } from 'payload';
 import type { PathsObject } from '@scalar/openapi-types/3.2';
 import type { BuildContext } from '../../types.js';
-export declare const buildCollectionPaths: ({ collection, ctx, }: {
+import type { EntitySecurity } from '../security.js';
+export declare const buildCollectionPaths: ({ collection, ctx, security, }: {
     collection: SanitizedCollectionConfig;
     ctx: BuildContext;
+    security?: EntitySecurity;
 }) => PathsObject;