@tailor-platform/sdk 1.60.1 → 1.60.3

package/docs/configuration.md

@@ -13,6 +13,8 @@ For service-specific documentation, see:
 - [Static Website](./services/staticwebsite.md) - Static file hosting
 - [Secret Manager](./services/secret.md) - Secure credential storage
 
+To deploy the same config to multiple workspaces with per-environment values, see [Multi-Environment Configuration](./multi-environment.md).
+
 ### Application Settings
 
 ```typescript
@@ -105,6 +107,7 @@ When using external resources:
 - The resource itself is not deployed by this project
 - The resource must be deployed and available before referencing it
 - You can combine external resources with locally-defined resources
+- TailorDB type names must remain unique across local and external TailorDB namespaces; `deploy` checks external TailorDB type names before applying changes
 - Destructive operations like `tailordb truncate` (and `seedPlugin`'s `seed:reset`) automatically exclude external resources to prevent accidental data loss in shared resources
 
 ### Built-in IdP
@@ -183,7 +186,7 @@ export default defineConfig({
 
 ### Environment Variables
 
-Define environment variables that can be accessed in resolvers, executors, and workflows:
+Use `env` in `defineConfig()` for non-secret values that application code needs at runtime, such as environment names, feature flags, and public service URLs. Values must be strings, numbers, or booleans.
 
 ```typescript
 export default defineConfig({
@@ -196,6 +199,32 @@ export default defineConfig({
 });
 ```
 
+`tailor.config.ts` runs locally when an SDK command loads the config. If values come from your shell or an env file, SDK commands can load them before config evaluation with the global [`--env-file`](./cli-reference.md#environment-file-loading) and `--env-file-if-exists` options:
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  env: {
+    foo: Number(process.env.FOO ?? "1"),
+    bar: process.env.BAR ?? "hello",
+    baz: (process.env.BAZ ?? "true") === "true",
+  },
+});
+```
+
+If the same config defines an auth before-login hook, make sure the config module can be evaluated without Node-only globals in the platform runtime. Avoid arbitrary `process.env` reads in that module; pass literal values, or values generated into a config module before deployment, and read them from the hook's `env` argument.
+
+When the SDK deploys application code or runs detected service code with `function test-run`, it passes the resolved values as the `env` argument. Do not read `process.env` from deployed resolvers, executors, workflow jobs, auth hooks, or migration scripts; Node-side environment variables are not available there. Put sensitive values in [Secret Manager](./services/secret.md) instead of `env`.
+
+| Code location             | Runtime access                                                                                                                            |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Resolver body             | `body: ({ env }) => ...`                                                                                                                  |
+| Executor callbacks        | `body: ({ env }) => ...`, `url: ({ env }) => String(env.bar)`, `variables: ({ env }) => ({ enabled: env.baz })`, or similar callback args |
+| Workflow job body         | `body: (input, { env }) => ...`                                                                                                           |
+| Auth before-login hook    | `handler: async ({ env }) => ...`                                                                                                         |
+| TailorDB migration script | `main(trx, { env }: MigrationContext)`                                                                                                    |
+| `function test-run`       | Same `env` argument shape as the detected resolver, executor, or workflow job                                                             |
+
 ```typescript
 // In resolvers
 body: ({ input, env }) => {
@@ -226,6 +255,12 @@ hooks: {
     invoker: "hook-invoker",
   },
 };
+
+// In TailorDB migration scripts
+export async function main(trx: Transaction, { env }: MigrationContext): Promise<void> {
+  if (!env.baz) return;
+  await trx.updateTable("User").set({ stage: env.bar }).execute();
+}
 ```
 
 ### Workflow Service

package/docs/multi-environment.md

@@ -0,0 +1,74 @@
+# Multi-Environment Configuration
+
+A project typically runs in more than one environment — for example, each developer's own workspace, a staging workspace, and a production workspace. The SDK has no separate "environment" concept: an environment is a workspace you deploy to, and all environments share the same `tailor.config.ts`. This guide shows how to switch the deployment target and how to vary configuration values per environment.
+
+The auto-managed `id` in `defineConfig()` identifies the application, not an environment. Keep the same committed `id` when deploying the same config to multiple workspaces; see [Application Settings](./configuration.md#application-settings).
+
+## Selecting the target workspace
+
+Deployment commands resolve the target workspace from, in priority order, the `--workspace-id` (`-w`) option, the `TAILOR_PLATFORM_WORKSPACE_ID` environment variable, and the active profile. See [Workspace ID Priority](./cli-reference.md#workspace-id-priority).
+
+For one-off commands, pass the workspace explicitly:
+
+```bash
+tailor-sdk deploy -w <staging-workspace-id>
+```
+
+For environments you switch between regularly, create a named profile per environment with the [profile commands](./cli/workspace.md#profile-create) and select it with `--profile` (`-p`) or `TAILOR_PLATFORM_PROFILE`:
+
+```bash
+tailor-sdk profile create staging -u you@example.com -w <staging-workspace-id>
+tailor-sdk profile create production -u you@example.com -w <production-workspace-id> --permission read
+
+tailor-sdk deploy -p staging
+```
+
+Profiles are created with `write` permission by default. The production profile above opts into `--permission read`, which blocks write commands such as `deploy` while the profile is active — a guard against deploying to production by accident. To deploy to production deliberately, pass the workspace explicitly with `-w` without selecting the profile — the guard applies only while a profile is selected via `-p` or `TAILOR_PLATFORM_PROFILE` — or use a separate profile created with `write` permission.
+
+## Varying config values per environment
+
+`tailor.config.ts` is a TypeScript module evaluated locally each time an SDK command loads it, so any value can branch on `process.env`. If the config also defines an auth before-login hook, mind the `process.env` caveat in [Environment Variables](./configuration.md#environment-variables). Keep one env file per environment and load it with the global [`--env-file`](./cli-reference.md#environment-file-loading) option:
+
+```ini
+# .env.production
+APP_ENV=production
+LOG_LEVEL=WARN
+```
+
+```bash
+tailor-sdk deploy -w <production-workspace-id> --env-file .env.production
+```
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  logLevel: process.env.LOG_LEVEL ?? "DEBUG",
+});
+```
+
+Variables already set in your shell are not overwritten by env files, and later files override earlier ones — see [Environment File Loading](./cli-reference.md#environment-file-loading).
+
+## Passing environment values to application code
+
+`process.env` is only available while the config is evaluated locally; deployed resolvers, executors, workflow jobs, auth hooks, and migration scripts cannot read it. To make a value available at runtime, forward it through `env` in `defineConfig()`:
+
+```typescript
+export default defineConfig({
+  name: "my-app",
+  env: {
+    appEnv: process.env.APP_ENV ?? "development",
+  },
+});
+```
+
+See [Environment Variables](./configuration.md#environment-variables) for how `env` values reach each code location. For sensitive values such as API keys, use [Secret Manager](./services/secret.md) instead and supply the per-environment value via `process.env` the same way.
+
+## Settings that belong to a single environment
+
+Some settings reference resources that can exist in only one environment at a time. The static website [customDomains](./services/staticwebsite.md#customdomains) option is an example: a domain is globally unique, so the same `customDomains` value cannot be deployed from two workspaces. Set such values only in the environment that owns the resource:
+
+```typescript
+defineStaticWebSite("my-website", {
+  customDomains: process.env.APP_ENV === "production" ? ["app.example.com"] : undefined,
+});
+```

package/docs/services/executor.md

@@ -212,14 +212,14 @@ Execute JavaScript/TypeScript functions:
 createExecutor({
   operation: {
     kind: "function",
-    body: async ({ newRecord }) => {
-      console.log("New record created:", newRecord);
+    body: async ({ newRecord, env }) => {
+      console.log(`New record created in ${env.bar}:`, newRecord);
     },
   },
 });
 ```
 
-`function` and `jobFunction` `body` args include an `invoker` field: the principal running this function, overridden by `authInvoker` when set; `null` for anonymous calls. Other operation kinds (`graphql`, `webhook`, `workflow`) do not pass `invoker` into their callbacks.
+Executor callbacks receive the trigger args, including `env` from `defineConfig({ env })`. `function` and `jobFunction` `body` args also include an `invoker` field: the principal running this function, overridden by `authInvoker` when set; `null` for anonymous calls. Other operation kinds (`graphql`, `webhook`, `workflow`) receive `env` through their callback args but do not pass `invoker` into those callbacks.
 
 ### Job Function Operation
 

package/docs/services/staticwebsite.md

@@ -74,6 +74,8 @@ defineStaticWebSite("my-website", {
 
 After deploying, use `tailor-sdk 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).
+
 ## Type-safe URL References
 
 The returned website object provides a `url` property that resolves to the actual URL at deployment time. Use this for type-safe configuration:

package/docs/services/tailordb.md

@@ -23,7 +23,7 @@ Define TailorDB Types in files matching glob patterns specified in `tailor.confi
 - **Multiple types per file**: You can define multiple TailorDB types in a single file
 - **Export method**: Use named exports (`export const`)
 - **Export both value and type**: Always export both the runtime value and TypeScript type
-- **Uniqueness**: Type names must be unique across all TailorDB files
+- **Uniqueness**: Type names must be unique across all TailorDB namespaces in the application
 
 ```typescript
 import { db } from "@tailor-platform/sdk";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "1.60.1",
+  "version": "1.60.3",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {