@tailor-platform/sdk 1.50.1 → 1.51.1

package/docs/cli/tailordb.md

@@ -77,14 +77,14 @@ tailor-sdk tailordb truncate [options] [types]
 
 **Options**
 
-| Option                          | Alias | Description                                | Required | Default              | Env                               |
-| ------------------------------- | ----- | ------------------------------------------ | -------- | -------------------- | --------------------------------- |
-| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
-| `--profile <PROFILE>`           | `-p`  | Workspace profile                          | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
-| `--config <CONFIG>`             | `-c`  | Path to SDK config file                    | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
-| `--yes`                         | `-y`  | Skip confirmation prompts                  | No       | `false`              | -                                 |
-| `--all`                         | `-a`  | Truncate all tables in all namespaces      | No       | `false`              | -                                 |
-| `--namespace <NAMESPACE>`       | `-n`  | Truncate all tables in specified namespace | No       | -                    | -                                 |
+| Option                          | Alias | Description                                                                | Required | Default              | Env                               |
+| ------------------------------- | ----- | -------------------------------------------------------------------------- | -------- | -------------------- | --------------------------------- |
+| `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID                                                               | No       | -                    | `TAILOR_PLATFORM_WORKSPACE_ID`    |
+| `--profile <PROFILE>`           | `-p`  | Workspace profile                                                          | No       | -                    | `TAILOR_PLATFORM_PROFILE`         |
+| `--config <CONFIG>`             | `-c`  | Path to SDK config file                                                    | No       | `"tailor.config.ts"` | `TAILOR_PLATFORM_SDK_CONFIG_PATH` |
+| `--yes`                         | `-y`  | Skip confirmation prompts                                                  | No       | `false`              | -                                 |
+| `--all`                         | `-a`  | Truncate all tables in all owned namespaces (excludes external namespaces) | No       | `false`              | -                                 |
+| `--namespace <NAMESPACE>`       | `-n`  | Truncate all tables in specified namespace                                 | No       | -                    | -                                 |
 
 <!-- politty:command:tailordb truncate:options:end -->
 
@@ -122,6 +122,7 @@ tailor-sdk tailordb truncate User Post --yes
   - `--namespace`: requires typing `truncate <namespace-name>`
   - Specific types: requires typing `yes`
 - Use `--yes` flag to skip confirmation prompts (useful for scripts and CI/CD)
+- Namespaces declared with `{ external: true }` are skipped by `--all` and rejected with a dedicated error when targeted by `--namespace`. Run truncate from the app that owns the namespace.
 
 <!-- politty:command:tailordb migration:heading:start -->
 

package/docs/cli-reference.md

@@ -53,22 +53,23 @@ tailor-sdk deploy --env-file .env --env-file .env.production
 
 You can use environment variables to configure workspace and authentication:
 
-| Variable                                     | Description                                                                  |
-| -------------------------------------------- | ---------------------------------------------------------------------------- |
-| `TAILOR_PLATFORM_WORKSPACE_ID`               | Workspace ID for deployment commands                                         |
-| `TAILOR_PLATFORM_ORGANIZATION_ID`            | Organization ID for organization commands                                    |
-| `TAILOR_PLATFORM_FOLDER_ID`                  | Folder ID for folder commands                                                |
-| `TAILOR_PLATFORM_TOKEN`                      | Authentication token (alternative to `login`)                                |
-| `TAILOR_TOKEN`                               | **Deprecated.** Use `TAILOR_PLATFORM_TOKEN` instead                          |
-| `TAILOR_PLATFORM_PROFILE`                    | Workspace profile name                                                       |
-| `TAILOR_PLATFORM_SDK_CONFIG_PATH`            | Path to SDK config file                                                      |
-| `TAILOR_PLATFORM_SDK_DTS_PATH`               | Output path for generated `tailor.d.ts` type definition file                 |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Client ID for `login --machine-user`                                         |
-| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Client secret for `login --machine-user`                                     |
-| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function test-run` |
-| `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)  |
-| `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                             |
-| `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                   |
+| Variable                                     | Description                                                                                       |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `TAILOR_PLATFORM_WORKSPACE_ID`               | Workspace ID for deployment commands                                                              |
+| `TAILOR_PLATFORM_ORGANIZATION_ID`            | Organization ID for organization commands                                                         |
+| `TAILOR_PLATFORM_FOLDER_ID`                  | Folder ID for folder commands                                                                     |
+| `TAILOR_PLATFORM_TOKEN`                      | Authentication token (alternative to `login`)                                                     |
+| `TAILOR_TOKEN`                               | **Deprecated.** Use `TAILOR_PLATFORM_TOKEN` instead                                               |
+| `TAILOR_PLATFORM_PROFILE`                    | Workspace profile name                                                                            |
+| `TAILOR_PLATFORM_SDK_CONFIG_PATH`            | Path to SDK config file                                                                           |
+| `TAILOR_PLATFORM_SDK_DTS_PATH`               | Output path for generated `tailor.d.ts` type definition file                                      |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_ID`     | Client ID for `login --machine-user`                                                              |
+| `TAILOR_PLATFORM_MACHINE_USER_CLIENT_SECRET` | Client secret for `login --machine-user`                                                          |
+| `TAILOR_PLATFORM_MACHINE_USER_NAME`          | Default machine user name for `query`, `workflow start`, `function test-run`                      |
+| `TAILOR_BUNDLE_CONCURRENCY`                  | Max concurrent bundle workers for `deploy` (resolvers/executors/workflows). Defaults to CPU count |
+| `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)                       |
+| `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                  |
+| `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                                        |
 
 ### Authentication Token Priority
 

package/docs/configuration.md

@@ -93,6 +93,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
+- 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
 

package/docs/generator/builtin.md

@@ -253,3 +253,5 @@ node seed/exec.mjs -m admin --truncate --yes
 The `--machine-user` option is required at runtime if `machineUserName` is not configured in the generator options.
 
 The generated files are compatible with gql-ingest for bulk data import.
+
+The `exec.mjs` is fully regenerated on every `sdk generate` and starts with an `@generated` header — do not hand-edit it. Its `--truncate` path reuses the `tailordb truncate` command, so namespaces declared with `{ external: true }` are skipped automatically and a shell app cannot wipe a sibling app's data via `seed:reset`.

package/docs/runtime.md

@@ -0,0 +1,113 @@
+# Runtime API
+
+`@tailor-platform/sdk/runtime` provides typed wrappers for the `tailor.*` and `tailordb.file` APIs that the Tailor Platform Function runtime injects into the global scope at execution time. The wrappers are thin and delegate to the platform-provided globals; they exist so that you can:
+
+- Reach the runtime API without relying on a separate ambient `.d.ts` package
+- Get IDE-friendly imports (`iconv.convert`, `idp.Client`, …) instead of unmemorable `tailor.iconv.convert(...)` calls
+- Use the same module surface in resolvers, executors, and workflows
+
+The wrappers and their associated types are self-contained — you do not need to activate any ambient globals to use them. If you also want `tailor.iconv.convert(...)` calls to type-check, opt into the globals via the [Activating the global types](#activating-the-global-types) section below.
+
+## Quick Start
+
+```ts
+import {
+  iconv,
+  secretmanager,
+  authconnection,
+  idp,
+  workflow,
+  context,
+  file,
+} from "@tailor-platform/sdk/runtime";
+
+const utf8 = iconv.convert(sjisBuffer, "Shift_JIS", "UTF-8");
+
+const apiKey = await secretmanager.getSecret("my-vault", "API_KEY");
+
+const token = await authconnection.getConnectionToken("google");
+
+const client = new idp.Client({ namespace: "my-namespace" });
+const { users } = await client.users({ first: 10 });
+
+const executionId = await workflow.triggerWorkflow("approval", { reportId });
+
+const invoker = context.getInvoker();
+
+const { metadata } = await file.upload("my-namespace", "Document", "attachment", recordId, bytes);
+```
+
+## Subpath imports
+
+Each namespace can also be imported individually so you only pull what you need:
+
+```ts
+import * as iconv from "@tailor-platform/sdk/runtime/iconv";
+import type { ListUsersResponse, ClientConfig } from "@tailor-platform/sdk/runtime/idp";
+```
+
+## Activating the global types
+
+Most users do not need to touch the globals entry — `@tailor-platform/sdk/runtime` (and its subpath modules) cover the same surface without depending on any ambient declaration.
+
+For backwards compatibility with the previous `@tailor-platform/function-types`-based setup, the SDK still activates the ambient `tailor.*` / `tailordb.*` types automatically when you import from `@tailor-platform/sdk`. **This implicit activation will be removed in v2.0**; new code should prefer the typed wrappers from `@tailor-platform/sdk/runtime`.
+
+If you want to opt into the globals explicitly (or you are migrating ahead of v2.0), add a single side-effect import anywhere in your project:
+
+```ts
+import "@tailor-platform/sdk/runtime/globals";
+```
+
+Or register the entry in `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "types": ["@tailor-platform/sdk/runtime/globals"],
+  },
+}
+```
+
+## Namespaces
+
+The runtime entry re-exports the following namespaces. Detailed signatures, parameters, and return types live in the JSDoc next to each export — hover the symbol in your IDE or browse the source.
+
+- `iconv` — character encoding conversion (`convert`, `convertBuffer`, `decode`, `encode`, `encodings`, `Iconv`)
+- `secretmanager` — secret-vault access (`getSecret`, `getSecrets`)
+- `authconnection` — OAuth-style connection tokens (`getConnectionToken`)
+- `idp` — IdP user management (`new Client({ namespace })`)
+- `workflow` — workflow & job control (`triggerWorkflow`, `triggerJobFunction`, `wait`, `resolve`)
+- `context` — execution context (`getInvoker`)
+- `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `openDownloadStream`)
+
+## Testing
+
+`@tailor-platform/sdk/vitest` ships mock controllers for every runtime namespace. Pair them with the `tailor-runtime` Vitest environment so your unit tests run against the same wrappers your production code does.
+
+```ts
+import { iconv, secretmanager } from "@tailor-platform/sdk/runtime";
+import { iconvMock, secretmanagerMock } from "@tailor-platform/sdk/vitest";
+import { beforeEach, expect, test } from "vitest";
+
+beforeEach(() => {
+  iconvMock.reset();
+  secretmanagerMock.reset();
+});
+
+test("encodes via iconv", () => {
+  iconvMock.setResolver(() => new Uint8Array([0x82, 0xa0]));
+
+  const out = iconv.convert("あ", "UTF-8", "Shift_JIS");
+
+  expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
+  expect(iconvMock.calls[0]?.method).toBe("convert");
+});
+
+test("reads from a vault", async () => {
+  secretmanagerMock.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
+
+  await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
+});
+```
+
+See [Testing Guide](./testing.md#runtime-environment-emulation-beta) for the full list of mock controllers and the `tailor-runtime` environment setup.

package/docs/testing.md

@@ -228,6 +228,27 @@ test("mock file download", async () => {
 });
 ```
 
+For `openDownloadStream`, enqueue an iterable of `StreamValue` items — `metadata`, one or more `chunk` items, and a terminal `complete`. Raw `Uint8Array` / `ArrayBuffer` chunks are rejected so tests stay aligned with the platform's structured stream contract.
+
+```typescript
+test("mock file download stream", async () => {
+  fileMock.enqueueResult([
+    {
+      type: "metadata",
+      metadata: { contentType: "image/png", fileSize: 3, sha256sum: "abc" },
+    },
+    { type: "chunk", data: new Uint8Array([1, 2]), position: 0 },
+    { type: "chunk", data: new Uint8Array([3]), position: 2 },
+    { type: "complete" },
+  ]);
+
+  const stream = await tailordb.file.openDownloadStream("ns", "Doc", "attachment", "r-1");
+  const items = [];
+  for await (const item of stream) items.push(item);
+  expect(items).toHaveLength(4);
+});
+```
+
 ### Iconv Mock
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk",
-  "version": "1.50.1",
+  "version": "1.51.1",
   "description": "Tailor Platform SDK - The SDK to work with Tailor Platform",
   "license": "MIT",
   "repository": {
@@ -87,6 +87,51 @@
       "types": "./dist/vitest/environment.d.mts",
       "import": "./dist/vitest/environment.mjs",
       "default": "./dist/vitest/environment.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.mts",
+      "import": "./dist/runtime/index.mjs",
+      "default": "./dist/runtime/index.mjs"
+    },
+    "./runtime/globals": {
+      "types": "./dist/runtime/globals.d.mts",
+      "import": "./dist/runtime/globals.mjs",
+      "default": "./dist/runtime/globals.mjs"
+    },
+    "./runtime/iconv": {
+      "types": "./dist/runtime/iconv.d.mts",
+      "import": "./dist/runtime/iconv.mjs",
+      "default": "./dist/runtime/iconv.mjs"
+    },
+    "./runtime/secretmanager": {
+      "types": "./dist/runtime/secretmanager.d.mts",
+      "import": "./dist/runtime/secretmanager.mjs",
+      "default": "./dist/runtime/secretmanager.mjs"
+    },
+    "./runtime/authconnection": {
+      "types": "./dist/runtime/authconnection.d.mts",
+      "import": "./dist/runtime/authconnection.mjs",
+      "default": "./dist/runtime/authconnection.mjs"
+    },
+    "./runtime/idp": {
+      "types": "./dist/runtime/idp.d.mts",
+      "import": "./dist/runtime/idp.mjs",
+      "default": "./dist/runtime/idp.mjs"
+    },
+    "./runtime/workflow": {
+      "types": "./dist/runtime/workflow.d.mts",
+      "import": "./dist/runtime/workflow.mjs",
+      "default": "./dist/runtime/workflow.mjs"
+    },
+    "./runtime/context": {
+      "types": "./dist/runtime/context.d.mts",
+      "import": "./dist/runtime/context.mjs",
+      "default": "./dist/runtime/context.mjs"
+    },
+    "./runtime/file": {
+      "types": "./dist/runtime/file.d.mts",
+      "import": "./dist/runtime/file.mjs",
+      "default": "./dist/runtime/file.mjs"
     }
   },
   "dependencies": {
@@ -101,14 +146,13 @@
     "@liam-hq/cli": "0.7.24",
     "@napi-rs/keyring": "1.3.0",
     "@opentelemetry/api": "1.9.1",
-    "@opentelemetry/exporter-trace-otlp-proto": "0.216.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "0.218.0",
     "@opentelemetry/resources": "2.7.1",
     "@opentelemetry/sdk-trace-node": "2.7.1",
-    "@opentelemetry/semantic-conventions": "1.40.0",
+    "@opentelemetry/semantic-conventions": "1.41.1",
     "@oxc-project/types": "0.127.0",
     "@standard-schema/spec": "1.1.0",
     "@tailor-platform/function-kysely-tailordb": "0.1.3",
-    "@tailor-platform/function-types": "0.8.5",
     "@toiroakr/lines-db": "0.9.2",
     "@toiroakr/read-multiline": "0.4.1",
     "@urql/core": "6.0.1",
@@ -118,8 +162,8 @@
     "date-fns": "4.1.0",
     "es-toolkit": "1.46.1",
     "find-up-simple": "1.0.1",
-    "globals": "17.5.0",
-    "graphql": "16.13.2",
+    "globals": "17.6.0",
+    "graphql": "16.14.0",
     "inflection": "3.0.2",
     "kysely": "0.28.17",
     "madge": "8.0.0",
@@ -142,7 +186,7 @@
     "type-fest": "5.6.0",
     "undici": "6.25.0",
     "xdg-basedir": "5.1.0",
-    "zod": "4.3.6"
+    "zod": "4.4.3"
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "2.7.1",
@@ -150,11 +194,11 @@
     "@types/mime-types": "3.0.1",
     "@types/node": "24.12.4",
     "@types/semver": "7.7.1",
-    "@typescript/native-preview": "7.0.0-dev.20260516.1",
+    "@typescript/native-preview": "7.0.0-dev.20260524.1",
     "@vitest/coverage-v8": "4.1.6",
     "oxfmt": "0.46.0",
     "oxlint": "1.61.0",
-    "oxlint-tsgolint": "0.22.1",
+    "oxlint-tsgolint": "0.23.0",
     "sonda": "0.11.1",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",