@lowdefy/docs-content 6.1.0 → 7.0.0

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 (285) hide show
  1. package/README.md +1 -0
  2. package/content/actions/downloadcsv.md +1 -1
  3. package/content/actions/emailotpsend.md +58 -0
  4. package/content/actions/emailotpverify.md +79 -0
  5. package/content/actions/getlocalstorage.md +43 -0
  6. package/content/actions/link.md +47 -1
  7. package/content/actions/login.md +25 -5
  8. package/content/actions/logout.md +7 -5
  9. package/content/actions/magiclinkverify.md +117 -0
  10. package/content/actions/pdfmake.md +2 -2
  11. package/content/actions/posthogalias.md +29 -0
  12. package/content/actions/posthogcapture.md +49 -0
  13. package/content/actions/posthogcapturepageleave.md +38 -0
  14. package/content/actions/posthogfeatureflag.md +50 -0
  15. package/content/actions/posthoggroup.md +37 -0
  16. package/content/actions/posthogidentify.md +54 -0
  17. package/content/actions/posthoginit.md +96 -0
  18. package/content/actions/posthogoptin.md +29 -0
  19. package/content/actions/posthogoptout.md +29 -0
  20. package/content/actions/posthogpageview.md +37 -0
  21. package/content/actions/posthogreloadfeatureflags.md +47 -0
  22. package/content/actions/posthogreset.md +28 -0
  23. package/content/actions/posthogsetpersonproperties.md +36 -0
  24. package/content/actions/removelocalstorage.md +28 -0
  25. package/content/actions/resetvalidation.md +5 -3
  26. package/content/actions/setdarkmode.md +3 -3
  27. package/content/actions/setglobal.md +2 -0
  28. package/content/actions/setlocale.md +1 -1
  29. package/content/actions/setlocalstorage.md +34 -0
  30. package/content/actions/setstate.md +2 -0
  31. package/content/actions/validate.md +7 -4
  32. package/content/adapter-reference/mongodbauthadapter.md +46 -0
  33. package/content/agents/agent-endpoint-tools.md +24 -0
  34. package/content/agents/agent-properties.md +13 -3
  35. package/content/agents/agent-server-hooks.md +1 -1
  36. package/content/agents/agentchat.md +43 -7
  37. package/content/agents/agentconversations.md +42 -8
  38. package/content/agents/agents-introduction.md +107 -0
  39. package/content/callback-reference/auth0logoutcallback.md +54 -0
  40. package/content/concepts/ai-agent-docs.md +455 -106
  41. package/content/concepts/blocks.md +150 -0
  42. package/content/concepts/connections-and-requests.md +402 -0
  43. package/content/concepts/custom-html.md +42 -0
  44. package/content/concepts/custom-styling.md +50 -5
  45. package/content/concepts/dynamic-page-content.md +309 -0
  46. package/content/concepts/events-and-actions.md +154 -2
  47. package/content/concepts/four-primitives.md +31 -0
  48. package/content/concepts/html-attributes.md +293 -0
  49. package/content/concepts/i18n.md +8 -3
  50. package/content/concepts/keyboard-shortcuts.md +2 -2
  51. package/content/concepts/layout-overview.md +1 -1
  52. package/content/concepts/logger.md +99 -0
  53. package/content/concepts/lowdefy-api.md +1319 -0
  54. package/content/concepts/lowdefy-schema.md +136 -3
  55. package/content/concepts/menus.md +8 -7
  56. package/content/concepts/module-authoring.md +76 -5
  57. package/content/concepts/modules.md +3 -1
  58. package/content/concepts/notifications.md +180 -0
  59. package/content/concepts/operators.md +7 -0
  60. package/content/concepts/page-and-app-state.md +252 -0
  61. package/content/concepts/page-paths.md +209 -0
  62. package/content/concepts/theming.md +582 -0
  63. package/content/connections/aigateway.md +375 -0
  64. package/content/connections/anthropic.md +169 -2
  65. package/content/connections/awss3.md +178 -2
  66. package/content/connections/axioshttp.md +181 -0
  67. package/content/connections/google.md +169 -2
  68. package/content/connections/mongodb.md +1014 -3
  69. package/content/connections/openai-connection.md +169 -2
  70. package/content/connections/sendgridmail.md +2 -0
  71. package/content/connections/smtp.md +3 -1
  72. package/content/connections/treg.md +329 -0
  73. package/content/container-blocks/affix.md +47 -7
  74. package/content/container-blocks/alert.md +76 -24
  75. package/content/container-blocks/badge.md +100 -24
  76. package/content/container-blocks/box.md +9 -9
  77. package/content/container-blocks/card.md +132 -27
  78. package/content/container-blocks/carousel.md +60 -7
  79. package/content/container-blocks/collapse.md +153 -9
  80. package/content/container-blocks/configprovider.md +35 -13
  81. package/content/container-blocks/confirmmodal.md +69 -23
  82. package/content/container-blocks/content.md +62 -98
  83. package/content/container-blocks/descriptions.md +45 -4
  84. package/content/container-blocks/drawer.md +139 -28
  85. package/content/container-blocks/dropdownmenu.md +119 -31
  86. package/content/container-blocks/flex.md +40 -62
  87. package/content/container-blocks/footer.md +15 -11
  88. package/content/container-blocks/googlemapsheatmap.md +1 -1
  89. package/content/container-blocks/googlemapsscript.md +2 -2
  90. package/content/container-blocks/header.md +71 -36
  91. package/content/container-blocks/label.md +34 -7
  92. package/content/container-blocks/layout.md +52 -34
  93. package/content/container-blocks/masonry.md +17 -71
  94. package/content/container-blocks/mobilemenu.md +131 -88
  95. package/content/container-blocks/modal.md +161 -26
  96. package/content/container-blocks/pageheadermenu.md +138 -31
  97. package/content/container-blocks/pagesidebarlayout.md +230 -27
  98. package/content/container-blocks/pagesidermenu.md +153 -43
  99. package/content/container-blocks/popover.md +34 -31
  100. package/content/container-blocks/result.md +32 -21
  101. package/content/container-blocks/sider.md +85 -122
  102. package/content/container-blocks/span.md +7 -7
  103. package/content/container-blocks/spinner.md +3 -3
  104. package/content/container-blocks/splitter.md +150 -68
  105. package/content/container-blocks/tabs.md +64 -12
  106. package/content/container-blocks/tooltip.md +22 -46
  107. package/content/container-blocks/watermark.md +22 -4
  108. package/content/controls/parallel_for.md +21 -2
  109. package/content/controls/reject.md +24 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +1 -0
  112. package/content/controls/try.md +4 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +10 -7
  115. package/content/deployment/docker.md +22 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +17 -6
  118. package/content/display-blocks/aggrid.md +33 -16
  119. package/content/display-blocks/anchor.md +16 -15
  120. package/content/display-blocks/avatar.md +57 -37
  121. package/content/display-blocks/breadcrumb.md +70 -21
  122. package/content/display-blocks/button.md +93 -19
  123. package/content/display-blocks/calendar.md +12 -0
  124. package/content/display-blocks/clickablehtml.md +239 -0
  125. package/content/display-blocks/dangeroushtml.md +1 -1
  126. package/content/display-blocks/difflist.md +1 -1
  127. package/content/display-blocks/difftimeline.md +1 -1
  128. package/content/display-blocks/divider.md +64 -3
  129. package/content/display-blocks/dropdownbutton.md +81 -30
  130. package/content/display-blocks/echart.md +35 -1
  131. package/content/display-blocks/eventlog.md +363 -0
  132. package/content/display-blocks/floatbutton.md +129 -42
  133. package/content/display-blocks/html.md +61 -1
  134. package/content/display-blocks/icon.md +250 -67
  135. package/content/display-blocks/img.md +2 -2
  136. package/content/display-blocks/menu.md +146 -73
  137. package/content/display-blocks/message.md +38 -124
  138. package/content/display-blocks/notification.md +94 -222
  139. package/content/display-blocks/paragraph.md +59 -9
  140. package/content/display-blocks/pollingtimer.md +263 -0
  141. package/content/display-blocks/progress.md +96 -17
  142. package/content/display-blocks/qrcode.md +19 -4
  143. package/content/display-blocks/s3download.md +1 -1
  144. package/content/display-blocks/search.md +19 -9
  145. package/content/display-blocks/skeletonbutton.md +1 -0
  146. package/content/display-blocks/skeletoninput.md +1 -0
  147. package/content/display-blocks/statistic.md +75 -17
  148. package/content/display-blocks/steps.md +58 -25
  149. package/content/display-blocks/table.md +2527 -0
  150. package/content/display-blocks/tablelight.md +621 -0
  151. package/content/display-blocks/tag.md +102 -17
  152. package/content/display-blocks/title.md +50 -11
  153. package/content/display-blocks/tour.md +33 -23
  154. package/content/input-blocks/autocomplete.md +81 -9
  155. package/content/input-blocks/buttonselector.md +45 -8
  156. package/content/input-blocks/captcha.md +40 -0
  157. package/content/input-blocks/checkboxselector.md +97 -7
  158. package/content/input-blocks/checkboxswitch.md +33 -3
  159. package/content/input-blocks/colorselector.md +63 -14
  160. package/content/input-blocks/daterangeselector.md +165 -45
  161. package/content/input-blocks/dateselector.md +139 -41
  162. package/content/input-blocks/datetimeselector.md +158 -49
  163. package/content/input-blocks/inputgallery.md +3 -3
  164. package/content/input-blocks/intentinput.md +207 -0
  165. package/content/input-blocks/monthselector.md +120 -52
  166. package/content/input-blocks/multipleselector.md +150 -39
  167. package/content/input-blocks/numberinput.md +98 -12
  168. package/content/input-blocks/pagination.md +70 -14
  169. package/content/input-blocks/paragraphinput.md +51 -37
  170. package/content/input-blocks/passwordinput.md +60 -6
  171. package/content/input-blocks/phonenumberinput.md +59 -26
  172. package/content/input-blocks/placesautocomplete.md +319 -0
  173. package/content/input-blocks/radioselector.md +83 -7
  174. package/content/input-blocks/ratingslider.md +57 -26
  175. package/content/input-blocks/s3uploadbutton.md +24 -24
  176. package/content/input-blocks/s3uploaddragger.md +3 -3
  177. package/content/input-blocks/s3uploadphoto.md +5 -5
  178. package/content/input-blocks/segmentedselector.md +72 -32
  179. package/content/input-blocks/selector.md +109 -21
  180. package/content/input-blocks/switch.md +65 -17
  181. package/content/input-blocks/tableinput.md +445 -0
  182. package/content/input-blocks/tagmultipleselector.md +114 -0
  183. package/content/input-blocks/tagselector.md +114 -0
  184. package/content/input-blocks/textarea.md +32 -3
  185. package/content/input-blocks/textinput.md +70 -29
  186. package/content/input-blocks/tiptapinput.md +1 -1
  187. package/content/input-blocks/tiptapmentioninput.md +2 -2
  188. package/content/input-blocks/titleinput.md +39 -12
  189. package/content/input-blocks/treeinput.md +49 -25
  190. package/content/input-blocks/treemultipleselector.md +127 -10
  191. package/content/input-blocks/treeselector.md +97 -9
  192. package/content/input-blocks/upload.md +64 -15
  193. package/content/input-blocks/uploaddragger.md +17 -1
  194. package/content/input-blocks/uploadphoto.md +18 -1
  195. package/content/input-blocks/weekselector.md +120 -55
  196. package/content/learn/introduction.md +27 -0
  197. package/content/learn/quickstart.md +53 -0
  198. package/content/learn/showcase.md +8 -0
  199. package/content/list-blocks/controlledlist.md +24 -15
  200. package/content/list-blocks/list.md +11 -11
  201. package/content/list-blocks/masonrylist.md +7 -34
  202. package/content/migration/auth-upgrade.md +337 -0
  203. package/content/migration/upgrade-guide.md +1 -0
  204. package/content/migration/v3-to-v4.md +417 -0
  205. package/content/migration/v6-to-v7.md +620 -0
  206. package/content/operators/_agent.md +155 -0
  207. package/content/operators/_app.md +2 -1
  208. package/content/operators/_array.md +122 -1
  209. package/content/operators/_build.md +1 -0
  210. package/content/operators/_credential.md +57 -0
  211. package/content/operators/_cron.md +292 -0
  212. package/content/operators/_date.md +2 -0
  213. package/content/operators/_error.md +24 -1
  214. package/content/operators/_get.md +6 -6
  215. package/content/operators/_hmac.md +78 -0
  216. package/content/operators/_js.md +2 -1
  217. package/content/operators/_location.md +1 -1
  218. package/content/operators/_media.md +13 -0
  219. package/content/operators/_module.md +56 -2
  220. package/content/operators/_operator.md +17 -3
  221. package/content/operators/_path_params.md +82 -0
  222. package/content/operators/_ref.md +258 -0
  223. package/content/operators/_request.md +1 -1
  224. package/content/operators/_request_details.md +6 -0
  225. package/content/operators/_type.md +14 -3
  226. package/content/operators/_url_query.md +2 -0
  227. package/content/operators/_user.md +3 -3
  228. package/content/plugins/plugins-actions.md +10 -0
  229. package/content/plugins/plugins-connections.md +25 -0
  230. package/content/plugins/plugins-dev.md +66 -0
  231. package/content/plugins/plugins-icon-sets.md +267 -0
  232. package/content/plugins/plugins-introduction.md +27 -1
  233. package/content/plugins/plugins.md +19 -0
  234. package/content/plugins/posthog.md +359 -0
  235. package/content/provider-reference/auth-js-providers.md +107 -0
  236. package/content/provider-reference/openidconnectprovider.md +44 -0
  237. package/content/recipes/recipes.md +16 -0
  238. package/content/reference/actions-reference.md +31 -0
  239. package/content/reference/blocks-reference.md +35 -0
  240. package/content/reference/cli.md +403 -0
  241. package/content/reference/connections-reference.md +23 -0
  242. package/content/reference/operators-reference.md +47 -0
  243. package/content/reference/reference.md +16 -0
  244. package/content/reference/schema-reference.md +12 -0
  245. package/content/testing/config-tests.md +677 -0
  246. package/content/testing/e2e-configuration.md +31 -1
  247. package/content/testing/e2e-getting-started.md +1 -1
  248. package/content/testing/e2e-introduction.md +1 -1
  249. package/content/testing/e2e-writing-tests.md +12 -1
  250. package/content/testing/explore-pull-request.md +136 -0
  251. package/content/testing/journey-data-sets.md +326 -0
  252. package/content/tutorial/tutorial-actions-operators.md +2 -2
  253. package/content/tutorial/tutorial-add-blocks.md +2 -2
  254. package/content/tutorial/tutorial-create-page.md +48 -2
  255. package/content/tutorial/tutorial-display-data-page.md +3 -3
  256. package/content/tutorial/tutorial-requests-api.md +155 -0
  257. package/content/tutorial/tutorial-requests-sql.md +153 -0
  258. package/content/tutorial/tutorial-start.md +66 -1
  259. package/content/user-authentication/auth-configuration.md +267 -0
  260. package/content/user-authentication/auth-providers.md +24 -0
  261. package/content/user-authentication/auth-steps.md +141 -0
  262. package/content/user-authentication/login-and-logout.md +160 -8
  263. package/content/user-authentication/mcp-oauth.md +424 -0
  264. package/content/user-authentication/organizations.md +246 -0
  265. package/content/user-authentication/protected-pages-apis.md +97 -0
  266. package/content/user-authentication/roles.md +49 -0
  267. package/content/user-authentication/two-factor.md +229 -0
  268. package/content/user-authentication/user-object.md +58 -0
  269. package/content/user-authentication/users-introduction.md +8 -0
  270. package/content/websockets/websocket-publish.md +105 -0
  271. package/content/websockets/websocket-subscriptions.md +136 -0
  272. package/content/websockets/websockets-introduction.md +101 -0
  273. package/hazards.json +56 -0
  274. package/index.json +3458 -14
  275. package/package.json +10 -1
  276. package/scripts/extractAgentDocs.js +41 -30
  277. package/scripts/hashDocSources.js +38 -0
  278. package/scripts/isRedirectPage.js +26 -0
  279. package/scripts/recordSourceHashes.js +97 -0
  280. package/scripts/resolvePageSections.js +42 -0
  281. package/scripts/sectionKind.js +27 -0
  282. package/content/concepts/cli.md +0 -223
  283. package/content/other/introduction.md +0 -39
  284. package/content/other/next-auth-providers.md +0 -3
  285. /package/content/{other → actions}/updatesession.md +0 -0
