httpsnippet-client-api 7.0.0-alpha.6 → 7.0.0-beta.12

package/src/index.ts

@@ -1,20 +1,42 @@
 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`.
+ *
+ * @example @petstore/v1.0#n6kvf10vakpemvplx
+ * @example @petstore#n6kvf10vakpemvplx
+ */
+const registryUUIDRegex = /^@(?<project>[a-zA-Z0-9-_]+)(\/?(?<version>.+))?#(?<uuid>[a-z0-9]+)$/;
+
+/**
+ * @note This function also exists in `api/fetcher`.
+ */
+function getProjectPrefixFromRegistryUUID(uri: string) {
+  const matches = uri.match(registryUUIDRegex);
+  if (!matches) {
+    return undefined;
+  }
+
+  return matches.groups?.project;
+}
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 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[] = [];
@@ -27,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) {
@@ -75,8 +97,24 @@ function getAuthSources(operation: Operation) {
 }
 
 interface APIOptions {
-  apiDefinition: OASDocument;
-  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;
   indent?: string | false;
 }
@@ -88,28 +126,47 @@ 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: 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.api.registryURI);
+      sdkVariable = camelCase(sdkPackageName || 'sdk');
+    }
+
     const operationSlugs = foundOperation.url.slugs;
     const operation = oas.operation(foundOperation.url.nonNormalizedPath, method);
     const operationPathParameters = operation.getParameters().filter(param => param.in === 'path');
@@ -119,7 +176,7 @@ const client: Client<APIOptions> = {
 
     const { blank, push, join } = new CodeBuilder({ indent: opts.indent || '  ' });
 
-    push(`const sdk = require('api')('${opts.apiDefinitionUri}');`);
+    push(`import ${sdkVariable} from '@api/${sdkPackageName}';`);
     blank();
 
     // If we have multiple servers configured and our source URL differs from the stock URL that we
@@ -134,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.
@@ -153,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;
@@ -199,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]} `, '');
@@ -208,7 +265,7 @@ const client: Client<APIOptions> = {
               authKey = authKey.split(':');
             }
 
-            authData.push(buildAuthSnippet(authKey));
+            authData.push(buildAuthSnippet(sdkVariable, authKey));
           }
 
           delete headers[header];
@@ -232,9 +289,14 @@ const client: Client<APIOptions> = {
         }
 
         // If we haven't used our header anywhere else, or we've deleted it from the payload
-        // because it'll be handled internally by `api` then we should add the lowercased version
-        // of our header into the generated code snippet.
-        requestHeaders[headerLower] = headers[header];
+        // because it'll be handled internally by `api` then we should add it into our code snippet.
+        if (['accept', 'content-type'].includes(headerLower)) {
+          requestHeaders[headerLower] = headers[header];
+        } else {
+          // Non-reserved headers retain their casing because we want to generate a snippet that
+          // matches the TS types that are created during codegeneration.
+          requestHeaders[header] = headers[header];
+        }
       });
 
       if (Object.keys(requestHeaders).length > 0) {
@@ -306,7 +368,7 @@ const client: Client<APIOptions> = {
       push(configData.join('\n'));
     }
 
-    push(`sdk.${accessor}(${args.join(', ')})`);
+    push(`${sdkVariable}.${accessor}(${args.join(', ')})`);
     push('.then(({ data }) => console.log(data))', 1);
     push('.catch(err => console.error(err));', 1);
 
@@ -314,4 +376,9 @@ const client: Client<APIOptions> = {
   },
 };
 
-export default client;
+const plugin: ClientPlugin<APIOptions> = {
+  target: 'node',
+  client,
+};
+
+export default plugin;

package/tsup.config.ts

@@ -1,6 +1,6 @@
+/* eslint-disable import/no-extraneous-dependencies, node/no-extraneous-import */
 import type { Options } from 'tsup';
 
-// eslint-disable-next-line import/no-extraneous-dependencies
 import { defineConfig } from 'tsup';
 
 // eslint-disable-next-line import/no-relative-packages
@@ -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,
 }));