@flowrunner/cli 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/ai-docs/instructions/service-code-format/01-service-structure.md +27 -2
  2. package/ai-docs/instructions/service-code-format/04-http-requests.md +29 -0
  3. package/ai-docs/instructions/service-code-format/05-dictionaries.md +19 -0
  4. package/ai-docs/instructions/service-code-format/08-polling-triggers.md +68 -5
  5. package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +51 -8
  6. package/ai-docs/instructions/service-code-format/12-service-readme.md +5 -0
  7. package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +18 -5
  8. package/ai-docs/instructions/service-code-format/14-reference-service.md +7 -2
  9. package/ai-docs/instructions/service-code-format/16-gotchas.md +16 -4
  10. package/ai-docs/providers/claude/agents/flowrunner-service-code-engineer.md +9 -2
  11. package/dist/cli.js +429 -239
  12. package/dist/cli.js.map +4 -4
  13. package/dist/index.js +420 -232
  14. package/dist/index.js.map +4 -4
  15. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
  16. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
  17. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
  18. package/dist/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
  19. package/dist/types/packages/cli/src/constants/testing.d.ts +9 -4
  20. package/dist/types/shared/src/constants/knowledge-base.d.ts +1 -0
  21. package/dist/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
  22. package/dist/types/shared/src/scheme/crm/dto.d.ts +2 -2
  23. package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
  24. package/dist/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
  25. package/dist/types/shared/src/scheme/workspace/dto.d.ts +1 -1
  26. package/package.json +3 -3
  27. package/runtime/index.js +39 -24
  28. package/runtime/index.js.map +2 -2
  29. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/system-params.d.ts +2 -0
  30. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +6 -2
  31. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +6 -1
  32. package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/verify.d.ts +1 -1
  33. package/runtime/types/shared/src/constants/knowledge-base.d.ts +1 -0
  34. package/runtime/types/shared/src/scheme/billing/java.dto.d.ts +19 -1
  35. package/runtime/types/shared/src/scheme/crm/dto.d.ts +2 -2
  36. package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +1 -1
  37. package/runtime/types/shared/src/scheme/knowledge-base/dto.d.ts +156 -0
  38. package/runtime/types/shared/src/scheme/workspace/dto.d.ts +1 -1
@@ -61,7 +61,7 @@ logo for that one item. Omit it and the item inherits the service's.
61
61
  | `logo` | string | ✓ | Icon path, resolved **inside the service's `public/` folder** — see [Folder layout](#folder-layout). |
62
62
  | `appearanceColors` | `[string, string]` | – | `[primary, secondary]`. |
63
63
  | `usesFileStorage` | boolean | – | `true` provisions `ctx.files`; when false, `ctx.files` is a proxy that throws. Default false. See [10-files-api.md](10-files-api.md). |
