api 7.0.0-beta.2 → 7.0.0-beta.4

package/dist/bin.js

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import commands from './commands/index.js';
+import logger from './logger.js';
 import * as pkg from './packageInfo.js';
 (async () => {
     const program = new Command();
@@ -13,6 +14,10 @@ import * as pkg from './packageInfo.js';
     Object.entries(commands).forEach(([, cmd]) => {
         program.addCommand(cmd);
     });
-    await program.parseAsync(process.argv);
+    await program.parseAsync(process.argv).catch(err => {
+        if (err.message)
+            logger(err.message, true);
+        process.exit(1);
+    });
 })();
 //# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AAExC,CAAC,KAAK,IAAI,EAAE;IACV,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC/B,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAErC;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAoB,EAAE,EAAE;QAC9D,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACzC,CAAC,CAAC,EAAE,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,QAAQ,MAAM,qBAAqB,CAAC;AAC3C,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AAExC,CAAC,KAAK,IAAI,EAAE;IACV,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAC/B,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IAErC;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,CAAoB,EAAE,EAAE;QAC9D,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IAEH,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;QACjD,IAAI,GAAG,CAAC,OAAO;YAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,EAAE,CAAC"}

package/dist/codegen/codegenerator.d.ts

@@ -2,16 +2,50 @@ import type { InstallerOptions } from './factory.js';
 import type Storage from '../storage.js';
 import type Oas from 'oas';
 export default abstract class CodeGenerator {
+    /** The associated API definition */
     spec: Oas;
+    /**
+     * The path to the API definion (might be a local path, a URL, or an API registry identifier)
+     * @example https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
+     * @example @petstore/v1.0#n6kvf10vakpemvplx
+     * @example ./petstore.json
+     */
     specPath: string;
+    /**
+     * The user-specified identifier for the SDK,
+     * used as the directory name in the `.api/apis` directory
+     * where the SDK source code is located.
+     */
     identifier: string;
+    /** The user agent which is set for all outgoing fetch requests */
     userAgent: string;
+    /**
+     * The license associated with the SDK.
+     * This is extrapolated from the API definition file.
+     */
+    spdxLicense?: string;
+    /**
+     * Contact info for the API and/or SDK author in case users need support.
+     * This is extrapolated from the API definition file.
+     */
+    apiContact: {
+        name?: string;
+        url?: string;
+    };
+    /**
+     * An object containing any downstream packages that are required
+     * for building/executing the SDK.
+     */
     requiredPackages: Record<string, {
         dependencyType: 'production' | 'development';
         reason: string;
         url?: string;
         version: string;
     }>;
+    /**
+     * An example code snippet that a user can run to get started with the SDK.
+     */
+    exampleCodeSnippet?: string | false;
     constructor(spec: Oas, specPath: string, identifier: string);
     abstract generate(): Promise<Record<string, string>>;
     abstract install(storage: Storage, opts?: InstallerOptions): Promise<void>;
@@ -24,6 +58,7 @@ export default abstract class CodeGenerator {
      */
     static uninstall(storage: Storage, opts?: InstallerOptions): Promise<void>;
     abstract compile(storage: Storage, opts?: InstallerOptions): Promise<void>;
+    abstract getExampleCodeSnippet(): Promise<string | false>;
     hasRequiredPackages(): boolean;
 }
 //# sourceMappingURL=codegenerator.d.ts.map

package/dist/codegen/codegenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codegenerator.d.ts","sourceRoot":"","sources":["../../src/codegen/codegenerator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,OAAO,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAI3B,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,aAAa;IACzC,IAAI,EAAE,GAAG,CAAC;IAEV,QAAQ,EAAE,MAAM,CAAC;IAEjB,UAAU,EAAE,MAAM,CAAC;IAEnB,SAAS,EAAE,MAAM,CAAC;IAElB,gBAAgB,EAAG,MAAM,CACvB,MAAM,EACN;QACE,cAAc,EAAE,YAAY,GAAG,aAAa,CAAC;QAC7C,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CACF,CAAC;gBAEU,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IA4B3D,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpD,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E;;;;;;OAMG;WAEU,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhF,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E,mBAAmB;CAGpB"}
+{"version":3,"file":"codegenerator.d.ts","sourceRoot":"","sources":["../../src/codegen/codegenerator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,OAAO,MAAM,eAAe,CAAC;AACzC,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAO3B,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,aAAa;IACzC,oCAAoC;IACpC,IAAI,EAAE,GAAG,CAAC;IAEV;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAM;IAEjD;;;OAGG;IACH,gBAAgB,EAAG,MAAM,CACvB,MAAM,EACN;QACE,cAAc,EAAE,YAAY,GAAG,aAAa,CAAC;QAC7C,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CACF,CAAC;IAEF;;OAEG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;gBAExB,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAgE3D,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEpD,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E;;;;;;OAMG;WAEU,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhF,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAE1E,QAAQ,CAAC,qBAAqB,IAAI,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC;IAEzD,mBAAmB;CAGpB"}

package/dist/codegen/codegenerator.js

@@ -1,10 +1,42 @@
+import { findLicense } from 'license';
 import { PACKAGE_NAME, PACKAGE_VERSION } from '../packageInfo.js';
 export default class CodeGenerator {
+    /** The associated API definition */
     spec;
+    /**
+     * The path to the API definion (might be a local path, a URL, or an API registry identifier)
+     * @example https://raw.githubusercontent.com/readmeio/oas-examples/main/3.0/json/petstore-simple.json
+     * @example @petstore/v1.0#n6kvf10vakpemvplx
+     * @example ./petstore.json
+     */
     specPath;
+    /**
+     * The user-specified identifier for the SDK,
+     * used as the directory name in the `.api/apis` directory
+     * where the SDK source code is located.
+     */
     identifier;
+    /** The user agent which is set for all outgoing fetch requests */
     userAgent;
+    /**
+     * The license associated with the SDK.
+     * This is extrapolated from the API definition file.
+     */
+    spdxLicense;
+    /**
+     * Contact info for the API and/or SDK author in case users need support.
+     * This is extrapolated from the API definition file.
+     */
+    apiContact = {};
+    /**
+     * An object containing any downstream packages that are required
+     * for building/executing the SDK.
+     */
     requiredPackages;
+    /**
+     * An example code snippet that a user can run to get started with the SDK.
+     */
+    exampleCodeSnippet;
     constructor(spec, specPath, identifier) {
         this.spec = spec;
         this.specPath = specPath;
@@ -27,6 +59,40 @@ export default class CodeGenerator {
         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.');
         }
+        const infoObject = this.spec.api.info;
+        if (infoObject?.license?.name || infoObject?.license?.identifier) {
+            let spdxLicense;
+            if (infoObject?.license?.identifier) {
+                spdxLicense = infoObject?.license?.identifier;
+            }
+            else {
+                // Though `name` is required by the OpenAPI specification but most people seem to use `name`
+                // instead `identifier` for their licensing identifier so if they've done this we should
+                // try to make the license name recognizable by the `license` package. For example this'll
+                // change "Apache 2.0" to the SPDX-recognized "Apache-2.0".
+                spdxLicense = infoObject?.license?.name.replace(/ /g, '-');
+            }
+            // If the license they've got has too many matches we shouldn't try to pick a license because
+            // we'll run the risk of licensing it under a license they didn't intend.
+            if (findLicense(spdxLicense).length === 1) {
+                this.spdxLicense = spdxLicense;
+            }
+        }
+        if (infoObject?.contact) {
+            if (infoObject.contact?.name || infoObject.contact?.email) {
+                if (infoObject.contact?.name && infoObject.contact?.email) {
+                    this.apiContact.name = `${infoObject.contact.name} <${infoObject.contact.email}>`;
+                }
+                else {
+                    this.apiContact.name = infoObject.contact.email
+                        ? `<${infoObject.contact.email}>`
+                        : infoObject.contact.name ?? undefined;
+                }
+            }
+            if (infoObject.contact?.url) {
+                this.apiContact.url = infoObject.contact.url;
+            }
+        }
     }
     /**
      * It would be better if this were an abstract function but TS/JS doesn't have support for that so

package/dist/codegen/codegenerator.js.map

@@ -1 +1 @@
-{"version":3,"file":"codegenerator.js","sourceRoot":"","sources":["../../src/codegen/codegenerator.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAElE,MAAM,CAAC,OAAO,OAAgB,aAAa;IACzC,IAAI,CAAM;IAEV,QAAQ,CAAS;IAEjB,UAAU,CAAS;IAEnB,SAAS,CAAS;IAElB,gBAAgB,CAQd;IAEF,YAAY,IAAS,EAAE,QAAgB,EAAE,UAAkB;QACzD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,6FAA6F;QAC7F,4FAA4F;QAC5F,4CAA4C;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,OAAO,KAAK,YAAY,IAAI,eAAe,GAAG,CAAC;QAEtF;;;;;;;;;WASG;QACH,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE;YACnD,MAAM,IAAI,KAAK,CACb,yHAAyH,CAC1H,CAAC;SACH;IACH,CAAC;IAMD;;;;;;OAMG;IACH,6DAA6D;IAC7D,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,OAAgB,EAAE,IAAuB;QAC9D,MAAM,IAAI,SAAS,CAAC,oEAAoE,CAAC,CAAC;IAC5F,CAAC;IAID,mBAAmB;QACjB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACrD,CAAC;CACF"}
+{"version":3,"file":"codegenerator.js","sourceRoot":"","sources":["../../src/codegen/codegenerator.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAElE,MAAM,CAAC,OAAO,OAAgB,aAAa;IACzC,oCAAoC;IACpC,IAAI,CAAM;IAEV;;;;;OAKG;IACH,QAAQ,CAAS;IAEjB;;;;OAIG;IACH,UAAU,CAAS;IAEnB,kEAAkE;IAClE,SAAS,CAAS;IAElB;;;OAGG;IACH,WAAW,CAAU;IAErB;;;OAGG;IACH,UAAU,GAAoC,EAAE,CAAC;IAEjD;;;OAGG;IACH,gBAAgB,CAQd;IAEF;;OAEG;IACH,kBAAkB,CAAkB;IAEpC,YAAY,IAAS,EAAE,QAAgB,EAAE,UAAkB;QACzD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAE7B,6FAA6F;QAC7F,4FAA4F;QAC5F,4CAA4C;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC,IAAI,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,GAAG,UAAU,IAAI,IAAI,CAAC,OAAO,KAAK,YAAY,IAAI,eAAe,GAAG,CAAC;QAEtF;;;;;;;;;WASG;QACH,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE;YACnD,MAAM,IAAI,KAAK,CACb,yHAAyH,CAC1H,CAAC;SACH;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAA8B,CAAC;QAChE,IAAI,UAAU,EAAE,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE;YAChE,IAAI,WAAW,CAAC;YAChB,IAAI,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE;gBACnC,WAAW,GAAG,UAAU,EAAE,OAAO,EAAE,UAAU,CAAC;aAC/C;iBAAM;gBACL,4FAA4F;gBAC5F,wFAAwF;gBACxF,0FAA0F;gBAC1F,2DAA2D;gBAC3D,WAAW,GAAG,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;aAC5D;YAED,6FAA6F;YAC7F,yEAAyE;YACzE,IAAI,WAAW,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE;gBACzC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;aAChC;SACF;QAED,IAAI,UAAU,EAAE,OAAO,EAAE;YACvB,IAAI,UAAU,CAAC,OAAO,EAAE,IAAI,IAAI,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE;gBACzD,IAAI,UAAU,CAAC,OAAO,EAAE,IAAI,IAAI,UAAU,CAAC,OAAO,EAAE,KAAK,EAAE;oBACzD,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,KAAK,UAAU,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC;iBACnF;qBAAM;oBACL,IAAI,CAAC,UAAU,CAAC,IAAI,GAAG,UAAU,CAAC,OAAO,CAAC,KAAK;wBAC7C,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,KAAK,GAAG;wBACjC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,IAAI,SAAS,CAAC;iBAC1C;aACF;YAED,IAAI,UAAU,CAAC,OAAO,EAAE,GAAG,EAAE;gBAC3B,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC;aAC9C;SACF;IACH,CAAC;IAMD;;;;;;OAMG;IACH,6DAA6D;IAC7D,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,OAAgB,EAAE,IAAuB;QAC9D,MAAM,IAAI,SAAS,CAAC,oEAAoE,CAAC,CAAC;IAC5F,CAAC;IAMD,mBAAmB;QACjB,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACrD,CAAC;CACF"}

package/dist/codegen/languages/typescript/index.d.ts

@@ -1,6 +1,6 @@
 import type { InstallerOptions } from '../../factory.js';
 import type Oas from 'oas';
-import type { ClassDeclaration } from 'ts-morph';
+import type { ClassDeclaration, SourceFile } from 'ts-morph';
 import { Project } from 'ts-morph';
 import Storage from '../../../storage.js';
 import CodeGenerator from '../../codegenerator.js';
@@ -30,26 +30,48 @@ export default class TSGenerator extends CodeGenerator {
     generate(): Promise<{
         [x: string]: string;
     }>;
+    getExampleCodeSnippet(): Promise<string | false>;
     /**
      * Create our main SDK source file.
      *
      */
     private createSDKSource;
+    /**
+     * Create an IIFE export of our SDK in the SDK source file so users can do
+     * `import sdk from '<package>'` and have a ready-to-go instance of their SDK -- eliminating them
+     * having to create an instance with `new SDK()`.
+     *
+     * This will also fill our a JSDoc heading on the IIFE we're creating based on various pieces of
+     * data that may be present in the OpenAPI definition `info` object.
+     *
+     * Additionally if a license in `info.license` is recognized by the SPDX we'll also create a
+     * `LICENSE` file in for their generated SDK. We're only supporting SPDX-recognized licenses for
+     * this because we otherwise have no idea what the license represents and we should be extremely
+     * cautious around assuming intent with software licensing.
+     *
+     * @see {@link https://spdx.org/licenses/}
+     */
+    createSDKExport(sourceFile: SourceFile): SourceFile;
+    /**
+     * Creates a `.gitignore` file to prevent the `dist/` directory from being tracked.
+     *
+     */
+    createGitIgnore(): SourceFile;
     /**
      * Create the `tsconfig.json` file that will allow this SDK to be compiled for use.
      *
      */
-    createTSConfig(): import("ts-morph").SourceFile;
+    createTSConfig(): SourceFile;
     /**
      * Create the `package.json` file that will ultimately make this SDK available to use.
      *
      */
-    createPackageJSON(): import("ts-morph").SourceFile;
+    createPackageJSON(): SourceFile;
     /**
      * Create a placeholder `README.md` file in the repository, with information on how to use/administer the SDK.
      *
      */
-    createREADME(): import("ts-morph").SourceFile;
+    createREADME(): Promise<SourceFile>;
     /**
      * Create our main schemas file. This is where all of the JSON Schema that our TypeScript typing
      * infrastructure sources its data from. Without this there are no types.

package/dist/codegen/languages/typescript/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/codegen/languages/typescript/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAI3B,OAAO,KAAK,EACV,gBAAgB,EAMjB,MAAM,UAAU,CAAC;AAUlB,OAAO,EAAmB,OAAO,EAAoD,MAAM,UAAU,CAAC;AAItG,OAAO,OAAO,MAAM,qBAAqB,CAAC;AAC1C,OAAO,aAAa,MAAM,wBAAwB,CAAC;AAiCnD,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,aAAa;;IACpD,OAAO,EAAE,OAAO,CAAC;IAEjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE3B,GAAG,EAAG,gBAAgB,CAAC;IAEvB,OAAO,EAAE,MAAM,CACb,MAAM,EAEJ;QACE,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAED,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC1B,CAAC;IAEF,4BAA4B,UAAS;gBAEzB,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAiDrD,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;WAoC9D,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBpF;;;OAGG;IAEG,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB3E;;;OAGG;IACG,QAAQ;;;IAqDd;;;OAGG;IACH,OAAO,CAAC,eAAe;IAuJvB;;;OAGG;IACH,cAAc;IAgBd;;;OAGG;IACH,iBAAiB;IAwEjB;;;OAGG;IACH,YAAY;IAyBZ;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAgEzB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAevB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAuM/B;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAoChC;;;;OAIG;IACH,OAAO,CAAC,iCAAiC;IAiDzC;;;OAGG;IACH,OAAO,CAAC,gCAAgC;IAiExC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/codegen/languages/typescript/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,GAAG,MAAM,KAAK,CAAC;AAK3B,OAAO,KAAK,EACV,gBAAgB,EAMhB,UAAU,EACX,MAAM,UAAU,CAAC;AAWlB,OAAO,EAAmB,OAAO,EAAoD,MAAM,UAAU,CAAC;AAKtG,OAAO,OAAO,MAAM,qBAAqB,CAAC;AAC1C,OAAO,aAAa,MAAM,wBAAwB,CAAC;AAiDnD,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,aAAa;;IACpD,OAAO,EAAE,OAAO,CAAC;IAEjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE3B,GAAG,EAAG,gBAAgB,CAAC;IAEvB,OAAO,EAAE,MAAM,CACb,MAAM,EAEJ;QACE,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAED,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAC1B,CAAC;IAEF,4BAA4B,UAAS;gBAEzB,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAiDrD,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;WA0B9D,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IASpF;;;OAGG;IAEG,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3E;;;OAGG;IACG,QAAQ;;;IAsDR,qBAAqB;IAiB3B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAgIvB;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,UAAU,EAAE,UAAU;IA4GtC;;;OAGG;IACH,eAAe;IAYf;;;OAGG;IACH,cAAc;IAmBd;;;OAGG;IACH,iBAAiB;IA+EjB;;;OAGG;IACG,YAAY;IAsClB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAgEzB;;;;;;OAMG;IACH,OAAO,CAAC,eAAe;IAevB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAuM/B;;;;;OAKG;IACH,OAAO,CAAC,wBAAwB;IAoChC;;;;OAIG;IACH,OAAO,CAAC,iCAAiC;IAiDzC;;;OAGG;IACH,OAAO,CAAC,gCAAgC;IAiExC;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAsB1B"}

package/dist/codegen/languages/typescript/index.js

@@ -1,9 +1,11 @@
 import path from 'node:path';
 import corePkg from '@readme/api-core/package.json' assert { type: 'json' };
 import { execa } from 'execa';
+import { getLicense } from 'license';
 import setWith from 'lodash.setwith';
 import semver from 'semver';
 import { IndentationText, Project, QuoteKind, ScriptTarget, VariableDeclarationKind } from 'ts-morph';
+import { buildCodeSnippetForOperation, getSuggestedOperation } from '../../../lib/suggestedOperations.js';
 import logger from '../../../logger.js';
 import { PACKAGE_VERSION } from '../../../packageInfo.js';
 import Storage from '../../../storage.js';
@@ -23,6 +25,19 @@ import { docblockEscape, generateTypeName, wordWrap } from './util.js';
  */
 const REF_PLACEHOLDER = '::convert::';
 const REF_PLACEHOLDER_REGEX = /"::convert::([a-zA-Z_$\\d]*)"/g;
+function handleExecSuccess(res, opts = {}) {
+    if (opts.dryRun) {
+        (opts.logger ? opts.logger : logger)(res.command);
+        (opts.logger ? opts.logger : logger)(res.stdout);
+    }
+}
+function handleExecFailure(err, opts = {}) {
+    if (opts.dryRun) {
+        (opts.logger ? opts.logger : logger)(err.message);
+        return;
+    }
+    throw err;
+}
 export default class TSGenerator extends CodeGenerator {
     project;
     types;
@@ -81,12 +96,7 @@ export default class TSGenerator extends CodeGenerator {
         // adding `@api/<sdk identifier>` as a dependency there so you can load it with
         // `require('@api/<sdk identifier>)`.
         return execa('npm', [...npmInstall, installDir].filter(Boolean))
-            .then(res => {
-            if (opts.dryRun) {
-                (opts.logger ? opts.logger : logger)(res.command);
-                (opts.logger ? opts.logger : logger)(res.stdout);
-            }
-        })
+            .then(res => handleExecSuccess(res, opts))
             .catch(err => {
             // If `npm install` throws this error it always happens **after** our dependencies have been
             // installed and is an annoying quirk that sometimes occurs when installing a package within
@@ -96,26 +106,15 @@ export default class TSGenerator extends CodeGenerator {
                 (opts.logger ? opts.logger : logger)("npm threw an error but we're ignoring it");
                 return;
             }
-            if (opts.dryRun) {
-                (opts.logger ? opts.logger : logger)(err.message);
-                return;
-            }
-            throw err;
+            handleExecFailure(err, opts);
         });
     }
     static async uninstall(storage, opts = {}) {
         const pkgName = storage.getPackageName();
         const args = ['uninstall', pkgName, opts.dryRun ? '--dry-run' : ''].filter(Boolean);
         return execa('npm', args)
-            .then(res => {
-            if (opts.dryRun) {
-                (opts.logger ? opts.logger : logger)(res.command);
-                (opts.logger ? opts.logger : logger)(res.stdout);
-            }
-        })
-            .catch(err => {
-            throw err;
-        });
+            .then(res => handleExecSuccess(res, opts))
+            .catch(err => handleExecFailure(err, opts));
     }
     /**
      * Compile the TS code we generated into JS for use in CJS and ESM environments.
@@ -124,22 +123,14 @@ export default class TSGenerator extends CodeGenerator {
     // eslint-disable-next-line class-methods-use-this
     async compile(storage, opts = {}) {
         const installDir = storage.getIdentifierStorageDir();
-        await execa('npx', ['tsup'], {
+        await execa('npm', ['pkg', 'set', 'scripts.prepare=tsup'], { cwd: installDir })
+            .then(res => handleExecSuccess(res, opts))
+            .catch(err => handleExecFailure(err, opts));
+        await execa('npm', ['run', 'prepare'], {
             cwd: installDir,
         })
-            .then(res => {
-            if (opts.dryRun) {
-                (opts.logger ? opts.logger : logger)(res.command);
-                (opts.logger ? opts.logger : logger)(res.stdout);
-            }
-        })
-            .catch(err => {
-            if (opts.dryRun) {
-                (opts.logger ? opts.logger : logger)(err.message);
-                return;
-            }
-            throw err;
-        });
+            .then(res => handleExecSuccess(res, opts))
+            .catch(err => handleExecFailure(err, opts));
     }
     /**
      * Generate the current OpenAPI definition into a TypeScript library.
@@ -148,9 +139,10 @@ export default class TSGenerator extends CodeGenerator {
     async generate() {
         const srcDirectory = this.project.createDirectory('src');
         const sdkSource = this.createSDKSource(srcDirectory);
+        this.createGitIgnore();
         this.createPackageJSON();
         this.createTSConfig();
-        this.createREADME();
+        await this.createREADME();
         if (Object.keys(this.schemas).length) {
             this.createSchemasFile(srcDirectory);
             this.createTypesFile(srcDirectory);
@@ -159,7 +151,7 @@ export default class TSGenerator extends CodeGenerator {
             // If we don't have any schemas then we shouldn't import a `types` file that doesn't exist.
             sdkSource
                 .getImportDeclarations()
-                .find(id => id.getText() === "import type * as types from './types';")
+                .find(id => id.getText() === "import type * as types from './types.js';")
                 ?.remove();
         }
         // If this SDK doesn't use the `HTTPMethodRange` interface for handling `2XX` response status
@@ -193,6 +185,20 @@ export default class TSGenerator extends CodeGenerator {
             }),
         ].reduce((prev, next) => Object.assign(prev, next));
     }
+    async getExampleCodeSnippet() {
+        // if we've already built the code snippet, return it instead of re-building it!
+        if (typeof this.exampleCodeSnippet !== 'undefined') {
+            return this.exampleCodeSnippet;
+        }
+        const operation = getSuggestedOperation(this.spec);
+        if (!operation) {
+            this.exampleCodeSnippet = false;
+            return false;
+        }
+        const snippet = await buildCodeSnippetForOperation(this.spec, operation, { identifier: this.identifier });
+        this.exampleCodeSnippet = snippet;
+        return snippet;
+    }
     /**
      * Create our main SDK source file.
      *
@@ -202,7 +208,7 @@ export default class TSGenerator extends CodeGenerator {
         const sourceFile = sourceDirectory.createSourceFile('index.ts', '');
         sourceFile.addImportDeclarations([
             // This import will be automatically removed later if the SDK ends up not having any types.
-            { defaultImport: 'type * as types', moduleSpecifier: './types' },
+            { defaultImport: 'type * as types', moduleSpecifier: './types.js' },
             {
                 // `HTTPMethodRange` will be conditionally removed later if it ends up not being used.
                 defaultImport: 'type { ConfigOptions, FetchResponse, HTTPMethodRange }',
@@ -211,7 +217,6 @@ export default class TSGenerator extends CodeGenerator {
             { defaultImport: 'APICore', moduleSpecifier: '@readme/api-core' },
             { defaultImport: 'definition', moduleSpecifier: this.specPath },
         ]);
-        // @todo add TOS, License, info.* to a docblock at the top of the SDK.
         this.sdk = sourceFile.addClass({
             name: 'SDK',
             properties: [{ name: 'core', type: 'APICore' }],
@@ -305,9 +310,98 @@ sdk.server('https://eu.api.example.com/v14');`)),
         Object.entries(operations).forEach(([operationId, data]) => {
             this.createOperationAccessor(data.operation, operationId, data.types.params, data.types.responses);
         });
-        // Export our SDK into the source file.
+        this.createSDKExport(sourceFile);
+        return sourceFile;
+    }
+    /**
+     * Create an IIFE export of our SDK in the SDK source file so users can do
+     * `import sdk from '<package>'` and have a ready-to-go instance of their SDK -- eliminating them
+     * having to create an instance with `new SDK()`.
+     *
+     * This will also fill our a JSDoc heading on the IIFE we're creating based on various pieces of
+     * data that may be present in the OpenAPI definition `info` object.
+     *
+     * Additionally if a license in `info.license` is recognized by the SPDX we'll also create a
+     * `LICENSE` file in for their generated SDK. We're only supporting SPDX-recognized licenses for
+     * this because we otherwise have no idea what the license represents and we should be extremely
+     * cautious around assuming intent with software licensing.
+     *
+     * @see {@link https://spdx.org/licenses/}
+     */
+    createSDKExport(sourceFile) {
+        let docblock = {};
+        // The OpenAPI 3.1 `info` object added some properties that aren't available in 3.0 but 3.1
+        // still contains everything that was available in 3.0 so to allow us to not have to do gross
+        // `as OpenAPIV3_1.InfoObject` typing everywhere we're just assuming that we have 3.1 object
+        // here.
+        const infoObject = this.spec.api.info;
+        if (infoObject?.title || infoObject?.description) {
+            docblock.description = writer => {
+                if (infoObject.title) {
+                    writer.writeLine(docblockEscape(wordWrap(infoObject.title)));
+                }
+                if (infoObject.description) {
+                    writer.conditionalNewLine(!!infoObject.title);
+                    writer.writeLine(docblockEscape(wordWrap(infoObject.description)));
+                }
+                writer.newLineIfLastNot();
+                return writer;
+            };
+        }
+        if (this.apiContact.name) {
+            docblock = TSGenerator.#addTagToDocblock(docblock, {
+                tagName: 'author',
+                text: this.apiContact.name,
+            });
+        }
+        if (this.apiContact.url) {
+            docblock = TSGenerator.#addTagToDocblock(docblock, {
+                tagName: 'see',
+                text: `{@link ${this.apiContact.url}}`,
+            });
+        }
+        if (infoObject?.termsOfService) {
+            docblock = TSGenerator.#addTagToDocblock(docblock, {
+                tagName: 'see',
+                text: `{@link ${infoObject.termsOfService} Terms of Service}`,
+            });
+        }
+        if (this.spdxLicense) {
+            docblock = TSGenerator.#addTagToDocblock(docblock, {
+                tagName: 'license',
+                text: this.spdxLicense,
+            });
+            // Some licenses like `Apache-2.0` have the year as `[yyyy]` but the `license` package only
+            // supports templating on `<templatekey>` so we need to fix this ourselves.
+            // https://github.com/Ovyerus/license/issues/12
+            const year = new Date().getFullYear().toString();
+            const license = getLicense(this.spdxLicense, {
+                year,
+                // `license` doesn't support empty strings so we need to fake it here
+                author: this.apiContact.name ?? ' ',
+            })
+                .replace(/<yyyy>/g, year)
+                .replace(/\[yyyy\]/g, year);
+            this.project.createSourceFile('LICENSE', license);
+        }
+        else if (infoObject?.license) {
+            // If they have a license but it's not recognized by the SPDX we should still surface it.
+            if (infoObject?.license?.name) {
+                docblock = TSGenerator.#addTagToDocblock(docblock, {
+                    tagName: 'license',
+                    text: infoObject.license.name,
+                });
+            }
+            if (infoObject.license?.url) {
+                docblock = TSGenerator.#addTagToDocblock(docblock, {
+                    tagName: 'see',
+                    text: `{@link ${infoObject.license.url}}`,
+                });
+            }
+        }
         sourceFile.addVariableStatement({
             declarationKind: VariableDeclarationKind.Const,
+            docs: Object.keys(docblock).length ? [docblock] : [],
             declarations: [
                 {
                     name: 'createSDK',
@@ -329,6 +423,19 @@ sdk.server('https://eu.api.example.com/v14');`)),
         });
         return sourceFile;
     }
+    /**
+     * Creates a `.gitignore` file to prevent the `dist/` directory from being tracked.
+     *
+     */
+    createGitIgnore() {
+        const file = `# This file prevents the \`dist/\` directory from being tracked via git.
+# This is recommended since the \`prepare\` npm script automatically
+# regenerates the contents of the \`dist/\` directory as needed.
+dist/
+`;
+        const sourceFile = this.project.createSourceFile('.gitignore', file);
+        return sourceFile;
+    }
     /**
      * Create the `tsconfig.json` file that will allow this SDK to be compiled for use.
      *
@@ -337,8 +444,11 @@ sdk.server('https://eu.api.example.com/v14');`)),
         const sourceFile = this.project.createSourceFile('tsconfig.json', '');
         const config = {
             compilerOptions: {
-                module: 'NodeNext',
+                esModuleInterop: true,
+                module: 'ESNext',
+                moduleResolution: 'Bundler',
                 resolveJsonModule: true,
+                strict: true,
             },
             include: ['./src/**/*'],
         };
@@ -384,31 +494,37 @@ sdk.server('https://eu.api.example.com/v14');`)),
         const pkg = {
             name: `@api/${this.identifier}`,
             version: pkgVersion.version,
-            main: './dist/index.js',
-            types: './dist/index.d.ts',
-            module: './dist/index.mts',
+            type: 'module',
+            main: 'dist/index.cjs',
+            types: 'dist/index.d.cts',
+            module: 'dist/index.ts',
             exports: {
                 '.': {
-                    import: './dist/index.mjs',
-                    require: './dist/index.js',
+                    import: './dist/index.js',
+                    require: './dist/index.cjs',
                 },
                 ...(hasTypes
                     ? {
                         './types': {
-                            import: './dist/types.d.mts',
-                            require: './dist/types.d.ts',
+                            import: './dist/types.js',
+                            require: './dist/types.cjs',
                         },
                     }
                     : {}),
+                './package.json': './package.json',
             },
+            license: this.spdxLicense ?? '',
             files: ['dist', 'openapi.json'],
             scripts: {
-                prepare: 'tsup',
+                lint: 'tsc --noEmit',
             },
             dependencies,
             devDependencies,
             tsup: tsupOptions,
         };
+        if (!this.spdxLicense) {
+            delete pkg.license;
+        }
         sourceFile.addStatements(JSON.stringify(pkg, null, 2));
         return sourceFile;
     }
@@ -416,16 +532,27 @@ sdk.server('https://eu.api.example.com/v14');`)),
      * Create a placeholder `README.md` file in the repository, with information on how to use/administer the SDK.
      *
      */
