@seshuk/payload-plugin-openapi 0.2.1 → 1.0.0-beta.1

package/dist/endpoints/interactiveAuth.js

@@ -1,27 +0,0 @@
-const interactiveAuthHandler = (authCollectionSlug)=>async (req)=>{
-        const form = await req.formData?.();
-        const username = form?.get('username')?.toString() ?? '';
-        const password = form?.get('password')?.toString() ?? '';
-        try {
-            const result = await req.payload.login({
-                collection: authCollectionSlug,
-                data: {
-                    email: username,
-                    username,
-                    password
-                }
-            });
-            return Response.json({
-                access_token: result.token,
-                token_type: 'JWT',
-                expires_in: result.exp
-            });
-        } catch  {
-            return Response.json({
-                error: 'invalid_grant'
-            }, {
-                status: 400
-            });
-        }
-    };
-export { interactiveAuthHandler };

package/dist/endpoints/spec.d.ts

@@ -1,5 +0,0 @@
-import type { PayloadHandler } from 'payload';
-import type { ResolvedOptions } from '../types.js';
-type SpecHandler = (options: ResolvedOptions) => PayloadHandler;
-export declare const specHandler: SpecHandler;
-export {};

package/dist/endpoints/spec.js

@@ -1,39 +0,0 @@
-import { buildOpenApiDocument } from "../spec/build.js";
-const deriveServerUrl = (req)=>{
-    const host = req.headers.get('host') ?? 'localhost:3000';
-    const protocol = host.startsWith('localhost') || host.startsWith('127.') ? 'http' : 'https';
-    return `${protocol}://${host}`;
-};
-const requestedLang = (req)=>{
-    const raw = new URL(req.url ?? '', 'http://localhost').searchParams.get('lang');
-    if (!raw) return;
-    const supported = req.payload.config.i18n?.supportedLanguages;
-    return !supported || raw in supported ? raw : void 0;
-};
-const specHandler = (options)=>{
-    const cache = new Map();
-    return async (req)=>{
-        const requested = requestedLang(req);
-        const lang = requested ?? req.i18n?.language ?? req.payload.config.i18n?.fallbackLanguage ?? 'en';
-        let doc = cache.get(lang);
-        if (!options.cache || !doc) {
-            doc = await buildOpenApiDocument({
-                payload: req.payload,
-                options,
-                language: lang,
-                i18n: requested ? void 0 : req.i18n
-            });
-            cache.set(lang, doc);
-        }
-        const document = {
-            ...doc,
-            servers: [
-                {
-                    url: deriveServerUrl(req)
-                }
-            ]
-        };
-        return Response.json(document);
-    };
-};
-export { specHandler };

package/dist/options.d.ts

@@ -1,2 +0,0 @@
-import type { OpenApiPluginOptions, ResolvedOptions } from './types.js';
-export declare const resolveOptions: (options: OpenApiPluginOptions) => ResolvedOptions;

package/dist/options.js

@@ -1,45 +0,0 @@
-import { PLUGIN_NAME } from "./constants.js";
-const resolveFilters = (filters = {})=>({
-        include: filters.include ?? [],
-        exclude: filters.exclude ?? [],
-        includeHidden: filters.includeHidden ?? false,
-        includeSystem: filters.includeSystem ?? false,
-        includeCustom: filters.includeCustom ?? true,
-        includeAuth: filters.includeAuth ?? true,
-        includeAdminAuth: filters.includeAdminAuth ?? false,
-        includeVersions: filters.includeVersions ?? true,
-        includeJobs: filters.includeJobs ?? true,
-        excludeOperations: filters.excludeOperations ?? [],
-        excludeWhen: filters.excludeWhen
-    });
-const DEFAULT_AUTH_ENDPOINT = '/openapi-auth';
-const resolveInteractiveAuth = (option)=>{
-    if (!option) return {
-        enabled: false,
-        endpoint: DEFAULT_AUTH_ENDPOINT
-    };
-    if (true === option) return {
-        enabled: true,
-        endpoint: DEFAULT_AUTH_ENDPOINT
-    };
-    return {
-        enabled: true,
-        endpoint: option.endpoint ?? DEFAULT_AUTH_ENDPOINT
-    };
-};
-const resolveOptions = (options)=>{
-    if (!options.metadata?.title || !options.metadata?.version) throw new Error(`${PLUGIN_NAME}: metadata.title and metadata.version are required.`);
-    return {
-        metadata: options.metadata,
-        openapiVersion: options.openapiVersion ?? '3.2',
-        specEndpoint: options.specEndpoint ?? '/openapi.json',
-        serve: options.serve ?? true,
-        filters: resolveFilters(options.filters),
-        interactiveAuth: resolveInteractiveAuth(options.interactiveAuth),
-        nestedTags: options.nestedTags ?? false,
-        securityWhen: options.securityWhen,
-        cache: options.cache ?? true,
-        extensions: options.extensions ?? []
-    };
-};
-export { resolveOptions };

