@enfocussw/switch-scripting-context 25.11.0-beta.10

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

@@ -0,0 +1,51 @@
+# Debugging Scripts
+
+Debugging requires configuring the Script element in Switch Designer — the agent cannot do this directly but can guide the user through the steps.
+
+## Constraints
+
+- Only works with script folders and non-password-protected packages
+- Only one script can be in debug mode at a time
+- Execution mode is forced to Serialized while debug is enabled
+- Only these four entry points can be debugged: `jobArrived`, `timerFired`, `httpRequestTriggeredAsync`, `findExternalEditorPath`
+
+## Enabling debug mode in Switch Designer
+
+In the Script element properties, once a script folder or package is selected, three extra properties appear:
+
+| Property | Value |
+|---|---|
+| Enable debug mode | Yes |
+| Port | 9229 (default) |
+| Debug entry points | Select from the supported entry points above |
+
+## Attaching VS Code
+
+**Script folder:** Open the script folder in VS Code and press F5. The `.vscode/launch.json` created by `SwitchScriptTool --create` is pre-configured for attach mode.
+
+**Package (no `launch.json`):** Create `launch.json` manually:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "attach",
+      "name": "Attach",
+      "port": 9229,
+      "skipFiles": ["<node_internals>/**"]
+    }
+  ]
+}
+```
+
+Use the port number set in the Script element properties.
+
+After attaching, VS Code stops in internal Switch code first — press F5 once more to reach the script entry point. Set breakpoints anywhere in the entry point being debugged.
+
+## Critical warning
+
+**Disable debug mode in Switch Designer when the debug session is finished.**
+
+If left enabled, the flow hangs silently — `jobArrived` leaves jobs stuck in the input folder, other entry points hang with no visible error or indication.

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

@@ -0,0 +1,167 @@
+# 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.
+
+## 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
+```
+
+### 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 [api-enums.md](api-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/api-entry-points.md

@@ -0,0 +1,82 @@
+# 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.
+
+## 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.
+
+## 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.
+
+```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()`. Maximum execution: 60 seconds, after which the script executor is killed. Applies to: `jobArrived`, `timerFired`, `httpRequestTriggeredSync`, `httpRequestTriggeredAsync`, `flowStartTriggered`, `flowStopTriggered`.
+
+## Webhooks
+
+```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.
+
+```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.
+
+```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.
+
+```ts
+async function validateConnectionProperties(s: Switch, flowElement: FlowElement, c: Connection, tags: string[]): Promise<{ tag: string, valid: boolean }[]>
+```
+Validates one or more connection property values.
+
+```ts
+async function findExternalEditorPath(s: Switch, flowElement: FlowElement, tag: string): Promise<string>
+```
+Resolves the path to an external editor for a property.

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

@@ -0,0 +1,153 @@
+# 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).
+
+## LogLevel
+
+Used with `job.log()` and `flowElement.log()`.
+
+| Value | String |
+|---|---|
+| `LogLevel.Info` | `"info"` |
+| `LogLevel.Warning` | `"warning"` |
+| `LogLevel.Error` | `"error"` |
+| `LogLevel.Debug` | `"debug"` |
+
+## 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"` |
+
+## Scope
+
+Used with `s.getGlobalData()`, `s.setGlobalData()`, `s.removeGlobalData()`.
+
+| Value | String |
+|---|---|
+| `Scope.Element` | `"element"` |
+| `Scope.Flow` | `"flow"` |
+| `Scope.FlowElement` | `"flowElement"` |
+| `Scope.FlowElements` | `"flowElements"` |
+| `Scope.Global` | `"global"` |
+
+## Priority
+
+Used with `job.setPriority()` / `job.getPriority()`.
+
+| 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`.
+
+## HttpRequest.Method
+
+Used with `s.httpRequestSubscribe()` and `s.httpRequestUnsubscribe()`.
+
+| 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.
+
+| Value | String |
+|---|---|
+| `NoYesListPropertyStringValue.No` | `"No"` |
+| `NoYesListPropertyStringValue.Yes` | `"Yes"` |
+
+## EnfocusSwitchPrivateDataTag
+
+Well-known tags for `job.getPrivateData()` / `job.setPrivateData()`.
+
+| 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`.
+
+| 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`.
+
+| Value | String |
+|---|---|
+| `ImageDocument.ColorSpace.SRGB` | `"sRGB"` |
+| `ImageDocument.ColorSpace.Uncalibrated` | `"uncalibrated"` |

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

@@ -0,0 +1,70 @@
+# 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.
+
+## Two independent concurrency tiers
+
+`NumberOfSlots`/`ExecutionGroup` (see
+[Execution modes](api-script-structure.md#execution-modes)) 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](api-job-patterns.md#executor-cleanup-thresholds)).
+
+## Module-level state persists across jobs on the same executor
+
+Because executor processes are long-lived and reused, any state held outside an entry point function
+— module-level `let`/`const`/`var`, an in-memory cache, a counter — can survive from one job
+invocation to the next if the same executor happens to service both. It is **not** reset before each
+`jobArrived`/`timerFired`/etc. call, and which executor services a given job is not something a
+script controls or can predict. This is useful for caching (e.g. a parsed config file, a pooled
+connection) but also a common source of bugs: don't assume module-level state starts fresh for every
+job, and don't assume it's shared with an *arbitrary* other job either — reset explicitly at the
+start of an entry point if a fresh value is required per job.
+
+`getInitialize()`/`getFinalize()` (if the script uses them) run once per script per process
+lifetime, not once per job — the same caveat applies to anything they set up.
+
+## 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
+[api-logging.md](api-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
+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)).
+
+## Native (binary) addons are not supported
+
+Scripts with ESM dependencies are bundled before execution; 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
+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

@@ -0,0 +1,112 @@
+# 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.
+
+## Identity
+
+```ts
+flowElement.getName(): string
+```
+Returns the name of this flow element.
+
+```ts
+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 a hidden dependent property. See [api-property-editors.md](api-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)`.
+
+```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.
+
+## 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.
+
+## Logging
+
+See [api-logging.md](api-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`. 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.
+
+```ts
+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
+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
+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.
+
+```ts
+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
+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.