chore(internal): fix format script

Author: stainless-app[bot]

.devcontainer/devcontainer.json

@@ -9,9 +9,7 @@
   "postCreateCommand": "yarn install",
   "customizations": {
     "vscode": {
-      "extensions": [
-        "esbenp.prettier-vscode"
-      ]
+      "extensions": ["esbenp.prettier-vscode"]
     }
   }
 }

.github/workflows/release-doctor.yml

@@ -19,4 +19,3 @@ jobs:
           bash ./bin/check-release-environment
         env:
           NPM_TOKEN: ${{ secrets.WRITER_NPM_TOKEN || secrets.NPM_TOKEN }}
-

MIGRATION.md

@@ -4,95 +4,40 @@ This guide outlines the changes and steps needed to migrate your codebase to the
 
 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 `writer-sdk` package, then run `./node_modules/.bin/writer-sdk 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 18.x last LTS (Required for built-in fetch support)
+- Node.js 18.x last LTS (Required for builtin fetch support)
   - This was previously documented as the minimum supported Node.js version but Node.js 16.x mostly worked at runtime; now it will not.
 - TypeScript 4.9
 - Jest 28
 
-## Minimum types requirements
-
-### DOM
-
-`tsconfig.json`
-
-```jsonc
-{
-  "target": "ES2015", // note: we recommend ES2020 or higher
-  "lib": ["DOM", "DOM.Iterable", "ES2018"]
-}
-```
-
-### Node.js
-
-`tsconfig.json`
-
-```jsonc
-{
-  "target": "ES2015" // note: we recommend ES2020 or higher
-}
-```
-
-`package.json`
-
-```json
-{
-  "devDependencies": {
-    "@types/node": ">= 18.18.7"
-  }
-}
-```
-
-### Cloudflare Workers
-
-`tsconfig.json`
-
-```jsonc
-{
-  "target": "ES2015", // 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
+## Breaking changes
 
-`tsconfig.json`
+### Web types for `withResponse`, `asResponse`, and `APIError.headers`
 
-```jsonc
-{
-  "target": "ES2015" // note: we recommend ES2020 or higher
-}
-```
-
-`package.json`
+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).
 
-```json
-{
-  "devDependencies": {
-    "@types/bun": ">= 1.2.0"
-  }
-}
+```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);
 ```
 
-### Deno
-
-No config needed!
-
-## Breaking changes
+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>`.
 
 ### Named path parameters
 
@@ -355,6 +300,80 @@ import Writer from 'writer-sdk/src';
 import Writer from 'writer-sdk';
 ```
 
-### Headers
+## 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
 
-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 just `Record<string, string | null | undefined>`.
+`tsconfig.json`
+
+```jsonc
+{
+  "target": "ES2018" // note: we recommend ES2020 or higher
+}
+```
+
+`package.json`
+
+```json
+{
+  "devDependencies": {
+    "@types/node": ">= 18.18.7"
+  }
+}
+```
+
+### 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"
+  }
+}
+```

bin/cli

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('child_process');
+
+const commands = {
+  migrate: {
+    description: 'Run migrations to update to the latest major SDK version',
+    fn: () => {
+      const result = spawnSync(
+        'npx',
+        [
+          '-y',
+          'https://github.com/stainless-api/migrate-ts/releases/download/0.0.2/stainless-api-migrate-0.0.2-6.tgz',
+          '--migrationConfig',
+          require.resolve('./migration-config.json'),
+          ...process.argv.slice(3),
+        ],
+        { stdio: 'inherit' },
+      );
+      if (result.status !== 0) {
+        process.exit(result.status);
+      }
+    },
+  },
+};
+
+function exitWithHelp() {
+  console.log(`Usage: writer-sdk <subcommand>`);
+  console.log();
+  console.log('Subcommands:');
+
+  for (const [name, info] of Object.entries(commands)) {
+    console.log(`  ${name}  ${info.description}`);
+  }
+
+  console.log();
+  process.exit(1);
+}
+
+if (process.argv.length < 3) {
+  exitWithHelp();
+}
+
+const commandName = process.argv[2];
+
+const command = commands[commandName];
+if (!command) {
+  console.log(`Unknown subcommand ${commandName}.`);
+  exitWithHelp();
+}
+
+command.fn();

