@calimero-network/mero-react 10.3.0 → 11.0.0

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