@tailor-platform/sdk 2.0.0-next.0 → 2.0.0-next.10

package/docs/multi-environment.md

@@ -11,20 +11,42 @@ Deployment commands resolve the target workspace from, in priority order, the `-
 For one-off commands, pass the workspace explicitly:
 
 ```bash
-tailor-sdk deploy -w <staging-workspace-id>
+tailor 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 profile create staging -u you@example.com -w <staging-workspace-id>
+tailor profile create production -u you@example.com -w <production-workspace-id> --permission read
 
-tailor-sdk deploy -p staging
+tailor 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.
 
+If a profile targets a non-default Tailor Platform API, save that connection on the profile as well. User login tokens are stored per Platform URL, so you can log in once for each Platform and then switch with only the profile:
+
+```bash
+export TAILOR_PLATFORM_URL=<platform-api-url>
+export TAILOR_PLATFORM_OAUTH2_CLIENT_ID=<oauth2-client-id>
+export TAILOR_PLATFORM_CONSOLE_URL=<console-url>
+
+tailor login
+tailor profile create development \
+  -u you@example.com \
+  -w <development-workspace-id> \
+  --platform-url "$TAILOR_PLATFORM_URL" \
+  --oauth2-client-id "$TAILOR_PLATFORM_OAUTH2_CLIENT_ID" \
+  --console-url "$TAILOR_PLATFORM_CONSOLE_URL"
+
+unset TAILOR_PLATFORM_URL TAILOR_PLATFORM_OAUTH2_CLIENT_ID TAILOR_PLATFORM_CONSOLE_URL
+tailor deploy -p development
+tailor open -p development
+```
+
+After the profile exists, run `tailor login -p development` to refresh the login for that Platform without re-exporting the connection variables.
+
 ## 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:
@@ -32,17 +54,17 @@ Profiles are created with `write` permission by default. The production profile
 ```ini
 # .env.production
 APP_ENV=production
-LOG_LEVEL=WARN
+TAILOR_APP_LOG_LEVEL=WARN
 ```
 
 ```bash
-tailor-sdk deploy -w <production-workspace-id> --env-file .env.production
+tailor deploy -w <production-workspace-id> --env-file .env.production
 ```
 
 ```typescript
 export default defineConfig({
   name: "my-app",
-  logLevel: process.env.LOG_LEVEL ?? "DEBUG",
+  logLevel: process.env.TAILOR_APP_LOG_LEVEL ?? "DEBUG",
 });
 ```
 

package/docs/plugin/custom.md

