api 7.0.0-beta.0 → 7.0.0-beta.10

package/schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "api storage lockfile",
+  "description": "See https://api.readme.dev/docs",
+  "type": "object",
+  "required": ["apis"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "apis": { "type": "array", "description": "The list of installed APIs", "items": { "$ref": "#/definitions/api" } }
+  },
+  "definitions": {
+    "api": {
+      "type": "object",
+      "required": ["createdAt", "identifier", "installerVersion", "integrity"],
+      "properties": {
+        "createdAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "The date that this SDK was installed.",
+          "examples": ["2023-10-19T20:35:39.268Z"]
+        },
+        "identifier": {
+          "type": "string",
+          "description": "A unique identifier of the API. This'll be used to do imports on `@api/<identifier>` and also where the SDK code will be located in `.api/apis/<identifier>`",
+          "examples": ["petstore"]
+        },
+        "installerVersion": {
+          "type": "string",
+          "description": "The version of `api` that was used to install this SDK.",
+          "examples": ["7.0.0"]
+        },
+        "integrity": {
+          "type": "string",
+          "description": "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.",
+          "examples": [
+            "sha512-otRF5TLMeDczSJlrmWLNDHLfmXg+C98oa/I/X2WWycwngh+a6WsbnjTbfwKGRU5DFbagOn2qX2SRvtBGOBRVGg=="
+          ]
+        },
+        "language": {
+          "type": "string",
+          "description": "The language that this SDK was generated for.",
+          "default": "js",
+          "enum": ["js"]
+        },
+        "private": {
+          "type": "boolean",
+          "description": "Was this SDK installed as a private, unpublished, package to the filesystem?"
+        },
+        "source": {
+          "type": "string",
+          "description": "The original source that was used to generate the SDK with.",
+          "examples": [
+            "https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json",
+            "./petstore.json",
+            "@developers/v2.0#nysezql0wwo236"
+          ]
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "The date that this SDK was last rebuilt or updated.",
+          "examples": ["2023-10-19T20:35:39.268Z"]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/bin.ts

@@ -1,21 +0,0 @@
-import { Command } from 'commander';
-
-import commands from './commands/index.js';
-import * as pkg from './packageInfo.js';
-
-(async () => {
-  const program = new Command();
-  program.name(pkg.PACKAGE_NAME);
-  program.version(pkg.PACKAGE_VERSION);
-
-  /**
-   * Instead of using Commander's `executableDir` API for loading in external command files we're
-   * programatically doing it like this because it's cleaner for us to let Commander manage option
-   * and argument parsing within this file than having each command  manage that itself.
-   */
-  Object.entries(commands).forEach(([, cmd]: [string, Command]) => {
-    program.addCommand(cmd);
-  });
-
-  await program.parseAsync(process.argv);
-})();

package/src/codegen/codegenerator.ts

@@ -1,75 +0,0 @@
-import type Storage from '../storage.js';
-import type Oas from 'oas';
-
-import { PACKAGE_NAME, PACKAGE_VERSION } from '../packageInfo.js';
-
-export interface InstallerOptions {
-  /**
-   * Will initiate a dry run install process. Used for simulating installations within a unit test.
-   */
-  dryRun?: boolean;
-
-  /**
-   * Used for stubbing out the logger that we use within the installation process so it can be
-   * easily introspected without having to mock out `console.*`.
-   */
-  logger?: (msg: string) => void;
-}
-
-export default abstract class CodeGenerator {
-  spec: Oas;
-
-  specPath: string;
-
-  identifier: string;
-
-  userAgent: string;
-
-  requiredPackages!: Record<
-    string,
-    {
-      dependencyType: 'production' | 'development';
-      reason: string;
-      url?: string;
-      version: string;
-    }
-  >;
-
-  constructor(spec: Oas, specPath: string, identifier: string) {
-    this.spec = spec;
-    this.specPath = specPath;
-    this.identifier = identifier;
-
-    // User agents should be contextual to the spec in question and the version of `api` that was
-    // used to generate the SDK. For example, this'll look like `petstore/1.0.0 (api/4.2.0)` for
-    // a `petstore` spec installed on api@4.2.0.
-    const info = spec.getDefinition().info;
-    this.userAgent = `${identifier}/${info.version} (${PACKAGE_NAME}/${PACKAGE_VERSION})`;
-
-    /**
-     * This check is barbaric but there are a number of issues with how the `transformer` work we
-     * have in `oas` and in `.getParametersAsJSONSchema()` and `.getResponseAsJSONSchema()` that
-     * are fully crashing when attempting to codegen an SDK for an API definition that has a
-     * circular reference.
-     *
-     * In order to get v5 out the door we're not going to support this case initialy.
-     *
-     * @see {@link https://github.com/readmeio/api/issues/549}
-     */
-    if (JSON.stringify(spec.api).includes('"$ref":"#/')) {
-      throw new Error(
-        'Sorry, this library does not yet support generating an SDK for an OpenAPI definition that contains circular references.',
-      );
-    }
-  }
-
-  abstract generate(): Promise<Record<string, string>>;
-
-  abstract install(storage: Storage, opts?: InstallerOptions): Promise<void>;
-
-  abstract compile(storage: Storage, opts?: InstallerOptions): Promise<void>;
-
-  hasRequiredPackages() {
-    return Boolean(Object.keys(this.requiredPackages));
-  }
-}

package/src/codegen/factory.ts

@@ -1,23 +0,0 @@
-import type CodeGenerator from './codegenerator.js';
-import type Oas from 'oas';
-
-import TSGenerator from './languages/typescript/index.js';
-
-export enum SupportedLanguages {
-  JS = 'js',
-}
-
-export default function codegenFactory(
-  language: SupportedLanguages,
-  spec: Oas,
-  specPath: string,
-  identifier: string,
-): CodeGenerator {
-  switch (language) {
-    case SupportedLanguages.JS:
-      return new TSGenerator(spec, specPath, identifier);
-
-    default:
-      throw new TypeError(`Unsupported language supplied: ${language}`);
-  }
-}