@seshuk/payload-plugin-openapi 0.1.0

package/dist/spec/components.js

@@ -0,0 +1,280 @@
+import { refTo } from "./names.js";
+const nullableType = (type)=>({
+        type: [
+            type,
+            'null'
+        ]
+    });
+const jsonResponse = (description, schema)=>({
+        description,
+        content: {
+            'application/json': {
+                schema
+            }
+        }
+    });
+const jsonOk = (description, schema)=>({
+        200: jsonResponse(description, schema)
+    });
+const jsonBody = (schema)=>({
+        required: true,
+        content: {
+            'application/json': {
+                schema
+            }
+        }
+    });
+const messageResponse = (description)=>jsonOk(description, {
+        type: 'object',
+        properties: {
+            message: {
+                type: 'string'
+            }
+        }
+    });
+const ERROR_SCHEMA_NAME = 'ErrorResponse';
+const ERROR_KEYS = {
+    400: 'error400',
+    401: 'error401',
+    403: 'error403',
+    404: 'error404',
+    500: 'error500'
+};
+const ERRORS = {
+    list: [
+        '400',
+        '403',
+        '500'
+    ],
+    read: [
+        '403',
+        '404',
+        '500'
+    ],
+    create: [
+        '400',
+        '403',
+        '500'
+    ],
+    update: [
+        '400',
+        '403',
+        '404',
+        '500'
+    ],
+    delete: [
+        '403',
+        '404',
+        '500'
+    ],
+    globalRead: [
+        '403',
+        '500'
+    ],
+    globalUpdate: [
+        '400',
+        '403',
+        '500'
+    ],
+    login: [
+        '400',
+        '401',
+        '403',
+        '500'
+    ],
+    session: [
+        '401',
+        '500'
+    ],
+    authAction: [
+        '400',
+        '403',
+        '500'
+    ],
+    versionList: [
+        '400',
+        '403',
+        '404',
+        '500'
+    ],
+    versionRead: [
+        '403',
+        '404',
+        '500'
+    ],
+    versionRestore: [
+        '403',
+        '404',
+        '500'
+    ]
+};
+const buildErrorResponseSchema = ()=>({
+        type: 'object',
+        properties: {
+            errors: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    properties: {
+                        message: {
+                            type: 'string'
+                        },
+                        name: {
+                            type: 'string'
+                        },
+                        field: {
+                            type: 'string'
+                        },
+                        data: {
+                            type: 'object',
+                            additionalProperties: true
+                        }
+                    },
+                    required: [
+                        'message'
+                    ]
+                }
+            }
+        },
+        required: [
+            'errors'
+        ]
+    });
+const errorRef = {
+    $ref: refTo(ERROR_SCHEMA_NAME)
+};
+const errorContent = (description)=>({
+        description,
+        content: {
+            'application/json': {
+                schema: errorRef
+            }
+        }
+    });
+const errorResponses = (codes, t)=>{
+    const responses = {};
+    for (const code of codes)responses[code] = errorContent(t(ERROR_KEYS[code]));
+    return responses;
+};
+const buildListEnvelopeSchema = (base)=>({
+        type: 'object',
+        properties: {
+            docs: {
+                type: 'array',
+                items: {
+                    $ref: refTo(base)
+                }
+            },
+            totalDocs: {
+                type: 'integer'
+            },
+            limit: {
+                type: 'integer'
+            },
+            totalPages: {
+                type: 'integer'
+            },
+            page: {
+                type: 'integer'
+            },
+            pagingCounter: {
+                type: 'integer'
+            },
+            hasPrevPage: {
+                type: 'boolean'
+            },
+            hasNextPage: {
+                type: 'boolean'
+            },
+            prevPage: nullableType('integer'),
+            nextPage: nullableType('integer')
+        },
+        required: [
+            'docs',
+            'totalDocs',
+            'limit',
+            'totalPages',
+            'page'
+        ]
+    });
+const uploadRequestBody = ({ bodyRef, fileRequired, t })=>{
+    const fieldsSchemaName = bodyRef.$ref.split('/').pop() ?? 'the document';
+    return {
+        required: fileRequired,
+        description: t('uploadBody'),
+        content: {
+            'multipart/form-data': {
+                schema: {
+                    type: 'object',
+                    properties: {
+                        file: {
+                            type: 'string',
+                            format: 'binary',
+                            description: t('uploadFile')
+                        },
+                        _payload: {
+                            allOf: [
+                                bodyRef
+                            ],
+                            description: t('uploadPayloadField', {
+                                schema: fieldsSchemaName
+                            })
+                        }
+                    },
+                    ...fileRequired ? {
+                        required: [
+                            'file'
+                        ]
+                    } : {}
+                },
+                encoding: {
+                    file: {
+                        contentType: 'application/octet-stream'
+                    },
+                    _payload: {
+                        contentType: 'application/json'
+                    }
+                }
+            },
+            'application/json': {
+                schema: bodyRef
+            }
+        }
+    };
+};
+const SECURITY_SCHEME_NAME = 'PayloadToken';
+const INTERACTIVE_SCHEME_NAME = 'PayloadLogin';
+const interactiveSecurityScheme = ({ tokenUrl, t })=>({
+        type: 'oauth2',
+        description: t('securityInteractive'),
+        flows: {
+            password: {
+                tokenUrl,
+                scopes: {}
+            }
+        }
+    });
+const securityScheme = ({ cookiePrefix, t })=>({
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+        description: t('securityBearer', {
+            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 };

package/dist/spec/downconvert.d.ts

@@ -0,0 +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;

package/dist/spec/downconvert.js

@@ -0,0 +1,55 @@
+const NULL = 'null';
+const UNSUPPORTED_KEYWORDS = [
+    '$schema',
+    '$id',
+    '$comment',
+    'unevaluatedProperties',
+    'patternProperties',
+    'propertyNames'
+];
+const isStringType = (type)=>'string' === type || Array.isArray(type) && type.includes('string');
+const downconvertTo30 = (node)=>{
+    if (Array.isArray(node)) return node.map(downconvertTo30);
+    if (!node || 'object' != typeof node) return node;
+    const out = {};
+    for (const [key, value] of Object.entries(node))out[key] = downconvertTo30(value);
+    if (isStringType(out.type) && 'application/octet-stream' === out.contentMediaType) {
+        if (void 0 === out.format) out.format = 'binary';
+        delete out.contentMediaType;
+    }
+    if (isStringType(out.type) && 'base64' === out.contentEncoding) {
+        if (void 0 === out.format) out.format = 'byte';
+        delete out.contentEncoding;
+    }
+    if (Array.isArray(out.type)) {
+        const types = out.type;
+        if (types.includes(NULL)) out.nullable = true;
+        const rest = types.filter((t)=>t !== NULL);
+        out.type = 1 === rest.length ? rest[0] : rest;
+    }
+    if ('const' in out) {
+        out.enum = [
+            out.const
+        ];
+        delete out.const;
+    }
+    if (Array.isArray(out.examples)) {
+        const examples = out.examples;
+        if (examples.length > 0) out.example = examples[0];
+        if (examples.length > 1) out['x-examples'] = examples;
+        delete out.examples;
+    }
+    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)
+    });
+export { toOpenApi30, toOpenApi31 };

package/dist/spec/entitySchemas.d.ts

@@ -0,0 +1,15 @@
+import type { Block, SanitizedConfig } from 'payload';
+import type { SchemaObject } from '@scalar/openapi-types/3.2';
+import type { BuildContext, Entity } from '../types.js';
+export declare const resolveLocalizedStrings: (value: unknown, ctx: BuildContext) => unknown;
+export interface EntitySchemas {
+    read: SchemaObject;
+    create: SchemaObject;
+    update: SchemaObject;
+}
+export declare const buildEntitySchemas: ({ entity, config, ctx, }: {
+    entity: Entity;
+    config: SanitizedConfig;
+    ctx: BuildContext;
+}) => Promise<EntitySchemas>;
+export declare const buildBlockSchema: (block: Block, config: SanitizedConfig) => SchemaObject;

package/dist/spec/entitySchemas.js

@@ -0,0 +1,246 @@
+import { entityToJSONSchema } from "payload";
+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";
+const READ_HIDDEN_FIELDS = new Set([
+    ...AUTH_FIELDS,
+    'collection'
+]);
+const SERVER_FIELDS = [
+    'id',
+    'createdAt',
+    'updatedAt'
+];
+const stripInterfaceName = (entity)=>{
+    const { interfaceName: _omit, ...rest } = entity;
+    return rest;
+};
+const toComponentSchema = ({ config, source, idType })=>{
+    const jsonSchema = entityToJSONSchema(config, source, new Map(), idType);
+    const blockSlugs = new Set((config.blocks ?? []).map((b)=>b.slug));
+    const schema = rewriteRefs(jsonSchema, blockSlugs);
+    delete schema.title;
+    return schema;
+};
+const fieldOpenapi = (field)=>{
+    const meta = field.custom?.openapi;
+    return isPlainObject(meta) ? meta : void 0;
+};
+const isLocaleKeyed = (value, ctx)=>{
+    if (!isPlainObject(value)) return false;
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every((k)=>ctx.locales.includes(k)) && Object.values(value).every((v)=>'string' == typeof v);
+};
+const LOCALIZABLE_KEYS = new Set([
+    "description",
+    'title',
+    'summary'
+]);
+const resolveTextValue = (value, ctx)=>{
+    if ('function' == typeof value) try {
+        const result = value({
+            t: ctx.i18n.t,
+            i18n: ctx.i18n
+        });
+        return 'string' == typeof result && result.length > 0 ? result : void 0;
+    } catch  {
+        return;
+    }
+    if (isLocaleKeyed(value, ctx)) return getTranslation(value, ctx.i18n);
+};
+const resolveLocalizedStrings = (value, ctx)=>{
+    if (!isPlainObject(value)) return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)){
+        if (LOCALIZABLE_KEYS.has(k)) {
+            const resolved = resolveTextValue(v, ctx);
+            if (void 0 !== resolved) out[k] = resolved;
+            else if ('function' != typeof v) out[k] = resolveLocalizedStrings(v, ctx);
+            continue;
+        }
+        out[k] = resolveLocalizedStrings(v, ctx);
+    }
+    return out;
+};
+const applyFieldOverrides = ({ schema, fields, ctx })=>{
+    if (!schema.properties) return;
+    for (const field of flattenFields(fields)){
+        const name = 'name' in field ? field.name : void 0;
+        const override = fieldOpenapi(field);
+        if (!name || !override) continue;
+        const current = schema.properties[name];
+        if (isPlainObject(current)) {
+            const resolved = resolveLocalizedStrings(override, ctx);
+            schema.properties[name] = deepMerge(current, resolved);
+        }
+    }
+};
+const isRef = (value)=>isPlainObject(value) && 'string' == typeof value.$ref;
+const isBlockBranch = (branch)=>{
+    if (isRef(branch)) return branch.$ref.startsWith('#/components/schemas/Block');
+    return isPlainObject(branch) && isPlainObject(branch.properties) && 'blockType' in branch.properties;
+};
+const addBlockDiscriminators = (node)=>{
+    if (Array.isArray(node)) {
+        for (const item of node)addBlockDiscriminators(item);
+        return;
+    }
+    if (!isPlainObject(node)) return;
+    const oneOf = node.oneOf;
+    if (Array.isArray(oneOf) && oneOf.length > 0 && oneOf.every(isBlockBranch)) node.discriminator = {
+        propertyName: 'blockType'
+    };
+    for (const value of Object.values(node))addBlockDiscriminators(value);
+};
+const markLocalizedFields = ({ schema, fields, ctx })=>{
+    if (!schema.properties || 0 === ctx.locales.length) return;
+    for (const field of flattenFields(fields)){
+        if (!('localized' in field) || !field.localized) continue;
+        const name = 'name' in field ? field.name : void 0;
+        if (!name || !(name in schema.properties)) continue;
+        const single = schema.properties[name];
+        schema.properties[name] = {
+            oneOf: [
+                single,
+                {
+                    type: 'object',
+                    description: makeT(ctx.i18n)('schemaPerLocale'),
+                    properties: Object.fromEntries(ctx.locales.map((l)=>[
+                            l,
+                            single
+                        ]))
+                }
+            ]
+        };
+    }
+};
+const removeProps = (schema, names)=>{
+    if (!schema.properties) return;
+    for (const name of names)delete schema.properties[name];
+    if (Array.isArray(schema.required)) {
+        const drop = new Set(names);
+        schema.required = schema.required.filter((r)=>!drop.has(r));
+    }
+};
+const buildBaseSchema = ({ entity, config, ctx })=>{
+    const schema = toComponentSchema({
+        config,
+        source: stripInterfaceName(entity),
+        idType: ctx.defaultIDType
+    });
+    const isAuth = 'auth' in entity && Boolean(entity.auth);
+    if (isAuth) removeProps(schema, READ_HIDDEN_FIELDS);
+    applyFieldOverrides({
+        schema,
+        fields: entity.fields,
+        ctx
+    });
+    addBlockDiscriminators(schema);
+    return schema;
+};
+const cloneSchema = (schema)=>({
+        ...schema,
+        properties: {
+            ...schema.properties
+        },
+        required: Array.isArray(schema.required) ? [
+            ...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 isAuth = 'auth' in entity && Boolean(entity.auth);
+    const idType = ctx.defaultIDType;
+    const create = cloneSchema(read);
+    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'
+        };
+        create.required = [
+            ...new Set([
+                ...create.required ?? [],
+                'password'
+            ])
+        ];
+    }
+    const update = cloneSchema(read);
+    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'
+    };
+    markLocalizedFields({
+        schema: read,
+        fields: entity.fields,
+        ctx
+    });
+    return {
+        read,
+        create,
+        update
+    };
+};
+const buildBlockSchema = (block, config)=>{
+    const schema = toComponentSchema({
+        config,
+        source: stripInterfaceName(block),
+        idType: 'text'
+    });
+    const blockType = {
+        type: 'string',
+        enum: [
+            block.slug
+        ]
+    };
+    const properties = {
+        ...schema.properties,
+        blockType
+    };
+    const required = [
+        ...new Set([
+            'blockType',
+            ...schema.required ?? []
+        ])
+    ];
+    return {
+        ...schema,
+        type: 'object',
+        properties,
+        required
+    };
+};
+export { buildBlockSchema, buildEntitySchemas, resolveLocalizedStrings };

