@enfocussw/switch-scripting-context 0.1.0

package/docs/switch-api/api-versions.md

@@ -0,0 +1,127 @@
+---
+id: api-versions
+category: switch-api
+order: 25
+summary: "Which Switch release added each scripting API class, method, and enum value; API availability follows the running Switch, not `manifest.xml`"
+triggers:
+  - "Writing or reviewing code for a script or app that must run on a Switch version older than the latest, or when the user names a minimum Switch version"
+---
+
+# API availability by Switch version
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- The running Switch decides which methods exist
+  - Checking at runtime
+- Release names
+- Source and limits of this list
+- Baseline (every Switch version with Node.js scripting)
+- Added per release
+- Declaration changes to existing methods
+<!-- docs-index:contents end -->
+
+## The running Switch decides which methods exist
+
+Each Switch installation ships one copy of the scripting module, and every bundled Node.js version
+uses that same copy. So which API methods a script can call depends on the Switch Server the script
+runs on, not on anything in the script package. A script whose `manifest.xml` says `20.1` runs on
+Node.js 12 in Switch 26.11, and it still gets the full 26.11 API.
+
+The two versions are independent:
+
+| Depends on | Decided by |
+|---|---|
+| Node.js version (language features, Node built-ins) | `SwitchVersion` in `manifest.xml`, looked up by the running Switch. See [node-versions.md](../switch-project/node-versions.md) |
+| Scripting API (classes, methods, enum values below) | The version of the Switch Server the script runs on |
+
+When code must run on an older Switch, check every API call against the tables below for the
+**oldest** Switch version the script or app must support. For an app, that is the version baseline
+from [project-planning.md § Switch version baseline](../switch-project/project-planning.md#switch-version-baseline-apps-only).
+
+### Checking at runtime
+
+`s.getServerVersion()` (Switch 24.0+) returns the running Switch version as a number, e.g. `25.11`.
+It doesn't exist on older Switch versions, so it can't detect those. To use a newer method when
+available and fall back otherwise, test for the method itself:
+
+```ts
+if (typeof job.getVariableAsString === 'function') {
+    // Switch 24.0+
+} else {
+    // fallback for older Switch versions
+}
+```
+
+## Release names
+
+| `SwitchVersion` | Release |
+|---|---|
+| `20.0` | Switch 2020 Spring |
+| `20.1` | Switch 2020 Fall |
+| `21.0` | Switch 2021 Spring |
+| `21.1` | Switch 2021 Fall |
+| `22.0` | Switch 2022 Spring |
+| `22.1` | Switch 2022 Fall |
+| `23.1` | Switch 2023 Fall |
+| `24.0` | Switch 2024 Spring |
+| `24.1` | Switch 2024 Fall |
+| `25.11` | Switch 25.11 |
+| `26.11` | Switch 26.11 |
+
+## Source and limits of this list
+
+The list comes from Enfocus's published type declarations
+(`github.com/enfocus-switch/types-switch-scripting`), diffed from one release's tags to the next.
+Several tags for one release (for example 22.1.0 and 22.1.1) are corrections to the declarations
+for that release, not API changes, so they count as one release. A release with no tag added
+nothing.
+
+- The first tags (1.0.0 and 1.0.1, October 2020) are the baseline. The declarations don't separate
+  Switch 2020 Spring from 2020 Fall, so treat the baseline as available in every Switch version
+  that runs Node.js scripts.
+- Tag 1.1.0 (May 2021) is Switch 2021 Spring. The later tags carry the release number (21.1.x,
+  22.0.x, 22.1.x, 24.0.x, 24.1.x).
+- The declarations end at v24.1.1-final (Switch 2024 Fall). SwitchScriptTool 26.11 still scaffolds
+  that version. A check of the scripting module in a pre-release Switch build found no public class,
+  method, or enum value that v24.1.1 lacks, and 26.11 adds no scripting API. So nothing was added in
+  23.1, 25.11, or 26.11.
+- Entry points aren't part of the type declarations, so this list doesn't record when each entry
+  point appeared. The webhook entry points (`httpRequestTriggeredSync`/`Async`) need
+  `s.httpRequestSubscribe()`, so they can't be used before Switch 21.1 either.
+
+## Baseline (every Switch version with Node.js scripting)
+
+| Class | Members |
+|---|---|
+| `Switch` | `getGlobalData`, `setGlobalData`, `removeGlobalData` (including the `lock` parameter) |
+| `FlowElement` | `getPropertyStringValue`, `getPropertyType`, `getPropertyDisplayName`, `hasProperty`, `getOutConnections`, `setTimerInterval`, `log`, `failProcess`, `createJob`, `getPluginResourcesPath` |
+| `Job` | `getName`, `getId`, `isFile`, `isFolder`, `get`, `sendToNull`, `sendToSingle`, `sendTo`, `sendToData`, `sendToLog`, `fail`, `log`, `createChild`, `getPrivateData`, `setPrivateData`, `removePrivateData`, `listDatasets`, `createDataset`, `getDataset`, `removeDataset` |
+| `Connection` | `getId`, `getName`, `getPropertyStringValue`, `getPropertyType`, `getPropertyDisplayName`, `hasProperty` |
+| Enums | `AccessLevel` (all), `Connection.Level` (all), `PropertyType` (all), `LogLevel.Info`/`Warning`/`Error`, `DatasetModel.Opaque`/`XML`/`XMP`/`JDF`, `Scope.Element`/`FlowElement`/`Global` |
+
+## Added per release
+
+| Release | Added |
+|---|---|
+| 21.0 | `flowElement.getJobs()`; `PdfDocument` and `PdfPage` (whole classes); `EnfocusSwitchPrivateDataTag` with `hierarchy`, `emailAddresses`, `emailBody`, `userName`, `userFullName`, `userEmail`, `origin`; `LogLevel.Debug` |
+| 21.1 | `flowElement.getName()`; `HttpRequest` and `HttpResponse` (whole classes, including `HttpRequest.Method`); `s.httpRequestSubscribe()`, `s.httpRequestUnsubscribe()`; `ImageDocument` (whole class, including `ImageDocument.ColorMode` and `ImageDocument.ColorSpace`); `EnfocusSwitchPrivateDataTag.initiated`, `.submittedTo` |
+| 22.0 | `flowElement.getFlowName()`; `Switch.tr()`; `XmlDocument` (whole class); `Scope.Flow`, `Scope.FlowElements`; `DatasetModel.JSON` |
+| 22.1 | `job.getPriority()`, `job.setPriority()`, `Priority` enum; `job.sendToChannel()`, `flowElement.subscribeToChannel()`; `job.processLater()`; `s.setAbortData()`; `XmpDocument` (whole class), `pdfDocument.getXMP()`; `EnfocusSwitchPrivateDataTag.state` |
+| 23.1 | Nothing |
+| 24.0 | `flowElement.getScriptDataPath()`, `flowElement.createPathWithName()`; `job.getVariableAsString()`, `job.getxmlData()`, `job.getxmpData()`, `job.getJdfData()`, `job.getJSONData()`; `s.getPreferenceSetting()`, `s.getServerVersion()`; `NoYesListPropertyStringValue` |
+| 24.1 | `connection.getType()`, `connection.getFileCount()`, `flowElement.getFileCount()` |
+| 25.11, 26.11 | Nothing |
+
+## Declaration changes to existing methods
+
+These signatures changed between releases in the declarations. The declarations don't say whether
+older runtimes enforced the older signature, so when targeting a release before the change, write
+code that satisfies both.
+
+- Before 21.0, private data and global data values were declared as `string`; from 21.0 they are
+  `any`. On 20.x, store strings (for example `JSON.stringify` the value) and parse them on read.
+- Before 21.0, `job.fail()` declared `messageParams` as required. On 20.x, pass an array, even an
+  empty one.
+- Before 22.1, `flowElement.failProcess()` declared `messageParam` as a required `string`. On an
+  older Switch, pass a string.

package/docs/switch-api/connection.md

@@ -0,0 +1,82 @@
+---
+id: connection
+category: switch-api
+order: 6
+summary: "`Connection`: type, properties, file count"
+triggers:
+  - "Routing to specific connections or reading connection properties"
+---
+
+# Connection Class
+
+A `Connection` represents an outgoing connection from the flow element. Obtain instances via `flowElement.getOutConnections()`.
+
+## Identity
+
+```ts
+connection.getId(): string
+```
+Unique ID for the connection. Stable across deactivate/reactivate, Switch restarts, holding/releasing connections, and renaming the flow itself. Changes on export/re-import, a flow upgrade, or renaming the flow *element* (not the flow).
+
+```ts
+connection.getName(): string
+```
+Display name as shown on the canvas. May be an empty string.
+
+```ts
+// Switch 24.1+
+connection.getType(): string
+```
+Connection type. One of: `"Move"`, `"Filter"`, `"Traffic-data"`, `"Traffic-log"`, `"Traffic-datawithlog"`.
+
+## Connection properties
+
+Connection properties are declared in the script's XML declaration (`ConnectionFields`) and configured per-connection in the canvas. See [script-declaration.md](../switch-project/script-declaration.md) for how to declare them (via SwitchScripter).
+
+```ts
+connection.getPropertyStringValue(tag: string): Promise<string | string[]>
+```
+Returns the connection property value as a string. 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.
+
+This is **not** how to check which traffic light level(s) a connection accepts before calling `job.sendToData()` — `"Success"`/`"Warning"`/`"Error"` are not property tags, so passing one throws the same invalid-tag error. There is no supported way to check in advance; see [Connection.Level enum](#connectionlevel-enum) below.
+
+```ts
+connection.getPropertyType(tag: string): PropertyType
+```
+Returns the `PropertyType` of the property.
+
+```ts
+connection.getPropertyDisplayName(tag: string): string
+```
+Returns the English display name of the property (for use in log messages).
+
+```ts
+connection.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.
+
+## File count
+
+```ts
+// Switch 24.1+
+connection.getFileCount(nested?: boolean): Promise<number>
+```
+Returns the number of files in the folder at the other end of this connection. If `nested` is `false`, counts only direct children; if `true` (the default, so it can be omitted), counts recursively (subfolders themselves are not counted).
+
+## Connection.Level enum
+
+Used with `job.sendToData()` and `job.sendToLog()` to select which traffic light connection a job routes to.
+
+| Value | String |
+|---|---|
+| `Connection.Level.Success` | `"success"` |
+| `Connection.Level.Warning` | `"warning"` |
+| `Connection.Level.Error` | `"error"` |
+
+Available as `EnfocusSwitch.Connection.Level.*` outside `main.ts`.
+
+**Traffic light levels are not a readable connection property.** `flowElement.getOutConnections()`
+returns the outgoing `Connection` objects, but the supported API has no way to determine which
+level(s) a given connection accepts. Don't call `connection.getPropertyStringValue("Success")`, `"Warning"`, or `"Error"` expecting to
+read this back; those are not valid property tags for a traffic light connection. To route
+optionally, see [job-patterns.md § Sending jobs](job-patterns.md#sending-jobs).

package/docs/switch-api/document-classes.md

@@ -0,0 +1,189 @@
+---
+id: document-classes
+category: switch-api
+order: 9
+summary: "`PdfDocument`, `PdfPage`, `ImageDocument`, `XmlDocument`, `XmpDocument`: read-only file introspection"
+triggers:
+  - "Inspecting PDF, image, XML, or XMP file contents"
+---
+
+# Document Classes
+
+Read-only document introspection utilities. All methods may throw — wrap in `try/catch`. Load this file when working with PDF, image, XML, or XMP documents.
+
+Each class needs a minimum Switch version: `PdfDocument` and `PdfPage` 21.0+, `ImageDocument` 21.1+, `XmlDocument` 22.0+, `XmpDocument` and `doc.getXMP()` 22.1+.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- PdfDocument
+  - Static page dimension methods
+- PdfPage
+- ImageDocument
+- XmlDocument
+- XmpDocument
+<!-- docs-index:contents end -->
+
+## PdfDocument
+
+Open a PDF to inspect metadata and page geometry.
+
+```ts
+PdfDocument.open(path: string): PdfDocument
+```
+Opens the PDF. Call `close()` when done.
+
+```ts
+doc.close(): void
+```
+
+```ts
+doc.getNumberOfPages(): number
+PdfDocument.getNumberOfPages(path: string): number
+```
+
+```ts
+doc.getPDFVersion(): string                        // e.g. "1.6"
+PdfDocument.getPDFVersion(path: string): string
+
+doc.getPDFXVersion(): string                       // empty string if not PDF/X
+PdfDocument.getPDFXVersion(path: string): string
+
+doc.getSecurityMethod(): string
+PdfDocument.getSecurityMethod(path: string): string
+
+doc.getPage(pageNumber?: number): PdfPage          // 1-based; defaults to page 1
+doc.getXMP(): XmpDocument                          // Switch 22.1+
+```
+
+### Static page dimension methods
+
+All take `(path: string, pageNumber?: number, effective?: boolean)` — page numbers are 1-based, `effective` defaults to `true` (applies rotation and scaling). All return `number` in points.
+
+| Method | Description |
+|---|---|
+| `PdfDocument.getPageHeight` | Alias for media box height |
+| `PdfDocument.getPageWidth` | Alias for media box width |
+| `PdfDocument.getPageMediaBoxHeight` / `Width` | Media box |
+| `PdfDocument.getPageCropBoxHeight` / `Width` | Crop box |
+| `PdfDocument.getPageBleedBoxHeight` / `Width` | Bleed box |
+| `PdfDocument.getPageTrimBoxHeight` / `Width` | Trim box |
+| `PdfDocument.getPageArtBoxHeight` / `Width` | Art box — **known issue:** currently returns the crop box value instead (not expected to be fixed soon) |
+
+```ts
+PdfDocument.getPageRotation(path: string, pageNumber?: number): number   // degrees
+PdfDocument.getPageScaling(path: string, pageNumber?: number): number
+PdfDocument.getPageLabel(path: string, pageNumber?: number): string      // empty if none
+```
+
+---
+
+## PdfPage
+
+Obtained via `PdfDocument.getPage()`. Instance-level page geometry. All dimensions in points.
+
+```ts
+page.getHeight(effective?: boolean): number      // alias for getMediaBoxHeight
+page.getWidth(effective?: boolean): number       // alias for getMediaBoxWidth
+
+page.getMediaBoxHeight(effective?: boolean): number
+page.getMediaBoxWidth(effective?: boolean): number
+page.getCropBoxHeight(effective?: boolean): number
+page.getCropBoxWidth(effective?: boolean): number
+page.getBleedBoxHeight(effective?: boolean): number
+page.getBleedBoxWidth(effective?: boolean): number
+page.getTrimBoxHeight(effective?: boolean): number
+page.getTrimBoxWidth(effective?: boolean): number
+page.getArtBoxHeight(effective?: boolean): number   // known issue: currently returns the crop box value
+page.getArtBoxWidth(effective?: boolean): number    // known issue: currently returns the crop box value
+
+page.getRotation(): number    // degrees
+page.getScaling(): number
+page.getPageLabel(): string   // empty if none
+```
+
+`effective` defaults to `true` — applies rotation and scaling.
+
+---
+
+## ImageDocument
+
+Supported formats: JPEG, TIFF, PNG. Reads values from EXIF and XMP.
+
+**`open` is async** — use `await`:
+
+```ts
+const img = await ImageDocument.open(path);
+// ...
+img.close();
+```
+
+All static methods also return `Promise<T>`.
+
+```ts
+ImageDocument.open(path: string): Promise<ImageDocument>
+img.close(): void
+
+img.getWidth(): number
+ImageDocument.getWidth(path: string): Promise<number>
+
+img.getHeight(): number
+ImageDocument.getHeight(path: string): Promise<number>
+
+img.getColorMode(): ImageDocument.ColorMode
+ImageDocument.getColorMode(path: string): Promise<ImageDocument.ColorMode>
+
+img.getColorSpace(): ImageDocument.ColorSpace
+ImageDocument.getColorSpace(path: string): Promise<ImageDocument.ColorSpace>
+
+img.getICCProfile(): string              // Photoshop, falling back to the EXIF ProfileDescription if absent
+ImageDocument.getICCProfile(path: string): Promise<string>
+
+img.getSamplesPerPixel(): number
+ImageDocument.getSamplesPerPixel(path: string): Promise<number>
+```
+
+See [enums.md](enums.md) for `ImageDocument.ColorMode` and `ImageDocument.ColorSpace` values.
+
+---
+
+## XmlDocument
+
+XPath 1.0 queries against XML files or strings.
+
+```ts
+XmlDocument.open(path: string): XmlDocument
+XmlDocument.parse(xmlString: string): XmlDocument
+
+doc.evaluate(xpath: string, prefixMap?: { [prefix: string]: string }): boolean | number | string | object | undefined
+doc.getDefaultNSMap(): { [prefix: string]: string }
+```
+
+XPath does not support default namespaces — always use a prefix. `getDefaultNSMap()` returns all namespace mappings occurring in the document; the default namespace (if any) is accessible via the special prefixes `default_switch_ns`, `dn`, and `jdf`. `evaluate()` can also return an `object` (e.g. a node-set result), not just the primitive types.
+
+```ts
+const doc = XmlDocument.open(path);
+const map = doc.getDefaultNSMap();
+const result = doc.evaluate('/dn:root/dn:item/@id', map);
+```
+
+---
+
+## XmpDocument
+
+Evaluate XMP location paths (not XPath) against XMP-only files. Obtained from `PdfDocument.getXMP()` or opened directly.
+
+> **Note**: `open()` requires an XMP-only file — do not pass a PDF or image path.
+
+```ts
+XmpDocument.open(path: string): XmpDocument
+
+doc.evaluate(
+    xmpLocationPath: string,
+    additionalPrefixMap?: { [prefix: string]: string }
+): boolean | number | string | undefined
+
+doc.save(path: string): void
+```
+
+If `additionalPrefixMap` is omitted, the default prefix map (all standard XMP namespaces plus any extras in the file) is used.

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

@@ -0,0 +1,185 @@
+---
+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.
+
+<!-- docs-index:contents begin -->
+## Contents
+
+- Entry-point scanner constraints
+- Flow lifecycle
+- Timer
+- Job processing
+- Webhooks
+- Script expression
+- Property UI callbacks
+<!-- docs-index:contents end -->
+
+## 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)`, called from inside `timerFired`; calling it from any other entry point has no effect (see [flow-element.md § Timer](flow-element.md#timer)). 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+). Applies to: `jobArrived`, `timerFired`, `httpRequestTriggeredSync`, `httpRequestTriggeredAsync`, `flowStartTriggered`, `flowStopTriggered`.
+
+**The timeout for `jobArrived` and `timerFired` is the flow element's "Abort after (minutes)" property (`AbortTimeoutMinutes`), not 60 seconds.** Left at `Default`, it takes the Switch preference Error handling > "Abort processes after (minutes)". While the element is in debug mode, Switch never aborts it. The 60-second figure applies only to `abort` itself: it gets at most 60 seconds, after which the script executor is killed.
+
+## 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).