@opendatalabs/vana-sdk 0.1.0-alpha.7ee7635 → 0.1.0-alpha.80df35f

package/dist/controllers/data.d.ts

@@ -1,18 +1,10 @@
-import { Address } from 'viem';
-import { StorageUploadResult } from '../types/storage.js';
-import { EncryptedUploadParams, UploadResult, UnencryptedUploadParams, UploadParams, UserFile, GetUserTrustedServersParams, TrustedServer, AddRefinerParams, AddRefinerResult, Refiner, UpdateSchemaIdParams, UpdateSchemaIdResult, UploadEncryptedFileResult } from '../types/data.js';
-import { TransactionResult } from '../types/operations.js';
-import { ControllerContext } from '../types/controller-context.js';
-import { DataSchema } from '../utils/schemaValidation.js';
-import '../generated/event-types.js';
-import '../generated/server/server-exports.js';
-import '../generated/server/server.js';
-import '../platform/interface.js';
-import '../types/config.js';
-import '../types/chains.js';
-import '../types/permissions.js';
-import '../storage/manager.js';
-
+import type { Address } from "viem";
+import type { StorageUploadResult } from "../types/storage";
+import type { UserFile, UploadParams, UploadResult, UploadEncryptedFileResult, Refiner, AddRefinerParams, AddRefinerResult, UpdateSchemaIdParams, UpdateSchemaIdResult, TrustedServer, GetUserTrustedServersParams, EncryptedUploadParams, UnencryptedUploadParams, EncryptFileOptions, EncryptFileResult, DecryptFileOptions, UploadFileWithPermissionsParams, AddFilePermissionParams, DecryptFileWithPermissionOptions } from "../types/index";
+import type { TransactionResult } from "../types/operations";
+import type { ControllerContext } from "./permissions";
+import { BaseController } from "./base";
+import { type DataSchema } from "../utils/schemaValidation";
 /**
  * Manages encrypted user data files and their blockchain registration on the Vana network.
  *
@@ -56,8 +48,7 @@ import '../storage/manager.js';
  * @category Data Management
  * @see {@link https://docs.vana.com/developer/data-registry | Vana Data Registry Documentation} for conceptual overview
  */
