Why?

The Node SDK's API methods have always been a little unusual among our SDKs. Rather than generate API calls directly, it generated "method specs" which included a path, expected arguments, and response type (among others). Then, because the runtime function couldn't know anything about the incoming arguments, it shipped a bunch of logic to extract path arguments, params objects, options objects, and API keys. This has worked well enough, but was overly generous about the inputs it would handle. This has lead to both bugs and surprising behavior.

So the goal of this PR is simple: fully type our runtime code to match the generated type signatures.

As a result, we're removing a lot of ways it's been possible to call these methods. All of these used to be valid, but would show type errors during editing:

stripe.customers.retrieve('cus_123', 'sk_test_123')
stripe.customers.create({name: 'david', host: 'example.com'}, 'sk_test_123')
stripe.customers.create({apiKey: 'sk_test_123'})
stripe.customers.list(customers => {
  // do something with customers
})

Now, callers have to conform to a much more consistent (and well typed) signature:

  create(
    params?: Checkout.SessionCreateParams,
    options?: RequestOptions
  ): Promise<Response<Session>>;

This means we're dropping support for:

• callbacks
• non-path-param strings
• RequestOptions as the first argument if the method takes Params
• Keys being allowed on either params or options objects

This gets us a much more consistent HTTP request experience internally and reduces the opportunity for surprising behavior.

What?

• refactor every generated method to call this._makeRequest with the proper inputs instead of going through StripeMethod
• remove StripeMethod and a bunch of supporting code (like url param replacers)
• updated many tests to not use callbacks anymore (without changing functionality)
• removed unused tests
• removed .method and .extend functions - these were never meant to be public facing and weren't used outside our tests
• update signature for StripeResource._makeRequest to take method, path, params, etc instead of an untyped array. Update body accordingly
• fixed some internal docs links
• disambiguated a RequestOptions type since only one was user-facing

See Also

• DEVSDK-3060

Changelog

• ⚠️ Refactor how incoming method arguments are parsed. Type signatures for API methods should be much more accurate and reliable now
  • ⚠️ Remove support for providing callbacks to API methods. Use async / await instead
  • ⚠️ Remove support for passing a plain API key as a function arg. If supplied on a per-request basis, it should be in the RequestOptions under the apiKey property
  • ⚠️ Keys from params and options objects are no longer mixed. If present on a method, RequestParams must always come first and RequestOptions must always come second. To supply options without params, pass undefined as the first argument explicitly
  • ⚠️ Removed methods from StripeResource: createFullPath, createResourcePathWithSymbols, extend, method and _joinUrlParts. These were mostly intended for internal use and we no longer need them

As a result, the following call patterns are no longer supported:

stripe.customers.retrieve('cus_123', 'sk_test_123')
stripe.customers.create({name: 'david', host: 'example.com'}, 'sk_test_123')
stripe.customers.create({apiKey: 'sk_test_123'})
stripe.customers.list(customers => {
  // do something with customers
})

If those look familiar, head over to the migration guide to update your code.