Dodo Payments

# Migration guide This guide outlines the changes and steps needed to migrate your codebase to the latest version of the Dodo Payments TypeScript SDK. The main changes are that the SDK now relies on the [builtin Web fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) instead of `node-fetch` and has zero dependencies. ## Migration CLI Most programs will only need minimal changes, but to assist there is a migration tool that will automatically update your code for the new version. To use it, upgrade the `dodopayments` package, then run `./node_modules/.bin/dodopayments migrate ./your/src/folders` to update your code. To preview the changes without writing them to disk, run the tool with `--dry`. ## Environment requirements The minimum supported runtime and tooling versions are now: - Node.js 20 LTS (Most recent non-EOL Node version) - TypeScript 4.9 - Jest 28 ## Breaking changes ### Web types for `withResponse`, `asResponse`, and `APIError.headers` Because we now use the builtin Web fetch API on all platforms, if you wrote code that used `withResponse` or `asResponse` and then accessed `node-fetch`-specific properties on the result, you will need to switch to standardized alternatives. For example, `body` is now a [Web `ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) rather than a [node `Readable`](https://nodejs.org/api/stream.html#readable-streams). ```ts // Before: const res = await client.example.retrieve('string/with/slash').asResponse(); res.body.pipe(process.stdout); // After: import { Readable } from 'node:stream'; const res = await client.example.retrieve('string/with/slash').asResponse(); Readable.fromWeb(res.body).pipe(process.stdout); ``` Additionally, the `headers` property on `APIError` objects is now an instance of the Web [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) class. It was previously defined as `Record<string, string | null | undefined>`. ### URI encoded path parameters Path params are now properly encoded by default. If you were manually encoding path parameters before giving them to the SDK, you must now stop doing that and pass the param without any encoding applied. For example: ```diff - client.example.retrieve(encodeURIComponent('string/with/slash')) + client.example.retrieve('string/with/slash') // retrieves /example/string%2Fwith%2Fslash ``` Previously without the `encodeURIComponent()` call we would have used the path `/example/string/with/slash`; now we'll use `/example/string%2Fwith%2Fslash`. ### Removed request options overloads When making requests with no required body, query or header parameters, you must now explicitly pass `null`, `undefined` or an empty object `{}` to the params argument in order to customise request options. ```diff client.example.list(); client.example.list({}, { headers: { ... } }); client.example.list(null, { headers: { ... } }); client.example.list(undefined, { headers: { ... } }); - client.example.list({ headers: { ... } }); + client.example.list({}, { headers: { ... } }); ``` This affects the following methods: - `client.payments.list()` - `client.subscriptions.list()` - `client.subscriptions.retrieveUsageHistory()` - `client.licenseKeys.list()` - `client.licenseKeyInstances.list()` - `client.customers.list()` - `client.customers.customerPortal.create()` - `client.customers.wallets.ledgerEntries.list()` - `client.refunds.list()` - `client.disputes.list()` - `client.payouts.list()` - `client.products.list()` - `client.products.images.update()` - `client.discounts.list()` - `client.addons.list()` - `client.webhooks.list()` - `client.usageEvents.list()` - `client.meters.list()` ### Removed `httpAgent` in favor of `fetchOptions` The `httpAgent` client option has been removed in favor of a [platform-specific `fetchOptions` property](https://github.com/dodopayments/dodopayments-typescript#fetch-options). This change was made as `httpAgent` relied on `node:http` agents which are not supported by any runtime's builtin fetch implementation. If you were using `httpAgent` for proxy support, check out the [new proxy documentation](https://github.com/dodopayments/dodopayments-typescript#configuring-proxies). Before: ```ts import DodoPayments from 'dodopayments'; import http from 'http'; import { HttpsProxyAgent } from 'https-proxy-agent'; // Configure the default for all requests: const client = new DodoPayments({ httpAgent: new HttpsProxyAgent(process.env.PROXY_URL), }); ``` After: ```ts import DodoPayments from 'dodopayments'; import * as undici from 'undici'; const proxyAgent = new undici.ProxyAgent(process.env.PROXY_URL); const client = new DodoPayments({ fetchOptions: { dispatcher: proxyAgent, }, }); ``` ### Changed exports #### Refactor of `dodopayments/core`, `error`, `pagination`, `resource` and `uploads` Much of the `dodopayments/core` file was intended to be internal-only but it was publicly accessible, as such it has been refactored and split up into internal and public files, with public-facing code moved to a new `core` folder and internal code moving to the private `internal` folder. At the same time, we moved some public-facing files which were previously at the top level into `core` to make the file structure cleaner and more clear: ```typescript // Before import 'dodopayments/error'; import 'dodopayments/pagination'; import 'dodopayments/resource'; import 'dodopayments/uploads'; // After import 'dodopayments/core/error'; import 'dodopayments/core/pagination'; import 'dodopayments/core/resource'; import 'dodopayments/core/uploads'; ``` If you were relying on anything that was only exported from `dodopayments/core` and is also not accessible anywhere else, please open an issue and we'll consider adding it to the public API. #### Resource classes Previously under certain circumstances it was possible to import resource classes like `CheckoutSessions` directly from the root of the package. This was never valid at the type level and only worked in CommonJS files. Now you must always either reference them as static class properties or import them directly from the files in which they are defined. ```typescript // Before const { CheckoutSessions } = require('dodopayments'); // After const { DodoPayments } = require('dodopayments'); DodoPayments.CheckoutSessions; // or import directly from dodopayments/resources/checkout-sessions ``` #### Cleaned up `uploads` exports As part of the `core` refactor, `dodopayments/uploads` was moved to `dodopayments/core/uploads` and the following exports were removed, as they were not intended to be a part of the public API: - `fileFromPath` - `BlobPart` - `BlobLike` - `FileLike` - `ResponseLike` - `isResponseLike` - `isBlobLike` - `isFileLike` - `isUploadable` - `isMultipartBody` - `maybeMultipartFormRequestOptions` - `multipartFormRequestOptions` - `createForm` Note that `Uploadable` & `toFile` **are** still exported: ```typescript import { type Uploadable, toFile } from 'dodopayments/core/uploads'; ``` #### `APIClient` The `APIClient` base client class has been removed as it is no longer needed. If you were importing this class then you must now import the main client class: ```typescript // Before import { APIClient } from 'dodopayments/core'; // After import { DodoPayments } from 'dodopayments'; ``` ### File handling The deprecated `fileFromPath` helper has been removed in favor of native Node.js streams: ```ts // Before DodoPayments.fileFromPath('path/to/file'); // After import fs from 'fs'; fs.createReadStream('path/to/file'); ``` Note that this function previously only worked on Node.js. If you're using Bun, you can use [`Bun.file`](https://bun.sh/docs/api/file-io) instead. ### Shims removal Previously you could configure the types that the SDK used like this: ```ts // Tell TypeScript and the package to use the global Web fetch instead of node-fetch. import 'dodopayments/shims/web'; import DodoPayments from 'dodopayments'; ``` The `dodopayments/shims` imports have been removed. Your global types must now be [correctly configured](#minimum-types-requirements). ### Pagination changes The `for await` syntax **is not affected**. This still works as-is: ```ts // Automatically fetches more pages as needed. for await (const paymentListResponse of client.payments.list()) { console.log(paymentListResponse); } ``` The interface for manually paginating through list results has been simplified: ```ts // Before page.nextPageParams(); page.nextPageInfo(); // Required manually handling { url } | { params } type // After page.nextPageRequestOptions(); ``` #### Removed unnecessary classes Page classes for individual methods are now type aliases: ```ts // Before export class PaymentListResponsesDefaultPageNumberPagination extends DefaultPageNumberPagination<PaymentListResponse> {} // After export type PaymentListResponsesDefaultPageNumberPagination = DefaultPageNumberPagination<PaymentListResponse>; ``` If you were importing these classes at runtime, you'll need to switch to importing the base class or only import them at the type-level. ### `dodopayments/src` directory removed Previously IDEs may have auto-completed imports from the `dodopayments/src` directory, however this directory was only included for an improved go-to-definition experience and should not have been used at runtime. If you have any `dodopayments/src/*` imports, you will need to replace them with `dodopayments/*`. ```ts // Before import DodoPayments from 'dodopayments/src'; // After import DodoPayments from 'dodopayments'; ``` ## TypeScript troubleshooting When referencing the library after updating, you may encounter new type errors related to JS features like private properties or fetch classes like Request, Response, and Headers. To resolve these issues, configure your tsconfig.json and install the appropriate `@types` packages for your runtime environment using the guidelines below: ### Browsers `tsconfig.json` ```jsonc { "target": "ES2018", // note: we recommend ES2020 or higher "lib": ["DOM", "DOM.Iterable", "ES2018"] } ``` ### Node.js `tsconfig.json` ```jsonc { "target": "ES2018" // note: we recommend ES2020 or higher } ``` `package.json` ```json { "devDependencies": { "@types/node": ">= 20" } } ``` ### Cloudflare Workers `tsconfig.json` ```jsonc { "target": "ES2018", // note: we recommend ES2020 or higher "lib": ["ES2020"], // <- needed by @cloudflare/workers-types "types": ["@cloudflare/workers-types"] } ``` `package.json` ```json { "devDependencies": { "@cloudflare/workers-types": ">= 0.20221111.0" } } ``` ### Bun `tsconfig.json` ```jsonc { "target": "ES2018" // note: we recommend ES2020 or higher } ``` `package.json` ```json { "devDependencies": { "@types/bun": ">= 1.2.0" } } ```