@readme/api-core 7.0.0-alpha.2 → 7.0.0-alpha.4

package/dist/lib/prepareParams.js

@@ -1,378 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const node_fs_1 = __importDefault(require("node:fs"));
-const node_path_1 = __importDefault(require("node:path"));
-const node_stream_1 = __importDefault(require("node:stream"));
-const caseless_1 = __importDefault(require("caseless"));
-const parser_1 = __importDefault(require("datauri/parser"));
-const sync_1 = __importDefault(require("datauri/sync"));
-const get_stream_1 = __importDefault(require("get-stream"));
-const lodash_merge_1 = __importDefault(require("lodash.merge"));
-const remove_undefined_objects_1 = __importDefault(require("remove-undefined-objects"));
-const getJSONSchemaDefaults_1 = __importDefault(require("./getJSONSchemaDefaults"));
-// These headers are normally only defined by the OpenAPI definition but we allow the user to
-// manually supply them in their `metadata` parameter if they wish.
-const specialHeaders = ['accept', 'authorization'];
-/**
- * Extract all available parameters from an operations Parameter Object into a digestable array
- * that we can use to apply to the request.
- *
- * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#parameterObject}
- * @see {@link https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameterObject}
- */
-function digestParameters(parameters) {
-    return parameters.reduce((prev, param) => {
-        if ('$ref' in param || 'allOf' in param || 'anyOf' in param || 'oneOf' in param) {
-            throw new Error("The OpenAPI document for this operation wasn't dereferenced before processing.");
-        }
-        else if (param.name in prev) {
-            throw new Error(`The operation you are using has the same parameter, ${param.name}, spread across multiple entry points. We unfortunately can't handle this right now.`);
-        }
-        return Object.assign(prev, { [param.name]: param });
-    }, {});
-}
-// https://github.com/you-dont-need/You-Dont-Need-Lodash-Underscore#_isempty
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function isEmpty(obj) {
-    return [Object, Array].includes((obj || {}).constructor) && !Object.entries(obj || {}).length;
-}
-function isObject(thing) {
-    if (thing instanceof node_stream_1.default.Readable) {
-        return false;
-    }
-    return typeof thing === 'object' && thing !== null && !Array.isArray(thing);
-}
-function isPrimitive(obj) {
-    return obj === null || typeof obj === 'number' || typeof obj === 'string';
-}
-function merge(src, target) {
-    if (Array.isArray(target)) {
-        // @todo we need to add support for merging array defaults with array body/metadata arguments
-        return target;
-    }
-    else if (!isObject(target)) {
-        return target;
-    }
-    return (0, lodash_merge_1.default)(src, target);
-}
-/**
- * Ingest a file path or readable stream into a common object that we can later use to process it
- * into a parameters object for making an API request.
- *
- */
-function processFile(paramName, file) {
-    if (typeof file === 'string') {
-        // In order to support relative pathed files, we need to attempt to resolve them.
-        const resolvedFile = node_path_1.default.resolve(file);
-        return new Promise((resolve, reject) => {
-            node_fs_1.default.stat(resolvedFile, async (err) => {
-                if (err) {
-                    if (err.code === 'ENOENT') {
-                        // It's less than ideal for us to handle files that don't exist like this but because
-                        // `file` is a string it might actually be the full text contents of the file and not
-                        // actually a path.
-                        //
-                        // We also can't really regex to see if `file` *looks*` like a path because one should be
-                        // able to pass in a relative `owlbert.png` (instead of `./owlbert.png`) and though that
-                        // doesn't *look* like a path, it is one that should still work.
-                        return resolve(undefined);
-                    }
-                    return reject(err);
-                }
-                const fileMetadata = await (0, sync_1.default)(resolvedFile);
-                const payloadFilename = encodeURIComponent(node_path_1.default.basename(resolvedFile));
-                return resolve({
-                    paramName,
-                    base64: fileMetadata?.content?.replace(';base64', `;name=${payloadFilename};base64`),
-                    filename: payloadFilename,
-                    buffer: fileMetadata.buffer,
-                });
-            });
-        });
-    }
-    else if (file instanceof node_stream_1.default.Readable) {
-        return get_stream_1.default.buffer(file).then(buffer => {
-            const filePath = file.path;
-            const parser = new parser_1.default();
-            const base64 = parser.format(filePath, buffer).content;
-            const payloadFilename = encodeURIComponent(node_path_1.default.basename(filePath));
-            return {
-                paramName,
-                base64: base64?.replace(';base64', `;name=${payloadFilename};base64`),
-                filename: payloadFilename,
-                buffer,
-            };
-        });
-    }
-    return Promise.reject(new TypeError(paramName
-        ? `The data supplied for the \`${paramName}\` request body parameter is not a file handler that we support.`
-        : 'The data supplied for the request body payload is not a file handler that we support.'));
-}
-/**
- * With potentially supplied body and/or metadata we need to run through them against a given API
- * operation to see what's what and prepare any available parameters to be used in an API request
- * with `@readme/oas-to-har`.
- *
- */
-async function prepareParams(operation, body, metadata) {
-    let metadataIntersected = false;
-    const digestedParameters = digestParameters(operation.getParameters());
-    const jsonSchema = operation.getParametersAsJSONSchema();
-    /**
-     * It might be common for somebody to run `sdk.findPetsByStatus({ status: 'available' }, {})`, in
-     * which case we want to filter out the second (metadata) parameter and treat the first parameter
-     * as the metadata instead. If we don't do this, their supplied `status` metadata will be treated
-     * as a body parameter, and because there's no `status` body parameter, and no supplied metadata
-     * (because it's an empty object), the request won't send a payload.
-     *
-     * @see {@link https://github.com/readmeio/api/issues/449}
-     */
-    // eslint-disable-next-line no-param-reassign
-    metadata = (0, remove_undefined_objects_1.default)(metadata);
-    if (!jsonSchema && (body !== undefined || metadata !== undefined)) {
-        let throwNoParamsError = true;
-        // If this operation doesn't have any parameters for us to transform to JSON Schema but they've
-        // sent us either an `Accept` or `Authorization` header (or both) we should let them do that.
-        // We should, however, only do this check for the `body` parameter as if they've sent this
-        // request both `body` and `metadata` we can reject it outright as the operation won't have any
-        // body data.
-        if (body !== undefined) {
-            if (typeof body === 'object' && body !== null && !Array.isArray(body)) {
-                if (Object.keys(body).length <= 2) {
-                    const bodyParams = (0, caseless_1.default)(body);
-                    if (specialHeaders.some(header => bodyParams.has(header))) {
-                        throwNoParamsError = false;
-                    }
-                }
-            }
-        }
-        if (throwNoParamsError) {
-            throw new Error("You supplied metadata and/or body data for this operation but it doesn't have any documented parameters or request payloads. If you think this is an error please contact support for the API you're using.");
-        }
-    }
-    const jsonSchemaDefaults = jsonSchema ? (0, getJSONSchemaDefaults_1.default)(jsonSchema) : {};
-    const params = jsonSchemaDefaults;
-    // If a body argument was supplied we need to do a bit of work to see if it's actually a body
-    // argument or metadata because the library lets you supply either a body, metadata, or body with
-    // metadata.
-    if (typeof body !== 'undefined') {
-        if (Array.isArray(body) || isPrimitive(body)) {
-            // If the body param is an array or a primitive then we know it's absolutely a body because
-            // metadata can only ever be undefined or an object.
-            params.body = merge(params.body, body);
-        }
-        else if (typeof metadata === 'undefined') {
-            // No metadata was explicitly provided so we need to analyze the body to determine if it's a
-            // body or should be actually be treated as metadata.
-            const headerParams = (0, caseless_1.default)({});
-            Object.entries(digestedParameters).forEach(([paramName, param]) => {
-                // Headers are sent case-insensitive so we need to make sure that we're properly
-                // matching them when detecting what our incoming payload looks like.
-                if (param.in === 'header') {
-                    headerParams.set(paramName, '');
-                }
-            });
-            // `Accept` and `Authorization` headers can't be defined as normal parameters but we should
-            // always allow the user to supply them if they wish.
-            specialHeaders.forEach(header => {
-                if (!headerParams.has(header)) {
-                    headerParams.set(header, '');
-                }
-            });
-            const intersection = Object.keys(body).filter(value => {
-                if (Object.keys(digestedParameters).includes(value)) {
-                    return true;
-                }
-                else if (headerParams.has(value)) {
-                    return true;
-                }
-                return false;
-            }).length;
-            // If more than 25% of the body intersects with the parameters that we've got on hand, then
-            // we should treat it as a metadata object and organize into parameters.
-            if (intersection && intersection / Object.keys(body).length > 0.25) {
-                /* eslint-disable no-param-reassign */
-                metadataIntersected = true;
-                metadata = merge(params.body, body);
-                body = undefined;
-                /* eslint-enable no-param-reassign */
-            }
-            else {
-                // For all other cases, we should just treat the supplied body as a body.
-                params.body = merge(params.body, body);
-            }
-        }
-        else {
-            // Body and metadata were both supplied.
-            params.body = merge(params.body, body);
-        }
-    }
-    if (!operation.hasRequestBody()) {
-        // If this operation doesn't have any documented request body then we shouldn't be sending
-        // anything.
-        delete params.body;
-    }
-    else {
-        if (!('body' in params))
-            params.body = {};
-        // We need to retrieve the request body for this operation to search for any `binary` format
-        // data that the user wants to send so we know what we need to prepare for the final API
-        // request.
-        const payloadJsonSchema = jsonSchema.find(js => js.type === 'body');
-        if (payloadJsonSchema) {
-            if (!params.files)
-                params.files = {};
-            const conversions = [];
-            // @todo add support for `type: array`, `oneOf` and `anyOf`
-            if (payloadJsonSchema.schema?.properties) {
-                Object.entries(payloadJsonSchema.schema?.properties)
-                    .filter(([, schema]) => schema?.format === 'binary')
-                    .filter(([prop]) => Object.keys(params.body).includes(prop))
-                    .forEach(([prop]) => {
-                    conversions.push(processFile(prop, params.body[prop]));
-                });
-            }
-            else if (payloadJsonSchema.schema?.type === 'string') {
-                if (payloadJsonSchema.schema?.format === 'binary') {
-                    conversions.push(processFile(undefined, params.body));
-                }
-            }
-            await Promise.all(conversions)
-                .then(fileMetadata => fileMetadata.filter(Boolean))
-                .then(fm => {
-                fm.forEach(fileMetadata => {
-                    if (!fileMetadata) {
-                        // If we don't have any metadata here it's because the file we have is likely
-                        // the full string content of the file so since we don't have any filenames to
-                        // work with we shouldn't do any additional handling to the `body` or `files`
-                        // parameters.
-                        return;
-                    }
-                    if (fileMetadata.paramName) {
-                        params.body[fileMetadata.paramName] = fileMetadata.base64;
-                    }
-                    else {
-                        params.body = fileMetadata.base64;
-                    }
-                    if (fileMetadata.buffer && params?.files) {
-                        params.files[fileMetadata.filename] = fileMetadata.buffer;
-                    }
-                });
-            });
-        }
-    }
-    // Form data should be placed within `formData` instead of `body` for it to properly get picked
-    // up by `fetch-har`.
-    if (operation.isFormUrlEncoded()) {
-        params.formData = merge(params.formData, params.body);
-        delete params.body;
-    }
-    // Only spend time trying to organize metadata into parameters if we were able to digest
-    // parameters out of the operation schema. If we couldn't digest anything, but metadata was
-    // supplied then we wouldn't know how to send it in the request!
-    if (typeof metadata !== 'undefined') {
-        if (!('cookie' in params))
-            params.cookie = {};
-        if (!('header' in params))
-            params.header = {};
-        if (!('path' in params))
-            params.path = {};
-        if (!('query' in params))
-            params.query = {};
-        Object.entries(digestedParameters).forEach(([paramName, param]) => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            let value;
-            let metadataHeaderParam;
-            if (typeof metadata === 'object' && !isEmpty(metadata)) {
-                if (paramName in metadata) {
-                    value = metadata[paramName];
-                    metadataHeaderParam = paramName;
-                }
-                else if (param.in === 'header') {
-                    // Headers are sent case-insensitive so we need to make sure that we're properly
-                    // matching them when detecting what our incoming payload looks like.
-                    metadataHeaderParam = Object.keys(metadata).find(k => k.toLowerCase() === paramName.toLowerCase()) || '';
-                    value = metadata[metadataHeaderParam];
-                }
-            }
-            if (value === undefined) {
-                return;
-            }
-            /* eslint-disable no-param-reassign */
-            switch (param.in) {
-                case 'path':
-                    params.path[paramName] = value;
-                    if (metadata?.[paramName])
-                        delete metadata[paramName];
-                    break;
-                case 'query':
-                    params.query[paramName] = value;
-                    if (metadata?.[paramName])
-                        delete metadata[paramName];
-                    break;
-                case 'header':
-                    params.header[paramName.toLowerCase()] = value;
-                    if (metadataHeaderParam && metadata?.[metadataHeaderParam])
-                        delete metadata[metadataHeaderParam];
-                    break;
-                case 'cookie':
-                    params.cookie[paramName] = value;
-                    if (metadata?.[paramName])
-                        delete metadata[paramName];
-                    break;
-                default: // no-op
-            }
-            /* eslint-enable no-param-reassign */
-            // Because a user might have sent just a metadata object, we want to make sure that we filter
-            // out anything that they sent that is a parameter from also being sent as part of a form
-            // data payload for `x-www-form-urlencoded` requests.
-            if (metadataIntersected && operation.isFormUrlEncoded()) {
-                if (paramName in params.formData) {
-                    delete params.formData[paramName];
-                }
-            }
-        });
-        // If there's any leftover metadata that hasn't been moved into form data for this request we
-        // need to move it or else it'll get tossed.
-        if (!isEmpty(metadata)) {
-            if (typeof metadata === 'object') {
-                // If the user supplied an `accept` or `authorization` header themselves we should allow it
-                // through. Normally these headers are automatically handled by `@readme/oas-to-har` but in
-                // the event that maybe the user wants to return XML for an API that normally returns JSON
-                // or specify a custom auth header (maybe we can't handle their auth case right) this is the
-                // only way with this library that they can do that.
-                specialHeaders.forEach(headerName => {
-                    const headerParam = Object.keys(metadata || {}).find(m => m.toLowerCase() === headerName);
-                    if (headerParam) {
-                        // this if-statement below is a typeguard
-                        if (typeof metadata === 'object') {
-                            // this if-statement below is a typeguard
-                            if (typeof params.header === 'object') {
-                                params.header[headerName] = metadata[headerParam];
-                            }
-                            // eslint-disable-next-line no-param-reassign
-                            delete metadata[headerParam];
-                        }
-                    }
-                });
-            }
-            if (operation.isFormUrlEncoded()) {
-                params.formData = merge(params.formData, metadata);
-            }
-            else {
-                // Any other remaining unused metadata will be unused because we don't know where to place
-                // it in the request.
-            }
-        }
-    }
-    ['body', 'cookie', 'files', 'formData', 'header', 'path', 'query'].forEach((type) => {
-        if (type in params && isEmpty(params[type])) {
-            delete params[type];
-        }
-    });
-    return params;
-}
-exports.default = prepareParams;

