@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
package/docs/spaces.md CHANGED
@@ -1,275 +1,290 @@
1
- # Spaces in the library
1
+ # Spaces
2
2
 
3
- What the library chooses when it creates, invites to, reads and keeps
4
- spaces: constitution templates, invite defaults, profiles, the space manager, and how
5
- an app shows the account's own automations.
3
+ A space is a shared place: the records in it, and the people who may read
4
+ and write them. On this page we'll make a space, invite someone to it, and
5
+ then look at how a space decides who may do what.
6
6
 
7
- > Not protocol. None of this is checked by a peer, and another implementation
8
- > may do it differently and still interoperate. What peers must agree on about
9
- > spaces is in [spec 03 — Spaces](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
7
+ ## Making a space
10
8
 
11
- ## Presets
9
+ Give it a name, say whether it is private, and pick a preset for its roles:
10
+
11
+ ```ts
12
+ import { rolePresets } from '@minca/core';
13
+
14
+ const space = await node.spaces.create({
15
+ name: 'Bike co-op',
16
+ visibility: 'private',
17
+ ...rolePresets.community,
18
+ });
19
+ ```
20
+
21
+ A `private` space encrypts every record with the space's key, so only its
22
+ members can read it. A `public` one can be read by anyone who has it.
23
+
24
+ You are the space's founder. With no preset, the space gets `solo`: just you.
25
+
26
+ ## Inviting someone
27
+
28
+ `invite` makes an invite, a string you send to someone:
12
29
 
13
- A preset is a constitution template: who sits at the top, the roles a space
14
- is founded with and the grants each holds, and the roles the creator starts
15
- with ([spec 03 §1–§2](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
16
- The protocol reads whatever a constitution names and never looks at a
17
- preset's name; these are a sensible start for an app. Spread one into
18
- `spaces.create`, change it, or write your own:
30
+ ```ts
31
+ const invite = await node.spaces.invite(space.id);
32
+ ```
33
+
34
+ On their side, `preview` shows what it is for, and `join` takes them in:
19
35
 
20
36
  ```ts
21
- await node.spaces.create({ name: 'Bike co-op', visibility: 'private', ...rolePresets.coop });
37
+ declare const invite: string;
38
+ // ---cut---
39
+ const preview = await node.spaces.preview(invite); // its name, who sent it, the role
40
+ const joined = await node.spaces.join(invite);
22
41
  ```
23
42
 
24
- | Preset | `top` | Roles and their grants |
25
- | ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
26
- | `solo` | `founders` | none: the founder alone |
27
- | `team` | `founders` | editor: `/record`; `/collection/define`; `/role/assign` with `.role == "editor"` |
28
- | `community` | `founders` | admin: `/record`, `/collection/define`, `/role/assign`, `/role/define` for every role but admin, `/role/unassign` and `/member/remove` of anyone not an admin, `/std.automation/instruct`, `/space/succeed`, `/key/change`, `/space/relays`, `/space/keepers`; moderator: `/record`, `/role/assign` with `.role == "member"`, `/std.automation/instruct`; member: `/record/write` and `/record/delete` where `.byCreator` is true, outside `STAFF_COLLECTIONS` |
29
- | `coop` | `none` | steward (the creator's): `/record`, `/collection/define`, `/role/define` for member, `/role/assign` and `/role/unassign` of member or steward, `/member/remove` of anyone, `/std.automation/instruct`, `/space/succeed`, `/key/change`, `/space/relays`, `/space/keepers`; member: as in `community`, and `/space/succeed` |
30
-
31
- Under `top: founders` the creator is the space's founder and holds every
32
- command whatever the roles say, so no `founders` preset needs a role for it.
33
- `cofounders` names others who found it too. Under `top: none` (`coop`) there
34
- is no founder: the creator holds only `creatorRoles`, here `steward`, and
35
- another steward can remove it.
36
-
37
- Each preset must say explicitly whether members may change each other's
38
- records: a grant of `/record/write` without a policy on `.byCreator` lets
39
- them. In `community` and `coop`, members change only what they made, and
40
- moderators or stewards anything.
41
-
42
- What `.roles` protects, and what it doesn't. "Of anyone not an admin" is a
43
- policy on the target's roles, read as of the remover's own view, which the
44
- remover chooses by what it names as seen (spec 03 §2.3, §3.2). It stops an
45
- admin who has seen another's promotion. It doesn't stop one who names a view
46
- from before it, or acts concurrently with it: `community` admins can still
47
- remove or demote each other that way. `.roles` protects only against a
48
- remover whose view includes the target's role. A space where that matters
49
- gives removal to fewer people, or to the founders alone.
50
-
51
- A role that may define itself can be locked by rival definitions (spec 03
52
- §2): two of its holders who rewrite it apart and disagree leave it holding
53
- only what they share, and if that drops `/role/define`, nobody in it can
54
- settle them. So a preset gives `/role/define` for a role to another role, or
55
- to the founders alone: in `community` the founders define admin, and admins
56
- define the rest. In `coop` stewards define member, and nobody defines
57
- steward: its grants are the constitution's, and changing them takes a
58
- successor.
59
-
60
- `STAFF_COLLECTIONS` are the standard collections only moderators start in a
61
- community: announcements, badges, awards, pins, labels, channels, hosts and
62
- the space's own profile (`std.space-profile`).
63
- Their definitions used to say so with `create` rules; now the template does.
64
-
65
- When a space is created with no roles, it gets `solo`. The account's derived
66
- spaces (the registry, the contacts space) use `solo`'s roles, none, byte for
67
- byte: their ids depend on it
68
- ([spec 03 §13.1](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
69
- Changing `solo` would change those ids, so it must not change.
70
-
71
- _Source: `packages/core/src/space/presets.ts` (`solo`, `team`, `community`, `coop`, `STAFF_COLLECTIONS`), `packages/core/src/space/grants.ts`, `packages/core/src/space/space-manager.ts` (`create`), `packages/core/src/node/node.ts` (`spaces.create`). Tests: `packages/core/tests/space.test.ts`, `packages/core/tests/space-profile.test.ts`, `packages/core/tests/roles.test.ts` ("definitions", "`community` admins can remove each other by naming a view before the promotion"), `packages/core/tests/constitution.test.ts` ("the templates are well formed", "a co-op: no founders…")._
72
-
73
- ## The top and founders
74
-
75
- `spaces.access(id)` says who is at the top: `top` (`founders` or `none`),
76
- each member's `founder`, and `founder` for this account. A founder may:
77
-
78
- - **step down** with `spaces.stepDown(id, { keep? })`: it stays, with the
79
- roles it holds, and is a founder no more. Given `keep`, it assigns itself
80
- that role first. With no role it would be no member, so the library
81
- refuses; to go altogether, `leave`. Stepping down strikes whatever this
82
- account did elsewhere that hadn't seen it, as leaving does, so do it from
83
- a device that has synced;
84
- - **leave**, with `spaces.leave(id)`, as anyone may.
85
-
86
- Nobody removes or demotes a founder but the founder itself, so an app shows
87
- no remove button on a founder, and a "Step down" button on your own row when
88
- you are one.
89
-
90
- **Headless.** `access.headless` is true when no founder is left and no
91
- member may define or assign any role. Members keep what their roles allow,
92
- but nobody can change roles, and nothing in the constitution can change. An
93
- app says so plainly ("No one can change roles here any more") and offers the
94
- way on: naming a successor (below), which any member may do once no member holds `/space/succeed`.
95
-
96
- _Source: `packages/core/src/node/space-membership.ts` (`stepDown`, `access`), `packages/core/src/space/roles.ts` (`headless`). Tests: `packages/core/tests/constitution.test.ts` ("stepping down", "a founder steps down, keeping a role…")._
43
+ By default the invite gives the `member` role. Pass `{ role: 'editor' }` for
44
+ another, or `{ write: false }` to let them read and not write.
45
+
46
+ An invite is long. For something to paste in a chat, ask for a short link,
47
+ about 85 characters:
48
+
49
+ ```ts
50
+ const link = await node.spaces.invite(space.id, { short: true });
51
+ ```
52
+
53
+ ## Invite links
54
+
55
+ A private invite carries the space's key, so put it after `#` in a link.
56
+ Browsers never send that part to a server. `@minca/react` has three helpers:
57
+
58
+ - `inviteLink(invite)` makes a link to the current page.
59
+ - `inviteFromLink(text)` takes the invite out of a pasted link.
60
+ - `useInviteLink()` reads the invite the page was opened with.
61
+
62
+ ## Leaving
63
+
64
+ ```ts
65
+ await node.spaces.leave(space.id);
66
+ ```
67
+
68
+ Anyone may leave, founders too.
69
+
70
+ ## Presets
71
+
72
+ A preset is a starting constitution: who sits at the top, and the roles the
73
+ space begins with. `solo`, `team`, `community` and `coop` are described in
74
+ [Permissions](permissions.md#presets).
97
75
 
98
76
  ## Successors
99
77
 
100
- A space whose constitution must change, or a headless one, moves on to a
101
- successor (spec 03 §2.7). With the library:
78
+ A space whose constitution must change, or a headless one, moves on to a new
79
+ space, its successor:
102
80
 
103
- 1. Create the new space naming the old: `spaces.create({ …, succeeds: oldId })`.
104
- 2. Name it in the old space: `spaces.succeed(oldId, newId)`. It needs
81
+ 1. Create the new space, naming the old:
82
+ `spaces.create({ …, succeeds: oldId })`.
83
+ 2. Name it in the old space: `spaces.succeed(oldId, newId)`. This needs
105
84
  `/space/succeed`, or a place in a space where no member holds it. Where
106
85
  this node holds the new space, it refuses one whose constitution doesn't
107
86
  say it succeeds the old.
108
- 3. Tell members how to join it: an invite to the new space, posted in the
109
- old one (an announcement, a message). The succeed record carries only the
110
- new space's id.
87
+ 3. Tell members how to join: post an invite to the new space in the old one.
88
+ The succeed record carries only the new space's id.
111
89
 
112
- `spaces.access(oldId).successors` lists every space named, each with the
113
- accounts that named it: `[{ space, by }]`. A successor changes nothing in
114
- the old space; whoever stays carries on there.
90
+ A successor changes nothing in the old space. Whoever stays carries on there.
115
91
 
116
- What an app shows:
92
+ ### Showing successors
117
93
 
118
- - every successor named, **in no order**: never one as first, and never one
119
- picked for the member, since which community a member joins is theirs to
120
- choose. The list's order means nothing;
121
- - who named each, and whether each namer is still a member: a succeed stays
122
- named after its namer is removed;
123
- - that a space is a successor only once both hold: the new space's
124
- `succeeds` (`SpaceSummary.succeeds`, `preview(invite).space.succeeds`)
125
- names the old one, and the old one's `successors` names the new. An
126
- invite to a space that claims to succeed another, with no succeed for it
127
- there, is a copy, and is shown as one.
94
+ `spaces.access(oldId).successors` lists every space named, with who named
95
+ it ([`SpaceAccess`](https://minca.dev/api/core/interfaces/SpaceAccess/)).
96
+ Show:
128
97
 
129
- _Source: `packages/core/src/node/node.ts` (`spaces.succeed`), `packages/core/src/node/space-membership.ts` (`succeed`, `access`), `packages/core/src/space/space-manager.ts` (`previewInvite`). Tests: `packages/core/tests/constitution.test.ts` ("/space/succeed", "a successor: made with succeeds…")._
98
+ - **Every successor, in no order.** Never pick one for the member, or show
99
+ one first. Which community to join is theirs to choose.
100
+ - **Who named each**, and whether they are still a member. A succeed stays
101
+ after its namer is removed.
102
+ - **A successor only when both sides agree.** The new space's `succeeds`
103
+ (`SpaceSummary.succeeds`, `preview(invite).space.succeeds`) names the old,
104
+ and the old one's `successors` names the new. An invite to a space that
105
+ claims to succeed another, with no succeed for it there, is a copy. Show it
106
+ as one.
107
+
108
+ See [spec 03 §2.7](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
130
109
 
131
110
  ## Invites
132
111
 
133
- `node.spaces.invite(id, options?)`:
134
-
135
- - With no role given, it opens an invite for `member` when the inviter may
136
- assign it (`/role/assign` with `{ role, self: false, roles: [] }`), else for
137
- the first role by name it may assign. With none (as in `solo`), it makes a
138
- view-only invite. Opening an invite for a role needs the same grant as
139
- assigning it to someone holding nothing. Peers judge each join as the
140
- assignment the invite's opener makes, to whoever joins (spec 03 §4.5): an
141
- opener whose grant says `.self == false` can't join its own invite. A
142
- joiner judged in a view from before the opener lost the grant still gets
143
- in: to stop an invite, close it.
144
- - `write: false` always makes a view-only invite.
145
- - Each role invite gets its own fresh secret and its own `sys.invite` record,
146
- so one can be closed without the others.
147
- - The invite names the space's relays, or the inviter's own when the space
148
- names none, and the always-on nodes that hold it: the account's hosts and
149
- the space's own, at most 8, each pinned by its DID. A host that can't be
150
- described within three seconds is left out rather than hold the invite up.
151
- - `short: true` makes a short link (spec 03 §7.7), about 85 characters: the
152
- invite is sealed and left in the mailbox of the account's first host and of
153
- the first relay that takes it, and the link names those two. Where no
154
- mailbox takes it, or the space's constitution is too large for one, the
155
- long invite is returned instead; it works the same. `until` (ms) says when
156
- to stop sharing it.
157
-
158
- **Short links the account keeps.** Each short link's sealed invite is kept in
159
- the account registry (`sys.link`), never its secret, and copied to every
160
- carrier's carry space, so the account's host serves it while every device is
161
- away. Every hour, and whenever the registry or a space's key changes, a
162
- device holding the account key drops each one again where the space's members
163
- meet. One past its `until`, or carrying a key the space has moved on from, is
164
- ended: its role invite is closed and the record deleted. `closeInvite` by a
165
- short link closes its invite and forgets the record. The device that made a
166
- link holds its secret nowhere: copy the link when it is made.
112
+ `node.spaces.invite(id, options?)` takes the options in
113
+ [`InviteOptions`](https://minca.dev/api/core/interfaces/InviteOptions/): the
114
+ role it gives, `write: false` for a view-only invite, and `short` for a short
115
+ link.
116
+
117
+ ### Which role
118
+
119
+ With no `role`, the invite is for `member` when you may assign it. Otherwise
120
+ it is for the first role, by name, that you may assign. With none, as in
121
+ `solo`, it is view-only.
122
+
123
+ Opening an invite for a role needs the same grant as assigning that role to
124
+ someone who holds nothing: `/role/assign` with
125
+ `{ role, self: false, roles: [] }`. Each join counts as you assigning the
126
+ role to whoever joins. So if your grant says `.self == false`, you can't join
127
+ your own invite.
128
+
129
+ Someone judged on a view from before you lost the grant still gets in. To
130
+ stop an invite, close it with `spaces.closeInvite`.
131
+
132
+ Each role invite has its own secret and its own `sys.invite` record, so you
133
+ can close one without the others.
134
+
135
+ See [spec 03 §4.5](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
136
+
137
+ ### What an invite carries
138
+
139
+ An invite names where to find the space:
140
+
141
+ - the space's relays, or yours when the space names none;
142
+ - the always-on nodes that hold it, your account's hosts and the space's own,
143
+ at most 8, each pinned by its DID. A host that doesn't answer within three
144
+ seconds is left out, so it never holds the invite up.
145
+
146
+ On `join`, the node uses the invite's relays only when they pass
147
+ `checkRelays` and it has no relay list for the space yet. The invite's nodes
148
+ are dialled for the space, and kept like its relays.
149
+
150
+ Until the invite's record reaches this device, the space is held with
151
+ `joining: true`, and the node tries again as records arrive. See
152
+ [spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
153
+
154
+ ### Previewing
167
155
 
168
156
  `node.spaces.preview(invite)` reads an invite without storing anything, and
169
- for a short link fetches it first, which is why it is async:
157
+ gives an [`InvitePreview`](https://minca.dev/api/core/interfaces/InvitePreview/).
158
+ `invitedBy` is the account that signed the invite. `preview` and `join` both
159
+ refuse an invite whose signature or note doesn't check out. See
160
+ [spec 03 §7.4](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
170
161
 
171
- ```
172
- { space: { id, name, visibility, founders, createdAt, succeeds? }, invitedBy,
173
- carriesKey, carriesWrite, role, // role is null for a view-only invite
174
- until? } // a short link's, when given
175
- ```
162
+ ### Short links
163
+
164
+ `short: true` seals the invite and leaves it in two mailboxes: your account's
165
+ first host's, and the first relay's that takes it. The link names those two.
166
+ When no mailbox takes it, or the space's constitution is too big for one, you
167
+ get the long invite back. It works the same.
168
+
169
+ `preview` fetches a short link first, which is why it is async. The node
170
+ remembers it, so a preview and the join after it ask the mailboxes once. A
171
+ link whose invite is nowhere fails with "That invite was not found": it may
172
+ have expired, or its mailboxes may be down.
176
173
 
177
- `invitedBy` is the account that signed the invitation: `preview` and `join`
178
- both refuse an invite whose signature or note doesn't check out ([spec 03 §7.4](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
179
- A short link is fetched once and remembered by the node, so a preview and the
180
- join after it ask the mailboxes once. A link whose invite is nowhere fails
181
- with "That invite was not found"; it may have expired or its places be down.
182
- Invite nodes are dialled for the space alongside the hosts the account uses,
183
- and kept like its invite relays.
174
+ The device that made a link keeps its secret nowhere, so copy the link when
175
+ you make it.
184
176
 
185
- On `join`, relays carried by the invite are a hint: the node uses them only
186
- when they pass `checkRelays` and it holds no relay list for the space yet.
187
- While the invite's record has not reached this device, the space is held with
188
- `joining: true` and the node tries again as records arrive
189
- ([spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
177
+ See [spec 03 §7.7](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md).
190
178
 
191
- _Source: `packages/core/src/node/node.ts` (`spaces.invite`, `preview`, `join`), `packages/core/src/node/node-hosting.ts` (`nodesOf`), `packages/core/src/node/node-carriers.ts` (`inviteTo`, `shortInvite`, `resolveInvite`, `keepLinks`), `packages/core/src/space/space-manager.ts` (`previewInvite`, `join`), `packages/core/src/space/invite-link.ts`. Tests: `packages/core/tests/space.test.ts` ("invites"), `packages/core/tests/roles.test.ts` ("invites"), `packages/core/tests/invite-link.test.ts`, `packages/cli/tests/host.test.ts` ("someone invited reaches the space through the inviter’s host…", "a short link: the host keeps it…")._
179
+ ### Short links the account keeps
180
+
181
+ Each short link's sealed invite, never its secret, is kept in the account
182
+ registry as `sys.link`. It is copied to every carrier, so your host serves it
183
+ while all your devices are away.
184
+
185
+ Every hour, and whenever the registry or a space's key changes, a device
186
+ holding the account key drops each link again where the space's members meet.
187
+ A link past its `until`, or carrying a key the space has moved on from, is
188
+ ended: its invite is closed and the record deleted.
189
+
190
+ `closeInvite` with a short link closes its invite and forgets the record.
192
191
 
193
192
  ## Keeping a space's keys and relays
194
193
 
195
- The node does the protocol's key upkeep by itself, in each space it opens:
194
+ The node looks after each space it opens by itself:
196
195
 
197
- - On every upkeep it publishes this account's member key when it differs from
198
- the one published.
199
- - When a key change is due and its account may invoke `/key/change` and it
196
+ - It publishes this account's member key when it differs from the one
197
+ published.
198
+ - When a key change is due, and the account may invoke `/key/change` and
200
199
  holds the current key, it changes the key. `node.spaces.changeKey` does the
201
200
  same by hand.
202
- - In a space with no relays named yet, a node whose account may invoke
203
- `/space/relays` names its own.
204
-
205
- _Source: `packages/core/src/node/space-keys.ts` (`upkeep`, `rotateKey`, `nameRelays`). Tests: `packages/core/tests/key-change.test.ts`, `packages/core/tests/space-relays.test.ts`._
201
+ - In a space with no relays named yet, if the account may invoke
202
+ `/space/relays`, it names its own.
206
203
 
207
204
  ## Flagged accounts
208
205
 
209
- `spaces.access(id).flagged` lists accounts proven to have broken the protocol's
210
- rules in the space, by warrants members wrote and this node checked
211
- ([warrants](warrants.md)).
206
+ `spaces.access(id).flagged` lists accounts proven to have broken the
207
+ protocol's rules in the space. The proof is a warrant a member wrote and this
208
+ node checked. See [warrants](warrants.md).
212
209
 
213
210
  ## Profiles
214
211
 
215
- The record format, and whose versions count, is protocol
216
- ([spec 03 §11](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
217
- The rest is the library's.
218
-
219
- **Reading.** For each `profile:` key, the node looks at versions newest first,
220
- skipping any that is not `sys.profile`, does not verify, does not stand, or
221
- whose root's `hex40` is not the record key:
222
-
223
- - a deleted version ends the search: no profile;
224
- - the first remaining version gives `name` (trimmed, cut to 64 characters;
225
- empty means no profile), `did` (its root) and `updatedAt` (its `createdAt`);
226
- - `contactKey` comes from the newest remaining version that carries a valid
227
- P-256 point, so a newer version written without one does not hide it.
228
- - `avatar` comes from the newest version only (one without it has taken it
229
- away): a file reference (`records.addFile`) whose `mime` is an image.
230
-
231
- **Writing.** Profiles are written with `retain`, so older versions stay. A
232
- writer that does not hold the contact key must carry forward the
233
- `contactKey` of its current profile.
234
-
235
- **The account's name and picture.** The account keeps its name in the
236
- account registry, as `sys.profile` at key `profile` with body
237
- `{ name, avatar? }`; the newest version wins. `node.account.setName` writes
238
- the name, `setAvatar({ bytes, mime })` the picture (a file in the registry;
239
- the app resizes it first), and `picture()` reads it back. The node publishes
240
- both into every space it opens, and again on a change. A space's members
241
- can't read the registry, so the picture is copied into each space once, as a
242
- file of that space, and its reference names the registry file it copies
243
- (`source`), so opening the space again makes no second copy. A picture that
244
- can't be copied now (its bytes on a device that is away) leaves the space's
245
- copy as it was, and never holds back the name. Profiles are retained, so a
246
- picture once shared stays with the members who hold it: taking it away
247
- shows none from then on, and withdraws nothing. It publishes
248
- in every space but the registry and the contacts space, and not at all from
249
- a node whose note lacks `/account/write` (an agent's); a non-member
250
- publishes nothing
251
- ([spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md)).
252
-
253
- > **Planned:** profiles, round two.
254
- >
255
- > - **A name per space** ("in this space, call me…"). The record is already
256
- > per space; what is missing is a way to say the name was chosen for this
257
- > space, so publishing the account name on the next rename does not
258
- > overwrite it.
259
- > - **Private nicknames for others**: a name you give someone, seen only by
260
- > you. It belongs in the account's own spaces, not in the shared one;
261
- > `std.contact`'s `name` already does this for contacts.
262
- >
263
- > Open questions: the field names; the avatar's size limit and format; and
264
- > whether nicknames for people who are not contacts get a collection of their
265
- > own. `profile:` keys may also change (spec 03 §8.6).
266
-
267
- _Source: `packages/core/src/node/space-profiles.ts` (`loadProfiles`), `packages/core/src/node/space-runtime.ts` (`publishProfile`), `packages/core/src/node/node-contacts.ts` (`publishProfile`, `ownName`, `account.setName`), `packages/core/src/space/account-registry.ts` (`PROFILE_COLLECTION`, `PROFILE_KEY`). Tests: `packages/core/tests/profiles.test.ts`, `packages/core/tests/contacts.test.ts` ("the contact key"), `packages/core/tests/account.test.ts` ("the account name")._
212
+ A profile is the name and picture someone shows in a space.
213
+ `node.spaces.profiles(id)` lists them.
214
+
215
+ ### Your name and picture
216
+
217
+ ```ts
218
+ declare const bytes: Uint8Array;
219
+ // ---cut---
220
+ await node.account.setName('Leif');
221
+ await node.account.setAvatar({ bytes, mime: 'image/png' });
222
+ ```
223
+
224
+ Both need the account key. Resize the picture first, and pass `null` to
225
+ remove it. `node.account.picture()` reads it back.
226
+
227
+ The node publishes both into every space it opens, and again when they
228
+ change. It skips the registry and the contacts space. A node whose note
229
+ lacks `/account/write`, such as an agent's, publishes nothing, and neither
230
+ does a non-member.
231
+
232
+ A picture once shared stays with the members who have it. Taking it away
233
+ shows none from then on, but withdraws nothing.
234
+
235
+ ### Showing names
236
+
237
+ A name is whatever its owner typed, so two people can both be "Sam".
238
+ `displayName(did, profiles)`, or `useNames(space)` in React, adds the tail
239
+ of the identity when a name is shared. For someone with no profile it shows
240
+ the tail alone.
241
+
242
+ ### How a profile is read
243
+
244
+ For each `profile:` key, the node looks at versions newest first. It skips
245
+ any that is not `sys.profile`, does not verify, does not stand, or whose
246
+ root's `hex40` is not the record key. Then:
247
+
248
+ - A deleted version ends the search: no profile.
249
+ - The first remaining version gives `name` (trimmed, cut to 64 characters;
250
+ empty means no profile), `did` (its root) and `updatedAt` (its
251
+ `createdAt`).
252
+ - `contactKey` comes from the newest remaining version with a valid P-256
253
+ point, so a newer version without one does not hide it.
254
+ - `avatar` comes from the newest version only, so a version without it takes
255
+ it away. It is a file reference (`records.addFile`) whose `mime` is an
256
+ image.
257
+
258
+ ### How a profile is written
259
+
260
+ Profiles are written with `retain`, so older versions stay. A writer that
261
+ does not hold the contact key must carry forward the `contactKey` of its
262
+ current profile.
263
+
264
+ The account keeps its own name in the account registry, as `sys.profile` at
265
+ key `profile`, with body `{ name, avatar? }`. The newest version wins.
266
+
267
+ Members of a space can't read the registry, so the picture is copied into
268
+ each space once, as a file of that space. Its reference names the registry
269
+ file it copies (`source`), so opening the space again makes no second copy. A
270
+ picture that can't be copied now, because its bytes are on a device that is
271
+ away, leaves the space's copy as it was. It never holds back the name.
272
+
273
+ The record format, and whose versions count, are protocol. See
274
+ [spec 03 §11](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)
275
+ and [spec 06 §1.3](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
276
+
277
+ > **Planned:** profiles, round two. A name per space ("in this space, call
278
+ > me…"), which the next rename of the account would not overwrite. And
279
+ > private nicknames for others, kept in the account's own spaces, as
280
+ > `std.contact`'s `name` already does for contacts. Open: the field names, the
281
+ > avatar's size limit and format, a collection for nicknames of non-contacts,
282
+ > and whether `profile:` keys change (spec 03 §8.6).
268
283
 
269
284
  ## The space manager
270
285
 
271
- The space manager keeps, per space, in a storage adapter (the node's
272
- `registry` store, sealed at rest; see [node](node.md#stores)):
286
+ The space manager keeps what the node knows about each space in its
287
+ `registry` store, sealed at rest (see [node](node.md#stores)):
273
288
 
274
289
  | Storage key | Value |
275
290
  | --------------------- | -------------------------------------------------------------------------------------------- |
@@ -283,26 +298,24 @@ The space manager keeps, per space, in a storage adapter (the node's
283
298
  `remove` deletes all six. Joining again with a secret while one is waiting
284
299
  keeps the newer one.
285
300
 
286
- _Source: `packages/core/src/space/space-manager.ts`. Tests: `packages/core/tests/space.test.ts` ("space manager")._
287
-
288
301
  ## The account's own automations
289
302
 
290
303
  What the account wants to hear about is an automation of its own, kept in
291
- its registry ([automations](automations.md#the-accounts-own)). Its `app`
304
+ its registry. See [automations](automations.md#the-accounts-own). Its `app`
292
305
  names the app that proposed it, and that app shows what it matches. A home
293
306
  adds none of its own.
294
307
 
295
- **Narrowing with `where`.** A proposal, and an app's `notify` entry, may
296
- carry a `where` in its query: a filter over the record, the same as a
297
- query's ([query-format.md](query-format.md)): body fields, `link:<rel>`, and
298
- of the record's own fields `@key`, `@collection`, `@createdBy` and
299
- `@createdAt`. An app can build one from what a person picks — "a task whose
300
- priority is at least 3", "a poll that isn't closed" — rather than offering a
301
- fixed list. `checkOwnAutomation` says whether one can be kept, and
302
- `matches(record, filter)` whether it holds, which an app can use to show
303
- what it would have matched before proposing it.
308
+ ### Narrowing with `where`
309
+
310
+ A proposal, or an app's `notify` entry, can carry a `where`: a filter over
311
+ the record, the same as a [query's](query-format.md). It can test body
312
+ fields, `link:<rel>`, `@key`, `@collection`, `@createdBy` and `@createdAt`.
313
+ Build one from what a person picks, "a task whose priority is at least 3",
314
+ rather than offering a fixed list:
304
315
 
305
316
  ```typescript
317
+ import { notifyOn } from '@minca/core/schemas';
318
+
306
319
  await connection.propose([
307
320
  notifyOn('Urgent task for me', 'std.task', {
308
321
  assignees: { $contains: '$me' },
@@ -311,9 +324,11 @@ await connection.propose([
311
324
  ]);
312
325
  ```
313
326
 
314
- A condition on a topic field, at the top of `where` or in an `$and` there,
315
- is what a carrier's wake matches; the rest is judged only by the app. Without
316
- one, a carrier wakes the app for every new record of the collection, and the
317
- app turns down the rest.
327
+ `checkOwnAutomation` says whether one can be kept. `matches(record, filter)`
328
+ says whether a filter holds, so you can show what it would have matched
329
+ before proposing it.
318
330
 
319
- _Source: `packages/core/src/space/own-automations.ts` (`checkOwnAutomation`, `notifyOn`, `matchesRecord`), `packages/core/src/query/filter.ts` (`checkFilter`, `matches`), `packages/core/src/node/node-carriers.ts` (`automations`), `apps/example/src/notifications.ts`. Tests: `packages/core/tests/carrier.test.ts` ("notifications through a carrier"), `packages/core/tests/topics.test.ts` ("an automation of the account’s own: its where")._
331
+ A carrier wakes the app only on a condition on a topic field, at the top of
332
+ `where` or in an `$and` there. The app judges the rest. With no such
333
+ condition, a carrier wakes the app for every new record of the collection,
334
+ and the app turns down the rest.