@enfocussw/switch-scripting-context 0.1.0

package/docs/switch-api/enums.md

@@ -0,0 +1,181 @@
+---
+id: enums
+category: switch-api
+order: 8
+summary: "All enums with string values (`LogLevel`, `AccessLevel`, `DatasetModel`, `Scope`, `Priority`, `Connection.Level`, etc.)"
+triggers:
+  - "Looking up enum values"
+---
+
+# Switch Scripting Enums
+
+All enums are available globally in `main.ts`. They are also accessible via `EnfocusSwitch.*` when used outside `main.ts` (e.g. in imported modules). Enums and values without a Switch version below exist in every Switch version with Node.js scripting; see [api-versions.md](api-versions.md).
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- LogLevel
+- AccessLevel
+- DatasetModel
+- Scope
+- Priority
+- Connection.Level
+- HttpRequest.Method
+- PropertyType
+- NoYesListPropertyStringValue
+- EnfocusSwitchPrivateDataTag
+- ImageDocument.ColorMode
+- ImageDocument.ColorSpace
+<!-- docs-index:contents end -->
+
+## LogLevel
+
+Used with `job.log()` and `flowElement.log()`.
+
+| Value | String |
+|---|---|
+| `LogLevel.Info` | `"info"` |
+| `LogLevel.Warning` | `"warning"` |
+| `LogLevel.Error` | `"error"` |
+| `LogLevel.Debug` | `"debug"` (Switch 21.0+) |
+
+## AccessLevel
+
+Used with `job.get()` and `job.getDataset()`.
+
+| Value | String |
+|---|---|
+| `AccessLevel.ReadOnly` | `"readOnly"` |
+| `AccessLevel.ReadWrite` | `"readWrite"` |
+
+## DatasetModel
+
+Used with `job.createDataset()`, `job.sendToLog()`, and `job.listDatasets()`.
+
+| Value | String |
+|---|---|
+| `DatasetModel.Opaque` | `"Opaque"` |
+| `DatasetModel.XML` | `"XML"` |
+| `DatasetModel.XMP` | `"XMP"` |
+| `DatasetModel.JDF` | `"JDF"` |
+| `DatasetModel.JSON` | `"JSON"` (Switch 22.0+) |
+
+## Scope
+
+Used with `s.getGlobalData()`, `s.setGlobalData()`, `s.removeGlobalData()`.
+
+| Value | String |
+|---|---|
+| `Scope.Element` | `"element"` |
+| `Scope.Flow` | `"flow"` (Switch 22.0+) |
+| `Scope.FlowElement` | `"flowElement"` |
+| `Scope.FlowElements` | `"flowElements"` (Switch 22.0+) |
+| `Scope.Global` | `"global"` |
+
+## Priority
+
+Used with `job.setPriority()` / `job.getPriority()`. Switch 22.1+.
+
+| Value | Number |
+|---|---|
+| `Priority.Low` | `-100000` |
+| `Priority.BelowNormal` | `-10000` |
+| `Priority.Normal` | `0` |
+| `Priority.AboveNormal` | `10000` |
+| `Priority.High` | `100000` |
+
+## Connection.Level
+
+Used with `job.sendToData()` and `job.sendToLog()` for traffic light connections.
+
+| Value | String |
+|---|---|
+| `Connection.Level.Success` | `"success"` |
+| `Connection.Level.Warning` | `"warning"` |
+| `Connection.Level.Error` | `"error"` |
+
+Also available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`. It selects which level to
+route to; it is not a property you can read back from a `Connection` object, see
+[connection.md § Connection.Level enum](connection.md#connectionlevel-enum).
+
+## HttpRequest.Method
+
+Used with `s.httpRequestSubscribe()` and `s.httpRequestUnsubscribe()`. Switch 21.1+.
+
+| Value | String |
+|---|---|
+| `HttpRequest.Method.POST` | `"POST"` |
+| `HttpRequest.Method.PUT` | `"PUT"` |
+| `HttpRequest.Method.DELETE` | `"DELETE"` |
+
+Also available as `EnfocusSwitch.HttpRequest.Method.*` outside `main.ts`.
+
+## PropertyType
+
+Returned by `flowElement.getPropertyType()` and `connection.getPropertyType()`.
+
+| Value | String |
+|---|---|
+| `PropertyType.Literal` | `"literal"` |
+| `PropertyType.Number` | `"number"` |
+| `PropertyType.Date` | `"date"` |
+| `PropertyType.HoursAndMinutes` | `"hoursandminutes"` |
+| `PropertyType.Boolean` | `"boolean"` |
+| `PropertyType.String` | `"string"` |
+| `PropertyType.FilePath` | `"filepath"` |
+| `PropertyType.FolderPath` | `"folderpath"` |
+| `PropertyType.FileType` | `"filetype"` |
+| `PropertyType.FolderPattern` | `"folderpattern"` |
+| `PropertyType.Regex` | `"regex"` |
+| `PropertyType.OAuthToken` | `"oauthtoken"` |
+
+## NoYesListPropertyStringValue
+
+Convenience for `Boolean`-typed properties returned as strings. Switch 24.0+.
+
+| Value | String |
+|---|---|
+| `NoYesListPropertyStringValue.No` | `"No"` |
+| `NoYesListPropertyStringValue.Yes` | `"Yes"` |
+
+## EnfocusSwitchPrivateDataTag
+
+Well-known tags for `job.getPrivateData()` / `job.setPrivateData()`. The enum needs Switch 21.0+; `initiated` and `submittedTo` need 21.1+, and `state` needs 22.1+.
+
+| Value | String |
+|---|---|
+| `EnfocusSwitchPrivateDataTag.hierarchy` | `"EnfocusSwitch.hierarchy"` |
+| `EnfocusSwitchPrivateDataTag.emailAddresses` | `"EnfocusSwitch.emailAddresses"` |
+| `EnfocusSwitchPrivateDataTag.emailBody` | `"EnfocusSwitch.emailBody"` |
+| `EnfocusSwitchPrivateDataTag.userName` | `"EnfocusSwitch.userName"` |
+| `EnfocusSwitchPrivateDataTag.userFullName` | `"EnfocusSwitch.userFullName"` |
+| `EnfocusSwitchPrivateDataTag.userEmail` | `"EnfocusSwitch.userEmail"` |
+| `EnfocusSwitchPrivateDataTag.origin` | `"EnfocusSwitch.origin"` |
+| `EnfocusSwitchPrivateDataTag.initiated` | `"EnfocusSwitch.initiated"` |
+| `EnfocusSwitchPrivateDataTag.submittedTo` | `"EnfocusSwitch.submittedTo"` |
+| `EnfocusSwitchPrivateDataTag.state` | `"EnfocusSwitch.state"` |
+
+## ImageDocument.ColorMode
+
+Used with `ImageDocument.getColorMode()`. Available as `EnfocusSwitch.ImageDocument.ColorMode.*` outside `main.ts`. Switch 21.1+.
+
+| Value | String |
+|---|---|
+| `ImageDocument.ColorMode.Bitmap` | `"Bitmap"` |
+| `ImageDocument.ColorMode.Gray` | `"Gray"` |
+| `ImageDocument.ColorMode.IndexedColor` | `"Indexed color"` |
+| `ImageDocument.ColorMode.RGB` | `"RGB"` |
+| `ImageDocument.ColorMode.CMYK` | `"CMYK"` |
+| `ImageDocument.ColorMode.Multichannel` | `"Multichannel"` |
+| `ImageDocument.ColorMode.Duotone` | `"Duotone"` |
+| `ImageDocument.ColorMode.LabColor` | `"Lab color"` |
+| `ImageDocument.ColorMode.Unknown` | `"Unknown"` |
+
+## ImageDocument.ColorSpace
+
+Used with `ImageDocument.getColorSpace()`. Available as `EnfocusSwitch.ImageDocument.ColorSpace.*` outside `main.ts`. Switch 21.1+.
+
+| Value | String |
+|---|---|
+| `ImageDocument.ColorSpace.SRGB` | `"sRGB"` |
+| `ImageDocument.ColorSpace.Uncalibrated` | `"uncalibrated"` |

package/docs/switch-api/execution-environment.md

@@ -0,0 +1,143 @@
+---
+id: execution-environment
+category: switch-api
+order: 17
+summary: "Execution modes (`Concurrent`/`Serialized`, `ExecutionGroup`, `NumberOfSlots`), process/concurrency model, state persistence across job invocations, unhandled-rejection behavior, npm/native module constraints"
+triggers:
+  - "Choosing or changing an execution mode, relying on module-level state across jobs, handling errors/rejections, or using third-party npm packages"
+---
+
+# Execution Environment
+
+How the Node.js process a script runs in behaves, beyond the entry point API itself. Apart from the
+execution mode below, these are consequences of the host process model rather than things a script
+configures — understanding them avoids subtle bugs around state persistence and error handling.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Execution modes
+- Two independent concurrency tiers
+- Don't rely on in-memory state between entry point calls
+- Unhandled promise rejections end the run, not the process
+- Third-party npm modules: file-based scripts only
+- Native (binary) addons are not supported
+- No explicit CPU or memory cap beyond the documented thresholds
+<!-- docs-index:contents end -->
+
+## Execution modes
+
+Set in the XML declaration via SwitchScripter, or by editing it directly (see
+[script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields)). Applies to all
+instances of the script.
+
+**Concurrent** — entry points for the same or different instances may run in parallel. Scripts must
+synchronize access to any shared resources; for global data, use the `lock` parameter of
+`getGlobalData` (see [switch.md § Locking](switch.md#locking)). `NumberOfSlots` is only meaningful in
+this mode.
+
+**Serialized** — entry points within the same **execution group** are never concurrent. Instances
+in different execution groups may still run in parallel.
+
+**Execution group** — only relevant for Serialized mode. Should be a reverse-domain string (e.g.
+`com.mycompany.myScript`) to avoid collisions. Defaults to the Script ID if left empty.
+
+Neither setting maps to a count of Node.js OS processes — see below.
+
+## Two independent concurrency tiers
+
+`NumberOfSlots`/`ExecutionGroup` (above) and the pool of Node.js processes that
+actually run script code are governed completely separately — there is no one-to-one mapping between
+them:
+
+- **`NumberOfSlots`** is a job-admission throttle on the Switch Server, scoped to that one flow
+  element instance (keyed by flow + element id): it limits how many jobs may be dispatched to that
+  instance at once, falling back to a server-wide default if left as `Default`. **`ExecutionGroup`**
+  (meaningful only for `Serialized` mode) is a true cross-flow-element named lock — every flow
+  element that declares the same group string, anywhere on the server, contends for one shared lock.
+  Neither is a count of OS processes.
+- Separately, a shared pool of long-lived Node.js executor processes actually runs the script code
+  for every script element on the server, sized by a single server-wide concurrency setting — not
+  one process per slot, per instance, or per script. A job dispatched by the Server is handed to
+  whichever pooled executor is free (or a new one is spawned if none are); executors are reused
+  across many jobs and across different flow elements running the same Node.js version, until
+  recycled (see
+  [Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)).
+
+## Don't rely on in-memory state between entry point calls
+
+Write every entry point so it neither depends on state from an earlier call nor assumes it starts
+from a clean process.
+
+The executor evaluates the whole script again before every entry point call. Top-level
+`let`/`const`/`var` declarations and functions in the script file are recreated each time, so a
+counter or cache held in one does not carry over to the next job.
+
+Some in-memory state can still outlive a call, because executor processes are long-lived and
+shared:
+
+- Properties set on `global`/`globalThis`. One executor runs code for every script element pooled
+  onto it, so a global can be read or overwritten by a different script.
+- Internal state of CommonJS packages loaded with `require()`. Node caches a required module for
+  the life of the process, so a singleton inside the package (a client, a connection pool, a
+  configured default) can be reused by a later call. ES-module packages that are bundled into the
+  script (see [Native (binary) addons](#native-binary-addons-are-not-supported)) are evaluated
+  again on each call like the script itself.
+- Timers, sockets, and other handles a call leaves open keep running after the entry point returns.
+
+Whether any of this reaches a given job depends on which executor the job lands on and whether that
+executor was recycled in between. A script cannot control or predict either. This is a side effect
+of the process model, not a supported feature, and it can change between Switch versions:
+
+- Don't use globals or package-level singletons to cache data or pass it between jobs. Store data
+  that must outlive a call with `s.setGlobalData()` (see [switch.md](switch.md)) or on the job
+  itself.
+- Don't set globals. If a package keeps internal state, configure it explicitly at the start of
+  each entry point rather than assuming either a fresh or a previously configured instance.
+- Close connections, clear timers, and release file handles before the entry point returns.
+
+Switch logs this message when a call leaves async work pending, as a Warning before Switch 26.11
+and as a Debug message from 26.11: "The script execution has ended while an async function or
+callback in the script might not have finished yet. Please check the script code for unresolved
+promises or missing await statements." On Switch 26.07 it appeared
+when an entry point returned while a `getGlobalData` call was still pending. The
+executor waits one event-loop turn plus 5 ms after the entry point's promise resolves, then logs the
+message if a promise, timer or callback started during the call is still alive, so a timer left
+behind by `Promise.race` triggers it too. From 26.11 it only reaches the log when "Log debug
+messages" is on (see [logging.md](logging.md)); before 26.11 every run that triggers it logs a
+Warning. Treat it as a missing `await` or an unsettled promise: whatever is still pending can keep running after the entry point has returned.
+
+The executor also recognises `getInitialize()`/`getFinalize()` functions in a script. They are not
+part of the public scripting API; don't define them.
+
+## Unhandled promise rejections end the run, not the process
+
+An unhandled promise rejection inside an entry point call ends that job's/run's execution — but the
+underlying executor process is **not** killed and continues serving subsequent job invocations,
+including for other flow elements pooled onto the same executor. Don't rely on an unhandled
+rejection to surface as a hard failure of the whole executor; always catch and handle errors
+explicitly (e.g. via `job.fail()`/`flowElement.failProcess()` — see
+[logging.md](logging.md)) rather than letting a promise reject unhandled.
+
+## Third-party npm modules: file-based scripts only
+
+A script **expression** (entered inline in a flow element property, not a file-based script/app —
+see [Script expression](entry-points.md#script-expression)) cannot use third-party npm modules
+at all; only Node.js built-ins are available via `require`. A file-based script/app can use
+third-party modules from its own `node_modules` folder (see
+[Script folder files](../switch-project/script-structure.md#script-folder-files)).
+
+## Native (binary) addons are not supported
+
+Scripts with ESM dependencies are bundled before execution, when `SwitchVersion` in `manifest.xml`
+is `24.0` or higher (see
+[node-versions.md § Other effects of `SwitchVersion`](../switch-project/node-versions.md#other-effects-of-switchversion)); this bundling path does not support
+native/binary Node addons (`.node` files). Stick to pure-JavaScript/TypeScript dependencies.
+
+## No explicit CPU or memory cap beyond the documented thresholds
+
+Beyond the entry-point abort timeout and executor recycling thresholds already documented (see
+[Job processing](entry-points.md#job-processing) and
+[Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)), there is no
+additional CPU-time or memory limit enforced on a script's own code. A runaway loop or leak is
+bounded only by those thresholds, not stopped proactively.

package/docs/switch-api/flow-element.md

@@ -0,0 +1,143 @@
+---
+id: flow-element
+category: switch-api
+order: 4
+summary: "`FlowElement`: properties, connections, job creation, logging"
+triggers:
+  - "Reading properties, creating jobs, logging, connections"
+---
+
+# FlowElement Class
+
+The `FlowElement` instance `flowElement` is passed to every entry point that operates on a flow element. It provides access to properties, connections, job creation, and logging.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Identity
+- Properties
+- Connections
+- Timer
+- Logging
+- Job creation (jobArrived / timerFired / httpRequestTriggeredAsync)
+- Channels
+- Utilities
+<!-- docs-index:contents end -->
+
+## Identity
+
+```ts
+// Switch 21.1+
+flowElement.getName(): string
+```
+Returns the name of this flow element.
+
+```ts
+// Switch 22.0+
+flowElement.getFlowName(): string
+```
+Returns the name of the flow containing this element.
+
+## Properties
+
+Properties are configured by the user in the Switch canvas and declared in the script's XML declaration.
+
+```ts
+flowElement.getPropertyStringValue(tag: string): Promise<string | string[]>
+```
+Returns the property value as a string (or array for multi-value properties). For `OAuthToken` properties, returns a valid refreshed token. Throws `"Invalid tag: <tag>"` if the tag is unknown **or if it's a `Dependency` dependent currently hidden by its master's value** — see [script-declaration.md § Dependency](../switch-project/script-declaration.md#custom-property-elements-elementfields). A property just added to the declaration also counts as unknown until the element is reloaded with "Reload script" — see [script-declaration.md § Agent editing policy](../switch-project/script-declaration.md#agent-editing-policy). Before fetching a dependent property, confirm its condition holds (from the already-read master value, or via `hasProperty(tag)` below) rather than fetching it unconditionally. See [property-editors.md](../switch-project/property-editors.md) for editor types and their return value formats.
+
+> **Dynamic values (Switch variables and script expressions) are only resolved when `getPropertyStringValue()` is called from `jobArrived`.** In any other entry point (e.g. `timerFired`) the raw unresolved string is returned.
+>
+> **Workaround for deferred processing:** Read property values in `jobArrived` and store them with `s.setGlobalData()`. In `timerFired`, retrieve the stored values and fetch the waiting jobs with `flowElement.getJobs(ids)` (Switch 21.0+). Several `jobArrived` invocations can update the stored list at once, so lock it while you change it; see [job-patterns.md § Shared state in global data](job-patterns.md#shared-state-in-global-data).
+
+```ts
+flowElement.getPropertyType(tag: string): PropertyType
+```
+Returns the `PropertyType` of the property — required to correctly interpret the string value when multiple input types are possible.
+
+```ts
+flowElement.getPropertyDisplayName(tag: string): string
+```
+Returns the English display name of the property (for use in log messages).
+
+```ts
+flowElement.hasProperty(tag: string): boolean
+```
+Returns `true` if the property exists and is visible for the current configuration. Use this to guard `getPropertyStringValue(tag)` calls on `Dependency` dependents — see the note above.
+
+## Connections
+
+```ts
+flowElement.getOutConnections(): Connection[]
+```
+Returns all outgoing connections (arbitrary order). Empty array if none.
+
+## Timer
+
+```ts
+flowElement.setTimerInterval(seconds: number): void
+```
+Sets the interval between `timerFired` invocations. Default is 300 s. The actual interval may be longer under load.
+
+**Only takes effect when called from `timerFired`.** Switch applies the new interval once that invocation returns. Called from any other entry point (`flowStartTriggered`, `jobArrived`, ...), the value is ignored and Switch logs the Warning `A timer interval can only be set inside a 'timerFired' entry point`. The new interval applies from the next `timerFired` call onwards.
+
+## Logging
+
+See [logging.md](logging.md) for log level semantics and logging practice.
+
+```ts
+flowElement.log(level: LogLevel, message: string, messageParams?: (string | number | boolean)[]): Promise<void>
+```
+Logs a message for the flow element. Use `%1`, `%2`, etc. in the message string for substitution via `messageParams`.
+
+```ts
+flowElement.failProcess(message: string, messageParam?: string | number | boolean): void
+```
+Logs a fatal error and puts the element into the "problem process" state. `messageParam` substitutes `%1`; before Switch 22.1, always pass it, as a string (see [api-versions.md](api-versions.md#declaration-changes-to-existing-methods)). Throws `"Job routing is not allowed in this entry point."` if called from an entry point where routing isn't permitted.
+
+## Job creation (jobArrived / timerFired / httpRequestTriggeredAsync)
+
+```ts
+flowElement.createJob(path: string): Promise<Job>
+```
+Creates a new job from an existing file/folder path. Valid in `jobArrived`, `timerFired`, and `httpRequestTriggeredAsync` (confirmed working there; the only webhook entry point that receives `flowElement`). The new job has default properties (no parent). The caller is responsible for cleaning up the source file after routing. See [job-patterns.md](job-patterns.md#temp-file-cleanup) for temp file cleanup rules and [job-patterns.md](job-patterns.md#sending-jobs) for routing constraints.
+
+```ts
+// Switch 21.0+
+flowElement.getJobs(ids: string[]): Promise<Job[]>
+```
+Returns up to 10,000 waiting jobs by ID. Throws if `ids` is not an array, is empty, or exceeds 10,000 entries. Call at most once per entry point. Not available in concurrent `jobArrived`. Private data and metadata of returned jobs cannot be read in the same invocation.
+
+## Channels
+
+```ts
+// Switch 22.1+
+flowElement.subscribeToChannel(channelId: string, backingFolderPath: string): void
+```
+Subscribes to a channel to receive jobs from it. Only one subscriber per channel at a time. Must be called inside `flowStartTriggered`.
+
+## Utilities
+
+```ts
+// Switch 24.0+
+flowElement.createPathWithName(name: string, createFolder: boolean): Promise<any>
+```
+Creates a temporary path (optionally as a folder — `createFolder` is required, not optional). Returns an empty string only if creating the folder throws (e.g. a permissions error); it does not check whether the path already exists first. This is the recommended way to create temp files — see [job-patterns.md](job-patterns.md#temp-file-cleanup) for cleanup rules, including why this method should be preferred over ad hoc temp-file approaches like the `tmp` npm package.
+
+```ts
+// Switch 24.1+
+flowElement.getFileCount(nested?: boolean): Promise<number>
+```
+Returns the number of files in the active flow. If `nested` is `false`, counts only direct children; if `true` (the default, so it can be omitted), counts recursively (folders themselves are not counted).
+
+```ts
+// Switch 24.0+
+flowElement.getScriptDataPath(): string
+```
+Returns the path to the ScriptData folder for this element.
+
+```ts
+flowElement.getPluginResourcesPath(): string
+```
+Returns the script resources folder path. For scripted plug-ins and apps, returns the resources folder. For script folders, returns the folder path. **For a regular script package (`.sscript`) running locally**, returns the parent folder of the deployed package file — external resources are not bundled inside the package itself, so anything the script needs at runtime must be placed in that parent folder alongside the `.sscript`, not referenced from inside it. **Throws** `"flowElement.getPluginResourcesPath() is supported only in App or Configurator."` for a non-local (server-deployed) `.sscript` package.

package/docs/switch-api/http.md

@@ -0,0 +1,96 @@
+---
+id: http
+category: switch-api
+order: 7
+summary: "`HttpRequest` / `HttpResponse` + webhook pattern"
+triggers:
+  - "Handling incoming HTTP webhooks"
+---
+
+# HttpRequest & HttpResponse Classes
+
+Used in the `httpRequestTriggeredSync` and `httpRequestTriggeredAsync` entry points (see [entry-points.md § Webhooks](entry-points.md#webhooks)). Webhook subscriptions are registered via `s.httpRequestSubscribe()` (see [switch.md § Webhooks](switch.md#webhooks)) in `flowStartTriggered`. Both classes, `HttpRequest.Method`, and the subscribe methods need Switch 21.1+ (see [api-versions.md](api-versions.md)).
+
+## HttpRequest
+
+Represents an incoming webhook HTTP request.
+
+```ts
+request.method: HttpRequest.Method    // "POST" | "PUT" | "DELETE"
+request.path: string                  // relative URL path
+request.query: { [key: string]: string | string[] }   // query string parameters
+request.headers: { [header: string]: string }         // request headers
+request.remoteAddress: string         // client IP address
+request.body: ArrayBuffer | undefined // raw request body
+```
+
+```ts
+request.getBodyAsString(): string
+```
+Returns the raw request body decoded as a UTF-8 string.
+
+## HttpResponse
+
+Used only in `httpRequestTriggeredSync` to send a response before the function returns.
+
+```ts
+response.setStatusCode(statusCode: number): void
+```
+Set the HTTP status code (e.g. `200`, `400`, `500`).
+
+```ts
+response.setHeader(name: string, value: string): void
+```
+Set a response header.
+
+```ts
+response.setBody(data: ArrayBuffer | string): void
+```
+Set the response body.
+
+## HttpRequest.Method enum
+
+| Value | String |
+|---|---|
+| `HttpRequest.Method.POST` | `"POST"` |
+| `HttpRequest.Method.PUT` | `"PUT"` |
+| `HttpRequest.Method.DELETE` | `"DELETE"` |
+
+Available as `EnfocusSwitch.HttpRequest.Method.*` outside `main.ts`.
+
+## Webhook pattern
+
+```ts
+// flowStartTriggered — subscribe once when the flow starts
+async function flowStartTriggered(s: Switch, flowElement: FlowElement): Promise<void> {
+    await s.httpRequestSubscribe(HttpRequest.Method.POST, '/my-path', []);
+}
+
+// flowStopTriggered — unsubscribe when the flow stops
+async function flowStopTriggered(s: Switch, flowElement: FlowElement): Promise<void> {
+    await s.httpRequestUnsubscribe(HttpRequest.Method.POST, '/my-path');
+}
+
+// httpRequestTriggeredSync — handle synchronously, must set response before returning
+async function httpRequestTriggeredSync(request: HttpRequest, args: any[], response: HttpResponse, s: Switch): Promise<void> {
+    const body = request.getBodyAsString();
+    response.setStatusCode(200);
+    response.setHeader('Content-Type', 'application/json');
+    response.setBody(JSON.stringify({ received: true }));
+}
+
+// httpRequestTriggeredAsync — handle asynchronously, no response required
+async function httpRequestTriggeredAsync(request: HttpRequest, args: any[], s: Switch, flowElement: FlowElement): Promise<void> {
+    const body = request.getBodyAsString();
+    // process asynchronously...
+}
+```
+
+## Constraints
+
+- Request body limit: 1 MB (server returns HTTP 413 if exceeded)
+- Queue limit: 10,000 pending requests per element (HTTP 429)
+- Sync handler execution timeout: 1 minute (HTTP 524)
+- Default sync response if none set explicitly: HTTP 200 with body `{"status": true}`
+- Async handler only invoked if sync handler is absent or returned a 2xx status
+- Use unpredictable URL paths for security