bin/migration-config.json

@@ -0,0 +1,40 @@
+{
+  "pkg": "writer-sdk",
+  "githubRepo": "https://github.com/writer/writer-node",
+  "clientClass": "Writer",
+  "methods": [
+    {
+      "base": "graphs",
+      "name": "removeFileFromGraph",
+      "params": [
+        {
+          "type": "param",
+          "key": "file_id",
+          "location": "path"
+        },
+        {
+          "type": "params",
+          "maybeOverload": false
+        },
+        {
+          "type": "options"
+        }
+      ],
+      "oldParams": [
+        {
+          "type": "param",
+          "key": "graph_id",
+          "location": "path"
+        },
+        {
+          "type": "param",
+          "key": "file_id",
+          "location": "path"
+        },
+        {
+          "type": "options"
+        }
+      ]
+    }
+  ]
+}

package.json

@@ -17,7 +17,7 @@
     "test": "./scripts/test",
     "build": "./scripts/build",
     "prepublishOnly": "echo 'to publish, run yarn build && (cd dist; yarn publish)' && exit 1",
-    "format": "prettier --write --cache --cache-strategy metadata . !dist",
+    "format": "./scripts/format",
     "prepare": "if ./scripts/utils/check-is-in-git-install.sh; then ./scripts/build && ./scripts/utils/git-swap.sh; fi",
     "tsn": "ts-node -r tsconfig-paths/register",
     "lint": "./scripts/lint",
@@ -59,6 +59,9 @@
     "writer-sdk": ".",
     "writer-sdk/*": "./src/*"
   },
+  "bin": {
+    "writer-sdk": "bin/cli"
+  },
   "exports": {
     ".": {
       "import": "./dist/index.mjs",

release-please-config.json

@@ -60,8 +60,5 @@
     }
   ],
   "release-type": "node",
-  "extra-files": [
-    "src/version.ts",
-    "README.md"
-  ]
+  "extra-files": ["src/version.ts", "README.md"]
 }

scripts/build

@@ -19,9 +19,13 @@ for file in LICENSE CHANGELOG.md; do
   if [ -e "${file}" ]; then cp "${file}" dist; fi
 done
 if [ -e "bin/cli" ]; then
-  mkdir dist/bin
+  mkdir -p dist/bin
   cp -p "bin/cli" dist/bin/;
 fi
+if [ -e "bin/migration-config.json" ]; then
+  mkdir -p dist/bin
+  cp -p "bin/migration-config.json" dist/bin/;
+fi
 # this converts the export map paths for the dist directory
 # and does a few other minor things
 node scripts/utils/make-dist-package-json.cjs > dist/package.json

scripts/format

@@ -6,3 +6,7 @@ cd "$(dirname "$0")/.."
 
 echo "==> Running eslint --fix"
 ./node_modules/.bin/eslint --fix .
+
+echo "==> Running prettier --write"
+# format things eslint didn't
+./node_modules/.bin/prettier --write --cache --cache-strategy metadata . '!**/dist' '!**/*.ts' '!**/*.mts' '!**/*.cts' '!**/*.js' '!**/*.mjs' '!**/*.cjs'

tsconfig.build.json

@@ -6,7 +6,7 @@
     "rootDir": "./dist/src",
     "paths": {
       "writer-sdk/*": ["dist/src/*"],
-      "writer-sdk": ["dist/src/index.ts"],
+      "writer-sdk": ["dist/src/index.ts"]
     },
     "noEmit": false,
     "declaration": true,