@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/building-an-app.md
CHANGED
|
@@ -1,25 +1,27 @@
|
|
|
1
1
|
# Building an app
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
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
|
-
##
|
|
7
|
+
## Connecting
|
|
7
8
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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',
|
|
21
|
+
home: 'https://home.minca.social/connect',
|
|
19
22
|
request: {
|
|
20
23
|
name: 'Todo',
|
|
21
|
-
access: 'write',
|
|
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
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
81
|
-
|
|
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
|
-
|
|
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
|
-
|
|
55
|
+
## A collection
|
|
90
56
|
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
|
|
101
|
-
|
|
60
|
+
```ts
|
|
61
|
+
import * as z from 'zod';
|
|
62
|
+
import { collection } from '@minca/core';
|
|
102
63
|
|
|
103
|
-
const
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
124
|
-
|
|
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
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
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
|
-
|
|
169
|
-
|
|
170
|
-
|
|
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
|
-
|
|
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
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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 {
|
|
99
|
+
import { useQuery, useSpaces } from '@minca/react';
|
|
184
100
|
|
|
185
|
-
|
|
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
|
|
188
|
-
const {
|
|
189
|
-
|
|
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
|
-
<
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
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
|
-
|
|
207
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|