@calimero-network/mero-react 10.3.0 → 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,369 +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
70
-
71
- ### `<MeroProvider>`
72
-
73
- Wraps your app with a MeroJs instance, auth state, and SSE connectivity.
65
+ A frontend hosted elsewhere reaches a Calimero Cloud cluster by name, failing over between its nodes:
74
66
 
75
67
  ```tsx
76
- <MeroProvider
77
- mode={AppMode.SingleContext} // required
78
- packageName="com.calimero.my-app" // for package-based apps
79
- timeoutMs={30000} // optional, default 30s
80
- >
81
- {children}
82
- </MeroProvider>
68
+ <MeroProvider cluster="eu-shared-1" minReleaseVersion="2.3.109" appId={APP_ID}>
83
69
  ```
84
70
 
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
- | `servedByNode` | `boolean` | No | The node serves this page from its own origin. See [Serving an app from a node](#serving-an-app-from-a-node). |
96
- | `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). |
97
-
98
- Modes and their permissions:
99
-
100
- | Mode | Permissions | Use case |
101
- |------|-------------|----------|
102
- | `SingleContext` | `context:execute` | Apps that work with one context |
103
- | `MultiContext` | `context:create`, `context:list`, `context:execute` | Apps managing multiple contexts |
104
- | `Admin` | `admin` | Admin dashboards, dev tools |
105
-
106
- 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.
107
-
108
- #### Serving an app from a node
109
-
110
- When a node serves your bundled frontend (for example at `my-app.localhost:2428`), pass `servedByNode`.
111
- The node is then the page's own origin: the client talks to `window.location.origin` whatever the login callback's `node_url` says, and nothing probes other origins.
112
- `ConnectButton` skips the node picker and goes straight to `/auth/login` on that origin, which the node redirects to its login page.
113
- Set the prop yourself, for example from a build flag; the provider does not detect it.
71
+ For local development against `merod local` (three `--dev` nodes with mock attestation on 127.0.0.1:2501-2503):
114
72
 
115
73
  ```tsx
116
- <MeroProvider mode={AppMode.MultiContext} servedByNode>
74
+ <MeroProvider
75
+ nodeUrl="http://127.0.0.1:2501"
76
+ nodes={['http://127.0.0.1:2502', 'http://127.0.0.1:2503']}
77
+ allowMock
78
+ >
117
79
  ```
118
80
 
119
- The node serves the page under a strict CSP (`connect-src 'self'`), so the bundle must:
120
-
121
- - be built with Vite `base: './'` and reference assets by relative URL;
122
- - have no inline scripts and no CDN-hosted scripts, styles or fonts.
123
-
124
- 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. |
125
101
 
126
102
  ### `useMero()`
127
103
 
128
- Access the MeroJs instance, auth state, and actions.
129
-
130
- ```tsx
104
+ ```ts
131
105
  const {
132
- mero, // MeroJs | null — the SDK instance
133
- isAuthenticated, // boolean
134
- isOnline, // boolean — SSE connection state
135
- isLoading, // boolean — initial session restore
136
- nodeUrl, // string | null
137
- applicationId, // string | null — node: from the auth callback; account: see below
138
- contextId, // string | null — from auth callback
139
- contextIdentity, // string | null — executor public key from auth callback
140
- connectToNode, // (url: string) => void — starts auth redirect
141
- admin, // AdminApiClient | null — the session's admin: node admin on a node, account admin on an account
142
- 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,
143
121
  } = useMero();
144
122
  ```
145
123
 
146
- 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`.
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.
147
125
 
148
- 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.
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`.
149
130
 
150
- 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.
131
+ ## Hooks
151
132
 
152
- Through `mero` you access the full MeroJs API:
133
+ Every read hook returns `{ data, loading, error, failure, refetch }`. Every action hook returns its action plus `{ loading, error, failure }`.
153
134
 
154
- ```tsx
155
- // Admin API (flat methods, NOT nested)
156
- await mero.admin.healthCheck();
157
- await mero.admin.getContexts();
158
- await mero.admin.getContext(contextId);
159
- await mero.admin.getContextIdentitiesOwned(contextId);
160
- await mero.admin.listApplications();
161
- await mero.admin.getApplication(appId);
162
- await mero.admin.installApplication(request);
163
- await mero.admin.createContext(request);
164
- await mero.admin.uploadBlob(request);
165
- await mero.admin.getPeersCount();
166
-
167
- // Auth API
168
- await mero.auth.getProviders();
169
- await mero.auth.generateTokens(request);
170
- await mero.auth.refreshToken(request);
171
-
172
- // RPC
173
- await mero.rpc.execute({ contextId, method, argsJson, executorPublicKey });
174
-
175
- // SSE events
176
- mero.events.connect();
177
- mero.events.subscribe(contextIds);
178
- mero.events.on('event', handler);
179
-
180
- // Tokens
181
- mero.getTokenData(); // { access_token, refresh_token, expires_at } | null
182
- mero.isAuthenticated(); // boolean
183
- ```
184
-
185
- ### `useExecute(contextId, executorId)`
186
-
187
- Wraps `mero.rpc.execute()` with loading/error state. Unmount-safe.
188
-
189
- ```tsx
190
- const { execute, loading, error } = useExecute(contextId, contextIdentity);
191
-
192
- // Generic typed
193
- const todos = await execute<Todo[]>('list');
194
- await execute('add', { title: 'Buy milk' });
195
- await execute('toggle', { id: '1' });
196
- ```
197
-
198
- | Return | Type | Description |
199
- |--------|------|-------------|
200
- | `execute` | `<T>(method, params?) => Promise<T \| null>` | Call a contract method |
201
- | `loading` | `boolean` | Request in flight |
202
- | `error` | `Error \| null` | Last error |
203
-
204
- ### `useSubscription(contextIds, callback)`
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.
205
138
 
206
- Manages SSE event subscription lifecycle. StrictMode-safe — connects once per MeroJs instance, cleans up on unmount.
139
+ ### App: calls, views, events
207
140
 
208
- ```tsx
209
- useSubscription(
210
- contextId ? [contextId] : [],
211
- (event) => {
212
- console.log('Context event:', event.contextId, event.data);
213
- refreshData();
214
- },
215
- );
216
- ```
217
-
218
- | Param | Type | Description |
219
- |-------|------|-------------|
220
- | `contextIds` | `string[]` | Context IDs to subscribe to (empty array = no subscription) |
221
- | `callback` | `(event: SseEventData) => void` | Called on each context event |
222
-
223
- The SSE connection is shared — multiple `useSubscription` hooks reuse the same connection. The first one to mount calls `connect()`, subsequent ones just add handlers.
224
-
225
- ### `useContexts(applicationId?)`
226
-
227
- Fetches contexts from the node, optionally filtered by application ID.
228
-
229
- ```tsx
230
- const { contexts, loading, error, refetch } = useContexts(applicationId);
231
-
232
- // contexts: Array<{ contextId: string; applicationId: string }>
233
- ```
234
-
235
- ### Blob hooks
236
-
237
- `useBlobInfo` / `useBlobUrl` / `useUploadBlob` read and write the node's blob
238
- store. The reads take an optional `contextId`, and it is what picks the mode:
239
-
240
- - **without `contextId`** — local-only. The node answers from its own blob
241
- store immediately, or 404s.
242
- - **with `contextId`** — network discovery. The node probes that context's
243
- peers (availability nodes first) for a holder.
244
-
245
- Discovery is slow: core bounds the search by a **~30s deadline**, and for
246
- `useBlobUrl` the byte transfer is on top of that. `loading` is real UI state on
247
- these hooks, not decoration.
248
-
249
- ```tsx
250
- // Presence and size, no download — ask this before pulling something large.
251
- const { info, notFound, loading, error } = useBlobInfo(blobId, { contextId });
252
- // info: { blobId, size, hash?, mimeType?, source?: 'local' | 'peer' } | null
253
-
254
- // Bytes as an object URL, revoked for you on unmount and on id/context change.
255
- const { url } = useBlobUrl(blobId, { contextId, type: 'image/png' });
256
- return url ? <img src={url} /> : null;
257
-
258
- // Upload. Pass contextId to announce the blob so the context's peers can
259
- // discover it later.
260
- const { uploadBlob, loading, error } = useUploadBlob();
261
- const result = await uploadBlob({ data: bytes, contextId });
262
- ```
263
-
264
- A null/undefined `blobId` fetches nothing, like the other `string | null` read
265
- hooks. `hash` and `mimeType` are genuinely optional — a peer probe carries only
266
- presence and size, so a discovery-sourced hit has neither; read `info.source`
267
- to tell a local answer from a peer one. `notFound` marks the node's legitimate
268
- "no holder" 404 apart from a transport failure; `error` is set for both.
269
-
270
- ### Storage helpers
271
-
272
- Persist/read node URL, application ID, context ID, and context identity in localStorage.
273
-
274
- ```tsx
275
- import {
276
- getNodeUrl, setNodeUrl, clearNodeUrl,
277
- getApplicationId, setApplicationId, clearApplicationId,
278
- clearAllStorage,
279
- } from '@calimero-network/mero-react';
280
- ```
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. |
281
148
 
282
- These are used internally by `MeroProvider` but exported for apps that need direct access.
149
+ `appId` defaults to the provider's `appId`.
283
150
 
284
- ### Invitations by link
151
+ How `useSubscription` behaves:
285
152
 
286
- 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.
287
157
 
288
- ```tsx
289
- import {
290
- primeInvitationCapture,
291
- useInviteRedemption,
292
- InvitationDialog,
293
- InvitationGate,
294
- buildInviteLink,
295
- } from '@calimero-network/mero-react';
158
+ ### Apps
296
159
 
297
- // main.tsx, before the router runs: take the link from the URL or the desktop
298
- // bridge and buffer it until something asks.
299
- 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) |
300
168
 
301
- // The app root, once: ask, join, wait for the data, done.
302
- function Invitations() {
303
- const redemption = useInviteRedemption({
304
- parse: (token) => decodeMyToken(token), // { namespaceId, invitation, teamName? }
305
- redeemer: { join, isMember }, // mero-js `InviteRedeemer`
306
- onJoined: (namespaceId) => navigate(`/w/${namespaceId}`),
307
- });
308
- return (
309
- <>
310
- {/* Logged out: "You're invited", with the login. Logged in: nothing. */}
311
- <InvitationGate parse={decodeMyToken} noun="workspace" appName="My App" />
312
- <InvitationDialog redemption={redemption} noun="workspace" appName="My App" />
313
- </>
314
- );
315
- }
169
+ ### Organizations and teams
316
170
 
317
- // Sharing: one link shape for every app.
318
- 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);
319
211
  ```
320
212
 
321
- 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).
322
-
323
- `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`.
324
214
 
