@seshuk/payload-plugin-openapi 0.1.0

package/dist/spec/filters.js

@@ -0,0 +1,74 @@
+const SYSTEM_COLLECTIONS = new Set([
+    'payload-jobs',
+    'payload-locked-documents',
+    'payload-preferences',
+    'payload-migrations',
+    'payload-folders'
+]);
+const HTTP_METHODS = [
+    'get',
+    'post',
+    'patch',
+    'put',
+    'delete'
+];
+const matchesEntity = (matcher, { slug, kind })=>{
+    if ('string' == typeof matcher) return matcher === slug;
+    if (matcher instanceof RegExp) return matcher.test(slug);
+    return matcher.kind === kind && matcher.slug === slug;
+};
+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 passesIncludeExclude = (entity, filters)=>{
+    if (filters.include.length > 0 && !anyMatch(filters.include, entity)) return false;
+    if (anyMatch(filters.exclude, entity)) return false;
+    return true;
+};
+const shouldIncludeCollection = (collection, filters)=>{
+    const { slug } = collection;
+    if (SYSTEM_COLLECTIONS.has(slug) && !filters.includeSystem) return false;
+    if (!filters.includeHidden && isHiddenCollection(collection)) return false;
+    return passesIncludeExclude({
+        slug,
+        kind: 'collection'
+    }, filters);
+};
+const shouldIncludeGlobal = (global, filters)=>passesIncludeExclude({
+        slug: global.slug,
+        kind: 'global'
+    }, filters);
+const ruleMatchesMethod = (rule, method)=>{
+    if (void 0 === rule.method) return true;
+    return Array.isArray(rule.method) ? rule.method.includes(method) : rule.method === method;
+};
+const ruleMatchesSlug = (rule, slug)=>{
+    if (void 0 === rule.slug) return true;
+    return rule.slug instanceof RegExp ? rule.slug.test(slug) : rule.slug === slug;
+};
+const ruleMatches = (rule, { method, slug, kind, path })=>ruleMatchesMethod(rule, method) && ruleMatchesSlug(rule, slug) && (void 0 === rule.kind || rule.kind === kind) && (void 0 === rule.path || rule.path.test(path));
+const isOperationExcluded = (filters, op)=>{
+    if (filters.excludeOperations.some((rule)=>ruleMatches(rule, op))) return true;
+    return filters.excludeWhen?.(op) ?? false;
+};
+const filterOperations = ({ paths, slug, kind, filters })=>{
+    if (0 === filters.excludeOperations.length && !filters.excludeWhen) return paths;
+    for (const [path, item] of Object.entries(paths)){
+        if (!item) continue;
+        let remaining = 0;
+        const ops = item;
+        for (const method of HTTP_METHODS)if (ops[method]) if (isOperationExcluded(filters, {
+            method,
+            slug,
+            kind,
+            path
+        })) delete ops[method];
+        else remaining += 1;
+        if (0 === remaining) delete paths[path];
+    }
+    return paths;
+};
+export { filterOperations, shouldIncludeCollection, shouldIncludeGlobal };

package/dist/spec/names.d.ts

@@ -0,0 +1,14 @@
+export declare const schemaName: (slug: string) => string;
+export declare const blockSchemaName: (slug: string) => string;
+export declare const globalSchemaName: (slug: string) => string;
+export declare const listSchemaName: (base: string) => string;
+export declare const createSchemaName: (base: string) => string;
+export declare const updateSchemaName: (base: string) => string;
+export declare const querySchemaName: (base: string) => string;
+export declare const selectSchemaName: (base: string) => string;
+export declare const populateSchemaName: (base: string) => string;
+export declare const joinsSchemaName: (base: string) => string;
+export declare const refTo: (name: string) => string;
+type JsonValue = Record<string, unknown> | unknown[] | string | number | boolean | null;
+export declare const rewriteRefs: (node: JsonValue, blockSlugs?: Set<string>) => JsonValue;
+export {};

package/dist/spec/names.js

