api 7.0.0-alpha.0 → 7.0.0-alpha.2

package/dist/commands/index.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    install: import("commander").Command;
+};
+export default _default;

package/dist/commands/index.js

@@ -0,0 +1,9 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const install_1 = __importDefault(require("./install"));
+exports.default = {
+    install: install_1.default,
+};

package/dist/commands/install.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+declare const cmd: Command;
+export default cmd;

package/dist/commands/install.js

@@ -0,0 +1,179 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const figures_1 = __importDefault(require("figures"));
+const oas_1 = __importDefault(require("oas"));
+const ora_1 = __importDefault(require("ora"));
+const codegen_1 = __importDefault(require("../codegen"));
+const fetcher_1 = __importDefault(require("../fetcher"));
+const prompt_1 = __importDefault(require("../lib/prompt"));
+const logger_1 = __importDefault(require("../logger"));
+const storage_1 = __importDefault(require("../storage"));
+// @todo log logs to `.api/.logs` and have `.logs` ignored
+const cmd = new commander_1.Command();
+cmd
+    .name('install')
+    .description('install an API SDK into your codebase')
+    .argument('<uri>', 'an API to install')
+    .option('-i, --identifier <identifier>', 'API identifier (eg. `@api/petstore`)')
+    .addOption(new commander_1.Option('-l, --lang <language>', 'SDK language').choices([
+    'js',
+    'js-cjs',
+    'js-esm',
+    'ts',
+]))
+    .addOption(new commander_1.Option('-y, --yes', 'Automatically answer "yes" to any prompts printed'))
+    .action(async (uri, options) => {
+    let language;
+    if (options.lang) {
+        language = options.lang;
+    }
+    else {
+        ({ value: language } = await (0, prompt_1.default)({
+            type: 'select',
+            name: 'value',
+            message: 'What language would you like to generate an SDK for?',
+            choices: [
+                { title: 'TypeScript', value: 'ts' },
+                { title: 'JavaScript', value: 'js' },
+            ],
+            initial: 1,
+        }));
+    }
+    // Because our TS generation outputs raw TS source files we don't need to worry about CJS/ESM.
+    if (language === 'js') {
+        ({ value: language } = await (0, prompt_1.default)({
+            type: 'select',
+            name: 'value',
+            message: 'How are your project imports and exports structured?',
+            choices: [
+                { title: 'CommonJS', description: 'require/exports', value: 'cjs' },
+                { title: 'ECMAScript Modules', description: 'import/export', value: 'esm' },
+            ],
+            initial: 0,
+            format: sel => (sel === 'cjs' ? 'js-cjs' : 'js-esm'),
+        }));
+    }
+    // @todo let them know that we're going to be creating a `.api/ directory
+    // @todo detect if they have a gitigore and .npmignore and if .api woudl be ignored by that
+    // @todo don't support swagger files without upconverting them
+    if (storage_1.default.isInLockFile({ source: uri })) {
+        // @todo
+        // logger(`It looks like you already have this API installed. Would you like to update it?`);
+    }
+    let identifier;
+    if (options.identifier) {
+        // `Storage.isIdentifierValid` will throw an exception if an identifier is invalid.
+        if (storage_1.default.isIdentifierValid(options.identifier)) {
+            identifier = options.identifier;
+        }
+    }
+    else if (fetcher_1.default.isAPIRegistryUUID(uri)) {
+        identifier = fetcher_1.default.getProjectPrefixFromRegistryUUID(uri);
+    }
+    else {
+        ({ value: identifier } = await (0, prompt_1.default)({
+            type: 'text',
+            name: 'value',
+            message: 'What would you like to identify this API as? This will be how you import the SDK. (e.g. entering `petstore` would result in `@api/petstore`)',
+            validate: value => {
+                if (!value) {
+                    return false;
+                }
+                try {
+                    return storage_1.default.isIdentifierValid(value, true);
+                }
+                catch (err) {
+                    return err.message;
+                }
+            },
+        }));
+    }
+    if (!identifier) {
+        (0, logger_1.default)('You must tell us what you would like to identify this API as in order to install it.', true);
+        process.exit(1);
+    }
+    let spinner = (0, ora_1.default)('Fetching your API').start();
+    const storage = new storage_1.default(uri, identifier);
+    const oas = await storage
+        .load()
+        .then(res => {
+        spinner.succeed(spinner.text);
+        return res;
+    })
+        .then(oas_1.default.init)
+        .catch(err => {
+        // @todo cleanup installed files
+        spinner.fail(spinner.text);
+        (0, logger_1.default)(err.message, true);
+        process.exit(1);
+    });
+    // @todo look for a prettier config and if we find one ask them if we should use it
+    spinner = (0, ora_1.default)('Generating your SDK').start();
+    const generator = (0, codegen_1.default)(language, oas, './openapi.json', identifier);
+    const sdkSource = await generator
+        .generator()
+        .then(res => {
+        spinner.succeed(spinner.text);
+        return res;
+    })
+        .catch(err => {
+        // @todo cleanup installed files
+        spinner.fail(spinner.text);
+        (0, logger_1.default)(err.message, true);
+        process.exit(1);
+    });
+    spinner = (0, ora_1.default)('Saving your SDK into your codebase').start();
+    await storage
+        .saveSourceFiles(sdkSource)
+        .then(() => {
+        spinner.succeed(spinner.text);
+    })
+        .catch(err => {
+        // @todo cleanup installed files
+        spinner.fail(spinner.text);
+        (0, logger_1.default)(err.message, true);
+        process.exit(1);
+    });
+    if (generator.hasRequiredPackages()) {
+        (0, logger_1.default)(`${figures_1.default.warning} This generator requires some packages to be installed alongside it:`);
+        Object.entries(generator.requiredPackages).forEach(([pkg, pkgInfo]) => {
+            (0, logger_1.default)(`  ${figures_1.default.pointerSmall} ${pkg}: ${pkgInfo.reason} ${pkgInfo.url}`);
+        });
+        if (!options.yes) {
+            await (0, prompt_1.default)({
+                type: 'confirm',
+                name: 'value',
+                message: 'OK to proceed with package installation?',
+                initial: true,
+            }).then(({ value }) => {
+                if (!value) {
+                    // @todo cleanup installed files
+                    (0, logger_1.default)('Installation cancelled.', true);
+                    process.exit(1);
+                }
+            });
+        }
+        spinner = (0, ora_1.default)('Installing required packages').start();
+        try {
+            await generator.installer(storage);
+            spinner.succeed(spinner.text);
+        }
+        catch (err) {
+            // @todo cleanup installed files
+            spinner.fail(spinner.text);
+            (0, logger_1.default)(err.message, true);
+            process.exit(1);
+        }
+    }
+    (0, logger_1.default)('🚀 All done!');
+})
+    .addHelpText('after', `
+Examples:
+  $ api install @developers/v2.0#nysezql0wwo236
+  $ api install https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
+  $ api install ./petstore.json`);
+exports.default = cmd;