@@ -69,7 +69,9 @@ The same connection and requests work against any S3-compatible service — set
69
69
  ## Requests
70
70
 
71
71
  Request types:
72
+ - AwsS3DeleteObject
72
73
  - AwsS3GetObject
74
+ - AwsS3HeadObject
73
75
  - AwsS3PresignedGetObject
74
76
  - AwsS3PresignedPostPolicy
75
77
  - AwsS3PutObject
@@ -196,6 +198,59 @@ api:
196
198
  _step: put_copy.key
197
199
  ```
198
200
 
201
+ ### AwsS3HeadObject
202
+
203
+ The `AwsS3HeadObject` request checks on the server whether an object exists in the bucket and
204
+ returns its metadata without reading its content. Use it in an [API endpoint](/lowdefy-api) routine
205
+ to confirm a file uploaded from the browser with an `AwsS3PresignedPostPolicy` actually arrived, and
206
+ to take its size and content type from S3 rather than from the caller. The connection must allow
207
+ reads (`read` is `true` by default).
208
+
209
+ #### Properties
210
+ - `key: string`: __Required__ - Key under which the object is stored.
211
+ - `versionId: string`: VersionId used to reference a specific version of the object.
212
+
213
+ Returns `{ exists: true, bucket, key, size, contentType, etag, lastModified, versionId }` for an
214
+ object that exists (`size` in bytes, `lastModified` a date, `contentType` and `versionId` only when
215
+ S3 returns them), and `{ exists: false, bucket, key }` when S3 answers not found. Any other S3 error
216
+ throws. S3 answers not found only when the credentials may list the bucket (`s3:ListBucket`);
217
+ without that permission a missing object is a 403 error, which throws.
218
+
219
+ #### Examples
220
+
221
+ ###### Record an upload only once it is in the bucket:
222
+ ```yaml
223
+ api:
224
+ - id: record_upload
225
+ type: Api
226
+ routine:
227
+ - id: head_object
228
+ type: AwsS3HeadObject
229
+ connectionId: my_bucket
230
+ properties:
231
+ key:
232
+ _payload: key
233
+ - :if:
234
+ _not:
235
+ _step: head_object.exists
236
+ :then:
237
+ - :reject: The upload did not arrive.
238
+ - id: insert_file
239
+ type: MongoDBInsertOne
240
+ connectionId: files
241
+ properties:
242
+ doc:
243
+ key:
244
+ _step: head_object.key
245
+ size:
246
+ _step: head_object.size
247
+ contentType:
248
+ _step: head_object.contentType
249
+ - ':return':
250
+ size:
251
+ _step: head_object.size
252
+ ```
253
+
199
254
  ### AwsS3PutObject
200
255
 
201
256
  The `AwsS3PutObject` request writes an object to the bucket from the server. It accepts base64 encoded
@@ -203,12 +258,31 @@ content, which makes it the storage half of the server-side file handling patter
203
258
  `emitFileContent: true` sends the file as a base64 payload to an [API endpoint](/lowdefy-api) with the
204
259
  `CallAPI` action, and a routine step stores it. The connection must set `write: true`.
205
260
 
261
+ In place of `content`, it takes a `url` and streams what that https link answers into the bucket, so a
262
+ routine can copy a file it is handed as a presigned link without the bytes passing through the routine.
263
+ The copy is capped at `maxBytes`, can be limited to `contentTypes`, and must finish within `timeout`.
264
+
206
265
  #### Properties
207
266
  - `key: string`: __Required__ - Key under which the object will be stored.
208
- - `content: string`: __Required__ - Object content as a base64 encoded string.
209
- - `contentType: string`: MIME type of the object (sets the Content-Type of the stored object).
267
+ - `content: string`: Object content as a base64 encoded string. Give either `content` or `url`.
268
+ - `url: string`: An `https:` link to a public address whose answer is streamed into the bucket. Give either `content` or `url`.
269
+ - `maxBytes: integer`: __Required with `url`__ - The most bytes the link may answer with. A `Content-Length` over it is refused before the body is read, and a body that passes it is cut off and refused, so nothing larger is stored.
270
+ - `contentTypes: string[]`: With `url`, the content types the link may answer with, such as `image/png`, `image/*` or `application/pdf`. Any other answer is refused.
271
+ - `timeout: integer`: Default: `20000` - With `url`, the milliseconds the whole fetch and upload may take.
272
+ - `contentType: string`: MIME type of the object (sets the Content-Type of the stored object). With `url`, the stored object takes the link's `Content-Type` unless this is given.
210
273
  - `acl: enum`: Access control lists used to grant read and write access (same values as AwsS3PresignedPostPolicy).
211
274
 
275
+ Returns `{ bucket, key, size, contentType }`, with `size` in bytes and `contentType` the stored content type, or `null` when there is none.
276
+
277
+ A refused copy from a `url` stores nothing and throws an error whose `code` names the reason, so a `:catch` can answer each its own way (`_error: code`):
278
+
279
+ - `url_not_https`: the link, or a link it redirects to, is not `https:`. Refused before that link is requested.
280
+ - `url_not_public`: the link, or a link it redirects to, leads to an address that is not public: loopback, private, link-local (such as a cloud metadata address), unique-local, carrier-grade NAT, unspecified or multicast. The address is checked as the connection is opened, so nothing is sent to it.
281
+ - `too_large`: the answer is larger than `maxBytes`.
282
+ - `content_type`: the answer's `Content-Type` is not one of `contentTypes`.
283
+ - `fetch_failed`: the link answered with a status that is not 2xx (the error's `statusCode` holds it), could not be reached, or sent a body that does not match its `Content-Length`.
284
+ - `timeout`: the fetch and upload took longer than `timeout`.
285
+
212
286
  #### Examples
213
287
 
214
288
  ###### Store a file sent as an endpoint payload:
@@ -234,6 +308,108 @@ api:
234
308
  _step: put_object.key
235
309
  ```
236
310
 
311
+ ###### Copy a screenshot handed over as a presigned link:
312
+ ```yaml
313
+ api:
314
+ - id: copy_screenshot
315
+ type: InternalApi
316
+ routine:
317
+ - :try:
318
+ - id: copy
319
+ type: AwsS3PutObject
320
+ connectionId: my_bucket
321
+ properties:
322
+ key:
323
+ _string.concat:
324
+ - 'screenshots/'
325
+ - _payload: ticket_id
326
+ url:
327
+ _payload: screenshot_url
328
+ maxBytes: 10000000
329
+ contentTypes:
330
+ - image/*
331
+ :catch:
332
+ - :if:
333
+ _eq:
334
+ - _error: code
335
+ - too_large
336
+ :then:
337
+ :reject: The screenshot is larger than 10 MB.
338
+ - :throw:
339
+ _error: true
340
+ - ':return':
341
+ size:
342
+ _step: copy.size
343
+ ```
344
+
345
+ ### AwsS3DeleteObject
346
+
347
+ The `AwsS3DeleteObject` request deletes one object, or up to 1000 objects in one call, from the
348
+ connection's bucket. Use it in an [API endpoint](/lowdefy-api) routine to remove objects the routine
349
+ stored and no longer wants, such as the files it copied before a later step refused the call. It
350
+ deletes only from the bucket the connection names; the request takes no bucket. The connection must
351
+ set `write: true`.
352
+
353
+ #### Properties
354
+ - `key: string`: Key of the object to delete. Give either `key` or `keys`.
355
+ - `keys: string[]`: Keys of the objects to delete, 1 to 1000. Give either `key` or `keys`.
356
+
357
+ Returns `{ bucket, deleted, errors }`: `deleted` lists the keys deleted, and `errors` lists each key
358
+ S3 could not delete as `{ key, code, message }`, such as `AccessDenied`. A key with no object
359
+ counts as deleted, as S3 reports it. A failure of the call itself, such as wrong credentials or a
360
+ missing bucket, throws. With one `key`, a key S3 cannot delete throws too, so `errors` is always
361
+ empty.
362
+
363
+ #### Examples
364
+
365
+ ###### Remove both copies when either copy is refused:
366
+ ```yaml
367
+ api:
368
+ - id: attach_files
369
+ type: Api
370
+ routine:
371
+ - :try:
372
+ - id: copy_screenshot
373
+ type: AwsS3PutObject
374
+ connectionId: my_bucket
375
+ properties:
376
+ key:
377
+ _string.concat:
378
+ - 'tickets/'
379
+ - _payload: ticket_id
380
+ - '/screenshot'
381
+ url:
382
+ _payload: screenshot_url
383
+ maxBytes: 10000000
384
+ - id: copy_log
385
+ type: AwsS3PutObject
386
+ connectionId: my_bucket
387
+ properties:
388
+ key:
389
+ _string.concat:
390
+ - 'tickets/'
391
+ - _payload: ticket_id
392
+ - '/log'
393
+ url:
394
+ _payload: log_url
395
+ maxBytes: 10000000
396
+ :catch:
397
+ - id: remove_copies
398
+ type: AwsS3DeleteObject
399
+ connectionId: my_bucket
400
+ properties:
401
+ keys:
402
+ - _string.concat:
403
+ - 'tickets/'
404
+ - _payload: ticket_id
405
+ - '/screenshot'
406
+ - _string.concat:
407
+ - 'tickets/'
408
+ - _payload: ticket_id
409
+ - '/log'
410
+ - :reject: The files could not be stored.
411
+ ```
412
+
237
413
  ## Creating a bucket
238
414
 
239
415
  ###### Step 1 - Create an AWS account
@@ -0,0 +1,181 @@
1
+ # AxiosHttp
2
+
3
+ The `AxiosHttp` connection is used to connect to APIs and web servers using HTTP or HTTPS.
4
+
5
+ It uses the [axios](https://github.com/axios/axios) library.
6
+
7
+ The same properties can be set on both connections and requests. The properties will be merged, with the request properties overwriting connection properties. This allows properties like authentication headers and the baseURL to be set on the connection, with request specific properties like the request.
8
+
9
+ >Secrets like authentication headers and API keys should be stored using the [`_secret`](_secret) operator.
10
+
11
+ ## Connections
12
+
13
+ Connection types:
14
+ - AxiosHttp
15
+
16
+ ## Requests
17
+
18
+ Request types:
19
+ - AxiosHttp
20
+
21
+ ### AxiosHttp
22
+
23
+ #### Properties
24
+
25
+ - `url: string`: The server URL that will be used for the request.
26
+ - `method: enum`: Default: `'get'` - The request method to be used when making the request. Options are:
27
+ - `'get'`
28
+ - `'delete'`
29
+ - `'head'`
30
+ - `'options'`
31
+ - `'post'`
32
+ - `'put'`
33
+ - `'patch'`
34
+ - `baseURL: string`: `baseURL` will be prepended to `url` unless `url` is absolute. It can be convenient to set `baseURL` for an axios connection to pass relative URLs to requests or mutations using that connection.
35
+ - `headers: object`: An object with custom headers to be sent sent with the request. The object keys should be header names, and the values should be the string header values.
36
+ - `params: object`: An object with URL parameters to be sent with the request.
37
+ - `data: string | object | array`: The data to be sent as the request body. Only applicable for request methods `'put'`, `'post'`, and `'patch'`. Can be an object, array or a string in the format `'Country=Brasil&City=Belo Horizonte'`.
38
+ - `auth: object`: Indicates that HTTP Basic authorization should be used, and supplies credentials. This will set an `Authorization` header, overwriting any existing `Authorization` custom headers you have set using `headers`. Only HTTP Basic auth is configurable through this parameter, for Bearer tokens and such, use `Authorization` custom headers instead. The `auth` object should have the following fields:
39
+ - `username: string`
40
+ - `password: string`
41
+ - `httpAgentOptions: object`: Options to pass to the Node.js [`http.Agent`](https://nodejs.org/api/http.html#http_class_http_agent) class.
42
+ - `httpsAgentOptions: object`: Options to pass to the Node.js [`https.Agent`](https://nodejs.org/api/http.html#http_class_http_agent) class.
43
+ - `maxContentLength: number`: Defines the max size of the http response content allowed in bytes.
44
+ - `maxRedirects: number`: Defines the maximum number of redirects to follow. If set to 0, no redirects will be followed.
45
+ - `proxy: object`: Defines the hostname and port of the proxy server. The `proxy` object should have the following fields:
46
+ - `host: string`: Host IP address (eg. `'127.0.0.1'`).
47
+ - `port: number`: Port number.
48
+ - `auth: object`: Object with username and password.
49
+ - `responseType: enum`: Default: `'json'` - The type of data that the server will respond with. Options are:
50
+ - `'document'`
51
+ - `'json'`
52
+ - `'text'`
53
+ - `responseEncoding: string`: Default: `'utf8'` - Indicates encoding to use for decoding responses.
54
+ - `timeout: number`: Default: `0` (no timeout) - The number of milliseconds before the request times out. If the request takes longer than `timeout`, the request will be aborted. Set to `0` for no timeout.
55
+ - `transformRequest: function`: A function to transform the request data before it is sent. Receives `data` and `headers` as arguments and should return the data to be sent.
56
+ - `transformResponse: function`: A function to transform the received data. Receives `data` as an argument and should return the transformed data.
57
+ - `validateStatus: function`: A function to validate whether the response should complete successfully given a status code. Receives `status` as an argument and should `true` if the status code is valid.
58
+
59
+
60
+ #### Examples
61
+
62
+ Properties for a AxiosHttp can be set on either the connection, the request, or both. However, both a connection and request need to be defined.
63
+
64
+ ###### A basic full example requesting data from https://jsonplaceholder.typicode.com
65
+
66
+ ```yaml
67
+ lowdefy: 6.1.0
68
+ name: Lowdefy starter
69
+ connections:
70
+ - id: my_api
71
+ type: AxiosHttp
72
+ properties:
73
+ baseURL: https://jsonplaceholder.typicode.com
74
+ pages:
75
+ - id: welcome
76
+ type: PageHeaderMenu
77
+ requests:
78
+ - id: get_posts
79
+ type: AxiosHttp
80
+ connectionId: my_api
81
+ properties:
82
+ url: /posts
83
+ events:
84
+ onInit:
85
+ - id: fetch_get_posts
86
+ type: Request
87
+ params: get_posts
88
+ blocks:
89
+ - id: rest_data
90
+ type: Markdown
91
+ properties:
92
+ content:
93
+ _string.concat:
94
+ - |
95
+ ```yaml
96
+ - _custom_yaml_stringify:
97
+ - _request: get_posts
98
+ - |
99
+ ```
100
+ ```
101
+
102
+ ###### Using the connection to set baseURL and authorization, and handle specific requests as requests.
103
+ ```yaml
104
+ connections:
105
+ - id: app_api
106
+ type: AxiosHttp
107
+ properties:
108
+ baseURL: app.com/api
109
+ auth:
110
+ username: api_user
111
+ password:
112
+ _secret: API_PASSWORD
113
+ # ...
114
+ requests:
115
+ - id: get_orders
116
+ type: AxiosHttp
117
+ connectionId: app_api
118
+ properties:
119
+ url: /orders
120
+ - id: update_order
121
+ type: AxiosHttp
122
+ connectionId: app_api
123
+ payload:
124
+ order_id:
125
+ _state: order_id
126
+ data:
127
+ _state: true
128
+ properties:
129
+ url:
130
+ _nunjucks:
131
+ template: /orders/{{ order_id }}
132
+ on:
133
+ order_id:
134
+ _payload: order_id
135
+ method: post
136
+ data:
137
+ _payload: data
138
+ ```
139
+
140
+
141
+ ###### Setting properties on only the connection:
142
+ ```yaml
143
+ connections:
144
+ - id: get_count
145
+ type: AxiosHttp
146
+ properties:
147
+ url: myapp.com/api/count
148
+ headers:
149
+ X-Api-Key:
150
+ _secret: API_KEY
151
+ # ...
152
+ requests:
153
+ - id: get_count
154
+ type: AxiosHttp
155
+ connectionId: get_count
156
+ ```
157
+
158
+ ###### Setting properties on only the request, and using a generic connection:
159
+ ```yaml
160
+ connections:
161
+ - id: axios
162
+ type: AxiosHttp
163
+ # ...
164
+ requests:
165
+ - id: get_api_1
166
+ type: AxiosHttp
167
+ connectionId: axios
168
+ properties:
169
+ url: app1.com/api/things
170
+ - id: post_to_api_2
171
+ type: AxiosHttp
172
+ connectionId: axios
173
+ payload:
174
+ data:
175
+ _state: true
176
+ properties:
177
+ url: api.otherapp.org/other/thing
178
+ method: post
179
+ data:
180
+ _payload: data
181
+ ```
@@ -11,6 +11,8 @@ The Google connection connects to the [Google Gemini API](https://ai.google.dev/
11
11
  #### Properties
12
12
  - `apiKey: string`: __Required__ - Google API key. Use [`_secret`](/_secret) to reference this securely.
13
13
  - `baseURL: string`: Optional base URL for the Google API.
14
+ - `maxOutputTokens: number`: Default maximum number of tokens a model call generates, for the requests and agents on this connection that do not set their own.
15
+ - `timeout: number`: Default milliseconds a model call may take, retries included, before it is cancelled, for the requests and agents on this connection that do not set their own. See _Limits and cancellation_ below.
14
16
 
15
17
  ###### Connection example:
16
18
  ```yaml
@@ -87,11 +89,32 @@ Request types:
87
89
 
88
90
  - GenerateText
89
91
  - GenerateObject
92
+ - Decide
90
93
 
91
- All AI provider connections (`Anthropic`, `OpenAI`, `Google`, `AIGateway`) provide the same `GenerateText` and `GenerateObject` request types — the `connectionId` selects the provider. These make a single, one-shot model call and return the result. They can be used as page requests, or as steps in [API endpoint routines](/api) — useful for classify, extract, summarize, or decide steps where the surrounding logic stays in your routine.
94
+ All AI provider connections (`Anthropic`, `OpenAI`, `Google`, `AIGateway`) provide the same `GenerateText`, `GenerateObject` and `Decide` request types — the `connectionId` selects the provider. These make a single, one-shot model call and return the result. They can be used as page requests, or as steps in [API endpoint routines](/api) — useful for classify, extract, summarize, or decide steps where the surrounding logic stays in your routine. For a closed-vocabulary decision — pick one of these options, yes or no, rate on this scale — use `Decide`.
92
95
 
93
96
  For multi-step tool use, see [agents](/agents-introduction) instead.
94
97
 
98
+ ### Limits and cancellation
99
+
100
+ Two limits bound every AI request. Set them on the request, or on the connection as the default for every request and agent that uses it:
101
+
102
+ - `maxOutputTokens` caps the tokens one call generates. Without it, the provider's default applies.
103
+ - `timeout` cancels a call, retries included, that runs longer than this many milliseconds. The request fails with a `ServiceError`.
104
+
105
+ A call is also cancelled when the request that started it closes, so a provider call that nobody is waiting for stops instead of running, and billing, to its end:
106
+
107
+ - A page request, or an API endpoint called over HTTP, is cancelled when the server's request timeout (`config.requestTimeout`, default 30 seconds) answers first, which fails it with a `ServiceError`. On the Node server it is also cancelled when the client disconnects; that is logged as a warning, not an error.
108
+ - On [Vercel](/vercel), only the request timeout cancels a call: a client disconnect does not, and the call runs until it finishes, times out, or the function reaches `config.vercel.maxDuration`. Keep `config.requestTimeout` below `maxDuration`, or Vercel stops the function before the timeout can cancel anything (the build warns when it is not).
109
+ - Endpoints with `async: true`, `detached: true` calls, and scheduled runs answer at once and then run to their end: the closing request does not cancel them.
110
+ - An agent chat turn runs to its end after the client disconnects, so its `onFinish` hooks still save the conversation. Bound it with the agent's `timeout` and `maxSteps`. A `CallAgent` step is cancelled with the routine that runs it.
111
+
112
+ ### Files in messages
113
+
114
+ A file part in `messages` (`{ type: 'file', data: <link>, mediaType }`) goes to the model as a link when the provider takes that media type as a link (the main providers do for images and PDFs). Any other file, such as a CSV or text file, is downloaded by the server and sent as content, within the request's `fileDownload` limits. The server downloads only an `https:` link to a public address, checking the address on every redirect, and a failed download names the file's host, never its link, so a signed link stays out of the server log. `Decide` takes no files.
115
+
116
+ When a provider rate-limits a call (HTTP 429), the model client retries it (`maxRetries`), waiting as long as the provider's `Retry-After` asks, up to a minute. If the retries run out, the request fails with a `ServiceError`, as a 429 does on every connection, and the server log records the `Retry-After` value.
117
+
95
118
  ### GenerateText
96
119
 
97
120
  Generates text from a prompt.
@@ -102,7 +125,12 @@ Generates text from a prompt.
102
125
  - `prompt: string`: Text prompt. Use either `prompt` or `messages`, not both.
103
126
  - `messages: object[]`: Model messages (`{ role, content }`). Use either `prompt` or `messages`, not both.
104
127
  - `system: string`: System prompt.
105
- - `maxOutputTokens: number`: Maximum number of tokens to generate.
128
+ - `allowSystemInMessages: boolean`: Default: `false` - Allow `system` role messages in `messages`. A system message instructs the model as the app itself, so without this a request whose `messages` include one fails. Only set it when the messages come from the app, never from a user (for example a message list built from `_payload`). Use `system` for the system prompt.
129
+ - `maxOutputTokens: number`: Maximum number of tokens to generate. Defaults to the connection's `maxOutputTokens`.
130
+ - `timeout: number`: Milliseconds the model call may take, retries included, before it is cancelled. Defaults to the connection's `timeout`.
131
+ - `fileDownload: object`: Limits on a file in `messages` the server downloads (see [Files in messages](#files-in-messages)).
132
+ - `maxBytes: integer`: Default: `20971520` (20 MB) - Largest file the server downloads. A larger file fails the request.
133
+ - `timeout: integer`: Default: `30000` - Milliseconds a file download may take.
106
134
  - `temperature: number`: Sampling temperature (0 to 2).
107
135
  - `topP: number`: Nucleus sampling.
108
136
  - `topK: number`: Only sample from the top K options for each subsequent token.
@@ -226,3 +254,142 @@ api:
226
254
  category:
227
255
  _step: classify.object.category
228
256
  ```
257
+
258
+ ### Decide
259
+
260
+ Makes typed decisions about a piece of state: pick one of a set of options, judge a statement true or false, or place something on an ordered scale. Every answer comes back in the shape you declared, with a confidence, so a routine can branch on it — and send a low-confidence answer to a person instead.
261
+
262
+ The build knows every option, so a routine branch that compares an answer with a name that is not one of its options — `_eq: [{ _step: triage.team.choice }, bil-ling]` — fails the build rather than silently never matching. A `_step` reference to a question the step does not ask, or to a field its answer does not have, fails the build the same way.
263
+
264
+ `Decide` has two backends behind the same interface:
265
+
266
+ - `evaluation` — an evaluation model, such as TypeSafe's Jev (`typesafe-ai/jev`) on the [AI Gateway](/AIGateway). It returns a probability for every option in one pass, in under a second, and bills input tokens only. The default, and only available, on the `AIGateway` connection.
267
+ - `structured-output` — any language model, asked for the answers as structured output that follows a schema of the questions. Providers do not all enforce the schema, so Lowdefy checks each answer against its question (see `null` answers below). Available on every AI connection, and the default on `Anthropic`, `OpenAI` and `Google`. Its confidence is the model's own estimate, not a calibrated probability.
268
+
269
+ Keep the state to what the questions need: an evaluation model reads the state literally, and accuracy drops as it grows. A `Decide` is never a security boundary — text in the state can argue for its own answer.
270
+
271
+ #### Properties
272
+
273
+ - `model: string`: **Required** - Model id to decide with, e.g. `typesafe-ai/jev`. Pin a version wherever a confidence threshold is tuned — a `latest` alias changes answers on release.
274
+ - `state: string | object | array`: **Required** - What the questions are about.
275
+ - `questions: object`: **Required** - Named questions, answered together against the state. Each question id becomes a key of the response (`usage` is reserved). A question is one of:
276
+ - `{ choice: string, options: object }` - Pick exactly one option. `options` maps option names (2 to 255) to what each one means (`null` for no description), or to an object with a `description` — its other keys are ignored, so one file can describe the options for `Decide` and for an [`IntentInput`](/IntentInput) block.
277
+ - `{ yesno: string, criteria?: { yes: string, no: string } }` - Judge a statement true or false. `criteria` optionally says what counts as yes and as no.
278
+ - `{ score: string, levels: string[] }` - Place the state on 2 to 10 ordered levels, lowest first.
279
+ - `backend: enum`: `evaluation` or `structured-output`. Defaults to `evaluation` on `AIGateway` and `structured-output` elsewhere.
280
+ - `maxOutputTokens: number`: Maximum number of tokens to generate, on the `structured-output` backend (an evaluation model generates no text). Defaults to the connection's `maxOutputTokens`.
281
+ - `timeout: number`: Milliseconds the model call may take, retries included, before it is cancelled. Defaults to the connection's `timeout`.
282
+ - `maxRetries: number`: Maximum number of retries. Defaults to 2.
283
+ - `providerOptions: object`: Provider-specific options, keyed by provider (e.g. `gateway: { zeroDataRetention: true }`).
284
+
285
+ #### Response
286
+
287
+ One key per question, plus `usage`:
288
+
289
+ ```yaml
290
+ <choice question>:
291
+ choice: string # The chosen option.
292
+ confidence: number # 0 to 1.
293
+ probabilities: object # Probability per option (evaluation backend), else null.
294
+ <yesno question>:
295
+ answer: boolean # true when the statement holds.
296
+ probability: number # Probability that it holds.
297
+ confidence: number # Probability of the given answer.
298
+ <score question>:
299
+ level: string # The most likely level.
300
+ index: number # Its position, from 0.
301
+ score: number # Fractional position on the scale (evaluation backend).
302
+ confidence: number # 0 to 1.
303
+ probabilities: object # Probability per level (evaluation backend), else null.
304
+ usage: object # Token usage ({ inputTokens, outputTokens, totalTokens }).
305
+ ```
306
+
307
+ An answer outside its question's terms (an option or level the question does not have, a yes/no that is not true or false, or no answer at all) comes back with every field `null`, its confidence included. `_lt` compares `null` below any number, so a confidence gate such as `_lt: [{ _step: triage.team.confidence }, 0.7]` holds it back like a low-confidence answer, and a branch on the choice matches none of the options.
308
+
309
+ #### Examples
310
+
311
+ ###### Route a support ticket, and queue uncertain ones for a person:
312
+
313
+ ```yaml
314
+ api:
315
+ - id: triage-ticket
316
+ type: Api
317
+ routine:
318
+ - id: triage
319
+ type: Decide
320
+ connectionId: gateway
321
+ properties:
322
+ model: typesafe-ai/jev
323
+ state:
324
+ subject:
325
+ _payload: subject
326
+ body:
327
+ _payload: body
328
+ questions:
329
+ team:
330
+ choice: Which team handles this ticket
331
+ options:
332
+ billing: Invoices, charges and refunds
333
+ tech: Outages and bugs
334
+ sales: Plans and quotes
335
+ down:
336
+ yesno: The customer says the service is down
337
+ providerOptions:
338
+ gateway:
339
+ zeroDataRetention: true
340
+ - ':if':
341
+ _lt:
342
+ - _step: triage.team.confidence
343
+ - 0.7
344
+ ':then':
345
+ - id: queue_review
346
+ type: MongoDBInsertOne
347
+ connectionId: review_queue
348
+ properties:
349
+ doc:
350
+ subject:
351
+ _payload: subject
352
+ suggested_team:
353
+ _step: triage.team.choice
354
+ - ':return':
355
+ status: review
356
+ - ':if':
357
+ _eq:
358
+ - _step: triage.team.choice
359
+ - billing
360
+ ':then':
361
+ - id: open_billing_case
362
+ type: CallApi
363
+ properties:
364
+ endpointId: open-billing-case
365
+ - ':return':
366
+ team:
367
+ _step: triage.team.choice
368
+ urgent:
369
+ _step: triage.down.answer
370
+ ```
371
+
372
+ ###### The same decision with any language model:
373
+
374
+ ```yaml
375
+ requests:
376
+ - id: rate_review
377
+ type: Decide
378
+ connectionId: claude
379
+ payload:
380
+ review:
381
+ _state: review_text
382
+ properties:
383
+ model: claude-haiku-4-5
384
+ state:
385
+ _payload: review
386
+ questions:
387
+ sentiment:
388
+ score: How positive is this review
389
+ levels:
390
+ - Very negative
391
+ - Negative
392
+ - Neutral
393
+ - Positive
394
+ - Very positive
395
+ ```