@@ -0,0 +1,37 @@
+import { upperFirst } from "../utils.js";
+const schemaName = (slug)=>upperFirst(slug.replace(/-([a-z])/g, (_, c)=>c.toUpperCase()));
+const blockSchemaName = (slug)=>{
+    const stripped = slug.replace(/^block[-_]?/i, '').replace(/[-_]?block$/i, '');
+    return `Block${schemaName(stripped || slug)}`;
+};
+const globalSchemaName = (slug)=>`Global${schemaName(slug)}`;
+const listSchemaName = (base)=>`${base}List`;
+const createSchemaName = (base)=>`${base}Create`;
+const updateSchemaName = (base)=>`${base}Update`;
+const querySchemaName = (base)=>`${base}QueryOperations`;
+const selectSchemaName = (base)=>`${base}Select`;
+const populateSchemaName = (base)=>`${base}Populate`;
+const joinsSchemaName = (base)=>`${base}Joins`;
+const refTo = (name)=>`#/components/schemas/${name}`;
+const REF = /^#\/(?:definitions|\$defs|components\/schemas)\/(.+)$/;
+const normalizeRef = (ref, blockSlugs)=>{
+    const match = REF.exec(ref);
+    if (!match) return ref;
+    const captured = match[1];
+    const pascal = schemaName(captured);
+    const blockSlug = [
+        ...blockSlugs
+    ].find((s)=>s === captured || schemaName(s) === pascal);
+    if (blockSlug) return `#/components/schemas/${blockSchemaName(blockSlug)}`;
+    return `#/components/schemas/${pascal}`;
+};
+const rewriteRefs = (node, blockSlugs = new Set())=>{
+    if (Array.isArray(node)) return node.map((item)=>rewriteRefs(item, blockSlugs));
+    if (node && 'object' == typeof node) {
+        const out = {};
+        for (const [key, value] of Object.entries(node))out[key] = '$ref' === key && 'string' == typeof value ? normalizeRef(value, blockSlugs) : rewriteRefs(value, blockSlugs);
+        return out;
+    }
+    return node;
+};
+export { blockSchemaName, createSchemaName, globalSchemaName, joinsSchemaName, listSchemaName, populateSchemaName, querySchemaName, refTo, rewriteRefs, schemaName, selectSchemaName, updateSchemaName };

package/dist/spec/params.d.ts

@@ -0,0 +1,47 @@
+import type { Field } from 'payload';
+import type { ParameterObject, SchemaObject } from '@scalar/openapi-types/3.2';
+import type { BuildContext } from '../types.js';
+export declare const buildSelectSchema: ({ fields, ctx }: {
+    fields: Field[];
+    ctx: BuildContext;
+}) => SchemaObject;
+export declare const buildPopulateSchema: ({ fields, ctx, }: {
+    fields: Field[];
+    ctx: BuildContext;
+}) => SchemaObject | undefined;
+export declare const buildJoinsSchema: ({ fields, ctx }: {
+    fields: Field[];
+    ctx: BuildContext;
+}) => SchemaObject | undefined;
+export interface ParamSchemas {
+    select: SchemaObject;
+    populate?: SchemaObject;
+    joins?: SchemaObject;
+}
+export declare const buildParamSchemas: ({ fields, ctx }: {
+    fields: Field[];
+    ctx: BuildContext;
+}) => ParamSchemas;
+export declare const collectionHasFilters: (fields: Field[]) => boolean;
+export declare const buildQueryOperationsSchema: ({ base, fields, ctx, }: {
+    base: string;
+    fields: Field[];
+    ctx: BuildContext;
+}) => SchemaObject;
+export interface ReadParamRefs {
+    select: boolean;
+    populate: boolean;
+    joins: boolean;
+}
+export declare const commonReadParams: ({ base, ctx, refs, }: {
+    base: string;
+    ctx: BuildContext;
+    refs: ReadParamRefs;
+}) => ParameterObject[];
+export declare const whereParam: (base: string) => ParameterObject;
+export declare const buildListParams: ({ base, fields, ctx, refs, }: {
+    base: string;
+    fields: Field[];
+    ctx: BuildContext;
+    refs: ReadParamRefs;
+}) => ParameterObject[];

package/dist/spec/params.js

