@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

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

@@ -0,0 +1,1143 @@
+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 beeApiUrl?;
+    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)
+     * @param options.subsidisedGatewayUrl - A gateway that stamps uploads for a person with no drive of their own (optional)
+     * @param options.beeApiUrl - The Bee node this site's content reads and stamped uploads go through, in place of the person's own setting. Their account and device coordination stay on their own node. Change it later with {@link setBeeApiUrl} (optional)
+     * @throws {Error} If constructed where there is no `window` (a server render)
+     * @throws {SwarmIdError} `invalid-request` if the provided app metadata is invalid, or `beeApiUrl` is not an http(s) URL without credentials, query or fragment
+     */
+    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)
+     * @returns return.beeApiUrl - The Bee node this site gave, if it gave one. The person's own node is never reported
+     * @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>;
+    /**
+     * Changes the Bee node this site's content reads and stamped uploads go
+     * through, without a reload, for example when the viewer picks another source. It
+     * replaces the `beeApiUrl` given at construction, and takes over from the
+     * person's own Bee setting on this site if none was given. Every other site,
+     * and Swarm ID itself, keep the person's setting. The checks and writes
+     * that coordinate the person's account and devices always use their own
+     * node. Nothing is stored: the next page load starts from the
+     * constructor's `beeApiUrl` again.
+     *
+     * Works signed in or not. A subsidised gateway the person's own custom node
+     * had switched off comes back once the site names its node.
+     *
+     * @param url - An http(s) URL, optionally with a path, without credentials, query or fragment
+     * @throws {SwarmIdError} `invalid-request` if `url` is not such a URL, and nothing is sent
+     * @throws {SwarmIdError} `invalid-state` if the client is not initialized
+     * @throws {SwarmIdError} `timeout` if the request times out
+     *
+     * @example
+     * ```typescript
+     * await client.setBeeApiUrl('https://bee.example.com/')
+     * console.log(client.connectionInfo.beeApiUrl)
+     * ```
+     */
+    setBeeApiUrl(url: string): Promise<void>;
+    /**
+     * 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;
+}