@lowdefy/docs-content 6.0.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 +41 -4
  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 +185 -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 +12 -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 +144 -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 +3 -0
  71. package/content/connections/smtp.md +16 -0
  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 +26 -3
  110. package/content/controls/return.md +17 -1
  111. package/content/controls/throw.md +30 -2
  112. package/content/controls/try.md +24 -2
  113. package/content/controls/while.md +46 -0
  114. package/content/deployment/deployment-environments.md +146 -0
  115. package/content/deployment/docker.md +23 -7
  116. package/content/deployment/node-server.md +4 -0
  117. package/content/deployment/vercel.md +25 -19
  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 +196 -0
  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 +3472 -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
@@ -49,11 +49,11 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
49
49
  size: small
50
50
  addItemButton:
51
51
  title: Bookmark
52
- icon: AiOutlinePlus
52
+ icon: add
53
53
  color: primary
54
54
  variant: dashed
55
55
  removeItemIcon:
56
- name: AiOutlineDelete
56
+ name: delete
57
57
  blocks:
58
58
  - id: bookmarks.$.url
59
59
  type: TextInput
@@ -63,7 +63,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
63
63
  label:
64
64
  disabled: true
65
65
  placeholder: https://...
66
- prefixIcon: AiOutlineLink
66
+ prefixIcon: link
67
67
  - id: bookmarks.$.label
68
68
  type: TextInput
69
69
  layout:
@@ -81,7 +81,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
81
81
  title: Attendees
82
82
  addItemButton:
83
83
  title: Add Attendee
84
- icon: AiOutlineUserAdd
84
+ icon: UserPlus
85
85
  color: primary
86
86
  variant: outlined
87
87
  blocks:
@@ -169,7 +169,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
169
169
  layout:
170
170
  flex: 0 0 auto
171
171
  properties:
172
- label: Needs supervision
172
+ title: Needs supervision
173
173
  size: small
174
174
  - id: attendees.$.wheelchair
175
175
  type: Switch
@@ -180,7 +180,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
180
180
  layout:
181
181
  flex: 0 0 auto
182
182
  properties:
183
- label: Wheelchair access
183
+ title: Wheelchair access
184
184
  size: small
185
185
  - id: attendees.$.dietary
186
186
  type: TextInput
@@ -205,7 +205,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
205
205
  flex: 0 0 auto
206
206
  properties:
207
207
  title: Register All
208
- icon: AiOutlineSend
208
+ icon: send
209
209
  color: primary
210
210
  variant: solid
211
211
  events:
@@ -228,7 +228,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
228
228
  title: Expenses
229
229
  addItemButton:
230
230
  title: Add Expense
231
- icon: AiOutlinePlus
231
+ icon: add
232
232
  color: primary
233
233
  variant: dashed
234
234
  theme:
@@ -304,7 +304,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
304
304
  flex: 0 0 auto
305
305
  properties:
306
306
  title: Submit Report
307
- icon: AiOutlineSend
307
+ icon: send
308
308
  color: primary
309
309
  variant: solid
310
310
  events:
@@ -327,7 +327,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
327
327
  title: Projects
328
328
  addItemButton:
329
329
  title: Add Project
330
- icon: AiOutlinePlus
330
+ icon: add
331
331
  color: primary
332
332
  variant: outlined
333
333
  blocks:
@@ -360,7 +360,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
360
360
  size: small
361
361
  addItemButton:
362
362
  title: Add Task
363
- icon: AiOutlinePlus
363
+ icon: add
364
364
  size: small
365
365
  variant: dashed
366
366
  blocks:
@@ -379,7 +379,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
379
379
  layout:
380
380
  flex: 0 0 auto
381
381
  properties:
382
- label: Done
382
+ title: Done
383
383
  size: small
384
384
  - id: projects_footer
385
385
  type: Box
@@ -392,7 +392,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
392
392
  flex: 0 0 auto
393
393
  properties:
394
394
  title: Save All
395
- icon: AiOutlineSave
395
+ icon: save
396
396
  color: primary
397
397
  variant: solid
398
398
  events:
@@ -416,7 +416,7 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
416
416
  size: small
417
417
  addItemButton:
418
418
  title: Add Tag
419
- icon: AiOutlinePlus
419
+ icon: add
420
420
  size: small
421
421
  variant: dashed
422
422
  events:
@@ -462,7 +462,16 @@ Dynamic list with built-in add and remove controls. Supports custom add/remove b
462
462
  | `hideAddButton` | boolean | `false` | When true, hide the add new item button. |
463
463
  | `size` | string | `"default"` | Size of the list. Enum: `small`, `default`, `large`. |
464
464
  | `addItemButton` | object | - | Custom add item button properties. |
