From 3d0d08493ca72f717362f57472d380812b3b61f8 Mon Sep 17 00:00:00 2001 From: Andrew Harris Date: Wed, 15 Jul 2026 15:48:13 +0100 Subject: [PATCH 1/2] Recommend script files for errorHandling scripts The build-plugin skill only showed errorHandling scripts inline in the stream JSON, which gets unreadable beyond a one-liner. The deploy pipeline resolves errorHandling.script file references from dataStreams/scripts/ exactly like postRequestScript, so the skill now documents that form, shows the errorHandling/ sub-folder in the scaffold layout, and cross-links it from the post-request script wiring section. Co-Authored-By: Claude Fable 5 --- .claude/skills/build-plugin/SKILL.md | 2 ++ .../build-plugin/references/data-streams.md | 20 ++++++++++++++++++- 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/.claude/skills/build-plugin/SKILL.md b/.claude/skills/build-plugin/SKILL.md index d508a634..07ba6815 100644 --- a/.claude/skills/build-plugin/SKILL.md +++ b/.claude/skills/build-plugin/SKILL.md @@ -188,6 +188,8 @@ my-plugin/ myStream.json scripts/ myScript.js + errorHandling/ + myStream.js # errorHandling scripts referenced by path, like postRequestScript defaultContent/ manifest.json scopes.json diff --git a/.claude/skills/build-plugin/references/data-streams.md b/.claude/skills/build-plugin/references/data-streams.md index 8c220cd1..14ccc646 100644 --- a/.claude/skills/build-plugin/references/data-streams.md +++ b/.claude/skills/build-plugin/references/data-streams.md @@ -479,6 +479,24 @@ The `paging` block in `config` controls how SquaredUp fetches multiple pages. "errorHandling": { "type": "script", "script": "result = response.status + ': ' + data.error;" } ``` +### Script files over inline scripts + +For anything beyond a trivial one-liner, don't inline the script in the JSON — reference a file, the same mechanism [`postRequestScript`](#post-request-scripts) uses. Place the file in `dataStreams/scripts/errorHandling/`, named after the stream's `name` field, and set `script` to its path relative to `dataStreams/scripts/` — **the `.js` extension is required** (a bare `.js` path with no newline is what marks the value as a file reference; deploy inlines the file's source, and an unresolvable reference is a validation error). + +Stream JSON (`dataStreams/incidents.json`): + +```json +"errorHandling": { "type": "script", "script": "errorHandling/incidents.js" } +``` + +Script file (`dataStreams/scripts/errorHandling/incidents.js`) — multi-line source, and `{{ ... }}` expressions work exactly as they do inline: + +```javascript +const apiMsg = data && (data.message || data.error); + +result = apiMsg || ('Request failed with HTTP ' + response.status); +``` + --- ## pathToData @@ -736,7 +754,7 @@ Scripts run after the HTTP response is received. Input is `data` (parsed JSON bo ### Wiring a script to a stream -Set `postRequestScript` inside `config` to the script's filename — **the `.js` extension is required**. Name the file after the stream's `name` field and place it in `dataStreams/scripts/`. +Set `postRequestScript` inside `config` to the script's filename — **the `.js` extension is required**. Name the file after the stream's `name` field and place it in `dataStreams/scripts/`. ([errorHandling scripts](#errorhandling) use the same file-reference mechanism, from the `errorHandling/` sub-folder.) Stream JSON (`dataStreams/incidents.json`): From 70a72c1e9dab3b5cda46efebff7ec44f2de5c4f4 Mon Sep 17 00:00:00 2001 From: Andrew Harris Date: Thu, 16 Jul 2026 08:24:55 +0100 Subject: [PATCH 2/2] Always recommend errorHandling script files The section still hinted that inlining the script in the stream JSON was fine for trivial one-liners, so agents kept inlining. Script files are easier to review, so the exemption goes: the intro example now shows the file-reference form and the wording that offered inline as an option is removed, along with the wiring example that duplicated the intro. No new guidance added. Co-Authored-By: Claude Fable 5 --- .../skills/build-plugin/references/data-streams.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/.claude/skills/build-plugin/references/data-streams.md b/.claude/skills/build-plugin/references/data-streams.md index 14ccc646..e94a2a94 100644 --- a/.claude/skills/build-plugin/references/data-streams.md +++ b/.claude/skills/build-plugin/references/data-streams.md @@ -476,20 +476,14 @@ The `paging` block in `config` controls how SquaredUp fetches multiple pages. "errorHandling": { "type": "path", "realm": "payload", "path": "error.message" } // Custom script — access response (.status, .body) and data -"errorHandling": { "type": "script", "script": "result = response.status + ': ' + data.error;" } +"errorHandling": { "type": "script", "script": "errorHandling/incidents.js" } ``` -### Script files over inline scripts - -For anything beyond a trivial one-liner, don't inline the script in the JSON — reference a file, the same mechanism [`postRequestScript`](#post-request-scripts) uses. Place the file in `dataStreams/scripts/errorHandling/`, named after the stream's `name` field, and set `script` to its path relative to `dataStreams/scripts/` — **the `.js` extension is required** (a bare `.js` path with no newline is what marks the value as a file reference; deploy inlines the file's source, and an unresolvable reference is a validation error). - -Stream JSON (`dataStreams/incidents.json`): +### Script files -```json -"errorHandling": { "type": "script", "script": "errorHandling/incidents.js" } -``` +Reference the script as a file — the same mechanism [`postRequestScript`](#post-request-scripts) uses. Place the file in `dataStreams/scripts/errorHandling/`, named after the stream's `name` field, and set `script` to its path relative to `dataStreams/scripts/` — **the `.js` extension is required** (a bare `.js` path with no newline is what marks the value as a file reference; deploy inlines the file's source, and an unresolvable reference is a validation error). -Script file (`dataStreams/scripts/errorHandling/incidents.js`) — multi-line source, and `{{ ... }}` expressions work exactly as they do inline: +Script file (`dataStreams/scripts/errorHandling/incidents.js`) — `{{ ... }}` expressions work in script files too: ```javascript const apiMsg = data && (data.message || data.error);