@@ -0,0 +1,344 @@
+import { makeT } from "../translations/index.js";
+import { exposableFields } from "./fields.js";
+import { joinsSchemaName, populateSchemaName, querySchemaName, refTo, selectSchemaName } from "./names.js";
+const fieldName = (field)=>'name' in field && 'string' == typeof field.name ? field.name : void 0;
+const relationTargets = (field)=>{
+    if ('relationship' !== field.type && 'upload' !== field.type) return [];
+    const relTo = field.relationTo;
+    return Array.isArray(relTo) ? relTo : [
+        relTo
+    ];
+};
+const buildSelectSchema = ({ fields, ctx })=>{
+    const properties = {};
+    for (const field of exposableFields(fields)){
+        const name = fieldName(field);
+        if (name) properties[name] = {
+            type: 'boolean'
+        };
+    }
+    return {
+        type: 'object',
+        additionalProperties: false,
+        description: makeT(ctx.i18n)('schemaSelect'),
+        properties
+    };
+};
+const buildPopulateSchema = ({ fields, ctx })=>{
+    const targets = new Set();
+    for (const field of exposableFields(fields))for (const target of relationTargets(field))targets.add(target);
+    if (0 === targets.size) return;
+    const properties = {};
+    for (const target of targets)properties[target] = {
+        type: 'object',
+        additionalProperties: {
+            type: 'boolean'
+        }
+    };
+    return {
+        type: 'object',
+        additionalProperties: false,
+        description: makeT(ctx.i18n)('schemaPopulate'),
+        properties
+    };
+};
+const buildJoinsSchema = ({ fields, ctx })=>{
+    const joinControls = {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            limit: {
+                type: 'integer'
+            },
+            page: {
+                type: 'integer'
+            },
+            sort: {
+                type: 'string'
+            },
+            count: {
+                type: 'boolean'
+            },
+            where: {
+                type: 'object',
+                additionalProperties: true
+            }
+        }
+    };
+    const properties = {};
+    for (const field of exposableFields(fields)){
+        if ('join' !== field.type) continue;
+        const name = fieldName(field);
+        if (name) properties[name] = joinControls;
+    }
+    if (0 === Object.keys(properties).length) return;
+    return {
+        type: 'object',
+        additionalProperties: false,
+        description: makeT(ctx.i18n)('schemaJoins'),
+        properties
+    };
+};
+const buildParamSchemas = ({ fields, ctx })=>({
+        select: buildSelectSchema({
+            fields,
+            ctx
+        }),
+        populate: buildPopulateSchema({
+            fields,
+            ctx
+        }),
+        joins: buildJoinsSchema({
+            fields,
+            ctx
+        })
+    });
+const OPERATORS_BY_TYPE = {
+    text: [
+        'equals',
+        'not_equals',
+        'like',
+        'contains',
+        'in',
+        'not_in',
+        'exists'
+    ],
+    textarea: [
+        'equals',
+        'not_equals',
+        'like',
+        'contains',
+        'in',
+        'not_in',
+        'exists'
+    ],
+    email: [
+        'equals',
+        'not_equals',
+        'like',
+        'contains',
+        'in',
+        'not_in',
+        'exists'
+    ],
+    code: [
+        'equals',
+        'not_equals',
+        'like',
+        'contains',
+        'exists'
+    ],
+    number: [
+        'equals',
+        'not_equals',
+        'greater_than',
+        'greater_than_equal',
+        'less_than',
+        'less_than_equal',
+        'in',
+        'not_in',
+        'exists'
+    ],
+    date: [
+        'equals',
+        'not_equals',
+        'greater_than',
+        'greater_than_equal',
+        'less_than',
+        'less_than_equal',
+        'exists'
+    ],
+    checkbox: [
+        'equals',
+        'not_equals',
+        'exists'
+    ],
+    radio: [
+        'equals',
+        'not_equals',
+        'in',
+        'not_in',
+        'exists'
+    ],
+    select: [
+        'equals',
+        'not_equals',
+        'in',
+        'not_in',
+        'exists'
+    ],
+    relationship: [
+        'equals',
+        'not_equals',
+        'in',
+        'not_in',
+        'exists'
+    ],
+    upload: [
+        'equals',
+        'not_equals',
+        'in',
+        'not_in',
+        'exists'
+    ]
+};
+const fieldHasQueryOperators = (field)=>Boolean(OPERATORS_BY_TYPE[field.type]);
+const collectionHasFilters = (fields)=>exposableFields(fields).some((f)=>fieldName(f) && fieldHasQueryOperators(f));
+const buildQueryOperationsSchema = ({ base, fields, ctx })=>{
+    const properties = {};
+    for (const field of exposableFields(fields)){
+        const name = fieldName(field);
+        const operators = OPERATORS_BY_TYPE[field.type];
+        if (name && operators) properties[name] = {
+            type: 'object',
+            additionalProperties: false,
+            properties: Object.fromEntries(operators.map((op)=>[
+                    op,
+                    {}
+                ]))
+        };
+    }
+    const selfRef = {
+        $ref: refTo(querySchemaName(base))
+    };
+    properties.and = {
+        type: 'array',
+        items: selfRef
+    };
+    properties.or = {
+        type: 'array',
+        items: selfRef
+    };
+    return {
+        type: 'object',
+        additionalProperties: false,
+        description: makeT(ctx.i18n)('schemaWhere'),
+        properties
+    };
+};
+const objectParam = (name, ref)=>({
+        name,
+        in: 'query',
+        content: {
+            'application/json': {
+                schema: ref ? {
+                    $ref: ref
+                } : {
+                    type: 'object',
+                    additionalProperties: true
+                }
+            }
+        }
+    });
+const localeParam = (ctx)=>({
+        name: 'locale',
+        in: 'query',
+        description: makeT(ctx.i18n)('paramLocale'),
+        schema: ctx.locales.length > 0 ? {
+            type: 'string',
+            enum: [
+                ...ctx.locales,
+                'all'
+            ]
+        } : {
+            type: 'string'
+        }
+    });
+const fallbackLocaleParam = (ctx)=>({
+        name: 'fallback-locale',
+        in: 'query',
+        description: makeT(ctx.i18n)('paramFallbackLocale'),
+        schema: ctx.locales.length > 0 ? {
+            type: 'string',
+            enum: [
+                ...ctx.locales,
+                'none'
+            ]
+        } : {
+            type: 'string'
+        }
+    });
+const commonReadParams = ({ base, ctx, refs })=>{
+    const params = [
+        {
+            name: 'depth',
+            in: 'query',
+            description: makeT(ctx.i18n)('paramDepth'),
+            schema: {
+                type: 'integer'
+            }
+        },
+        localeParam(ctx),
+        fallbackLocaleParam(ctx),
+        objectParam('select', refs.select ? refTo(selectSchemaName(base)) : void 0),
+        {
+            name: 'flattenLocales',
+            in: 'query',
+            description: makeT(ctx.i18n)('paramFlattenLocales'),
+            schema: {
+                type: 'boolean'
+            }
+        },
+        {
+            name: 'draft',
+            in: 'query',
+            description: makeT(ctx.i18n)('paramDraft'),
+            schema: {
+                type: 'boolean'
+            }
+        },
+        {
+            name: 'trash',
+            in: 'query',
+            description: makeT(ctx.i18n)('paramTrash'),
+            schema: {
+                type: 'boolean'
+            }
+        }
+    ];
+    if (refs.populate) params.push(objectParam('populate', refTo(populateSchemaName(base))));
+    if (refs.joins) params.push(objectParam('joins', refTo(joinsSchemaName(base))));
+    return params;
+};
+const whereParam = (base)=>objectParam('where', refTo(querySchemaName(base)));
+const buildListParams = ({ base, fields, ctx, refs })=>{
+    const params = [
+        {
+            name: 'page',
+            in: 'query',
+            schema: {
+                type: 'integer'
+            }
+        },
+        {
+            name: 'limit',
+            in: 'query',
+            schema: {
+                type: 'integer'
+            }
+        },
+        {
+            name: 'pagination',
+            in: 'query',
+            schema: {
+                type: 'boolean'
+            }
+        },
+        {
+            name: 'sort',
+            in: 'query',
+            description: makeT(ctx.i18n)('paramSort'),
+            schema: {
+                type: 'string'
+            }
+        },
+        ...commonReadParams({
+            base,
+            ctx,
+            refs
+        })
+    ];
+    if (collectionHasFilters(fields)) params.push(whereParam(base));
+    return params;
+};
+export { buildJoinsSchema, buildListParams, buildParamSchemas, buildPopulateSchema, buildQueryOperationsSchema, buildSelectSchema, collectionHasFilters, commonReadParams, whereParam };

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

@@ -0,0 +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 buildAuthPaths: ({ collection, ctx, includeAdmin, nestedTags, }: {
+    collection: SanitizedCollectionConfig;
+    ctx: BuildContext;
+    includeAdmin: boolean;
+    nestedTags: boolean;
+}) => PathsObject;