@minca/core 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +2 -0
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/node-contacts.d.ts.map +1 -1
  22. package/dist/node/node-contacts.js +1 -0
  23. package/dist/node/node-contacts.js.map +1 -1
  24. package/dist/node/node-records.d.ts.map +1 -1
  25. package/dist/node/node-records.js +6 -1
  26. package/dist/node/node-records.js.map +1 -1
  27. package/dist/node/node.d.ts.map +1 -1
  28. package/dist/node/node.js +13 -1
  29. package/dist/node/node.js.map +1 -1
  30. package/dist/node/remote.d.ts.map +1 -1
  31. package/dist/node/remote.js +7 -1
  32. package/dist/node/remote.js.map +1 -1
  33. package/dist/node/space-runtime.d.ts +5 -3
  34. package/dist/node/space-runtime.d.ts.map +1 -1
  35. package/dist/node/space-runtime.js +3 -1
  36. package/dist/node/space-runtime.js.map +1 -1
  37. package/dist/node/types.d.ts +112 -36
  38. package/dist/node/types.d.ts.map +1 -1
  39. package/dist/query/types.d.ts +1 -0
  40. package/dist/query/types.d.ts.map +1 -1
  41. package/dist/query/types.js.map +1 -1
  42. package/dist/records/contract-builder.d.ts +22 -6
  43. package/dist/records/contract-builder.d.ts.map +1 -1
  44. package/dist/records/contract-builder.js.map +1 -1
  45. package/dist/schemas/automations.d.ts +6 -2
  46. package/dist/schemas/automations.d.ts.map +1 -1
  47. package/dist/schemas/automations.js.map +1 -1
  48. package/dist/schemas/connectors.d.ts +4 -3
  49. package/dist/schemas/connectors.d.ts.map +1 -1
  50. package/dist/schemas/connectors.js +4 -3
  51. package/dist/schemas/connectors.js.map +1 -1
  52. package/dist/schemas/library/media.js +1 -1
  53. package/dist/schemas/library/media.js.map +1 -1
  54. package/dist/session/auth.d.ts +7 -3
  55. package/dist/session/auth.d.ts.map +1 -1
  56. package/dist/session/auth.js.map +1 -1
  57. package/dist/storage/blob-store.d.ts +3 -0
  58. package/dist/storage/blob-store.d.ts.map +1 -1
  59. package/dist/types.d.ts +11 -2
  60. package/dist/types.d.ts.map +1 -1
  61. package/dist/types.js.map +1 -1
  62. package/docs/README.md +86 -93
  63. package/docs/actions.md +213 -152
  64. package/docs/agents.md +198 -167
  65. package/docs/automations.md +296 -204
  66. package/docs/blueprints-and-guides.md +405 -311
  67. package/docs/bots.md +208 -134
  68. package/docs/building-an-app.md +74 -163
  69. package/docs/collections.md +248 -328
  70. package/docs/computed.md +112 -89
  71. package/docs/contacts.md +151 -112
  72. package/docs/contracts.md +299 -120
  73. package/docs/direct-messages.md +80 -65
  74. package/docs/inbox.md +138 -93
  75. package/docs/node.md +1072 -996
  76. package/docs/permissions.md +142 -0
  77. package/docs/proposing-collections.md +74 -55
  78. package/docs/query-format.md +150 -126
  79. package/docs/records-and-queries.md +205 -126
  80. package/docs/sign-in.md +496 -418
  81. package/docs/spaces.md +261 -246
  82. package/docs/standard-library.md +473 -526
  83. package/docs/storage.md +325 -348
  84. package/docs/usernames.md +164 -97
  85. package/docs/warrants.md +100 -67
  86. package/package.json +1 -1
@@ -1,25 +1,27 @@
1
1
  # Building an app
2
2
 
3
- An app needs a node. There are two ways to get one, and they end in the same
4
- place: a `P2PNode` you read and write through.
3
+ A Minca app keeps its data in the person's own spaces, not on a server of
4
+ yours. On this page we'll build a small to-do list: connect, save a to-do, and
5
+ show the list as it changes.
5
6
 
6
- ## Connect to the person's account home (recommended)
7
+ ## Connecting
7
8
 