325
- `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
326
216
 
327
- **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:
328
-
329
- ```tsx
330
- // The page showing the namespace: `settled` once a read has come back,
331
- // including an empty one.
332
- 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
+ };
333
243
  ```
334
244
 
335
- 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.
336
-
337
- 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.
338
-
339
- 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`.
340
-
341
- ### Re-exports from mero-js
342
-
343
- 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.
344
-
345
- ```tsx
346
- // All of these work from a single import
347
- import {
348
- MeroProvider, useMero, useExecute, useSubscription, // react
349
- MeroJs, RpcClient, SseClient, WsClient, // core
350
- parseAuthCallback, buildAuthLoginUrl, // auth helpers
351
- LocalStorageTokenStore, MemoryTokenStore, // token stores
352
- } from '@calimero-network/mero-react';
353
- ```
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 |
354
257
 
355
- ## Theming
258
+ ## Components
356
259
 
357
- `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.
358
262
 
359
- ```tsx
360
- import { ConnectButton } from '@calimero-network/mero-react';
361
-
362
- // Default green palette — no theme prop needed
363
- <ConnectButton />
364
-
365
- // Override only what you want; the rest stay default
366
- <ConnectButton
367
- theme={{
368
- primary: '#ff4081',
369
- primaryHover: '#e91e63',
370
- primaryText: '#ffffff',
371
- }}
372
- />
373
- ```
263
+ ### Theming
374
264
 
375
- 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:
376
266
 
377
267
  ```css
