@tailor-platform/sdk 1.67.1 → 1.69.0

package/docs/cli/executor.md

@@ -2,30 +2,16 @@
 
 Commands for managing executors and executor jobs.
 
-<!-- politty:command:executor:heading:start -->
-
 ## executor
 
-<!-- politty:command:executor:heading:end -->
-
-<!-- politty:command:executor:description:start -->
-
 Manage executors
 
-<!-- politty:command:executor:description:end -->
-
-<!-- politty:command:executor:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk executor [command]
 ```
 
-<!-- politty:command:executor:usage:end -->
-
-<!-- politty:command:executor:subcommands:start -->
-
 **Commands**
 
 | Command                                 | Description                   |
@@ -36,38 +22,18 @@ tailor-sdk executor [command]
 | [`executor get`](#executor-get)         | Get executor details          |
 | [`executor webhook`](#executor-webhook) | Manage executor webhooks      |
 
-<!-- politty:command:executor:subcommands:end -->
-
-<!-- politty:command:executor:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:executor:global-options-link:end -->
-
-<!-- politty:command:executor list:heading:start -->
-
 ### executor list
 
-<!-- politty:command:executor list:heading:end -->
-
-<!-- politty:command:executor list:description:start -->
-
 List all executors
 
-<!-- politty:command:executor list:description:end -->
-
-<!-- politty:command:executor list:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk executor list [options]
 ```
 
-<!-- politty:command:executor list:usage:end -->
-
-<!-- politty:command:executor list:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                              | Required | Default  | Env                            |
@@ -77,48 +43,24 @@ tailor-sdk executor list [options]
 | `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
 | `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |
 
-<!-- politty:command:executor list:options:end -->
-
-<!-- politty:command:executor list:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:executor list:global-options-link:end -->
-
-<!-- politty:command:executor get:heading:start -->
-
 ### executor get
 
-<!-- politty:command:executor get:heading:end -->
-
-<!-- politty:command:executor get:description:start -->
-
 Get executor details
 
-<!-- politty:command:executor get:description:end -->
-
-<!-- politty:command:executor get:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk executor get [options] <name>
 ```
 
-<!-- politty:command:executor get:usage:end -->
-
-<!-- politty:command:executor get:arguments:start -->
-
 **Arguments**
 
 | Argument | Description   | Required |
 | -------- | ------------- | -------- |
 | `name`   | Executor name | Yes      |
 
-<!-- politty:command:executor get:arguments:end -->
-
-<!-- politty:command:executor get:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description       | Required | Default | Env                            |
@@ -126,38 +68,18 @@ tailor-sdk executor get [options] <name>
 | `--workspace-id <WORKSPACE_ID>` | `-w`  | Workspace ID      | No       | -       | `TAILOR_PLATFORM_WORKSPACE_ID` |
 | `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
 
-<!-- politty:command:executor get:options:end -->
-
-<!-- politty:command:executor get:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:executor get:global-options-link:end -->
-
-<!-- politty:command:executor jobs:heading:start -->
-
 ### executor jobs
 
-<!-- politty:command:executor jobs:heading:end -->
-
-<!-- politty:command:executor jobs:description:start -->
-
 List or get executor jobs.
 
-<!-- politty:command:executor jobs:description:end -->
-
-<!-- politty:command:executor jobs:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk executor jobs [options] <executor-name> [job-id]
 ```
 
-<!-- politty:command:executor jobs:usage:end -->
-
-<!-- politty:command:executor jobs:arguments:start -->
-
 **Arguments**
 
 | Argument        | Description                             | Required |
@@ -165,10 +87,6 @@ tailor-sdk executor jobs [options] <executor-name> [job-id]
 | `executor-name` | Executor name                           | Yes      |
 | `job-id`        | Job ID (if provided, shows job details) | No       |
 
-<!-- politty:command:executor jobs:arguments:end -->
-
-<!-- politty:command:executor jobs:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                                                                           | Required | Default  | Env                            |
@@ -179,13 +97,12 @@ tailor-sdk executor jobs [options] <executor-name> [job-id]
 | `--attempts`                    | -     | Show job attempts (only with job ID) (detail mode only)                                               | No       | `false`  | -                              |
 | `--wait`                        | `-W`  | Wait for job completion and downstream execution (workflow/function) if applicable (detail mode only) | No       | `false`  | -                              |
 | `--interval <INTERVAL>`         | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m')                                        | No       | `"3s"`   | -                              |
+| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait when using --wait (e.g., '30s', '5m')                                            | No       | `"5m"`   | -                              |
 | `--order <ORDER>`               | -     | Sort order (asc or desc)                                                                              | No       | `"desc"` | -                              |
 | `--limit <LIMIT>`               | -     | Maximum number of jobs to list (0: unlimited, default: 50) (list mode only)                           | No       | `50`     | -                              |
 | `--logs`                        | `-l`  | Display function execution logs after completion (requires --wait)                                    | No       | `false`  | -                              |
 
-<!-- politty:command:executor jobs:options:end -->
-
-<!-- politty:command:executor jobs:examples:start -->
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Examples**
 
@@ -231,48 +148,22 @@ $ tailor-sdk executor jobs my-executor <job-id> -W
 $ tailor-sdk executor jobs my-executor <job-id> -W -l
 ```
 
