feat(sdk): vendor function-types and add @tailor-platform/sdk/runtime

.changeset/runtime-wrapper.md

@@ -0,0 +1,22 @@
+---
+"@tailor-platform/sdk": minor
+---
+
+Add `@tailor-platform/sdk/runtime` — typed wrappers for the Tailor Platform Function runtime APIs (`tailor.iconv`, `tailor.secretmanager`, `tailor.authconnection`, `tailor.idp`, `tailor.workflow`, `tailor.context`, and `tailordb.file`). The wrappers and their types are fully self-contained, so you can use them without activating any ambient globals.
+
+```ts
+import { iconv, secretmanager, idp, 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 client = new idp.Client({ namespace: "my-namespace" });
+const { metadata } = await file.upload("ns", "Document", "attachment", recordId, bytes);
+```
+
+The SDK no longer depends on the external `@tailor-platform/function-types` package; its declarations are now vendored inside the SDK. For backwards compatibility the ambient `tailor.*` / `tailordb.*` types are still activated automatically when you import from `@tailor-platform/sdk`, so existing code keeps type-checking with no changes. This implicit activation will be removed in v2.0 — new code is encouraged to use the typed wrappers from `@tailor-platform/sdk/runtime`, or to opt into the globals explicitly via `import "@tailor-platform/sdk/runtime/globals"` (or by listing the entry in `tsconfig.json`'s `compilerOptions.types`).
+
+The capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`) is preserved as a `@deprecated` alias of the new lowercase `tailordb.*` namespace for source-level compatibility with `@tailor-platform/function-types`. It will be removed in v2.0; run `pnpm dlx @tailor-platform/sdk-codemod v2/tailordb-namespace` to migrate. The `@tailor-platform/function-types` declarations are vendored inside the SDK and activated automatically, so you can simply remove `@tailor-platform/function-types` from your `package.json` (and from `tsconfig.json` `compilerOptions.types` if listed) once you've upgraded.
+
+Other test-mock changes from `@tailor-platform/sdk/vitest`:
+
+- Breaking: when an `openDownloadStream` (or `toFileStream()`) call consumes a queued mock result, raw `Uint8Array` / `ArrayBuffer` payloads are now rejected. Enqueue a structured iterable of `StreamValue` items (`{ type: "metadata" }`, `{ type: "chunk", data, position }`, `{ type: "complete" }`) so test streams stay aligned with the platform's structured stream contract. The shorthand `Uint8Array` enqueue is still accepted by `download` / `downloadAsBase64`.

.changeset/sdk-codemod-tailordb-namespace.md

@@ -0,0 +1,5 @@
+---
+"@tailor-platform/sdk-codemod": patch
+---
+
+Add `v2/tailordb-namespace` codemod for the `@tailor-platform/function-types` → `@tailor-platform/sdk` vendoring: rewrite references to the deprecated capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`, `typeof Tailordb.Client`) to the new lowercase `tailordb.*` namespace re-published by the SDK.

example/generated/files.ts

