@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
package/docs/README.md CHANGED
@@ -1,114 +1,107 @@
1
- # Building on Minca
1
+ # Understanding Minca
2
2
 
3
- Short guides for building an app with `@minca/core`. They ship in the
4
- package, so they always match the version installed: an agent working in an
5
- app's repository finds them at `node_modules/@minca/core/docs/`.
3
+ Minca apps keep their data in spaces that people own, not on a server you
4
+ run. This page explains the few ideas everything else builds on. Read it
5
+ first, then [build a small app](building-an-app.md).
6
6
 
7
- The repository's README (https://github.com/leifriksheim/minca) gives the
8
- whole picture, and where each thing is described. The protocol
9
- itself (what goes over the wire, what is signed, what every peer checks) is
10
- specified in `spec/` in the repository: https://github.com/leifriksheim/minca/tree/main/spec
7
+ These docs ship inside `@minca/core`, so they always match the version you
8
+ have installed. An agent working in your app's repository finds them at
9
+ `node_modules/@minca/core/docs/`.
11
10
 
12
11
  ## The model in ten lines
13
12
 
14
- - An **account** is a seed the person keeps. Apps never need it.
15
- - A **node** (`createNode`) is the whole stack in one object: it signs, stores,
16
- encrypts, checks and syncs. Everything below goes through it.
17
- - A **space** is a shared place: its members, their roles, and its data.
18
- Its first record is its constitution: its founders, if any, and the roles
19
- it starts with. Private spaces are encrypted end to end.
20
- - A **collection** is a named kind of record in a space, like `app.todo.item`.
21
- Its definition (a JSON Schema, links, rules) is stored in the space itself.
22
- - A **record** is a signed JSON body with a key that stays the same across
23
- edits. Every edit is a new version.
24
- - **Grants** say who may do what: each role holds commands like
25
- `/record/write`, narrowed by a policy, and accounts get them by being
26
- assigned a role. A collection's **rules** say what its records must keep
27
- to. Every device checks every record that arrives against both, so there
28
- is no server to write. **Contracts** say what a record must be, citing
29
- other records as evidence; every reader counts only records that pass
30
- them (spec 09).
31
- - **Computed fields** are values a collection's definition works out from
32
- what links to a record, like a todo done once two people react ๐Ÿ‘. Each
33
- device works them out from what it holds: a view, where a contract is a
34
- verdict.
35
- - **Queries** are plain JSON: Mongo-style filters, sorting, paging, and
36
- `include` to follow links. Name the collection by its definition and
37
- `where` and `sort` are typed: a misspelled field is a compile error.
13
+ - An **account** is a person. Its keys stay with them, and your app never sees them.
14
+ - A **space** is a shared place: who is in it, what each of them may do, and
15
+ the data. Private spaces are encrypted end to end.
16
+ - A **collection** is a kind of record in a space, like `app.todo.item`.
17
+ - A **record** is a signed piece of JSON. Editing it makes a new version.
18
+ - A **role** says what its members may write. Every device checks every
19
+ record it receives, so there is no server to trust.
20
+ - A **node** (`createNode`) does all of this for you: it signs, stores, checks and syncs.
21
+
22
+ That's the whole model. A few more ideas build on it, and each has its own
23
+ page when you need it:
24
+
25
+ - **Rules** and **contracts** say what a collection's records must keep to,
26
+ like whose turn it is. See [Collections](collections.md) and
27
+ [Contracts](contracts.md).
28
+ - **Computed fields** are values worked out from what links to a record,
29
+ like "done once two people react ๐Ÿ‘". See [Computed fields](computed.md).
30
+ - **Queries** are plain JSON, and typed when you pass a collection. See
31
+ [Records and queries](records-and-queries.md).
38
32
 
39
33
  ## Guides
40
34
 
41
- | Guide | Read it to |
42
- | ---------------------------------------------------- | ------------------------------------------------------------------- |
43
- | [building-an-app.md](building-an-app.md) | Get a node: sign-in, the account home, React |
44
- | [collections.md](collections.md) | Say what your data is and who may do what with it |
45
- | [records-and-queries.md](records-and-queries.md) | Write, edit, delete, query and watch records |
46
- | [proposing-collections.md](proposing-collections.md) | Grow a space's collections, and say how to use them, with no deploy |
47
- | [agents.md](agents.md) | Let an agent read and write as the person, from a terminal or MCP |
35
+ | Guide | Read it to |
36
+ | ---------------------------------------------------- | -------------------------------------------- |
37
+ | [building-an-app.md](building-an-app.md) | Build a small to-do app |
38
+ | [collections.md](collections.md) | Say what your data is, and who may change it |
39
+ | [records-and-queries.md](records-and-queries.md) | Write, edit, delete, query and watch records |
40
+ | [proposing-collections.md](proposing-collections.md) | Add collections to a space with no deploy |
41
+ | [agents.md](agents.md) | Let an agent read and write as the person |
48
42
 
