TypeScript definitions

[rattrayalex-stripe]

This adds TypeScript definitions for stripe-node, reflecting the latest API version.

To try it out, install with:

yarn add https://github.com/stripe/stripe-node#typescript
# or 
npm install --save https://github.com/stripe/stripe-node/tarball/typescript

Docs are here.

Feedback from the community would be much appreciated on this! Email me at rattrayalex@stripe.com or leave comments here.

Fixes #296

[bruun]

First of all, this is awesome 🙌

I've given it a quick go in our codebase, and with strict null checks enabled we immediately got a lot of type errors due to the id properties on retrieved resources (PaymentIntent, Transfer, etc) being optional. Do ids in general need to be optional?

The same goes for certain properties on objects, such as amount and currency on a PaymentIntent. Can these actually be optional when they are required in the PaymentIntentCreateParams?

Other issues I came across in my brief testing this morning:

• stripe.accounts.retrieve seems to be missing a signature for retrieving a Custom Account by id.
• We're now getting an error when importing Stripe with import * as Stripe from 'stripe' (using module: commonjs in our .tsconfig):
  • This module can only be referenced with ECMAScript imports/exports by turning on the 'esModuleInterop' flag and referencing its default exports

EDIT: Found the part about importing using import Stripe from 'stripe' in the docs, but that causes a similar error:

[rattrayalex-stripe]

Awesome, thanks @bruun , this is super helpful. Appreciate all the specifics very much, will look into all of those shortly.

Updated the docs to mention the esModuleInterop flag, which unfortunately you do need to use

[rattrayalex-stripe]

Thanks so much again for the feedback @bruun – all your comments have been addressed. Care to give it another shot?

[bruun]

No problem @rattrayalex-stripe :)

The change to optional fields helped a lot, thanks!

One last thing that I can think of at the moment, it would be great if definitions like this:

/**
* The business type. Can be `individual` or `company`.
*/
business_type: string | null;

Could be limited to the actual possible values

/**
* The business type. Can be `individual` or `company`.
*/
business_type: "individual" | "company" | null;

[rattrayalex-stripe]

Terrific, thanks @bruun ! How much work was it to move your project over from DT? Did you need to change a lot of things or just install & it worked?

Yes, we have a project underway to find all of those strings and convert them over to enums!

Curious for your thoughts on our reliance on the tsconfig.json types field. It's a bit unorthodox but we want to make it clear that these types represent only a single API version (and give people
time to port over from DefinitelyTyped, if that's onerous).

[bruun]

Moving over from DT was pretty painless, and mostly consisted of renaming Stripe.paymentIntents.IPaymentIntent -> Stripe.PaymentIntent etc. The new type definitions even revealed some bugs in our code :-)

The hard part, and something I haven't managed to solve yet due to time constraints, is making our codebase work with esModuleInterop: true. It introduces a ton of errors unrelated to Stripe we'll need to fix, and many runtime errors not caught by the TypeScript compiler. There might be a quick fix for this, and it certainly isn't the Stripe library's fault, but it does mean we can't switch from DT right away.

The reliance on the types field in tsconfig.json is indeed a bit unorthodox, but not a problem for me personally. There are probably mixed opinions here. However, I noticed one issue that might be related:

If we do not explicitly import Stripe from 'stripe' in a module, this code results in a TS error:

The above error disappears if we explicitly import Stripe in that module.
However, if we don't import Stripe and change the code to the following, the error disappears:

There might be something very off in our module resolution which might also explain the esModuleInterop problems, but I thought I'd mention it just in case.

[rattrayalex-stripe]

Hi @bruun,

Thanks, that's great to hear! We love catching bugs.

We definitely don't want users to have to make runtime changes to adopt our types. I changed the export scheme so esModuleInterop isn't required anymore. Care to remove that and try again? Hopefully should be much smoother!

