@minca/core 0.1.16 → 0.1.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -9
- package/dist/elements/auth-styles.d.ts +1 -1
- package/dist/elements/auth-styles.d.ts.map +1 -1
- package/dist/elements/auth-styles.js +14 -5
- package/dist/elements/auth-styles.js.map +1 -1
- package/dist/elements/minca-auth.d.ts.map +1 -1
- package/dist/elements/minca-auth.js +18 -15
- package/dist/elements/minca-auth.js.map +1 -1
- package/dist/files/space-files.d.ts +2 -2
- package/dist/files/space-files.d.ts.map +1 -1
- package/dist/files/space-files.js +7 -5
- package/dist/files/space-files.js.map +1 -1
- package/dist/inbox/names.d.ts +1 -1
- package/dist/inbox/names.js +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/network/ws-transport.d.ts.map +1 -1
- package/dist/network/ws-transport.js +3 -0
- package/dist/network/ws-transport.js.map +1 -1
- package/dist/node/actions.d.ts +5 -0
- package/dist/node/actions.d.ts.map +1 -1
- package/dist/node/actions.js +39 -20
- package/dist/node/actions.js.map +1 -1
- package/dist/node/api.d.ts +2 -0
- package/dist/node/api.d.ts.map +1 -1
- package/dist/node/api.js +2 -0
- package/dist/node/api.js.map +1 -1
- package/dist/node/carrier.js +1 -1
- package/dist/node/carrier.js.map +1 -1
- package/dist/node/node-carriers.d.ts.map +1 -1
- package/dist/node/node-carriers.js +6 -1
- package/dist/node/node-carriers.js.map +1 -1
- package/dist/node/node-contacts.d.ts.map +1 -1
- package/dist/node/node-contacts.js +1 -0
- package/dist/node/node-contacts.js.map +1 -1
- package/dist/node/node-hosting.d.ts.map +1 -1
- package/dist/node/node-hosting.js +11 -4
- package/dist/node/node-hosting.js.map +1 -1
- package/dist/node/node-records.d.ts.map +1 -1
- package/dist/node/node-records.js +6 -1
- package/dist/node/node-records.js.map +1 -1
- package/dist/node/node.d.ts.map +1 -1
- package/dist/node/node.js +14 -1
- package/dist/node/node.js.map +1 -1
- package/dist/node/remote.d.ts.map +1 -1
- package/dist/node/remote.js +7 -1
- package/dist/node/remote.js.map +1 -1
- package/dist/node/space-holding.d.ts +7 -3
- package/dist/node/space-holding.d.ts.map +1 -1
- package/dist/node/space-holding.js +90 -18
- package/dist/node/space-holding.js.map +1 -1
- package/dist/node/space-peers.d.ts.map +1 -1
- package/dist/node/space-peers.js +58 -24
- package/dist/node/space-peers.js.map +1 -1
- package/dist/node/space-runtime.d.ts +11 -3
- package/dist/node/space-runtime.d.ts.map +1 -1
- package/dist/node/space-runtime.js +22 -1
- package/dist/node/space-runtime.js.map +1 -1
- package/dist/node/space-writing.d.ts +2 -0
- package/dist/node/space-writing.d.ts.map +1 -1
- package/dist/node/space-writing.js +2 -0
- package/dist/node/space-writing.js.map +1 -1
- package/dist/node/types.d.ts +130 -36
- package/dist/node/types.d.ts.map +1 -1
- package/dist/query/types.d.ts +1 -0
- package/dist/query/types.d.ts.map +1 -1
- package/dist/query/types.js.map +1 -1
- package/dist/records/contract-builder.d.ts +22 -6
- package/dist/records/contract-builder.d.ts.map +1 -1
- package/dist/records/contract-builder.js.map +1 -1
- package/dist/schemas/automations.d.ts +6 -2
- package/dist/schemas/automations.d.ts.map +1 -1
- package/dist/schemas/automations.js.map +1 -1
- package/dist/schemas/connectors.d.ts +4 -3
- package/dist/schemas/connectors.d.ts.map +1 -1
- package/dist/schemas/connectors.js +4 -3
- package/dist/schemas/connectors.js.map +1 -1
- package/dist/schemas/library/media.js +1 -1
- package/dist/schemas/library/media.js.map +1 -1
- package/dist/schemas/library/social.d.ts +258 -0
- package/dist/schemas/library/social.d.ts.map +1 -1
- package/dist/schemas/library/social.js +28 -1
- package/dist/schemas/library/social.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/hosting.d.ts.map +1 -1
- package/dist/session/hosting.js +8 -2
- package/dist/session/hosting.js.map +1 -1
- package/dist/space/presets.d.ts +2 -2
- package/dist/space/presets.d.ts.map +1 -1
- package/dist/space/presets.js +3 -2
- package/dist/space/presets.js.map +1 -1
- package/dist/storage/blob-store.d.ts +3 -0
- package/dist/storage/blob-store.d.ts.map +1 -1
- package/dist/types.d.ts +11 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -93
- package/docs/actions.md +212 -144
- package/docs/agents.md +198 -155
- package/docs/automations.md +296 -204
- package/docs/blueprints-and-guides.md +405 -295
- package/docs/bots.md +208 -134
- package/docs/building-an-app.md +74 -163
- package/docs/collections.md +248 -328
- package/docs/computed.md +112 -89
- package/docs/contacts.md +151 -112
- package/docs/contracts.md +299 -120
- package/docs/direct-messages.md +80 -61
- package/docs/inbox.md +138 -93
- package/docs/node.md +1072 -972
- package/docs/permissions.md +142 -0
- package/docs/proposing-collections.md +74 -55
- package/docs/query-format.md +150 -126
- package/docs/records-and-queries.md +205 -126
- package/docs/sign-in.md +496 -418
- package/docs/spaces.md +261 -245
- package/docs/standard-library.md +473 -504
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -2
package/docs/computed.md
CHANGED
|
@@ -1,16 +1,23 @@
|
|
|
1
1
|
# Computed fields
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
3
|
+
A computed field is a value every app works out from the records it holds,
|
|
4
|
+
instead of one somebody writes. Use one for counts, tallies and flags that
|
|
5
|
+
follow from other records, like "a to-do is done once two people have
|
|
6
|
+
reacted 👍".
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
8
|
+
Computed fields are a library convention. Peers store a definition's
|
|
9
|
+
`computed` member and never read it
|
|
10
|
+
([#247](https://github.com/leifriksheim/minca/issues/247)).
|
|
11
|
+
|
|
12
|
+
## An example
|
|
13
|
+
|
|
14
|
+
Say it once, in the collection's definition, then query on it like any
|
|
15
|
+
field:
|
|
12
16
|
|
|
13
17
|
```ts
|
|
18
|
+
import * as z from 'zod';
|
|
19
|
+
import { collection } from '@minca/core';
|
|
20
|
+
|
|
14
21
|
const reaction = collection({
|
|
15
22
|
name: 'app.reaction',
|
|
16
23
|
schema: z.object({ emoji: z.string() }),
|
|
@@ -30,7 +37,7 @@ const todo = collection({
|
|
|
30
37
|
},
|
|
31
38
|
});
|
|
32
39
|
|
|
33
|
-
const { records } = await node.records.query(space, {
|
|
40
|
+
const { records } = await node.records.query(space.id, {
|
|
34
41
|
collection: todo,
|
|
35
42
|
where: { done: false },
|
|
36
43
|
sort: { thumbs: 'desc' },
|
|
@@ -39,58 +46,57 @@ records[0]?.body.text; // what was written
|
|
|
39
46
|
records[0]?.computed.done; // what this node works out: boolean | null
|
|
40
47
|
```
|
|
41
48
|
|
|
49
|
+
No one writes `done`, and no one signs a claim about it.
|
|
50
|
+
|
|
42
51
|
## A view, not a verdict
|
|
43
52
|
|
|
44
53
|
Each node works computed fields out from what it holds. Two nodes holding
|
|
45
|
-
different records
|
|
46
|
-
`done` as soon as he
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
54
|
+
different records see different values until they have synced. Bob sees
|
|
55
|
+
`done` as soon as he reacts. Alice sees it once his reaction reaches her.
|
|
56
|
+
|
|
57
|
+
Withdraw a reaction and `done` turns back. The same happens when a member is
|
|
58
|
+
removed and the removal keeps nothing of theirs. A node that holds only some
|
|
59
|
+
collections counts only what it holds.
|
|
50
60
|
|
|
51
61
|
That is right for what an app shows: done flags, like counts, tallies,
|
|
52
|
-
leaderboards. It is wrong for
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
evidence, and every reader judges exactly that.
|
|
62
|
+
leaderboards. It is wrong for anything that can't be taken back, like a
|
|
63
|
+
payment, or a move the next move depends on. Those need a verdict that is the
|
|
64
|
+
same on every node and stays fixed. That is what a [contract](contracts.md)
|
|
65
|
+
gives: the writer cites the evidence, and every reader judges exactly that.
|
|
57
66
|
|
|
58
67
|
The two are written the same way. Where a computed field searches with
|
|
59
|
-
`linked(reaction, 'on')`, a contract
|
|
60
|
-
`cited(body.reactions, reaction)
|
|
68
|
+
`linked(reaction, 'on')`, a contract reads what a claim cites with
|
|
69
|
+
`cited(body.reactions, reaction)`. The rest of the expression is the same.
|
|
61
70
|
|
|
62
71
|
## Writing them
|
|
63
72
|
|
|
64
|
-
`computed` is a function that gets the record's names and
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
- **
|
|
75
|
-
|
|
76
|
-
`
|
|
77
|
-
|
|
78
|
-
- **
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
- **One field from another**: give one a name with `const`, and use it in the
|
|
82
|
-
next, as `done` uses `thumbs`. Each lookup of what links here is done once
|
|
83
|
-
per record, however many fields use it.
|
|
73
|
+
`computed` is a function that gets the record's names and returns an object
|
|
74
|
+
of fields. It is turned into CEL, the language contracts use, when you define
|
|
75
|
+
the collection.
|
|
76
|
+
|
|
77
|
+
What it can read and call is on
|
|
78
|
+
[`ComputedContext`](https://minca.dev/api/core/interfaces/ComputedContext/).
|
|
79
|
+
The one a contract lacks is `linked(collection, rel)`, the records that link
|
|
80
|
+
to this one. Pass the definition, and a role it lacks, or one that points
|
|
81
|
+
elsewhere, is a type error.
|
|
82
|
+
|
|
83
|
+
- **Methods** are a contract's
|
|
84
|
+
([Contracts](contracts.md#writing-one-in-typescript)): `where`, `map`,
|
|
85
|
+
`distinct`, `count`, `sum`, `exists`, `all`, comparisons and arithmetic. A
|
|
86
|
+
balance is `linked(payment, 'to').map((p) => p.body.amount).sum()`.
|
|
87
|
+
- **One field can use another.** Name it with `const` and use it in the next,
|
|
88
|
+
as `done` uses `thumbs`. Each `linked()` lookup runs once per record,
|
|
89
|
+
however many fields use it.
|
|
84
90
|
|
|
85
91
|
A field's type follows from its expression: a count is a `number`, a
|
|
86
|
-
comparison a `boolean`.
|
|
87
|
-
for, as when
|
|
92
|
+
comparison a `boolean`. A field is `null` for a record it can't be worked out
|
|
93
|
+
for, such as when the body lacks a field it reads, or it runs past the limits
|
|
88
94
|
contracts have.
|
|
89
95
|
|
|
90
96
|
## As data
|
|
91
97
|
|
|
92
|
-
A definition stores each field
|
|
93
|
-
|
|
98
|
+
A definition stores each field as CEL, so an agent or another language can
|
|
99
|
+
write the same thing:
|
|
94
100
|
|
|
95
101
|
```json
|
|
96
102
|
"computed": {
|
|
@@ -99,60 +105,77 @@ writes the same:
|
|
|
99
105
|
}
|
|
100
106
|
```
|
|
101
107
|
|
|
102
|
-
`
|
|
108
|
+
## What `define` refuses
|
|
103
109
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
-
|
|
107
|
-
|
|
110
|
+
`collections.define` refuses these, saying where:
|
|
111
|
+
|
|
112
|
+
- more than 16 fields;
|
|
113
|
+
- a name that isn't lower camel case;
|
|
114
|
+
- an expression over 4,000 characters, or over 2,000 parts in all;
|
|
115
|
+
- anything outside the CEL subset contracts have
|
|
116
|
+
([spec 09 §5](https://github.com/leifriksheim/minca/blob/main/spec/09-contracts.md)),
|
|
117
|
+
or `prev`, `versions` or `member`;
|
|
108
118
|
- `linked()` with anything but a literal collection name and link role;
|
|
109
119
|
- a field named like a field of the body's schema;
|
|
110
120
|
- a field that misreads the schemas: a body field that isn't there, a string
|
|
111
|
-
compared with a number, `linked()` of a collection
|
|
112
|
-
|
|
113
|
-
collections.
|
|
121
|
+
compared with a number, or `linked()` of a collection the space doesn't
|
|
122
|
+
define, that doesn't declare that role, or whose role points at other
|
|
123
|
+
collections.
|
|
114
124
|
|
|
115
|
-
A
|
|
125
|
+
A `std.*` collection the space doesn't define is read untyped. A contract
|
|
126
|
+
can't call `linked()`, since what a contract reads must be the same on every
|
|
116
127
|
node.
|
|
117
128
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
doesn't declare can still share a computed field's name, and a query reads
|
|
122
|
-
the computed field: whoever defines the collection decides both anyway.
|
|
129
|
+
A definition may come from another implementation, or be written by hand.
|
|
130
|
+
When its `computed` is malformed, too large, or names a field the body's
|
|
131
|
+
schema declares, readers treat it as having no computed fields.
|
|
123
132
|
|
|
124
133
|
## Reading them
|
|
125
134
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
135
|
+
Every record a query gives has `computed` beside `body`, with its
|
|
136
|
+
collection's fields, or `{}` without any. Included records have theirs too.
|
|
137
|
+
`body` stays what its author signed, so writing `{ ...record.body, text }`
|
|
138
|
+
back never writes a computed value.
|
|
139
|
+
|
|
140
|
+
`where` and `sort` name a computed field the way they name a body field:
|
|
141
|
+
`{ done: false }`. An include's `where` reads the computed fields of what it
|
|
142
|
+
finds. With a typed collection, a name that is neither a body field nor a
|
|
143
|
+
computed field is a type error.
|
|
144
|
+
|
|
145
|
+
A computed field always wins over a body member of the same name. A schema
|
|
146
|
+
that lets bodies hold extra members can't make a query read one in its place.
|
|
147
|
+
Whoever defines the collection decides both anyway.
|
|
148
|
+
|
|
149
|
+
Fields are worked out by the definition as it is now, not as it was when each
|
|
150
|
+
record was written.
|
|
151
|
+
|
|
152
|
+
## Watching them
|
|
153
|
+
|
|
154
|
+
A record can come to match `{ done: true }` without changing. Bob's 👍 makes
|
|
155
|
+
the to-do done, so anything that watches a filter on a computed field also
|
|
156
|
+
watches what it reads:
|
|
157
|
+
|
|
158
|
+
- an [automation](automations.md) sets off when the 👍 is written (after its
|
|
159
|
+
`since`);
|
|
160
|
+
- an app's own notifications say so then, once;
|
|
161
|
+
- a carrier wakes the app on a new 👍 as well as on a new to-do.
|
|
162
|
+
|
|
163
|
+
## Cost
|
|
164
|
+
|
|
165
|
+
Filtering or sorting on a computed field works it out for every candidate.
|
|
166
|
+
Otherwise it is worked out only for the page returned. A `linked()` lookup
|
|
167
|
+
follows the link index once per record, so keep fields to what a screen
|
|
168
|
+
shows.
|
|
169
|
+
|
|
170
|
+
## Showing them in a form
|
|
171
|
+
|
|
172
|
+
An app that draws records from their definitions, as the example's data view
|
|
173
|
+
does, gets each computed field as JSON Schema from
|
|
174
|
+
`computedSchemas(definition, definitionOf)`. A count is an `integer`, a
|
|
175
|
+
comparison a `boolean`, and each is marked `readOnly`. Show them beside the
|
|
153
176
|
body's fields, marked as worked out here, and leave them out of forms.
|
|
154
177
|
|
|
155
|
-
Not yet
|
|
156
|
-
follows a record's own links out.
|
|
178
|
+
## Not yet
|
|
157
179
|
|
|
158
|
-
|
|
180
|
+
- Computed fields on `records.get` and `records.list`.
|
|
181
|
+
- A `linked()` that follows a record's own links out.
|
package/docs/contacts.md
CHANGED
|
@@ -1,23 +1,117 @@
|
|
|
1
1
|
# Contacts
|
|
2
2
|
|
|
3
|
-
A contact is someone you share a
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
inbox.
|
|
3
|
+
A contact is someone you share a private **space for two** with. Use this
|
|
4
|
+
page to ask someone you already share a space with to become a contact. For
|
|
5
|
+
someone you share no space with, use their [inbox](inbox.md).
|
|
7
6
|
|
|
8
|
-
|
|
9
|
-
it. Peers that have never heard of `std.contact` or `std.contact-request`
|
|
10
|
-
sync, store and judge them like any other record. The knock they carry is
|
|
11
|
-
protocol: how it is signed and sealed, and what the person it is for checks,
|
|
12
|
-
is [spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md),
|
|
13
|
-
the same however it is handed over.
|
|
14
|
-
Asking someone you share **no** space with goes through their inbox
|
|
15
|
-
([inbox.md](inbox.md)).
|
|
7
|
+
## Asking someone
|
|
16
8
|
|
|
17
|
-
|
|
9
|
+
Pick a space you both belong to, and the person to ask:
|
|
18
10
|
|
|
19
|
-
|
|
20
|
-
|
|
11
|
+
```ts
|
|
12
|
+
const { space: pairSpace, carried } = await node.contacts.ask(space.id, did, { note: 'Hi from the co-op!' });
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
This makes a new private space for two, puts them on your list with it, and
|
|
16
|
+
leaves a request for them in the shared space. `space`, here `pairSpace`, is
|
|
17
|
+
the space for two.
|
|
18
|
+
|
|
19
|
+
`carried` is false when none of your always-on carriers held the space in
|
|
20
|
+
time. Then they can join only while one of your devices is online.
|
|
21
|
+
|
|
22
|
+
## Answering a request
|
|
23
|
+
|
|
24
|
+
On their side, `requests` lists what was left for them, and `accept` joins:
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
const [request] = await node.contacts.requests(space.id);
|
|
28
|
+
if (request) {
|
|
29
|
+
const contact = await node.contacts.accept(space.id, request.key);
|
|
30
|
+
}
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
There is no reply. Joining the space for two is the answer, and you each
|
|
34
|
+
have the other on your list.
|
|
35
|
+
|
|
36
|
+
## The list
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
const contacts = await node.contacts.list();
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`get`, `put`, `remove`, `block` and the rest are in
|
|
43
|
+
[`NodeContacts`](https://minca.dev/api/core/interfaces/NodeContacts/), and
|
|
44
|
+
each contact is a
|
|
45
|
+
[`ContactView`](https://minca.dev/api/core/interfaces/ContactView/). Its
|
|
46
|
+
`name` is what you call them. They never see it.
|
|
47
|
+
|
|
48
|
+
`remove` and `block` leave the space for two, giving up your place there,
|
|
49
|
+
unless another contact names the same space. `block` keeps them on the list
|
|
50
|
+
with `blocked: true`, and hides their requests in every space and in your
|
|
51
|
+
inbox. `others` lists accounts in the space for two besides the two of you,
|
|
52
|
+
from its members, profiles and connected peers.
|
|
53
|
+
|
|
54
|
+
A contact's `username` is what their domain answered when you found them by
|
|
55
|
+
it. Nothing checks it again: once a name lapses and someone else claims it,
|
|
56
|
+
a lookup leads to them, and your contact keeps the old one.
|
|
57
|
+
|
|
58
|
+
## Inviting a contact into a space
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
await node.contacts.invite(did, space.id, { role: 'member' });
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
This leaves an invite for them in your space for two. They must have joined
|
|
65
|
+
that space first. A request nobody has answered yet is refused, so you never
|
|
66
|
+
open a space to whoever a username led to before you have seen who they are.
|
|
67
|
+
A blocked contact is refused too.
|
|
68
|
+
|
|
69
|
+
On their side, `invites()` lists what contacts left for them, newest first,
|
|
70
|
+
and `join` takes them in:
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
const [invite] = await node.contacts.invites();
|
|
74
|
+
if (invite) await node.contacts.join(invite.pairSpace, invite.key);
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Each item is a
|
|
78
|
+
[`SpaceInviteView`](https://minca.dev/api/core/interfaces/SpaceInviteView/).
|
|
79
|
+
Only invites to spaces you don't hold yet are listed. Only the contact's own
|
|
80
|
+
records count, and each invite is checked as joining checks it: signed by
|
|
81
|
+
the contact, for the space whose constitution it carries. That is where
|
|
82
|
+
`space` and `name` come from. Invites from someone blocked are not shown.
|
|
83
|
+
|
|
84
|
+
`invites()` also closes and deletes your own invites that the contact has
|
|
85
|
+
joined with.
|
|
86
|
+
|
|
87
|
+
## Who may ask
|
|
88
|
+
|
|
89
|
+
`ask` and `accept` need a session note that grants `/account/write` for the
|
|
90
|
+
whole account. An app granted `contacts` can see the list and the requests,
|
|
91
|
+
but can't ask or accept. See
|
|
92
|
+
[spec 06 §2.5](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md).
|
|
93
|
+
|
|
94
|
+
## How `ask` works
|
|
95
|
+
|
|
96
|
+
1. It creates a private `team` space named `"<my name> & <their name>"`, and
|
|
97
|
+
opens an `editor` invite to it.
|
|
98
|
+
2. It waits up to 3 seconds for an online carrier to hold the space
|
|
99
|
+
(`spaces.carried`).
|
|
100
|
+
3. It writes a `std.contact` for them, with that space.
|
|
101
|
+
4. It leaves the request, a sealed knock, as a `std.contact-request`.
|
|
102
|
+
|
|
103
|
+
It returns `{ space, request, carried }`: the space for two, the request's
|
|
104
|
+
record key, and whether a carrier held it. It needs the other person's
|
|
105
|
+
`contactKey` on their profile in that space. `accept` joins the invite, and
|
|
106
|
+
writes a `std.contact` for the asker with the space for two.
|
|
107
|
+
|
|
108
|
+
`requests(space)` skips blocked senders, and knocks whose space for two you
|
|
109
|
+
already hold.
|
|
110
|
+
|
|
111
|
+
## `std.contact`
|
|
112
|
+
|
|
113
|
+
The list lives in the account's contacts space, derived with the label
|
|
114
|
+
`minca/contacts`, one record per person:
|
|
21
115
|
|
|
22
116
|
```
|
|
23
117
|
std.contact (rules: onePer ["did"])
|
|
@@ -28,123 +122,68 @@ record key = records.onePerKey(contactsSpace, "std.contact", { did })
|
|
|
28
122
|
// a shared key, spec 02 §7.3: onePer without @author
|
|
29
123
|
```
|
|
30
124
|
|
|
31
|
-
`
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
A reader must ignore a record whose key is not the one its `did` derives. It
|
|
36
|
-
also ignores one whose root is not the account, as it does for every record in
|
|
37
|
-
the account's derived spaces (spec 03 §13.1).
|
|
125
|
+
`space` is the id of the space for two. A reader ignores a record whose key
|
|
126
|
+
is not the one its `did` derives. It also ignores one whose root is not the
|
|
127
|
+
account, as for every record in the account's derived spaces (spec 03
|
|
128
|
+
§13.1).
|
|
38
129
|
|
|
39
130
|
## The contact key
|
|
40
131
|
|
|
41
|
-
A
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
132
|
+
A request is sealed to the other person's contact key: the public half,
|
|
133
|
+
published as `contactKey` on their profile in the space. A node holds the
|
|
134
|
+
private half only when it was given it (`config.contactKey`). An agent never
|
|
135
|
+
is. See spec 01 §10.1 for how it is derived, and spec 03 §11 for the
|
|
136
|
+
profile.
|
|
45
137
|
|
|
46
|
-
##
|
|
138
|
+
## `std.contact-request`
|
|
47
139
|
|
|
48
140
|
```
|
|
49
141
|
std.contact-request (no rules; who may write one is the space's grants)
|
|
50
142
|
{ to: <the askee's contact key, as on their profile here, ≤64>, sealed: string ≤16000 }
|
|
51
143
|
```
|
|
52
144
|
|
|
53
|
-
`
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
asked, not whom.
|
|
145
|
+
`sealed` is a knock sealed to `to`, whose invite is to the new space for two.
|
|
146
|
+
`ask` defines the collection first if the space lacks it, which needs
|
|
147
|
+
`/collection/define`. In a private space the body is sealed with the space
|
|
148
|
+
key too, so other members see that someone asked, not whom.
|
|
58
149
|
|
|
59
150
|
The receiver opens a request only when `to` is its own contact key, the
|
|
60
|
-
knock checks out
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
- `put({ did, name, space?, note? })`: adds someone, or changes what the list
|
|
69
|
-
says about them.
|
|
70
|
-
- `ask(space, did, { note? })` needs whole-account access and the askee's
|
|
71
|
-
`contactKey` on their profile in that space. It creates a private `team`
|
|
72
|
-
space named `"<my name> & <their name>"`, opens an `editor` invite to it,
|
|
73
|
-
waits up to 3 seconds for a carrier that is online to hold it (`spaces.carried`), writes a
|
|
74
|
-
`std.contact` for them with that space, then leaves the knock as
|
|
75
|
-
`std.contact-request`. It returns the space for two, the record's key, and `carried`:
|
|
76
|
-
false when no carrier held the space in time, so the askee can join only
|
|
77
|
-
while one of the asker's devices is online.
|
|
78
|
-
- `requests(space)` lists the knocks left there that open for this account,
|
|
79
|
-
skipping blocked senders and knocks whose space for two the account already
|
|
80
|
-
holds.
|
|
81
|
-
- `accept(space, requestKey)` joins the invite (spec 03 §7.6) and writes a
|
|
82
|
-
`std.contact` for the asker with the space for two. There is no reply
|
|
83
|
-
record: joining is the answer.
|
|
84
|
-
- `remove(did)` leaves the space for two (spec 03 §6.2), giving up the
|
|
85
|
-
account's place there, unless another contact names it, and deletes the
|
|
86
|
-
`std.contact`.
|
|
87
|
-
- `block(did)` leaves the space for two likewise and writes the contact with
|
|
88
|
-
`blocked: true`.
|
|
89
|
-
- `others(did)` lists accounts other than the two seen in the space for two
|
|
90
|
-
(members, profiles, connected peers).
|
|
91
|
-
- `invite(did, spaceId, { role? })` invites a contact into a space you hold:
|
|
92
|
-
it makes an invite for `role` and leaves it as a `std.space-invite` in your
|
|
93
|
-
space for two with them. The contact must have joined the space for two: a
|
|
94
|
-
knock nobody answered yet is refused, so a space is never opened to whoever
|
|
95
|
-
a username happens to lead to before you have seen who they are. A blocked
|
|
96
|
-
contact is refused.
|
|
97
|
-
- `invites()` lists the invites a contact left for you in your space for two
|
|
98
|
-
with them, to spaces you don't hold yet, newest first:
|
|
99
|
-
`{ from, space, name, invite, pairSpace, key, createdAt }`. Only the
|
|
100
|
-
contact's own records count, and each invite is checked as joining checks
|
|
101
|
-
it: signed by the contact, for the space whose constitution it carries,
|
|
102
|
-
which is where `space` and `name` come from. Invites from someone blocked are
|
|
103
|
-
not shown. It also closes, and deletes, invites of yours the contact has
|
|
104
|
-
joined with.
|
|
105
|
-
- `join(pairSpace, key)` joins the space an invite from that contact is for.
|
|
151
|
+
knock checks out, and the knock's account is the record's root and not its
|
|
152
|
+
own. A knock someone else copied into another record is not theirs to leave,
|
|
153
|
+
and opens as nothing.
|
|
154
|
+
|
|
155
|
+
The list and the request are conventions: peers that have never heard of
|
|
156
|
+
them sync and judge them like any other record. The knock inside is
|
|
157
|
+
protocol, the same however it is handed over. See
|
|
158
|
+
[spec 07 §6](https://github.com/leifriksheim/minca/blob/main/spec/07-inbox.md).
|
|
106
159
|
|
|
107
160
|
## `std.space-invite`
|
|
108
161
|
|
|
109
|
-
An invite to a space, left in a space for two: `{ space, invite }`,
|
|
162
|
+
An invite to a space, left in a space for two: `{ space, invite }`, with
|
|
110
163
|
`onePer: ['space']`, so inviting again to the same space replaces it.
|
|
111
164
|
|
|
112
|
-
It
|
|
113
|
-
it, the next time it reads `invites()`.
|
|
114
|
-
rejoin with it, as with any open role invite
|
|
115
|
-
([#170](https://github.com/leifriksheim/minca/issues/170)), and whoever else
|
|
116
|
-
holds a place in the space for two reads it
|
|
117
|
-
([#313](https://github.com/leifriksheim/minca/issues/313)). An invite with no
|
|
118
|
-
role, to view, carries the space key and can't be closed
|
|
119
|
-
([#172](https://github.com/leifriksheim/minca/issues/172)).
|
|
120
|
-
|
|
121
|
-
A contact's `username` is what their domain answered when you found them by
|
|
122
|
-
it. Nothing checks it again: once a name lapses and someone else claims it, a
|
|
123
|
-
lookup leads to them, and the contact keeps the old one.
|
|
165
|
+
It stays open until its maker's node sees the contact in the space and
|
|
166
|
+
closes it, the next time it reads `invites()`.
|
|
124
167
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
([
|
|
129
|
-
|
|
130
|
-
|
|
168
|
+
Until then, a contact removed from the space can rejoin with it, as with
|
|
169
|
+
any open role invite ([#170](https://github.com/leifriksheim/minca/issues/170)).
|
|
170
|
+
Anyone else with a place in the space for two can read it
|
|
171
|
+
([#313](https://github.com/leifriksheim/minca/issues/313)). A view-only
|
|
172
|
+
invite carries the space key and can't be closed
|
|
173
|
+
([#172](https://github.com/leifriksheim/minca/issues/172)).
|
|
131
174
|
|
|
132
175
|
## Planned: requests that can be taken back
|
|
133
176
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
`std.contact`
|
|
139
|
-
|
|
140
|
-
- `
|
|
141
|
-
|
|
142
|
-
- `
|
|
143
|
-
|
|
144
|
-
for two.
|
|
145
|
-
- `spaces.leave(id)` on a space a `std.contact` names does what `remove` does
|
|
146
|
-
for that contact.
|
|
147
|
-
- `ContactView` gains `waiting: boolean`, true while the other account has no
|
|
148
|
-
member record in the space for two.
|
|
177
|
+
Today `remove` and `block` leave your request standing, so they can still
|
|
178
|
+
accept it, into a space nobody holds. And `spaces.leave` on a space for two
|
|
179
|
+
leaves the `std.contact` that names it. The plan:
|
|
180
|
+
|
|
181
|
+
- `std.contact` gains `asked?: { space: string ≤256, key: string ≤256 }`,
|
|
182
|
+
where `ask` left the request.
|
|
183
|
+
- `remove` and `block` delete that request, when the space is still held and
|
|
184
|
+
the record still stands, before leaving the space for two.
|
|
185
|
+
- `spaces.leave` on a space a `std.contact` names does what `remove` does.
|
|
186
|
+
- `ContactView` gains `waiting: boolean`, true while the other account has
|
|
187
|
+
no member record in the space for two.
|
|
149
188
|
|
|
150
189
|
Tracked in [#40](https://github.com/leifriksheim/minca/issues/40).
|