@minca/core 0.1.17 → 0.2.0
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 +3 -1
- 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/index.d.ts +1 -1
- package/dist/node/index.d.ts.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/node/watch-notifications.d.ts +6 -0
- package/dist/node/watch-notifications.d.ts.map +1 -1
- package/dist/node/watch-notifications.js +47 -9
- package/dist/node/watch-notifications.js.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/account-hint.d.ts +2 -2
- package/dist/session/account-hint.d.ts.map +1 -1
- package/dist/session/account-hint.js +3 -3
- package/dist/session/account-hint.js.map +1 -1
- package/dist/session/auth.d.ts +7 -3
- package/dist/session/auth.d.ts.map +1 -1
- package/dist/session/auth.js.map +1 -1
- package/dist/session/connection.d.ts +18 -0
- package/dist/session/connection.d.ts.map +1 -1
- package/dist/session/connection.js +11 -0
- package/dist/session/connection.js.map +1 -1
- package/dist/session/index.d.ts +2 -2
- package/dist/session/index.d.ts.map +1 -1
- package/dist/session/index.js +2 -2
- package/dist/session/index.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 +86 -159
- 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 +1081 -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 +487 -416
- package/docs/spaces.md +261 -246
- package/docs/standard-library.md +487 -526
- package/docs/storage.md +325 -348
- package/docs/usernames.md +164 -97
- package/docs/warrants.md +100 -67
- package/package.json +1 -6
- package/dist/elements/auth-styles.d.ts +0 -18
- package/dist/elements/auth-styles.d.ts.map +0 -1
- package/dist/elements/auth-styles.js +0 -206
- package/dist/elements/auth-styles.js.map +0 -1
- package/dist/elements/dom.d.ts +0 -29
- package/dist/elements/dom.d.ts.map +0 -1
- package/dist/elements/dom.js +0 -91
- package/dist/elements/dom.js.map +0 -1
- package/dist/elements/index.d.ts +0 -13
- package/dist/elements/index.d.ts.map +0 -1
- package/dist/elements/index.js +0 -11
- package/dist/elements/index.js.map +0 -1
- package/dist/elements/minca-auth.d.ts +0 -55
- package/dist/elements/minca-auth.d.ts.map +0 -1
- package/dist/elements/minca-auth.js +0 -768
- package/dist/elements/minca-auth.js.map +0 -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,114 @@ 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
|
-
```
|
|
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.
|
|
67
48
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
import { MincaProvider, MincaAuth, useMinca } from '@minca/react';
|
|
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.
|
|
71
51
|
|
|
72
|
-
|
|
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.
|
|
73
54
|
|
|
74
|
-
|
|
75
|
-
const { state } = useMinca();
|
|
76
|
-
if (state?.stage !== 'ready') return <MincaAuth />;
|
|
77
|
-
return <Todos />;
|
|
78
|
-
}
|
|
55
|
+
## The account home
|
|
79
56
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
57
|
+
The person's account, its settings and its other apps live at their home, not
|
|
58
|
+
in your app. Open it from a click, for the account your app acts for:
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
import type { MincaConnection } from '@minca/core/session';
|
|
62
|
+
declare const connection: MincaConnection;
|
|
63
|
+
// ---cut---
|
|
64
|
+
connection.openHome(); // the account page
|
|
65
|
+
connection.openHome('notifications'); // at a section of it
|
|
85
66
|
```
|
|
86
67
|
|
|
87
|
-
|
|
68
|
+
It opens in a window of its own, centred on yours. The home holds the
|
|
69
|
+
person's keys, so it is never shown inside your page.
|
|
88
70
|
|
|
89
|
-
|
|
71
|
+
## A collection
|
|
90
72
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
createNode,
|
|
94
|
-
createIdentityManager,
|
|
95
|
-
createLocalRootSigner,
|
|
96
|
-
indexedDBStores,
|
|
97
|
-
rolePresets,
|
|
98
|
-
} from '@minca/core';
|
|
73
|
+
Records live in collections, like rows in a table. Say what a to-do looks
|
|
74
|
+
like:
|
|
99
75
|
|
|
100
|
-
|
|
101
|
-
|
|
76
|
+
```ts
|
|
77
|
+
import * as z from 'zod';
|
|
78
|
+
import { collection } from '@minca/core';
|
|
102
79
|
|
|
103
|
-
const
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
80
|
+
export const todos = collection({
|
|
81
|
+
name: 'app.todo.item',
|
|
82
|
+
title: 'To-do',
|
|
83
|
+
schema: z.object({ text: z.string().min(1), done: z.boolean() }),
|
|
107
84
|
});
|
|
108
85
|
```
|
|
109
86
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
```typescript
|
|
115
|
-
const space = await node.spaces.create({ name: 'Groceries', visibility: 'private', ...rolePresets.team });
|
|
87
|
+
The definition is stored in the space itself, so any app that opens the space
|
|
88
|
+
knows what a to-do is. Add it once, with the `node` that `useNode()` gives
|
|
89
|
+
you in a component:
|
|
116
90
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
await node.spaces.join(invite); // on the friend's side
|
|
120
|
-
await node.spaces.closeInvite(space.id, invite); // nobody else joins with it
|
|
91
|
+
```ts
|
|
92
|
+
await node.collections.define(space.id, todos);
|
|
121
93
|
```
|
|
122
94
|
|
|
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` |
|
|
95
|
+
We'll look at schemas, rules and the shared standard collections in
|
|
96
|
+
[Collections](collections.md).
|
|
157
97
|
|
|
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
|
-
}
|
|
98
|
+
## Saving a record
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
await node.records.put(space.id, todos, { text: 'Buy milk', done: false });
|
|
166
102
|
```
|
|
167
103
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
104
|
+
The record is signed by the person, through your app's key, and syncs to
|
|
105
|
+
everyone else in the space. Because `todos` carries its schema, TypeScript
|
|
106
|
+
checks the body as you write it.
|
|
171
107
|
|
|
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.
|
|
108
|
+
## Showing records
|
|
176
109
|
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
page was opened with:
|
|
110
|
+
`useQuery` gives the records, and runs again whenever they change, here or
|
|
111
|
+
on someone else's device. `Todos`, which `App` shows once connected, picks the
|
|
112
|
+
space from the ones the person gave:
|
|
181
113
|
|
|
182
114
|
```tsx
|
|
183
|
-
import {
|
|
115
|
+
import { useQuery, useSpaces } from '@minca/react';
|
|
184
116
|
|
|
185
|
-
|
|
117
|
+
export function Todos() {
|
|
118
|
+
const { spaces } = useSpaces();
|
|
119
|
+
const space = spaces[0];
|
|
120
|
+
return space ? <TodoList space={space.id} /> : null;
|
|
121
|
+
}
|
|
186
122
|
|
|
187
|
-
function
|
|
188
|
-
const {
|
|
189
|
-
|
|
190
|
-
if (!invite || !preview) return null;
|
|
123
|
+
function TodoList({ space }: { space: string }) {
|
|
124
|
+
const { result } = useQuery(space, { collection: todos, sort: { '@createdAt': 'asc' } });
|
|
125
|
+
if (!result) return null;
|
|
191
126
|
return (
|
|
192
|
-
<
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
.then(dismiss)
|
|
198
|
-
}
|
|
199
|
-
>
|
|
200
|
-
Join {preview.space.name}
|
|
201
|
-
</button>
|
|
127
|
+
<ul>
|
|
128
|
+
{result.records.map((todo) => (
|
|
129
|
+
<li key={todo.key}>{todo.body.text}</li>
|
|
130
|
+
))}
|
|
131
|
+
</ul>
|
|
202
132
|
);
|
|
203
133
|
}
|
|
204
134
|
```
|
|
205
135
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
## Live messages
|
|
136
|
+
That's a whole app. Share the space with a friend, and you both see the same
|
|
137
|
+
list.
|
|
210
138
|
|
|
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
|
-
```
|
|
139
|
+
## Next steps
|
|
220
140
|
|
|
221
|
-
|
|
141
|
+
- [Records and queries](records-and-queries.md): editing, deleting, filters
|
|
142
|
+
and links between records.
|
|
143
|
+
- [Collections](collections.md): what a schema can say, and who may write
|
|
144
|
+
what.
|
|
145
|
+
- [Spaces](spaces.md): making spaces, and inviting people to them.
|
|
146
|
+
- [Signing in](sign-in.md): for an app that keeps the account itself,
|
|
147
|
+
instead of connecting to a home.
|
|
148
|
+
- [The node](node.md#react): every React hook.
|