@opendatalabs/vana-sdk 0.1.0-alpha.b390e7f → 0.1.0-alpha.d6bebb0

package/dist/index.node.cjs

@@ -34179,6 +34179,13 @@ var PermissionsController = class {
         }
       }
       const nonce = await this.getUserNonce();
+      if (params.granteeId === void 0 || params.granteeId === null) {
+        throw new Error(
+          "granteeId is required. Please select a grantee from the available list."
+        );
+      }
+      const granteeId = params.granteeId;
+      console.debug("\u{1F50D} Debug - Using provided granteeId:", granteeId);
       console.debug(
         "\u{1F50D} Debug - Final grant URL being passed to compose:",
         grantUrl
@@ -34192,7 +34199,8 @@ var PermissionsController = class {
         grantUrl,
         serializedParameters: getGrantFileHash(grantFile),
         // Hash as placeholder
-        nonce
+        nonce,
+        granteeId
       });
       const signature = await this.signTypedData(typedData);
       return await this.submitSignedGrant(typedData, signature);
@@ -34272,6 +34280,13 @@ var PermissionsController = class {
         }
       }
       const nonce = await this.getUserNonce();
+      if (params.granteeId === void 0 || params.granteeId === null) {
+        throw new Error(
+          "granteeId is required. Please select a grantee from the available list."
+        );
+      }
+      const granteeId = params.granteeId;
+      console.debug("\u{1F50D} Debug - Using provided granteeId:", granteeId);
       console.debug(
         "\u{1F50D} Debug - Final grant URL being passed to compose:",
         grantUrl
@@ -34285,7 +34300,8 @@ var PermissionsController = class {
         grantUrl,
         serializedParameters: getGrantFileHash(grantFile),
         // Hash as placeholder
-        nonce
+        nonce,
+        granteeId
       });
       const signature = await this.signTypedData(typedData);
       return { typedData, signature };
@@ -34481,12 +34497,14 @@ var PermissionsController = class {
     const permissionInput = {
       nonce: typedData.message.nonce,
       grant: typedData.message.grant,
-      fileIds: typedData.message.fileIds
+      fileIds: typedData.message.fileIds,
+      granteeId: typedData.message.granteeId
     };
     console.debug("\u{1F50D} Debug - Permission input being sent to contract:", {
       nonce: permissionInput.nonce.toString(),
       grant: permissionInput.grant,
-      fileIds: permissionInput.fileIds.map((id) => id.toString())
+      fileIds: permissionInput.fileIds.map((id) => id.toString()),
+      granteeId: permissionInput.granteeId.toString()
     });
     console.debug("\u{1F50D} Debug - Grant field value:", typedData.message.grant);
     console.debug(
@@ -34507,6 +34525,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
@@ -34634,6 +34654,7 @@ var PermissionsController = class {
    * @param params.grantUrl - URL where the grant details are stored
    * @param params.serializedParameters - Serialized parameters for the operation
    * @param params.nonce - Unique number to prevent replay attacks
+   * @param params.granteeId - The ID of the grantee from the registry
    * @returns Promise resolving to the typed data structure
    */
   async composePermissionGrantMessage(params) {
@@ -34657,14 +34678,16 @@ var PermissionsController = class {
         Permission: [
           { name: "nonce", type: "uint256" },
           { name: "grant", type: "string" },
-          { name: "fileIds", type: "uint256[]" }
+          { name: "fileIds", type: "uint256[]" },
+          { name: "granteeId", type: "uint256" }
         ]
       },
       primaryType: "Permission",
       message: {
         nonce: params.nonce,
         grant: params.grantUrl,
-        fileIds: params.files.map((fileId) => BigInt(fileId))
+        fileIds: params.files.map((fileId) => BigInt(fileId)),
+        granteeId: BigInt(params.granteeId)
       }
     };
   }
@@ -35648,7 +35671,8 @@ var DataController = class {
       schemaId,
       permissions = [],
       encrypt: encrypt3 = true,
-      providerName
+      providerName,
+      owner
     } = params;
     try {
       let blob;
@@ -35726,7 +35750,7 @@ var DataController = class {
         filename,
         providerName
       );
-      const userAddress = await this.getUserAddress();
+      const userAddress = owner || await this.getUserAddress();
       let encryptedPermissions = [];
       if (permissions.length > 0 && encrypt3) {
         const userEncryptionKey = await generateEncryptionKey(
@@ -35760,7 +35784,8 @@ var DataController = class {
             url: uploadResult.url,
             userAddress,
             permissions: encryptedPermissions,
-            schemaId: schemaId || 0
+            schemaId: schemaId || 0,
+            ownerAddress: owner
           }
         );
       } else if (this.context.relayerCallbacks?.submitFileAddition) {
@@ -38021,6 +38046,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(
@@ -38063,10 +38121,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({
@@ -38168,6 +38229,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(
@@ -38465,7 +38570,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
@@ -40415,15 +40521,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) {
@@ -40431,16 +40557,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) {