cliodot 1.0.0 → 1.2.0

package/README.md

@@ -79,7 +79,8 @@ Pass a `body` (or plain object) as the trigger; the engine treats it as `trigger
 | Field | Description |
 |-------|-------------|
 | `body` / `data` | Request body; use `v.body('account')`, `v.body('email')` |
-| `headers` | HTTP headers (`v.header('x-api-key')`) |
+| `headers` | Simulated HTTP headers for the run (`v.header('x-api-key')`); merged with `executionHeaders` (see below) |
+| `executionHeaders` | Extra headers merged after `headers` (same sanitization); useful to separate trigger data from auth headers |
 | `pathParams` | Route params (`v.pathParam('id')`) |
 | `params` | Extra params (`v.param('page')`) |
 | `query` | Query string params (`v.query('filter')`) |
@@ -91,6 +92,32 @@ flosync.run('my-workflow', { body: { id: 1 } });
 flosync.run('my-workflow', { body: { id: 1 }, headers: { 'x-request-id': 'abc' }, pathParams: { id: '123' }, query: { page: 1 } });
 ```
 
+### Execution headers (local and remote)
+
+Workflow steps read `state.headers` (for example `v.header('authorization')`). You control what appears there via the run payload and, for remote runs, the client options below.
+
+Local runs (`flosync.run` with a registered workflow): `headers` and `executionHeaders` on the payload are merged (after sanitization) into `state.headers`. You can also pass `executionHeaders` as the third argument to `flosync.run`, which merges on top of the payload.
+
+```javascript
+await flosync.run('my-workflow', { body: { id: 1 }, headers: { 'x-request-id': 'a' } }, {
+  executionHeaders: { authorization: `Bearer ${integrationToken}` },
+});
+```
+
+Remote runs (`flosync.run` / `flosync.runById` with `apiKey` and `apiSecret`, or `FlosyncClient`): the SDK sends its own `Authorization` header to the Cliodot API (session JWT). That value is not copied into the workflow `state.headers`, since it is not the same credential your integration steps expect.
+
+To give the server workflow the bearer or other headers it was designed for, pass them explicitly:
+
+- In the payload: `headers` or `executionHeaders` on the object you pass to `run` / `runById` (both are merged into the test payload the API receives).
+- On the client: `client.workflows.run(groupId, triggerId, { payload, executionHeaders })` — `executionHeaders` is sent in the JSON body and merged last on the server.
+- Webhook test: `client.workflows.runByWebhook(path, method, { body, executionHeaders })`.
+
+Merge order on the server is: sanitized real incoming HTTP headers (transport), then `payload.headers`, then `executionHeaders` from the body. Later keys win. Cookies, hop-by-hop headers, `sec-*`, `proxy-*`, and `proxy-authorization` are dropped from user-supplied maps. `authorization` is allowed in `headers` / `executionHeaders` so you can supply an integration bearer; it is still stripped from the raw request line so the Cliodot session token does not overwrite your value.
+
+`sanitizeExecutionHeaders` is exported if you want to preview what will be sent; the same rules apply on the server.
+
+Public webhooks (unauthenticated URL): the server does not apply an `executionHeaders` field from the JSON body for merging. Use normal request headers or put values in the webhook payload and map them in the workflow.
+
 ## Configuration
 
 ```javascript
@@ -99,6 +126,7 @@ flosync.configure({
   apiSecret: process.env.FLOSYNC_API_SECRET,
   baseUrl: 'http://localhost:8080' //optional,
   projectId: process.env.FLOSYNC_PROJECT_ID,
+  debug: false, // Enable to include stepResults in every response
   connectors: {
     'mongodb.system': { uri: process.env.MONGO_URI, database: 'myapp' },
     'mysql.system': { uri: process.env.MYSQL_URI },
@@ -156,10 +184,46 @@ s.validator({ amount: v.body('amount'), email: v.body('email') });
 s.transform({ total: v.stepResult('calculate', 'total'), id: v.stepResult('charge', 'id') });
 ```
 
