@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.
- package/README.md +2 -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/node/actions.d.ts +3 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +1 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +1 -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-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-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 +13 -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-runtime.d.ts +5 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +3 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/types.d.ts +112 -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/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/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 +213 -152
- package/docs/agents.md +198 -167
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -311
- 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 -65
- package/docs/inbox.md +138 -93
- package/docs/node.md +1072 -996
- 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 -246
- package/docs/standard-library.md +473 -526
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -1
package/docs/spaces.md
CHANGED
|
@@ -1,275 +1,290 @@
|
|
|
1
|
-
# Spaces
|
|
1
|
+
# Spaces
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
-
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
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:
|
|
104
|
-
|
|
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
|
|
109
|
-
|
|
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
|
-
|
|
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
|
-
|
|
92
|
+
### Showing successors
|
|
117
93
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
|
|
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
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
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
|
-
|
|
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
|
-
|
|
173
|
-
|
|
174
|
-
|
|
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
|
-
|
|
178
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
194
|
+
The node looks after each space it opens by itself:
|
|
196
195
|
|
|
197
|
-
-
|
|
198
|
-
|
|
199
|
-
- When a key change is due and
|
|
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,
|
|
203
|
-
`/space/relays
|
|
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
|
|
210
|
-
rules in the space
|
|
211
|
-
|
|
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
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
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
|
|
272
|
-
`registry` store, sealed at rest
|
|
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
|
|
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
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
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
|
-
|
|
315
|
-
|
|
316
|
-
|
|
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
|
-
|
|
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.
|