@minca/core 0.1.17 → 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.
Files changed (86) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +2 -0
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/node-contacts.d.ts.map +1 -1
  22. package/dist/node/node-contacts.js +1 -0
  23. package/dist/node/node-contacts.js.map +1 -1
  24. package/dist/node/node-records.d.ts.map +1 -1
  25. package/dist/node/node-records.js +6 -1
  26. package/dist/node/node-records.js.map +1 -1
  27. package/dist/node/node.d.ts.map +1 -1
  28. package/dist/node/node.js +13 -1
  29. package/dist/node/node.js.map +1 -1
  30. package/dist/node/remote.d.ts.map +1 -1
  31. package/dist/node/remote.js +7 -1
  32. package/dist/node/remote.js.map +1 -1
  33. package/dist/node/space-runtime.d.ts +5 -3
  34. package/dist/node/space-runtime.d.ts.map +1 -1
  35. package/dist/node/space-runtime.js +3 -1
  36. package/dist/node/space-runtime.js.map +1 -1
  37. package/dist/node/types.d.ts +112 -36
  38. package/dist/node/types.d.ts.map +1 -1
  39. package/dist/query/types.d.ts +1 -0
  40. package/dist/query/types.d.ts.map +1 -1
  41. package/dist/query/types.js.map +1 -1
  42. package/dist/records/contract-builder.d.ts +22 -6
  43. package/dist/records/contract-builder.d.ts.map +1 -1
  44. package/dist/records/contract-builder.js.map +1 -1
  45. package/dist/schemas/automations.d.ts +6 -2
  46. package/dist/schemas/automations.d.ts.map +1 -1
  47. package/dist/schemas/automations.js.map +1 -1
  48. package/dist/schemas/connectors.d.ts +4 -3
  49. package/dist/schemas/connectors.d.ts.map +1 -1
  50. package/dist/schemas/connectors.js +4 -3
  51. package/dist/schemas/connectors.js.map +1 -1
  52. package/dist/schemas/library/media.js +1 -1
  53. package/dist/schemas/library/media.js.map +1 -1
  54. package/dist/session/auth.d.ts +7 -3
  55. package/dist/session/auth.d.ts.map +1 -1
  56. package/dist/session/auth.js.map +1 -1
  57. package/dist/storage/blob-store.d.ts +3 -0
  58. package/dist/storage/blob-store.d.ts.map +1 -1
  59. package/dist/types.d.ts +11 -2
  60. package/dist/types.d.ts.map +1 -1
  61. package/dist/types.js.map +1 -1
  62. package/docs/README.md +86 -93
  63. package/docs/actions.md +213 -152
  64. package/docs/agents.md +198 -167
  65. package/docs/automations.md +296 -204
  66. package/docs/blueprints-and-guides.md +405 -311
  67. package/docs/bots.md +208 -134
  68. package/docs/building-an-app.md +74 -163
  69. package/docs/collections.md +248 -328
  70. package/docs/computed.md +112 -89
  71. package/docs/contacts.md +151 -112
  72. package/docs/contracts.md +299 -120
  73. package/docs/direct-messages.md +80 -65
  74. package/docs/inbox.md +138 -93
  75. package/docs/node.md +1072 -996
  76. package/docs/permissions.md +142 -0
  77. package/docs/proposing-collections.md +74 -55
  78. package/docs/query-format.md +150 -126
  79. package/docs/records-and-queries.md +205 -126
  80. package/docs/sign-in.md +496 -418
  81. package/docs/spaces.md +261 -246
  82. package/docs/standard-library.md +473 -526
  83. package/docs/storage.md +325 -348
  84. package/docs/usernames.md +164 -97
  85. package/docs/warrants.md +100 -67
  86. package/package.json +1 -1
@@ -1,22 +1,60 @@
1
1
  # Automations
2
2
 