8
- The app never sees the account's seed. It asks the person's account home for
9
- access, the person picks which spaces it gets, and the home signs a note from
10
- the account to a key the app made for itself. Every peer checks that note, so
11
- the app cannot write anywhere it was not given.
9
+ Every app starts by asking the person for access, with
10
+ `createMincaConnection`. Wrap your app in `MincaProvider`, and use
11
+ `useConnection` to show a button until the person has said yes:
12
12
 
13
13
  ```tsx
14
+ declare function Todos(): React.JSX.Element;
15
+ // ---cut---
16
+ import { createRoot } from 'react-dom/client';
14
17
  import { createMincaConnection } from '@minca/core/session';
15
18
  import { MincaProvider, useConnection } from '@minca/react';
16
19
 
17
20
  const connection = createMincaConnection({
18
- home: 'https://home.minca.social/connect', // a suggestion: the person may use their own
21
+ home: 'https://home.minca.social/connect',
19
22
  request: {
20
23
  name: 'Todo',
21
- access: 'write', // or 'read'
22
- scope: 'spaces', // or 'account', for every space
24
+ access: 'write',
23
25
  create: [{ name: 'Todos', visibility: 'private' }],
24
26
  },
25
27
  network: { relays: ['wss://relay.minca.social'] },
@@ -33,189 +35,98 @@ createRoot(root).render(
33
35
 
34
36
  function App() {
35
37
  const { connection, state } = useConnection();
36
- if (state.status !== 'ready')
38
+ if (state.status !== 'ready') {
37
39
  return <button onClick={() => connection.connect()}>Connect with Minca</button>;
40
+ }
38
41
  return <Todos />;
39
42
  }
40
43
  ```
41
44
 
42
- - The grant lasts seven days and is remembered between visits. When it runs
43
- out, `state.status` is `expired`, and connecting again renews it.
44
- - `scope: 'spaces'` gives the spaces the person picks, plus any the app asked
45
- to `create`. `scope: 'account'` gives every space, and lets the app make and
46
- join spaces. Ask for the narrower one unless the app is a view onto
47
- everything.
48
- - Without React: `connectToHome`, `startConnectedNode` and `grantStore` from
49
- `@minca/core/session`.
50
-
51
- ## Sign in inside the app
52
-
53
- For an app that holds the account itself. The flow (where data lives, which
54
- account, password or passkey, creating one, pairing a phone) ships as an
55
- element and as a React component.
56
-
57
- ```html
58
- <minca-auth app-name="Todo" relays="wss://relay.minca.social"></minca-auth>
59
- <script type="module">
60
- import '@minca/core/elements';
61
- document.querySelector('minca-auth').addEventListener('minca-session', (event) => {
62
- const session = event.detail.session; // { account, did, sessionDid, node }, or null
63
- if (session) start(session.node);
64
- });
65
- </script>
66
- ```
67
-
68
- ```tsx
69
- import { createMincaAuth } from '@minca/core/session';
70
- import { MincaProvider, MincaAuth, useMinca } from '@minca/react';
71
-
72
- const auth = createMincaAuth({ appName: 'Todo', network: { relays: ['wss://relay.minca.social'] } });
73
-
74
- function App() {
75
- const { state } = useMinca();
76
- if (state?.stage !== 'ready') return <MincaAuth />;
77
- return <Todos />;
78
- }
45
+ `home` is where the person's account lives. They see your app's name and what
46
+ it asks for, and pick which of their spaces to give it. `create` asks for a
47
+ new space just for your app, so there's somewhere to start.
79
48
 
80
- createRoot(root).render(
81
- <MincaProvider auth={auth}>
82
- <App />
83
- </MincaProvider>,
84
- );
85
- ```
49
+ Your app never sees the person's keys. It gets a key of its own, allowed into
50
+ the spaces it was given and nowhere else.
86
51
 
87
- ## A node by hand
52
+ The connection is remembered between visits, and lasts a week. When it runs
53
+ out, `state.status` is `'expired'`, and connecting again renews it.
88
54
 
89
- For scripts, tests and servers:
55
+ ## A collection
90
56
 
