@solarpunkltd/swarm-id 0.0.0-stage → 0.8.0

package/dist/swarm-id-client.d.ts

@@ -0,0 +1,1114 @@
+import type { ClientOptions, ConnectOptions, AuthStatus, Avatar, ConnectionInfo, UploadResult, FileData, UploadOptions, UploadFilesOptions, CollectionFileInput, CollectionEntry, ActUploadOptions, DownloadOptions, RequestOptions, Reference, SOCReader, SOCWriter, FeedReaderOptions, FeedWriterOptions, FeedReader, FeedWriter, SequentialFeedReaderOptions, SequentialFeedWriterOptions, SequentialFeedReader, SequentialFeedWriter, StampChunkInput, StampedChunk, PostageBatch } from "./types";
+import { EthAddress, PrivateKey } from "@ethersphere/bee-js";
+/**
+ * Main client library for integrating Swarm ID authentication and storage capabilities
+ * into web applications.
+ *
+ * SwarmIdClient enables parent windows to interact with a Swarm ID iframe proxy,
+ * providing secure authentication, identity management, and data upload/download
+ * functionality to the Swarm decentralized storage network.
+ *
+ * @example
+ * ```typescript
+ * const client = new SwarmIdClient({
+ *   iframeOrigin: 'https://swarm-id.example.com',
+ *   metadata: {
+ *     name: 'My App',
+ *     description: 'A decentralized application'
+ *   },
+ *   onConnectionChange: (info) => {
+ *     console.log('Connection changed:', info.identity?.name, info.canUpload)
+ *   }
+ * })
+ *
+ * await client.initialize()
+ *
+ * // Check canUpload — an authenticated user can still lack upload capability
+ * // when they have no postage stamp and no subsidised gateway is configured.
+ * if (client.connectionInfo.identity && client.connectionInfo.canUpload) {
+ *   const result = await client.uploadData(new Uint8Array([1, 2, 3]))
+ *   console.log('Uploaded with reference:', result.reference)
+ * }
+ * ```
+ */
+export declare class SwarmIdClient {
+    private iframe;
+    private iframeOrigin;
+    private iframePath;
+    private timeout;
+    private initializationTimeout;
+    private onConnectionChange?;
+    private lastConnectionInfo;
+    private firstConnectionInfoPromise;
+    private firstConnectionInfoResolve?;
+    private firstConnectionInfoReject?;
+    private iframeLoadReject?;
+    private popupMode;
+    private metadata;
+    private buttonConfig?;
+    private containerId?;
+    private subsidisedGatewayUrl?;
+    private ready;
+    /**
+     * Whether the proxy iframe can read the trusted domain's first-party store,
+     * as reported on `proxyReady`. Decides which transport `connect()` uses
+     * (#613); undefined against a proxy that predates the field, which reads as
+     * "not proven shared".
+     */
+    private storageShared;
+    private readyPromise;
+    private readyResolve?;
+    private readyReject?;
+    private pendingRequests;
+    /**
+     * Progress callbacks of in-flight uploads, by request id. Dispatched from
+     * the one window listener, so progress passes the same source and origin
+     * checks as every other message from the iframe.
+     */
+    private progressListeners;
+    private requestIdCounter;
+    private messageListener;
+    private proxyInitializedPromise;
+    private proxyInitializedResolve?;
+    private proxyInitializedReject?;
+    /**
+     * Creates a new SwarmIdClient instance.
+     *
+     * @param options - Configuration options for the client
+     * @param options.iframeOrigin - The origin URL where the Swarm ID proxy iframe is hosted
+     * @param options.iframePath - The path to the proxy iframe (defaults to "/proxy")
+     * @param options.timeout - Request timeout in milliseconds (defaults to 30000). Bounds each call's whole round trip through the iframe; a call's own `requestOptions.timeout` replaces it for that call
+     * @param options.onConnectionChange - Callback invoked when the dApp-visible ConnectionInfo changes (identity, stamp, account type, auth)
+     * @param options.popupMode - How to display the authentication popup: "popup" or "window" (defaults to "window")
+     * @param options.metadata - Application metadata shown to users during authentication
+     * @param options.metadata.name - Application name (1-100 characters)
+     * @param options.metadata.description - Optional application description (max 500 characters)
+     * @param options.metadata.icon - Optional application icon as a data URL (SVG or PNG, max 4KB)
+     * @param options.buttonConfig - Button configuration for the authentication UI (optional)
+     * @param options.buttonConfig.connectText - Text for the connect button (optional)
+     * @param options.buttonConfig.disconnectText - Text for the disconnect button (optional)
+     * @param options.buttonConfig.loadingText - Text shown during loading (optional)
+     * @param options.buttonConfig.backgroundColor - Background color for buttons (optional)
+     * @param options.buttonConfig.color - Text color for buttons (optional)
+     * @param options.buttonConfig.borderRadius - Border radius for buttons and iframe (optional)
+     * @param options.buttonConfig.fontFamily - CSS font-family for the button, so it can match the embedding page; a font stack falls back as usual (optional)
+     * @param options.buttonConfig.fontSize - CSS font-size for the button; the default floating iframe is a fixed 300x50 px and hides its overflow, so a size that does not fit is clipped — pass `containerId` to own the box (optional)
+     * @param options.buttonConfig.fontWeight - CSS font-weight for the button, as a keyword or a number (optional)
+     * @param options.containerId - ID of container element to place iframe in (optional)
+     * @throws {Error} If constructed where there is no `window` (a server render)
+     * @throws {SwarmIdError} `invalid-request` if the provided app metadata is invalid
+     */
+    constructor(options: ClientOptions);
+    /**
+     * Initializes the client by creating and embedding the proxy iframe.
+     *
+     * This method must be called before using any other client methods.
+     * It creates a hidden iframe, waits for the proxy to initialize,
+     * identifies the parent application to the proxy, and waits for
+     * the proxy to signal readiness.
+     *
+     * @returns A promise that resolves when the client is fully initialized
+     * @throws {SwarmIdError} `invalid-state` if the client is already initialized, or `destroy()` runs before it resolves
+     * @throws {SwarmIdError} `invalid-request` if `containerId` names no element
+     * @throws {SwarmIdError} `init-failed` if the iframe fails to load, origin validation fails on the proxy side, or the proxy does not respond within `initializationTimeout` (30 seconds by default)
+     *
+     * @example
+     * ```typescript
+     * const client = new SwarmIdClient({ ... })
+     * try {
+     *   await client.initialize()
+     *   console.log('Client ready')
+     * } catch (error) {
+     *   console.error('Failed to initialize:', error)
+     * }
+     * ```
+     */
+    initialize(): Promise<void>;
+    /**
+     * Setup message listener for iframe responses
+     */
+    private setupMessageListener;
+    /**
+     * Handle messages from iframe
+     */
+    private handleIframeMessage;
+    /**
+     * Send message to iframe
+     */
+    private sendMessage;
+    /**
+     * Send request and wait for response
+     */
+    private sendRequest;
+    /**
+     * The round-trip bound for one call, from its own `requestOptions.timeout`.
+     *
+     * Only a value `setTimeout` can honour is taken. Zero and negatives mean
+     * "no timeout" to Bee, which is where this option went before it also bound
+     * the round trip — taken literally here they would reject on the next tick,
+     * the opposite of what the caller asked, so they fall back to the client
+     * default and still reach Bee unchanged. A value past the 32-bit timer
+     * ceiling means "as long as it takes", and `setTimeout` would wrap it into
+     * firing almost at once, so it clamps to the ceiling instead. `Infinity` and
+     * `NaN` never get this far: `z.number()` rejects them on the way out.
+     */
+    private roundTripTimeout;
+    /**
+     * Generate unique request ID
+     */
+    private generateRequestId;
+    private normalizeSocIdentifier;
+    private normalizeSocKey;
+    private normalizeFeedTopic;
+    private normalizeReference;
+    private normalizeFeedTimestamp;
+    private normalizeFeedIndex;
+    private normalizePayload;
+    private socChunkFromResponse;
+    /**
+     * Ensure client is initialized
+     */
+    private ensureReady;
+    /**
+     * Returns the authentication iframe element.
+     *
+     * The iframe displays authentication UI based on the current auth status:
+     * - If not authenticated: shows a "Connect" button
+     * - If authenticated: shows identity info and a "Disconnect" button
+     *
+     * The iframe is positioned fixed in the bottom-right corner of the viewport.
+     *
+     * @returns The iframe element displaying the authentication UI
+     * @throws {SwarmIdError} `invalid-state` if the client is not initialized, or the iframe is not available
+     *
+     * @example
+     * ```typescript
+     * const iframe = client.getAuthIframe()
+     * // The iframe is already displayed; this returns a reference to it
+     * ```
+     */
+    getAuthIframe(): HTMLIFrameElement;
+    /**
+     * Checks the current authentication status with the Swarm ID proxy.
+     *
+     * @returns A promise resolving to the authentication status object
+     * @returns return.authenticated - Whether the user is currently authenticated
+     * @returns return.origin - The origin that authenticated (if authenticated)
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const status = await client.checkAuthStatus()
+     * if (status.authenticated) {
+     *   console.log('Authenticated from:', status.origin)
+     * }
+     * ```
+     */
+    checkAuthStatus(): Promise<AuthStatus>;
+    /**
+     * Gets the current postage batch for the authenticated identity.
+     *
+     * Returns information about the postage stamp associated with the
+     * connected identity, including batch ID, utilization, depth, and TTL.
+     *
+     * @returns A promise resolving to the PostageBatch or undefined if none is configured
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const batch = await client.getPostageBatch()
+     * if (batch) {
+     *   console.log('Batch ID:', batch.batchID)
+     *   console.log('Utilization:', batch.utilization)
+     *   console.log('Depth:', batch.depth)
+     *   console.log('TTL:', batch.batchTTL)
+     * } else {
+     *   console.log('No postage batch configured')
+     * }
+     * ```
+     */
+    getPostageBatch(): Promise<PostageBatch | undefined>;
+    /**
+     * Disconnects the current session and clears authentication data.
+     *
+     * After disconnection, the user will need to re-authenticate to perform
+     * uploads or access identity-related features. The
+     * {@link ClientOptions.onConnectionChange} callback will fire with an
+     * un-authenticated snapshot.
+     *
+     * @returns A promise that resolves when disconnection is complete
+     * @throws {SwarmIdError} `invalid-state` if the client is not initialized
+     * @throws {SwarmIdError} `internal` if the proxy reports the disconnect failed
+     * @throws {SwarmIdError} `timeout` if the request times out
+     *
+     * @example
+     * ```typescript
+     * await client.disconnect()
+     * console.log('User logged out')
+     * ```
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Opens the Swarm ID authentication page in a new window.
+     *
+     * This method creates the same authentication URL as used by the iframe
+     * proxy and opens it in a new browser window. The user can authenticate
+     * with their Swarm ID, and the resulting authentication will be available
+     * to the client when they return.
+     *
+     * **Which window opens it** is decided by the iframe's STORAGE, not by the
+     * user agent (#613):
+     * - Shared storage: opened here, from the parent, so the click's activation is
+     *   still unspent. The popup writes the connection to the first-party store
+     *   the iframe reads, and a `storage` event carries it across.
+     * - Partitioned, or not proven shared: the proxy opens it, so the popup's
+     *   `window.opener` points back at the iframe and the session can be handed
+     *   over directly — the only channel into a partitioned frame. The session
+     *   is then kept in that partition's own store until it is disconnected or
+     *   its 7 days are up (#635), so a reload does not re-run this; a handover
+     *   that arrives without the account view is refused outright rather than
+     *   producing a session that cannot upload and cannot hear a revoke. A popup
+     *   blocked on this path falls back to opening from the parent.
+     *
+     * Safari private mode sessions are ephemeral (lost when the private window
+     * closes). The whole partitioned path — handover, stamper, upload — is
+     * confirmed on real Safari; see
+     * https://github.com/snaha/swarm-id/issues/584
+     *
+     * @param options - Configuration options for the connect flow
+     * @throws {SwarmIdError} `invalid-state` if the client is not initialized
+     * @throws {SwarmIdError} `popup-blocked` if the browser blocks the popup
+     *
+     * @example
+     * ```typescript
+     * const client = new SwarmIdClient({ ... })
+     * await client.initialize()
+     *
+     * // Open authentication page
+     * await client.connect()
+     * ```
+     */
+    connect(options?: ConnectOptions): Promise<void>;
+    /**
+     * Open the auth popup from the dApp page.
+     *
+     * Carries no challenge: a popup opened here has the dApp page as its
+     * `window.opener`, so there is nothing for a handover to attach to, and the
+     * popup falls back to the storage write it does anyway.
+     *
+     * @returns whether the popup opened — a blocked one returns null, which the
+     *   caller must not report as a connect in progress.
+     */
+    private openAuthWindow;
+    /**
+     * Current dApp-visible {@link ConnectionInfo} snapshot — identity, app key,
+     * upload capability, and upload mode. Populated by the proxy as soon as it
+     * is ready and refreshed whenever any of those derived fields change.
+     * Subscribe to {@link ClientOptions.onConnectionChange} to react to updates.
+     *
+     * @throws {SwarmIdError} `invalid-state` if {@link initialize} has not resolved yet
+     *
+     * @example
+     * ```typescript
+     * await client.initialize()
+     * const info = client.connectionInfo
+     * if (info.canUpload) {
+     *   console.log('Ready to upload as:', info.identity?.name)
+     * }
+     * ```
+     */
+    get connectionInfo(): ConnectionInfo;
+    /**
+     * Avatar of the connected identity at a specific size.
+     *
+     * Most callers want `connectionInfo.identity.avatar` instead — it is already
+     * resolved on every snapshot and needs no call. Reach for this only to
+     * render at a size the default does not suit. Async so that honouring a size
+     * may involve fetching, which anything but the generated avatar would.
+     *
+     * @param options.size - Width and height in pixels
+     * @returns The avatar, or `undefined` when no identity is connected
+     */
+    getAvatar(options?: {
+        size?: number;
+    }): Promise<Avatar | undefined>;
+    /**
+     * Checks whether the Bee node is reachable.
+     *
+     * This method never throws an exception. If the client is not initialized,
+     * the request times out, or any other error occurs, it returns `false`.
+     *
+     * @returns A promise resolving to `true` if the Bee node is reachable, `false` otherwise
+     *
+     * @example
+     * ```typescript
+     * const connected = await client.isBeeConnected()
+     * if (connected) {
+     *   console.log('Bee node is online')
+     * } else {
+     *   console.log('Bee node is offline')
+     * }
+     * ```
+     */
+    isBeeConnected(): Promise<boolean>;
+    /**
+     * Gets information about the Bee node configuration.
+     *
+     * Needs a real Bee node: the public gateway has no `/node` endpoint, so this
+     * rejects there. Do not gate uploads on it — it exists to detect a dev-mode
+     * node, where deferred uploads are required.
+     *
+     * This method retrieves the current Bee node's operating mode and feature flags.
+     * Use this to determine if deferred uploads are required (dev mode) or if direct
+     * uploads are available (production modes).
+     *
+     * @returns A promise resolving to the node info object
+     * @returns return.beeMode - The Bee node operating mode ("dev", "light", "full", "ultra-light")
+     * @returns return.chequebookEnabled - Whether the chequebook is enabled
+     * @returns return.swapEnabled - Whether SWAP is enabled
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the Bee node is not reachable
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const nodeInfo = await client.getNodeInfo()
+     * if (nodeInfo.beeMode === 'dev') {
+     *   // Dev mode requires deferred uploads
+     *   await client.uploadData(data, { deferred: true })
+     * } else {
+     *   // Production modes can use direct uploads
+     *   await client.uploadData(data, { deferred: false })
+     * }
+     * ```
+     */
+    getNodeInfo(): Promise<{
+        beeMode: string;
+        chequebookEnabled: boolean;
+        swapEnabled: boolean;
+    }>;
+    /**
+     * Uploads raw binary data to the Swarm network.
+     *
+     * Read the returned reference back with {@link downloadData}, or from a
+     * gateway at `/bytes/<reference>`. It carries no manifest, so
+     * {@link downloadFile} and `/bzz/` cannot resolve it.
+     *
+     * The data is uploaded using the authenticated user's postage stamp.
+     * Progress can be tracked via the optional callback.
+     *
+     * @param data - The binary data to upload as a Uint8Array
+     * @param options - Optional upload configuration
+     * @param options.pin - Whether to pin the data locally (defaults to false; ignored on a subsidised gateway)
+     * @param options.encrypt - Whether to encrypt the data (defaults to false)
+     * @param options.tag - Tag ID for tracking upload progress
+     * @param options.deferred - Whether to use deferred upload (defaults to false)
+     * @param options.onProgress - Optional callback for tracking upload progress
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the upload result
+     * @returns return.reference - The Swarm reference (hash) of the uploaded data
+     * @returns return.tagUid - The tag UID if a tag was created
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not authenticated or cannot upload
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const data = new TextEncoder().encode('Hello, Swarm!')
+     * const result = await client.uploadData(data, {
+     *   encrypt: true,
+     *   onProgress: (progress) => {
+     *     console.log(`Progress: ${progress.processed}/${progress.total}`)
+     *   },
+     * })
+     * console.log('Reference:', result.reference)
+     * ```
+     */
+    uploadData(data: Uint8Array, options?: UploadOptions, requestOptions?: RequestOptions): Promise<UploadResult>;
+    /**
+     * Downloads raw binary data from the Swarm network: the counterpart of
+     * {@link uploadData}. Pass an encrypted (128-hex) reference here rather
+     * than putting it in a gateway URL — it contains the decryption key.
+     *
+     * @param reference - The Swarm reference (hash) of the data to download.
+     *                    Can be 64 hex chars (32 bytes) or 128 hex chars (64 bytes for encrypted)
+     * @param options - Optional download configuration
+     * @param options.redundancyStrategy - Strategy for handling redundancy (0-3)
+     * @param options.fallback - Whether to use fallback retrieval
+     * @param options.timeoutMs - Download timeout in milliseconds
+     * @param options.actPublisher - ACT publisher for encrypted content
+     * @param options.actHistoryAddress - ACT history address for encrypted content
+     * @param options.actTimestamp - ACT timestamp for encrypted content
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the downloaded data as a Uint8Array
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the reference is not found
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const data = await client.downloadData('a1b2c3...') // 64 char hex reference
+     * const text = new TextDecoder().decode(data)
+     * console.log('Downloaded:', text)
+     * ```
+     */
+    downloadData(reference: Reference, options?: DownloadOptions, requestOptions?: RequestOptions): Promise<Uint8Array>;
+    /**
+     * Derive a stable, app-scoped secret for this identity + app origin.
+     *
+     * Computes `HMAC(appSecret, label)` inside the iframe, where `appSecret` is the
+     * app-specific secret that never leaves the trusted context. The result is
+     * deterministic — the same identity, app origin, and label always yield the
+     * same bytes across sessions and devices — yet unguessable to anyone without
+     * the identity. Use it to seed feed topics or other app material without
+     * exposing the recoverable app public key (#520).
+     *
+     * @param label - Application-chosen domain separator (e.g. `"state-feed"`)
+     * @returns A promise resolving to the 32-byte derived secret
+     * @throws {Error} If the client is not initialized or not authenticated
+     *
+     * @example
+     * ```typescript
+     * const seed = await client.deriveAppSecret('state-feed')
+     * const topic = keccak256(seed) // an unguessable, stable feed topic
+     * ```
+     */
+    deriveAppSecret(label: string): Promise<Uint8Array>;
+    /**
+     * The site's chat key: the private key this site's chat signs messages
+     * with, whose address `connectionInfo.chatBinding` names as the account's
+     * chat address on this site (docs/Chat-Binding.md).
+     *
+     * It is derived inside the iframe from the app secret, which never leaves
+     * it, and is the same for this account and this site on every device. The
+     * library keeps it in memory only and never writes it to storage. Hold it no
+     * longer than the chat needs it, and never publish it.
+     *
+     * @returns A promise resolving to the 32-byte secp256k1 private key
+     * @throws {SwarmIdError} If the client is not initialized, or with code
+     *   `not-authenticated` when no account is connected
+     *
+     * @example
+     * ```typescript
+     * const chatKey = await client.getChatKey()
+     * const signer = new PrivateKey(chatKey) // its address is the binding's chat address
+     * ```
+     */
+    getChatKey(): Promise<Uint8Array>;
+    /**
+     * Stamp a chunk with the account's own postage stamp and get the stamp back,
+     * to send the chunk through whatever Swarm access the app chose: a gateway,
+     * its own Bee node or a browser node.
+     *
+     * The frame computes the chunk's address itself, so the whole chunk goes in,
+     * never an address. A content chunk is stamped as it is. A single-owner chunk
+     * is signed by the frame in this same call, with the app's own secret
+     * (`signer: "app"`) or a private key the app supplies, such as a chat's
+     * shared GSOC inbox key. A pre-signed chunk is refused, and so is one owned
+     * by any of the account's own keys.
+     *
+     * The stamp is returned only once the bucket counter it spent is saved and,
+     * for an account shared between devices, published, as an upload is
+     * acknowledged. Two calls never return the same bucket slot.
+     *
+     * @param chunk - The chunk: `data` is the 8-byte little-endian span followed
+     *   by the payload, 8 to 4104 bytes
+     * @returns The chunk address, the stamp as the `swarm-postage-stamp` header
+     *   value, and for a single-owner chunk its owner and signature
+     * @throws {SwarmIdError} `upload-unavailable` with reason `subsidised` when
+     *   the account is in subsidised mode, where the gateway stamps and there is
+     *   no stamp of the account's to return, and `invalid-request` for a chunk of the
+     *   wrong shape or an owner that is one of the account's keys
+     *
+     * @example
+     * ```typescript
+     * const { address, stamp } = await client.stampChunk({ kind: 'content', data })
+     * await fetch(`${gateway}/chunks`, {
+     *   method: 'POST',
+     *   headers: { 'swarm-postage-stamp': stamp },
+     *   body: data,
+     * })
+     * ```
+     */
+    stampChunk(chunk: StampChunkInput): Promise<StampedChunk>;
+    /**
+     * Uploads a file to the Swarm network, wrapped in a manifest that carries
+     * its name and content type. Read the reference back with
+     * {@link downloadFile}. A gateway's `/bzz/<reference>/` is only for a plain
+     * reference, uploaded with `encrypt: false`.
+     *
+     * Accepts either a File object (from file input) or raw Uint8Array data.
+     * When using a File object, the filename is automatically extracted unless
+     * explicitly overridden.
+     *
+     * Content is encrypted unless `options.encrypt` is `false`, and the
+     * manifest too — a 64-byte reference that carries the key — unless
+     * `options.encrypt` or `options.encryptManifest` is `false`. The same rule
+     * as {@link uploadFiles}.
+     *
+     * @param file - The file to upload (File object or Uint8Array)
+     * @param name - Optional filename (extracted from File object if not provided)
+     * @param options - Optional upload configuration
+     * @param options.pin - Whether to pin the file locally (defaults to false; ignored on a subsidised gateway)
+     * @param options.encrypt - Whether to encrypt the file content (defaults to true); `false` also leaves the manifest plain
+     * @param options.encryptManifest - Whether to encrypt the manifest too (defaults to true); `false` gives a 32-byte reference over encrypted content
+     * @param options.tag - Tag ID for tracking upload progress
+     * @param options.deferred - Whether to use deferred upload (defaults to false)
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the upload result
+     * @returns return.reference - The Swarm reference (hash) of the uploaded file
+     * @returns return.tagUid - The tag UID if a tag was created
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not authenticated or cannot upload
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * // From file input
+     * const fileInput = document.querySelector('input[type="file"]')
+     * const file = fileInput.files[0]
+     * const result = await client.uploadFile(file)
+     *
+     * // From Uint8Array with custom name
+     * const data = new Uint8Array([...])
+     * const result = await client.uploadFile(data, 'document.pdf')
+     * ```
+     */
+    uploadFile(file: File | Uint8Array, name?: string, options?: UploadOptions, requestOptions?: RequestOptions): Promise<UploadResult>;
+    /**
+     * Downloads a file from the Swarm network: the counterpart of
+     * {@link uploadFile}. It resolves a manifest, so a reference produced by
+     * {@link uploadData} fails here inside the manifest parser; use
+     * {@link downloadData} for those.
+     *
+     * Returns both the file data and its original filename (if available).
+     * For manifest references, an optional path can be specified to retrieve
+     * a specific file from the manifest.
+     *
+     * @param reference - The Swarm reference (hash) of the file to download
+     * @param path - Optional path within a manifest to retrieve a specific file
+     * @param options - Optional download configuration
+     * @param options.redundancyStrategy - Strategy for handling redundancy (0-3)
+     * @param options.fallback - Whether to use fallback retrieval
+     * @param options.timeoutMs - Download timeout in milliseconds
+     * @param options.actPublisher - ACT publisher for encrypted content
+     * @param options.actHistoryAddress - ACT history address for encrypted content
+     * @param options.actTimestamp - ACT timestamp for encrypted content
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the file data object
+     * @returns return.name - The filename
+     * @returns return.data - The file contents as a Uint8Array
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the reference is not found
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const file = await client.downloadFile('a1b2c3...')
+     * console.log('Filename:', file.name)
+     *
+     * // Create download link
+     * const blob = new Blob([file.data])
+     * const url = URL.createObjectURL(blob)
+     * ```
+     */
+    downloadFile(reference: Reference, path?: string, options?: DownloadOptions, requestOptions?: RequestOptions): Promise<FileData>;
+    /**
+     * Uploads a folder as one manifest (#750): a fork per file with its path and
+     * content type, which a gateway serves at `/bzz/<reference>/<path>` when the
+     * folder is plain (`encrypt: false`). Takes what bee-js takes — the
+     * `FileList` of a `webkitdirectory` input or a dropped directory, a `File[]`,
+     * or `{ path, file }` pairs for a folder the app assembled itself. A `File`'s
+     * path is its `webkitRelativePath` minus the picked folder's own name, or its
+     * name.
+     *
+     * Content is encrypted unless `options.encrypt` is `false`, and the
+     * manifest too — a 64-byte root reference — unless `options.encrypt` or
+     * `options.encryptManifest` is `false`. Name `options.indexDocument` for
+     * the bare `/bzz/<reference>/` to serve a file. Read a folder back with
+     * {@link listFiles} and {@link downloadData} per entry, or one file with
+     * {@link downloadFile} and its path.
+     *
+     * Every file is read into memory before the upload starts; for folders
+     * larger than that, upload the files with {@link uploadData} and build the
+     * manifest with `@ethersphere/core-sdk`.
+     *
+     * @param files - The folder's files
+     * @param options - Optional upload configuration; `onProgress` counts files, `useWorkers` / `workerCount` stamp in a pool as with {@link uploadData}
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the upload result
+     * @returns return.reference - The Swarm reference of the manifest
+     * @returns return.tagUid - The tag UID if a tag was created
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not authenticated or cannot upload
+     * @throws {Error} If two files share a path
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * // <input type="file" webkitdirectory>
+     * const { reference } = await client.uploadFiles(input.files, {
+     *   indexDocument: 'index.html',
+     * })
+     * // or assembled by the app
+     * await client.uploadFiles([{ path: 'a/b.txt', file: new Blob(['hi']) }])
+     * ```
+     */
+    uploadFiles(files: FileList | Iterable<File | CollectionFileInput>, options?: UploadFilesOptions, requestOptions?: RequestOptions): Promise<UploadResult>;
+    /**
+     * Lists the files of a manifest uploaded with {@link uploadFiles} (or any
+     * manifest): each entry's path, content type, and the reference of its
+     * content, which {@link downloadData} reads.
+     *
+     * @param reference - The Swarm reference of the manifest
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry)
+     * @returns A promise resolving to the entries, the index-document fork excluded
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the reference is not a manifest or is not found
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * for (const { path, reference } of await client.listFiles(root)) {
+     *   const data = await client.downloadData(reference)
+     * }
+     * ```
+     */
+    listFiles(reference: Reference, requestOptions?: RequestOptions): Promise<CollectionEntry[]>;
+    /**
+     * Forward the proxy's `uploadProgress` messages for one request to a
+     * callback, through the window listener's checks. Returns the function that
+     * stops forwarding; a no-op without a callback.
+     */
+    private listenForProgress;
+    /**
+     * Uploads a single chunk to the Swarm network.
+     *
+     * Chunks are the fundamental unit of storage in Swarm (4KB each).
+     * This method is useful for low-level operations or when implementing
+     * custom chunking strategies.
+     *
+     * `data` is the chunk's payload, not a finished chunk: the proxy builds the
+     * content-addressed chunk around it (span header, BMT address) and returns
+     * that address. A chunk that already carries its span header is wrapped a
+     * second time and stored under an address nothing else computes (#774). To
+     * store a folder as a manifest, use {@link uploadFiles}; to save a Mantaray
+     * tree of your own, use `saveMantarayTreeRecursively` with {@link uploadData}.
+     *
+     * @param data - The chunk payload, 1 to 4096 bytes
+     * @param options - Optional upload configuration
+     * @param options.pin - Whether to pin the chunk locally (defaults to false; ignored on a subsidised gateway)
+     * @param options.encrypt - Whether to encrypt the chunk (defaults to false)
+     * @param options.tag - Tag ID for tracking upload progress
+     * @param options.deferred - Whether to use deferred upload (defaults to false)
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the upload result
+     * @returns return.reference - The Swarm reference (hash) of the uploaded chunk
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not authenticated or cannot upload
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const chunk = new Uint8Array(4096) // 4KB chunk
+     * chunk.fill(0x42) // Fill with data
+     * const result = await client.uploadChunk(chunk)
+     * console.log('Chunk reference:', result.reference)
+     * ```
+     */
+    uploadChunk(data: Uint8Array, options?: UploadOptions, requestOptions?: RequestOptions): Promise<UploadResult>;
+    /**
+     * Downloads a single chunk from the Swarm network.
+     *
+     * Retrieves a chunk by its reference hash. This method is useful for
+     * low-level operations or when implementing custom retrieval strategies.
+     *
+     * @param reference - The Swarm reference (hash) of the chunk to download
+     * @param options - Optional download configuration
+     * @param options.redundancyStrategy - Strategy for handling redundancy (0-3)
+     * @param options.fallback - Whether to use fallback retrieval
+     * @param options.timeoutMs - Download timeout in milliseconds
+     * @param options.actPublisher - ACT publisher for encrypted content
+     * @param options.actHistoryAddress - ACT history address for encrypted content
+     * @param options.actTimestamp - ACT timestamp for encrypted content
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the chunk data as a Uint8Array
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the reference is not found
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const chunk = await client.downloadChunk('a1b2c3...')
+     * console.log('Chunk size:', chunk.length)
+     * ```
+     */
+    downloadChunk(reference: Reference, options?: DownloadOptions, requestOptions?: RequestOptions): Promise<Uint8Array>;
+    /**
+     * Returns an object for reading single owner chunks (SOC).
+     *
+     * @param ownerAddress - Ethereum address of the SOC owner
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns SOCReader with `download` (encrypted) and `rawDownload` (unencrypted)
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const reader = client.makeSOCReader(owner)
+     * const soc = await reader.download(identifier, encryptionKey)
+     * console.log('Payload:', new TextDecoder().decode(soc.payload))
+     * ```
+     */
+    makeSOCReader(ownerAddress: EthAddress | Uint8Array | string, requestOptions?: RequestOptions): SOCReader;
+    /**
+     * Returns an object for reading and writing single owner chunks (SOC).
+     *
+     * Uploads are encrypted by default. Use `rawUpload` for unencrypted SOCs.
+     *
+     * @param signer - Optional SOC signer private key. If omitted, the proxy uses the app signer.
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns SOCWriter with `upload`, `rawUpload`, `download`, and `rawDownload`
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const writer = client.makeSOCWriter()
+     * const upload = await writer.upload(identifier, payload)
+     * const soc = await writer.download(identifier, upload.encryptionKey)
+     * ```
+     */
+    makeSOCWriter(signer?: PrivateKey | Uint8Array | string, requestOptions?: RequestOptions): SOCWriter;
+    /**
+     * Returns an object for reading epoch-based feeds.
+     *
+     * @param options - Feed reader options
+     * @param options.topic - Feed topic (32 bytes)
+     * @param options.owner - Optional feed owner address
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns FeedReader with `getOwner`, `downloadReference`, and `downloadPayload`
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the request times out
+     */
+    makeEpochFeedReader(options: FeedReaderOptions, requestOptions?: RequestOptions): FeedReader;
+    /**
+     * Returns an object for reading and writing epoch-based feeds.
+     *
+     * @param options - Feed writer options
+     * @param options.topic - Feed topic (32 bytes)
+     * @param options.signer - Optional feed signer private key. If omitted, the proxy uses the app signer.
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns FeedWriter with `getOwner`, `downloadReference`, `downloadPayload`, `uploadPayload`, and `uploadReference`
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the request times out
+     */
+    makeEpochFeedWriter(options: FeedWriterOptions, requestOptions?: RequestOptions): FeedWriter;
+    /**
+     * Returns a sequential feed reader (chunk API only).
+     *
+     * @param options - Sequential feed reader options
+     * @param options.topic - Feed topic (32 bytes)
+     * @param options.owner - Optional feed owner address
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns SequentialFeedReader with payload/reference download helpers
+     */
+    makeSequentialFeedReader(options: SequentialFeedReaderOptions, requestOptions?: RequestOptions): SequentialFeedReader;
+    /**
+     * Returns a sequential feed writer (chunk API only).
+     *
+     * @param options - Sequential feed writer options
+     * @param options.topic - Feed topic (32 bytes)
+     * @param options.signer - Optional signer private key. If omitted, proxy uses app signer.
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns SequentialFeedWriter with payload/reference upload helpers
+     */
+    makeSequentialFeedWriter(options: SequentialFeedWriterOptions, requestOptions?: RequestOptions): SequentialFeedWriter;
+    /**
+     * Creates a feed manifest for accessing feed content via URL.
+     *
+     * A feed manifest enables accessing the latest feed content via a URL path
+     * (e.g., `/bzz/{manifest-reference}/`). The manifest stores metadata about
+     * the feed including owner, topic, and type.
+     *
+     * @param topic - Feed topic (32-byte hex string)
+     * @param options - Optional configuration
+     * @param options.owner - Feed owner address; if omitted, uses app signer
+     * @param options.uploadOptions - Upload configuration (pin, deferred, etc.)
+     * @param requestOptions - Request configuration (timeout, headers). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns Promise resolving to the manifest reference
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If no owner is provided and no app signer is available
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * // Create manifest for a feed (uses app signer as owner)
+     * const manifestRef = await client.createFeedManifest(topic)
+     * console.log('Feed accessible at /bzz/' + manifestRef)
+     *
+     * // Create manifest with explicit owner
+     * const manifestRef = await client.createFeedManifest(topic, {
+     *   owner: '0x1234...',
+     * })
+     * ```
+     */
+    createFeedManifest(topic: string, options?: {
+        owner?: string;
+        /** Feed type: "Sequence" for sequential feeds, "Epoch" for epoch feeds. Default: "Sequence" */
+        feedType?: "Sequence" | "Epoch";
+        uploadOptions?: UploadOptions;
+    }, requestOptions?: RequestOptions): Promise<string>;
+    /**
+     * Mines a private key whose SOC address is proximate to a target overlay.
+     *
+     * This is a synchronous, pure computation that does not require authentication.
+     * The mined signer can be used with {@link gsocSend} to send GSOC messages
+     * that route to the target overlay node.
+     *
+     * @param targetOverlay - The target overlay address to mine proximity for
+     * @param identifier - The GSOC identifier
+     * @param proximity - Optional proximity depth (defaults to 12 in bee-js)
+     * @returns A promise resolving to the mined signer as a hex string (private key)
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If no valid signer can be mined
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const signer = await client.gsocMine(targetOverlay, identifier)
+     * // Use signer with gsocSend
+     * await client.gsocSend(signer, identifier, data)
+     * ```
+     */
+    gsocMine(targetOverlay: string, identifier: string, proximity?: number): Promise<string>;
+    /**
+     * Sends a GSOC (Global Single Owner Chunk) message using a mined signer.
+     *
+     * The signer should be obtained from {@link gsocMine}. The message is sent
+     * using the proxy's stored postage batch ID.
+     *
+     * @param signer - The mined signer as a hex string (from gsocMine)
+     * @param identifier - The GSOC identifier
+     * @param data - The message data to send
+     * @param options - Optional upload configuration
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the upload result with reference and optional tagUid
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not authenticated
+     * @throws {Error} If no postage batch ID is available
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const signer = await client.gsocMine(targetOverlay, identifier)
+     * const result = await client.gsocSend(signer, identifier, new TextEncoder().encode('Hello!'))
+     * console.log('GSOC reference:', result.reference)
+     * ```
+     */
+    gsocSend(signer: string, identifier: string, data: Uint8Array, options?: UploadOptions, requestOptions?: RequestOptions): Promise<UploadResult>;
+    /**
+     * Uploads data with ACT (Access Control Tries) protection.
+     *
+     * This method encrypts the data and creates an ACT that controls who can decrypt it.
+     * Only the specified grantees (and the publisher) can decrypt and access the data.
+     *
+     * @param data - The binary data to upload as a Uint8Array
+     * @param grantees - Array of grantee public keys as compressed hex strings (33 bytes = 66 hex chars).
+     *   A grantee is either another user's `appKey.publicKey` (that user in this app origin only) or
+     *   their `identity.sharingPublicKey` (that user in every app they connect, #519)
+     * @param options - Optional upload configuration
+     * @param options.publisher - `"app"` (default) publishes with this origin's app key; `"identity"`
+     *   publishes with the account-wide sharing key, so any of the user's apps can manage the grantees later
+     * @param options.pin - Whether to pin the data locally (defaults to false; ignored on a subsidised gateway)
+     * @param options.tag - Tag ID for tracking upload progress
+     * @param options.deferred - Whether to use deferred upload (defaults to false)
+     * @param options.onProgress - Optional callback for tracking upload progress
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the ACT upload result
+     * @returns return.encryptedReference - The encrypted reference that must be stored with the ACT
+     * @returns return.actReference - The Swarm reference (hash) of the ACT manifest
+     * @returns return.historyReference - The Swarm reference of the history manifest (use for future operations)
+     * @returns return.granteeListReference - The Swarm reference of the encrypted grantee list
+     * @returns return.publisherPubKey - The publisher's compressed public key (share with grantees)
+     * @returns return.tagUid - The tag UID if a tag was created
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not authenticated or cannot upload
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const data = new TextEncoder().encode('Secret message')
+     * const grantees = ['03a1b2c3...'] // Compressed public keys of allowed readers
+     * const result = await client.actUploadData(data, grantees, {
+     *   onProgress: (progress) => {
+     *     console.log(`Progress: ${progress.processed}/${progress.total}`)
+     *   },
+     * })
+     * console.log('History Reference:', result.historyReference)
+     * console.log('Encrypted Reference:', result.encryptedReference)
+     * console.log('Publisher Public Key:', result.publisherPubKey)
+     * ```
+     */
+    actUploadData(data: Uint8Array, grantees: string[], options?: ActUploadOptions, requestOptions?: RequestOptions): Promise<{
+        encryptedReference: string;
+        historyReference: string;
+        granteeListReference: string;
+        publisherPubKey: string;
+        actReference: string;
+        tagUid?: number;
+    }>;
+    /**
+     * Downloads ACT-protected data from the Swarm network.
+     *
+     * This method decrypts the ACT to recover the content reference,
+     * then downloads and returns the decrypted data. Only authorized
+     * grantees (including the publisher) can successfully decrypt.
+     *
+     * @param encryptedReference - The encrypted reference from actUploadData
+     * @param historyReference - The history reference from actUploadData
+     * @param publisherPubKey - The publisher's compressed public key from actUploadData
+     * @param timestamp - Optional timestamp to look up a specific ACT version
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the decrypted data as a Uint8Array
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not authorized to decrypt the ACT
+     * @throws {Error} If the references are not found
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * // Using the references from actUploadData
+     * const data = await client.actDownloadData(
+     *   encryptedReference,
+     *   historyReference,
+     *   publisherPubKey
+     * )
+     * const text = new TextDecoder().decode(data)
+     * console.log('Decrypted:', text)
+     * ```
+     */
+    actDownloadData(encryptedReference: string, historyReference: string, publisherPubKey: string, timestamp?: number, requestOptions?: RequestOptions): Promise<Uint8Array>;
+    /**
+     * Adds new grantees to an existing ACT.
+     *
+     * This method adds new public keys to the ACT's access list.
+     * Only the publisher (original uploader) can add grantees.
+     * Returns new references since Swarm content is immutable.
+     *
+     * @param historyReference - The current history reference
+     * @param grantees - Array of new grantee public keys as compressed hex strings
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the new references
+     * @returns return.historyReference - The new history reference after adding grantees
+     * @returns return.granteeListReference - The new grantee list reference
+     * @returns return.actReference - The new ACT reference
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not the publisher
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const newGrantees = ['03d4e5f6...'] // New public keys to grant access
+     * const result = await client.actAddGrantees(historyReference, newGrantees)
+     * console.log('New History Reference:', result.historyReference)
+     * // The encrypted reference remains the same
+     * ```
+     */
+    actAddGrantees(historyReference: string, grantees: string[], requestOptions?: RequestOptions): Promise<{
+        historyReference: string;
+        granteeListReference: string;
+        actReference: string;
+    }>;
+    /**
+     * Revokes grantees from an existing ACT.
+     *
+     * This method removes public keys from the ACT's access list, producing a new
+     * ACT/history without the revoked entries.
+     *
+     * IMPORTANT: Revocation cannot un-share already-published content. A former
+     * grantee kept the access key while granted and the reference lives in
+     * immutable history, so they can still decrypt content published before
+     * revocation. Revocation only stops access to content published afterwards.
+     * The returned `encryptedReference` is unchanged — it is NOT re-encrypted, as
+     * that would leak the keystream to former grantees (#496).
+     *
+     * @param historyReference - The current history reference
+     * @param encryptedReference - The current encrypted reference
+     * @param revokeGrantees - Array of grantee public keys to revoke as compressed hex strings
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to the new references after revocation
+     * @returns return.encryptedReference - The content reference, unchanged
+     * @returns return.historyReference - The new history reference after revocation
+     * @returns return.granteeListReference - The new grantee list reference
+     * @returns return.actReference - The new ACT reference after revocation
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not the publisher
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const revokeKeys = ['03a1b2c3...'] // Public keys to revoke
+     * const result = await client.actRevokeGrantees(historyReference, encryptedReference, revokeKeys)
+     * console.log('New History Reference:', result.historyReference)
+     * // encryptedReference is unchanged; historyReference/actReference are new
+     * ```
+     */
+    actRevokeGrantees(historyReference: string, encryptedReference: string, revokeGrantees: string[], requestOptions?: RequestOptions): Promise<{
+        encryptedReference: string;
+        historyReference: string;
+        granteeListReference: string;
+        actReference: string;
+    }>;
+    /**
+     * Retrieves the list of grantees from an ACT.
+     *
+     * Only the publisher (original uploader) can view the grantee list,
+     * as it is encrypted with the publisher's key.
+     *
+     * @param historyReference - The history reference
+     * @param requestOptions - Optional request configuration (timeout, headers, endlesslyRetry). `timeout` replaces the client default for this call's whole round trip, not only the Bee request
+     * @returns A promise resolving to an array of grantee public keys as compressed hex strings
+     * @throws {Error} If the client is not initialized
+     * @throws {Error} If the user is not the publisher
+     * @throws {Error} If the request times out
+     *
+     * @example
+     * ```typescript
+     * const grantees = await client.actGetGrantees(historyReference)
+     * console.log('Current grantees:', grantees.length)
+     * grantees.forEach(pubKey => console.log('  -', pubKey))
+     * ```
+     */
+    actGetGrantees(historyReference: string, requestOptions?: RequestOptions): Promise<string[]>;
+    /**
+     * Destroys the client and releases all resources.
+     *
+     * This method should be called when the client is no longer needed.
+     * It performs the following cleanup:
+     * - Rejects every pending request, and a pending `initialize()`, with a
+     *   `SwarmIdError` of code `invalid-state`
+     * - Removes the message event listener
+     * - Removes the iframe from the DOM
+     * - Resets the client to an uninitialized state
+     *
+     * After calling destroy(), the client instance cannot be reused.
+     * Create a new instance if you need to reconnect.
+     *
+     * @example
+     * ```typescript
+     * // Clean up when component unmounts
+     * useEffect(() => {
+     *   const client = new SwarmIdClient({ ... })
+     *   client.initialize()
+     *
+     *   return () => {
+     *     client.destroy()
+     *   }
+     * }, [])
+     * ```
+     */
+    destroy(): void;
+}