@@ -1,3 +1,11 @@
+import * as file from "@tailor-platform/sdk/runtime/file";
+import type {
+  FileUploadOptions,
+  FileUploadResponse,
+  FileMetadata,
+  FileStreamIterator,
+} from "@tailor-platform/sdk/runtime/file";
+
 export interface TypeWithFiles {
   SalesOrder: {
     fields: "receipt" | "form";
@@ -21,7 +29,7 @@ export async function downloadFile<T extends keyof TypeWithFiles>(
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ) {
-  return await tailordb.file.download(namespaces[type], type, field, recordId);
+  return await file.download(namespaces[type], type, field, recordId);
 }
 
 export async function uploadFile<T extends keyof TypeWithFiles>(
@@ -31,29 +39,29 @@ export async function uploadFile<T extends keyof TypeWithFiles>(
   data: string | ArrayBuffer | Uint8Array<ArrayBufferLike> | number[],
   options?: FileUploadOptions,
 ): Promise<FileUploadResponse> {
-  return await tailordb.file.upload(namespaces[type], type, field, recordId, data, options);
+  return await file.upload(namespaces[type], type, field, recordId, data, options);
 }
 
 export async function deleteFile<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<void> {
-  return await tailordb.file.delete(namespaces[type], type, field, recordId);
+  return await file.delete(namespaces[type], type, field, recordId);
 }
 
 export async function getFileMetadata<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<FileMetadata> {
-  return await tailordb.file.getMetadata(namespaces[type], type, field, recordId);
+  return await file.getMetadata(namespaces[type], type, field, recordId);
 }
 
 export async function openFileDownloadStream<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<FileStreamIterator> {
-  return await tailordb.file.openDownloadStream(namespaces[type], type, field, recordId);
+  return await file.openDownloadStream(namespaces[type], type, field, recordId);
 }

example/tests/fixtures/expected/files.ts

@@ -1,3 +1,11 @@
+import * as file from "@tailor-platform/sdk/runtime/file";
+import type {
+  FileUploadOptions,
+  FileUploadResponse,
+  FileMetadata,
+  FileStreamIterator,
+} from "@tailor-platform/sdk/runtime/file";
+
 export interface TypeWithFiles {
   SalesOrder: {
     fields: "receipt" | "form";
@@ -21,7 +29,7 @@ export async function downloadFile<T extends keyof TypeWithFiles>(
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ) {
-  return await tailordb.file.download(namespaces[type], type, field, recordId);
+  return await file.download(namespaces[type], type, field, recordId);
 }
 
 export async function uploadFile<T extends keyof TypeWithFiles>(
@@ -31,29 +39,29 @@ export async function uploadFile<T extends keyof TypeWithFiles>(
   data: string | ArrayBuffer | Uint8Array<ArrayBufferLike> | number[],
   options?: FileUploadOptions,
 ): Promise<FileUploadResponse> {
-  return await tailordb.file.upload(namespaces[type], type, field, recordId, data, options);
+  return await file.upload(namespaces[type], type, field, recordId, data, options);
 }
 
 export async function deleteFile<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<void> {
-  return await tailordb.file.delete(namespaces[type], type, field, recordId);
+  return await file.delete(namespaces[type], type, field, recordId);
 }
 
 export async function getFileMetadata<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<FileMetadata> {
-  return await tailordb.file.getMetadata(namespaces[type], type, field, recordId);
+  return await file.getMetadata(namespaces[type], type, field, recordId);
 }
 
 export async function openFileDownloadStream<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<FileStreamIterator> {
-  return await tailordb.file.openDownloadStream(namespaces[type], type, field, recordId);
+  return await file.openDownloadStream(namespaces[type], type, field, recordId);
 }

packages/create-sdk/templates/generators/src/generated/files.ts

@@ -1,3 +1,11 @@
+import * as file from "@tailor-platform/sdk/runtime/file";
+import type {
+  FileUploadOptions,
+  FileUploadResponse,
+  FileMetadata,
+  FileStreamIterator,
+} from "@tailor-platform/sdk/runtime/file";
+
 export interface TypeWithFiles {
   Product: {
     fields: "image";
@@ -13,7 +21,7 @@ export async function downloadFile<T extends keyof TypeWithFiles>(
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ) {
-  return await tailordb.file.download(namespaces[type], type, field, recordId);
+  return await file.download(namespaces[type], type, field, recordId);
 }
 
 export async function uploadFile<T extends keyof TypeWithFiles>(
@@ -23,29 +31,29 @@ export async function uploadFile<T extends keyof TypeWithFiles>(
   data: string | ArrayBuffer | Uint8Array<ArrayBufferLike> | number[],
   options?: FileUploadOptions,
 ): Promise<FileUploadResponse> {
-  return await tailordb.file.upload(namespaces[type], type, field, recordId, data, options);
+  return await file.upload(namespaces[type], type, field, recordId, data, options);
 }
 
 export async function deleteFile<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<void> {
-  return await tailordb.file.delete(namespaces[type], type, field, recordId);
+  return await file.delete(namespaces[type], type, field, recordId);
 }
 
 export async function getFileMetadata<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<FileMetadata> {
-  return await tailordb.file.getMetadata(namespaces[type], type, field, recordId);
+  return await file.getMetadata(namespaces[type], type, field, recordId);
 }
 
 export async function openFileDownloadStream<T extends keyof TypeWithFiles>(
   type: T,
   field: TypeWithFiles[T]["fields"],
   recordId: string,
 ): Promise<FileStreamIterator> {
-  return await tailordb.file.openDownloadStream(namespaces[type], type, field, recordId);
+  return await file.openDownloadStream(namespaces[type], type, field, recordId);
 }

packages/sdk-codemod/codemods/v2/tailordb-namespace/codemod.yaml

@@ -0,0 +1,7 @@
+name: "@tailor-platform/tailordb-namespace"
+version: "1.0.0"
+description: "Rename the deprecated capital-cased `Tailordb` ambient namespace to lowercase `tailordb` (e.g. `Tailordb.QueryResult` → `tailordb.QueryResult`)"
+engine: jssg
+language: typescript
+since: "1.0.0"
+until: "2.0.0"

packages/sdk-codemod/codemods/v2/tailordb-namespace/scripts/transform.ts

@@ -0,0 +1,36 @@
+// Members exposed by the deprecated `Tailordb` ambient namespace from
+// `@tailor-platform/function-types`. Each was a type-only declaration that
+// has been re-published under the new lowercase `tailordb` namespace by the
+// SDK. Anything outside this list is left untouched so user-defined symbols
+// that happen to share the `Tailordb.` prefix are not rewritten by accident.
+const TAILORDB_MEMBERS = ["QueryResult", "CommandType", "Client"] as const;
+
+const MEMBER_GROUP = TAILORDB_MEMBERS.join("|");
+
+// Match `Tailordb.<Member>` with word boundaries so neither prefix nor
+// suffix collisions (e.g. `MyTailordb.X`, `Tailordb.QueryResultExtra`) are
+// rewritten. Generic-argument lists and `typeof` qualifiers are not part of
+// the match — they fall outside the boundary and are preserved verbatim.
+const PATTERN = new RegExp(String.raw`\bTailordb\.(${MEMBER_GROUP})\b`, "g");
+
+/**
+ * Rewrite references to the deprecated capital-cased `Tailordb` ambient
+ * namespace to the new lowercase `tailordb` namespace. The capital-cased
+ * namespace was inherited from `@tailor-platform/function-types`; the SDK
+ * keeps it as a `@deprecated` alias in v1 and removes it in v2.
+ *
+ * Only the known type-only members (`QueryResult`, `CommandType`, `Client`)
+ * are rewritten so that unrelated user-defined symbols sharing the
+ * `Tailordb.` prefix remain untouched. Both type-position references
+ * (`Tailordb.QueryResult<T>`, `typeof Tailordb.Client`) and value-position
+ * references (`new Tailordb.Client(...)`) are handled by the same rule.
+ * @param source - File contents
+ * @param _filePath - Absolute path to the file (kept for the runner signature)
+ * @returns Transformed source or null when nothing matched.
+ */
+export default function transform(source: string, _filePath: string): string | null {
+  if (!source.includes("Tailordb.")) return null;
+  PATTERN.lastIndex = 0;
+  const updated = source.replace(PATTERN, (_match, member: string) => `tailordb.${member}`);
+  return updated === source ? null : updated;
+}

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/basic-query-result/expected.ts

@@ -0,0 +1,5 @@
+async function fetchRows<O>(): Promise<tailordb.QueryResult<O>> {
+  return {} as tailordb.QueryResult<O>;
+}
+
+const command: tailordb.CommandType = "SELECT";

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/basic-query-result/input.ts

@@ -0,0 +1,5 @@
+async function fetchRows<O>(): Promise<Tailordb.QueryResult<O>> {
+  return {} as Tailordb.QueryResult<O>;
+}
+
+const command: Tailordb.CommandType = "SELECT";

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/client-instance-and-typeof/expected.ts

@@ -0,0 +1,7 @@
+function takeClient(client: tailordb.Client): void {
+  void client;
+}
+
+function makeClient(Ctor: typeof tailordb.Client): tailordb.Client {
+  return new Ctor({ namespace: "demo" });
+}

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/client-instance-and-typeof/input.ts

@@ -0,0 +1,7 @@
+function takeClient(client: Tailordb.Client): void {
+  void client;
+}
+
+function makeClient(Ctor: typeof Tailordb.Client): Tailordb.Client {
+  return new Ctor({ namespace: "demo" });
+}

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/generic-arg/expected.ts

@@ -0,0 +1,9 @@
+interface Row {
+  id: string;
+}
+
+type RowsResult = tailordb.QueryResult<Row>;
+
+function describe(result: tailordb.QueryResult<{ id: number; tags: readonly string[] }>): number {
+  return result.rowCount;
+}

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/generic-arg/input.ts

@@ -0,0 +1,9 @@
+interface Row {
+  id: string;
+}
+
+type RowsResult = Tailordb.QueryResult<Row>;
+
+function describe(result: Tailordb.QueryResult<{ id: number; tags: readonly string[] }>): number {
+  return result.rowCount;
+}

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/multiple-members/expected.ts

@@ -0,0 +1,9 @@
+async function run<O>(): Promise<tailordb.QueryResult<O>> {
+  const cmd: tailordb.CommandType = "SELECT";
+  const client: tailordb.Client = new (tailordb.Client as typeof tailordb.Client)({
+    namespace: "demo",
+  });
+  void cmd;
+  void client;
+  return {} as tailordb.QueryResult<O>;
+}

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/multiple-members/input.ts

@@ -0,0 +1,9 @@
+async function run<O>(): Promise<Tailordb.QueryResult<O>> {
+  const cmd: Tailordb.CommandType = "SELECT";
+  const client: Tailordb.Client = new (Tailordb.Client as typeof Tailordb.Client)({
+    namespace: "demo",
+  });
+  void cmd;
+  void client;
+  return {} as Tailordb.QueryResult<O>;
+}

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/no-match/input.ts

@@ -0,0 +1,8 @@
+import { createResolver, t } from "@tailor-platform/sdk";
+
+export default createResolver({
+  name: "hello",
+  type: "Query",
+  output: t.string(),
+  body: () => "world",
+});

packages/sdk-codemod/codemods/v2/tailordb-namespace/tests/unrelated-prefix/input.ts

@@ -0,0 +1,15 @@
+// Identifiers that merely *start* with `Tailordb` (or have an unknown
+// member) must not be rewritten by the codemod.
+
+namespace MyTailordb {
+  export type QueryResult<T> = { rows: T[] };
+}
+
+type Mine = MyTailordb.QueryResult<{ id: string }>;
+
+// Unknown member on the deprecated namespace stays untouched (best-effort
+// safety net — there is no `Tailordb.NotAType` on the SDK side).
+type Untouched = Tailordb.NotAType;
+
+// A suffix-extended member name must also stay intact.
+type Extra = Tailordb.QueryResultExtra;

packages/sdk-codemod/src/registry.ts

@@ -77,6 +77,16 @@ const allCodemods: CodemodPackage[] = [
     scriptPath: "v2/auth-invoker-unwrap/scripts/transform.js",
     legacyPatterns: ["auth.invoker"],
   },
+  {
+    id: "v2/tailordb-namespace",
+    name: "Tailordb → tailordb (lowercase ambient namespace)",
+    description:
+      "Rewrite references to the deprecated capital-cased `Tailordb` ambient namespace (`Tailordb.QueryResult`, `Tailordb.CommandType`, `Tailordb.Client`, `typeof Tailordb.Client`) to the new lowercase `tailordb.*` namespace re-published by the SDK in place of `@tailor-platform/function-types`.",
+    since: "1.0.0",
+    until: "2.0.0",
+    scriptPath: "v2/tailordb-namespace/scripts/transform.js",
+    legacyPatterns: ["Tailordb."],
+  },
 ];
 
 /**

packages/sdk-codemod/src/transform.test.ts

@@ -90,4 +90,8 @@ describe("codemod transforms", () => {
   it("v2/auth-invoker-unwrap transforms correctly", async () => {
     await runFixtureCases("v2/auth-invoker-unwrap");
   });
+
+  it("v2/tailordb-namespace transforms correctly", async () => {
+    await runFixtureCases("v2/tailordb-namespace");
+  });
 });

packages/sdk-codemod/tsdown.config.ts

@@ -25,6 +25,8 @@ export default defineConfig([
       "v2/cli-rename/scripts/transform": "codemods/v2/cli-rename/scripts/transform.ts",
       "v2/auth-invoker-unwrap/scripts/transform":
         "codemods/v2/auth-invoker-unwrap/scripts/transform.ts",
+      "v2/tailordb-namespace/scripts/transform":
+        "codemods/v2/tailordb-namespace/scripts/transform.ts",
     },
     format: ["esm"],
     target: "node18",

packages/sdk/README.md

@@ -85,6 +85,7 @@ the installed SDK version. Files are copied (not symlinked) so they survive
 
 ### Guides
 
+- [Runtime API](./docs/runtime.md) - Typed wrappers for `tailor.iconv`, `tailor.secretmanager`, `tailor.idp`, `tailor.workflow`, `tailor.context`, `tailor.authconnection`, and `tailordb.file`
 - [Testing Guide](./docs/testing.md) - Unit and E2E testing patterns
 - [CLI Reference](./docs/cli-reference.md) - Command-line interface documentation