@tailor-platform/sdk 2.29.1 → 2.30.0

package/docs/migration/v3.md

@@ -1,277 +0,0 @@
-# Migrating to v3
-
-<!-- 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>
-```
-
-## workflow.execJobFunction (imported) removed — use job.start()
-
-**Migration:** Manual
-
-`execJobFunction` on the `workflow` value imported from @tailor-platform/sdk/runtime(/workflow) is removed in v3. Calling it directly from a workflow job body to reach another job is not detected as a build-time dependency and has no working use; the target job's own `.start()` method is the only supported way to call it. This does not affect the ambient `tailor.workflow.execJobFunction` global — that's what `.start()` itself compiles down to at build time, and it remains fully supported.
-
-Before:
-
-```ts
-import { workflow } from "@tailor-platform/sdk/runtime";
-
-await workflow.execJobFunction("worker", { id: 1 });
-```
-
-After:
-
-```ts
-import { worker } from "./jobs/worker";
-
-await worker.start({ id: 1 });
-```
-
-<details>
-<summary>Prompt for an AI agent (to perform this migration)</summary>
-
-```text
-workflow.execJobFunction — the value imported from
-@tailor-platform/sdk/runtime or @tailor-platform/sdk/runtime/workflow — is
-removed in v3. Replace each call with the target job's own .start() method:
-import the WorkflowJob the call names and call <job>.start(args, options)
-instead of workflow.execJobFunction("<job-name>", args, options).
-
-This only removes the re-export from @tailor-platform/sdk/runtime. It does
-not affect the ambient tailor.workflow.execJobFunction global, which stays
-fully supported and is what .start() itself compiles down to at build time.
-This codemod does not rewrite ambient tailor.workflow.execJobFunction(...)
-call sites, since removing the import re-export does not affect them — but
-if such a call site sits inside workflow job source and calls another job
-by name, a separate build-time check already rejects it; migrate that call
-to the target job's own .start() method too.
-
-If the job name passed to execJobFunction is not a string literal (a truly
-dynamic dispatch), there is currently no supported replacement — .start()
-only targets a statically known job. Flag this case for a human instead of
-guessing a rewrite.
-```
-
-</details>
-
-## function test-run → function run
-
-**Migration:** Partially automatic
-
-Rename `tailor function test-run` invocations to `tailor function run`. `test-run` remains as a deprecated alias until it is removed in v3.
-
-Before:
-
-```sh
-tailor function test-run resolvers/add.ts --arg '{"a":1,"b":2}'
-```
-
-After:
-
-```sh
-tailor function run resolvers/add.ts --arg '{"a":1,"b":2}'
-```
-
-<details>
-<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
-
-```text
-The `tailor function test-run` subcommand is renamed to `tailor function run`;
-the old name is removed in v3. Replace any remaining `function test-run`
-invocations the codemod did not rewrite (e.g. wrapped across lines or invoked
-through a package runner such as `npx @tailor-platform/sdk`) with
-`function run`. Leave prose that merely mentions the old subcommand name
-unchanged unless it documents a command to type.
-```
-
-</details>
-
-## relation() toward.type → toward.table
-
-**Migration:** Partially automatic
-
-Rename the `.relation()` option `toward.type` to `toward.table`, matching the `db.type()` → `db.table()` rename. The relation's own `type` (its cardinality, e.g. `"n-1"`) is unchanged — only the target-table reference nested under `toward` moves.
-
-Before:
-
-```ts
-customerId: db.uuid().relation({
-  type: "n-1",
-  toward: { type: customer },
-}),
-```
-
-After:
-
-```ts
-customerId: db.uuid().relation({
-  type: "n-1",
-  toward: { table: customer },
-}),
-```
-
-<details>
-<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
-
-```text
-In Tailor SDK v3, `.relation()`'s `toward.type` option is renamed to
-`toward.table` (it names a target table, not a TypeScript/GraphQL type).
-Rename any remaining `toward.type` the codemod did not rewrite (e.g. a
-`toward` object reached through a shared variable, spread, or computed
-key) to `toward.table`. Do not touch the relation's own outer `type`
-property, which is the relation's cardinality (e.g. "n-1", "1-1",
-"keyOnly") and keeps its name.
-```
-
-</details>
-
-## defineConfig inlineSourcemap / logLevel → buildOptions
-
-**Migration:** Partially automatic
-
-Move the top-level `inlineSourcemap` and `logLevel` of `defineConfig()` into `buildOptions`, which groups the settings that control how functions are bundled. The top-level fields keep working until they are removed in v3; setting the same option in both places is rejected.
-
-Before:
-
-```ts
-export default defineConfig({
-  name: "my-app",
-  inlineSourcemap: false,
-  logLevel: "WARN",
-});
-```
-
-After:
-
-```ts
-export default defineConfig({
-  name: "my-app",
-  buildOptions: {
-    inlineSourcemap: false,
-    logLevel: "WARN",
-  },
-});
-```
-
-<details>
-<summary>Prompt for an AI agent (to finish the cases the codemod could not migrate)</summary>
-
-```text
-In Tailor SDK v3, the top-level `inlineSourcemap` and `logLevel` options of
-`defineConfig()` from `@tailor-platform/sdk` are removed in favor of
-`buildOptions.inlineSourcemap` and `buildOptions.logLevel`. For each flagged
-config, move those two properties into a `buildOptions` object (create it if
-it does not exist) without changing their values. When the config is built
-from a variable or a spread, move them in the object that actually defines
-them. If an option is set both at the top level and in `buildOptions`, keep
-the value that the deployed app should use and delete the other; the build
-rejects a config that sets both. Leave `logLevel` options of other tools
-(for example a Vite or Vitest config) unchanged.
-```
-
-</details>
-
-## String file uploads → explicit encoding
-
-**Migration:** Manual
-
-String inputs to the SDK `file.upload` and generated `uploadFile` require an explicit `encoding` in v3. Add `encoding: "utf8"` to preserve the previous behavior; use `"base64"` only when decoding the input is intended. Byte inputs are unchanged. This migration requires checking the input type and regenerating file helpers, so it provides review guidance instead of rewriting calls automatically.
-
-Before:
-
-```ts
-await file.upload(ns, table, field, id, text, { contentType: "text/plain" });
-```
-
-After:
-
-```ts
-await file.upload(ns, table, field, id, text, { contentType: "text/plain", encoding: "utf8" });
-```
-
-<details>
-<summary>Prompt for an AI agent (to perform this migration)</summary>
-
-```text
-Inspect calls to the imported SDK file.upload (including aliases and destructured upload)
-and generated uploadFile helpers, including shared wrappers and option objects.
-For string inputs, add encoding: utf8 to preserve existing text storage behavior.
-Choose encoding: base64 only if decoding is explicitly intended; never infer it from
-the string contents or contentType. Preserve all existing upload options.
-Leave byte-only inputs unchanged. For string | byte unions, supplying encoding: utf8
-preserves behavior because byte input ignores encoding. Narrow shared options types
-so TypeScript can see that encoding is present for strings.
-Run tailor generate to regenerate uploadFile helpers instead of editing generated files.
-The global tailordb.file.upload does not support this encoding option; switch to the
-file import from @tailor-platform/sdk/runtime before using it.
-Do not change unrelated upload APIs or already explicit encodings.
-```
-
-</details>
-
-## secrets.get()/getAll() (defineSecretManager) removed — use secretmanager from @tailor-platform/sdk/runtime
-
-**Migration:** Manual
-
-The `get()`/`getAll()` methods on the object `defineSecretManager()` returns are removed in v3. Importing that object into a resolver, executor, or workflow file bundles the raw values passed to `defineSecretManager()` into that function's deployed code, which fails to build once any value comes from `process.env`. `secretmanager.getSecret()`/`getSecrets()` from `@tailor-platform/sdk/runtime` read the same secrets without importing the config object.
-
-Before:
-
-```ts
-import { secrets } from "../tailor.config";
-
-const apiKey = await secrets.get("api-keys", "stripe-secret-key");
-```
-
-After:
-
-```ts
-import { secretmanager } from "@tailor-platform/sdk/runtime";
-
-const apiKey = await secretmanager.getSecret("api-keys", "stripe-secret-key");
-```
-
-Before:
-
-```ts
-import { secrets } from "../tailor.config";
-
-const [apiKey, webhookSecret] = await secrets.getAll("api-keys", [
-  "sendgrid-api-key",
-  "stripe-secret-key",
-]);
-```
-
-After:
-
-```ts
-import { secretmanager } from "@tailor-platform/sdk/runtime";
-
-const { "sendgrid-api-key": apiKey, "stripe-secret-key": webhookSecret } =
-  await secretmanager.getSecrets("api-keys", ["sendgrid-api-key", "stripe-secret-key"]);
-```
-
-<details>
-<summary>Prompt for an AI agent (to perform this migration)</summary>
-
-```text
-`secrets.get()`/`getAll()` on the object `defineSecretManager()` returns are removed in v3.
-Replace the import with `import { secretmanager } from "@tailor-platform/sdk/runtime";` and
-call `secretmanager.getSecret(vault, name)` in place of `secrets.get(vault, name)`.
-
-`getAll()` needs more than a rename: `secrets.getAll(vault, names)` returned an array of
-values in the same order as `names`, while `secretmanager.getSecrets(vault, names)` returns
-a partial record keyed by each requested name (a name with no value is omitted instead of
-being `undefined` at its index). Rewrite positional destructuring (`const [a, b] = await
-secrets.getAll(v, ["A", "B"])`) into keyed destructuring (`const { A: a, B: b } = await
-secretmanager.getSecrets(v, ["A", "B"])`).
-
-Also review: a `secrets` object re-exported or re-assigned to another name before use, and a
-file that already imports something else named `secretmanager` (rename one of the two on
-conflict).
-```
-
-</details>