+### Typed `stepResult` paths (`defineStepVars`)
+
+`v.stepResult(stepId, ...pathParts)` treats every segment as a plain `string`, so your editor cannot suggest valid fields from a connector response or from another step’s output.
+
+Use **`defineStepVars`** to describe, once per workflow file, a map from **step id** (the decorated **method name**) to that step’s **result type**. The returned **`stepResult`** then constrains the first argument to those keys and each following argument to the next key along a valid path into that type (nested objects supported up to a fixed depth). Import **`ConnectorResponse`** (and your **`defineTypedConnector`** value) so connector steps reuse the same response shape you already declared for typing.
+
+```typescript
+import { defineStepVars, v, defineTypedConnector } from "cliodot";
+import type { ConnectorResponse } from "cliodot";
+
+const Api = defineTypedConnector("my-api", { pay: "pay" }, {
+  pay: {
+    body: {} as { amount: number },
+    response: { status: "", data: { id: "", link: "" } },
+  },
+});
+
+const steps = defineStepVars<{
+  pay: ConnectorResponse<typeof Api, "pay">;
+  validate: { errors?: Record<string, unknown> };
+}>();
+
+steps.stepResult("pay", "data", "link");
+steps.stepResult("validate", "errors");
+```
+
+The type **`StepKeyPath<T>`** is exported if you want to reuse the path-tuple logic elsewhere. Plain **`v.stepResult`** remains available for ad hoc strings and for code that does not need completions.
+
+### Class decorators (`buildWorkflowFromClass`)
+
+For `@Connector`, you can target a connector that exists only on Flowsync in three ways: pass the published connector id and action as strings (`@Connector('my-connector', 'charge', { installation_id: '...', connector_version: '1.2.0' })`); use `defineCustomConnector` / `defineCustomConnectorFromList` with that same id; or use `defineRemoteConnectorRef('my-connector', { pay: 'charge' })` and `@Connector(MyRef, 'pay', config)` for a clearer name. With `apiKey` and `apiSecret` set, the local runner loads REST definitions through `client.connectors.get` and respects `connector_version` on the step when fetching.
+
+**`@CallWorkflow` by webhook path** — Use `@CallWorkflow({ webhookPath: '/orders', webhookMethod: 'POST' }, payload)` where `webhookPath` and `webhookMethod` match the child workflow’s HTTP trigger (same values as `@Http('POST', '/orders')` on that workflow). You do **not** pass a workflow group id for this mode: the platform finds the child by path and method for the tenant. When the local runner calls Flowsync with `apiKey` / `apiSecret`, it uses **`POST /workflows/test/webhook`** with a JSON body `{ webhookPath, webhookMethod, payload, ... }` (`client.workflows.runByWebhook`). On the server, `call_workflow` resolves the child the same way as a real webhook (including route patterns) and merges path params into the child’s `pathParams`. The second decorator argument is the child payload; optional fields on that object include `environment` (`dev` / `prod`), `executionHeaders`, and `remote: true` to skip the in-memory registry and always hit the API. `webhookPath` / `webhookMethod` may be templated with `{{ }}` and are rendered before lookup.
+
+**`@CallWorkflow` by group id** — `@CallWorkflow('my-group-id', payload)` runs the child via **`POST /workflows/:groupId/test/trigger/:triggerId`** (see `client.workflows.run`). Use this when you target a specific group and trigger explicitly. You can combine `workflow_id` with a webhook path in the serialized step only when you need both; the path-only flow above stays independent of group ids.
+
 ### Step Types
 
-- `connector(id, action, config)` - REST/API call
-- `db(engine, action, config)` - MongoDB, MySQL, PostgreSQL, or Redis
+- `connector(id, action, config)` - REST/API call (optional `connector_version` in `config` for versioned tenant connectors when syncing workflows to Flowsync)
+- `db(engine, action, config)` - MongoDB, MySQL, PostgreSQL, or Redis (optional `connector_version` when relevant)
 - `validator(fields)` - Validate input
 - `condition(expr)` - Branch on expression (use `.then()` and `.else()`)
 - `transform(mapping)` - Map or transform data
@@ -235,15 +299,190 @@ The overridden output becomes the value of `v.stepResult("<stepId>")` for subseq
 
 In `stage: "post"`, `ctx.input` is the decorated step output produced by the connector/function call.
 
