@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.
Files changed (120) 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 +3 -1
  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/index.d.ts +1 -1
  22. package/dist/node/index.d.ts.map +1 -1
  23. package/dist/node/node-contacts.d.ts.map +1 -1
  24. package/dist/node/node-contacts.js +1 -0
  25. package/dist/node/node-contacts.js.map +1 -1
  26. package/dist/node/node-records.d.ts.map +1 -1
  27. package/dist/node/node-records.js +6 -1
  28. package/dist/node/node-records.js.map +1 -1
  29. package/dist/node/node.d.ts.map +1 -1
  30. package/dist/node/node.js +13 -1
  31. package/dist/node/node.js.map +1 -1
  32. package/dist/node/remote.d.ts.map +1 -1
  33. package/dist/node/remote.js +7 -1
  34. package/dist/node/remote.js.map +1 -1
  35. package/dist/node/space-runtime.d.ts +5 -3
  36. package/dist/node/space-runtime.d.ts.map +1 -1
  37. package/dist/node/space-runtime.js +3 -1
  38. package/dist/node/space-runtime.js.map +1 -1
  39. package/dist/node/types.d.ts +112 -36
  40. package/dist/node/types.d.ts.map +1 -1
  41. package/dist/node/watch-notifications.d.ts +6 -0
  42. package/dist/node/watch-notifications.d.ts.map +1 -1
  43. package/dist/node/watch-notifications.js +47 -9
  44. package/dist/node/watch-notifications.js.map +1 -1
  45. package/dist/query/types.d.ts +1 -0
  46. package/dist/query/types.d.ts.map +1 -1
  47. package/dist/query/types.js.map +1 -1
  48. package/dist/records/contract-builder.d.ts +22 -6
  49. package/dist/records/contract-builder.d.ts.map +1 -1
  50. package/dist/records/contract-builder.js.map +1 -1
  51. package/dist/schemas/automations.d.ts +6 -2
  52. package/dist/schemas/automations.d.ts.map +1 -1
  53. package/dist/schemas/automations.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +4 -3
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/connectors.js +4 -3
  57. package/dist/schemas/connectors.js.map +1 -1
  58. package/dist/schemas/library/media.js +1 -1
  59. package/dist/schemas/library/media.js.map +1 -1
  60. package/dist/session/account-hint.d.ts +2 -2
  61. package/dist/session/account-hint.d.ts.map +1 -1
  62. package/dist/session/account-hint.js +3 -3
  63. package/dist/session/account-hint.js.map +1 -1
  64. package/dist/session/auth.d.ts +7 -3
  65. package/dist/session/auth.d.ts.map +1 -1
  66. package/dist/session/auth.js.map +1 -1
  67. package/dist/session/connection.d.ts +18 -0
  68. package/dist/session/connection.d.ts.map +1 -1
  69. package/dist/session/connection.js +11 -0
  70. package/dist/session/connection.js.map +1 -1
  71. package/dist/session/index.d.ts +2 -2
  72. package/dist/session/index.d.ts.map +1 -1
  73. package/dist/session/index.js +2 -2
  74. package/dist/session/index.js.map +1 -1
  75. package/dist/storage/blob-store.d.ts +3 -0
  76. package/dist/storage/blob-store.d.ts.map +1 -1
  77. package/dist/types.d.ts +11 -2
  78. package/dist/types.d.ts.map +1 -1
  79. package/dist/types.js.map +1 -1
  80. package/docs/README.md +86 -93
  81. package/docs/actions.md +213 -152
  82. package/docs/agents.md +198 -167
  83. package/docs/automations.md +296 -204
  84. package/docs/blueprints-and-guides.md +405 -311
  85. package/docs/bots.md +208 -134
  86. package/docs/building-an-app.md +86 -159
  87. package/docs/collections.md +248 -328
  88. package/docs/computed.md +112 -89
  89. package/docs/contacts.md +151 -112
  90. package/docs/contracts.md +299 -120
  91. package/docs/direct-messages.md +80 -65
  92. package/docs/inbox.md +138 -93
  93. package/docs/node.md +1081 -996
  94. package/docs/permissions.md +142 -0
  95. package/docs/proposing-collections.md +74 -55
  96. package/docs/query-format.md +150 -126
  97. package/docs/records-and-queries.md +205 -126
  98. package/docs/sign-in.md +487 -416
  99. package/docs/spaces.md +261 -246
  100. package/docs/standard-library.md +487 -526
  101. package/docs/storage.md +325 -348
  102. package/docs/usernames.md +164 -97
  103. package/docs/warrants.md +100 -67
  104. package/package.json +1 -6
  105. package/dist/elements/auth-styles.d.ts +0 -18
  106. package/dist/elements/auth-styles.d.ts.map +0 -1
  107. package/dist/elements/auth-styles.js +0 -206
  108. package/dist/elements/auth-styles.js.map +0 -1
  109. package/dist/elements/dom.d.ts +0 -29
  110. package/dist/elements/dom.d.ts.map +0 -1
  111. package/dist/elements/dom.js +0 -91
  112. package/dist/elements/dom.js.map +0 -1
  113. package/dist/elements/index.d.ts +0 -13
  114. package/dist/elements/index.d.ts.map +0 -1
  115. package/dist/elements/index.js +0 -11
  116. package/dist/elements/index.js.map +0 -1
  117. package/dist/elements/minca-auth.d.ts +0 -55
  118. package/dist/elements/minca-auth.d.ts.map +0 -1
  119. package/dist/elements/minca-auth.js +0 -768
  120. package/dist/elements/minca-auth.js.map +0 -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,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
