@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.
Files changed (32) hide show
  1. package/content/adapter-reference/mongodbauthadapter.md +2 -2
  2. package/content/agents/agents-introduction.md +1 -1
  3. package/content/callback-reference/auth0logoutcallback.md +1 -1
  4. package/content/concepts/blocks.md +1 -1
  5. package/content/concepts/connections-and-requests.md +8 -8
  6. package/content/concepts/custom-html.md +1 -1
  7. package/content/concepts/logger.md +1 -1
  8. package/content/concepts/lowdefy-api.md +3 -3
  9. package/content/concepts/page-and-app-state.md +2 -2
  10. package/content/concepts/theming.md +1 -1
  11. package/content/connections/axioshttp.md +1 -1
  12. package/content/input-blocks/ratingslider.md +1 -0
  13. package/content/migration/v3-to-v4.md +2 -2
  14. package/content/operators/_api.md +11 -9
  15. package/content/operators/_ref.md +6 -6
  16. package/content/provider-reference/auth-js-providers.md +2 -2
  17. package/content/provider-reference/openidconnectprovider.md +1 -1
  18. package/content/testing/config-tests.md +2 -0
  19. package/content/tutorial/tutorial-create-page.md +1 -1
  20. package/content/tutorial/tutorial-requests-api.md +1 -1
  21. package/content/tutorial/tutorial-requests-sql.md +1 -1
  22. package/content/tutorial/tutorial-start.md +1 -1
  23. package/content/user-authentication/auth-configuration.md +9 -9
  24. package/content/user-authentication/auth-steps.md +2 -2
  25. package/content/user-authentication/organizations.md +11 -1
  26. package/content/user-authentication/protected-pages-apis.md +4 -4
  27. package/content/user-authentication/roles.md +2 -2
  28. package/content/user-authentication/user-object.md +1 -1
  29. package/content/websockets/websocket-publish.md +1 -1
  30. package/content/websockets/websockets-introduction.md +54 -2
  31. package/index.json +8 -8
  32. 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.1.0
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.1.0
34
+ lowdefy: 7.2.0
35
35
  auth:
36
36
  database:
37
37
  id: auth_db
@@ -9,7 +9,7 @@ Agents are defined at the root of your Lowdefy configuration, alongside `connect
9
9
  A connection, an agent, and a chat block — that's all you need:
10
10
 
11
11
  ```yaml
12
- lowdefy: 7.1.0
12
+ lowdefy: 7.2.0
13
13
 
14
14
  connections:
15
15
  - id: anthropic
@@ -16,7 +16,7 @@ To trigger the Auth0 logout, the `Logout` action `callbackUrl.url` param should
16
16
  ###### Configuring Auth0LogoutCallback.
17
17
 
18
18
  ```yaml
19
- lowdefy: 7.1.0
19
+ lowdefy: 7.2.0
20
20
  providers:
21
21
  - id: auth0
22
22
  type: Auth0Provider
@@ -35,7 +35,7 @@ Lowdefy has a set of default block types as defined in the Lowdefy docs. Most of
35
35
 
36
36
  ###### Default block type config example:
37
37
  ```yaml
38
- lowdefy: 7.1.0
38
+ lowdefy: 7.2.0
39
39
  pages:
40
40
  - id: example_dashboard
41
41
  type: PageHeaderMenu
@@ -22,7 +22,7 @@ The schema for a Lowdefy connection is:
22
22
 
23
23
  ###### Connections definition example:
24
24
  ```yaml
25
- lowdefy: 7.1.0
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.1.0
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.1.0
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.1.0
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.1.0
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.1.0
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.1.0
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.1.0
324
+ lowdefy: 7.2.0
325
325
 
326
326
  connections:
327
327
  - id: my_api
@@ -25,7 +25,7 @@ To add [Google Analytics](/https://developers.google.com/analytics/devguides/col
25
25
 
26
26
  ```yaml
27
27
  name: google-analytics-example
28
- lowdefy: 7.1.0
28
+ lowdefy: 7.2.0
29
29
  # ...
30
30
  app:
31
31
  html:
@@ -28,7 +28,7 @@ For client-side error capture, you also need to expose the DSN to the browser:
28
28
  You can customize Sentry behavior using the `logger` configuration in your `lowdefy.yaml`:
29
29
 
30
30
  ```yaml
31
- lowdefy: 7.1.0
31
+ lowdefy: 7.2.0
32
32
 
33
33
  logger:
34
34
  sentry:
@@ -42,7 +42,7 @@ The schema for a Lowdefy API is:
42
42
  ###### API definition example:
43
43
 
44
44
  ```yaml
45
- lowdefy: '7.1.0'
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.1.0'
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.1.0'
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.1.0
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.1.0
104
+ lowdefy: 7.2.0
105
105
  global:
106
106
  key: value
107
107
  pages:
@@ -7,7 +7,7 @@ Lowdefy uses the [Ant Design](https://ant.design/) design token system for themi
7
7
  Configure your app's theme in `lowdefy.yaml` under `theme.antd`:
8
8
 
9
9
  ```yaml
10
- lowdefy: 7.1.0
10
+ lowdefy: 7.2.0
11
11
  theme:
12
12
  antd:
13
13
  token:
@@ -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.1.0
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.1.0
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.1.0
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: fetch_products.response.products
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: fetch_products.loading # Show loading text while API is loading
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
- _not:
118
- _api: fetch_products.success
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: fetch_products.error
126
+ _api: get_products.error
125
127
  then:
126
- _api: fetch_products.error.message
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: fetch_products.success
135
+ - _api: get_products.success
134
136
  - _not:
135
- _api: fetch_products.loading
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.1.0
85
+ lowdefy: 7.2.0
86
86
  pages:
87
87
  - _ref: pages/page1.yaml
88
88
  - _ref: pages/page2.yaml
@@ -103,7 +103,7 @@ blocks:
103
103
  ```
104
104
  Returns:
105
105
  ```
106
- lowdefy: 7.1.0
106
+ lowdefy: 7.2.0
107
107
  pages:
108
108
  - id: page1
109
109
  type: PageHeaderMenu
@@ -176,7 +176,7 @@ blocks:
176
176
  ###### Use key:
177
177
  ```yaml
178
178
  # lowdefy.yaml
179
- lowdefy: 7.1.0
179
+ lowdefy: 7.2.0
180
180
  version:
181
181
  _ref:
182
182
  path: package.json
@@ -190,7 +190,7 @@ version:
190
190
  ```
191
191
  Returns:
192
192
  ```
193
- lowdefy: 7.1.0
193
+ lowdefy: 7.2.0
194
194
  version: 1.0.0
195
195
  ```
196
196
 
@@ -227,7 +227,7 @@ module.exports = useLocalOrSharedConfig;
227
227
 
228
228
  ```yaml
229
229
  // lowdefy.yaml
230
- lowdefy: 7.1.0
230
+ lowdefy: 7.2.0
231
231
 
232
232
  cli:
233
233
  refResolver: resolvers/useLocalOrSharedConfig.js
@@ -253,7 +253,7 @@ module.exports = addFooter;
253
253
  ```
254
254
  ```yaml
255
255
  // lowdefy.yaml
256
- lowdefy: 7.1.0
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.1.0
78
+ lowdefy: 7.2.0
79
79
  auth:
80
80
  providers:
81
81
  - id: auth0
@@ -94,7 +94,7 @@ In Auth0, the callback URL should be configured to `https://example.com/api/auth
94
94
  ###### GitHub configuration:
95
95
 
96
96
  ```yaml
97
- lowdefy: 7.1.0
97
+ lowdefy: 7.2.0
98
98
  auth:
99
99
  providers:
100
100
  - id: github
@@ -28,7 +28,7 @@ The OpenIDConnectProvider can be used to authenticate with a OpenID Connect comp
28
28
  Usually only the `wellKnown`, `clientId` and `clientSecret` properties need to be configured:
29
29
 
30
30
  ```yaml
31
- lowdefy: 7.1.0
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
@@ -33,7 +33,7 @@ Change the `lowdefy.yaml` to look like this:
33
33
 
34
34
  ```yaml
35
35
  name: lowdefy-project-template
36
- lowdefy: 7.1.0
36
+ lowdefy: 7.2.0
37
37
 
38
38
  pages:
39
39
  ################ -------- Copy from here -------- ################
@@ -18,7 +18,7 @@ In your `lowdefy.yaml` file, add the following:
18
18
 
19
19
  ```yaml
20
20
  name: lowdefy-project-template
21
- version: 7.1.0
21
+ version: 7.2.0
22
22
 
23
23
  ################ -------- Copy from here -------- ################
24
24
  connections:
@@ -51,7 +51,7 @@ In your `lowdefy.yaml` file, add the following:
51
51
 
52
52
  ```yaml
53
53
  name: lowdefy-project-template
54
- version: 7.1.0
54
+ version: 7.2.0
55
55
 
56
56
  connections:
57
57
  # ...
@@ -63,7 +63,7 @@ Made by a Lowdefy 🤖
63
63
  Open the `lowdefy.yaml` file using a text editor like [VS Code](https://code.visualstudio.com/download). The content of the file should look like this:
64
64
 
65
65
  ```yaml
66
- lowdefy: 7.1.0
66
+ lowdefy: 7.2.0
67
67
  name: Lowdefy starter
68
68
 
69
69
  pages:
@@ -11,7 +11,7 @@ For a login method to work you must configure **at least one mechanism** (`email
11
11
  A required signing secret, given as a `_secret` reference:
12
12
 
13
13
  ```yaml
14
- lowdefy: 7.1.0
14
+ lowdefy: 7.2.0
15
15
  auth:
16
16
  secret:
17
17
  _secret: BETTER_AUTH_SECRET
@@ -24,7 +24,7 @@ Also pin the app's canonical origin — the `url` of the current environment in
24
24
  Sessions, users, accounts and organizations are stored through an adapter:
25
25
 
26
26
  ```yaml
27
- lowdefy: 7.1.0
27
+ lowdefy: 7.2.0
28
28
  auth:
29
29
  database:
30
30
  id: auth_db
@@ -46,7 +46,7 @@ See the [MongoDBAuthAdapter](/MongoDBAuthAdapter) reference. Collection names fo
46
46
  - **Passkeys** — `auth.passkey` (`enabled`, `rpId`, `rpName`).
47
47
 
48
48
  ```yaml
49
- lowdefy: 7.1.0
49
+ lowdefy: 7.2.0
50
50
  auth:
51
51
  emailAndPassword:
52
52
  enabled: true
@@ -58,7 +58,7 @@ auth:
58
58
  `auth.email` references an **SMTP connection** by id — the connection owns `from`, `replyTo`, the transport and the delivery filter, and is shared by every auth email flow. There is no inline transport shape. Optionally map individual flows to your own notification templates:
59
59
 
60
60
  ```yaml
61
- lowdefy: 7.1.0
61
+ lowdefy: 7.2.0
62
62
  auth:
63
63
  email:
64
64
  connectionId: email # an SMTP connection in connections[]
@@ -94,7 +94,7 @@ BetterAuth ships no UI — your app owns its auth pages, and `auth.authPages` po
94
94
  | `magicLink` | — | landing page for the sign-in email (opt-in; see below) |
95
95
 
96
96
  ```yaml
97
- lowdefy: 7.1.0
97
+ lowdefy: 7.2.0
98
98
  auth:
99
99
  authPages:
100
100
  signIn: /login
@@ -113,7 +113,7 @@ A verification email links to Better Auth's verify endpoint, which confirms the
113
113
  Set the key and the sign-in email links to a page of your own instead, with the token and the callback destinations carried on its URL query. Fetching a Lowdefy page is harmless, so the token stays unspent until a real click runs [`MagicLinkVerify`](/MagicLinkVerify):
114
114
 
115
115
  ```yaml
116
- lowdefy: 7.1.0
116
+ lowdefy: 7.2.0
117
117
  auth:
118
118
  magicLink:
119
119
  enabled: true
@@ -161,7 +161,7 @@ See [Two-Factor Authentication](/two-factor) for the two-factor pages, and the [
161
161
  Database sessions. Length is `expiresIn` (seconds, default 604800 = 7 days); `updateAge` (default 86400) is how often an active session's expiry is refreshed:
162
162
 
163
163
  ```yaml
164
- lowdefy: 7.1.0
164
+ lowdefy: 7.2.0
165
165
  auth:
166
166
  session:
167
167
  expiresIn: 43200 # 12 hours in seconds
@@ -177,7 +177,7 @@ auth:
177
177
  - **API strategies** — `auth.strategies` authenticates non-session callers (server-to-server) with an `apiKey` or a `jwt`:
178
178
 
179
179
  ```yaml
180
- lowdefy: 7.1.0
180
+ lowdefy: 7.2.0
181
181
  auth:
182
182
  strategies:
183
183
  - id: service-key
@@ -231,7 +231,7 @@ Add the `auth.dev.mockUser` section to your `lowdefy.yaml`:
231
231
 
232
232
  ###### Configure a mock user for development
233
233
  ```yaml
234
- lowdefy: 7.1.0
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.1.0
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.1.0
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.1.0
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.1.0
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.1.0
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.1.0
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
 
@@ -5,7 +5,7 @@ A `Channel` websocket relays messages between clients: any subscriber can publis
5
5
  ## A Minimal Chat
6
6
 
7
7
  ```yaml
8
- lowdefy: 7.1.0
8
+ lowdefy: 7.2.0
9
9
 
10
10
  websockets:
11
11
  - id: team_chat
@@ -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.1.0
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.1.0",
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": "9a3abf01a934df3610372700d1f888e1558e5b5287209b1691ffed1d1db504ec"
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": "be6003a3d5dce08abc7e74e6766c5031d0710b73fc24204b8bd9a694bcdbaed8"
3304
+ "hash": "a799ed56573f37a7374538657a5c523e8b0a3bd3e35dabed7492bf705ca26873"
3305
3305
  },
3306
3306
  "user-authentication/auth-steps": {
3307
3307
  "files": [
3308
3308
  "users/auth-steps.yaml"
3309
3309
  ],
3310
- "hash": "46c67f8c9ecf56a5f18ba4f109bb011beb956daa90a0844405ab7cb396e1cf4d"
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": "8abd5b2a058647962e6bf8ea6e0a2deb64b369beb2a1bff8fe5aa79cb03dd06a"
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": "94fd498047ff9b857bc2ac3d2c8832f39e83beeeff6fb107a950635278c96eb8"
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": "9d27407b34aa8454525cb37e210a879f1e324fad8c777394f0cfc735c7a3f78c"
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": "2194aa8b560f6c3789f57e591c7d91dc1a0c34099ba968e69397d993e4d34089"
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.2.0",
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.2.0"
39
+ "@lowdefy/nunjucks": "7.3.0"
40
40
  },
41
41
  "publishConfig": {
42
42
  "access": "public"