-<!-- politty:command:executor jobs:examples:end -->
-
-<!-- politty:command:executor jobs:global-options-link:start -->
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-<!-- politty:command:executor jobs:global-options-link:end -->
-
-<!-- politty:command:executor trigger:heading:start -->
-
 ### executor trigger
 
-<!-- politty:command:executor trigger:heading:end -->
-
-<!-- politty:command:executor trigger:description:start -->
-
 Trigger an executor manually.
 
-<!-- politty:command:executor trigger:description:end -->
-
-<!-- politty:command:executor trigger:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk executor trigger [options] <executor-name>
 ```
 
-<!-- politty:command:executor trigger:usage:end -->
-
-<!-- politty:command:executor trigger:arguments:start -->
-
 **Arguments**
 
 | Argument        | Description   | Required |
 | --------------- | ------------- | -------- |
 | `executor-name` | Executor name | Yes      |
 
-<!-- politty:command:executor trigger:arguments:end -->
-
-<!-- politty:command:executor trigger:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                                                        | Required | Default | Env                            |
@@ -283,12 +174,9 @@ tailor-sdk executor trigger [options] <executor-name>
 | `--header <HEADER>`             | `-H`  | Request header (format: 'Key: Value', can be specified multiple times)             | No       | -       | -                              |
 | `--wait`                        | `-W`  | Wait for job completion and downstream execution (workflow/function) if applicable | No       | `false` | -                              |
 | `--interval <INTERVAL>`         | `-i`  | Polling interval when using --wait (e.g., '3s', '500ms', '1m')                     | No       | `"3s"`  | -                              |
+| `--timeout <TIMEOUT>`           | `-t`  | Maximum time to wait when using --wait (e.g., '30s', '5m')                         | No       | `"5m"`  | -                              |
 | `--logs`                        | `-l`  | Display function execution logs after completion (requires --wait)                 | No       | `false` | -                              |
 
-<!-- politty:command:executor trigger:options:end -->
-
-<!-- politty:command:executor trigger:examples:start -->
-
 **Examples**
 
 **Trigger an executor**
@@ -321,9 +209,56 @@ $ tailor-sdk executor trigger my-executor -W
 $ tailor-sdk executor trigger my-executor -W -l
 ```
 
-<!-- politty:command:executor trigger:examples:end -->
+**Shell automation**
+
+Trigger an executor and wait for the executor job plus any downstream workflow or
+function execution:
+
+```bash
+tailor-sdk executor trigger daily-workflow \
+  --wait \
+  --timeout 5m \
+  --interval 5s \
+  --json
+```
 
-<!-- politty:command:executor trigger:notes:start -->
+Wait for an existing job when another process already captured the job ID:
+
+```bash
+tailor-sdk executor jobs daily-workflow "$job_id" \
+  --wait \
+  --timeout 5m \
+  --logs \
+  --json
+```
+
+**Programmatic API**
+
+Import your executor definition and pass it to the typed API:
+
+```ts
+import { triggerExecutor, watchExecutorJob } from "@tailor-platform/sdk/cli";
+import dailyWorkflow from "../executors/dailyWorkflow";
+
+const { jobId } = await triggerExecutor({
+  executor: dailyWorkflow,
+});
+
+if (!jobId) {
+  throw new Error("Executor trigger did not return a job ID");
+}
+
+const result = await watchExecutorJob({
+  executor: dailyWorkflow,
+  jobId,
+  timeout: 5 * 60 * 1000,
+  interval: 5000,
+});
+
+if (result.timedOut) {
+  throw new Error(`Executor job ${result.job.id} timed out at ${result.job.status}`);
+}
+```
 
 **Notes**
 
@@ -342,37 +277,19 @@ When using `--wait`, the CLI tracks not only the executor job but also any downs
 
 The `--logs` option displays logs from the downstream execution when available.
 
-<!-- politty:command:executor trigger:notes:end -->
-
-<!-- politty:command:executor trigger:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:executor trigger:global-options-link:end -->
-
-<!-- politty:command:executor webhook:heading:start -->
-
 ### executor webhook
 