64
- | `configItems` | `z.object` | – | App + shared config (see [02-zod-types.md](02-zod-types.md)). → `appConfigDescriptions` / `sharedConfigDescriptions`. Omit when the service needs none; a plain object of fields is **not** accepted (see [03-parameters.md](03-parameters.md)). |
64
+ | `configItems` | `z.object` | – | App + shared config (see [02-zod-types.md](02-zod-types.md)). → `appConfigDescriptions` / `sharedConfigDescriptions`. Omit when the service needs none — see [Services with no credentials](#services-with-no-credentials); a plain object of fields is **not** accepted (see [03-parameters.md](03-parameters.md)). |
65
65
  | `initContext` | fn | – | `({ config, oauth }) => context`; runs once per invocation. Runs for OAuth flows too (`oauth` may be empty). |
66
66
  | `apiRequest` | fn | – | Shared HTTP helper (envelope-unwrap, error-normalize, redacted logging). See [04-http-requests.md](04-http-requests.md). |
67
67
  | `helpers` | fn | – | ctx factory `(ctx) => ({ ... })` for **genuinely reusable service logic**; result exposed as `helpers` in every handler bag. `ctx` = `{ config, context, oauth, apiRequest, files, filesScope, logger }` (no `params`). |
@@ -153,7 +153,7 @@ shape once, and every registrar carries it into every handler:
153
153
 
154
154
  | Declared here | Becomes | Typed as |
155
155
  |---|---|---|
156
- | `configItems` | `config` in every handler (and in `initContext`) | `z.infer` of the schema |
156
+ | `configItems` | `config` in every handler (and in `initContext`) | `z.infer` of the schema — `{}` when the prop is omitted |
157
157
  | `initContext` | `context` in every handler | its return type |
158
158
  | `helpers` | `helpers` in every handler | its return type |
159
159
  | `apiRequest` | `apiRequest` in every handler | your own signature, minus the `context` / `logger` the runtime injects |
@@ -178,3 +178,28 @@ ext.addAction({
178
178
 
179
179
  The full per-handler context bag, and how each key is inferred, is documented in
180
180
  [07-actions.md](07-actions.md#inferred-types).
181
+
182
+ ## Services with no credentials
183
+
184
+ A service wrapping a free public API needs no credentials, and `configItems` is genuinely optional — omit
185
+ the prop entirely rather than declaring an empty `z.object({})`:
186
+
187
+ ```js
188
+ const ext = Flowrunner.createExtension({
189
+ id: 'openmeteo', name: 'Open-Meteo', description: 'Free weather forecasts', logo: '/icon.png',
190
+ // no configItems — nothing to configure
191
+ initContext: () => ({ apiUrl: 'https://api.open-meteo.com/v1' }),
192
+ })
193
+ ```
194
+
195
+ What follows from that:
196
+
197
+ - **`config` is `{}` in every handler**, never `undefined` — so `config.anything` is safely `undefined`
198
+ rather than a crash, and no handler needs to guard before reading it.
199
+ - **`getServiceConfigs()` returns `[]`**, and the console renders the service with **no configuration
200
+ form**. The user installs it and its actions are immediately usable — there is no empty settings screen
201
+ and nothing to fill in.
202
+ - **`initContext` still runs**, and is still where a base URL belongs. Its `config` argument is the same
203
+ empty object.
204
+
205
+ This is a complete, valid service — the absence of `configItems` is not something to work around.
@@ -29,6 +29,35 @@ Author-defined, but conventionally:
29
29
  place to read resolved credentials/tokens.
30
30
  - The helper is exposed in every handler's context bag as `apiRequest` (see [07-actions.md](07-actions.md)),
31
31
  and is also the natural building block for `helpers`.
32
+ - `...custom` is not decoration: **the bag a handler passes is the bag your helper receives**, so any extra
33
+ prop you invent is forwarded verbatim. That is the seam for anything per-call.
34
+
35
+ ### More than one host
36
+
37
+ APIs that split across hosts — a search or geocoding endpoint on one domain, the main API on another — are
38
+ common, and the `...custom` pass-through is how one helper serves both. Take a prop naming the host and
39
+ resolve it against a map; the default keeps every existing call site unchanged:
40
+
41
+ ```js
42
+ const API_HOSTS = {
43
+ main : 'https://api.example.com/v1',
44
+ geocode: 'https://geocoding.example.com/v1',
45
+ }
46
+
47
+ apiRequest: async ({ url, method = 'get', body, query, context, api = 'main' }) =>
48
+ new Flowrunner.Request(`${ API_HOSTS[api] }${ url }`, method, body)
49
+ .set({ Authorization: `Bearer ${ context.apiKey }` })
50
+ .query(query),
51
+ ```
52
+
53
+ ```js
54
+ await apiRequest({ url: '/weather', query: { lat, lon } }) // main host
55
+ await apiRequest({ url: '/search', query: { name }, api: 'geocode' }) // the other one
56
+ ```
57
+
58
+ Keep the per-host differences *inside* the helper — a host that needs no auth, or a different header — so
59
+ handlers keep naming only the endpoint they want. Declaring a second `apiRequest` is not an option: the
60
+ extension takes one.
32
61
 
33
62
  The rest of this document is the client surface underneath that helper — `Flowrunner.Request`, the runtime
34
63
  HTTP client, always on the global ([13-runtime-contracts.md](13-runtime-contracts.md)) and requiring no
@@ -18,6 +18,25 @@ via `.dictionary(ref)` on a param (see [02-zod-types.md](02-zod-types.md)). A di
18
18
  |---|---|
19
19
  | `{ search, cursor, criteria, context, apiRequest, helpers }` | `{ items: [{ label, value, note? }], cursor? }` (bare array ok if no pagination) |
20
20
 
21
+ ### What an item's three fields do
22
+
23
+ | Field | Role |
24
+ |---|---|
25
+ | `label` | The name shown in the picker. Truncated to one line, so put the distinguishing part first. |
26
+ | `value` | What is stored in the flow and handed to your handler. Never shown. |
27
+ | `note` | Optional second line beneath the label, in smaller muted text — the disambiguator. |
28
+
29
+ **`note` is for telling two identical labels apart.** Places share names, files share titles, people share
30
+ surnames; `note` is where the city, the folder or the email goes so the flow author can pick the right one.
31
+
32
+ - It renders as **Markdown** (tables excluded), so a link or a bit of `code` works. It scrolls past roughly
33
+ four lines rather than growing the row, so keep it to one or two.
34
+ - **It is not searched.** The picker does no client-side filtering at all — the typed term is passed to your
35
+ `execute` as `search`, and matching is entirely up to you. A user who types something that appears only in
36
+ a `note` gets a match only if your handler chose to search that field. So keep anything a user would
37
+ reasonably type in `label`, and treat `note` as read-only context.
38
+ - Omit it when labels are already unique; an empty second line on every row just makes the list longer.
39
+
21
40
  ```js
22
41
  const getTablesDictionary = ext.dictionary({
23
42
  id : 'getTablesDictionary',
@@ -22,7 +22,7 @@ Declare **exactly one** mechanism.
22
22
  | Mechanism | Config | Runtime behavior |
23
23
  |---|---|---|
24
24
  | `dedupe` (seen-set) | `item => id` (or field path); or `{ by, stateKey='seen', max=500 }` | Keeps a bounded id set under `stateKey`; emits items whose id is new. Covers new-by-id + stateless-newest (head-only `fetch`). |
25
- | `watermark` (marker) | `{ by, stateKey='watermark', sortedDesc? }` — `by` = field path or `(item,{params})=>value` | Stores newest marker, emits items past it, advances. `sortedDesc:true` early-breaks. Covers new-by-date + new-or-updated. |
25
+ | `watermark` (marker) | `{ by, stateKey='watermark', sortedDesc? }` — `by` = field path or `(item,{params})=>value` | Stores newest marker, emits items past it, advances. `sortedDesc:true` stops at the first non-newer item — **only for a strictly newest-first feed**, see below. Covers new-by-date + new-or-updated. |
26
26
  | `poll` (escape hatch) | fn (above) | Full control; author owns `state` shape. Covers overlap-window+dedup, lag-held cursor, consuming/offset feeds. |
27
27
 
28
28
  ## Lifecycle — `state` before → after \| emits
@@ -30,12 +30,75 @@ Declare **exactly one** mechanism.
30
30
  | Phase | `dedupe` | `watermark` | `poll` |
31
31
  |---|---|---|---|
32
32
  | start (no state) | `null → { seen:{…} }` \| `[]` (seed) | `null → { <marker> }` \| `[]` (seed) | `null → seeded` \| `[]` (seed yourself) |
33
- | learningMode | `null → null` \| `[newest]` (reset) | `null → null` \| `[newest]` (reset) | `null → null` \| `[newest]` (reset) |
33
+ | learningMode | `null → null` \| everything `fetch` returned | `null → null` \| everything `fetch` returned | **no handling** — whatever you return |
34
34
  | timer | `{seen} → {seen+new}` \| `[new]` | `{marker} → {advanced}` \| `[past marker]` | yours → yours \| your delta |
35
35
 
36
- `isLearningMode`: during setup the runtime calls `fetch`/`poll` with `isLearningMode:true`; return a real
37
- (limited) sample; the runtime emits it and does **not** persist state. This is distinct from `result`
38
- (which describes shape only).
36
+ ### Learning mode
37
+
38
+ During setup the runtime calls your handler with `isLearningMode:true` so the trigger can show the flow
39
+ author a preview of what it will emit. **What the runtime does with the result depends on the mechanism,
40
+ and the difference matters** — it is not a detail the runtime smooths over.
41
+
42
+ With **`dedupe` / `watermark`** the runtime short-circuits: it emits *everything* `fetch` returned and
43
+ persists no state. It does **not** reduce the list to the newest item — **limiting the preview is your
44
+ job**, inside `fetch`, by reading `isLearningMode` and requesting a small page:
45
+
46
+ ```js
47
+ fetch: async ({ params, isLearningMode, apiRequest }) => {
48
+ const items = await apiRequest({ url: '/events', query: { limit: isLearningMode ? 5 : 100 } })
49
+
50
+ return items
51
+ }
52
+ ```
53
+
54
+ With **`poll`** the runtime does **nothing at all**. It forwards the flag and returns your
55
+ `{ events, state }` verbatim — so the state you return during setup *is* persisted, and the events you
56
+ return *are* the preview. A `poll` handler that ignores `isLearningMode` shows the flow author an empty
57
+ preview (its first cycle seeds and emits nothing) and burns its seed state before the trigger is even
58
+ saved. Branch on the flag explicitly:
59
+
60
+ ```js
61
+ poll: async ({ params, state, isLearningMode, apiRequest }) => {
62
+ const items = await apiRequest({ url: '/events', query: { limit: isLearningMode ? 5 : 100 } })
63
+
64
+ // Setup preview: show a sample, persist nothing.
65
+ if (isLearningMode) {
66
+ return { events: items, state: null }
67
+ }
68
+
69
+ return { events: yourDelta(items, state), state: yourNextState(items) }
70
+ }
71
+ ```
72
+
73
+ This is distinct from `result` (which describes shape only).
74
+
75
+ ## Two ways a watermark drops events silently
76
+
77
+ Both of these lose events permanently, with no error and nothing in the logs — the trigger simply never
78
+ fires for the item. Decide about each one before choosing `watermark`.
79
+
80
+ **A late arrival is never seen.** The marker only ever moves forward, to the newest value in the batch.
81
+ An item that shows up in a later poll carrying an *older* `by` value — backdated, queued upstream, or
82
+ written by a provider whose clock runs behind — is already behind the marker, so it is not emitted, and
83
+ the marker has moved past it for good. Where the provider stamps `updatedAt` on every write, watermark on
84
+ that rather than `createdAt`: a late or amended item then arrives with a fresh value and is caught. Where
85
+ it does not, `dedupe` compares ids and does not care about ordering.
86
+
87
+ **`sortedDesc:true` stops at the first non-newer item.** It is a scan optimization for a feed that is
88
+ *strictly* newest-first: the runtime breaks out of the loop rather than checking the rest of the page.
89
+ On a feed that is only *mostly* sorted, every newer item sitting behind an older one is dropped — and
90
+ because the marker still advances to the newest value in the batch, it is dropped permanently:
91
+
92
+ ```js
93
+ // Feed returns: [ {id: 3, at: '10:05'}, {id: 2, at: '09:58'}, {id: 4, at: '10:07'} ]
94
+ // Marker: '10:00'
95
+ watermark: { by: 'at', sortedDesc: true } // emits [3], stops at 2 — item 4 is lost for good
96
+ watermark: { by: 'at' } // emits [3, 4] — scans the whole page
97
+ ```
98
+
99
+ A page is rarely worth the scan it saves. **Set `sortedDesc` only when the provider documents a strict
100
+ newest-first order**, and leave it off whenever the ordering is incidental, client-side, or merely
101
+ observed to hold.
39
102
 
40
103
  ## One trigger per event
41
104
 
@@ -74,12 +74,12 @@ does its own lowercased retry; that behaviour does not extend to `verifyRequest`
74
74
  | `subscribe` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` (null first), `connectionId` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
75
75
  | `unsubscribe` | `callbackUrl`, `webhookData`, `connectionId` | `{ webhookData? }` |
76
76
  | `refresh` | `callbackUrl`, `triggers:[{ id, params, providerEventName? }]`, `webhookData` | `{ webhookData?, refreshIntervalInSeconds }` |
77
- | `handshake` | `{ requestBody, headers, rawBody }` | `{ responseToWebhook? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
78
- | `resolveEvents` | `rawBody`, `headers`, `query`, `body`, `connectionId` | `{ events:[{ id, providerEventData }], eventScopeId?, handshake?, responseToWebhook? }` |
77
+ | `handshake` | `{ requestBody, headers, rawBody, webhookData }` | `{ responseToWebhook? }` (runtime adds `handshake:true`); nothing → proceed. Empty-body deliveries are auto-acked by default (no `handshake` needed). |
78
+ | `resolveEvents` | `rawBody`, `headers`, `query`, `body`, `webhookData`, `connectionId` | `{ events:[{ id, providerEventData }], eventScopeId?, handshake?, responseToWebhook? }` |
79
79
 
80
80
  Both also still accept the **deprecated** `responseToExternalService` / `responseHeaders` — see
81
81
  [below](#responsetoexternalservice--deprecated).
82
- | `verifyRequest` | `{ rawBody, headers }` + the full ctx bag — `context` included | `boolean` (plain, not a Promise) |
82
+ | `verifyRequest` | `{ rawBody, headers, webhookData }` + the full ctx bag — `context` included | `boolean` (plain, not a Promise) |
83
83
 
84
84
  **The `triggers` bag holds one entry per (trigger × `providerEventName`)**, so a trigger declaring several
85
85
  names appears several times. A trigger that declares **no** `providerEventName` — what you write when
@@ -89,6 +89,49 @@ reconcile it. Guard the field rather than assuming it (`if (t.providerEventName)
89
89
  on it unconditionally. Nothing is left out of the bag: a name resolving to no trigger **rejects the whole
90
90
  call** — see [Unknown trigger names](#unknown-trigger-names) below.
91
91
 
92
+ ### `webhookData` on the inbound path — read-only
93
+
94
+ Every inbound seam receives the **stored webhook document**: whatever `subscribe` (or `refresh`) last returned
95
+ as `webhookData`, persisted by the platform and looked up for this delivery.
96
+
97
+ | Seam | Runs | Reads `webhookData` |
98
+ |---|---|---|
99
+ | `handshake`, `verify`/`verifyRequest`, `resolveEvents` | once per delivery | ✓ |
100
+ | `match` (predicate form), `extendResult` | per instance / once per event | ✓ |
101
+ | `extendEventData` | per trigger, pure | — |
102
+
103
+ It is the only channel from registration to delivery, and the case it exists for is the **signing secret a
104
+ provider mints when the webhook is created**: it comes back from the registration call, `subscribe` stores it,
105
+ and the delivery it signs can then be verified against it. The same applies to an external webhook id or
106
+ tenant id a delivery has to be recognised or filtered by.
107
+
108
+ ⚠️ **Reading is all these seams do.** None of them can update the document — their result types have no
109
+ `webhookData` field, and one returned anyway is dropped. Only `subscribe`, `refresh` and `unsubscribe`
110
+ persist it, so anything an inbound delivery would like to record has to wait for the next one of those.
111
+ Do not design around writing it back from a delivery.
112
+
113
+ ```js
114
+ verify: {
115
+ header : 'x-provider-signature',
116
+ algo : 'sha256',
117
+ encoding: 'hex',
118
+ // The per-webhook secret the provider issued at registration; the app-level config key is the fallback
119
+ // for a webhook registered before the service started storing it.
120
+ secret : (config, { webhookData }) => webhookData?.signingSecret ?? config.signingSecret,
121
+ },
122
+ ```
123
+
124
+ ⚠️ **`webhookData` is `null` whenever there is no document to read**, and that is a normal delivery, not a
125
+ broken one:
126
+
127
+ - nothing has been stored for this webhook yet, or
128
+ - the delivery arrived on the **general callback of a service that is not app-hosted** — the document is
129
+ stored per workspace, so there is no workspace to look one up for.
130
+
131
+ So read it defensively (`webhookData?.field`), and never let an absent document *reject* a delivery on its
132
+ own: "no id to compare against" is not "the ids differ". Anything mandatory for verification still belongs in
133
+ `config`, with the stored value as the refinement over it.
134
+
92
135
  ### `responseToWebhook` — answering the provider
93
136
 
94
137
  Some providers do not accept a generic `200`. Xero's *Intent to Receive* validation sends two deliveries and
@@ -163,14 +206,14 @@ than the missing input it is — and sends you hunting for a wrong secret.
163
206
 
164
207
  ### `verify` fields
165
208
 
166
- HMACs the **raw body alone** with `secret(config)` and compares it to the header in constant time.
209
+ HMACs the **raw body alone** with the key `secret` returns and compares it to the header in constant time.
167
210
 
168
211
  | Field | Req | Description |
169
212
  |---|---|---|
170
213
  | `header` | ✓ | Signature header. Read as declared, then retried lowercased. Absent header → fail. |
171
214
  | `algo` | ✓ | Hash algorithm, e.g. `'sha256'`. |
172
215
  | `encoding` | ✓ | `'hex' \| 'base64'` — the digest encoding the provider sends. |
173
- | `secret` | ✓ | `(config) => key`. |
216
+ | `secret` | ✓ | `(config, { webhookData }) => key`. The second argument is the stored webhook document — `null` when there is none — for a provider that mints the secret at registration time. |
174
217
  | `timestampHeader` | – | Header carrying the request timestamp. **Required for `freshness` to run.** |
175
218
  | `freshness` | – | Max age in seconds. **Only checked when `timestampHeader` is also declared** — on its own it is silently inert. A declared-but-absent timestamp header passes. |
176
219
 
@@ -236,8 +279,8 @@ Use `params` for **filters** — which chat, which board, which status — never
236
279
  |---|---|---|
237
280
  | `extendEventData` | `{ requestBody, providerEventData }` | partial object (merged onto `providerEventData`, **pure, pre-match**) |
238
281
  | `match` (object) | `{ paramKey: 'path.in.providerEventData' }` | declarative — type-coerced equality per filled param; empty param → all |
239
- | `match` (fn) | `{ params, providerEventData }` | `boolean` — for ranges/contains/derived logic |
240
- | `extendResult` | `{ providerEventData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
282
+ | `match` (fn) | `{ params, providerEventData, webhookData }` | `boolean` — for ranges/contains/derived logic |
283
+ | `extendResult` | `{ providerEventData, webhookData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
241
284
 
242
285
  **Inbound runtime flow:** `handshake?` → `verify`/`verifyRequest` → read `extractProviderEventName` → for
243
286
  each trigger whose `providerEventName` matches, build `providerEventData` (`extractProviderEventData` +
@@ -254,7 +297,7 @@ costs no provider call.
254
297
  |---|---|
255
298
  | subscribe (flow start) | `null → webhookData` (create webhook / resolve `eventScopeId`) |
256
299
  | subscribe (set changed) | `webhookData → webhookData'` (recreate: delete prior + create; or diff) |
257
- | inbound event | unchanged \| emits matched instances |
300
+ | inbound event | unchanged — **read-only** for every inbound seam (`handshake`, `verify`/`verifyRequest`, `resolveEvents`, `match`, `extendResult`) \| emits matched instances |
258
301
  | refresh (opt) | `webhookData → webhookData'` (renew) |
259
302
  | unsubscribe (flow stop) | `webhookData → {}` (tear down) |
260
303
 
@@ -31,6 +31,11 @@ service's `src/index.js` (the single source of truth).
31
31
  `dynamicParams`, `result` loader functions, `initContext`, `apiRequest`, `helpers`, and
32
32
  `ext.setupOauth2` / `ext.setupRealtimeTriggers` setup calls. These are internal support declarations, and
33
33
  the SYSTEM methods generated from them are never documented.
34
+ - **The exclusion is about declarations, not consequences.** It keeps the plumbing out; it does not silence
35
+ something a *user* has to know. Where a parameter has to be typed by hand because the API offers no way to
36
+ list or resolve it, that is a user-facing limitation — put one sentence in **Description**, phrased as what
37
+ the user must supply and where to get it. Never as a note about a missing dictionary, which is the internal
38
+ half and stays out.
34
39
  - If a `GENERATED_README.md` exists in the service directory it may be used as a source, but never modify it —
35
40
  it is auto-generated and excluded from version control.
36
41
 
@@ -96,13 +96,26 @@ buildServiceDefinition('telegram', ENTRY)
96
96
  |---|---|---|
97
97
  | `handleTriggerUpsertWebhook` | `{ invocation: { callbackUrl, triggers, webhookData?, connectionId? } }` | `{ webhookData?, eventScopeId?, refreshIntervalInSeconds? }` |
98
98
  | `handleTriggerDeleteWebhook` | `{ invocation: { callbackUrl, webhookData, connectionId? } }` | `{ webhookData? }` |
99
- | `handleTriggerSelectMatched` | `{ invocation: { eventName, eventData, triggers } }` | `{ ids, enrichedEventData }` |
100
- | `handleTriggerResolveEvents` | `{ invocation: { body, rawBody?, headers?, query?, connectionId? } }` | `{ events: [{ name, data }], responseToWebhook? }` (plus the deprecated `responseToExternalService`, still forwarded) |
99
+ | `handleTriggerSelectMatched` | `{ invocation: { eventName, eventData, triggers, webhookData? } }` | `{ ids, enrichedEventData }` |
100
+ | `handleTriggerResolveEvents` | `{ invocation: { body, rawBody?, headers?, queryParams?, webhookData?, connectionId? } }` | `{ events: [{ name, data }], responseToWebhook? }` (plus the deprecated `responseToExternalService`, still forwarded) |
101
101
 
102
102
  `handleTriggerResolveEvents` is the inbound-delivery seam. **`body` is required** — omitting it fails with
103
- `body: Invalid input: expected nonoptional, received undefined`. `rawBody` and `headers` are the only fields
104
- forwarded to `verifyRequest`; `query` is accepted but not forwarded, and `connectionId` is echoed back on the
105
- response. Unknown fields in `invocation` are ignored rather than rejected.
103
+ `body: Invalid input: expected nonoptional, received undefined`. `rawBody`, `headers` and `webhookData` are
104
+ the fields forwarded to `verifyRequest`; `connectionId` is echoed back on the response. Unknown fields in
105
+ `invocation` are ignored rather than rejected.
106
+
107
+ ⚠️ **The query string is `queryParams` in the invocation and `query` in the handler bag.** Spelling it
108
+ `query` in `methodData` is one of those ignored unknown fields, so `resolveEvents` sees `query: {}` and a
109
+ spec asserting on a query-string branch silently drives the wrong path.
110
+
111
+ **`webhookData` is the webhook document the platform stored** — what `subscribe`/`refresh` last returned —
112
+ looked up for this delivery. It reaches `handshake`, `verify`/`verifyRequest` and `resolveEvents` here, and
113
+ `match`/`extendResult` on `handleTriggerSelectMatched`, and is `null` when none is stored or when the request
114
+ carries no workspace to look one up for (the general callback of a service that is not app-hosted). Both
115
+ methods only **read** it: neither response carries a `webhookData` field, so a document returned from one is
116
+ dropped — only upsert/refresh/delete persist. The harness never supplies it on its own: pass it in
117
+ `invocation` to drive a path that depends on it
118
+ ([09-realtime-triggers.md](09-realtime-triggers.md#webhookdata-on-the-inbound-path--read-only)).
106
119
 
107
120
  It answers `{ events: [] }` for a delivery no trigger claims, and `{ handshake: true, events: [] }` for an
108
121
  empty body — the runtime acks those automatically, with no `handshake` declared
@@ -183,15 +183,20 @@ ext.addPollingTrigger({
183
183
  description: 'Fires for each new note on a board.',
184
184
  params : z.object({ boardId: z.string().optional().label('Board').dictionary(getBoardsDictionary) }),
185
185
  result : { id: 'note_1', body: 'Ship it', boardId: 'brd_1', createdAt: '2026-01-01T00:00:00Z' },
186
- fetch : async ({ params, apiRequest }) => {
186
+ fetch : async ({ params, isLearningMode, apiRequest }) => {
187
187
  if (!params.boardId) {
188
188
  return []
189
189
  }
190
190
 
191
- const response = await apiRequest({ url: `/boards/${ params.boardId }/notes`, query: { sort: '-createdAt' } })
191
+ // The runtime emits everything this returns during setup, so cap the preview here — 08.
192
+ const response = await apiRequest({
193
+ url : `/boards/${ params.boardId }/notes`,
194
+ query: { sort: '-createdAt', limit: isLearningMode ? 5 : 100 },
195
+ })
192
196
 
193
197
  return response.notes ?? []
194
198
  },
199
+ // `sortedDesc` is safe only because the request above pins the order — 08.
195
200
  watermark: { by: 'createdAt', sortedDesc: true },
196
201
  })
197
202
 
@@ -177,10 +177,22 @@ tempting move is defensive code that tries to work either way — feature-detect
177
177
  shapes. **That hedge is how a silent bug gets written**: it looks careful, it type-checks, and it picks the
178
178
  wrong branch without complaining.
179
179
 
180
- Establish the fact instead. A scratch script against `@flowrunner/cli/runtime` settles most runtime questions
181
- in a minute (see [13-runtime-contracts.md](13-runtime-contracts.md) for the pattern and the reload caveat),
182
- and a local `http` server settles any question about what actually goes out on the wire. Then write the one
183
- branch that is true — and add the fact to 13, which is the fix that stops the next service repeating it.
180
+ Establish the fact instead — but only where it is yours to establish. The line runs between **your code**
181
+ and **the runtime's contract**:
182
+
183
+ - **Your own code is yours to check.** Build the service with `buildServiceDefinition`, read its configs
184
+ with `getServiceConfigs`, call your own handler bodies directly, and point a local `http` server at it to
185
+ see what actually goes out on the wire. A scratch script against `@flowrunner/cli/runtime` settles these
186
+ in a minute — see [13-runtime-contracts.md](13-runtime-contracts.md) for the pattern and the reload caveat.
187
+ - **An undocumented runtime contract is not.** If the open question is what the *runtime* will hand your
188
+ handler in production, a scratch script cannot answer it. Calling a method with malformed input reads the
189
+ runtime's input validator back to you, not production behaviour, and conclusions drawn that way have been
190
+ wrong before — [13-runtime-contracts.md](13-runtime-contracts.md) names the contracts the local harness
191
+ cannot reach at all. **Report the gap, and write the single branch the documentation implies.** Do not
192
+ read the bundled runtime's source to settle it.
193
+
194
+ Either way the hedge is still the wrong answer: write the one branch that is true, and get the fact added
195
+ to 13, which is the fix that stops the next service repeating it.
184
196
 
185
197
  ## Where a fact already lives
186
198
 
@@ -116,14 +116,21 @@ test engineer can always rebuild the authoritative list itself.
116
116
  states which contracts are exercisable locally and which the harness cannot reach. If what you need is
117
117
  not there, say so in your report and proceed on the documented behaviour — do not guess, and never present
118
118
  an inference drawn from error messages as a verified finding.
119
+ - **This does not ban the documented harness.** Running *your own service* through the public exports —
120
+ `buildServiceDefinition`, `getServiceConfigs`, `runServiceMethod`, calling your own handler bodies, or
121
+ pointing a local `http` server at your requests — is the expected way to check your work, and
122
+ `13-runtime-contracts.md` and `16-gotchas.md` both tell you to do it. Importing `@flowrunner/cli/runtime`
123
+ for that is not "reading `node_modules/`"; opening its source to infer behaviour is. The line is whether
124
+ you are verifying **code you wrote** or interrogating **a contract you were not given**.
119
125
  - **Never hedge against an unclear contract.** When you cannot tell how a runtime API behaves, do not write
120
126
  code that tries to work either way — feature-detecting a method, tolerating two shapes, `?.` over a call
121
127
  you are unsure exists. That hedge looks careful, type-checks, and silently picks the wrong branch; it has
122
128
  already shipped a service whose file upload sent an empty request. Instead: re-read the reference, and if
123
129
  the answer genuinely is not there, **write the single branch the documentation implies and report the gap**
124
130
  — naming the fact you could not confirm — so it reaches `13-runtime-contracts.md` or `16-gotchas.md`. Do
125
- not investigate the runtime to settle it yourself; the reference is the contract, and a hole in it is for
126
- the developer to close, not for you to paper over.
131
+ not go inside the runtime to settle it yourself; the reference is the contract, and a hole in it is for
132
+ the developer to close, not for you to paper over. (Checking your *own* code against the harness, per the
133
+ bullet above, is a different thing and is expected.)
127
134
  - **You do not write tests — none, of any kind, unless you were explicitly asked to.** Not a suite, not a
128
135
  single `it()`, not a "temporary" or "throwaway" test file you intend to delete. `flowrunner-service-test-engineer`
129
136
  owns `services/{id}/tests/`, and an engineer who owns both ends up fixing the service to make the test