@@ -18,7 +18,7 @@ const myPlugin: Plugin = {
 export default myPlugin; // Required: must be default export
 ```
 
-This is required so that generators can use plugin-generated TailorDB types via `getGeneratedType()`.
+This is required so that other plugins and generation-time hooks can use plugin-generated TailorDB types via `getGeneratedType()`.
 
 ## Plugin Interface
 
@@ -93,7 +93,7 @@ interface Plugin<TypeConfig = unknown, PluginConfig = unknown> {
 onTypeLoaded(context) {
   const { type, typeConfig, namespace } = context;
   return {
-    types: { archive: db.type(`Deleted_${type.name}`, { ... }) },
+    types: { archive: db.table(`Deleted_${type.name}`, { ... }) },
     extends: { fields: { deletedAt: db.datetime({ optional: true }) } },
     executors: [{ name: `${type.name}-on-delete`, resolve: async () => await import("./on-delete"), context: { sourceType: type, namespace } }],
   };
@@ -122,7 +122,7 @@ Same as `TypePluginOutput` but without `extends` (namespace plugins cannot exten
 ```typescript
 onNamespaceLoaded(context) {
   return {
-    types: { auditLog: db.type("AuditLog", { action: db.string(), ... }) },
+    types: { auditLog: db.table("AuditLog", { action: db.string(), ... }) },
   };
 },
 ```
@@ -276,7 +276,7 @@ import type {
 
 ## getGeneratedType Helper
 
-The SDK provides an async `getGeneratedType()` helper function to retrieve plugin-generated TailorDB types. This enables generators and other tools to work with types generated by plugins.
+The SDK provides an async `getGeneratedType()` helper function to retrieve plugin-generated TailorDB types. This enables plugins and other tools to work with types generated by plugins.
 
 ```typescript
 import { join } from "node:path";
@@ -343,7 +343,7 @@ function processSoftDelete(
 
   // Generate archive type
   const archiveType = db
-    .type(`${prefix}${type.name}`, {
+    .table(`${prefix}${type.name}`, {
       originalId: db.uuid().description("ID of the deleted record"),
       originalData: db.string().description("JSON snapshot of deleted record"),
       deletedAt: db.datetime().description("When the record was deleted"),
@@ -450,7 +450,7 @@ export const plugins = definePlugins(
 
 // tailordb/customer.ts
 export const customer = db
-  .type("Customer", {
+  .table("Customer", {
     name: db.string(),
     email: db.string(),
   })

package/docs/plugin/index.md

@@ -6,7 +6,7 @@ Plugins extend TailorDB types by automatically generating additional types, exec
 
 ## Overview
 
-When you run `tailor-sdk generate`, the SDK:
+When you run `tailor generate`, the SDK:
 
 1. Loads all TailorDB types with plugin attachments
 2. Passes each type to the attached plugins
@@ -43,7 +43,7 @@ Use the `.plugin()` method to attach plugins to specific types:
 import { db } from "@tailor-platform/sdk";
 
 export const user = db
-  .type("User", {
+  .table("User", {
     name: db.string(),
     email: db.string(),
   })
@@ -58,7 +58,7 @@ Some plugins accept per-type configuration:
 
 ```typescript
 export const customer = db
-  .type("Customer", {
+  .table("Customer", {
     name: db.string(),
     // ...
   })
@@ -102,18 +102,18 @@ Plugins can generate:
 - **Field Extensions**: Additional fields added to the source type
 - **Output Files**: TypeScript code and other files via generation-time hooks
 
-Generated files are placed under `.tailor-sdk/<plugin-id>/` (the plugin ID is sanitized,
+Generated files are placed under `.tailor/<plugin-id>/` (the plugin ID is sanitized,
 e.g. `@example/soft-delete` → `example-soft-delete`), such as:
 
-- `.tailor-sdk/example-soft-delete/types`
-- `.tailor-sdk/example-soft-delete/executors`
+- `.tailor/example-soft-delete/types`
+- `.tailor/example-soft-delete/executors`
 
 ## Plugin Lifecycle
 
-Plugins have 5 hooks across two lifecycle phases. Each hook fires at a specific point in the `tailor-sdk generate` pipeline:
+Plugins have 5 hooks across two lifecycle phases. Each hook fires at a specific point in the `tailor generate` pipeline:
 
 ```
-tailor-sdk generate
+tailor generate
 │
 ├─ Load TailorDB types
 │   ├─ onTypeLoaded        ← per type with .plugin() attached
@@ -149,7 +149,7 @@ These hooks produce TailorDB types, resolvers, and executors that become part of
 | `onResolverReady` | TailorDB types, Resolvers, Auth            | Write output files |
 | `onExecutorReady` | TailorDB types, Resolvers, Executors, Auth | Write output files |
 
-These hooks receive all finalized data and produce output files (TypeScript code, etc.). They replace the previous standalone `defineGenerators()` approach. No `importPath` required.
+These hooks receive all finalized data and produce output files (TypeScript code, etc.). No `importPath` required.
 
 A plugin can implement hooks from either or both phases.
 

package/docs/quickstart.md

@@ -12,7 +12,7 @@ Contact us [here](https://www.tailor.tech/demo) to get started.
 
 ### Install Node.js
 
-The SDK requires Node.js 22 or later. Install Node.js via your package manager by following the official Node.js instructions.
+The SDK requires Node.js 22.15.0 or later. Install Node.js via your package manager by following the official Node.js instructions.
 
 Alternatively, you can use [Bun](https://bun.sh/) as the runtime.
 
@@ -24,20 +24,22 @@ The following command creates a new project with the required configuration file
 
 ```bash
 npm create @tailor-platform/sdk -- --template hello-world example-app
+cd example-app
 # Or with Bun:
 # bun create @tailor-platform/sdk --template hello-world example-app
+# cd example-app
 ```
 
 Before deploying your app, you need to create a workspace:
 
 ```bash
-npx tailor-sdk login
-npx tailor-sdk workspace create --name <workspace-name> --region <workspace-region>
-npx tailor-sdk workspace list
+npx tailor login
+npx tailor workspace create --name <workspace-name> --region <workspace-region>
+npx tailor workspace list
 
 # Or with Bun:
-# bunx tailor-sdk login
-# bunx tailor-sdk workspace create --name <workspace-name> --region <workspace-region>
+# bunx tailor login
+# bunx tailor workspace create --name <workspace-name> --region <workspace-region>
 
 # OR
 # Create a new workspace using Tailor Platform Console
@@ -49,7 +51,6 @@ npx tailor-sdk workspace list
 Run the deploy command to deploy your project:
 
 ```bash
-cd example-app
 npm run deploy -- --workspace-id <your-workspace-id>
 # Or with Bun:
 # bun run deploy --workspace-id <your-workspace-id>

package/docs/runtime.md

@@ -19,6 +19,8 @@ import {
   workflow,
   context,
   file,
+  aigateway,
+  logger,
 } from "@tailor-platform/sdk/runtime";
 
 const utf8 = iconv.convert(sjisBuffer, "Shift_JIS", "UTF-8");
@@ -30,11 +32,15 @@ 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 executionId = await workflow.startWorkflow("approval", { reportId });
 
 const invoker = context.getInvoker();
 
 const { metadata } = await file.upload("my-namespace", "Document", "attachment", recordId, bytes);
+
+const { url } = await aigateway.get("my-aigateway");
+
+logger.info("order processed", { orderId: "o-1", total: 99.5 });
 ```
 
 ## Subpath imports
@@ -42,17 +48,17 @@ const { metadata } = await file.upload("my-namespace", "Document", "attachment",
 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";
+import { iconv } from "@tailor-platform/sdk/runtime/iconv";
+import { idp, type ListUsersResponse, type ClientConfig } from "@tailor-platform/sdk/runtime/idp";
 ```
 
+`TailorContextAPI` and `TailorWorkflowAPI` describe the imported SDK wrapper objects. When typing direct access to the platform-provided globals or a runtime mock, use `PlatformContextAPI` or `PlatformWorkflowAPI` instead.
+
 ## 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:
+Importing from `@tailor-platform/sdk` does not activate the ambient `tailor.*` / `tailordb.*` declarations. If you want to opt into the globals, add a single side-effect import anywhere in your project:
 
 ```ts
 import "@tailor-platform/sdk/runtime/globals";
@@ -68,6 +74,8 @@ Or register the entry in `tsconfig.json`:
 }
 ```
 
+The globals entry exposes the lowercase `tailordb.*` namespace only. If your project still references the removed capital-cased `Tailordb.*` namespace from `@tailor-platform/function-types`, migrate before upgrading in two steps: run `pnpm dlx @tailor-platform/sdk-codemod v2/tailordb-namespace` to rewrite `Tailordb.*` references to lowercase `tailordb.*`, then add the `import "@tailor-platform/sdk/runtime/globals"` opt-in above so the rewritten references resolve.
+
 ## 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.
@@ -76,9 +84,11 @@ The runtime entry re-exports the following namespaces. Detailed signatures, para
 - `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`)
+- `workflow` — workflow & job control (`startWorkflow`, `resumeWorkflowExecution`, `execJobFunction`, `wait`, `resolve`; `startJobFunction` is kept as an alias of `execJobFunction`)
 - `context` — execution context (`getInvoker`)
-- `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`, `openDownloadStream` _(deprecated)_)
+- `file` — `tailordb.file` BLOB API (`upload`, `download`, `downloadAsBase64`, `delete`, `getMetadata`, `downloadStream`, `uploadStream`)
+- `aigateway` — AI Gateway URL resolution (`get`)
+- `logger` — structured logging with severity and attributes; the message is written to standard output, the full entry with its attributes is exported over OpenTelemetry where the attributes are queryable (`debug`, `info`, `warn`, `error`, `setAttributes`)
 
 ## Testing
 
@@ -91,17 +101,16 @@ import { expect, test } from "vitest";
 
 test("encodes via iconv", () => {
   using iconvM = mockIconv();
-  iconvM.setResolver(() => new Uint8Array([0x82, 0xa0]));
+  iconvM.convert.mockReturnValue(new Uint8Array([0x82, 0xa0]));
 
   const out = iconv.convert("あ", "UTF-8", "Shift_JIS");
 
   expect(out).toEqual(new Uint8Array([0x82, 0xa0]));
-  expect(iconvM.calls[0]?.method).toBe("convert");
+  expect(iconvM.convert).toHaveBeenCalledWith("あ", "UTF-8", "Shift_JIS");
 }); // iconvM disposed here — the iconv mock is removed (previous state restored)
 
 test("reads from a vault", async () => {
-  using sm = mockSecretmanager();
-  sm.setSecrets({ "my-vault": { API_KEY: "sk-123" } });
+  using sm = mockSecretmanager({ secrets: { "my-vault": { API_KEY: "sk-123" } } });
 
   await expect(secretmanager.getSecret("my-vault", "API_KEY")).resolves.toBe("sk-123");
 });

package/docs/services/aigateway.md

@@ -0,0 +1,115 @@
+# AI Gateway
+
+AI Gateway provides a unified endpoint for accessing a range of large language models through a single OpenAI-compatible API, with platform-managed credentials and workspace-scoped authentication.
+
+## Overview
+
+AI Gateway provides:
+
+- A unified, OpenAI-compatible endpoint for multiple LLM models
+- Mandatory authentication via your workspace's auth (request tokens are resolved against the configured auth namespace)
+- Per-workspace isolation: each gateway is provisioned with its own platform-assigned URL
+- Optional CORS allow-list for browser-based clients
+- Built-in usage tracking and rate limiting (configured platform-side)
+
+## Configuration
+
+Configure an AI Gateway using `defineAIGateway()`:
+
+**Definition Rules:**
+
+- **Multiple gateways allowed**: You can define multiple AI Gateways in your config file
+- **Configuration location**: Define in `tailor.config.ts` and add to the `aiGateways` array
+- **Uniqueness**: Gateway names must be unique across all AI Gateways
+- **Name pattern**: `name` must match `^[a-z0-9][a-z0-9-]{1,28}[a-z0-9]$` (lowercase alphanumeric and hyphens, 3-30 characters)
+
+```typescript
+import { defineAIGateway, defineConfig } from "@tailor-platform/sdk";
+
+const aiGateway = defineAIGateway("my-aigateway", {
+  authNamespace: "default",
+});
+
+export default defineConfig({
+  name: "my-app",
+  aiGateways: [aiGateway],
+});
+```
+
+## Options
+
+### authNamespace
+
+The auth namespace used to resolve request tokens against your workspace's auth configuration. Must match an existing auth namespace.
+
+```typescript
+defineAIGateway("my-aigateway", {
+  authNamespace: "default",
+});
+```
+
+### cors
+
+Optional list of allowed origins for browser-based clients. Each entry is one of:
+
+- `*` — any origin (any scheme, any host)
+- `http(s)://*` — any host on the given scheme
+- `http(s)://*.example.com` — any subdomain of `example.com` on the given scheme
+- `http(s)://app.example.com` — an exact origin
+
+An optional `:port` may be appended in all URL forms. Omitting `cors` (or passing `[]`) disables cross-origin access — browsers will block any cross-origin reads.
+
+```typescript
+defineAIGateway("my-aigateway", {
+  authNamespace: "default",
+  cors: ["https://app.example.com", "https://*.example.com"],
+});
+```
+
+## Complete Example
+
+```typescript
+import {
+  defineAIGateway,
+  defineAuth,
+  defineConfig,
+  defineStaticWebSite,
+} from "@tailor-platform/sdk";
+
+const website = defineStaticWebSite("my-frontend", {
+  description: "Frontend application",
+});
+
+const aiGateway = defineAIGateway("my-aigateway", {
+  // Name of an auth namespace in your workspace; request tokens are resolved against it.
+  authNamespace: "default",
+  cors: [website.url],
+});
+
+const auth = defineAuth("my-auth", {
+  // ...auth configuration...
+});
+
+export default defineConfig({
+  name: "my-app",
+  auth,
+  staticWebsites: [website],
+  aiGateways: [aiGateway],
+});
+```
+
+## Runtime Usage
+
+Resolvers, executors, and workflow jobs can resolve a gateway's platform-assigned URL by name via `aigateway.get()`. The name is type-checked and autocompleted against the AI Gateways defined in `aiGateways`:
+
+```typescript
+import { aigateway } from "@tailor-platform/sdk/runtime";
+
+const { url } = await aigateway.get("my-aigateway");
+
+// await aigateway.get("unknown"); // Type error — only "my-aigateway" is allowed
+```
+
+Type narrowing is provided by the generated `tailor.d.ts` (the `AIGatewayNameRegistry` interface). Run `tailor generate` (or `deploy`) after defining new AI Gateways to refresh it. Before the first generate run, `get()` accepts any string.
+
+The same URL is also shown by `tailor show`, which lists the URL of each AI Gateway defined in `aiGateways` once it has been deployed.