3
- "When a channel has more than 100 messages, say so in it." "When a poll has
4
- 10 votes, close it." "When someone mentions the bot, answer them." An automation
5
- finds records with a query, keeps those a filter matches, and does one
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
- One kind of record for all of these, whoever runs it: a person's app, their
9
- agent, or a bot a community added.
10
-
11
- > Not protocol. A peer that has never heard of automations syncs, stores and judges
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, so everyone in the space sees what runs and
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
- | Field | Meaning |
42
- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
43
- | `name` | What people call it |
44
- | `when` | `query`: a query in [the query format](query-format.md). `holds`, optional: a filter each result must match. `from` and `others`, optional: below. |
45
- | `every` | Optional. Five cron fields, minute hour day month weekday, in the runner's local time: the automation also runs by itself then. An automation has `when`, `every`, or both. |
46
- | `then` | What it does, below |
47
- | `by` | Optional. The DID of the bot that runs it; without it, its maker's own devices and agent do ([Who runs an automation](#who-runs-an-automation)) |
48
- | `picked` | Optional. How an app's builder showed the automation, so it can show it in words and open it again. Never read to run it. |
49
- | `paused` | Optional. Kept, but not run. |
50
- | `since` | Nothing that came to hold before this sets it off: a record whose last change, the newest record any include found, and the newest its computed fields read are older is left alone. |
51
-
52
- `"$me"`, anywhere in `query` or `holds`, is whoever runs the automation: its maker,
53
- or the bot in `by`. So "a message mentioning me" is `{ "mentions":
54
- { "$contains": "$me" } }` for a person and for a bot alike. `from` lists role
55
- names; only records written by someone holding one of them set the automation off,
56
- and `"member"` is any member at all, the founders included. With `others`,
57
- only records someone other than its runner wrote set it off. What sets it off
58
- is the record, or, when a computed field its filter names made it hold, the
59
- record that field read whose coming made it hold: Bob's 👍 that made Alice's
60
- todo done is Bob's, so `others` lets it through and `from` asks Bob's roles.
61
- A 😡 after it changes nothing, so it sets nothing off, and a todo done before
62
- the automation was made never does. Which came last goes by the writers'
63
- clocks, so of two people whose 👍s made it done, either can claim to have
64
- been the last.
65
-
66
- `every` uses `*`, a number, a range `a-b`, a step `/n` and lists with commas;
67
- weekday 0 or 7 is Sunday; a day and a weekday both given means either. At
68
- those times the automation acts once, about no record: `$it` links nothing and
69
- `{title}` stays as written, so an automation that changes a record needs a `when`.
70
-
71
- `holds` is a filter in [the query format](query-format.md) over each result,
72
- which may also read `include:<name>`: what the query's `include` of that name
73
- found for the record, a number for an include with `count`, else the list of
74
- records. Use it for what a query's own `where` can't say, like "more than 100
75
- messages".
76
-
77
- Anything a query can find, an automation can act on. What points at a record is
78
- counted by following links, so a relation must be a link to be counted
79
- ([collections.md](collections.md#links)).
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
- | `then.kind` | Fields | Does |
84
- | ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------- |
85
- | `notify` | `text` | Shows a notification on the device that runs it, through the runner's `notify` |
86
- | `add` | `collection`, `text`, `links` | Adds a record to `collection`, made from `text` alone (`quickAddBody`), carrying `links` |
87
- | `set` | `field`, `value` (text, number, bool) | Sets one field of the record, when its maker may edit it |
88
- | `ask` | `text` | Gives `text`, in the maker's words, to an agent that runs automations, with what set it off |
89
-
90
- `add` works with any collection whose records one line of text can make: its
91
- naming field (`title`, `name`, `text`, …) is filled with `text`, and every
92
- other field must have an empty value, a `default`, `false` or `[]`, or not be
93
- required. A message, a comment and a task are all added this way, and so is a
94
- collection someone defined yesterday. Each of `links` is `{ "rel", "to" }`,
95
- where `to` is a record's key or `"$it"`, the record the automation holds for: a
96
- message posted in a channel the automation is about links `channel` to `"$it"`, one
97
- that shares it links `shares`.
98
-
99
- In `text`, `{title}` is what the record is called (its `title`, `name`,
100
- `question` or `text`, or the runner's `title`), and `{<include>}` how many
101
- that include found: `{messages}` above.
102
-
103
- `ask` is for an agent: `minca agent`, or a bot. It is told the automation's words
104
- as its maker's, and what set it off as data, never as instructions, with one
105
- exception: when whoever wrote that record may instruct it (for a bot, the
106
- automation's maker or any member granted `/std.automation/instruct` in the space, and
107
- only one who holds every grant of the bot's roles, so nobody reaches past
108
- their own grants through it; for a person's own agent, only the person),
109
- the runner says so, and what they ask
110
- in it may be done. What it quotes, and the messages before it, stay data. A
111
- runner without one leaves automations that ask to one that has.
112
-
113
- Holding every grant of the bot's roles is not holding what the bot can do
114
- with them. `.byCreator` reads whose record it is, and when the bot acts, its
115
- own records are the ones it wrote: a reply, a summary, an app it made for
116
- someone. So whoever may instruct a bot can have it edit or delete a record
117
- it wrote for someone else, though their own `.byCreator` grant would never
118
- reach that record.
119
-
120
- _Source:_ `packages/cli/src/agent-automations.ts` (`triggerPrompt`, `ruleContext`,
121
- `writerInstructs`); `packages/cli/tests/agent-automations.test.ts`.
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 holds for, the runner first writes a
126
- `std.automation-run`, then acts, then says in the run what it did, and the key of
127
- the record it added (`made`). A run is one per automation per record (`onePer:
128
- ['link:automation', 'link:about']`), which is how an automation acts once for each record
129
- however often, and by however many devices, it is looked at; it is the automation's
130
- history for anyone in the space.
131
-
132
- A runner that asks a model, which takes seconds, also says so where people
133
- look: its `std.activity` about the record that set the automation off (or the
134
- automation, for one set off by the time) is `waiting` while it is queued behind
135
- another, `working` while it runs, then `done` or `failed`. The space must
136
- keep `std.activity`; where it doesn't, nothing is shown and the automation runs as
137
- before ([standard library](standard-library.md)).
138
-
139
- Nothing an automation added sets off an automation: a record some run names in `made` is
140
- left alone. Without that, "when a message is added, add a message" would
141
- answer itself forever, and two automations could answer each other. Nor does
142
- anything the runner's agent, or the bot, wrote itself, so an agent asked to
143
- act can't set itself off.
144
-
145
- Whatever an automation writes is written as its runner, so an automation can do nothing its
146
- runner couldn't do by hand. Who may change or delete one is the space's
147
- grants, as for any record: in `community`, its maker, the moderators and the
148
- admins.
149
-
150
- A bot answering mentions, from anyone holding a role, run by the bot:
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
- ### Who runs an automation
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
- - Without `by`, its maker: `runAutomations(node, space, maker)` once, or
168
- `startAutomations(node, { account })`, which runs them in every space the node
169
- follows, again after each change, and at the times they name. The example
170
- app runs them while it is open, but not those that ask or run at set times
171
- (`timed: false`); `minca agent` runs all of them.
172
- - With `by`, only that bot, and only while the maker may invoke
173
- `/std.automation/instruct` in the space (`INSTRUCT`): a grant held by a role says
174
- who may direct a bot there. It is a command of the library's own: peers
175
- never check it, and a space grants it like any other, to a role
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 rather than in a space is the account's own:
194
- nobody else sees it, and it looks at the spaces it names. Its body is a
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
- | Field | Meaning |
217
- | -------- | -------------------------------------------------------------------------------------------- |
218
- | `spaces` | `"all"`, every space of the account, or a list of space ids |
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
- ```ts
242
- import { notifyOn } from '@minca/core/schemas';
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
- connection.propose([
245
- notifyOn('Mentioned', 'std.message', { mentions: { $contains: '$me' } }),
246
- { ...notifyOn('New message in Club', 'std.message'), spaces: [club] },
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
- A proposal leaves out what the home fills in: `then` defaults to notifying
251
- with its name, `when.others` to true, `spaces` to all the app may reach,
252
- `open` to the app's address, and `since` to now. The app shows what they
253
- match itself, while it runs (`watchNotifications`), and
254
- `node.automations` lists, pauses and removes them where the account key is.
255
-
256
- **Carriers wake an app for them.** A carrier can't read, so each device with
257
- the account key copies each one into every carry space as a wake (`sys.wake`,
258
- [spec 03 §15](../../../spec/03-spaces.md)): the collection, the spaces,
259
- `others`, and in each space, the tags of the values its `where` requires of
260
- a topic. A condition requires values when it is on a field the space's
261
- definition declares a topic and is at the top of `where`, or in an `$and`
262
- there: `field: value`, `$eq`, `$contains` or `$in`. The first such
263
- condition gives the tags: one per value, so "near me" as
264
- `{ "place.cells": { "$in": [nine cells] } }` is nine tags. A space where
265
- `where` requires no topic value gets no tags, so any new record of the
266
- collection wakes the app, which then turns down what `where` doesn't match.
267
- A private space whose key the device lacks gets an empty list, and wakes
268
- nothing.
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, so each device also writes a wake for each collection that field
272
- reads (`wake:<id>:<collection>`), with no tags but the empty lists: any new 👍
273
- in those spaces wakes the app, which works the field out and judges. Only
274
- the fields the `where` names count, and a filter whose fields read more than
275
- four collections gets no more wakes than its own, so a definition can't make
276
- every member's devices write a wake per name it lists.
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: `$contains` on a text field matches part of it, and a tag only a
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
- _Source: `packages/core/src/space/own-automations.ts` (`checkOwnAutomation`, `notifyOn`, `checkProposal`, `fromProposal`, `wakeFor`, `linkedWakes`, `holdsFor`, `setsOff`), `packages/core/src/query/computed.ts` (`linkedReads`, `lastRead`), `packages/core/src/node/node-carriers.ts` (`automations`, `syncPasses`), `packages/core/src/node/watch-notifications.ts`, `packages/core/src/schemas/automations.ts` (`matching`). Tests: `packages/core/tests/topics.test.ts` ("an automation of the account’s own: its where"), `packages/core/tests/carrier.test.ts` ("notifications through a carrier"), `packages/core/tests/connect.test.ts` ("an app proposing automations", "an app showing its own notifications"), `packages/core/tests/watch-notifications.test.ts`, `packages/core/tests/computed.test.ts` ("computed: what watches a filter on them"), `packages/core/tests/geo.test.ts`._
375
+ [Spec 03 §15](../../../spec/03-spaces.md).