package/dist/spec/build.d.ts

@@ -1,14 +0,0 @@
-import type { BasePayload } from 'payload';
-import type { I18n } from '@payloadcms/translations';
-import type { Document } from '@scalar/openapi-types/3.2';
-import type { ResolvedOptions } from '../types.js';
-export interface BuildOpenApiInput {
-    payload: BasePayload;
-    options: ResolvedOptions;
-    language?: string;
-    i18n?: I18n;
-    servers?: {
-        url: string;
-    }[];
-}
-export declare const buildOpenApiDocument: (input: BuildOpenApiInput) => Promise<Document>;

package/dist/spec/build.js

@@ -1,36 +0,0 @@
-import { getLocalI18n } from "payload";
-import { buildDocument } from "./buildDocument.js";
-import { toOpenApi30, toOpenApi31 } from "./downconvert.js";
-const buildOpenApiDocument = async (input)=>{
-    const { payload, options, language, servers } = input;
-    const { config } = payload;
-    const locales = false === config.localization ? [] : config.localization.locales.map((locale)=>locale.code);
-    const i18n = input.i18n ?? await getLocalI18n({
-        config,
-        language: language ?? config.i18n?.fallbackLanguage
-    });
-    const supported = Object.keys(config.i18n?.supportedLanguages ?? {});
-    const docLanguages = supported.length > 0 ? supported : [
-        'en'
-    ];
-    const ctx = {
-        defaultIDType: payload.db.defaultIDType,
-        locales,
-        apiRoute: config.routes?.api ?? '/api',
-        docLanguages,
-        i18n
-    };
-    const doc = await buildDocument({
-        options,
-        servers: servers ?? [],
-        collections: Object.values(payload.collections).map((collection)=>collection.config),
-        globals: config.globals,
-        config,
-        ctx,
-        logger: payload.logger
-    });
-    if ('3.0' === options.openapiVersion) return toOpenApi30(doc);
-    if ('3.1' === options.openapiVersion) return toOpenApi31(doc);
-    return doc;
-};
-export { buildOpenApiDocument };

package/dist/spec/buildDocument.d.ts

@@ -1,15 +0,0 @@
-import type { PayloadLogger, SanitizedCollectionConfig, SanitizedConfig, SanitizedGlobalConfig } from 'payload';
-import type { Document } from '@scalar/openapi-types/3.2';
-import type { BuildContext, ResolvedOptions } from '../types.js';
-export interface BuildInput {
-    options: ResolvedOptions;
-    servers: {
-        url: string;
-    }[];
-    collections: SanitizedCollectionConfig[];
-    globals: SanitizedGlobalConfig[];
-    config: SanitizedConfig;
-    ctx: BuildContext;
-    logger: PayloadLogger;
-}
-export declare const buildDocument: (input: BuildInput) => Promise<Document>;

package/dist/spec/buildDocument.js

