@synonymdev/pubky 0.16.2 → 0.17.1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@synonymdev/pubky",
   "type": "module",
   "description": "Decentralized identity, auth flows, and user-owned storage",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/pubky.d.ts

@@ -45,7 +45,7 @@ export interface VerifiedGrantClaims {
  * Provides a simplified, actionable set of error categories for developers
  * to handle in their code.
  */
-export type PubkyErrorName = "RequestError" | "InvalidInput" | "AuthenticationError" | "PkarrError" | "ClientStateError" | "InternalError";
+export type PubkyErrorName = "RequestError" | "CredentialRefreshError" | "InvalidInput" | "AuthenticationError" | "PkarrError" | "ClientStateError" | "InternalError";
 
 /**
  * Optional x-callback-url metadata carried by a Pubky deep link.
@@ -152,7 +152,7 @@ export type GrantApprovalFormat = "bareGrant" | "signedApprovalV1";
  *
  * @property name - A machine-readable error code from {@link PubkyErrorName}. Use this for programmatic error handling.
  * @property message - A human-readable, descriptive error message suitable for logging.
- * @property data - An optional payload containing structured context for an error. For a `RequestError`, this may contain an object with the HTTP status code, e.g., `{ statusCode: 404 }`.
+ * @property data - Optional structured context. For a `RequestError` it is a {@link RequestErrorData}, e.g. `{ reason: "Http", statusCode: 404 }`.
  *
  * @example
  * ```typescript
@@ -160,14 +160,11 @@ export type GrantApprovalFormat = "bareGrant" | "signedApprovalV1";
  *   await client.signup(...);
  * } catch (e) {
  *   const error = e as PubkyError;
- *   if (
- *     error.name === "RequestError" &&
- *     typeof error.data === "object" &&
- *     error.data !== null &&
- *     "statusCode" in error.data &&
- *     (error.data as { statusCode?: number }).statusCode === 404
- *   ) {
- *     // Handle not found...
+ *   if (error.name === "RequestError") {
+ *     const data = error.data as RequestErrorData;
+ *     if (data.statusCode === 404) {
+ *       // Handle not found...
+ *     }
  *   }
  * }
  * ```
@@ -178,13 +175,34 @@ export interface PubkyError extends Error {
     data?: unknown;
 }
 
+/** The classified cause of a `RequestError`, carried in `PubkyError.data.reason`. */
+export type RequestErrorReason =
+| "Http"
+| "Timeout"
+| "Connection"
+| "Body"
+| "Decode"
+| "InvalidRequest"
+| "Other";
+
+/**
+ * `PubkyError.data` for a `RequestError`.
+ *
+ * `statusCode` is present when `reason` is `"Http"`. A reason describes the
+ * failure, not whether retrying is safe.
+ */
+export interface RequestErrorData {
+    reason: RequestErrorReason;
+    statusCode?: number;
+}
+
 /**
  * Represents the standard error structure for all exceptions thrown by the Pubky
  * WASM client.
  *
  * @property name - A machine-readable error code from {@link PubkyErrorName}. Use this for programmatic error handling.
  * @property message - A human-readable, descriptive error message suitable for logging.
- * @property data - An optional payload containing structured context for an error. For a `RequestError`, this may contain an object with the HTTP status code, e.g., `{ statusCode: 404 }`.
+ * @property data - Optional structured context. For a `RequestError` it is a {@link RequestErrorData}, e.g. `{ reason: "Http", statusCode: 404 }`.
  *
  * @example
  * ```typescript
@@ -192,14 +210,11 @@ export interface PubkyError extends Error {
  *   await client.signup(...);
  * } catch (e) {
  *   const error = e as PubkyError;
- *   if (
- *     error.name === 'RequestError' &&
- *     typeof error.data === 'object' &&
- *     error.data !== null &&
- *     'statusCode' in error.data &&
- *     (error.data as { statusCode?: number }).statusCode === 404
- *   ) {
- *     // Handle not found...
+ *   if (error.name === 'RequestError') {
+ *     const data = error.data as RequestErrorData;
+ *     if (data.statusCode === 404) {
+ *       // Handle not found...
+ *     }
  *   }
  * }
  * ```
@@ -1937,8 +1952,10 @@ export class SessionInfo {
  *
  * 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.
+ * Automatic grant refresh failures use `CredentialRefreshError`, with the
+ * refresh HTTP status in `data.statusCode` when available. URL parsing failures
+ * use `InvalidInput`. Other credential preparation 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.
@@ -2044,6 +2061,38 @@ export class SessionStorage {
      * See {@link SessionStorage} for shared errors.
      */
     lock(path: Path, timeout_seconds: number): Promise<StorageLock>;
+    /**
+     * Upload a Blob or File to a locked path without copying its contents into
+     * WASM memory.
+     *
+     * @param {StorageLock} lock A lock you hold. The upload uses the lock's path.
+     * @param {Blob} body A Blob or File to upload.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} An expired or released lock rejects with status `412`.
+     * A file that changed since the write was prepared rejects with status `409`.
+     * See {@link SessionStorage.putBytesLocked} for recovery and
+     * {@link SessionStorage.putBlob} for input validation and shared errors.
+     * @example
+     * const lock = await session.storage.lock("/pub/example.com/file.bin", 30);
+     * try {
+     *   await session.storage.putBlobLocked(lock, file);
+     * } finally {
+     *   await session.storage.unlock(lock);
+     * }
+     */
+    putBlobLocked(lock: StorageLock, body: Blob): Promise<void>;
+    /**
+     * Upload a Blob or File without copying its contents into WASM memory.
+     *
+     * @param {Path} path File path; must not end with `/`.
+     * @param {Blob} body A Blob or File to upload.
+     * @returns {Promise<void>}
+     * @throws {PubkyError} `InvalidInput` if body is not a Blob or File;
+     * otherwise upload or shared write/request errors (see {@link SessionStorage}).
+     * @example
+     * await session.storage.putBlob("/pub/example.com/file.bin", file);
+     */
+    putBlob(path: Path, body: Blob): Promise<void>;
     /**
      * `PUT` binary data to the path of a lock this client holds.
      *