@minca/core 0.1.13 → 0.1.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (148) hide show
  1. package/README.md +2 -2
  2. package/dist/files/space-files.d.ts +15 -3
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +225 -37
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/index.d.ts +1 -1
  7. package/dist/index.d.ts.map +1 -1
  8. package/dist/index.js +1 -1
  9. package/dist/index.js.map +1 -1
  10. package/dist/network/introductions.d.ts +20 -7
  11. package/dist/network/introductions.d.ts.map +1 -1
  12. package/dist/network/introductions.js +9 -6
  13. package/dist/network/introductions.js.map +1 -1
  14. package/dist/network/mesh.d.ts.map +1 -1
  15. package/dist/network/mesh.js +88 -20
  16. package/dist/network/mesh.js.map +1 -1
  17. package/dist/network/relay-minca.d.ts +12 -1
  18. package/dist/network/relay-minca.d.ts.map +1 -1
  19. package/dist/network/relay-minca.js +14 -6
  20. package/dist/network/relay-minca.js.map +1 -1
  21. package/dist/network/relay-nostr.d.ts +14 -3
  22. package/dist/network/relay-nostr.d.ts.map +1 -1
  23. package/dist/network/relay-nostr.js +11 -9
  24. package/dist/network/relay-nostr.js.map +1 -1
  25. package/dist/network/relays.d.ts +26 -17
  26. package/dist/network/relays.d.ts.map +1 -1
  27. package/dist/network/relays.js +21 -28
  28. package/dist/network/relays.js.map +1 -1
  29. package/dist/network/rendezvous.d.ts +1 -1
  30. package/dist/network/rendezvous.d.ts.map +1 -1
  31. package/dist/network/rendezvous.js +2 -2
  32. package/dist/network/rendezvous.js.map +1 -1
  33. package/dist/node/actions.d.ts.map +1 -1
  34. package/dist/node/actions.js +54 -2
  35. package/dist/node/actions.js.map +1 -1
  36. package/dist/node/node.d.ts.map +1 -1
  37. package/dist/node/node.js +7 -7
  38. package/dist/node/node.js.map +1 -1
  39. package/dist/node/space-runtime.d.ts +1 -1
  40. package/dist/node/space-runtime.d.ts.map +1 -1
  41. package/dist/node/space-runtime.js +17 -5
  42. package/dist/node/space-runtime.js.map +1 -1
  43. package/dist/node/types.d.ts +4 -3
  44. package/dist/node/types.d.ts.map +1 -1
  45. package/dist/schema/collection-def.d.ts.map +1 -1
  46. package/dist/schema/collection-def.js +16 -5
  47. package/dist/schema/collection-def.js.map +1 -1
  48. package/dist/schemas/automations.d.ts +8 -0
  49. package/dist/schemas/automations.d.ts.map +1 -1
  50. package/dist/schemas/blueprints.d.ts +33 -0
  51. package/dist/schemas/blueprints.d.ts.map +1 -1
  52. package/dist/schemas/blueprints.js +63 -0
  53. package/dist/schemas/blueprints.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +12 -0
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/fragments.d.ts +22 -2
  57. package/dist/schemas/fragments.d.ts.map +1 -1
  58. package/dist/schemas/fragments.js +20 -12
  59. package/dist/schemas/fragments.js.map +1 -1
  60. package/dist/schemas/library/annotations.d.ts +30 -0
  61. package/dist/schemas/library/annotations.d.ts.map +1 -1
  62. package/dist/schemas/library/annotations.js +1 -0
  63. package/dist/schemas/library/annotations.js.map +1 -1
  64. package/dist/schemas/library/community.d.ts +28 -0
  65. package/dist/schemas/library/community.d.ts.map +1 -1
  66. package/dist/schemas/library/life.d.ts +62 -2
  67. package/dist/schemas/library/life.d.ts.map +1 -1
  68. package/dist/schemas/library/media.d.ts +36 -0
  69. package/dist/schemas/library/media.d.ts.map +1 -1
  70. package/dist/schemas/library/money.d.ts +74 -2
  71. package/dist/schemas/library/money.d.ts.map +1 -1
  72. package/dist/schemas/library/planning.d.ts +56 -0
  73. package/dist/schemas/library/planning.d.ts.map +1 -1
  74. package/dist/schemas/library/publishing.d.ts +80 -4
  75. package/dist/schemas/library/publishing.d.ts.map +1 -1
  76. package/dist/schemas/library/social.d.ts +44 -0
  77. package/dist/schemas/library/social.d.ts.map +1 -1
  78. package/docs/README.md +2 -2
  79. package/docs/actions.md +83 -56
  80. package/docs/blueprints-and-guides.md +41 -13
  81. package/docs/building-an-app.md +4 -4
  82. package/docs/collections.md +31 -3
  83. package/docs/node.md +15 -13
  84. package/docs/proposing-collections.md +42 -0
  85. package/docs/standard-library.md +26 -25
  86. package/docs/storage.md +33 -10
  87. package/package.json +2 -21
  88. package/dist/calls/calls.d.ts +0 -140
  89. package/dist/calls/calls.d.ts.map +0 -1
  90. package/dist/calls/calls.js +0 -861
  91. package/dist/calls/calls.js.map +0 -1
  92. package/dist/calls/index.d.ts +0 -4
  93. package/dist/calls/index.d.ts.map +0 -1
  94. package/dist/calls/index.js +0 -3
  95. package/dist/calls/index.js.map +0 -1
  96. package/dist/react/context.d.ts +0 -81
  97. package/dist/react/context.d.ts.map +0 -1
  98. package/dist/react/context.js +0 -97
  99. package/dist/react/context.js.map +0 -1
  100. package/dist/react/follow.d.ts +0 -11
  101. package/dist/react/follow.d.ts.map +0 -1
  102. package/dist/react/follow.js +0 -7
  103. package/dist/react/follow.js.map +0 -1
  104. package/dist/react/index.d.ts +0 -44
  105. package/dist/react/index.d.ts.map +0 -1
  106. package/dist/react/index.js +0 -40
  107. package/dist/react/index.js.map +0 -1
  108. package/dist/react/minca-auth.d.ts +0 -19
  109. package/dist/react/minca-auth.d.ts.map +0 -1
  110. package/dist/react/minca-auth.js +0 -36
  111. package/dist/react/minca-auth.js.map +0 -1
  112. package/dist/react/use-calls.d.ts +0 -21
  113. package/dist/react/use-calls.d.ts.map +0 -1
  114. package/dist/react/use-calls.js +0 -39
  115. package/dist/react/use-calls.js.map +0 -1
  116. package/dist/react/use-invite-link.d.ts +0 -24
  117. package/dist/react/use-invite-link.d.ts.map +0 -1
  118. package/dist/react/use-invite-link.js +0 -62
  119. package/dist/react/use-invite-link.js.map +0 -1
  120. package/dist/react/use-live.d.ts +0 -16
  121. package/dist/react/use-live.d.ts.map +0 -1
  122. package/dist/react/use-live.js +0 -56
  123. package/dist/react/use-live.js.map +0 -1
  124. package/dist/react/use-my-name.d.ts +0 -12
  125. package/dist/react/use-my-name.d.ts.map +0 -1
  126. package/dist/react/use-my-name.js +0 -38
  127. package/dist/react/use-my-name.js.map +0 -1
  128. package/dist/react/use-names.d.ts +0 -7
  129. package/dist/react/use-names.d.ts.map +0 -1
  130. package/dist/react/use-names.js +0 -13
  131. package/dist/react/use-names.js.map +0 -1
  132. package/dist/react/use-network.d.ts +0 -9
  133. package/dist/react/use-network.d.ts.map +0 -1
  134. package/dist/react/use-network.js +0 -33
  135. package/dist/react/use-network.js.map +0 -1
  136. package/dist/react/use-query.d.ts +0 -14
  137. package/dist/react/use-query.d.ts.map +0 -1
  138. package/dist/react/use-query.js +0 -26
  139. package/dist/react/use-query.js.map +0 -1
  140. package/dist/react/use-space.d.ts +0 -29
  141. package/dist/react/use-space.d.ts.map +0 -1
  142. package/dist/react/use-space.js +0 -57
  143. package/dist/react/use-space.js.map +0 -1
  144. package/dist/react/use-spaces.d.ts +0 -29
  145. package/dist/react/use-spaces.d.ts.map +0 -1
  146. package/dist/react/use-spaces.js +0 -78
  147. package/dist/react/use-spaces.js.map +0 -1
  148. package/docs/calls.md +0 -189
