@synonymdev/pubky 0.11.0 → 0.13.0

package/pubky.d.ts

@@ -4,14 +4,14 @@
  * An enum representing the available verbosity levels of the logger.
  */
 
-type Level = "error" | "warn" | "info" | "debug" | "trace";
+export type Level = "error" | "warn" | "info" | "debug" | "trace";
 /**
  * The `ReadableStreamType` enum.
  *
  * *This API requires the following crate features to be activated: `ReadableStreamType`*
  */
 
-type ReadableStreamType = "bytes";
+export type ReadableStreamType = "bytes";
 /**
  * A union type of all possible machine-readable codes for the `name` property
  * of a {@link PubkyError}.
@@ -51,11 +51,11 @@ export interface XCallbackParams {
  */
 export interface GrantAuthFlowOptions {
     /**
-     * App identifier shown in the user\'s grant/session list, typically a domain.
+     * App identifier shown in the user's grant/session list, typically a domain.
      */
     clientId: string;
     /**
-     * Optional HTTP relay base, e.g. `\"https://demo.httprelay.io/inbox/\"`.
+     * Optional HTTP relay base, e.g. `"https://demo.httprelay.io/inbox/"`.
      * Defaults to the default Synonym-hosted relay when omitted.
      */
     relay?: string | null;
@@ -88,6 +88,12 @@ export interface PubkyClientConfig {
      * Configuration on how to access pkarr packets on the mainline DHT.
      */
     pkarr?: PkarrConfig;
+    /**
+     * Maximum raw HTTP error-body bytes to capture. Defaults to 4096; zero skips the body.
+     * UTF-8 decoding can produce up to three times as many bytes of text, plus the
+     * truncation marker. This does not cap final message size or total memory use.
+     */
+    maxErrorBodyBytes?: number;
 }
 
 /**
@@ -137,10 +143,10 @@ export interface PubkyError extends Error {
  * } catch (e) {
  *   const error = e as PubkyError;
  *   if (
- *     error.name === \'RequestError\' &&
- *     typeof error.data === \'object\' &&
+ *     error.name === 'RequestError' &&
+ *     typeof error.data === 'object' &&
  *     error.data !== null &&
- *     \'statusCode\' in error.data &&
+ *     'statusCode' in error.data &&
  *     (error.data as { statusCode?: number }).statusCode === 404
  *   ) {
  *     // Handle not found...
@@ -162,7 +168,7 @@ export interface PubkyError {
  *
  * @typedef {Object} ResourceStats
  * @property {number=} contentLength  Size in bytes.
- * @property {string=} contentType    Media type (e.g. \"application/json; charset=utf-8\").
+ * @property {string=} contentType    Media type (e.g. "application/json; charset=utf-8").
  * @property {number=} lastModifiedMs Unix epoch milliseconds.
  * @property {string=} etag           Opaque server ETag for the current version.
  *
@@ -183,7 +189,7 @@ export interface ResourceStats {
      */
     contentLength?: number;
     /**
-     * Media type of the stored object (e.g., `\"application/json\"`).
+     * Media type of the stored object (e.g., `"application/json"`).
      */
     contentType?: string;
     /**
@@ -256,6 +262,8 @@ export class AuthFlow {
      * @returns {AuthFlow} A flow reconnected to the original relay channel.
      * @throws {PubkyError}
      * - `{ name: "AuthenticationError" }` if the URL is invalid or not a signin/signup link
+     *
+     * @deprecated Use `GrantAuthFlow.resume(...)` instead.
      */
     static resume(authorization_url: string): AuthFlow;
     /**
@@ -445,13 +453,6 @@ export class BrowserSessionStore {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    /**
-     * Clear all local stored session records for this origin.
-     *
-     * Delegated keys referenced by those stored session records are removed.
-     * Delegated keys that only belong to pending grant flows are preserved.
-     */
-    clear(): Promise<void>;
     /**
      * Clear all browser auth persistence owned by this SDK origin.
      *
@@ -461,6 +462,13 @@ export class BrowserSessionStore {
      * grants or immediately invalidate already-live in-memory sessions.
      */
     clearAll(): Promise<void>;
+    /**
+     * Clear all local stored session records for this origin.
+     *
+     * Delegated keys referenced by those stored session records are removed.
+     * Delegated keys that only belong to pending grant flows are preserved.
+     */
+    clear(): Promise<void>;
     /**
      * Whether IndexedDB is available for durable session persistence.
      */
@@ -501,26 +509,27 @@ export class Client {
      *
      * @example
      * const client = pubky.client;
-     * const res = await client.fetch(`https://_pubky.${user}/pub/app/file.txt`, { method: "PUT", body: "hi", credentials: "include" });
+     * const res = await client.fetch(`https://_pubky.${user}/storage/${user}/pub/app/file.txt`, { method: "PUT", body: "hi", credentials: "include" });
      */
     fetch(url: string, init?: RequestInit | null): Promise<Response>;
     /**
      * Create a Pubky HTTP client.
      *
      * @param {PubkyClientConfig} [config]
-     * Optional transport overrides:
-     * `{ pkarr?: { relays?: string[], request_timeout?: number } }`.
+     * Optional error-body limit and PKARR overrides:
+     * `{ maxErrorBodyBytes?: number, pkarr?: { relays?: string[], requestTimeout?: number } }`.
      *
      * @returns {Client}
      * A configured low-level client. Prefer `new Pubky().client` unless you
-     * need custom relays/timeouts.
+     * need custom relays, timeouts or error-body limits.
      *
      * @throws {InvalidInput}
-     * If any PKARR relay URL is invalid.
+     * If a relay URL is invalid or the error-body limit is not an integer in 0..=4294967295.
      *
      * @example
      * const client = new Client({
-     *   pkarr: { relays: ["https://relay1/","https://relay2/"], request_timeout: 8000 }
+     *   maxErrorBodyBytes: 1024,
+     *   pkarr: { relays: ["https://relay1/","https://relay2/"], requestTimeout: 8000 }
      * });
      * const pubky = Pubky.withClient(client);
      */
@@ -549,22 +558,14 @@ export class Client {
 /**
  * Cookie-only view over a cookie-backed `Session`.
  *
- * Grant-backed sessions do not expose this view; use `session.cookie` and
- * check for `undefined` before calling cookie-specific methods.
+ * New applications should use `session.grant` and `GrantSession`.
+ *
+ * @deprecated Use `GrantSession` instead.
  */
 export class CookieSession {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    /**
-     * Export session metadata for legacy cookie restore.
-     *
-     * The returned string contains no secrets; the browser cookie jar must
-     * still hold the HTTP-only cookie.
-     *
-     * @returns {string}
-     */
-    export(): string;
     /**
      * Export the cookie secret needed to restore this cookie session.
      *
@@ -572,8 +573,19 @@ export class CookieSession {
      * Node.js. Browser sessions cannot read HTTP-only Set-Cookie values.
      *
      * @returns {Promise<string>}
+     * @deprecated Use `GrantSession.exportLocalSecret()` instead.
      */
     exportSecret(): Promise<string>;
+    /**
+     * Export session metadata for legacy cookie restore.
+     *
+     * The returned string contains no secrets; the browser cookie jar must
+     * still hold the HTTP-only cookie.
+     *
+     * @returns {string}
+     * @deprecated Use `GrantSession.exportLocalSecret()` instead.
+     */
+    export(): string;
 }
 
 /**
@@ -649,6 +661,7 @@ export class Event {
  * Builder for creating an event stream subscription.
  *
  * Construct via `Pubky.eventStreamForUser()` or `Pubky.eventStreamFor()`.
+ * Configuration methods consume this builder unless documented otherwise.
  *
  * @example
  * ```typescript
@@ -681,6 +694,8 @@ export class EventStreamBuilder {
      *
      * Each user can have an independent cursor position. If a user already exists,
      * their cursor value is overwritten.
+     * Updates this builder and returns a copy for chaining. Rejected input
+     * leaves this builder unchanged.
      *
      * @param {Array<[string, string | null]>} users - Array of [z32PublicKey, cursor] tuples
      * @returns {EventStreamBuilder} - Builder for chaining
@@ -739,6 +754,20 @@ export class EventStreamBuilder {
      * @returns {EventStreamBuilder} - Builder for chaining
      */
     live(): EventStreamBuilder;
+    /**
+     * Set a client-side byte limit for SSE payloads. Unbounded by default.
+     * Limits accumulated data (including newlines joining data fields), each
+     * event name, and each ID separately in historical and live streams.
+     * Comments, unknown fields and framing bytes are excluded.
+     * There is no total block or stream byte limit.
+     * Overflow cancels the response and errors the ReadableStream.
+     * Updates this builder and returns a copy for chaining. Rejected input
+     * leaves this builder unchanged.
+     *
+     * @param {number} limit - Integer in 1..=4294967295.
+     * @throws {InvalidInput} If the limit is not a positive 32-bit integer.
+     */
+    maxEventBytes(limit: number): EventStreamBuilder;
     /**
      * Filter events by path. Call once per path to receive the
      * union of several scopes (e.g. `/pub/` plus a private `/priv/app/`).
@@ -822,6 +851,15 @@ export class GrantAuthFlow {
      * Block until the user approves on their signer device; returns a grant-backed `Session`.
      */
     awaitApproval(): Promise<Session>;
+    /**
+     * Resume a previously saved pending delegated grant auth flow.
+     *
+     * Runtime: delegated grant keys require a secure browser context with
+     * WebCrypto `crypto.subtle` and IndexedDB. The saved `keyId` must still
+     * exist in IndexedDB for the same origin. Unsupported runtimes reject with
+     * `ClientStateError`.
+     */
+    static resumeDelegated(saved_state: string): Promise<GrantAuthFlow>;
     /**
      * Resume a previously saved pending grant auth flow (standalone).
      * Prefer `pubky.resumeGrantAuthFlow()` to reuse a facade client.
@@ -833,15 +871,6 @@ export class GrantAuthFlow {
      * @returns {GrantAuthFlow} A flow reconnected to the original relay channel.
      */
     static resume(saved_state: string): GrantAuthFlow;
-    /**
-     * Resume a previously saved pending delegated grant auth flow.
-     *
-     * Runtime: delegated grant keys require a secure browser context with
-     * WebCrypto `crypto.subtle` and IndexedDB. The saved `keyId` must still
-     * exist in IndexedDB for the same origin. Unsupported runtimes reject with
-     * `ClientStateError`.
-     */
-    static resumeDelegated(saved_state: string): Promise<GrantAuthFlow>;
     /**
      * Save sensitive state required to resume this delegated pending grant flow.
      *
@@ -857,6 +886,17 @@ export class GrantAuthFlow {
      * `pubky.resumeGrantAuthFlow()`.
      */
     saveLocal(): string;
+    /**
+     * Start a browser delegated grant-backed flow.
+     *
+     * The SDK creates a fresh non-extractable WebCrypto Ed25519 key in
+     * IndexedDB and uses that key for grant Proof-of-Possession signing.
+     *
+     * Runtime: delegated grant keys require a secure browser context with
+     * WebCrypto `crypto.subtle` and IndexedDB. Unsupported runtimes reject
+     * with `ClientStateError`.
+     */
+    static startDelegated(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): Promise<GrantAuthFlow>;
     /**
      * Start a grant-backed flow with a new DHT client.
      * Prefer `pubky.startGrantAuthFlow()` to reuse a facade DHT client.
@@ -876,17 +916,6 @@ export class GrantAuthFlow {
      * then `awaitApproval()` to receive a grant-backed `Session`.
      */
     static start(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): GrantAuthFlow;
-    /**
-     * Start a browser delegated grant-backed flow.
-     *
-     * The SDK creates a fresh non-extractable WebCrypto Ed25519 key in
-     * IndexedDB and uses that key for grant Proof-of-Possession signing.
-     *
-     * Runtime: delegated grant keys require a secure browser context with
-     * WebCrypto `crypto.subtle` and IndexedDB. Unsupported runtimes reject
-     * with `ClientStateError`.
-     */
-    static startDelegated(capabilities: Capabilities, kind: AuthFlowKind, options: GrantAuthFlowOptions): Promise<GrantAuthFlow>;
     /**
      * Non-blocking single poll step (advanced UIs).
      *
@@ -1055,6 +1084,18 @@ export class IntoUnderlyingByteSource {
     readonly type: ReadableStreamType;
 }
 
+declare class IntoUnderlyingByteSource2 {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableByteStreamController): Promise<any>;
+    start(controller: ReadableByteStreamController): void;
+    readonly autoAllocateChunkSize: number;
+    readonly type: ReadableStreamType;
+}
+export type { IntoUnderlyingByteSource2 };
+
 export class IntoUnderlyingSink {
     private constructor();
     free(): void;
@@ -1064,6 +1105,16 @@ export class IntoUnderlyingSink {
     write(chunk: any): Promise<any>;
 }
 
+declare class IntoUnderlyingSink2 {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    abort(reason: any): Promise<any>;
+    close(): Promise<any>;
+    write(chunk: any): Promise<any>;
+}
+export type { IntoUnderlyingSink2 };
+
 export class IntoUnderlyingSource {
     private constructor();
     free(): void;
@@ -1072,6 +1123,15 @@ export class IntoUnderlyingSource {
     pull(controller: ReadableStreamDefaultController): Promise<any>;
 }
 
+declare class IntoUnderlyingSource2 {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    cancel(): void;
+    pull(controller: ReadableStreamDefaultController): Promise<any>;
+}
+export type { IntoUnderlyingSource2 };
+
 export class Keypair {
     private constructor();
     free(): void;
@@ -1119,14 +1179,6 @@ export class Pkdns {
      * PKDNS actor with publishing enabled (requires a keypair).
      */
     static fromKeypair(keypair: Keypair): Pkdns;
-    /**
-     * Resolve the homeserver for **this** user (requires keypair).
-     *
-     * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
-     * @throws When no keypair is attached, Pkarr resolution fails, or a resolved `_pubky` target
-     *   is malformed.
-     */
-    getHomeserver(): Promise<PublicKey | undefined>;
     /**
      * Resolve the homeserver for a given public key (read-only).
      *
@@ -1136,6 +1188,14 @@ export class Pkdns {
      * @throws When Pkarr resolution fails or a resolved `_pubky` target is malformed.
      */
     getHomeserverOf(pubky: PublicKey): Promise<PublicKey | undefined>;
+    /**
+     * Resolve the homeserver for **this** user (requires keypair).
+     *
+     * @returns {Promise<PublicKey|undefined>} Homeserver public key or `undefined` if not found.
+     * @throws When no keypair is attached, Pkarr resolution fails, or a resolved `_pubky` target
+     *   is malformed.
+     */
+    getHomeserver(): Promise<PublicKey | undefined>;
     /**
      * Read-only PKDNS actor (no keypair; resolve only).
      */
@@ -1167,19 +1227,19 @@ export class Pubky {
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Create an event stream builder for a specific homeserver.
+     * Create an event stream builder for a single user.
      *
-     * Use this when you already know the homeserver pubkey. This avoids
-     * Pkarr resolution overhead. Obtain a homeserver pubkey via `getHomeserverOf()`.
+     * This is the simplest way to subscribe to events for one user. The homeserver
+     * is automatically resolved from the user's Pkarr record.
      *
-     * @param {PublicKey} homeserver - The homeserver public key
+     * @param {PublicKey} user - The user's public key
+     * @param {string | null} cursor - Optional cursor position to start from
      * @returns {EventStreamBuilder} - Builder for configuring and subscribing to the stream
      *
      * @example
      * ```typescript
-     * const homeserver = await pubky.getHomeserverOf(user1);
-     * const stream = await pubky.eventStreamFor(homeserver)
-     *   .addUsers([[user1.z32(), null], [user2.z32(), null]])
+     * const user = PublicKey.from("o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo");
+     * const stream = await pubky.eventStreamForUser(user, null)
      *   .live()
      *   .subscribe();
      *
@@ -1188,21 +1248,21 @@ export class Pubky {
      * }
      * ```
      */
-    eventStreamFor(homeserver: PublicKey): EventStreamBuilder;
+    eventStreamForUser(user: PublicKey, cursor?: string | null): EventStreamBuilder;
     /**
-     * Create an event stream builder for a single user.
+     * Create an event stream builder for a specific homeserver.
      *
-     * This is the simplest way to subscribe to events for one user. The homeserver
-     * is automatically resolved from the user's Pkarr record.
+     * Use this when you already know the homeserver pubkey. This avoids
+     * Pkarr resolution overhead. Obtain a homeserver pubkey via `getHomeserverOf()`.
      *
-     * @param {PublicKey} user - The user's public key
-     * @param {string | null} cursor - Optional cursor position to start from
+     * @param {PublicKey} homeserver - The homeserver public key
      * @returns {EventStreamBuilder} - Builder for configuring and subscribing to the stream
      *
      * @example
      * ```typescript
-     * const user = PublicKey.from("o1gg96ewuojmopcjbz8895478wdtxtzzuxnfjjz8o8e77csa1ngo");
-     * const stream = await pubky.eventStreamForUser(user, null)
+     * const homeserver = await pubky.getHomeserverOf(user1);
+     * const stream = await pubky.eventStreamFor(homeserver)
+     *   .addUsers([[user1.z32(), null], [user2.z32(), null]])
      *   .live()
      *   .subscribe();
      *
@@ -1211,7 +1271,7 @@ export class Pubky {
      * }
      * ```
      */
-    eventStreamForUser(user: PublicKey, cursor?: string | null): EventStreamBuilder;
+    eventStreamFor(homeserver: PublicKey): EventStreamBuilder;
     /**
      * Resolve the homeserver for a given public key (read-only).
      *
@@ -1291,6 +1351,8 @@ export class Pubky {
      *     sessionStorage.removeItem("pubky-auth-url");
      *   }
      * }
+     *
+     * @deprecated Use `resumeGrantAuthFlow(...)` instead.
      */
     resumeCookieAuthFlow(authorization_url: string): AuthFlow;
     /**
@@ -1356,6 +1418,8 @@ export class Pubky {
      * const flow = pubky.startCookieAuthFlow("/pub/my-cool-app/:rw");
      * renderQr(flow.authorizationUrl);
      * const session = await flow.awaitApproval();
+     *
+     * @deprecated Use `startGrantAuthFlow(...)` instead.
      */
     startCookieAuthFlow(capabilities: Capabilities, kind: AuthFlowKind, relay?: string | null, x_callback?: XCallbackParams | null): AuthFlow;
     /**
@@ -1521,13 +1585,6 @@ export class PublicStorage {
      * @returns {Promise<boolean>}
      */
     exists(address: Address): Promise<boolean>;
-    /**
-     * Perform a streaming `GET` and expose the raw `Response` object.
-     *
-     * @param {Address} address
-     * @returns {Promise<Response>}
-     */
-    get(address: Address): Promise<Response>;
     /**
      * Fetch bytes from an addressed path.
      *
@@ -1549,6 +1606,13 @@ export class PublicStorage {
      * @returns {Promise<string>}
      */
     getText(address: Address): Promise<string>;
+    /**
+     * Perform a streaming `GET` and expose the raw `Response` object.
+     *
+     * @param {Address} address
+     * @returns {Promise<Response>}
+     */
+    get(address: Address): Promise<Response>;
     /**
      * List a directory. Results are `pubky://…` identifier URLs.
      *
@@ -1596,18 +1660,6 @@ export class Session {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
-    /**
-     * Export the session metadata so it can be restored after a tab refresh.
-     *
-     * The export string contains **no secrets**; it only serializes the public `SessionInfo`.
-     * Browsers remain responsible for persisting the HTTP-only session cookie.
-     *
-     * @returns {string}
-     * A base64 string to store (e.g. in `localStorage`).
-     *
-     * @deprecated Prefer `exportLocalSecret()` for grant sessions.
-     */
-    export(): string;
     /**
      * Export the local secret material needed to restore this session.
      *
@@ -1623,6 +1675,18 @@ export class Session {
      * A secret token that can be passed to `pubky.restoreSession()`.
      */
     exportLocalSecret(): Promise<string>;
+    /**
+     * Export the session metadata so it can be restored after a tab refresh.
+     *
+     * The export string contains **no secrets**; it only serializes the public `SessionInfo`.
+     * Browsers remain responsible for persisting the HTTP-only session cookie.
+     *
+     * @returns {string}
+     * A base64 string to store (e.g. in `localStorage`).
+     *
+     * @deprecated Use `GrantSession.exportLocalSecret()` instead.
+     */
+    export(): string;
     /**
      * Restore a session from an `export()` string.
      *
@@ -1635,7 +1699,7 @@ export class Session {
      * Optional client to reuse transport configuration.
      * @returns {Promise<Session>}
      *
-     * @deprecated Prefer `Pubky.restoreSession(...)`.
+     * @deprecated Use `Pubky.restoreSession(...)` with a grant secret.
      */
     static restore(exported: string, client?: Client | null): Promise<Session>;
     /**
@@ -1651,6 +1715,7 @@ export class Session {
      * Grant-backed sessions return `undefined`.
      *
      * @returns {CookieSession|undefined}
+     * @deprecated Use `session.grant` and `GrantSession` instead.
      */
     readonly cookie: CookieSession | undefined;
     /**
@@ -1704,94 +1769,123 @@ export class SessionInfo {
 
 /**
  * Read/write storage scoped to **your** session (absolute paths: `/pub/...` or `/priv/...`).
+ *
+ * Failures reject with a {@link PubkyError}. Path validation, transport, and HTTP
+ * failures use `RequestError`; only HTTP errors include `data.statusCode`.
+ * URL parsing failures use `InvalidInput`. Credential preparation, refresh,
+ * and reading response bodies can also fail.
+ *
+ * Only {@link SessionStorage.exists} and {@link SessionStorage.stats} treat
+ * HTTP 404/410 as missing. Other HTTP failures, including 401/403 and 5xx, reject.
+ * Writes require write permission and can fail on directory targets (400),
+ * file/directory path conflicts (409), or exceeded quotas (507).
  */
 export class SessionStorage {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
-     * Delete a path (file or empty directory).
+     * Delete a file. Directory targets are unsupported.
      *
-     * @param {Path} path
+     * @param {Path} path File path; must not end with `/`.
      * @returns {Promise<void>}
+     * @throws {PubkyError} Missing file (404), directory target (400), or shared errors
+     * (see {@link SessionStorage}).
      */
     delete(path: Path): Promise<void>;
     /**
-     * Check existence.
+     * Check existence with a HEAD request.
      *
      * @param {Path} path
-     * @returns {Promise<boolean>}
+     * @returns {Promise<boolean>} `true` on success; `false` for HTTP 404/410.
+     * @throws {PubkyError} All other failures (see {@link SessionStorage}).
      */
     exists(path: Path): Promise<boolean>;
-    /**
-     * GET a streaming response for an absolute session path.
-     *
-     * @param {Path} path
-     * @returns {Promise<Response>}
-     */
-    get(path: Path): Promise<Response>;
     /**
      * GET bytes from an absolute session path.
      *
      * @param {Path} path
-     * @returns {Promise<Uint8Array>}
+     * @returns {Promise<Uint8Array>} The complete response body.
+     * @throws {PubkyError} Missing resource (404/410) or shared errors (see {@link SessionStorage}).
      */
     getBytes(path: Path): Promise<Uint8Array>;
     /**
      * GET JSON from an absolute session path.
      *
      * @param {Path} path
-     * @returns {Promise<any>}
+     * @returns {Promise<any>} The parsed JSON value.
+     * @throws {PubkyError} Missing resource (404/410), JSON parsing/conversion failures,
+     * or shared errors (see {@link SessionStorage}).
      */
     getJson(path: Path): Promise<any>;
     /**
      * GET text from an absolute session path.
      *
      * @param {Path} path
-     * @returns {Promise<string>}
+     * @returns {Promise<string>} The complete response body decoded as text.
+     * @throws {PubkyError} Missing resource (404/410) or shared errors (see {@link SessionStorage}).
      */
     getText(path: Path): Promise<string>;
     /**
-     * List a directory (absolute session path). Returns `pubky://…` URLs.
+     * GET a streaming response for an absolute session path.
+     *
+     * Reading the returned response body can still fail after this resolves.
+     *
+     * @param {Path} path
+     * @returns {Promise<Response>} A successful response with an unread body.
+     * @throws {PubkyError} Missing resource (404/410) or other request/response errors.
+     * See {@link SessionStorage} for shared errors.
+     */
+    get(path: Path): Promise<Response>;
+    /**
+     * List a directory (absolute session path).
      *
      * @param {Path} path Must end with `/`.
-     * @param {string|null=} cursor Optional suffix or full URL to start **after**.
+     * @param {string|null=} cursor Optional last entry URL to start **after**.
      * @param {boolean=} reverse Default `false`.
      * @param {number=} limit Optional result limit.
      * @param {boolean=} shallow Default `false`.
-     * @returns {Promise<string[]>}
+     * @returns {Promise<string[]>} `pubky://…` entry URLs, or an empty array for an empty page.
+     * @throws {PubkyError} Missing directory (404), invalid cursor (400), invalid response
+     * entries, or shared errors (see {@link SessionStorage}).
      */
     list(path: Path, cursor?: string | null, reverse?: boolean | null, limit?: number | null, shallow?: boolean | null): Promise<string[]>;
     /**
-     * PUT binary at an absolute session path.
+     * Create or replace a file with binary data at an absolute session path.
      *
-     * @param {Path} path
-     * @param {Uint8Array} bytes
+     * @param {Path} path File path; must not end with `/`.
+     * @param {Uint8Array} body
      * @returns {Promise<void>}
+     * @throws {PubkyError} Upload or shared write/request errors (see {@link SessionStorage}).
      */
     putBytes(path: Path, body: Uint8Array): Promise<void>;
     /**
-     * PUT JSON at an absolute session path.
+     * Create or replace a file with JSON at an absolute session path.
      *
-     * @param {Path} path Absolute path (e.g. `"/pub/app/data.json"`).
-     * @param {any} value JSON-serializable value.
+     * @param {Path} path File path (e.g. `"/pub/app/data.json"`); must not end with `/`.
+     * @param {any} body JSON-serializable value.
      * @returns {Promise<void>}
+     * @throws {PubkyError} `InvalidInput` if `body` cannot be converted to JSON;
+     * otherwise serialization, upload, or shared write/request errors (see {@link SessionStorage}).
      */
     putJson(path: Path, body: any): Promise<void>;
     /**
-     * PUT text at an absolute session path.
+     * Create or replace a file with text at an absolute session path.
      *
-     * @param {Path} path
-     * @param {string} text
+     * @param {Path} path File path; must not end with `/`.
+     * @param {string} body
      * @returns {Promise<void>}
+     * @throws {PubkyError} Upload or shared write/request errors (see {@link SessionStorage}).
      */
     putText(path: Path, body: string): Promise<void>;
     /**
      * Get metadata for an absolute, session-scoped path (e.g. `"/pub/app/file.json"`).
      *
+     * On success, missing or unparseable metadata headers leave their properties absent.
+     *
      * @param {Path} path Absolute path under your user (starts with `/`).
-     * @returns {Promise<ResourceStats|undefined>} `undefined` if the resource does not exist.
-     * @throws {PubkyError} On invalid input or transport/server errors.
+     * @returns {Promise<ResourceStats|undefined>} Metadata on success; `undefined` for HTTP 404/410.
+     * @throws {PubkyError} All other failures (see {@link SessionStorage}).
      */
     stats(path: Path): Promise<ResourceStats | undefined>;
 }
@@ -1826,39 +1920,45 @@ export class Signer {
      */
     handleDeepLink(pubkyauth_url: string): Promise<void>;
     /**
-     * Fast sign-in for a returning user. Publishes PKDNS in the background.
+     * Blocking sign-in. Waits for PKDNS publish to complete (slower; safer).
      *
      * Creates a valid grant-backed homeserver Session with root capabilities.
      * `clientId` is shown in the user's grant/session list.
      * @param {string} clientId App identifier, typically a domain.
      *
      * @returns {Promise<Session>}
+     */
+    signinBlocking(client_id: string): Promise<Session>;
+    /**
+     * Legacy cookie blocking signin. Prefer `signinBlocking(clientId)`.
      *
-     * @throws {PubkyError}
+     * @deprecated Prefer `signinBlocking(clientId)`.
      */
-    signin(client_id: string): Promise<Session>;
+    signinCookieBlocking(): Promise<Session>;
     /**
-     * Blocking sign-in. Waits for PKDNS publish to complete (slower; safer).
+     * Legacy cookie signin. Prefer `signin(clientId)`.
+     *
+     * @deprecated Prefer `signin(clientId)`.
+     */
+    signinCookie(): Promise<Session>;
+    /**
+     * Fast sign-in for a returning user. Publishes PKDNS in the background.
      *
      * Creates a valid grant-backed homeserver Session with root capabilities.
      * `clientId` is shown in the user's grant/session list.
      * @param {string} clientId App identifier, typically a domain.
      *
      * @returns {Promise<Session>}
-     */
-    signinBlocking(client_id: string): Promise<Session>;
-    /**
-     * Legacy cookie signin. Prefer `signin(clientId)`.
      *
-     * @deprecated Prefer `signin(clientId)`.
+     * @throws {PubkyError}
      */
-    signinCookie(): Promise<Session>;
+    signin(client_id: string): Promise<Session>;
     /**
-     * Legacy cookie blocking signin. Prefer `signinBlocking(clientId)`.
+     * Legacy cookie signup. Prefer `signup()` plus `signin(clientId)`.
      *
-     * @deprecated Prefer `signinBlocking(clientId)`.
+     * @deprecated Prefer `signup()` followed by `signin(clientId)`.
      */
-    signinCookieBlocking(): Promise<Session>;
+    signupCookie(homeserver: PublicKey, signup_token?: string | null): Promise<Session>;
     /**
      * Sign up at a homeserver.
      *
@@ -1873,12 +1973,6 @@ export class Signer {
      * - `RequestError` (network/server)
      */
     signup(homeserver: PublicKey, signup_token?: string | null): Promise<void>;
-    /**
-     * Legacy cookie signup. Prefer `signup()` plus `signin(clientId)`.
-     *
-     * @deprecated Prefer `signup()` followed by `signin(clientId)`.
-     */
-    signupCookie(homeserver: PublicKey, signup_token?: string | null): Promise<Session>;
     /**
      * Get a PKDNS actor bound to this signer's client & keypair (publishing enabled).
      *
@@ -2113,7 +2207,7 @@ export class StoredSessionInfo {
  * Resolve a `pubky://` or `pubky<pk>/…` identifier into the homeserver transport URL.
  *
  * @param {string} identifier Either `pubky<pk>/...` (preferred) or `pubky://<pk>/...`.
- * @returns {string} HTTPS URL in the form `https://_pubky.<pk>/...`.
+ * @returns {string} HTTPS URL in the form `https://_pubky.<pk>/storage/<pk>/...`.
  */
 export function resolvePubky(identifier: string): string;