Regarding the errors, yes, you do need to import Stripe (or use the instantiated stripe client) to do an instanceof check, since they happen at runtime. In fact, instanceof Stripe.StripeInvalidRequestError should be a type error (hopefully it wasn't only because of the wonky setup).

With esModuleInterop gone, are you able to adopt it smoothly?

[bruun]

@rattrayalex-stripe Removing the esModuleInterop requirement no longer breaks our other imports, but something is now wrong with the Stripe import and initialization.

The following does not give a type error, but fails at runtime:

// Typescript
import Stripe from 'stripe';
const stripe = new Stripe(API_KEY);``
 
// Compiles to
const Stripe = require("stripe");
const stripe = new Stripe(API_KEY);

// Fails at runtime with
const stripe = new Stripe(API_KEY);
               ^
TypeError: stripe_1.default is not a constructor

The following works at runtime, but yields a Typescript error (version 3.6.4):

// Typescript
import Stripe = require('stripe'); // (Same with keeping import * as Stripe from 'stripe')
const stripe = new Stripe(API_KEY);

// Compiles to
const stripe_1 = require("stripe");
const stripe = new stripe_1.default(API_KEY);

// Typescript error
Type 'typeof import("stripe")' has no construct signatures.ts(2351)

// Relevant properties from tsconfig
"target": "es2020",
"module": "commonjs",
"moduleResolution": "node",

Again, this could be a issue with our configuration or even my local setup, I'll try to look further into it on Monday.

[rattrayalex-stripe]

Thanks again @bruun ! Sorry about that, I should have checked that kind of setup first. Thanks for sharing your config.

I've now made a few changes (see updated docs) – you can now import Stripe from 'stripe' and it'll work at runtime in TS, you no longer need to specify the "types" field in tsconfig.json, and you now ~must specify the api version when you instantiate Stripe:

import Stripe from 'stripe';
const stripe = new Stripe('sk_test_123', {apiVersion: '2019-12-03'});

Give that a try? Curious what you think.

[bruun]

@rattrayalex-stripe Great, I can now successfully compile and run our code :-)

Personally I like the changes to the apiVersion, and having to explicitly ignore any errors. I think perhaps this part of the docs...

If you are on an older API Version (eg; 2019-10-17) and not able to upgrade, you may pass apiVersion: null to use your account's default API version.

... should include the more specific comment from types/lib.d.ts (emphasis mine):

If you wish to remain on your account's default API version, you may pass null or another version instead of the latest version, and add a @ts-ignore comment here and anywhere the types differ between API versions.

As we explicitly use an earlier API version than "2019-12-05", it wasn't immediately clear from the docs what the proper way of specifying this API version was. The second comment makes it very clear.

---

Coming back to the previously discussed instanceof issues, this still does not yield a type error until I explicitly import Stripe:

err instanceof Stripe.StripeInvalidRequestError

As you said previously, this fails at runtime because Stripe is not defined.

When not explicitly importing Stripe in a module, Stripe resolves to the namespace in lib.d.ts:

When explicitly importing Stripe, Stripe resolves to the class in index.d.ts:

Any ideas? I have made sure to remove Stripe from the tsconfig "types" array.

[rattrayalex-stripe]

Fantastic!

Great suggestion; reworded. Let me know what you think.

I removed the direct export of the error class types; they're now only accessible from Stripe.errors. Does that clear things up?

[bruun]

The docs are very clear now, thank you!

Removing the export on the class types didn't help, unfortunately. I have not worked much with namespaces and modules in Typescript so this is outside my comfort zone, but Typescript is apparently still able to find the StripeInvalidRequestError class type in the Stripe namespace, even when not explicitly exported.

[rattrayalex-stripe]

Ah, darn. I'm not sure if there's anything we can do about that, then. Presumably it'd be rare for users to run into this, and it only happened to you because of the unfortunate import story from before?

[bruun]

That sounds likely, yeah. Maybe someone will come along with a suggested fix once it's released and people start migrating from DT

[JetJet13]

Hey @rattrayalex-stripe,

I'm running into issues with the Stripe.invoices.listUpcomingLineItems method.

Edit: I forgot to mention that I'm using version 2019-12-03

I'm getting an error when I invoke listUpcomingLineItems as follows,

this.stripe.invoices.listUpcomingLineItems(customerId, {
      limit,
      starting_after: startingAfter,
    })