@@ -1,268 +0,0 @@
-import { getTranslation } from "@payloadcms/translations";
-import { PLUGIN_NAME } from "../constants.js";
-import { deepMerge } from "../utils.js";
-import { makeT } from "../translations/index.js";
-import { ERROR_SCHEMA_NAME, INTERACTIVE_SCHEME_NAME, SECURITY_SCHEME_NAME, buildErrorResponseSchema, buildListEnvelopeSchema, interactiveSecurityScheme, securityScheme } from "./components.js";
-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";
-import { buildCustomEndpointPaths } from "./paths/custom.js";
-import { buildGlobalPaths } from "./paths/globals.js";
-import { buildJobsPaths } from "./paths/jobs.js";
-import { buildVersionPaths, versionComponentSchemas } from "./paths/versions.js";
-const resolveDescription = (description, ctx)=>{
-    if (null == description) return;
-    const resolved = getTranslation(description, ctx.i18n);
-    return 'string' == typeof resolved && resolved.length > 0 ? resolved : void 0;
-};
-const registerParamSchemas = (schemas, base, fields, ctx)=>{
-    const { select, populate, joins } = buildParamSchemas({
-        fields,
-        ctx
-    });
-    schemas[selectSchemaName(base)] = select;
-    if (populate) schemas[populateSchemaName(base)] = populate;
-    if (joins) schemas[joinsSchemaName(base)] = joins;
-};
-const buildDocument = async (input)=>{
-    const { options, ctx, config, logger } = input;
-    const t = makeT(ctx.i18n);
-    const paths = {};
-    const schemas = {};
-    const { filters } = options;
-    const collections = input.collections.filter((c)=>shouldIncludeCollection(c, filters));
-    const globals = input.globals.filter((g)=>shouldIncludeGlobal(g, filters));
-    const collectionTagInfos = [];
-    const globalTagInfos = [];
-    for (const block of config.blocks ?? [])try {
-        schemas[blockSchemaName(block.slug)] = buildBlockSchema(block, config);
-    } catch (error) {
-        logger.warn(`${PLUGIN_NAME}: skipped block "${block.slug}": ${error.message}`);
-    }
-    for (const collection of collections)try {
-        const { read, create, update } = await buildEntitySchemas({
-            entity: collection,
-            config,
-            ctx
-        });
-        const base = schemaName(collection.slug);
-        collectionTagInfos.push({
-            base,
-            hasAuth: filters.includeAuth && Boolean(collection.auth),
-            hasVersions: Boolean(filters.includeVersions && collection.versions),
-            description: resolveDescription(collection.admin?.description, ctx)
-        });
-        schemas[base] = read;
-        schemas[createSchemaName(base)] = create;
-        schemas[updateSchemaName(base)] = update;
-        schemas[listSchemaName(base)] = buildListEnvelopeSchema(base);
-        if (collectionHasFilters(collection.fields)) schemas[querySchemaName(base)] = buildQueryOperationsSchema({
-            base,
-            fields: collection.fields,
-            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,
-                security
-            })
-        };
-        if (filters.includeAuth) Object.assign(collectionPaths, buildAuthPaths({
-            collection,
-            ctx,
-            includeAdmin: filters.includeAdminAuth,
-            nestedTags: options.nestedTags
-        }));
-        if (filters.includeVersions && collection.versions) {
-            const { version, versionList } = versionComponentSchemas({
-                docBase: base,
-                base,
-                idType: ctx.defaultIDType
-            });
-            schemas[`${base}Version`] = version;
-            schemas[`${base}VersionList`] = versionList;
-            Object.assign(collectionPaths, buildVersionPaths({
-                entity: collection,
-                pathBase: `${ctx.apiRoute}/${collection.slug}`,
-                ctx,
-                schemaBase: base,
-                nestedTags: options.nestedTags
-            }));
-        }
-        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}`);
-    }
-    for (const global of globals)try {
-        const { read, update } = await buildEntitySchemas({
-            entity: global,
-            config,
-            ctx
-        });
-        const gbase = globalSchemaName(global.slug);
-        globalTagInfos.push({
-            base: gbase,
-            hasVersions: Boolean(filters.includeVersions && global.versions),
-            description: resolveDescription(global.admin?.description, ctx)
-        });
-        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,
-                security
-            })
-        };
-        if (filters.includeVersions && global.versions) {
-            const { version, versionList } = versionComponentSchemas({
-                docBase: gbase,
-                base: gbase,
-                idType: ctx.defaultIDType
-            });
-            schemas[`${gbase}Version`] = version;
-            schemas[`${gbase}VersionList`] = versionList;
-            Object.assign(globalPaths, buildVersionPaths({
-                entity: global,
-                pathBase: `${ctx.apiRoute}/globals/${global.slug}`,
-                ctx,
-                schemaBase: gbase,
-                nestedTags: options.nestedTags,
-                global: true
-            }));
-        }
-        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}`);
-    }
-    if (filters.includeCustom) try {
-        Object.assign(paths, buildCustomEndpointPaths({
-            config,
-            collections,
-            globals,
-            ctx
-        }));
-    } catch (error) {
-        logger.warn(`${PLUGIN_NAME}: failed to collect custom endpoints: ${error.message}`);
-    }
-    const jobsConfig = config.jobs;
-    const hasJobs = filters.includeJobs && Boolean(jobsConfig?.tasks?.length || jobsConfig?.workflows?.length);
-    if (filters.includeJobs) try {
-        Object.assign(paths, buildJobsPaths({
-            config,
-            ctx
-        }));
-    } catch (error) {
-        logger.warn(`${PLUGIN_NAME}: failed to add jobs endpoint: ${error.message}`);
-    }
-    const supportedTimezones = config.admin?.timezones?.supportedTimezones;
-    if (Array.isArray(supportedTimezones) && supportedTimezones.length > 0) schemas[schemaName('supportedTimezones')] = {
-        type: 'string',
-        description: t('schemaSupportedTimezones'),
-        enum: supportedTimezones.map((tz)=>'string' == typeof tz ? tz : tz.value)
-    };
-    schemas[ERROR_SCHEMA_NAME] = buildErrorResponseSchema();
-    const cookiePrefix = config.cookiePrefix || 'payload';
-    const securitySchemes = {
-        [SECURITY_SCHEME_NAME]: securityScheme({
-            cookiePrefix,
-            t
-        })
-    };
-    if (options.interactiveAuth.enabled) securitySchemes[INTERACTIVE_SCHEME_NAME] = interactiveSecurityScheme({
-        tokenUrl: `${ctx.apiRoute}${options.interactiveAuth.endpoint}`,
-        t
-    });
-    const localeNote = ctx.locales.length > 0 ? `\n\n## ${t('localizationHeading')}\n\n` + t('localizationNote', {
-        locales: ctx.locales.map((l)=>`\`${l}\``).join(', ')
-    }) : '';
-    const docLanguagesNote = ctx.docLanguages.length > 1 ? `\n\n${t('docLanguagesNote', {
-        languages: ctx.docLanguages.map((l)=>`\`${l}\``).join(', ')
-    })}` : '';
-    const info = {
-        ...options.metadata,
-        description: `${options.metadata.description ?? ''}${localeNote}${docLanguagesNote}`.trim() || void 0
-    };
-    let doc = {
-        openapi: '3.2.0',
-        info,
-        servers: input.servers,
-        paths,
-        components: {
-            schemas,
-            securitySchemes
-        },
-        tags: buildTagHierarchy({
-            collections: collectionTagInfos,
-            globals: globalTagInfos,
-            hasJobs,
-            t,
-            nested: options.nestedTags
-        }),
-        'x-doc-languages': ctx.docLanguages
-    };
-    for (const ext of options.extensions)try {
-        if (ext.paths) doc.paths = deepMerge(doc.paths ?? {}, ext.paths);
-        if (ext.components) doc.components = deepMerge(doc.components ?? {}, ext.components);
-        if (ext.tags) {
-            const seen = new Set((doc.tags ?? []).map((tag)=>tag.name));
-            doc.tags = [
-                ...doc.tags ?? [],
-                ...ext.tags.filter((tag)=>!seen.has(tag.name))
-            ];
-        }
-        if (ext.transform) doc = ext.transform(doc, ctx);
-    } catch (error) {
-        logger.warn(`${PLUGIN_NAME}: extension failed and was skipped: ${error.message}`);
-    }
-    return doc;
-};
-export { buildDocument };

package/dist/spec/components.d.ts

@@ -1,44 +0,0 @@
-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;
-export declare const nullableType: (type: "integer" | "string" | "number" | "boolean") => SchemaObject;
-export declare const jsonResponse: (description: string, schema: SchemaOrRef) => ResponseObject;
-export declare const jsonOk: (description: string, schema: SchemaOrRef) => ResponsesObject;
-export declare const jsonBody: (schema: SchemaOrRef) => RequestBodyObject;
-export declare const messageResponse: (description: string) => ResponsesObject;
-export type ErrorCode = '400' | '401' | '403' | '404' | '500';
-export declare const ERROR_SCHEMA_NAME = "ErrorResponse";
-export declare const ERRORS: {
-    readonly list: ErrorCode[];
-    readonly read: ErrorCode[];
-    readonly create: ErrorCode[];
-    readonly update: ErrorCode[];
-    readonly delete: ErrorCode[];
-    readonly globalRead: ErrorCode[];
-    readonly globalUpdate: ErrorCode[];
-    readonly login: ErrorCode[];
-    readonly session: ErrorCode[];
-    readonly authAction: ErrorCode[];
-    readonly versionList: ErrorCode[];
-    readonly versionRead: ErrorCode[];
-    readonly versionRestore: ErrorCode[];
-};
-export declare const buildErrorResponseSchema: () => SchemaObject;
-export declare const errorResponses: (codes: ErrorCode[], t: Translate) => ResponsesObject;
-export declare const buildListEnvelopeSchema: (base: string) => SchemaObject;
-export declare const uploadRequestBody: ({ bodyRef, fileRequired, t, }: {
-    bodyRef: ReferenceObject;
-    fileRequired: boolean;
-    t: Translate;
-}) => RequestBodyObject;
-export declare const SECURITY_SCHEME_NAME = "PayloadToken";
-export declare const INTERACTIVE_SCHEME_NAME = "PayloadLogin";
-export declare const interactiveSecurityScheme: ({ tokenUrl, t, }: {
-    tokenUrl: string;
-    t: Translate;
-}) => SecuritySchemeObject;
-export declare const securityScheme: ({ cookiePrefix, t }: {
-    cookiePrefix: string;
-    t: Translate;
-}) => SecuritySchemeObject;
-export {};