@minca/core 0.1.16 → 0.1.18
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 +10 -9
- package/dist/elements/auth-styles.d.ts +1 -1
- package/dist/elements/auth-styles.d.ts.map +1 -1
- package/dist/elements/auth-styles.js +14 -5
- package/dist/elements/auth-styles.js.map +1 -1
- package/dist/elements/minca-auth.d.ts.map +1 -1
- package/dist/elements/minca-auth.js +18 -15
- package/dist/elements/minca-auth.js.map +1 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/network/ws-transport.d.ts.map +1 -1
- package/dist/network/ws-transport.js +3 -0
- package/dist/network/ws-transport.js.map +1 -1
- package/dist/node/actions.d.ts +5 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js +39 -20
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +2 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +2 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/node-carriers.d.ts.map +1 -1
- package/dist/node/node-carriers.js +6 -1
- package/dist/node/node-carriers.js.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-hosting.d.ts.map +1 -1
- package/dist/node/node-hosting.js +11 -4
- package/dist/node/node-hosting.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +14 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-holding.d.ts +7 -3
- package/dist/node/space-holding.d.ts.map +1 -1
- package/dist/node/space-holding.js +90 -18
- package/dist/node/space-holding.js.map +1 -1
- package/dist/node/space-peers.d.ts.map +1 -1
- package/dist/node/space-peers.js +58 -24
- package/dist/node/space-peers.js.map +1 -1
- package/dist/node/space-runtime.d.ts +11 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +22 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/space-writing.d.ts +2 -0
- package/dist/node/space-writing.d.ts.map +1 -1
- package/dist/node/space-writing.js +2 -0
- package/dist/node/space-writing.js.map +1 -1
- package/dist/node/types.d.ts +130 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/schemas/library/social.d.ts +258 -0
- package/dist/schemas/library/social.d.ts.map +1 -1
- package/dist/schemas/library/social.js +28 -1
- package/dist/schemas/library/social.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/hosting.d.ts.map +1 -1
- package/dist/session/hosting.js +8 -2
- package/dist/session/hosting.js.map +1 -1
- package/dist/space/presets.d.ts +2 -2
- package/dist/space/presets.d.ts.map +1 -1
- package/dist/space/presets.js +3 -2
- package/dist/space/presets.js.map +1 -1
- package/dist/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +212 -144
- package/docs/agents.md +198 -155
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -295
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +74 -163
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -61
- package/docs/inbox.md +138 -93
- package/docs/node.md +1072 -972
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +496 -418
- package/docs/spaces.md +261 -245
- package/docs/standard-library.md +473 -504
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -2
package/docs/automations.md
CHANGED
|
@@ -1,22 +1,60 @@
|
|
|
1
1
|
# Automations
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
10 votes, close it." "When someone mentions the bot, answer
|
|
5
|
-
|
|
6
|
-
thing for each, once; or does it at set times.
|
|
3
|
+
An automation does something when records in a space look a certain way.
|
|
4
|
+
"When a poll has 10 votes, close it." "When someone mentions the bot, answer
|
|
5
|
+
them." "When a channel passes 100 messages, say so in it."
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
> `std.automation` and `std.automation-run` like any other record. These are not the
|
|
13
|
-
> `rules` of a definition ([collections.md](collections.md#rules)), which
|
|
14
|
-
> every peer enforces and which can only refuse a version; these act.
|
|
7
|
+
Your app can run automations for a person, so can their agent, and so can a
|
|
8
|
+
bot a community adds. Unlike a collection's [rules](collections.md#rules),
|
|
9
|
+
which every peer enforces and which can only refuse a write, an automation
|
|
10
|
+
acts.
|
|
15
11
|
|
|
16
12
|
## An automation
|
|
17
13
|
|
|
18
|
-
An automation is a `std.automation` record
|
|
19
|
-
who made it:
|
|
14
|
+
An automation is a `std.automation` record. Everyone in the space sees what
|
|
15
|
+
runs and who made it. Here is one that tells you when someone mentions you:
|
|
16
|
+
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"name": "Mentioned",
|
|
20
|
+
"when": {
|
|
21
|
+
"query": { "collection": "std.message", "where": { "mentions": { "$contains": "$me" } } }
|
|
22
|
+
},
|
|
23
|
+
"then": { "kind": "notify", "text": "Someone mentioned you" },
|
|
24
|
+
"since": "2026-09-29T12:00:00Z"
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
`when` holds a query in [the query format](query-format.md). Each record it
|
|
29
|
+
finds sets the automation off, once. `then` says what to do. `$me` is whoever
|
|
30
|
+
runs the automation.
|
|
31
|
+
|
|
32
|
+
`since` is when it starts. A record that already matched before then is left
|
|
33
|
+
alone. That counts the record's last change, the newest record any `include`
|
|
34
|
+
found, and the newest record its computed fields read.
|
|
35
|
+
|
|
36
|
+
You save an automation like any other record:
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
import { automation } from '@minca/core/schemas';
|
|
40
|
+
|
|
41
|
+
await node.records.put(space.id, automation, {
|
|
42
|
+
name: 'Mentioned',
|
|
43
|
+
when: { query: { collection: 'std.message', where: { mentions: { $contains: '$me' } } } },
|
|
44
|
+
then: { kind: 'notify', text: 'Someone mentioned you' },
|
|
45
|
+
since: new Date().toISOString(),
|
|
46
|
+
});
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The space must have `std.automation` and `std.automation-run` defined.
|
|
50
|
+
Without them, nothing runs.
|
|
51
|
+
|
|
52
|
+
## Counting with `holds`
|
|
53
|
+
|
|
54
|
+
`holds` is a second filter, run over each result. It can read
|
|
55
|
+
`include:<name>`: what the query's `include` of that name found. That is a
|
|
56
|
+
number for an include with `count`, and a list of records otherwise. Use it
|
|
57
|
+
for what a query's own `where` can't say, like "more than 100 messages":
|
|
20
58
|
|
|
21
59
|
```json
|
|
22
60
|
{
|
|
@@ -38,116 +76,149 @@ who made it:
|
|
|
38
76
|
}
|
|
39
77
|
```
|
|
40
78
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
`
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
is the
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
clocks
|
|
64
|
-
been
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
79
|
+
What points at a record is counted by following links. So a relation must be
|
|
80
|
+
a [link](collections.md#links) to be counted.
|
|
81
|
+
|
|
82
|
+
## Who sets it off
|
|
83
|
+
|
|
84
|
+
`$me` works anywhere in `query` or `holds`. It is the automation's maker, or
|
|
85
|
+
the bot in `by`. So `{ "mentions": { "$contains": "$me" } }` means "mentions
|
|
86
|
+
me" for a person and for a bot alike.
|
|
87
|
+
|
|
88
|
+
Two more fields in `when` narrow who can set it off:
|
|
89
|
+
|
|
90
|
+
- `from` lists role names. Only records written by someone holding one of
|
|
91
|
+
them count. `"member"` is any member, founders included.
|
|
92
|
+
- `others: true` lets through only records someone other than the runner
|
|
93
|
+
wrote.
|
|
94
|
+
|
|
95
|
+
When a computed field in the filter made a record match, the record that set
|
|
96
|
+
it off is the one the field read. Say Bob's 👍 makes Alice's to-do done. That
|
|
97
|
+
was Bob's doing, so `others` lets it through and `from` asks about Bob's
|
|
98
|
+
roles. A 😡 after it changes nothing, so it sets nothing off. A to-do done
|
|
99
|
+
before the automation existed never does.
|
|
100
|
+
|
|
101
|
+
Which came last goes by the writers' clocks. Of two people whose 👍s made a
|
|
102
|
+
to-do done, either can claim to have been last.
|
|
103
|
+
|
|
104
|
+
## At set times
|
|
105
|
+
|
|
106
|
+
`every` runs an automation by itself, on a schedule. It takes five cron
|
|
107
|
+
fields, minute hour day month weekday, in the runner's local time:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"name": "Weekly reminder",
|
|
112
|
+
"every": "0 9 * * 1",
|
|
113
|
+
"then": { "kind": "notify", "text": "Plan the week" },
|
|
114
|
+
"since": "2026-09-29T12:00:00Z"
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Each field takes `*`, a number, a range `a-b`, a step `/n`, or a list with
|
|
119
|
+
commas. Weekday 0 or 7 is Sunday. When you give both a day and a weekday,
|
|
120
|
+
either one matches.
|
|
121
|
+
|
|
122
|
+
At those times the automation acts once, about no record. `$it` links nothing
|
|
123
|
+
and `{title}` stays as written. So an automation that changes a record needs a
|
|
124
|
+
`when`. An automation has `when`, `every`, or both.
|
|
80
125
|
|
|
81
126
|
## What it does
|
|
82
127
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
| `
|
|
86
|
-
|
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
89
|
-
|
|
90
|
-
`
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
`
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
`
|
|
128
|
+
`then.kind` picks one of four actions:
|
|
129
|
+
|
|
130
|
+
| `then.kind` | Fields | Does |
|
|
131
|
+
| ----------- | ----------------------------- | ------------------------------------------------------ |
|
|
132
|
+
| `notify` | `text` | Shows a notification on the device that runs it |
|
|
133
|
+
| `add` | `collection`, `text`, `links` | Adds a record made from `text`, carrying `links` |
|
|
134
|
+
| `set` | `field`, `value` | Sets one field of the record, if its maker may edit it |
|
|
135
|
+
| `ask` | `text` | Hands `text` to an agent, with what set it off |
|
|
136
|
+
|
|
137
|
+
`notify` goes through the runner's `notify`. `set` takes text, a number or a
|
|
138
|
+
boolean.
|
|
139
|
+
|
|
140
|
+
### Adding a record
|
|
141
|
+
|
|
142
|
+
`add` works with any collection whose records one line of text can make
|
|
143
|
+
(`quickAddBody`). Its naming field (`title`, `name`, `text`, …) gets `text`.
|
|
144
|
+
Every other field must have an empty value, a `default`, `false` or `[]`, or
|
|
145
|
+
not be required. A message, a comment and a task all work this way, and so
|
|
146
|
+
does a collection someone defined yesterday.
|
|
147
|
+
|
|
148
|
+
Each of `links` is `{ "rel", "to" }`. `to` is a record's key, or `"$it"`, the
|
|
149
|
+
record the automation is about. A message posted in a channel links `in` to
|
|
150
|
+
`"$it"`. One that shares the record links `shares`.
|
|
151
|
+
|
|
152
|
+
In `text`, `{title}` is what the record is called: its `title`, `name`,
|
|
153
|
+
`question` or `text`, or the runner's `title`. `{<include>}` is how many that
|
|
154
|
+
include found, like `{messages}` above.
|
|
155
|
+
|
|
156
|
+
### Asking an agent
|
|
157
|
+
|
|
158
|
+
`ask` is for an agent: `minca agent`, or a bot. A runner without one leaves
|
|
159
|
+
these automations to one that has.
|
|
160
|
+
|
|
161
|
+
The agent gets the automation's words as its maker's. What set it off comes as
|
|
162
|
+
data, never as instructions. The one exception is a writer who may instruct
|
|
163
|
+
the agent:
|
|
164
|
+
|
|
165
|
+
- For a bot, that is the automation's maker, or a member granted
|
|
166
|
+
`/std.automation/instruct` in the space who also holds every grant of the
|
|
167
|
+
bot's roles. Nobody reaches past their own grants through a bot.
|
|
168
|
+
- For a person's own agent, only the person.
|
|
169
|
+
|
|
170
|
+
Then the runner says so, and what they ask may be done. What their record
|
|
171
|
+
quotes, and the messages before it, stay data.
|
|
172
|
+
|
|
173
|
+
Holding every grant of a bot's roles is not the same as holding what the bot
|
|
174
|
+
can do. `.byCreator` grants read whose record it is, and the bot's own records
|
|
175
|
+
are the ones it wrote: a reply, a summary, an app it made for someone. So
|
|
176
|
+
whoever may instruct a bot can have it edit or delete a record it wrote for
|
|
177
|
+
someone else, though their own `.byCreator` grant would never reach it.
|
|
122
178
|
|
|
123
179
|
## Running
|
|
124
180
|
|
|
125
|
-
For each record an automation newly
|
|
126
|
-
`std.automation-run
|
|
127
|
-
the record it added (`made`).
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
181
|
+
For each record an automation newly matches, the runner writes a
|
|
182
|
+
`std.automation-run` first, then acts, then fills in the run: what it did, and
|
|
183
|
+
the key of any record it added (`made`).
|
|
184
|
+
|
|
185
|
+
There is one run per automation per record (`onePer: ['link:automation',
|
|
186
|
+
'link:about']`). That's how an automation acts once for each record, however
|
|
187
|
+
often and by however many devices it is looked at. The runs are its history,
|
|
188
|
+
for anyone in the space to see.
|
|
189
|
+
|
|
190
|
+
A runner that asks a model takes seconds, so it shows its progress in a
|
|
191
|
+
`std.activity` about the record that set it off, or about the automation when
|
|
192
|
+
it ran on a schedule. The state is `waiting` while queued, `working` while it
|
|
193
|
+
runs, then `done` or `failed`. In a space without `std.activity`, nothing is
|
|
194
|
+
shown and the automation runs as before ([standard
|
|
195
|
+
library](standard-library.md)).
|
|
196
|
+
|
|
197
|
+
### No loops
|
|
198
|
+
|
|
199
|
+
Nothing an automation added sets off an automation: a record some run names
|
|
200
|
+
in `made` is left alone. Otherwise "when a message is added, add a message"
|
|
201
|
+
would answer itself forever. Nothing the runner's agent or bot wrote itself
|
|
202
|
+
sets one off either, so an agent can't set itself off.
|
|
203
|
+
|
|
204
|
+
### Permissions
|
|
205
|
+
|
|
206
|
+
An automation writes as its runner, so it can do nothing its runner couldn't
|
|
207
|
+
do by hand. Who may change or delete one is up to the space's grants, as for
|
|
208
|
+
any record. In `community`, that is its maker, the moderators and the admins.
|
|
209
|
+
|
|
210
|
+
### Who runs an automation
|
|
211
|
+
|
|
212
|
+
Without `by`, its maker does:
|
|
213
|
+
|
|
214
|
+
- `runAutomations(node, space, maker)` runs them once.
|
|
215
|
+
- `startAutomations(node, { account })` runs them in every space the node
|
|
216
|
+
follows, again after each change, and at the times they name.
|
|
217
|
+
|
|
218
|
+
The example app runs them while it is open, but not those that ask or run on a
|
|
219
|
+
schedule (`timed: false`). `minca agent` runs all of them.
|
|
220
|
+
|
|
221
|
+
With `by`, only that bot runs it. Here a bot answers mentions from any member:
|
|
151
222
|
|
|
152
223
|
```json
|
|
153
224
|
{
|
|
@@ -162,41 +233,35 @@ A bot answering mentions, from anyone holding a role, run by the bot:
|
|
|
162
233
|
}
|
|
163
234
|
```
|
|
164
235
|
|
|
165
|
-
|
|
236
|
+
The bot runs it only while the maker may invoke `/std.automation/instruct` in
|
|
237
|
+
the space (`INSTRUCT`). A space grants that to a role like any other grant,
|
|
238
|
+
and the founders hold it. Peers never check it: it is the library's own
|
|
239
|
+
command ([spec 03 §2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
|
|
240
|
+
See [bots](bots.md) for more.
|
|
241
|
+
|
|
242
|
+
An automation whose current version an agent wrote, under a records-only note
|
|
243
|
+
(`recordsOnly`), runs nowhere. An agent may suggest one, and it waits until
|
|
244
|
+
the person saves it themselves.
|
|
245
|
+
|
|
246
|
+
Two runners of one account, say an app and an agent, may both claim a record
|
|
247
|
+
before either hears of the other. `startAutomations` waits `claimMs` after
|
|
248
|
+
claiming. The earlier claim acts and the later one is taken back.
|
|
166
249
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
([spec 03 §2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
|
|
177
|
-
The space's founders hold it.
|
|
178
|
-
- An automation whose current version was written under a records-only note
|
|
179
|
-
(`recordsOnly`, an agent's) runs nowhere: an agent may suggest one, and it
|
|
180
|
-
waits until the person saves it themselves.
|
|
181
|
-
|
|
182
|
-
Two runners of one account, an app and an agent, may both claim a record
|
|
183
|
-
before either hears the other. `startAutomations` waits `claimMs` after claiming;
|
|
184
|
-
the earlier claim acts, and the later is taken back. Nothing runs while every
|
|
185
|
-
runner is closed: to keep automations running with every device off, run
|
|
186
|
-
`minca agent --no-chat`, or a bot on a host.
|
|
187
|
-
|
|
188
|
-
_Source: `packages/core/src/schemas/automations.ts` (`automation`, `automationRun`, `checkAutomation`, `matching`, `act`, `automationsFor`, `runAutomations`, `startAutomations`, `fillAutomationText`, `IT`, `ME`), `packages/core/src/schemas/cron.ts`, `packages/core/src/schema/quick-add.ts` (`quickAddBody`), `packages/core/src/query/filter.ts` (`checkFilter`, `matches`), `packages/cli/src/main.ts` (`runAgent`), `packages/cli/src/agent-automations.ts` (`triggerPrompt`), `apps/example/src/automations.ts` (`compile`, `useRunAutomations`). Tests: `packages/core/tests/automation-records.test.ts`, `packages/core/tests/automation-runners.test.ts` (all)._
|
|
250
|
+
Nothing runs while every runner is closed. To keep automations running with
|
|
251
|
+
every device off, run `minca agent --no-chat`, or a bot on a host.
|
|
252
|
+
|
|
253
|
+
### Fields
|
|
254
|
+
|
|
255
|
+
Every field of an automation is listed under
|
|
256
|
+
[`Automation`](https://minca.dev/api/schemas/interfaces/Automation/), and how
|
|
257
|
+
a runner is set up under
|
|
258
|
+
[`startAutomations`](https://minca.dev/api/schemas/functions/startAutomations/).
|
|
189
259
|
|
|
190
260
|
## The account's own
|
|
191
261
|
|
|
192
262
|
"Let me know when someone mentions me, in any of my spaces." An automation
|
|
193
|
-
kept in the account registry
|
|
194
|
-
|
|
195
|
-
`std.automation`'s, with three more fields, kept as `sys.automation` at
|
|
196
|
-
`automation:<id>` ([spec 03 §13.2](../../../spec/03-spaces.md)). A system
|
|
197
|
-
collection has no definition, so no key of the account, an app given all of
|
|
198
|
-
it included, can redefine it to stop the person pausing or removing one. For
|
|
199
|
-
now it only notifies:
|
|
263
|
+
kept in the account registry, not in a space, is the account's own. Nobody
|
|
264
|
+
else sees it, and it looks at the spaces it names. For now it only notifies:
|
|
200
265
|
|
|
201
266
|
```json
|
|
202
267
|
{
|
|
@@ -213,71 +278,98 @@ now it only notifies:
|
|
|
213
278
|
}
|
|
214
279
|
```
|
|
215
280
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
| `open` | Optional. Where clicking its notification goes, an `https://` address. Default: the home. |
|
|
220
|
-
| `app` | Optional. The app that proposed it, `{ origin, name? }`, by the origin the browser reported. |
|
|
221
|
-
|
|
222
|
-
It must check out as one (`checkOwnAutomation`): `then.kind` is `notify`; no
|
|
223
|
-
`every` and no `by`, since the account runs it as records are written;
|
|
224
|
-
`when.query` is one collection and, optionally, a `where` over each record
|
|
225
|
-
alone (its body, its [computed fields](computed.md), `link:<role>`, `@key`,
|
|
226
|
-
`@collection`, `@createdBy`, `@createdAt`), with no `include`, and no
|
|
227
|
-
`holds` or `from`. `$me` is the account.
|
|
228
|
-
|
|
229
|
-
It notifies about a record when the record **comes to match**: when it is
|
|
230
|
-
written, or, for a `where` that names a computed field, when something that
|
|
231
|
-
field reads is, as a 👍 can make a todo done. Once per record: one edited
|
|
232
|
-
out of matching and back in is not news again, so no one can notify the
|
|
233
|
-
account over and over with one record. What sets it off must be written
|
|
234
|
-
after `since` and within the last day, and with `others`, by someone else.
|
|
235
|
-
"Newest" and "within the last day" go by the clock of whoever wrote it.
|
|
236
|
-
|
|
237
|
-
**Apps propose them**, the person says yes in the account home, and the home
|
|
238
|
-
writes them, naming the app ([spec 06 §2.11](../../../spec/06-nodes-and-sessions.md), whose `Proposal` is the shape below).
|
|
239
|
-
An app describes what it can notify about with `notifyOn`:
|
|
281
|
+
It is a `std.automation` body with three more fields: `spaces`, the spaces it
|
|
282
|
+
looks at, `open`, where its notification leads, and `app`, the app that
|
|
283
|
+
proposed it ([`Automation`](https://minca.dev/api/schemas/interfaces/Automation/)).
|
|
240
284
|
|
|
241
|
-
|
|
242
|
-
|
|
285
|
+
It is kept as `sys.automation` at `automation:<id>`. A system collection has
|
|
286
|
+
no definition, so no key of the account can redefine it to stop the person
|
|
287
|
+
pausing or removing one. That includes an app given all of it.
|
|
288
|
+
|
|
289
|
+
It must pass `checkOwnAutomation`:
|
|
290
|
+
|
|
291
|
+
- `then.kind` is `notify`.
|
|
292
|
+
- No `every` and no `by`: the account runs it as records are written.
|
|
293
|
+
- `when.query` names one collection, with no `include`. It may have a `where`
|
|
294
|
+
over each record alone: its body, its [computed fields](computed.md),
|
|
295
|
+
`link:<role>`, `@key`, `@collection`, `@createdBy` and `@createdAt`.
|
|
296
|
+
- No `holds` and no `from`. `$me` is the account.
|
|
297
|
+
|
|
298
|
+
It notifies about a record when the record **comes to match**. That is when
|
|
299
|
+
the record is written, or, for a `where` that names a computed field, when
|
|
300
|
+
something the field reads is written, the way a 👍 can make a to-do done. It
|
|
301
|
+
notifies once per record. A record edited out of matching and back in is not
|
|
302
|
+
news again, so nobody can notify the account over and over with one record.
|
|
303
|
+
|
|
304
|
+
What sets it off must be written after `since` and within the last day, and,
|
|
305
|
+
with `others`, by someone else. Both go by the clock of whoever wrote it.
|
|
306
|
+
|
|
307
|
+
[Spec 03 §13.2](../../../spec/03-spaces.md).
|
|
308
|
+
|
|
309
|
+
### Proposing one from an app
|
|
243
310
|
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
311
|
+
Apps propose these, the person says yes in the account home, and the home
|
|
312
|
+
writes them, naming the app. Describe what your app can notify about with
|
|
313
|
+
`notifyOn`:
|
|
314
|
+
|
|
315
|
+
```tsx
|
|
316
|
+
import { notifyOn } from '@minca/core/schemas';
|
|
317
|
+
import { useConnection } from '@minca/react';
|
|
318
|
+
|
|
319
|
+
function NotifyMe() {
|
|
320
|
+
const { connection } = useConnection();
|
|
321
|
+
const propose = () =>
|
|
322
|
+
connection.propose([
|
|
323
|
+
notifyOn('Mentioned', 'std.message', { mentions: { $contains: '$me' } }),
|
|
324
|
+
{ ...notifyOn('New message here', 'std.message'), spaces: [space.id] },
|
|
325
|
+
]);
|
|
326
|
+
return <button onClick={propose}>Notify me</button>;
|
|
327
|
+
}
|
|
248
328
|
```
|
|
249
329
|
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
`
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
330
|
+
`propose` opens the home, so call it from a click.
|
|
331
|
+
|
|
332
|
+
A proposal leaves out what the home fills in. `then` notifies with the
|
|
333
|
+
proposal's name, `when.others` is true, `spaces` is every space the app may
|
|
334
|
+
reach, `open` is the app's address, and `since` is now. An `open` you give
|
|
335
|
+
must be on your app's own site. One request takes 1 to 8 proposals.
|
|
336
|
+
|
|
337
|
+
While your app runs, it shows what they match itself (`watchNotifications`).
|
|
338
|
+
`node.automations` lists, pauses and removes them wherever the account key is.
|
|
339
|
+
|
|
340
|
+
[Spec 06 §2.11](../../../spec/06-nodes-and-sessions.md) defines the
|
|
341
|
+
`Proposal` shape.
|
|
342
|
+
|
|
343
|
+
### Waking an app through a carrier
|
|
344
|
+
|
|
345
|
+
A carrier can't read, so it can't tell which records match. Instead, each
|
|
346
|
+
device with the account key copies each automation into every carry space as
|
|
347
|
+
a wake (`sys.wake`). A wake holds the collection, the spaces, `others`, and,
|
|
348
|
+
in each space, the tags of the topic values its `where` requires. When a
|
|
349
|
+
matching record arrives, the carrier wakes the app, and the app judges it.
|
|
350
|
+
|
|
351
|
+
A condition requires values when it is on a field the space declares a topic,
|
|
352
|
+
at the top of `where` or in an `$and` there: `field: value`, `$eq`,
|
|
353
|
+
`$contains` or `$in`. The first such condition gives the tags, one per value.
|
|
354
|
+
So "near me" as `{ "place.cells": { "$in": [nine cells] } }` is nine tags.
|
|
355
|
+
|
|
356
|
+
- A space where `where` requires no topic value gets no tags. Any new record
|
|
357
|
+
of the collection wakes the app, which turns down what `where` doesn't
|
|
358
|
+
match.
|
|
359
|
+
- A private space whose key the device lacks gets an empty list, and wakes
|
|
360
|
+
nothing.
|
|
269
361
|
|
|
270
362
|
A `where` that names a computed field changes when what the field reads is
|
|
271
|
-
written
|
|
272
|
-
reads (`wake:<id>:<collection>`), with no tags
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
363
|
+
written. So each device also writes a wake for each collection that field
|
|
364
|
+
reads (`wake:<id>:<collection>`), with no tags. Any new 👍 in those spaces
|
|
365
|
+
wakes the app, which works the field out and judges. Only the fields the
|
|
366
|
+
`where` names count. A filter whose fields read more than four collections
|
|
367
|
+
gets no more wakes than its own, so a definition can't make every member's
|
|
368
|
+
devices write a wake per name it lists.
|
|
277
369
|
|
|
278
370
|
A wake can only let through more than the app would, never less, with one
|
|
279
|
-
exception
|
|
371
|
+
exception. `$contains` on a text field matches part of it, and a tag only a
|
|
280
372
|
whole value. Mark as topics only fields that hold whole values: people,
|
|
281
373
|
links, cells.
|
|
282
374
|
|
|
283
|
-
|
|
375
|
+
[Spec 03 §15](../../../spec/03-spaces.md).
|