@opendatalabs/vana-sdk 0.1.0-alpha.8eb4e46 → 0.1.0-alpha.a145c3c

package/dist/index.node.cjs

@@ -413,7 +413,6 @@ __export(index_node_exports, {
   BaseController: () => BaseController,
   BlockchainError: () => BlockchainError,
   BrowserPlatformAdapter: () => BrowserPlatformAdapter,
-  CallbackStorage: () => CallbackStorage,
   CircuitBreaker: () => CircuitBreaker,
   ContractFactory: () => ContractFactory,
   ContractNotFoundError: () => ContractNotFoundError,
@@ -448,6 +447,7 @@ __export(index_node_exports, {
   SchemaValidator: () => SchemaValidator,
   SerializationError: () => SerializationError,
   ServerController: () => ServerController,
+  ServerProxyStorage: () => ServerProxyStorage,
   ServerUrlMismatchError: () => ServerUrlMismatchError,
   SignatureError: () => SignatureError,
   StorageError: () => StorageError,
@@ -34507,6 +34507,8 @@ var PermissionsController = class {
    * Revokes a previously granted permission.
    *
    * @param params - Parameters for revoking the permission
+   * @param params.permissionId - Permission identifier as bigint for contract compatibility.
+   *   Obtain from permission grants via `getUserPermissionGrantsOnChain()`.
    * @returns Promise resolving to transaction hash
    * @example
    * ```typescript
@@ -35648,8 +35650,7 @@ var DataController = class {
       schemaId,
       permissions = [],
       encrypt: encrypt3 = true,
-      providerName,
-      owner
+      providerName
     } = params;
     try {
       let blob;
@@ -35727,7 +35728,7 @@ var DataController = class {
         filename,
         providerName
       );
-      const userAddress = owner || await this.getUserAddress();
+      const userAddress = await this.getUserAddress();
       let encryptedPermissions = [];
       if (permissions.length > 0 && encrypt3) {
         const userEncryptionKey = await generateEncryptionKey(
@@ -35761,8 +35762,7 @@ var DataController = class {
             url: uploadResult.url,
             userAddress,
             permissions: encryptedPermissions,
-            schemaId: schemaId || 0,
-            ownerAddress: owner
+            schemaId: schemaId || 0
           }
         );
       } else if (this.context.relayerCallbacks?.submitFileAddition) {
@@ -38023,6 +38023,39 @@ var ServerController = class {
     this.context = context;
   }
   PERSONAL_SERVER_BASE_URL = process.env.NEXT_PUBLIC_PERSONAL_SERVER_BASE_URL;
+  /**
+   * Retrieves the cryptographic identity of a personal server.
+   *
+   * @remarks
+   * This method fetches the public key and metadata for a personal server,
+   * which is required for encrypting data before sharing with the server.
+   * The identity includes the server's public key, address, and operational
+   * details needed for secure communication. This information is cached
+   * by identity servers to enable offline key retrieval.
+   *
+   * @param request - Parameters containing the user address
+   * @param request.userAddress - The wallet address associated with the personal server
+   * @returns Promise resolving to the server's identity information
+   * @throws {NetworkError} When the identity service is unavailable or returns invalid data
+   * @throws {PersonalServerError} When server identity cannot be retrieved
+   * @example
+   * ```typescript
+   * // Get server identity for data encryption
+   * const identity = await vana.server.getIdentity({
+   *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+   * });
+   * 
+   * console.log(`Server: ${identity.name}`);
+   * console.log(`Address: ${identity.address}`);
+   * console.log(`Public Key: ${identity.public_key}`);
+   * 
+   * // Use the public key for encrypting data to share with this server
+   * const encryptedData = await encryptWithWalletPublicKey(
+   *   userData,
+   *   identity.public_key
+   * );
+   * ```
+   */
   async getIdentity(request) {
     try {
       const response = await fetch(
@@ -38065,10 +38098,13 @@ var ServerController = class {
    * This method submits a computation request to the personal server API.
    * The response includes the operation ID.
    * @param params - The request parameters object
-   * @param params.permissionId - The permission ID authorizing this operation
+   * @param params.permissionId - The permission ID authorizing this operation.
+   *   Obtain from granted permissions via `vana.permissions.getUserPermissionGrantsOnChain()`.
    * @returns A Promise that resolves to an operation response with status and control URLs
-   * @throws {PersonalServerError} When server request fails or parameters are invalid
-   * @throws {NetworkError} When personal server API communication fails
+   * @throws {PersonalServerError} When server request fails or parameters are invalid.
+   *   Verify permissionId exists and is active for the target server.
+   * @throws {NetworkError} When personal server API communication fails.
+   *   Check server URL configuration and network connectivity.
    * @example
    * ```typescript
    * const response = await vana.server.createOperation({
@@ -38170,6 +38206,50 @@ var ServerController = class {
       );
     }
   }
+  /**
+   * Cancels a running operation on the personal server.
+   *
+   * @remarks
+   * This method attempts to cancel an operation that is currently processing
+   * on the personal server. The operation must be in a cancellable state
+   * (typically `starting` or `processing`). Not all operations support 
+   * cancellation, and cancellation may not be immediate. The server will
+   * attempt to stop the operation and update its status to `canceled`.
+   *
+   * **Cancellation Behavior:**
+   * - Operations in `succeeded` or `failed` states cannot be canceled
+   * - Some long-running operations may take time to respond to cancellation
+   * - Always verify cancellation by polling the operation status afterward
+   *
+   * @param operationId - The unique identifier of the operation to cancel,
+   *   obtained from `createOperation()` response
+   * @returns Promise that resolves when the cancellation request is accepted
+   * @throws {PersonalServerError} When the operation cannot be canceled or doesn't exist.
+   *   Check operation status - it may already be completed or failed.
+   * @throws {NetworkError} When unable to reach the personal server API.
+   *   Verify server URL and network connectivity.
+   * @example
+   * ```typescript
+   * // Start a long-running operation
+   * const operation = await vana.server.createOperation({
+   *   permissionId: 123
+   * });
+   *
+   * // Cancel if needed
+   * try {
+   *   await vana.server.cancelOperation(operation.id);
+   *   console.log("Cancellation requested");
+   *   
+   *   // Verify cancellation
+   *   const status = await vana.server.getOperation(operation.id);
+   *   if (status.status === "canceled") {
+   *     console.log("Operation successfully canceled");
+   *   }
+   * } catch (error) {
+   *   console.error("Failed to cancel:", error);
+   * }
+   * ```
+   */
   async cancelOperation(operationId) {
     try {
       const response = await fetch(
@@ -38467,7 +38547,8 @@ var ProtocolController = class {
    * are actually deployed on the current network.
    * @param contractName - The name of the Vana contract to retrieve (use const assertion for full typing)
    * @returns An object containing the contract's address and fully typed ABI
-   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain
+   * @throws {ContractNotFoundError} When the contract is not deployed on the current chain.
+   *   Verify contract name spelling and check current network with `getChainId()`.
    * @example
    * ```typescript
    * // Get contract info with full type inference
@@ -39651,151 +39732,175 @@ var PinataStorage = class {
   }
 };
 
-// src/storage/providers/callback-storage.ts
-var CallbackStorage = class {
-  constructor(callbacks) {
-    this.callbacks = callbacks;
-    if (!callbacks.upload || !callbacks.download) {
-      throw new Error(
-        "CallbackStorage requires both upload and download callbacks"
+// src/storage/providers/server-proxy.ts
+var ServerProxyStorage = class {
+  constructor(config) {
+    this.config = config;
+    if (!config.uploadUrl) {
+      throw new StorageError(
+        "Upload URL is required",
+        "MISSING_UPLOAD_URL",
+        "server-proxy"
+      );
+    }
+    if (!config.downloadUrl) {
+      throw new StorageError(
+        "Download URL is required",
+        "MISSING_DOWNLOAD_URL",
+        "server-proxy"
       );
     }
   }
   /**
-   * Upload a file using the provided callback
+   * Uploads a file through your server endpoint
    *
-   * @param file - The blob to upload
-   * @param filename - Optional filename for the upload
-   * @returns The upload result with URL and metadata
+   * @remarks
+   * This method sends the file to your configured upload endpoint via FormData.
+   * Your server is responsible for handling the actual storage implementation
+   * and must return a JSON response with `success: true` and an `identifier` field.
+   *
+   * @param file - The file to upload
+   * @param filename - Optional custom filename
+   * @returns Promise that resolves to the server-provided identifier
+   * @throws {StorageError} When the upload fails or server returns an error
+   *
+   * @example
+   * ```typescript
+   * const identifier = await serverStorage.upload(fileBlob, { name: "report.pdf" });
+   * console.log("File uploaded with identifier:", identifier);
+   * ```
    */
   async upload(file, filename) {
     try {
-      const result = await this.callbacks.upload(file, filename);
-      if (!result.url || result.url.trim() === "") {
+      const formData = new FormData();
+      formData.append("file", file);
+      if (filename) {
+        formData.append("name", filename);
+      }
+      const response = await fetch(this.config.uploadUrl, {
+        method: "POST",
+        body: formData
+      });
+      if (!response.ok) {
+        const _errorText = await response.text();
         throw new StorageError(
-          "Upload callback returned invalid result: missing or empty url",
-          "INVALID_UPLOAD_RESULT",
-          "callback-storage"
+          `Server upload failed: ${response.status} ${response.statusText}`,
+          "UPLOAD_FAILED",
+          "server-proxy"
         );
       }
-      return result;
+      const result = await response.json();
+      if (!result.success) {
+        throw new StorageError(
+          `Upload failed: ${result.error || "Unknown server error"}`,
+          "UPLOAD_FAILED",
+          "server-proxy"
+        );
+      }
+      if (!result.identifier) {
+        throw new StorageError(
+          "Server upload succeeded but no identifier returned",
+          "NO_IDENTIFIER_RETURNED",
+          "server-proxy"
+        );
+      }
+      return {
+        url: result.url || result.identifier,
+        size: file.size,
+        contentType: file.type || "application/octet-stream"
+      };
     } catch (error) {
       if (error instanceof StorageError) {
         throw error;
       }
       throw new StorageError(
-        `Upload failed: ${error instanceof Error ? error.message : String(error)}`,
+        `Server proxy upload error: ${error instanceof Error ? error.message : "Unknown error"}`,
         "UPLOAD_ERROR",
-        "callback-storage",
-        { cause: error instanceof Error ? error : void 0 }
+        "server-proxy"
       );
     }
   }
   /**
-   * Download a file using the provided callback
+   * Downloads a file through your server endpoint
    *
-   * @param url - The URL or identifier to download
-   * @returns The downloaded blob
+   * @remarks
+   * This method sends the identifier to your configured download endpoint via POST request.
+   * Your server is responsible for retrieving the file from your storage backend
+   * and returning the file content as a blob response.
+   *
+   * @param url - The server-provided URL or identifier from upload
+   * @returns Promise that resolves to the downloaded file content
+   * @throws {StorageError} When the download fails or file is not found
+   *
+   * @example
+   * ```typescript
+   * const fileBlob = await serverStorage.download("file-123");
+   * const url = URL.createObjectURL(fileBlob);
+   * ```
    */
   async download(url) {
     try {
-      const identifier = this.callbacks.extractIdentifier ? this.callbacks.extractIdentifier(url) : url;
-      const blob = await this.callbacks.download(identifier);
-      if (!(blob instanceof Blob)) {
+      const identifier = this.extractIdentifierFromUrl(url);
+      const response = await fetch(this.config.downloadUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ identifier })
+      });
+      if (!response.ok) {
+        const _errorText = await response.text();
         throw new StorageError(
-          "Download callback returned invalid result: expected Blob",
-          "INVALID_DOWNLOAD_RESULT",
-          "callback-storage"
+          `Server download failed: ${response.status} ${response.statusText}`,
+          "DOWNLOAD_FAILED",
+          "server-proxy"
         );
       }
-      return blob;
+      return await response.blob();
     } catch (error) {
       if (error instanceof StorageError) {
         throw error;
       }
       throw new StorageError(
-        `Download failed: ${error instanceof Error ? error.message : String(error)}`,
+        `Server proxy download error: ${error instanceof Error ? error.message : "Unknown error"}`,
         "DOWNLOAD_ERROR",
-        "callback-storage",
-        { cause: error instanceof Error ? error : void 0 }
+        "server-proxy"
       );
     }
   }
-  /**
-   * List files using the provided callback (if available)
-   *
-   * @param options - Optional list options including filters and pagination
-   * @returns Array of storage files
-   */
-  async list(options) {
-    if (!this.callbacks.list) {
-      throw new StorageError(
-        "List operation not supported - no list callback provided",
-        "NOT_SUPPORTED",
-        "callback-storage"
-      );
-    }
-    try {
-      const result = await this.callbacks.list(options?.namePattern, options);
-      return result.items.map((item, index) => ({
-        id: item.identifier,
-        name: item.identifier.split("/").pop() || `file-${index}`,
-        url: item.identifier,
-        size: item.size || 0,
-        contentType: "application/octet-stream",
-        createdAt: item.lastModified || /* @__PURE__ */ new Date(),
-        metadata: item.metadata
-      }));
-    } catch (error) {
-      throw new StorageError(
-        `List failed: ${error instanceof Error ? error.message : String(error)}`,
-        "LIST_ERROR",
-        "callback-storage",
-        { cause: error instanceof Error ? error : void 0 }
-      );
-    }
+  async list(_options) {
+    throw new StorageError(
+      "List operation is not supported by server proxy storage",
+      "LIST_NOT_SUPPORTED",
+      "server-proxy"
+    );
   }
-  /**
-   * Delete a file using the provided callback (if available)
-   *
-   * @param url - The URL or identifier to delete
-   * @returns True if deletion succeeded
-   */
-  async delete(url) {
-    if (!this.callbacks.delete) {
-      throw new StorageError(
-        "Delete operation not supported - no delete callback provided",
-        "NOT_SUPPORTED",
-        "callback-storage"
-      );
-    }
-    try {
-      const identifier = this.callbacks.extractIdentifier ? this.callbacks.extractIdentifier(url) : url;
-      return await this.callbacks.delete(identifier);
-    } catch (error) {
-      throw new StorageError(
-        `Delete failed: ${error instanceof Error ? error.message : String(error)}`,
-        "DELETE_ERROR",
-        "callback-storage",
-        { cause: error instanceof Error ? error : void 0 }
-      );
-    }
+  async delete(_url) {
+    throw new StorageError(
+      "Delete operation is not supported by server proxy storage",
+      "DELETE_NOT_SUPPORTED",
+      "server-proxy"
+    );
   }
   /**
-   * Get provider configuration
+   * Extract identifier from URL or return as-is
    *
-   * @returns Provider configuration metadata
+   * @param url - URL or identifier string
+   * @returns identifier string
    */
+  extractIdentifierFromUrl(url) {
+    return url;
+  }
   getConfig() {
     return {
-      name: "callback-storage",
-      type: "callback",
+      name: "Server Proxy",
+      type: "server-proxy",
       requiresAuth: false,
       features: {
         upload: true,
         download: true,
-        list: !!this.callbacks.list,
-        delete: !!this.callbacks.delete
+        list: false,
+        delete: false
       }
     };
   }
@@ -40417,15 +40522,35 @@ var VanaCore = class {
   }
   /**
    * Encrypts data using the Vana protocol standard encryption.
-   * This method automatically uses the correct platform adapter for the current environment.
+   * 
+   * @remarks
+   * This method implements the Vana network's standard encryption protocol using
+   * platform-appropriate cryptographic libraries. It automatically handles different
+   * input types (string or Blob) and produces encrypted output suitable for secure
+   * storage or transmission. The encryption is compatible with the network's
+   * decryption protocols and can be decrypted by authorized parties.
    *
-   * @param data The data to encrypt (string or Blob)
-   * @param key The key to use as encryption key
-   * @returns The encrypted data as Blob
+   * @param data - The data to encrypt (string or Blob)
+   * @param key - The encryption key (typically generated via `generateEncryptionKey`)
+   * @returns The encrypted data as a Blob
+   * @throws {Error} When encryption fails due to invalid key or data format
    * @example
    * ```typescript
-   * const encryptionKey = await generateEncryptionKey(walletClient);
-   * const encrypted = await vana.encryptBlob("sensitive data", encryptionKey);
+   * import { generateEncryptionKey } from '@opendatalabs/vana-sdk/node';
+   * 
+   * // Generate encryption key from wallet signature
+   * const encryptionKey = await generateEncryptionKey(vana.walletClient);
+   * 
+   * // Encrypt string data
+   * const sensitiveData = "User's private information";
+   * const encrypted = await vana.encryptBlob(sensitiveData, encryptionKey);
+   * 
+   * // Encrypt file data
+   * const fileBlob = new Blob([fileContent], { type: 'application/json' });
+   * const encryptedFile = await vana.encryptBlob(fileBlob, encryptionKey);
+   * 
+   * // Store encrypted data safely
+   * await storageProvider.upload(encrypted, 'encrypted-data.bin');
    * ```
    */
   async encryptBlob(data, key) {
@@ -40433,16 +40558,52 @@ var VanaCore = class {
   }
   /**
    * Decrypts data that was encrypted using the Vana protocol.
-   * This method automatically uses the correct platform adapter for the current environment.
+   * 
+   * @remarks
+   * This method decrypts data that was previously encrypted using the Vana network's
+   * standard encryption protocol. It requires the same wallet signature that was used
+   * for encryption and automatically uses the appropriate platform adapter for
+   * cryptographic operations. The decrypted output maintains the original data format.
    *
-   * @param encryptedData The encrypted data (string or Blob)
-   * @param walletSignature The wallet signature to use as decryption key
-   * @returns The decrypted data as Blob
+   * @param encryptedData - The encrypted data (string or Blob)
+   * @param walletSignature - The wallet signature used as decryption key
+   * @returns The decrypted data as a Blob
+   * @throws {Error} When decryption fails due to invalid signature or corrupted data
    * @example
    * ```typescript
-   * const encryptionKey = await generateEncryptionKey(walletClient);
-   * const decrypted = await vana.decryptBlob(encryptedData, encryptionKey);
-   * const text = await decrypted.text();
+   * import { generateEncryptionKey } from '@opendatalabs/vana-sdk/node';
+   * 
+   * // Retrieve encrypted data from storage
+   * const encryptedBlob = await storageProvider.download('encrypted-data.bin');
+   * 
+   * // Generate the same key used for encryption
+   * const decryptionKey = await generateEncryptionKey(vana.walletClient);
+   * 
+   * // Decrypt the data
+   * const decrypted = await vana.decryptBlob(encryptedBlob, decryptionKey);
+   * 
+   * // Convert back to original format
+   * const originalText = await decrypted.text();
+   * const originalJson = JSON.parse(originalText);
+   * 
+   * console.log('Decrypted data:', originalJson);
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // Decrypt file downloaded from Vana network
+   * const userFiles = await vana.data.getUserFiles();
+   * const file = userFiles[0];
+   * 
+   * // Download encrypted content
+   * const encrypted = await fetch(file.url).then(r => r.blob());
+   * 
+   * // Decrypt with user's key
+   * const decryptionKey = await generateEncryptionKey(vana.walletClient);
+   * const decrypted = await vana.decryptBlob(encrypted, decryptionKey);
+   * 
+   * // Process original data
+   * const fileContent = await decrypted.arrayBuffer();
    * ```
    */
   async decryptBlob(encryptedData, walletSignature) {
@@ -41360,7 +41521,6 @@ var index_node_default = Vana;
   BaseController,
   BlockchainError,
   BrowserPlatformAdapter,
-  CallbackStorage,
   CircuitBreaker,
   ContractFactory,
   ContractNotFoundError,
@@ -41395,6 +41555,7 @@ var index_node_default = Vana;
   SchemaValidator,
   SerializationError,
   ServerController,
+  ServerProxyStorage,
   ServerUrlMismatchError,
   SignatureError,
   StorageError,