@tailor-platform/sdk 0.16.3 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @tailor-platform/sdk
 
+## 0.17.0
+
+### Minor Changes
+
+- [#158](https://github.com/tailor-platform/sdk/pull/158) [`cde0a0a`](https://github.com/tailor-platform/sdk/commit/cde0a0a3e1d517e8036f799ce2a0b8958f7e18c4) Thanks [@riku99](https://github.com/riku99)! - CLI changes:
+  - Replace `--format` with `--json` for all list/detail commands. `--format` is no longer supported.
+  - Change default table layout for list output and humanize `createdAt` / `updatedAt` in table format (JSON remains ISO strings).
+  - `workspace list`: hide `updatedAt` in table output and add `--limit=<number>` to cap the number of workspaces shown.
+
+  **Breaking:** Scripts or tooling that relied on `--format` or the previous table layout may need to be updated.
+
+### Patch Changes
+
+- [#197](https://github.com/tailor-platform/sdk/pull/197) [`6c141f0`](https://github.com/tailor-platform/sdk/commit/6c141f0cf23d360f531dec2a39330b3fa755f7e1) Thanks [@toiroakr](https://github.com/toiroakr)! - Fix `tailordb truncate` command argument parsing: `-n` alias now works correctly and multiple type names can be specified as space-separated arguments
+
+- [#191](https://github.com/tailor-platform/sdk/pull/191) [`92f0e99`](https://github.com/tailor-platform/sdk/commit/92f0e99f0bbcdd4616b56157cd2b67a71757fb05) Thanks [@toiroakr](https://github.com/toiroakr)! - fix: createTailorDBHook for Date
+
 ## 0.16.3
 
 ### Patch Changes

package/README.md

@@ -1,13 +1,80 @@
 # Tailor Platform SDK
 
-The Tailor Platform SDK is a library for building applications on the Tailor Platform using TypeScript.
+`@tailor-platform/sdk` is a TypeScript SDK for building applications on the [Tailor Platform](https://docs.tailor.tech/).
 
-# Documentation
+## Overview
 
-You can also view the documentation on [our website](https://docs.tailor.tech/reference/tailor-sdk/quickstart).
+Tailor Platform is a headless business platform that provides backend services for building enterprise applications. The SDK enables you to:
 
-- [Quickstart](./docs/quickstart.md)
-- [App Configuration](./docs/configuration.md)
-- [Core Concepts](./docs/core-concepts.md)
-- [CLI Reference](./docs/cli-reference.md)
-- [Testing Guide](./docs/testing.md)
+- Define type-safe database schemas with TailorDB
+- Create custom GraphQL resolvers with business logic
+- Set up event-driven executors for automation
+- Orchestrate complex workflows with multiple jobs
+- Configure authentication and authorization
+
+All configurations are written in TypeScript, providing full type safety.
+
+### Important Notes
+
+Some SDK concepts differ from the native Tailor Platform. Be aware of these differences when referring to the official Tailor Platform documentation.
+
+#### Resolver
+
+The SDK's Resolver corresponds to Tailor Platform's [Pipeline Resolver](https://docs.tailor.tech/guides/pipeline). The key difference is that Pipeline steps are replaced with a single `body` function. See [Resolver](./docs/services/resolver.md) for details.
+
+## Installation
+
+```bash
+npm install @tailor-platform/sdk
+# OR
+yarn add @tailor-platform/sdk
+# OR
+pnpm add @tailor-platform/sdk
+```
+
+## Quick Start
+
+Create a new project using the CLI:
+
+```bash
+npm create @tailor-platform/sdk my-app --template hello-world
+cd my-app
+npm run deploy -- --workspace-id <your-workspace-id>
+```
+
+See [Available Templates](https://github.com/tailor-platform/sdk/tree/main/packages/create-sdk#available-templates) for more options.
+
+For more details, see the [Quickstart Guide](./docs/quickstart.md).
+
+## Learn More
+
+### Configuration
+
+- [Configuration](./docs/configuration.md) - Application and service configuration
+
+### Services
+
+| Service                                            | Description                                  |
+| -------------------------------------------------- | -------------------------------------------- |
+| [TailorDB](./docs/services/tailordb.md)            | Type-safe database schema definition         |
+| [Resolver](./docs/services/resolver.md)            | Custom GraphQL resolvers with business logic |
+| [Executor](./docs/services/executor.md)            | Event-driven handlers for automation         |
+| [Workflow](./docs/services/workflow.md)            | Job orchestration for complex operations     |
+| [Auth](./docs/services/auth.md)                    | Authentication and authorization             |
+| [IdP](./docs/services/idp.md)                      | Built-in identity provider                   |
+| [Static Website](./docs/services/staticwebsite.md) | Static file hosting                          |
+| [Secret Manager](./docs/services/secret.md)        | Secure credential storage                    |
+
+### Guides
+
+- [Testing Guide](./docs/testing.md) - Unit and E2E testing patterns
+- [CLI Reference](./docs/cli-reference.md) - Command-line interface documentation
+
+### Templates
+
+See [Create Tailor Platform SDK](https://github.com/tailor-platform/sdk/tree/main/packages/create-sdk) for available project templates.
+
+## Requirements
+
+- Node.js 22 or later
+- A Tailor Platform account ([request access](https://www.tailor.tech/demo))

package/dist/cli/api.d.mts

@@ -124,6 +124,7 @@ interface CodeGenerator<T = any, R = any, E = any, Ts = any, Rs = any> extends O
     input: GeneratorInput<Ts, Rs>;
     executorInputs: E[];
     baseDir: string;
+    configPath: string;
   }): GeneratorResult | Promise<GeneratorResult>;
 }
 //#endregion
@@ -193,7 +194,10 @@ interface WorkspaceCreateOptions {
 declare function workspaceCreate(options: WorkspaceCreateOptions): Promise<WorkspaceInfo>;
 //#endregion
 //#region src/cli/workspace/list.d.ts
-declare function workspaceList(): Promise<WorkspaceInfo[]>;
+interface WorkspaceListOptions {
+  limit?: number;
+}
+declare function workspaceList(options?: WorkspaceListOptions): Promise<WorkspaceInfo[]>;
 //#endregion
 //#region src/cli/workspace/delete.d.ts
 interface WorkspaceDeleteOptions {

package/dist/cli/api.mjs

@@ -1,4 +1,4 @@
-import { apply, generate, generateUserTypes, loadAccessToken, loadConfig, loadWorkspaceId, machineUserList, machineUserToken, oauth2ClientGet, oauth2ClientList, remove, show, workflowExecutionGet, workflowExecutionsList, workflowGet, workflowList, workflowResume, workflowStart, workspaceCreate, workspaceDelete, workspaceList } from "../resume-kyHIaNvK.mjs";
+import { apply, generate, generateUserTypes, loadAccessToken, loadConfig, loadWorkspaceId, machineUserList, machineUserToken, oauth2ClientGet, oauth2ClientList, remove, show, workflowExecutionGet, workflowExecutionsList, workflowGet, workflowList, workflowResume, workflowStart, workspaceCreate, workspaceDelete, workspaceList } from "../resume-B2ba5opn.mjs";
 import "../job-CL8myeqs.mjs";
 import { register } from "node:module";
 

package/dist/cli/index.mjs

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
-import { PATScope, applyCommand, commonArgs, createCommand, deleteCommand, executionsCommand, fetchAll, fetchLatestToken, fetchUserInfo, formatArgs, generateCommand, getCommand, getCommand$1, initOAuth2Client, initOperatorClient, listCommand as listCommand$1, listCommand$1 as listCommand$6, listCommand$2 as listCommand$7, listCommand$3 as listCommand, loadAccessToken, loadConfig, loadWorkspaceId, parseFormat, printWithFormat, readPackageJson, readPlatformConfig, removeCommand, resumeCommand, showCommand, startCommand, tokenCommand, withCommonArgs, writePlatformConfig } from "../resume-kyHIaNvK.mjs";
+import { PATScope, applyCommand, commonArgs, createCommand, deleteCommand, executionsCommand, fetchAll, fetchLatestToken, fetchUserInfo, generateCommand, getCommand, getCommand$1, initOAuth2Client, initOperatorClient, jsonArgs, listCommand as listCommand$1, listCommand$1 as listCommand$6, listCommand$2 as listCommand$7, listCommand$3 as listCommand, loadAccessToken, loadConfig, loadWorkspaceId, printData, readPackageJson, readPlatformConfig, removeCommand, resumeCommand, showCommand, startCommand, tokenCommand, withCommonArgs, writePlatformConfig } from "../resume-B2ba5opn.mjs";
 import "../job-CL8myeqs.mjs";
 import { register } from "node:module";
 import { defineCommand, runCommand, runMain } from "citty";
-import { z } from "zod";
 import * as crypto from "node:crypto";
 import ml from "multiline-ts";
 import { consola as consola$1 } from "consola";
@@ -218,7 +217,7 @@ const createCommand$3 = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...formatArgs,
+		...jsonArgs,
 		name: {
 			type: "positional",
 			description: "Profile name",
@@ -238,7 +237,6 @@ const createCommand$3 = defineCommand({
 		}
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parseFormat(args.format);
 		const config = readPlatformConfig();
 		if (config.profiles[args.name]) throw new Error(`Profile "${args.name}" already exists.`);
 		const token = await fetchLatestToken(config, args.user);
@@ -252,13 +250,13 @@ const createCommand$3 = defineCommand({
 			workspace_id: args["workspace-id"]
 		};
 		writePlatformConfig(config);
-		if (format === "table") consola$1.success(`Profile "${args.name}" created successfully.`);
+		if (!args.json) consola$1.success(`Profile "${args.name}" created successfully.`);
 		const profileInfo = {
 			name: args.name,
 			user: args.user,
 			workspaceId: args["workspace-id"]
 		};
-		printWithFormat(profileInfo, format);
+		printData(profileInfo, args.json);
 	})
 });
 
@@ -295,10 +293,9 @@ const listCommand$5 = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...formatArgs
+		...jsonArgs
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parseFormat(args.format);
 		const config = readPlatformConfig();
 		const profiles = Object.entries(config.profiles);
 		if (profiles.length === 0) {
@@ -313,7 +310,7 @@ const listCommand$5 = defineCommand({
 			user: profile.user,
 			workspaceId: profile.workspace_id
 		}));
-		printWithFormat(profileInfos, format);
+		printData(profileInfos, args.json);
 	})
 });
 
@@ -326,7 +323,7 @@ const updateCommand$1 = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...formatArgs,
+		...jsonArgs,
 		name: {
 			type: "positional",
 			description: "Profile name",
@@ -344,7 +341,6 @@ const updateCommand$1 = defineCommand({
 		}
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parseFormat(args.format);
 		const config = readPlatformConfig();
 		if (!config.profiles[args.name]) throw new Error(`Profile "${args.name}" not found.`);
 		if (!args.user && !args["workspace-id"]) throw new Error("Please provide at least one property to update.");
@@ -362,13 +358,13 @@ const updateCommand$1 = defineCommand({
 		profile.user = newUser;
 		profile.workspace_id = newWorkspaceId;
 		writePlatformConfig(config);
-		if (format === "table") consola$1.success(`Profile "${args.name}" updated successfully`);
+		if (!args.json) consola$1.success(`Profile "${args.name}" updated successfully`);
 		const profileInfo = {
 			name: args.name,
 			user: newUser,
 			workspaceId: newWorkspaceId
 		};
-		printWithFormat(profileInfo, format);
+		printData(profileInfo, args.json);
 	})
 });
 
@@ -554,7 +550,7 @@ const listSecretCommand = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...formatArgs,
+		...jsonArgs,
 		"workspace-id": {
 			type: "string",
 			description: "Workspace ID",
@@ -572,14 +568,13 @@ const listSecretCommand = defineCommand({
 		}
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parseFormat(args.format);
 		try {
 			const secrets = await secretList({
 				workspaceId: args["workspace-id"],
 				profile: args.profile,
 				vaultName: args["vault-name"]
 			});
-			printWithFormat(secrets, format);
+			printData(secrets, args.json);
 		} catch (error) {
 			if (error instanceof ConnectError && error.code === Code.NotFound) throw new Error(`Vault "${args["vault-name"]}" not found.`);
 			throw error;
@@ -789,7 +784,7 @@ const listCommand$4 = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...formatArgs,
+		...jsonArgs,
 		"workspace-id": {
 			type: "string",
 			description: "Workspace ID",
@@ -802,12 +797,11 @@ const listCommand$4 = defineCommand({
 		}
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parseFormat(args.format);
 		const vaults = await vaultList({
 			workspaceId: args["workspace-id"],
 			profile: args.profile
 		});
-		printWithFormat(vaults, format);
+		printData(vaults, args.json);
 	})
 });
 
@@ -896,12 +890,13 @@ async function truncate(options) {
 	const hasTypes = options?.types && options.types.length > 0;
 	const hasNamespace = !!options?.namespace;
 	const hasAll = !!options?.all;
-	if ([
-		hasTypes,
+	const optionCount = [
+		hasAll,
 		hasNamespace,
-		hasAll
-	].filter(Boolean).length > 1) throw new Error("Cannot specify multiple options: choose one of --all, --namespace, or type names");
-	if (!hasTypes && !hasNamespace && !hasAll) throw new Error("Please specify one of: --all, --namespace <name>, or type names");
+		hasTypes
+	].filter(Boolean).length;
+	if (optionCount === 0) throw new Error("Please specify one of: --all, --namespace <name>, or type names");
+	if (optionCount > 1) throw new Error("Options --all, --namespace, and type names are mutually exclusive. Please specify only one.");
 	const namespaces = await getAllNamespaces(options?.configPath);
 	if (hasAll) {
 		if (namespaces.length === 0) {
@@ -977,7 +972,7 @@ const truncateCommand = defineCommand({
 		...commonArgs,
 		types: {
 			type: "positional",
-			description: "Type names to truncate (space-separated)",
+			description: "Type names to truncate",
 			required: false
 		},
 		all: {
@@ -988,7 +983,7 @@ const truncateCommand = defineCommand({
 		},
 		namespace: {
 			type: "string",
-			description: "Truncate all tables in specified namespace",
+			description: "Namespace to use (if type names are specified, truncates only those types in this namespace)",
 			alias: "n"
 		},
 		yes: {
@@ -1015,13 +1010,14 @@ const truncateCommand = defineCommand({
 		}
 	},
 	run: withCommonArgs(async (args) => {
+		const types = args._.length > 0 ? args._.map((arg) => String(arg)).filter(Boolean) : void 0;
 		await truncate({
 			workspaceId: args["workspace-id"],
 			profile: args.profile,
 			configPath: args.config,
 			all: args.all,
 			namespace: args.namespace,
-			types: args.types ? args.types.split(/\s+/).filter(Boolean) : void 0,
+			types,
 			yes: args.yes
 		});
 	})
@@ -1071,10 +1067,9 @@ const listCommand$2 = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...formatArgs
+		...jsonArgs
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parseFormat(args.format);
 		const config = readPlatformConfig();
 		const users = Object.keys(config.users);
 		if (users.length === 0) {
@@ -1084,35 +1079,19 @@ const listCommand$2 = defineCommand({
       `);
 			return;
 		}
-		switch (format) {
-			case "table":
-				users.forEach((user) => {
-					if (user === config.current_user) console.log(chalk.green.bold(`${user} (current)`));
-					else console.log(user);
-				});
-				break;
-			case "json":
-				console.log(JSON.stringify(users));
-				break;
-			default: throw new Error(`Format "${format}" is invalid.`);
+		if (args.json) {
+			console.log(JSON.stringify(users));
+			return;
 		}
+		users.forEach((user) => {
+			if (user === config.current_user) console.log(chalk.green.bold(`${user} (current)`));
+			else console.log(user);
+		});
 	})
 });
 
 //#endregion
 //#region src/cli/user/pat/transform.ts
-const patFormatSchema = z.enum(["text", "json"]);
-const patFormatArgs = { format: {
-	type: "string",
-	description: `Output format (${patFormatSchema.options.join(", ")})`,
-	alias: "f",
-	default: "text"
-} };
-function parsePATFormat(format) {
-	const parsed = patFormatSchema.safeParse(format);
-	if (!parsed.success) throw new Error(`Format "${format}" is invalid. Must be one of: ${patFormatSchema.options.join(", ")}`);
-	return parsed.data;
-}
 function patScopeToString(scope) {
 	switch (scope) {
 		case PATScope.PAT_SCOPE_READ: return "read";
@@ -1132,9 +1111,14 @@ function getScopesFromWriteFlag(write) {
 function getScopeStringsFromWriteFlag(write) {
 	return write ? ["read", "write"] : ["read"];
 }
-function printCreatedToken(name, token, write, format, action) {
+function printCreatedToken(name, token, write, action, json) {
 	const scopes = getScopeStringsFromWriteFlag(write);
-	if (format === "text") console.log(ml`
+	if (json) console.log(JSON.stringify({
+		name,
+		scopes,
+		token
+	}));
+	else console.log(ml`
       Personal access token ${action} successfully.
 
         name: ${name}
@@ -1143,11 +1127,6 @@ function printCreatedToken(name, token, write, format, action) {
 
       Please save this token in a secure location. You won't be able to see it again.
     `);
-	else console.log(JSON.stringify({
-		name,
-		scopes,
-		token
-	}));
 }
 
 //#endregion
@@ -1159,7 +1138,7 @@ const createCommand$1 = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...patFormatArgs,
+		...jsonArgs,
 		name: {
 			type: "positional",
 			description: "Token name",
@@ -1173,7 +1152,6 @@ const createCommand$1 = defineCommand({
 		}
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parsePATFormat(args.format);
 		const config = readPlatformConfig();
 		if (!config.current_user) throw new Error(ml`
         No user logged in.
@@ -1187,7 +1165,7 @@ const createCommand$1 = defineCommand({
 			scopes
 		});
 		if (!result.accessToken) throw new Error("Failed to create personal access token");
-		printCreatedToken(args.name, result.accessToken, args.write, format, "created");
+		printCreatedToken(args.name, result.accessToken, args.write, "created", args.json);
 	})
 });
 
@@ -1227,10 +1205,9 @@ const listCommand$3 = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...patFormatArgs
+		...jsonArgs
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parsePATFormat(args.format);
 		const config = readPlatformConfig();
 		if (!config.current_user) throw new Error(ml`
         No user logged in.
@@ -1249,17 +1226,17 @@ const listCommand$3 = defineCommand({
       `);
 			return;
 		}
-		if (format === "text") {
-			const maxNameLength = Math.max(...pats.map((pat) => pat.name.length));
-			pats.forEach((pat) => {
-				const info = transformPersonalAccessToken(pat);
-				const paddedName = info.name.padStart(maxNameLength);
-				console.log(`${paddedName}: ${info.scopes.join("/")}`);
-			});
-		} else {
+		if (args.json) {
 			const patInfos = pats.map(transformPersonalAccessToken);
 			console.log(JSON.stringify(patInfos));
+			return;
 		}
+		const maxNameLength = Math.max(...pats.map((pat) => pat.name.length));
+		pats.forEach((pat) => {
+			const info = transformPersonalAccessToken(pat);
+			const paddedName = info.name.padStart(maxNameLength);
+			console.log(`${paddedName}: ${info.scopes.join("/")}`);
+		});
 	})
 });
 
@@ -1272,7 +1249,7 @@ const updateCommand = defineCommand({
 	},
 	args: {
 		...commonArgs,
-		...patFormatArgs,
+		...jsonArgs,
 		name: {
 			type: "positional",
 			description: "Token name",
@@ -1286,7 +1263,6 @@ const updateCommand = defineCommand({
 		}
 	},
 	run: withCommonArgs(async (args) => {
-		const format = parsePATFormat(args.format);
 		const config = readPlatformConfig();
 		if (!config.current_user) throw new Error(ml`
         No user logged in.
@@ -1301,7 +1277,7 @@ const updateCommand = defineCommand({
 			scopes
 		});
 		if (!result.accessToken) throw new Error("Failed to create personal access token");
-		printCreatedToken(args.name, result.accessToken, args.write, format, "updated");
+		printCreatedToken(args.name, result.accessToken, args.write, "updated", args.json);
 	})
 });