package/dist/lib/prepareServer.d.ts

@@ -1,10 +0,0 @@
-import type Oas from 'oas';
-/**
- * With an SDK server config and an instance of OAS we should extract and prepare the server and
- * any server variables to be supplied to `@readme/oas-to-har`.
- *
- */
-export default function prepareServer(spec: Oas, url: string, variables?: Record<string, string | number>): false | {
-    selected: number;
-    variables: Record<string, string | number>;
-};

package/dist/lib/prepareServer.js

@@ -1,46 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-function stripTrailingSlash(url) {
-    if (url[url.length - 1] === '/') {
-        return url.slice(0, -1);
-    }
-    return url;
-}
-/**
- * With an SDK server config and an instance of OAS we should extract and prepare the server and
- * any server variables to be supplied to `@readme/oas-to-har`.
- *
- */
-function prepareServer(spec, url, variables = {}) {
-    let serverIdx;
-    const sanitizedUrl = stripTrailingSlash(url);
-    (spec.api.servers || []).forEach((server, i) => {
-        if (server.url === sanitizedUrl) {
-            serverIdx = i;
-        }
-    });
-    // If we were able to find the passed in server in the OAS servers, we should use that! If we
-    // couldn't and server variables were passed in we should try our best to handle that, otherwise
-    // we should ignore the passed in server and use whever the default from the OAS is.
-    if (serverIdx) {
-        return {
-            selected: serverIdx,
-            variables,
-        };
-    }
-    else if (Object.keys(variables).length) {
-        // @todo we should run `oas.replaceUrl(url)` and pass that unto `@readme/oas-to-har`
-    }
-    else {
-        const server = spec.splitVariables(url);
-        if (server) {
-            return {
-                selected: server.selected,
-                variables: server.variables,
-            };
-        }
-        // @todo we should pass `url` directly into `@readme/oas-to-har` as the base URL
-    }
-    return false;
-}
-exports.default = prepareServer;