@lowdefy/docs-content 7.1.0 → 7.3.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 (53) hide show
  1. package/content/actions/login.md +1 -1
  2. package/content/actions/posthoginit.md +1 -1
  3. package/content/adapter-reference/mongodbauthadapter.md +2 -2
  4. package/content/agents/agents-introduction.md +41 -1
  5. package/content/callback-reference/auth0logoutcallback.md +1 -1
  6. package/content/concepts/ai-agent-docs.md +116 -108
  7. package/content/concepts/blocks.md +1 -1
  8. package/content/concepts/connections-and-requests.md +8 -8
  9. package/content/concepts/custom-html.md +1 -1
  10. package/content/concepts/dynamic-page-content.md +26 -15
  11. package/content/concepts/events-and-actions.md +24 -0
  12. package/content/concepts/logger.md +1 -1
  13. package/content/concepts/lowdefy-api.md +81 -14
  14. package/content/concepts/lowdefy-schema.md +11 -0
  15. package/content/concepts/mobile-apps.md +110 -0
  16. package/content/concepts/page-and-app-state.md +2 -2
  17. package/content/concepts/theming.md +1 -1
  18. package/content/connections/axioshttp.md +1 -1
  19. package/content/connections/mongodb.md +22 -6
  20. package/content/controls/reject.md +2 -2
  21. package/content/deployment/vercel.md +1 -1
  22. package/content/display-blocks/aggrid.md +1 -1
  23. package/content/display-blocks/search.md +86 -2
  24. package/content/display-blocks/table.md +154 -9
  25. package/content/input-blocks/ratingslider.md +1 -0
  26. package/content/input-blocks/tableinput.md +12 -4
  27. package/content/input-blocks/tiptapinput.md +3 -2
  28. package/content/input-blocks/tiptapmentioninput.md +3 -2
  29. package/content/migration/v3-to-v4.md +2 -2
  30. package/content/operators/_api.md +11 -9
  31. package/content/operators/_base64.md +2 -2
  32. package/content/operators/_log.md +1 -1
  33. package/content/operators/_ref.md +6 -6
  34. package/content/plugins/plugins-introduction.md +13 -0
  35. package/content/plugins/posthog.md +1 -1
  36. package/content/provider-reference/auth-js-providers.md +2 -2
  37. package/content/provider-reference/openidconnectprovider.md +1 -1
  38. package/content/reference/cli.md +164 -0
  39. package/content/testing/config-tests.md +4 -2
  40. package/content/tutorial/tutorial-create-page.md +1 -1
  41. package/content/tutorial/tutorial-requests-api.md +1 -1
  42. package/content/tutorial/tutorial-requests-sql.md +1 -1
  43. package/content/tutorial/tutorial-start.md +1 -1
  44. package/content/user-authentication/auth-configuration.md +9 -9
  45. package/content/user-authentication/auth-steps.md +6 -4
  46. package/content/user-authentication/organizations.md +68 -1
  47. package/content/user-authentication/protected-pages-apis.md +4 -4
  48. package/content/user-authentication/roles.md +2 -2
  49. package/content/user-authentication/user-object.md +2 -2
  50. package/content/websockets/websocket-publish.md +1 -1
  51. package/content/websockets/websockets-introduction.md +54 -2
  52. package/index.json +74 -59
  53. package/package.json +2 -2
