Annotate prototypes with types (#1619)

src/StripeResource.ts

@@ -58,10 +58,12 @@ function StripeResource(
 
 StripeResource.prototype = {
   _stripe: null as StripeObject | null,
-  path: '',
+  // @ts-ignore the type of path changes in ctor
+  path: '' as UrlInterpolator,
+  resourcePath: '',
 
   // Methods that don't use the API's default '/v1' path can override it with this setting.
-  basePath: null,
+  basePath: null!,
 
   initialize(): void {},
 
@@ -120,25 +122,7 @@ StripeResource.prototype = {
   // DEPRECATED: Here for backcompat in case users relied on this.
   wrapTimeout: utils.callbackifyPromiseWithTimeout,
 
-  // eslint-disable-next-line no-warning-comments
-  // TODO: Unused?
-  _timeoutHandler(
-    timeout: number,
-    req: any,
-    callback: RequestCallback
-  ): () => void {
-    return (): void => {
-      const timeoutErr = new TypeError('ETIMEDOUT');
-      (timeoutErr as any).code = 'ETIMEDOUT';
-
-      req.destroy(timeoutErr);
-    };
-  },
-
-  _addHeadersDirectlyToObject(
-    obj: Record<string, unknown>,
-    headers: RequestHeaders
-  ): void {
+  _addHeadersDirectlyToObject(obj: any, headers: RequestHeaders): void {
     // For convenience, make some headers easily accessible on
     // lastResponse.
 
@@ -303,29 +287,12 @@ StripeResource.prototype = {
     }`;
   },
 
-  _errorHandler(
-    res: never,
-    requestRetries: number,
-    callback: RequestCallback
-  ): (message: string, detail: string) => void {
-    return (message: string, detail: string): void => {
-      callback.call(
-        this,
-        new StripeConnectionError({
-          message: this._generateConnectionErrorMessage(requestRetries),
-          detail,
-        }),
-        null
-      );
-    };
-  },
-
   // For more on when and how to retry API requests, see https://stripe.com/docs/error-handling#safely-retrying-requests-with-idempotency
   _shouldRetry(
-    res: HttpClientResponseInterface,
+    res: null | HttpClientResponseInterface,
     numRetries: number,
     maxRetries: number,
-    error?: {code: number}
+    error?: HttpClientResponseError
   ): boolean {
     if (
       error &&
@@ -525,7 +492,7 @@ StripeResource.prototype = {
     method: string,
     host: string,
     path: string,
-    data: string,
+    data: RequestData,
     auth: string,
     options: RequestOptions = {},
     callback: RequestCallback
@@ -589,7 +556,7 @@ StripeResource.prototype = {
 
       const requestRetries = numRetries || 0;
 
-      const maxRetries = this._getMaxNetworkRetries(options.settings);
+      const maxRetries = this._getMaxNetworkRetries(options.settings || {});
 
       this._stripe._emitter.emit('request', requestEvent);
 
@@ -671,6 +638,6 @@ StripeResource.prototype = {
       prepareAndMakeRequest(null, utils.stringifyRequestData(data || {}));
     }
   },
-};
+} as StripeResourceObject;
 
 export = StripeResource;

src/Types.d.ts

@@ -107,26 +107,51 @@ interface HttpClientInterface {
   ) => Promise<HttpClientResponseInterface>;
 }
 type StripeObject = {
+  getClientUserAgentSeeded: (
+    seed: Record<string, string>,
+    callback: (userAgent: string) => void
+  ) => void;
+  getUname: (callback: (uname: string) => void) => void;
+  setProtocol: (protocol: string) => void;
+  setPort: (port: number) => void;
+  getClientUserAgent: (callback: (clientUserAgent: string) => void) => void;
+  getTelemetryEnabled: () => boolean;
+  getAppInfoAsString: () => string;
+  getInitialNetworkRetryDelay: () => number;
+  getMaxNetworkRetryDelay: () => number;
+  getMaxNetworkRetries: () => number;
+  getConstant: <T = string>(name: string) => T;
+  _setApiField: <K extends keyof StripeObject['_api']>(
+    name: K,
+    value: StripeObject['_api'][K]
+  ) => void;
+  getApiField: <K extends keyof StripeObject['_api']>(
+    key: K
+  ) => StripeObject['_api'][K];
+  _setApiNumberField: (name: string, value: number) => unknown;
+  _appInfo: any;
   on: any;
   off: any;
   once: any;
   VERSION: string;
   StripeResource: typeof StripeResource;
   errors: any;
   webhooks: any;
-  getApiField: <T = string>(name: string) => T;
   _prepResources: () => void;
   _setAppInfo: (appInfo: AppInfo) => void;
   _setApiKey: (apiKey: string) => void;
-  _prevRequestMetrics: number[];
+  _prevRequestMetrics: Array<{
+    request_id: string;
+    request_duration_ms: number;
+  }>;
   _api: {
     auth: string | null;
     host: string;
     port: string | number;
     protocol: string;
     basePath: string;
     version: string;
-    timeout: string;
+    timeout: number;
     maxNetworkRetries: number;
     agent: string;
     httpClient: any;
@@ -136,6 +161,7 @@ type StripeObject = {
   _emitter: import('events').EventEmitter;
   _enableTelemetry: boolean;
   _getPropsFromConfig: (config: Record<string, unknown>) => UserProvidedConfig;
+  _clientId?: string;
 };
 type StripeRawError = {
   message?: string;
@@ -169,22 +195,76 @@ type StripeResourceObject = {
   basePath: UrlInterpolator;
   path: UrlInterpolator;
   resourcePath: string;
-  includeBasic: Array<string>;
+  includeBasic?: Array<string>;
   createResourcePathWithSymbols: (path: string | null | undefined) => string;
   createFullPath: (
     interpolator: UrlInterpolator,
     urlData: RequestData
   ) => string;
-  _request: (
+  _request(
     method: string,
     host: string,
     path: string,
     data: RequestData,
     auth: string,
     options: RequestOptions,
     callback: RequestCallback
-  ) => void;
+  ): void;
   initialize: (...args: Array<any>) => void;
+  _joinUrlParts: (urlParts: string[]) => string;
+  _getRequestId: (headers: RequestHeaders) => string;
+  _makeResponseEvent: (
+    requestEvent: RequestEvent,
+    statusCode: number,
+    headers: ResponseHeaders
+  ) => ResponseEvent;
+  _getUserAgentString: () => string;
+  _getTelemetryHeader: () => string;
+  requestDataProcessor:
+    | null
+    | ((
+        method: string,
+        data: RequestData,
+        headers: RequestHeaders | undefined,
+        prepareAndMakeRequest: (error: Error | null, data: string) => void
+      ) => void);
+  _recordRequestMetrics: (requestId: string, elapsed?: number) => void;
+  _addHeadersDirectlyToObject: (obj: any, headers: ResponseHeaders) => void;
+  _getMaxNetworkRetries: (settings: RequestSettings) => number;
+  _defaultIdempotencyKey: (
+    method: string,
+    userSuppliedSettings: RequestSettings
+  ) => string | number | string[];
+  _getSleepTimeInMS: (
+    requestRetries: number,
+    retryAfter: number | null
+  ) => number | undefined;
+  _shouldRetry: (
+    res: HttpClientResponseInterface | null,
+    requestRetries: number,
+    maxRetries: number,
+    error?: HttpClientResponseError
+  ) => boolean | undefined;
+  _jsonResponseHandler: (
+    requestEvent: RequestEvent,
+    callback: RequestCallback
+  ) => (res: HttpClientResponseInterface) => void;
+  _streamingResponseHandler: (
+    requestEvent: RequestEvent,
+    callback: RequestCallback
+  ) => (res: HttpClientResponseInterface) => RequestCallbackReturn;
+  _generateConnectionErrorMessage: (
+    requestRetries: number
+  ) => string | undefined;
+  _makeHeaders: (
+    auth: string,
+    length: number,
+    apiVersion: string,
+    clientUserAgent: string,
+    method: string,
+    headers: RequestHeaders | undefined,
+    settings: RequestSettings | undefined
+  ) => RequestHeaders;
 };
 type UrlInterpolator = (params: Record<string, unknown>) => string;
 type UserProvidedConfig = {