@blokjs/helper 0.2.0 → 0.4.0

package/dist/workflow.schema.json

@@ -0,0 +1,426 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "Blok Workflow v2",
+	"description": "Schema for Blok v2 JSON workflows. Steps inline their `inputs`; output auto-persists to ctx.state[id]. Use the `branch` step shape for if/else flow control. See https://blok.build/docs/workflow-v2 for full reference.",
+	"type": "object",
+	"properties": {
+		"name": {
+			"type": "string",
+			"minLength": 3,
+			"description": "Workflow display name. Min 3 characters. Shown in Studio."
+		},
+		"version": {
+			"type": "string",
+			"minLength": 5,
+			"description": "Semantic version (x.x.x). Used for trace recording and audit."
+		},
+		"description": {
+			"type": "string",
+			"description": "What this workflow does. Optional but recommended — surfaces in Studio and CLI."
+		},
+		"trigger": {
+			"type": "object",
+			"additionalProperties": {},
+			"propertyNames": {
+				"enum": [
+					"http",
+					"grpc",
+					"manual",
+					"cron",
+					"queue",
+					"pubsub",
+					"worker",
+					"webhook",
+					"sse",
+					"websocket"
+				]
+			},
+			"description": "Trigger configuration. Most workflows use { http: { method: 'GET' } }. See TRIGGER_SCHEMAS for per-kind shapes."
+		},
+		"steps": {
+			"type": "array",
+			"items": {
+				"anyOf": [
+					{
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Stable identifier for the branch step. Visible in traces."
+							},
+							"branch": {
+								"type": "object",
+								"properties": {
+									"when": {
+										"type": "string",
+										"minLength": 1,
+										"description": "JavaScript expression. Truthy → run `then` branch; falsy → run `else` branch. $ proxy expressions compile to strings at the call site (e.g. $.req.query.kind === 'true')."
+									},
+									"then": {
+										"type": "array",
+										"items": {},
+										"description": "Steps to execute when `when` is truthy."
+									},
+									"else": {
+										"type": "array",
+										"items": {},
+										"description": "Steps to execute when `when` is falsy. Optional."
+									}
+								},
+								"required": [
+									"when",
+									"then"
+								],
+								"additionalProperties": false,
+								"description": "Conditional sub-pipeline."
+							},
+							"active": {
+								"type": "boolean"
+							},
+							"stop": {
+								"type": "boolean"
+							}
+						},
+						"required": [
+							"id",
+							"branch"
+						],
+						"additionalProperties": false
+					},
+					{
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Stable identifier. The sub-workflow's output lands on $.state[id] after the child completes. Required."
+							},
+							"subworkflow": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Name of the workflow to invoke. Looked up in the WorkflowRegistry at run time — must match the `name:` field of an HTTP-loaded or manually-registered workflow."
+							},
+							"inputs": {
+								"type": "object",
+								"additionalProperties": {},
+								"description": "Inputs passed to the child as `ctx.request.body`. The child reads them via `$.req.body.<key>` exactly as if HTTP-triggered. May contain $ proxy refs."
+							},
+							"wait": {
+								"type": "boolean",
+								"description": "If true (default), parent step blocks until child completes and the child's ctx.response becomes the parent step's output. If false, dispatch is fire-and-forget — the parent step returns immediately with `{runId, workflowName, scheduledAt}` and the child runs asynchronously via setImmediate. The child still appears in Studio's Sub-runs strip and the parentRunId/parentNodeRunId lineage is preserved. Combine with `idempotencyKey` for at-most-once dispatch (Trigger.dev / Stripe semantics: the runId is cached against the key regardless of child outcome; new key needed to retry on failure)."
+							},
+							"as": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Alternative state key (defaults to id). Mutually exclusive with spread."
+							},
+							"spread": {
+								"type": "boolean",
+								"description": "Shallow-merge child's response keys into state. Mutually exclusive with as."
+							},
+							"ephemeral": {
+								"type": "boolean",
+								"description": "If true, child output is NOT stored in state. Only ctx.prev carries it."
+							},
+							"active": {
+								"type": "boolean",
+								"description": "If false, the step is skipped at runtime. Default true."
+							},
+							"stop": {
+								"type": "boolean",
+								"description": "If true, the workflow halts after this step completes."
+							},
+							"idempotencyKey": {
+								"type": "string",
+								"minLength": 1,
+								"description": "When set, the sub-workflow's parent step output is cached against the triple (parentWorkflow, step.id, key). Cache semantics depend on `wait`: with `wait: true` (default), cache HIT means the child workflow is NEVER invoked — including any side effects (use with care for sub-workflows that send emails, charge cards, etc.). With `wait: false`, cache HIT returns the SAME `{runId, workflowName, scheduledAt}` for the lifetime of the cache entry — at-most-once dispatch deduplication. To retry on child failure, use a new key."
+							},
+							"idempotencyKeyTTL": {
+								"type": "integer",
+								"minimum": 0,
+								"description": "Cache lifetime in milliseconds. Defaults to 24h. Pass 0 to immediately expire."
+							},
+							"retry": {
+								"type": "object",
+								"properties": {
+									"maxAttempts": {
+										"type": "integer",
+										"minimum": 1,
+										"maximum": 20,
+										"description": "Total attempts including the first run. 1 = no retry. Capped at 20."
+									},
+									"minTimeoutInMs": {
+										"type": "integer",
+										"minimum": 0,
+										"description": "Initial backoff delay in ms before the second attempt. Default 1000."
+									},
+									"maxTimeoutInMs": {
+										"type": "integer",
+										"minimum": 0,
+										"description": "Cap on the backoff delay between attempts. Default 30000."
+									},
+									"factor": {
+										"type": "number",
+										"minimum": 1,
+										"description": "Exponential backoff factor: delay = min(maxTimeout, minTimeout * factor^(attempt-1)). Default 2."
+									}
+								},
+								"required": [
+									"maxAttempts"
+								],
+								"additionalProperties": false,
+								"description": "Retry the WHOLE sub-workflow on failure. Each retry creates a fresh child run record under the same parent."
+							},
+							"maxDuration": {
+								"anyOf": [
+									{
+										"type": "integer",
+										"minimum": 0
+									},
+									{
+										"type": "string",
+										"minLength": 1,
+										"pattern": "^\\d+(ms|s|m|h|d)$"
+									}
+								],
+								"description": "OPTIONAL. Per-attempt execution timeout. Caps the synchronous wait for `wait: true` sub-workflows. No-op for `wait: false` (parent returns immediately; the child's max-duration is the child's concern). Number (ms) or duration string. On final-attempt timeout, the run auto-flips to `\"timedOut\"`."
+							}
+						},
+						"required": [
+							"id",
+							"subworkflow"
+						],
+						"additionalProperties": false
+					},
+					{
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Stable identifier."
+							},
+							"wait": {
+								"type": "object",
+								"properties": {
+									"for": {
+										"anyOf": [
+											{
+												"type": "integer",
+												"minimum": 0
+											},
+											{
+												"type": "string",
+												"minLength": 1,
+												"pattern": "^\\d+(ms|s|m|h|d)$"
+											}
+										],
+										"description": "Wait this long. Mutually exclusive with `until`. Number (ms) or duration string (`500ms`, `30s`, `5m`, `2h`, `1d`)."
+									},
+									"until": {
+										"type": [
+											"number",
+											"string"
+										],
+										"description": "Wait until this absolute time. Number is ms-since-epoch; string is an ISO date or a $-proxy expression. Mutually exclusive with `for`."
+									}
+								},
+								"additionalProperties": false
+							},
+							"as": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Alternative state key (defaults to `id`)."
+							},
+							"ephemeral": {
+								"type": "boolean",
+								"description": "If true, no state entry is recorded."
+							},
+							"active": {
+								"type": "boolean"
+							},
+							"stop": {
+								"type": "boolean"
+							},
+							"idempotencyKey": {
+								"not": {}
+							},
+							"retry": {
+								"not": {}
+							},
+							"maxDuration": {
+								"not": {}
+							},
+							"concurrencyKey": {
+								"not": {}
+							},
+							"spread": {
+								"not": {}
+							}
+						},
+						"required": [
+							"id",
+							"wait"
+						],
+						"additionalProperties": false
+					},
+					{
+						"type": "object",
+						"properties": {
+							"id": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Stable identifier. Other steps reference this step's output as $.state[id]. Required."
+							},
+							"use": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Node reference. Examples: '@blokjs/api-call', 'my-custom-node'. Type is inferred from this value when `type` is not set."
+							},
+							"type": {
+								"type": "string",
+								"enum": [
+									"local",
+									"module",
+									"runtime.python3",
+									"runtime.nodejs",
+									"runtime.bun",
+									"runtime.go",
+									"runtime.java",
+									"runtime.rust",
+									"runtime.php",
+									"runtime.csharp",
+									"runtime.ruby",
+									"runtime.docker",
+									"runtime.wasm"
+								],
+								"description": "Node type (module/local/runtime.*). When omitted, inferred from `use`: runtime.* prefixes are explicit; @blokjs/* and most others default to 'module'."
+							},
+							"inputs": {
+								"type": "object",
+								"additionalProperties": {},
+								"description": "Inputs passed to the node. May contain $ proxy references (e.g. $.state.foo, $.req.body.id) or 'js/...' expressions for runtime evaluation."
+							},
+							"as": {
+								"type": "string",
+								"minLength": 1,
+								"description": "Alternative name for this step's output in state. Defaults to `id`. Useful when the id is implementation-detail-y and the output is referenced by a domain term."
+							},
+							"spread": {
+								"type": "boolean",
+								"description": "If true, the result.data object's top-level keys are shallow-merged into state. Use for multi-output nodes in data-pipeline workflows. Mutually exclusive with `as`."
+							},
+							"ephemeral": {
+								"type": "boolean",
+								"description": "If true, this step's output is NOT stored in state. Only ctx.prev carries it to the immediately next step. Use for side-effects (logging, audit, telemetry)."
+							},
+							"runtime": {
+								"type": "string",
+								"enum": [
+									"nodejs",
+									"bun",
+									"python3",
+									"go",
+									"java",
+									"rust",
+									"php",
+									"csharp",
+									"ruby",
+									"docker",
+									"wasm"
+								],
+								"description": "Optional runtime hint. Most authors don't need this; the type already encodes it."
+							},
+							"active": {
+								"type": "boolean",
+								"description": "If false, the step is skipped at runtime. Default true."
+							},
+							"stop": {
+								"type": "boolean",
+								"description": "If true, the workflow halts after this step completes. Default false."
+							},
+							"stream_logs": {
+								"type": "boolean",
+								"description": "Per-step opt-in for live log streaming. Inherits from BLOK_STREAM_LOGS env when unset."
+							},
+							"idempotencyKey": {
+								"type": "string",
+								"minLength": 1,
+								"description": "When set, the step's result is cached against the triple (workflowName, step.id, idempotencyKey). On a subsequent run with the same triple, execution is skipped and the cached result populates state through the same persistence rules (ephemeral / spread / as). Accepts a literal string or a $ proxy expression that compiles to `js/ctx....` (e.g. $.req.body.requestId)."
+							},
+							"idempotencyKeyTTL": {
+								"type": "integer",
+								"minimum": 0,
+								"description": "Cache lifetime in milliseconds. Defaults to 24h (86_400_000) when omitted. Pass 0 to mark a cached result as immediately expired (effectively disables caching)."
+							},
+							"retry": {
+								"type": "object",
+								"properties": {
+									"maxAttempts": {
+										"type": "integer",
+										"minimum": 1,
+										"maximum": 20,
+										"description": "Total attempts including the first run. 1 = no retry. Capped at 20."
+									},
+									"minTimeoutInMs": {
+										"type": "integer",
+										"minimum": 0,
+										"description": "Initial backoff delay in ms before the second attempt. Default 1000."
+									},
+									"maxTimeoutInMs": {
+										"type": "integer",
+										"minimum": 0,
+										"description": "Cap on the backoff delay between attempts. Default 30000."
+									},
+									"factor": {
+										"type": "number",
+										"minimum": 1,
+										"description": "Exponential backoff factor: delay = min(maxTimeout, minTimeout * factor^(attempt-1)). Default 2."
+									}
+								},
+								"required": [
+									"maxAttempts"
+								],
+								"additionalProperties": false,
+								"description": "Retry configuration with capped exponential backoff. When omitted, the step runs at most once (no retry) — matches pre-v0.3.x behavior."
+							},
+							"maxDuration": {
+								"anyOf": [
+									{
+										"type": "integer",
+										"minimum": 0
+									},
+									{
+										"type": "string",
+										"minLength": 1,
+										"pattern": "^\\d+(ms|s|m|h|d)$"
+									}
+								],
+								"description": "OPTIONAL. Per-attempt execution timeout. Number (ms) or duration string ('30s', '5m', '500ms'). When the step's `step.process()` exceeds this duration, the attempt fails with a StepTimeoutError. Pairs with `retry` — each attempt gets its own timeout (total budget = maxDuration × maxAttempts). On final-attempt timeout, the run auto-flips to `\"timedOut\"` status (distinct from `\"failed\"` so SLA dashboards can separate timeouts from logic failures)."
+							},
+							"set_var": {
+								"type": "boolean",
+								"description": "@deprecated v2 default-stores every step's output. `set_var: true` is a no-op; `set_var: false` is normalized to `ephemeral: true`."
+							}
+						},
+						"required": [
+							"id",
+							"use"
+						],
+						"additionalProperties": false
+					}
+				]
+			},
+			"minItems": 1,
+			"description": "Pipeline of steps to execute in order. At least one step required."
+		}
+	},
+	"required": [
+		"name",
+		"version",
+		"trigger",
+		"steps"
+	],
+	"additionalProperties": false
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@blokjs/helper",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "",
 	"engines": {
 		"node": ">=18.0.0"
@@ -8,14 +8,13 @@
 	"type": "module",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
-	"files": [
-		"dist"
-	],
+	"files": ["dist"],
 	"author": "Marco A. Castillo Della Sera",
 	"license": "MIT",
 	"scripts": {
-		"build": "rm -rf dist && bun run tsc",
+		"build": "rm -rf dist && bun run tsc && bun run build:schema",
 		"build:dev": "tsc --watch",
+		"build:schema": "bun run scripts/build-schema.ts",
 		"test:dev": "vitest",
 		"test": "vitest run",
 		"typecheck": "tsc --noEmit --incremental"
@@ -23,7 +22,8 @@
 	"devDependencies": {
 		"@types/node": "^22.15.21",
 		"typescript": "^5.8.3",
-		"vitest": "^4.0.18"
+		"vitest": "^4.0.18",
+		"zod-to-json-schema": "^3.25.2"
 	},
 	"dependencies": {
 		"zod": "^3.24.2"