49
43
  ## Reference
50
44
 
51
- What the library does, in full. None of it is protocol: no peer checks it,
52
- and another implementation may do it differently and still sync with this
53
- one. Some of it is a convention apps share, like `std.*` bodies and direct
54
- messages: an app that does it differently still syncs, but can't read what
55
- the others wrote.
56
-
57
- | Page | Covers |
58
- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
59
- | [node.md](node.md) | `createNode`: configuration, root signers and session notes, stores, holding spaces, following the account, events, the network, the app-side client, carriers and hosting, doors, React |
60
- | [sign-in.md](sign-in.md) | `createMincaAuth`: places, account stores, ways in, passkeys, staying signed in, pods, pairing, the account home's side |
61
- | [actions.md](actions.md) | The node's actions, and the CLI, MCP and WebMCP tools made of them |
62
- | [query-format.md](query-format.md) | The JSON query format: filters, operators, sort and cursor, include |
63
- | [standard-library.md](standard-library.md) | Every `std.*` collection, and the conventions they follow |
64
- | [direct-messages.md](direct-messages.md) | `std.direct` and `node.direct`: text sealed for some members of a space |
65
- | [blueprints-and-guides.md](blueprints-and-guides.md) | `std.blueprint` and `std.guide`: proposing collections, the review, updates, guides, compatibility |
66
- | [computed.md](computed.md) | `computed`: values every app derives the same way from what links to a record, like done once two people react ๐Ÿ‘ |
67
- | [contracts.md](contracts.md) | `contract` (`check` and `line`): how the library runs contracts (spec 09), counts only versions that pass, and refuses its own failing ones |
68
- | [automations.md](automations.md) | `std.automation`: when a query finds records, or at set times, do something: in an app, an agent or a bot; and the account's own, which notify it |
69
- | [bots.md](bots.md) | Who may configure a bot, its instructions, connecting one to a service a host offers, writing a connector, and GitHub |
70
- | [calls](../../calls/README.md) | Voice and video calls in a space: the `call.*` messages, ringing, joining, leaving |
71
- | [contacts.md](contacts.md) | `std.contact`: the list, asking in a shared space, `node.contacts` |
72
- | [inbox.md](inbox.md) | The inbox kept as a record, and how a knock becomes a contact: `std.inbox`, `std.knock` |
73
- | [usernames.md](usernames.md) | `leif@minca.social`: looking a username up, claiming one, and the name service minca.social runs |
74
- | [spaces.md](spaces.md) | Constitution templates, invite defaults, key upkeep, profiles, the space manager |
75
- | [warrants.md](warrants.md) | `std.warrant`: proof that an account broke the protocol's rules, written by members and checked by every node before it shows a flag |
76
- | [storage.md](storage.md) | Pacing sync, the store in memory, storage adapters, IndexedDB, data folders, blob stores and mirrors |
45
+ What the library does, in full. None of it is protocol, so another
46
+ implementation may do it differently and still sync. Some of it, like the
47
+ `std.*` collections, is a convention apps share: an app that ignores it still
48
+ syncs, but can't read what the others wrote.
49
+
50
+ | Page | Covers |
51
+ | ---------------------------------------------------- | ------------------------------------------------------------------------ |
52
+ | [node.md](node.md) | `createNode`: configuration, stores, events, the network, hosting, React |
53
+ | [sign-in.md](sign-in.md) | `createMincaAuth`: accounts, passkeys, staying signed in, pairing |
54
+ | [actions.md](actions.md) | The node's actions, and the CLI, MCP and WebMCP tools made from them |
55
+ | [query-format.md](query-format.md) | The JSON query format: filters, sort, paging, `include` |
56
+ | [standard-library.md](standard-library.md) | Every `std.*` collection |
57
+ | [direct-messages.md](direct-messages.md) | `std.direct`: text sealed for some members of a space |
58
+ | [blueprints-and-guides.md](blueprints-and-guides.md) | `std.blueprint` and `std.guide`: proposing, reviewing, updating |
59
+ | [computed.md](computed.md) | Values every app works out the same way from what links to a record |
60
+ | [contracts.md](contracts.md) | What a record must be to count, checked by every reader |
61
+ | [automations.md](automations.md) | `std.automation`: do something when records change, or at set times |
62
+ | [bots.md](bots.md) | Bots: who configures them, their instructions, connectors, GitHub |
63
+ | [calls](../../calls/README.md) | Voice and video calls in a space |
64
+ | [contacts.md](contacts.md) | `std.contact` and `node.contacts` |
65
+ | [inbox.md](inbox.md) | The inbox, and how a knock becomes a contact |
66
+ | [usernames.md](usernames.md) | `leif@minca.social`: looking up and claiming usernames |
67
+ | [spaces.md](spaces.md) | Making spaces, invites, profiles, the space manager |
68
+ | [permissions.md](permissions.md) | Roles, grants, presets, and who sits at the top |
69
+ | [warrants.md](warrants.md) | `std.warrant`: proof that an account broke the protocol's rules |
70
+ | [storage.md](storage.md) | Sync pacing, storage adapters, IndexedDB, data folders, blob stores |
71
+
72
+ The protocol itself, what goes over the wire and what every peer checks, is
73
+ in the [spec](https://github.com/leifriksheim/minca/tree/main/spec).
77
74
 
78
75
  ## Rules of thumb
79
76
 
80
- - Import only from the package's entry points: `@minca/core`, and
81
- `/react`, `/session`, `/schemas`, `/elements` for those parts.
82
- - Name your collections reverse-DNS style, `app.<yours>.<thing>`. `sys.*` is
83
- the protocol's own, and `std.*` is the shared library in `/schemas`.
84
- - Check the standard library (`@minca/core/schemas`) before defining a
85
- reaction, comment, tag, message, task or poll of your own. Using the same
86
- one is how two apps see each other's data.
87
- - Never keep state outside records if other people should see it. Records are
88
- what syncs.
77
+ - Import only from the package's entry points: `@minca/core` and its
78
+ `/session`, `/schemas`, `/elements`, `/storage` and `/inbox`, and
79
+ `@minca/react` for React.
80
+ - Name your collections `app.<yours>.<thing>`. `sys.*` belongs to the
81
+ protocol and `std.*` to the standard library.
82
+ - Before you define a reaction, comment, tag, message, task or poll, look in
83
+ the standard library (`@minca/core/schemas`). Using the same one is how two
84
+ apps see each other's data.
85
+ - Keep anything other people should see in records. Records are what syncs.
89
86
  - A refused write throws with the reason in plain words. Show it, or check
90
87
  first with `node.records.can` and hide the button.
91
88
 
92
89
  ## Planned in the library
93
90
 
94
- What the protocol still has planned is in [the spec](https://github.com/leifriksheim/minca/blob/main/spec/README.md),
95
- under **Planned** in each part. Library work that isn't protocol:
96
-
97
- - **Typed queries, further.** Typed `where` inside an `include`, a
98
- misspelled collection name as a compile error, types generated from a
99
- space's stored definitions, and a dev-time warning when declared schemas
100
- differ from the space's catalogue.
101
- - **Computed fields, further.** On `records.get` and `records.list`, not
102
- only queries; and a `linked()` that follows a record's own links out.
103
- - **Typed handles.** `collection()` already emits the schema, the rules and
104
- the types from one builder; what's left is a handle bound to a space,
105
- `node.use(space, Poll)`.
106
- - **Definitions that update themselves.** `useSchemas` and `applyBlueprint` applying
107
- harmless changes, with `differences()` in `packages/core/src/schemas/blueprints.ts`
108
- replaced by the planned `compare` ([02](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md),
109
- compatible definitions).
110
- - **Asking for what a version cites.** A version pending on a cited version
111
- from a collection this node doesn't hold, asking for it
91
+ The protocol's own plans are in [the spec](https://github.com/leifriksheim/minca/blob/main/spec/README.md).
92
+ In the library:
93
+
94
+ - **More typed queries.** Typed `where` inside an `include`, a misspelled
95
+ collection name as a compile error, types generated from a space's stored
96
+ definitions, and a warning in development when your schemas differ from
97
+ the space's.
98
+ - **More computed fields.** On `records.get` and `records.list`, and a
99
+ `linked()` that follows a record's own links.
100
+ - **Typed handles.** A collection bound to a space: `node.use(space, Poll)`.
101
+ - **Definitions that update themselves.** `useSchemas` and `applyBlueprint`
102
+ applying harmless changes on their own.
103
+ - **Asking for what a version cites**, when it comes from a collection this
104
+ node doesn't hold
112
105
  ([spec 09 ยง9](../../../spec/09-contracts.md#9-planned-asking-for-what-a-version-cites),
113
106
  [#138](https://github.com/leifriksheim/minca/issues/138)).
114
- - **Web components** for the standard schemas.
107
+ - **Web components** for the standard collections.