-Example: list todos using decorators
+#### `stage: "post"` in depth
+
+`post` is the hook that runs **after** the decorated step’s primary work finishes. For `@Connector`, `@Db`, and other steps that call out to a runtime implementation, the sequence is: resolve inputs → run the connector or database action (or built-in executor) → take the returned payload as the step output → **then** run your method body with `ctx.input` set to that output. Anything you return as `{ out }` replaces what gets stored in `stepResults` for that step id, so the rest of the workflow sees your transformed value. Use `setVars` in the same return value to publish workflow variables without changing the step output. Failures and HTTP error handling still apply to the primary step; the post hook is for normalization (mapping provider DTOs to your domain shape), redacting fields, enriching derived properties, or turning awkward API responses into a stable contract for later steps and responders. `@Step` defaults to `stage: "post"` so standalone code steps behave like “compute output from prior context” without injecting an extra predecessor code step.
+
+### `WorkflowContext<TInput, TSteps, TVars>`
+
+Instead of using `ctx: any`, you can type the context object passed to step methods. Import `WorkflowContext` from `cliodot`:
+
+```typescript
+import type { WorkflowContext } from "cliodot";
+```
+
+`WorkflowContext` is generic with three optional type parameters:
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `TInput` | `Record<string, any>` | Shape of `ctx.input` (previous step output or trigger data) |
+| `TSteps` | `Record<string, any>` | Shape of `ctx.steps` (accumulated step results) |
+| `TVars` | `Record<string, any>` | Shape of `ctx.vars` (workflow-level variables) |
+
+The full context object includes:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `input` | `TInput` | Input data for this step |
+| `trigger` | `any` | Raw trigger payload |
+| `steps` | `TSteps` | All step results keyed by step ID |
+| `vars` | `TVars` | Workflow variables (read/write via `setVars`) |
+| `headers` | `Record<string, string>` | HTTP headers from the request |
+| `params` | `Record<string, any>` | Merged query + route params |
+| `pathParams` | `Record<string, any>` | URL path parameters |
+| `query` | `Record<string, any>` | Query string parameters |
+| `body` | `any` | Raw request body |
+| `env` | `Record<string, string>` | Environment variables |
+
+The interface also has an index signature (`[key: string]: any`) so users can attach custom properties.
+
+### `StepOutput<T>`
+
+The return type for step methods that produce output. Import from `cliodot`:
+
+```typescript
+import type { StepOutput } from "cliodot";
+```
+
+```typescript
+export interface StepOutput<T = any> {
+  /** The output payload — stored in stepResults[stepId] */
+  out: T;
+  /** Optional: update workflow variables */
+  setVars?: Record<string, any>;
+}
+```
+
+Usage:
+
+```typescript
+@Connector(MyStore.id, MyStore.actions.list, {}, { order: 0, stage: "post" })
+list(ctx: WorkflowContext<{ items: Item[] }>): StepOutput<{ sorted: Item[] }> {
+  const sorted = [...ctx.input.items].sort((a, b) => a.id - b.id);
+  return { out: { sorted } };
+}
+```
+
+> **Note:** `StepOutput` is different from the `StepResult` exported by `WorkflowBuilder` (which is the builder-pattern return type with `.then()` / `.else()` chaining). Use `StepOutput` for decorator workflow method return types.
+
+### `@Step` — Custom Step Decorator
+
+`@Step` is a generic decorator for writing custom workflow step logic without needing to pair it with a connector, database, or other built-in step type. The method body is extracted at build time and executed as a code step with access to the full `WorkflowContext`.
+
+```typescript
+import { Workflow, Http, Step, Responder, buildWorkflowFromClass, v } from "cliodot";
+import type { WorkflowContext, StepOutput } from "cliodot";
+```
+
+**Options** (same as other step decorators):
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `id` | `string` | method name | Custom step ID |
+| `order` | `number` | auto | Execution order |
+| `stage` | `"pre" \| "post"` | `"post"` | When the method body runs |
+| `then` | `string` | — | Step ID to jump to on success |
+| `else` | `string` | — | Step ID to jump to on failure |
+
+**Basic example:**
+
+```typescript
+@Workflow("greet-user", "Greet User")
+@Http("POST", "/greet")
+class GreetWorkflow {
+  @Step({ order: 0 })
+  greet(ctx: WorkflowContext<{ name: string }>): StepOutput<{ greeting: string }> {
+    const name = ctx.input.name || "World";
+    return { out: { greeting: `Hello, ${name}!` } };
+  }
+
+  @Responder("json", { body: { message: v.stepResult("greet", "greeting") } }, { order: 1 })
+  respond() {}
+}
+
+export const greetWorkflow = buildWorkflowFromClass(GreetWorkflow);
+```
+
+**With `setVars` and branching:**
+
+```typescript
+@Workflow("process-order", "Process Order")
+@Http("POST", "/orders/process")
+class ProcessOrderWorkflow {
+  @Step({ order: 0, then: "finalize", else: "reject" })
+  validate(ctx: WorkflowContext<{ amount: number; currency: string }>): StepOutput<{ valid: boolean }> {
+    const { amount, currency } = ctx.input;
+    const valid = amount > 0 && ["USD", "EUR", "GBP"].includes(currency);
+    return {
+      out: { valid },
+      setVars: { processedAt: new Date().toISOString() },
+    };
+  }
+
+  @Responder("json", { body: { ok: true, processedAt: v.vars("processedAt") } }, { order: 1 })
+  finalize() {}
+
+  @Responder("json", { statusCode: 400, body: { ok: false, error: "Invalid order" } }, { order: 2 })
+  reject() {}
+}
+```
+
+**Combining `@Step` with other decorators:**
+
+`@Step` can be freely combined with `@Connector`, `@Db`, `@Condition`, `@Responder`, etc. in the same workflow class:
+
+```typescript
+@Workflow("mixed-workflow", "Mixed Workflow")
+@Http("POST", "/mixed")
+class MixedWorkflow {
+  @Step({ order: 0 })
+  prepare(ctx: WorkflowContext<{ email: string }>): StepOutput<{ normalized: string }> {
+    return { out: { normalized: ctx.input.email.toLowerCase().trim() } };
+  }
+
+  @Db("mongodb", "findOne", { collection: "users", query: { email: v.stepResult("prepare", "normalized") } }, { order: 1 })
+  findUser() {}
+
+  @Condition(v.expr("stepResults.findUser != null"), { then: "found", else: "notFound", order: 2 })
+  check() {}
+
+  @Responder("json", { body: { user: v.stepResult("findUser") } }, { order: 3 })
+  found() {}
+
+  @Responder("json", { statusCode: 404, body: { error: "User not found" } }, { order: 4 })
+  notFound() {}
+}
+```
+
+### Decorator example: list todos with typed context
 
 ```typescript
 import { flosync, v, Workflow, Http, Connector, Condition, Responder, buildWorkflowFromClass, defineCustomConnector } from "cliodot";
+import type { WorkflowContext, StepOutput } from "cliodot";
 
 const CarrierStore = defineCustomConnector("carrier.store", {
   listTodos: "listTodos",
 });
 
+interface TodoItem {
+  title?: string;
+  completed?: boolean;
+  createdAt?: string;
+  [key: string]: any;
+}
+
+interface ListInput {
+  todos?: TodoItem[];
+  [key: string]: any;
+}
+
+interface ListOutput {
+  todos: Array<TodoItem & { title_upper: string; completed_label: string }>;
+  completedTodos: TodoItem[];
+  pendingTodos: TodoItem[];
+  stats: { total: number; completed: number; pending: number };
+}
+
 @Workflow("todos-list-decorators", "Todos List (Decorators)")
 @Http("GET", "/todos")
 class TodosListDecoratorsWorkflow {
@@ -253,13 +492,38 @@ class TodosListDecoratorsWorkflow {
     { params: { limit: 10 } },
     { order: 0, stage: "post" }
   )
-  list(ctx: any) {
-    const todos = Array.isArray(ctx?.input?.todos) ? ctx.input.todos : [];
-    const formatted = todos.map((t: any) => {
+  list(ctx: WorkflowContext<ListInput>): StepOutput<ListOutput> {
+    const input = ctx?.input ?? {};
+    const todos = Array.isArray(input.todos) ? input.todos : [];
+    const sorted = [...todos].sort((a, b) =>
+      new Date(b?.createdAt ?? 0).getTime() - new Date(a?.createdAt ?? 0).getTime()
+    );
+    const completedTodos = sorted.filter((t) => Boolean(t?.completed));
+    const pendingTodos = sorted.filter((t) => !Boolean(t?.completed));
+
+    const decoratedTodos = sorted.map((t) => {
       const title = String(t?.title ?? "").trim();
-      return { ...t, title, title_upper: title.toUpperCase() };
+      return {
+        ...t,
+        title,
+        title_upper: title.toUpperCase(),
+        completed_label: t?.completed ? "done" as const : "todo" as const,
+      };
     });
-    return { out: { ...(ctx?.input ?? {}), todos: formatted } };
+
+    return {
+      out: {
+        ...input,
+        todos: decoratedTodos,
+        completedTodos,
+        pendingTodos,
+        stats: {
+          total: sorted.length,
+          completed: completedTodos.length,
+          pending: pendingTodos.length,
+        },
+      },
+    };
   }
 
   @Condition(v.stepResult("list", "valid"), { then: "ok", else: "unauth", order: 1 })
@@ -421,6 +685,123 @@ Example validation failure response body:
 
 `@Util` is typed the same way as `s.util(ConnectorId.Utility.String, "slugify", { ... })` in the fluent builder. `@Db` supports the `mongodb` and `mysql` engines (see [Database](#database)). Step IDs in `v.stepResult("slugify", "value")` refer to the **method name** you put on each decorated step (after sanitization, dots and hyphens in custom IDs become underscores).
 
+### Decorator Connectors
+
+For ultimate flexibility, you can define your own **Connectors** using class-based decorators instead of using the generic `defineCustomConnector` pattern. 
+
+Use the `@ConnectorClass` decorator and map endpoints instantly without rewriting HTTP loops or complex REST logic!
+
+```typescript
+import { ConnectorClass, ActionEndpoint, ActionCustom, buildConnectorFromClass, flosync } from "cliodot";
+
+// You can pass configuration mimicking flosync REST definition payloads directly into the class decorator:
+@ConnectorClass("paystack", "Paystack Integrations", {
+  type: "REST",
+  base_url: "https://api.paystack.co",
+  auth: { type: "bearer", token: process.env.PAYSTACK_SECRET_KEY }
+})
+export class Paystack {
+  
+  // Handled entirely by Flosync's underlying REST connector automatically!
+  @ActionEndpoint("initializeTransaction", "POST", "/transaction/initialize", {
+     headers: { "Content-Type": "application/json" }
+  })
+  initializeTransaction() {}
+
+  // Paths parameter resolution happens completely implicitly via the REST connector.
+  @ActionEndpoint("verifyTransaction", "GET", "/transaction/verify/:reference")
+  verifyTransaction() {}
+  
+  // Or, run a completely custom code execution if you need SDKs or Database integrations
+  @ActionCustom("generateSignature")
+  async generateSignature(payload: any) {
+     const crypto = require("crypto");
+     return { signature: crypto.createHmac('sha512', process.env.SECRET).update(payload.body.data).digest('hex') };
+  }
+}
+
+// Convert class into standard flosync connector schema
+export const paystackConfig = buildConnectorFromClass(Paystack);
+
+export const PaystackConnector = {
+  id: PaystackImplementation.id,
+  actions: PaystackImplementation.actions
+};
+
+// Register it natively just like any built-in module
+flosync.registerConnector(paystackConfig.id, paystackConfig);
+```
+
+#### Authentication Options
+
+Flosync supports built-in, natively executed REST authentication blocks inside the `@ConnectorClass` config object. You do not need to write boilerplate header injection code!
+
+1. **Bearer Token (*Default*)**
+   ```typescript
+   auth: { type: "bearer", token: "your-token", header_name: "Authorization", prefix: "Bearer " }
+   ```
+2. **API Key**
+   ```typescript
+   auth: { type: "api_key", api_key: "your-api-key", key_name: "x-api-key" }
+   ```
+3. **No Auth**
+   ```typescript
+   auth: { type: "none" }
+   ```
+
+Then hook it right into your workflows! This example uses `@Validator` for type-safe input checking, generates a unique payment reference using the built-in `utility.random` connector, and passes it to the Paystack API:
+
+```typescript
+import { Workflow, Http, Connector, Responder, Validator, v } from "cliodot";
+
+@Workflow("payment-initialize", "Initialize Payment")
+@Http("POST", "/payment/initialize")
+export class PaymentInitializeWorkflow {
+
+  @Validator([
+    {
+      fields: [v.body("email")],
+      validators: [{ name: "required" }, { name: "is_email" }]
+    },
+    {
+      fields: [v.body("amount")],
+      validators: [{ name: "required" }]
+    }
+  ], { order: 0, then: "generateReference", else: "invalid" })
+  validate() {}
+
+  @Responder("json", { 
+    statusCode: 400,
+    body: { 
+      ok: false,
+      message: "Validation failed", 
+      errors: v.stepResult("validate", "errors") 
+    } 
+  }, { order: 1 })
+  invalid() {}
+
+  @Connector("utility.random", "random_uuid", {}, { order: 2 })
+  generateReference() {}
+
+  @Connector(
+    PaystackConnector.id, 
+    PaystackConnector.actions.initializeTransaction, 
+    { 
+      body: { 
+        email: v.body("email"), 
+        amount: v.body("amount"),
+        reference: v.stepResult("generateReference", "value"),
+      } 
+    },
+    { order: 3 }
+  )
+  initialize() {}
+
+  @Responder("json", { body: { message: "Payment initialized successfully", data: v.stepResult("initialize") } }, { order: 4 })
+  respond() {}
+}
+```
+
 ### Custom `execute` connector plus decorators (catalog sample)
 
 For behavior that is not a REST template (in-memory demo data, your own SDK, legacy SOAP adapter, etc.), register a connector with an `execute` function, then call it from decorators with `@Connector` exactly like a built-in connector. This mirrors the `carrier.store` pattern: actions such as `listProducts` and `createProduct`, `options.body` / `options.params` / `options.pathParams` passed from the step config.
@@ -503,10 +884,10 @@ class CatalogListDecoratorsWorkflow {
     { params: { limit: v.query("limit") } },
     { order: 0, stage: "post" }
   )
-  list(ctx: any) {
+  list(ctx: WorkflowContext<{ products?: CatalogProduct[]; [k: string]: any }>): StepOutput<{ products: any[]; count: number }> {
     const input = ctx?.input ?? {};
     const items = Array.isArray(input.products) ? input.products : [];
-    const withLabels = items.map((p: CatalogProduct) => ({
+    const withLabels = items.map((p) => ({
       ...p,
       price_display: `$${Number(p.price).toFixed(2)}`,
     }));
@@ -540,7 +921,7 @@ class CatalogCreateDecoratorsWorkflow {
     { body: { name: v.body("name"), price: v.body("price") } },
     { order: 0, stage: "post" }
   )
-  save(ctx: any) {
+  save(ctx: WorkflowContext<{ ok?: boolean; product?: CatalogProduct; [k: string]: any }>): StepOutput<any> {
     const input = ctx?.input ?? {};
     if (!input.ok) return { out: input };
     const p = input.product as CatalogProduct;
@@ -636,6 +1017,40 @@ await flosync.runFunctionById('function-id', { amount: 100 });
 
 If a workflow/function is registered locally, `run` / `runFunction` use the local version. If not found and the client is configured, they run remotely. Pass `{ remote: false }` to disable remote fallback.
 
+### Connector versioning (REST connectors)
+
+Tenant REST connectors can have **published semver snapshots**. The SDK and API use that version when loading connector definitions for workflow runs and for direct execute calls.
+
+**Workflow steps (fluent builder and `@Connector` config)**  
+Include an optional semver string on the step config so pushed workflows pin the same snapshot the runner expects:
+
+```typescript
+s.connector("paystack_conn_id", "initializeTransaction", {
+  connector_version: "1.2.0",
+  body: { email: v.body("email"), amount: v.body("amount") },
+});
+```
+
+Event triggers can pin the source connector the same way on the workflow object: `trigger.source_connector_id` and `trigger.source_connector_version` (see types in `IWorkflowTrigger`).
+
+**`flosync.runConnector` (remote)**  
+Pass `connector_version` in the options object. Non-owners must match their **installed** version; owners may use other published versions or `draft` per API rules.
+
+```typescript
+await flosync.runConnector(Paystack, "initializeTransaction", {
+  connector_version: "1.2.0",
+  body: { email: "a@b.com", amount: 100 },
+});
+```
+
+**`FlosyncClient`** (after `configure` with `apiKey` / `apiSecret`):
+
+- `client.connectors.get(connectorId, { semver: "1.2.0" })` or `{ version: "1.2.0" }` — same query params as the Flowsync GET connector API.
+- `client.connectors.install(connectorId, { auth, base_url, version: "latest" })` — `version` is optional (body or query on the server).
+- `client.connectors.execute(connectorId, action, { connector_version: "1.2.0", body, params, ... })` — sent as `connector_version` on the execute request body.
+
+Workflows built with `WorkflowBuilder` / decorators serialize `connector_version` onto nodes when you `workflows.push`, so pulls round-trip the field.
+
 ## Database
 
 Use `s.db(engine, action, config)` or `s.connector(connectorId, action, config)` with built-in database connectors.
@@ -699,6 +1114,192 @@ s.responder('redirect', { location: 'https://example.com', statusCode: 301 });
 s.responder('empty', { statusCode: 202 });
 ```
 