package/dist/fetcher.d.ts

@@ -0,0 +1,53 @@
+import type { OASDocument } from 'oas/rmoas.types';
+export default class Fetcher {
+    uri: string | OASDocument;
+    /**
+     * @example @petstore/v1.0#n6kvf10vakpemvplx
+     * @example @petstore#n6kvf10vakpemvplx
+     */
+    static registryUUIDRegex: RegExp;
+    constructor(uri: string | OASDocument);
+    static isAPIRegistryUUID(uri: string): boolean;
+    static isGitHubBlobURL(uri: string): boolean;
+    static getProjectPrefixFromRegistryUUID(uri: string): string | undefined;
+    load(): Promise<(import("openapi-types").OpenAPIV3.Document<{}> & Record<string, unknown>) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string | undefined;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[] | undefined;
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "paths"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "paths"> & Record<string, unknown>) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string | undefined;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[] | undefined;
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "webhooks"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "webhooks"> & Record<string, unknown>) | (Omit<Omit<import("openapi-types").OpenAPIV3.Document<{}>, "paths" | "components">, "paths" | "components" | "info" | "servers" | "webhooks" | "jsonSchemaDialect"> & {
+        info: import("openapi-types").OpenAPIV3_1.InfoObject;
+        jsonSchemaDialect?: string | undefined;
+        servers?: import("openapi-types").OpenAPIV3_1.ServerObject[] | undefined;
+    } & Pick<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }, "components"> & Omit<Partial<{
+        paths: import("openapi-types").OpenAPIV3_1.PathsObject<{}, {}>;
+        webhooks: Record<string, import("openapi-types").OpenAPIV3_1.ReferenceObject | import("openapi-types").OpenAPIV3_1.PathItemObject<{}>>;
+        components: import("openapi-types").OpenAPIV3_1.ComponentsObject;
+    }>, "components"> & Record<string, unknown>)>;
+    static getURL(url: string): Promise<any>;
+    static getFile(uri: string): Promise<any>;
+    static validate(json: OASDocument): Promise<import("openapi-types").OpenAPI.Document<{}>>;
+}