378
268
  :root {
@@ -381,176 +271,78 @@ The same theme is forwarded to the embedded `LoginModal` and is also exposed as
381
271
  }
382
272
  ```
383
273
 
384
- 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.
385
-
386
- | 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 |
387
305
  | --- | --- |
388
- | `mero-login-overlay` | the full-screen backdrop, a direct child of `body` |
389
- | `mero-login-dialog` | the dialog surface |
390
- | `mero-login-close`, `mero-login-header`, `mero-login-logo`, `mero-login-title` | close button, header, emblem, "Connect to Calimero" |
391
- | `mero-login-tabs`, `mero-login-tab` (+ `mero-login-tab-active`), `mero-login-panel` | Node / Cloud tabs and their panels |
392
- | `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 |
393
- | `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 |
394
- | `mero-login-input`, `mero-login-toolbar`, `mero-login-rescan` | manual URL field, rescan link |
395
- | `mero-login-actions`, `mero-login-button mero-login-primary` | Connect / Enrol buttons |
396
- | `mero-login-discovering`, `mero-login-loading`, `mero-login-spinner`, `mero-login-account` | progress states, the Cloud tab's body |
397
-
398
- ```css
399
- /* `body >` outranks mero-react's own single-class rules, injected after yours. */
400
- body > .mero-login-overlay {
401
- --mero-login-shadow: 0 30px 60px -30px rgba(20, 26, 60, 0.45);
402
- font-family: 'Figtree', sans-serif;
403
- }
404
- ```
405
-
406
- `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`.
407
-
408
- 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.
409
-
410
- **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.
411
-
412
- ### `<ConnectButton>` props
413
-
414
- ```tsx
415
- // Square 40×40 icon button — logo only, no text
416
- <ConnectButton logoOnly />
417
-
418
- // Custom label (shorthand: bare string overrides the disconnected label)
419
- <ConnectButton label="Sign in with Calimero" />
420
-
421
- // Per-state label overrides
422
- <ConnectButton
423
- label={{
424
- connect: 'Sign in',
425
- connected: 'Signed in',
426
- reconnecting: 'Reconnecting…',
427
- }}
428
- />
429
- ```
430
-
431
- | Prop | Type | Default | Notes |
432
- |------|------|---------|-------|
433
- | `connectionType` | `ConnectionType \| CustomConnectionConfig` | `Remote` | `Custom` connects straight to the given URL, skipping the modal. Every other value opens the LoginModal (local node discovery + manual URL entry). Inside a `servedByNode` provider the button skips the modal and logs in at the page's own origin. |
434
- | `theme` | `MeroTheme` | — | Partial token override. |
435
- | `logoOnly` | `boolean` | `false` | Render only the Calimero logo (square button). The label is still announced via `aria-label`. |
436
- | `label` | `string \| { connect?, connected?, reconnecting? }` | — | Override default labels. Bare string targets the disconnected state. |
437
- | `className` / `style` | — | — | Forwarded to the inner `<button>`. |
438
- | `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. |
439
- | `accountDefaults` | `{ walletUrl?: string }` | — | Local development only: enrol at a wallet other than the hosted one. |
440
-
441
- ### `<LoginModal>` and the Cloud tab
442
-
443
- 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`.
444
-
445
- ```tsx
446
- // Node + Cloud tabs, account sign-in included (default)
447
- <LoginModal isOpen={open} onConnect={connectToNode} onClose={() => setOpen(false)} />
448
-
449
- // Node dialog only, no tabs — the pre-Cloud behaviour
450
- <LoginModal cloud={false} isOpen={open} onConnect={connectToNode} onClose={() => setOpen(false)} />
451
-
452
- // Your own enrolment (what ConnectButton does): the object is used verbatim
453
- <LoginModal cloud={{ onEnrol, note, walletUrl, customWallet }} initialTab="cloud" ... />
454
- ```
455
-
456
- | `cloud` | Cloud tab | Enrolment callback read by |
457
- |---------|-----------|----------------------------|
458
- | omitted | shown, sourced by the modal | the modal |
459
- | `false` | none (no tabs) | nobody here |
460
- | object | shown, the caller's values | the caller |
461
-
462
- `initialTab` defaults to `'node'`; with `cloud` omitted it defaults to `'cloud'` on the load coming back from the wallet. An explicit `initialTab` wins.
463
-
464
- 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>`.
465
-
466
- ## Enums
467
-
468
- ```tsx
469
- AppMode.SingleContext // 'single-context'
470
- AppMode.MultiContext // 'multi-context'
471
- AppMode.Admin // 'admin'
472
-
473
- ConnectionType.Remote // 'remote' — opens the LoginModal (discovery + manual URL)
474
- ConnectionType.Custom // 'custom' — skip the modal, connect to a fixed URL
475
- ConnectionType.RemoteAndLocal // deprecated, same as Remote
476
- ConnectionType.Local // deprecated, same as Remote
477
- ```
478
-
479
- ## Types
480
-
481
- ```tsx
482
- import type {
483
- MeroContextValue, // useMero() return type
484
- MeroProviderConfig, // MeroProvider props (without children)
485
- MeroProviderProps, // MeroProvider props (with children)
486
- CustomConnectionConfig, // { type: ConnectionType.Custom, url: string }
487
- AppContext, // { contextId, executorId, applicationId }
488
- ExecutionResult, // { success, result?, error? }
489
- ApplicationContextRecord,// { contextId, applicationId }
490
- ContextDiscoveryOptions, // options for useContextDiscovery
491
- ContextDiscoveryState, // return type of useContextDiscovery
492
- MeroTheme, // partial theme override for ConnectButton / LoginModal
493
- ResolvedMeroTheme, // fully populated theme returned by resolveMeroTheme()
494
- } from '@calimero-network/mero-react';
495
- ```
496
-
497
- ## Full exports list
498
-
499
- ```
500
- // Provider & context (mero-react)
501
- MeroProvider, useMero, MeroContext
502
-
503
- // Components (mero-react)
504
- ConnectButton, LoginModal
505
-
506
- // Theming (mero-react)
507
- MeroTheme, ResolvedMeroTheme, defaultMeroTheme, resolveMeroTheme, themeToCssVars
508
-
509
- // Enums (mero-react)
510
- AppMode, ConnectionType
511
-
512
- // Hooks (mero-react)
513
- useExecute, useSubscription
514
- useContexts, useApplicationContexts, useContextGroup, useContextDiscovery
515
- useCreateContext, useDeleteContext, useJoinContext
516
- useGroupInfo, useGroupMembers, useGroupContexts, useGroupInvitations, useGroupCapabilities
517
- useJoinGroup, useDeleteGroup, useAddGroupMembers, useRemoveGroupMembers
518
- useSyncGroup, useReparentGroup, useSubgroups
519
- useUpgradeGroup, useGroupUpgradeStatus, useRetryGroupUpgrade
520
- useSetGroupMetadata, useSetMemberMetadata, useSetContextMetadata
521
- useGroupMetadata, useMemberMetadata, useUpdateMemberRole
522
- useSetDefaultCapabilities, useDefaultCapabilities
523
- useSetSubgroupVisibility, useSubgroupVisibility, useSetTeeAdmissionPolicy
524
- useDetachContextFromGroup
525
- useNamespaces, useNamespace, useNamespaceGroups, useNodeIdentity
526
- useNamespacesForApplication, useCreateNamespace, useDeleteNamespace
527
- useJoinNamespace, useRedeemInvitation, useCreateNamespaceInvitation, useCreateGroupInNamespace
528
- useBlobInfo, useBlobUrl, useUploadBlob
529
-
530
- // Types (mero-react)
531
- MeroContextValue, MeroProviderConfig, MeroProviderProps
532
- CustomConnectionConfig, AppContext, ExecutionResult
533
- ApplicationContextRecord, ContextDiscoveryOptions, ContextDiscoveryState
534
- BlobHookOptions, UseBlobUrlOptions, MutationOptions
535
-
536
- // Storage (mero-react)
537
- localStorageTokenStorage
538
- getNodeUrl, setNodeUrl, clearNodeUrl
539
- getApplicationId, setApplicationId, clearApplicationId
540
- getContextId, setContextId, clearContextId
541
- getContextIdentity, setContextIdentity, clearContextIdentity
542
- clearAllStorage
543
-
544
- // Everything from @calimero-network/mero-js (auto re-exported)
545
- MeroJs, createMeroJs, MeroJsConfig, TokenData
546
- RpcClient, RpcError, ExecuteParams
547
- SseClient, SseEventData, WsClient, WsEventData
548
- AuthApiClient, AdminApiClient
549
- LocalStorageTokenStore, MemoryTokenStore, TokenStore
550
- parseAuthCallback, buildAuthLoginUrl, AuthCallbackResult, AuthLoginOptions
551
- WebHttpClient, HttpClient, HTTPError
552
- // ...and all other mero-js exports
553
- ```
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`.
554
346
 
555
347
  ## License
556
348