+## Validation
+
+The `@Validator` decorator provides type-safe input validation for workflow steps. Validators use a `ValidationRule` union type that gives you full IDE auto-completion for all available rules and their configuration options.
+
+### Basic usage
+
+```typescript
+import { Validator, v } from "cliodot";
+
+@Validator([
+  {
+    fields: [v.body("email")],
+    validators: [{ name: "required" }, { name: "is_email" }]
+  },
+  {
+    fields: [v.body("amount")],
+    validators: [{ name: "required" }, { name: "is_number" }]
+  }
+], { order: 0, then: "process", else: "error" })
+validate() {}
+```
+
+### Available validators
+
+| Validator | Config | Description |
+|-----------|--------|-------------|
+| `required` | `{ message? }` | Field must be present and non-null |
+| `not_empty` | `{ message? }` | Field must not be empty |
+| `is_empty` | `{ message? }` | Field must be empty |
+| `is_email` | `{ message? }` | Valid email format |
+| `is_number` | `{ message? }` | Must be a number |
+| `is_string` | `{ message? }` | Must be a string |
+| `is_boolean` | `{ message? }` | Must be a boolean |
+| `is_array` | `{ message? }` | Must be an array |
+| `is_object` | `{ message? }` | Must be an object |
+| `is_url` | `{ message? }` | Valid URL format |
+| `is_date` | `{ message? }` | Valid date format |
+| `is_uuid` | `{ message? }` | Valid UUID (v1-v5) |
+| `is_cuid` | `{ message? }` | Valid CUID |
+| `is_jwt` | `{ message? }` | Valid JWT structure (`header.payload.signature`) |
+| `is_json` | `{ message? }` | Valid parseable JSON string |
+| `is_alphanumeric` | `{ message? }` | Letters and numbers only |
+| `is_alpha` | `{ message? }` | Letters only |
+| `is_numeric_string` | `{ message? }` | Numeric digits only |
+| `is_hex_color` | `{ message? }` | Valid hex color (`#FFF` or `#123456`) |
+| `is_base64` | `{ message? }` | Valid base64 encoded string |
+| `is_credit_card` | `{ message? }` | Valid credit card (Luhn algorithm) |
+| `is_lowercase` | `{ message? }` | Must be all lowercase |
+| `is_uppercase` | `{ message? }` | Must be all uppercase |
+| `is_slug` | `{ message? }` | Valid URL slug (`my-cool-slug`) |
+| `is_mac_address` | `{ message? }` | Valid MAC address |
+| `is_port` | `{ message? }` | Valid TCP/UDP port (0-65535) |
+| `is_currency` | `{ message? }` | Valid currency format |
+| `is_latitude` | `{ message? }` | Valid latitude (-90 to 90) |
+| `is_longitude` | `{ message? }` | Valid longitude (-180 to 180) |
+| `is_strong_password` | `{ minLength?, minLowercase?, minUppercase?, minNumbers?, minSymbols?, message? }` | Configurable password strength |
+| `is_ip` | `{ version?: 4 \| 6, message? }` | Valid IPv4 or IPv6 address |
+| `is_phone` | `{ pattern?, message? }` | Phone number format |
+| `is_address` | `{ minLength?, maxLength?, message? }` | Address string checks |
+| `contains` / `not_contains` | `{ search, caseSensitive?, message? }` | String contains/excludes a value |
+| `begins_with` | `{ prefix, caseSensitive?, message? }` | String starts with prefix |
+| `ends_with` | `{ suffix, caseSensitive?, message? }` | String ends with suffix |
+| `is_in` / `not_in` | `{ values: any[], caseSensitive?, message? }` | Value is/isn't in a list |
+| `length` | `{ min?, max?, exact?, message? }` | String/array length bounds |
+| `range` | `{ min?, max?, message? }` | Numeric range bounds |
+| `matches` | `{ pattern, flags?, message? }` | Regex pattern match |
+| `equals` / `not_equals` | `{ value, message? }` | Strict equality check |
+| `greater_than` / `less_than` | `{ value: number, message? }` | Numeric comparison |
+| `greater_than_or_equal` / `less_than_or_equal` | `{ value: number, message? }` | Inclusive numeric comparison |
+
+### Configurable validators
+
+Some validators accept rich configuration objects with IDE autocomplete:
+
+```typescript
+// Strong password with custom constraints
+@Validator([
+  {
+    fields: [v.body("password")],
+    validators: [{
+      name: "is_strong_password",
+      config: { minLength: 12, minUppercase: 2, minSymbols: 1 }
+    }]
+  }
+], { order: 0, then: "register", else: "invalid" })
+validatePassword() {}
+
+// IP address with version lock
+@Validator([
+  {
+    fields: [v.body("server_ip")],
+    validators: [{ name: "is_ip", config: { version: 4 } }]
+  }
+], { order: 0, then: "connect", else: "invalid" })
+validateIP() {}
+
+// Range + custom message
+@Validator([
+  {
+    fields: [v.body("age")],
+    validators: [{
+      name: "range",
+      config: { min: 18, max: 120, message: "Age must be between 18 and 120" }
+    }]
+  }
+], { order: 0, then: "proceed", else: "invalid" })
+validateAge() {}
+```
+
+### Validation branching
+
+Use `then` and `else` to route the workflow based on validation results:
+
+```typescript
+@Validator([
+  { fields: [v.body("email")], validators: [{ name: "required" }, { name: "is_email" }] }
+], { order: 0, then: "process", else: "validationError" })
+validate() {}
+
+@Responder("json", {
+  statusCode: 400,
+  body: { ok: false, errors: v.stepResult("validate", "errors") }
+}, { order: 1 })
+validationError() {}
+```
+
+When validation fails, the `errors` object is populated with field-level error messages that the responder can return to the client.
+
+## Debug Mode
+
+Flosync includes a built-in debug mode that injects a `_debug` object into workflow responses, containing the full `stepResults` map of every step that executed. This is invaluable for development and troubleshooting without adding `console.log` statements.
+
+### Enabling debug
+
+**1. Global (via config)** — applies to all workflow runs:
+
+```typescript
+flosync.configure({
+  debug: true,
+  connectors: { ... },
+});
+```
+
+**2. Per-request (via header)** — enable for a single call:
+
+```bash
+curl -X POST http://localhost:3384/payment/initialize \
+  -H "Content-Type: application/json" \
+  -H "x-flosync-debug: true" \
+  -d '{"email": "user@example.com", "amount": 5000}'
+```
+
+**3. Per-request (via query param):**
+
+```bash
+curl "http://localhost:3384/books?debug=true"
+```
+
+### Debug output
+
+When debug mode is active, a `_debug` key is appended to the response body:
+
+```json
+{
+  "message": "Payment initialized successfully",
+  "data": {
+    "authorization_url": "https://checkout.paystack.com/abc123",
+    "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+  },
+  "_debug": {
+    "stepResults": {
+      "validate": { "valid": true },
+      "generateReference": { "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
+      "initialize": {
+        "authorization_url": "https://checkout.paystack.com/abc123",
+        "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+      }
+    }
+  }
+}
+```
+
+When debug mode is **off** (default), the `_debug` key is completely absent — zero overhead and no payload pollution.
+
+> **Note:** Debug mode works for both local workflow execution (`flosync.run()`) and remote execution via `client.workflows.run()` / `client.workflows.runByWebhook()`.
+
 ## Encryption
 
 Use `s.encrypt(connectorId, action, config)` with built-in encryption connectors. All use Node `crypto`; Argon2 and bcrypt require optional packages.