Error: Stripe: Unknown arguments (<customerId>,[object Object]). Did you mean to pass an options object? ... (on API request to GET `/invoices/upcoming/lines`)

Workaround

I have managed to find a workaround, which is to ignore the type definitions and insert the customerId inside the params object

    const method: any = this.stripe.invoices
    return method.listUpcomingLineItems({
      customer: customerId,
      limit,
      starting_after: startingAfter,
    })

Suggested Fix

Replace

listUpcomingLineItems(
      id: string,
      params?: InvoiceLineItemListUpcomingParams,
      options?: RequestOptions
): ApiListPromise<InvoiceLineItem>;


listUpcomingLineItems(
      id: string,
      options?: RequestOptions
    ): ApiListPromise<InvoiceLineItem>;

With

listUpcomingLineItems(
      params: InvoiceLineItemListUpcomingParams,
      options?: RequestOptions
): ApiListPromise<InvoiceLineItem>;


listUpcomingLineItems(
      params: InvoiceLineItemListUpcomingParams,
      options?: RequestOptions
    ): ApiListPromise<InvoiceLineItem>;

and update InvoiceLineItemListUpcomingParams to include customer

  interface InvoiceLineItemListUpcomingParams {
    /**
     * The identifier of the customer whose upcoming invoice line items you'd like to retrieve.
     */
    customer: string;
    .
    .
    .
}

[rattrayalex-stripe]

Thanks for reporting @JetJet13 ! You're correct; I hope to fix this up today.
How has everything else been?

[JetJet13]

No real issues to report aside from the one mentioned. The transition from @types/stripe has been pretty good so far.

Thanks for picking this up!

[rattrayalex-stripe]

@JetJet13 the issues with listUpcomingLineItems and InvoiceLineItemListUpcomingParams should now be fixed.

@bruun we're no longer polluting the global namespace, so the Stripe.StripeInvalidRequestError problem should now be fixed.

[ob-stripe]

Again, amazing job @rattrayalex-stripe and @jlomas-stripe!

I focused on the non-TS files and the manually written TS files (shared.d.ts, lib.d.ts, webhooks.d.ts, and OAuth.d.ts). Left one comment, but LGTM otherwise. I'd feel better if someone with more Node/TS experience reviewed too, but up to you.

[ob-stripe]

payload and header can be either string or Buffers, cf.

stripe-node/lib/Webhooks.js

Lines 71 to 72 in f6e5ad3

	payload = Buffer.isBuffer(payload) ? payload.toString('utf8') : payload;
	header = Buffer.isBuffer(header) ? header.toString('utf8') : header;

[rattrayalex-stripe]

Thanks fixed. Note that this required adding @types/node as a dependency, meaning it could add a bit of bloat for non-TS users. Given this is a server-only package, I don't think that's the end of the world.

[richardm-stripe]

Let's make sure our release script updates this automatically.

[richardm-stripe]

e.g., I think is our style

[richardm-stripe]

serIalizing

[rattrayalex-stripe]

Will correct typos in a follow-on, we'll likely have more work to do on README in any case.

[rattrayalex-stripe]

Thanks to everyone in the community for the feedback!

You're welcome & encouraged to continue using this branch until v8.0.0 is released, likely in early-mid January, and please do continue to provide feedback, big & small!

[xenoterracide]

hey, we're using this, I know it's merged... but any chance more interfaces could be exported? specifically I wanted to make a type that configures our payment intents for both stripe and stripe terminal

const intent = await this.stripe.paymentIntents.create({
  ...payment.paymentMethod.options,
  amount: payment.getAmount(),
  currency: payment.getCurrency(),
  capture_method: 'manual',
});

and in one of my payment methods I have

export default class StripeCardPresent implements PaymentMethod {
  readonly options: { [key: string]: any };

  constructor() {
    this.options = {
      payment_method_types: ['card_present'],
    };
  }
}

what'd I'd really like to do is have PaymentIntentCreateParams exported so that I can make my type generic, and have it return this.

I can make a new ticket if y'all prefer.

[rattrayalex-stripe]

@xenoterracide Yes, please open a new ticket!