package/dist/fetcher.js

@@ -0,0 +1,123 @@
+"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 openapi_parser_1 = __importDefault(require("@readme/openapi-parser"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+class Fetcher {
+    uri;
+    /**
+     * @example @petstore/v1.0#n6kvf10vakpemvplx
+     * @example @petstore#n6kvf10vakpemvplx
+     */
+    static registryUUIDRegex = /^@(?<project>[a-zA-Z0-9-_]+)(\/?(?<version>.+))?#(?<uuid>[a-z0-9]+)$/;
+    constructor(uri) {
+        if (typeof uri === 'string') {
+            if (Fetcher.isAPIRegistryUUID(uri)) {
+                // Resolve OpenAPI definition shorthand accessors from within the ReadMe API Registry.
+                this.uri = uri.replace(Fetcher.registryUUIDRegex, 'https://dash.readme.com/api/v1/api-registry/$4');
+            }
+            else if (Fetcher.isGitHubBlobURL(uri)) {
+                /**
+                 * People may try to use a public repository URL to the source viewer on GitHub not knowing
+                 * that this page actually serves HTML. In this case we want to rewrite these to the "raw"
+                 * version of this page that'll allow us to access the API definition.
+                 *
+                 * @example https://github.com/readmeio/oas-examples/blob/main/3.1/json/petstore.json
+                 */
+                this.uri = uri.replace(/\/\/github.com/, '//raw.githubusercontent.com').replace(/\/blob\//, '/');
+            }
+            else {
+                this.uri = uri;
+            }
+        }
+        else {
+            this.uri = uri;
+        }
+    }
+    static isAPIRegistryUUID(uri) {
+        return Fetcher.registryUUIDRegex.test(uri);
+    }
+    static isGitHubBlobURL(uri) {
+        return /\/\/github.com\/[-_a-zA-Z0-9]+\/[-_a-zA-Z0-9]+\/blob\/(.*).(yaml|json|yml)/.test(uri);
+    }
+    static getProjectPrefixFromRegistryUUID(uri) {
+        const matches = uri.match(Fetcher.registryUUIDRegex);
+        if (!matches) {
+            return undefined;
+        }
+        return matches.groups?.project;
+    }
+    async load() {
+        if (typeof this.uri !== 'string') {
+            throw new TypeError("Something disastrous occurred and a non-string URI was supplied to the Fetcher library. This shouldn't have happened!");
+        }
+        return Promise.resolve(this.uri)
+            .then(uri => {
+            let url;
+            try {
+                url = new URL(uri);
+            }
+            catch (err) {
+                // If that try fails for whatever reason than the URI that we have isn't a real URL and
+                // we can safely attempt to look for it on the filesystem.
+                return Fetcher.getFile(uri);
+            }
+            return Fetcher.getURL(url.href);
+        })
+            .then(res => Fetcher.validate(res))
+            .then(res => res);
+    }
+    static getURL(url) {
+        // @todo maybe include our user-agent here to identify our request
+        return fetch(url).then(res => {
+            if (!res.ok) {
+                throw new Error(`Unable to retrieve URL (${url}). Reason: ${res.statusText}`);
+            }
+            if (res.headers.get('content-type') === 'application/yaml' || /\.(yaml|yml)/.test(url)) {
+                return res.text().then(text => {
+                    return js_yaml_1.default.load(text);
+                });
+            }
+            return res.json();
+        });
+    }
+    static getFile(uri) {
+        // Support relative paths by resolving them against the cwd.
+        const file = node_path_1.default.resolve(process.cwd(), uri);
+        if (!node_fs_1.default.existsSync(file)) {
+            throw new Error(`Sorry, we were unable to load an API definition from ${file}. Please either supply a URL or a path on your filesystem.`);
+        }
+        return Promise.resolve(node_fs_1.default.readFileSync(file, 'utf8')).then((res) => {
+            if (/\.(yaml|yml)/.test(file)) {
+                return js_yaml_1.default.load(res);
+            }
+            return JSON.parse(res);
+        });
+    }
+    static validate(json) {
+        if (json.swagger) {
+            throw new Error('Sorry, this module only supports OpenAPI definitions.');
+        }
+        // The `validate` method handles dereferencing for us.
+        return openapi_parser_1.default.validate(json, {
+            dereference: {
+                /**
+                 * If circular `$refs` are ignored they'll remain in the API definition as `$ref: String`.
+                 * This allows us to not only do easy circular reference detection but also stringify and
+                 * save dereferenced API definitions back into the cache directory.
+                 */
+                circular: 'ignore',
+            },
+        }).catch(err => {
+            if (/is not a valid openapi definition/i.test(err.message)) {
+                throw new Error("Sorry, that doesn't look like a valid OpenAPI definition.");
+            }
+            throw err;
+        });
+    }
+}
+exports.default = Fetcher;

