@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/standard-library.md
CHANGED
|
@@ -1,572 +1,519 @@
|
|
|
1
1
|
# The standard library
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
3
|
+
The standard library is a set of ready-made collections for the things most
|
|
4
|
+
apps keep: messages, events, tasks, files, reactions. When your app keeps one
|
|
5
|
+
of those, use the standard one. Every other app that uses it reads your
|
|
6
|
+
records, and you read theirs.
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import type { NodeRecord } from '@minca/core';
|
|
10
|
+
declare const post: NodeRecord;
|
|
11
|
+
// ---cut---
|
|
12
|
+
import { reaction, comment, useSchemas } from '@minca/core/schemas';
|
|
13
|
+
|
|
14
|
+
await useSchemas(node, space.id, [reaction, comment]);
|
|
15
|
+
await node.records.put(
|
|
16
|
+
space.id,
|
|
17
|
+
reaction,
|
|
18
|
+
{ emoji: '👍' },
|
|
19
|
+
{
|
|
20
|
+
links: [{ rel: 'about', to: post.key }],
|
|
21
|
+
},
|
|
22
|
+
);
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
`useSchemas` defines the ones the space doesn't know yet and leaves the rest
|
|
26
|
+
alone, so you can call it every time a space opens.
|
|
27
|
+
|
|
28
|
+
The definitions are ordinary collections. The protocol knows none of them.
|
|
29
|
+
They are drawn from atproto lexicons, Nostr NIPs, JSContact (RFC 9553),
|
|
30
|
+
JSCalendar (RFC 8984) and schema.org; issue
|
|
12
31
|
[#36](https://github.com/leifriksheim/minca/issues/36) has the sources.
|
|
13
32
|
|
|
14
33
|
## What a `std.*` name means
|
|
15
34
|
|
|
16
|
-
A collection name belongs to the space that defines it. There is no
|
|
17
|
-
|
|
18
|
-
each other's records is
|
|
19
|
-
|
|
35
|
+
A collection name belongs to the space that defines it. There is no
|
|
36
|
+
registry, so two spaces could give one name different shapes. What lets two
|
|
37
|
+
apps read each other's records is a shared definition, and the library is
|
|
38
|
+
where apps find one.
|
|
20
39
|
|
|
21
|
-
`std.*` names
|
|
22
|
-
`std.*` definition of another shape
|
|
23
|
-
to the convention:
|
|
40
|
+
`std.*` names belong to the library by convention. Peers don't refuse a
|
|
41
|
+
`std.*` definition of another shape, but the node's agent actions keep to it:
|
|
24
42
|
|
|
25
|
-
- `collections_standard` lists the library, and gives any
|
|
26
|
-
|
|
27
|
-
- `collections_propose` takes a standard collection by name (`"std.event"`
|
|
28
|
-
|
|
29
|
-
- `collections_propose` refuses a `std.*` name the library
|
|
43
|
+
- `collections_standard` lists the library, and gives any definition in
|
|
44
|
+
full.
|
|
45
|
+
- `collections_propose` takes a standard collection by name (`"std.event"`)
|
|
46
|
+
and stores the library's definition for it.
|
|
47
|
+
- `collections_propose` refuses a `std.*` name the library doesn't have, and
|
|
30
48
|
a `std.*` definition whose `schema`, `links`, `rules`, `topics` or
|
|
31
|
-
`history` differ from the library's.
|
|
32
|
-
|
|
49
|
+
`history` differ from the library's. The `title` and `description` may be
|
|
50
|
+
your own.
|
|
33
51
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
52
|
+
Name your app's own collections for what they hold (`carpool.ride`), not
|
|
53
|
+
with a generic prefix (`app.ride`) another app may want too. To open
|
|
54
|
+
collections by what they hold rather than by name, see
|
|
55
|
+
[compatible definitions](blueprints-and-guides.md#compatible-definitions).
|
|
56
|
+
See also [actions](actions.md) and
|
|
57
|
+
[spec 02 §6.4](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
|
|
40
58
|
|
|
41
59
|
## How the library is shaped
|
|
42
60
|
|
|
43
|
-
People
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
look-alike), so an app that needs more on a `std.file`, say, defines
|
|
64
|
-
`recipes.photo-note` with an `about` link to the file and
|
|
65
|
-
`onePer: [link:about]`. Every other app still reads the file; only the
|
|
66
|
-
recipes app reads the note. Never a parallel `recipes.photo` collection.
|
|
67
|
-
4. **Links use one vocabulary**, below. A link that says where a record
|
|
68
|
-
sits is `in`, whether that is a channel, a board column or a list.
|
|
61
|
+
People build several apps over the same records, often by asking an agent.
|
|
62
|
+
That only works if every app picks the same collection for the same thing.
|
|
63
|
+
Five rules keep the choice obvious.
|
|
64
|
+
|
|
65
|
+
1. **One collection per kind of thing.** Variants are optional fields. A
|
|
66
|
+
photo, a video and a PDF are each a `std.file`, with `width`, `duration`
|
|
67
|
+
or neither. Two collections an agent could pick for the same thing is a
|
|
68
|
+
bug in the library.
|
|
69
|
+
2. **A group is a relation, not a field.** `std.tag` is a loose label, any
|
|
70
|
+
number per record. `std.list` with a `std.list-item` per member is a
|
|
71
|
+
named, ordered group that exists while empty: a folder, an album, a
|
|
72
|
+
playlist, an itinerary (`kind`). So one file can be in a chat, a category
|
|
73
|
+
and an album at once. A facet nearly every app filters by, like an
|
|
74
|
+
event's `category`, may stay a field.
|
|
75
|
+
3. **What your app adds to a standard record is a record of its own.** Say
|
|
76
|
+
your recipes app needs more on a `std.file`. Define `recipes.photo-note`
|
|
77
|
+
with an `about` link to the file and `onePer: [link:about]`. Every app
|
|
78
|
+
still reads the file. Never a parallel `recipes.photo`.
|
|
79
|
+
4. **Links share one vocabulary** (below). Where a record sits is always
|
|
80
|
+
`in`: a channel, a board column or a list.
|
|
69
81
|
5. **A description says when not to use it.** Agents choose by reading
|
|
70
|
-
descriptions, so
|
|
71
|
-
|
|
72
|
-
std.ballot."
|
|
82
|
+
descriptions, so a definition names the neighbour it could be mistaken
|
|
83
|
+
for: "To vote on a std.proposal, use std.ballot."
|
|
73
84
|
|
|
74
85
|
## Conventions
|
|
75
86
|
|
|
76
|
-
- What several people edit is several records, not an array in one body
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
|
105
|
-
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
87
|
+
- What several people edit is several records, not an array in one body. A
|
|
88
|
+
list and its items, a document and its blocks, an order and its updates.
|
|
89
|
+
- "One per person" or "one per slot" is the `onePer` rule.
|
|
90
|
+
- A picture or a video in a `std.file` may carry a `thumbnail`: a small
|
|
91
|
+
still, about 480 px on its longer side, that apps show in its place until
|
|
92
|
+
someone opens it. It is small enough for every device to fetch ahead, so a
|
|
93
|
+
long chat shows its pictures without fetching each file whole. A picture
|
|
94
|
+
that is already small has none, and an app shows the picture itself. An
|
|
95
|
+
app shows a thumbnail only for a `mime` of `image/` or `video/`, and only
|
|
96
|
+
one of at most 256 KiB: it is the writer's word, like the rest of the body.
|
|
97
|
+
- Bodies have no `createdAt`, since the record has one. They carry only the
|
|
98
|
+
times of the thing itself: `start`, `due`, `takenAt`.
|
|
99
|
+
- Link roles: `about` (what an annotation is on), `replyTo` and `root`
|
|
100
|
+
(threads), `parent` (trees), `in` (member of a list, album, calendar,
|
|
101
|
+
document or account), `shares` (quotes).
|
|
102
|
+
- What only one person should see is kept where only they read it: a block
|
|
103
|
+
on the contact ([contacts](contacts.md)), and their own settings and
|
|
104
|
+
reminders in the account registry, `node.account.space()`
|
|
105
|
+
([the node](node.md#records-and-the-account)).
|
|
106
|
+
|
|
107
|
+
See [spec 02 §4.3 and §7.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
|
|
108
|
+
|
|
109
|
+
## Fragments
|
|
110
|
+
|
|
111
|
+
Shared shapes like a time or an amount of money are built by the library's
|
|
112
|
+
`fragments`, so they are identical in every definition. You can use them in
|
|
113
|
+
your own definitions too.
|
|
114
|
+
|
|
115
|
+
| Fragment | Shape |
|
|
116
|
+
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
117
|
+
| `when` | string 10–64, `x-kind: "when"`: RFC 3339 (`2026-03-01T18:30:00+01:00`), or `YYYY-MM-DD` for a whole day |
|
|
118
|
+
| `day` | string of 10, `x-kind: "day"`: `YYYY-MM-DD` |
|
|
119
|
+
| `url` | string 1–2048, `x-kind: "url"` |
|
|
120
|
+
| `timeZone` | string 1–64: an IANA zone, `Europe/Oslo` |
|
|
121
|
+
| DID | string 1–256, `x-kind: "did"`: an account (built by `person`) |
|
|
122
|
+
| `money` | `{ amount, currency }`, `x-kind: "money"`, both required. `amount` is a decimal string 1–32 (`"12.50"`), never a number. `currency` is ISO 4217 |
|
|
123
|
+
| `address` | `{ street, locality, region, postcode, country }`, each optional. `country` is ISO 3166-1 alpha-2 |
|
|
124
|
+
| `place` | `{ name, address, lat, lon, cells }` (built by `placeRef`), each optional. WGS 84. `cells` is up to 8 geohash cells ([Places and areas](#places-and-areas)) |
|
|
125
|
+
| `blob` | `{ hash, size, mime, name?, key?, salt? }`, `x-kind: "file"`: what `records.addFile` gives |
|
|
126
|
+
| `image` | `{ blob, alt? }`, `x-kind: "image"`, `alt` ≤ 2000 |
|
|
127
|
+
| `position` | string 1–200, `x-kind: "position"` ([Positions](#positions)) |
|
|
128
|
+
|
|
129
|
+
A `blob`'s `hash` is the file's id (64 hex characters), and its `key` and
|
|
130
|
+
`salt` open it (22 base64url characters each). See [storage](storage.md#files).
|
|
131
|
+
|
|
132
|
+
`when` and `day` are checked only for length until the schema dialect has
|
|
133
|
+
`format` (Planned, below).
|
|
112
134
|
|
|
113
135
|
## The definitions
|
|
114
136
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
`
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
`
|
|
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
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
| `std.file` | **`name`** string 1–255; **`mime`** string 1–255; `size` integer ≥ 0; `blob` blob; `url` string 1–2048; `alt` string ≤ 2000; `width` integer ≥ 1; `height` integer ≥ 1; `duration` number ≥ 0; `takenAt` when; `place` place; `thumbnail` blob; `captions` blob | `about` → `*`, one | — |
|
|
182
|
-
| `std.track` | **`title`** string 1–300; `artists` string 1–200[] (≤ 20); `album` string ≤ 300; `duration` number ≥ 0; `isrc` string ≤ 12; `mbid` string ≤ 36 | `file` → `std.file`, one | — |
|
|
183
|
-
| `std.play` | **`title`** string 1–300; `artists` string 1–200[] (≤ 20); `album` string ≤ 300; `duration` number ≥ 0; `isrc` string ≤ 12; `mbid` string ≤ 36; **`playedAt`** when | `about` → `std.track`, one | — |
|
|
184
|
-
|
|
185
|
-
**Time and planning**
|
|
186
|
-
|
|
187
|
-
| Name | Body | Links | Rules |
|
|
188
|
-
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------- |
|
|
189
|
-
| `std.calendar` | **`name`** string 1–200; `color` string ≤ 32 | — | — |
|
|
190
|
-
| `std.event` | **`title`** string 1–500; `description` string ≤ 10000; `category` string ≤ 100; **`start`** when; `end` when; `tz` string 1–64; `allDay` boolean; `place` place; `url` string 1–2048; `rrule` string 1–1000; `status` `confirmed`/`tentative`/`cancelled`; topic `place.cells` | `in` → `std.calendar`, one | — |
|
|
191
|
-
| `std.rsvp` | **`status`** `going`/`maybe`/`no`; `guests` integer 0–100; `note` string ≤ 500; `respondingTo` DID; topic `respondingTo` | `about` → `std.event`, one | `onePer: [@author, link:about]` |
|
|
192
|
-
| `std.slot` | **`start`** when; **`end`** when; `tz` string 1–64; `note` string ≤ 1000 | `in` → `std.calendar`, one | — |
|
|
193
|
-
| `std.column` | **`name`** string 1–200; `position` string 1–200 | `in` → `std.project`, one | — |
|
|
194
|
-
| `std.task` | **`title`** string 1–500; `notes` string ≤ 10000; `position` string 1–200; `due` when; `status` `todo`/`doing`/`done`/`cancelled`; `assignees` DID[] (≤ 20); `priority` integer 0–4; topic `assignees` | `in` → `std.column`, `std.project`, one; `parent` → `std.task`, one | — |
|
|
195
|
-
| `std.project` | **`name`** string 1–200; `description` string ≤ 10000; `status` `planned`/`active`/`paused`/`done`/`cancelled`; `due` when | — | — |
|
|
196
|
-
| `std.time-entry` | **`start`** when; `end` when; `note` string ≤ 1000 | `about` → `*`, one | — |
|
|
197
|
-
| `std.reminder` | **`at`** when; `note` string ≤ 1000; `done` boolean | `about` → `*`, one | — |
|
|
198
|
-
| `std.habit` | **`name`** string 1–200; `schedule` string ≤ 1000; `target` number ≥ 0; `unit` string ≤ 32; `position` string 1–200 | — | — |
|
|
199
|
-
| `std.checkin` | **`date`** day; `value` number; `note` string ≤ 1000 | `about` → `std.habit`, one | `onePer: [@author, link:about, date]` |
|
|
200
|
-
|
|
201
|
-
**Places and travel**
|
|
202
|
-
|
|
203
|
-
| Name | Body | Links | Rules |
|
|
204
|
-
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------- |
|
|
205
|
-
| `std.place` | **`name`** string 1–200; `address` address; `lat` number -90–90; `lon` number -180–180; `cells` string 1–12[] (≤ 8); `category` string ≤ 100; `url` string 1–2048; topic `cells` | — | — |
|
|
206
|
-
| `std.visit` | **`at`** when; `note` string ≤ 2000 | `about` → `std.place`, one | — |
|
|
207
|
-
| `std.trip` | **`title`** string 1–200; `start` day; `end` day; `note` string ≤ 10000 | — | — |
|
|
208
|
-
| `std.location` | **`lat`** number -90–90; **`lon`** number -180–180; `accuracy` number ≥ 0; **`at`** when | — | `onePer: [@author]` |
|
|
209
|
-
|
|
210
|
-
**Home and life**
|
|
211
|
-
|
|
212
|
-
| Name | Body | Links | Rules |
|
|
213
|
-
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------- |
|
|
214
|
-
| `std.recipe` | **`title`** string 1–300; `description` string ≤ 2000; `ingredients` { **`text`** string 1–500, `quantity` number ≥ 0, `unit` string ≤ 32 }[] (≤ 200); `steps` string 1–5000[] (≤ 200); `servings` integer ≥ 1; `prepMinutes` integer ≥ 0; `cookMinutes` integer ≥ 0; `image` image; `source` string 1–2048 | — | — |
|
|
215
|
-
| `std.meal` | **`date`** day; **`meal`** `breakfast`/`lunch`/`dinner`/`snack`; `note` string ≤ 1000 | `about` → `std.recipe`, one | `onePer: [date, meal]` |
|
|
216
|
-
| `std.journal-entry` | **`date`** day; `content` string ≤ 200000; `mood` string ≤ 32 | — | `onePer: [@author, date]` |
|
|
217
|
-
| `std.measurement` | **`kind`** string 1–64; **`value`** number; **`unit`** string 1–32; **`at`** when; `note` string ≤ 1000 | — | — |
|
|
218
|
-
| `std.workout` | **`type`** string 1–64; **`start`** when; `duration` number ≥ 0; `distance` number ≥ 0; `route` blob; `note` string ≤ 2000 | — | — |
|
|
219
|
-
| `std.work` | **`kind`** `book`/`film`/`show`/`album`/`game`/`podcast`/`other`; **`title`** string 1–500; `creators` string 1–200[] (≤ 20); `year` integer 0–9999; `ids` { `isbn` string ≤ 17, `imdb` string ≤ 16, `mbid` string ≤ 36, `wikidata` string ≤ 16 }; `cover` blob | — | — |
|
|
220
|
-
| `std.progress` | **`status`** `want`/`doing`/`done`/`dropped`; `percent` number 0–100; `finishedAt` when; `note` string ≤ 2000 | `about` → `std.work`, one | `onePer: [@author, link:about]` |
|
|
221
|
-
|
|
222
|
-
**Money and trade**
|
|
223
|
-
|
|
224
|
-
| Name | Body | Links | Rules |
|
|
225
|
-
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | --------------------------- |
|
|
226
|
-
| `std.expense` | **`title`** string 1–200; **`amount`** money; **`paidBy`** DID; `split` { **`did`** DID, `share` string 1–32 }[] (≤ 100); `date` day; `note` string ≤ 2000; `owedBy` DID[] (≤ 63), the people in `split`; topics `paidBy`, `owedBy` | — | history `all` |
|
|
227
|
-
| `std.settlement` | **`from`** DID; **`to`** DID; **`amount`** money; `date` day; `note` string ≤ 1000; topics `from`, `to` | — | `fixed: [from, to, amount]` |
|
|
228
|
-
| `std.money-account` | **`name`** string 1–200; **`currency`** string 3–3; `kind` string ≤ 32 | — | — |
|
|
229
|
-
| `std.transaction` | **`amount`** money; **`date`** day; `payee` string ≤ 200; `category` string ≤ 100; `note` string ≤ 1000; `cleared` boolean | `in` → `std.money-account`, one | — |
|
|
230
|
-
| `std.listing` | **`title`** string 1–300; `description` string ≤ 10000; `price` money; `category` string ≤ 100; `condition` `new`/`like-new`/`good`/`fair`/`for-parts`; `images` image[] (≤ 12); `status` `available`/`reserved`/`sold`; `place` place; topic `place.cells` | — | — |
|
|
231
|
-
| `std.order` | **`items`** { **`title`** string 1–300, **`quantity`** integer ≥ 1, `price` money }[] (1–100); `total` money; `note` string ≤ 2000; `respondingTo` DID; topic `respondingTo` | `about` → `std.listing`, many | — |
|
|
232
|
-
| `std.order-update` | **`status`** `accepted`/`paid`/`shipped`/`delivered`/`cancelled`/`refunded`; `note` string ≤ 2000; `respondingTo` DID; topic `respondingTo` | `about` → `std.order`, one | — |
|
|
233
|
-
|
|
234
|
-
**Community and governance**
|
|
235
|
-
|
|
236
|
-
| Name | Body | Links | Rules |
|
|
237
|
-
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------- |
|
|
238
|
-
| `std.poll` | **`question`** string 1–500; **`options`** string 1–200[]; `closed` boolean | — | `fixed: [options]` |
|
|
239
|
-
| `std.vote` | **`choice`** integer ≥ 0; `choices` integer ≥ 0[] (≤ 100); `respondingTo` DID; topic `respondingTo` | `about` → `std.poll`, one | `onePer: [@author, link:about]` |
|
|
240
|
-
| `std.proposal` | **`title`** string 1–300; `body` string ≤ 20000; **`options`** string 1–200[] (1–20); `closesAt` when; `status` `open`/`passed`/`rejected`/`withdrawn`; `quorum` integer 1–10000 | — | `fixed: [options]` |
|
|
241
|
-
| `std.ballot` | **`choice`** integer ≥ 0; `respondingTo` DID; topic `respondingTo` | `about` → `std.proposal`, one | `onePer: [@author, link:about]`; `fixed: [choice]` |
|
|
242
|
-
| `std.decision` | **`outcome`** integer ≥ 0; **`proposal`** string 1–128 (a version id); **`ballots`** string 1–128[] (≤ 256) | `about` → `std.proposal`, one | `onePer: [link:about]`; `check` (below) |
|
|
243
|
-
| `std.goal` | **`title`** string 1–300; `body` string ≤ 20000; **`target`** integer 1–10⁹; **`unit`** string 1–50; `closesAt` when | — | `fixed: [target, unit]` |
|
|
244
|
-
| `std.pledge` | **`amount`** integer 1–10⁹; `note` string ≤ 1000; `respondingTo` DID; topic `respondingTo` | `about` → `std.goal`, one | `onePer: [@author, link:about]`; `fixed: [amount]` |
|
|
245
|
-
| `std.goal-reached` | **`goal`** string 1–128 (a version id); **`pledges`** string 1–128[] (≤ 256) | `about` → `std.goal`, one | `onePer: [link:about]`; `check` (below) |
|
|
246
|
-
| `std.announcement` | **`title`** string 1–300; `text` string ≤ 20000 | — | — |
|
|
247
|
-
| `std.badge` | **`name`** string 1–100; `description` string ≤ 1000; `image` blob | — | — |
|
|
248
|
-
| `std.award` | **`did`** DID; `note` string ≤ 1000; topic `did` | `about` → `std.badge`, one | `onePer: [link:about, did]` |
|
|
249
|
-
|
|
250
|
-
**Proven outcomes.** A `std.decision` and a `std.goal-reached` are not
|
|
251
|
-
declared by anyone: each cites the records that prove it, by version id, and
|
|
252
|
-
every device checks the proof before it counts one ([contracts.md](contracts.md)). Anyone in the space may write one, once, when the
|
|
253
|
-
proof is there:
|
|
254
|
-
|
|
255
|
-
- `std.decision` cites the proposal's first version (`proposal`) and ballots
|
|
256
|
-
(`ballots`). Its contract: the proposal is the one it is `about`, as first
|
|
257
|
-
put; `outcome` is one of its options; and the ballots cited that are about
|
|
258
|
-
that proposal and chose `outcome` come from at least `quorum` different
|
|
259
|
-
people. A proposal without a `quorum` can't be decided this way.
|
|
260
|
-
- `std.goal-reached` cites the goal's first version (`goal`) and pledges
|
|
261
|
-
(`pledges`). Its contract: the goal is the one it is `about`, as first set;
|
|
262
|
-
each person's pledge counts once; and the pledges add up to `target`.
|
|
263
|
-
|
|
264
|
-
A cited version proves what was signed, so what they count is final: a
|
|
265
|
-
ballot's `choice` and a pledge's `amount` are `fixed`, and their first
|
|
266
|
-
versions are kept whole (`onePer`), so they can be cited. That is why
|
|
267
|
-
`std.ballot` exists beside `std.vote`: a vote can be changed, a ballot can't.
|
|
137
|
+
How to read the tables:
|
|
138
|
+
|
|
139
|
+
- A **bold** field is required.
|
|
140
|
+
- `string 1–200` gives its shortest and longest length.
|
|
141
|
+
- `[]` is a list, with its most items in brackets.
|
|
142
|
+
- `a`/`b` is a choice of values.
|
|
143
|
+
- Links read `role` → what it may point at, and how many.
|
|
144
|
+
- Rules are `onePer`, `fixed` and `final`, and whether it has a contract.
|
|
145
|
+
|
|
146
|
+
Who may add, change and remove records isn't up to the definition, but to
|
|
147
|
+
the space's grants. In the `community` template, members change only what
|
|
148
|
+
they made, moderators change anything, and only moderators and admins write
|
|
149
|
+
in the collections in `STAFF_COLLECTIONS` ([spaces](permissions.md#presets)).
|
|
150
|
+
|
|
151
|
+
The tables are made from the definitions in `@minca/core/schemas` each time
|
|
152
|
+
[minca.dev](https://minca.dev/collections/standard-library/#the-definitions)
|
|
153
|
+
is built, so they always match the code.
|
|
154
|
+
|
|
155
|
+
<!-- catalogue: standard -->
|
|
156
|
+
|
|
157
|
+
## About some of them
|
|
158
|
+
|
|
159
|
+
### `std.call`
|
|
160
|
+
|
|
161
|
+
Calls themselves are kept nowhere ([calls](../../calls/README.md)). If the
|
|
162
|
+
space defines `std.call`, a call leaves a record of its history there.
|
|
163
|
+
|
|
164
|
+
| Field | Type | Meaning |
|
|
165
|
+
| ----------- | ----------------------- | -------------------------------------------- |
|
|
166
|
+
| `status` | `"missed"` \| `"ended"` | Required. |
|
|
167
|
+
| `to` | string ≤ 256 | For a missed call: who was rung. |
|
|
168
|
+
| `startedAt` | ISO date, ≤ 64 | Required. |
|
|
169
|
+
| `endedAt` | ISO date, ≤ 64 | For an ended call. |
|
|
170
|
+
| `people` | string ≤ 256[] (≤ 64) | For an ended call: every account seen in it. |
|
|
171
|
+
|
|
172
|
+
```json
|
|
173
|
+
{
|
|
174
|
+
"status": "ended",
|
|
175
|
+
"startedAt": "2026-09-26T10:00:00.000Z",
|
|
176
|
+
"endedAt": "2026-09-26T10:14:02.311Z",
|
|
177
|
+
"people": ["did:key:zDnaeSm3…", "did:key:zDnaeXL64…"]
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
The call a device is in is kept in `sessionStorage` under `minca-call` as
|
|
182
|
+
`{ space, call }`, so after a reload the page can offer to rejoin.
|
|
183
|
+
|
|
184
|
+
### Tasks
|
|
185
|
+
|
|
186
|
+
A task is `in` its column, or `in` its project when it has no column. A
|
|
187
|
+
column is `in` its project.
|
|
188
|
+
|
|
189
|
+
### Proven outcomes
|
|
190
|
+
|
|
191
|
+
Nobody declares a `std.decision` or a `std.goal-reached`. Each one cites the
|
|
192
|
+
records that prove it, by version id, and every device checks the proof
|
|
193
|
+
before it counts. Anyone in the space may write one, once, when the proof is
|
|
194
|
+
there.
|
|
195
|
+
|
|
196
|
+
- A `std.decision` cites the proposal's first version (`proposal`) and the
|
|
197
|
+
ballots (`ballots`). It holds when the ballots about that proposal that
|
|
198
|
+
chose `outcome` come from at least `quorum` different people. A proposal
|
|
199
|
+
without a `quorum` can't be decided this way.
|
|
200
|
+
- A `std.goal-reached` cites the goal's first version (`goal`) and the
|
|
201
|
+
pledges (`pledges`). It holds when the pledges add up to `target`,
|
|
202
|
+
counting each person once.
|
|
268
203
|
|
|
269
204
|
```json
|
|
270
205
|
{ "outcome": 0, "proposal": "bay24o4l…", "ballots": ["bq7x…", "b3kd…", "bm2a…"] }
|
|
271
206
|
```
|
|
272
207
|
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
`std.host`
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
`
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
collections adds `std.profile` where a space keeps none, as an app does when
|
|
349
|
-
it starts a hosted bot.
|
|
350
|
-
Besides its own automations, it runs the automations in a space that name it in `by`,
|
|
351
|
-
made by members granted `/std.automation/instruct` there
|
|
352
|
-
([automations.md](automations.md#who-runs-an-automation)). In the `community` template, admins
|
|
353
|
-
and moderators hold it. Nothing the bot writes sets an automation off.
|
|
354
|
-
What it writes shows as the bot, and every member's device checks it against
|
|
355
|
-
the bot's role, so a role that may post messages but not delete keeps a
|
|
208
|
+
A ballot's `choice` and a pledge's `amount` are `fixed`, so what was counted
|
|
209
|
+
can't change. That's why `std.ballot` exists beside `std.vote`: a vote can be
|
|
210
|
+
changed, a ballot can't. See [contracts](contracts.md).
|
|
211
|
+
|
|
212
|
+
### `std.host`
|
|
213
|
+
|
|
214
|
+
A `std.host` names a host the space pays to keep it online. Anyone in the
|
|
215
|
+
space may chip in, and members' devices hand the host the space's pass. That
|
|
216
|
+
means naming a host sends it every member's pass, so the `community`
|
|
217
|
+
template leaves `std.host` to admins and moderators. See
|
|
218
|
+
[node](node.md#a-space-paying-for-itself) and
|
|
219
|
+
[spec 08 §2](https://github.com/leifriksheim/minca/blob/main/spec/08-hosting.md).
|
|
220
|
+
|
|
221
|
+
### Automations, bots, blueprints and guides
|
|
222
|
+
|
|
223
|
+
- `std.automation` and `std.automation-run`: what a space does by itself
|
|
224
|
+
when records change or at set times, and what each run did. See
|
|
225
|
+
[automations](automations.md).
|
|
226
|
+
- `std.bot`, `std.connect` and `std.connector`: how a community wants its
|
|
227
|
+
bot to be, asking a bot's host to connect it to a service like GitHub, and
|
|
228
|
+
what the bot is connected to. See [bots](bots.md).
|
|
229
|
+
|
|
230
|
+
`std.blueprint` holds collections someone proposes for the space, not yet
|
|
231
|
+
added. `std.guide` says how some of the space's collections are meant to be
|
|
232
|
+
used. See [blueprints and guides](blueprints-and-guides.md).
|
|
233
|
+
|
|
234
|
+
## Activity
|
|
235
|
+
|
|
236
|
+
`std.activity` shows that someone is at work on a record, for as long as it
|
|
237
|
+
lasts: "My bot is working on it…" under a message, or a spinner on a task.
|
|
238
|
+
Anyone may write one, but only about their own work.
|
|
239
|
+
|
|
240
|
+
| Name | Body | Links | Rules |
|
|
241
|
+
| -------------- | ------------------------------------------------------------------------------------------------------ | ------------------ | ------------------------------- |
|
|
242
|
+
| `std.activity` | **`state`** `working`/`waiting`/`done`/`failed`; `label` string ≤ 120; **`at`** when, since this state | `about` → any, one | `onePer: [@author, link:about]` |
|
|
243
|
+
|
|
244
|
+
There's one per account per record, so writing again moves the same record
|
|
245
|
+
from `waiting` to `working` to `done` or `failed`. A label left out keeps
|
|
246
|
+
the one it had.
|
|
247
|
+
|
|
248
|
+
```ts
|
|
249
|
+
import type { NodeRecord } from '@minca/core';
|
|
250
|
+
declare const message: NodeRecord;
|
|
251
|
+
// ---cut---
|
|
252
|
+
import { setActivity, activeNow } from '@minca/core/schemas';
|
|
253
|
+
|
|
254
|
+
await setActivity(node, space.id, message.key, 'working', 'Reading the thread');
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
A `working` or `waiting` activity whose `at` is more than five minutes old
|
|
258
|
+
(`ACTIVITY_STALE_SECONDS`) must be shown as over, since its writer may have
|
|
259
|
+
gone away. `activeNow(body)` tells you whether one is still going.
|
|
260
|
+
|
|
261
|
+
An agent or bot says what it's doing with the `activity_set` action
|
|
262
|
+
([actions](actions.md)). A bot's automation runner marks what set each
|
|
263
|
+
automation off: `waiting` when queued, `working` with the automation's name
|
|
264
|
+
when it starts, then `done` or `failed`
|
|
265
|
+
([automations](automations.md#running)).
|
|
266
|
+
|
|
267
|
+
## Bots
|
|
268
|
+
|
|
269
|
+
A bot is an account of its own that people invite to their spaces as a
|
|
270
|
+
member. The protocol can't tell bots and people apart. A bot says it is one
|
|
271
|
+
with `bot: true` on its own `std.profile`, which only it can write, and apps
|
|
272
|
+
may show that. It's the account's own word, like its name, so leaving it out
|
|
273
|
+
proves nothing.
|
|
274
|
+
|
|
275
|
+
A bot that may add collections adds `std.profile` where a space has none.
|
|
276
|
+
Besides its own automations, it runs the space's automations that name it in
|
|
277
|
+
`by`, made by members granted `/std.automation/instruct`. In the `community`
|
|
278
|
+
template, admins and moderators hold that grant. Nothing the bot writes sets
|
|
279
|
+
an automation off. See [automations](automations.md#who-runs-an-automation).
|
|
280
|
+
|
|
281
|
+
What a bot writes shows as the bot, and every member's device checks it
|
|
282
|
+
against the bot's role. So a role that may post but not delete keeps a
|
|
356
283
|
misled bot from deleting.
|
|
357
284
|
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
`std.space-profile` is how a space presents itself,
|
|
361
|
-
|
|
362
|
-
the space was founded with
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
the
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
and a carrier's wake can match it unread ([spec 02 §8](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
|
|
391
|
-
A `std.task`'s `assignees` is a topic in the same way: "assigned to me" is
|
|
392
|
-
`where: { "assignees": { "$contains": "$me" } }`, with a tag for each assignee.
|
|
285
|
+
## The space's profile
|
|
286
|
+
|
|
287
|
+
`std.space-profile` is how a space presents itself, the way `std.profile` is
|
|
288
|
+
how a person does. Apps show its `name` and `avatar` in place of the name
|
|
289
|
+
the space was founded with.
|
|
290
|
+
|
|
291
|
+
The founding name stays in the constitution, where nobody can change it. An
|
|
292
|
+
invite shows that name to someone who can't read the space yet, so the name
|
|
293
|
+
they see after joining may differ.
|
|
294
|
+
|
|
295
|
+
There's one per space. `space` holds the space's id, and `onePer: [space]`
|
|
296
|
+
gives everyone the same key, so changing it is editing one shared record.
|
|
297
|
+
Which edit stands follows the order of versions, never a writer's clock. A
|
|
298
|
+
reader takes only the record whose `space` is its own space's id.
|
|
299
|
+
|
|
300
|
+
Anyone who may write there could also start a rival record at that key, so
|
|
301
|
+
who may write it matters. It's in `STAFF_COLLECTIONS`: in a `community`,
|
|
302
|
+
admins and moderators can and members can't. In a `coop`, stewards can.
|
|
303
|
+
|
|
304
|
+
A space made before `std.space-profile` existed keeps the grants it was made
|
|
305
|
+
with. There, any member decides the name and picture, and outranks staff,
|
|
306
|
+
until an admin redefines the member role.
|
|
307
|
+
|
|
308
|
+
The example app reads no `std.space-profile` in a space for two. It names
|
|
309
|
+
the space for the other person.
|
|
310
|
+
|
|
311
|
+
## Mentions and replies
|
|
312
|
+
|
|
313
|
+
A `std.message`, `std.comment` or `std.post` names the accounts it calls on
|
|
314
|
+
in `mentions`. When it replies to someone, it names their account in
|
|
315
|
+
`replyingTo`. `std.note`, `std.doc-block` and `std.article` have `mentions`
|
|
316
|
+
too.
|
|
393
317
|
|
|
394
318
|
```json
|
|
395
319
|
{ "text": "@Sam are you coming?", "mentions": ["did:key:zDnae…Sam"], "replyingTo": "did:key:zDnae…Sam" }
|
|
396
320
|
```
|
|
397
321
|
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
changing that definition. An app's own collection can name a `mentions` field
|
|
401
|
-
as a topic the same way.
|
|
402
|
-
|
|
403
|
-
_Source: `packages/core/src/schemas/library/publishing.ts` (`message`, `post`), `packages/core/src/schemas/library/annotations.ts` (`comment`), `packages/core/src/schemas/library/planning.ts` (`task`), `apps/example/src/components/std/Mentions.tsx`, `apps/example/src/components/apps/Chat.tsx`, `apps/example/src/components/std/Comments.tsx`. Tests: `packages/core/tests/topics.test.ts` ("mentions and replies are tagged, so “mentions me” and “replies to me” match only those", "a std.comment is tagged like a message…", "a std.post is tagged like a message…", "a task carries a tag for each assignee…", "an app that needs std.message gets its topics…")._
|
|
404
|
-
|
|
405
|
-
**Responses.** A record written in answer to someone's record names them in
|
|
406
|
-
`respondingTo`: a `std.reaction`, `std.comment` or `std.repost` the author of
|
|
407
|
-
what it is about, a `std.rsvp` the event's, a
|
|
408
|
-
`std.vote` the poll's, a `std.ballot` the proposal's, a `std.pledge` the
|
|
409
|
-
goal's, a `std.claim` the claimed record's, a `std.order` the listing's, and a
|
|
410
|
-
`std.order-update` the order's. It is their topic, so "someone reacted to,
|
|
411
|
-
commented on, or answered what I wrote" is `where: { "respondingTo":
|
|
412
|
-
{ "$contains": "$me" } }`, matched unread by a carrier's wake. The link says the same for a node
|
|
413
|
-
that can read, but a carrier can't read a private space's links, so the
|
|
414
|
-
account is written out. An app fills it from the author of the record it
|
|
415
|
-
links to, and leaves it out when that is the writer themselves.
|
|
416
|
-
|
|
417
|
-
A comment can carry all three: `respondingTo` the author of what it is
|
|
418
|
-
about, `replyingTo` the author of the comment it answers, and `mentions`.
|
|
419
|
-
|
|
420
|
-
Not every annotation has one. A `std.report` names nobody, so whoever is
|
|
421
|
-
reported is not told, and a keeper can't tell whom it is about. Bookmarks,
|
|
422
|
-
highlights, pins and tags are the writer's own, and what tracks the writer's
|
|
423
|
-
own life (`std.progress`, `std.checkin`, `std.visit`, `std.meal`,
|
|
424
|
-
`std.time-entry`, `std.reminder`) answers nobody.
|
|
425
|
-
|
|
426
|
-
**People as topics.** Where a record names people it is about, they are its
|
|
427
|
-
topics: `did` on `std.award` (given a badge), `std.follow` (followed) and
|
|
428
|
-
`std.list-item` (put on a list); `from` and `to` on `std.settlement`; `to`
|
|
429
|
-
and `people` on `std.call`. A `std.expense` names who owes a share inside
|
|
430
|
-
`split`, a list of objects, which a topic can't reach (spec 02 §8.1: a path
|
|
431
|
-
goes through objects only), so `owedBy` repeats those accounts as a list, at
|
|
432
|
-
most 63 so that with `paidBy` every one is tagged: a record carries at most
|
|
433
|
-
64 tags.
|
|
434
|
-
|
|
435
|
-
_Source: `packages/core/src/schemas/library/annotations.ts`, `packages/core/src/schemas/library/publishing.ts`, `packages/core/src/schemas/library/planning.ts`, `packages/core/src/schemas/library/community.ts`, `packages/core/src/schemas/library/money.ts`, `packages/core/src/schemas/library/social.ts`, `packages/core/src/schemas/library/media.ts`; `apps/example/src/derive/people.ts` (`respondingTo`), `apps/example/src/components/std/Reactions.tsx`, `apps/example/src/components/std/Comments.tsx`, `apps/example/src/components/apps/Polls.tsx`, `apps/example/src/components/apps/Decisions.tsx`, `apps/example/src/components/apps/Events.tsx`, `apps/example/src/components/apps/Marketplace.tsx`. Tests: `packages/core/tests/topics.test.ts` ("every standard collection that names people has them as topics…", "a report names nobody…", "a std.reaction is tagged for the person in its respondingTo…" and the rest of that list)._
|
|
436
|
-
|
|
437
|
-
**Channels.** A space with more than one conversation lists `std.channel`
|
|
438
|
-
records, by `position` then name, and a message is `in` its channel:
|
|
439
|
-
`where: { 'link:in': key }` finds a channel's messages, and
|
|
440
|
-
`include: { messages: { rel: 'in', from: 'std.message', count: true } }`
|
|
441
|
-
counts them. A message in no channel is in the space's own room,
|
|
442
|
-
which a chat shows first, as "general". In the `community` template only
|
|
443
|
-
moderators and admins make or rename a channel. A channel is a label, not a boundary: every member reads
|
|
444
|
-
every channel. Something only some members may read is a space of its own, or
|
|
445
|
-
a direct message.
|
|
446
|
-
|
|
447
|
-
**Direct messages.** A `std.direct` is sealed (`node.direct`, [direct-messages.md](direct-messages.md)):
|
|
448
|
-
only the people in `to` and whoever wrote it can read `data`. A chat groups
|
|
449
|
-
them into conversations by everyone in them, `to` plus the writer, and must
|
|
450
|
-
show one it can't open as unreadable, not drop it. `to` is a topic, so
|
|
451
|
-
"direct messages to me" is an automation of the account's own whose wake a
|
|
452
|
-
keeper can match unread.
|
|
453
|
-
|
|
454
|
-
_Source: `packages/core/src/schemas/library/publishing.ts` (`channel`, `direct`), `packages/core/src/privacy/direct.ts`, `apps/example/src/components/apps/Chat.tsx`. Tests: `packages/core/tests/direct.test.ts`._
|
|
455
|
-
|
|
456
|
-
**Changes to earlier definitions.** Before v1 the library is reshaped
|
|
457
|
-
without migrations, to keep to the rules above. The last such change merged
|
|
458
|
-
`std.attachment`, `std.photo`, `std.video`, `std.folder` and `std.album` into
|
|
459
|
-
one `std.file` (groups of files are `std.list`s); removed `std.booking` (a
|
|
460
|
-
booking is a `std.claim` about a `std.slot`), `std.reference` (any link
|
|
461
|
-
refers) and `std.bookmark` (a saved thing is a `std.list-item`); renamed
|
|
462
|
-
`std.message`'s `channel` link and `std.task`'s `column` link to `in`, and
|
|
463
|
-
dropped the task's `project` link (a task is `in` a project when it has no
|
|
464
|
-
column, and a column is `in` its project); made `std.tag` one record per
|
|
465
|
-
person, record and label; gave `std.track` a `file` link and `std.play` an
|
|
466
|
-
`about` link to its track; and narrowed `std.vote` to polls, since a proposal
|
|
467
|
-
is decided by `std.ballot`s. A space that holds an earlier definition keeps
|
|
468
|
-
it until someone applies a blueprint that carries the new one.
|
|
469
|
-
|
|
470
|
-
Since then ([#105](https://github.com/leifriksheim/minca/issues/105)), `std.comment` and `std.post` gained the same optional
|
|
471
|
-
`mentions` and `replyingTo` as a message, and `std.note`, `std.doc-block` and
|
|
472
|
-
`std.article` a `mentions`, all as topics; eleven annotations and answers
|
|
473
|
-
gained `respondingTo` (Responses, above); `std.expense` gained `owedBy`; and
|
|
474
|
-
the people fields of `std.task`, `std.award`, `std.follow`,
|
|
475
|
-
`std.list-item`, `std.settlement`, `std.call` and `std.expense` became
|
|
476
|
-
topics. A new topic tags only what is
|
|
477
|
-
written under the new definition: records written before it carry no tags,
|
|
478
|
-
so "mentions me" and "assigned to me" match from then on.
|
|
479
|
-
|
|
480
|
-
**Also exported** from the same module (specified with their features):
|
|
481
|
-
|
|
482
|
-
| Name | Body | Rules | Where |
|
|
483
|
-
| --------------------- | --------------------------------------------------------------------------------------------------------- | ----------------- | ----------------------- |
|
|
484
|
-
| `std.contact` | `did` ≤ 256 and `name` ≤ 200, required; `space` ≤ 256; `note` ≤ 2000; `blocked` boolean; `username` ≤ 320 | `onePer: [did]` | [contacts](contacts.md) |
|
|
485
|
-
| `std.contact-request` | `to` ≤ 64 and `sealed` ≤ 16000, required | — | [contacts](contacts.md) |
|
|
486
|
-
| `std.inbox` | `gen` ≥ 0 and `places` (1–3, each ≤ 200), required; `name` ≤ 64; `username` ≤ 320; `usernameUntil` | — | [inbox.md](inbox.md) |
|
|
487
|
-
| `std.knock` | `space` ≤ 256, `name` ≤ 64 and `invite` ≤ 12000, all required; `username` ≤ 320 | `onePer: [space]` | [inbox.md](inbox.md) |
|
|
488
|
-
| `std.space-invite` | `space` ≤ 256 and `invite` ≤ 12000, required | `onePer: [space]` | [contacts](contacts.md) |
|
|
489
|
-
|
|
490
|
-
**Positions.** `position` is a string that sorts (by plain string comparison)
|
|
491
|
-
where a record goes in a hand-made order. Digits are `0–9a–z`; a position
|
|
492
|
-
never ends in `0`, so there is always room between two. Equal positions sort by
|
|
493
|
-
key. A record without one goes at the end. `positionBetween(before, after)` in
|
|
494
|
-
the library makes one; any string that sorts correctly is valid.
|
|
495
|
-
|
|
496
|
-
_Source: `packages/core/src/schemas/fragments.ts`, `packages/core/src/schemas/library/` (one file per area), `packages/core/src/schemas/standard.ts` (`standardGroups`), `packages/core/src/schemas/index.ts` (`positionBetween`, `useSchemas`), `packages/core/src/schemas/contacts.ts`. Tests: `packages/core/tests/schemas.test.ts` ("the standard library", "standard nouns"), `packages/core/tests/contacts.test.ts`, `packages/core/tests/records-only.test.ts`._
|
|
497
|
-
|
|
498
|
-
**Places and areas.** A place with a point also carries its `cells`: the
|
|
499
|
-
geohash of `lat` and `lon` at precisions 3, 4, 5 and 6, coarsest first, about
|
|
500
|
-
156 km, 39 km, 4.9 km and 1.2 km across (`cellsOf(lat, lon)`). Geohash is
|
|
501
|
-
Niemeyer's: longitude and latitude bits interleaved, longitude first, five to
|
|
502
|
-
a character of `0123456789bcdefghjkmnpqrstuvwxyz`. For Grünerløkka in Oslo,
|
|
503
|
-
`lat` 59.9226 and `lon` 10.7522 give `["u4x", "u4xs", "u4xsu", "u4xsus"]`.
|
|
322
|
+
Fill them from what the person picked, like an `@name` they chose or the
|
|
323
|
+
message they replied to. Never fill them by matching text.
|
|
504
324
|
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
Tags match by equality only, which is why the cells are written out at each
|
|
509
|
-
size instead of one long geohash and a prefix.
|
|
510
|
-
|
|
511
|
-
To find what is within a radius, `cellsAround(lat, lon, km)` picks the finest
|
|
512
|
-
precision whose cells are at least `km` wide and tall at that latitude, and
|
|
513
|
-
returns the point's own cell and the eight around it. Everything inside the
|
|
514
|
-
circle is in one of them, so a query or a keeper matches those (in a query,
|
|
515
|
-
`{ "$or": [{ "place.cells": { "$contains": cell } }, …] }`), and the exact
|
|
516
|
-
distance (`distanceKm`, haversine on a sphere of 6371.0088 km) decides the
|
|
517
|
-
rest. It returns null for a radius over about 150 km, or a circle around a
|
|
518
|
-
pole; then every place is a candidate. A record written by something that
|
|
519
|
-
knows nothing of cells has none, and is found only by its point.
|
|
520
|
-
|
|
521
|
-
`cells` say what `lat` and `lon` already say, and nothing checks that they
|
|
522
|
-
agree: a peer only checks that the tags match the cells. An app that reads
|
|
523
|
-
the body uses the point; a wrong cell only hides a record from area matches.
|
|
524
|
-
A listing usually means someone's home, so the example's marketplace keeps
|
|
525
|
-
only the part of town, moving the point to the middle of its precision 6 cell
|
|
526
|
-
and leaving out the street.
|
|
325
|
+
They are topics, as is a message's `in` link. So an automation of the
|
|
326
|
+
account's own can ask for only what mentions it, replies to it, or is in one
|
|
327
|
+
channel, and a carrier's wake can match these unread:
|
|
527
328
|
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
329
|
+
```json
|
|
330
|
+
{ "where": { "mentions": { "$contains": "$me" } } }
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
A `std.task`'s `assignees` is a topic the same way, so "assigned to me" is
|
|
334
|
+
`where: { "assignees": { "$contains": "$me" } }`.
|
|
335
|
+
|
|
336
|
+
A comment can be `about` any record. So commenting is how to mention someone
|
|
337
|
+
on a record whose definition has no `mentions`. Your own collections can
|
|
338
|
+
name a `mentions` field as a topic too. See
|
|
339
|
+
[automations](automations.md#the-accounts-own) and
|
|
340
|
+
[spec 02 §8](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
|
|
341
|
+
|
|
342
|
+
## Responses
|
|
343
|
+
|
|
344
|
+
A record written in answer to someone's record names them in
|
|
345
|
+
`respondingTo`. It's the author of what it answers:
|
|
346
|
+
|
|
347
|
+
| Record | `respondingTo` |
|
|
348
|
+
| ------------------------------------------- | ----------------------------------- |
|
|
349
|
+
| `std.reaction`, `std.comment`, `std.repost` | the author of what it is about |
|
|
350
|
+
| `std.rsvp` | the event's author |
|
|
351
|
+
| `std.vote`, `std.ballot` | the poll's or the proposal's author |
|
|
352
|
+
| `std.pledge` | the goal's author |
|
|
353
|
+
| `std.claim` | the claimed record's author |
|
|
354
|
+
| `std.order`, `std.order-update` | the listing's or the order's author |
|
|
355
|
+
|
|
356
|
+
It's a topic, so "someone answered what I wrote" is
|
|
357
|
+
`where: { "respondingTo": { "$contains": "$me" } }`, and a carrier's wake can
|
|
358
|
+
match it unread. The link says the same to a node that can read, but a
|
|
359
|
+
carrier can't read a private space's links, so the account is written out.
|
|
360
|
+
Fill it from the author of the linked record, and leave it out when that's
|
|
361
|
+
the writer.
|
|
362
|
+
|
|
363
|
+
A comment can carry all three: `respondingTo`, `replyingTo` and `mentions`.
|
|
364
|
+
|
|
365
|
+
Some annotations name nobody. A `std.report` doesn't, so whoever is
|
|
366
|
+
reported isn't told, and a keeper can't tell whom it's about. Highlights,
|
|
367
|
+
pins and tags are the writer's own. What tracks the writer's own life
|
|
368
|
+
(`std.progress`, `std.checkin`, `std.visit`, `std.meal`, `std.time-entry`,
|
|
369
|
+
`std.reminder`) answers nobody.
|
|
370
|
+
|
|
371
|
+
## People as topics
|
|
372
|
+
|
|
373
|
+
Where a record names the people it is about, they are its topics:
|
|
374
|
+
|
|
375
|
+
- `did` on `std.award`, `std.follow` and `std.list-item`
|
|
376
|
+
- `from` and `to` on `std.settlement`
|
|
377
|
+
- `to` and `people` on `std.call`
|
|
378
|
+
- `paidBy` and `owedBy` on `std.expense`
|
|
379
|
+
|
|
380
|
+
A topic can't reach into a list of objects, so `std.expense` repeats the
|
|
381
|
+
people in `split` as `owedBy`. It holds at most 63, so that with `paidBy`
|
|
382
|
+
each one is tagged: a record carries at most 64 tags. See
|
|
383
|
+
[spec 02 §8.1](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
|
|
384
|
+
|
|
385
|
+
## Channels
|
|
386
|
+
|
|
387
|
+
A space with more than one conversation keeps `std.channel` records, sorted
|
|
388
|
+
by `position` then name. A message is `in` its channel.
|
|
389
|
+
|
|
390
|
+
```ts
|
|
391
|
+
import type { NodeRecord } from '@minca/core';
|
|
392
|
+
declare const channel: NodeRecord;
|
|
393
|
+
// ---cut---
|
|
394
|
+
import type { Query } from '@minca/core';
|
|
395
|
+
|
|
396
|
+
// A channel's messages
|
|
397
|
+
const messages: Query = { collection: 'std.message', where: { 'link:in': channel.key } };
|
|
398
|
+
|
|
399
|
+
// Each channel, with how many messages it holds
|
|
400
|
+
const channels: Query = {
|
|
401
|
+
collection: 'std.channel',
|
|
402
|
+
include: { messages: { rel: 'in', from: 'std.message', count: true } },
|
|
403
|
+
};
|
|
404
|
+
```
|
|
405
|
+
|
|
406
|
+
A message in no channel is in the space's own room, which a chat shows
|
|
407
|
+
first as "general". In the `community` template only moderators and admins
|
|
408
|
+
make or rename channels.
|
|
409
|
+
|
|
410
|
+
A channel is a label, not a boundary: every member reads every channel. For
|
|
411
|
+
something only some members may read, use a space of its own or a direct
|
|
412
|
+
message.
|
|
531
413
|
|
|
532
|
-
|
|
414
|
+
## Direct messages
|
|
533
415
|
|
|
534
|
-
|
|
416
|
+
A `std.direct` is sealed. Only the people in `to` and whoever wrote it can
|
|
417
|
+
read `data`. Write and read it through `node.direct`
|
|
418
|
+
([direct messages](direct-messages.md)).
|
|
535
419
|
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
420
|
+
A chat groups direct messages into conversations by everyone in them: `to`
|
|
421
|
+
plus the writer. One it can't open must show as unreadable, not disappear.
|
|
422
|
+
`to` is a topic, so "direct messages to me" can be an automation of the
|
|
423
|
+
account's own that a keeper matches unread.
|
|
424
|
+
|
|
425
|
+
## Positions
|
|
426
|
+
|
|
427
|
+
A `position` is a string that sorts where a record goes in a hand-made
|
|
428
|
+
order, by plain string comparison. Make one with `positionBetween`:
|
|
429
|
+
|
|
430
|
+
```ts
|
|
431
|
+
import type { NodeRecord } from '@minca/core';
|
|
432
|
+
declare const above: NodeRecord<{ position: string }> | undefined;
|
|
433
|
+
declare const below: NodeRecord<{ position: string }> | undefined;
|
|
434
|
+
// ---cut---
|
|
435
|
+
import { positionBetween } from '@minca/core/schemas';
|
|
436
|
+
|
|
437
|
+
positionBetween(above?.body?.position, below?.body?.position);
|
|
438
|
+
```
|
|
543
439
|
|
|
544
|
-
|
|
440
|
+
Either side may be missing, for the ends. Digits are `0–9a–z`, and a
|
|
441
|
+
position never ends in `0`, so there's always room between two. Equal
|
|
442
|
+
positions sort by key. A record without one goes at the end. Any string that
|
|
443
|
+
sorts correctly is valid.
|
|
545
444
|
|
|
546
|
-
|
|
547
|
-
`std.call` record in the space, written only if the space defines `std.call`:
|
|
445
|
+
## Places and areas
|
|
548
446
|
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
| `to` | string ≤ 256 | For a missed call: who was rung. |
|
|
553
|
-
| `startedAt` | string ≤ 64 (ISO date) | required |
|
|
554
|
-
| `endedAt` | string ≤ 64 (ISO date) | For an ended call. |
|
|
555
|
-
| `people` | string[] ≤ 64 items, each ≤ 256 | For an ended call: every account seen in it. |
|
|
447
|
+
A place with a point also carries its `cells`: the geohash of `lat` and
|
|
448
|
+
`lon` at precisions 3, 4, 5 and 6, coarsest first. They're about 156 km,
|
|
449
|
+
39 km, 4.9 km and 1.2 km across. `cellsOf(lat, lon)` makes them.
|
|
556
450
|
|
|
557
|
-
|
|
451
|
+
For Grünerløkka in Oslo, `lat` 59.9226 and `lon` 10.7522 give
|
|
452
|
+
`["u4x", "u4xs", "u4xsu", "u4xsus"]`. Geohash here is Niemeyer's: longitude
|
|
453
|
+
and latitude bits interleaved, longitude first, five to a character of
|
|
454
|
+
`0123456789bcdefghjkmnpqrstuvwxyz`.
|
|
455
|
+
|
|
456
|
+
`std.event` and `std.listing` name `place.cells` as a topic, and `std.place`
|
|
457
|
+
names `cells`. So a keeper that can't read a private space can still hand
|
|
458
|
+
over "listings in these cells". Tags match only when equal, which is why
|
|
459
|
+
each size is written out instead of one long geohash.
|
|
460
|
+
|
|
461
|
+
### Finding what is nearby
|
|
462
|
+
|
|
463
|
+
`cellsAround(lat, lon, km)` gives the nine cells that cover a circle: the
|
|
464
|
+
point's own cell and the eight around it, at the finest precision whose
|
|
465
|
+
cells are at least `km` across. Match any of them, then let the exact
|
|
466
|
+
distance decide:
|
|
558
467
|
|
|
559
468
|
```json
|
|
560
|
-
{
|
|
561
|
-
"status": "ended",
|
|
562
|
-
"startedAt": "2026-09-26T10:00:00.000Z",
|
|
563
|
-
"endedAt": "2026-09-26T10:14:02.311Z",
|
|
564
|
-
"people": ["did:key:zDnaeSm3…", "did:key:zDnaeXL64…"]
|
|
565
|
-
}
|
|
469
|
+
{ "$or": [{ "place.cells": { "$contains": "u4xs" } }, { "place.cells": { "$contains": "u4xk" } }] }
|
|
566
470
|
```
|
|
567
471
|
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
472
|
+
`distanceKm` is haversine on a sphere of 6371.0088 km. `cellsAround` returns
|
|
473
|
+
null for a radius over about 150 km, or a circle around a pole. Then every
|
|
474
|
+
place is a candidate. A record written without cells is found only by its
|
|
475
|
+
point.
|
|
476
|
+
|
|
477
|
+
Nothing checks that `cells` agree with `lat` and `lon`. A peer only checks
|
|
478
|
+
that the tags match the cells. Apps that read the body use the point, so a
|
|
479
|
+
wrong cell only hides a record from area matches.
|
|
480
|
+
|
|
481
|
+
A listing usually means someone's home, so the example's marketplace keeps
|
|
482
|
+
only the part of town. It moves the point to the middle of its precision 6
|
|
483
|
+
cell and leaves out the street.
|
|
484
|
+
|
|
485
|
+
Finding places by name isn't part of the library. The example asks Photon,
|
|
486
|
+
which uses OpenStreetMap's data (set by `VITE_MINCA_PLACES`), and shows OpenStreetMap's credit beside the results.
|
|
487
|
+
See [spec 02 §8](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
|
|
488
|
+
|
|
489
|
+
## Changing a definition
|
|
490
|
+
|
|
491
|
+
Before v1 the library changes without migrations. A space that holds an
|
|
492
|
+
earlier definition keeps it until someone applies a blueprint that carries
|
|
493
|
+
the new one.
|
|
494
|
+
|
|
495
|
+
A field that becomes a topic tags only what is written after the change.
|
|
496
|
+
Older records carry no tags, so "mentions me" or "assigned to me" match only
|
|
497
|
+
from then on.
|
|
498
|
+
|
|
499
|
+
Recent changes:
|
|
500
|
+
|
|
501
|
+
- `std.attachment`, `std.photo`, `std.video`, `std.folder` and `std.album`
|
|
502
|
+
became one `std.file`. Groups of files are `std.list`s.
|
|
503
|
+
- `std.booking` is a `std.claim` about a `std.slot`. `std.bookmark` is a
|
|
504
|
+
`std.list-item`. `std.reference` is gone: any link refers.
|
|
505
|
+
- `std.message`'s `channel` link and `std.task`'s `column` link are now `in`.
|
|
506
|
+
- `std.vote` is for polls only. A proposal is decided by `std.ballot`s.
|
|
507
|
+
- `mentions`, `replyingTo`, `respondingTo` and `owedBy` were added, and the
|
|
508
|
+
people fields became topics
|
|
509
|
+
([#105](https://github.com/leifriksheim/minca/issues/105)).
|
|
510
|
+
|
|
511
|
+
## Planned
|
|
512
|
+
|
|
513
|
+
> **Planned:** references to other spaces. `std.follow`'s `space` is a plain
|
|
514
|
+
> space id, and a repost or list item can only point within its own space
|
|
515
|
+
> ([#38](https://github.com/leifriksheim/minca/issues/38),
|
|
516
|
+
> [spec 02 §5.3](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
|
|
571
517
|
|
|
572
|
-
|
|
518
|
+
> **Planned:** `format` in the schema dialect, to check `when`, `day` and
|
|
519
|
+
> `url` ([spec 02 §6.2](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
|