@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/dist/index.d.cts CHANGED
@@ -1,268 +1,903 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
- import * as React from 'react';
3
- import React__default, { CSSProperties, ReactNode } from 'react';
2
+ import React, { CSSProperties } from 'react';
4
3
  import * as _calimero_network_mero_js from '@calimero-network/mero-js';
5
- import { MeroJs, MeroClient, DelegatedAccountSession, TokenStore, DelegatedCredential, BootstrapResult, SignedGroupOpenInvitation, InviteFailureReason, InviteRedeemer, RedeemOutcome, BootstrapFailure, SetMetadataRequest, SseEventData, GroupMembershipEventData, GroupMigrationEventData, Codec, AddGroupMembersRequest, GetBlobInfoResponseData, CreateContextRequest, CreateGroupInNamespaceRequest, CreateNamespaceRequest, CreateNamespaceInvitationRequest, CreateNamespaceInvitationResponseData, CreateRecursiveInvitationResponseData, GroupUpgradeStatusResponseData, GroupContextEntry, GroupInfo, CreateGroupInvitationRequest, MetadataRecord, ClassifiedError, JoinGroupRequest, JoinNamespaceRequest, MigrationStatus, MigrationStatusRollup, MemberMigrationStatusEntry, MigrateMyEntriesSummary, Namespace, SubgroupEntry, NodeIdentity, RemoveGroupMembersRequest, ReparentGroupRequest, ResyncContextRequest, SetDefaultCapabilitiesRequest, SetSubgroupVisibilityRequest, SetTeeAdmissionPolicyRequest, UpdateMemberRoleRequest, UpgradeGroupRequest, UploadBlobRequest, TokenData } from '@calimero-network/mero-js';
4
+ import { CloudPolicy, CalimeroClient, CalimeroClientOptions, CalimeroSession, PasskeyProvider, CloudRetryOptions, CallResult, ViewResult, AppInfo, OrgInfo, ConsentRequest, ConsentStarted, OpenConsentOptions, ConsentResult, BlobInfo } from '@calimero-network/mero-js';
6
5
  export * from '@calimero-network/mero-js';
7
- export { AccountAdminDeps, BootstrapFailure, BootstrapFromInvitationInput, BootstrapResult, BootstrapStep, BootstrapSuccess, CAPABILITIES, Codec, DEFAULT_LOCAL_NODE_PORTS, DelegatedCredential, DelegatedAccountSession as DelegatedSession, DiscoverLocalNodesOptions, EphemeralClient, EphemeralEntry, FoundedDelegatedNamespace, HA_ACCOUNT_NOT_LINKED_MESSAGE, HA_REFUSAL_MESSAGES, InvitationNotClaimableError, JoinWithNodeFailure, JoinWithNodeInput, JoinWithNodeResult, JoinWithNodeStep, JoinWithNodeSuccess, MetadataRecord, NoRelayError, NotForAccountError, RegistryBundle, RelayResolutionFailure, RelayResolutionStep, ResolveRelayFromInvitationInput, ResolveRelayResult, ResolvedApplication, ResolvedInvitationRelay, applicationIdForBundle, bootstrapFromInvitation, clearDelegatedCredential, createAccountAdmin, createDelegatedContext, createNodeAdmin, discoverLocalNodes, hasCap, joinWithNode, listDelegatedContexts, localNodeUrl, nodeEndpoint, normaliseAccount, pinRelayNodeKey, probeNodeHealth, readDelegatedCredential, readPinnedRelayNodeKey, readRelayMap, relayForContext, rememberRelay, resolveApplicationIdFromRegistry, resolveRelayFromInvitation, saveDelegatedCredential, selectLatestBundle, withCap, withoutCap } from '@calimero-network/mero-js';
8
6
 
9
7
  /**
10
- * Application mode determines the permission scope
8
+ * The `CalimeroClient` the provider holds, and the policy it verifies nodes
9
+ * under.
11
10
  */