- - 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
- ```
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
- ```tsx
69
- import { createMincaAuth } from '@minca/core/session';
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
- const auth = createMincaAuth({ appName: 'Todo', network: { relays: ['wss://relay.minca.social'] } });
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
- function App() {
75
- const { state } = useMinca();
76
- if (state?.stage !== 'ready') return <MincaAuth />;
77
- return <Todos />;
78
- }
55
+ ## The account home
79
56
 
80
- createRoot(root).render(
81
- <MincaProvider auth={auth}>
82
- <App />
83
- </MincaProvider>,
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
- ## A node by hand
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
- For scripts, tests and servers:
71
+ ## A collection
90
72
 
91
- ```typescript
92
- import {
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
- const manager = createIdentityManager();
101
- const me = await manager.fromRecoveryCode(code);
76
+ ```ts
77
+ import * as z from 'zod';
78
+ import { collection } from '@minca/core';
102
79
 
103
- const node = await createNode({
104
- signer: createLocalRootSigner(me, manager.getProvider()),
105
- stores: indexedDBStores('my-app'),
106
- network: { relays: ['wss://relay.minca.social'] },
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
- Leave out `network` to stay offline. Call `node.close()` when done.
111
-
112
- ## Spaces
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
- 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
91
+ ```ts
92
+ await node.collections.define(space.id, todos);
121
93
  ```
122
94
 
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` |
95
+ We'll look at schemas, rules and the shared standard collections in
96
+ [Collections](collections.md).
157
97
 
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
- }
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
- **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.
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
- **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.
108
+ ## Showing records
176
109
 
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:
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 { inviteLink, useInviteLink, useMyName, useNode } from '@minca/react';
115
+ import { useQuery, useSpaces } from '@minca/react';
184
116
 
185
- const link = inviteLink(await node.spaces.invite(space.id, { short: true })); // https://app.example/#invite=…
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 Invited({ onJoin }: { onJoin: (invite: string) => Promise<unknown> }) {
188
- const { invite, preview, dismiss } = useInviteLink();
189
- const me = useMyName();
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
- <button
193
- onClick={() =>
194
- void me
195
- .save()
196
- .then(() => onJoin(invite))
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
- `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
136
+ That's a whole app. Share the space with a friend, and you both see the same
137
+ list.
210
138
 
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
- ```
139
+ ## Next steps
220
140
 
221
- At most 64 KB each. Someone who isn't connected misses it.
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.