package/dist/lib/prompt.d.ts

@@ -0,0 +1,9 @@
+import prompts from 'prompts';
+/**
+ * The `prompts` library doesn't always interpret CTRL+C and release the terminal back to the user
+ * so we need handle this ourselves. This function is just a simple overload of the main `prompts`
+ * import that we use.
+ *
+ * @see {@link https://github.com/terkelg/prompts/issues/252}
+ */
+export default function promptTerminal<T extends string = string>(question: prompts.PromptObject<T>, options?: prompts.Options): Promise<prompts.Answers<T>>;

package/dist/lib/prompt.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const prompts_1 = __importDefault(require("prompts"));
+/**
+ * The `prompts` library doesn't always interpret CTRL+C and release the terminal back to the user
+ * so we need handle this ourselves. This function is just a simple overload of the main `prompts`
+ * import that we use.
+ *
+ * @see {@link https://github.com/terkelg/prompts/issues/252}
+ */
+async function promptTerminal(question, options) {
+    const enableTerminalCursor = () => {
+        process.stdout.write('\x1B[?25h');
+    };
+    const onState = (state) => {
+        if (state.aborted) {
+            // If we don't re-enable the terminal cursor before exiting the program, the cursor will
+            // remain hidden.
+            enableTerminalCursor();
+            process.stdout.write('\n');
+            process.exit(1);
+        }
+    };
+    return (0, prompts_1.default)({ ...question, onState }, options);
+}
+exports.default = promptTerminal;

package/dist/logger.d.ts

@@ -0,0 +1 @@
+export default function logger(log: string, error?: boolean): void;

package/dist/logger.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable no-console */
+const chalk_1 = __importDefault(require("chalk"));
+function logger(log, error) {
+    if (error) {
+        console.error(chalk_1.default.red(log));
+    }
+    else {
+        console.log(log);
+    }
+}
+exports.default = logger;

package/dist/packageInfo.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_NAME = "api";
+export declare const PACKAGE_VERSION = "7.0.0-alpha.2";

package/dist/packageInfo.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACKAGE_VERSION = exports.PACKAGE_NAME = void 0;
+// This file is automatically updated by the build script.
+exports.PACKAGE_NAME = 'api';
+exports.PACKAGE_VERSION = '7.0.0-alpha.2';

