Skip to content

Commit d13beb7

Browse files
committed
fix(automation): describe the HTTP and approval flow nodes in business words
The node description and config help are the Studio flow palette and node-card text an admin reads. Rewrite the HTTP node's description and its method / durable / timeoutMs / signingSecret / body help, and the approval node's description, in business words; the outbox, HMAC, literal and CEL detail moves to code comments beside each entry. Copy only: no key, type, default or behaviour change. Claude-Session: https://claude.ai/code/session_01FEkQ5oZiDbKQCsyey7KM7z Co-authored-by: Claude <noreply@anthropic.com>
1 parent 23d1303 commit d13beb7

4 files changed

Lines changed: 58 additions & 14 deletions

File tree

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
'@objectstack/service-automation': patch
3+
'@objectstack/plugin-approvals': patch
4+
---
5+
6+
Clause-②: no
7+
Metadata-protocol: none
8+
9+
The HTTP and approval flow nodes now describe themselves in business words. The node description and
10+
config help are the text the Studio flow palette and node cards show an admin, and the HTTP node's
11+
spoke of the messaging outbox, retry / dead-letter, an HMAC-SHA256 secret, "a literal, read as
12+
written" and a CEL value envelope; the approval node's said it "suspends the flow". The HTTP node now
13+
reads "Send a request to an outside web service: wait for its answer, or hand it off to be delivered
14+
in the background with automatic retries", with plain help for the request kind, background delivery,
15+
the wait time, the signing secret and what to send; the approval node reads "Ask people to approve or
16+
reject a record". The engineer detail moved to code comments beside each entry. No key, type, default,
17+
accepted value or behaviour changed.

‎packages/plugins/plugin-approvals/src/approval-node.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -135,8 +135,11 @@ export function registerApprovalNode(
135135
type: APPROVAL_NODE_TYPE,
136136
version: '1.0.0',
137137
name: 'Approval',
138-
description: 'Route a record for human approval; suspends the flow until a decision, '
139-
+ 'then continues down the approve / reject branch.',
138+
// Palette and node-card text an admin reads, in business words. The run
139+
// suspends here until a decision, then resumes down the `approve` /
140+
// `reject` edge (see `resumeAuthority` below).
141+
description: 'Ask people to approve or reject a record. The flow waits for their decision, '
142+
+ 'then continues down the approve or reject path.',
140143
icon: 'check-circle',
141144
category: 'human',
142145
paradigms: ['flow'],

‎packages/services/service-automation/src/builtin/http-node-signing.test.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,10 @@ import { registerHttpNodes } from './http-nodes.js';
1919
* wire, on EVERY arm the node can take.
2020
*
2121
* The key is declared without qualification — `HttpConfigSchema.signingSecret`
22-
* and the descriptor's `configSchema` both read "HMAC-SHA256 secret →
23-
* X-Objectstack-Signature" — yet only the durable arm used to hand it to
24-
* anything that signs (the messaging outbox). The inline arm, and the durable
22+
* reads "HMAC-SHA256 secret → X-Objectstack-Signature", and the descriptor's
23+
* `configSchema` says it signs each request — yet only the durable arm used
24+
* to hand it to anything that signs (the messaging outbox). The inline arm,
25+
* and the durable
2526
* arm's no-outbox fallback that degrades to it, built their `fetch` from
2627
* `headers` alone: the request went out unsigned and the run said
2728
* `success: true`.

‎packages/services/service-automation/src/builtin/http-nodes.ts‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -123,9 +123,15 @@ export function registerHttpNodes(engine: AutomationEngine, ctx: PluginContext):
123123
type: HTTP_TYPE,
124124
version: '1.0.0',
125125
name: 'HTTP',
126+
// The description and the config help below are the Studio flow
127+
// palette and node-card text an admin reads, so they speak business
128+
// words. The engineer detail they used to carry lives here: with
129+
// `durable: true` the call is enqueued on the messaging HTTP outbox
130+
// (retry / dead-letter) and the run does not see the response;
131+
// otherwise it runs inline and returns the response.
126132
description:
127-
'Call an external HTTP endpoint. With `durable: true`, the call is enqueued on the '
128-
+ 'messaging outbox with retry / dead-letter; otherwise it runs inline and returns the response.',
133+
'Send a request to an outside web service: wait for its answer, or hand it off to be '
134+
+ 'delivered in the background with automatic retries.',
129135
icon: 'globe',
130136
category: 'io',
131137
source: 'builtin',
@@ -166,9 +172,13 @@ export function registerHttpNodes(engine: AutomationEngine, ctx: PluginContext):
166172
+ 'path is the secret: call the service through a token-authenticated connector instead, such '
167173
+ 'as the `slack` connector with its bot token.',
168174
},
175+
// `method` is a literal, read as written (#19939): no `{{ }}`
176+
// rendering. Default `GET`; `POST` when `durable` is true.
169177
method: {
170178
type: 'string',
171-
description: 'HTTP method (default GET; POST when durable) — a literal, read as written',
179+
description:
180+
'The kind of request, such as GET or POST. GET by default; POST when the request is '
181+
+ 'delivered in the background.',
172182
},
173183
headers: {
174184
type: 'object',
@@ -180,19 +190,32 @@ export function registerHttpNodes(engine: AutomationEngine, ctx: PluginContext):
180190
+ 'authenticated upstream through a `connector_action` on a declarative connector whose '
181191
+ '`auth.credentialRef` names the secret.',
182192
},
193+
// `body` is JSON-serialised: a CEL value envelope
194+
// `{ dialect: 'cel', source }` evaluated per run to the payload,
195+
// or a literal sent as written.
183196
body: {
184-
description:
185-
'Request body (JSON-serialised) — a CEL value envelope `{ dialect: \'cel\', source }` '
186-
+ 'evaluated per run to the payload, or a literal sent as written',
197+
description: 'What to send, as JSON: a fixed value, or an expression worked out on each run.',
187198
},
199+
// `durable: true` is fire-and-forget through the messaging HTTP
200+
// outbox (retry / dead-letter) instead of an inline
201+
// request / response.
188202
durable: {
189203
type: 'boolean',
190-
description: 'Fire-and-forget via the durable outbox (retry/dead-letter) instead of inline request/response',
204+
description:
205+
'Deliver the request in the background and keep retrying if it fails, instead of '
206+
+ 'waiting for the answer; the flow does not see the response.',
191207
},
192-
timeoutMs: { type: 'number', description: 'Per-request timeout (ms)' },
208+
// Per-request timeout in milliseconds, on both arms; a literal
209+
// number, read as written.
210+
timeoutMs: { type: 'number', description: 'How long to wait for an answer, in milliseconds.' },
211+
// The HMAC-SHA256 secret that signs the request body into the
212+
// `X-Objectstack-Signature` header, on every arm; the secret
213+
// itself, read as written (`''` sends unsigned on purpose).
193214
signingSecret: {
194215
type: 'string',
195-
description: 'HMAC-SHA256 secret → X-Objectstack-Signature — the secret itself, read as written',
216+
description:
217+
'A shared secret used to sign each request, so the receiving service can check it came '
218+
+ 'from you (sent as the X-Objectstack-Signature header).',
196219
},
197220
},
198221
},

0 commit comments

Comments
 (0)