-<!-- politty:command:executor webhook:heading:end -->
-
-<!-- politty:command:executor webhook:description:start -->
-
 Manage executor webhooks
 
-<!-- politty:command:executor webhook:description:end -->
-
-<!-- politty:command:executor webhook:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk executor webhook [command]
 ```
 
-<!-- politty:command:executor webhook:usage:end -->
-
-<!-- politty:command:executor webhook:subcommands:start -->
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Commands**
 
@@ -380,38 +297,16 @@ tailor-sdk executor webhook [command]
 | ------------------------------------------------- | --------------------------------------------- |
 | [`executor webhook list`](#executor-webhook-list) | List executors with incoming webhook triggers |
 
-<!-- politty:command:executor webhook:subcommands:end -->
-
-<!-- politty:command:executor webhook:global-options-link:start -->
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-<!-- politty:command:executor webhook:global-options-link:end -->
-
-<!-- politty:command:executor webhook list:heading:start -->
-
 #### executor webhook list
 
-<!-- politty:command:executor webhook list:heading:end -->
-
-<!-- politty:command:executor webhook list:description:start -->
-
 List executors with incoming webhook triggers
 
-<!-- politty:command:executor webhook list:description:end -->
-
-<!-- politty:command:executor webhook list:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk executor webhook list [options]
 ```
 
-<!-- politty:command:executor webhook list:usage:end -->
-
-<!-- politty:command:executor webhook list:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                              | Required | Default  | Env                            |
@@ -421,10 +316,4 @@ tailor-sdk executor webhook list [options]
 | `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
 | `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |
 
-<!-- politty:command:executor webhook list:options:end -->
-
-<!-- politty:command:executor webhook list:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-<!-- politty:command:executor webhook list:global-options-link:end -->

package/docs/cli/function.md

@@ -2,29 +2,17 @@
 
 Commands for managing function registries and viewing function execution logs.
 
-<!-- politty:command:function:heading:start -->
-
 ## function
 
-<!-- politty:command:function:heading:end -->
-
-<!-- politty:command:function:description:start -->
-
 Manage functions
 
-<!-- politty:command:function:description:end -->
-
-<!-- politty:command:function:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk function [command]
 ```
 
-<!-- politty:command:function:usage:end -->
-
-<!-- politty:command:function:subcommands:start -->
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Commands**
 
@@ -35,37 +23,16 @@ tailor-sdk function [command]
 | [`function logs`](#function-logs)         | List or get function execution logs.                            |
 | [`function test-run`](#function-test-run) | Run a function on the Tailor Platform server without deploying. |
 
-<!-- politty:command:function:subcommands:end -->
-
-<!-- politty:command:function:global-options-link:start -->
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-<!-- politty:command:function:global-options-link:end -->
-<!-- politty:command:function get:heading:start -->
-
 ### function get
 
-<!-- politty:command:function get:heading:end -->
-
-<!-- politty:command:function get:description:start -->
-
 Get a function registry by name
 
-<!-- politty:command:function get:description:end -->
-
-<!-- politty:command:function get:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk function get [options]
 ```
 
-<!-- politty:command:function get:usage:end -->
-
-<!-- politty:command:function get:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description       | Required | Default | Env                            |
@@ -74,37 +41,18 @@ tailor-sdk function get [options]
 | `--profile <PROFILE>`           | `-p`  | Workspace profile | No       | -       | `TAILOR_PLATFORM_PROFILE`      |
 | `--name <NAME>`                 | `-n`  | Function name     | Yes      | -       | -                              |
 
-<!-- politty:command:function get:options:end -->
-
-<!-- politty:command:function get:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:function get:global-options-link:end -->
-<!-- politty:command:function list:heading:start -->
-
 ### function list
 
-<!-- politty:command:function list:heading:end -->
-
-<!-- politty:command:function list:description:start -->
-
 List function registries in a workspace
 
-<!-- politty:command:function list:description:end -->
-
-<!-- politty:command:function list:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk function list [options]
 ```
 
-<!-- politty:command:function list:usage:end -->
-
-<!-- politty:command:function list:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                              | Required | Default  | Env                            |
@@ -114,48 +62,24 @@ tailor-sdk function list [options]
 | `--order <ORDER>`               | -     | Sort order (asc or desc)                                 | No       | `"desc"` | -                              |
 | `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0 or omit: unlimited) | No       | -        | -                              |
 
-<!-- politty:command:function list:options:end -->
-
-<!-- politty:command:function list:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:function list:global-options-link:end -->
-
-<!-- politty:command:function logs:heading:start -->
-
 ### function logs
 