91
- ```typescript
92
- import {
93
- createNode,
94
- createIdentityManager,
95
- createLocalRootSigner,
96
- indexedDBStores,
97
- rolePresets,
98
- } from '@minca/core';
57
+ Records live in collections, like rows in a table. Say what a to-do looks
58
+ like:
99
59
 
100
- const manager = createIdentityManager();
101
- const me = await manager.fromRecoveryCode(code);
60
+ ```ts
61
+ import * as z from 'zod';
62
+ import { collection } from '@minca/core';
102
63
 
103
- const node = await createNode({
104
- signer: createLocalRootSigner(me, manager.getProvider()),
105
- stores: indexedDBStores('my-app'),
106
- network: { relays: ['wss://relay.minca.social'] },
64
+ export const todos = collection({
65
+ name: 'app.todo.item',
66
+ title: 'To-do',
67
+ schema: z.object({ text: z.string().min(1), done: z.boolean() }),
107
68
  });
108
69
  ```
109
70
 
110
- Leave out `network` to stay offline. Call `node.close()` when done.
71
+ The definition is stored in the space itself, so any app that opens the space
72
+ knows what a to-do is. Add it once, with the `node` that `useNode()` gives
73
+ you in a component:
111
74
 
112
- ## Spaces
113
-
114
- ```typescript
115
- const space = await node.spaces.create({ name: 'Groceries', visibility: 'private', ...rolePresets.team });
116
-
117
- const invite = await node.spaces.invite(space.id, { short: true }); // ~85 characters; treat it as a secret
118
- const view = await node.spaces.invite(space.id, { write: false }); // read-only
119
- await node.spaces.join(invite); // on the friend's side
120
- await node.spaces.closeInvite(space.id, invite); // nobody else joins with it
75
+ ```ts
76
+ await node.collections.define(space.id, todos);
121
77
  ```
122
78
 
123
- - `rolePresets` are constitution templates: `solo` (just you; invites are
124
- view-only), `team` (everyone invited can write, invite and add
125
- collections), `community` (admins, moderators, members) and `coop` (no
126
- founders: stewards and members, `top: 'none'`). Or pass your own `roles`.
127
- Under the first three you are the space's founder: you hold every command,
128
- and nobody else can remove you; `spaces.stepDown` gives that up
129
- ([spaces.md](spaces.md#the-top-and-founders)).
130
- - A private invite carries the space key. Anyone holding it can read the
131
- space, so don't log it or put it in a URL a server sees (use the fragment,
132
- `#invite=…`).
133
- - `node.spaces.list()` gives every space this node has, with `readable`,
134
- `writable` and `role`.
135
-
136
- ## React hooks
137
-
138
- All from `@minca/react`, below a `MincaProvider`:
139
-
140
- | Hook | Gives |
141
- | ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
142
- | `useNode()` | The node, to write with |
143
- | `useSpaces({ having? })` | The spaces, kept current, with `create`, `join`, `leave` |
144
- | `useQuery(space, query)` | `{ result, error }`, re-run as records change here or arrive from peers |
145
- | `useRecord(space, key)` / `useLinked(space, key)` | One record; the records pointing at it |
146
- | `useCollections(space)` / `useProfiles(space)` / `useAccess(space)` | What a space holds; who is in it; roles and members |
147
- | `useSpaceStatus(space)` | Connection and peers |
148
- | `useCan(space, action, target)` | Whether to show an edit or delete button |
149
- | `useHoldSpace(space)` | Keeps a space syncing while the view is on screen |
150
- | `useLive(space, load, deps)` | Anything else, reloaded as the space changes |
151
- | `useWatched(load, deps, { when, settle, every })` | Anything else, reloaded after the node events you pick |
152
- | `useAsync(load, deps)` | One answer: `loading`, `done` with its value, or `failed` |
153
- | `useAccountPicture()` | The account's picture as a URL, or null |
154
- | `useNames(space)` | `name(did)`: what someone is called there, never passing for another |
155
- | `useMyName()` | The account's name, to ask for when making or joining a space |
156
- | `useInviteLink()` | The invite this page was opened with, what it is for, and `dismiss` |
79
+ We'll look at schemas, rules and the shared standard collections in
80
+ [Collections](collections.md).
157
81
 
158
- ```tsx
159
- function Todos({ space }: { space: string }) {
160
- const node = useNode();
161
- const { result } = useQuery(space, { collection: todos, sort: { '@createdAt': 'asc' } });
162
- if (!result) return null;
163
- if (!result.complete && result.records.length === 0) return <p>Loading…</p>;
164
- return result.records.map((todo) => <Todo key={todo.key} todo={todo} />);
165
- }
82
+ ## Saving a record
83
+
84
+ ```ts
85
+ await node.records.put(space.id, todos, { text: 'Buy milk', done: false });
166
86
  ```
167
87
 
168
- **An app given the whole account** sees every space in it. `useSpaces({ having: [proposal] })`
169
- lists only the spaces that define those collections: the ones the app works in.
170
- A space still being joined is kept, since its definitions haven't arrived yet.
88
+ The record is signed by the person, through your app's key, and syncs to
89
+ everyone else in the space. Because `todos` carries its schema, TypeScript
90
+ checks the body as you write it.
171
91
 
172
- **Names.** A name is whatever its owner typed, so two people can both be "Sam".
173
- `useNames(space)` (or `displayName(did, profiles)` from `@minca/core`)
174
- adds the tail of the identity when a name is shared, and shows the tail alone
175
- for someone with no profile.
92
+ ## Showing records
176
93
 
177
- **Invite links** carry the invite after `#`, which browsers never send to a
178
- server. `inviteLink(invite)` makes one for this page, `inviteFromLink(text)`
179
- takes the invite out of a pasted link, and `useInviteLink()` reads the one the
180
- page was opened with:
94
+ `useQuery` gives the records, and runs again whenever they change, here or
95
+ on someone else's device. `Todos`, which `App` shows once connected, picks the
96
+ space from the ones the person gave:
181
97
 
182
98
  ```tsx
183
- import { inviteLink, useInviteLink, useMyName, useNode } from '@minca/react';
99
+ import { useQuery, useSpaces } from '@minca/react';
184
100
 
185
- const link = inviteLink(await node.spaces.invite(space.id, { short: true })); // https://app.example/#invite=…
101
+ export function Todos() {
102
+ const { spaces } = useSpaces();
103
+ const space = spaces[0];
104
+ return space ? <TodoList space={space.id} /> : null;
105
+ }
186
106
 
187
- function Invited({ onJoin }: { onJoin: (invite: string) => Promise<unknown> }) {
188
- const { invite, preview, dismiss } = useInviteLink();
189
- const me = useMyName();
190
- if (!invite || !preview) return null;
107
+ function TodoList({ space }: { space: string }) {
108
+ const { result } = useQuery(space, { collection: todos, sort: { '@createdAt': 'asc' } });
109
+ if (!result) return null;
191
110
  return (
192
- <button
193
- onClick={() =>
194
- void me
195
- .save()
196
- .then(() => onJoin(invite))
197
- .then(dismiss)
198
- }
199
- >
200
- Join {preview.space.name}
201
- </button>
111
+ <ul>
112
+ {result.records.map((todo) => (
113
+ <li key={todo.key}>{todo.body.text}</li>
114
+ ))}
115
+ </ul>
202
116
  );
203
117
  }
204
118
  ```
205
119
 
206
- `result.complete` is false while an app that holds only part of a space is
207
- still fetching a collection. Show "Loading…", not "Nothing here".
208
-
209
- ## Live messages
120
+ That's a whole app. Share the space with a friend, and you both see the same
121
+ list.
210
122
 
211
- For things that should reach whoever is connected now and be kept nowhere,
212
- like typing or presence:
213
-
214
- ```typescript
215
- await node.spaces.send(space.id, { type: 'typing' });
216
- node.subscribe((event) => {
217
- if (event.type === 'message') console.log(event.from, event.message); // from: the sender's account
218
- });
219
- ```
123
+ ## Next steps
220
124
 
221
- At most 64 KB each. Someone who isn't connected misses it.
125
+ - [Records and queries](records-and-queries.md): editing, deleting, filters
126
+ and links between records.
127
+ - [Collections](collections.md): what a schema can say, and who may write
128
+ what.
129
+ - [Spaces](spaces.md): making spaces, and inviting people to them.
130
+ - [Signing in](sign-in.md): for an app that keeps the account itself,
131
+ instead of connecting to a home.
132
+ - [The node](node.md#react): every React hook.