@flowrunner/cli 0.1.12 → 0.1.13-dev.1
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.
- package/ai-docs/instructions/service-code-format/02-zod-types.md +3 -1
- package/ai-docs/instructions/service-code-format/05-dictionaries.md +59 -1
- package/ai-docs/instructions/service-code-format/06-oauth2.md +29 -1
- package/ai-docs/instructions/service-code-format/09-realtime-triggers.md +104 -5
- package/ai-docs/instructions/service-code-format/11-output-model.md +6 -0
- package/ai-docs/instructions/service-code-format/13-runtime-contracts.md +6 -3
- package/dist/cli.js +10673 -85
- package/dist/cli.js.map +4 -4
- package/dist/index.js +10642 -78
- package/dist/index.js.map +4 -4
- package/dist/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +1 -0
- package/dist/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +4 -2
- package/dist/types/flow-extension-runner/src/v2/model/params-model.d.ts +2 -2
- package/dist/types/flow-extension-runner/src/v2/params/index.d.ts +1 -0
- package/dist/types/flow-extension-runner/src/v2/params/json/encode.d.ts +7 -1
- package/dist/types/flow-extension-runner/src/v2/params/schema/dictionary-binding.d.ts +37 -0
- package/dist/types/flow-extension-runner/src/v2/params/zod.d.ts +7 -5
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +12 -2
- package/dist/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +11 -2
- package/dist/types/flow-extension-runner/src/v2/types.d.ts +1 -0
- package/dist/types/shared/src/constants/error-codes.d.ts +3 -0
- package/dist/types/shared/src/constants/index.d.ts +1 -0
- package/dist/types/shared/src/constants/notification-types.d.ts +59 -0
- package/dist/types/shared/src/constants/oauth-connection-error.d.ts +3 -0
- package/dist/types/shared/src/errors/api.d.ts +11 -0
- package/dist/types/shared/src/errors/index.d.ts +1 -0
- package/dist/types/shared/src/errors/oauth-connection.d.ts +4 -0
- package/dist/types/shared/src/scheme/flowrunner/java.dto.d.ts +26 -0
- package/dist/types/shared/src/scheme/integration-connection/dto.d.ts +46 -4
- package/dist/types/shared/src/scheme/notifications/dto.d.ts +1 -0
- package/dist/types/shared/src/scheme/notifications/rest.d.ts +2 -0
- package/dist/types/shared/src/scheme/shared-extensions/list.d.ts +52 -11
- package/dist/types/shared/src/scheme/shared-extensions/workspace-stack.d.ts +2 -2
- package/package.json +1 -4
- package/runtime/index.js +10631 -57
- package/runtime/index.js.map +4 -4
- package/runtime/types/flow-extension-runner/src/v2/dictionaries/dictionary-method.d.ts +1 -0
- package/runtime/types/flow-extension-runner/src/v2/model/field-mapper.d.ts +4 -2
- package/runtime/types/flow-extension-runner/src/v2/model/params-model.d.ts +2 -2
- package/runtime/types/flow-extension-runner/src/v2/params/index.d.ts +1 -0
- package/runtime/types/flow-extension-runner/src/v2/params/json/encode.d.ts +7 -1
- package/runtime/types/flow-extension-runner/src/v2/params/schema/dictionary-binding.d.ts +37 -0
- package/runtime/types/flow-extension-runner/src/v2/params/zod.d.ts +7 -5
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/trigger-method.d.ts +12 -2
- package/runtime/types/flow-extension-runner/src/v2/realtime-triggers/types.d.ts +11 -2
- package/runtime/types/flow-extension-runner/src/v2/types.d.ts +1 -0
- package/runtime/types/shared/src/constants/error-codes.d.ts +3 -0
- package/runtime/types/shared/src/constants/index.d.ts +1 -0
- package/runtime/types/shared/src/constants/notification-types.d.ts +59 -0
- package/runtime/types/shared/src/constants/oauth-connection-error.d.ts +3 -0
- package/runtime/types/shared/src/errors/api.d.ts +11 -0
- package/runtime/types/shared/src/errors/index.d.ts +1 -0
- package/runtime/types/shared/src/errors/oauth-connection.d.ts +4 -0
- package/runtime/types/shared/src/scheme/flowrunner/java.dto.d.ts +26 -0
- package/runtime/types/shared/src/scheme/integration-connection/dto.d.ts +46 -4
- package/runtime/types/shared/src/scheme/notifications/dto.d.ts +1 -0
- package/runtime/types/shared/src/scheme/notifications/rest.d.ts +2 -0
- package/runtime/types/shared/src/scheme/shared-extensions/list.d.ts +52 -11
- package/runtime/types/shared/src/scheme/shared-extensions/workspace-stack.d.ts +2 -2
|
@@ -40,7 +40,9 @@ Notes:
|
|
|
40
40
|
It has no effect anywhere else: not on `z.text()`, which has no password mode, and not on an action or
|
|
41
41
|
trigger param, whose value lives in the flow definition and is readable through the API — masking that
|
|
42
42
|
input would suggest a protection that is not there. Put credentials in a `z.string()` config item.
|
|
43
|
-
- `.dictionary(ref)` binds a param to a dictionary for dynamic options and auto-derives its `dependsOn
|
|
43
|
+
- `.dictionary(ref)` binds a param to a dictionary for dynamic options and auto-derives its `dependsOn` — the
|
|
44
|
+
dictionary's criteria keys, or their `criteriaAliases` where the method calls them differently (see
|
|
45
|
+
[05-dictionaries.md](05-dictionaries.md#one-dictionary-differently-named-params)).
|
|
44
46
|
- `.dynamicProps({ dependsOn, execute })` loads the **inner fields** of an object param at design time, from
|
|
45
47
|
the values of the sibling params named in `dependsOn`. It is allowed on **top-level action params only**
|
|
46
48
|
(not on trigger params, config items, dictionary `criteria`, nested fields or an array's element), and the
|
|
@@ -2,7 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Dictionaries provide **dynamic options** for a param dropdown. `ext.dictionary(props)` returns a ref used
|
|
4
4
|
via `.dictionary(ref)` on a param (see [02-zod-types.md](02-zod-types.md)). A dictionary declares its
|
|
5
|
-
`criteria` once, and consumers auto-derive their `dependsOn` from it
|
|
5
|
+
`criteria` once, and consumers auto-derive their `dependsOn` from it — as the names of their own params, through
|
|
6
|
+
`criteriaAliases` when those differ (see [One dictionary, differently named params](#one-dictionary-differently-named-params)).
|
|
6
7
|
|
|
7
8
|
| Property | Type | Description |
|
|
8
9
|
|---|---|---|
|
|
@@ -11,6 +12,7 @@ via `.dictionary(ref)` on a param (see [02-zod-types.md](02-zod-types.md)). A di
|
|
|
11
12
|
| `label` | string | **Human-readable name** → `operationName`. Dictionaries are shown in the UI and exposed to AI tools, so **always set a label**. Falls back to `id` when omitted. |
|
|
12
13
|
| `description` | string | Description. |
|
|
13
14
|
| `criteria` | `z.object` | Optional dependency inputs (become `dependsOn` on consumers). Omit when the dictionary depends on nothing; declared ⇒ must be a `z.object` (see [03-parameters.md](03-parameters.md)). |
|
|
15
|
+
| `criteriaAliases` | `{ [criteriaKey]: string[] }` | Optional. Other param names a criteria key may be fed by, so one dictionary serves actions that call the same input differently. See [One dictionary, differently named params](#one-dictionary-differently-named-params). |
|
|
14
16
|
| `result` | `{ items, cursor }` \| `z.` schema | Optional sample output → `metaInfo.sampleResult` + `OBJECT` `returnType`. Omit → `sampleResult: null`, `returnType: OBJECT`. |
|
|
15
17
|
| `execute` | fn | see below. |
|
|
16
18
|
|
|
@@ -61,6 +63,62 @@ const tableIdParam = z.string()
|
|
|
61
63
|
- **The `id` starts with `get` and ends with `Dictionary`**, and the const holding the ref carries the same
|
|
62
64
|
name — so the declaration and every `.dictionary(ref)` read alike.
|
|
63
65
|
|
|
66
|
+
## One dictionary, differently named params
|
|
67
|
+
|
|
68
|
+
A consumer's `dependsOn` is the dictionary's criteria keys, so by default **a criteria key must have the same
|
|
69
|
+
name as the param that feeds it**. When actions call the same input differently — most of them say
|
|
70
|
+
`documentId`, but a copy action has a `sourceDocumentId` and a `targetDocumentId` — do not declare a second
|
|
71
|
+
dictionary and do not rename the params. Name the other params in `criteriaAliases`:
|
|
72
|
+
|
|
73
|
+
```js
|
|
74
|
+
const getSheetsDictionary = ext.dictionary({
|
|
75
|
+
id : 'getSheetsDictionary',
|
|
76
|
+
label : 'Sheets',
|
|
77
|
+
criteria : z.object({ documentId: z.string().optional() }),
|
|
78
|
+
criteriaAliases: { documentId: ['sourceDocumentId'] },
|
|
79
|
+
execute : async ({ search, criteria, apiRequest }) => {
|
|
80
|
+
// always `criteria.documentId`, whichever param the user filled in
|
|
81
|
+
},
|
|
82
|
+
})
|
|
83
|
+
|
|
84
|
+
// every consumer binds it the same way:
|
|
85
|
+
sheetId: z.number().label('Sheet').dictionary(getSheetsDictionary)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
- **Publishing.** Each consumer's `dependsOn` names whichever of `[key, ...aliases]` its own method declares:
|
|
89
|
+
`['documentId']` on an action with a `documentId` param, `['sourceDocumentId']` on the copy action. The
|
|
90
|
+
dropdown waits for, and reloads on, the param that is actually on the form. A consumer whose method declares
|
|
91
|
+
none of the names keeps the key, as without aliases.
|
|
92
|
+
- **Invoking.** Before `criteria` is validated, a blank key (`undefined`, `null` or `''`) is filled from the
|
|
93
|
+
first non-blank alias, in declaration order; a filled key wins. The aliases are then dropped with the other
|
|
94
|
+
undeclared fields, so **`execute` only ever sees the criteria key**.
|
|
95
|
+
- **What "declares" means.** A top-level param sees the method's top-level params. A field inside an object
|
|
96
|
+
sees the fields next to it **and** the method's top-level params — the same values the Flow Builder sends as
|
|
97
|
+
criteria. A field loaded by `.dynamicProps()` / `dynamicParams` sees the action's params too.
|
|
98
|
+
|
|
99
|
+
**A field must not see two names of one key.** If an action declares both `documentId` and its alias
|
|
100
|
+
`sourceDocumentId`, the Flow Builder sends both, and the dictionary cannot tell which document the user meant.
|
|
101
|
+
The service fails to load:
|
|
102
|
+
|
|
103
|
+
> `` action "copySheet": `params.sheetId` uses dictionary "getSheetsDictionary", whose criteria "documentId"
|
|
104
|
+
> can come from "documentId" or "sourceDocumentId" — and this field can see all of them, so the dictionary
|
|
105
|
+
> cannot tell which one is meant. ``
|
|
106
|
+
|
|
107
|
+
Rename one of the params, or bind that field to a dictionary without the alias.
|
|
108
|
+
|
|
109
|
+
`criteriaAliases` itself is checked when the service loads. Each of these fails with `FR_EXT_INVALID_SCHEMA`:
|
|
110
|
+
|
|
111
|
+
| Mistake | Message (after `dictionary "<id>": `) |
|
|
112
|
+
|---|---|
|
|
113
|
+
| not an object | `` `criteriaAliases` must be an object of `{ criteriaKey: ['otherParamName'] }`. `` |
|
|
114
|
+
| a key that is not in `criteria` | `` `criteriaAliases` names "x", which is not a key of its `criteria`. `` |
|
|
115
|
+
| an empty list, or a name that is not a non-empty string | `` `criteriaAliases.x` must be a non-empty array of param names. `` |
|
|
116
|
+
| an alias that is itself a criteria key | `` `criteriaAliases.x` names "y", which is itself a key of `criteria`. `` |
|
|
117
|
+
| one alias under two keys | `` "y" is an alias of both "x" and "z" — an alias may feed one criteria key only. `` |
|
|
118
|
+
|
|
119
|
+
Aliases never reach the published definition: `dependsOn` carries the consumer's names, and nothing else on
|
|
120
|
+
the wire changes.
|
|
121
|
+
|
|
64
122
|
## Browse versus resolve — a dictionary does not need a listing endpoint
|
|
65
123
|
|
|
66
124
|
`execute` receives **`search`**, the text the flow author has typed. That makes two different dictionaries
|
|
@@ -23,7 +23,35 @@ for the common case; any handler below overrides its step. Combined scopes = `sc
|
|
|
23
23
|
|---|---|---|
|
|
24
24
|
| `getConnectionURL` | `{ config, context, scopes }` | `string` (authorize URL) |
|
|
25
25
|
| `executeCallback` | `{ callbackObject, config, context }` | `{ token, expirationInSeconds?, refreshToken?, connectionIdentityName?, connectionIdentityImageURL?, overwrite?, userData? }` |
|
|
26
|
-
| `refreshToken` | `{ refreshToken, config, context }` | `{ token, expirationInSeconds?, refreshToken? }` |
|
|
26
|
+
| `refreshToken` | `{ refreshToken, config, context, oauth }` | `{ token, expirationInSeconds?, refreshToken? }` |
|
|
27
|
+
|
|
28
|
+
`getConnectionURL` and `executeCallback` run before any token exists, so their `oauth` is empty. `refreshToken`
|
|
29
|
+
is different: the platform sends the connection's **current (expired) token** in the `oauth-access-token`
|
|
30
|
+
header, so `oauth = { accessToken, token? }` and `initContext` see it exactly as in any other handler. That is
|
|
31
|
+
how a composite token survives a refresh — rebuild the next one from the data in the current one, because the
|
|
32
|
+
provider's refresh response does not repeat what it returned at connect time:
|
|
33
|
+
|
|
34
|
+
```js
|
|
35
|
+
refreshToken: async ({ refreshToken, config, oauth }) => {
|
|
36
|
+
const res = await exchangeRefreshToken(config, refreshToken)
|
|
37
|
+
|
|
38
|
+
// `oauth.token` is `deserializeToken(<current token>)` — carry the realm id over
|
|
39
|
+
return {
|
|
40
|
+
token : `${ res.access_token }::realm::${ oauth.token.realmId }`,
|
|
41
|
+
refreshToken: res.refresh_token ?? refreshToken,
|
|
42
|
+
expirationInSeconds: res.expires_in,
|
|
43
|
+
}
|
|
44
|
+
},
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Refresh failures
|
|
48
|
+
|
|
49
|
+
When a refresh fails, the platform shows the connection as needing a reconnect, fails the step with a
|
|
50
|
+
"reconnect it" error and notifies the workspace team. Any error from the refresh does this, as does a refresh that
|
|
51
|
+
returns no `token`: an outage, a timeout and a refused refresh token all ask the user to sign in again.
|
|
52
|
+
|
|
53
|
+
Nothing to do in the service: with the built-in refresh (declarative `tokenUrl`) or a custom `refreshToken`, let any
|
|
54
|
+
error propagate.
|
|
27
55
|
|
|
28
56
|
## Using OAuth in handlers
|
|
29
57
|
|
|
@@ -53,7 +53,7 @@ running and the error appears in the customer's **workspace log** on each refres
|
|
|
53
53
|
| `extractProviderEventData` | path \| fn | Base `providerEventData` handed to matched triggers. Default = whole body. |
|
|
54
54
|
| `scopeAt` | path | ALL_APPS routing key path (route where `scopeAt === eventScopeId`). |
|
|
55
55
|
| `verify` | object | Declarative signature check — see the field table below. |
|
|
56
|
-
| `handshake` | fn |
|
|
56
|
+
| `handshake` | fn | Decides which deliveries are endpoint-verification handshakes — replaces the empty-body default (see [Handshakes](#handshakes)). |
|
|
57
57
|
| `subscribe` | fn | Required (see table). |
|
|
58
58
|
| `unsubscribe` | fn | Required (see table). |
|
|
59
59
|
| `refresh` | fn | Optional. |
|
|
@@ -74,7 +74,7 @@ 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, webhookData }` | `{ responseToWebhook
|
|
77
|
+
| `handshake` | `{ requestBody, headers, rawBody, webhookData }` | `true` → ack with a plain 200; `{ responseToWebhook }` → ack with that response (runtime adds `handshake:true`); nothing / `false` / `{}` → proceed. See [Handshakes](#handshakes). |
|
|
78
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
|
|
@@ -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
|
+
### Handshakes
|
|
93
|
+
|
|
94
|
+
A handshake is a delivery the provider sends to check the callback URL rather than to report an event. It is
|
|
95
|
+
acked and goes no further: no `verify`, no routing, nothing fires.
|
|
96
|
+
|
|
97
|
+
**Without a `handshake` hook, an empty body is a handshake.** A body that is `null`, `''` or `{}` is acked with
|
|
98
|
+
`{ handshake: true, events: [] }` and a plain 200 — the URL-verification ping most providers send. Most
|
|
99
|
+
services need nothing more.
|
|
100
|
+
|
|
101
|
+
**A declared `handshake` replaces that default — it does not run before it.** The hook alone decides, and an
|
|
102
|
+
empty body it does not claim proceeds to `verify` and `resolveEvents` like any other delivery. That is what a
|
|
103
|
+
provider whose real events carry **no body** needs (Google Drive puts the whole notification in `X-Goog-*`
|
|
104
|
+
headers): with the default in place, its events would be acked as pings and never fire.
|
|
105
|
+
|
|
106
|
+
| The hook | The delivery |
|
|
107
|
+
|---|---|
|
|
108
|
+
| returns `true` | handshake — acked with a plain 200 |
|
|
109
|
+
| returns `{ responseToWebhook }` (or the deprecated `responseToExternalService` / `responseHeaders`) | handshake — answered with that response |
|
|
110
|
+
| returns nothing, `false`, or an object with no response in it (`{}`) | not a handshake — proceeds |
|
|
111
|
+
| throws | answered `{ events: [], responseToWebhook: { httpStatus, body: { message } } }` — the error's own `statusCode` (or `status`) when it is a 4xx, otherwise **400** |
|
|
112
|
+
|
|
113
|
+
```js
|
|
114
|
+
// Google Drive-style: a real change notification has no body. Only the channel-opened message is a handshake.
|
|
115
|
+
handshake: ({ headers }) => headers['x-goog-resource-state'] === 'sync',
|
|
116
|
+
|
|
117
|
+
// Slack-style: an echoed challenge — and, since the hook replaces the default, the empty-body ping too.
|
|
118
|
+
handshake: ({ requestBody }) => {
|
|
119
|
+
if (requestBody?.challenge) {
|
|
120
|
+
return { responseToWebhook: { rawBody: requestBody.challenge } }
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
return requestBody == null || Object.keys(requestBody).length === 0
|
|
124
|
+
},
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
⚠️ **`handshake` runs before signature verification**, so it sees an unverified request. Acking one is harmless
|
|
128
|
+
— a handshake never fires anything — but do not grant anything from it, and remember that a **thrown message
|
|
129
|
+
is sent to that unverified caller**: throw what the provider may read.
|
|
130
|
+
|
|
131
|
+
⚠️ **Declaring `handshake` for a challenge drops the empty-body default.** If the provider also pings with an
|
|
132
|
+
empty body, claim it in the hook (as above), or the ping proceeds to `verify` — which answers 401 when there is
|
|
133
|
+
no body to check.
|
|
134
|
+
|
|
92
135
|
### `webhookData` on the inbound path — read-only
|
|
93
136
|
|
|
94
137
|
Every inbound seam receives the **stored webhook document**: whatever `subscribe` (or `refresh`) last returned
|
|
@@ -271,6 +314,7 @@ Use `params` for **filters** — which chat, which board, which status — never
|
|
|
271
314
|
| `params` | `z.object` | – | Trigger config — omit if it takes none (see [03-parameters.md](03-parameters.md)). |
|
|
272
315
|
| `result` | value \| schema \| loader | ✓ | Emitted event shape (post-`extendResult`). |
|
|
273
316
|
| `extendEventData` | fn | – | see table. |
|
|
317
|
+
| `extendMatchData` | fn | – | see table, and [Filtering on data the delivery does not carry](#filtering-on-data-the-delivery-does-not-carry). |
|
|
274
318
|
| `match` | object \| fn | – | Instance selection (declarative object or predicate fn). |
|
|
275
319
|
| `extendResult` | fn | – | see table. |
|
|
276
320
|
| `oauth2Scopes` | string[] | – | Extra scopes. |
|
|
@@ -279,12 +323,67 @@ Use `params` for **filters** — which chat, which board, which status — never
|
|
|
279
323
|
|---|---|---|
|
|
280
324
|
| `extendEventData` | `{ requestBody, providerEventData }` | partial object (merged onto `providerEventData`, **pure, pre-match**) |
|
|
281
325
|
| `match` (object) | `{ paramKey: 'path.in.providerEventData' }` | declarative — type-coerced equality per filled param; empty param → all |
|
|
282
|
-
| `
|
|
326
|
+
| `extendMatchData` | `{ providerEventData, webhookData, instances:[{ id, params }], apiRequest, … }` (full ctx bag, on the connection's token) | partial object merged onto `providerEventData` for `match` and `extendResult` (**select, once per event, pre-match, may call API**) |
|
|
327
|
+
| `match` (fn) | `{ params, providerEventData, webhookData }` | `boolean` (or a Promise of one — awaited) — for ranges/contains/derived logic |
|
|
283
328
|
| `extendResult` | `{ providerEventData, webhookData, apiRequest, … }` | augmented `providerEventData` (**post-match, once if matched, may call API**); surfaces as `enrichedEventData` in the runtime response |
|
|
284
329
|
|
|
285
|
-
**Inbound runtime flow:** `handshake
|
|
330
|
+
**Inbound runtime flow:** `handshake` (or the empty-body default) → `verify`/`verifyRequest` → read `extractProviderEventName` → for
|
|
286
331
|
each trigger whose `providerEventName` matches, build `providerEventData` (`extractProviderEventData` +
|
|
287
|
-
`extendEventData`) → `match` per instance → if ≥1 matched,
|
|
332
|
+
`extendEventData`) → *(select)* `extendMatchData` once → `match` per instance → if ≥1 matched,
|
|
333
|
+
`extendResult` once → fire.
|
|
334
|
+
|
|
335
|
+
### Filtering on data the delivery does not carry
|
|
336
|
+
|
|
337
|
+
Many webhooks name a resource without describing it — Xero sends an invoice's id, not its type or status. An
|
|
338
|
+
instance filter on those fields can only be decided after **reading the resource**, and that needs the
|
|
339
|
+
connection's token, which exists only on the select seam. The hooks split along that line:
|
|
340
|
+
|
|
341
|
+
| Hook | Seam | Token / `apiRequest` | Runs | Can change who fires |
|
|
342
|
+
|---|---|---|---|---|
|
|
343
|
+
| `extendEventData` | resolve (declarative routing only — not with `resolveEvents`) | ✗ — no connection chosen yet | per trigger, per delivery | ✓ (pure) |
|
|
344
|
+
| `extendMatchData` | select | ✓ | once per event, **before** `match` | ✓ |
|
|
345
|
+
| `extendResult` | select | ✓ | once per event, **after** `match`, if ≥1 matched | ✗ |
|
|
346
|
+
|
|
347
|
+
So fetch what a filter needs in `extendMatchData`, and keep `match` declarative over the fetched fields:
|
|
348
|
+
|
|
349
|
+
```js
|
|
350
|
+
ext.addRealtimeTrigger({
|
|
351
|
+
id : 'onInvoiceUpdated',
|
|
352
|
+
params: z.object({ invoiceType: z.string().optional(), status: z.string().optional() }),
|
|
353
|
+
extendMatchData: async ({ providerEventData, apiRequest }) => {
|
|
354
|
+
const response = await apiRequest({ url: `${ API_BASE_URL }/Invoices/${ encodeURIComponent(providerEventData.resourceId) }` })
|
|
355
|
+
const invoice = response?.Invoices?.[0]
|
|
356
|
+
|
|
357
|
+
return invoice ? { invoice: { Type: invoice.Type, Status: invoice.Status } } : {}
|
|
358
|
+
},
|
|
359
|
+
match: { invoiceType: 'invoice.Type', status: 'invoice.Status' },
|
|
360
|
+
})
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
- **One read per event**, however many instances are configured — never put the read in an async `match`,
|
|
364
|
+
which runs once per instance.
|
|
365
|
+
- **Read only when a flow filters.** The runtime skips the hook when nothing would read its result: no
|
|
366
|
+
configured instances, no `match` declared, or a declarative `match` none of whose params any instance has
|
|
367
|
+
filled (an empty param means "any", so every instance matches whatever the read returns). An event with no
|
|
368
|
+
filtering flow therefore costs no provider call.
|
|
369
|
+
- **Behind a predicate `match`, decide it yourself.** The runtime cannot see which params a function reads, so
|
|
370
|
+
the hook always runs and receives `instances` — `[{ id, params }]` for every configured instance — to skip
|
|
371
|
+
the read when none of them filters on what it would fetch:
|
|
372
|
+
|
|
373
|
+
```js
|
|
374
|
+
extendMatchData: async ({ providerEventData, apiRequest, instances }) => {
|
|
375
|
+
if (!instances.some(({ params }) => params.minAmount != null)) {
|
|
376
|
+
return {}
|
|
377
|
+
}
|
|
378
|
+
…
|
|
379
|
+
},
|
|
380
|
+
match: ({ params, providerEventData }) => params.minAmount == null || providerEventData.amount >= params.minAmount,
|
|
381
|
+
```
|
|
382
|
+
- **The fired event is unchanged.** What it returns is merged onto `providerEventData` for `match` and
|
|
383
|
+
`extendResult` only; to put fetched data on the event, return it from `extendResult`.
|
|
384
|
+
- **A failed read is not a failed delivery.** If it throws, the runtime logs a warning and matches on the
|
|
385
|
+
delivered data: instances filtering on the missing fields decline, unfiltered ones still fire. Return `{}`
|
|
386
|
+
(or nothing) for "not found" to get the same outcome without the warning.
|
|
288
387
|
|
|
289
388
|
**A trigger declaring no `match` fires every configured instance** — "no filter" means "fires always", and
|
|
290
389
|
that is a different case from a name this service does not declare, which selects nothing (see
|
|
@@ -70,6 +70,12 @@ All params are body params (`queryParams` is always `[]`). A param's information
|
|
|
70
70
|
**Nested object properties are the exception** — they inline their display metadata (`label`, `uiComponent`,
|
|
71
71
|
`dictionary`, `dependsOn`) directly on the property.
|
|
72
72
|
|
|
73
|
+
**A dictionary-bound field's `dependsOn` names the consumer's own params.** It is the dictionary's criteria keys,
|
|
74
|
+
each replaced by the alias the field's method declares when the dictionary has `criteriaAliases`
|
|
75
|
+
([05-dictionaries.md](05-dictionaries.md#one-dictionary-differently-named-params)). The same names appear in
|
|
76
|
+
`metaInfo.args`, on nested properties, and in `paramsSchema` as `meta.frDictionary: { id, dependsOn }`. The
|
|
77
|
+
aliases themselves are never published.
|
|
78
|
+
|
|
73
79
|
**A platform param group is the other exception.** `z.filesUploadOptions([…])` and its siblings
|
|
74
80
|
(see [03-parameters.md](03-parameters.md)) publish their `uiComponent` token on the param *as well as* in
|
|
75
81
|
`metaInfo.args`, at every depth. That token says what the param **is**, not how one control should look, so a
|
|
@@ -110,7 +110,7 @@ spec asserting on a query-string branch silently drives the wrong path.
|
|
|
110
110
|
|
|
111
111
|
**`webhookData` is the webhook document the platform stored** — what `subscribe`/`refresh` last returned —
|
|
112
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
|
|
113
|
+
`extendMatchData`/`match`/`extendResult` on `handleTriggerSelectMatched`, and is `null` when none is stored or when the request
|
|
114
114
|
carries no workspace to look one up for (the general callback of a service that is not app-hosted). Both
|
|
115
115
|
methods only **read** it: neither response carries a `webhookData` field, so a document returned from one is
|
|
116
116
|
dropped — only upsert/refresh/delete persist. The harness never supplies it on its own: pass it in
|
|
@@ -118,8 +118,11 @@ dropped — only upsert/refresh/delete persist. The harness never supplies it on
|
|
|
118
118
|
([09-realtime-triggers.md](09-realtime-triggers.md#webhookdata-on-the-inbound-path--read-only)).
|
|
119
119
|
|
|
120
120
|
It answers `{ events: [] }` for a delivery no trigger claims, and `{ handshake: true, events: [] }` for an
|
|
121
|
-
empty body
|
|
122
|
-
|
|
121
|
+
empty body (`null`, `''` or `{}`) **when the service declares no `handshake`**. A declared `handshake`
|
|
122
|
+
replaces that default: an empty body it does not claim proceeds to `verify` and `resolveEvents`, and a
|
|
123
|
+
`handshake` that throws resolves with `{ events: [], responseToWebhook: { httpStatus, body: { message } } }`
|
|
124
|
+
(the error's 4xx, otherwise 400) rather than rejecting
|
|
125
|
+
([09-realtime-triggers.md](09-realtime-triggers.md#handshakes)). A `verify` / `verifyRequest` that turns a delivery down
|
|
123
126
|
**resolves** with `{ events: [], responseToWebhook: { httpStatus: 401, rawBody: '' } }` — it does not reject,
|
|
124
127
|
so assert on the returned value, not on a thrown error.
|
|
125
128
|
|