@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.
- package/README.md +1 -0
- package/content/actions/downloadcsv.md +1 -1
- package/content/actions/emailotpsend.md +58 -0
- package/content/actions/emailotpverify.md +79 -0
- package/content/actions/getlocalstorage.md +43 -0
- package/content/actions/link.md +47 -1
- package/content/actions/login.md +25 -5
- package/content/actions/logout.md +7 -5
- package/content/actions/magiclinkverify.md +117 -0
- package/content/actions/pdfmake.md +2 -2
- package/content/actions/posthogalias.md +29 -0
- package/content/actions/posthogcapture.md +49 -0
- package/content/actions/posthogcapturepageleave.md +38 -0
- package/content/actions/posthogfeatureflag.md +50 -0
- package/content/actions/posthoggroup.md +37 -0
- package/content/actions/posthogidentify.md +54 -0
- package/content/actions/posthoginit.md +96 -0
- package/content/actions/posthogoptin.md +29 -0
- package/content/actions/posthogoptout.md +29 -0
- package/content/actions/posthogpageview.md +37 -0
- package/content/actions/posthogreloadfeatureflags.md +47 -0
- package/content/actions/posthogreset.md +28 -0
- package/content/actions/posthogsetpersonproperties.md +36 -0
- package/content/actions/removelocalstorage.md +28 -0
- package/content/actions/resetvalidation.md +5 -3
- package/content/actions/setdarkmode.md +3 -3
- package/content/actions/setglobal.md +2 -0
- package/content/actions/setlocale.md +1 -1
- package/content/actions/setlocalstorage.md +34 -0
- package/content/actions/setstate.md +2 -0
- package/content/actions/validate.md +7 -4
- package/content/adapter-reference/mongodbauthadapter.md +46 -0
- package/content/agents/agent-endpoint-tools.md +24 -0
- package/content/agents/agent-properties.md +13 -3
- package/content/agents/agent-server-hooks.md +1 -1
- package/content/agents/agentchat.md +41 -4
- package/content/agents/agentconversations.md +42 -8
- package/content/agents/agents-introduction.md +107 -0
- package/content/callback-reference/auth0logoutcallback.md +54 -0
- package/content/concepts/ai-agent-docs.md +455 -106
- package/content/concepts/blocks.md +150 -0
- package/content/concepts/connections-and-requests.md +402 -0
- package/content/concepts/custom-html.md +42 -0
- package/content/concepts/custom-styling.md +50 -5
- package/content/concepts/dynamic-page-content.md +309 -0
- package/content/concepts/events-and-actions.md +185 -2
- package/content/concepts/four-primitives.md +31 -0
- package/content/concepts/html-attributes.md +293 -0
- package/content/concepts/i18n.md +12 -3
- package/content/concepts/keyboard-shortcuts.md +2 -2
- package/content/concepts/layout-overview.md +1 -1
- package/content/concepts/logger.md +99 -0
- package/content/concepts/lowdefy-api.md +1319 -0
- package/content/concepts/lowdefy-schema.md +144 -3
- package/content/concepts/menus.md +8 -7
- package/content/concepts/module-authoring.md +76 -5
- package/content/concepts/modules.md +3 -1
- package/content/concepts/notifications.md +180 -0
- package/content/concepts/operators.md +7 -0
- package/content/concepts/page-and-app-state.md +252 -0
- package/content/concepts/page-paths.md +209 -0
- package/content/concepts/theming.md +582 -0
- package/content/connections/aigateway.md +375 -0
- package/content/connections/anthropic.md +169 -2
- package/content/connections/awss3.md +178 -2
- package/content/connections/axioshttp.md +181 -0
- package/content/connections/google.md +169 -2
- package/content/connections/mongodb.md +1014 -3
- package/content/connections/openai-connection.md +169 -2
- package/content/connections/sendgridmail.md +3 -0
- package/content/connections/smtp.md +16 -0
- package/content/connections/treg.md +329 -0
- package/content/container-blocks/affix.md +47 -7
- package/content/container-blocks/alert.md +76 -24
- package/content/container-blocks/badge.md +100 -24
- package/content/container-blocks/box.md +9 -9
- package/content/container-blocks/card.md +132 -27
- package/content/container-blocks/carousel.md +60 -7
- package/content/container-blocks/collapse.md +153 -9
- package/content/container-blocks/configprovider.md +35 -13
- package/content/container-blocks/confirmmodal.md +69 -23
- package/content/container-blocks/content.md +62 -98
- package/content/container-blocks/descriptions.md +45 -4
- package/content/container-blocks/drawer.md +139 -28
- package/content/container-blocks/dropdownmenu.md +119 -31
- package/content/container-blocks/flex.md +40 -62
- package/content/container-blocks/footer.md +15 -11
- package/content/container-blocks/googlemapsheatmap.md +1 -1
- package/content/container-blocks/googlemapsscript.md +2 -2
- package/content/container-blocks/header.md +71 -36
- package/content/container-blocks/label.md +34 -7
- package/content/container-blocks/layout.md +52 -34
- package/content/container-blocks/masonry.md +17 -71
- package/content/container-blocks/mobilemenu.md +131 -88
- package/content/container-blocks/modal.md +161 -26
- package/content/container-blocks/pageheadermenu.md +138 -31
- package/content/container-blocks/pagesidebarlayout.md +230 -27
- package/content/container-blocks/pagesidermenu.md +153 -43
- package/content/container-blocks/popover.md +34 -31
- package/content/container-blocks/result.md +32 -21
- package/content/container-blocks/sider.md +85 -122
- package/content/container-blocks/span.md +7 -7
- package/content/container-blocks/spinner.md +3 -3
- package/content/container-blocks/splitter.md +150 -68
- package/content/container-blocks/tabs.md +64 -12
- package/content/container-blocks/tooltip.md +22 -46
- package/content/container-blocks/watermark.md +22 -4
- package/content/controls/parallel_for.md +21 -2
- package/content/controls/reject.md +26 -3
- package/content/controls/return.md +17 -1
- package/content/controls/throw.md +30 -2
- package/content/controls/try.md +24 -2
- package/content/controls/while.md +46 -0
- package/content/deployment/deployment-environments.md +146 -0
- package/content/deployment/docker.md +23 -7
- package/content/deployment/node-server.md +4 -0
- package/content/deployment/vercel.md +25 -19
- package/content/display-blocks/aggrid.md +33 -16
- package/content/display-blocks/anchor.md +16 -15
- package/content/display-blocks/avatar.md +57 -37
- package/content/display-blocks/breadcrumb.md +70 -21
- package/content/display-blocks/button.md +93 -19
- package/content/display-blocks/calendar.md +12 -0
- package/content/display-blocks/clickablehtml.md +239 -0
- package/content/display-blocks/dangeroushtml.md +1 -1
- package/content/display-blocks/difflist.md +1 -1
- package/content/display-blocks/difftimeline.md +1 -1
- package/content/display-blocks/divider.md +64 -3
- package/content/display-blocks/dropdownbutton.md +81 -30
- package/content/display-blocks/echart.md +35 -1
- package/content/display-blocks/eventlog.md +363 -0
- package/content/display-blocks/floatbutton.md +129 -42
- package/content/display-blocks/html.md +61 -1
- package/content/display-blocks/icon.md +250 -67
- package/content/display-blocks/img.md +2 -2
- package/content/display-blocks/menu.md +146 -73
- package/content/display-blocks/message.md +38 -124
- package/content/display-blocks/notification.md +94 -222
- package/content/display-blocks/paragraph.md +59 -9
- package/content/display-blocks/pollingtimer.md +263 -0
- package/content/display-blocks/progress.md +96 -17
- package/content/display-blocks/qrcode.md +19 -4
- package/content/display-blocks/s3download.md +1 -1
- package/content/display-blocks/search.md +19 -9
- package/content/display-blocks/skeletonbutton.md +1 -0
- package/content/display-blocks/skeletoninput.md +1 -0
- package/content/display-blocks/statistic.md +75 -17
- package/content/display-blocks/steps.md +58 -25
- package/content/display-blocks/table.md +2527 -0
- package/content/display-blocks/tablelight.md +621 -0
- package/content/display-blocks/tag.md +102 -17
- package/content/display-blocks/title.md +50 -11
- package/content/display-blocks/tour.md +33 -23
- package/content/input-blocks/autocomplete.md +81 -9
- package/content/input-blocks/buttonselector.md +45 -8
- package/content/input-blocks/captcha.md +40 -0
- package/content/input-blocks/checkboxselector.md +97 -7
- package/content/input-blocks/checkboxswitch.md +33 -3
- package/content/input-blocks/colorselector.md +63 -14
- package/content/input-blocks/daterangeselector.md +165 -45
- package/content/input-blocks/dateselector.md +139 -41
- package/content/input-blocks/datetimeselector.md +158 -49
- package/content/input-blocks/inputgallery.md +3 -3
- package/content/input-blocks/intentinput.md +207 -0
- package/content/input-blocks/monthselector.md +120 -52
- package/content/input-blocks/multipleselector.md +150 -39
- package/content/input-blocks/numberinput.md +98 -12
- package/content/input-blocks/pagination.md +70 -14
- package/content/input-blocks/paragraphinput.md +51 -37
- package/content/input-blocks/passwordinput.md +60 -6
- package/content/input-blocks/phonenumberinput.md +59 -26
- package/content/input-blocks/placesautocomplete.md +319 -0
- package/content/input-blocks/radioselector.md +83 -7
- package/content/input-blocks/ratingslider.md +57 -26
- package/content/input-blocks/s3uploadbutton.md +24 -24
- package/content/input-blocks/s3uploaddragger.md +3 -3
- package/content/input-blocks/s3uploadphoto.md +5 -5
- package/content/input-blocks/segmentedselector.md +72 -32
- package/content/input-blocks/selector.md +109 -21
- package/content/input-blocks/switch.md +65 -17
- package/content/input-blocks/tableinput.md +445 -0
- package/content/input-blocks/tagmultipleselector.md +114 -0
- package/content/input-blocks/tagselector.md +114 -0
- package/content/input-blocks/textarea.md +32 -3
- package/content/input-blocks/textinput.md +70 -29
- package/content/input-blocks/tiptapinput.md +1 -1
- package/content/input-blocks/tiptapmentioninput.md +2 -2
- package/content/input-blocks/titleinput.md +39 -12
- package/content/input-blocks/treeinput.md +49 -25
- package/content/input-blocks/treemultipleselector.md +127 -10
- package/content/input-blocks/treeselector.md +97 -9
- package/content/input-blocks/upload.md +64 -15
- package/content/input-blocks/uploaddragger.md +17 -1
- package/content/input-blocks/uploadphoto.md +18 -1
- package/content/input-blocks/weekselector.md +120 -55
- package/content/learn/introduction.md +27 -0
- package/content/learn/quickstart.md +53 -0
- package/content/learn/showcase.md +8 -0
- package/content/list-blocks/controlledlist.md +24 -15
- package/content/list-blocks/list.md +11 -11
- package/content/list-blocks/masonrylist.md +7 -34
- package/content/migration/auth-upgrade.md +337 -0
- package/content/migration/upgrade-guide.md +1 -0
- package/content/migration/v3-to-v4.md +417 -0
- package/content/migration/v6-to-v7.md +620 -0
- package/content/operators/_agent.md +155 -0
- package/content/operators/_app.md +2 -1
- package/content/operators/_array.md +122 -1
- package/content/operators/_build.md +1 -0
- package/content/operators/_credential.md +57 -0
- package/content/operators/_cron.md +292 -0
- package/content/operators/_date.md +2 -0
- package/content/operators/_error.md +196 -0
- package/content/operators/_get.md +6 -6
- package/content/operators/_hmac.md +78 -0
- package/content/operators/_js.md +2 -1
- package/content/operators/_location.md +1 -1
- package/content/operators/_media.md +13 -0
- package/content/operators/_module.md +56 -2
- package/content/operators/_operator.md +17 -3
- package/content/operators/_path_params.md +82 -0
- package/content/operators/_ref.md +258 -0
- package/content/operators/_request.md +1 -1
- package/content/operators/_request_details.md +6 -0
- package/content/operators/_type.md +14 -3
- package/content/operators/_url_query.md +2 -0
- package/content/operators/_user.md +3 -3
- package/content/plugins/plugins-actions.md +10 -0
- package/content/plugins/plugins-connections.md +25 -0
- package/content/plugins/plugins-dev.md +66 -0
- package/content/plugins/plugins-icon-sets.md +267 -0
- package/content/plugins/plugins-introduction.md +27 -1
- package/content/plugins/plugins.md +19 -0
- package/content/plugins/posthog.md +359 -0
- package/content/provider-reference/auth-js-providers.md +107 -0
- package/content/provider-reference/openidconnectprovider.md +44 -0
- package/content/recipes/recipes.md +16 -0
- package/content/reference/actions-reference.md +31 -0
- package/content/reference/blocks-reference.md +35 -0
- package/content/reference/cli.md +403 -0
- package/content/reference/connections-reference.md +23 -0
- package/content/reference/operators-reference.md +47 -0
- package/content/reference/reference.md +16 -0
- package/content/reference/schema-reference.md +12 -0
- package/content/testing/config-tests.md +677 -0
- package/content/testing/e2e-configuration.md +31 -1
- package/content/testing/e2e-getting-started.md +1 -1
- package/content/testing/e2e-introduction.md +1 -1
- package/content/testing/e2e-writing-tests.md +12 -1
- package/content/testing/explore-pull-request.md +136 -0
- package/content/testing/journey-data-sets.md +326 -0
- package/content/tutorial/tutorial-actions-operators.md +2 -2
- package/content/tutorial/tutorial-add-blocks.md +2 -2
- package/content/tutorial/tutorial-create-page.md +48 -2
- package/content/tutorial/tutorial-display-data-page.md +3 -3
- package/content/tutorial/tutorial-requests-api.md +155 -0
- package/content/tutorial/tutorial-requests-sql.md +153 -0
- package/content/tutorial/tutorial-start.md +66 -1
- package/content/user-authentication/auth-configuration.md +267 -0
- package/content/user-authentication/auth-providers.md +24 -0
- package/content/user-authentication/auth-steps.md +141 -0
- package/content/user-authentication/login-and-logout.md +160 -8
- package/content/user-authentication/mcp-oauth.md +424 -0
- package/content/user-authentication/organizations.md +246 -0
- package/content/user-authentication/protected-pages-apis.md +97 -0
- package/content/user-authentication/roles.md +49 -0
- package/content/user-authentication/two-factor.md +229 -0
- package/content/user-authentication/user-object.md +58 -0
- package/content/user-authentication/users-introduction.md +8 -0
- package/content/websockets/websocket-publish.md +105 -0
- package/content/websockets/websocket-subscriptions.md +136 -0
- package/content/websockets/websockets-introduction.md +101 -0
- package/hazards.json +56 -0
- package/index.json +3472 -14
- package/package.json +10 -1
- package/scripts/extractAgentDocs.js +41 -30
- package/scripts/hashDocSources.js +38 -0
- package/scripts/isRedirectPage.js +26 -0
- package/scripts/recordSourceHashes.js +97 -0
- package/scripts/resolvePageSections.js +42 -0
- package/scripts/sectionKind.js +27 -0
- package/content/concepts/cli.md +0 -223
- package/content/other/introduction.md +0 -39
- package/content/other/next-auth-providers.md +0 -3
- /package/content/{other → actions}/updatesession.md +0 -0
|
@@ -15,6 +15,7 @@ The root schema for a Lowdefy app is:
|
|
|
15
15
|
- `config: object`: An object with app configuration like the home page pageId.
|
|
16
16
|
- `auth: object` An object with authentication and authorization configuration.
|
|
17
17
|
- `global: object`: A data object that can be accessed anywhere in the app using the [`_global`](/_global) operator.
|
|
18
|
+
- `events: object`: App events, `onInit` and `onInitAsync`, that run once each time the app loads in the browser. See [App events](/events-and-actions#app-events).
|
|
18
19
|
- `connections: object[]`: An array of [`connection`](/connections-and-requests) objects.
|
|
19
20
|
- `plugins: object[]`: An array of `plugin` objects to customize and add block types.
|
|
20
21
|
- `modules: object[]`: An array of module entries. Each module references a reusable configuration package distributed via GitHub or local file paths. See [Modules](/modules) for details.
|
|
@@ -41,10 +42,94 @@ Find the more detailed block schema [here](/blocks).
|
|
|
41
42
|
|
|
42
43
|
The config object has the following properties:
|
|
43
44
|
|
|
44
|
-
- `
|
|
45
|
+
- `environments: object`: The deployment environments of the app, keyed by name (for example `prod`, `staging`, `local`). Each build is for one of them, named by the `LOWDEFY_ENVIRONMENT` environment variable, and the current environment supplies the defaults for everything environment-specific. See [Deployment environments](/deployment-environments). Each environment has:
|
|
46
|
+
- `url: string`: The deployment origin, for example `https://staging.example.com`. Default for the auth canonical URL (`BETTER_AUTH_URL`) and the MCP resource URIs, notification links and logos (`RenderNotification` `serverUrl`), and where crons are forwarded to.
|
|
47
|
+
- `cron.secret: string`: The **name** of the Lowdefy secret holding this environment's `CRON_SECRET` — a plain string, not a `_secret` operator (environment settings are resolved at build time, where `_secret` is not evaluated). The value is read at runtime from `LOWDEFY_SECRET_<name>` on the deployment that forwards. An environment with a `cron.secret` has its schedules forwarded to it from the environment Vercel fires crons on.
|
|
48
|
+
- `cron.enabled: boolean`: Set `false` to register no cron jobs for this environment. Defaults to `true`.
|
|
49
|
+
- `email.filter: object`: The delivery filter (`replaceAddress`, `allowlist`, `regex`) applied to every `SMTPMailSend` and `SendGridMailSend` request in this environment, unless the connection sets its own `filter` (`filter: false` on a connection turns filtering off).
|
|
50
|
+
- `email.enabled: boolean`: Set `false` to send no email from `SMTPMailSend` and `SendGridMailSend` requests in this environment (auth emails still send). Defaults to `true`.
|
|
51
|
+
- `sentry.enabled: boolean`: Set `false` to turn Sentry off, server and client, in this environment. Defaults to `true`.
|
|
52
|
+
- `guards: object`: Pin secrets and environment variables to a pattern kept in config. `guards.secrets` maps a Lowdefy secret name (`LOWDEFY_SECRET_<name>`) and `guards.env` an environment variable name to a regular expression; in this environment the build fails unless each value matches (a missing value fails too), so changing a guarded value also takes a config change. See [Guards](/deployment-environments).
|
|
53
|
+
- `posthog.enabled: boolean`: Set `false` to turn PostHog off in this environment: `PostHogInit` behaves as `enabled: false` (no key needed) and every PostHog action is a no-op. Defaults to `true`.
|
|
54
|
+
- `environment: string`: The name of the environment this build is for, used when the `LOWDEFY_ENVIRONMENT` environment variable is not set; the variable always wins. When `environments` is declared it must be one of its names. Server log lines carry it as `environment`, `_app: environment` reads it, and Sentry reports under it unless `logger.sentry.environment` is set.
|
|
45
55
|
- `basePath: string`: Set the base path to serve the Lowdefy application from. This will route all pages under `https://example.com/<base-path>/<page-id>` instead of the default `https://example.com/<page-id>`. The basePath value must start with "/".
|
|
46
|
-
- `homePageId: string`: The id of the page that will load when a visitor navigates to the home route, in other words, when the visitor navigates to `yourdomain.com` or `yourdomain.com/`.
|
|
56
|
+
- `homePageId: string`: The id of the page that will load when a visitor navigates to the home route, in other words, when the visitor navigates to `yourdomain.com` or `yourdomain.com/`. The home page cannot have placeholders in its [`path`](/page-paths).
|
|
57
|
+
- `dependencyTracking: boolean`: Defaults to `true`. The browser re-evaluates only the blocks whose inputs changed (the state paths, requests and globals their operators read) instead of every block on the page after each change. Set to `false` to evaluate every block on every update, as earlier versions did.
|
|
47
58
|
- `requestTimeout: number`: Maximum time in milliseconds a request may run before the server returns a timeout. This protects against requests that hang on an upstream call (database, SMTP, an external API) running all the way to the host's function limit — important on serverless platforms that bill by execution duration. Defaults to `30000` (30 seconds). Set to `0` to disable. Agent streaming routes are exempt, since they are long-lived by design.
|
|
59
|
+
- `security: object`: Opt-in browser security settings. See [Security](#security) below.
|
|
60
|
+
- `contentSecurityPolicy: boolean | object`: Send a Content-Security-Policy header with app pages. Set `true` for the default policy, or an object with:
|
|
61
|
+
- `reportOnly: boolean`: Send the policy as `Content-Security-Policy-Report-Only`, so the browser reports what it would block without blocking it. Defaults to `false`.
|
|
62
|
+
- `directives: object`: Sources to add to the default policy, keyed by directive name, for example `script-src: ['https://www.googletagmanager.com']`.
|
|
63
|
+
- `trustedProxies: string[]`: IP addresses and CIDR ranges (for example `10.0.0.0/8`) of the reverse proxies and load balancers in front of a self-hosted server. The server takes each request's client address from its connection, and reads `X-Forwarded-For` only when that connection comes from a trusted proxy, skipping trusted hops from the right. Auth rate limits, sessions and request logs use this address. Defaults to none, so a client cannot choose its own address. Not used on Vercel, where the platform supplies the client address. See [Behind a reverse proxy](/docker#behind-a-reverse-proxy).
|
|
64
|
+
|
|
65
|
+
## Security
|
|
66
|
+
|
|
67
|
+
### Content Security Policy
|
|
68
|
+
|
|
69
|
+
A [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) tells the browser which scripts, styles, images and connections a page may use. It is off by default. Turn it on with `config.security.contentSecurityPolicy`:
|
|
70
|
+
|
|
71
|
+
```yaml
|
|
72
|
+
config:
|
|
73
|
+
security:
|
|
74
|
+
contentSecurityPolicy: true
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
The server then sends this policy with every page:
|
|
78
|
+
|
|
79
|
+
| Directive | Sources |
|
|
80
|
+
| --------- | ------- |
|
|
81
|
+
| `default-src` | `'self'` |
|
|
82
|
+
| `script-src` | `'self'` and a nonce |
|
|
83
|
+
| `style-src` | `'self' 'unsafe-inline'` |
|
|
84
|
+
| `img-src` | `'self' data: blob:` |
|
|
85
|
+
| `font-src` | `'self' data:` |
|
|
86
|
+
| `connect-src` | `'self' https://api.lowdefy.net`, and the page's own websocket origin when the app has websockets |
|
|
87
|
+
| `object-src` | `'none'` |
|
|
88
|
+
| `base-uri` | `'self'` |
|
|
89
|
+
| `frame-ancestors` | `'self'` |
|
|
90
|
+
|
|
91
|
+
Each page render draws a new random nonce. Lowdefy's own inline scripts, and every `<script>` and `<style>` element in [`app.html.appendHead` and `app.html.appendBody`](/custom-html), carry it, so they keep running. Inline scripts added to the page any other way, and inline event handler attributes such as `onclick` in appended HTML, are blocked. Styles allow `'unsafe-inline'`, because some antd components add style elements and style attributes that cannot carry a nonce (the scroll lock of a modal or drawer, text area auto size, watermarks). `connect-src` lists `https://api.lowdefy.net`, where the browser sends Lowdefy usage data.
|
|
92
|
+
|
|
93
|
+
#### Report only first
|
|
94
|
+
|
|
95
|
+
Turning the policy on can block something an app relies on, such as an analytics script or images from another host. Send it report-only first: the browser logs each violation to the console, and blocks nothing.
|
|
96
|
+
|
|
97
|
+
```yaml
|
|
98
|
+
config:
|
|
99
|
+
security:
|
|
100
|
+
contentSecurityPolicy:
|
|
101
|
+
reportOnly: true
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Open the app's pages, look for `Content Security Policy` messages in the browser console, add the sources they name, and remove `reportOnly` once the console is clean.
|
|
105
|
+
|
|
106
|
+
#### Adding sources
|
|
107
|
+
|
|
108
|
+
`directives` adds sources to the default policy. Each key is a directive name and each value is a list of sources; sources are added to the defaults, never replace them, and a directive the defaults do not set is added. A source is written as the browser expects it, so keywords keep their single quotes.
|
|
109
|
+
|
|
110
|
+
```yaml
|
|
111
|
+
config:
|
|
112
|
+
security:
|
|
113
|
+
contentSecurityPolicy:
|
|
114
|
+
directives:
|
|
115
|
+
script-src:
|
|
116
|
+
- https://www.googletagmanager.com
|
|
117
|
+
connect-src:
|
|
118
|
+
- https://www.google-analytics.com
|
|
119
|
+
img-src:
|
|
120
|
+
- https://images.example.com
|
|
121
|
+
frame-src:
|
|
122
|
+
- https://www.youtube.com
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Some features need an extra source:
|
|
126
|
+
|
|
127
|
+
- Templates rendered in the browser with nunjucks (the `_nunjucks` operator, and `html` templates in selector options and table cells) compile to JavaScript, and need `"'unsafe-eval'"` in `script-src`. Blocks that can render these templates load nunjucks with the page, which logs an `eval` violation even when no template is used.
|
|
128
|
+
- Images, fonts, frames and API calls on other hosts need those hosts in `img-src`, `font-src`, `frame-src` and `connect-src`.
|
|
129
|
+
|
|
130
|
+
Adding `'unsafe-inline'` to `script-src` leaves the nonce off that directive, since browsers ignore `'unsafe-inline'` when a nonce is present.
|
|
131
|
+
|
|
132
|
+
The policy applies to `lowdefy dev` too, so problems show while developing.
|
|
48
133
|
|
|
49
134
|
## Auth
|
|
50
135
|
|
|
@@ -69,6 +154,8 @@ See more about how user authentication and authorization [here](/users-introduct
|
|
|
69
154
|
|
|
70
155
|
In a Lowdefy app, you can define global variables in the __global__ object, which can be accessed using the [`_global`](/_global) operator, and modified using the [`SetGlobal`](/SetGlobal) action. This is a good place to store data or configuration that is used over various pages throughout the app, for example, user preferences that can be modified using `SetGlobal` on one page and easily referenced on all others.
|
|
71
156
|
|
|
157
|
+
The app [`events`](/events-and-actions#app-events) `onInit` and `onInitAsync` run once each time the app loads, before the first page's own events, and are a good place to set global values, for example user settings fetched with a [`CallAPI`](/CallAPI) action.
|
|
158
|
+
|
|
72
159
|
## Connections
|
|
73
160
|
|
|
74
161
|
In a Lowdefy app you can integrate with other services like API's or databases using `connections` and `requests`. Use connections to configure the settings to a service, for example, settings such as urls or [`secrets`](/secrets) like passwords or API keys. Requests use connections to interact with external services, for example, inserting a data record or executing a query on a database, or simply calling an API end-point.
|
|
@@ -107,6 +194,8 @@ Pages in a Lowdefy app are actually just blocks, the building blocks of a Lowdef
|
|
|
107
194
|
|
|
108
195
|
Each page should have an `id` that is unique among all pages in the app. Each page is served with the `pageId` as the url route. That is, if a page is created with id `page1`, it will be served at `domain.com/page1`. Module pages use the path `/{entryId}/{pageId}` — for example, a page `users-list` in a module entry `team-users` is served at `domain.com/team-users/users-list`.
|
|
109
196
|
|
|
197
|
+
A page can set `path` to be served at an address other than its id, with placeholders for values such as a record id: a page with `path: tickets/{space}/{ticket_id}` is served at `domain.com/tickets/support/1234`, and reads `support` and `1234` with the [`_path_params`](/_path_params) operator. A path that starts with a placeholder must be quoted, like `path: '{space}/tickets/{ticket_id}'`. The page's `id` stays its identity in auth config, menus and links. See [Page paths](/page-paths).
|
|
198
|
+
|
|
110
199
|
If `properties.title` is set on a page block, the title will be set as the page title (This is the title displayed on the tabs in your browser).
|
|
111
200
|
|
|
112
201
|
Let's have a look at how to define a page and it's blocks. We can start with a simple page a card block on it. We can add a title to our card, by making use of the card block's title property. We can also add a paragraph block to our card so that it won't be so empty.
|
|
@@ -286,6 +375,12 @@ The `~ignoreBuildChecks` property suppresses build-time validation errors and wa
|
|
|
286
375
|
|
|
287
376
|
### Available Check Slugs
|
|
288
377
|
|
|
378
|
+
Every build error or warning from a check that the build prints shows its slug after the error name, so the slug to silence is on screen:
|
|
379
|
+
|
|
380
|
+
```
|
|
381
|
+
[ConfigWarning · state-refs] _state references "dynamicState" but no block with id "dynamicState" exists
|
|
382
|
+
```
|
|
383
|
+
|
|
289
384
|
| Slug | What it suppresses |
|
|
290
385
|
|------|-------------------|
|
|
291
386
|
| `state-refs` | Undefined `_state` reference warnings |
|
|
@@ -294,8 +389,54 @@ The `~ignoreBuildChecks` property suppresses build-time validation errors and wa
|
|
|
294
389
|
| `link-refs` | Invalid Link action page reference warnings |
|
|
295
390
|
| `request-refs` | Invalid Request action reference warnings |
|
|
296
391
|
| `connection-refs` | Nonexistent connection ID references |
|
|
392
|
+
| `callapi-refs` | Invalid CallAPI action endpoint reference warnings |
|
|
393
|
+
| `callapi-internal-refs` | CallAPI actions targeting InternalApi endpoints |
|
|
394
|
+
| `dynamic-endpoint-refs` | Invalid Dynamic block endpoint reference warnings |
|
|
395
|
+
| `websocket-refs` | Invalid websocket action reference warnings |
|
|
396
|
+
| `callmethod-refs` | CallMethod actions targeting blocks not defined on the page |
|
|
397
|
+
| `icons` | Unresolvable icon name warnings |
|
|
297
398
|
| `types` | All type validation (blocks, operators, actions, requests, connections) |
|
|
298
399
|
| `schema` | JSON schema validation errors |
|
|
400
|
+
| `secrets` | Environment variable names that are not set in the build environment |
|
|
401
|
+
| `plugin-checks` | Every plugin build check rule, and the plugin schema check |
|
|
402
|
+
| `plugin-schema` | Block properties, action params and operator params that break their plugin schema |
|
|
403
|
+
|
|
404
|
+
### Plugin Schema Checks
|
|
405
|
+
|
|
406
|
+
The build also checks each block's `properties`, each action's `params` and each operator's params against the schema the plugin ships for that type, after `_ref` and `_build` operators resolve. Config that breaks a schema gives a warning with the type, the field and its file and line:
|
|
407
|
+
|
|
408
|
+
```
|
|
409
|
+
[ConfigWarning · plugin-schema] Block "Button" property "colr" is not allowed.
|
|
410
|
+
[ConfigWarning · plugin-schema] Operator "_if" required param "test" is missing.
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
A value an operator gives at runtime is not checked, since the build cannot know it: `columns: { _state: columns }` passes where the schema wants an array. Keys still are, so a missing `test` or a misspelt key reports even when its neighbours are operators. Connections and requests are checked by the server on every call, not by the build.
|
|
414
|
+
|
|
415
|
+
Schema findings are warnings, unless the plugin makes them errors. List `plugin-schema` in `~ignoreBuildChecks` to silence them on a node and its descendants; `plugin-checks` and `--skip-plugin-checks` cover them too.
|
|
416
|
+
|
|
417
|
+
### Plugin Check Rules
|
|
418
|
+
|
|
419
|
+
Plugins can ship build check rules for their operators, blocks, actions, requests and connections. A plugin rule's id is its slug: list it in `~ignoreBuildChecks` to silence that one rule, or list `plugin-checks` to silence every plugin rule. `true` silences plugin rules too.
|
|
420
|
+
|
|
421
|
+
A plugin's rules run once the plugin is installed. When a build uses a plugin that is not installed yet, `lowdefy build` and `lowdefy dev` install it and build again, so its rules run on a fresh checkout too. To skip every plugin rule for one run, pass `--skip-plugin-checks` to `lowdefy build`, `lowdefy dev` or `lowdefy journeys scope`.
|
|
422
|
+
|
|
423
|
+
```yaml
|
|
424
|
+
# Silence one plugin rule on this block and its descendants
|
|
425
|
+
~ignoreBuildChecks:
|
|
426
|
+
- if-test
|
|
427
|
+
|
|
428
|
+
# Silence every plugin rule on this block and its descendants
|
|
429
|
+
~ignoreBuildChecks:
|
|
430
|
+
- plugin-checks
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
Check slugs are kebab-case: lowercase letters and digits joined by single dashes.
|
|
434
|
+
|
|
435
|
+
The `@lowdefy/operators-js` plugin ships these rules:
|
|
436
|
+
|
|
437
|
+
| Slug | Level | What it checks |
|
|
438
|
+
|------|-------|----------------|
|
|
439
|
+
| `if-test` | error | An `_if` needs its condition under `test`. `_if: { _eq: [1, 1], then: a, else: b }` fails the build; write `_if: { test: { _eq: [1, 1] }, then: a, else: b }`. Params that are one operator, such as `_if: { _state: ifParams }`, pass. |
|
|
299
440
|
|
|
300
441
|
### Example: Dynamic State
|
|
301
442
|
|
|
@@ -314,7 +455,7 @@ blocks:
|
|
|
314
455
|
|
|
315
456
|
Without `~ignoreBuildChecks`, the build would warn:
|
|
316
457
|
```
|
|
317
|
-
[
|
|
458
|
+
[ConfigWarning · state-refs] _state references "dynamicState" but no block with id "dynamicState" exists
|
|
318
459
|
```
|
|
319
460
|
|
|
320
461
|
### Example: Page-Level Suppression
|
|
@@ -19,12 +19,13 @@ The schema for a `MenuLink` is:
|
|
|
19
19
|
- `id: string`: __Required__ - A identifier for the link unique to the menu.
|
|
20
20
|
- `type: string`: __Required__ - The type should be `MenuLink`.
|
|
21
21
|
- `pageId: string`: The id of the page to link to. Used as the menu item title if no title is provided.
|
|
22
|
+
- `pathParams: object`: Values for the placeholders in the linked page's [`path`](/page-paths), by placeholder name. The values must be strings written in the config, since menus are built once for the app, and the build fails when a placeholder has no value. A menu link to a page with a path is highlighted on every instance of the page, whatever its values.
|
|
22
23
|
- `url: string`: An external url to link to.
|
|
23
24
|
- `class: string | array | object`: CSS classes (including Tailwind utilities) for the item. Flat applies to the item wrapper; use an object with dot-prefixed slot keys (`.element`, `.icon`, `.label`) to target specific parts.
|
|
24
25
|
- `style: object`: CSS styles for the item. Flat applies to the wrapper; use dot-prefixed slot keys (`.element`, `.icon`, `.label`) to target specific parts.
|
|
25
26
|
- `properties: object`: The properties of the menu link. These are:
|
|
26
27
|
- `title: string`: The title to display for the link.
|
|
27
|
-
- `icon: string | object`:
|
|
28
|
+
- `icon: string | object`: An icon name, such as the semantic name `home` or the [Lucide](https://lucide.dev/icons) name `House`, or properties of an [Icon](/Icon) block to use as the icon for the link.
|
|
28
29
|
- `danger: boolean`: Apply danger style (switches the item onto antd's `dangerItem*` token set).
|
|
29
30
|
- `disabled: boolean`: Disable the item — blocks clicks and applies a greyed style.
|
|
30
31
|
- `tooltip: string`: Tooltip text shown when the menu is collapsed.
|
|
@@ -38,7 +39,7 @@ The schema for a `MenuGroup` is:
|
|
|
38
39
|
- `style: object`: CSS styles for the group's title row. Use dot-prefixed slot keys to target specific parts.
|
|
39
40
|
- `properties: object`: The properties of the menu group. These are:
|
|
40
41
|
- `title: string`: The title to display for the group.
|
|
41
|
-
- `icon: string | object`:
|
|
42
|
+
- `icon: string | object`: An icon name, such as the semantic name `home` or the [Lucide](https://lucide.dev/icons) name `House`, or properties of an [Icon](/Icon) block to use as the icon for the group.
|
|
42
43
|
- `disabled: boolean`: Disable the group — blocks expansion and applies a greyed style.
|
|
43
44
|
- `tooltip: string`: Tooltip text shown when the menu is collapsed.
|
|
44
45
|
- `links: object[]`: An array of `MenuLink` or `MenuGroup` objects that should be grouped together in the group.
|
|
@@ -62,11 +63,11 @@ menus:
|
|
|
62
63
|
pageId: page1
|
|
63
64
|
properties:
|
|
64
65
|
title: Page 1
|
|
65
|
-
icon:
|
|
66
|
+
icon: file
|
|
66
67
|
- id: top-group
|
|
67
68
|
properties:
|
|
68
69
|
title: Group
|
|
69
|
-
icon:
|
|
70
|
+
icon: Group
|
|
70
71
|
links:
|
|
71
72
|
- id: page2
|
|
72
73
|
type: MenuLink
|
|
@@ -93,13 +94,13 @@ menus:
|
|
|
93
94
|
pageId: page1
|
|
94
95
|
properties:
|
|
95
96
|
title: Page 1
|
|
96
|
-
icon:
|
|
97
|
+
icon: file
|
|
97
98
|
- id: page3
|
|
98
99
|
type: MenuLink
|
|
99
100
|
pageId: page3
|
|
100
101
|
properties:
|
|
101
102
|
title: Page 3
|
|
102
|
-
icon:
|
|
103
|
+
icon: SlidersHorizontal
|
|
103
104
|
```
|
|
104
105
|
|
|
105
106
|
We can make use of [protected pages and APIs](/protected-pages-apis) and [roles](/roles) to filter the menu items according to the pages that the user has access to.
|
|
@@ -130,7 +131,7 @@ menus:
|
|
|
130
131
|
pageId: page1
|
|
131
132
|
properties:
|
|
132
133
|
title: Page 1
|
|
133
|
-
icon:
|
|
134
|
+
icon: file
|
|
134
135
|
- id: page2
|
|
135
136
|
type: MenuLink
|
|
136
137
|
pageId: page2 # pageId will be used as link title
|
|
@@ -69,7 +69,7 @@ The build prevents `../` from escaping the package root — the git repo root fo
|
|
|
69
69
|
|
|
70
70
|
## How Modules Stay Scoped and Composable
|
|
71
71
|
|
|
72
|
-
Three mechanisms keep modules working at scale. **Auto-scoping** prefixes every page, connection, API endpoint, notification, and menu item ID with the entry's `id`, so module authors write plain IDs and installing the same module twice under different entry IDs produces no collisions. **`_module.var`** lets any file in the module read the entry's vars at any depth, without the app threading values through nested `_ref`s. **Typed exports** declared in `exports:` mark which pages, components, endpoints, connections, and menus are public, so internal files stay internal and renaming one does not break consumers.
|
|
72
|
+
Three mechanisms keep modules working at scale. **Auto-scoping** prefixes every page, connection, API endpoint, notification, websocket, and menu item ID with the entry's `id`, so module authors write plain IDs and installing the same module twice under different entry IDs produces no collisions. **`_module.var`** lets any file in the module read the entry's vars at any depth, without the app threading values through nested `_ref`s. **Typed exports** declared in `exports:` mark which pages, components, endpoints, connections, and menus are public, so internal files stay internal and renaming one does not break consumers.
|
|
73
73
|
|
|
74
74
|
## Writing module.lowdefy.yaml
|
|
75
75
|
|
|
@@ -109,6 +109,9 @@ api:
|
|
|
109
109
|
notifications:
|
|
110
110
|
- _ref: notifications/invite-user.yaml
|
|
111
111
|
|
|
112
|
+
websockets:
|
|
113
|
+
- _ref: websockets/user-changes.yaml
|
|
114
|
+
|
|
112
115
|
components:
|
|
113
116
|
- id: user-avatar
|
|
114
117
|
component:
|
|
@@ -143,7 +146,7 @@ The `vars` section declares what configuration the module accepts. Each variable
|
|
|
143
146
|
- `description` — Documentation for the variable's purpose.
|
|
144
147
|
- `properties` — For `object` vars, declares nested keys with their own type, default, required, and description. Consumer values are merged at the property level — only overridden keys change.
|
|
145
148
|
|
|
146
|
-
Defaults are expressions. They can be literals, or operator trees — `_ref`, `_module.var`, `_build.*`, or any combination. The build resolves a default lazily, only when `_module.var` reads the var and the consumer did not provide a value. Vars with `properties` merge at the property level: the consumer overrides only the keys they provide, and the rest resolve their own defaults independently.
|
|
149
|
+
Defaults are expressions. They can be literals, or operator trees — `_ref`, `_module.var`, `_build.*`, or any combination. The build resolves a default lazily, only when `_module.var` reads the var and the consumer did not provide a value. Vars with `properties` merge at the property level: the consumer overrides only the keys they provide, and the rest resolve their own defaults independently. A property with no consumer value and no default is left out of the object, not set to `null`.
|
|
147
150
|
|
|
148
151
|
Unused vars are never read, so their defaults never resolve and their declared `type` is never checked.
|
|
149
152
|
|
|
@@ -236,7 +239,7 @@ show_filter:
|
|
|
236
239
|
|
|
237
240
|
## Using ID Operators
|
|
238
241
|
|
|
239
|
-
Module authors use [`_module.pageId`](/_module), [`_module.connectionId`](/_module), [`_module.endpointId`](/_module), and [`_module.
|
|
242
|
+
Module authors use [`_module.pageId`](/_module), [`_module.connectionId`](/_module), [`_module.endpointId`](/_module), [`_module.notificationId`](/_module), and [`_module.websocketId`](/_module) to reference sibling resources. These resolve to the fully scoped ID at build time:
|
|
240
243
|
|
|
241
244
|
```yaml
|
|
242
245
|
# Link to a sibling page
|
|
@@ -267,6 +270,74 @@ label:
|
|
|
267
270
|
- " - User Admin"
|
|
268
271
|
```
|
|
269
272
|
|
|
273
|
+
## Endpoint Access
|
|
274
|
+
|
|
275
|
+
In an app with auth configured, an API endpoint a module ships needs a signed-in caller unless the module or the app makes it public. The module lists the endpoints anyone may call, such as a sign-up or status check, under `auth.api.public` in its manifest:
|
|
276
|
+
|
|
277
|
+
```yaml
|
|
278
|
+
# module.lowdefy.yaml
|
|
279
|
+
auth:
|
|
280
|
+
api:
|
|
281
|
+
public:
|
|
282
|
+
- ticket-status
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
The app makes a module endpoint public with `auth.api.public: true`, or by naming it in an `auth.api.public` list. Otherwise it stays protected, also with no `auth.api` rule or under a `protected` list that does not name it, where an app endpoint would be public. This holds for `InternalApi` endpoints and for calls made from a routine too: a public app endpoint, or a webhook without a `verify` gate, that calls a module endpoint with `CallApi` is refused when the caller is signed out. A role in `auth.api.roles` restricts a module endpoint whether it is public or not. A webhook endpoint must still be listed in the app's `auth.api.public`. In an app without auth, module endpoints follow the app's rules like any other.
|
|
286
|
+
|
|
287
|
+
## Agent Access
|
|
288
|
+
|
|
289
|
+
Agents a module ships in `agents:` are served from the API surface, so the app's `auth.api` rules match their scoped ids, as they do for endpoints. In an app with auth configured, a module agent needs a signed-in caller unless the module or the app makes it public. A signed-out caller who runs an agent spends model calls and runs its tools, so a module lists the agents anyone may use under `auth.agents.public` in its manifest:
|
|
290
|
+
|
|
291
|
+
```yaml
|
|
292
|
+
# module.lowdefy.yaml
|
|
293
|
+
auth:
|
|
294
|
+
agents:
|
|
295
|
+
public:
|
|
296
|
+
- concierge
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
The app makes a module agent public with `auth.api.public: true`, or by naming it in an `auth.api.public` list. Otherwise it stays protected, also with no `auth.api` rule or under a `protected` list that does not name it, where an app agent would be public. A role in `auth.api.roles` restricts a module agent whether it is public or not. In an app without auth, module agents follow the app's rules like any other.
|
|
300
|
+
|
|
301
|
+
A public agent does not open its tools: each tool endpoint keeps its own access, so a module endpoint the agent calls as a tool is refused when the caller is signed out unless the endpoint is public too. List the tools a public agent needs under `auth.api.public` as well, and a sub-agent it hands work to under `auth.agents.public`.
|
|
302
|
+
|
|
303
|
+
## Shipping Websockets
|
|
304
|
+
|
|
305
|
+
A module declares the websockets its pages subscribe to in `websockets:`, so an app that installs the module needs no websocket config of its own. Each item takes the same fields as an app's top-level [`websockets`](/websockets-introduction) (`id`, `type`, `connectionId`, `properties`, `tenant`). Write `connectionId` with `_module.connectionId`, so a connection the app remaps resolves to the app's connection:
|
|
306
|
+
|
|
307
|
+
```yaml
|
|
308
|
+
# websockets/user-changes.yaml
|
|
309
|
+
id: user-changes
|
|
310
|
+
type: MongoDBChangeStream
|
|
311
|
+
connectionId:
|
|
312
|
+
_module.connectionId: users-db
|
|
313
|
+
properties:
|
|
314
|
+
pipeline:
|
|
315
|
+
- $match:
|
|
316
|
+
operationType: update
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
Module pages subscribe with `_module.websocketId`:
|
|
320
|
+
|
|
321
|
+
```yaml
|
|
322
|
+
subscriptions:
|
|
323
|
+
- websocketId:
|
|
324
|
+
_module.websocketId: user-changes
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
The id is scoped like every other module id: in an entry with `id: user-admin` it is `user-admin/user-changes`. The app's `auth.websockets` rules match the scoped id, so `user-admin/**` under `auth.websockets.roles` restricts every websocket the entry ships. A `_secret` in a websocket's properties must be declared in the manifest's `secrets`, as for connections.
|
|
328
|
+
|
|
329
|
+
In an app with auth configured, a module websocket needs a signed-in caller unless the module or the app makes it public. The module lists the websockets anyone may subscribe to under `auth.websockets.public` in its manifest:
|
|
330
|
+
|
|
331
|
+
```yaml
|
|
332
|
+
# module.lowdefy.yaml
|
|
333
|
+
auth:
|
|
334
|
+
websockets:
|
|
335
|
+
public:
|
|
336
|
+
- status-feed
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
The app makes a module websocket public with `auth.websockets.public: true`, or by naming it in an `auth.websockets.public` list. Otherwise it stays protected, also with no `auth.websockets` rule or under a `protected` list that does not name it, where an app websocket would be public. A role in `auth.websockets.roles` restricts a module websocket whether it is public or not. In an app without auth, module websockets follow the app's rules like any other.
|
|
340
|
+
|
|
270
341
|
## Exposing Components
|
|
271
342
|
|
|
272
343
|
Components are reusable config fragments that consuming apps can `_ref` into any page. Declare them in the manifest:
|
|
@@ -416,14 +487,14 @@ links:
|
|
|
416
487
|
_module.pageId: users-list
|
|
417
488
|
properties:
|
|
418
489
|
title: Users
|
|
419
|
-
icon:
|
|
490
|
+
icon: user
|
|
420
491
|
- id: invite
|
|
421
492
|
type: MenuLink
|
|
422
493
|
pageId:
|
|
423
494
|
_module.pageId: user-invite
|
|
424
495
|
properties:
|
|
425
496
|
title: Invite User
|
|
426
|
-
icon:
|
|
497
|
+
icon: UserPlus
|
|
427
498
|
```
|
|
428
499
|
|
|
429
500
|
The app wraps these in a MenuGroup:
|
|
@@ -237,7 +237,9 @@ Local paths resolve relative to the project root. Useful for development and tes
|
|
|
237
237
|
source: "file:../my-module"
|
|
238
238
|
```
|
|
239
239
|
|
|
240
|
-
For private GitHub repositories, set the `GITHUB_TOKEN` environment variable.
|
|
240
|
+
For private GitHub repositories, set the `GITHUB_TOKEN` environment variable. Without it, the build uses the token of the `gh` CLI when one is signed in.
|
|
241
|
+
|
|
242
|
+
A private repository can also be read with an SSH key, such as a read-only deploy key: set the `GITHUB_SSH_KEY` environment variable to the private key. When the GitHub API cannot find a repository or refuses the token, the build fetches it with `git` over SSH using that key. Public repositories are still downloaded through the API, since a deploy key can only read the repository it belongs to. Over SSH, `ref` must be a tag, a branch or a full 40-character commit SHA, and the build machine needs `git` and `ssh` installed.
|
|
241
243
|
|
|
242
244
|
## Plugin Dependency Validation
|
|
243
245
|
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# Notifications
|
|
2
|
+
|
|
3
|
+
Lowdefy can render branded notification emails from config. You define a notification's content once in a `notifications:` section — as a template with interpolated properties — and render it from an API routine with the `RenderNotification` step. Rendering is all the framework does: **storing a notification, deduplicating, sending the email, and tracking delivery are composed in your API routines**, either by hand or with a notifications module.
|
|
4
|
+
|
|
5
|
+
This split is deliberate. Rendering an email safely (turning template properties and data into HTML, with a guarantee that user data can never inject links or markup) and composing link URLs are the two things config alone cannot do, so they live in the framework. Everything else — inserting a record, sending, retrying — is ordinary [requests](/connections-and-requests) and [API routines](/lowdefy-api), which you already have. A consequence worth knowing: because storing is just a request and sending is just a request, notifications work with any database and any email provider Lowdefy connects to.
|
|
6
|
+
|
|
7
|
+
## The `notifications:` section
|
|
8
|
+
|
|
9
|
+
`notifications:` is a root section. Each entry is `{ id, type, properties }`, where **the template is the type**:
|
|
10
|
+
|
|
11
|
+
```yaml
|
|
12
|
+
notifications:
|
|
13
|
+
- id: task-assigned
|
|
14
|
+
type: NotificationEmail
|
|
15
|
+
properties:
|
|
16
|
+
subject: 'New task: {{ task.title }}'
|
|
17
|
+
title: Task assigned to you
|
|
18
|
+
message: |
|
|
19
|
+
Hi {{ contact.name }},
|
|
20
|
+
|
|
21
|
+
**{{ task.title }}** has been assigned to you.
|
|
22
|
+
metadata:
|
|
23
|
+
- label: Due
|
|
24
|
+
value: '{{ task.due_date }}'
|
|
25
|
+
button:
|
|
26
|
+
label: View task
|
|
27
|
+
testData:
|
|
28
|
+
contact:
|
|
29
|
+
name: Jane Doe
|
|
30
|
+
task:
|
|
31
|
+
title: Review the quarterly report
|
|
32
|
+
due_date: 2026-07-15
|
|
33
|
+
links:
|
|
34
|
+
button:
|
|
35
|
+
pageId: task-view
|
|
36
|
+
urlQuery:
|
|
37
|
+
_id: T-001
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The definition fields are:
|
|
41
|
+
|
|
42
|
+
- `id: string`: **Required** - A unique notification id, referenced by the `RenderNotification` step.
|
|
43
|
+
- `type: string`: **Required** - The template type — a built-in template (`NotificationEmail`, `DigestEmail`, `AlertEmail`) or a custom template plugin.
|
|
44
|
+
- `properties: object`: **Required** - The template's content. `properties.subject` is always required; the rest depend on the template type.
|
|
45
|
+
- `theme: object`: Per-notification overrides of the `app.email` theme (see [Theming](#theming)).
|
|
46
|
+
- `testData: object`: Sample data used to render the notification in the [email preview](#previewing-emails). Not used at runtime.
|
|
47
|
+
|
|
48
|
+
### Module notifications
|
|
49
|
+
|
|
50
|
+
Modules can ship notification templates: `module.lowdefy.yaml` accepts a `notifications:` section, and each template's id scopes to `{entry}/{id}` (installing `user-admin` gives `user-admin/invite-user`), so the same module installed twice never collides. Module content references its own templates with [`_module.notificationId`](/_module) — in a `RenderNotification` step or a dispatch payload — and app-level config reaches a module's template with the object form (`_module.notificationId: { id: invite-user, module: user-admin }`) or the literal scoped string. This lets a module that drives a notification flow (like user invites) ship its default email instead of every app hand-writing it. Module notifications resolve `_module.var` in their properties, so template copy can be configured through the module's vars.
|
|
51
|
+
|
|
52
|
+
### Interpolation
|
|
53
|
+
|
|
54
|
+
Template property strings interpolate against the render data with [Nunjucks](https://mozilla.github.io/nunjucks/) — `{{ task.title }}` just works, including `{% if %}` conditionals. This applies inside `notifications:` properties only.
|
|
55
|
+
|
|
56
|
+
Interpolated values are **inert** — they can never carry markup or links unless you mark them with the `markdown` filter (below). A task title of `[click here](https://evil.example)` renders as literal text, not a link. Only the markdown you write in the template formats; the data you interpolate is escaped. This closes the injection risk of putting user data into a branded email.
|
|
57
|
+
|
|
58
|
+
There is no operator evaluation inside template properties — they are data templates, not operator config. Build-time operators like [`_ref`](/references-and-templates) still work as everywhere else.
|
|
59
|
+
|
|
60
|
+
#### Markdown the app wrote
|
|
61
|
+
|
|
62
|
+
When a value is markdown your app wrote on purpose — a release note body, a templated summary — mark it with the `markdown` filter so it renders as headings, lists, links and images:
|
|
63
|
+
|
|
64
|
+
```yaml
|
|
65
|
+
properties:
|
|
66
|
+
subject: '{{ title }}'
|
|
67
|
+
message: "{{ intro }}\n\n{{ body | markdown }}"
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`intro` stays escaped; `body` renders as markdown. Use the filter only on markdown your app itself wrote, never on text a user typed: a filtered value can carry links and images into the email. Raw HTML stays escaped even in a filtered value, so a `<script>` tag still prints as text. Images render no wider than the email column. Outside markdown properties the filter changes nothing.
|
|
71
|
+
|
|
72
|
+
### Links
|
|
73
|
+
|
|
74
|
+
Links live under `data.links` (and inside the arrays a template declares, like `data.actions`), supplied as Lowdefy-native `{ pageId, urlQuery, pathParams }` objects. The `RenderNotification` step resolves them to full URLs at render time — see [Rendering notifications as a routine step](/lowdefy-api#rendering-notifications-as-a-routine-step). A link that is already an absolute URL string passes through unchanged.
|
|
75
|
+
|
|
76
|
+
A link to a page with a [`path`](/page-paths) gives the values of its placeholders in `pathParams`, as the `Link` action does:
|
|
77
|
+
|
|
78
|
+
```yaml
|
|
79
|
+
links:
|
|
80
|
+
button:
|
|
81
|
+
pageId: ticket
|
|
82
|
+
pathParams:
|
|
83
|
+
space: support
|
|
84
|
+
ticket_id: T-001
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
For a page with `path: tickets/{space}/{ticket_id}`, this renders as `https://myapp.com/tickets/support/T-001`. Every placeholder needs a value, or rendering fails with an error naming the page and the placeholder. The step resolves links in a copy of the item, so the item you store keeps the original `{ pageId, urlQuery, pathParams }` link, and the app can open it in the browser with a `Link` action, or from a landing page.
|
|
88
|
+
|
|
89
|
+
## Built-in templates
|
|
90
|
+
|
|
91
|
+
Three templates cover most needs. Each renders only the sections you provide — omit `quote` and no quote block appears.
|
|
92
|
+
|
|
93
|
+
### NotificationEmail
|
|
94
|
+
|
|
95
|
+
The general-purpose template.
|
|
96
|
+
|
|
97
|
+
- `subject: string`: **Required** - Email subject line.
|
|
98
|
+
- `title: string`: Heading shown at the top of the email.
|
|
99
|
+
- `message: string`: Main message, rendered as markdown.
|
|
100
|
+
- `preview: string`: Preview text shown in email client inbox listings.
|
|
101
|
+
- `metadata: object[]`: Label-value pairs rendered as a table. Each item is `{ label, value }`.
|
|
102
|
+
- `quote: object`: A quoted block, `{ text, author }`.
|
|
103
|
+
- `button: object`: A call-to-action button, `{ label }`. Its link is resolved from `data.links.button`.
|
|
104
|
+
|
|
105
|
+
Renders one data key: `data.actions` — an array of `{ title, message, link }` action items, shown as an action list.
|
|
106
|
+
|
|
107
|
+
### DigestEmail
|
|
108
|
+
|
|
109
|
+
For roundups of many items.
|
|
110
|
+
|
|
111
|
+
- `subject: string`: **Required** - Email subject line.
|
|
112
|
+
- `title: string`: Heading shown at the top of the email.
|
|
113
|
+
- `intro: string`: Introductory text, rendered as markdown.
|
|
114
|
+
- `button: object`: A call-to-action button, `{ label }`, linked from `data.links.button`.
|
|
115
|
+
|
|
116
|
+
Renders one data key: `data.items` — an array of `{ title, message, link, meta }` rows.
|
|
117
|
+
|
|
118
|
+
### AlertEmail
|
|
119
|
+
|
|
120
|
+
For status-toned notices.
|
|
121
|
+
|
|
122
|
+
- `subject: string`: **Required** - Email subject line.
|
|
123
|
+
- `tone: string`: One of `info`, `success`, `warning`, or `error`. Sets the accent color.
|
|
124
|
+
- `title: string`: Heading shown at the top of the email.
|
|
125
|
+
- `message: string`: Main message, rendered as markdown.
|
|
126
|
+
- `metadata: object[]`: Label-value pairs rendered as a table.
|
|
127
|
+
- `button: object`: A call-to-action button, `{ label }`, linked from `data.links.button`.
|
|
128
|
+
|
|
129
|
+
### Structured data (`actions`, `items`)
|
|
130
|
+
|
|
131
|
+
Structured arrays are never wired in config — a template documents the data keys it renders, and your pipeline supplies the array under that key (`data.actions` for `NotificationEmail`, `data.items` for `DigestEmail`). Each item's `link` field is resolved to a URL the same way `links.button` is.
|
|
132
|
+
|
|
133
|
+
## Theming
|
|
134
|
+
|
|
135
|
+
One theme per app, under `app.email`:
|
|
136
|
+
|
|
137
|
+
```yaml
|
|
138
|
+
app:
|
|
139
|
+
email:
|
|
140
|
+
logo: https://cdn.myapp.com/logo.png
|
|
141
|
+
companyName: MyApp
|
|
142
|
+
primaryColor: '#1990ff'
|
|
143
|
+
signature: |
|
|
144
|
+
Regards,
|
|
145
|
+
The MyApp Team
|
|
146
|
+
footer: You receive these emails because you have a MyApp account.
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The layout — logo header, greeting, content, signature, footer — is fixed; the theme parameterizes it. A notification can override any theme field (for example a sub-brand logo) with a `theme:` object; overrides shallow-merge over `app.email`.
|
|
150
|
+
|
|
151
|
+
Two fields default from your existing app config when you don't set them: `companyName` from the app's root `name:`, and `primaryColor` from `theme.antd.token.colorPrimary` — so a branded app gets branded emails without repeating itself. Set a field explicitly (an empty string works as an opt-out for `companyName`) to override the derived value.
|
|
152
|
+
|
|
153
|
+
The `logo` can be an app-relative path to a `public/` asset:
|
|
154
|
+
|
|
155
|
+
```yaml
|
|
156
|
+
app:
|
|
157
|
+
email:
|
|
158
|
+
logo: /logo-light-theme.png
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
A relative logo resolves against the `serverUrl` passed to the `RenderNotification` step (by default the current environment's `url` in `config.environments`), so one config works across environments. Email clients can only load absolute URLs — when no `serverUrl` is available the logo is omitted and the header falls back to the `companyName` text.
|
|
162
|
+
|
|
163
|
+
## Custom templates
|
|
164
|
+
|
|
165
|
+
Rich emails beyond the built-in templates are plugins — plain [React Email](https://react.email/) components. A custom template exports a component receiving `{ properties, data, theme, links }` and a properties schema, and declares its type under a new `notifications` type category — the same registration pattern as other [plugins](/plugins-introduction). Once installed, use it as a `type` in the `notifications:` section like any built-in template.
|
|
166
|
+
|
|
167
|
+
## Sending notifications
|
|
168
|
+
|
|
169
|
+
The framework renders; the pipeline is yours to compose. In an API routine you:
|
|
170
|
+
|
|
171
|
+
1. Render the notification with a [`RenderNotification` step](/lowdefy-api#rendering-notifications-as-a-routine-step), which returns `{ subject, title, preview, html, text, data }`.
|
|
172
|
+
2. Store a record with an ordinary request (for example `MongoDBInsertOne`) if you want an inbox, deduplication, or retries.
|
|
173
|
+
3. Send the email with an email request — [`SMTPMailSend`](/SMTP) or [`SendGridMailSend`](/SendGridMail).
|
|
174
|
+
4. Update the record with the send result.
|
|
175
|
+
|
|
176
|
+
That pipeline is about sixty lines of routine YAML, and you own every choice in it — record shape, deduplication strategy, retry policy. If you'd rather not write it, the official [`modules-mongodb` notifications module](https://github.com/lowdefy/modules-mongodb) ships the whole pipeline (dispatch, dedup, send, tracking) plus an inbox, bell, and mark-as-read landing page — you just define the templates and shape your events into notification items.
|
|
177
|
+
|
|
178
|
+
## Previewing emails
|
|
179
|
+
|
|
180
|
+
The [`lowdefy emails`](/cli#emails) CLI command renders every notification from its `testData` and opens [React Email](https://react.email/)'s preview server, so you can iterate on templates without sending real mail. It warns when a template renders a data key that your `testData` is missing. The preview has no server URL, so a relative `logo` falls back to the `companyName` text header there.
|
|
@@ -6,6 +6,12 @@ Each operators expects arguments with a specific structure. They can be the resu
|
|
|
6
6
|
|
|
7
7
|
If an operator errors while evaluating, it returns a `null` value, and logs the error to the console.
|
|
8
8
|
|
|
9
|
+
## How an operator is recognised
|
|
10
|
+
|
|
11
|
+
An object in config is evaluated as an operator when it has exactly one key, that key starts with `_`, and the part of the key before the first `.` names an operator installed in the app. Objects with more than one key, and strings that start with `_`, are never operators.
|
|
12
|
+
|
|
13
|
+
This means config written as data can collide with an operator. A one-key object such as `{ _user: 1 }` in a MongoDB `$project` stage, or `{ _date: ... }` in a `SetState` param, is evaluated as that operator instead of being kept as written. A one-key object whose key names no operator, such as `{ _score: 0.5 }`, stays data but logs a build warning that the operator type is not defined. Avoid field names and state keys that start with `_` (other than `_id`) where they could end up as the only key of an object.
|
|
14
|
+
|
|
9
15
|
## Client or server operators
|
|
10
16
|
|
|
11
17
|
Some operators are only available on either the client or the server. For example, the [`_menu`](/_menu) operator is only useful on the client and is thus not included in server requests. Likewise, the [`_secret`](/_secret) operator is only available on the server for security reasons.
|
|
@@ -22,6 +28,7 @@ If a operator has special environment considerations, it is indicated on the ind
|
|
|
22
28
|
- [_location](/_location)
|
|
23
29
|
- [_media](/_media)
|
|
24
30
|
- [_menu](/_menu)
|
|
31
|
+
- [_path_params](/_path_params)
|
|
25
32
|
- [_request](/_request)
|
|
26
33
|
- [_url_query](/_url_query)
|
|
27
34
|
|