docs: fix api-extractor configuration and add missing annotations

kuhe · kuhe · commit 9be94f6bfbe8 · 2025-03-24T10:48:33.000-04:00
diff --git a/packages/core/api-extractor.json b/packages/core/api-extractor.json
@@ -1,4 +1,4 @@
 {
   "extends": "../../api-extractor.packages.json",
-  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+  "mainEntryPointFilePath": "./src/api-extractor-type-index.d.ts"
 }
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -4,8 +4,8 @@
   "description": "Core functions & classes shared by multiple AWS SDK clients.",
   "scripts": {
     "build": "yarn lint && concurrently 'yarn:build:cjs' 'yarn:build:es' 'yarn:build:types'",
-    "build:cjs": "node ../../scripts/compilation/inline core",
-    "build:es": "tsc -p tsconfig.es.json",
+    "build:cjs": "node ../../scripts/compilation/inline core && rm ./dist-cjs/api-extractor-type-index.js",
+    "build:es": "tsc -p tsconfig.es.json && rm ./dist-es/api-extractor-type-index.js",
     "build:include:deps": "lerna run --scope $npm_package_name --include-dependencies build",
     "build:types": "tsc -p tsconfig.types.json",
     "build:types:downlevel": "downlevel-dts dist-types dist-types/ts3.4",
diff --git a/packages/core/src/api-extractor-type-index.d.ts b/packages/core/src/api-extractor-type-index.d.ts
@@ -0,0 +1,5 @@
+export * from "../dist-types";
+export * from "../dist-types/submodules/account-id-endpoint";
+export * from "../dist-types/submodules/client";
+export * from "../dist-types/submodules/httpAuthSchemes";
+export * from "../dist-types/submodules/protocols";
diff --git a/packages/core/src/submodules/account-id-endpoint/AccountIdEndpointModeConfigResolver.ts b/packages/core/src/submodules/account-id-endpoint/AccountIdEndpointModeConfigResolver.ts
@@ -26,9 +26,6 @@ interface PreviouslyResolved {}
  * @internal
  */
 export interface AccountIdEndpointModeResolvedConfig {
-  /**
-   * Resolved value for input config {config.accountIdEndpointMode}
-   */
   accountIdEndpointMode: Provider<AccountIdEndpointMode>;
 }
 
diff --git a/packages/core/src/submodules/account-id-endpoint/AccountIdEndpointModeConstants.ts b/packages/core/src/submodules/account-id-endpoint/AccountIdEndpointModeConstants.ts
@@ -1,7 +1,16 @@
+/**
+ * @public
+ */
 export type AccountIdEndpointMode = "disabled" | "preferred" | "required";
 
+/**
+ * @internal
+ */
 export const DEFAULT_ACCOUNT_ID_ENDPOINT_MODE = "preferred";
 
+/**
+ * @internal
+ */
 export const ACCOUNT_ID_ENDPOINT_MODE_VALUES: AccountIdEndpointMode[] = ["disabled", "preferred", "required"];
 
 /**
diff --git a/packages/core/src/submodules/httpAuthSchemes/aws_sdk/AwsSdkSigV4Signer.ts b/packages/core/src/submodules/httpAuthSchemes/aws_sdk/AwsSdkSigV4Signer.ts
@@ -82,9 +82,9 @@ export const validateSigningProperties = async (
 };
 
 /**
- * @internal
  * Note: this is not a signing algorithm implementation. The sign method
  * accepts the real signer as an input parameter.
+ * @internal
  */
 export class AwsSdkSigV4Signer implements HttpSigner {
   async sign(
@@ -151,6 +151,7 @@ export class AwsSdkSigV4Signer implements HttpSigner {
 }
 
 /**
+ * @internal
  * @deprecated renamed to {@link AwsSdkSigV4Signer}
  */
 export const AWSSDKSigV4Signer = AwsSdkSigV4Signer;
diff --git a/packages/core/src/submodules/httpAuthSchemes/aws_sdk/resolveAwsSdkSigV4Config.ts b/packages/core/src/submodules/httpAuthSchemes/aws_sdk/resolveAwsSdkSigV4Config.ts
@@ -21,7 +21,7 @@ import {
 } from "@smithy/types";
 
 /**
- * @internal
+ * @public
  */
 export interface AwsSdkSigV4AuthInputConfig {
   /**
@@ -129,7 +129,8 @@ export const resolveAwsSdkSigV4Config = <T>(
     }
   }
 
-  const boundCredentialsProvider = async (options: Record<string, any> | undefined) => credentialsProvider!({ ...options, callerClientConfig: config });
+  const boundCredentialsProvider = async (options: Record<string, any> | undefined) =>
+    credentialsProvider!({ ...options, callerClientConfig: config });
 
   // Populate sigv4 arguments
   const {
@@ -235,21 +236,25 @@ export const resolveAwsSdkSigV4Config = <T>(
 };
 
 /**
+ * @internal
  * @deprecated renamed to {@link AwsSdkSigV4AuthInputConfig}
  */
 export interface AWSSDKSigV4AuthInputConfig extends AwsSdkSigV4AuthInputConfig {}
 
 /**
+ * @internal
  * @deprecated renamed to {@link AwsSdkSigV4PreviouslyResolved}
  */
 export interface AWSSDKSigV4PreviouslyResolved extends AwsSdkSigV4PreviouslyResolved {}
 
 /**
+ * @internal
  * @deprecated renamed to {@link AwsSdkSigV4AuthResolvedConfig}
  */
 export interface AWSSDKSigV4AuthResolvedConfig extends AwsSdkSigV4AuthResolvedConfig {}
 
 /**
+ * @internal
  * @deprecated renamed to {@link resolveAwsSdkSigV4Config}
  */
 export const resolveAWSSDKSigV4Config = resolveAwsSdkSigV4Config;
diff --git a/packages/core/src/submodules/protocols/json/parseJsonBody.ts b/packages/core/src/submodules/protocols/json/parseJsonBody.ts
@@ -2,6 +2,9 @@ import type { HttpResponse, SerdeContext } from "@smithy/types";
 
 import { collectBodyString } from "../common";
 
+/**
+ * @internal
+ */
 export const parseJsonBody = (streamBody: any, context: SerdeContext): any =>
   collectBodyString(streamBody, context).then((encoded) => {
     if (encoded.length) {
@@ -19,12 +22,18 @@ export const parseJsonBody = (streamBody: any, context: SerdeContext): any =>
     return {};
   });
 
+/**
+ * @internal
+ */
 export const parseJsonErrorBody = async (errorBody: any, context: SerdeContext) => {
   const value = await parseJsonBody(errorBody, context);
   value.message = value.message ?? value.Message;
   return value;
 };
 
+/**
+ * @internal
+ */
 export const loadRestJsonErrorCode = (output: HttpResponse, data: any): string | undefined => {
   const findKey = (object: any, key: string) => Object.keys(object).find((k) => k.toLowerCase() === key.toLowerCase());
 
diff --git a/packages/core/src/submodules/protocols/xml/parseXmlBody.ts b/packages/core/src/submodules/protocols/xml/parseXmlBody.ts
@@ -4,6 +4,9 @@ import { XMLParser } from "fast-xml-parser";
 
 import { collectBodyString } from "../common";
 
+/**
+ * @internal
+ */
 export const parseXmlBody = (streamBody: any, context: SerdeContext): any =>
   collectBodyString(streamBody, context).then((encoded) => {
     if (encoded.length) {
@@ -43,6 +46,9 @@ export const parseXmlBody = (streamBody: any, context: SerdeContext): any =>
     return {};
   });
 
+/**
+ * @internal
+ */
 export const parseXmlErrorBody = async (errorBody: any, context: SerdeContext) => {
   const value = await parseXmlBody(errorBody, context);
   if (value.Error) {
@@ -51,6 +57,9 @@ export const parseXmlErrorBody = async (errorBody: any, context: SerdeContext) =
   return value;
 };
 
+/**
+ * @internal
+ */
 export const loadRestXmlErrorCode = (output: HttpResponse, data: any): string | undefined => {
   if (data?.Error?.Code !== undefined) {
     return data.Error.Code;
diff --git a/packages/middleware-endpoint-discovery/api-extractor.json b/packages/middleware-endpoint-discovery/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/middleware-endpoint-discovery/src/configurations.ts b/packages/middleware-endpoint-discovery/src/configurations.ts
@@ -5,6 +5,9 @@ const CONFIG_ENDPOINT_DISCOVERY = "endpoint_discovery_enabled";
 
 const isFalsy = (value: string) => ["false", "0"].indexOf(value) >= 0;
 
+/**
+ * @internal
+ */
 export const NODE_ENDPOINT_DISCOVERY_CONFIG_OPTIONS: LoadedConfigSelectors<boolean | undefined> = {
   environmentVariableSelector: (env) => {
     for (let i = 0; i < ENV_ENDPOINT_DISCOVERY.length; i++) {
diff --git a/packages/middleware-endpoint-discovery/src/getEndpointDiscoveryPlugin.ts b/packages/middleware-endpoint-discovery/src/getEndpointDiscoveryPlugin.ts
@@ -3,20 +3,29 @@ import { BuildHandlerOptions, HttpHandlerOptions, MiddlewareStack, Pluggable } f
 import { endpointDiscoveryMiddleware } from "./endpointDiscoveryMiddleware";
 import { EndpointDiscoveryResolvedConfig, PreviouslyResolved } from "./resolveEndpointDiscoveryConfig";
 
+/**
+ * @internal
+ */
 export const endpointDiscoveryMiddlewareOptions: BuildHandlerOptions = {
   name: "endpointDiscoveryMiddleware",
   step: "build",
   tags: ["ENDPOINT_DISCOVERY"],
   override: true,
 };
 
+/**
+ * @public
+ */
 export interface EndpointDiscoveryMiddlewareConfig {
   isDiscoveredEndpointRequired: boolean;
   clientStack: MiddlewareStack<any, any>;
   options?: HttpHandlerOptions;
   identifiers?: Record<string, string>;
 }
 
+/**
+ * @internal
+ */
 export const getEndpointDiscoveryPlugin = (
   pluginConfig: EndpointDiscoveryResolvedConfig & PreviouslyResolved,
   middlewareConfig: EndpointDiscoveryMiddlewareConfig
@@ -27,6 +36,7 @@ export const getEndpointDiscoveryPlugin = (
 });
 
 /**
+ * @internal
  * @deprecated Use getEndpointDiscoveryPlugin
  */
 export const getEndpointDiscoveryRequiredPlugin = (
@@ -42,6 +52,7 @@ export const getEndpointDiscoveryRequiredPlugin = (
 });
 
 /**
+ * @internal
  * @deprecated Use getEndpointDiscoveryPlugin
  */
 export const getEndpointDiscoveryOptionalPlugin = (
diff --git a/packages/middleware-endpoint-discovery/src/resolveEndpointDiscoveryConfig.ts b/packages/middleware-endpoint-discovery/src/resolveEndpointDiscoveryConfig.ts
@@ -1,6 +1,9 @@
 import { EndpointCache } from "@aws-sdk/endpoint-cache";
 import { AwsCredentialIdentity, MemoizedProvider, Provider } from "@smithy/types";
 
+/**
+ * @internal
+ */
 export interface PreviouslyResolved {
   isCustomEndpoint?: boolean;
   credentials: MemoizedProvider<AwsCredentialIdentity>;
@@ -59,6 +62,9 @@ export interface EndpointDiscoveryConfigOptions {
   endpointDiscoveryCommandCtor: new (comandConfig: any) => any;
 }
 
+/**
+ * @internal
+ */
 export const resolveEndpointDiscoveryConfig = <T>(
   input: T & PreviouslyResolved & EndpointDiscoveryInputConfig,
   { endpointDiscoveryCommandCtor }: EndpointDiscoveryConfigOptions
diff --git a/packages/middleware-host-header/api-extractor.json b/packages/middleware-host-header/api-extractor.json
@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.packages.json",
+  "mainEntryPointFilePath": "./dist-types/index.d.ts"
+}
diff --git a/packages/middleware-host-header/src/index.ts b/packages/middleware-host-header/src/index.ts
@@ -10,18 +10,28 @@ interface PreviouslyResolved {
   requestHandler: RequestHandler<any, any>;
 }
 
+/**
+ * @internal
+ */
 export interface HostHeaderResolvedConfig {
   /**
    * The HTTP handler to use. Fetch in browser and Https in Nodejs.
    */
   requestHandler: RequestHandler<any, any>;
 }
+
+/**
+ * @internal
+ */
 export function resolveHostHeaderConfig<T>(
   input: T & PreviouslyResolved & HostHeaderInputConfig
 ): T & HostHeaderResolvedConfig {
   return input;
 }
 
+/**
+ * @internal
+ */
 export const hostHeaderMiddleware =
   <Input extends object, Output extends object>(options: HostHeaderResolvedConfig): BuildMiddleware<Input, Output> =>
   (next) =>
@@ -43,6 +53,9 @@ export const hostHeaderMiddleware =
     return next(args);
   };
 
+/**
+ * @internal
+ */
 export const hostHeaderMiddlewareOptions: BuildHandlerOptions & AbsoluteLocation = {
   name: "hostHeaderMiddleware",
   step: "build",
@@ -51,6 +64,9 @@ export const hostHeaderMiddlewareOptions: BuildHandlerOptions & AbsoluteLocation
   override: true,
 };
 
+/**
+ * @internal
+ */
 export const getHostHeaderPlugin = (options: HostHeaderResolvedConfig): Pluggable<any, any> => ({
   applyToStack: (clientStack) => {
     clientStack.add(hostHeaderMiddleware(options), hostHeaderMiddlewareOptions);
diff --git a/scripts/validation/submodules-linter.js b/scripts/validation/submodules-linter.js
@@ -23,6 +23,18 @@ for (const submodulePackage of submodulePackages) {
   for (const submodule of submodules) {
     const submodulePath = path.join(root, "src", "submodules", submodule);
     if (fs.existsSync(submodulePath) && fs.lstatSync(submodulePath).isDirectory()) {
+      // api extractor type index
+      const apiExtractorAggregateTypeIndexPath = path.join(root, "src", "api-extractor-type-index.d.ts");
+      if (fs.existsSync(apiExtractorAggregateTypeIndexPath)) {
+        const fileContents = fs.readFileSync(apiExtractorAggregateTypeIndexPath, "utf-8");
+        if (!fileContents.includes(`export * from "../dist-types/submodules/${submodule}";`)) {
+          fs.writeFileSync(
+            apiExtractorAggregateTypeIndexPath,
+            fileContents + `export * from "../dist-types/submodules/${submodule}";`
+          );
+          errors.push(`${submodule} not exported from src/api-extractor-type-index.d.ts`);
+        }
+      }
       // package.json metadata.
       if (!pkgJson.exports[`./${submodule}`]) {
         errors.push(`${submodule} submodule is missing exports statement in package.json`);

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`	`1`	`{`
`2`	`2`	`"extends": "../../api-extractor.packages.json",`
`3`		`- "mainEntryPointFilePath": "./dist-types/index.d.ts"`
	`3`	`+ "mainEntryPointFilePath": "./src/api-extractor-type-index.d.ts"`
`4`	`4`	`}`
Original file line number	Diff line number	Diff line change
`@@ -26,9 +26,6 @@ interface PreviouslyResolved {}`
`26`	`26`	`* @internal`
`27`	`27`	`*/`
`28`	`28`	`export interface AccountIdEndpointModeResolvedConfig {`
`29`		`- /**`
`30`		`- * Resolved value for input config {config.accountIdEndpointMode}`
`31`		`- */`
`32`	`29`	`accountIdEndpointMode: Provider<AccountIdEndpointMode>;`
`33`	`30`	`}`
`34`	`31`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +{
 +  "extends": "../../api-extractor.packages.json",
 +  "mainEntryPointFilePath": "./dist-types/index.d.ts"
 +}