@enfocussw/switch-scripting-context 25.11.0-beta.9 → 25.11.1-beta.1

package/docs/switch-api/entry-points.md

@@ -0,0 +1,171 @@
+---
+id: entry-points
+category: switch-api
+order: 2
+summary: "All entry point signatures, constraints, and when each is called"
+triggers:
+  - "Scaffolding a script, adding/editing an entry point, or making any edit to main.ts/main.js"
+---
+
+# Switch Script Entry Points
+
+Entry points are top-level `async` functions with specific names. They are **not exported**. Switch calls them automatically based on flow events.
+
+## Entry-point scanner constraints
+
+Switch discovers a script's entry points by regex, not by parsing. Before matching
+`function\s+(name)\s*\(` it strips comments and literals with a regex that doesn't understand JS
+escaping. Certain source shapes make that strip regex delete large spans of real code — and every
+`function` declaration inside the deleted span becomes invisible to Switch, whether or not that
+function is itself well-formed.
+
+This applies to **every** entry point on this page, not only the four checked below — a swallowed
+`validateProperties` or `getLibraryForProperty` fails silently (the callback just never runs, no
+error anywhere), which is worse than the loud failure the four below produce. The one exception is
+`calculateScriptExpression`: it's invoked directly at runtime rather than through this scanner, so
+it isn't at risk.
+
+If none of `jobArrived`, `timerFired`, `flowStopTriggered`, `httpRequestTriggeredAsync` survives,
+Switch fails with `Cannot open script '<name>': no entry points found` — `httpRequestTriggeredSync`
+alone does not satisfy this check. Both the packed `.sscript` (the entry-point list is baked in at
+pack time) and the unpacked script folder (`main.js` is rescanned by this same scanner every time
+Switch loads it, e.g. running or debugging from Designer) are affected. Packing does not validate
+or warn about any of this — a script that packs cleanly can still fail to load.
+
+**Rules for writing entry points in `main.ts`/`main.js`:**
+
+1. Never write a string literal whose content ends with a backslash: `"\\"`, `'\\'`, `` `\\` ``,
+   `"C:\\Temp\\"`. This is the highest-frequency trigger — the strip regex hunts for the next
+   matching quote character anywhere later in the file to close the literal (a backslash right
+   before the real closing quote makes it skip past that quote), and deletes everything in between.
+   Use `"\x5c"`, `"\u005C"`, `String.fromCharCode(92)`, or restructure (e.g.
+   `JSON.stringify(v).slice(1, -1)` for backslash/quote escaping) instead. A backslash elsewhere in
+   the literal is fine: `"\\n is newline"`, `"a\\b"`.
+2. Avoid regex literals — including ones that look properly closed, like `/[^/]+/` (a character
+   class containing an unescaped `/`). The strip regex doesn't understand character classes, so it
+   closes the "literal" early at the inner `/` and leaves a dangling `/` that swallows forward to
+   the next `/` anywhere later in the file. Use `new RegExp("...")` instead.
+3. Avoid division that isn't in the plain `word / word` shape. `a / b` is recognised and stripped
+   safely; `) / 2`, `] / 2`, and `/=` are not, and the leftover `/` swallows forward exactly like an
+   unclosed regex literal. Rewrite as `Math.floor(x / y)` with plain identifiers, or hoist to a
+   named variable first.
+4. Declare every entry point with the literal `function` keyword at top level:
+   `function jobArrived(...)` or `async function jobArrived(...)`. Arrow functions,
+   `exports.jobArrived = function (...)`, and class methods are invisible to the scanner.
+5. Entry-point names are matched case-sensitively. `JobArrived` is silently dropped during
+   extraction — if another valid entry point is also present the script packs and loads without
+   error, the misnamed function just never runs.
+
+See [tooling.md § Verify entry points before packing](../switch-project/tooling.md#verify-entry-points-before-packing)
+for a script to catch this before it reaches Switch.
+
+## Flow lifecycle
+
+```ts
+async function flowStartTriggered(s: Switch, flowElement: FlowElement): Promise<void>
+```
+Called when the flow starts. Use to subscribe to webhooks (`s.httpRequestSubscribe`) or channels (`flowElement.subscribeToChannel`). Cannot coexist with `timerFired` or `jobArrived` as the sole entry point. May execute in parallel for concurrent elements. Not available for debugging.
+
+```ts
+async function flowStopTriggered(s: Switch, flowElement: FlowElement): Promise<void>
+```
+Called when the flow stops. May execute in parallel for concurrent elements. Not available for debugging.
+
+## Timer
+
+```ts
+async function timerFired(s: Switch, flowElement: FlowElement): Promise<void>
+```
+Called on a recurring timer. First fires after `flowStartTriggered`. Set the interval via `flowElement.setTimerInterval(seconds)`. Cannot coexist with `flowStartTriggered` as the sole entry point.
+
+Required when `IncomingConnections="No"`; optional (alongside `jobArrived`) when
+`IncomingConnections="Yes"`. Never leave it present but empty — remove it entirely if it does
+nothing.
+
+## Job processing
+
+```ts
+async function jobArrived(s: Switch, flowElement: FlowElement, job: Job): Promise<void>
+```
+Called when a job arrives. Must eventually call a `job.sendTo*()` or `job.fail()`. Can run concurrently if configured in the script XML declaration.
+
+`jobArrived` and `timerFired` presence must match the declared connections — present when
+`IncomingConnections="Yes"` (`timerFired` may additionally be present); when
+`IncomingConnections="No"`, `timerFired` must be present instead. See
+[script-declaration.md](../switch-project/script-declaration.md#built-in-elementfields). Never leave an empty
+`jobArrived` or `timerFired` in the script — remove the function entirely if it does nothing.
+
+**Gotcha: a flow restart replays every queued job through `jobArrived` again.** This includes a job
+whose real processing was deferred elsewhere, such as a job registered in global data and actually
+handled later in `timerFired`. `jobArrived` does not skip a job just because it was already
+registered on a previous run; if the element still has a large backlog queued when the flow
+restarts, every one of those jobs fires `jobArrived` again, and working through a long backlog this
+way can take a long time even when each invocation only needs to recognize the job as already
+registered and return. A script that defers processing this way must check global data at the top
+of `jobArrived` and return immediately for a job already registered there, rather than assuming
+`jobArrived` fires exactly once per job.
+
+```ts
+async function abort(s: Switch, flowElement: FlowElement, job: Job, abortData: any): Promise<void>
+```
+Called when an entry point exceeds its configured timeout. The `abortData` value was set beforehand via `s.setAbortData()` (Switch 22.1+). Maximum execution: 60 seconds, after which the script executor is killed. Applies to: `jobArrived`, `timerFired`, `httpRequestTriggeredSync`, `httpRequestTriggeredAsync`, `flowStartTriggered`, `flowStopTriggered`.
+
+## Webhooks
+
+Both webhook entry points need Switch 21.1+, the first release with `s.httpRequestSubscribe()`.
+
+```ts
+async function httpRequestTriggeredSync(request: HttpRequest, args: any[], response: HttpResponse, s: Switch): Promise<void>
+```
+Synchronous webhook handler. A response **must** be sent before the function returns. Registered via `s.httpRequestSubscribe()` in `flowStartTriggered`. Executes in concurrent mode. Request body limit: 1 MB (HTTP 413). Queue limit: 10,000 pending requests (HTTP 429). Execution timeout: 1 minute (HTTP 524). Default response if none set: HTTP 200 with `{"status": true}`.
+
+```ts
+async function httpRequestTriggeredAsync(request: HttpRequest, args: any[], s: Switch, flowElement: FlowElement): Promise<void>
+```
+Asynchronous webhook handler. No response is required. Registered via `s.httpRequestSubscribe()` in `flowStartTriggered`. Only invoked if `httpRequestTriggeredSync` is not defined, or if the sync handler returned a 2xx status.
+
+## Script expression
+
+```ts
+async function calculateScriptExpression(s: Switch, flowElement: FlowElement, job: Job): Promise<string | number | boolean>
+```
+Called to evaluate a script expression for the flow element. The return value is used as the expression result.
+
+## Property UI callbacks
+
+Not available for debugging.
+
+```ts
+async function getLibraryForProperty(s: Switch, flowElement: FlowElement, tag: string): Promise<string[]>
+```
+Returns a dynamic list of values for a property's library dropdown. Mandatory if any property uses
+the `askplugin`/`askplugin2` editor (see
+[property-editors.md](../switch-project/property-editors.md#modal-editors)). Log an error via `flowElement.log()`
+if the list would otherwise come back empty, so the user can see why the dropdown has nothing in it.
+
+```ts
+async function getLibraryForConnectionProperty(s: Switch, flowElement: FlowElement, c: Connection, tag: string): Promise<string[]>
+```
+Returns a dynamic list of values for a connection property's library dropdown. Same guidance as
+`getLibraryForProperty` above, for connection fields using `askplugin`/`askplugin2`.
+
+```ts
+async function validateProperties(s: Switch, flowElement: FlowElement, tags: string[]): Promise<{ tag: string, valid: boolean }[]>
+```
+Validates one or more property values. Return one result object per tag. Mandatory if any property
+declares `Validation="Custom"` or `"Standard and custom"` (see
+[script-declaration.md](../switch-project/script-declaration.md#custom-property-elements-elementfields)). Log
+an error via `flowElement.log()` for any tag returned with `valid: false`, so the user sees why.
+
+```ts
+async function validateConnectionProperties(s: Switch, flowElement: FlowElement, c: Connection, tags: string[]): Promise<{ tag: string, valid: boolean }[]>
+```
+Validates one or more connection property values. Same guidance as `validateProperties` above, for
+connection fields declaring `Validation="Custom"`/`"Standard and custom"`.
+
+```ts
+async function findExternalEditorPath(s: Switch, flowElement: FlowElement, tag: string): Promise<string>
+```
+Resolves the path to an external editor for a property. Required whenever the
+`external`/`external2`/… editor is used, unless the dependent `Application` property is non-empty —
+see [property-editors.md § Notes](../switch-project/property-editors.md#notes).

package/docs/switch-api/{api-enums.md → enums.md}

@@ -1,6 +1,15 @@
+---
+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).
+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).
 
 ## LogLevel
 
@@ -11,7 +20,7 @@ Used with `job.log()` and `flowElement.log()`.
 | `LogLevel.Info` | `"info"` |
 | `LogLevel.Warning` | `"warning"` |
 | `LogLevel.Error` | `"error"` |
-| `LogLevel.Debug` | `"debug"` |
+| `LogLevel.Debug` | `"debug"` (Switch 21.0+) |
 
 ## AccessLevel
 
@@ -32,7 +41,7 @@ Used with `job.createDataset()`, `job.sendToLog()`, and `job.listDatasets()`.
 | `DatasetModel.XML` | `"XML"` |
 | `DatasetModel.XMP` | `"XMP"` |
 | `DatasetModel.JDF` | `"JDF"` |
-| `DatasetModel.JSON` | `"JSON"` |
+| `DatasetModel.JSON` | `"JSON"` (Switch 22.0+) |
 
 ## Scope
 
@@ -41,14 +50,14 @@ Used with `s.getGlobalData()`, `s.setGlobalData()`, `s.removeGlobalData()`.
 | Value | String |
 |---|---|
 | `Scope.Element` | `"element"` |
-| `Scope.Flow` | `"flow"` |
+| `Scope.Flow` | `"flow"` (Switch 22.0+) |
 | `Scope.FlowElement` | `"flowElement"` |
-| `Scope.FlowElements` | `"flowElements"` |
+| `Scope.FlowElements` | `"flowElements"` (Switch 22.0+) |
 | `Scope.Global` | `"global"` |
 
 ## Priority
 
-Used with `job.setPriority()` / `job.getPriority()`.
+Used with `job.setPriority()` / `job.getPriority()`. Switch 22.1+.
 
 | Value | Number |
 |---|---|
@@ -68,11 +77,13 @@ Used with `job.sendToData()` and `job.sendToLog()` for traffic light connections
 | `Connection.Level.Warning` | `"warning"` |
 | `Connection.Level.Error` | `"error"` |
 
-Also available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`.
+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()`.
+Used with `s.httpRequestSubscribe()` and `s.httpRequestUnsubscribe()`. Switch 21.1+.
 
 | Value | String |
 |---|---|
@@ -103,7 +114,7 @@ Returned by `flowElement.getPropertyType()` and `connection.getPropertyType()`.
 
 ## NoYesListPropertyStringValue
 
-Convenience for `Boolean`-typed properties returned as strings.
+Convenience for `Boolean`-typed properties returned as strings. Switch 24.0+.
 
 | Value | String |
 |---|---|
@@ -112,7 +123,7 @@ Convenience for `Boolean`-typed properties returned as strings.
 
 ## EnfocusSwitchPrivateDataTag
 
-Well-known tags for `job.getPrivateData()` / `job.setPrivateData()`.
+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 |
 |---|---|
@@ -129,7 +140,7 @@ Well-known tags for `job.getPrivateData()` / `job.setPrivateData()`.
 
 ## ImageDocument.ColorMode
 
-Used with `ImageDocument.getColorMode()`. Available as `EnfocusSwitch.ImageDocument.ColorMode.*` outside `main.ts`.
+Used with `ImageDocument.getColorMode()`. Available as `EnfocusSwitch.ImageDocument.ColorMode.*` outside `main.ts`. Switch 21.1+.
 
 | Value | String |
 |---|---|
@@ -145,7 +156,7 @@ Used with `ImageDocument.getColorMode()`. Available as `EnfocusSwitch.ImageDocum
 
 ## ImageDocument.ColorSpace
 
-Used with `ImageDocument.getColorSpace()`. Available as `EnfocusSwitch.ImageDocument.ColorSpace.*` outside `main.ts`.
+Used with `ImageDocument.getColorSpace()`. Available as `EnfocusSwitch.ImageDocument.ColorSpace.*` outside `main.ts`. Switch 21.1+.
 
 | Value | String |
 |---|---|

package/docs/switch-api/{api-execution-environment.md → execution-environment.md}

@@ -1,13 +1,38 @@
+---
+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. These are
-consequences of the host process model, not things a script configures — understanding them avoids
-subtle bugs around state persistence and error handling.
+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.
+
+## 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. `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` (see
-[Execution modes](api-script-structure.md#execution-modes)) and the pool of Node.js processes that
+`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:
 
@@ -23,7 +48,7 @@ them:
   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](api-job-patterns.md#executor-cleanup-thresholds)).
+  [Executor cleanup thresholds](job-patterns.md#executor-cleanup-thresholds)).
 
 ## Module-level state persists across jobs on the same executor
 
@@ -46,25 +71,27 @@ underlying executor process is **not** killed and continues serving subsequent j
 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
-[api-logging.md](api-logging.md)) rather than letting a promise reject unhandled.
+[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](api-entry-points.md#script-expression)) cannot use third-party npm modules
+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](api-script-structure.md#script-folder-files)).
+[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; this bundling path does not support
+Scripts with ESM dependencies are bundled before execution, when `SwitchVersion` in `manifest.xml`
+is `24.0` or higher (see
+[script-structure.md § Other effects of `SwitchVersion`](../switch-project/script-structure.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](api-entry-points.md#job-processing) and
-[Executor cleanup thresholds](api-job-patterns.md#executor-cleanup-thresholds)), there is no
+[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/{api-flow-element.md → flow-element.md}

@@ -1,3 +1,12 @@
+---
+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.
@@ -5,11 +14,13 @@ The `FlowElement` instance `flowElement` is passed to every entry point that ope
 ## 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.
@@ -21,11 +32,11 @@ Properties are configured by the user in the Switch canvas and declared in the s
 ```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 a hidden dependent property. See [api-property-editors.md](api-property-editors.md) for editor types and their return value formats.
+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). 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)`.
+> **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+).
 
 ```ts
 flowElement.getPropertyType(tag: string): PropertyType
@@ -40,7 +51,7 @@ 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.
+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
 
@@ -58,7 +69,7 @@ Sets the interval between `timerFired` invocations. Default is 300 s. The actual
 
 ## Logging
 
-See [api-logging.md](api-logging.md) for log level semantics and logging practice.
+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>
@@ -68,16 +79,17 @@ Logs a message for the flow element. Use `%1`, `%2`, etc. in the message string
 ```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`. Throws `"Job routing is not allowed in this entry point."` if called from an entry point where routing isn't permitted.
+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)
 
 ```ts
 flowElement.createJob(path: string): Promise<Job>
 ```
-Creates a new job from an existing file/folder path. Valid only in `jobArrived` and `timerFired`. The new job has default properties (no parent). The caller is responsible for cleaning up the source file after routing. See [api-job-patterns.md](api-job-patterns.md) for temp file cleanup rules and routing constraints.
+Creates a new job from an existing file/folder path. Valid only in `jobArrived` and `timerFired`. 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.
@@ -85,6 +97,7 @@ Returns up to 10,000 waiting jobs by ID. Throws if `ids` is not an array, is emp
 ## 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`.
@@ -92,16 +105,19 @@ Subscribes to a channel to receive jobs from it. Only one subscriber per channel
 ## 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.
+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.

package/docs/switch-api/{api-http.md → http.md}

@@ -1,6 +1,15 @@
+---
+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. Webhook subscriptions are registered via `s.httpRequestSubscribe()` in `flowStartTriggered`.
+Used in the `httpRequestTriggeredSync` and `httpRequestTriggeredAsync` entry points. Webhook subscriptions are registered via `s.httpRequestSubscribe()` in `flowStartTriggered`. Both classes, `HttpRequest.Method`, and the subscribe methods need Switch 21.1+.
 
 ## HttpRequest