@lowdefy/docs-content 7.1.0 → 7.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/content/actions/login.md +1 -1
  2. package/content/actions/posthoginit.md +1 -1
  3. package/content/adapter-reference/mongodbauthadapter.md +2 -2
  4. package/content/agents/agents-introduction.md +41 -1
  5. package/content/callback-reference/auth0logoutcallback.md +1 -1
  6. package/content/concepts/ai-agent-docs.md +116 -108
  7. package/content/concepts/blocks.md +1 -1
  8. package/content/concepts/connections-and-requests.md +8 -8
  9. package/content/concepts/custom-html.md +1 -1
  10. package/content/concepts/dynamic-page-content.md +26 -15
  11. package/content/concepts/events-and-actions.md +24 -0
  12. package/content/concepts/logger.md +1 -1
  13. package/content/concepts/lowdefy-api.md +81 -14
  14. package/content/concepts/lowdefy-schema.md +11 -0
  15. package/content/concepts/mobile-apps.md +110 -0
  16. package/content/concepts/page-and-app-state.md +2 -2
  17. package/content/concepts/theming.md +1 -1
  18. package/content/connections/axioshttp.md +1 -1
  19. package/content/connections/mongodb.md +22 -6
  20. package/content/controls/reject.md +2 -2
  21. package/content/deployment/vercel.md +1 -1
  22. package/content/display-blocks/aggrid.md +1 -1
  23. package/content/display-blocks/search.md +86 -2
  24. package/content/display-blocks/table.md +154 -9
  25. package/content/input-blocks/ratingslider.md +1 -0
  26. package/content/input-blocks/tableinput.md +12 -4
  27. package/content/input-blocks/tiptapinput.md +3 -2
  28. package/content/input-blocks/tiptapmentioninput.md +3 -2
  29. package/content/migration/v3-to-v4.md +2 -2
  30. package/content/operators/_api.md +11 -9
  31. package/content/operators/_base64.md +2 -2
  32. package/content/operators/_log.md +1 -1
  33. package/content/operators/_ref.md +6 -6
  34. package/content/plugins/plugins-introduction.md +13 -0
  35. package/content/plugins/posthog.md +1 -1
  36. package/content/provider-reference/auth-js-providers.md +2 -2
  37. package/content/provider-reference/openidconnectprovider.md +1 -1
  38. package/content/reference/cli.md +164 -0
  39. package/content/testing/config-tests.md +4 -2
  40. package/content/tutorial/tutorial-create-page.md +1 -1
  41. package/content/tutorial/tutorial-requests-api.md +1 -1
  42. package/content/tutorial/tutorial-requests-sql.md +1 -1
  43. package/content/tutorial/tutorial-start.md +1 -1
  44. package/content/user-authentication/auth-configuration.md +9 -9
  45. package/content/user-authentication/auth-steps.md +6 -4
  46. package/content/user-authentication/organizations.md +68 -1
  47. package/content/user-authentication/protected-pages-apis.md +4 -4
  48. package/content/user-authentication/roles.md +2 -2
  49. package/content/user-authentication/user-object.md +2 -2
  50. package/content/websockets/websocket-publish.md +1 -1
  51. package/content/websockets/websockets-introduction.md +54 -2
  52. package/index.json +74 -59
  53. package/package.json +2 -2
@@ -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.0.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.0.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.0.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.0.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.0.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.0.0
27
+ lowdefy: 7.2.0
28
28
  auth:
29
29
  pages:
30
30
  public: true
@@ -20,11 +20,11 @@ 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
 
27
- A caller resolved from an [API strategy](/auth-configuration) (`apiKey`, `jwt`) sits outside the membership boundary: it carries `id`, `roles`, `attributes` and `auth_method`, but no organization, `name`, `image`, `profile` or `two_factor_enrolled`. A signed-in user who holds only a pending invitation (before they accept, under `tenant`) is an *awaiting-organization* caller — known to the always-public accept page, refused everywhere else.
27
+ A caller resolved from an [API strategy](/auth-configuration) (`apiKey`, `jwt`) sits outside the membership boundary: it carries `id`, `roles`, `attributes` and `auth_method`, but no organization, `name`, `image`, `profile` or `two_factor_enrolled`. A signed-in user who holds only a pending invitation (before they accept) is an *awaiting-organization* caller — known to the always-public accept page, refused everywhere else. Under `pinned`, only an invitation to the app's organization counts.
28
28
 
29
29
  ## Examples
30
30
 
@@ -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.0.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.0.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`.