httpsnippet-client-api 7.0.0-beta.0 → 7.0.0-beta.13

package/src/index.ts

@@ -1,13 +1,15 @@
 import type { ReducedHelperObject } from '@readme/httpsnippet/helpers/reducer';
-import type { Client } from '@readme/httpsnippet/targets';
-import type Operation from 'oas/operation';
-import type { HttpMethods, OASDocument } from 'oas/rmoas.types';
+import type { Client, ClientPlugin } from '@readme/httpsnippet/targets';
+import type { Operation } from 'oas/operation';
+import type { HttpMethods, OASDocument } from 'oas/types';
 
 import { CodeBuilder } from '@readme/httpsnippet/helpers/code-builder';
+import camelCase from 'camelcase'; // eslint-disable-line import/no-extraneous-dependencies
 import contentType from 'content-type';
 import Oas from 'oas';
 import { matchesMimeType } from 'oas/utils';
-import stringifyObject from 'stringify-object';
+import { isReservedOrBuiltinsLC } from 'reserved2';
+import stringifyObject from 'stringify-object'; // eslint-disable-line import/no-extraneous-dependencies
 
 /**
  * @note This regex also exists in `api/fetcher`.
@@ -34,7 +36,7 @@ function stringify(obj: any, opts = {}) {
   return stringifyObject(obj, { indent: '  ', ...opts });
 }
 
-function buildAuthSnippet(authKey: string | string[]) {
+function buildAuthSnippet(sdkVariable: string, authKey: string[] | string) {
   // Auth key will be an array for Basic auth cases.
   if (Array.isArray(authKey)) {
     const auth: string[] = [];
@@ -47,10 +49,10 @@ function buildAuthSnippet(authKey: string | string[]) {
       auth.push(`'${token.replace(/'/g, "\\'")}'`);
     });
 
-    return `sdk.auth(${auth.join(', ')});`;
+    return `${sdkVariable}.auth(${auth.join(', ')});`;
   }
 
-  return `sdk.auth('${authKey.replace(/'/g, "\\'")}');`;
+  return `${sdkVariable}.auth('${authKey.replace(/'/g, "\\'")}');`;
 }
 
 function getAuthSources(operation: Operation) {
@@ -95,21 +97,25 @@ function getAuthSources(operation: Operation) {
 }
 
 interface APIOptions {
-  apiDefinition: OASDocument;
-  /**
-   * The URI that is used to download this API definition from `npx api install`.
-   *
-   * @example @developers/v2.0#17273l2glm9fq4l5
-   */
-  apiDefinitionUri: string;
+  api?: {
+    definition: OASDocument;
+
+    /**
+     * The string to identify this SDK as. This is used in the `import sdk from '<identifier>'`
+     * sample as well as the the variable name we attach the SDK to.
+     *
+     * @example `@api/developers`
+     */
+    identifier?: string;
+
+    /**
+     * The URI that is used to download this API definition from `npx api install`.
+     *
+     * @example `@developers/v2.0#17273l2glm9fq4l5`
+     */
+    registryURI: string;
+  };
   escapeBrackets?: boolean;
-  /**
-   * The string to identify this SDK as. This is used in the `import sdk from '@api/<identifier>'`
-   * sample as well as the the variable name we attach the SDK to.
-   *
-   * @example developers
-   */
-  identifier?: string;
   indent?: string | false;
 }
 