465
- | `removeItemIcon` | string \| object | - | Custom remove item icon properties. Defaults to `AiOutlineMinusCircle` at a standard size with the antd error color inherited from the icon wrapper — override via `class.removeIcon` / `style.removeIcon` for visual tweaks, or via this property to change the icon name itself. |
465
+ | `removeItemIcon` | string \| object | - | Custom remove item icon properties. Defaults to `remove` at a standard size with the antd error color inherited from the icon wrapper — override via `class.removeIcon` / `style.removeIcon` for visual tweaks, or via this property to change the icon name itself. |
466
+ | `removeItemIcon.name` | string | - | Icon name: a semantic name like `edit`, a Lucide icon name like `Pencil`, or a set-qualified name like `tabler:Pencil`. |
467
+ | `removeItemIcon.color` | string | - | Icon color. |
468
+ | `removeItemIcon.size` | string \| number | - | Size of the icon. Defaults to `theme.icons.size`. |
469
+ | `removeItemIcon.rotate` | number | - | Number of degrees to rotate the icon. |
470
+ | `removeItemIcon.spin` | boolean | - | Continuously spin the icon with animation. |
471
+ | `removeItemIcon.strokeWidth` | number | - | Stroke width of the icon lines, in pixels of the 24px icon grid. Defaults to `theme.icons.strokeWidth` (2). |
472
+ | `removeItemIcon.nonScalingStroke` | boolean | - | Keep the stroke width constant at any icon size. Defaults to `theme.icons.nonScalingStroke`. |
473
+ | `removeItemIcon.title` | string | - | Icon hover title for accessibility. An empty string marks the icon as decorative. |
474
+ | `removeItemIcon.disableLoadingIcon` | boolean | - | While loading after the icon has been clicked, don't render the loading icon. |
466
475
  | `hideRemoveButton` | boolean | `false` | When true, hide the remove item button on each list item. |
467
476
  | `noDataTitle` | string | - | Title to show when list is empty. |
468
477
  | `minItems` | number | `0` | Minimum number of items in the controlled list. |
@@ -24,7 +24,7 @@ Notes
24
24
  flex: 0 0 auto
25
25
  properties:
26
26
  title: Add Note
27
- icon: AiOutlinePlus
27
+ icon: add
28
28
  color: primary
29
29
  variant: solid
30
30
  size: small
@@ -53,7 +53,7 @@ Notes
53
53
  layout:
54
54
  flex: 0 0 auto
55
55
  properties:
56
- icon: AiOutlineClose
56
+ icon: close
57
57
  color: default
58
58
  variant: text
59
59
  shape: circle
@@ -119,7 +119,7 @@ Tasks
119
119
  flex: 0 0 auto
120
120
  properties:
121
121
  title: Add Task
122
- icon: AiOutlinePlus
122
+ icon: add
123
123
  color: primary
124
124
  variant: solid
125
125
  size: small
@@ -193,7 +193,7 @@ Tasks
193
193
  layout:
194
194
  flex: 0 0 auto
195
195
  properties:
196
- icon: AiOutlineArrowUp
196
+ icon: arrow-up
197
197
  color: default
198
198
  variant: text
199
199
  size: small
@@ -212,7 +212,7 @@ Tasks
212
212
  layout:
213
213
  flex: 0 0 auto
214
214
  properties:
215
- icon: AiOutlineArrowDown
215
+ icon: arrow-down
216
216
  color: default
217
217
  variant: text
218
218
  size: small
@@ -231,7 +231,7 @@ Tasks
231
231
  layout:
232
232
  flex: 0 0 auto
233
233
  properties:
234
- icon: AiOutlineDelete
234
+ icon: delete
235
235
  color: danger
236
236
  variant: text
237
237
  size: small
@@ -256,7 +256,7 @@ Tasks
256
256
  flex: 0 0 auto
257
257
  properties:
258
258
  title: Save Tasks
259
- icon: AiOutlineSave
259
+ icon: save
260
260
  color: primary
261
261
  variant: solid
262
262
  events:
@@ -300,7 +300,7 @@ User Directory
300
300
  flex: 0 0 auto
301
301
  properties:
302
302
  title: Load Users
303
- icon: AiOutlineCloudDownload
303
+ icon: CloudDownload
304
304
  color: primary
305
305
  variant: solid
306
306
  size: small
@@ -394,7 +394,7 @@ Invoice #1042
394
394
  flex: 0 0 auto
395
395
  properties:
396
396
  title: Add Line
397
- icon: AiOutlinePlus
397
+ icon: add
398
398
  color: primary
399
399
  variant: dashed
400
400
  size: small
@@ -453,7 +453,7 @@ Invoice #1042
453
453
  layout:
454
454
  flex: 0 0 auto
455
455
  properties:
456
- icon: AiOutlineMinusCircle
456
+ icon: remove
457
457
  color: danger
458
458
  variant: text
459
459
  size: small
@@ -493,7 +493,7 @@ Invoice #1042
493
493
  flex: 0 0 auto
494
494
  properties:
495
495
  title: Submit Invoice
496
- icon: AiOutlineSend
496
+ icon: send
497
497
  color: primary
498
498
  variant: solid
499
499
  events:
@@ -1,6 +1,6 @@
1
1
  # MasonryList
2
2
 
3
- Masonry-style grid layout for list data. Items flow into columns and stack vertically, filling gaps left by shorter items. Provide an array in state and use _state operators in the template to access each item's data.
3
+ Masonry-style grid layout for list data. Items flow into columns and stack vertically, filling gaps left by shorter items. Provide an array in state and use _state operators in the template to access each item's data.
4
4
 
5
5
  ```yaml
6
6
  - id: ml_basic
@@ -162,7 +162,7 @@ Masonry-style grid layout for list data. Items flow into columns and stack verti
162
162
  properties:
163
163
  content:
164
164
  _state: ml_team.$.initials
165
- backgroundColor:
165
+ color:
166
166
  _state: ml_team.$.bg
167
167
  - id: ml_team.$.name_block
168
168
  type: Title
@@ -179,40 +179,12 @@ Masonry-style grid layout for list data. Items flow into columns and stack verti
179
179
  _state: ml_team.$.role
180
180
  ```
181
181
 