package/dist/spec/fields.d.ts

@@ -0,0 +1,5 @@
+import type { Field } from 'payload';
+export declare const isHiddenField: (field: Field) => boolean;
+export declare const AUTH_FIELDS: Set<string>;
+export declare const flattenFields: (fields: Field[]) => Field[];
+export declare const exposableFields: (fields: Field[]) => Field[];

package/dist/spec/fields.js

@@ -0,0 +1,44 @@
+const isHiddenField = (field)=>'hidden' in field && true === field.hidden;
+const AUTH_FIELDS = new Set([
+    'salt',
+    'hash',
+    'password',
+    'resetPasswordToken',
+    'resetPasswordExpiration',
+    'loginAttempts',
+    'lockUntil',
+    'sessions'
+]);
+const hasName = (field)=>'name' in field && 'string' == typeof field.name;
+const flattenFields = (fields)=>{
+    const out = [];
+    for (const field of fields)if ('ui' !== field.type) {
+        if ('row' === field.type || 'collapsible' === field.type) {
+            out.push(...flattenFields(field.fields));
+            continue;
+        }
+        if ('tabs' === field.type) {
+            for (const tab of field.tabs){
+                const tabName = hasName(tab) ? tab.name : void 0;
+                if (tabName) out.push({
+                    type: 'group',
+                    name: tabName,
+                    fields: tab.fields
+                });
+                else out.push(...flattenFields(tab.fields));
+            }
+            continue;
+        }
+        if ('group' === field.type && !hasName(field)) {
+            out.push(...flattenFields(field.fields));
+            continue;
+        }
+        out.push(field);
+    }
+    return out;
+};
+const exposableFields = (fields)=>flattenFields(fields).filter((field)=>{
+        const name = 'name' in field ? field.name : void 0;
+        return Boolean(name) && !isHiddenField(field) && !AUTH_FIELDS.has(name);
+    });
+export { AUTH_FIELDS, exposableFields, flattenFields, isHiddenField };

package/dist/spec/filters.d.ts

@@ -0,0 +1,11 @@
+import type { SanitizedCollectionConfig, SanitizedGlobalConfig } from 'payload';
+import type { PathsObject } from '@scalar/openapi-types/3.2';
+import type { EntityKind, ResolvedFilters } from '../types.js';
+export declare const shouldIncludeCollection: (collection: SanitizedCollectionConfig, filters: ResolvedFilters) => boolean;
+export declare const shouldIncludeGlobal: (global: SanitizedGlobalConfig, filters: ResolvedFilters) => boolean;
+export declare const filterOperations: ({ paths, slug, kind, filters, }: {
+    paths: PathsObject;
+    slug: string;
+    kind: EntityKind;
+    filters: ResolvedFilters;
+}) => PathsObject;