-declare class DataController {
-    private readonly context;
+export declare class DataController extends BaseController {
     constructor(context: ControllerContext);
     /**
      * Uploads user data with automatic encryption and blockchain registration.
@@ -88,9 +79,7 @@ declare class DataController {
      * - Operation permissions: What operations can be performed on the data (handled separately)
      *
      * @param params - Upload parameters including content, filename, schema, and permissions
-     * @param params.permissions[].account - The recipient's wallet address that will access the data.
-     * @param params.permissions[].publicKey - The recipient's public key for encryption (hex string with 0x prefix).
-     *   Obtain via `vana.server.getIdentity(userAddress).public_key` for personal servers.
+     * @param params.permissions - Optional array of file permissions for granting decryption access
      * @param params.schemaId - Optional schema ID for data validation. Get available schemas from `vana.schemas.list()`.
      * @param params.owner - Optional owner address if uploading on behalf of another user (requires delegation).
      * @returns Promise resolving to upload results with file ID and transaction hash
@@ -157,6 +146,51 @@ declare class DataController {
     upload(params: EncryptedUploadParams): Promise<UploadResult>;
     upload(params: UnencryptedUploadParams): Promise<UploadResult>;
     upload(params: UploadParams): Promise<UploadResult>;
+    /**
+     * Encrypts data using wallet-derived encryption.
+     *
+     * @remarks
+     * This method provides secure, wallet-based encryption for data before uploading
+     * to the Vana network. It's the counterpart to decryptFile for preparing data
+     * for secure storage.
+     *
+     * The method automatically:
+     * - Generates an encryption key from the user's wallet signature
+     * - Converts the input data to a Blob if necessary
+     * - Encrypts the data using the generated key
+     * - Returns both the encrypted data and the encryption key
+     *
+     * The encryption key returned can be stored and later used for decryption,
+     * or shared with others to grant them decryption access.
+     *
+     * @param data - The data to encrypt (Blob, string, or object)
+     * @param options - Optional encryption configuration
+     * @returns Promise resolving to encrypted data and the encryption key used
+     * @throws {Error} When wallet is not connected or encryption fails
+     * @example
+     * ```typescript
+     * // Encrypt a string
+     * const { encryptedData, encryptionKey } = await vana.data.encryptFile(
+     *   "My secret data"
+     * );
+     *
+     * // Encrypt JSON with custom MIME type
+     * const { encryptedData, encryptionKey } = await vana.data.encryptFile(
+     *   { name: "Alice", age: 30 },
+     *   { mimeType: "application/json" }
+     * );
+     *
+     * // With custom encryption seed
+     * const { encryptedData, encryptionKey } = await vana.data.encryptFile(
+     *   "Secret message",
+     *   { seed: "My custom encryption seed" }
+     * );
+     *
+     * // Upload the encrypted data
+     * const result = await vana.data.uploadToStorage(encryptedData);
+     * ```
+     */
+    encryptFile(data: Blob | string | object, options?: EncryptFileOptions): Promise<EncryptFileResult>;
     /**
      * Decrypts a file owned by the user using their wallet signature.
      *
@@ -212,7 +246,7 @@ declare class DataController {
      * fs.writeFileSync('decrypted-file.txt', Buffer.from(buffer));
      * ```
      */
-    decryptFile(file: UserFile, encryptionSeed?: string): Promise<Blob>;
+    decryptFile(file: UserFile, options?: DecryptFileOptions): Promise<Blob>;
     /**
      * Retrieves all data files owned by a specific user address.
      *
@@ -508,7 +542,6 @@ declare class DataController {
      * @returns Promise resolving to the user's wallet address
      * @throws {Error} When no addresses are available in wallet client
      */
-    private getUserAddress;
     /**
      * Adds a file with permissions to the DataRegistry contract.
      *
@@ -533,17 +566,84 @@ declare class DataController {
      * Adds a file to the registry with permissions and schema.
      * This combines the functionality of addFileWithPermissions and schema validation.
      *
+     * @remarks
+     * This method automatically encrypts permissions when a publicKey is provided.
+     * It generates the user's encryption key and encrypts it with each recipient's
+     * public key before registering on the blockchain.
+     *
      * @param url - The URL of the file to register
      * @param ownerAddress - The address of the file owner
-     * @param permissions - Array of permissions to grant (account and encrypted key)
+     * @param permissions - Array of permissions to grant, each with account and publicKey properties
      * @param schemaId - The schema ID to associate with the file (0 for no schema)
-     * @returns Promise resolving to object with fileId and transactionHash
-     * @throws {Error} When chain ID is not available
-     * @throws {ContractError} When contract execution fails
-     * @throws {Error} When transaction receipt is not available
-     * @throws {Error} When FileAdded event cannot be parsed
+     * @returns Promise resolving to TransactionResult with fileId and transactionHash
+     * @throws {Error} "Chain ID not available" - When wallet chain is not configured
+     * @throws {Error} "Failed to generate encryption key" - When encryption key generation fails
+     * @throws {Error} "Permission for {account} must include 'publicKey'" - When publicKey is missing
+     * @throws {Error} "Failed to add file with permissions and schema: {error}" - When transaction fails
+     * @example
+     * ```typescript
+     * // Get server's public key
+     * const serverIdentity = await vana.server.getIdentity({
+     *   userAddress: "0x..."
+     * });
+     *
+     * // Add file with permissions and schema
+     * const result = await vana.data.addFileWithPermissionsAndSchema(
+     *   "ipfs://QmXxx...",
+     *   ownerAddress,
+     *   [{
+     *     account: serverIdentity.address,
+     *     publicKey: serverIdentity.publicKey
+     *   }],
+     *   schemaId
+     * );
+     *
+     * console.log(`File ${result.fileId} registered in tx ${result.hash}`);
+     * ```
      */
     addFileWithPermissionsAndSchema(url: string, ownerAddress: Address, permissions?: Array<{
+        account: Address;
+        publicKey: string;
+    }>, schemaId?: number): Promise<TransactionResult<"DataRegistry", "addFileWithPermissionsAndSchema">>;
+    /**
+     * Adds a file with pre-encrypted permissions and schema to the DataRegistry.
+     *
+     * @remarks
+     * This method is designed for relay services and advanced use cases where permissions
+     * have already been encrypted client-side. Unlike `addFileWithPermissionsAndSchema()`,
+     * this method expects permissions in the encrypted format with a 'key' field instead
+     * of 'publicKey'.
+     *
+     * This is typically used by relay endpoints that receive pre-encrypted data from
+     * the client SDK's `upload()` method, avoiding double encryption.
+     *
+     * @param url - The storage URL of the file (e.g., IPFS URL)
+     * @param ownerAddress - The address that will own this file
+     * @param permissions - Array of pre-encrypted permissions with 'account' and 'key' fields
+     * @param schemaId - Optional schema ID for data validation (defaults to 0)
+     * @returns Promise resolving to transaction result with hash and contract details
+     * @throws {Error} When chain ID is not available
+     * @throws {Error} When wallet is not connected
+     * @throws {Error} When transaction fails
+     * @example
+     * ```typescript
+     * // In a relay endpoint that receives pre-encrypted permissions
+     * const result = await vana.data.addFileWithEncryptedPermissionsAndSchema(
+     *   "ipfs://QmXxx...",
+     *   ownerAddress,
+     *   [
+     *     {
+     *       account: "0xServerAddress...",
+     *       key: "encrypted_key_string" // Already encrypted by client
+     *     }
+     *   ],
+     *   schemaId
+     * );
+     *
+     * console.log(`File registered in tx ${result.hash}`);
+     * ```
+     */
+    addFileWithEncryptedPermissionsAndSchema(url: string, ownerAddress: Address, permissions?: Array<{
         account: Address;
         key: string;
     }>, schemaId?: number): Promise<TransactionResult<"DataRegistry", "addFileWithPermissionsAndSchema">>;
@@ -667,16 +767,10 @@ declare class DataController {
      * 3. Encrypts the user's encryption key with the provided public key
      * 4. Registers the file with permissions
      *
-     * @param data - The file data to encrypt and upload
-     * @param permissions - Array of permissions to grant, each with account address and public key
-     * @param filename - Optional filename for the upload
-     * @param providerName - Optional storage provider to use
+     * @param params - Upload parameters including data, permissions, and options
      * @returns Promise resolving to upload result with file ID and storage URL
      */
-    uploadFileWithPermissions(data: Blob, permissions: Array<{
-        account: Address;
-        publicKey: string;
-    }>, filename?: string, providerName?: string): Promise<UploadEncryptedFileResult>;
+    uploadFileWithPermissions(params: UploadFileWithPermissionsParams): Promise<UploadEncryptedFileResult>;
     /**
      * Uploads content to storage without registering it on the blockchain.
      * This method only handles the storage upload and returns the file URL.
@@ -700,21 +794,27 @@ declare class DataController {
      * For advanced users who need more control over transaction timing,
      * use `submitFilePermission()` instead.
      *
-     * @param fileId - The ID of the file to add permissions for
-     * @param account - The address of the account to grant permission to
-     * @param publicKey - The public key to encrypt the user's encryption key with (hex string with 0x prefix)
+     * @param params - Parameters for adding file permission
+     * @param params.fileId - The ID of the file to grant permission for
+     * @param params.account - The recipient's wallet address that will access the file
+     * @param params.publicKey - The recipient's public key for encryption.
+     *   Obtain via `vana.server.getIdentity(account).publicKey`
      * @returns Promise resolving to permission data from PermissionGranted event
      * @throws {Error} "No addresses available in wallet client" - When wallet is not connected
      * @throws {Error} "Chain ID not available" - When wallet chain is not configured
      * @throws {Error} "Failed to add permission to file: {error}" - When transaction fails or user doesn't own file
      * @example
      * ```typescript
-     * const result = await vana.data.addPermissionToFile(fileId, account, publicKey);
+     * const result = await vana.data.addPermissionToFile({
+     *   fileId: 123,
+     *   account: "0xRecipientAddress...",
+     *   publicKey: "0xRecipientPublicKey..."
+     * });
      * console.log(`Permission granted to ${result.account} for file ${result.fileId}`);
      * console.log(`Transaction: ${result.transactionHash}`);
      * ```
      */
-    addPermissionToFile(fileId: number, account: Address, publicKey: string): Promise<TransactionResult<"DataRegistry", "addFilePermission">>;
+    addPermissionToFile(params: AddFilePermissionParams): Promise<TransactionResult<"DataRegistry", "addFilePermission">>;
     /**
      * Submits a file permission transaction to the blockchain.
      *
@@ -726,7 +826,7 @@ declare class DataController {
      * @param fileId - The ID of the file to grant permission for
      * @param account - The recipient's wallet address that will access the file
      * @param publicKey - The recipient's public key for encryption.
-     *   Obtain via `vana.server.getIdentity(account).public_key`
+     *   Obtain via `vana.server.getIdentity(account).publicKey`
      * @returns Promise resolving to TransactionResult for tracking the transaction
      * @throws {Error} When chain ID is not available
      * @throws {Error} When encryption key generation fails
@@ -762,10 +862,11 @@ declare class DataController {
      *
      * @param file - The file to decrypt
      * @param privateKey - The private key to decrypt the user's encryption key
-     * @param account - The account address that has permission (defaults to current wallet account)
+     * @param options - Optional decryption configuration
+     * @param options.account - The account address that has permission (defaults to current wallet account)
      * @returns Promise resolving to the decrypted file data
      */
-    decryptFileWithPermission(file: UserFile, privateKey: string, account?: Address): Promise<Blob>;
+    decryptFileWithPermission(file: UserFile, privateKey: string, options?: DecryptFileWithPermissionOptions): Promise<Blob>;
     /**
      * Simple network-agnostic fetch utility for retrieving file content.
      *
@@ -911,5 +1012,3 @@ declare class DataController {
      */
     fetchAndValidateSchema(url: string): Promise<DataSchema>;
 }
-
-export { DataController };