182
- ```yaml
183
- - id: ml_seq
184
- type: MasonryList
185
- properties:
186
- columns: 3
187
- gutter: 16
188
- sequential: true
189
- blocks:
190
- - id: ml_seq.$.card
191
- type: Card
192
- class:
193
- _state: ml_seq.$.bg
194
- properties:
195
- size: small
196
- blocks:
197
- - id: ml_seq.$.title_block
198
- type: Title
199
- properties:
200
- content:
201
- _state: ml_seq.$.title
202
- level: 5
203
- - id: ml_seq.$.desc_block
204
- type: Paragraph
205
- properties:
206
- content:
207
- _state: ml_seq.$.desc
208
- ```
209
-
210
182
  | Property | Type | Default | Description |
211
183
  | --- | --- | --- | --- |
212
- | `columns` | integer \| object | - | Number of columns, or responsive breakpoint object (e.g. { xs: 1, sm: 2, md: 3 }). |
213
- | `fresh` | boolean | `false` | Force refresh the masonry layout. |
214
- | `gutter` | number \| array | - | Gap between items in pixels. Number or [horizontal, vertical] array. |
215
- | `sequential` | boolean | `false` | Render items sequentially (top to bottom, then next column). Default is balanced column-fill. |
184
+ | `columns` | integer \| object | `3` | Number of columns, or responsive breakpoint object (e.g. { xs: 1, sm: 2, md: 3 }). |
185
+ | `fresh` | boolean | `false` | Keep watching the size of each item and re-layout when it changes, for items whose height changes after they render (images loading, expanding content). |
186
+ | `gutter` | number \| array \| object | `0` | Gap between items in pixels. A number, a responsive breakpoint object (e.g. { xs: 8, md: 16 }), or a [horizontal, vertical] array of either. |
187
+ | `sequential` | boolean | `false` | Has no effect: antd Masonry always places each item in the shortest column. Kept so existing configs stay valid. |
216
188
  | `theme` | object | - | Antd design token overrides for this block. Masonry uses global motion tokens for item animations. See [antd design tokens](https://ant.design/components/overview#design-token). See [Ant Design masonry tokens](https://ant.design/components/masonry). |
217
189
  | `theme.motionDurationSlow` | string | `"0.3s"` | Duration of item position and fade-in animations. |
218
190
  | `theme.motionDurationFast` | string | `"0.1s"` | Duration of item fade-out animations. |
@@ -224,6 +196,7 @@ No events defined.
224
196
  | --- | --- |
225
197
  | `/block` | Outer block wrapper (always available). |
226
198
  | `/element` | The MasonryList element. |
199
+ | `/item` | Each item in the masonry grid. |
227
200
 
228
201
  | Slot | Description |
229
202
  | --- | --- |
@@ -0,0 +1,337 @@
1
+ # Auth Upgrade (BetterAuth)
2
+
3
+ This guide covers upgrading an app from the previous NextAuth-shaped `auth:` configuration to the BetterAuth-based auth system. The `auth:` block is restructured, sessions are database-backed, the session user shape changes, and roles move onto organization memberships. Every app with auth is affected.
4
+
5
+ API auth strategies (`auth.strategies`) are purely additive — an app with no strategies configured behaves exactly as before.
6
+
7
+ ## Summary of breaking changes
8
+
9
+ | Change | Old | New |
10
+ |---|---|---|
11
+ | Database required | Optional (JWT-only possible) | `auth.database` required for any login method |
12
+ | Provider type names | `GoogleProvider`, `GitHubProvider`, ... | `Google`, `GitHub`, ... (`OpenIDConnectProvider` → `GenericOAuth`) |
13
+ | Callbacks / events | `auth.callbacks`, `auth.events` (JS plugins) | `auth.hooks` — bindings to `InternalApi` endpoints |
14
+ | Session strategy | `session.strategy: jwt` supported | Database sessions only; `maxAge` → `expiresIn` |
15
+ | Collection names | `users`, `accounts`, `sessions` | `user-*` convention, fixed by the adapter |
16
+ | `userFields` | Mapped provider claims onto the session | Removed — each mapped key has a new home (see below) |
17
+ | Secret | `NEXTAUTH_SECRET` env var | `auth.secret` with the `_secret` operator |
18
+ | Auth UI | NextAuth built-in pages, `auth.theme` | Removed — the app provides its own pages |
19
+ | Magic link | `EmailProvider` in `providers` | `auth.magicLink` + `auth.email` |
20
+ | `authPages` | `signIn`, `signOut`, `error`, `verifyRequest`, `newUser` | `signIn`, `signUp`, `error`, `forgotPassword`, `resetPassword`, `verifyEmail` |
21
+ | OIDC profile claims | ~20 claims copied onto the session user | Only `id`, `name`, `email`, `image`, `email_verified` |
22
+ | `sub` | `_user.sub` = provider's OIDC subject | Removed — `_user.id` is the internal id (a different value) |
23
+ | Roles | On the user record via `userFields` | App roles on `member.appRoles` (`_user.roles`); the organization's `owner`/`admin`/`member` tier on `member.role` (`_user.org_roles`) |
24
+ | Attributes | `_user.app_attributes`, `_user.global_attributes` | One merged `_user.attributes` bag |
25
+ | Signed-out request to any URL | `/404` if the page is missing, sign-in if protected | Sign-in for every URL, in apps whose unlisted ids default to protected |
26
+ | Missing request / endpoint id, signed out (auth'd app) | `500` (missing) vs `401` (protected) | `401` for both |
27
+ | 404 page | Had to serve signed-out visitors refused a protected page | Only ever serves signed-in visitors, in a protected app |
28
+
29
+ ## Upgrade steps
30
+
31
+ ### 1. Restructure the `auth:` block
32
+
33
+ Rename provider types (drop the `Provider` suffix; `OpenIDConnectProvider` becomes `GenericOAuth` with `discoveryUrl` and a `scopes` array). Convert the session block — `strategy` is gone, `maxAge` becomes `expiresIn`:
34
+
35
+ ```yaml
36
+ auth:
37
+ session:
38
+ expiresIn: 604800 # was maxAge
39
+ updateAge: 86400
40
+ ```
41
+
42
+ Remove `theme`, `debug`, `advanced`, and `userFields` — they have no successor keys. `theme` styled NextAuth's built-in pages, which no longer exist. Every `userFields` mapping has a new home — see [the session user shape](#the-session-user-shape) below.
43
+
44
+ ### 2. Add `auth.secret`
45
+
46
+ The `NEXTAUTH_SECRET` / `AUTH_SECRET` environment variables are no longer read. Configure the secret explicitly:
47
+
48
+ ```yaml
49
+ auth:
50
+ secret:
51
+ _secret: BETTER_AUTH_SECRET
52
+ ```
53
+
54
+ Set `LOWDEFY_SECRET_BETTER_AUTH_SECRET` to a secure random string (`openssl rand -base64 32`). Reusing your old secret value is fine — sessions are invalidated by the upgrade anyway.
55
+
56
+ ### 3. Pin the canonical URL with `BETTER_AUTH_URL`
57
+
58
+ Set the `BETTER_AUTH_URL` environment variable to your app's canonical origin (e.g. `https://app.example.com`), or declare it once as the current environment's `url` in [`config.environments`](/lowdefy-schema). Auth builds password-reset, magic-link and email-verification links — and the origins it trusts for the CSRF check and for `callbackURL` / `redirectTo` targets — from this value. When it is pinned, those links and origins are fixed. When it is unset, both come from each incoming request, so the host in an emailed link would come from the request too. A production server therefore refuses to start when it is unset and auth sends emails with links: any app with `auth.email` configured, since it sends verification, password-reset, magic-link and invitation emails. The error names the flows. Without `auth.email` the server starts and logs a warning, and auth trusts only the origin each request arrived on. The dev server (`lowdefy dev`) still uses the request origin. Pinning it is also needed behind a proxy that terminates TLS and forwards plain `http` (see [Deploy with Docker](/docker)). This replaces the old `NEXTAUTH_URL` variable.
59
+
60
+ ### 3b. Declare trusted proxies
61
+
62
+ Auth rate limits (for example 3 sign-in attempts per 10 seconds) count attempts per client address, and sessions record it. A self-hosted server takes the client address from the connection and does not read `X-Forwarded-For`, which any client can set. Behind a reverse proxy or load balancer, every request then comes from the proxy, so list its addresses in [`config.trustedProxies`](/lowdefy-schema) and the server reads the client address the proxy forwarded:
63
+
64
+ ```yaml
65
+ config:
66
+ trustedProxies:
67
+ - 10.0.0.0/8
68
+ ```
69
+
70
+ On Vercel nothing is needed: the platform supplies the client address. See [Deploy with Docker](/docker#behind-a-reverse-proxy).
71
+
72
+ ### 4. Add `auth.database`
73
+
74
+ Sessions are database-backed, so every app with a login method needs an adapter — including apps that previously ran JWT-only with no adapter:
75
+
76
+ ```yaml
77
+ auth:
78
+ database:
79
+ id: auth_db
80
+ type: MongoDBAuthAdapter
81
+ properties:
82
+ uri:
83
+ _secret: AUTH_DATABASE_URI
84
+ ```
85
+
86
+ If you used the old `MongoDBAdapter`: the type is renamed, `databaseUri` becomes `uri`, and `options.databaseName` folds into the URI path. There is no `options.collections` mapping — collection names are fixed by the adapter.
87
+
88
+ ### 5. Migrate MongoDB collections
89
+
90
+ The adapter uses the `user-*` naming convention, and the names are fixed — there is no rename escape hatch:
91
+
92
+ - `users` keeps its name.
93
+ - Rename `accounts` to `user-accounts`.
94
+ - Drop `sessions` and `verification_tokens` — the session format changes and users sign in again.
95
+
96
+ If you configured custom collection names via the old `options.collections`, rename those collections to the fixed names instead.
97
+
98
+ ### 6. Migrate `EmailProvider` to `magicLink`
99
+
100
+ Magic-link login is a plugin with its own key, not a provider entry. `auth.email` no longer carries an inline SMTP transport — it references an `SMTP` connection by id. That one connection owns `from`, `replyTo`, the transport, and the delivery `filter`, and is shared by every email flow (magic links, verification, password reset, invitations):
101
+
102
+ ```yaml
103
+ connections:
104
+ - id: email
105
+ type: SMTP
106
+ properties:
107
+ from: noreply@example.com
108
+ host:
109
+ _secret: SMTP_HOST
110
+ port: 587
111
+ auth:
112
+ user:
113
+ _secret: SMTP_USER
114
+ pass:
115
+ _secret: SMTP_PASS
116
+ auth:
117
+ magicLink:
118
+ enabled: true
119
+ expiresIn: 300
120
+ email:
121
+ connectionId: email # an SMTP connection in connections[]
122
+ ```
123
+
124
+ The client signs in with the `Login` action: `params: { magicLink: true, email: ... }`.
125
+
126
+ **Auth emails obey the connection's delivery filter.** Because auth email now sends through the same `SMTP` connection your app uses for notification and routine mail, that connection's `filter` (dev catch-all, sandbox allowlist/regex, none in production) governs auth email too. This closes the old footgun where auth emails bypassed the filter and shipped to real inboxes while everything else was caught in development.
127
+
128
+ **Branded HTML by default.** The four auth emails — verification, password reset, magic link, and invitation — render branded HTML from your `app.email` theme (logo, colour, layout), not the old plain-text link. There is no per-flow theme knob; one `app.email` brand covers them all.
129
+
130
+ **Overriding a flow.** Point any flow at one of your own `notifications:` entries to replace its email with a bespoke notification template (its own copy, subject, and per-notification `theme` merged over `app.email`):
131
+
132
+ ```yaml
133
+ auth:
134
+ email:
135
+ connectionId: email
136
+ templates: # all optional; unset → branded stock template
137
+ verifyEmail: verify-email-notification
138
+ resetPassword: reset-password-notification
139
+ magicLink: magic-link-notification
140
+ invitation: invite-notification
141
+ ```
142
+
143
+ Each value is a notification id from `notifications:`. These `templates` keys are an email-flow namespace, separate from the `authPages` roles despite the shared `resetPassword` / `verifyEmail` spelling. An override template **must surface the framework `url` behind its call-to-action** — the engine injects `url` (and, for invitations, the accept-page link). A verify email with no verify link is a dead end, so a template that ignores `url` is a mistake.
144
+
145
+ **`invitation.send` is removed.** The invitation email is now symmetric with the other three: branded stock `InvitationEmail` by default, an override notification when configured. The old `invitation.send` auth hook — whose only purpose was branding the invite before overrides existed — is gone. If you bound it, point `auth.email.templates.invitation` at a notification instead.
146
+
147
+ ### 7. Rewrite callbacks and events as hooks
148
+
149
+ `auth.callbacks` and `auth.events` are replaced by `auth.hooks`. A hook is not a plugin — it binds an auth lifecycle point to an `InternalApi` endpoint, and the endpoint's routine does the work, reading the hook payload with the `_payload` operator:
150
+
151
+ ```yaml
152
+ auth:
153
+ hooks:
154
+ - id: audit-login
155
+ point: session.create.after
156
+ endpointId: audit-login
157
+ ```
158
+
159
+ Where old slots land:
160
+
161
+ | Old | New point |
162
+ |---|---|
163
+ | `createUser` event | `user.create.after` |
164
+ | `signIn` event | `session.create.after` |
165
+ | `signOut` event | `session.delete.after` |
166
+ | `linkAccount` event | `account.create.after` |
167
+ | `updateUser` event | `user.update.after` |
168
+ | `signIn` callback (allow / deny) | `session.create.before` — `:reject` vetoes the sign-in |
169
+ | `jwt` callback | None — database sessions carry no JWT; persist data via a create hook instead |
170
+ | `redirect` callback | None — post-login navigation is the `Login` action's `callbackUrl` |
171
+ | `session` callback | None — the session shape is fixed; store extra data in attributes or app collections |
172
+
173
+ Custom callback/event plugin logic moves into the endpoint's routine; anything a routine can't express goes in a custom request plugin called from the routine.
174
+
175
+ ### 8. Build your auth pages
176
+
177
+ BetterAuth ships no UI. The app owns its sign-in, sign-up, and error pages, and `auth.authPages` points at them:
178
+
179
+ ```yaml
180
+ auth:
181
+ authPages:
182
+ signIn: /login
183
+ signUp: /signup
184
+ error: /auth-error
185
+ ```
186
+
187
+ The old `signOut`, `verifyRequest`, and `newUser` keys are removed. New optional keys for email flows: `signUp`, `forgotPassword`, `resetPassword`, `verifyEmail`. `twoFactor` is a further key, and unlike those it is **required** when `auth.twoFactor.enabled` is true — the build fails without it, because the engine routes the two-factor challenge to that page itself. See [Two-Factor Authentication](/two-factor).
188
+
189
+ `acceptInvitation` is a further key, naming the page that consumes an `?invitationId=` link. **Write its copy for the unauthenticated case.** Where one app sends another organization's invitations, the invitee accepts on the *sending* app, and `AcceptInvitation` sets the active organization inside its own transaction — so the accept page itself renders unauthenticated the moment the accept succeeds. That page must tell an already-signed-in invitee to sign in again **at the app they are on**, not at the app that sent the invitation: the active-organization policy runs at every session create and re-pins them here, while the production cookie prefix is shared across apps on one host, so signing in at the other app flips the shared session back the other way.
190
+
191
+ Sign-in uses the `Login` action, which dispatches by parameter — `providerId` for OAuth, `magicLink: true`, or `email` + `password`. Email/password sign-up pages use the new `SignUp` action; social and magic-link "sign-up" pages use `Login`, since those methods create the account on first sign-in. Sign-in errors now surface inline (the `Login` action returns `error.code`) rather than as a `?error=` query parameter on the error page.
192
+
193
+ ### 9. Migrate user records to the new model
194
+
195
+ Roles move off the user record onto organization memberships, and the fused user-contact record splits into an app-owned `contact` and auth-owned `user` and `member` records. Neither the core upgrade nor any module ships a data migration for this: each app writes its own, once, against its auth database. Apps that never stored roles or app data on the user record only need the collection renames from step 5.
196
+
197
+ For apps built on the [`modules-mongodb`](https://github.com/lowdefy/modules-mongodb) `user_contacts` convention — one combined record per person, with `is_user`, an `apps.{app_name}` map and `global_attributes` — the mapping is:
198
+
199
+ - **One `users` row per contact with `is_user: true` in any app.** Keep the contact's `_id` as the user's `_id`, so `_user.id` and every record that stores it stay valid. The adapter stores ids as strings, so a contact keyed by an `ObjectId` needs its hex string here. Fill the user fields `name`, `email`, `email_verified`, `image`, `created_at` and `updated_at` from the contact.
200
+ - **`global_attributes` becomes `users.attributes`.**
201
+ - **One `user-members` row per enabled `apps.{app_name}` entry**, with `user_id` set to the user's `_id`, `organization_id` set to the app's pinned slug (`auth.organizations.org` — under `pinned` the slug is the organization's id), `app_roles` from the entry's `roles`, `attributes` from its `app_attributes`, `role: member` and a `created_at`. A disabled entry gets no row.
202
+ - **The contact is reshaped in place**, without the `apps` map and without the `is_user`, `invite` and `disabled` flags. It stays the app's record of the person.
203
+ - **At least one member per organization holds `role: owner`**, so someone can send invitations. Without one, the organization is the closed loop described under [Bootstrapping the first administrator](#bootstrapping-the-first-administrator).
204
+
205
+ Write these rows with the stored field names, which are snake_case (`user_id`, `organization_id`, `app_roles`, `created_at`): the adapter maps BetterAuth's camelCase names, such as `appRoles` in the auth steps, to snake_case on the way in. The module side of the upgrade — vars, role catalog and column paths — is covered by the `user-admin` module's migration how-to (`docs/user-admin/how-to/migration.md` in `modules-mongodb`).
206
+
207
+ ### 10. Sign in again
208
+
209
+ Existing sessions are invalidated — the session format changed. There is nothing to migrate; users log in once after the upgrade.
210
+
211
+ ## The session user shape
212
+
213
+ The session user carries `id`, `name`, `email`, `image`, `email_verified`, `active_organization_id`, and the user record's own `profile` bag, plus three fields Lowdefy resolves from the caller's row in the active organization:
214
+
215
+ - **`roles`** — the app's own role names, read from the active membership's `appRoles` array. These are what page and endpoint `auth.roles` gates match, and the only thing they match.
216
+ - **`org_roles`** — the organization tier, from `member.role`: `owner`, `admin` or `member`. This is an administrative fact about the active organization, and it is **not a gate source** — `createAuthorize` reads only `roles`. An app that wants a page for organization administrators gates that page on one of its own app roles, and lets the write authority answer the administration question separately, at the step.
217
+ - **`attributes`** — the one merged bag of authorization inputs: `user.attributes` (global) under the active `member.attributes` (per-organization), merged per key, member wins.
218
+
219
+ **`_user.role` (singular) carries nothing.** It rides the session-user spread off the user record, and Lowdefy never writes it. It sits one character away from `roles`, so an app that gates on `_user.role` is gating on a constant — the gate either always passes or always fails, and never for the reason the author intended. Read `roles`.
220
+
221
+ There is no `impersonatedBy` field on the session user. Impersonation is not part of the platform.
222
+
223
+ Where old `_user` reads land:
224
+
225
+ | Old read | New home |
226
+ |---|---|
227
+ | `_user.sub` | `_user.id` — a **different value**: the internal id, not the provider subject. The provider subject lives on the `user-accounts` collection (`accountId`). |
228
+ | `_user.picture` | `_user.image` |
229
+ | `_user.email_verified` | `_user.email_verified` — unchanged; the pre-upgrade OIDC claim and the resolved caller field already share this name. |
230
+ | `_user.roles` | Unchanged read — but roles now resolve from the active organization membership's `appRoles`, granted via invitations and auth steps, not provider claims. |
231
+ | `_user.orgRoles` | `_user.org_roles` — the organization tier from `member.role` (`owner`, `admin`, `member`). |
232
+ | `_user.twoFactorEnrolled` | `_user.two_factor_enrolled` — whether the caller holds a factor satisfying `auth.twoFactor.required`. |
233
+ | `_user.authMethod` | `_user.auth_method` — the strategy that authenticated the caller, on strategy-resolved callers only. |
234
+ | `_user.app_attributes.*` | `_user.attributes.*` — per-app values live on the membership (`member.attributes`). |
235
+ | `_user.global_attributes.*` | `_user.attributes.*` — global values live on the user (`user.attributes`); merged per key, member wins. |
236
+ | Other OIDC claims (`given_name`, `phone_number`, `address`, ...) | Not in the session. Persist what you need at signup via an endpoint hook — profile data onto your contact collection, authorization inputs into attributes — and read it from there. |
237
+
238
+ ## Page and API existence is no longer observable before you sign in
239
+
240
+ This is a behaviour change every app inherits, not a two-factor feature. It removes an enumeration asymmetry — a logged-out caller used to be able to tell a real-but-protected id apart from an absent one by the response they got back. That is an information leak the engine design had accepted as a documented cost of following web convention, not an access-control failure: no protected page or request was ever reachable without a session. Nothing about who can *reach* a surface changes here — only what a signed-out caller can *learn* about which surfaces exist.
241
+
242
+ **The rule.** When the caller is not authenticated, existence is never consulted. A protected app answers the sign-in page for any URL a logged-out visitor asks for — whether that URL is a real protected page or a typo that matches nothing. Existence is only resolved once there is a session to resolve it against.
243
+
244
+ **Which apps change, which don't.** Only apps whose *unlisted* page ids default to protected are affected. The `auth.pages.protected: [...]` shape (an explicit protected list, everything else public) is **untouched** — a logged-out visitor typing a wrong URL still gets `/404`, because unlisted ids there are public. Every other shape treats an unlisted id as protected, so a logged-out typo now lands on the sign-in page, then resolves to `/404` once the visitor authenticates — one extra hop for a wrong URL.
245
+
246
+ | Config | An unlisted page id is |
247
+ |---|---|
248
+ | `auth.pages.public: [...]` | protected |
249
+ | `auth.pages.protected: true` | protected |
250
+ | `auth.pages.protected: [...]` | public |
251
+ | neither | public |
252
+
253
+ **A known imprecision, so nobody files it as a bug.** The default the runtime reads for an unlisted id is a single build-resolved boolean, deliberately coarser than the glob-list config that produced it. In an app configured `auth.pages.public: ['docs/**']` (so unlisted ids default to protected), a signed-out visitor typing `docs/typo` gets the sign-in page rather than `/404`, even though the `docs/**` namespace was declared public. Every id that **is** in the build carries its own resolved decision, so no real page changes behaviour — only a URL matching nothing reads the coarse default. Shipping the pattern lists into the build artifact and re-matching globs per request was considered and rejected: the artifact exists precisely so the runtime reads a resolved decision and never re-derives access from patterns.
254
+
255
+ **What you can delete.** In a protected app the 404 page now answers one question — "does a page with this id exist for this signed-in caller?" — instead of three. The auth logic some apps hand-write onto their 404 page (a session check, a conditional "sign in" link for the logged-out case) is now dead code: a logged-out visitor never reaches the 404 page, so it only ever renders for someone already signed in. Delete it. The build still forces the `404` page id public, unchanged, so the page itself is always reachable.
256
+
257
+ **The API surface.** In an authenticated app a logged-out caller gets `401 Authentication required` for **every** request and endpoint id, present or absent. Two consequences for upgrading apps. A missing id used to surface as a `500`, so any error handling keyed on the status code will now see `401` where it previously saw `500`. And a typo'd `requestId` called from a logged-out browser now reads "Authentication required" rather than a not-found error — expected, given existence is no longer disclosed pre-auth. The **authenticated** case is unchanged: for a signed-in caller a missing id and a role-refused id both still surface as the same opaque "does not exist". A no-auth app is unchanged, and so is a system or routine context — the `401` rewrite is for a real session-less human on a protected surface, not for "no user" in general.
258
+
259
+ **Websockets are unchanged.** The websocket surface was already symmetric — a logged-out caller could never distinguish a present subscription id from an absent one — so it needed no change and got none. It is called out here only so a reader does not conclude the surface was overlooked.
260
+
261
+ ## Administering organizations
262
+
263
+ Administering an organization means holding `admin` (or `owner`) in that organization — the `member.role` tier, on the caller's own member row there. There is no app-wide administering role, and no config key that grants administration across organizations: nothing to configure. Every auth step declares the authority it requires, and the step floor authorizes the caller against their member row in the organization the step names, so a caller who administers the team organization holds nothing in the customer organization. The steps that write the deployment-wide `user` row — `UpdateUserProfile`, `UpdateUserAttributes`, `BanUser`, `UnbanUser`, `DeleteUser`, `RevokeUserSessions` — additionally require the **target** to hold a member row in that organization, so an administrator can only reach people who are members of an organization they administer.
264
+
265
+ ## Bootstrapping the first administrator
266
+
267
+ Nothing grants organization authority implicitly. On a fresh `policy: pinned` + `signup: invite-only` deployment that is a closed loop: nobody can be invited, because inviting needs `invitation: ['create']` authority that nobody holds, and nobody can sign up, because the admission gate admits only members and pending invitees. Breaking the loop is one document inserted into the `user-invitations` collection, by hand, outside the platform:
268
+
269
+ ```js
270
+ { _id: <uuid>, organization_id: 'team', email: 'admin@example.com',
271
+ role: 'owner', app_roles: [], status: 'pending',
272
+ inviter_id: 'bootstrap', expires_at: <future date>, created_at: new Date() }
273
+ ```
274
+
275
+ **The field names are snake_case.** The adapter stores BetterAuth's camelCase fields (`organizationId`, `appRoles`, `inviterId`, `expiresAt`, `createdAt`) under snake_case names, as for the user and member rows above. A document written with the camelCase names matches no pending invitation for the organization, so the admission gate refuses the sign-up and the bootstrap never starts.
276
+
277
+ **`organization_id` is the configured slug.** Under `pinned` the organization's id *is* `auth.organizations.org`, so there is no id to look up and the same document works in every environment.
278
+
279
+ **The key is `_id`, not `id`.** The adapter maps the logical `id` to the physical `_id` inbound and back outbound, so every invitation the platform writes stores its id at `_id`. A document inserted literally as `{ id: … }` gets a driver-generated `ObjectId` `_id` plus a stray `id` field, after which the accept flow's invitation lookup never finds it — while the admission gate, which looks the invitation up by email, organization and status rather than by id, happily admits the person to sign up. The result is a user who can log in, an invitation that cannot be accepted, and no error pointing at either. Use `_id`.
280
+
281
+ **The role is `owner`, not `admin`, and that is not cosmetic.** With no owner in the organization every membership guard is inert: `removeMember`'s creator protection engages only when the target holds the creator role, and `updateMemberRole`'s last-owner count only when the updater is the creator editing themselves. So a sole `admin` could demote themselves to `member`, or remove the last other `admin`, after which nobody anywhere holds `member: ['update']` or `invitation: ['create']` — and under `signup: invite-only` nobody can sign up to fix it. Seeding `owner` makes all three guards live, and costs nothing reachable: `owner`'s only statement beyond `admin`'s is `organization: ['delete']`, whose endpoint is disabled under `pinned` and has no step.
282
+
283
+ **Deliver the accept URL by hand.** The accept URL is built only inside the invitation email sender, which only the `InviteMember` step reaches, so a hand-inserted invitation sends no email. Give the nominated person this link:
284
+
285
+ ```
286
+ {baseUrlOrigin}{basePath}{authPages.acceptInvitation}?invitationId=<the _id above>
287
+ ```
288
+
289
+ **The pre-accept state looks like a failure and is not.** Under `invite-only`, an invitee holding only a pending invitation gets a session with **no** active organization, and a session with no active organization resolves unauthenticated. So the nominated person signs up successfully and lands logged out everywhere. That is the carve-out working: it admits them just far enough to accept. The link is the only way forward — the front door alone does not finish the bootstrap.
290
+
291
+ **Email verification is required before accepting.** Lowdefy sets a function-form `advanced.database.generateId`, which makes the organization plugin require a verified email for the accept-by-invitation-id action. Normal flow, not a workaround: verify the address, then open the link.
292
+
293
+ **Under `signup: open` this route does not grant the role.** The auto-join hooks mint a `role: 'member'` member row before the accept, and accepting an invitation into an organization you already belong to only marks the invitation accepted — it never changes an existing membership. There the single write is the other one: the person signs up normally, and the operator sets `member.role: 'owner'` on the row they already have. That one field is the whole grant — no second write and no denormalized copy to leave stale, because nothing writes `user.role`.
294
+
295
+ **Bootstrap is per-organization, not per-deployment.** An `admin` of the team organization holds no authority in the customer organization, so that organization's first `admin` needs its own inserted invitation. After the first one, each organization is self-sustaining: its owner can invite and promote from inside the app.
296
+
297
+ ## Retired client actions
298
+
299
+ Seven client actions are gone. An app that authors one fails at build with the unknown-action-type error; each has a named replacement, except the two that do not:
300
+
301
+ | Retired action | Replacement |
302
+ |---|---|
303
+ | `ImpersonateUser` | **None.** The capability is retired. |
304
+ | `StopImpersonating` | **None.** The capability is retired. |
305
+ | `InviteMember` | The `InviteMember` step |
306
+ | `CancelInvitation` | The `CancelInvitation` step |
307
+ | `UpdateMemberRole` | The `UpdateMemberOrgRole` step (the `owner`/`admin`/`member` tier). App roles are the `UpdateMemberRoles` step. |
308
+ | `RemoveMember` | The `RemoveMember` step |
309
+ | `UpdateOrganization` | The `UpdateOrganization` step |
310
+
311
+ The rule that produced the list also tells you which actions will keep existing: **a client action is an operation that mutates the caller's own session, and nothing else.** So `SetActiveOrganization`, `AcceptInvitation` and `LeaveOrganization` remain — each acts on the caller. An app administering **other** people's memberships authors a routine instead, and that is what earns it the per-step authority floor, an explicitly named target organization, and both role tiers (`appRoles` and `orgRole`) rather than one fused `role`.
312
+
313
+ Two consequences. A `pinned` app never had these actions working in the first place — every organization route is disabled under `pinned` — so this reads as a removal only for `tenant` apps. And the step path is what makes cross-organization administration possible at all: a client action forwards no organization id, so it could only ever act on the session's active organization.
314
+
315
+ ## Exposing MCP tools to assistants
316
+
317
+ New in this release: a Lowdefy app can be an **OAuth 2.1 authorization server** and expose its API endpoints as authenticated tools to MCP clients (Claude, ChatGPT, IDE assistants). There is one MCP resource at `/api/mcp`; the organization a call acts in is a token claim chosen at authorization, not a URL segment. Enable it with `auth.oauthProvider` and tag endpoints in the `mcp` block. This is entirely additive — an app with no `mcp` endpoints and no `auth.oauthProvider` is unaffected.
318
+
319
+ **One rule to internalise before you ship it: never list an MCP endpoint id in `auth.api.public`.** A single public tool suppresses the OAuth challenge for the whole route, so a newly connected assistant reports "connected" and never authenticates. The full model — the flow, the `organization_id` claim, `mcp:read` / `mcp:write` scopes, the consent and organization-picker pages, and switching or disconnecting with `RevokeMcpGrant` — is on the [MCP Server & OAuth](/mcp-oauth) page.
320
+
321
+ The `mcp.agents` config key is removed; MCP agent tools are not supported.
322
+
323
+ ## Where the details now live
324
+
325
+ This guide is the migration path; the current behaviour is documented on the dedicated pages:
326
+
327
+ - [Organizations & Multi-Tenancy](/organizations) — the `pinned` / `tenant` policies and the tenant wall.
328
+ - [Auth Steps](/auth-steps) — the per-step authority model and every step's scope and permission.
329
+ - [MCP Server & OAuth](/mcp-oauth) — the authenticated MCP surface.
330
+ - [User Object](/user-object) — the fixed `_user` shape.
331
+
332
+ ## What you don't need to change
333
+
334
+ - **Page and API authorization** — `auth.pages` and `auth.api` (`protected` / `public` / `roles`) keep their shape and semantics.
335
+ - **Page role lists** — existing role names keep working; roles are matched as strings exactly as before.
336
+ - **Provider ids** — OAuth callback URLs are still `/api/auth/callback/<id>`; keep your provider `id` values.
337
+ - **`dev.mockUser`** — still available in the dev server.