package/docs/calls.md DELETED
@@ -1,189 +0,0 @@
1
- # Calls
2
-
3
- A call is voice and video between the members of a space. It is live messages
4
- in that space ([spec 04 §9.2](https://github.com/leifriksheim/minca/blob/main/spec/04-network.md)),
5
- plus one WebRTC connection of its own between each pair of devices in it (a
6
- full mesh, good up to about six people with video). Its history is a [`std.call`](standard-library.md#stdcall)
7
- record.
8
-
9
- This is a convention built on the protocol, not part of it. Peers that have
10
- never heard of calls sync, store and judge every record the same way; a call
11
- message is a live message like any other to them. Only apps that want to call
12
- each other have to agree on the messages below. It uses these protocol parts:
13
- live messages and the space's peer connection
14
- ([spec 04](https://github.com/leifriksheim/minca/blob/main/spec/04-network.md)),
15
- roles ([spec 03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)),
16
- and TURN from relays (spec 04 §10).
17
-
18
- The setup travels over the space's peer connection, whose handshake proved
19
- who is at the other end, so an offer really comes from that device. A relay
20
- only introduces devices and never sees a call.
21
-
22
- In the library, `createCalls(node)` from `@minca/core/calls` runs all
23
- of it; in React, `CallsProvider` and `useCalls` ([node.md](node.md#client-conveniences)).
24
-
25
- ```ts
26
- import { createCalls } from '@minca/core/calls';
27
-
28
- const calls = createCalls(node);
29
- await calls.start(space); // join the call going on here, or start one
30
- await calls.ring(space, account); // or ring one person
31
- ```
32
-
33
- ## Messages
34
-
35
- Every call message is a JSON object with a `type` and a `call` id: a string
36
- of 1–64 characters (the library makes 12 random bytes in lowercase hex). A
37
- receiver must ignore a call message that is not one of these types, lacks a
38
- valid `call`, comes from a peer with no account (`from: null`), or comes from
39
- a key whose note writes records somewhere but can't define collections in
40
- this space (`recordsOnly: true`, a `/record` note), judged on the whole note,
41
- so a key given records in another space doesn't pass as the account here. The account trusts such a key less
42
- than itself, and in a call it would speak as the account. A key whose note
43
- only reads (`/record/read`) is not one: it may take part, as an app that only
44
- reads may. Its note can't tell whether it was asked for records only, since
45
- both kinds of read note are the same. This keeps an honest records-only program out of calls; it is
46
- not a boundary against a hostile app, which can ask the account for a read
47
- note for the same key and show that one instead. An app given write in one
48
- space only is also kept out of calls in others.
49
-
50
- | `type` | Sent to | Fields | Meaning |
51
- | --------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------- |
52
- | `call.here` | the space, every `heartbeat` (5 s); or one device | `since` (ms, when the sender joined), `camera` (bool), `muted` (bool) | "I am in this call." |
53
- | `call.ring` | one account | — | Ring that account's devices. |
54
- | `call.answered` | the caller's account, and the answerer's own account | — | Answered; stop ringing. |
55
- | `call.declined` | the caller's account, and the decliner's own account | — | Declined; stop ringing. |
56
- | `call.cancel` | the rung account | — | The caller stopped ringing. |
57
- | `call.signal` | one device | `description` (`{ type: "offer"\|"answer", sdp }`) or `candidate` (`RTCIceCandidateInit`) | Connection setup. |
58
- | `call.leave` | the space | — | "I left", now rather than after the timeout. |
59
-
60
- Examples:
61
-
62
- ```json
63
- { "type": "call.here", "call": "3f9a1c0b7e2d4a6f8b1c2d3e", "since": 1790422901000, "camera": false, "muted": false }
64
- { "type": "call.signal", "call": "3f9a1c0b7e2d4a6f8b1c2d3e", "description": { "type": "offer", "sdp": "v=0\r\n…" } }
65
- ```
66
-
67
- ## Who takes part
68
-
69
- Only **members**, the space's founders and accounts holding a role there,
70
- take part. A receiver must ignore `call.here`, `call.ring` and `call.signal`
71
- from an account that is neither (a view-only reader). The library caches the member list
72
- for 10 s and asks once more for someone not in it.
73
-
74
- A device must not ring for more than 3 `call.ring`s from one account in any
75
- 60 s; later ones are ignored. `call.cancel` is honoured only from the account
76
- that rang.
77
-
78
- > **Planned: blocked people do not ring.** A device will ignore `call.ring`
79
- > from an account the person has blocked (`contacts.block`,
80
- > [spec 03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)).
81
- > Today a ring is checked only for membership and rate. Tracked in
82
- > [#20](https://github.com/leifriksheim/minca/issues/20).
83
-
84
- ## Presence
85
-
86
- A device is in at most one call per space at a time: a `call.here` for
87
- another call moves it. A device not heard from for 15 s (`gone`) is dropped,
88
- and the connection to it closed. On hearing a new device's first `call.here`
89
- in the call it is in, a device sends its own `call.here` straight to that
90
- device.
91
-
92
- ## Joining, and which call
93
-
94
- `start(space)` joins the call already going on in the space (the one with the
95
- lowest id, if several) or starts one with a new id. Joining holds the space
96
- ([holding a space](node.md#opening-and-holding-spaces)) for as long as the
97
- call lasts, so moving between screens never interrupts it. When a device
98
- alone in its call (no connections yet) hears a `call.here` for a call with a
99
- lower id in the same space, it moves into that call: two calls started at
100
- once merge into the lower id.
101
-
102
- ## Connections
103
-
104
- - Between two devices, the one with the **lower session DID** (by string
105
- comparison) makes the offer. A device must ignore an offer from a device
106
- whose session DID is higher than its own, and an answer on a connection it
107
- did not offer or that already has one.
108
- - Each connection is made with one audio and one video transceiver
109
- (`sendrecv`) from the start. Muting, turning the camera on or off and
110
- sharing the screen replace the sender's track and are announced with
111
- `call.here`; they never renegotiate.
112
- - Candidates arriving before the remote description are queued (at most 64).
113
- - The offering side keeps at most one connection to each device, and offers
114
- only to a device it has none with.
115
- - When a connection fails, or its offer or answer cannot be applied, the
116
- offering side offers again after 2 s if the other device is still in the
117
- call. A connection not connected within `gone` (15 s) of its offer counts as
118
- failed too: an offer or answer lost on the way leaves a connection that
119
- never fails, only never connects.
120
- - ICE servers come from `node.iceServers()` ([node.md](node.md)): the
121
- configured ones plus TURN servers a relay offers.
122
-
123
- ## Ringing
124
-
125
- 1. The caller starts (or joins) the call, sends `call.ring` to the callee's
126
- account and shows `outgoing: ringing`.
127
- 2. The callee's devices ring for 45 s unless answered, declined or cancelled.
128
- A ring also stops when the caller's device has left the call, or has not
129
- been heard in it for `gone` (15 s): a page that closed without a
130
- `call.leave` rings nobody.
131
- 3. Answering: stop ringing, join the call (with that id), send
132
- `call.answered` to the caller's account and to one's own account (so other
133
- devices stop). Joining a call that is ringing the device, by any route, is
134
- answering it. Declining: `call.declined` the same way.
135
- 4. The caller on `call.answered` clears `outgoing`; on `call.declined` shows
136
- `declined` and, if nobody else is in the call 2.5 s later, leaves. A
137
- `call.here` in the call from the rung account clears `outgoing` too, so an
138
- answer lost on the way still stops the ringing.
139
- 5. After 45 s unanswered, the caller sends `call.cancel`, writes a missed-call
140
- record ([`std.call`](standard-library.md#stdcall)), shows `missed`, and
141
- leaves 2.5 s later if alone.
142
-
143
- A device must not ring again for a call it stopped ringing for (answered,
144
- declined, cancelled or timed out) in the last 90 s: the same `call.ring` can
145
- arrive twice.
146
-
147
- Group calls do not ring: a call going on shows to everyone with the space
148
- open.
149
-
150
- ## Leaving
151
-
152
- Leaving closes every connection, stops the local tracks, sends `call.leave`
153
- to the space, and, if still ringing someone, sends `call.cancel` and writes a
154
- missed-call record. If nobody else is left in the call and anyone else was
155
- ever in it, the leaver writes an ended-call record. The space's hold is
156
- released 1 s later, so the goodbye gets out first.
157
-
158
- The call a device is in is kept in `sessionStorage` under `minca-call`, so
159
- after a reload the page can offer to rejoin
160
- ([`std.call`](standard-library.md#stdcall)).
161
-
162
- Reference values, all in `createCalls`'s options or constants: `heartbeatMs`
163
- 5 s, `goneMs` 15 s, `ringMs` 45 s; 2 s before offering again, 2.5 s before
164
- giving up on a declined or missed ring, 1 s before letting go of the space,
165
- 10 s for the member list.
166
-
167
- _Source: `packages/core/src/calls/calls.ts` (`createCalls`, `isCallMessage`, `RINGS_PER_MINUTE`, `GIVE_UP_MS`, `LEAVE_LINGER_MS`, `MEMBERS_MS`, `RETRY_MS`), `packages/core/src/react/use-calls.ts`, `packages/core/src/node/space-runtime.ts` (`accountOf`). Tests: `packages/core/tests/calls.test.ts`, `packages/core/tests/live.test.ts` ("recordsOnly marks a note that writes records here and nothing more, not one that only reads"), `packages/core/tests/live-elsewhere.test.ts`._
168
-
169
- ## Planned
170
-
171
- > **Planned.** Not settled.
172
- >
173
- > - **Ringing with the app closed.** A ring reaches only devices with the
174
- > space open. Reaching a closed browser or a phone needs Web Push from a
175
- > carrier ([spec 06 §4.4](https://github.com/leifriksheim/minca/blob/main/spec/06-nodes-and-sessions.md), Planned);
176
- > the extension, always running while the browser is, could ring too. Not
177
- > designed: a live message is not a record, so a carrier has nothing to
178
- > match a ring against today.
179
- > - **Big calls.** Past about 6 video streams a full mesh runs out of upload
180
- > bandwidth. The known answer is a forwarding server (an SFU) with
181
- > end-to-end encryption on top (SFrame), so it forwards media it cannot
182
- > watch. A host could run one. Not designed.
183
- > - **Listening without talking.** View-only readers are kept out of calls
184
- > ([who takes part](#who-takes-part)). A space where readers may listen
185
- > could come as a grant held by a role, e.g. a library command `/call/listen`
186
- > ([spec 03](https://github.com/leifriksheim/minca/blob/main/spec/03-spaces.md)). Open.
187
- > - **Calls across apps.** A call lives in the app that started it; another
188
- > app on another origin does not see it. Moving a call between apps would
189
- > need the account home to hold it. No plan yet.