@tailor-platform/sdk 2.0.0-next.1 → 2.0.0-next.3

package/docs/migration/v2.md

@@ -0,0 +1,735 @@
+# Migrating to v2
+
+<!-- Generated from the sdk-codemod registry. Run `pnpm codemod:docs:update` and edit `packages/sdk-codemod/src/registry.ts` instead of this file. -->
+
+Run the codemods, then finish anything reported as not migrated automatically:
+
+```sh
+npx @tailor-platform/sdk-codemod --from <current-version> --to <target-version>
+```
+
+## defineGenerators → definePlugins
+
+**Migration:** Partially automatic
+
+Migrate defineGenerators() tuple syntax to definePlugins() with explicit plugin imports
+
+Before:
+
+```ts
+import { defineGenerators } from "@tailor-platform/sdk";
+
+export const generators = defineGenerators(
+  ["@tailor-platform/kysely-type", { distPath: "db.ts" }],
+);
+```
+
+After:
+
+```ts
+import { definePlugins } from "@tailor-platform/sdk";
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
+
+export const generators = definePlugins(kyselyTypePlugin({ distPath: "db.ts" }));
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+defineGenerators() is replaced by definePlugins() in v2. The codemod rewrites the
+known plugin tuples (kysely-type, enum-constants, file-utils, seed). For any
+remaining defineGenerators([...]) the codemod left in place — a plugin it does not
+know, or a non-tuple/spread form — convert it to definePlugins(pluginFn(config)),
+importing the matching plugin from its @tailor-platform/sdk/plugin/<name> subpath.
+```
+
+</details>
+
+## @tailor-platform/sdk/cli plugin imports → dedicated subpaths
+
+**Migration:** Automatic
+
+Rewrite deprecated plugin re-export imports (kyselyTypePlugin, enumConstantsPlugin, fileUtilsPlugin, seedPlugin) from `@tailor-platform/sdk/cli` to their dedicated plugin subpaths
+
+Before:
+
+```ts
+import { kyselyTypePlugin } from "@tailor-platform/sdk/cli";
+```
+
+After:
+
+```ts
+import { kyselyTypePlugin } from "@tailor-platform/sdk/plugin/kysely-type";
+```
+
+## function test-run --arg input unwrap
+
+**Migration:** Automatic
+
+Strip the deprecated {input: ...} wrapper from `tailor function test-run --arg` JSON in scripts and docs
+
+Before:
+
+```sh
+tailor function test-run resolvers/add.ts --arg '{"input":{"a":1}}'
+```
+
+After:
+
+```sh
+tailor function test-run resolvers/add.ts --arg '{"a":1}'
+```
+
+## tailor-sdk-skills → tailor skills add
+
+**Migration:** Partially automatic
+
+Replace deprecated `tailor-sdk-skills` invocations with `tailor skills add`
+
+Before:
+
+```sh
+npx tailor-sdk-skills
+```
+
+After:
+
+```sh
+tailor skills add
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The standalone tailor-sdk-skills binary is removed in v2; call the skills add
+subcommand on the main tailor CLI instead. Replace any remaining
+tailor-sdk-skills invocations the codemod did not rewrite with
+`tailor skills add`.
+```
+
+</details>
+
+## Unify TailorUser/TailorActor/TailorActorType/TailorInvoker → TailorPrincipal
+
+**Migration:** Partially automatic
+
+Rename TailorUser/TailorActor/TailorActorType/TailorInvoker to TailorPrincipal, drop unauthenticatedTailorUser, rename resolver body `user` to `caller`, and rename TailorDB callback `user` to `invoker`
+
+Type references unify under `TailorPrincipal`:
+
+Before:
+
+```ts
+import type { TailorUser } from "@tailor-platform/sdk";
+```
+
+After:
+
+```ts
+import type { TailorPrincipal } from "@tailor-platform/sdk";
+```
+
+The resolver body `user` becomes `caller`:
+
+Before:
+
+```ts
+body: ({ input, user }) => user.id,
+```
+
+After:
+
+```ts
+body: ({ input, caller }) => caller.id,
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Finish the cases the codemod left for manual migration:
+- Rename user -> caller in resolver bodies the codemod skipped because a `caller`
+  binding already exists or renaming would shadow/collide with another value.
+- Replace member-access on the removed unauthenticatedTailorUser (e.g.
+  unauthenticatedTailorUser.id); the codemod only replaced standalone references
+  with null and left member access to surface a type error.
+- Review helper adapters that still accept or read `context.user`; v2 resolver
+  context uses nullable `caller` and `invoker`, so project-specific helper
+  semantics for anonymous callers and command invokers must be chosen explicitly.
+- Review `caller?.` values passed to APIs that require non-null values. If the
+  resolver requires authentication, throw or otherwise narrow before the call;
+  if anonymous callers are allowed, keep the nullable flow explicit.
+Use TailorPrincipal for the unified user/actor/invoker type.
+```
+
+</details>
+
+## AttributeMap → Attributes
+
+**Migration:** Partially automatic
+
+Rename auth attribute module augmentation and related SDK type names from `AttributeMap` to `Attributes`
+
+Module augmentation uses `Attributes`:
+
+Before:
+
+```ts
+declare module "@tailor-platform/sdk" {
+  interface AttributeMap {
+    role: string;
+  }
+}
+```
+
+After:
+
+```ts
+declare module "@tailor-platform/sdk" {
+  interface Attributes {
+    role: string;
+  }
+}
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2, the auth attribute type API is renamed from `AttributeMap`
+to `Attributes`; related SDK types are renamed to `UserAttributes` and
+`InferredAttributes`. The codemod rewrites SDK imports, re-exports,
+namespace-qualified references, import() type references, and module
+augmentations. Review any remaining matches manually and leave unrelated
+local names or deploy/proto wire field names unchanged.
+```
+
+</details>
+
+## tailor-sdk apply → tailor-sdk deploy
+
+**Migration:** Automatic
+
+Rewrite `tailor-sdk apply` invocations in package.json scripts, shell scripts, CI configs, and docs to the canonical v2 `tailor-sdk deploy` command
+
+Before:
+
+```sh
+tailor-sdk apply --profile prod
+```
+
+After:
+
+```sh
+tailor-sdk deploy --profile prod
+```
+
+## v2 CLI rename
+
+**Migration:** Partially automatic
+
+Rewrite `tailor-sdk crash-report` to `tailor-sdk crashreport` and `--machineuser` to `--machine-user` across package.json scripts, shell scripts, CI configs, and docs
+
+Before:
+
+```sh
+tailor-sdk crash-report list
+tailor-sdk login --machineuser
+```
+
+After:
+
+```sh
+tailor-sdk crashreport list
+tailor-sdk login --machine-user
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Apply the v2 CLI renames the codemod did not reach (only `tailor-sdk`-prefixed
+invocations are rewritten): `tailor-sdk crash-report` -> `tailor-sdk crashreport`
+and the `--machineuser` option -> `--machine-user`. Leave unrelated commands that
+happen to use `--machineuser` alone.
+```
+
+</details>
+
+## SDK environment variable rename
+
+**Migration:** Partially automatic
+
+Rewrite unambiguous removed SDK environment variable names to their v2 `TAILOR_*` names and flag generic names for manual review
+
+Before:
+
+```sh
+TAILOR_PLATFORM_SDK_BUILD_ONLY=true tailor-sdk deploy
+```
+
+After:
+
+```sh
+TAILOR_DEPLOY_BUILD_ONLY=true tailor-sdk deploy
+```
+
+Before:
+
+```ts
+const token = process.env.TAILOR_TOKEN;
+```
+
+After:
+
+```ts
+const token = process.env.TAILOR_PLATFORM_TOKEN;
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Review any remaining removed SDK environment variable names after the codemod
+runs. The codemod intentionally leaves generic names such as `LOG_LEVEL`,
+`PLATFORM_URL`, and `PLATFORM_OAUTH2_CLIENT_ID` for manual review because
+they can configure non-SDK tools. Replace only actual SDK usages with their
+v2 names. If a remaining match is an unrelated local identifier, fixture
+label, or historical documentation that intentionally does not configure the
+SDK, leave it unchanged.
+```
+
+</details>
+
+## auth.invoker("name") → "name"
+
+**Migration:** Partially automatic
+
+Replace statically identified SDK `auth.invoker("name")` option values with the bare `"name"` string while preserving the `authInvoker` key for SDK versions before the option rename.
+
+Before:
+
+```ts
+createResolver({ authInvoker: auth.invoker("manager") });
+```
+
+After:
+
+```ts
+createResolver({ authInvoker: "manager" });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2 the auth.invoker() helper is removed; an invoker is now the
+machine user name passed directly as a string. The codemod already rewrote the
+statically identified SDK option form authInvoker: auth.invoker("name") to authInvoker: "name". These files still contain
+auth.invoker(...) calls that need manual review.
+
+For each remaining auth.invoker(<expr>) call:
+1. Replace the whole call with <expr> only where the target option expects a
+   machine user name string; platform/runtime authInvoker payloads still expect
+   the object form.
+2. Keep the authInvoker key when targeting SDK versions before the invoker
+   option rename; later v2 targets run a separate codemod for that key rename.
+3. After removing every auth.invoker usage in a file, delete the now-unused auth
+   import (keeping it pulls Node-only config modules into runtime bundles); leave
+   the import if auth is still referenced elsewhere.
+
+Do not change behavior beyond the auth.invoker() removal.
+```
+
+</details>
+
+## auth.invoker("name") → invoker: "name"
+
+**Migration:** Partially automatic
+
+Rename statically identified SDK `authInvoker` options to `invoker`, replace `auth.invoker("name")` there with the bare `"name"` string, and drop the `auth` import when no other reference remains. Ambiguous workflow `.trigger()` calls are left for manual review. The `auth.invoker()` helper is removed in v2 because importing `auth` from `tailor.config.ts` into runtime files pulls Node-only modules into the bundle.
+
+Before:
+
+```ts
+createResolver({ invoker: auth.invoker("manager") });
+```
+
+After:
+
+```ts
+createResolver({ invoker: "manager" });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2 the auth.invoker() helper is removed; an invoker is now the
+machine user name passed directly as a string. The codemod already rewrote the
+statically identified SDK option form authInvoker: auth.invoker("name") to invoker: "name" and renamed supported authInvoker option keys. These files still contain
+auth.invoker(...) calls or authInvoker keys that need manual review.
+
+For each remaining auth.invoker(<expr>) call:
+1. Replace the whole call with <expr> only where the target option expects a
+   machine user name string; platform/runtime authInvoker payloads still expect
+   the object form.
+2. Rename remaining authInvoker option keys to invoker only for SDK resolver,
+   executor, workflow.trigger(), or startWorkflow() options. Keep platform/runtime
+   payload keys such as tailor.workflow.triggerWorkflow(..., { authInvoker: ... }).
+3. After removing every auth.invoker usage in a file, delete the now-unused auth
+   import (keeping it pulls Node-only config modules into runtime bundles); leave
+   the import if auth is still referenced elsewhere.
+
+Do not change behavior beyond the SDK option rename and auth.invoker() removal.
+```
+
+</details>
+
+## auth.getConnectionToken() → runtime authconnection
+
+**Migration:** Partially automatic
+
+The deprecated `auth.getConnectionToken()` helper returned by `defineAuth()` is removed in v2. Use `authconnection.getConnectionToken(...)` from `@tailor-platform/sdk/runtime` in resolvers, executors, and workflows instead.
+
+Before:
+
+```ts
+import { auth } from "../tailor.config";
+
+const token = await auth.getConnectionToken("google");
+```
+
+After:
+
+```ts
+import { authconnection } from "@tailor-platform/sdk/runtime";
+
+const token = await authconnection.getConnectionToken("google");
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2 the auth.getConnectionToken() helper returned by defineAuth()
+is removed. Runtime code should call authconnection.getConnectionToken(...) from
+@tailor-platform/sdk/runtime instead of importing auth from tailor.config.ts.
+
+For each getConnectionToken usage where <receiver> is a defineAuth() result
+imported from tailor.config.ts:
+1. Replace <receiver>.getConnectionToken(<expr>) calls with
+   authconnection.getConnectionToken(<expr>).
+2. Update non-call references, including <receiver>.getConnectionToken,
+   <receiver>["getConnectionToken"], and destructuring from <receiver>, to
+   reference authconnection instead.
+3. Add or reuse `import { authconnection } from "@tailor-platform/sdk/runtime"`.
+4. Remove the auth import from tailor.config.ts only when no other auth reference
+   remains in the file.
+
+Leave usages unchanged when the receiver is already the runtime authconnection
+wrapper or global tailor.authconnection.
+```
+
+</details>
+
+## Tailordb → tailordb (lowercase ambient namespace)
+
+**Migration:** Partially automatic
+
+Rewrite references to the removed capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`, `typeof Tailordb.Client`) to the lowercase `tailordb.*` namespace exposed by `@tailor-platform/sdk/runtime/globals`. Because v2 no longer activates ambient declarations automatically, each file that contains `tailordb.*` references after the rewrite must also add `import "@tailor-platform/sdk/runtime/globals"`.
+
+Before:
+
+```ts
+const command: Tailordb.CommandType = "SELECT";
+```
+
+After:
+
+```ts
+import "@tailor-platform/sdk/runtime/globals";
+const command: tailordb.CommandType = "SELECT";
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The capital-cased Tailordb ambient namespace is removed in v2; use the lowercase
+tailordb.* namespace from @tailor-platform/sdk/runtime/globals. The codemod rewrites
+the known members (QueryResult, CommandType, Client). Rewrite any other remaining
+Tailordb.* reference to its tailordb.* equivalent (and confirm the member still
+exists on the lowercase namespace).
+Also add `import "@tailor-platform/sdk/runtime/globals"` at the top of each file
+that contains any tailordb.* type reference — v2 no longer activates ambient
+declarations automatically on SDK import.
+```
+
+</details>
+
+## executeScript arg JSON.stringify → value
+
+**Migration:** Partially automatic
+
+Unwrap `JSON.stringify(...)` passed as the `executeScript` `arg` option. In v2 `arg` takes a JSON-serializable value and is serialized internally, so a pre-stringified argument double-encodes.
+
+Before:
+
+```ts
+await executeScript({ ...opts, arg: JSON.stringify({ a: 1 }) });
+```
+
+After:
+
+```ts
+await executeScript({ ...opts, arg: { a: 1 } });
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+In Tailor SDK v2 the executeScript() arg option takes a JSON-serializable value
+and is serialized internally, so a pre-stringified argument double-encodes. The
+codemod already rewrote the direct form arg: JSON.stringify(X) to arg: X. Review
+the executeScript calls in these files for cases it could not rewrite — where the
+arg value is reached indirectly, for example:
+- a variable holding a JSON.stringify(...) result (const s = JSON.stringify(x); ... arg: s)
+- JSON.stringify(x, null, 2) or another multi-argument form
+- an options object built or spread dynamically
+
+For each such call, pass the underlying value directly as arg (drop the
+JSON.stringify wrapper) so executeScript serializes it once. Leave calls that
+already pass a plain value unchanged.
+```
+
+</details>
+
+## defineWaitPoint/defineWaitPoints → createWaitPoint/createWaitPoints
+
+**Migration:** Partially automatic
+
+Rename `defineWaitPoint` and `defineWaitPoints` to `createWaitPoint` and `createWaitPoints`. The functions create runtime instances with `.wait()` / `.resolve()` methods, so the `create*` prefix is used consistently.
+
+Before:
+
+```ts
+import { defineWaitPoints } from "@tailor-platform/sdk";
+
+export const { approval } = defineWaitPoints((define) => ({
+  approval: define<{ message: string }, { approved: boolean }>(),
+}));
+```
+
+After:
+
+```ts
+import { createWaitPoints } from "@tailor-platform/sdk";
+
+export const { approval } = createWaitPoints((define) => ({
+  approval: define<{ message: string }, { approved: boolean }>(),
+}));
+```
+
+## openDownloadStream → downloadStream
+
+**Migration:** Manual
+
+The deprecated `openDownloadStream` file-streaming API is removed in v2. Use `downloadStream` for streamed file downloads. The generated file utilities now emit `downloadFileStream` (which calls `downloadStream` and returns `FileDownloadStreamResponse`) instead of the removed `openFileDownloadStream` helper.
+
+Before:
+
+```ts
+const res = await openDownloadStream(namespace, typeName, fieldName, recordId);
+```
+
+After:
+
+```ts
+const res = await downloadStream(namespace, typeName, fieldName, recordId);
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+The openDownloadStream file-streaming API is removed in v2. Replace every call to
+openDownloadStream with downloadStream (same arguments). If you used the generated
+openFileDownloadStream helper, switch to downloadFileStream, which calls
+downloadStream and returns FileDownloadStreamResponse.
+```
+
+</details>
+
+## Ambient runtime globals are opt-in
+
+**Migration:** Partially automatic
+
+Importing `@tailor-platform/sdk` no longer activates the ambient `tailor.*` / `tailordb.*` global declarations. The codemod rewrites simple direct `new tailor.idp.Client(...)` calls to the typed `idp.Client` wrapper from `@tailor-platform/sdk/runtime`; broader runtime global usage remains review-only. Only if you relied on the ambient globals directly, add `import "@tailor-platform/sdk/runtime/globals"`. (The capital-cased `Tailordb.*` namespace is removed separately — see the `Tailordb → tailordb` codemod.)
+
+Preferred: switch to the typed wrappers from `@tailor-platform/sdk/runtime` and drop the ambient globals:
+
+Before:
+
+```ts
+const client = new tailor.idp.Client();
+```
+
+After:
+
+```ts
+import { idp } from "@tailor-platform/sdk/runtime";
+const client = new idp.Client({ namespace: "my-namespace" });
+```
+
+Fallback: only if you must keep referencing the bare `tailor.*` names, opt into the global declarations:
+
+Before:
+
+```ts
+const client = new tailor.idp.Client();
+```
+
+After:
+
+```ts
+import "@tailor-platform/sdk/runtime/globals";
+const client = new tailor.idp.Client();
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+The v2 SDK no longer enables ambient Tailor runtime globals from
+`@tailor-platform/sdk`. For each flagged file that uses `tailor.*`,
+`tailordb.*`, or Tailor runtime error globals, prefer migrating to the
+typed wrappers from `@tailor-platform/sdk/runtime`. The codemod already
+rewrites direct `new tailor.idp.Client(...)` calls to `new idp.Client(...)`
+when the file has no conflicting `tailor` or `idp` binding. For any remaining
+`tailor.idp.Client` references, either resolve the binding collision and use
+`idp.Client`, or keep the ambient global deliberately.
+
+Only when the file must keep referencing the bare `tailor.*` names directly,
+opt into the global declarations instead by adding one of these:
+- per-file: `import "@tailor-platform/sdk/runtime/globals";`
+- project-wide: `"types": ["@tailor-platform/sdk/runtime/globals"]` in
+  the relevant tsconfig compilerOptions
+
+Leave files unchanged when the matching name is local, imported from another
+module, or appears only in comments or prose strings. Embedded code strings
+that use runtime globals are review-only findings; do not insert imports inside
+string literals.
+```
+
+</details>
+
+## Workflow .trigger() and trigger tests
+
+**Migration:** Manual
+
+Workflow job `.trigger()` now aligns with the platform runtime: it returns the job result directly instead of a Promise wrapper, and tests no longer run job bodies locally. Mock trigger responses with `mockWorkflow()` (`setJobHandler` / `enqueueResult`, assert via `triggeredJobs`), or use `runWorkflowLocally()` for a full-chain local run.
+
+Tests must mock the workflow runtime instead of running bodies locally:
+
+Before:
+
+```ts
+const result = await orderJob.trigger({ id });
+expect(result.status).toBe("done");
+```
+
+After:
+
+```ts
+using wf = mockWorkflow();
+wf.setJobHandler((jobName) => (jobName === "order-job" ? { status: "done" } : null));
+const result = await orderJob.trigger({ id });
+expect(result.status).toBe("done");
+```
+
+<details>
+<summary>Prompt for an AI agent (to perform this migration)</summary>
+
+```text
+Workflow job .trigger() now uses the platform workflow runtime instead of running
+the job body locally. In tests, acquire `using wf = mockWorkflow()` and provide
+trigger responses (setJobHandler / enqueueResult), or use runWorkflowLocally() for a
+full-chain local run; an unmocked trigger now throws. Outside tests, treat the
+trigger result as the job output directly (no Promise wrapper to unwrap).
+```
+
+</details>
+
+## tailor-sdk binary → tailor
+
+**Migration:** Partially automatic
+
+Rename the CLI binary from `tailor-sdk` to `tailor` in package.json scripts, shell scripts, CI workflows, source files, generated declaration comments, and documentation. Does not rename `.tailor-sdk` directory paths or the `create-tailor-sdk` scaffolding package. Note: v2 also changes the default generated output directory from `.tailor-sdk/` to `.tailor/` and the setup lock file from `.github/tailor-sdk.lock` to `.github/tailor.lock`. Run `mv .tailor-sdk .tailor` to migrate the generated output directory (preserves auth connection state and other local files). Run `git mv .github/tailor-sdk.lock .github/tailor.lock` if the old lock file exists; without it `tailor setup check` will treat all managed workflows as missing. Exact ignore-file entries for `.tailor-sdk/` are handled by the generated-output ignore codemod.
+
+Before:
+
+```sh
+tailor-sdk deploy
+npx tailor-sdk@latest login
+```
+
+After:
+
+```sh
+tailor deploy
+npx @tailor-platform/sdk@latest login
+```
+
+<details>
+<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
+
+```text
+Rename any remaining `tailor-sdk` binary invocations to `tailor`. Only rewrite
+the binary name — leave `.tailor-sdk` directory paths and `create-tailor-sdk`
+package references unchanged.
+```
+
+</details>
+
+## .tailor-sdk ignore entries → .tailor
+
+**Migration:** Automatic
+
+Rewrite exact ignore-file entries for the v1 generated output directory from `.tailor-sdk` to the v2 `.tailor` directory. Other `.tailor-sdk` paths and prose are left unchanged.
+
+Before:
+
+```gitignore
+.tailor-sdk/
+```
+
+After:
+
+```gitignore
+.tailor/
+```
+
+## Behavioral changes (no migration required)
+
+These v2 changes alter runtime or CLI behavior; no source change is needed.
+
+### CLI tokens stored in the OS keyring
+
+CLI login tokens are stored in the OS keyring by default when available, falling back to the platform config file when it is not. No source change is required; re-login if you need tokens moved into the keyring.
+
+### CLI users keyed by subject ID
+
+The CLI stores human users by their stable subject ID instead of email (email is kept for display). Legacy email-keyed entries are migrated automatically on the next login or token refresh. No source change is required.
+
+### function logs require a content hash for source mapping
+
+`tailor function logs` maps stack traces against the function bundle only when the execution recorded a `contentHash`. Executions without one now show raw stack traces instead of mapped frames. No source change is required.
+
+### Node.js minimum version raised to 22.15.0
+
+v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. No source change is required; ensure your environment runs Node.js 22.15.0+.