package/dist/storage.d.ts

@@ -0,0 +1,106 @@
+import type { OASDocument } from 'oas/rmoas.types';
+import Fetcher from './fetcher';
+export default class Storage {
+    static dir: string;
+    static lockfile: false | Lockfile;
+    /**
+     * This is the original source that the file came from (relative/absolute file path, URL, ReadMe
+     * registry UUID, etc.).
+     */
+    source: string;
+    identifier: string;
+    fetcher: Fetcher;
+    constructor(source: string, identifier?: string);
+    static getLockfilePath(): string;
+    static getAPIsDir(): string;
+    static setStorageDir(dir?: string): void;
+    /**
+     * Reset the state of the entire storage system.
+     *
+     * This will completely destroy the contents of the `.api/` directory!
+     */
+    static reset(): Promise<void>;
+    static getDefaultLockfile(): Lockfile;
+    static generateIntegrityHash(definition: OASDocument): string;
+    static getLockfile(): Lockfile;
+    static isIdentifierValid(identifier: string, prefixWithAPINamespace?: boolean): boolean;
+    static isInLockFile(search: {
+        identifier?: string;
+        source?: string;
+    }): false | LockfileAPI;
+    setIdentifier(identifier: string): void;
+    /**
+     * Determine if the current spec + identifier we're working with is already in the lockfile.
+     */
+    isInLockfile(): boolean;
+    /**
+     * Retrieve the lockfile record for the current spec + identifier if it exists in the lockfile.
+     */
+    getFromLockfile(): LockfileAPI | undefined;
+    getIdentifierStorageDir(): string;
+    getAPIDefinition(): any;
+    saveSourceFiles(files: Record<string, string>): Promise<unknown>;
+    load(): Promise<OASDocument>;
+    /**
+     * @example <caption>Storage directory structure</caption>
+     * .api/
+     * ├── api.json             // The `package-lock.json` equivalent that records everything that's
+     * |                        // installed, when it was installed, what the original source was,
+     * |                        // and what version of `api` was used.
+     * └── apis/
+     *     ├── readme/
+     *     |   ├── node_modules/
+     *     │   ├── index.js     // We may offer the option to export a raw TS file for folks who want
+     *     |   |                // that, but for now it'll be a compiled JS file.
+     *     │   ├── index.d.ts   // All types for their SDK, ready to use in an IDE.
+     *     │   |── openapi.json
+     *     │   └── package.json
+     *     └── petstore/
+     *         ├── node_modules/
+     *         ├── index.js
+     *         ├── index.d.ts
+     *         ├── openapi.json
+     *         └── package.json
+     *
+     */
+    save(spec: OASDocument): OASDocument;
+}
+interface Lockfile {
+    apis: LockfileAPI[];
+    /**
+     * The `api.json` schema version. This will only ever change if we introduce breaking changes to
+     * this store.
+     */
+    version: '1.0';
+}
+interface LockfileAPI {
+    /**
+     * A unique identifier of the API. This'll be used to do requires on `@api/<identifier>` and also
+     * where the SDK code will be located in `.api/apis/<identifier>`.
+     *
+     * @example petstore
+     */
+    identifier: string;
+    /**
+     * The version of `api` that was used to install this SDK.
+     *
+     * @example 5.0.0
+     */
+    installerVersion: string;
+    /**
+     * An integrity hash that will be used to determine on `npx api update` calls if the API has
+     * changed since the SDK was last generated.
+     *
+     * @example sha512-ld+djZk8uRWmzXC+JYla1PTBScg0NjP/8x9vOOKRW+DuJ3NNMRjrpfbY7T77Jgnc87dZZsU49robbQfYe3ukug==
+     */
+    integrity: string;
+    /**
+     * The original source that was used to generate the SDK with.
+     *
+     * @example https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
+     * @example ./petstore.json
+     * @example @developers/v2.0#nysezql0wwo236
+     */
+    source: string;
+}
+export {};