@haex-space/vault-sdk 4.8.1 → 4.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1164,6 +1164,67 @@ unknown job rejects it with an error.
1164
1164
  `models.startAsync`, `models.onCompleted` and `models.cancelAsync` give you the job's id and its end
1165
1165
  separately. A job has no tools and sees only the input you send.
1166
1166
 
1167
+ The choice of models stays with the user in the host; your extension shows no model picker of its
1168
+ own. To ask before the first job, for example when your extension opens for the first time, call
1169
+ `models.requestAccessAsync({ needs: ["text", "image"], effort: "low" })`: it resolves with the
1170
+ allowed models that fit, or the host asks the user as it would for a job. It rejects with
1171
+ `no_capable_model` when no model of the host fits; offer `models.openSettingsAsync()` then, which
1172
+ opens the host's page of your extension's models. Nothing is sent to a model, and consent for a
1173
+ destination outside the device comes with the first job that sends data.
1174
+
1175
+ ### Peers
1176
+
1177
+ Channels between frames of your extension on devices of different vaults, for example a multiplayer
1178
+ game. Declare the permission in `manifest.json`; inviting a contact also needs read access to that
1179
+ contact:
1180
+
1181
+ ```json
1182
+ "permissions": {
1183
+ "peers": [{ "target": "*", "action": "connect" }],
1184
+ "contacts": [{ "target": "*", "action": "read" }]
1185
+ }
1186
+ ```
1187
+
1188
+ A channel starts in one of two ways:
1189
+
1190
+ - **Invitation.** `peers.inviteAsync(contactId, payload)` reaches all devices of the contact. The
1191
+ invited user accepts or declines only in the vault's own prompt; the SDK has no accept or decline,
1192
+ and your extension learns of the invitation only after it was accepted, as `channel-opened`
1193
+ (the vault opens your extension first if needed). The inviting side gets `invite-status` exactly
1194
+ once: `accepted` (with `channelId`), `declined`, `not-installed`, `unreachable` (with
1195
+ `hint: "share_current_card"`: ask the contact to share a current card) or `expired`.
1196
+ `cancelInviteAsync(inviteId)` withdraws an open invitation.
1197
+ - **Lobby.** `peers.openLobbyAsync(lobbyId, "contacts" | "public")` returns a join code that starts
1198
+ with `haex-vault:join:`; treat it as opaque text and hand it on. Another device joins with
1199
+ `peers.joinAsync(joinCode, displayName, payload)` and gets `{ channelId, lobbyId }`; the host gets
1200
+ `joined`. A contacts-only lobby admits only the host's contacts. `closeLobbyAsync` stops the code,
1201
+ open channels stay; `removeAsync(channelId)` closes a channel of your lobby and keeps that device
1202
+ out.
1203
+
1204
+ ```ts
1205
+ const peers = client.peers;
1206
+ peers.on("channel-opened", ({ channelId, from, payload }) => startGame(channelId, from.name, payload));
1207
+ peers.on("message", ({ channelId, data, reliable }) => receive(channelId, data, reliable));
1208
+ peers.on("channel-closed", ({ channelId, reason }) => dropPlayer(channelId, reason)); // closed, lost, timeout
1209
+
1210
+ const { joinCode } = await peers.openLobbyAsync("doom-1", "public");
1211
+ peers.on("joined", ({ channelId, displayName, verified }) => addPlayer(channelId, displayName, verified));
1212
+
1213
+ await peers.sendAsync(channelId, packet); // fast, may be lost
1214
+ await peers.sendAsync(channelId, state, { reliable: true }); // in order
1215
+ await peers.closeAsync(channelId); // both sides get channel-closed
1216
+ ```
1217
+
1218
+ Limits: a fast message holds at most `peers.MAX_FAST_BYTES` (1,024) bytes, a reliable one
1219
+ `peers.MAX_RELIABLE_BYTES` (65,536); at most 16 reliable messages may wait per channel. The `payload`
1220
+ of an invitation or a join is JSON of at most `peers.MAX_PAYLOAD_BYTES` (4,096) bytes. Host errors
1221
+ with a reason reject as `PeerError` with the host's `code`, its `reason` (`contact_unknown`,
1222
+ `invite_not_open`, `channel_unknown`, `channel_closed`, `lobby_closed`, `not_admitted`, `too_large`,
1223
+ `limit`, `network_unavailable`, `invalid_input`), a `kind` such as `PEER_LOBBY_CLOSED`, and `limit`
1224
+ for `too_large` and `limit`. `not_admitted` shares code 1002 with a refused permission; tell them
1225
+ apart by `reason`. When your extension's last frame on a device closes, the vault closes its
1226
+ channels and lobbies and withdraws its open invitations.
1227
+
1167
1228
  ### Database Operations
1168
1229
 
1169
1230
  #### Query
@@ -1,4 +1,4 @@
1
- import { b as HaexHubEvent, c as EXTERNAL_EVENTS, D as DatabaseQueryResult, M as Migration, d as MigrationResult, W as WebRequestOptions, e as WebResponse, f as EventCallback, a as ExtensionManifest, H as HaexHubConfig, E as ExtensionInfo, A as ApplicationContext, g as DatabasePermissionRequest, P as PermissionResponse, S as SearchResult, R as RequestOptions } from './types-3iifP-Q1.js';
1
+ import { b as HaexHubEvent, c as EXTERNAL_EVENTS, D as DatabaseQueryResult, M as Migration, d as MigrationResult, W as WebRequestOptions, e as WebResponse, f as EventCallback, a as ExtensionManifest, H as HaexHubConfig, E as ExtensionInfo, A as ApplicationContext, g as DatabasePermissionRequest, P as PermissionResponse, S as SearchResult, R as RequestOptions } from './types-BZVkX0Wf.mjs';
2
2
  import { SqliteRemoteDatabase } from 'drizzle-orm/sqlite-proxy';
3
3
 
4
4
  /**
@@ -1700,6 +1700,12 @@ interface ExtensionModel {
1700
1700
  /** The highest effort the user allowed. */
1701
1701
  maxEffort: ModelEffort;