@@ -785,6 +1386,143 @@ import { defineCustomConnectorFromList } from 'cliodot';
 const MyStore = defineCustomConnectorFromList('my.store', ['login', 'listItems', 'createItem']);
 ```
 
+### Typed connectors (for remote connectors)
+
+When using remote connectors, you do not have the implementation locally. `defineTypedConnector` lets you define per-action schema so TypeScript can infer request/response shapes across decorators, builder calls, and `runConnector`.
+
+```typescript
+import { defineTypedConnector } from "cliodot";
+
+const Paystack = defineTypedConnector("paystack", {
+  initializeTransaction: "Initialize Transaction",
+  verifyTransaction: "Verify Transaction",
+  listTransactions: "List Transactions",
+}, {
+  initializeTransaction: {
+    body: {} as { email: string; amount: number; reference?: string; callback_url?: string },
+    headers: {} as { "Idempotency-Key"?: string },
+    vars: {} as { traceId?: string },
+    response: {} as { authorization_url: string; access_code: string; reference: string },
+  },
+  verifyTransaction: {
+    pathParams: {} as { reference: string },
+    response: {} as { status: string; amount: number; currency: string; paid_at: string },
+  },
+  listTransactions: {
+    params: {} as { page?: number; perPage?: number; status?: string },
+    response: {} as { data: Array<{ reference: string; amount: number; status: string }> },
+  },
+});
+```
+
+Schema fields:
+
+| Field | Description |
+|-------|-------------|
+| `body` | Shape of request body |
+| `params` | Shape of query/params |
+| `pathParams` | Shape of URL path params |
+| `headers` | Shape of custom headers |
+| `vars` | Shape of step-level vars merged before execution |
+| `response` | Shape of expected response |
+
+Use `{} as YourType` to define each shape without runtime values.
+
+**Extracting types with helper utilities:**
+
+```typescript
+import type {
+  ConnectorBody,
+  ConnectorParams,
+  ConnectorPathParams,
+  ConnectorHeaders,
+  ConnectorVars,
+  ConnectorResponse,
+} from "cliodot";
+
+type InitBody = ConnectorBody<typeof Paystack, "initializeTransaction">;
+type InitHeaders = ConnectorHeaders<typeof Paystack, "initializeTransaction">;
+type InitVars = ConnectorVars<typeof Paystack, "initializeTransaction">;
+type VerifyPath = ConnectorPathParams<typeof Paystack, "verifyTransaction">;
+type ListParams = ConnectorParams<typeof Paystack, "listTransactions">;
+type VerifyResponse = ConnectorResponse<typeof Paystack, "verifyTransaction">;
+```
+
+**Using in decorators (typed action key + typed config):**
+
+```typescript
+import { Workflow, Http, Connector, Responder, v } from "cliodot";
+import type { WorkflowContext, StepOutput, ConnectorResponse } from "cliodot";
+
+type InitResponse = ConnectorResponse<typeof Paystack, "initializeTransaction">;
+
+@Workflow("paystack-init", "Initialize Paystack Payment")
+@Http("POST", "/pay")
+class PaystackInitWorkflow {
+  @Connector(
+    Paystack,
+    "initializeTransaction",
+    {
+      body: { email: v.body("email"), amount: v.body("amount"), callback_url: v.body("callback_url") },
+      headers: { "Idempotency-Key": "{{ trigger.idempotencyKey }}" },
+      vars: { traceId: "{{ trigger.traceId }}" },
+    },
+    { order: 0, stage: "post" }
+  )
+  init(ctx: WorkflowContext<InitResponse>): StepOutput<{ url: string; ref: string }> {
+    return {
+      out: {
+        url: ctx.input.authorization_url,
+        ref: ctx.input.reference,
+      },
+    };
+  }
+
+  @Responder("json", {
+    body: { url: v.stepResult("init", "url"), reference: v.stepResult("init", "ref") },
+  }, { order: 1 })
+  respond() {}
+}
+```
+
+You can still use the classic style (`Paystack.id` + `Paystack.actions.someAction`) if you prefer.
+
+**Typed connectors also work in builder and direct runs:**
+
+```typescript
+// Builder
+workflow.step("init", (s) =>
+  s.connector(Paystack, "initializeTransaction", {
+    body: { email: "{{ trigger.email }}", amount: "{{ trigger.amount }}" },
+    headers: { "Idempotency-Key": "{{ trigger.idempotencyKey }}" },
+  })
+);
+
+// Direct connector execution
+await flosync.runConnector(Paystack, "verifyTransaction", {
+  pathParams: { reference: "ref_123" },
+});
+```
+
+Template strings are accepted in typed request fields (`body`, `params`, `pathParams`, `headers`, `vars`) so workflow expressions continue to work with strong typing.
+
+Available type helpers:
+
+| Helper | Description |
+|--------|-------------|
+| `ConnectorBody<TDef, TAction>` | Extracts `body` type |
+| `ConnectorParams<TDef, TAction>` | Extracts `params` type |
+| `ConnectorPathParams<TDef, TAction>` | Extracts `pathParams` type |
+| `ConnectorHeaders<TDef, TAction>` | Extracts `headers` type |
+| `ConnectorVars<TDef, TAction>` | Extracts `vars` type |
+| `ConnectorResponse<TDef, TAction>` | Extracts `response` type |
+| `ConnectorActionRequest<TDef, TAction>` | Extracts full request shape |
+| `ConnectorTypedRequestConfig<TDef, TAction>` | Typed decorator/builder request config |
+
+Examples-first guide:
+
+- [`Typed Connector End-to-End Samples`](./TYPED_CONNECTOR_EXAMPLES.md)
+
 ## Connectors by ID
 
 Use `s.connector(connectorId, action, config)` with any connector ID. For remote runs, connectors are resolved from your account. For local runs, register connectors first with `flosync.registerConnector(id, connector)` or pass config in `configure({ connectors: { 'connector-id': { ... } } })`.
@@ -849,7 +1587,7 @@ const data = await client.connectors.execute('paystack', 'Verify Transaction', {
 | `client.workflows.pull(groupId)` | Fetch workflow as IWorkflow |
 | `client.workflows.list(options?)` | List workflow groups |
 | `client.workflows.run(groupId, triggerId, payload)` | Run by trigger ID (payload may include `environment: "dev" \| "prod"`) |
-| `client.workflows.runByWebhook(path, method, payload)` | Run by webhook path (payload may include `environment`) |
+| `client.workflows.runByWebhook(path, method, payload)` | **`POST /workflows/test/webhook`** — run the workflow whose HTTP trigger matches `path` and `method` (no group id in the request). Payload may include `environment`, `executionHeaders`, and the child body fields (merged into `payload` for the API). |
 | `client.workflows.promote(groupId)` | Promote to production |
 
 See [Workflows](../docs/WORKFLOWS.md) for full documentation. See [Building and Pushing Custom Connectors](../docs/BUILDING_CONNECTORS.md) for connectors.