@@ -120,36 +126,45 @@ const client: Client<APIOptions> = {
     link: 'https://npm.im/api',
     description: 'Automatic SDK generation from an OpenAPI definition.',
     extname: '.js',
+    installation: 'npx api install "{packageName}"',
   },
   convert: ({ cookiesObj, headersObj, postData, queryObj, url, ...source }, options) => {
     const opts = {
       ...options,
-    } as APIOptions;
-
-    if (!('apiDefinitionUri' in opts)) {
-      throw new Error('This HTTP Snippet client must have an `apiDefinitionUri` option supplied to it.');
-    } else if (!('apiDefinition' in opts)) {
-      throw new Error('This HTTP Snippet client must have an `apiDefinition` option supplied to it.');
+    };
+
+    if (!opts?.api) {
+      throw new Error('This HTTPSnippet client must have an `api` config supplied to it.');
+    } else if (!opts?.api?.definition) {
+      throw new Error('This HTTPSnippet client must have an `api.definition` option supplied to it.');
+    } else if (!opts?.api?.registryURI) {
+      throw new Error('This HTTPSnippet client must have an `api.registryURI` option supplied to it.');
     }
 
     const method = source.method.toLowerCase() as HttpMethods;
-    const oas = new Oas(opts.apiDefinition);
+    const oas = new Oas(opts.api.definition);
     const apiDefinition = oas.getDefinition();
     const foundOperation = oas.findOperation(url, method);
     if (!foundOperation) {
       throw new Error(
-        `Unable to locate a matching operation in the supplied \`apiDefinition\` for: ${source.method} ${url}`,
+        `Unable to locate a matching operation in the supplied \`api.definition\` for: ${source.method} ${url}`,
       );
     }
 
-    let sdkPackageName;
-    let sdkVariable;
-    if (opts.identifier) {
-      sdkPackageName = opts.identifier;
-      sdkVariable = opts.identifier;
+    let sdkPackageName: string | undefined;
+    let sdkVariable: string;
+    if (opts.api.identifier) {
+      sdkPackageName = opts.api.identifier;
+
+      sdkVariable = camelCase(opts.api.identifier);
+      if (isReservedOrBuiltinsLC(sdkVariable)) {
+        // If this identifier is a reserved JS word then we should prefix it with an underscore so
+        // this snippet can be valid code.
+        sdkVariable = `_${sdkVariable}`;
+      }
     } else {
-      sdkPackageName = getProjectPrefixFromRegistryUUID(opts.apiDefinitionUri);
-      sdkVariable = 'sdk';
+      sdkPackageName = getProjectPrefixFromRegistryUUID(opts.api.registryURI);
+      sdkVariable = camelCase(sdkPackageName || 'sdk');
     }
 
     const operationSlugs = foundOperation.url.slugs;
@@ -176,14 +191,14 @@ const client: Client<APIOptions> = {
         const serverVars = oas.splitVariables(baseUrl);
         const serverUrl = serverVars ? oas.url(serverVars.selected, serverVars.variables) : baseUrl;
 
-        configData.push(`sdk.server('${serverUrl}');`);
+        configData.push(`${sdkVariable}.server('${serverUrl}');`);
       }
     }
 
-    let metadata: Record<string, string | string[]> = {};
+    let metadata: Record<string, string[] | string> = {};
     Object.keys(queryObj).forEach(param => {
       if (authSources.query.includes(param)) {
-        authData.push(buildAuthSnippet(queryObj[param]));
+        authData.push(buildAuthSnippet(sdkVariable, queryObj[param]));
 
         // If this query param is part of an auth source then we don't want it doubled up in the
         // snippet.
@@ -195,7 +210,7 @@ const client: Client<APIOptions> = {
 
     Object.keys(cookiesObj).forEach(cookie => {
       if (authSources.cookie.includes(cookie)) {
-        authData.push(buildAuthSnippet(cookiesObj[cookie]));
+        authData.push(buildAuthSnippet(sdkVariable, cookiesObj[cookie]));
 
         // If this cookie is part of an auth source then we don't want it doubled up.
         return;
@@ -241,7 +256,7 @@ const client: Client<APIOptions> = {
           // into our auth data so we can build up an `.auth()` snippet for the SDK.
           const authScheme = authSources.header[headerLower];
           if (authScheme === '*') {
-            authData.push(buildAuthSnippet(headers[header]));
+            authData.push(buildAuthSnippet(sdkVariable, headers[header]));
           } else {
             // @ts-expect-error `headers[header]` is typed improperly in HTTPSnippet.
             let authKey = headers[header].replace(`${authSources.header[headerLower]} `, '');
@@ -250,7 +265,7 @@ const client: Client<APIOptions> = {
               authKey = authKey.split(':');
             }
 
-            authData.push(buildAuthSnippet(authKey));
+            authData.push(buildAuthSnippet(sdkVariable, authKey));
           }
 
           delete headers[header];
@@ -361,4 +376,9 @@ const client: Client<APIOptions> = {
   },
 };
 
-export default client;
+const plugin: ClientPlugin<APIOptions> = {
+  target: 'node',
+  client,
+};
+
+export default plugin;

package/tsup.config.ts

@@ -11,5 +11,15 @@ export default defineConfig((options: Options) => ({
   ...config,
 
   entry: ['src/index.ts'],
+
+  noExternal: [
+    // These dependencies are ESM-only but because we're building for ESM **and** CJS we can't
+    // treat them as external dependencies as CJS libraries can't load ESM code that uses `export`.
+    // `noExternal` will instead treeshake these dependencies down and include them in our compiled
+    // dists.
+    'camelcase',
+    'stringify-object',
+  ],
+
   silent: !options.watch,
 }));