diff --git a/types/2020-08-27/index.d.ts b/types/2020-08-27/index.d.ts index b943c01e04..0eb7736d65 100644 --- a/types/2020-08-27/index.d.ts +++ b/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; diff --git a/types/Errors.d.ts b/types/Errors.d.ts index 8995ae8808..bb2fa59095 100644 --- a/types/Errors.d.ts +++ b/types/Errors.d.ts @@ -1,5 +1,8 @@ declare module 'stripe' { namespace Stripe { + /** + * @deprecated The {@link Stripe.Errors} type is deprecated, please use the {@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'; + } + } } } diff --git a/types/test/typescriptTest.ts b/types/test/typescriptTest.ts index aa8ed12092..0c0cacb449 100644 --- a/types/test/typescriptTest.ts +++ b/types/test/typescriptTest.ts @@ -267,3 +267,30 @@ async (): Promise => { 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', +});