1702
1702
  }
1703
+ /** What a job of the extension will need, to ask for a grant before it (holzi spec 055 US9). */
1704
+ interface ModelAccessRequest {
1705
+ needs: ("text" | "image")[];
1706
+ /** The effort the extension wishes for; the user chooses the ceiling. */
1707
+ effort?: ModelEffort;
1708
+ }
1703
1709
  /** An image as Base64, at most 25 MiB raw; at most 8 per job. */
1704
1710
  interface ModelJobImage {
1705
1711
  mimeType: "image/jpeg" | "image/png" | "image/webp";
@@ -1780,13 +1786,25 @@ interface ModelJobCompletion {
1780
1786
  *
1781
1787
  * The user decides at run time: the first job asks which model the extension may use and up to
1782
1788
  * which effort, and before data goes to a destination outside this device it asks for consent.
1783
- * The SDK waits for these answers and starts the job again, like for every other permission.
1789
+ * The SDK waits for these answers and starts the job again, like for every other permission. The
1790
+ * choice stays with the host: {@link requestAccessAsync} asks before the first job, and
1791
+ * {@link openSettingsAsync} leads the user to the host's page of this extension's models.
1784
1792
  */
1785
1793
  declare class ModelsAPI {
1786
1794
  private client;
1787
1795
  constructor(client: HaexVaultSdk);
1788
1796
  /** The models the user allowed to this extension; empty without any. */
1789
1797
  listAsync(): Promise<ExtensionModel[]>;
1798
+ /**
1799
+ * Asks for a grant before the first job (holzi spec 055 US9) and resolves with the allowed
1800
+ * models that fit `needs`. Without one, the host asks the user as it would for a job, and the
1801
+ * SDK waits for the answer. Rejects with `no_capable_model` (8001) when no model of the host
1802
+ * fits and with a denial (1002) when the user refused. Nothing is sent to a model, and consent
1803
+ * for a destination outside this device is asked with the first job that sends data.
1804
+ */
1805
+ requestAccessAsync(request: ModelAccessRequest): Promise<ExtensionModel[]>;
1806
+ /** Opens the host's page of this extension's models, where the user chooses models and effort. */
1807
+ openSettingsAsync(): Promise<void>;
1790
1808
  /** Starts a job; its end comes as {@link onCompleted}. Use {@link runAsync} to await it. */
1791
1809
  startAsync(job: ModelJob): Promise<{
1792
1810
  jobId: string;
@@ -1811,6 +1829,177 @@ declare class ModelsAPI {
1811
1829
  }): Promise<ModelJobCompletion>;
1812
1830
  }
1813
1831
 
1832
+ /**
1833
+ * Types of peer channels (holzi spec 057, `contracts/bridge.md` and `contracts/sdk.md`): channels
1834
+ * between frames of the same extension on devices of different vaults.
1835
+ */
1836
+ /** Who may join a lobby by its code: only the host's contacts, or anyone holding the code. */
1837
+ type PeerVisibility = "contacts" | "public";
1838
+ /**
1839
+ * The outcome of an invitation (`peers:invite-status`), exactly once per invitation, on the
1840
+ * inviting side.
1841
+ */
1842
+ interface PeerInviteStatus {
1843
+ inviteId: string;
1844
+ status: "accepted" | "declined" | "not-installed" | "unreachable" | "expired";
1845
+ /** Only with `accepted`: the channel to the invited device. */
1846
+ channelId?: string;
1847
+ /** Only with `unreachable`: ask the contact to share a current card. */
1848
+ hint?: "share_current_card";
1849
+ }
1850
+ /**
1851
+ * A channel opened by an invitation the user accepted in holzi's prompt (`peers:channel-opened`),
1852
+ * on the invited side.
1853
+ */
1854
+ interface PeerChannelOpened {
1855
+ channelId: string;
1856
+ origin: "invitation";
1857
+ inviteId: string;
1858
+ from: {
1859
+ /** Only when the extension's `contacts` permission covers this contact. */
1860
+ contactId?: string;
1861
+ /** The name on the other vault's card, not the display name of the address book. */
1862
+ name: string;
1863
+ };
1864
+ /** The JSON the inviting extension sent with the invitation. */
1865
+ payload: unknown;
1866
+ }
1867
+ /** A device that joined one of this device's lobbies by code (`peers:joined`), on the host. */
1868
+ interface PeerJoined {
1869
+ lobbyId: string;
1870
+ channelId: string;
1871
+ /** Chosen by the joining user and unchecked. */
1872
+ displayName: string;
1873
+ /** `true` when the joining device belongs to a contact. */
1874
+ verified: boolean;
1875
+ /** Only when the extension's `contacts` permission covers this contact. */
1876
+ contactId?: string;
1877
+ /** The JSON the joining extension sent with the join. */
1878
+ payload: unknown;
1879
+ }
1880
+ /** A message on a channel (`peers:message`), with its data decoded from Base64. */
1881
+ interface PeerMessage {
1882
+ channelId: string;
1883
+ data: Uint8Array;
1884
+ reliable: boolean;
1885
+ }
1886
+ /**
1887
+ * The end of a channel (`peers:channel-closed`): `closed` by either side, `lost` when a reliable
1888
+ * message could not be delivered, `timeout` when the other side stopped answering.
1889
+ */
1890
+ interface PeerChannelClosed {
1891
+ channelId: string;
1892
+ reason: "closed" | "lost" | "timeout";
1893
+ }
1894
+ /** The events of `client.peers.on`, by their name without the `peers:` prefix. */
1895
+ interface PeerEventMap {
1896
+ "invite-status": PeerInviteStatus;
1897
+ "channel-opened": PeerChannelOpened;
1898
+ joined: PeerJoined;
1899
+ message: PeerMessage;
1900
+ "channel-closed": PeerChannelClosed;
1901
+ }
1902
+ type PeerEventType = keyof PeerEventMap;
1903
+ /** The `details.reason` of a host error of a peers method. */
1904
+ type PeerErrorReason = "contact_unknown" | "invite_not_open" | "channel_unknown" | "channel_closed" | "lobby_closed" | "not_admitted" | "too_large" | "limit" | "network_unavailable" | "invalid_input";
1905
+
1906
+ /**
1907
+ * The name of each `details.reason` in haex-doom's draft of this API; `limit`,
1908
+ * `network_unavailable` and `invalid_input` are new there.
1909
+ */
1910
+ declare const PEER_ERROR_KINDS: {
1911
+ readonly contact_unknown: "PEER_CONTACT_UNKNOWN";
1912
+ readonly invite_not_open: "PEER_INVITE_UNKNOWN";
1913
+ readonly channel_unknown: "PEER_CHANNEL_CLOSED";
1914
+ readonly channel_closed: "PEER_CHANNEL_CLOSED";
1915
+ readonly too_large: "PEER_PAYLOAD_TOO_LARGE";
1916
+ readonly lobby_closed: "PEER_LOBBY_CLOSED";
1917
+ readonly not_admitted: "PEER_NOT_ALLOWED";
1918
+ readonly limit: "PEER_LIMIT";
1919
+ readonly network_unavailable: "PEER_NETWORK_UNAVAILABLE";
1920
+ readonly invalid_input: "PEER_INVALID_INPUT";
1921
+ };
1922
+ type PeerErrorKind = (typeof PEER_ERROR_KINDS)[PeerErrorReason];
1923
+ /**
1924
+ * A host error of a peers method that names its `details.reason`. `code` stays the host's number
1925
+ * (1001, 1002, 3001, 7000, 8001); `not_admitted` shares 1002 with a refused permission, so tell
1926
+ * them apart by `reason`. The host's error is kept as `cause`.
1927
+ */
1928
+ declare class PeerError extends Error {
1929
+ readonly code: number;
1930
+ readonly reason: PeerErrorReason;
1931
+ readonly details: Record<string, unknown>;
1932
+ readonly kind: PeerErrorKind;
1933
+ /** The host's `details.limit` with `too_large` (bytes) and `limit` (count). */
1934
+ readonly limit?: number;
1935
+ constructor(code: number, reason: PeerErrorReason, message: string, details?: Record<string, unknown>, options?: {
1936
+ cause?: unknown;
1937
+ });
1938
+ }
1939
+ /**
1940
+ * Channels between frames of this extension on devices of different vaults (holzi spec 057).
1941
+ * Needs the `peers` permission (`{ target: "*", action: "connect" }`); inviting a contact also
1942
+ * needs `contacts` read access to that contact.
1943
+ *
1944
+ * A channel starts in one of two ways. An invitation goes to all devices of a contact; the user
1945
+ * accepts or declines it only in holzi's own prompt, so the SDK has no accept or decline. The
1946
+ * invited side gets `channel-opened`, the inviting side `invite-status`. A lobby hands out an
1947
+ * opaque join code (`haex-vault:join:…`); a device that joins with it gets the channel from
1948
+ * {@link PeersAPI.joinAsync}, the host gets `joined`.
1949
+ *
1950
+ * Errors with a `details.reason` reject as {@link PeerError}; others reject unchanged.
1951
+ */
1952
+ declare class PeersAPI {
1953
+ private client;
1954
+ /** Largest fast message (`reliable: false`) in bytes. */
1955
+ readonly MAX_FAST_BYTES = 1024;
1956
+ /** Largest reliable message in bytes. */
1957
+ readonly MAX_RELIABLE_BYTES = 65536;
1958
+ /** Largest `payload` of an invitation or a join, as JSON, in bytes. */
1959
+ readonly MAX_PAYLOAD_BYTES = 4096;
1960
+ constructor(client: HaexVaultSdk);
1961
+ private call;
1962
+ /** Invites a contact; the outcome follows as `invite-status` with this `inviteId`. */
1963
+ inviteAsync(contactId: string, payload: unknown): Promise<{
1964
+ inviteId: string;
1965
+ }>;
1966
+ /** Withdraws an open invitation on all devices of the contact; no `invite-status` follows. */
1967
+ cancelInviteAsync(inviteId: string): Promise<void>;
1968
+ /**
1969
+ * Opens a lobby; `lobbyId` is 1–64 characters of `[A-Za-z0-9._-]`. The join code is opaque:
1970
+ * hand it on as it is.
1971
+ */
1972
+ openLobbyAsync(lobbyId: string, visibility: PeerVisibility): Promise<{
1973
+ joinCode: string;
1974
+ }>;
1975
+ /** Closes a lobby: its code stops working, its channels stay open. An unknown lobby is fine. */
1976
+ closeLobbyAsync(lobbyId: string): Promise<void>;
1977
+ /**
1978
+ * Joins a lobby by its code with a self-chosen `displayName` (1–64 characters). The host
1979
+ * answers within 15 s; a lobby that cannot be joined for any reason rejects as `lobby_closed`.
1980
+ */
1981
+ joinAsync(joinCode: string, displayName: string, payload: unknown): Promise<{
1982
+ channelId: string;
1983
+ lobbyId: string;
1984
+ }>;
1985
+ /** Closes a channel of an own lobby and keeps that device (and vault) out of the lobby. */
1986
+ removeAsync(channelId: string): Promise<void>;
1987
+ /**
1988
+ * Sends bytes over a channel: fast (default, at most {@link MAX_FAST_BYTES}, may be lost) or
1989
+ * `reliable` (at most {@link MAX_RELIABLE_BYTES}, in order; 16 may wait per channel).
1990
+ */
1991
+ sendAsync(channelId: string, data: Uint8Array, options?: {
1992
+ reliable?: boolean;
1993
+ }): Promise<void>;
1994
+ /** Closes a channel; both sides get `channel-closed` with `reason: "closed"`. */
1995
+ closeAsync(channelId: string): Promise<void>;
1996
+ /**
1997
+ * Listens for one of the peers events (`invite-status`, `channel-opened`, `joined`, `message`,
1998
+ * `channel-closed`); `message.data` arrives as bytes. Returns an unsubscribe function.
1999
+ */
2000
+ on<T extends PeerEventType>(type: T, handler: (event: PeerEventMap[T]) => void): () => void;
2001
+ }
2002
+
1814
2003
  /**
1815
2004
  * Mail types — IMAP fetch + SMTP send.
1816
2005
  *
@@ -2290,6 +2479,7 @@ declare class HaexVaultSdk {
2290
2479
  readonly passwords: PasswordsAPI;
2291
2480
  readonly contacts: ContactsAPI;
2292
2481
  readonly models: ModelsAPI;
2482
+ readonly peers: PeersAPI;
2293
2483
  readonly mail: MailAPI;
2294
2484
  readonly notifications: NotificationsAPI;
2295
2485
  readonly tab: TabAPI;
@@ -2346,5 +2536,5 @@ declare class HaexVaultSdk {
2346
2536
  private log;
2347
2537
  }
2348
2538
 
2349
- export { DatabaseAPI as D, HaexVaultSdk as H, FilesystemAPI as L, KnownPath as N, LOCALSEND_EVENTS as P, LocalSendAPI as Q, StorageAPI as S, MailAPI as V, RemoteStorageAPI as aB, ShellAPI as aO, SpacesAPI as a_, ModelsAPI as ae, NotificationsAPI as ai, PasswordsAPI as aq, PermissionsAPI as at, TabAPI as b0, ToolsAPI as b3, WebAPI as b7, canExternalClientSendRequests as b8, isExternalClientConnected as b9, ContactsAPI as i, DialogAPI as o, EncryptedFoldersAPI as t, ExternalConnectionErrorCode as x, ExternalConnectionState as y };
2350
- export type { MailNewMessagesEvent as $, AuthorizedClient as A, BlockedClient as B, ConfirmOptions as C, EncryptedFolderAccess as E, ExternalRequestEvent as F, ExternalRequestHandler as G, ExternalRequestPayload as I, ExternalResponse as J, FileStat as K, ImapConfig as M, KnownPaths as O, LocalSendEvent as R, FileInfo as T, LocalSendSettings as U, MailAccount as W, MailAddress as X, Attachment as Y, FetchRange as Z, MailMessage as _, ConnectionSecurity as a, SyncBackendInfo as a$, MailSearchCriteria as a0, MailSearchResult as a1, MailboxInfo as a2, MessageEnvelope as a3, ModelEffort as a4, ModelJob as a5, ModelJobAttempt as a6, ModelJobCompletion as a7, ModelJobErrorCode as a8, ModelJobFormat as a9, SftpProposal as aA, StorageBackendInfo as aC, StorageBackendType as aD, StorageObjectInfo as aE, UpdateBackendRequest as aF, WebDavProposal as aG, RequestedExtension as aH, SelectFileOptions as aI, SelectFolderOptions as aJ, ServerInfo as aK, ServerStatus as aL, SessionAuthorization as aM, SharedSpace as aN, ShellCreateOptions as aP, ShellCreateResponse as aQ, ShellExitEvent as aR, ShellOutputEvent as aS, SmtpConfig as aT, SpaceAccessTokenInfo as aU, SpaceAssignment as aV, SpaceInvite as aW, SpaceKeyGrantInfo as aX, SpaceMember as aY, SpaceMemberInfo as aZ, ModelJobImage as aa, ModelJobProvenance as ab, ModelJobStep as ac, ModelPlace as ad, NotificationAction as af, NotificationClickEvent as ag, NotificationOptions as ah, OutgoingAttachment as aj, OutgoingMessage as ak, PasswordInput as al, PasswordItemFull as am, PasswordItemSummary as an, PasswordKeyValue as ao, PasswordKeyValueInput as ap, PendingAuthorization as ar, PendingTransfer as as, AddBackendRequest as au, FolderBackendInfo as av, S3BackendInfo as aw, S3Config as ax, S3Proposal as ay, S3PublicConfig as az, ContactDetail as b, ToolContext as b1, ToolHandler as b2, TransferDirection as b4, TransferProgress as b5, TransferState as b6, ContactHolziAddresses as c, ContactHolziDevice as d, ContactList as e, ContactListOptions as f, ContactSummary as g, ContactValue as h, DecryptedSpace as j, DeepLink as k, Device as l, DeviceInfo as m, DeviceType as n, DirEntry as p, EncryptedFolderChoice as q, EncryptedFolderEntry as r, EncryptedFolderProviderErrorKind as s, ExtensionModel as u, ExternalAuthDecision as v, ExternalConnection as w, ExternalRequest as z };
2539
+ export { DatabaseAPI as D, HaexVaultSdk as H, FilesystemAPI as L, KnownPath as N, LOCALSEND_EVENTS as P, LocalSendAPI as Q, StorageAPI as S, MailAPI as V, PeersAPI as aE, PermissionsAPI as aH, RemoteStorageAPI as aP, ModelsAPI as af, NotificationsAPI as aj, PEER_ERROR_KINDS as am, PasswordsAPI as as, PeerError as av, ShellAPI as b0, SpacesAPI as bc, TabAPI as be, ToolsAPI as bh, WebAPI as bl, canExternalClientSendRequests as bm, isExternalClientConnected as bn, ContactsAPI as i, DialogAPI as o, EncryptedFoldersAPI as t, ExternalConnectionErrorCode as x, ExternalConnectionState as y };
2540
+ export type { MailNewMessagesEvent as $, AuthorizedClient as A, BlockedClient as B, ConfirmOptions as C, EncryptedFolderAccess as E, ExternalRequestEvent as F, ExternalRequestHandler as G, ExternalRequestPayload as I, ExternalResponse as J, FileStat as K, ImapConfig as M, KnownPaths as O, LocalSendEvent as R, FileInfo as T, LocalSendSettings as U, MailAccount as W, MailAddress as X, Attachment as Y, FetchRange as Z, MailMessage as _, ConnectionSecurity as a, SharedSpace as a$, MailSearchCriteria as a0, MailSearchResult as a1, MailboxInfo as a2, MessageEnvelope as a3, ModelAccessRequest as a4, ModelEffort as a5, ModelJob as a6, ModelJobAttempt as a7, ModelJobCompletion as a8, ModelJobErrorCode as a9, PeerInviteStatus as aA, PeerJoined as aB, PeerMessage as aC, PeerVisibility as aD, PendingAuthorization as aF, PendingTransfer as aG, AddBackendRequest as aI, FolderBackendInfo as aJ, S3BackendInfo as aK, S3Config as aL, S3Proposal as aM, S3PublicConfig as aN, SftpProposal as aO, StorageBackendInfo as aQ, StorageBackendType as aR, StorageObjectInfo as aS, UpdateBackendRequest as aT, WebDavProposal as aU, RequestedExtension as aV, SelectFileOptions as aW, SelectFolderOptions as aX, ServerInfo as aY, ServerStatus as aZ, SessionAuthorization as a_, ModelJobFormat as aa, ModelJobImage as ab, ModelJobProvenance as ac, ModelJobStep as ad, ModelPlace as ae, NotificationAction as ag, NotificationClickEvent as ah, NotificationOptions as ai, OutgoingAttachment as ak, OutgoingMessage as al, PasswordInput as an, PasswordItemFull as ao, PasswordItemSummary as ap, PasswordKeyValue as aq, PasswordKeyValueInput as ar, PeerChannelClosed as at, PeerChannelOpened as au, PeerErrorKind as aw, PeerErrorReason as ax, PeerEventMap as ay, PeerEventType as az, ContactDetail as b, ShellCreateOptions as b1, ShellCreateResponse as b2, ShellExitEvent as b3, ShellOutputEvent as b4, SmtpConfig as b5, SpaceAccessTokenInfo as b6, SpaceAssignment as b7, SpaceInvite as b8, SpaceKeyGrantInfo as b9, SpaceMember as ba, SpaceMemberInfo as bb, SyncBackendInfo as bd, ToolContext as bf, ToolHandler as bg, TransferDirection as bi, TransferProgress as bj, TransferState as bk, ContactHolziAddresses as c, ContactHolziDevice as d, ContactList as e, ContactListOptions as f, ContactSummary as g, ContactValue as h, DecryptedSpace as j, DeepLink as k, Device as l, DeviceInfo as m, DeviceType as n, DirEntry as p, EncryptedFolderChoice as q, EncryptedFolderEntry as r, EncryptedFolderProviderErrorKind as s, ExtensionModel as u, ExternalAuthDecision as v, ExternalConnection as w, ExternalRequest as z };
@@ -1,4 +1,4 @@
1
- import { b as HaexHubEvent, c as EXTERNAL_EVENTS, D as DatabaseQueryResult, M as Migration, d as MigrationResult, W as WebRequestOptions, e as WebResponse, f as EventCallback, a as ExtensionManifest, H as HaexHubConfig, E as ExtensionInfo, A as ApplicationContext, g as DatabasePermissionRequest, P as PermissionResponse, S as SearchResult, R as RequestOptions } from './types-3iifP-Q1.mjs';
1
+ import { b as HaexHubEvent, c as EXTERNAL_EVENTS, D as DatabaseQueryResult, M as Migration, d as MigrationResult, W as WebRequestOptions, e as WebResponse, f as EventCallback, a as ExtensionManifest, H as HaexHubConfig, E as ExtensionInfo, A as ApplicationContext, g as DatabasePermissionRequest, P as PermissionResponse, S as SearchResult, R as RequestOptions } from './types-BZVkX0Wf.js';
2
2
  import { SqliteRemoteDatabase } from 'drizzle-orm/sqlite-proxy';
3
3
 
4
4
  /**
@@ -1700,6 +1700,12 @@ interface ExtensionModel {
1700
1700
  /** The highest effort the user allowed. */
1701
1701
  maxEffort: ModelEffort;
1702
1702
  }
1703
+ /** What a job of the extension will need, to ask for a grant before it (holzi spec 055 US9). */
1704
+ interface ModelAccessRequest {
1705
+ needs: ("text" | "image")[];
1706
+ /** The effort the extension wishes for; the user chooses the ceiling. */
1707
+ effort?: ModelEffort;
1708
+ }
1703
1709
  /** An image as Base64, at most 25 MiB raw; at most 8 per job. */
1704
1710
  interface ModelJobImage {
1705
1711
  mimeType: "image/jpeg" | "image/png" | "image/webp";
@@ -1780,13 +1786,25 @@ interface ModelJobCompletion {
1780
1786
  *
1781
1787
  * The user decides at run time: the first job asks which model the extension may use and up to
1782
1788
  * which effort, and before data goes to a destination outside this device it asks for consent.
1783
- * The SDK waits for these answers and starts the job again, like for every other permission.
1789
+ * The SDK waits for these answers and starts the job again, like for every other permission. The
1790
+ * choice stays with the host: {@link requestAccessAsync} asks before the first job, and
1791
+ * {@link openSettingsAsync} leads the user to the host's page of this extension's models.
1784
1792
  */
1785
1793
  declare class ModelsAPI {
1786
1794
  private client;
1787
1795
  constructor(client: HaexVaultSdk);
1788
1796
  /** The models the user allowed to this extension; empty without any. */
1789
1797
  listAsync(): Promise<ExtensionModel[]>;
1798
+ /**
1799
+ * Asks for a grant before the first job (holzi spec 055 US9) and resolves with the allowed
1800
+ * models that fit `needs`. Without one, the host asks the user as it would for a job, and the
1801
+ * SDK waits for the answer. Rejects with `no_capable_model` (8001) when no model of the host
1802
+ * fits and with a denial (1002) when the user refused. Nothing is sent to a model, and consent
1803
+ * for a destination outside this device is asked with the first job that sends data.
1804
+ */
1805
+ requestAccessAsync(request: ModelAccessRequest): Promise<ExtensionModel[]>;
1806
+ /** Opens the host's page of this extension's models, where the user chooses models and effort. */
1807
+ openSettingsAsync(): Promise<void>;
1790
1808
  /** Starts a job; its end comes as {@link onCompleted}. Use {@link runAsync} to await it. */
1791
1809
  startAsync(job: ModelJob): Promise<{
1792
1810
  jobId: string;
@@ -1811,6 +1829,177 @@ declare class ModelsAPI {
1811
1829
  }): Promise<ModelJobCompletion>;
1812
1830
  }
1813
1831
 
1832
+ /**
1833
+ * Types of peer channels (holzi spec 057, `contracts/bridge.md` and `contracts/sdk.md`): channels
1834
+ * between frames of the same extension on devices of different vaults.
1835
+ */
1836
+ /** Who may join a lobby by its code: only the host's contacts, or anyone holding the code. */
1837
+ type PeerVisibility = "contacts" | "public";
1838
+ /**
1839
+ * The outcome of an invitation (`peers:invite-status`), exactly once per invitation, on the
1840
+ * inviting side.
1841
+ */
1842
+ interface PeerInviteStatus {
1843
+ inviteId: string;
1844
+ status: "accepted" | "declined" | "not-installed" | "unreachable" | "expired";
1845
+ /** Only with `accepted`: the channel to the invited device. */
1846
+ channelId?: string;
1847
+ /** Only with `unreachable`: ask the contact to share a current card. */
1848
+ hint?: "share_current_card";
1849
+ }
1850
+ /**
1851
+ * A channel opened by an invitation the user accepted in holzi's prompt (`peers:channel-opened`),
1852
+ * on the invited side.
1853
+ */
1854
+ interface PeerChannelOpened {
1855
+ channelId: string;
1856
+ origin: "invitation";
1857
+ inviteId: string;
1858
+ from: {
1859
+ /** Only when the extension's `contacts` permission covers this contact. */
1860
+ contactId?: string;
1861
+ /** The name on the other vault's card, not the display name of the address book. */
1862
+ name: string;
1863
+ };
1864
+ /** The JSON the inviting extension sent with the invitation. */
1865
+ payload: unknown;
1866
+ }
1867
+ /** A device that joined one of this device's lobbies by code (`peers:joined`), on the host. */
1868
+ interface PeerJoined {
1869
+ lobbyId: string;
1870
+ channelId: string;
1871
+ /** Chosen by the joining user and unchecked. */
1872
+ displayName: string;
1873
+ /** `true` when the joining device belongs to a contact. */
1874
+ verified: boolean;
1875
+ /** Only when the extension's `contacts` permission covers this contact. */
1876
+ contactId?: string;
1877
+ /** The JSON the joining extension sent with the join. */
1878
+ payload: unknown;
1879
+ }
1880
+ /** A message on a channel (`peers:message`), with its data decoded from Base64. */
1881
+ interface PeerMessage {
1882
+ channelId: string;
1883
+ data: Uint8Array;
1884
+ reliable: boolean;
1885
+ }
1886
+ /**
1887
+ * The end of a channel (`peers:channel-closed`): `closed` by either side, `lost` when a reliable
1888
+ * message could not be delivered, `timeout` when the other side stopped answering.
1889
+ */
1890
+ interface PeerChannelClosed {
1891
+ channelId: string;
1892
+ reason: "closed" | "lost" | "timeout";
1893
+ }
1894
+ /** The events of `client.peers.on`, by their name without the `peers:` prefix. */
1895
+ interface PeerEventMap {
1896
+ "invite-status": PeerInviteStatus;
1897
+ "channel-opened": PeerChannelOpened;
1898
+ joined: PeerJoined;
1899
+ message: PeerMessage;
1900
+ "channel-closed": PeerChannelClosed;
1901
+ }
1902
+ type PeerEventType = keyof PeerEventMap;
1903
+ /** The `details.reason` of a host error of a peers method. */
1904
+ type PeerErrorReason = "contact_unknown" | "invite_not_open" | "channel_unknown" | "channel_closed" | "lobby_closed" | "not_admitted" | "too_large" | "limit" | "network_unavailable" | "invalid_input";
1905
+
1906
+ /**
1907
+ * The name of each `details.reason` in haex-doom's draft of this API; `limit`,
1908
+ * `network_unavailable` and `invalid_input` are new there.
1909
+ */
1910
+ declare const PEER_ERROR_KINDS: {
1911
+ readonly contact_unknown: "PEER_CONTACT_UNKNOWN";
1912
+ readonly invite_not_open: "PEER_INVITE_UNKNOWN";
1913
+ readonly channel_unknown: "PEER_CHANNEL_CLOSED";
1914
+ readonly channel_closed: "PEER_CHANNEL_CLOSED";
1915
+ readonly too_large: "PEER_PAYLOAD_TOO_LARGE";
1916
+ readonly lobby_closed: "PEER_LOBBY_CLOSED";
1917
+ readonly not_admitted: "PEER_NOT_ALLOWED";
1918
+ readonly limit: "PEER_LIMIT";
1919
+ readonly network_unavailable: "PEER_NETWORK_UNAVAILABLE";
1920
+ readonly invalid_input: "PEER_INVALID_INPUT";
1921
+ };
1922
+ type PeerErrorKind = (typeof PEER_ERROR_KINDS)[PeerErrorReason];
1923
+ /**
1924
+ * A host error of a peers method that names its `details.reason`. `code` stays the host's number
1925
+ * (1001, 1002, 3001, 7000, 8001); `not_admitted` shares 1002 with a refused permission, so tell
1926
+ * them apart by `reason`. The host's error is kept as `cause`.
1927
+ */
1928
+ declare class PeerError extends Error {
1929
+ readonly code: number;
1930
+ readonly reason: PeerErrorReason;
1931
+ readonly details: Record<string, unknown>;
1932
+ readonly kind: PeerErrorKind;
1933
+ /** The host's `details.limit` with `too_large` (bytes) and `limit` (count). */
1934
+ readonly limit?: number;
1935
+ constructor(code: number, reason: PeerErrorReason, message: string, details?: Record<string, unknown>, options?: {
1936
+ cause?: unknown;
1937
+ });
1938
+ }
1939
+ /**
1940
+ * Channels between frames of this extension on devices of different vaults (holzi spec 057).
1941
+ * Needs the `peers` permission (`{ target: "*", action: "connect" }`); inviting a contact also
1942
+ * needs `contacts` read access to that contact.
1943
+ *
1944
+ * A channel starts in one of two ways. An invitation goes to all devices of a contact; the user
1945
+ * accepts or declines it only in holzi's own prompt, so the SDK has no accept or decline. The
1946
+ * invited side gets `channel-opened`, the inviting side `invite-status`. A lobby hands out an
1947
+ * opaque join code (`haex-vault:join:…`); a device that joins with it gets the channel from
1948
+ * {@link PeersAPI.joinAsync}, the host gets `joined`.
1949
+ *
1950
+ * Errors with a `details.reason` reject as {@link PeerError}; others reject unchanged.
1951
+ */
1952
+ declare class PeersAPI {
1953
+ private client;
1954
+ /** Largest fast message (`reliable: false`) in bytes. */
1955
+ readonly MAX_FAST_BYTES = 1024;
1956
+ /** Largest reliable message in bytes. */
1957
+ readonly MAX_RELIABLE_BYTES = 65536;
1958
+ /** Largest `payload` of an invitation or a join, as JSON, in bytes. */
1959
+ readonly MAX_PAYLOAD_BYTES = 4096;
1960
+ constructor(client: HaexVaultSdk);
1961
+ private call;
1962
+ /** Invites a contact; the outcome follows as `invite-status` with this `inviteId`. */
1963
+ inviteAsync(contactId: string, payload: unknown): Promise<{
1964
+ inviteId: string;
1965
+ }>;
1966
+ /** Withdraws an open invitation on all devices of the contact; no `invite-status` follows. */
1967
+ cancelInviteAsync(inviteId: string): Promise<void>;
1968
+ /**
1969
+ * Opens a lobby; `lobbyId` is 1–64 characters of `[A-Za-z0-9._-]`. The join code is opaque:
1970
+ * hand it on as it is.
1971
+ */
1972
+ openLobbyAsync(lobbyId: string, visibility: PeerVisibility): Promise<{
1973
+ joinCode: string;
1974
+ }>;
1975
+ /** Closes a lobby: its code stops working, its channels stay open. An unknown lobby is fine. */
1976
+ closeLobbyAsync(lobbyId: string): Promise<void>;
1977
+ /**
1978
+ * Joins a lobby by its code with a self-chosen `displayName` (1–64 characters). The host
1979
+ * answers within 15 s; a lobby that cannot be joined for any reason rejects as `lobby_closed`.
1980
+ */
1981
+ joinAsync(joinCode: string, displayName: string, payload: unknown): Promise<{
1982
+ channelId: string;
1983
+ lobbyId: string;
1984
+ }>;
1985
+ /** Closes a channel of an own lobby and keeps that device (and vault) out of the lobby. */
1986
+ removeAsync(channelId: string): Promise<void>;
1987
+ /**
1988
+ * Sends bytes over a channel: fast (default, at most {@link MAX_FAST_BYTES}, may be lost) or
1989
+ * `reliable` (at most {@link MAX_RELIABLE_BYTES}, in order; 16 may wait per channel).
1990
+ */
1991
+ sendAsync(channelId: string, data: Uint8Array, options?: {
1992
+ reliable?: boolean;
1993
+ }): Promise<void>;
1994
+ /** Closes a channel; both sides get `channel-closed` with `reason: "closed"`. */
1995
+ closeAsync(channelId: string): Promise<void>;
1996
+ /**
1997
+ * Listens for one of the peers events (`invite-status`, `channel-opened`, `joined`, `message`,
1998
+ * `channel-closed`); `message.data` arrives as bytes. Returns an unsubscribe function.
1999
+ */
2000
+ on<T extends PeerEventType>(type: T, handler: (event: PeerEventMap[T]) => void): () => void;
2001
+ }
2002
+
1814
2003
  /**
1815
2004
  * Mail types — IMAP fetch + SMTP send.
1816
2005
  *
@@ -2290,6 +2479,7 @@ declare class HaexVaultSdk {
2290
2479
  readonly passwords: PasswordsAPI;
2291
2480
  readonly contacts: ContactsAPI;
2292
2481
  readonly models: ModelsAPI;
2482
+ readonly peers: PeersAPI;
2293
2483
  readonly mail: MailAPI;
2294
2484
  readonly notifications: NotificationsAPI;
2295
2485
  readonly tab: TabAPI;
@@ -2346,5 +2536,5 @@ declare class HaexVaultSdk {
2346
2536
  private log;
2347
2537
  }
2348
2538
 
2349
- export { DatabaseAPI as D, HaexVaultSdk as H, FilesystemAPI as L, KnownPath as N, LOCALSEND_EVENTS as P, LocalSendAPI as Q, StorageAPI as S, MailAPI as V, RemoteStorageAPI as aB, ShellAPI as aO, SpacesAPI as a_, ModelsAPI as ae, NotificationsAPI as ai, PasswordsAPI as aq, PermissionsAPI as at, TabAPI as b0, ToolsAPI as b3, WebAPI as b7, canExternalClientSendRequests as b8, isExternalClientConnected as b9, ContactsAPI as i, DialogAPI as o, EncryptedFoldersAPI as t, ExternalConnectionErrorCode as x, ExternalConnectionState as y };
2350
- export type { MailNewMessagesEvent as $, AuthorizedClient as A, BlockedClient as B, ConfirmOptions as C, EncryptedFolderAccess as E, ExternalRequestEvent as F, ExternalRequestHandler as G, ExternalRequestPayload as I, ExternalResponse as J, FileStat as K, ImapConfig as M, KnownPaths as O, LocalSendEvent as R, FileInfo as T, LocalSendSettings as U, MailAccount as W, MailAddress as X, Attachment as Y, FetchRange as Z, MailMessage as _, ConnectionSecurity as a, SyncBackendInfo as a$, MailSearchCriteria as a0, MailSearchResult as a1, MailboxInfo as a2, MessageEnvelope as a3, ModelEffort as a4, ModelJob as a5, ModelJobAttempt as a6, ModelJobCompletion as a7, ModelJobErrorCode as a8, ModelJobFormat as a9, SftpProposal as aA, StorageBackendInfo as aC, StorageBackendType as aD, StorageObjectInfo as aE, UpdateBackendRequest as aF, WebDavProposal as aG, RequestedExtension as aH, SelectFileOptions as aI, SelectFolderOptions as aJ, ServerInfo as aK, ServerStatus as aL, SessionAuthorization as aM, SharedSpace as aN, ShellCreateOptions as aP, ShellCreateResponse as aQ, ShellExitEvent as aR, ShellOutputEvent as aS, SmtpConfig as aT, SpaceAccessTokenInfo as aU, SpaceAssignment as aV, SpaceInvite as aW, SpaceKeyGrantInfo as aX, SpaceMember as aY, SpaceMemberInfo as aZ, ModelJobImage as aa, ModelJobProvenance as ab, ModelJobStep as ac, ModelPlace as ad, NotificationAction as af, NotificationClickEvent as ag, NotificationOptions as ah, OutgoingAttachment as aj, OutgoingMessage as ak, PasswordInput as al, PasswordItemFull as am, PasswordItemSummary as an, PasswordKeyValue as ao, PasswordKeyValueInput as ap, PendingAuthorization as ar, PendingTransfer as as, AddBackendRequest as au, FolderBackendInfo as av, S3BackendInfo as aw, S3Config as ax, S3Proposal as ay, S3PublicConfig as az, ContactDetail as b, ToolContext as b1, ToolHandler as b2, TransferDirection as b4, TransferProgress as b5, TransferState as b6, ContactHolziAddresses as c, ContactHolziDevice as d, ContactList as e, ContactListOptions as f, ContactSummary as g, ContactValue as h, DecryptedSpace as j, DeepLink as k, Device as l, DeviceInfo as m, DeviceType as n, DirEntry as p, EncryptedFolderChoice as q, EncryptedFolderEntry as r, EncryptedFolderProviderErrorKind as s, ExtensionModel as u, ExternalAuthDecision as v, ExternalConnection as w, ExternalRequest as z };
2539
+ export { DatabaseAPI as D, HaexVaultSdk as H, FilesystemAPI as L, KnownPath as N, LOCALSEND_EVENTS as P, LocalSendAPI as Q, StorageAPI as S, MailAPI as V, PeersAPI as aE, PermissionsAPI as aH, RemoteStorageAPI as aP, ModelsAPI as af, NotificationsAPI as aj, PEER_ERROR_KINDS as am, PasswordsAPI as as, PeerError as av, ShellAPI as b0, SpacesAPI as bc, TabAPI as be, ToolsAPI as bh, WebAPI as bl, canExternalClientSendRequests as bm, isExternalClientConnected as bn, ContactsAPI as i, DialogAPI as o, EncryptedFoldersAPI as t, ExternalConnectionErrorCode as x, ExternalConnectionState as y };
2540
+ export type { MailNewMessagesEvent as $, AuthorizedClient as A, BlockedClient as B, ConfirmOptions as C, EncryptedFolderAccess as E, ExternalRequestEvent as F, ExternalRequestHandler as G, ExternalRequestPayload as I, ExternalResponse as J, FileStat as K, ImapConfig as M, KnownPaths as O, LocalSendEvent as R, FileInfo as T, LocalSendSettings as U, MailAccount as W, MailAddress as X, Attachment as Y, FetchRange as Z, MailMessage as _, ConnectionSecurity as a, SharedSpace as a$, MailSearchCriteria as a0, MailSearchResult as a1, MailboxInfo as a2, MessageEnvelope as a3, ModelAccessRequest as a4, ModelEffort as a5, ModelJob as a6, ModelJobAttempt as a7, ModelJobCompletion as a8, ModelJobErrorCode as a9, PeerInviteStatus as aA, PeerJoined as aB, PeerMessage as aC, PeerVisibility as aD, PendingAuthorization as aF, PendingTransfer as aG, AddBackendRequest as aI, FolderBackendInfo as aJ, S3BackendInfo as aK, S3Config as aL, S3Proposal as aM, S3PublicConfig as aN, SftpProposal as aO, StorageBackendInfo as aQ, StorageBackendType as aR, StorageObjectInfo as aS, UpdateBackendRequest as aT, WebDavProposal as aU, RequestedExtension as aV, SelectFileOptions as aW, SelectFolderOptions as aX, ServerInfo as aY, ServerStatus as aZ, SessionAuthorization as a_, ModelJobFormat as aa, ModelJobImage as ab, ModelJobProvenance as ac, ModelJobStep as ad, ModelPlace as ae, NotificationAction as ag, NotificationClickEvent as ah, NotificationOptions as ai, OutgoingAttachment as ak, OutgoingMessage as al, PasswordInput as an, PasswordItemFull as ao, PasswordItemSummary as ap, PasswordKeyValue as aq, PasswordKeyValueInput as ar, PeerChannelClosed as at, PeerChannelOpened as au, PeerErrorKind as aw, PeerErrorReason as ax, PeerEventMap as ay, PeerEventType as az, ContactDetail as b, ShellCreateOptions as b1, ShellCreateResponse as b2, ShellExitEvent as b3, ShellOutputEvent as b4, SmtpConfig as b5, SpaceAccessTokenInfo as b6, SpaceAssignment as b7, SpaceInvite as b8, SpaceKeyGrantInfo as b9, SpaceMember as ba, SpaceMemberInfo as bb, SyncBackendInfo as bd, ToolContext as bf, ToolHandler as bg, TransferDirection as bi, TransferProgress as bj, TransferState as bk, ContactHolziAddresses as c, ContactHolziDevice as d, ContactList as e, ContactListOptions as f, ContactSummary as g, ContactValue as h, DecryptedSpace as j, DeepLink as k, Device as l, DeviceInfo as m, DeviceType as n, DirEntry as p, EncryptedFolderChoice as q, EncryptedFolderEntry as r, EncryptedFolderProviderErrorKind as s, ExtensionModel as u, ExternalAuthDecision as v, ExternalConnection as w, ExternalRequest as z };