@lowdefy/docs-content 7.2.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.
- package/content/adapter-reference/mongodbauthadapter.md +2 -2
- package/content/agents/agents-introduction.md +1 -1
- package/content/callback-reference/auth0logoutcallback.md +1 -1
- package/content/concepts/blocks.md +1 -1
- package/content/concepts/connections-and-requests.md +8 -8
- package/content/concepts/custom-html.md +1 -1
- package/content/concepts/logger.md +1 -1
- package/content/concepts/lowdefy-api.md +3 -3
- package/content/concepts/page-and-app-state.md +2 -2
- package/content/concepts/theming.md +1 -1
- package/content/connections/axioshttp.md +1 -1
- package/content/input-blocks/ratingslider.md +1 -0
- package/content/migration/v3-to-v4.md +2 -2
- package/content/operators/_api.md +11 -9
- package/content/operators/_ref.md +6 -6
- package/content/provider-reference/auth-js-providers.md +2 -2
- package/content/provider-reference/openidconnectprovider.md +1 -1
- package/content/testing/config-tests.md +2 -0
- package/content/tutorial/tutorial-create-page.md +1 -1
- package/content/tutorial/tutorial-requests-api.md +1 -1
- package/content/tutorial/tutorial-requests-sql.md +1 -1
- package/content/tutorial/tutorial-start.md +1 -1
- package/content/user-authentication/auth-configuration.md +9 -9
- package/content/user-authentication/auth-steps.md +2 -2
- package/content/user-authentication/organizations.md +11 -1
- package/content/user-authentication/protected-pages-apis.md +4 -4
- package/content/user-authentication/roles.md +2 -2
- package/content/user-authentication/user-object.md +1 -1
- package/content/websockets/websocket-publish.md +1 -1
- package/content/websockets/websockets-introduction.md +54 -2
- package/index.json +8 -8
- package/package.json +2 -2
|
@@ -18,7 +18,7 @@ If you are upgrading from the old `MongoDBAdapter`: the type is renamed, `databa
|
|
|
18
18
|
###### Minimum configuration.
|
|
19
19
|
|
|
20
20
|
```yaml
|
|
21
|
-
lowdefy: 7.
|
|
21
|
+
lowdefy: 7.2.0
|
|
22
22
|
auth:
|
|
23
23
|
database:
|
|
24
24
|
id: auth_db
|
|
@@ -31,7 +31,7 @@ auth:
|
|
|
31
31
|
###### Full configuration.
|
|
32
32
|
|
|
33
33
|
```yaml
|
|
34
|
-
lowdefy: 7.
|
|
34
|
+
lowdefy: 7.2.0
|
|
35
35
|
auth:
|
|
36
36
|
database:
|
|
37
37
|
id: auth_db
|
|
@@ -22,7 +22,7 @@ The schema for a Lowdefy connection is:
|
|
|
22
22
|
|
|
23
23
|
###### Connections definition example:
|
|
24
24
|
```yaml
|
|
25
|
-
lowdefy: 7.
|
|
25
|
+
lowdefy: 7.2.0
|
|
26
26
|
connections:
|
|
27
27
|
- id: connection1
|
|
28
28
|
type: ConnectionType1
|
|
@@ -100,7 +100,7 @@ _request: my_request
|
|
|
100
100
|
|
|
101
101
|
###### lowdefy.yaml
|
|
102
102
|
```yaml
|
|
103
|
-
lowdefy: 7.
|
|
103
|
+
lowdefy: 7.2.0
|
|
104
104
|
|
|
105
105
|
connections:
|
|
106
106
|
- id: connection1
|
|
@@ -142,7 +142,7 @@ To create this `connection`, define the connection as follows in the `lowdefy.ya
|
|
|
142
142
|
|
|
143
143
|
###### lowdefy.yaml
|
|
144
144
|
```yaml
|
|
145
|
-
lowdefy: 7.
|
|
145
|
+
lowdefy: 7.2.0
|
|
146
146
|
|
|
147
147
|
connections:
|
|
148
148
|
- id: my_api
|
|
@@ -159,7 +159,7 @@ To use this connection, a `request` must be defined, which references the corres
|
|
|
159
159
|
|
|
160
160
|
###### lowdefy.yaml
|
|
161
161
|
```yaml
|
|
162
|
-
lowdefy: 7.
|
|
162
|
+
lowdefy: 7.2.0
|
|
163
163
|
|
|
164
164
|
connections:
|
|
165
165
|
- id: my_api
|
|
@@ -183,7 +183,7 @@ This request should be called when the page is mounted. To do this, the [`Reques
|
|
|
183
183
|
|
|
184
184
|
###### lowdefy.yaml
|
|
185
185
|
```yaml
|
|
186
|
-
lowdefy: 7.
|
|
186
|
+
lowdefy: 7.2.0
|
|
187
187
|
|
|
188
188
|
connections:
|
|
189
189
|
- id: my_api
|
|
@@ -214,7 +214,7 @@ In this example, a [`Selector`](/Selector) block will be added. The [`_array.map
|
|
|
214
214
|
|
|
215
215
|
###### lowdefy.yaml
|
|
216
216
|
```yaml
|
|
217
|
-
lowdefy: 7.
|
|
217
|
+
lowdefy: 7.2.0
|
|
218
218
|
|
|
219
219
|
connections:
|
|
220
220
|
- id: my_api
|
|
@@ -259,7 +259,7 @@ To do this, create a new request that will make use of a `payload` to get the po
|
|
|
259
259
|
|
|
260
260
|
###### lowdefy.yaml
|
|
261
261
|
```yaml
|
|
262
|
-
lowdefy: 7.
|
|
262
|
+
lowdefy: 7.2.0
|
|
263
263
|
|
|
264
264
|
connections:
|
|
265
265
|
- id: my_api
|
|
@@ -321,7 +321,7 @@ This is done as follows:
|
|
|
321
321
|
|
|
322
322
|
###### lowdefy.yaml
|
|
323
323
|
```yaml
|
|
324
|
-
lowdefy: 7.
|
|
324
|
+
lowdefy: 7.2.0
|
|
325
325
|
|
|
326
326
|
connections:
|
|
327
327
|
- id: my_api
|
|
@@ -42,7 +42,7 @@ The schema for a Lowdefy API is:
|
|
|
42
42
|
###### API definition example:
|
|
43
43
|
|
|
44
44
|
```yaml
|
|
45
|
-
lowdefy: '7.
|
|
45
|
+
lowdefy: '7.2.0'
|
|
46
46
|
|
|
47
47
|
connections:
|
|
48
48
|
- id: users
|
|
@@ -77,7 +77,7 @@ Lowdefy APIs use the same [authorization configuration](/protected-pages-apis) a
|
|
|
77
77
|
Unlike requests which are defined on a specific page and inherit the authorization of the page they are defined on, API endpoints can be called from any page in the app. Thus they do not inherit the authorization of the page they are called from, and authorization should be configured separately.
|
|
78
78
|
|
|
79
79
|
```yaml
|
|
80
|
-
lowdefy: '7.
|
|
80
|
+
lowdefy: '7.2.0'
|
|
81
81
|
|
|
82
82
|
auth:
|
|
83
83
|
# Configure which APIs require authentication
|
|
@@ -1235,7 +1235,7 @@ blocks:
|
|
|
1235
1235
|
Here's a comprehensive example showing various features:
|
|
1236
1236
|
|
|
1237
1237
|
```yaml
|
|
1238
|
-
lowdefy: '7.
|
|
1238
|
+
lowdefy: '7.2.0'
|
|
1239
1239
|
auth:
|
|
1240
1240
|
api:
|
|
1241
1241
|
protected: true
|
|
@@ -83,7 +83,7 @@ This example shows how you can create and read from `global`:
|
|
|
83
83
|
|
|
84
84
|
`lowdefy.yaml`
|
|
85
85
|
```yaml
|
|
86
|
-
lowdefy: 7.
|
|
86
|
+
lowdefy: 7.2.0
|
|
87
87
|
global:
|
|
88
88
|
key: value
|
|
89
89
|
pages:
|
|
@@ -101,7 +101,7 @@ The following examples shows how to modify the `global` object:
|
|
|
101
101
|
|
|
102
102
|
`lowdefy.yaml`
|
|
103
103
|
```yaml
|
|
104
|
-
lowdefy: 7.
|
|
104
|
+
lowdefy: 7.2.0
|
|
105
105
|
global:
|
|
106
106
|
key: value
|
|
107
107
|
pages:
|
|
@@ -64,7 +64,7 @@ Properties for a AxiosHttp can be set on either the connection, the request, or
|
|
|
64
64
|
###### A basic full example requesting data from https://jsonplaceholder.typicode.com
|
|
65
65
|
|
|
66
66
|
```yaml
|
|
67
|
-
lowdefy: 7.
|
|
67
|
+
lowdefy: 7.2.0
|
|
68
68
|
name: Lowdefy starter
|
|
69
69
|
connections:
|
|
70
70
|
- id: my_api
|
|
@@ -669,6 +669,7 @@ Rating slider with customizable range, icons, and N/A option.
|
|
|
669
669
|
| `label.hasFeedback` | boolean | `true` | Display feedback extra from validation, this does not disable validation. |
|
|
670
670
|
| `label.inline` | boolean | `false` | Render input and label inline. |
|
|
671
671
|
| `label.wrap` | boolean | `false` | Wrap long label text onto multiple lines when the label is inline. Labels above their input always wrap. |
|
|
672
|
+
| `marks` | object | - | Tick marks on the slider. Keys are slider values and values are labels: a string, or `{ style, label }` as antd takes. Replaces the marks `showMarks` draws, including the blank mark one step below `min`. Example: { 0: "0", 5: "5", 10: "10" }. |
|
|
672
673
|
| `min` | number | `0` | The minimum value of the slider. |
|
|
673
674
|
| `max` | number | `10` | The maximum value of the slider. |
|
|
674
675
|
| `notApplicableLabel` | string | `"N/A"` | Label shown at the null value of the slider. |
|
|
@@ -363,7 +363,7 @@ blocks:
|
|
|
363
363
|
The `LOWDEFY_SERVER_BASE_PATH` environment variable configuration option has been removed. To configure a base path, use the `config.basePath` configuration option.
|
|
364
364
|
|
|
365
365
|
``yaml
|
|
366
|
-
lowdefy: 7.
|
|
366
|
+
lowdefy: 7.2.0
|
|
367
367
|
|
|
368
368
|
config:
|
|
369
369
|
basePath: /foo
|
|
@@ -371,7 +371,7 @@ config:
|
|
|
371
371
|
|
|
372
372
|
The `_build.env` operator can be used to set the base path using an environment variable:
|
|
373
373
|
```yaml
|
|
374
|
-
lowdefy: 7.
|
|
374
|
+
lowdefy: 7.2.0
|
|
375
375
|
|
|
376
376
|
config:
|
|
377
377
|
basePath:
|
|
@@ -97,42 +97,44 @@ events:
|
|
|
97
97
|
type: CallAPI
|
|
98
98
|
params:
|
|
99
99
|
endpointId: get_products
|
|
100
|
+
holdValue: true # Without holdValue, _api returns null while the call is loading
|
|
100
101
|
- id: set_products_list
|
|
101
102
|
type: SetState
|
|
102
103
|
params:
|
|
103
|
-
products_list
|
|
104
|
-
_api:
|
|
104
|
+
products_list:
|
|
105
|
+
_api: get_products.response.products
|
|
105
106
|
|
|
106
107
|
blocks:
|
|
107
108
|
- id: loading_text
|
|
108
109
|
type: Html
|
|
109
110
|
visible:
|
|
110
|
-
_api:
|
|
111
|
+
_api: get_products.loading # Show loading text while API is loading
|
|
111
112
|
properties:
|
|
112
113
|
html: '<div class="secondary">Loading...</div>'
|
|
113
114
|
|
|
114
115
|
- id: error_message
|
|
115
116
|
type: Alert
|
|
116
117
|
visible:
|
|
117
|
-
|
|
118
|
-
_api:
|
|
118
|
+
_eq: # success is null while the call is loading
|
|
119
|
+
- _api: get_products.success
|
|
120
|
+
- false
|
|
119
121
|
properties:
|
|
120
122
|
type: error
|
|
121
123
|
message:
|
|
122
124
|
_if:
|
|
123
125
|
test:
|
|
124
|
-
_api:
|
|
126
|
+
_api: get_products.error
|
|
125
127
|
then:
|
|
126
|
-
_api:
|
|
128
|
+
_api: get_products.error.message
|
|
127
129
|
else: 'An error occurred'
|
|
128
130
|
|
|
129
131
|
- id: products_list
|
|
130
132
|
type: List
|
|
131
133
|
visible:
|
|
132
134
|
_and:
|
|
133
|
-
- _api:
|
|
135
|
+
- _api: get_products.success
|
|
134
136
|
- _not:
|
|
135
|
-
_api:
|
|
137
|
+
_api: get_products.loading
|
|
136
138
|
```
|
|
137
139
|
|
|
138
140
|
###### Working with multiple API calls:
|
|
@@ -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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
256
|
+
lowdefy: 7.2.0
|
|
257
257
|
|
|
258
258
|
pages:
|
|
259
259
|
- _ref:
|
|
@@ -75,7 +75,7 @@ The providers that can be used are:
|
|
|
75
75
|
###### Auth0 configuration:
|
|
76
76
|
|
|
77
77
|
```yaml
|
|
78
|
-
lowdefy: 7.
|
|
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.
|
|
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.
|
|
31
|
+
lowdefy: 7.2.0
|
|
32
32
|
providers:
|
|
33
33
|
- id: my_provider
|
|
34
34
|
type: OpenIDConnectProvider
|
|
@@ -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
|
|
@@ -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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
234
|
+
lowdefy: 7.2.0
|
|
235
235
|
|
|
236
236
|
auth:
|
|
237
237
|
providers:
|
|
@@ -114,7 +114,7 @@ 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. |
|
|
@@ -125,7 +125,7 @@ Scope, required permission, and target for every auth step. Permissions are chec
|
|
|
125
125
|
| `UnsuspendMember` | org | `member: [suspend]` | — | Lift a suspension (`memberId`); the member keeps the roles they held. |
|
|
126
126
|
| `UpdateOrganization` | org | `organization: [update]` | — | Update the organization row (name, slug, metadata). |
|
|
127
127
|
| `RevokeOrgMcpToken` | org | `member: [update]` | — | Switch off any [member token](/mcp-oauth#tokens-for-scripts) in the organization (`id`). |
|
|
128
|
-
| `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. |
|
|
129
129
|
| `UpdateUserAttributes` | org | `user: [set-attributes]` | `userId` | Set global user attributes. |
|
|
130
130
|
| `BanUser` | org | `user: [ban]` | `userId` | Ban a user. |
|
|
131
131
|
| `UnbanUser` | org | `user: [ban]` | `userId` | Lift a ban. |
|
|
@@ -55,7 +55,17 @@ An equivalent unique index you created yourself, under any name, is accepted. If
|
|
|
55
55
|
|
|
56
56
|
### Invitations for existing members
|
|
57
57
|
|
|
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. 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.
|
|
59
69
|
|
|
60
70
|
### Suspending a member
|
|
61
71
|
|
|
@@ -14,7 +14,7 @@ The 404 page (used to indicate that a requested page cannot be found) is always
|
|
|
14
14
|
|
|
15
15
|
###### List specific public pages and APIs:
|
|
16
16
|
```yaml
|
|
17
|
-
lowdefy: 7.
|
|
17
|
+
lowdefy: 7.2.0
|
|
18
18
|
auth:
|
|
19
19
|
pages:
|
|
20
20
|
protected: true
|
|
@@ -31,7 +31,7 @@ auth:
|
|
|
31
31
|
|
|
32
32
|
###### List specific protected pages and APIs:
|
|
33
33
|
```yaml
|
|
34
|
-
lowdefy: 7.
|
|
34
|
+
lowdefy: 7.2.0
|
|
35
35
|
auth:
|
|
36
36
|
pages:
|
|
37
37
|
public: true
|
|
@@ -47,7 +47,7 @@ auth:
|
|
|
47
47
|
|
|
48
48
|
###### Mixed configuration:
|
|
49
49
|
```yaml
|
|
50
|
-
lowdefy: 7.
|
|
50
|
+
lowdefy: 7.2.0
|
|
51
51
|
auth:
|
|
52
52
|
# Protect specific pages while keeping most public
|
|
53
53
|
pages:
|
|
@@ -75,7 +75,7 @@ Exact page IDs still work: `home`, `team-users/users-list`.
|
|
|
75
75
|
|
|
76
76
|
###### Wildcard pattern example:
|
|
77
77
|
```yaml
|
|
78
|
-
lowdefy: 7.
|
|
78
|
+
lowdefy: 7.2.0
|
|
79
79
|
auth:
|
|
80
80
|
pages:
|
|
81
81
|
protected: true
|
|
@@ -7,7 +7,7 @@ Roles are read from the `roles` field on the [user object](/user-object) — an
|
|
|
7
7
|
Declare the role names your app uses in `auth.roles` (id, optional label and description) so tooling can list them:
|
|
8
8
|
|
|
9
9
|
```yaml
|
|
10
|
-
lowdefy: 7.
|
|
10
|
+
lowdefy: 7.2.0
|
|
11
11
|
auth:
|
|
12
12
|
roles:
|
|
13
13
|
- id: user-admin
|
|
@@ -24,7 +24,7 @@ Similarly, the API endpoints that are protected by roles are configured in the `
|
|
|
24
24
|
|
|
25
25
|
###### Protect pages and API endpoints using roles:
|
|
26
26
|
```yaml
|
|
27
|
-
lowdefy: 7.
|
|
27
|
+
lowdefy: 7.2.0
|
|
28
28
|
auth:
|
|
29
29
|
pages:
|
|
30
30
|
public: true
|
|
@@ -20,7 +20,7 @@ Its shape is **fixed**. Unlike the old provider-claim mapping, there is no `user
|
|
|
20
20
|
| `two_factor_enrolled` | session | Whether the caller holds a factor satisfying `auth.twoFactor.required`. |
|
|
21
21
|
| `auth_method` | strategy, mcp | How the caller authenticated — the strategy id, or `'mcp'` for an [assistant](/mcp-oauth). Absent on browser sessions. |
|
|
22
22
|
| `profile` | session | The user record's opaque display/app-data bag. Absent (never `{}`) when the user has written no profile. |
|
|
23
|
-
| `contact_id` | session | Link to the app's canonical record for this person, when one exists. |
|
|
23
|
+
| `contact_id` | session | Link to the app's canonical record for this person, when one exists. Set once, when the person accepts an invitation that carries `contactId`; no auth step changes it. |
|
|
24
24
|
|
|
25
25
|
> **`_user.role` (singular) carries nothing.** Lowdefy never writes it; it sits one character from `roles`, so gating on `_user.role` is gating on a constant. Read `roles`.
|
|
26
26
|
|
|
@@ -9,7 +9,7 @@ Websockets work identically on a self-hosted Node.js server and on Vercel, where
|
|
|
9
9
|
A channel and a page subscription — this page shows a live tick counter:
|
|
10
10
|
|
|
11
11
|
```yaml
|
|
12
|
-
lowdefy: 7.
|
|
12
|
+
lowdefy: 7.2.0
|
|
13
13
|
|
|
14
14
|
websockets:
|
|
15
15
|
- id: ticker
|
|
@@ -38,7 +38,7 @@ When the page loads, the client opens a websocket connection, subscribes to `tic
|
|
|
38
38
|
|
|
39
39
|
1. A page with `subscriptions` mounts. The client opens one shared WebSocket connection to the Lowdefy server (lazily — apps without websockets never connect).
|
|
40
40
|
2. For each subscription, the client evaluates the subscription `payload` (client-side operators like `_state`) and sends a subscribe frame.
|
|
41
|
-
3. The server authorizes the subscription against the channel's `auth` config, then evaluates the websocket `properties` server-side — `_payload` reads the subscription payload and `_user` reads the subscriber's session, so a channel can be user-specific.
|
|
41
|
+
3. The server authorizes the subscription against the channel's `auth` config and, when the websocket has a `check`, calls the check endpoint as the subscriber. It then evaluates the websocket `properties` server-side — `_payload` reads the subscription payload and `_user` reads the subscriber's session, so a channel can be user-specific.
|
|
42
42
|
4. Subscribers whose evaluated properties are identical share one running source on the server. The first subscriber starts it; the last one to leave stops it.
|
|
43
43
|
5. Messages from the source are pushed to all subscribers, update the channel state read by the [`_websocket`](/websocket-subscriptions) operator, and fire the subscription's `onMessage` event.
|
|
44
44
|
|
|
@@ -52,6 +52,9 @@ Websockets are defined in the top-level `websockets` array:
|
|
|
52
52
|
- `type: string`: __Required__ - The websocket type. `Channel` and `Interval` ship with Lowdefy; connection plugins provide types like [`MongoDBChangeStream`](/MongoDB).
|
|
53
53
|
- `connectionId: string`: The `id` of a [connection](/connections) for connection-backed types.
|
|
54
54
|
- `properties: object`: Settings for the type. __Operators are evaluated server-side per subscription__ — `_secret`, `_user`, and `_payload` are available.
|
|
55
|
+
- `check: object`: An [API endpoint](/api-endpoints) that decides whether this caller may hear, or publish to, the channel. It runs on every subscribe and publish, and once a minute while a subscription stays open. See [Securing Channels](#securing-channels).
|
|
56
|
+
- `endpointId: string`: __Required__ - The `Api` or `InternalApi` endpoint to call. The build fails when the app has no endpoint with this id.
|
|
57
|
+
- `payload: object`: The payload sent to the endpoint, evaluated server-side with `_payload`, `_user` and `_secret`. Defaults to the subscription payload.
|
|
55
58
|
|
|
56
59
|
###### A user-specific channel:
|
|
57
60
|
```yaml
|
|
@@ -95,6 +98,55 @@ Unauthorized subscriptions receive the same response as subscriptions to channel
|
|
|
95
98
|
|
|
96
99
|
An open connection follows the session. The server checks the caller again on every subscribe and at least once a minute. When the user signs out, the session ends, the membership is removed, the roles change or the user switches organization, the server closes the connection and the client reconnects straight away as the current caller. Subscriptions the current caller may not hold fail as they would on a freshly loaded page.
|
|
97
100
|
|
|
101
|
+
### Checking access to a record
|
|
102
|
+
|
|
103
|
+
Roles decide who may hear a channel at all. A channel whose payload names a record, such as the events on one ticket, also needs to know whether this subscriber may see that ticket. A pipeline filter can not answer that, since it only sees the change event, so give the websocket a `check`: an endpoint that answers from your own data.
|
|
104
|
+
|
|
105
|
+
```yaml
|
|
106
|
+
api:
|
|
107
|
+
- id: can-view-ticket
|
|
108
|
+
type: InternalApi
|
|
109
|
+
routine:
|
|
110
|
+
- id: ticket
|
|
111
|
+
type: MongoDBFindOne
|
|
112
|
+
connectionId: tickets
|
|
113
|
+
properties:
|
|
114
|
+
query:
|
|
115
|
+
_id:
|
|
116
|
+
_payload: ticket_id
|
|
117
|
+
$or:
|
|
118
|
+
- author_id:
|
|
119
|
+
_user: id
|
|
120
|
+
- subscriber_ids:
|
|
121
|
+
_user: id
|
|
122
|
+
- :return:
|
|
123
|
+
_ne:
|
|
124
|
+
- _step: ticket
|
|
125
|
+
- null
|
|
126
|
+
|
|
127
|
+
websockets:
|
|
128
|
+
- id: ticket_events
|
|
129
|
+
type: MongoDBChangeStream
|
|
130
|
+
connectionId: events
|
|
131
|
+
check:
|
|
132
|
+
endpointId: can-view-ticket
|
|
133
|
+
payload:
|
|
134
|
+
ticket_id:
|
|
135
|
+
_payload: ticket_id
|
|
136
|
+
properties:
|
|
137
|
+
pipeline:
|
|
138
|
+
- $match:
|
|
139
|
+
fullDocument.ticket_id:
|
|
140
|
+
_payload: ticket_id
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
- The endpoint runs as the subscriber, with the same `_user`, roles and organization as a request from that session.
|
|
144
|
+
- Only a return value of exactly `true` lets the subscription continue. Any other value, an error, or an endpoint the subscriber may not call refuses it with the same response as a channel that does not exist. An error in the check or the endpoint is also logged.
|
|
145
|
+
- The check runs on every subscribe: the first one, the resubscribe after a reconnect, and a [`Subscribe`](/websocket-publish) with a new payload. It runs again at least once a minute while a subscription stays open, so revoking access ends a running subscription within a minute: the subscription gets the refusal as an error and no further messages. Each open subscription calls the endpoint once a minute, so keep the check cheap.
|
|
146
|
+
- The check is not part of the channel identity. Subscribers whose evaluated `properties` match still share one running source, and each is checked on their own.
|
|
147
|
+
- A publish is checked too, with an empty payload, since a publish evaluates the websocket `properties` without one. A check that reads the payload therefore refuses every publish, and a check that does not, such as membership of a group, decides who may publish as well as who may hear.
|
|
148
|
+
- A module websocket names its own endpoint with [`_module.endpointId`](/_module).
|
|
149
|
+
|
|
98
150
|
## What's Next
|
|
99
151
|
|
|
100
152
|
- [Page Subscriptions](/websocket-subscriptions) — Subscribe pages to channels, handle messages with events, and read channel state with `_websocket`.
|
package/index.json
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"version": "7.
|
|
2
|
+
"version": "7.2.0",
|
|
3
3
|
"docs": [
|
|
4
4
|
{
|
|
5
5
|
"slug": "learn/introduction",
|
|
@@ -3176,7 +3176,7 @@
|
|
|
3176
3176
|
"version.yaml",
|
|
3177
3177
|
"websockets/introduction.yaml"
|
|
3178
3178
|
],
|
|
3179
|
-
"hash": "
|
|
3179
|
+
"hash": "949ab851163dc40decd06e30ad974087dea1115f91ab6791104a2c010b5a6197"
|
|
3180
3180
|
},
|
|
3181
3181
|
"websockets/websocket-subscriptions": {
|
|
3182
3182
|
"files": [
|
|
@@ -3301,13 +3301,13 @@
|
|
|
3301
3301
|
"files": [
|
|
3302
3302
|
"users/organizations.yaml"
|
|
3303
3303
|
],
|
|
3304
|
-
"hash": "
|
|
3304
|
+
"hash": "a799ed56573f37a7374538657a5c523e8b0a3bd3e35dabed7492bf705ca26873"
|
|
3305
3305
|
},
|
|
3306
3306
|
"user-authentication/auth-steps": {
|
|
3307
3307
|
"files": [
|
|
3308
3308
|
"users/auth-steps.yaml"
|
|
3309
3309
|
],
|
|
3310
|
-
"hash": "
|
|
3310
|
+
"hash": "6a3fd58bb355b46f33246b84c6993d3dda0d60495bd56d94384f505873888903"
|
|
3311
3311
|
},
|
|
3312
3312
|
"user-authentication/mcp-oauth": {
|
|
3313
3313
|
"files": [
|
|
@@ -3319,7 +3319,7 @@
|
|
|
3319
3319
|
"files": [
|
|
3320
3320
|
"users/user-object.yaml"
|
|
3321
3321
|
],
|
|
3322
|
-
"hash": "
|
|
3322
|
+
"hash": "c56c01fd7f124bce78c8c920a96e09010fffe98e1b50e33638a277bfead730f6"
|
|
3323
3323
|
},
|
|
3324
3324
|
"user-authentication/auth-configuration": {
|
|
3325
3325
|
"files": [
|
|
@@ -3361,7 +3361,7 @@
|
|
|
3361
3361
|
"testing/config-tests.md",
|
|
3362
3362
|
"testing/config-tests.yaml"
|
|
3363
3363
|
],
|
|
3364
|
-
"hash": "
|
|
3364
|
+
"hash": "954e1aaacaf6abe246a4574fad5dee7e54b947b48652133da667e592e678f122"
|
|
3365
3365
|
},
|
|
3366
3366
|
"testing/journey-data-sets": {
|
|
3367
3367
|
"files": [
|
|
@@ -3709,7 +3709,7 @@
|
|
|
3709
3709
|
"blocks/input/RatingSlider.yaml",
|
|
3710
3710
|
"templates/blocks/gallery.yaml.njk"
|
|
3711
3711
|
],
|
|
3712
|
-
"hash": "
|
|
3712
|
+
"hash": "f52c19b663d984b6d0c2d517603d3a8b21fd925563a9eba96790f6687b012dc5"
|
|
3713
3713
|
},
|
|
3714
3714
|
"input-blocks/segmentedselector": {
|
|
3715
3715
|
"files": [
|
|
@@ -5293,7 +5293,7 @@
|
|
|
5293
5293
|
"operators/_api.yaml",
|
|
5294
5294
|
"templates/operators.yaml.njk"
|
|
5295
5295
|
],
|
|
5296
|
-
"hash": "
|
|
5296
|
+
"hash": "8181db4d7542c90ad8cc2be7db4eb94f545a8361f32a001aa7339bff336ad268"
|
|
5297
5297
|
},
|
|
5298
5298
|
"operators/_app": {
|
|
5299
5299
|
"files": [
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lowdefy/docs-content",
|
|
3
|
-
"version": "7.
|
|
3
|
+
"version": "7.3.0",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"description": "Lowdefy documentation extracted as markdown for AI coding agents.",
|
|
6
6
|
"homepage": "https://lowdefy.com",
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
"scripts/*"
|
|
37
37
|
],
|
|
38
38
|
"dependencies": {
|
|
39
|
-
"@lowdefy/nunjucks": "7.
|
|
39
|
+
"@lowdefy/nunjucks": "7.3.0"
|
|
40
40
|
},
|
|
41
41
|
"publishConfig": {
|
|
42
42
|
"access": "public"
|