@calimero-network/mero-react 10.2.1 → 11.0.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 CHANGED
@@ -1,8 +1,18 @@
1
1
  # @calimero-network/mero-react
2
2
 
3
- React bindings for [@calimero-network/mero-js](../mero-js) — the Calimero Network SDK.
3
+ React bindings for **Calimero 1.0**, on the mero-js 28 client (`CalimeroClient`).
4
4
 
5
- No external UI framework. No styled-components. No axios. A provider, 44 hooks, storage helpers, and optional headless utility components (ConnectButton, LoginModal).
5
+ A 1.0 node runs in an attested TDX cluster. The client verifies the node's attestation, seals every request to the node's attested key, and signs people in with **passkeys**. mero-react puts one client in context and builds the hooks on top of it:
6
+
7
+ - passkey sign-in and sign-up;
8
+ - sessions that refresh by themselves;
9
+ - calls, views and live events on an app instance;
10
+ - organizations, teams and invites;
11
+ - the node's consent page for approvals;
12
+ - blobs and presence;
13
+ - typed errors your UI can switch on.
14
+
15
+ > **Upgrading from 10.x?** 11.0 is a rewrite for core 1.0, which removed `/admin-api`, `/jsonrpc`, `/ws`, `/sse`, mero-auth and `/auth/token`. Read [Migrating from 10.x](#migrating-from-10x) below.
6
16
 
7
17
  ## Installation
8
18
 
@@ -10,352 +20,249 @@ No external UI framework. No styled-components. No axios. A provider, 44 hooks,
10
20
  pnpm add @calimero-network/mero-react
11
21
  ```
12
22
 
13
- Peer dependencies: `react` ^18 || ^19, `react-dom` ^18 || ^19. `mero-js` is a bundled dependency — no separate install needed.
23
+ `@calimero-network/mero-js` (^28.0) comes with it, and every mero-js export is re-exported, so apps need only this import. React 18 or 19 is a peer dependency.
14
24
 
15
25
  ## Quick start
16
26
 
17
27
  ```tsx
18
- import { MeroProvider, useMero, useExecute, useSubscription, AppMode } from '@calimero-network/mero-react';
28
+ import {
29
+ MeroProvider,
30
+ ConnectButton,
31
+ useMero,
32
+ useView,
33
+ useExecute,
34
+ useSubscription,
35
+ } from '@calimero-network/mero-react';
19
36
 
20
- function App() {
37
+ export function Root() {
21
38
  return (
22
- <MeroProvider mode={AppMode.SingleContext} packageName="com.calimero.my-app">
23
- <MyApp />
39
+ // A frontend the node serves at {label}.{apps-domain}:
40
+ <MeroProvider servedByNode minReleaseVersion="2.3.109" appId={APP_ID}>
41
+ <App />
24
42
  </MeroProvider>
25
43
  );
26
44
  }
27
45
 
28
- function MyApp() {
29
- const { isAuthenticated, connectToNode, logout, contextId, contextIdentity } = useMero();
30
-
31
- if (!isAuthenticated) {
32
- return <button onClick={() => connectToNode('http://localhost:4001')}>Connect</button>;
33
- }
34
-
35
- return <Dashboard />;
36
- }
37
-
38
- function Dashboard() {
39
- const { contextId, contextIdentity } = useMero();
40
- const { execute, loading } = useExecute(contextId, contextIdentity);
41
- const [items, setItems] = useState([]);
42
-
43
- // Real-time updates via SSE
44
- useSubscription(
45
- contextId ? [contextId] : [],
46
- () => fetchItems(),
47
- );
48
-
49
- const fetchItems = async () => {
50
- const data = await execute('list');
51
- if (data) setItems(data);
52
- };
53
-
54
- const addItem = async (title: string) => {
55
- await execute('add', { title });
56
- await fetchItems();
57
- };
46
+ function App() {
47
+ const { isAuthenticated } = useMero();
48
+ const items = useView<string[]>('list_items');
49
+ const { execute, failure } = useExecute();
50
+ useSubscription(undefined, (event) => {
51
+ if (event.kind === 'ItemAdded') void items.refetch();
52
+ });
58
53
 
54
+ if (!isAuthenticated) return <ConnectButton appName="Notes" />;
59
55
  return (
60
- <div>
61
- {loading && <p>Loading...</p>}
62
- {items.map(item => <div key={item.id}>{item.title}</div>)}
63
- <button onClick={() => addItem('New item')}>Add</button>
64
- </div>
56
+ <>
57
+ <ul>{items.data?.map((item) => <li key={item}>{item}</li>)}</ul>
58
+ <button onClick={() => execute('add_item', { text: 'hello' })}>Add</button>
59
+ {failure && <p role="alert">{failure.message}</p>}
60
+ </>
65
61
  );
66
62
  }
67
63
  ```
68
64
 
69
- ## API reference
65
+ A frontend hosted elsewhere reaches a Calimero Cloud cluster by name, failing over between its nodes:
70
66
 
71
- ### `<MeroProvider>`
67
+ ```tsx
68
+ <MeroProvider cluster="eu-shared-1" minReleaseVersion="2.3.109" appId={APP_ID}>
69
+ ```
72
70
 
73
- Wraps your app with a MeroJs instance, auth state, and SSE connectivity.
71
+ For local development against `merod local` (three `--dev` nodes with mock attestation on 127.0.0.1:2501-2503):
74
72
 
75
73
  ```tsx
76
74
  <MeroProvider
77
- mode={AppMode.SingleContext} // required
78
- packageName="com.calimero.my-app" // for package-based apps
79
- timeoutMs={30000} // optional, default 30s
75
+ nodeUrl="http://127.0.0.1:2501"
76
+ nodes={['http://127.0.0.1:2502', 'http://127.0.0.1:2503']}
77
+ allowMock
80
78
  >
81
- {children}
82
- </MeroProvider>
83
79
  ```
84
80
 
85
- Props (`MeroProviderConfig & { children }`):
86
-
87
- | Prop | Type | Required | Description |
88
- |------|------|----------|-------------|
89
- | `mode` | `AppMode` | Yes | `SingleContext`, `MultiContext`, or `Admin` |
90
- | `packageName` | `string` | No | Package name for registry/node lookup |
91
- | `packageVersion` | `string` | No | Specific version (defaults to latest) |
92
- | `registryUrl` | `string` | No | Registry URL override |
93
- | `timeoutMs` | `number` | No | HTTP request timeout (default 30000) |
94
- | `allowedNodeUrls` | `string[]` | No | Origins the OAuth callback may authenticate against. The initiated node is always trusted; this allowlist additionally permits direct-callback entry. A callback `node_url` matching neither is rejected. |
95
- | `tokenStore` | `TokenStore` | No | Pluggable access/refresh token store. Defaults to localStorage. Pass a `MemoryTokenStore` or cookie-backed store for sensitive deployments (localStorage tokens are XSS-readable). |
96
-
97
- Modes and their permissions:
98
-
99
- | Mode | Permissions | Use case |
100
- |------|-------------|----------|
101
- | `SingleContext` | `context:execute` | Apps that work with one context |
102
- | `MultiContext` | `context:create`, `context:list`, `context:execute` | Apps managing multiple contexts |
103
- | `Admin` | `admin` | Admin dashboards, dev tools |
104
-
105
- Auth flow: when `connectToNode(url)` is called, the provider redirects to the node's auth page. After login, the node redirects back with tokens in the URL hash. The provider processes these once (StrictMode-safe via ref) and sets `isAuthenticated = true`. The callback's `node_url` is validated against the node login was initiated with (or `allowedNodeUrls`); a `node_url` matching neither is rejected.
106
-
107
- Online detection: the provider opens an SSE connection to the node after auth. `isOnline` reflects the SSE connection state — no polling.
81
+ `allowMock` accepts mock attestation quotes. Never set it from anything a visitor controls, such as a URL parameter or the environment of a deployed build.
82
+
83
+ ## `<MeroProvider>`
84
+
85
+ | Prop | Type | What it does |
86
+ | --- | --- | --- |
87
+ | `minReleaseVersion` | `string` | The oldest mero-tee release to trust, for example `2.3.109`. This is shorthand for `policy: { release: { minReleaseVersion } }`. |
88
+ | `policy` | `CloudPolicy` | The full attestation policy (profile, release source, `verifyQuote`, `appHash`). Takes precedence over `minReleaseVersion`. |
89
+ | `allowMock` | `boolean` | Accept mock quotes (`merod local`, `--dev` clusters). The provider throws if `minReleaseVersion`, `policy` and `allowMock` are all missing. |
90
+ | `servedByNode` | `boolean` | The node serves this page. The node is then `window.location.origin`, and a passkey ceremony here opens a session bound to this app's package. `ConnectButton` skips the node field. |
91
+ | `nodeUrl` | `string` | The node to use when the page is not node-served. Without it (and without `cluster`), the provider uses the node or cluster kept from the last visit, or waits for `connectToNode` / `connectToCluster`. |
92
+ | `nodes` | `string[]` | Other nodes of the cluster, with `nodeUrl`. On `421 WRONG_NODE`, or when a node stays unavailable, the client moves to the next one. |
93
+ | `cluster` | `string` | A Calimero Cloud cluster by name (`eu-shared-1`), in place of `nodeUrl`. The client reads the cluster's nodes from the public node directory (mero-js `CalimeroClient.connect`) and fails over between them. The directory only picks which nodes to try: each is attested under your policy first. `nodeUrl` wins when both are given. |
94
+ | `zone`, `directory` | `string` | With `cluster`: the zone whose nodes are tried first, and another node directory than mero-js `DEFAULT_DIRECTORY`. |
95
+ | `appId` | `string` | The app instance that hooks default to. |
96
+ | `sessionStore` | `SessionStore` | Where the session is kept. The default is `localStorageSessionStore`; `memorySessionStore()` keeps it for the tab's lifetime only. |
97
+ | `passkey` | `PasskeyProvider` | The WebAuthn prompt. The default is mero-js `browserPasskey()`. |
98
+ | `fetch`, `retry` | | Passed through to `CalimeroClient`. |
99
+ | `client` | `CalimeroClient` | Use this client instead of building one, for tests or custom setups. |
100
+ | `onError` | `(failure) => void` | Called with every failure that a hook or a sign-in reports. |
108
101
 
109
102
  ### `useMero()`
110
103
 
111
- Access the MeroJs instance, auth state, and actions.
112
-
113
- ```tsx
104
+ ```ts
114
105
  const {
115
- mero, // MeroJs | null — the SDK instance
116
- isAuthenticated, // boolean
117
- isOnline, // boolean — SSE connection state
118
- isLoading, // boolean — initial session restore
119
- nodeUrl, // string | null
120
- applicationId, // string | null — node: from the auth callback; account: see below
121
- contextId, // string | null — from auth callback
122
- contextIdentity, // string | null — executor public key from auth callback
123
- connectToNode, // (url: string) => void — starts auth redirect
124
- admin, // AdminApiClient | null — the session's admin: node admin on a node, account admin on an account
125
- logout, // () => void — clears tokens and state
106
+ client, // CalimeroClient | null (null until a node is known, or a cluster's nodes are)
107
+ nodeUrl, // the node in use
108
+ cluster, // the cluster connected to by name, or null
109
+ isConnecting, // the node directory is being read
110
+ connectToNode, // (url) => void
111
+ connectToCluster, // (name) => void
112
+ disconnect,
113
+ session, accountId, isAuthenticated, isLoading,
114
+ signIn, // () => Promise<CalimeroSession | null>: an existing passkey
115
+ signUp, // (name) => Promise<CalimeroSession | null>: a new account and passkey
116
+ signOut, signOutEverywhere,
117
+ appId, setAppId,
118
+ passkey, servedByNode, allowMock,
119
+ failure, // the last sign-in, connection or session failure, described
120
+ reportError,
126
121
  } = useMero();
127
122
  ```
128
123
 
129
- Every hook in this package goes through that `admin`, never the raw `mero.admin`: on a node it is the node's own admin API; on an account (delegated session) it is the account admin, whose reads go to the relay and whose writes are the account's own form of the call (invitations signed with the device key, joins through the admit route, group changes as governance ops under warrants). An app gets the same result from `useCreateNamespaceInvitation`, `useJoinNamespace`, `useAddGroupMembers` and the rest on a node and on an account; a call an account has no form of (`useUpgradeGroup`, `useDeleteNamespace`, `useJoinGroup`, ...) surfaces `NotForAccountError` through `error`.
130
-
131
- How an account (delegated session) learns its `applicationId`: `packageName` decides. When the app passes one, the id is derived from the registry: `sha256(borsh((package, signerId)))` of the newest non-yanked bundle, exactly as merod computes it at install, so a brand-new account can found its first namespace (`admin.createNamespace({ applicationId })`) and an account already used in other apps is never handed one of THEIR ids. The account's own contexts on the relay are consulted only when the app passes no `packageName` (or the registry did not answer, after one `console.warn`): one distinct application across them is the answer; several leaves it `null` on purpose (nothing says which the tab is for). When the registry lists the package under more than one publisher, it stays `null`. `applicationIdForBundle` and `resolveApplicationIdFromRegistry` are exported for apps that need the same derivation.
132
-
133
- On an account, `admin.createContext(request)` (and `useCreateContext`) signs a creation warrant the relay acts on: `applicationId`, `groupId`, `serviceName` (which service of a multi-service bundle, e.g. mero-docs' `registry`), `name`, `contextSeed` and `initializationParams` are all carried into it; `identitySecret` is not, since the account itself is the new context's member identity.
124
+ **Sessions.** A 1.0 session is a session token (`v2.…`) that lasts 15 minutes, plus a refresh token (`rt_…`) that lasts 30 days and can be used once.
134
125
 
135
- Through `mero` you access the full MeroJs API:
126
+ - The client refreshes by itself on a `401`. One refresh is shared by every request waiting on it, because reusing a refresh token revokes the session. When the node that issued the session is gone, the refresh goes to another node of the cluster (mero-js#318).
127
+ - The provider saves every new session to `sessionStore`, so a reload resumes the session.
128
+ - When a refresh is refused, hooks get `LoginRequired`, and the provider ends the session and sets `failure.kind = 'login'`.
129
+ - `mero` is still on the value as a deprecated alias of `client`.
136
130
 
137
- ```tsx
138
- // Admin API (flat methods, NOT nested)
139
- await mero.admin.healthCheck();
140
- await mero.admin.getContexts();
141
- await mero.admin.getContext(contextId);
142
- await mero.admin.getContextIdentitiesOwned(contextId);
143
- await mero.admin.listApplications();
144
- await mero.admin.getApplication(appId);
145
- await mero.admin.installApplication(request);
146
- await mero.admin.createContext(request);
147
- await mero.admin.uploadBlob(request);
148
- await mero.admin.getPeersCount();
149
-
150
- // Auth API
151
- await mero.auth.getProviders();
152
- await mero.auth.generateTokens(request);
153
- await mero.auth.refreshToken(request);
154
-
155
- // RPC
156
- await mero.rpc.execute({ contextId, method, argsJson, executorPublicKey });
157
-
158
- // SSE events
159
- mero.events.connect();
160
- mero.events.subscribe(contextIds);
161
- mero.events.on('event', handler);
162
-
163
- // Tokens
164
- mero.getTokenData(); // { access_token, refresh_token, expires_at } | null
165
- mero.isAuthenticated(); // boolean
166
- ```
131
+ ## Hooks
167
132
 
168
- ### `useExecute(contextId, executorId)`
133
+ Every read hook returns `{ data, loading, error, failure, refetch }`. Every action hook returns its action plus `{ loading, error, failure }`.
169
134
 
170
- Wraps `mero.rpc.execute()` with loading/error state. Unmount-safe.
135
+ - `error` is the error exactly as the client threw it, so `instanceof AppError` still works.
136
+ - `failure` is `describeError(error)`; see [Errors](#errors).
137
+ - An action resolves `null` when it fails. Pass `{ throwOnError: true }` to make it throw instead.
171
138
 
172
- ```tsx
173
- const { execute, loading, error } = useExecute(contextId, contextIdentity);
139
+ ### App: calls, views, events
174
140
 
175
- // Generic typed
176
- const todos = await execute<Todo[]>('list');
177
- await execute('add', { title: 'Buy milk' });
178
- await execute('toggle', { id: '1' });
179
- ```
180
-
181
- | Return | Type | Description |
182
- |--------|------|-------------|
183
- | `execute` | `<T>(method, params?) => Promise<T \| null>` | Call a contract method |
184
- | `loading` | `boolean` | Request in flight |
185
- | `error` | `Error \| null` | Last error |
186
-
187
- ### `useSubscription(contextIds, callback)`
188
-
189
- Manages SSE event subscription lifecycle. StrictMode-safe — connects once per MeroJs instance, cleans up on unmount.
190
-
191
- ```tsx
192
- useSubscription(
193
- contextId ? [contextId] : [],
194
- (event) => {
195
- console.log('Context event:', event.contextId, event.data);
196
- refreshData();
197
- },
198
- );
199
- ```
200
-
201
- | Param | Type | Description |
202
- |-------|------|-------------|
203
- | `contextIds` | `string[]` | Context IDs to subscribe to (empty array = no subscription) |
204
- | `callback` | `(event: SseEventData) => void` | Called on each context event |
205
-
206
- The SSE connection is shared — multiple `useSubscription` hooks reuse the same connection. The first one to mount calls `connect()`, subsequent ones just add handlers.
207
-
208
- ### `useContexts(applicationId?)`
209
-
210
- Fetches contexts from the node, optionally filtered by application ID.
211
-
212
- ```tsx
213
- const { contexts, loading, error, refetch } = useContexts(applicationId);
214
-
215
- // contexts: Array<{ contextId: string; applicationId: string }>
216
- ```
217
-
218
- ### Blob hooks
219
-
220
- `useBlobInfo` / `useBlobUrl` / `useUploadBlob` read and write the node's blob
221
- store. The reads take an optional `contextId`, and it is what picks the mode:
222
-
223
- - **without `contextId`** — local-only. The node answers from its own blob
224
- store immediately, or 404s.
225
- - **with `contextId`** — network discovery. The node probes that context's
226
- peers (availability nodes first) for a holder.
227
-
228
- Discovery is slow: core bounds the search by a **~30s deadline**, and for
229
- `useBlobUrl` the byte transfer is on top of that. `loading` is real UI state on
230
- these hooks, not decoration.
231
-
232
- ```tsx
233
- // Presence and size, no download — ask this before pulling something large.
234
- const { info, notFound, loading, error } = useBlobInfo(blobId, { contextId });
235
- // info: { blobId, size, hash?, mimeType?, source?: 'local' | 'peer' } | null
236
-
237
- // Bytes as an object URL, revoked for you on unmount and on id/context change.
238
- const { url } = useBlobUrl(blobId, { contextId, type: 'image/png' });
239
- return url ? <img src={url} /> : null;
240
-
241
- // Upload. Pass contextId to announce the blob so the context's peers can
242
- // discover it later.
243
- const { uploadBlob, loading, error } = useUploadBlob();
244
- const result = await uploadBlob({ data: bytes, contextId });
245
- ```
246
-
247
- A null/undefined `blobId` fetches nothing, like the other `string | null` read
248
- hooks. `hash` and `mimeType` are genuinely optional — a peer probe carries only
249
- presence and size, so a discovery-sourced hit has neither; read `info.source`
250
- to tell a local answer from a peer one. `notFound` marks the node's legitimate
251
- "no holder" 404 apart from a transport failure; `error` is set for both.
252
-
253
- ### Storage helpers
254
-
255
- Persist/read node URL, application ID, context ID, and context identity in localStorage.
256
-
257
- ```tsx
258
- import {
259
- getNodeUrl, setNodeUrl, clearNodeUrl,
260
- getApplicationId, setApplicationId, clearApplicationId,
261
- clearAllStorage,
262
- } from '@calimero-network/mero-react';
263
- ```
141
+ | Hook | Returns |
142
+ | --- | --- |
143
+ | `useApp(appId?)` | `{ appId, app, call, view, loading, error, failure, refetch }`. `call` and `view` are bound to the app and throw. |
144
+ | `useExecute(appId?, opts?)` | `{ execute, call, loading, error, failure }`. `execute(method, args?, { idempotencyKey?, confirm? })` resolves the method's result; `call` resolves the whole `CallResult` (`index`, `events`). `confirm: true` answers `412 CONFIRM_REQUIRED` with the passkey (`callConfirmed`). |
145
+ | `useView<T>(method, args?, { appId?, stale?, minIndex?, enabled? })` | `{ data: T, index, … }`. It reads again when the method or the arguments change. |
146
+ | `useSubscription(appIds?, callback, opts?)` | Calls `callback` with each `AppEvent` (`{ appId, id, index, seq, kind, data }`). |
147
+ | `useAppAbi(appId?)` | The app's ABI. |
264
148
 
265
- These are used internally by `MeroProvider` but exported for apps that need direct access.
149
+ `appId` defaults to the provider's `appId`.
266
150
 
267
- ### Invitations by link
151
+ How `useSubscription` behaves:
268
152
 
269
- An invitation reaches an app only by its link being opened: `https://links.calimero.network/<package>/join?invitation=…`. The links page opens the app with `?invitation=…` appended, and a desktop app that is already open receives a `deep-link` event. This module covers that path end to end:
153
+ - Each app gets one SSE stream with an `AbortController`. Unmounting, or changing the app ids, aborts it.
154
+ - A stream that ends or fails reopens with backoff from the last event it saw. Events at or before that one are skipped, so nothing is delivered twice.
155
+ - `from` defaults to `'live'`. Pass a log index to replay from it (`0` replays the whole history).
156
+ - `onOpen` is called each time a stream opens. Refetch views there to cover a gap.
270
157
 
271
- ```tsx
272
- import {
273
- primeInvitationCapture,
274
- useInviteRedemption,
275
- InvitationDialog,
276
- InvitationGate,
277
- buildInviteLink,
278
- } from '@calimero-network/mero-react';
158
+ ### Apps
279
159
 
280
- // main.tsx, before the router runs: take the link from the URL or the desktop
281
- // bridge and buffer it until something asks.
282
- primeInvitationCapture('my-app', { slug: 'com.example.my-app' });
160
+ | Hook | Was (10.x) |
161
+ | --- | --- |
162
+ | `useApps({ package?, bundle? })` | `useContexts` |
163
+ | `useCreateApp().create({ name, bundle, org?, access?, confirmMethods?, initArgs? })` | `useCreateContext` |
164
+ | `useDeleteApp().deleteApp(appId)` | `useDeleteContext` |
165
+ | `useSetAppMetadata().setMetadata(appId, metadata)` | `useSetContextMetadata` |
166
+ | `useUpgradeApp(appId?).upgrade({ version, … })` | `useUpgradeGroup`. It asks for the passkey. |
167
+ | `usePackages()` | none (new) |
283
168
 
284
- // The app root, once: ask, join, wait for the data, done.
285
- function Invitations() {
286
- const redemption = useInviteRedemption({
287
- parse: (token) => decodeMyToken(token), // { namespaceId, invitation, teamName? }
288
- redeemer: { join, isMember }, // mero-js `InviteRedeemer`
289
- onJoined: (namespaceId) => navigate(`/w/${namespaceId}`),
290
- });
291
- return (
292
- <>
293
- {/* Logged out: "You're invited", with the login. Logged in: nothing. */}
294
- <InvitationGate parse={decodeMyToken} noun="workspace" appName="My App" />
295
- <InvitationDialog redemption={redemption} noun="workspace" appName="My App" />
296
- </>
297
- );
298
- }
169
+ ### Organizations and teams
299
170
 
300
- // Sharing: one link shape for every app.
301
- const link = buildInviteLink('com.example.my-app', token);
171
+ | Hook | Was (10.x) |
172
+ | --- | --- |
173
+ | `useOrg(orgId)` | `useNamespace` |
174
+ | `useCreateOrg().create(name)` | `useCreateNamespace` |
175
+ | `useDeleteOrg().deleteOrg(orgId)` | `useDeleteNamespace`. It asks for the passkey. |
176
+ | `useSetMember().setMember(org, account, role)` | `useUpdateMemberRole`, and `useAddGroupMembers` at org level. It asks for the passkey. |
177
+ | `useRemoveMember().removeMember(org, account)` | none (new). It asks for the passkey. |
178
+ | `useSetOrgMetadata()`, `useSetMemberMetadata()` | `useSetGroupMetadata`, `useSetMemberMetadata` |
179
+ | `useSetCapabilities().setCapabilities(org, bits, { account?, team? })` | `useSetDefaultCapabilities`. It asks for the passkey. |
180
+ | `useTeam(org, team)` | `useGroupInfo` |
181
+ | `useCreateTeam().create({ orgId, name, join?, parent? })` | `useCreateGroupInNamespace` |
182
+ | `useUpdateTeam().update(org, team, { name?, join?, parent?, metadata? })` | `useSetGroupMetadata`, `useReparentGroup`, `useSetSubgroupVisibility` |
183
+ | `useDeleteTeam()`, `useSetTeamMember()`, `useRemoveTeamMember()` | `useDeleteGroup`, `useAddGroupMembers`, `useRemoveGroupMembers`. Setting and removing a team member ask for the passkey. |
184
+
185
+ **Passkey step-ups.** Since mero-js 28 the node approves membership changes, capabilities, invites, passkeys and API keys with the caller's passkey: it answers `412 CONFIRM_REQUIRED` and the client answers that with the provider's `passkey` (`browserPasskey()` by default), so the person sees a passkey prompt. A dismissed prompt fails the action with `failure.kind = 'cancelled'`.
186
+
187
+ ### Invites
188
+
189
+ | Hook | Notes |
190
+ | --- | --- |
191
+ | `useCreateInvite().create({ orgId, role?, teams?, ttlSecs?, uses?, linkBase? })` | Resolves `{ token, link }`. It asks for the passkey. The link carries the token in the fragment (`#invite=…`), so it stays out of server logs. |
192
+ | `useRedeemInvite().redeem(token)` | `POST /invites/{token}/redeem`. No passkey needed. |
193
+ | `useInviteRedemption({ autoRedeem? })` | The whole link flow. It reads the token from the address bar and removes it there, keeps it through sign-in, and redeems it once the person is signed in. `status` is `idle`, `waiting-for-sign-in`, `redeeming`, `redeemed` or `failed`. |
194
+
195
+ `inviteLink(token, base?)` and `readInviteToken(href)` are exported too.
196
+
197
+ ### Consent page
198
+
199
+ Approvals happen only on the page the node serves on its own origin, never inside an app. A session opened on an app's frontend cannot approve anything.
200
+
201
+ ```ts
202
+ const consent = useConsent();
203
+ await consent.open(upgradeConsent(appId, '1.2.0', window.location.href), {
204
+ // Show the confirmation code before leaving; the node's page shows the same one.
205
+ confirm: (started) => window.confirm(`The approval page will show the code ${started.code}. Continue?`),
206
+ }); // then navigates to the node's page
207
+ // … back on returnTo:
208
+ if (consent.returned) await consent.check(consent.returned.requestId); // confirm the hint
209
+ // or, when the page was opened in another window:
210
+ await consent.wait(started.requestId);
302
211
  ```
303
212
 
304
- An app whose join does more than join the namespace (entering a context, choosing where to land) passes `redeem: (parsed) => Promise<RedeemOutcome>` instead of `redeemer`; `parse` may return extra fields, which reach `redeem` and come back as `parsed`. The dialog takes `detail` (the app's own words under the question) and `status` (the step a slow join is on).
305
-
306
- `InvitationGate` is what a link shows someone who is not logged in. Without it they land on the app's ordinary logged-out page (usually its marketing landing), with nothing saying they were invited, while the invitation waits in storage for a login they have to think of themselves. The gate shows a full page instead: **You're invited to join “Design team”** (decoded by the app's own `parse`, which needs no session), in which app, with **Log in to join** (`ConnectButton` and its Node / Cloud dialog) and **Not now** (acks the invitation, so it does not come back). While the session is still restoring it shows a blank page with a spinner, so neither the landing page nor the invite screen flashes; once logged in it renders nothing and the dialog takes over. Mounted with no children it covers the page as a full-page layer; wrapped around the app (`<InvitationGate …>{app}</InvitationGate>`) it renders instead of the app. Test ids: `invite-landing` (with `data-state`: `checking`, `invited`, `invalid`), `invite-landing-login`, `invite-landing-decline`.
213
+ `useConsent()` returns `{ request, open, check, wait, cancel, started, code, result, returned, … }`. `code` is the confirmation code (`XXX-XXX`) the consent page shows for the request under way: show it next to the link or in `open`'s `confirm`, so the person can check they landed on the page their request opened. `open` throws `CONSENT_CODE_MISMATCH` when the node's code does not match the request (mero-js `confirmationCode`). Build requests with mero-js `releaseConsent`, `withdrawConsent` and `upgradeConsent`.
307
214
 
308
- `InvitationDialog` walks through every stage in one modal: **ask** (Join / Not now) → **joining** → **syncing** → **ready** (closes by itself), or **already a member**, or **failed** (the reason in plain words, with Try again when a retry can help).
215
+ ### Blobs, presence, account
309
216
 
310
- **Syncing** lasts until the joined namespace's data has arrived. Redemption marks the namespace just-joined, and the page that reads its data clears that mark:
311
-
312
- ```tsx
313
- // The page showing the namespace: `settled` once a read has come back,
314
- // including an empty one.
315
- const { isSyncing, dismiss } = useJoinSync({ namespaceId, settled: !loading });
217
+ | Hook | Notes |
218
+ | --- | --- |
219
+ | `useUploadBlob({ appId? }).upload(bytes \| Blob \| File)` | Resolves `{ blobId, id, size }`. Blobs now belong to an app instance. |
220
+ | `useBlobInfo(blobId, { appId? })`, `useBlobs(appId?)` | |
221
+ | `useBlobUrl(blobId, { appId?, mimeType? })` | `{ url }` is an object URL. The bytes come over the sealed channel, and the URL is revoked on unmount. |
222
+ | `useDeleteBlob({ appId? }).deleteBlob(blobId)` | |
223
+ | `useEphemeral<T>(appId, { codec?, initial?, throttleMs?, includeSelf? })` | Presence. Returns `{ peers: Map<account, T>, entries, setPresence, leave, error }`. It sends a heartbeat every 5 s and retracts on unmount. |
224
+ | `useAccount()` | `GET /auth/me`. Was `useNodeIdentity`. |
225
+ | `usePasskeys()` | `{ add, remove, label }` for the account's passkeys. Adding and removing are approved with a passkey the account already has; `add({ passkey?, approver? })` takes other providers for the new passkey and the approving one. |
226
+ | `useApiKeys()` | `{ keys, create, revoke, refetch, … }` for API keys (agents, servers). `create({ label?, apps?, methods?, readOnly?, allowConfirm?, ttlSecs? })` asks for the passkey, needs a passkey session, and resolves `{ keyId, key }`: the key is shown once. |
227
+
228
+ ## Errors
229
+
230
+ mero-js maps every refusal to a typed error (`errorFrom`, mero-js#312). mero-react keeps that error in `error` and adds `failure = describeError(error)`:
231
+
232
+ ```ts
233
+ type Failure = {
234
+ kind: FailureKind; // see the table
235
+ message: string; // a sentence you can show as it is
236
+ retryable: boolean;
237
+ status?: number; code?: string;
238
+ appCode?: string; fields?: Record<string, unknown>; // kind 'app'
239
+ committed?: false | 'unknown'; // kind 'unavailable'
240
+ release?: string; // kind 'release-deadline'
241
+ error: unknown;
242
+ };
316
243
  ```
317
244
 
318
- An app whose root already knows can pass `synced` to the dialog instead. A sync that never settles says so after `JOIN_SYNC_WATCHDOG_MS`, offering **Continue in background**, and lets go at `JOIN_SYNC_MAX_MS`. `JoinSyncBanner` is the matching in-page strip: a page that can be reached while its namespace is still syncing shows it rather than its empty state.
319
-
320
- Joining and syncing cannot be closed by a click on the backdrop or by Escape, and while the dialog is up the rest of the page is `inert`. After **Continue in background** the dialog keeps the flag's `JOIN_SYNC_MAX_MS` ceiling running, so a person who navigates away from the page that would clear it is not left with a namespace flagged for the rest of the session.
321
-
322
- The dialog is styled with the same `--mero-*` variables as `<ConnectButton>` and `<LoginModal>` (see [Theming](#theming)). Its test ids are `invite-prompt` (with `data-stage`), `invite-accept`, `invite-decline`, `invite-continue`, `invite-done`, `invite-retry` and `invite-error`.
323
-
324
- ### Re-exports from mero-js
325
-
326
- mero-react re-exports everything from mero-js via `export * from '@calimero-network/mero-js'`. Any new API added to mero-js is automatically available from mero-react — no manual sync needed.
327
-
328
- ```tsx
329
- // All of these work from a single import
330
- import {
331
- MeroProvider, useMero, useExecute, useSubscription, // react
332
- MeroJs, RpcClient, SseClient, WsClient, // core
333
- parseAuthCallback, buildAuthLoginUrl, // auth helpers
334
- LocalStorageTokenStore, MemoryTokenStore, // token stores
335
- } from '@calimero-network/mero-react';
336
- ```
245
+ | `kind` | From |
246
+ | --- | --- |
247
+ | `app` | `AppError` (`422 APP_ERROR`): the app's own error, with `appCode` and named `fields` |
248
+ | `trap` | `TrapError` (`422 TRAP`) |
249
+ | `login` | `LoginRequired`: the refresh was refused. The provider ends the session. |
250
+ | `confirm` / `cancelled` | `ConfirmRequired` (`412`) / `ConfirmCancelled` (the person dismissed the passkey prompt) |
251
+ | `wrong-node` | `WrongNode` / `421 NOT_LEADER` after failover ran out |
252
+ | `unavailable` | `UnavailableError` (`503` or no answer after retries). Check `committed`. |
253
+ | `not-found`, `forbidden`, `too-large`, `idempotency`, `rate-limited` | `404`, `403`, `413`, `409 IDEMPOTENCY_MISMATCH`, `429` |
254
+ | `release-deadline`, `consent-stale`, `operator-signature` | `409 RELEASE_DEADLINE`, `409 CONSENT_STALE`, `428 OPERATOR_SIGNATURE_REQUIRED` |
255
+ | `attestation` | The sealed channel or the attestation check failed |
256
+ | `directory` | `DirectoryError`: the node directory does not know the cluster (`code: 'not-found'`), lists no usable node (`empty`) or could not be read |
337
257
 
338
- ## Theming
258
+ ## Components
339
259
 
340
- `ConnectButton` and `LoginModal` default to the green Calimero palette used in admin-dashboard, tauri-app, and app-registry. Pass nothing for the default — provide a partial `MeroTheme` to override any subset.
260
+ - `<ConnectButton appName? allowSignUp? initialTab? theme? logoOnly? label? />`. Signed out, it shows "Sign in" and opens `LoginModal`. Signed in, it shows the account, with a menu for Sign out and Sign out everywhere.
261
+ - `<LoginModal isOpen onClose onSignedIn? initialTab? allowSignUp? appName? theme? />`. Sign in with a passkey, or create an account, which asks for a name. Off a node-served page it asks first for the node URL or a cluster name.
341
262
 
342
- ```tsx
343
- import { ConnectButton } from '@calimero-network/mero-react';
344
-
345
- // Default green palette — no theme prop needed
346
- <ConnectButton />
347
-
348
- // Override only what you want; the rest stay default
349
- <ConnectButton
350
- theme={{
351
- primary: '#ff4081',
352
- primaryHover: '#e91e63',
353
- primaryText: '#ffffff',
354
- }}
355
- />
356
- ```
263
+ ### Theming
357
264
 
358
- The same theme is forwarded to the embedded `LoginModal` and is also exposed as CSS variables on the component root, so a global stylesheet works too:
265
+ Pass a partial `MeroTheme` (`primary`, `primaryHover`, `primaryText`, `background`, `backgroundSecondary`, `backgroundTertiary`, `border`, `text`, `textSecondary`, `error`, `overlay`, `radius`), or set the `--mero-*` CSS variables globally:
359
266
 
360
267
  ```css
361
268
  :root {
@@ -364,176 +271,78 @@ The same theme is forwarded to the embedded `LoginModal` and is also exposed as
364
271
  }
365
272
  ```
366
273
 
367
- The connect dialog also carries stable class names, for what the tokens do not cover. Its inline styles still win over a class, so a class rule can add what the dialog leaves unset (its font is inherited from the page, for one) but not replace an inline value; the dialog's shadow, the one look that is neither a token nor inherited, reads `--mero-login-shadow` and keeps its default when that is unset.
368
-
369
- | Class | Element |
274
+ The dialog's classes are `mero-dialog-overlay`, `mero-dialog-panel`, `mero-dialog-title`, `mero-dialog-body`, `mero-dialog-field`, `mero-dialog-input`, `mero-dialog-button`, `mero-dialog-primary`, `mero-dialog-secondary` and `mero-dialog-link`. The button's classes are `mero-connect-button`, `mero-dropdown` and `mero-dropdown-item`.
275
+
276
+ ## Storage
277
+
278
+ - `localStorageSessionStore` and `memorySessionStore()`: session stores.
279
+ - `getNodeUrl` / `setNodeUrl` / `clearNodeUrl`, `getCluster` / `setCluster` / `clearCluster` and `getAppId` / `setAppId` / `clearAppId`.
280
+ - `clearAllStorage()` clears all of the above.
281
+ - Keys: `mero:session`, `mero:nodeUrl`, `mero:cluster`, `mero:appId`. 10.x tokens are not read.
282
+
283
+ ## Migrating from 10.x
284
+
285
+ core 1.0 is a different node, and mero-js 28 is a different client, so 11.0 is a breaking release. Most app ports are mechanical:
286
+
287
+ 1. **Provider.**
288
+ - Drop `mode`, `packageName`, `packageVersion`, `registryUrl`, `cloudBaseUrl`, `timeoutMs`, `allowedNodeUrls` and `tokenStore`.
289
+ - Add `minReleaseVersion` (production) or `allowMock` (`merod local`).
290
+ - Keep `servedByNode`. Pass `appId` if the app works on one instance.
291
+ 2. **Client.**
292
+ - `useMero().mero` (a `MeroJs` or relay client) is now `useMero().client` (a `CalimeroClient`).
293
+ - `mero.rpc.execute({ contextId, method, argsJson, executorPublicKey })` is now `client.call(appId, method, args)`, or `client.view(…)` for reads.
294
+ 3. **Vocabulary.**
295
+ - context is now app instance (`appId`);
296
+ - namespace is now organization;
297
+ - group is now team;
298
+ - executor / node identity is now the signed-in account.
299
+ 4. **Auth.**
300
+ - There is no redirect, callback or `access_token` in the URL any more.
301
+ - `connectToNode(url)` only picks the node. Signing in is `signIn()` or `signUp(name)` (passkeys), or `<ConnectButton />`.
302
+ 5. **Errors.** Switch on `failure.kind`, or `instanceof AppError` / `ConfirmRequired` / `WrongNode`, instead of HTTP status checks.
303
+
304
+ | 10.x | 11.0 |
370
305
  | --- | --- |
371
- | `mero-login-overlay` | the full-screen backdrop, a direct child of `body` |
372
- | `mero-login-dialog` | the dialog surface |
373
- | `mero-login-close`, `mero-login-header`, `mero-login-logo`, `mero-login-title` | close button, header, emblem, "Connect to Calimero" |
374
- | `mero-login-tabs`, `mero-login-tab` (+ `mero-login-tab-active`), `mero-login-panel` | Node / Cloud tabs and their panels |
375
- | `mero-login-info`, `mero-login-error`, `mero-login-note`, `mero-login-hint` | body copy, the connection error, the Cloud tab's note and wallet hint |
376
- | `mero-login-options`, `mero-login-option` (+ `mero-login-option-active`), `mero-login-option-indicator`, `mero-login-option-dot`, `mero-login-option-meta` | discovered-node radio list |
377
- | `mero-login-input`, `mero-login-toolbar`, `mero-login-rescan` | manual URL field, rescan link |
378
- | `mero-login-actions`, `mero-login-button mero-login-primary` | Connect / Enrol buttons |
379
- | `mero-login-discovering`, `mero-login-loading`, `mero-login-spinner`, `mero-login-account` | progress states, the Cloud tab's body |
380
-
381
- ```css
382
- /* `body >` outranks mero-react's own single-class rules, injected after yours. */
383
- body > .mero-login-overlay {
384
- --mero-login-shadow: 0 30px 60px -30px rgba(20, 26, 60, 0.45);
385
- font-family: 'Figtree', sans-serif;
386
- }
387
- ```
388
-
389
- `MeroTheme` keys (all optional): `primary`, `primaryHover`, `primaryText`, `background`, `backgroundSecondary`, `backgroundTertiary`, `border`, `text`, `textSecondary`, `error`, `overlay`, `radius`. Defaults: `#a5ff11` / `#8ed40d` / `#0d1117` / `#161b22` / `#1c2128` / `#30363d` / `#e6edf3` / `#8b949e` / `#ff6b6b` / `rgba(0,0,0,0.75)` / `8px`.
390
-
391
- Helpers: `defaultMeroTheme` (the full default palette), `resolveMeroTheme(partial?)` (merges a partial with defaults), and `themeToCssVars(resolved)` (returns a `CSSProperties` map of `--mero-*` variables for applying to your own container) are exported for advanced use.
392
-
393
- **Browser support**: hover-state and modal tints use CSS [`color-mix()`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix), which requires Chrome 111+, Safari 16.2+, or Firefox 113+ (all 2023). On older browsers the bundled `styles.css` falls back to the default green `rgba()` for the button hover; the modal renders without subtle tints but is otherwise fully functional.
394
-
395
- ### `<ConnectButton>` props
396
-
397
- ```tsx
398
- // Square 40×40 icon button — logo only, no text
399
- <ConnectButton logoOnly />
400
-
401
- // Custom label (shorthand: bare string overrides the disconnected label)
402
- <ConnectButton label="Sign in with Calimero" />
403
-
404
- // Per-state label overrides
405
- <ConnectButton
406
- label={{
407
- connect: 'Sign in',
408
- connected: 'Signed in',
409
- reconnecting: 'Reconnecting…',
410
- }}
411
- />
412
- ```
413
-
414
- | Prop | Type | Default | Notes |
415
- |------|------|---------|-------|
416
- | `connectionType` | `ConnectionType \| CustomConnectionConfig` | `Remote` | `Custom` connects straight to the given URL, skipping the modal. Every other value opens the LoginModal (node discovery + manual URL entry). |
417
- | `theme` | `MeroTheme` | — | Partial token override. |
418
- | `logoOnly` | `boolean` | `false` | Render only the Calimero logo (square button). The label is still announced via `aria-label`. |
419
- | `label` | `string \| { connect?, connected?, reconnecting? }` | — | Override default labels. Bare string targets the disconnected state. |
420
- | `className` / `style` | — | — | Forwarded to the inner `<button>`. |
421
- | `cloud` | `boolean` | `true` | The modal has two tabs: **Node** (discovery + URL, default) and **Cloud** (sign in with a Calimero account by enrolling at the wallet). `false` removes the Cloud tab. A page coming back from the wallet opens the modal on Cloud automatically. |
422
- | `accountDefaults` | `{ walletUrl?: string }` | — | Local development only: enrol at a wallet other than the hosted one. |
423
-
424
- ### `<LoginModal>` and the Cloud tab
425
-
426
- An app that mounts the modal itself gets the same two tabs with nothing wired: by default `LoginModal` sources its Cloud tab from `useAccountEnrolment()` internally, so "Enrol with your account" works and a page coming back from the wallet is completed (and lands on the Cloud tab) whether or not the modal is open. It must sit inside `MeroProvider`.
427
-
428
- ```tsx
429
- // Node + Cloud tabs, account sign-in included (default)
430
- <LoginModal isOpen={open} onConnect={connectToNode} onClose={() => setOpen(false)} />
431
-
432
- // Node dialog only, no tabs — the pre-Cloud behaviour
433
- <LoginModal cloud={false} isOpen={open} onConnect={connectToNode} onClose={() => setOpen(false)} />
434
-
435
- // Your own enrolment (what ConnectButton does): the object is used verbatim
436
- <LoginModal cloud={{ onEnrol, note, walletUrl, customWallet }} initialTab="cloud" ... />
437
- ```
438
-
439
- | `cloud` | Cloud tab | Enrolment callback read by |
440
- |---------|-----------|----------------------------|
441
- | omitted | shown, sourced by the modal | the modal |
442
- | `false` | none (no tabs) | nobody here |
443
- | object | shown, the caller's values | the caller |
444
-
445
- `initialTab` defaults to `'node'`; with `cloud` omitted it defaults to `'cloud'` on the load coming back from the wallet. An explicit `initialTab` wins.
446
-
447
- The caller owns `isOpen`. To have the modal open by itself on the way back from the wallet (as `ConnectButton` does), seed its open state with `isReturningFromWallet()`, which peeks at the fragment without consuming it: `const [open, setOpen] = useState(isReturningFromWallet);`. The account flow without any of these is `useAccountEnrolment()` (returns `goToWallet`, `note`, `returning`, `walletUrl`, `customWallet`); its UI is `<AccountSignInPanel>`.
448
-
449
- ## Enums
450
-
451
- ```tsx
452
- AppMode.SingleContext // 'single-context'
453
- AppMode.MultiContext // 'multi-context'
454
- AppMode.Admin // 'admin'
455
-
456
- ConnectionType.Remote // 'remote' — opens the LoginModal (discovery + manual URL)
457
- ConnectionType.Custom // 'custom' — skip the modal, connect to a fixed URL
458
- ConnectionType.RemoteAndLocal // deprecated, same as Remote
459
- ConnectionType.Local // deprecated, same as Remote
460
- ```
461
-
462
- ## Types
463
-
464
- ```tsx
465
- import type {
466
- MeroContextValue, // useMero() return type
467
- MeroProviderConfig, // MeroProvider props (without children)
468
- MeroProviderProps, // MeroProvider props (with children)
469
- CustomConnectionConfig, // { type: ConnectionType.Custom, url: string }
470
- AppContext, // { contextId, executorId, applicationId }
471
- ExecutionResult, // { success, result?, error? }
472
- ApplicationContextRecord,// { contextId, applicationId }
473
- ContextDiscoveryOptions, // options for useContextDiscovery
474
- ContextDiscoveryState, // return type of useContextDiscovery
475
- MeroTheme, // partial theme override for ConnectButton / LoginModal
476
- ResolvedMeroTheme, // fully populated theme returned by resolveMeroTheme()
477
- } from '@calimero-network/mero-react';
478
- ```
479
-
480
- ## Full exports list
481
-
482
- ```
483
- // Provider & context (mero-react)
484
- MeroProvider, useMero, MeroContext
485
-
486
- // Components (mero-react)
487
- ConnectButton, LoginModal
488
-
489
- // Theming (mero-react)
490
- MeroTheme, ResolvedMeroTheme, defaultMeroTheme, resolveMeroTheme, themeToCssVars
491
-
492
- // Enums (mero-react)
493
- AppMode, ConnectionType
494
-
495
- // Hooks (mero-react)
496
- useExecute, useSubscription
497
- useContexts, useApplicationContexts, useContextGroup, useContextDiscovery
498
- useCreateContext, useDeleteContext, useJoinContext
499
- useGroupInfo, useGroupMembers, useGroupContexts, useGroupInvitations, useGroupCapabilities
500
- useJoinGroup, useDeleteGroup, useAddGroupMembers, useRemoveGroupMembers
501
- useSyncGroup, useReparentGroup, useSubgroups
502
- useUpgradeGroup, useGroupUpgradeStatus, useRetryGroupUpgrade
503
- useSetGroupMetadata, useSetMemberMetadata, useSetContextMetadata
504
- useGroupMetadata, useMemberMetadata, useUpdateMemberRole
505
- useSetDefaultCapabilities, useDefaultCapabilities
506
- useSetSubgroupVisibility, useSubgroupVisibility, useSetTeeAdmissionPolicy
507
- useDetachContextFromGroup
508
- useNamespaces, useNamespace, useNamespaceGroups, useNodeIdentity
509
- useNamespacesForApplication, useCreateNamespace, useDeleteNamespace
510
- useJoinNamespace, useRedeemInvitation, useCreateNamespaceInvitation, useCreateGroupInNamespace
511
- useBlobInfo, useBlobUrl, useUploadBlob
512
-
513
- // Types (mero-react)
514
- MeroContextValue, MeroProviderConfig, MeroProviderProps
515
- CustomConnectionConfig, AppContext, ExecutionResult
516
- ApplicationContextRecord, ContextDiscoveryOptions, ContextDiscoveryState
517
- BlobHookOptions, UseBlobUrlOptions, MutationOptions
518
-
519
- // Storage (mero-react)
520
- localStorageTokenStorage
521
- getNodeUrl, setNodeUrl, clearNodeUrl
522
- getApplicationId, setApplicationId, clearApplicationId
523
- getContextId, setContextId, clearContextId
524
- getContextIdentity, setContextIdentity, clearContextIdentity
525
- clearAllStorage
526
-
527
- // Everything from @calimero-network/mero-js (auto re-exported)
528
- MeroJs, createMeroJs, MeroJsConfig, TokenData
529
- RpcClient, RpcError, ExecuteParams
530
- SseClient, SseEventData, WsClient, WsEventData
531
- AuthApiClient, AdminApiClient
532
- LocalStorageTokenStore, MemoryTokenStore, TokenStore
533
- parseAuthCallback, buildAuthLoginUrl, AuthCallbackResult, AuthLoginOptions
534
- WebHttpClient, HttpClient, HTTPError
535
- // ...and all other mero-js exports
536
- ```
306
+ | `MeroProvider mode={AppMode.X}` | `MeroProvider minReleaseVersion=… \| allowMock` (no modes, no permission scopes) |
307
+ | `useMero().mero` | `useMero().client` (`mero` is kept as a deprecated alias) |
308
+ | `useMero().contextId` / `contextIdentity` / `applicationId` | `useMero().appId` / `accountId` / none |
309
+ | `useMero().isOnline` | none: the client retries and fails over by itself |
310
+ | `connectToNode(url)` + redirect login | `connectToNode(url)` + `signIn()` / `signUp(name)` |
311
+ | `connectWithAccount`, `isDelegated`, `can`, `admin` | none (no relays, no delegated accounts) |
312
+ | `useExecute(contextId, executorId).execute(m, p)` | `useExecute(appId).execute(m, args, { confirm?, idempotencyKey? })` |
313
+ | none | `useView(method, args)`, `useApp(appId)` |
314
+ | `useSubscription(contextIds, cb)` / `{ contextIds, groupIds }` | `useSubscription(appIds, cb, { from?, onOpen? })` |
315
+ | `useContexts`, `useApplicationContexts`, `useNamespacesForApplication` | `useApps({ package? })` |
316
+ | `useCreateContext`, `useCreatePrivateContext` | `useCreateApp` (`access` for private apps) |
317
+ | `useDeleteContext`, `useSetContextMetadata` | `useDeleteApp`, `useSetAppMetadata` |
318
+ | `useNamespace`, `useNamespaces`, `useCreateNamespace`, `useDeleteNamespace` | `useOrg`, `useAccount` (orgs), `useCreateOrg`, `useDeleteOrg` |
319
+ | `useGroupInfo`, `useNamespaceGroups`, `useSubgroups`, `useContextGroup` | `useTeam` (teams are listed in `useOrg`) |
320
+ | `useCreateGroupInNamespace`, `useDeleteGroup` | `useCreateTeam`, `useDeleteTeam` |
321
+ | `useAddGroupMembers`, `useRemoveGroupMembers`, `useGroupMembers` | `useSetTeamMember`, `useRemoveTeamMember`, `useTeam` |
322
+ | `useUpdateMemberRole`, `useGroupCapabilities`, `useSetDefaultCapabilities` | `useSetMember`, `useOrg`, `useSetCapabilities` |
323
+ | `useSetGroupMetadata`, `useGroupMetadata`, `useMemberMetadata` | `useSetOrgMetadata` / `useUpdateTeam`, `useOrg` / `useTeam` |
324
+ | `useReparentGroup`, `useSetSubgroupVisibility` | `useUpdateTeam({ parent, join })` |
325
+ | `useCreateNamespaceInvitation`, `useGroupInvitations` | `useCreateInvite` |
326
+ | `useRedeemInvitation`, `useJoinNamespace`, `useJoinGroup`, `useJoinContext` | `useRedeemInvite` |
327
+ | `useInviteRedemption`, `useJoinInvitation` | `useInviteRedemption` (no relay or sync step) |
328
+ | `useUpgradeGroup`, `useInstallFromRegistry` | `useUpgradeApp`, or `useConsent` + `upgradeConsent` from an app frontend |
329
+ | `useGroupUpgradeStatus`, `useRetryGroupUpgrade` | mero-js `client.upgradeRun` / `retryUpgradeRun` (org upgrade runs) |
330
+ | `useUploadBlob`, `useBlobInfo`, `useBlobUrl` | Same names, now per app (`{ appId }`) |
331
+ | `useEphemeral(contextId, opts)` | `useEphemeral(appId, opts)`: peers keyed by account |
332
+ | `useNodeIdentity` | `useAccount` |
333
+ | `classifyError(err)` / `ClassifiedError` | `describeError(err)` / `Failure` |
334
+ | `getPermissionsForMode`, `AppMode`, `ConnectionType` | removed (no permission scopes) |
335
+ | `localStorageTokenStore`, `get/setContextId`, `get/setApplicationId`, `get/setContextIdentity` | `localStorageSessionStore`, `get/setAppId` |
336
+
337
+ **Removed with no replacement** (v1 or desktop only):
338
+
339
+ - admin-API hooks: `useSyncGroup`, `useResyncContext`, `useJoinSubgroupInheritance`, `useDetachContextFromGroup`, `useSetTeeAdmissionPolicy`, `useContextDiscovery`;
340
+ - migration hooks and components: `useMigrationStatus`, `useMigrationEvents`, `useMyAuthoredMigration`, `MigrationPendingBanner`, `MigrationAdminPanel`;
341
+ - version hooks: `useAppVersion`, `useLatestVersion`, `useGroupAppVersion`;
342
+ - the delegated / relay / account-enrolment layer: `useAccountEnrolment`, `useDelegatedBootstrap`, `ConnectButtonAccount`, `AccountSignInPanel`, and the relay, `joinWithNode` and `bootstrapFromInvitation` re-exports;
343
+ - invitation UI: `InvitationGate`, `InvitationDialog`, `JoinSyncBanner`, `useJoinSync`;
344
+ - local-node discovery: `discoverLocalNodes`;
345
+ - desktop (Tauri): `isDesktopWindow`.
537
346
 
538
347
  ## License
539
348