-<!-- politty:command:function logs:heading:end -->
-
-<!-- politty:command:function logs:description:start -->
-
 List or get function execution logs.
 
-<!-- politty:command:function logs:description:end -->
-
-<!-- politty:command:function logs:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk function logs [options] [execution-id]
 ```
 
-<!-- politty:command:function logs:usage:end -->
-
-<!-- politty:command:function logs:arguments:start -->
-
 **Arguments**
 
 | Argument       | Description                                         | Required |
 | -------------- | --------------------------------------------------- | -------- |
 | `execution-id` | Execution ID (if provided, shows details with logs) | No       |
 
-<!-- politty:command:function logs:arguments:end -->
-
-<!-- politty:command:function logs:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                      | Required | Default  | Env                            |
@@ -165,16 +89,8 @@ tailor-sdk function logs [options] [execution-id]
 | `--order <ORDER>`               | -     | Sort order (asc or desc)                         | No       | `"desc"` | -                              |
 | `--limit <LIMIT>`               | `-l`  | Maximum number of items to return (0: unlimited) | No       | `50`     | -                              |
 
-<!-- politty:command:function logs:options:end -->
-
-<!-- politty:command:function logs:global-options-link:start -->
-
 See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
-<!-- politty:command:function logs:global-options-link:end -->
-
-<!-- politty:command:function logs:examples:start -->
-
 **Examples**
 
 **List all function execution logs**
@@ -201,48 +117,28 @@ $ tailor-sdk function logs --json
 $ tailor-sdk function logs <execution-id> --json
 ```
 
-<!-- politty:command:function logs:examples:end -->
-
-<!-- politty:command:function logs:notes:start -->
-
 **Notes**
 
 When viewing a specific execution that failed, the command displays error details with the stack trace mapped back to your original source files (clickable file links and code snippets, matching `function test-run` output).
 
 Stack traces stay accurate even after later redeploys, because the trace is resolved against the exact build that produced the execution. If that build is no longer available, the command falls back to a plain-text error display.
 
-<!-- politty:command:function logs:notes:end -->
-
-<!-- politty:command:function test-run:heading:start -->
-
 ### function test-run
 
-<!-- politty:command:function test-run:heading:end -->
-<!-- politty:command:function test-run:description:start -->
-
 Run a function on the Tailor Platform server without deploying.
 
-<!-- politty:command:function test-run:description:end -->
-<!-- politty:command:function test-run:usage:start -->
-
 **Usage**
 
 ```
 tailor-sdk function test-run [options] <file>
 ```
 
-<!-- politty:command:function test-run:usage:end -->
-<!-- politty:command:function test-run:arguments:start -->
-
 **Arguments**
 
 | Argument | Description               | Required |
 | -------- | ------------------------- | -------- |
 | `file`   | Path to the function file | Yes      |
 
-<!-- politty:command:function test-run:arguments:end -->
-<!-- politty:command:function test-run:options:start -->
-
 **Options**
 
 | Option                          | Alias | Description                                                                                    | Required | Default              | Env                                 |
@@ -254,8 +150,7 @@ tailor-sdk function test-run [options] <file>
 | `--machine-user <MACHINE_USER>` | `-m`  | Machine user name for authentication. Falls back to the active profile's default machine user. | No       | -                    | `TAILOR_PLATFORM_MACHINE_USER_NAME` |
 | `--config <CONFIG>`             | `-c`  | Path to SDK config file                                                                        | No       | `"tailor.config.ts"` | -                                   |
 
-<!-- politty:command:function test-run:options:end -->
-<!-- politty:command:function test-run:examples:start -->
+See [Global Options](../cli-reference.md#global-options) for options available to all commands.
 
 **Examples**
 
@@ -277,9 +172,6 @@ $ tailor-sdk function test-run workflows/sample.ts --name validate-order
 $ tailor-sdk function test-run build/resolvers/add.js --arg '{"a":1,"b":2}'
 ```
 
-<!-- politty:command:function test-run:examples:end -->
-<!-- politty:command:function test-run:notes:start -->
-
 **Notes**
 
 You can pass either a source file (`.ts`) or a pre-bundled file (`.js`).
@@ -288,11 +180,3 @@ When a `.js` file is provided, detection and bundling are skipped and the file i
 > [!WARNING]
 > Workflow job `.trigger()` calls do not work in test-run mode.
 > Triggered jobs are not executed; only the target job's `body` function runs in isolation.
-
-<!-- politty:command:function test-run:notes:end -->
-
-<!-- politty:command:function test-run:global-options-link:start -->
-
-See [Global Options](../cli-reference.md#global-options) for options available to all commands.
-
-<!-- politty:command:function test-run:global-options-link:end -->