@@ -12,7 +12,7 @@ The `_base64` operator converts strings to and from [base64](https://en.wikipedi
12
12
  (value: string): string
13
13
  ```
14
14
 
15
- The `_base64.decode` method decodes base64 encoded content into an ASCII string.
15
+ The `_base64.decode` method decodes base64 or base64url encoded content into a UTF-8 string. In the browser, it throws an error if the decoded bytes are not valid UTF-8.
16
16
 
17
17
  #### Arguments
18
18
 
@@ -33,7 +33,7 @@ Returns: `"Hello"`.
33
33
  (value: string): string
34
34
  ```
35
35
 
36
- The `_base64.encode` method base64 encodes a ASCII string.
36
+ The `_base64.encode` method base64 encodes the UTF-8 bytes of a string.
37
37
 
38
38
  #### Arguments
39
39
 
@@ -4,7 +4,7 @@
4
4
  (value: any): any
5
5
  ```
6
6
 
7
- The `_log` operator logs it input to the console, and returns the value it received. Since it returns the value it received, it can be used to debug without affecting the rest of the configuration.
7
+ The `_log` operator logs its input and returns the value it received. Since it returns the value it received, it can be used to debug without affecting the rest of the configuration. In the browser it logs to the console. On the server it writes an info line to the server log, where secrets and values marked with `_credential` are removed like on every other log line.
8
8
 
9
9
  > This operator can be used as a [`_build`](/_build) operator method.
10
10
 
@@ -82,7 +82,7 @@ The file path to the referenced file, from the root of the project directory.
82
82
  ###### Reference pages:
83
83
  ```yaml
84
84
  # lowdefy.yaml
85
- lowdefy: 7.0.0
85
+ lowdefy: 7.2.0
86
86
  pages:
87
87
  - _ref: pages/page1.yaml
88
88
  - _ref: pages/page2.yaml
@@ -103,7 +103,7 @@ blocks:
103
103
  ```
104
104
  Returns:
105
105
  ```
106
- lowdefy: 7.0.0
106
+ lowdefy: 7.2.0
107
107
  pages:
108
108
  - id: page1
109
109
  type: PageHeaderMenu
@@ -176,7 +176,7 @@ blocks:
176
176
  ###### Use key:
177
177
  ```yaml
178
178
  # lowdefy.yaml
179
- lowdefy: 7.0.0
179
+ lowdefy: 7.2.0
180
180
  version:
181
181
  _ref:
182
182
  path: package.json
@@ -190,7 +190,7 @@ version:
190
190
  ```
191
191
  Returns:
192
192
  ```
193
- lowdefy: 7.0.0
193
+ lowdefy: 7.2.0
194
194
  version: 1.0.0
195
195
  ```
196
196
 
@@ -227,7 +227,7 @@ module.exports = useLocalOrSharedConfig;
227
227
 
228
228
  ```yaml
229
229
  // lowdefy.yaml
230
- lowdefy: 7.0.0
230
+ lowdefy: 7.2.0
231
231
 
232
232
  cli:
233
233
  refResolver: resolvers/useLocalOrSharedConfig.js
@@ -253,7 +253,7 @@ module.exports = addFooter;
253
253
  ```
254
254
  ```yaml
255
255
  // lowdefy.yaml
256
- lowdefy: 7.0.0
256
+ lowdefy: 7.2.0
257
257
 
258
258
  pages:
259
259
  - _ref:
@@ -53,3 +53,16 @@ properties: {
53
53
  },
54
54
  },
55
55
  ```
56
+
57
+ A block also marks how it draws a string with `textKind`: `html` for a property it renders with `renderHtml` (sanitised HTML), `text` for one it renders as escaped text, and `data` for a value it stores or compares but never draws, such as an option value (add `dataWith: label` when the block draws the value in place of a missing `label`). The policy then reads a whole URL, markdown links and words starting with `//` in such a property as words; with `text` tag syntax too; and in `data` every string, however nested, is text. Leave a property that renders markdown, CSS or a URL unmarked.
58
+
59
+ A table block marks its rows with `rowsKind`, naming its columns property, a column's type and children keys, the type a column without one has, and the column types that draw a cell as text: the cell options key with the options that read a row field into a cell, and the properties that draw rows themselves: `{ columns: 'columns', type: 'type', children: 'children', cell: 'cell', cellRowKeys: ['colorFrom'], drawnBy: ['expandable.template'], defaultType: 'text', textTypes: ['text', 'number', ...] }`. When every column has a text type, no column reads a row field into its cell and no `drawnBy` property is set, the rows are data.
60
+
61
+ ```js
62
+ properties: {
63
+ type: 'object',
64
+ properties: {
65
+ content: { type: 'string', textKind: 'html', description: 'Text content - supports html.' },
66
+ },
67
+ },
68
+ ```
@@ -129,7 +129,7 @@ By default, `posthog-js` sends the text of every element a person clicks. In a b
129
129
  On every event, whatever its name (autocaptured clicks, rage clicks, dead clicks and swipes, copy events and any event `posthog-js` adds later):
130
130
 
131
131
  - __Text that is not config text.__ Each clicked text (`$el_text`, `lowdefy_text`, the `text` entries of `$elements_chain` and `$elements`, `$selected_content` and link targets) is kept only when it equals, after whitespace is collapsed, a string in the config of the page the event was captured on, in the app's menus, in the i18n messages or in the antd locale. Everything else is removed: grid and table cell values, options and menu items a request fills, labels built from records, and anything a `Dynamic` block's endpoint returned. A link whose target is not config text keeps its `href` attribute, emptied, so the click still reads as a link click.
132
- - __Element attributes outside a structural allow-list.__ Only the tag, classes, `class`, `role`, `type`, `row-index`, `col-id`, `nth-child` and `nth-of-type` are kept, and `id` only when it is a block's wrapper id (`bl-<blockId>`). Other ids are removed, because ids that libraries generate can embed runtime keys: an antd tab is `rc-tabs-<n>-tab-<key>`, so a `Tabs` block keyed by record would send the record. Every other attribute is removed, including `title` (antd select options carry their label there), `aria-label`, `value`, `placeholder`, `alt` and every `data-*` attribute.
132
+ - __Element attributes outside a structural allow-list.__ Only the tag, classes, `class`, `role`, `type`, `row-index`, `col-id`, `data-row-index`, `data-col-key`, `nth-child` and `nth-of-type` are kept, and `id` only when it is a block's wrapper id (`bl-<blockId>`). Other ids are removed, because ids that libraries generate can embed runtime keys: an antd tab is `rc-tabs-<n>-tab-<key>`, so a `Tabs` block keyed by record would send the record. Every other attribute is removed, including `title` (antd select options carry their label there), `aria-label`, `value`, `placeholder`, `alt` and every other `data-*` attribute.
133
133
 
134
134
  ###### What stays
135
135
 
@@ -75,7 +75,7 @@ The providers that can be used are:
75
75
  ###### Auth0 configuration:
76
76
 
77
77
  ```yaml
78
- lowdefy: 7.0.0
78
+ lowdefy: 7.2.0
79
79
  auth:
80
80
  providers:
81
81
  - id: auth0
@@ -94,7 +94,7 @@ In Auth0, the callback URL should be configured to `https://example.com/api/auth
94
94
  ###### GitHub configuration:
95
95
 
96
96
  ```yaml
97
- lowdefy: 7.0.0
97
+ lowdefy: 7.2.0
98
98
  auth:
99
99
  providers:
100
100
  - id: github
@@ -28,7 +28,7 @@ The OpenIDConnectProvider can be used to authenticate with a OpenID Connect comp
28
28
  Usually only the `wellKnown`, `clientId` and `clientSecret` properties need to be configured:
29
29
 
30
30
  ```yaml
31
- lowdefy: 7.0.0
31
+ lowdefy: 7.2.0
32
32
  providers:
33
33
  - id: my_provider
34
34
  type: OpenIDConnectProvider
@@ -57,10 +57,13 @@ The `data list` command prints each [journey data set](/journey-data-sets) in `t
57
57
 
58
58
  The `dev` command starts a Lowdefy development server, running locally. It can be accessed in a browser at [http://localhost:3000](http://localhost:3000). The CLI watches the file system, and rebuilds the app and reloads served pages every time a change is made to any of the files in the project directory. The `dev` command should not be used to serve a production app, the `build` and `start` commands should be used instead.
59
59
 
60
+ - `--android`: _Experimental._ Open the app in Lowdefy Dev on an Android emulator, or on a phone connected by USB with USB debugging on. Starts the first virtual device when no device is connected, installs Lowdefy Dev, and connects it to the dev server through `adb reverse`, so the phone reaches it on `localhost`. Needs `adb` from the Android SDK (on your `PATH`, or under `ANDROID_HOME`). Until Lowdefy Dev builds are released, set `LOWDEFY_DEV_APP_ANDROID` to the path of a Lowdefy Dev `.apk`.
60
61
  - `--config-directory <config-directory>`: Change the config directory. The default is the current working directory.
61
62
  - `--dev-directory <dev-directory>`: Change the dev directory, the directory in which the development server is placed. The default is `<config-directory>/.lowdefy/dev`.
62
63
  - `--disable-telemetry`: Disable telemetry.
63
64
  - `--exit-with-pid <pid>`: Stop the server when the process with this id exits. For test runners and scripts that start the server. The `LOWDEFY_EXIT_WITH_PID` environment variable does the same, and passes through wrappers such as `pnpm exec` or a secrets manager.
65
+ - `--ios`: _Experimental._ Open the app in Lowdefy Dev on an iPhone simulator. Uses a booted simulator, or boots the newest iPhone, installs Lowdefy Dev and opens the dev server in it. Needs macOS with Xcode. Until Lowdefy Dev builds are released, set `LOWDEFY_DEV_APP_IOS` to the path of a Lowdefy Dev simulator build (`.app`).
66
+ - `--lan [interface]`: _Experimental._ Let a phone on the local network connect. The server also listens on the first private network address, or on the network interface you name (for example `--lan en0`), and prints the interface it chose with a QR code to scan with Lowdefy Dev. The code carries a pairing token that lasts until the server stops; a request from another machine without it is refused. The dev tools and the headless user of the [agent tools](/ai-agent-docs) answer only on your own computer, even with the token.
64
67
  - `--log-level <level>`: The minimum severity of logs to show in the CLI output. Options are `debug`, `info`, `warn` or `error`. The default is `info`.
65
68
  - `--mock-user [user]`: Start the dev server authenticated as a mock user, bypassing the login flow. Pass a JSON user object to set the identity and roles (e.g. `--mock-user '{"sub":"dev","roles":["admin"]}'`), or use the bare flag for a default user with no roles. This is the same mechanism as `auth.dev.mockUser`. Dev server only. See [Auth Configuration](/auth-configuration#mock-user-for-testing-dev-server-only).
66
69
  - `--no-open`: Do not open a new tab in the default browser.
@@ -287,6 +290,167 @@ The `journeys coverage` command reports what real use no journey in `tests/journ
287
290
  - `--since <since>`, `--from <YYYY-MM-DD>`, `--to <YYYY-MM-DD>`: The production window, as for [`journeys pull posthog`](#journeys-pull-posthog), at most 30 days.
288
291
  - `--config-directory`, `--dev-directory`, `--disable-telemetry`, `--log-level`: As for [`journeys session`](#journeys-session).
289
292
 
293
+ ## mobile
294
+
295
+ > **Experimental.** The `mobile` commands, and `lowdefy dev --ios`, `--android` and `--lan`, need `config.experimental.mobile: true` in `lowdefy.yaml`: without it the build fails on the `mobile` section. Commands and flags may change in a minor release. See [Mobile Apps](/mobile-apps).
296
+
297
+ The `mobile` commands build, submit and update the app's phone shells with [EAS](https://expo.dev/eas), from your own Expo, Apple and Google accounts. A shell is declared under `mobile.shells` in `lowdefy.yaml`. Each command builds the app, then writes the shell's Expo project to `.lowdefy/mobile/<shell>/project`: a copy of the published `@lowdefy/shell` at the app's Lowdefy version, with its own install, plus `shell.json`, `eas.json` (a build and submit profile per environment in `config.environments` that has a `url`, and a `development` profile) and the icon. Each build profile pins EAS to the pnpm version that installed the project, and reads EAS's `production` environment variables for an environment named `prod` or `production`, `preview` for any other. Each submit profile carries the shell's `ios.ascAppId`, the App Store Connect app id, so `submit` and `release` run without asking for it. The folder is generated; do not commit it. Every EAS command runs from it, through `npx eas-cli@<pinned version>` with `EAS_NO_VCS=1`, so nothing needs to be installed globally.
298
+
299
+ ```
300
+ lowdefy mobile config [--shell <id>] [--env <environment>] [--dry-run]
301
+ lowdefy mobile build [--shell <id>] [--env <environment>] [--platform ios|android|all] [--profile development] [--non-interactive] [--local] [--dry-run]
302
+ lowdefy mobile submit [--shell <id>] [--env <environment>] [--platform ios|android|all] [--non-interactive] [--dry-run]
303
+ lowdefy mobile update [--shell <id>] [--env <environment>] [--platform ios|android|all] [--rollout <percent> | --promote | --rollback] [--dry-run]
304
+ lowdefy mobile release [--shell <id>] [--env <environment>] [--platform ios|android|all] [--non-interactive] [--no-wait --auto-submit] [--rollout <percent>] [--dry-run]
305
+ lowdefy mobile checklist [--shell <id>] [--env <environment>]
306
+ ```
307
+
308
+ Every `mobile` command takes:
309
+
310
+ - `--shell <id>`: The shell to work on, a `mobile.shells` id. Needed when the app declares more than one.
311
+ - `--env <environment>`: The environment, a key of `config.environments`. The binary opens its `url` and listens on the EAS channel of the same name. The default is `production`.
312
+ - `--dry-run`: Print the EAS commands, with their working directory and environment variables, and run none. The project is still written.
313
+ - `--config-directory`, `--disable-telemetry`, `--log-level`, `--ref-resolver`, `--server-directory`, `--skip-plugin-checks`: As for [`build`](#build).
314
+
315
+ ### mobile config
316
+
317
+ Writes the shell's project and prints its runtime version, `<nativeVersion>-<profile>`, or `<nativeVersion>-<profile>-<plugins hash>` for a shell with [plugins](#shell-plugins). Over-the-air updates reach only binaries with the same runtime version, so it changes only when the shell's native code, capability profile or plugins do.
318
+
319
+ For a shell with plugins, it first reads each plugin's published `package.json` (`pnpm view`, from the app's directory, so the registries in the app's `.npmrc` apply) and checks its peers. It then adds each plugin and its native peers to the project's dependencies, writes the plugins into `shell.json`, and, after the install, refuses plugins the shell's profile must not take and type names that clash. Removing a plugin from `lowdefy.yaml` removes it from the project on the next run.
320
+
321
+ - `--dry-run`: Read and check the plugins, print the dependencies it would add and the install, and run nothing.
322
+
323
+ ### mobile build
324
+
325
+ Raises the store version, then runs `eas build --profile <environment>`. The shell's `version` gives the major and minor; each build reads the latest finished build on the channel for each store and uses the next patch, or `<major>.<minor>.0` for a first build or a new `version`. Both stores get the same version. Build numbers are kept by EAS.
326
+
327
+ - `--platform <platform>`: `ios`, `android` or `all`. The default is `all`.
328
+ - `--non-interactive`: Run without prompts, with the credentials stored in EAS, and queue the build without waiting for it. For CI. Without it the build is interactive, as the first build of a shell must be.
329
+ - `--local`: Build on this machine (`eas build --local`; a Mac for iOS).
330
+ - `--profile development`: Build a development client of the shell, for internal distribution, which connects to `lowdefy dev`. It takes no store version.
331
+
332
+ ### mobile submit
333
+
334
+ Uploads the latest build to TestFlight and Google Play internal testing (`eas submit --latest`), and nothing more. Review and promotion are steps for a person (see [`mobile checklist`](#mobile-checklist)).
335
+
336
+ - `--platform <platform>`, `--non-interactive`: As for `mobile build`.
337
+
338
+ ### mobile update
339
+
340
+ Sends the shell's JavaScript to installed binaries on the environment's channel as an over-the-air update (`eas update`). Only `@lowdefy/shell` code travels this way; the app's pages always come from its server. The update's message records the shell version, profile and runtime version: `lowdefy-shell@<version> profile=<profile> runtime=<runtime version>`.
341
+
342
+ - `--rollout <percent>`: Send the update to this percentage of devices.
343
+ - `--promote`: Roll the latest update for this runtime version out to every device.
344
+ - `--rollback`: Republish the update before the latest one for this runtime version. A later `release` of the same Lowdefy version sends the newer shell again, so roll back while you fix forward.
345
+ - `--platform <platform>`: As for `mobile build`.
346
+
347
+ ### mobile release
348
+
349
+ What CI runs. For each store it reads the latest finished build on the channel and compares its runtime version with the shell's:
350
+
351
+ - No build, or a different runtime version: raise the store version, build and submit.
352
+ - The same runtime version, and the latest update carries a different shell version, or none: send an update.
353
+ - Otherwise: nothing.
354
+
355
+ It prints one line per store saying which and why, and exits with 0. Any EAS failure exits with 1. Release always runs EAS without prompts, so the first build and submission of a shell are done by hand first.
356
+
357
+ - `--no-wait --auto-submit`: Queue each build and let EAS submit it when it finishes, so the CI job does not wait. `--no-wait` needs `--auto-submit`; without them release waits for each build, then submits it.
358
+ - `--rollout <percent>`: Passed to the update.
359
+ - `--platform <platform>`: As for `mobile build`. `--non-interactive` is accepted and changes nothing.
360
+ - `--dry-run`: Print the reads, and for each store both paths with the condition that picks each.
361
+
362
+ ### mobile checklist
363
+
364
+ Prints, filled in with the shell's own ids, the steps the stores still need a person for: creating the store records, the first build and submission, making a `private` app private, copying the Play app signing key into `android.sha256`, the privacy questions for the shell's profile and plugins, what each shell plugin declares, and, for `private` and `store` shells, review and promotion of each native release. It runs no EAS command.
365
+
366
+ ### Environment variables
367
+
368
+ - `EXPO_TOKEN`: Signs EAS in without `eas login`, for CI.
369
+ - `SENTRY_AUTH_TOKEN`: Optional. Uploads source maps on `build` and `update`.
370
+
371
+ Both pass through from your environment and are never written into the project.
372
+
373
+ ### Shell plugins
374
+
375
+ A shell can carry native code its capability profile does not, such as a Bluetooth printer or a device-management SDK, by listing Lowdefy shell plugins under `mobile.shells[].plugins`. Each is an npm package that declares the native modules, config plugins, permissions, privacy reasons and collected data it brings.
376
+
377
+ ```yaml
378
+ plugins:
379
+ - name: '@example/lowdefy-printer'
380
+ version: 2.1.0
381
+ mobile:
382
+ shells:
383
+ - id: field
384
+ profile: field
385
+ plugins:
386
+ - name: '@example/lowdefy-printer'
387
+ version: 2.1.0
388
+ typePrefix: Printer
389
+ - name: '@example/lowdefy-mdm'
390
+ version: 1.0.3
391
+ options:
392
+ tenant: field-team
393
+ ```
394
+
395
+ Each entry takes:
396
+
397
+ - `name: string`: __Required__ - The npm package name, from the public registry or one set in the app's `.npmrc`.
398
+ - `version: string`: __Required__ - An exact version, like `2.1.0` or `2.1.0-beta.1`. Ranges, dist-tags, git, `file:` and `workspace:` are refused, so one name and version is always the same native code.
399
+ - `typePrefix: string`: A prefix added to the plugin's type names, as for app [plugins](/lowdefy-schema).
400
+ - `options: object`: Passed to the plugin's config plugins. Options are baked into the binary and uploaded to EAS, so they never hold secrets.
401
+
402
+ The build checks that:
403
+
404
+ - A shell lists each plugin once.
405
+ - A package has one version across root `plugins` and every shell's `plugins`, since the app runs one version of a plugin.
406
+ - A mobile page uses a plugin's native blocks and actions only when every shell lists that plugin, since every shell opens every mobile page. The error names the page, the block or action and the shell that lacks the plugin.
407
+ - A plugin's native block or action type is not named like a built-in native type, such as `Box` or `SetState`. Set a `typePrefix`.
408
+
409
+ A shell with plugins gets its own runtime version, so it builds and updates on its own instead of sharing its profile's builds and updates. A change of a plugin's version or options needs a native build.
410
+
411
+ `mobile config` installs the plugins into the shell's project. It fails, naming the shell and plugin, when:
412
+
413
+ - The package or version is not on the registry.
414
+ - The plugin's `expo` peer range does not include the shell's Expo version.
415
+ - A native peer is not an exact version, or a peer (`expo` included) is not marked optional.
416
+ - The plugin links a native module the shell already carries in a capability profile, such as `expo-camera`. Pick the profile that carries it.
417
+ - The plugin asks for a permission the shell's profile leaves out, such as the camera on `basic`. The error names the profile to pick.
418
+ - A plugin type name clashes with a built-in native type or another plugin's. Set a `typePrefix`.
419
+
420
+ `mobile checklist` lists each plugin with the permissions, privacy reasons and data it declares, and joins its data to the privacy answers. It reads the plugins from the configured project, so run `mobile config` first.
421
+
422
+ #### Writing a shell plugin
423
+
424
+ A Lowdefy shell plugin is an npm package that exports:
425
+
426
+ - `./shell`: CommonJS, an object with the native code it brings: `capabilities`, `modules` (`{ [package]: nativeModuleName }`), `plugins` (Expo config plugin entries, or a function of the entry's `options` that returns them), `permissions` (iOS `Info.plist` keys and Android permissions), `privacyReasons` (`{ category, reasons }` for each required-reason API) and `dataCollected` (`{ type, purpose }`).
427
+ - `./native`: Optional. Its native block and action types, as named exports `blocks` and `actions`.
428
+ - `./types`: Optional. Its type names, with the native ones under `native: { blocks, actions, blockMetas, icons }`, so the build knows them. A native-only plugin, such as a wrapped device-management SDK, leaves it out and adds no types. A plugin in root `plugins` must export it.
429
+
430
+ Its native modules are `peerDependencies` at exact versions, beside an `expo` peer range, and every peer is marked optional in `peerDependenciesMeta`, so the web server's install leaves the native code out:
431
+
432
+ ```json
433
+ {
434
+ "name": "@example/lowdefy-printer",
435
+ "version": "2.1.0",
436
+ "exports": {
437
+ "./shell": "./shell.cjs",
438
+ "./native": "./native.js",
439
+ "./types": "./types.js"
440
+ },
441
+ "peerDependencies": {
442
+ "expo": ">=58.0.0 <59.0.0",
443
+ "react-native-ble-plx": "3.5.0"
444
+ },
445
+ "peerDependenciesMeta": {
446
+ "expo": { "optional": true },
447
+ "react-native-ble-plx": { "optional": true }
448
+ }
449
+ }
450
+ ```
451
+
452
+ `options` are written into `shell.json`, uploaded to EAS and baked into the binary, so they never hold secrets. A plugin that needs a secret reads an EAS environment variable in its config plugin. An SDK on Apple's list of commonly used SDKs also needs its own signed privacy manifest inside the SDK.
453
+
290
454
  ## upgrade
291
455
 
292
456
  The `upgrade` command upgrades a Lowdefy app to a newer version by walking you through migration prompts that handle breaking changes.
@@ -145,6 +145,8 @@ FAIL member saves a ticket
145
145
  action-error Request "save_ticket" failed in save.onClick with ServiceError. pages/tickets.yaml:88
146
146
  ```
147
147
 
148
+ When the dev server loses its web server, a request gets no answer and the journey fails with a `dev-server` line instead. That says nothing about the app: check the dev server log for a restart or crash, then run the journey again.
149
+
148
150
  Each error line gives its kind, its message and the config file and line it came from, when known. Fix the app in most cases. When the error is the outcome the app means, such as a unique index violation that a `catch` action shows as "already exists", either make it a user error in config (a `Throw` action is one), or assert it with `expect: { error: text }` straight after the interaction:
149
151
 
150
152
  ```yaml
@@ -173,8 +175,8 @@ A `blockId` reaches a block's own control — its button, input or link. Some co
173
175
  | Key | Meaning |
174
176
  | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
175
177
  | `blockId` | The block to search inside. |
176
- | `row` | A grid row, zero-based as displayed (`AgGrid*` blocks). Needs `blockId`. |
177
- | `column` | A grid cell in that row, by the column's `field` or `colId`. Needs `blockId`. |
178
+ | `row` | A grid row, zero-based as displayed (`AgGrid*`, `Table` and `TableInput` blocks). Needs `blockId`. |
179
+ | `column` | A grid cell in that row, by the column's `field`, `colId` or `key`. Needs `blockId`. |
178
180
  | `text` | The interactive control whose visible text is exactly this (a button label, a tab, a menu item). |
179
181
  | `containing` | The innermost element whose visible text contains this, as the page shows it, even across elements (`Assigned to <b>Jane</b>`, a label and value side by side): a row of a list a person picks by the name or email it shows. |
180
182
  | `nth` | When several elements match, the zero-based one to use. |
@@ -33,7 +33,7 @@ Change the `lowdefy.yaml` to look like this:
33
33
 
34
34
  ```yaml
35
35
  name: lowdefy-project-template
36
- lowdefy: 7.0.0
36
+ lowdefy: 7.2.0
37
37
 
38
38
  pages:
39
39
  ################ -------- Copy from here -------- ################
@@ -18,7 +18,7 @@ In your `lowdefy.yaml` file, add the following:
18
18
 
19
19
  ```yaml
20
20
  name: lowdefy-project-template
21
- version: 7.0.0
21
+ version: 7.2.0
22
22
 
23
23
  ################ -------- Copy from here -------- ################
24
24
  connections:
@@ -51,7 +51,7 @@ In your `lowdefy.yaml` file, add the following:
51
51
 
52
52
  ```yaml
53
53
  name: lowdefy-project-template
54
- version: 7.0.0
54
+ version: 7.2.0
55
55
 
56
56
  connections:
57
57
  # ...
@@ -63,7 +63,7 @@ Made by a Lowdefy 🤖
63
63
  Open the `lowdefy.yaml` file using a text editor like [VS Code](https://code.visualstudio.com/download). The content of the file should look like this:
64
64
 
65
65
  ```yaml
66
- lowdefy: 7.0.0
66
+ lowdefy: 7.2.0
67
67
  name: Lowdefy starter
68
68
 
69
69
  pages:
@@ -11,7 +11,7 @@ For a login method to work you must configure **at least one mechanism** (`email
11
11
  A required signing secret, given as a `_secret` reference:
12
12
 
13
13
  ```yaml
14
- lowdefy: 7.0.0
14
+ lowdefy: 7.2.0
15
15
  auth:
16
16
  secret:
17
17
  _secret: BETTER_AUTH_SECRET
@@ -24,7 +24,7 @@ Also pin the app's canonical origin — the `url` of the current environment in
24
24
  Sessions, users, accounts and organizations are stored through an adapter:
25
25
 
26
26
  ```yaml
27
- lowdefy: 7.0.0
27
+ lowdefy: 7.2.0
28
28
  auth:
29
29
  database:
30
30
  id: auth_db
@@ -46,7 +46,7 @@ See the [MongoDBAuthAdapter](/MongoDBAuthAdapter) reference. Collection names fo
46
46
  - **Passkeys** — `auth.passkey` (`enabled`, `rpId`, `rpName`).
47
47
 
48
48
  ```yaml
49
- lowdefy: 7.0.0
49
+ lowdefy: 7.2.0
50
50
  auth:
51
51
  emailAndPassword:
52
52
  enabled: true
@@ -58,7 +58,7 @@ auth:
58
58
  `auth.email` references an **SMTP connection** by id — the connection owns `from`, `replyTo`, the transport and the delivery filter, and is shared by every auth email flow. There is no inline transport shape. Optionally map individual flows to your own notification templates:
59
59
 
60
60
  ```yaml
61
- lowdefy: 7.0.0
61
+ lowdefy: 7.2.0
62
62
  auth:
63
63
  email:
64
64
  connectionId: email # an SMTP connection in connections[]
@@ -94,7 +94,7 @@ BetterAuth ships no UI — your app owns its auth pages, and `auth.authPages` po
94
94
  | `magicLink` | — | landing page for the sign-in email (opt-in; see below) |
95
95
 
96
96
  ```yaml
97
- lowdefy: 7.0.0
97
+ lowdefy: 7.2.0
98
98
  auth:
99
99
  authPages:
100
100
  signIn: /login
@@ -113,7 +113,7 @@ A verification email links to Better Auth's verify endpoint, which confirms the
113
113
  Set the key and the sign-in email links to a page of your own instead, with the token and the callback destinations carried on its URL query. Fetching a Lowdefy page is harmless, so the token stays unspent until a real click runs [`MagicLinkVerify`](/MagicLinkVerify):
114
114
 
115
115
  ```yaml
116
- lowdefy: 7.0.0
116
+ lowdefy: 7.2.0
117
117
  auth:
118
118
  magicLink:
119
119
  enabled: true
@@ -161,7 +161,7 @@ See [Two-Factor Authentication](/two-factor) for the two-factor pages, and the [
161
161
  Database sessions. Length is `expiresIn` (seconds, default 604800 = 7 days); `updateAge` (default 86400) is how often an active session's expiry is refreshed:
162
162
 
163
163
  ```yaml
164
- lowdefy: 7.0.0
164
+ lowdefy: 7.2.0
165
165
  auth:
166
166
  session:
167
167
  expiresIn: 43200 # 12 hours in seconds
@@ -177,7 +177,7 @@ auth:
177
177
  - **API strategies** — `auth.strategies` authenticates non-session callers (server-to-server) with an `apiKey` or a `jwt`:
178
178
 
179
179
  ```yaml
180
- lowdefy: 7.0.0
180
+ lowdefy: 7.2.0
181
181
  auth:
182
182
  strategies:
183
183
  - id: service-key
@@ -231,7 +231,7 @@ Add the `auth.dev.mockUser` section to your `lowdefy.yaml`:
231
231
 
232
232
  ###### Configure a mock user for development
233
233
  ```yaml
234
- lowdefy: 7.0.0
234
+ lowdefy: 7.2.0
235
235
 
236
236
  auth:
237
237
  providers:
@@ -114,16 +114,18 @@ Scope, required permission, and target for every auth step. Permissions are chec
114
114
 
115
115
  | Step | Scope | Permission | Target | What it does |
116
116
  | ---- | ----- | ---------- | ------ | ------------ |
117
- | `InviteMember` | org | `invitation: [create]` | — | Invite a member by email; carries `appRoles`, `orgRole`, `attributes`, `contactId`, `profile`; `resend` refreshes. |
117
+ | `InviteMember` | org | `invitation: [create]` | — | Invite a member by email; carries `appRoles`, `orgRole`, `attributes`, `contactId`, `profile`; `resend` refreshes. Accept sets `contactId` only on a login with no contact link, and refuses one linked to a different contact. |
118
118
  | `CancelInvitation` | org | `invitation: [cancel]` | — | Cancel a pending invitation. |
119
119
  | `ListMembers` | org | `member: [list]` | — | List members of the organization (accepts `organizationSlug`). |
120
120
  | `RemoveMember` | org | `member: [delete]` | — | Remove a member from the organization. |
121
121
  | `UpdateMemberRoles` | org | `member: [update]` | — | Set the membership's **app roles** (`appRoles` array; empty clears). |
122
- | `UpdateMemberOrgRole` | org | `member: [update]` | — | Set the **org tier** (`owner`/`admin`/`member`). |
122
+ | `UpdateMemberOrgRole` | org | `member: [update]` | — | Set the **org tier** (`owner`/`admin`/`member`). A suspended member cannot be made `owner`. |
123
123
  | `UpdateMemberAttributes` | org | `member: [update]` | — | Set the membership's per-organization attributes. |
124
+ | `SuspendMember` | org | `member: [suspend]` | — | [Suspend](/organizations#suspending-a-member) a member in this organization (`memberId`): the row and its roles stay, but it admits nobody. Refuses an `owner` (change their org tier first) and the caller's own membership. |
125
+ | `UnsuspendMember` | org | `member: [suspend]` | — | Lift a suspension (`memberId`); the member keeps the roles they held. |
124
126
  | `UpdateOrganization` | org | `organization: [update]` | — | Update the organization row (name, slug, metadata). |
125
127
  | `RevokeOrgMcpToken` | org | `member: [update]` | — | Switch off any [member token](/mcp-oauth#tokens-for-scripts) in the organization (`id`). |
126
- | `UpdateUserProfile` | org | `user: [update]` | `userId` (self-exempt) | Update a member's display name/image (per-organization copy). Self-service save is exempt. |
128
+ | `UpdateUserProfile` | org | `user: [update]` | `userId` (self-exempt) | Update a member's display name/image (per-organization copy) and profile. Self-service save is exempt. Does not write `contactId`, which only an accepted invitation sets. |
127
129
  | `UpdateUserAttributes` | org | `user: [set-attributes]` | `userId` | Set global user attributes. |
128
130
  | `BanUser` | org | `user: [ban]` | `userId` | Ban a user. |
129
131
  | `UnbanUser` | org | `user: [ban]` | `userId` | Lift a ban. |
@@ -131,7 +133,7 @@ Scope, required permission, and target for every auth step. Permissions are chec
131
133
  | `RevokeUserSessions` | org | `session: [revoke]` | `userId` | Sign a user out of all sessions. |
132
134
  | `ResetUserTwoFactor` | org | `user: [reset-two-factor]` | `userId` | Clear a user's two-factor enrolment and trust-device records. |
133
135
  | `RevokeUserPasskeys` | org | `user: [revoke-passkeys]` | `userId` | Remove a user's passkeys (`passkeyId` to target one). |
134
- | `CreateOrganization` | system | — | — | Create an organization (tenant provisioning). Needs `userId`, or `name`+`slug` for creator-less provisioning. |
136
+ | `CreateOrganization` | system | — | — | Create an organization (tenant provisioning). Takes `name` and `slug` (required), `logo`, `metadata` and an optional creator `userId`. The creator becomes its `owner`, with the app roles in [`auth.organizations.creatorAppRoles`](/organizations#app-roles-for-a-new-organizations-owner); without one the organization has no members until someone accepts an invitation. A slug another organization holds is refused. If a run fails after writing the organization but before its owner, running it again with the same creator and slug within ten minutes finishes it. |
135
137
  | `ListUsers` | system | — | — | List every user in the deployment. |
136
138
  | `LeaveOrganization` | caller | — | — | End the caller's own membership of the named organization (`organizationId`, required). [Leaving from a routine](#leaving-an-organization-from-a-routine). |
137
139
  | `RevokeMcpGrant` | caller | — | — | Revoke the calling assistant's own [MCP grant](/mcp-oauth#switching-organization-from-the-assistant). |
@@ -28,11 +28,14 @@ An app that sets nothing gets `pinned` with one auto-seeded organization, invite
28
28
  | `create` | `auto` \| `operator` | **tenant only** | `tenant` → `auto` | How a tenant organization comes into being: `auto` mints one for a user at first session; `operator` leaves creation to your own config (the `CreateOrganization` step). |
29
29
  | `invitationExpiresIn` | integer (seconds, min 60) | both | `172800` (48h) | How long an invitation stays acceptable. Re-sending an invitation refreshes its expiry. |
30
30
  | `membershipLimit` | integer (min 1) | both | `1000000` (effectively open) | The most members one organization may have. Once an organization has this many, accepting an invitation and adding a member are refused (a 403). Set it to cap organization size, for example per tenant. It is also the default page size of `ListMembers` when no `limit` is given. |
31
+ | `invitationLimit` | integer (min 1) | both | `1000000` (effectively open) | The most open invitations one organization may have. Once an organization has this many pending, unexpired invitations, inviting another is refused (a 403 with code `INVITATION_LIMIT_REACHED`). Expired, accepted and cancelled invitations don't count, and re-inviting an address replaces its open invitation rather than adding one. |
32
+ | `creatorAppRoles` | array of role ids | both | `[]` | App roles the owner of a new organization gets on their membership. See [App roles for a new organization's owner](#app-roles-for-a-new-organizations-owner). |
31
33
 
32
34
  The build cross-checks these, and the errors are worth knowing before you hit them:
33
35
 
34
36
  - **`org` is required under `pinned`** and **rejected under `tenant`** — under `tenant` there is no single organization to pin; organizations are created per user.
35
37
  - **`create` is rejected under `pinned`** — the active organization is ensured at startup, so there is nothing to create on demand.
38
+ - **Every `creatorAppRoles` id must be declared in `auth.roles`**, the same as the roles a page or API gate names.
36
39
  - **Renaming `org` strands the existing membership.** The startup ensure is by slug, so changing `org` mints a *fresh* organization rather than renaming the old one, and every existing `member` row still points at the old id. Treat the pinned slug as permanent.
37
40
 
38
41
  Defaults line up with intent: `pinned` defaults to a closed, invite-only internal app; `tenant` defaults to self-serve SaaS (`signup: open`, `create: auto`).
@@ -52,7 +55,42 @@ An equivalent unique index you created yourself, under any name, is accepted. If
52
55
 
53
56
  ### Invitations for existing members
54
57
 
55
- An invitation is how someone joins an organization, never how a membership changes. Accepting an invitation into an organization you already belong to (you joined another way after it was sent) succeeds and marks the invitation accepted, but leaves your membership exactly as it is: the invitation's role, app roles and attributes are not applied, and no second membership is written. If your session had no active organization, the accepted organization becomes active. To change an existing membership, use the [auth steps](/auth-steps) (`UpdateMemberOrgRole`, `UpdateMemberRoles`, `UpdateMemberAttributes`), which check the caller's authority at the time of the change.
58
+ An invitation is how someone joins an organization, never how a membership changes. Accepting an invitation into an organization you already belong to (you joined another way after it was sent) succeeds and marks the invitation accepted, but leaves your membership exactly as it is: the invitation's role, app roles and attributes are not applied, and no second membership is written. If your session had no active organization, the accepted organization becomes active. The invitation's contact link is the exception: it belongs to the login, not the membership, so it follows the rules in [Invitations and the contact link](#invitations-and-the-contact-link). To change an existing membership, use the [auth steps](/auth-steps) (`UpdateMemberOrgRole`, `UpdateMemberRoles`, `UpdateMemberAttributes`), which check the caller's authority at the time of the change.
59
+
60
+ ### Invitations and the contact link
61
+
62
+ An invitation may carry a `contactId`: the link from the login to the app's record for this person, read as [`_user.contact_id`](/user-object). Apps compare it in author and access checks, so it is set once, by accepting an invitation:
63
+
64
+ - Accepting an invitation sets the link on a login that has none.
65
+ - An invitation with no `contactId`, or the same one the login already holds, leaves the link as it is.
66
+ - An invitation naming a different contact than the login holds is refused with the code `CONTACT_LINK_MISMATCH`. No membership is written and the invitation stays pending. The person accepting sees a short message with no ids; the server logs a warning (`invitation_contact_link_mismatch`) with the login, the invitation and both contact ids, so whoever runs the app can find the case.
67
+
68
+ The page that accepts should call `UpdateSession` after `AcceptInvitation`, so the browser's `_user` picks up the new link (and the new organization) straight away. No auth step changes the link after that: `UpdateUserProfile` does not write `contactId`. A wrong link is corrected in the data.
69
+
70
+ ### Suspending a member
71
+
72
+ Suspending takes a person out of one organization while keeping their membership on record. `BanUser` bans the login, which covers every organization and every app sharing the auth database. `RemoveMember` deletes the membership, so the app's own queries stop finding the person and the roles they held. A suspended membership keeps its row, its `appRoles`, org tier and attributes, but admits nobody. Lowdefy treats it as no membership everywhere it decides who the caller is:
73
+
74
+ - The person's session resolves unauthenticated (`_user` is `null`), so protected pages, requests and API endpoints give them what they give a non-member. Their MCP access tokens and [member tokens](/mcp-oauth#tokens-for-scripts) stop working, and an MCP client's refresh is refused.
75
+ - Signing in to a `pinned` app is refused with `MEMBERSHIP_REQUIRED`, the code a refused non-member gets. Under `signup: open` they are not joined again, and a pending invitation does not let them in either.
76
+ - Under `tenant`, sign-in makes the oldest organization they are not suspended in active. With none, sign-in goes as it does for someone with no membership, so under `create: auto` they get a new organization of their own. `ListOrganizations` leaves the organization out, and `SetActiveOrganization` and the other organization endpoints refuse it as they refuse a non-member.
77
+ - A suspended membership grants no [auth-step](/auth-steps) authority. Administrators can still manage the suspended member, with `UnsuspendMember`, `RemoveMember`, `BanUser` and the other steps.
78
+ - Accepting an invitation does not lift a suspension or make the organization active (see [Invitations for existing members](#invitations-for-existing-members)).
79
+
80
+ The `SuspendMember` and `UnsuspendMember` auth steps set and lift it, and need the `member: [suspend]` permission, which `owner` and `admin` hold. An `owner` cannot be suspended: change their org tier with `UpdateMemberOrgRole` first, which only an owner can do. A suspended member cannot be made an `owner` either, so every owner of an organization is a member who can sign in.
81
+
82
+ ```yaml
83
+ id: suspend-member
84
+ type: Api
85
+ routine:
86
+ - id: suspend
87
+ type: SuspendMember
88
+ properties:
89
+ memberId:
90
+ _payload: memberId
91
+ ```
92
+
93
+ The membership row stores it as `suspended: true` in the `user-members` collection. Rows without the field, including every row written before it existed, are not suspended. `ListMembers` returns `suspended` on each row. A report that finds people by role reads suspended members too; to leave them out, filter on `suspended: { $ne: true }`.
56
94
 
57
95
  ## The `owner` / `admin` / `member` tier vs app roles
58
96
 
@@ -63,6 +101,35 @@ A membership carries **two** independent role authorities, and keeping them apar
63
101
 
64
102
  So an app that wants a page for organization administrators does **not** gate it on the `admin` tier — it gates on one of its own app roles, and lets the write authority answer the administration question separately, at the step. See [Roles](/roles) for page and API gating, and [Auth Steps](/auth-steps) for the administration model.
65
103
 
104
+ ### App roles for a new organization's owner
105
+
106
+ When Lowdefy creates an organization and makes someone its owner, that person gets the `owner` tier and, by default, no app roles. In an app whose pages, endpoints and menus are gated on app roles, a new signup's own organization is then closed to them. `creatorAppRoles` lists the app roles the owner gets as well:
107
+
108
+ ```yaml
109
+ auth:
110
+ roles:
111
+ - id: billing-admin
112
+ - id: editor
113
+ organizations:
114
+ policy: tenant
115
+ creatorAppRoles:
116
+ - billing-admin
117
+ - editor
118
+ pages:
119
+ roles:
120
+ billing-admin:
121
+ - billing
122
+ ```
123
+
124
+ Here a new signup under `create: auto` becomes the `owner` of their own organization with `_user.roles` `[billing-admin, editor]`, so the `billing` page opens for them. The owner's tier stays `owner`; only the membership's `appRoles` is added.
125
+
126
+ It applies wherever Lowdefy itself makes someone the owner of a new organization:
127
+
128
+ - the organization a tenant signup mints under `create: auto`;
129
+ - the [`CreateOrganization`](/auth-steps) step, when it is given a creator (`userId`). An organization created without a creator has no owner to grant roles to.
130
+
131
+ It does not apply to anyone who joins an existing organization: invited members get the app roles their invitation carries, and users auto-joined to a pinned organization under `signup: open` join as `member` with none. Changing the setting leaves existing memberships as they are; use `UpdateMemberRoles` for those.
132
+
66
133
  ## Bootstrapping the first administrator
67
134
 
68
135
  Nothing grants organization authority implicitly — not even to the first user. On a fresh `pinned` + `invite-only` deployment that is a closed loop: nobody can invite (inviting needs authority nobody holds) and nobody can sign up (the gate admits only members and pending invitees). Breaking the loop is a single invitation document inserted by hand into the `user-invitations` collection, seeded with the `owner` tier. The full recipe — the exact document, why the key must be `_id`, why the role must be `owner`, and how to deliver the accept link — is in the [Auth Upgrade guide](/auth-upgrade#bootstrapping-the-first-administrator).