-    createREADME() {
+    async createREADME() {
         let createdAt = new Date().toISOString();
         const currentAPI = Storage.getLockfile().apis.find(api => api.identifier === this.identifier);
         if (currentAPI)
             createdAt = currentAPI.createdAt;
+        let exampleUsage = 'Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀';
+        const exampleSnippet = await this.getExampleCodeSnippet();
+        if (exampleSnippet) {
+            exampleUsage = `
+## Example Usage 🚀
+
+\`\`\`js
+${exampleSnippet}
+\`\`\`
+`.trim();
+        }
         const file = `# \`@api/${this.identifier}\`
 
 This SDK was autogenerated by the [\`api\` SDK generator](https://api.readme.dev), powered by [ReadMe](https://readme.com) 🦉
 
-Add SDK setup information and usage examples here so your users get started in a jiffy! 🚀
+${exampleUsage}
 
 <!---
 
@@ -454,7 +581,7 @@ Generated at ${createdAt}
             // for these schemas into our main `schemas.ts` file.`
             sourceFile.addImportDeclaration({
                 defaultImport: schemaName,
-                moduleSpecifier: `./schemas/${schemaName}`,
+                moduleSpecifier: `./schemas/${schemaName}.js`,
             });
             // Though we aren't using Prettier to make these generated SDKs look amazing we should at
             // least make the schema files we generate not look like completely unreadable garbage.
@@ -470,7 +597,7 @@ Generated at ${createdAt}
                     // declaration for it.
                     schemaFile.addImportDeclaration({
                         defaultImport: ref,
-                        moduleSpecifier: `./${ref}`,
+                        moduleSpecifier: `./${ref}.js`,
                     });
                 });
             }
@@ -506,8 +633,8 @@ Generated at ${createdAt}
     createTypesFile(sourceDirectory) {
         const sourceFile = sourceDirectory.createSourceFile('types.ts', '');
         sourceFile.addImportDeclarations([
-            { defaultImport: 'type { FromSchema }', moduleSpecifier: '@readme/api-core/lib' },
-            { defaultImport: '* as schemas', moduleSpecifier: './schemas' },
+            { defaultImport: 'type { FromSchema }', moduleSpecifier: '@readme/api-core/types' },
+            { defaultImport: '* as schemas', moduleSpecifier: './schemas.js' },
         ]);
         Array.from(new Map(Array.from(this.types.entries()).sort())).forEach(([typeName, typeExpression]) => {
             sourceFile.addTypeAlias({ isExported: true, name: typeName, type: typeExpression });