12
- declare enum AppMode {
13
- /**
14
- * @deprecated since 2.1.0 — SingleContext is no longer supported and will
15
- * be removed in 3.0.0. Auth-frontend no longer drives
16
- * context/namespace/group selection; the auth callback returns only
17
- * `access_token`, `refresh_token`, `application_id`, and `node_url`.
18
- * Switch to {@link AppMode.MultiContext} and have your app manage
19
- * context selection itself.
20
- *
21
- * Migration: see `example/app/src/pages/context/SelectContext.tsx` for a
22
- * reference implementation. It uses `useContexts` /
23
- * `useNamespacesForApplication` for listing, then calls
24
- * `mero.admin.createNamespace` / `createGroupInNamespace` /
25
- * `createContext` directly (rather than the `useCreate*` hooks) so the
26
- * underlying server error surfaces to the user instead of being
27
- * swallowed by `useAsyncMutation`.
28
- */
29
- SingleContext = "single-context",
30
- /** Multi-context: user can manage multiple contexts */
31
- MultiContext = "multi-context",
32
- /** Admin: full administrative access */
33
- Admin = "admin"
34
- }
35
- /**
36
- * Connection type for the login modal
37
- */
38
- declare enum ConnectionType {
11
+
12
+ /** How the provider decides which nodes to trust. */
13
+ interface PolicyOptions {
14
+ /** The full policy, as mero-js takes it. Wins over `minReleaseVersion`. */
15
+ policy?: CloudPolicy;
39
16
  /**
40
- * @deprecated The login modal no longer has Local/Remote tabs — it always
41
- * shows node discovery + manual URL entry. Behaves the same as `Remote`.
17
+ * The oldest mero-tee release to trust (e.g. `2.3.109`): shorthand for
18
+ * `policy: { release: { minReleaseVersion } }`.
42
19
  */
43
- RemoteAndLocal = "remote-and-local",
44
- /** Open the login modal (node discovery + manual URL entry) */
45
- Remote = "remote",
20
+ minReleaseVersion?: string;
46
21
  /**
47
- * @deprecated The hardcoded default-local-node view was removed. Behaves
48
- * the same as `Remote`.
22
+ * Accept mock attestation quotes. For `merod local` and other `--dev`
23
+ * clusters only: never derive it from anything a visitor controls.
49
24
  */
50
- Local = "local",
51
- /** Custom URL (skip modal) */
52
- Custom = "custom"
25
+ allowMock?: boolean;
53
26
  }
54
27
  /**
55
- * Custom connection configuration
28
+ * The policy for {@link PolicyOptions}. Throws when nothing says what to trust:
29
+ * a client that trusted every quote would not be verifying anything.
56
30
  */
57
- interface CustomConnectionConfig {
58
- type: ConnectionType.Custom;
59
- url: string;
60
- }
31
+ declare function resolvePolicy({ policy, minReleaseVersion, allowMock }: PolicyOptions): CloudPolicy;
61
32
  /**
62
- * Context for an application
33
+ * A `CalimeroClient` that reports every session it takes: a sign-in, a sign-up
34
+ * and the refreshes the client makes by itself on a `401` (single-flight, any
35
+ * node). The provider keeps the newest in its store, so a reload resumes with a
36
+ * refresh token that has not been spent.
63
37
  */
64
- interface AppContext {
65
- contextId: string;
66
- executorId: string;
67
- applicationId: string;
38
+ declare class SessionReportingClient extends CalimeroClient {
39
+ private readonly report;
40
+ constructor(options: CalimeroClientOptions, onSession?: (session: CalimeroSession) => void);
41
+ useSession(session: CalimeroSession): void;
42
+ /** Take a session kept from an earlier page load, without reporting it back. */
43
+ restore(session: CalimeroSession): void;
68
44
  }
69
45
  /**
70
- * Result of an RPC execution
46
+ * {@link SessionReportingClient}'s reporting for a client mero-js built itself
47
+ * (`CalimeroClient.connect`, a cluster by name): every session it takes from
48
+ * now on goes to `onSession` too. Answers the unreported `useSession`, for a
49
+ * session kept from an earlier page load.
71
50
  */
72
- interface ExecutionResult<T = unknown> {
73
- success: boolean;
74
- result?: T;
75
- error?: string;
76
- }
77
- interface ApplicationContextRecord {
78
- contextId: string;
79
- applicationId: string;
80
- }
81
- interface ContextDiscoveryOptions {
82
- applicationId: string;
83
- knownContextIds?: string[];
84
- targetAlias?: string;
85
- pollIntervalMs?: number;
86
- timeoutMs?: number;
87
- }
88
- interface ContextDiscoveryState {
89
- context: ApplicationContextRecord | null;
90
- loading: boolean;
91
- error: Error | null;
92
- discover: () => Promise<ApplicationContextRecord | null>;
93
- reset: () => void;
51
+ declare function reportSessions(client: CalimeroClient, onSession: (session: CalimeroSession) => void): (session: CalimeroSession) => void;
52
+
53
+ /**
54
+ * The node's refusals, as an app shows them.
55
+ *
56
+ * mero-js turns every refusal into a typed error ({@link CalimeroError} and its
57
+ * subclasses, `errorFrom`). Hooks keep that error as it is in `error`, so an
58
+ * app can still `instanceof AppError` and read `appCode` / `fields`, and add
59
+ * {@link describeError}'s reading of it in `failure`: one `kind` to switch on,
60
+ * a sentence to show, and whether trying again can help.
61
+ */
62
+ type FailureKind =
63
+ /** The app refused the call (`422 APP_ERROR`): see `appCode` / `fields`. */
64
+ 'app'
65
+ /** The run trapped (`422 TRAP`): out of fuel, out of memory, a panic. */
66
+ | 'trap'
67
+ /** The session is gone and could not be refreshed: sign in again. */
68
+ | 'login'
69
+ /**
70
+ * The request needs the passkey (`412 CONFIRM_REQUIRED`) and none answered
71
+ * it: a call made without `confirm: true`, or a client method called with no
72
+ * passkey.
73
+ */
74
+ | 'confirm'
75
+ /** The person dismissed the passkey prompt. Nothing was sent. */
76
+ | 'cancelled'
77
+ /** `421 WRONG_NODE` / `NOT_LEADER` the client could not move past. */
78
+ | 'wrong-node'
79
+ /** `503` or no answer, after the client's retries ran out. */
80
+ | 'unavailable'
81
+ /** `404`: missing, or not visible to this account. */
82
+ | 'not-found'
83
+ /** `403`: this session may not do that (an app frontend cannot approve, say). */
84
+ | 'forbidden'
85
+ /** `409 RELEASE_DEADLINE`: approve the named release to lift it. */
86
+ | 'release-deadline'
87
+ /** `409 CONSENT_STALE`: ask for a new consent request. */
88
+ | 'consent-stale'
89
+ /** `428 OPERATOR_SIGNATURE_REQUIRED`. */
90
+ | 'operator-signature'
91
+ /** `413`: the arguments or the body are over the node's limit. */
92
+ | 'too-large'
93
+ /** `409 IDEMPOTENCY_MISMATCH`: the key was used with other arguments. */
94
+ | 'idempotency'
95
+ /** `429`: the node is at its limit (event streams, say). */
96
+ | 'rate-limited'
97
+ /** The node's attestation or the sealed channel failed. */
98
+ | 'attestation'
99
+ /** The node directory named no node of the cluster (`DirectoryError`). */
100
+ | 'directory'
101
+ /** Anything else. */
102
+ | 'unknown';
103
+ interface Failure {
104
+ kind: FailureKind;
105
+ /** A sentence an app can show as it is. */
106
+ message: string;
107
+ /** Whether the same request may succeed later without anything changing. */
108
+ retryable: boolean;
109
+ /** The node's HTTP status, when it answered. */
110
+ status?: number;
111
+ /** The node's error code (`APP_ERROR`, `WRONG_NODE`, ...), when it answered. */
112
+ code?: string;
113
+ /** For `kind: 'app'`: the app's declared error (`Taken`, `Forbidden`, ...). */
114
+ appCode?: string;
115
+ /** For `kind: 'app'`: the error's named fields. */
116
+ fields?: Record<string, unknown>;
117
+ /** For `kind: 'unavailable'`: whether the call may have committed. */
118
+ committed?: false | 'unknown';
119
+ /** For `kind: 'release-deadline'`: the mero-tee release to approve. */
120
+ release?: string;
121
+ /** The error itself. */
122
+ error: unknown;
123
+ }
124
+ /** Read any error a hook or the client threw. */
125
+ declare function describeError(error: unknown): Failure;
126
+ /** Whether an error means the session is gone for good (sign in again). */
127
+ declare function isLoginRequired(error: unknown): boolean;
128
+
129
+ /**
130
+ * What mero-react keeps between page loads: the node or cluster it talks to,
131
+ * the app instance it opened last, and the passkey session.
132
+ *
133
+ * A Calimero 1.0 session is a short-lived session token (`v2.…`, 15 minutes)
134
+ * plus a single-use refresh token (`rt_…`, 30 days). Both are kept together as
135
+ * one {@link CalimeroSession} so a reload resumes where the page left off: the
136
+ * client refreshes on the first `401` by itself.
137
+ */
138
+
139
+ /** Where the provider keeps the passkey session. */
140
+ interface SessionStore {
141
+ load(): CalimeroSession | null;
142
+ save(session: CalimeroSession): void;
143
+ clear(): void;
94
144
  }
95
145
  /**
96
- * Mero context value exposed by useMero hook
146
+ * The default store: `localStorage`, so a reload stays signed in.
147
+ *
148
+ * SECURITY: anything in `localStorage` is readable by every script on the
149
+ * origin, the refresh token included. A frontend the node serves runs on its
150
+ * own `{label}.{apps-domain}` origin under the node's CSP, which is the
151
+ * intended setup. Pass {@link memorySessionStore} to keep the session for the
152
+ * tab's lifetime only.
97
153
  */
154
+ declare const localStorageSessionStore: SessionStore;
155
+ /** A store that forgets the session when the page unloads. */
156
+ declare function memorySessionStore(initial?: CalimeroSession | null): SessionStore;
157
+ declare function getNodeUrl(): string | null;
158
+ declare function setNodeUrl(url: string): void;
159
+ declare function clearNodeUrl(): void;
160
+ /** The Calimero Cloud cluster (by name) chosen last, if a cluster was chosen. */
161
+ declare function getCluster(): string | null;
162
+ declare function setCluster(name: string): void;
163
+ declare function clearCluster(): void;
164
+ /** The app instance the page opened last (an app id, `SHA-256(app)`, hex). */
165
+ declare function getAppId(): string | null;
166
+ declare function setAppId(appId: string): void;
167
+ declare function clearAppId(): void;
168
+ /** Forget the node or cluster, the app and the session kept by the default store. */
169
+ declare function clearAllStorage(): void;
170
+
171
+ /** What `MeroProvider` takes, besides `children`. */
172
+ interface MeroProviderConfig extends PolicyOptions {
173
+ /**
174
+ * The node to talk to. Ignored when `servedByNode` (the page's own origin is
175
+ * the node). Without it (and without `cluster`) the provider uses the node
176
+ * or cluster kept from last time, or waits for `connectToNode` /
177
+ * `connectToCluster`.
178
+ */
179
+ nodeUrl?: string;
180
+ /**
181
+ * Other nodes of the same cluster, tried in order when a node answers
182
+ * `421 WRONG_NODE` or stays unavailable. Each is attested under the same
183
+ * policy first. Only with `nodeUrl`.
184
+ */
185
+ nodes?: string[];
186
+ /**
187
+ * A Calimero Cloud cluster by name (e.g. `eu-shared-1`), the alternative to
188
+ * `nodeUrl`: the client reads the cluster's nodes from the node directory
189
+ * (mero-js `CalimeroClient.connect`) and fails over between them. The
190
+ * directory only picks which nodes to try; each is attested under the
191
+ * policy first. Ignored when `servedByNode`; `nodeUrl` wins when both are
192
+ * given.
193
+ */
194
+ cluster?: string;
195
+ /** With `cluster`: try this zone's nodes first (e.g. `europe-west4-a`). */
196
+ zone?: string;
197
+ /** With `cluster`: the node directory to ask. Default mero-js `DEFAULT_DIRECTORY`. */
198
+ directory?: string;
199
+ /**
200
+ * Set when a node serves this page (`{label}.{apps-domain}`): the node is
201
+ * `window.location.origin`, and a passkey sign-in here opens a session bound
202
+ * to this app's package. `ConnectButton` then skips the node field.
203
+ */
204
+ servedByNode?: boolean;
205
+ /** The app instance hooks use when they are given none. */
206
+ appId?: string;
207
+ /** Where the session is kept. Default: `localStorageSessionStore`. */
208
+ sessionStore?: SessionStore;
209
+ /** The passkey prompt. Default: mero-js `browserPasskey()` (WebAuthn). */
210
+ passkey?: PasskeyProvider;
211
+ /** The `fetch` the client sends attestation and sealed envelopes with. */
212
+ fetch?: typeof fetch;
213
+ /** How calls and views retry a `503` or a dropped connection. */
214
+ retry?: CloudRetryOptions;
215
+ /**
216
+ * Use this client instead of building one (tests, or an app that needs a
217
+ * client configured beyond these props). Session reporting is then the
218
+ * caller's job.
219
+ */
220
+ client?: CalimeroClient;
221
+ /** Called with every failure a hook or a sign-in reports. */
222
+ onError?: (failure: Failure) => void;
223
+ }
224
+ /** What `useMero()` answers. */
98
225
  interface MeroContextValue {
99
226
  /**
100
- * The connected client, or null.
101
- *
102
- * Two shapes, because there are two ways to connect: a node login yields a
103
- * `MeroJs`, an account + relay connection yields a relay-transport
104
- * `MeroClient`. Both expose `rpc` as an `ExecuteTransport`, which is what a
105
- * generated ABI client depends on — so application logic is identical across
106
- * the two and needs no branch.
107
- *
108
- * The union is deliberately not flattened behind a cast. A relay client has
109
- * no `admin`, so code reaching for one should not typecheck as though it
110
- * were there; narrow with {@link MeroContextValue.isDelegated} first.
227
+ * The 1.0 client, or `null` until a node is known (and, for a cluster,
228
+ * until the directory has named its nodes).
111
229
  */
112
- mero: MeroJs | MeroClient | null;
113
- /** Whether the user is authenticated */
114
- isAuthenticated: boolean;
115
- /** Whether the connection is online */
116
- isOnline: boolean;
117
- /** The current node URL */
230
+ client: CalimeroClient | null;
231
+ /** @deprecated The same object as `client`; kept so `const { mero } = useMero()` still compiles. */
232
+ mero: CalimeroClient | null;
233
+ /** The node the client talks to (for a cluster, the node in use when it connected). */
118
234
  nodeUrl: string | null;
119
- /** The application ID */
120
- applicationId: string | null;
121
- /** The context ID (from auth flow) */
122
- contextId: string | null;
123
- /** The context identity / executor public key (from auth flow) */
124
- contextIdentity: string | null;
125
- /** Connect to a node URL and start auth flow */
235
+ /** The cluster the client was connected to by name, or `null`. */
236
+ cluster: string | null;
237
+ /** The node directory is being read for `cluster`. */
238
+ isConnecting: boolean;
239
+ /** Talk to another node (not when `servedByNode`). Signs out of the previous one locally. */
126
240
  connectToNode: (url: string) => void;
127
241
  /**
128
- * Adopt a delegated connection: an account, a device that account certified,
129
- * and a relay that writes on its behalf.
130
- *
131
- * Installs the relay client immediately — there is no redirect and no token to
132
- * wait for, because every request carries its own warrant.
133
- */
134
- connectWithAccount: (session: DelegatedAccountSession) => void;
135
- /**
136
- * Whether the connection is delegated (account + relay) rather than a node
137
- * login. True means `mero` is a relay-transport client, authenticated by the
138
- * account's device certificate: `rpc` writes under warrants, and `admin` and
139
- * `events` answer caller-scoped — this account's own contexts and namespaces,
140
- * and events only for contexts it is a member of.
242
+ * Talk to a Calimero Cloud cluster by name (not when `servedByNode`), with
243
+ * failover between its nodes. Signs out of the previous one locally.
141
244
  */
142
- isDelegated: boolean;
143
- /**
144
- * What this connection may do, so an app asks WHAT IS ALLOWED instead of
145
- * which transport it runs on. A node login can do everything; an account on
146
- * a relay can create contexts (delegated creation) but not namespaces or
147
- * invitations — those are a node's own operations today. A capability that
148
- * later becomes available to accounts turns true here with no app change.
149
- */
150
- can: MeroCapabilities;
151
- /**
152
- * The admin API to write against, whatever the session: the node's own admin
153
- * client on a node, the account admin (`createAccountAdmin`) on an account.
154
- * `null` until connected.
155
- */
156
- admin: _calimero_network_mero_js.AdminApiClient | null;
245
+ connectToCluster: (name: string) => void;
246
+ /** Forget the node or cluster, and the session. */
247
+ disconnect: () => void;
248
+ /** The passkey session, or `null`. */
249
+ session: CalimeroSession | null;
250
+ /** The signed-in account. */
251
+ accountId: string | null;
252
+ isAuthenticated: boolean;
253
+ /** A sign-in, sign-up or sign-out is under way. */
254
+ isLoading: boolean;
255
+ /** Sign in with an existing passkey. */
256
+ signIn: () => Promise<CalimeroSession | null>;
257
+ /** Create an account with a new passkey, and sign in. */
258
+ signUp: (name: string) => Promise<CalimeroSession | null>;
259
+ /** End this session (on the node too). */
260
+ signOut: () => Promise<void>;
261
+ /** End every session of the account, on every device. */
262
+ signOutEverywhere: () => Promise<void>;
263
+ /** @deprecated Use `signOut`. */
264
+ logout: () => void;
265
+ /** The app instance hooks default to. */
266
+ appId: string | null;
267
+ setAppId: (appId: string | null) => void;
268
+ /** The passkey prompt hooks use for confirmations. */
269
+ passkey: PasskeyProvider;
270
+ servedByNode: boolean;
271
+ /** Whether mock attestation is accepted (`merod local`). */
272
+ allowMock: boolean;
273
+ /** The last sign-in, connection or session failure. */
274
+ failure: Failure | null;
275
+ /** Hooks report what they caught here; a `LoginRequired` ends the session. */
276
+ reportError: (error: unknown) => void;
277
+ }
278
+
279
+ declare const MeroContext: React.Context<MeroContextValue | null>;
280
+ interface MeroProviderProps extends MeroProviderConfig {
281
+ children: React.ReactNode;
282
+ }
283
+ declare function MeroProvider({ children, nodeUrl: nodeUrlProp, nodes, cluster: clusterProp, zone, directory, policy, minReleaseVersion, allowMock, servedByNode, appId: appIdProp, sessionStore, passkey: passkeyProp, fetch: fetchProp, retry, client: injectedClient, onError, }: MeroProviderProps): react_jsx_runtime.JSX.Element;
284
+ /** The provider's client, session and actions. Throws outside a `MeroProvider`. */
285
+ declare function useMero(): MeroContextValue;
286
+
287
+ /** Options every action hook takes. */
288
+ interface MutationOptions {
157
289
  /**
158
- * The app's registry identity, as the provider was given it. An account
159
- * founding a namespace names this application for it, since a namespace
160
- * founded through a relay starts with none.
290
+ * Rethrow a failure from the action after recording it. By default an action
291
+ * resolves `null` when it fails, which is enough for a button; set this when
292
+ * the caller branches on the outcome.
161
293
  */
162
- app: {
163
- packageName?: string;
164
- packageVersion?: string;
165
- registryUrl?: string;
166
- };
167
- /** The cloud an account asks for routing; the hosted one when unset. */
168
- cloudBaseUrl?: string;
169
- /** Logout and clear tokens */
170
- logout: () => void;
171
- /** Loading state */
172
- isLoading: boolean;
294
+ throwOnError?: boolean;
295
+ }
296
+ interface AsyncState {
297
+ loading: boolean;
298
+ /** The error as the client threw it: `instanceof AppError` etc. still work. */
299
+ error: Error | null;
300
+ /** {@link describeError}'s reading of `error`. */
301
+ failure: Failure | null;
302
+ }
303
+ declare class NotConnectedError extends Error {
304
+ constructor(what?: string);
305
+ }
306
+ declare class NoAppError extends Error {
307
+ constructor();
308
+ }
309
+ interface ResourceState<T> extends AsyncState {
310
+ data: T;
311
+ refetch: () => Promise<void>;
312
+ }
313
+
314
+ interface CallOptions {
315
+ /** Your own idempotency key (kept 24 hours by the node). */
316
+ idempotencyKey?: string;
317
+ /** Answer a `412 CONFIRM_REQUIRED` with the passkey. */
318
+ confirm?: boolean;
319
+ }
320
+ interface ViewOptions {
321
+ /** Read from this node's replica without asking the leader. */
322
+ stale?: boolean;
323
+ /** With `stale`: wait until the replica has applied this log index (a call's `index`). */
324
+ minIndex?: number;
173
325
  }
174
326
  /**
175
- * MeroProvider configuration
327
+ * The app the page works on, with its record and bound `call` / `view`.
328
+ *
329
+ * `call` and `view` throw the client's typed errors as they are; for loading
330
+ * and error state around a call, use {@link useExecute}.
176
331
  */
177
- interface MeroProviderConfig {
178
- /** Application mode */
179
- mode: AppMode;
180
- /** Package name (for registry-based apps) */
181
- packageName?: string;
182
- /** Package version (optional, defaults to latest) */
183
- packageVersion?: string;
184
- /** Registry URL (optional) */
185
- registryUrl?: string;
186
- /**
187
- * The cloud an account asks which relay serves a namespace or an account.
188
- * Unset is the hosted cloud, which is right for every deployed app; this is
189
- * for a local or staging setup whose namespaces the hosted cloud never saw.
190
- */
191
- cloudBaseUrl?: string;
192
- /** Request timeout in milliseconds */
193
- timeoutMs?: number;
194
- /**
195
- * Origins the OAuth callback is allowed to authenticate against. Defends
196
- * against a malicious `node_url` in the callback URL (token exfiltration):
197
- * the node login was initiated with is always trusted, and this allowlist
198
- * additionally permits direct-callback entry to known nodes. When neither is
199
- * available (no initiated node and no allowlist) a callback node_url is
200
- * rejected and a security error is logged.
201
- */
202
- allowedNodeUrls?: string[];
203
- /**
204
- * Token store for access/refresh tokens. Defaults to a localStorage-backed
205
- * store that persists across reloads.
206
- *
207
- * SECURITY: localStorage tokens — including the refresh token — are readable
208
- * by any script on the page, so an XSS bug can exfiltrate them. For sensitive
209
- * deployments pass a `MemoryTokenStore` (session-only) or a store backed by an
210
- * HttpOnly cookie set by your auth service.
211
- */
212
- tokenStore?: TokenStore;
332
+ declare function useApp(appId?: string | null): {
333
+ appId: string | null;
334
+ app: Record<string, unknown> | null;
335
+ loading: boolean;
336
+ error: Error | null;
337
+ failure: Failure | null;
338
+ refetch: () => Promise<void>;
339
+ call: (method: string, args?: unknown, options?: CallOptions) => Promise<CallResult>;
340
+ view: (method: string, args?: unknown, options?: ViewOptions) => Promise<ViewResult>;
341
+ };
342
+ /**
343
+ * Calls with loading and error state. Was `useExecute(contextId, executorId)`:
344
+ * there is no executor any more (the caller is the signed-in account), and the
345
+ * context is now an app id.
346
+ *
347
+ * `execute` resolves the method's result, `call` the whole `CallResult`
348
+ * (`index`, `events`), and both resolve `null` on failure unless
349
+ * `throwOnError`.
350
+ */
351
+ declare function useExecute(appId?: string | null, options?: MutationOptions): {
352
+ execute: <T = unknown>(method: string, args?: unknown, callOptions?: CallOptions) => Promise<T | null>;
353
+ call: (method: string, args?: unknown, callOptions?: CallOptions) => Promise<CallResult | null>;
354
+ loading: boolean;
355
+ error: Error | null;
356
+ failure: Failure | null;
357
+ reset: () => void;
358
+ };
359
+ interface UseViewOptions extends ViewOptions {
360
+ appId?: string | null;
361
+ /** Do not read while false. Default true. */
362
+ enabled?: boolean;
213
363
  }
214
- /** See {@link MeroContextValue.can}. */
215
- interface MeroCapabilities {
216
- /** Found a namespace. */
217
- readonly createNamespace: boolean;
218
- /** Create a context inside a namespace this connection belongs to. */
219
- readonly createContext: boolean;
220
- /** Mint an invitation to a namespace. */
221
- readonly invite: boolean;
222
- /** Upgrade a group's application. A node's only: a relay carries just the first choice. */
223
- readonly upgrade: boolean;
364
+ interface UseViewResult<T> extends ResourceState<T | undefined> {
365
+ /** The log index the answer reflects. */
366
+ index: number | null;
224
367
  }
368
+ /**
369
+ * A view's answer, read again when the method or its arguments change. Pair it
370
+ * with `useSubscription` and call `refetch` on the events that matter.
371
+ */
372
+ declare function useView<T = unknown>(method: string, args?: unknown, options?: UseViewOptions): UseViewResult<T>;
373
+ /** The app's ABI (methods, events, errors), as the node reports it. */
374
+ declare function useAppAbi(appId?: string | null): ResourceState<Record<string, unknown> | null>;
225
375
 
226
- declare const MeroContext: React__default.Context<MeroContextValue | null>;
227
376
  /**
228
- * Permission grants requested for the client token at login.
377
+ * Live events (`GET /apps/{app}/events`, server-sent events over the sealed
378
+ * channel).
229
379
  *
230
- * Cores since 0.11.0-rc.9 default-deny admin-api routes the token holds no
231
- * scope for; cores >=0.11.0-rc.11 map the governance/blob/alias routes to the
232
- * client-grantable `namespace` / `group` / `blob` / `context:alias`
233
- * permissions, so app tokens must request them here or every workspace,
234
- * group, blob and context-alias call 403s.
380
+ * Each subscribed app gets one stream with an `AbortController`; unmounting,
381
+ * or changing the app ids, aborts it (mero-js ends an aborted stream within a
382
+ * few hundred milliseconds, mero-js#312). A stream that ends or fails by itself
383
+ * reopens with backoff, from the last event seen: the node numbers events
384
+ * `index:seq`, and anything at or before the last one delivered is skipped, so
385
+ * a reconnect neither drops nor repeats what this page already saw.
386
+ */
387
+
388
+ /** One event as `useSubscription` delivers it. */
389
+ interface AppEvent {
390
+ /** The app it came from. */
391
+ appId: string;
392
+ /** The node's id for it, `index:seq`. */
393
+ id: string;
394
+ /** The log index of the call that emitted it. */
395
+ index: number;
396
+ /** Its position among that call's events. */
397
+ seq: number;
398
+ /** The event's name (`ItemAdded`, ...). */
399
+ kind: string;
400
+ /** Its payload, parsed from JSON. */
401
+ data: unknown;
402
+ }
403
+ /** @deprecated The 0.x name; events are {@link AppEvent}s now. */
404
+ type SubscriptionEventData = AppEvent;
405
+ interface SubscriptionOptions {
406
+ /**
407
+ * Where to start: a log index to replay from (`0` is the whole history), or
408
+ * `'live'` (default) for events after the stream opens.
409
+ */
410
+ from?: number | 'live';
411
+ /** Do not subscribe while false. Default true. */
412
+ enabled?: boolean;
413
+ /** Called when a stream fails; it reopens unless the session ended or the app is gone. */
414
+ onError?: (error: unknown, appId: string) => void;
415
+ /** Called each time a stream (re)opens. Refetch views here to cover a gap. */
416
+ onOpen?: (appId: string) => void;
417
+ /** Longest wait between reconnects. Default 30 s. */
418
+ maxBackoffMs?: number;
419
+ }
420
+ interface Follow {
421
+ client: CalimeroClient;
422
+ appId: string;
423
+ from: number | 'live';
424
+ signal: AbortSignal;
425
+ maxBackoffMs: number;
426
+ deliver: (event: AppEvent) => void;
427
+ opened: (appId: string) => void;
428
+ failed: (error: unknown, appId: string) => void;
429
+ sessionEnded: (error: unknown) => void;
430
+ }
431
+ /** Follow one app's events until `signal` aborts. Exported for tests. */
432
+ declare function followEvents(f: Follow): Promise<void>;
433
+ /**
434
+ * Call `callback` for every event of the given app(s). Pass `null` (or an
435
+ * empty list) to subscribe to nothing. Without app ids it follows the
436
+ * provider's `appId`.
437
+ *
438
+ * Was `useSubscription(contextIds, callback)`: same shape, app ids in place of
439
+ * context ids. Group subscriptions are gone (teams emit no app events).
440
+ */
441
+ declare function useSubscription(appIds: string | string[] | null | undefined, callback: (event: AppEvent) => void, options?: SubscriptionOptions): void;
442
+
443
+ /** The app instances this account can see. Was `useContexts`. */
444
+ declare function useApps(filter?: {
445
+ package?: string;
446
+ bundle?: string;
447
+ }): ResourceState<AppInfo[]>;
448
+ interface CreateAppInput {
449
+ name: string;
450
+ /** A bundle hash, or a package release (`{ package, version? }`). */
451
+ bundle: string | {
452
+ package: string;
453
+ version?: string;
454
+ service?: string;
455
+ };
456
+ /** The organization that owns it (default: the account). */
457
+ org?: string;
458
+ access?: Record<string, unknown>;
459
+ /** Methods that need the caller's passkey on every call. */
460
+ confirmMethods?: string[];
461
+ initArgs?: unknown;
462
+ }
463
+ /** Create an app instance. Was `useCreateContext`. Resolves its app id. */
464
+ declare function useCreateApp(options?: MutationOptions): {
465
+ create: (input: CreateAppInput) => Promise<string | null>;
466
+ loading: boolean;
467
+ error: Error | null;
468
+ failure: Failure | null;
469
+ };
470
+ /** Delete an app instance. Was `useDeleteContext`. */
471
+ declare function useDeleteApp(options?: MutationOptions): {
472
+ deleteApp: (appId: string) => Promise<boolean | null>;
473
+ loading: boolean;
474
+ error: Error | null;
475
+ failure: Failure | null;
476
+ };
477
+ /** Set an app instance's metadata. Was `useSetContextMetadata`. */
478
+ declare function useSetAppMetadata(options?: MutationOptions): {
479
+ setMetadata: (appId: string, metadata: unknown) => Promise<boolean | null>;
480
+ loading: boolean;
481
+ error: Error | null;
482
+ failure: Failure | null;
483
+ };
484
+ interface UpgradeTarget {
485
+ version?: string;
486
+ package?: string;
487
+ service?: string;
488
+ bundle?: string;
489
+ migrate?: string;
490
+ }
491
+ /**
492
+ * Upgrade an app instance. Was `useUpgradeGroup`. Asks for the passkey (the
493
+ * node confirms an upgrade). A session opened on an app's own frontend cannot
494
+ * upgrade (`403`): send the person to the consent page instead
495
+ * (`useConsent` with `upgradeConsent`).
496
+ */
497
+ declare function useUpgradeApp(appId?: string | null, options?: MutationOptions): {
498
+ upgrade: (target: UpgradeTarget) => Promise<{
499
+ index: number;
500
+ status: string;
501
+ error: unknown;
502
+ } | null>;
503
+ loading: boolean;
504
+ error: Error | null;
505
+ failure: Failure | null;
506
+ };
507
+ /** The installed package releases. */
508
+ declare function usePackages(): ResourceState<_calimero_network_mero_js.PackageInfo[]>;
509
+
510
+ type OrgRole = 'guest' | 'member' | 'admin' | 'owner';
511
+ type TeamJoin = 'everyone' | 'invite';
512
+ type TeamRole = 'lead' | 'member' | 'readOnly';
513
+ /** An organization: members, teams, metadata, release approvers. Was `useNamespace`. */
514
+ declare function useOrg(orgId?: string | null): ResourceState<OrgInfo | null>;
515
+ /** Create an organization; resolves its id. Was `useCreateNamespace`. */
516
+ declare function useCreateOrg(options?: MutationOptions): {
517
+ loading: boolean;
518
+ error: Error | null;
519
+ failure: Failure | null;
520
+ create: (name: string) => Promise<string | null>;
521
+ };
522
+ /** Delete an organization (asks for the passkey). Was `useDeleteNamespace`. */
523
+ declare function useDeleteOrg(options?: MutationOptions): {
524
+ loading: boolean;
525
+ error: Error | null;
526
+ failure: Failure | null;
527
+ deleteOrg: (orgId: string) => Promise<boolean | null>;
528
+ };
529
+ /**
530
+ * Add a member or change their role (asks for the passkey). Was
531
+ * `useUpdateMemberRole` and, at the org level, `useAddGroupMembers`.
532
+ */
533
+ declare function useSetMember(options?: MutationOptions): {
534
+ loading: boolean;
535
+ error: Error | null;
536
+ failure: Failure | null;
537
+ setMember: (orgId: string, account: string, role: OrgRole) => Promise<boolean | null>;
538
+ };
539
+ /**
540
+ * Remove a member from an organization, or leave it (`account` your own).
541
+ * Asks for the passkey.
542
+ */
543
+ declare function useRemoveMember(options?: MutationOptions): {
544
+ loading: boolean;
545
+ error: Error | null;
546
+ failure: Failure | null;
547
+ removeMember: (orgId: string, account: string) => Promise<Record<string, unknown> | null>;
548
+ };
549
+ /** Set an organization's metadata. Was `useSetGroupMetadata` on a namespace root. */
550
+ declare function useSetOrgMetadata(options?: MutationOptions): {
551
+ loading: boolean;
552
+ error: Error | null;
553
+ failure: Failure | null;
554
+ setMetadata: (orgId: string, metadata: unknown) => Promise<boolean | null>;
555
+ };
556
+ /** Set a member's metadata (a display name, say). Same name as before; now per org. */
557
+ declare function useSetMemberMetadata(options?: MutationOptions): {
558
+ loading: boolean;
559
+ error: Error | null;
560
+ failure: Failure | null;
561
+ setMetadata: (orgId: string, account: string, metadata: unknown) => Promise<boolean | null>;
562
+ };
563
+ /**
564
+ * Set capability bits (`ORG_CAPABILITIES`) for an account or a team, or the
565
+ * org's default with neither. Asks for the passkey. Was
566
+ * `useSetDefaultCapabilities`.
567
+ */
568
+ declare function useSetCapabilities(options?: MutationOptions): {
569
+ loading: boolean;
570
+ error: Error | null;
571
+ failure: Failure | null;
572
+ setCapabilities: (orgId: string, capabilities: number, at?: {
573
+ account?: string;
574
+ team?: string;
575
+ }) => Promise<boolean | null>;
576
+ };
577
+ /** A team of an organization. Was `useGroupInfo`. */
578
+ declare function useTeam(orgId?: string | null, teamId?: string | null): ResourceState<Record<string, unknown> | null>;
579
+ interface CreateTeamInput {
580
+ orgId: string;
581
+ name: string;
582
+ join?: TeamJoin;
583
+ /** The team it sits under. */
584
+ parent?: string;
585
+ }
586
+ /** Create a team; resolves its id. Was `useCreateGroupInNamespace`. */
587
+ declare function useCreateTeam(options?: MutationOptions): {
588
+ loading: boolean;
589
+ error: Error | null;
590
+ failure: Failure | null;
591
+ create: ({ orgId, name, join, parent }: CreateTeamInput) => Promise<string | null>;
592
+ };
593
+ interface TeamUpdate {
594
+ name?: string;
595
+ join?: TeamJoin;
596
+ /** Move it under another team; `null` makes it top-level. */
597
+ parent?: string | null;
598
+ metadata?: unknown;
599
+ }
600
+ /**
601
+ * Rename, re-parent, change who may join, or set metadata. Was
602
+ * `useSetGroupMetadata`, `useReparentGroup` and `useSetSubgroupVisibility`.
603
+ */
604
+ declare function useUpdateTeam(options?: MutationOptions): {
605
+ loading: boolean;
606
+ error: Error | null;
607
+ failure: Failure | null;
608
+ update: (orgId: string, teamId: string, change: TeamUpdate) => Promise<boolean | null>;
609
+ };
610
+ /** Delete a team. Was `useDeleteGroup`. */
611
+ declare function useDeleteTeam(options?: MutationOptions): {
612
+ loading: boolean;
613
+ error: Error | null;
614
+ failure: Failure | null;
615
+ deleteTeam: (orgId: string, teamId: string) => Promise<boolean | null>;
616
+ };
617
+ /**
618
+ * Add an org member to a team, or change their row (asks for the passkey).
619
+ * Was `useAddGroupMembers`.
620
+ */
621
+ declare function useSetTeamMember(options?: MutationOptions): {
622
+ loading: boolean;
623
+ error: Error | null;
624
+ failure: Failure | null;
625
+ setTeamMember: (orgId: string, teamId: string, account: string, row?: {
626
+ role?: TeamRole;
627
+ lead?: boolean;
628
+ capabilities?: number;
629
+ }) => Promise<boolean | null>;
630
+ };
631
+ /** Remove someone from a team (asks for the passkey). Was `useRemoveGroupMembers`. */
632
+ declare function useRemoveTeamMember(options?: MutationOptions): {
633
+ loading: boolean;
634
+ error: Error | null;
635
+ failure: Failure | null;
636
+ removeTeamMember: (orgId: string, teamId: string, account: string) => Promise<boolean | null>;
637
+ };
638
+
639
+ /**
640
+ * Invitations: an org admin mints a token (`POST /orgs/{org}/invites`), the
641
+ * invitee redeems it while signed in (`POST /invites/{token}/redeem`) and
642
+ * becomes a member of the org (and of the teams the invite names).
235
643
  *
236
- * `context:list` is included even in single-context mode because every app
237
- * calls GET /admin-api/contexts/:id/identities-owned right after login, which
238
- * maps to a `context:list` requirement.
644
+ * There is no relay, no node to join and no sync to wait for any more: the
645
+ * cluster holds the membership, so the redeem's answer is the whole join.
239
646
  *
240
- * `context:subscribe` is what `/sse`, `/sse/subscription` and `/ws` require
241
- * (core's `PermissionValidator`, `validator.rs`, maps all three to
242
- * `Context(Subscribe(Global))`). Without it every event stream an app opens is
243
- * refused `403` + `X-Auth-Error: permission_denied`, so the app renders, reads
244
- * and writes, and simply never receives a live update. Only `AppMode.Admin`
245
- * escaped, because `admin` covers every route.
647
+ * Links carry the token in the URL fragment (`#invite=…`), which browsers do
648
+ * not send to servers, so it stays out of access logs.
649
+ */
650
+
651
+ /** A link to `base` (default: this page) that carries an invite token. */
652
+ declare function inviteLink(token: string, base?: string): string;
653
+ /** The invite token in a URL's fragment or query, or `null`. */
654
+ declare function readInviteToken(href: string): string | null;
655
+ interface CreateInviteInput {
656
+ orgId: string;
657
+ role?: Exclude<OrgRole, 'owner'>;
658
+ /** Teams the invitee joins too. */
659
+ teams?: string[];
660
+ /** How long the token lives. */
661
+ ttlSecs?: number;
662
+ /** How many times it can be redeemed. */
663
+ uses?: number;
664
+ /** The page the link opens (default: this one). */
665
+ linkBase?: string;
666
+ }
667
+ /**
668
+ * Mint an invitation (asks for the passkey). Was `useCreateNamespaceInvitation`.
669
+ * Resolves `{ token, link }`. Redeeming it needs no passkey.
670
+ */
671
+ declare function useCreateInvite(options?: MutationOptions): {
672
+ loading: boolean;
673
+ error: Error | null;
674
+ failure: Failure | null;
675
+ create: ({ orgId, role, teams, ttlSecs, uses, linkBase }: CreateInviteInput) => Promise<{
676
+ token: string;
677
+ link: string;
678
+ } | null>;
679
+ };
680
+ /** Redeem a token. Was `useRedeemInvitation` / `useJoinNamespace` / `useJoinGroup`. */
681
+ declare function useRedeemInvite(options?: MutationOptions): {
682
+ loading: boolean;
683
+ error: Error | null;
684
+ failure: Failure | null;
685
+ redeem: (token: string) => Promise<Record<string, unknown> | null>;
686
+ };
687
+ type InviteRedemptionStatus = 'idle' | 'waiting-for-sign-in' | 'redeeming' | 'redeemed' | 'failed';
688
+ interface InviteRedemption {
689
+ /** The token this page was opened with (or kept from before a sign-in). */
690
+ token: string | null;
691
+ status: InviteRedemptionStatus;
692
+ /** What the node answered on a redeem. */
693
+ result: Record<string, unknown> | null;
694
+ failure: Failure | null;
695
+ /** Redeem now (also after a failure). */
696
+ redeem: () => Promise<void>;
697
+ /** Forget the token. */
698
+ dismiss: () => void;
699
+ }
700
+ /**
701
+ * The invite link flow in one hook: read the token from the address bar (and
702
+ * take it out of it), keep it across the sign-in, redeem it once signed in.
703
+ * Same name as before; there is no relay or join-sync step any more.
704
+ */
705
+ declare function useInviteRedemption({ autoRedeem }?: {
706
+ autoRedeem?: boolean;
707
+ }): InviteRedemption;
708
+
709
+ interface WaitOptions {
710
+ intervalMs?: number;
711
+ /** Stop polling (the answer is then still `pending`). */
712
+ signal?: AbortSignal;
713
+ }
714
+ /**
715
+ * Request consent, open the page, wait for the decision.
716
+ *
717
+ * - `open(request)`: navigate this tab to the page (the default), or pass
718
+ * `navigate` to open it some other way (`window.open`, the system browser).
719
+ * Pass `{ navigate, confirm }` to show the person the confirmation `code`
720
+ * before the page opens: `confirm` runs with the node's answer (also kept in
721
+ * `started` and `code` by then), and answering `false` keeps the page shut.
722
+ * A code that does not match the request id throws `CONSENT_CODE_MISMATCH`.
723
+ * - `code`: the confirmation code (`XXX-XXX`) the consent page shows for the
724
+ * request under way. Show it next to the link; the page the person lands on
725
+ * should show the same one. `null` before a request, or from a node too old
726
+ * to send one.
727
+ * - `returned`: what the page put on this URL when it sent the person back
728
+ * (`?request_id=…&result=…`). A hint only: confirm it with `check`.
729
+ */
730
+ declare function useConsent(options?: MutationOptions): {
731
+ loading: boolean;
732
+ error: Error | null;
733
+ failure: Failure | null;
734
+ request: (req: ConsentRequest) => Promise<ConsentStarted | null>;
735
+ open: (req: ConsentRequest, how?: ((url: string) => void) | OpenConsentOptions) => Promise<ConsentStarted | null>;
736
+ check: (requestId: string) => Promise<ConsentResult | null>;
737
+ wait: (requestId: string, waitOptions?: WaitOptions) => Promise<ConsentResult | null>;
738
+ cancel: () => void | undefined;
739
+ started: ConsentStarted | null;
740
+ code: string | null;
741
+ result: ConsentResult | null;
742
+ returned: {
743
+ requestId: string;
744
+ result: "approved" | "declined";
745
+ } | null;
746
+ ready: boolean;
747
+ };
748
+
749
+ interface BlobHookOptions {
750
+ appId?: string | null;
751
+ }
752
+ interface UseBlobUrlOptions extends BlobHookOptions {
753
+ /** The object URL's type (default: none). */
754
+ mimeType?: string;
755
+ }
756
+ /** Upload bytes, a `Blob` or a `File`; resolves `{ blobId, id, size }`. */
757
+ declare function useUploadBlob(options?: BlobHookOptions & MutationOptions): {
758
+ loading: boolean;
759
+ error: Error | null;
760
+ failure: Failure | null;
761
+ upload: (data: Uint8Array | Blob | ArrayBuffer) => Promise<{
762
+ blobId: string;
763
+ id: string;
764
+ size: number;
765
+ } | null>;
766
+ };
767
+ /** A blob's size and ids. */
768
+ declare function useBlobInfo(blobId?: string | null, options?: BlobHookOptions): ResourceState<BlobInfo | null>;
769
+ /** The app's blobs. */
770
+ declare function useBlobs(appId?: string | null): ResourceState<BlobInfo[]>;
771
+ /**
772
+ * An object URL for a blob, for an `<img>` or a download link. The bytes come
773
+ * over the sealed channel, so a plain URL to the node would not work. Revoked
774
+ * when the blob changes or the component unmounts.
775
+ */
776
+ declare function useBlobUrl(blobId?: string | null, options?: UseBlobUrlOptions): {
777
+ url: string | null;
778
+ loading: boolean;
779
+ error: Error | null;
780
+ failure: Failure | null;
781
+ refetch: () => Promise<void>;
782
+ };
783
+ /** Delete a blob. */
784
+ declare function useDeleteBlob(options?: BlobHookOptions & MutationOptions): {
785
+ loading: boolean;
786
+ error: Error | null;
787
+ failure: Failure | null;
788
+ deleteBlob: (blobId: string) => Promise<boolean | null>;
789
+ };
790
+
791
+ /**
792
+ * Presence (`/apps/{app}/presence`): who is in an app now, and a small state
793
+ * each of them shares (a cursor, "typing"). In memory on every node, never
794
+ * logged.
246
795
  *
247
- * MEASURED against merod 0.11.0-rc.41 (build 88e323b): a client key minted with
248
- * the MultiContext list below minus `context:subscribe` gets `403` on
249
- * `GET /sse`; the same list with it gets `200`.
796
+ * Each device publishes `(seq, state)`; the newest `seq` wins, and an entry
797
+ * the device does not repeat within 7 seconds is gone. The hook heartbeats
798
+ * every 5 seconds and retracts (`state: null`) on unmount. The stream answers
799
+ * a `snapshot` first, then a `presence` event per change.
250
800
  *
251
- * `context:delete` is what `DELETE /admin-api/contexts/:id` requires
252
- * (`validator.rs`). An app that may create contexts may delete them, so
253
- * `useDeleteContext` works on a node instead of answering 403.
801
+ * Same name as before (`useEphemeral`); it now takes an app id where it took a
802
+ * context id, and keys peers by account.
803
+ */
804
+ /** How a state goes to bytes and back (at most 4 KiB). Default: JSON. */
805
+ interface Codec<T> {
806
+ encode(value: T): Uint8Array;
807
+ decode(bytes: Uint8Array): T;
808
+ }
809
+ declare const jsonCodec: Codec<any>;
810
+ /** One device present in the app. */
811
+ interface EphemeralEntry<T> {
812
+ account: string;
813
+ device: string;
814
+ state: T;
815
+ }
816
+ interface UseEphemeralOptions<T> {
817
+ codec?: Codec<T>;
818
+ /** The state to start from for the first `setPresence`. */
819
+ initial?: T;
820
+ /** Least time between publishes; the last value wins. Default 100 ms. */
821
+ throttleMs?: number;
822
+ /** Include this account's own entries in `peers`. Default false. */
823
+ includeSelf?: boolean;
824
+ /** Publish and follow only while true. Default true. */
825
+ enabled?: boolean;
826
+ }
827
+ interface UseEphemeralResult<T> {
828
+ /** Account → its newest state (one entry per account; see `entries` for devices). */
829
+ peers: Map<string, T>;
830
+ /** Every device present. */
831
+ entries: EphemeralEntry<T>[];
832
+ /** Merge into this device's state and publish it. */
833
+ setPresence: (partial: Partial<T>) => void;
834
+ /** Retract this device's presence now (it also happens on unmount). */
835
+ leave: () => void;
836
+ error: Error | null;
837
+ }
838
+ declare function useEphemeral<T extends object = Record<string, unknown>>(appId: string | null | undefined, options?: UseEphemeralOptions<T>): UseEphemeralResult<T>;
839
+
840
+ /** `GET /auth/me`: the account, its passkeys, its orgs. */
841
+ declare function useAccount(): {
842
+ data: Record<string, unknown> | null;
843
+ refetch: () => Promise<void>;
844
+ loading: boolean;
845
+ error: Error | null;
846
+ failure: Failure | null;
847
+ accountId: string | null;
848
+ };
849
+ /**
850
+ * Add a passkey (another device), remove one, or name one.
254
851
  *
255
- * Public: whatever mints a token for a mero-react app on its behalf (the
256
- * desktop's per-app key, admin-dashboard's, auth-frontend's allowlist) should
257
- * test against this rather than a hand copy. Three copies went without
258
- * `context:delete` and every app's context delete answered 403.
852
+ * Adding and removing are approved with a passkey the account already has
853
+ * (the node answers `412 CONFIRM_REQUIRED`): by default the provider's
854
+ * `passkey`, which in a browser lets the person pick any passkey they hold.
855
+ * `add({ passkey, approver })` takes other providers when the new passkey and
856
+ * the approving one come from different places (a security key next to the
857
+ * platform one).
259
858
  */
260
- declare function getPermissionsForMode(mode: AppMode): string[];
261
- interface MeroProviderProps extends MeroProviderConfig {
262
- children: React__default.ReactNode;
859
+ declare function usePasskeys(options?: MutationOptions): {
860
+ loading: boolean;
861
+ error: Error | null;
862
+ failure: Failure | null;
863
+ add: (providers?: {
864
+ passkey?: PasskeyProvider;
865
+ approver?: PasskeyProvider;
866
+ }) => Promise<string | null>;
867
+ remove: (credentialId: string) => Promise<boolean | null>;
868
+ label: (credentialId: string, name: string) => Promise<boolean | null>;
869
+ };
870
+ /** What `useApiKeys().create` takes. */
871
+ interface CreateApiKeyInput {
872
+ label?: string;
873
+ /** Apps the key may call (all of the account's when left out). */
874
+ apps?: string[];
875
+ /** Methods the key may call. */
876
+ methods?: string[];
877
+ readOnly?: boolean;
878
+ /** Let the key make calls that need a confirmation. */
879
+ allowConfirm?: boolean;
880
+ ttlSecs?: number;
263
881
  }
264
- declare function MeroProvider({ children, mode, packageName, packageVersion, registryUrl, cloudBaseUrl, timeoutMs, allowedNodeUrls, tokenStore: tokenStoreProp, }: MeroProviderProps): react_jsx_runtime.JSX.Element;
265
- declare function useMero(): MeroContextValue;
882
+ /**
883
+ * The account's API keys, for agents and servers: list them, create one
884
+ * (approved with the passkey; needs a passkey session, not an API key) and
885
+ * revoke one. `create` resolves `{ keyId, key }`, and the key is shown once.
886
+ */
887
+ declare function useApiKeys(options?: MutationOptions): {
888
+ loading: boolean;
889
+ error: Error | null;
890
+ failure: Failure | null;
891
+ keys: Record<string, unknown>[];
892
+ keysLoading: boolean;
893
+ keysFailure: Failure | null;
894
+ refetch: () => Promise<void>;
895
+ create: (input?: CreateApiKeyInput) => Promise<{
896
+ keyId: string;
897
+ key: string;
898
+ } | null>;
899
+ revoke: (keyId: string) => Promise<boolean | null>;
900
+ };
266
901
 
267
902
  /**
268
903
  * Theme tokens for mero-react components.
@@ -339,1518 +974,48 @@ declare function themeToCssVars(theme: ResolvedMeroTheme): CSSProperties;
339
974
  */
340
975
  declare function cssVar(theme: ResolvedMeroTheme, key: keyof MeroTheme): string;
341
976
 
977
+ type LoginModalTab = 'sign-in' | 'sign-up';
978
+ interface LoginModalProps {
979
+ isOpen: boolean;
980
+ onClose: () => void;
981
+ /** Called once a session is open. */
982
+ onSignedIn?: () => void;
983
+ /** Which form to open on. Default `sign-in`. */
984
+ initialTab?: LoginModalTab;
985
+ /** Offer account creation. Default true. */
986
+ allowSignUp?: boolean;
987
+ /** The app's name, shown above the title. */
988
+ appName?: string;
989
+ theme?: MeroTheme;
990
+ }
991
+ declare function LoginModal({ isOpen, onClose, onSignedIn, initialTab, allowSignUp, appName, theme, }: LoginModalProps): react_jsx_runtime.JSX.Element | null;
992
+
342
993
  interface ConnectButtonProps {
343
- /**
344
- * Connection behaviour. `Custom` (object form) connects straight to the
345
- * given URL, skipping the modal; every other value opens the LoginModal,
346
- * which always shows node discovery + manual URL entry.
347
- */
348
- connectionType?: ConnectionType | CustomConnectionConfig;
349
- /** Custom class name */
350
994
  className?: string;
351
- /** Custom styles */
352
- style?: React__default.CSSProperties;
353
- /** Theme overrides — accepts any subset of `MeroTheme` tokens */
995
+ style?: React.CSSProperties;
354
996
  theme?: MeroTheme;
355
- /**
356
- * Render only the Calimero logo, no text. Produces a square 40×40 icon
357
- * button. The label is still announced to screen readers via `aria-label`.
358
- * Default: false.
359
- */
997
+ /** Only the logo (a 40×40 icon button); the label stays for screen readers. */
360
998
  logoOnly?: boolean;
361
- /**
362
- * Override the default labels per state. A bare string is shorthand for
363
- * `{ connect: '<string>' }`. The connected and reconnecting states keep
364
- * their defaults unless explicitly overridden.
365
- */
999
+ /** Labels; a string is shorthand for `{ connect }`. */
366
1000
  label?: string | {
367
1001
  connect?: string;
368
1002
  connected?: string;
369
- reconnecting?: string;
370
- };
371
- /**
372
- * Offer the **Cloud** tab — sign in with a Calimero account — next to the
373
- * node dialog. Default true in a browser, false inside a Calimero Desktop
374
- * window (already bound to the desktop's node; see `isDesktopWindow`). With
375
- * false the modal has no tabs, and this button reads no enrolment callback,
376
- * leaving it to whichever component does.
377
- */
378
- cloud?: boolean;
379
- /**
380
- * Overrides for the account path, for local development only.
381
- */
382
- accountDefaults?: {
383
- /**
384
- * Point enrolment at a wallet other than the hosted one — for working ON
385
- * the wallet, e.g. one served from `localhost:8090`.
386
- */
387
- walletUrl?: string;
388
1003
  };
1004
+ /** The app's name, shown in the sign-in dialog. */
1005
+ appName?: string;
1006
+ /** Offer account creation in the dialog. Default true. */
1007
+ allowSignUp?: boolean;
1008
+ /** Which form the dialog opens on. */
1009
+ initialTab?: LoginModalTab;
389
1010
  }
390
- /**
391
- * ConnectButton - Displays connection status and handles login/logout
392
- */
393
- declare function ConnectButton({ connectionType, className, style, theme, logoOnly, label, cloud: cloudProp, accountDefaults, }: ConnectButtonProps): react_jsx_runtime.JSX.Element;
1011
+ /** `abcdef…123456`: enough of an account id to recognise it. */
1012
+ declare function shortAccount(account: string): string;
1013
+ declare function ConnectButton({ className, style, theme, logoOnly, label, appName, allowSignUp, initialTab, }: ConnectButtonProps): react_jsx_runtime.JSX.Element;
394
1014
 
395
- interface ConnectButtonAccountProps {
396
- className?: string;
397
- style?: React__default.CSSProperties;
398
- theme?: MeroTheme;
399
- /**
400
- * Overrides for local development. An app in production passes none of this,
401
- * and the pane asks the person for nothing at all.
402
- *
403
- * Nothing here is a value an end user could know, which is precisely why none
404
- * of it is a form field any more:
405
- *
406
- * - the **relay** is discovered — the certificate the enrolment returns proves
407
- * the cloud's account→relay lookup, so there is nothing to type and a prefill
408
- * would only be a staler second source of truth;
409
- * - the **context** is chosen after connecting, from the account's own contexts,
410
- * which `admin.getContexts()` answers caller-scoped through the request proof.
411
- */
412
- /**
413
- * Show the "I have an account" path. Default true in a browser, false inside
414
- * a Calimero Desktop window, which is already bound to the desktop's node
415
- * (see `isDesktopWindow`).
416
- */
417
- cloud?: boolean;
418
- defaults?: {
419
- /**
420
- * Point enrolment at a wallet other than the hosted one.
421
- *
422
- * Exists for working ON the wallet: a wallet served from `localhost:8090`
423
- * cannot be reached through the hosted URL, and without this the only way to
424
- * test a wallet change would be to deploy it.
425
- */
426
- walletUrl?: string;
427
- };
428
- }
429
- declare function ConnectButtonAccount({ className, style, theme, defaults, cloud: cloudProp, }: ConnectButtonAccountProps): react_jsx_runtime.JSX.Element;
430
-
431
- interface LoginModalProps {
432
- /** Callback when user connects */
433
- onConnect: (url: string) => void;
434
- /** Callback when modal is closed */
435
- onClose: () => void;
436
- /**
437
- * @deprecated Ignored. The modal always shows node discovery + manual URL
438
- * entry; the old hardcoded-default "Local" view was removed. Kept so
439
- * existing call sites keep compiling.
440
- */
441
- connectionType?: ConnectionType | CustomConnectionConfig;
442
- /** Whether the modal is open */
443
- isOpen: boolean;
444
- /** Theme overrides — accepts any subset of `MeroTheme` tokens */
445
- theme?: MeroTheme;
446
- /**
447
- * Ports probed when discovering local nodes. Defaults to the well-known
448
- * Calimero dev ports (2428, 2429, 2528, 2529). Mostly an escape hatch for
449
- * non-standard setups and tests.
450
- */
451
- localNodePorts?: readonly number[];
452
- /**
453
- * The second way in: a **Cloud** tab, signing in with a Calimero account by
454
- * enrolling this tab's device key at the wallet.
455
- *
456
- * - **Omitted** (the default): the tab is shown, sourced from
457
- * `useAccountEnrolment()` inside the modal — enrolment starts from the tab,
458
- * and a page coming back from the wallet is completed here, whether or not
459
- * the modal is open. Nothing to wire; the modal must be inside a
460
- * `MeroProvider`.
461
- * - **`false`**: no Cloud tab and no tabs at all — the node dialog as it was.
462
- * - **An object**: the caller's own enrolment, used verbatim; the modal reads
463
- * none itself. The values are `useAccountEnrolment`'s, as `ConnectButton`
464
- * passes them.
465
- *
466
- * Inside a Calimero Desktop window every form is as `false` — the window is
467
- * already bound to the desktop's node, so there is no relay and no passkey to
468
- * go through. `cloudOnDesktop` turns that off.
469
- */
470
- cloud?: false | {
471
- /** Start enrolment — normally `useAccountEnrolment().goToWallet`. */
472
- onEnrol: () => void;
473
- /** What the last enrolment had to say, shown on the Cloud tab. */
474
- note?: string | null;
475
- /** The wallet enrolment goes to. Shown only when `customWallet`. */
476
- walletUrl?: string;
477
- /** Whether `walletUrl` is an override rather than the hosted wallet. */
478
- customWallet?: boolean;
479
- };
480
- /**
481
- * Show the Cloud tab inside a Calimero Desktop window too. Default false:
482
- * the desktop logs in to its own node, so `cloud` — omitted or an object —
483
- * is ignored there (see `isDesktopWindow`).
484
- */
485
- cloudOnDesktop?: boolean;
486
- /**
487
- * The tab selected when the modal opens. Ignored with `cloud={false}`.
488
- *
489
- * Default `'node'` — except that a modal sourcing its own Cloud tab opens on
490
- * `'cloud'` when the page is coming back from the wallet, so whatever the
491
- * completion has to say is where the person is looking. An explicit value
492
- * always wins.
493
- */
494
- initialTab?: LoginModalTab;
495
- }
496
- /** The two tabs of the connect dialog, when it has a Cloud tab. */
497
- type LoginModalTab = 'node' | 'cloud';
498
- /**
499
- * LoginModal - Connection modal component
500
- */
501
- declare function LoginModal({ onConnect, onClose, isOpen, theme, localNodePorts, cloud, cloudOnDesktop, initialTab: initialTabProp, }: LoginModalProps): React.ReactPortal | null;
502
-
503
- interface AccountSignInPanelProps {
504
- /** Start enrolment — normally `useAccountEnrolment().goToWallet`. */
505
- onEnrol: () => void;
506
- /** What the last enrolment had to say (an error, or "nowhere to write yet"). */
507
- note?: string | null;
508
- /** The wallet enrolment goes to. Shown only when `customWallet`. */
509
- walletUrl?: string;
510
- /** Whether `walletUrl` is an override rather than the hosted wallet. */
511
- customWallet?: boolean;
512
- /** Theme overrides — accepts any subset of `MeroTheme` tokens */
513
- theme?: MeroTheme;
514
- }
515
- declare function AccountSignInPanel({ onEnrol, note, walletUrl, customWallet, theme, }: AccountSignInPanelProps): react_jsx_runtime.JSX.Element;
516
-
517
- interface CalimeroLogoProps extends React__default.SVGAttributes<SVGSVGElement> {
518
- /** Width / height shorthand (applied to both). Default: 24. */
519
- size?: number | string;
1015
+ interface CalimeroLogoProps extends React.SVGAttributes<SVGSVGElement> {
1016
+ /** Width / height shorthand (applied to both). Default: 24. */
1017
+ size?: number | string;
520
1018
  }
521
1019
  declare function CalimeroLogo({ size, color, style, ...rest }: CalimeroLogoProps): react_jsx_runtime.JSX.Element;
522
1020
 
523
- interface MigrationPendingBannerProps {
524
- /** Context whose authored entries to check / convert. */
525
- contextId: string;
526
- className?: string;
527
- /** Override the default prompt text. */
528
- children?: ReactNode;
529
- /** Fired once a convert leaves nothing pending (`remaining === 0`). */
530
- onMigrated?: () => void;
531
- }
532
- /**
533
- * Shows only when the current identity has entries below the target schema
534
- * (skew #1). A single button runs the one-tap `migrate_my_entries` convert and
535
- * the banner clears itself once nothing is pending.
536
- */
537
- declare function MigrationPendingBanner({ contextId, className, children, onMigrated, }: MigrationPendingBannerProps): react_jsx_runtime.JSX.Element | null;
538
-
539
- interface MigrationAdminPanelProps {
540
- /** Namespace whose migration rollup to display. */
541
- namespaceId: string;
542
- /** Re-fetch interval; migration facts arrive via heartbeat gossip. */
543
- pollIntervalMs?: number;
544
- className?: string;
545
- }
546
- /**
547
- * Operator view of a namespace's migration rollup (skew #3): the cohort
548
- * counters, `membersPendingSignature`, and a per-member table. Read-only —
549
- * pair with the upgrade-trigger hooks to drive a migration.
550
- */
551
- declare function MigrationAdminPanel({ namespaceId, pollIntervalMs, className }: MigrationAdminPanelProps): react_jsx_runtime.JSX.Element;
552
-
553
- /**
554
- * The delegated connect path, entered from an invitation instead of an account.
555
- *
556
- * `ConnectButtonAccount` enrols the device and then asks the cloud which relays
557
- * serve the ACCOUNT. For a first-time account that answer is `[]` and there is
558
- * nothing to connect to — correctly, since nothing yet serves an account that is
559
- * a member of nothing. This hook is the other door into the same connection: it
560
- * takes an invitation, resolves a relay from the NAMESPACE, presents the signed
561
- * join, and then connects through the node that carried it.
562
- *
563
- * It is `MeroContext`'s own `connectWithAccount` at the end, not a second
564
- * connection mechanism — the only difference is how the relay was found.
565
- */
566
-
567
- interface UseDelegatedBootstrapOptions {
568
- /** Point at a cloud other than the hosted manager. For local rigs. */
569
- readonly cloudBaseUrl?: string;
570
- }
571
- interface UseDelegatedBootstrapResult {
572
- /** The enrolled account and its certificate, or `null` if none was ever held. */
573
- readonly credential: DelegatedCredential | null;
574
- /**
575
- * Whether this account is signed in with nowhere to write.
576
- *
577
- * True means: an enrolled credential is held and no relay is known for it, so
578
- * the account→relay lookup has nothing and an invitation is what changes that.
579
- * Being signed in is NOT the missing part — that is the whole point, since you
580
- * have to be signed in to be invited.
581
- *
582
- * False covers "already has a relay" and "never enrolled", which need the two
583
- * other entry points rather than this one.
584
- */
585
- readonly needsBootstrap: boolean;
586
- readonly running: boolean;
587
- /** The last attempt's outcome, kept so a UI can name the failing step. */
588
- readonly result: BootstrapResult | null;
589
- /**
590
- * Admit this account to the invitation's namespace and connect through the
591
- * admitting node.
592
- *
593
- * Resolves rather than throws for every expected refusal: the step names are
594
- * the point, because an empty intersection, an unreachable admitter and a
595
- * namespace with no fleet assignment need three different actions.
596
- */
597
- readonly bootstrap: (input: {
598
- readonly namespaceId: string;
599
- readonly invitation: SignedGroupOpenInvitation;
600
- /**
601
- * A node to present the join to, skipping the cloud lookup — an operator's,
602
- * a local rig's, or one a future invitation carries.
603
- */
604
- readonly nodeUrl?: string;
605
- /** The context the invitation is for, so its relay is known before any listing. */
606
- readonly contextId?: string;
607
- }) => Promise<BootstrapResult>;
608
- }
609
- declare function useDelegatedBootstrap(options?: UseDelegatedBootstrapOptions): UseDelegatedBootstrapResult;
610
-
611
- /** The action an invite link carries: `calimero://<package>/join?invitation=…`. */
612
- declare const JOIN_ACTION = "join";
613
- /** The query parameter every app's invite builder emits. */
614
- declare const INVITATION_PARAM = "invitation";
615
- /**
616
- * The link an inviter shares, for every app: `https://links.calimero.network/<slug>/join?invitation=…`.
617
- *
618
- * One shape, so one path gets it into the app. The links page opens the app's
619
- * frontend with the query appended (web, PWA, a cold desktop start), and a
620
- * desktop that is already running hands it over as a `deep-link` bridge event;
621
- * `primeInvitationCapture` listens to both. Nobody pastes it anywhere.
622
- *
623
- * `slug` is the app's deep-link handler, which for a Calimero app is its package id.
624
- * `extra` rides along beside the token, for an app whose link carries more
625
- * than the token (a display name, a target id).
626
- */
627
- declare function buildInviteLink(slug: string, token: string, extra?: Record<string, string | undefined>): string;
628
- /** One captured invitation, with the ack the app owes the store. */
629
- interface CapturedInvitation {
630
- /** The raw invitation token, ready to parse. */
631
- token: string;
632
- /** Every query parameter the link carried, the token included. */
633
- params: Record<string, string>;
634
- /** Ack it so the store stops replaying it. Call once handled OR declined. */
635
- resolve: () => void;
636
- /**
637
- * Whether to attempt the join without being asked.
638
- *
639
- * False once this invitation has spent its automatic attempts. The token is
640
- * still handed over — so a field can be prefilled and one click retries it —
641
- * but a link that can never join stops re-firing on every load.
642
- */
643
- autoJoin: boolean;
644
- }
645
- type Listener = (invitation: CapturedInvitation) => void;
646
- /**
647
- * How many loads may auto-join one invitation before it needs a human.
648
- *
649
- * An unacked intent is replayed on every load by design, so that a transient
650
- * failure (node still starting, no member online yet) is retried rather than
651
- * lost. Without a ceiling a *permanent* failure is retried just as eagerly and
652
- * forever — which is what made every restart of the node re-fire a link that
653
- * had already been used.
654
- */
655
- declare const MAX_AUTO_JOIN_ATTEMPTS = 3;
656
- /** The token in a raw deep-link payload, or `null` if it carries none. */
657
- declare function invitationFromRaw(raw: string): string | null;
658
- /** The current URL with the invitation parameter removed. */
659
- declare function urlWithoutInvitation(href: string): string;
660
- /**
661
- * Start listening for inbound invitation links.
662
- *
663
- * Call once before React mounts: the launcher appends `?invitation=…` to the
664
- * app's own URL, and a router would otherwise replace the URL before any
665
- * component could read it.
666
- *
667
- * `appKey` namespaces the attempt ledger. Two apps served from one origin (the
668
- * dev server, a preview deployment) would otherwise share it.
669
- *
670
- * `slug` is this app's deep-link slug (its package id). Given it, a `join` link
671
- * addressed to a different app is dropped instead of being offered here.
672
- */
673
- declare function primeInvitationCapture(appKey?: string, options?: {
674
- slug?: string | readonly string[];
675
- }): void;
676
- /**
677
- * Subscribe to invitations. Replays one already captured, so a component that
678
- * mounts after the link was opened still sees it.
679
- */
680
- declare function onInvitation(listener: Listener): () => void;
681
- /**
682
- * The captured invitation right now, without subscribing.
683
- *
684
- * Unlike `onInvitation`, this does not consume it and does not register a
685
- * listener — it answers "is an invitation inbound?" for code that only needs
686
- * to know, such as a bootstrap deciding where to land the user.
687
- */
688
- declare function peekInvitation(): CapturedInvitation | null;
689
- /**
690
- * Be told when the captured invitation changes: one arrives, or it is acked.
691
- *
692
- * Unlike `onInvitation` this takes nothing: the invitation stays buffered for
693
- * whoever redeems it. It is for UI that only needs to know one is pending — the
694
- * logged-out invitation screen — and pairs with `peekInvitation` as a
695
- * `useSyncExternalStore` source.
696
- */
697
- declare function subscribeInvitation(watcher: () => void): () => void;
698
- /** Test seam: drop the controller and any buffered intent. */
699
- declare function resetInvitationCaptureForTests(): void;
700
-
701
- /**
702
- * What to tell a person about a failed join, or `null` to show the node's own
703
- * message (an `unknown` failure has nothing better to offer).
704
- *
705
- * `noun` is what the app calls the thing being joined: "team", "space", "vault".
706
- * The reason is mero-js's (`redeemInvitation`), read off the node's status.
707
- */
708
- /**
709
- * The reasons mero-js names for a join refusal, including the two it added for
710
- * a link already used and a removal. Listed here as well so this builds against
711
- * a mero-js that does not name them yet; such a mero-js reports both as
712
- * `refused`.
713
- */
714
- type JoinFailureReason = InviteFailureReason | 'already-used' | 'removed';
715
- declare function describeInviteFailure(reason: JoinFailureReason, noun?: string): string | null;
716
-
717
- /** What the token carries, once the app's codec has read it. */
718
- interface ParsedInvitation {
719
- namespaceId: string;
720
- /** The invitation struct the node's join body expects. */
721
- invitation: unknown;
722
- /** The human name the inviter embedded, if any. */
723
- teamName?: string;
724
- }
725
- /**
726
- * Where redemption has got to, for rendering.
727
- *
728
- * `joining` is the state the apps used to lack: following an invite
729
- * link put the app on a page with no sign anything was happening, for as long
730
- * as the join took — up to 95s when no member of the namespace was online.
731
- */
732
- type InviteState = {
733
- stage: "idle";
734
- } | {
735
- stage: "awaiting-confirmation";
736
- teamName?: string;
737
- } | {
738
- stage: "joining";
739
- teamName?: string;
740
- } | {
741
- stage: "joined";
742
- namespaceId: string;
743
- teamName?: string;
744
- } | {
745
- stage: "already-member";
746
- namespaceId: string;
747
- teamName?: string;
748
- } | {
749
- stage: "failed";
750
- /** The node's own words, or this package's for an unreadable link. */
751
- message: string;
752
- /** Why; `describeInviteFailure` turns it into something to show. */
753
- reason: InviteFailureReason;
754
- retryable: boolean;
755
- };
756
- interface UseInviteRedemptionOptions<P extends ParsedInvitation = ParsedInvitation> {
757
- /**
758
- * Read a raw token into its parts. Return `null` (or throw) if it is not a
759
- * usable invitation — the app owns this because the codecs differ slightly.
760
- * Extra fields the app returns (a vault name, a context id) come back as
761
- * `parsed` and are handed to `redeem`.
762
- */
763
- parse: (token: string, params: Record<string, string>) => P | null;
764
- /**
765
- * The two calls that differ between apps, for the standard join: join the
766
- * namespace, then check membership (mero-js `redeemInvitation`).
767
- */
768
- redeemer?: InviteRedeemer;
769
- /**
770
- * An app's own join flow, for one that does more than join the namespace
771
- * (enter a context, pick where to land). Takes precedence over `redeemer`.
772
- * Report a failure as a `failed` outcome rather than throwing; a throw is
773
- * read as an `unknown`, retryable failure.
774
- */
775
- redeem?: (parsed: P) => Promise<RedeemOutcome>;
776
- /**
777
- * Ask before joining, rather than joining on arrival.
778
- *
779
- * Not a stylistic choice, and deliberately per-app. Joining is a state
780
- * change: it puts you in someone else's namespace and gives them a peer that
781
- * syncs their data. For an app holding secrets — mero-pass is the clear case
782
- * — doing that on page load means a forwarded link, or a background tab that
783
- * refreshes, joins silently. Decoding is pure and local, so the scope can be
784
- * shown first and the join can need a click.
785
- *
786
- * With this set the state goes `awaiting-confirmation` and waits for
787
- * `accept()`; `decline()` acks the invitation so it stops coming back.
788
- *
789
- * On by default: an invitation reaches an app only by a link being opened,
790
- * and every app asks before it joins. Off only for a caller that has already
791
- * asked in its own words.
792
- */
793
- confirm?: boolean;
794
- /**
795
- * Called once, after a join has landed and before anything navigates. The
796
- * `already-member` case calls it too: the app still has to go and look at a
797
- * namespace it may never have opened.
798
- */
799
- onJoined?: (namespaceId: string, teamName?: string) => void;
800
- /**
801
- * Hold off until the app can actually join — a session, a resolved
802
- * application id. The invitation is buffered meanwhile, not dropped.
803
- */
804
- enabled?: boolean;
805
- }
806
- interface InviteRedemption<P extends ParsedInvitation = ParsedInvitation> {
807
- state: InviteState;
808
- /** The captured token, for prefilling a manual join field. */
809
- token: string | null;
810
- /** What the invitation names, available while confirming. */
811
- parsed: P | null;
812
- /** Go ahead with a join that is `awaiting-confirmation`. */
813
- accept: () => void;
814
- /** Decline it, and ack it so it does not come back. */
815
- decline: () => void;
816
- /** Retry the captured invitation by hand, past the automatic attempt cap. */
817
- retry: () => void;
818
- /** Take the result off the screen. */
819
- dismiss: () => void;
820
- }
821
- /**
822
- * Redeem an invitation that arrived by link, and report progress.
823
- *
824
- * Mount this once, high enough that it is not unmounted by routing. Capture is
825
- * process-wide and buffers, so mounting late is safe; being unmounted mid-join
826
- * only loses the on-screen state, never the invitation (it is acked on the
827
- * outcome, not on the render).
828
- */
829
- declare function useInviteRedemption<P extends ParsedInvitation = ParsedInvitation>({ parse, redeemer, redeem, confirm, onJoined, enabled, }: UseInviteRedemptionOptions<P>): InviteRedemption<P>;
830
-
831
- /** How long "You're in" stays up before the dialog closes by itself. */
832
- declare const INVITATION_READY_MS = 1200;
833
- interface InvitationDialogProps {
834
- /** The app's `useInviteRedemption(...)`. */
835
- redemption: InviteRedemption;
836
- /** What the app calls the thing being joined: "team", "workspace", "vault". */
837
- noun?: string;
838
- /** Shown above the title, so a person knows which app is asking. */
839
- appName?: string;
840
- /**
841
- * Optional: the joined namespace's data has been read, empty or not. For an
842
- * app whose root already knows; others leave this out and let the page that
843
- * reads the data clear the flag with `useJoinSync({ settled })`.
844
- */
845
- synced?: boolean;
846
- /**
847
- * Optional: the app's own words under the question, for an invitation whose
848
- * grant needs spelling out ("Joining gives you this vault and the rest of
849
- * the team it belongs to.").
850
- */
851
- detail?: string;
852
- /** Optional: which step a slow join is on, shown while joining. */
853
- status?: string | null;
854
- }
855
- /** The stage the dialog shows: redemption's, plus the wait for the data. */
856
- type InvitationDialogStage = 'awaiting-confirmation' | 'joining' | 'syncing' | 'ready' | 'already-member' | 'failed';
857
- declare function InvitationDialog({ redemption, noun, appName, synced, detail, status, }: InvitationDialogProps): React.ReactPortal | null;
858
-
859
- /**
860
- * Hear every mark and clear in this page. The flag is set by redemption (at
861
- * the app root) and cleared by whichever page reads the namespace's data
862
- * (`useJoinSync`), so this is how the one learns about the other without the
863
- * app threading page state up to its root.
864
- */
865
- declare function subscribeJustJoined(listener: () => void): () => void;
866
- /**
867
- * Call this the moment a join succeeds, before navigating. The app that reads
868
- * the flag is usually a different route from the one that accepted the invite.
869
- */
870
- declare function markNamespaceJustJoined(namespaceId: string): void;
871
- declare function clearNamespaceJustJoined(namespaceId: string): void;
872
- declare function isNamespaceJustJoined(namespaceId: string | null): boolean;
873
-
874
- /**
875
- * Base window for the gate. A governance op plus the namespace's own state
876
- * typically land in under a second on a healthy mesh; past this we give up
877
- * ONLY if nothing is actively in flight.
878
- */
879
- declare const JOIN_SYNC_WATCHDOG_MS = 30000;
880
- /**
881
- * Hard ceiling. Bounds a genuinely stuck sync so the gate can never pin the UI
882
- * forever, even while something keeps reporting activity.
883
- */
884
- declare const JOIN_SYNC_MAX_MS = 120000;
885
- /** How often the watchdog re-checks activity past the base window. */
886
- declare const JOIN_SYNC_POLL_MS = 2000;
887
- interface JoinSyncOptions {
888
- /** The namespace being shown. `null` while nothing is selected. */
889
- namespaceId: string | null;
890
- /**
891
- * The app's own answer to "has this namespace's data actually arrived?" —
892
- * the one thing that cannot be shared, because every app reads a different
893
- * collection. Pass `true` once a real read has come back, INCLUDING an empty
894
- * one: "no documents yet" is a settled answer, and waiting for a non-empty
895
- * result would gate an genuinely empty workspace forever.
896
- */
897
- settled: boolean;
898
- /**
899
- * Optional: a sync is making forward progress. Holds the gate open past the
900
- * base window, up to the hard ceiling. Leave undefined if the app has no
901
- * such signal — the gate then simply expires at the base window.
902
- *
903
- * A stuck or backing-off sync must report `false`, not `true`: the point of
904
- * the base window is to stop waiting on something that is not coming.
905
- */
906
- active?: boolean;
907
- }
908
- interface JoinSyncState {
909
- /**
910
- * Show the "syncing from peers" affordance. True only for a namespace this
911
- * session just joined, whose data has not arrived, within the watchdog.
912
- */
913
- isSyncing: boolean;
914
- /** Drop the gate now — for a "show me anyway" control. */
915
- dismiss: () => void;
916
- }
917
- /**
918
- * Gate the window between "you joined" and "your data is here".
919
- *
920
- * Without it a just-joined namespace renders its ordinary empty state, and the
921
- * user cannot tell an empty workspace from one that is still arriving. That
922
- * ambiguity is the whole reason this exists: the two look identical, and the
923
- * honest one is the less alarming of the two.
924
- */
925
- declare function useJoinSync({ namespaceId, settled, active, }: JoinSyncOptions): JoinSyncState;
926
-
927
- interface JoinSyncBannerProps {
928
- /** Usually `useJoinSync(...).isSyncing`. Renders nothing when false. */
929
- show: boolean;
930
- /** What is arriving, in the app's own words: "documents", "vaults", "sheets". */
931
- what?: string;
932
- /** Wire to `useJoinSync(...).dismiss` for a "show me anyway" escape. */
933
- onDismiss?: () => void;
934
- /** Escape hatches for apps with their own design system. */
935
- className?: string;
936
- style?: CSSProperties;
937
- children?: ReactNode;
938
- }
939
- /**
940
- * Deliberately inline-styled rather than using a stylesheet or utility classes.
941
- *
942
- * The apps in this monorepo do not share a CSS stack — Tailwind, CSS modules
943
- * and plain stylesheets are all represented — so anything class-based would
944
- * render unstyled in most of them. Inline styles are the only thing that looks
945
- * the same everywhere, and `className`/`style` are there for apps that want to
946
- * take it over. Colours come from CSS custom properties with literal
947
- * fallbacks, so an app that defines them gets its own palette for free and one
948
- * that does not still gets something legible in both themes.
949
- */
950
- declare function JoinSyncBanner({ show, what, onDismiss, className, style, children, }: JoinSyncBannerProps): react_jsx_runtime.JSX.Element | null;
951
-
952
- interface InvitationGateProps {
953
- /**
954
- * The app, shown as usual unless an invitation is waiting on a login. Leave
955
- * out to mount the gate beside the app instead, as a full-page layer.
956
- */
957
- children?: ReactNode;
958
- /**
959
- * The app's invitation codec, the same `parse` it gives `useInviteRedemption`.
960
- * Decoding needs no session, so the screen can name what is being joined.
961
- * Without it the screen falls back to the noun.
962
- */
963
- parse?: (token: string, params: Record<string, string>) => ParsedInvitation | null;
964
- /** What the app calls the thing being joined: "team", "workspace", "vault". */
965
- noun?: string;
966
- /** The app's name, so a person knows where the invitation is taking them. */
967
- appName?: string;
968
- /** Optional: the app's own words about what joining gives you. */
969
- detail?: string;
970
- /** Passed to the login button (theme, `cloud`, `connectionType`). */
971
- connectButtonProps?: Omit<ConnectButtonProps, 'label'>;
972
- }
973
- /** The captured invitation, re-rendering when one arrives or is acked. */
974
- declare function usePendingInvitation(): CapturedInvitation | null;
975
- declare function InvitationGate({ children, parse, noun, appName, detail, connectButtonProps, }: InvitationGateProps): react_jsx_runtime.JSX.Element | null;
976
-
977
- interface JoinInvitationInput {
978
- readonly namespaceId: string;
979
- /** The context the invitation was for, when it names one; a workspace invitation names none. */
980
- readonly contextId?: string;
981
- readonly invitation: SignedGroupOpenInvitation;
982
- }
983
- type JoinInvitationStep = BootstrapFailure['step'] | 'node-join';
984
- type JoinInvitationResult = {
985
- readonly ok: true;
986
- } | {
987
- readonly ok: false;
988
- readonly step: JoinInvitationStep;
989
- /** What went wrong, in words a person can act on. */
990
- readonly reason: string;
991
- /** True when no retry can succeed: a fresh invitation is the only cure. */
992
- readonly final: boolean;
993
- /** The HTTP status of the refusal, when there was one. */
994
- readonly status?: number;
995
- };
996
- /**
997
- * Whether a node's join failure means the invitation itself will never work.
998
- *
999
- * Errs toward false: a dropped invitation is unrecoverable for the user, a
1000
- * retried one costs a round trip, so a timeout or anything unfamiliar keeps
1001
- * it. Phrases, not bare words — `"invalid"` alone would also match an
1002
- * "invalid response" from a proxy, a transient failure.
1003
- */
1004
- declare function isFinalInvitationError(message: string | undefined | null): boolean;
1005
- declare function useJoinInvitation(): {
1006
- joinInvitation: (input: JoinInvitationInput) => Promise<JoinInvitationResult>;
1007
- joining: boolean;
1008
- /** The namespaces this connection is a member of: a node's own, or an account's across its relays. */
1009
- memberships: () => Promise<string[]>;
1010
- /**
1011
- * The `{ join, memberships }` pair mero-js's `redeemInvitation` drives, for
1012
- * whichever connection this is, so an app redeems an invitation (join once,
1013
- * then check membership) with no transport of its own. `join` throws on a
1014
- * refusal, carrying its HTTP status for the outcome's reason.
1015
- */
1016
- invitationRedeemer: (input: JoinInvitationInput) => InviteRedeemer;
1017
- };
1018
-
1019
- /**
1020
- * useAccountEnrolment — the account sign-in flow, with no UI.
1021
- *
1022
- * Moved out of {@link ConnectButtonAccount} unchanged, so that `ConnectButton`'s
1023
- * Cloud tab and `ConnectButtonAccount` share one copy of it: the device keys,
1024
- * the redirect to the wallet, and the completion when the tab comes back.
1025
- *
1026
- * - `goToWallet` generates (or reuses) this tab's device keys and leaves for the
1027
- * wallet. mero-js's `deviceEnrolmentUrl` remembers the request under a fresh
1028
- * state.
1029
- * - On the way back, the callback is read ONCE during render, the certificate
1030
- * is completed and saved (`completeDeviceEnrolment` refuses an answer to a
1031
- * request this browser did not start, and spends its state), the account's
1032
- * relays are looked up, and `connectWithAccount` connects.
1033
- * - `note` is what the person should be told about that — an error, or a
1034
- * connection with nowhere to write yet.
1035
- * - `returning` is true when this page load carries an enrolment callback,
1036
- * success or error, so a caller can show the place the note appears.
1037
- */
1038
- /**
1039
- * Whether this page load is the one coming back from the wallet — a completed
1040
- * enrolment or a declined one — WITHOUT consuming it.
1041
- *
1042
- * `useAccountEnrolment` reads the callback once and strips it from the address
1043
- * bar, so a second reader finds nothing. That makes `returning` from the hook
1044
- * unusable for the one decision that has to be taken before the hook runs: a
1045
- * component that owns `LoginModal`'s `isOpen` and wants the dialog open on the
1046
- * way back. This is the answer for it, as a `useState` initialiser:
1047
- *
1048
- * ```tsx
1049
- * const [open, setOpen] = useState(isReturningFromWallet);
1050
- * <LoginModal isOpen={open} ... /> // sources its own Cloud tab, lands on it
1051
- * ```
1052
- *
1053
- * The parent's initialiser runs before the modal's hook reads the fragment, so
1054
- * the two agree. `ConnectButton` needs none of this: it owns both.
1055
- */
1056
- declare function isReturningFromWallet(location?: {
1057
- hash: string;
1058
- } | undefined): boolean;
1059
- interface UseAccountEnrolmentOptions {
1060
- /**
1061
- * Point enrolment at a wallet other than the hosted one.
1062
- *
1063
- * Exists for working ON the wallet: a wallet served from `localhost:8090`
1064
- * cannot be reached through the hosted URL, and without this the only way to
1065
- * test a wallet change would be to deploy it.
1066
- */
1067
- walletUrl?: string;
1068
- /**
1069
- * When false, the hook reads no callback and completes nothing, so a
1070
- * component that has the account path switched off leaves the fragment for
1071
- * whichever component does handle it. Default true, except inside a
1072
- * Calimero Desktop window (see `isDesktopWindow`), whose app is already
1073
- * bound to the desktop's node and has no wallet callback to complete.
1074
- */
1075
- enabled?: boolean;
1076
- }
1077
- interface AccountEnrolment {
1078
- /** Leave for the wallet to enrol this tab's device key. */
1079
- goToWallet: () => Promise<void>;
1080
- /** What to tell the person about the last enrolment, or null. */
1081
- note: string | null;
1082
- /** Whether this page load carries an enrolment callback (success or error). */
1083
- returning: boolean;
1084
- /** The wallet enrolment goes to: the override, else the hosted one. */
1085
- walletUrl: string;
1086
- /** Whether `walletUrl` is an override rather than the hosted wallet. */
1087
- customWallet: boolean;
1088
- }
1089
- declare function useAccountEnrolment({ walletUrl: walletOverride, enabled, }?: UseAccountEnrolmentOptions): AccountEnrolment;
1090
-
1091
- interface UseEphemeralOptions<T> {
1092
- /** Encoding for the presence slice. Defaults to JSON. */
1093
- codec?: Codec<T>;
1094
- /** Base value for the first `setPresence` merge. */
1095
- initial?: T;
1096
- /** Minimum ms between publishes. Trailing edge — the latest value wins. */
1097
- throttleMs?: number;
1098
- /** Include your own echoed presence in `peers`. Default false. */
1099
- includeSelf?: boolean;
1100
- }
1101
- /** Shape returned by {@link useEphemeral}. */
1102
- interface UseEphemeralResult<T> {
1103
- peers: Map<string, T>;
1104
- setPresence: (partial: Partial<T>) => void;
1105
- ageOf: (author: string) => number | undefined;
1106
- error: Error | null;
1107
- }
1108
- /**
1109
- * Observe and publish ephemeral presence (cursors, typing, online) for a
1110
- * context.
1111
- *
1112
- * ONE read path: the subscription. When a client subscribes, the node replays
1113
- * that context's current presence to that connection as ordinary entries
1114
- * before the live deltas start, so seeding and updating share a single shape
1115
- * ({@link EphemeralEntry}) and a reconnect — `SseClient` auto-reconnects and
1116
- * re-subscribes — re-seeds itself. There is no snapshot fetch and no
1117
- * client-side reconciliation pass.
1118
- *
1119
- * Freshness is computed entirely from local clock deltas: a replayed entry is
1120
- * current as of `Date.now() - ageMs`, a live delta as of `Date.now()`. No
1121
- * cross-machine clock comparison is ever performed.
1122
- *
1123
- * No client-side TTL or heartbeat: the node sweeps at 7s and emits removals,
1124
- * and re-publishes on your behalf every 2.5s. A replay is treated as
1125
- * AUTHORITATIVE — see the replay-reconcile pass in the read effect — so a peer
1126
- * swept while the SSE connection was down does not survive the reconnect.
1127
- *
1128
- * `error` is derived, not accumulated: standing conditions (no `ephemeral`
1129
- * surface) are recomputed every render, one-shot async failures are latched
1130
- * keyed by the context they happened in, and whether a latched failure is even
1131
- * relevant (an unresolved identity when `includeSelf` is true) is decided at
1132
- * read time. Nothing survives a context switch.
1133
- */
1134
- declare function useEphemeral<T>(contextId: string | null, options?: UseEphemeralOptions<T>): UseEphemeralResult<T>;
1135
- /**
1136
- * Shape accepted by the metadata-setter hooks — re-exported from mero-js so
1137
- * callers have one canonical type. A `set*Metadata` call **replaces the whole
1138
- * record**: `data` defaults to `{}` and wholly replaces the stored map; omit
1139
- * `name` to keep the current name.
1140
- */
1141
- type SetMetadataInput = SetMetadataRequest;
1142
- /** Options a mutation hook that can fail meaningfully accepts. */
1143
- interface MutationOptions {
1144
- /**
1145
- * Rethrow a failed request from the action, after recording it in `error`
1146
- * and `failure`.
1147
- *
1148
- * By default an action resolves `null` on failure, which a caller awaiting it
1149
- * cannot tell apart from "not connected" — and a `catch` around it never
1150
- * runs, so a refused join reads as a successful one. Set this when the
1151
- * caller branches on the outcome.
1152
- */
1153
- throwOnError?: boolean;
1154
- }
1155
- /**
1156
- * Execute RPC methods against a context.
1157
- * Tracks loading/error state. Unmount-safe.
1158
- */
1159
- declare function useExecute(contextId: string | null, executorId: string | null): {
1160
- execute: <T = unknown>(method: string, params?: Record<string, unknown>) => Promise<T | null>;
1161
- loading: boolean;
1162
- error: Error | null;
1163
- };
1164
- /** Event payload delivered to a `useSubscription` callback. */
1165
- type SubscriptionEventData = SseEventData | GroupMembershipEventData | GroupMigrationEventData;
1166
- /** Ids to subscribe to. Either can be omitted, but not both. */
1167
- interface SubscriptionInput {
1168
- contextIds?: string[];
1169
- groupIds?: string[];
1170
- }
1171
- /**
1172
- * Subscribe to SSE events for context and/or group IDs.
1173
- * StrictMode-safe: tracks the SseClient instance in a ref to avoid
1174
- * double-connect on mount/unmount/remount cycles.
1175
- */
1176
- declare function useSubscription(contextIds: string[], callback: (event: SubscriptionEventData) => void): void;
1177
- declare function useSubscription(input: SubscriptionInput, callback: (event: SubscriptionEventData) => void): void;
1178
- /**
1179
- * Fetch contexts for the current node, optionally filtered by application ID.
1180
- */
1181
- declare function useContexts(applicationId?: string | null): {
1182
- contexts: ApplicationContextRecord[];
1183
- loading: boolean;
1184
- error: Error | null;
1185
- refetch: () => Promise<void>;
1186
- };
1187
- declare function useApplicationContexts(applicationId?: string | null): {
1188
- contexts: ApplicationContextRecord[];
1189
- loading: boolean;
1190
- error: Error | null;
1191
- refetch: () => Promise<void>;
1192
- };
1193
- declare function useGroupMembers(groupId?: string | null): {
1194
- members: _calimero_network_mero_js.GroupMember[];
1195
- loading: boolean;
1196
- error: Error | null;
1197
- refetch: () => Promise<void>;
1198
- };
1199
- declare function useGroupContexts(groupId?: string | null): {
1200
- contexts: GroupContextEntry[];
1201
- loading: boolean;
1202
- error: Error | null;
1203
- refetch: () => Promise<void>;
1204
- };
1205
- declare function useGroupInvitations(): {
1206
- createInvitation: (groupId: string, request?: CreateGroupInvitationRequest) => Promise<_calimero_network_mero_js.CreateGroupInvitationResponseData | _calimero_network_mero_js.CreateRecursiveGroupInvitationResponseData | null>;
1207
- loading: boolean;
1208
- error: Error | null;
1209
- };
1210
- declare function useJoinGroup(): {
1211
- joinGroup: (request: JoinGroupRequest) => Promise<_calimero_network_mero_js.JoinGroupResponseData | null>;
1212
- loading: boolean;
1213
- error: Error | null;
1214
- };
1215
- /**
1216
- * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
1217
- * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
1218
- * Both are 32-byte strings, so passing a key names nobody and raises nothing.
1219
- */
1220
- declare function useGroupCapabilities(groupId?: string | null, memberId?: string | null): {
1221
- capabilities: number | null;
1222
- loading: boolean;
1223
- error: Error | null;
1224
- refetch: () => Promise<number | null>;
1225
- setCapabilities: (nextCapabilities: number) => Promise<number | null>;
1226
- };
1227
- declare function useContextDiscovery(options: ContextDiscoveryOptions): ContextDiscoveryState;
1228
- declare function useCreateContext(): {
1229
- createContext: (request: CreateContextRequest) => Promise<{
1230
- contextId: string;
1231
- } | null>;
1232
- loading: boolean;
1233
- error: Error | null;
1234
- };
1235
- interface CreatePrivateContextRequest {
1236
- readonly namespaceId: string;
1237
- readonly applicationId: string;
1238
- /** The accounts that share it with you, and nobody else — e.g. the other person of a DM. */
1239
- readonly members: readonly string[];
1240
- readonly initializationParams?: number[];
1241
- }
1242
- /**
1243
- * Create a context only you and `members` are in (a DM, a small room): its own
1244
- * restricted group in the namespace, members added directly — they are in the
1245
- * namespace already, so nobody is invited. Same call on either connection:
1246
- *
1247
- * - a node login makes the group, adds the members and creates the context
1248
- * with its own admin calls (as mero-chat's DMs do);
1249
- * - an account has the relay serving the namespace do the same three steps,
1250
- * each under its own warrant (mero-js createDelegatedContext).
1251
- */
1252
- declare function useCreatePrivateContext(): {
1253
- createPrivateContext: (request: CreatePrivateContextRequest) => Promise<{
1254
- contextId: string;
1255
- } | null>;
1256
- loading: boolean;
1257
- error: Error | null;
1258
- };
1259
- declare function useDeleteContext(): {
1260
- deleteContext: (contextId: string) => Promise<_calimero_network_mero_js.DeleteContextResponseData | null>;
1261
- loading: boolean;
1262
- error: Error | null;
1263
- };
1264
- /**
1265
- * Join a context. `failure` says what kind of refusal a failed join was, and
1266
- * whether trying again later could work; pass `{ throwOnError: true }` to have
1267
- * `joinContext` reject instead of resolving `null`.
1268
- */
1269
- declare function useJoinContext(options?: MutationOptions): {
1270
- joinContext: (contextId: string) => Promise<_calimero_network_mero_js.JoinContextResponseData | null>;
1271
- loading: boolean;
1272
- error: Error | null;
1273
- failure: ClassifiedError | null;
1274
- };
1275
- declare function useJoinSubgroupInheritance(): {
1276
- joinSubgroupInheritance: (groupId: string) => Promise<{
1277
- groupId: string;
1278
- memberPublicKey: string;
1279
- wasInherited: boolean;
1280
- } | null>;
1281
- loading: boolean;
1282
- error: Error | null;
1283
- };
1284
- declare function useContextGroup(contextId?: string | null): {
1285
- groupId: string | null;
1286
- loading: boolean;
1287
- error: Error | null;
1288
- refetch: () => Promise<void>;
1289
- };
1290
- declare function useGroupInfo(groupId?: string | null): {
1291
- groupInfo: GroupInfo | null;
1292
- loading: boolean;
1293
- error: Error | null;
1294
- refetch: () => Promise<void>;
1295
- };
1296
- declare function useDeleteGroup(): {
1297
- deleteGroup: (groupId: string) => Promise<_calimero_network_mero_js.DeleteGroupResponseData | null>;
1298
- loading: boolean;
1299
- error: Error | null;
1300
- };
1301
- declare function useSyncGroup(): {
1302
- syncGroup: (groupId: string) => Promise<_calimero_network_mero_js.SyncGroupResponseData | null>;
1303
- loading: boolean;
1304
- error: Error | null;
1305
- };
1306
- /**
1307
- * Takes the invitee's signing KEY (bs58) - the one call on this resource that
1308
- * does, because someone being added may have no account here yet. Every other
1309
- * member call, including `useRemoveGroupMembers`, takes the ACCOUNT, so a value
1310
- * round-tripped from an add is the wrong one to remove with.
1311
- */
1312
- declare function useAddGroupMembers(): {
1313
- addGroupMembers: (groupId: string, request: AddGroupMembersRequest) => Promise<void | null>;
1314
- loading: boolean;
1315
- error: Error | null;
1316
- };
1317
- /**
1318
- * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
1319
- * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
1320
- * Both are 32-byte strings, so passing a key names nobody and raises nothing.
1321
- */
1322
- declare function useRemoveGroupMembers(): {
1323
- removeGroupMembers: (groupId: string, request: RemoveGroupMembersRequest) => Promise<void | null>;
1324
- loading: boolean;
1325
- error: Error | null;
1326
- };
1327
- declare function useNamespaces(): {
1328
- namespaces: Namespace[];
1329
- loading: boolean;
1330
- error: Error | null;
1331
- refetch: () => Promise<void>;
1332
- };
1333
- declare function useNamespace(namespaceId?: string | null): {
1334
- namespace: Namespace | null;
1335
- loading: boolean;
1336
- error: Error | null;
1337
- refetch: () => Promise<void>;
1338
- };
1339
- /**
1340
- * Who this node is: `accountId` is what member-addressing takes and what
1341
- * `useGroupMembers` rows are keyed by — `publicKey` is the signing key and
1342
- * addresses nobody. Both are 32-byte strings, so a swap fails silently.
1343
- */
1344
- declare function useNodeIdentity(): {
1345
- identity: NodeIdentity | null;
1346
- loading: boolean;
1347
- error: Error | null;
1348
- refetch: () => Promise<void>;
1349
- };
1350
- declare function useNamespacesForApplication(applicationId?: string | null): {
1351
- namespaces: Namespace[];
1352
- loading: boolean;
1353
- error: Error | null;
1354
- refetch: () => Promise<void>;
1355
- };
1356
- declare function useCreateNamespace(): {
1357
- createNamespace: (request: CreateNamespaceRequest) => Promise<_calimero_network_mero_js.CreateNamespaceResponseData | null>;
1358
- loading: boolean;
1359
- error: Error | null;
1360
- };
1361
- declare function useDeleteNamespace(): {
1362
- deleteNamespace: (namespaceId: string) => Promise<_calimero_network_mero_js.DeleteNamespaceResponseData | null>;
1363
- loading: boolean;
1364
- error: Error | null;
1365
- };
1366
- declare function useCreateNamespaceInvitation(): {
1367
- createNamespaceInvitation: (namespaceId: string, request?: CreateNamespaceInvitationRequest) => Promise<CreateNamespaceInvitationResponseData | CreateRecursiveInvitationResponseData | null>;
1368
- loading: boolean;
1369
- error: Error | null;
1370
- };
1371
- /**
1372
- * Join a namespace by invitation. `failure` says what kind of refusal a failed
1373
- * join was, and whether trying again later could work; pass
1374
- * `{ throwOnError: true }` to have `joinNamespace` reject instead of resolving
1375
- * `null`.
1376
- *
1377
- * To follow an invitation link, prefer {@link useRedeemInvitation}: it also
1378
- * recognises a join that landed although its request failed.
1379
- */
1380
- declare function useJoinNamespace(options?: MutationOptions): {
1381
- joinNamespace: (namespaceId: string, request: JoinNamespaceRequest) => Promise<_calimero_network_mero_js.JoinNamespaceResponseData | null>;
1382
- loading: boolean;
1383
- error: Error | null;
1384
- failure: ClassifiedError | null;
1385
- };
1386
- /**
1387
- * Follow an invitation: join its namespace once, then check membership, and
1388
- * report what happened as a {@link RedeemOutcome}.
1389
- *
1390
- * Unlike {@link useJoinNamespace}, a request that failed but whose join landed
1391
- * anyway — the desktop proxy aborts at 30s, a join with no member online takes
1392
- * longer — is `already-member`, not a failure. `shouldRetain(outcome)` from
1393
- * mero-js says whether to keep the invitation for another attempt.
1394
- *
1395
- * `redeem` resolves `null` only when there is no client to send it through.
1396
- */
1397
- declare function useRedeemInvitation(): {
1398
- redeem: (namespaceId: string, invitation: JoinNamespaceRequest["invitation"], options?: {
1399
- groupName?: string;
1400
- teamName?: string;
1401
- }) => Promise<RedeemOutcome | null>;
1402
- outcome: RedeemOutcome | null;
1403
- loading: boolean;
1404
- };
1405
- declare function useCreateGroupInNamespace(): {
1406
- createGroupInNamespace: (namespaceId: string, request?: CreateGroupInNamespaceRequest) => Promise<_calimero_network_mero_js.CreateGroupInNamespaceResponseData | null>;
1407
- loading: boolean;
1408
- error: Error | null;
1409
- };
1410
- declare function useNamespaceGroups(namespaceId?: string | null): {
1411
- groups: SubgroupEntry[];
1412
- loading: boolean;
1413
- error: Error | null;
1414
- refetch: () => Promise<void>;
1415
- };
1416
- /**
1417
- * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
1418
- * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
1419
- * Both are 32-byte strings, so passing a key names nobody and raises nothing.
1420
- */
1421
- declare function useUpdateMemberRole(): {
1422
- updateMemberRole: (groupId: string, identity: string, request: UpdateMemberRoleRequest) => Promise<void | null>;
1423
- loading: boolean;
1424
- error: Error | null;
1425
- };
1426
- declare function useSetDefaultCapabilities(): {
1427
- setDefaultCapabilities: (groupId: string, request: SetDefaultCapabilitiesRequest) => Promise<void | null>;
1428
- loading: boolean;
1429
- error: Error | null;
1430
- };
1431
- declare function useSetSubgroupVisibility(): {
1432
- setSubgroupVisibility: (groupId: string, request: SetSubgroupVisibilityRequest) => Promise<void | null>;
1433
- loading: boolean;
1434
- error: Error | null;
1435
- };
1436
- declare function useDefaultCapabilities(groupId?: string | null): {
1437
- defaultCapabilities: number | null;
1438
- loading: boolean;
1439
- error: Error | null;
1440
- refetch: () => Promise<void>;
1441
- };
1442
- declare function useSubgroupVisibility(groupId?: string | null): {
1443
- subgroupVisibility: string | null;
1444
- loading: boolean;
1445
- error: Error | null;
1446
- refetch: () => Promise<void>;
1447
- };
1448
- declare function useSetTeeAdmissionPolicy(): {
1449
- setTeeAdmissionPolicy: (groupId: string, request: SetTeeAdmissionPolicyRequest) => Promise<void | null>;
1450
- loading: boolean;
1451
- error: Error | null;
1452
- };
1453
- declare function useSetGroupMetadata(): {
1454
- setGroupMetadata: (groupId: string, request: SetMetadataInput) => Promise<void | null>;
1455
- loading: boolean;
1456
- error: Error | null;
1457
- };
1458
- /**
1459
- * Takes the member's ACCOUNT (64 hex), as `useGroupMembers` rows are keyed by
1460
- * and `useNodeIdentity().identity?.accountId` returns - NOT a signing key.
1461
- * Both are 32-byte strings, so passing a key names nobody and raises nothing.
1462
- */
1463
- declare function useSetMemberMetadata(): {
1464
- setMemberMetadata: (groupId: string, identity: string, request: SetMetadataInput) => Promise<void | null>;
1465
- loading: boolean;
1466
- error: Error | null;
1467
- };
1468
- declare function useSetContextMetadata(): {
1469
- setContextMetadata: (groupId: string, contextId: string, request: SetMetadataInput) => Promise<void | null>;
1470
- loading: boolean;
1471
- error: Error | null;
1472
- };
1473
- declare function useGroupMetadata(groupId?: string | null): {
1474
- metadata: MetadataRecord | null;
1475
- loading: boolean;
1476
- error: Error | null;
1477
- refetch: () => Promise<void>;
1478
- };
1479
- declare function useMemberMetadata(groupId?: string | null, identity?: string | null): {
1480
- metadata: MetadataRecord | null;
1481
- loading: boolean;
1482
- error: Error | null;
1483
- refetch: () => Promise<void>;
1484
- };
1485
- declare function useUpgradeGroup(): {
1486
- upgradeGroup: (groupId: string, request: UpgradeGroupRequest) => Promise<_calimero_network_mero_js.UpgradeGroupResponseData | null>;
1487
- loading: boolean;
1488
- error: Error | null;
1489
- };
1490
- /**
1491
- * Install a registry package version onto the node — the discrete "Download"
1492
- * step an Updates flow runs before an `upgradeGroup`. Resolves the installed
1493
- * application id (`InstallApplicationResponseData`). Downloading does not by
1494
- * itself change what any group runs; pair it with a subsequent upgrade.
1495
- */
1496
- declare function useInstallFromRegistry(): {
1497
- installFromRegistry: (packageName: string, version: string) => Promise<_calimero_network_mero_js.InstallApplicationResponseData | null>;
1498
- loading: boolean;
1499
- error: Error | null;
1500
- };
1501
- /**
1502
- * Kick off a full state re-pull for a context — operator recovery for a
1503
- * context stranded mid-sync. `force` re-pulls even when the node does not
1504
- * flag the context as stranded.
1505
- */
1506
- declare function useResyncContext(): {
1507
- resyncContext: (contextId: string, request?: ResyncContextRequest) => Promise<_calimero_network_mero_js.ResyncContextResponseData | null>;
1508
- loading: boolean;
1509
- error: Error | null;
1510
- };
1511
- declare function useGroupUpgradeStatus(groupId?: string | null): {
1512
- upgradeStatus: GroupUpgradeStatusResponseData;
1513
- loading: boolean;
1514
- error: Error | null;
1515
- refetch: () => Promise<void>;
1516
- };
1517
- declare function useRetryGroupUpgrade(): {
1518
- retryGroupUpgrade: (groupId: string) => Promise<_calimero_network_mero_js.UpgradeGroupResponseData | null>;
1519
- loading: boolean;
1520
- error: Error | null;
1521
- };
1522
- /** Move `childGroupId` under a new parent. */
1523
- declare function useReparentGroup(): {
1524
- reparentGroup: (childGroupId: string, request: ReparentGroupRequest) => Promise<_calimero_network_mero_js.ReparentGroupResponseData | null>;
1525
- loading: boolean;
1526
- error: Error | null;
1527
- };
1528
- declare function useSubgroups(groupId?: string | null): {
1529
- subgroups: SubgroupEntry[];
1530
- loading: boolean;
1531
- error: Error | null;
1532
- refetch: () => Promise<void>;
1533
- };
1534
- declare function useDetachContextFromGroup(): {
1535
- detachContextFromGroup: (groupId: string, contextId: string) => Promise<void | null>;
1536
- loading: boolean;
1537
- error: Error | null;
1538
- };
1539
- /**
1540
- * Subscribe to a namespace's `GroupMigration` events, invoking `onEvent` per
1541
- * frame and unsubscribing on unmount.
1542
- *
1543
- * A non-admin subscriber never sees `CascadeProgress`; core delivers that to
1544
- * namespace admins only, so a UI must not wait on it to decide progress.
1545
- */
1546
- /**
1547
- * Fallback poll cadence for `useMigrationStatus` when the SSE stream is
1548
- * unavailable (no token, a proxy that buffers, an older node) and the caller
1549
- * named no interval of its own. Chosen to match the heartbeat cadence that
1550
- * migration facts actually arrive on; an explicit `pollIntervalMs` overrides it.
1551
- */
1552
- declare const DEFAULT_MIGRATION_POLL_INTERVAL_MS = 5000;
1553
- declare function useMigrationEvents(namespaceId: string | null | undefined, onEvent: (event: GroupMigrationEventData) => void): boolean;
1554
- /**
1555
- * Migration-status rollup for a namespace (skew #3).
1556
- *
1557
- * Live: subscribes to the `GroupMigration` event family and re-reads on each
1558
- * frame. It re-READS rather than folding the event's counters in, because the
1559
- * rollup is recomputed from raw member rows and is the authoritative answer.
1560
- * `pollIntervalMs` stays as the fallback when SSE is unavailable, and when the
1561
- * caller names none it defaults to `DEFAULT_MIGRATION_POLL_INTERVAL_MS` for
1562
- * exactly as long as the stream is down - so the panel can never sit silently
1563
- * frozen with neither transport.
1564
- * Derived counters are null-safe before the first load.
1565
- */
1566
- declare function useMigrationStatus(namespaceId?: string | null, options?: {
1567
- pollIntervalMs?: number;
1568
- }): {
1569
- status: MigrationStatus | null;
1570
- rollup: MigrationStatusRollup | null;
1571
- members: MemberMigrationStatusEntry[];
1572
- allMigrated: boolean;
1573
- /**
1574
- * When this node watched the fleet converge, or `null`. Durable, unlike
1575
- * `allMigrated`, which is recomputed from in-TTL heartbeats and lapses back
1576
- * to false when a member simply goes quiet.
1577
- */
1578
- fleetCompletedAt: number | null;
1579
- membersPendingSignature: number;
1580
- /** Members whose migrate aborted (migration-check failed or apply errored). */
1581
- failed: number;
1582
- loading: boolean;
1583
- error: Error | null;
1584
- refetch: () => Promise<void>;
1585
- };
1586
- /**
1587
- * Bundle-version skew (#2): reads the context's installed `applicationVersion`
1588
- * (semver) and compares it to the app-declared `expected` build constant. Any
1589
- * mismatch (either direction) is `isStale` → "reload to update". Subscribes to
1590
- * `AppVersionChanged` so a live flip updates `appVersion` without a refetch.
1591
- */
1592
- declare function useAppVersion(contextId?: string | null, expected?: string): {
1593
- appVersion: string | undefined;
1594
- expected: string | undefined;
1595
- isStale: boolean;
1596
- loading: boolean;
1597
- error: Error | null;
1598
- refetch: () => Promise<void>;
1599
- };
1600
- /**
1601
- * "Is a newer version available?" for an Updates view. Reads a package's
1602
- * published versions from the registry and compares the newest to the running
1603
- * `currentVersion` (e.g. a context's `applicationVersion`). `updateAvailable`
1604
- * is true only when the registry's newest is strictly greater. This is the
1605
- * registry-side check the admin acts on; gate rendering on admin status at the
1606
- * call site. Pure read — fetching nothing until both `registryUrl` and
1607
- * `packageName` are provided.
1608
- */
1609
- declare function useLatestVersion(registryUrl?: string | null, packageName?: string | null, currentVersion?: string | null): {
1610
- versions: string[];
1611
- latestVersion: string;
1612
- currentVersion: string | null | undefined;
1613
- updateAvailable: boolean;
1614
- loading: boolean;
1615
- error: Error | null;
1616
- refetch: () => Promise<void>;
1617
- };
1618
- /**
1619
- * What app version does this group run, and is there a downloaded-but-not-yet-
1620
- * applied update? Replaces the appKey-vs-installed-blob comparison apps
1621
- * otherwise hand-roll: `pendingApply` is true when the group's `appKey` (the
1622
- * blob it targets) is present, non-zero, and differs from the blob actually
1623
- * installed for its `targetApplicationId`. Deciding whether to render or gate on
1624
- * that status (admin-only actions, etc.) is the call site's job.
1625
- *
1626
- * Resolution stays cheap: the group's record comes from `listNamespaces()` when
1627
- * the id is a namespace, else from `getGroupInfo()`; `getApplication()` then
1628
- * reads the installed version and blob. `activeUpgrade` is returned only when it
1629
- * arrives for free on the group-info path (it is not fetched separately).
1630
- * Subscribes to `AppVersionChanged` and refetches, since any version flip in the
1631
- * workspace can make the rollup stale.
1632
- */
1633
- declare function useGroupAppVersion(groupId?: string): {
1634
- loading: boolean;
1635
- error: Error | null;
1636
- refetch: () => Promise<void>;
1637
- /** Semver of the application the group currently targets (`null` until loaded). */
1638
- version: string | null;
1639
- /** The group's `targetApplicationId`. */
1640
- applicationId: string | null;
1641
- /** The installed blob differs from the one the group targets (see hook doc). */
1642
- pendingApply: boolean;
1643
- /** Only populated via the group-info path; `null` in the namespace path. */
1644
- activeUpgrade: GroupUpgradeStatusResponseData;
1645
- };
1646
- /**
1647
- * The caller's own identity-gated entries pending re-signature (skew #1).
1648
- * `pending` is `pendingCount > 0` (from `count_my_pending`); `authorize()` runs
1649
- * the one-tap `migrate_my_entries` convert and folds the resulting `remaining`
1650
- * back into the count.
1651
- */
1652
- declare function useMyAuthoredMigration(contextId?: string | null): {
1653
- summary: MigrateMyEntriesSummary | null;
1654
- pendingCount: number;
1655
- pending: boolean;
1656
- authorize: () => Promise<MigrateMyEntriesSummary | null>;
1657
- loading: boolean;
1658
- error: Error | null;
1659
- refresh: () => Promise<void>;
1660
- };
1661
- /**
1662
- * Options for the blob READ hooks.
1663
- *
1664
- * `contextId` is what picks the mode, and the two modes have wildly different
1665
- * costs:
1666
- *
1667
- * - **omitted** — local-only read. The node answers from its own blob store
1668
- * and returns immediately, or 404s.
1669
- * - **supplied** — network discovery. The node probes that context's peers
1670
- * (availability nodes first) for a holder. Core bounds the search by a ~30s
1671
- * deadline, and for {@link useBlobUrl} the byte transfer is on top of that.
1672
- *
1673
- * So `loading` is load-bearing UI state on these hooks, not decoration: a
1674
- * discovery read can plausibly spin for half a minute before it resolves
1675
- * either way. Render a spinner (or a cancel affordance) accordingly.
1676
- */
1677
- interface BlobHookOptions {
1678
- /** Context whose peers to probe. Omit for a local-only read. */
1679
- contextId?: string;
1680
- }
1681
- /** Options for {@link useBlobUrl}. */
1682
- interface UseBlobUrlOptions extends BlobHookOptions {
1683
- /**
1684
- * MIME type stamped on the `Blob` the object URL points at. The blob read
1685
- * itself carries no type, and a peer-sourced answer has no `mimeType` at
1686
- * all, so pass it when the consumer needs one (`<img>` sniffs; a download
1687
- * `<a>` and an `<iframe>` do not).
1688
- */
1689
- type?: string;
1690
- }
1691
- /**
1692
- * A blob's presence and size, WITHOUT downloading it — the cheap half of the
1693
- * blob surface, and the one to ask before pulling something large.
1694
- *
1695
- * `blobId` follows the same `string | null` convention as the other read
1696
- * hooks: null/undefined means "no read", not "read nothing" — nothing is
1697
- * fetched and `info` stays null.
1698
- *
1699
- * `hash` and `mimeType` on the result are genuinely optional: a peer probe
1700
- * answers with presence and size only, so a discovery-sourced hit carries
1701
- * neither. `info.source` (`'local' | 'peer'`, undefined on nodes that predate
1702
- * the header) tells the two apart — do not treat a missing `mimeType` as a
1703
- * malformed response.
1704
- *
1705
- * `notFound` distinguishes the legitimate "no holder" outcome (the node
1706
- * answered 404) from a transport failure. `error` is set in BOTH cases — this
1707
- * hook does not swallow the 404, it only labels it.
1708
- *
1709
- * Latency: immediate without `contextId`, up to core's ~30s discovery deadline
1710
- * with one. See {@link BlobHookOptions}.
1711
- */
1712
- declare function useBlobInfo(blobId?: string | null, options?: BlobHookOptions): {
1713
- info: GetBlobInfoResponseData | null;
1714
- notFound: boolean;
1715
- loading: boolean;
1716
- error: Error | null;
1717
- refetch: () => Promise<void>;
1718
- };
1719
- /**
1720
- * A blob's bytes as an object URL, ready for `<img src>`, an `<a href>`
1721
- * download, or an `<iframe>`.
1722
- *
1723
- * Lifecycle is handled here so the consumer never has to revoke: the URL is
1724
- * revoked on unmount, and whenever `blobId`/`contextId`/`type` change. `url`
1725
- * goes back to null synchronously on such a change, so a revoked URL is never
1726
- * handed out as the current one — render off `url` and it is always live.
1727
- *
1728
- * A response for a superseded `blobId` is dropped before an object URL is even
1729
- * created, so an out-of-order arrival can neither overwrite the newer result
1730
- * nor leak.
1731
- *
1732
- * Latency: this is the expensive hook. Without `contextId` it is a local read;
1733
- * with one it is discovery (core's ~30s deadline) PLUS the transfer of the
1734
- * bytes. Prefer {@link useBlobInfo} to decide whether the download is worth
1735
- * starting, and always render `loading`.
1736
- *
1737
- * `notFound` marks the node's 404 ("no peer holds this") apart from a
1738
- * transport failure; `error` is set for both.
1739
- */
1740
- declare function useBlobUrl(blobId?: string | null, options?: UseBlobUrlOptions): {
1741
- url: string | null;
1742
- notFound: boolean;
1743
- loading: boolean;
1744
- error: Error | null;
1745
- refetch: () => Promise<void>;
1746
- };
1747
- /**
1748
- * Upload bytes to the node's blob store. Mutation-shaped, like the other
1749
- * write hooks: `uploadBlob` resolves to `{ blobId, size }`, or null when the
1750
- * client is absent or the call failed (read `error` for which).
1751
- *
1752
- * Pass `contextId` to announce the blob to that context, which is what lets
1753
- * the context's other members later discover it with {@link useBlobUrl} /
1754
- * {@link useBlobInfo}. Without it the blob is only readable on this node.
1755
- */
1756
- declare function useUploadBlob(): {
1757
- uploadBlob: (request: UploadBlobRequest) => Promise<_calimero_network_mero_js.BlobInfo | null>;
1758
- loading: boolean;
1759
- error: Error | null;
1760
- };
1761
-
1762
- /**
1763
- * Storage utilities for mero-react
1764
- *
1765
- * Provides localStorage-based token storage and other persistence utilities.
1766
- */
1767
-
1768
- declare const localStorageTokenStorage: {
1769
- get(): Promise<TokenData | null>;
1770
- set(token: TokenData): Promise<void>;
1771
- clear(): Promise<void>;
1772
- };
1773
- /**
1774
- * Get the stored node URL
1775
- */
1776
- declare function getNodeUrl(): string | null;
1777
- /**
1778
- * Set the node URL
1779
- */
1780
- declare function setNodeUrl(url: string): void;
1781
- /**
1782
- * Clear the node URL
1783
- */
1784
- declare function clearNodeUrl(): void;
1785
- /**
1786
- * Get the node URL that minted the token bundle currently in the TokenStore.
1787
- */
1788
- declare function getTokenNodeUrl(): string | null;
1789
- /**
1790
- * Record the node URL that minted the token bundle now in the TokenStore.
1791
- */
1792
- declare function setTokenNodeUrl(url: string): void;
1793
- /**
1794
- * Clear the token bundle's node URL
1795
- */
1796
- declare function clearTokenNodeUrl(): void;
1797
- /**
1798
- * Get the stored application ID
1799
- */
1800
- declare function getApplicationId(): string | null;
1801
- /**
1802
- * Set the application ID
1803
- */
1804
- declare function setApplicationId(id: string): void;
1805
- /**
1806
- * Clear the application ID
1807
- */
1808
- declare function clearApplicationId(): void;
1809
- /**
1810
- * Get the stored context ID
1811
- */
1812
- declare function getContextId(): string | null;
1813
- /**
1814
- * Set the context ID
1815
- */
1816
- declare function setContextId(id: string): void;
1817
- /**
1818
- * Clear the context ID
1819
- */
1820
- declare function clearContextId(): void;
1821
- /**
1822
- * Get the stored context identity
1823
- */
1824
- declare function getContextIdentity(): string | null;
1825
- /**
1826
- * Set the context identity
1827
- */
1828
- declare function setContextIdentity(id: string): void;
1829
- /**
1830
- * Clear the context identity
1831
- */
1832
- declare function clearContextIdentity(): void;
1833
- /**
1834
- * Clear all mero-react storage
1835
- */
1836
- declare function clearAllStorage(): void;
1837
-
1838
- /**
1839
- * Is this page running inside a Calimero Desktop (Tauri) window?
1840
- *
1841
- * The desktop opens every app in its own webview, already bound to the node it
1842
- * runs, so the Cloud sign-in (wallet → relay, no node) is the wrong door there:
1843
- * it would leave the desktop's own node behind, and the wallet redirect would
1844
- * navigate the app window off to another origin.
1845
- *
1846
- * Two signals, either is enough:
1847
- * - `__TAURI_INTERNALS__` with a callable `invoke`, which Tauri injects natively
1848
- * into every webview it creates, remote URLs included;
1849
- * - `__TAURI_FETCH_PROXY_INJECTED__`, the marker the desktop's app-window
1850
- * init script sets, in case a future Tauri stops exposing the former there.
1851
- *
1852
- * Read at call time and SSR-safe: false whenever there is no `window`.
1853
- */
1854
- declare function isDesktopWindow(): boolean;
1855
-
1856
- export { type AccountEnrolment, AccountSignInPanel, type AccountSignInPanelProps, type AppContext, AppMode, type ApplicationContextRecord, type BlobHookOptions, CalimeroLogo, type CalimeroLogoProps, type CapturedInvitation, ConnectButton, ConnectButtonAccount, type ConnectButtonAccountProps, type ConnectButtonProps, ConnectionType, type ContextDiscoveryOptions, type ContextDiscoveryState, type CreatePrivateContextRequest, type CustomConnectionConfig, DEFAULT_MIGRATION_POLL_INTERVAL_MS, type ExecutionResult, INVITATION_PARAM, INVITATION_READY_MS, InvitationDialog, type InvitationDialogProps, type InvitationDialogStage, InvitationGate, type InvitationGateProps, type InviteRedemption, type InviteState, JOIN_ACTION, JOIN_SYNC_MAX_MS, JOIN_SYNC_POLL_MS, JOIN_SYNC_WATCHDOG_MS, type JoinFailureReason, type JoinInvitationInput, type JoinInvitationResult, type JoinInvitationStep, JoinSyncBanner, type JoinSyncBannerProps, type JoinSyncOptions, type JoinSyncState, LoginModal, type LoginModalProps, type LoginModalTab, MAX_AUTO_JOIN_ATTEMPTS, MERO_CSS_VARS, type MeroCapabilities, MeroContext, type MeroContextValue, MeroProvider, type MeroProviderConfig, type MeroProviderProps, type MeroTheme, MigrationAdminPanel, type MigrationAdminPanelProps, MigrationPendingBanner, type MigrationPendingBannerProps, type MutationOptions, type ParsedInvitation, type ResolvedMeroTheme, type SetMetadataInput, type SubscriptionEventData, type SubscriptionInput, type UseAccountEnrolmentOptions, type UseBlobUrlOptions, type UseDelegatedBootstrapOptions, type UseDelegatedBootstrapResult, type UseEphemeralOptions, type UseEphemeralResult, type UseInviteRedemptionOptions, buildInviteLink, clearAllStorage, clearApplicationId, clearContextId, clearContextIdentity, clearNamespaceJustJoined, clearNodeUrl, clearTokenNodeUrl, cssVar, defaultMeroTheme, describeInviteFailure, getApplicationId, getContextId, getContextIdentity, getNodeUrl, getPermissionsForMode, getTokenNodeUrl, invitationFromRaw, isDesktopWindow, isFinalInvitationError, isNamespaceJustJoined, isReturningFromWallet, localStorageTokenStorage, markNamespaceJustJoined, onInvitation, peekInvitation, primeInvitationCapture, resetInvitationCaptureForTests, resolveMeroTheme, setApplicationId, setContextId, setContextIdentity, setNodeUrl, setTokenNodeUrl, subscribeInvitation, subscribeJustJoined, themeToCssVars, urlWithoutInvitation, useAccountEnrolment, useAddGroupMembers, useAppVersion, useApplicationContexts, useBlobInfo, useBlobUrl, useContextDiscovery, useContextGroup, useContexts, useCreateContext, useCreateGroupInNamespace, useCreateNamespace, useCreateNamespaceInvitation, useCreatePrivateContext, useDefaultCapabilities, useDelegatedBootstrap, useDeleteContext, useDeleteGroup, useDeleteNamespace, useDetachContextFromGroup, useEphemeral, useExecute, useGroupAppVersion, useGroupCapabilities, useGroupContexts, useGroupInfo, useGroupInvitations, useGroupMembers, useGroupMetadata, useGroupUpgradeStatus, useInstallFromRegistry, useInviteRedemption, useJoinContext, useJoinGroup, useJoinInvitation, useJoinNamespace, useJoinSubgroupInheritance, useJoinSync, useLatestVersion, useMemberMetadata, useMero, useMigrationEvents, useMigrationStatus, useMyAuthoredMigration, useNamespace, useNamespaceGroups, useNamespaces, useNamespacesForApplication, useNodeIdentity, usePendingInvitation, useRedeemInvitation, useRemoveGroupMembers, useReparentGroup, useResyncContext, useRetryGroupUpgrade, useSetContextMetadata, useSetDefaultCapabilities, useSetGroupMetadata, useSetMemberMetadata, useSetSubgroupVisibility, useSetTeeAdmissionPolicy, useSubgroupVisibility, useSubgroups, useSubscription, useSyncGroup, useUpdateMemberRole, useUpgradeGroup, useUploadBlob };
1021
+ export { type AppEvent, type AsyncState, type BlobHookOptions, CalimeroLogo, type CalimeroLogoProps, type CallOptions, type Codec, ConnectButton, type ConnectButtonProps, type CreateApiKeyInput, type CreateAppInput, type CreateInviteInput, type CreateTeamInput, type EphemeralEntry, type Failure, type FailureKind, type InviteRedemption, type InviteRedemptionStatus, LoginModal, type LoginModalProps, type LoginModalTab, MERO_CSS_VARS, MeroContext, type MeroContextValue, MeroProvider, type MeroProviderConfig, type MeroProviderProps, type MeroTheme, type MutationOptions, NoAppError, NotConnectedError, type OrgRole, type PolicyOptions, type ResolvedMeroTheme, type ResourceState, SessionReportingClient, type SessionStore, type SubscriptionEventData, type SubscriptionOptions, type TeamJoin, type TeamRole, type TeamUpdate, type UpgradeTarget, type UseBlobUrlOptions, type UseEphemeralOptions, type UseEphemeralResult, type UseViewOptions, type UseViewResult, type ViewOptions, type WaitOptions, clearAllStorage, clearAppId, clearCluster, clearNodeUrl, cssVar, defaultMeroTheme, describeError, followEvents, getAppId, getCluster, getNodeUrl, inviteLink, isLoginRequired, jsonCodec, localStorageSessionStore, memorySessionStore, readInviteToken, reportSessions, resolveMeroTheme, resolvePolicy, setAppId, setCluster, setNodeUrl, shortAccount, themeToCssVars, useAccount, useApiKeys, useApp, useAppAbi, useApps, useBlobInfo, useBlobUrl, useBlobs, useConsent, useCreateApp, useCreateInvite, useCreateOrg, useCreateTeam, useDeleteApp, useDeleteBlob, useDeleteOrg, useDeleteTeam, useEphemeral, useExecute, useInviteRedemption, useMero, useOrg, usePackages, usePasskeys, useRedeemInvite, useRemoveMember, useRemoveTeamMember, useSetAppMetadata, useSetCapabilities, useSetMember, useSetMemberMetadata, useSetOrgMetadata, useSetTeamMember, useSubscription, useTeam, useUpdateTeam, useUpgradeApp, useUploadBlob, useView };