@tailor-platform/sdk 2.32.0 → 2.33.0

package/docs/plugin/custom.md

@@ -90,6 +90,40 @@ interface Plugin<TableConfig = unknown, PluginConfig = unknown> {
 | `executors` | `PluginGeneratedExecutor[]`                     | Additional executors to generate                       |
 | `extends`   | `{ fields?: Record<string, TailorAnyDBField> }` | Fields to add to the source table                      |
 
+Resolvers returned by `onTableLoaded` or `onNamespaceLoaded` are loaded, bundled, and deployed to
+the resolver namespace (a `resolver` key in your config) with the same name as the hook's TailorDB
+namespace (a `db` key). These are separate namespaces that only share the name: with
+`db: { main: ... }` and `resolver: { billing: ... }`, generated resolvers go to a `main` resolver
+namespace, not `billing`. If you configure a resolver namespace with that name, generated resolvers
+join its configured files and use its `defaultPermission`. Otherwise, a resolver namespace is created
+automatically. Configure `defaultPermission` to restrict access; without it, generated resolvers are
+accessible to anonymous callers, like regular resolvers with no permission declared. Generating into
+an external resolver namespace or duplicating a resolver name within a namespace fails the build.
+
+For example, a namespace hook can return a query using `t` field builders:
+
+```typescript
+onNamespaceLoaded() {
+  return {
+    resolvers: [{
+      name: "greet",
+      operation: "query",
+      inputFields: { name: t.string() },
+      outputFields: { message: t.string() },
+      body: 'return { message: `Hello, ${context.input.name}!` };',
+    }],
+  };
+}
+```
+
+The `body` string contains JavaScript statements with access to `context.input`, `context.caller`,
+`context.invoker`, and `context.env`. It can use `await` and platform globals, but cannot capture
+plugin-local variables. Embed configuration values as literals with `JSON.stringify` when building
+the string. Field validators must also be self-contained: they can use their arguments and standard
+JavaScript globals, and references to other names are rejected during generation. Input validation and date conversion follow the same rules as regular
+resolvers. Invalid field definitions or JavaScript syntax fail the build with the plugin and namespace
+identified in the error.
+
 Tables in `tables` are validated as complete TailorDB table definitions before registration.
 Fields in `extends.fields` are validated as part of the resulting source table. You can return a
 table builder directly or a structural copy such as `{ ...db.table(...) }`; a copy is accepted as

package/docs/plugin/index.md

@@ -102,6 +102,7 @@ export const plugins = definePlugins(
 Plugins can generate:
 
 - **Tables**: Additional TailorDB tables (e.g., `CustomerHistory`, `Deleted_Customer`)
+- **Resolvers**: Queries and mutations
 - **Executors**: Event handlers triggered by record changes
 - **Field Extensions**: Additional fields added to the source table
 - **Output Files**: TypeScript code and other files via generation-time hooks

package/docs/services/staticwebsite.md

@@ -78,7 +78,37 @@ defineStaticWebSite("my-website", {
 
 After deploying, use `tailor staticwebsite domain get <domain>` to check domain status and retrieve the CNAME targets required for DNS configuration.
 
-A domain can be associated with only one workspace at a time. To set custom domains only in the workspace that owns the domain, see [Multi-Environment Configuration](../multi-environment.md#settings-that-belong-to-a-single-environment).
+A domain can be associated with only one workspace at a time. To set custom domains only in the workspace that owns the domain, see [Multi-Environment Configuration](../multi-environment.md#settings-that-belong-to-a-single-environment). To hand a domain to another site or workspace without taking it offline, see [Moving a domain](#moving-a-domain).
+
+### Moving a domain
+
+A domain already serving traffic can be moved to another static website — in this workspace or another one — without downtime, without reissuing its certificate and without changing DNS. The site that currently holds the domain offers it; the receiving site accepts by listing the domain normally.
+
+On the side giving the domain up, replace the plain entry with the destination:
+
+```typescript
+defineStaticWebSite("my-website", {
+  customDomains: [{ domain: "app.example.com", transferTo: { workspaceId: "..." } }],
+});
+```
+
+Deploying opens the offer. On the receiving side, list the domain as usual and deploy:
+
+```typescript
+defineStaticWebSite("new-website", {
+  customDomains: ["app.example.com"],
+});
+```
+
+That deploy completes the move. The next plan on the giving side reports that the domain moved, and the entry should then be deleted — it describes a move that already happened, not ongoing state.
+
+The two deploys must be separate runs, even when both sites live in the same workspace: the receiving side cannot accept an offer that the same run is still opening, and `tailor deploy` says so rather than failing partway.
+
+These rules apply while an offer is open:
+
+- An offer expires after 7 days. Deploying the entry again after that opens a fresh offer.
+- Neither the domain nor the static website holding it can be removed. Change the entry back to a plain string and deploy to withdraw the offer first; `tailor deploy` and `tailor remove` both refuse before changing anything.
+- An offer takes a moment to become ready. Until it is, the receiving side cannot accept it and its deploy is refused; the giving side's plan says so.
 
 ## Type-safe URL References
 

package/docs/services/tailordb/migration.md

@@ -462,6 +462,25 @@ tailor deploy --migration-skip-steps main-db/backfillUser,main-db/backfillInvoic
 
 Write every step so that running it again is safe: besides the cases above, a step can run a second time when a deploy is interrupted right after it commits. Use `where` clauses that skip rows a step already migrated, as in the example. Rows written while a migration is in progress are not seen by steps that already completed. [Maintenance mode](#maintenance-mode) blocks GraphQL writes but not the writes your resolvers, executors, or workflows make through Kysely, and without it GraphQL clients can write too, so stop such writers until the migration finishes or write steps that tolerate them.
 
+#### Rolling back instead of resuming
+
+By default a failure after another step has completed leaves the migration in progress and the namespace's tables in maintenance mode until you fix the step and deploy again. When you would rather restore the tables first and fix the script afterwards, export `onFailure` next to `steps`:
+
+```typescript
+export const onFailure = "rollback";
+
+export const steps = {
+  // ...
+} satisfies MigrationSteps;
+```
+
+- `onFailure` is `"resume"` (the default, described above) or `"rollback"`. Write it as `export const onFailure = "rollback"` with one of those two string literals; `tailor tailordb migration validate` and `tailor deploy` reject anything else. A script that runs `main` ignores it.
+- With `"rollback"`, a failed step after another step has completed, and post-migration schema changes that fail after every step completed, roll back the pre-migration schema changes like a failing `main` script: tables that already existed are restored to their previous shape and GraphQL permissions, and tables the migration newly introduced are dropped. The in-progress record is cleared before the schema is rolled back, the tables leave maintenance mode, and the checkpoint is not advanced. `tailor deploy` then fails with the step's error under the code `MIGRATION_ROLLED_BACK`, and its suggestion says the next deploy runs every step again. A migration that an earlier deploy left in progress is rolled back the same way once its script exports `"rollback"`, including the tables and GraphQL permissions its earlier Pre-phase wrote.
+- Steps that already completed stay committed. Their changes to existing fields remain in the database, and nothing is recorded as in progress, so the next deploy runs every step again from the beginning. Every step must be safe to run again, or a rolled-back run applies those changes twice. Do not rely on data a step wrote to a field or table that the rollback removed.
+- If `tailor deploy` cannot tell whether a step ran, or the migration's workflow execution may still be running (for example the connection to it was lost), it does not roll anything back even with `"rollback"`: the migration stays in progress as described for a `main` script below. A migration an earlier deploy left in progress is rolled back only when its earlier run is confirmed to have ended, so a failure before that run is inspected, such as a schema error while applying the Pre-phase, keeps it in progress.
+- If the in-progress record cannot be cleared, `tailor deploy` does not roll the schema back. It logs a warning and keeps the migration in progress with its tables in maintenance mode, because a record that outlives a rollback would make the next deploy resume against a schema its completed steps no longer match. Deploy again to resume it as described above, or roll it back without deploying with `tailor tailordb migration resolve --rollback`.
+- If the schema or GraphQL permission of some tables cannot be rolled back, `tailor deploy` still fails with the step's original error. It also warns `Migration <namespace>/<N> was not rolled back completely` and lists the tables that need manual repair, and separately the tables whose GraphQL permission could not be set back. Check them in the workspace and repair them by hand; deploying again does not release them.
+
 ### Settling a migration that stays in progress
 
 When you do not want to resume the migration with another deploy — you abandoned it, or you repaired the data by hand — settle it with `tailor tailordb migration resolve`. Pass exactly one of two options:
@@ -905,10 +924,10 @@ Use `tailor tailordb migration rebaseline` rather than combining `migration gene
 
 ## Failure Recovery
 
-A script that exports `steps` follows different rules once one of its steps has completed: the migration stays in progress and the next deploy resumes it. See [Splitting a migration into steps](#splitting-a-migration-into-steps). Otherwise, if the pre-migration phase or `migrate.ts` fails:
+A script that exports `steps` follows different rules once one of its steps has completed: the migration stays in progress and the next deploy resumes it, unless the script exports `onFailure = "rollback"`. See [Splitting a migration into steps](#splitting-a-migration-into-steps) and [Rolling back instead of resuming](#rolling-back-instead-of-resuming). Otherwise, if the pre-migration phase or `migrate.ts` fails:
 
 - **The transaction rolls back** for that migration's script. Database changes the script made are undone.
-- **The pre-migration schema changes are rolled back** to the prior checkpoint: tables that already existed are restored to their previous shape, and tables the migration newly introduced are dropped. The workspace is left at its prior checkpoint and prior schema — not half-applied.
+- **The pre-migration schema changes are rolled back** to the prior checkpoint: tables that already existed are restored to their previous shape and GraphQL permissions, and tables the migration newly introduced are dropped. The workspace is left at its prior checkpoint and prior schema — not half-applied.
 - The whole `apply` aborts and the checkpoint label is not bumped. Subsequent migrations in the same run do not execute.
 
 The rollback is best-effort per table; if reverting a table fails, a warning is logged and the original migration error is still reported. The next deploy then stops with remote schema drift on that table. Run `tailor tailordb migration validate` to see which tables differ, return the namespace to its checkpoint with `tailor tailordb migration sync <N>`, where `<N>` is the checkpoint `tailor tailordb migration status` reports, and deploy again. `sync` deletes the tables and fields that are not in that migration's snapshot, together with any rows the failed migration wrote to them; the next deploy runs the failed migration again.
@@ -1037,10 +1056,12 @@ npm install -D @electric-sql/pglite
 
 The generated `db.pglite.ts` exports the `CREATE TABLE` script for the same schema `db.ts` types — the tables as the pre-migration phase leaves them while `migrate.ts` runs, including relaxed constraints, renamed fields under both names, and retained removed fields. Run it once on the PGlite instance, stage rows, then run the script in a transaction. `tailor tailordb migration script <N> --with-test` scaffolds this test too when `@electric-sql/pglite` is installed. Type the instance with `Unmigrated<Database>` rather than `Database`: `db.ts` types a column the migration makes required as `T | null` on read but `T` on write (and an enum it narrows as the old values on read but the new ones on write), so that `migrate.ts` cannot write what the migration is removing — which would also stop the test from staging the rows the script has to convert. `Unmigrated` lets every column be written with whatever it can still be read as; `main` still receives a `Transaction<Database>`.
 
+Relations are enforced as on the platform: a row that points at a parent that does not exist is rejected. Write the records the test starts from inside `prepareFixtures`, which leaves relations unchecked while it runs, so you can stage rows that predate a relation, such as rows whose parent does not exist that the script repairs. Relations are checked again when it returns, so the script itself still cannot write a missing parent. NOT NULL, UNIQUE, and CHECK constraints stay enforced. A relation is left unenforced while the pre-migration schema cannot satisfy it: when a pending type change leaves the field a different type from its target, when the migration retargets the relation to another table, or when the target field's unique constraint is still withheld. How relations on array fields and inside nested objects behave is described under [Real SQL execution with PGlite](../../testing.md#real-sql-execution-with-pglite-mocktailordbwithpglite).
+
 ```typescript
 // migrations/0005/migrate.pglite.test.ts
 import { PGlite } from "@electric-sql/pglite";
-import { createKyselyPGlite, type Unmigrated } from "@tailor-platform/sdk/vitest";
+import { createKyselyPGlite, prepareFixtures, type Unmigrated } from "@tailor-platform/sdk/vitest";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { pgliteSchema } from "./db.pglite";
 import { main } from "./migrate";
@@ -1061,13 +1082,15 @@ afterAll(async () => {
 describe("0005 add required email", () => {
   test("backfills null emails and keeps existing ones", async () => {
     const now = new Date();
-    await db
-      .insertInto("User")
-      .values([
-        { name: "a", email: null, createdAt: now, updatedAt: now },
-        { name: "b", email: "b@example.com", createdAt: now, updatedAt: now },
-      ])
-      .execute();
+    await prepareFixtures(pglite, async () => {
+      await db
+        .insertInto("User")
+        .values([
+          { name: "a", email: null, createdAt: now, updatedAt: now },
+          { name: "b", email: "b@example.com", createdAt: now, updatedAt: now },
+        ])
+        .execute();
+    });
 
     await db.transaction().execute((trx) => main(trx));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "2.32.0",
+  "version": "2.33.0",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -160,10 +160,10 @@
     "@bufbuild/protovalidate": "1.3.0",
     "@connectrpc/connect": "2.2.0",
     "@connectrpc/connect-node": "2.2.0",
-    "@inquirer/core": "12.0.4",
-    "@inquirer/prompts": "8.7.3",
+    "@inquirer/core": "12.0.5",
+    "@inquirer/prompts": "8.7.4",
     "@jridgewell/trace-mapping": "0.3.31",
-    "@napi-rs/keyring": "2.1.1",
+    "@napi-rs/keyring": "2.1.2",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/context-async-hooks": "2.12.0",
     "@opentelemetry/exporter-trace-otlp-proto": "0.223.0",
@@ -196,7 +196,7 @@
     "p-limit": "7.3.3",
     "pathe": "2.0.3",
     "pgsql-ast-parser": "12.0.2",
-    "pkg-types": "2.3.3",
+    "pkg-types": "2.4.0",
     "rolldown": "1.2.14",
     "semver": "7.8.5",
     "sql-highlight": "6.1.0",

package/dist/application-C2bPmmbh.mjs

@@ -1 +0,0 @@
-export{t as defineApplication,n as generatePluginFilesIfNeeded}from"./application-D0xNJbag.mjs";