Update error types to be namespaced under Stripe.error

types/2020-08-27/index.d.ts

@@ -217,8 +217,7 @@ declare module 'stripe' {
     /**
      * API Errors
      */
-    static errors: Stripe.Errors;
-    errors: Stripe.Errors;
+    errors: typeof Stripe.errors;
 
     on(event: 'request', handler: (event: Stripe.RequestEvent) => void): void;
     on(event: 'response', handler: (event: Stripe.ResponseEvent) => void): void;

types/Errors.d.ts

@@ -1,5 +1,8 @@
 declare module 'stripe' {
   namespace Stripe {
+    /**
+     * @deprecated The {@link Stripe.Errors} type is deprecated, please use {@link Stripe.errors} namespace directly.}
+     */
     export type Errors = {
       generate: typeof StripeError.generate;
       StripeError: typeof StripeError;
@@ -46,6 +49,10 @@ declare module 'stripe' {
       source?: Stripe.Source;
     };
 
+    /**
+     * @deprecated The {@link Stripe.StripeError} type is deprecated, please use {@link Stripe.errors.StripeError}.}
+     * The runtime StripeError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
+     */
     class StripeError extends Error {
       constructor(rawError: StripeRawError);
 
@@ -135,6 +142,9 @@ declare module 'stripe' {
     /**
      * Card errors are the most common type of error you should expect to handle.
      * They result when the user enters a card that can't be charged for some reason.
+     *
+     * @deprecated The {@link Stripe.StripeCardError} type is deprecated, please use {@link Stripe.errors.StripeCardError}.}
+     * The runtime StripeCardError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeCardError extends StripeError {
       readonly type: 'StripeCardError';
@@ -148,6 +158,9 @@ declare module 'stripe' {
 
     /**
      * Invalid request errors arise when your request has invalid parameters.
+     *
+     * @deprecated The {@link Stripe.StripeInvalidRequestError} type is deprecated, please use {@link Stripe.errors.StripeInvalidRequestError}.}
+     * The runtime StripeInvalidRequestError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeInvalidRequestError extends StripeError {
       readonly type: 'StripeInvalidRequestError';
@@ -160,6 +173,9 @@ declare module 'stripe' {
      *
      * It could also be raised in the case that a new error has been introduced in the API,
      * but this version of the library doesn't know how to handle it.
+     *
+     * @deprecated The {@link Stripe.StripeAPIError} type is deprecated, please use {@link Stripe.errors.StripeAPIError}.}
+     * The runtime StripeAPIError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeAPIError extends StripeError {
       readonly type: 'StripeAPIError';
@@ -168,6 +184,9 @@ declare module 'stripe' {
 
     /**
      * Failure to properly authenticate yourself in the request.
+     *
+     * @deprecated The {@link Stripe.StripeAuthenticationError} type is deprecated, please use {@link Stripe.errors.StripeAuthenticationError}.}
+     * The runtime StripeAuthenticationError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeAuthenticationError extends StripeError {
       readonly type: 'StripeAuthenticationError';
@@ -176,6 +195,9 @@ declare module 'stripe' {
 
     /**
      * Access was attempted on a resource that wasn't allowed.
+     *
+     * @deprecated The {@link Stripe.StripePermissionError} type is deprecated, please use {@link Stripe.errors.StripePermissionError}.}
+     * The runtime StripePermissionError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripePermissionError extends StripeError {
       readonly type: 'StripePermissionError';
@@ -184,6 +206,9 @@ declare module 'stripe' {
     /**
      * Too many requests hit the API too quickly.
      * @docs https://stripe.com/docs/rate-limits
+     *
+     * @deprecated The {@link Stripe.StripeRateLimitError} type is deprecated, please use {@link Stripe.errors.StripeRateLimitError}.}
+     * The runtime StripeRateLimitError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeRateLimitError extends StripeError {
       readonly type: 'StripeRateLimitError';
@@ -194,6 +219,9 @@ declare module 'stripe' {
      * The library cannot connect to Stripe.
      * This can happen for a variety of reasons,
      * such as loss of network connectivity or a bad TLS certificate.
+     *
+     * @deprecated The {@link Stripe.StripeConnectionError} type is deprecated, please use {@link Stripe.errors.StripeConnectionError}.}
+     * The runtime StripeConnectionError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeConnectionError extends StripeError {
       readonly type: 'StripeConnectionError';
@@ -202,6 +230,9 @@ declare module 'stripe' {
     /**
      * The signature verification for a webhook failed.
      * @docs https://stripe.com/docs/webhooks/signatures
+     *
+     * @deprecated The {@link Stripe.StripeSignatureVerificationError} type is deprecated, please use {@link Stripe.errors.StripeSignatureVerificationError}.}
+     * The runtime StripeSignatureVerificationError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeSignatureVerificationError extends StripeError {
       readonly type: 'StripeSignatureVerificationError';
@@ -210,6 +241,9 @@ declare module 'stripe' {
     /**
      * Idempotency errors occur when an `Idempotency-Key` is re-used on a request that does not match the first request's API endpoint and parameters.
      * @docs https://stripe.com/docs/api/idempotent_requests?lang=node
+     *
+     * @deprecated The {@link Stripe.StripeIdempotencyError} type is deprecated, please use {@link Stripe.errors.StripeIdempotencyError}.}
+     * The runtime StripeIdempotencyError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeIdempotencyError extends StripeError {
       readonly type: 'StripeIdempotencyError';
@@ -221,10 +255,221 @@ declare module 'stripe' {
      * expired, has been used, or doesn't belong to you; a refresh token doesn't
      * exist, or doesn't belong to you; or if an API key's mode (live or test)
      * doesn't match the mode of a code or refresh token.
+     *
+     * @deprecated The {@link Stripe.StripeInvalidGrantError} type is deprecated, please use {@link Stripe.errors.StripeInvalidGrantError}.}
+     * The runtime StripeInvalidGrantError type is located in the {@link errors} namespace. This definition was added by mistake but kept for backwards compatibility.
      */
     class StripeInvalidGrantError extends StripeError {
       readonly type: 'StripeInvalidGrantError';
       readonly rawType: 'invalid_grant';
     }
+
+    namespace errors {
+      function generate(
+        rawError: StripeRawError & {type: 'card_error'}
+      ): StripeCardError;
+      function generate(
+        rawError: StripeRawError & {type: 'invalid_request_error'}
+      ): StripeInvalidRequestError;
+      function generate(
+        rawError: StripeRawError & {type: 'api_error'}
+      ): StripeAPIError;
+      function generate(
+        rawError: StripeRawError & {type: 'authentication_error'}
+      ): StripeAuthenticationError;
+      function generate(
+        rawError: StripeRawError & {type: 'rate_limit_error'}
+      ): StripeRateLimitError;
+      function generate(
+        rawError: StripeRawError & {type: 'idempotency_error'}
+      ): StripeIdempotencyError;
+      function generate(
+        rawError: StripeRawError & {type: 'invalid_grant'}
+      ): StripeInvalidGrantError;
+      function generate(
+        rawError: StripeRawError & {type: RawErrorType}
+      ): StripeError;
+
+      class StripeError extends Error {
+        constructor(rawError: StripeRawError);
+
+        static generate(
+          rawError: StripeRawError & {type: 'card_error'}
+        ): StripeCardError;
+        static generate(
+          rawError: StripeRawError & {type: 'invalid_request_error'}
+        ): StripeInvalidRequestError;
+        static generate(
+          rawError: StripeRawError & {type: 'api_error'}
+        ): StripeAPIError;
+        static generate(
+          rawError: StripeRawError & {type: 'authentication_error'}
+        ): StripeAuthenticationError;
+        static generate(
+          rawError: StripeRawError & {type: 'rate_limit_error'}
+        ): StripeRateLimitError;
+        static generate(
+          rawError: StripeRawError & {type: 'idempotency_error'}
+        ): StripeIdempotencyError;
+        static generate(
+          rawError: StripeRawError & {type: 'invalid_grant'}
+        ): StripeInvalidGrantError;
+        static generate(
+          rawError: StripeRawError & {type: RawErrorType}
+        ): StripeError;
+
+        /**
+         * A human-readable message giving more details about the error. For card errors, these messages can
+         * be shown to your users.
+         */
+        readonly message: string;
+
+        readonly type: keyof Errors;
+
+        /**
+         * See the "error types" section at https://stripe.com/docs/api/errors
+         */
+        readonly rawType: RawErrorType;
+
+        /**
+         * For card errors, a short string describing the kind of card error that occurred.
+         *
+         * @docs https://stripe.com/docs/error-codes
+         */
+        readonly code?: string;
+
+        /**
+         * A URL to more information about the error code reported.
+         *
+         * @docs https://stripe.com/docs/error-codes
+         */
+        readonly doc_url?: string;
+
+        /**
+         * Typically a 4xx or 5xx.
+         */
+        readonly statusCode?: number;
+
+        readonly raw: unknown;
+
+        readonly headers: {
+          [key: string]: string;
+        };
+
+        readonly requestId: string;
+
+        /**
+         * The parameter the error relates to if the error is parameter-specific. You can use this to display a
+         * message near the correct form field, for example.
+         */
+        readonly param?: string;
+
+        /** @deprecated */
+        readonly detail?: unknown;
+
+        readonly charge?: string;
+        readonly decline_code?: string;
+        readonly payment_intent?: PaymentIntent;
+        readonly payment_method?: PaymentMethod;
+        readonly payment_method_type?: string;
+        readonly setup_intent?: SetupIntent;
+        readonly source?: Source;
+      }
+
+      /**
+       * Card errors are the most common type of error you should expect to handle.
+       * They result when the user enters a card that can't be charged for some reason.
+       */
+      class StripeCardError extends StripeError {
+        readonly type: 'StripeCardError';
+        readonly rawType: 'card_error';
+
+        /**
+         * @docs https://stripe.com/docs/declines/codes
+         */
+        readonly decline_code: string;
+      }
+
+      /**
+       * Invalid request errors arise when your request has invalid parameters.
+       */
+      class StripeInvalidRequestError extends StripeError {
+        readonly type: 'StripeInvalidRequestError';
+        readonly rawType: 'invalid_request_error';
+      }
+
+      /**
+       * API errors cover any other type of problem (e.g., a temporary problem with Stripe's servers),
+       * and are extremely uncommon.
+       *
+       * It could also be raised in the case that a new error has been introduced in the API,
+       * but this version of the library doesn't know how to handle it.
+       */
+      class StripeAPIError extends StripeError {
+        readonly type: 'StripeAPIError';
+        readonly rawType: 'api_error';
+      }
+
+      /**
+       * Failure to properly authenticate yourself in the request.
+       */
+      class StripeAuthenticationError extends StripeError {
+        readonly type: 'StripeAuthenticationError';
+        readonly rawType: 'authentication_error';
+      }
+
+      /**
+       * Access was attempted on a resource that wasn't allowed.
+       */
+      class StripePermissionError extends StripeError {
+        readonly type: 'StripePermissionError';
+      }
+
+      /**
+       * Too many requests hit the API too quickly.
+       * @docs https://stripe.com/docs/rate-limits
+       */
+      class StripeRateLimitError extends StripeError {
+        readonly type: 'StripeRateLimitError';
+        readonly rawType: 'rate_limit_error';
+      }
+
+      /**
+       * The library cannot connect to Stripe.
+       * This can happen for a variety of reasons,
+       * such as loss of network connectivity or a bad TLS certificate.
+       */
+      class StripeConnectionError extends StripeError {
+        readonly type: 'StripeConnectionError';
+      }
+
+      /**
+       * The signature verification for a webhook failed.
+       * @docs https://stripe.com/docs/webhooks/signatures
+       */
+      class StripeSignatureVerificationError extends StripeError {
+        readonly type: 'StripeSignatureVerificationError';
+      }
+
+      /**
+       * Idempotency errors occur when an `Idempotency-Key` is re-used on a request that does not match the first request's API endpoint and parameters.
+       * @docs https://stripe.com/docs/api/idempotent_requests?lang=node
+       */
+      class StripeIdempotencyError extends StripeError {
+        readonly type: 'StripeIdempotencyError';
+        readonly rawType: 'idempotency_error';
+      }
+
+      /**
+       * InvalidGrantError is raised when a specified code doesn't exist, is
+       * expired, has been used, or doesn't belong to you; a refresh token doesn't
+       * exist, or doesn't belong to you; or if an API key's mode (live or test)
+       * doesn't match the mode of a code or refresh token.
+       */
+      class StripeInvalidGrantError extends StripeError {
+        readonly type: 'StripeInvalidGrantError';
+        readonly rawType: 'invalid_grant';
+      }
+    }
   }
 }

types/test/typescriptTest.ts

@@ -267,3 +267,30 @@ async (): Promise<void> => {
 
   const event2 = await stripe.events.retrieve(event.id);
 };
+
+// Can reference error types
+let errors: Stripe.Errors;
+let rawError: Stripe.StripeRawError;
+
+let oldError: Stripe.StripeError;
+let newError: Stripe.errors.StripeError;
+
+const instanceofCheck1 = {} instanceof Stripe.errors.StripeError;
+const instanceofCheck2 = {} instanceof Stripe.errors.StripeAPIError;
+const instanceofCheck3 = {} instanceof Stripe.StripeError;
+const instanceofCheck4 = {} instanceof Stripe.StripeAPIError;
+const instanceofCheck5 = {} instanceof stripe.errors.StripeError;
+const instanceofCheck6 = {} instanceof stripe.errors.StripeAPIError;
+
+Stripe.errors.generate({
+  type: 'card_error',
+});
+stripe.errors.generate({
+  type: 'card_error',
+});
+Stripe.StripeError.generate({
+  type: 'card_error',
+});
+Stripe.errors.StripeError.generate({
+  type: 'card_error',
+});