@opendatalabs/vana-sdk 0.1.0-alpha.ffe4659 → 2.0.0

package/dist/controllers/server.js

@@ -0,0 +1,624 @@
+import { SERVER_PATHS } from "../generated/server/server-exports";
+import {
+  NetworkError,
+  SerializationError,
+  SignatureError,
+  PersonalServerError
+} from "../errors";
+import { BaseController } from "./base";
+import { SignatureCache } from "../utils/signatureCache";
+class ServerController extends BaseController {
+  constructor(context) {
+    super(context);
+  }
+  get personalServerBaseUrl() {
+    if (!this.context.defaultPersonalServerUrl) {
+      throw new PersonalServerError(
+        "Personal server URL is required for server operations. Please configure defaultPersonalServerUrl in your VanaConfig."
+      );
+    }
+    let url = this.context.defaultPersonalServerUrl;
+    if (url.endsWith("/api/v1")) {
+      url = url.slice(0, -7);
+    }
+    return url;
+  }
+  /**
+   * Retrieves cryptographic identity for a personal server.
+   *
+   * @remarks
+   * Fetches public key and metadata required for data encryption.
+   * Identity cached by infrastructure for offline retrieval.
+   * Each user address maps to deterministic server identity.
+   *
+   * @param request - Identity request parameters
+   * @param request.userAddress - Wallet address of server owner
+   *
+   * @returns Server identity with public key and metadata
+   *
+   * @throws {NetworkError} Identity service unavailable.
+   *   Check network connection and server URL configuration.
+   * @throws {PersonalServerError} Identity retrieval failed.
+   *   Verify user address and server registration.
+   *
+   * @example
+   * ```typescript
+   * const identity = await vana.server.getIdentity({
+   *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+   * });
+   *
+   * console.log(`Server: ${identity.name}`);
+   * console.log(`Address: ${identity.address}`);
+   * console.log(`Public Key: ${identity.publicKey}`);
+   *
+   * // Use for encryption before data sharing
+   * const encrypted = await encryptWithPublicKey(
+   *   data,
+   *   identity.publicKey
+   * );
+   * ```
+   */
+  async getIdentity(request) {
+    try {
+      const response = await fetch(
+        `${this.personalServerBaseUrl}${SERVER_PATHS.identity}?address=${request.userAddress}`,
+        {
+          method: "GET",
+          headers: {
+            "Content-Type": "application/json"
+          }
+        }
+      );
+      console.debug("\u{1F50D} Debug - getIdentity response", response);
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new NetworkError(
+          `Local identity API request failed: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      const serverResponse = await response.json();
+      return {
+        kind: serverResponse.personal_server.kind,
+        address: serverResponse.personal_server.address,
+        publicKey: serverResponse.personal_server.public_key,
+        baseUrl: this.personalServerBaseUrl,
+        name: "Hosted Vana Server"
+      };
+    } catch (error) {
+      if (error instanceof NetworkError || error instanceof PersonalServerError) {
+        throw error;
+      }
+      throw new PersonalServerError(
+        `Failed to get personal server identity: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Creates a server operation and returns its details from the OpenAPI schema.
+   *
+   * @remarks
+   * This method submits a computation request to the personal server and returns
+   * the server's CreateOperationResponse. The response contains the operation ID
+   * which can be used with `waitForOperation()` to poll for completion.
+   *
+   * @param params - The operation request parameters
+   * @param params.permissionId - The permission ID authorizing this operation.
+   *   Obtain via `vana.permissions.getUserPermissionGrantsOnChain()`.
+   * @returns Server response with operation ID
+   * @throws {PersonalServerError} When the server request fails or parameters are invalid
+   * @throws {NetworkError} When personal server API communication fails
+   * @example
+   * ```typescript
+   * const response = await vana.server.createOperation({
+   *   permissionId: 123
+   * });
+   * console.log(`Operation ID: ${response.id}`);
+   *
+   * // Wait for completion
+   * const result = await vana.server.waitForOperation(response.id);
+   * console.log("Result:", result.result);
+   * ```
+   */
+  async createOperation(params) {
+    this.assertWallet();
+    try {
+      const requestData = {
+        permission_id: params.permissionId
+      };
+      const requestJson = JSON.stringify(requestData);
+      const signature = await this.createSignature(requestJson);
+      const requestBody = {
+        app_signature: signature,
+        operation_request_json: requestJson
+      };
+      console.debug("\u{1F50D} Debug - createOperation requestBody", requestBody);
+      const response = await this.makeRequest(requestBody);
+      return response;
+    } catch (error) {
+      if (error instanceof Error) {
+        if (error instanceof NetworkError || error instanceof SerializationError || error instanceof SignatureError || error instanceof PersonalServerError) {
+          throw error;
+        }
+        throw new PersonalServerError(
+          `Personal server operation creation failed: ${error.message}`,
+          error
+        );
+      }
+      throw new PersonalServerError(
+        "Personal server operation creation failed with unknown error"
+      );
+    }
+  }
+  /**
+   * Retrieves the current status and result of a server operation.
+   *
+   * @remarks
+   * Common status values: `starting`, `processing`, `succeeded`, `failed`, `canceled`.
+   * When status is `succeeded`, the result field contains the operation output.
+   * Returns the server response directly from the OpenAPI schema.
+   *
+   * @param operationId - The ID of the operation to query
+   * @returns The operation status response from the server
+   * @throws {NetworkError} When the API request fails or returns invalid data
+   * @example
+   * ```typescript
+   * const operation = await vana.server.getOperation(operationId);
+   * if (operation.status === 'succeeded') {
+   *   console.log('Result:', operation.result);
+   *   console.log('Started at:', operation.started_at);
+   *   console.log('Finished at:', operation.finished_at);
+   * }
+   * ```
+   */
+  async getOperation(operationId) {
+    try {
+      console.debug("Polling Operation Status:", operationId);
+      const response = await fetch(
+        `${this.personalServerBaseUrl}${SERVER_PATHS.getOperation(operationId)}`,
+        {
+          method: "GET",
+          headers: {
+            "Content-Type": "application/json"
+          }
+        }
+      );
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.debug("Polling Error Response:", {
+          status: response.status,
+          statusText: response.statusText,
+          error: errorText
+        });
+        throw new NetworkError(
+          `Status polling failed: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      const data = await response.json();
+      console.debug("Polling Success Response:", data);
+      return data;
+    } catch (error) {
+      if (error instanceof NetworkError) {
+        throw error;
+      }
+      throw new NetworkError(
+        `Failed to poll status: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Waits for an operation to complete and returns the final result.
+   *
+   * @remarks
+   * This method polls the operation status at regular intervals until it
+   * reaches a terminal state (succeeded, failed, or canceled). Supports
+   * ergonomic overloads to accept either an Operation object or just the ID.
+   * Returns the server response directly from the OpenAPI schema.
+   *
+   * @param opOrId - Either an Operation object or operation ID string
+   * @param options - Optional polling configuration
+   * @returns The completed operation with result and timestamp data
+   * @throws {PersonalServerError} When the operation fails or times out
+   * @example
+   * ```typescript
+   * // Using operation object
+   * const operation = await vana.server.createOperation({ permissionId: 123 });
+   * const completed = await vana.server.waitForOperation(operation);
+   *
+   * // Using just the ID
+   * const completed = await vana.server.waitForOperation("op_abc123");
+   *
+   * // With custom timeout
+   * const completed = await vana.server.waitForOperation(operation, {
+   *   timeout: 60000,
+   *   pollingInterval: 1000
+   * });
+   *
+   * // Access server-provided timestamps
+   * console.log('Started:', completed.started_at);
+   * console.log('Finished:', completed.finished_at);
+   * ```
+   */
+  async waitForOperation(opOrId, options) {
+    const id = typeof opOrId === "string" ? opOrId : opOrId.id;
+    const startTime = Date.now();
+    const timeout = options?.timeout ?? 3e4;
+    const interval = options?.pollingInterval ?? 500;
+    while (true) {
+      const operation = await this.getOperation(id);
+      if (operation.status === "succeeded") {
+        return operation;
+      }
+      if (operation.status === "failed") {
+        let errorMessage = "Unknown error";
+        if (operation.result) {
+          const resultObj = operation.result;
+          errorMessage = typeof resultObj.error === "string" ? resultObj.error : typeof resultObj.detail === "string" ? resultObj.detail : JSON.stringify(operation.result);
+        }
+        throw new PersonalServerError(
+          `Operation ${operation.status}: ${errorMessage}`
+        );
+      }
+      if (operation.status === "canceled") {
+        throw new PersonalServerError(`Operation was canceled`);
+      }
+      if (Date.now() - startTime > timeout) {
+        throw new PersonalServerError(`Operation timed out after ${timeout}ms`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  }
+  /**
+   * Downloads an artifact generated by a server operation.
+   *
+   * @remarks
+   * Artifacts are files generated during operations like Gemini agent analysis.
+   * The download requires authentication using the application's signature.
+   * This method returns the artifact as a Blob that can be saved or processed.
+   *
+   * **Simplified Signature Scheme:**
+   * The signature is generated over the operation ID only, allowing a single signature
+   * to be reused for listing and downloading multiple artifacts from the same operation.
+   * This simplifies client implementation while maintaining security - access to the
+   * operation ID grants access to all artifacts.
+   *
+   * @param params - The download parameters
+   * @param params.operationId - The operation ID that generated the artifact
+   * @param params.artifactPath - The path to the artifact file to download
+   * @returns A Blob containing the artifact data
+   * @throws {PersonalServerError} When the artifact cannot be downloaded or doesn't exist
+   * @throws {NetworkError} When unable to reach the personal server API
+   * @throws {SignatureError} When unable to create the required signature
+   * @example
+   * ```typescript
+   * // Download an artifact after a Gemini operation
+   * const blob = await vana.server.downloadArtifact({
+   *   operationId: 'op_123',
+   *   artifactPath: 'analysis_report.pdf'
+   * });
+   *
+   * // Save to file in Node.js
+   * const buffer = await blob.arrayBuffer();
+   * fs.writeFileSync('report.pdf', Buffer.from(buffer));
+   *
+   * // Or create download link in browser
+   * const url = URL.createObjectURL(blob);
+   * const a = document.createElement('a');
+   * a.href = url;
+   * a.download = 'report.pdf';
+   * a.click();
+   * ```
+   */
+  async downloadArtifact(params) {
+    this.assertWallet();
+    try {
+      const signatureData = {
+        operation_id: params.operationId
+      };
+      const requestJson = JSON.stringify(signatureData);
+      const messageHash = SignatureCache.hashMessage(signatureData);
+      let signature = SignatureCache.get(
+        this.context.platform.cache,
+        this.getAccountAddress(),
+        messageHash
+      );
+      if (!signature) {
+        signature = await this.createSignature(requestJson);
+        SignatureCache.set(
+          this.context.platform.cache,
+          this.getAccountAddress(),
+          messageHash,
+          signature,
+          24
+          // Cache for 24 hours since operation_id doesn't change
+        );
+      }
+      const requestBody = {
+        operation_id: params.operationId,
+        artifact_path: params.artifactPath,
+        signature
+      };
+      const response = await fetch(
+        `${this.personalServerBaseUrl}${SERVER_PATHS.downloadArtifact}`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(requestBody)
+        }
+      );
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new PersonalServerError(
+          `Artifact download failed: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      return await response.blob();
+    } catch (error) {
+      if (error instanceof NetworkError || error instanceof PersonalServerError || error instanceof SignatureError) {
+        throw error;
+      }
+      throw new PersonalServerError(
+        `Failed to download artifact: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Lists all artifacts generated by a server operation.
+   *
+   * @remarks
+   * Retrieves metadata for all artifact files produced by an operation,
+   * including file paths, sizes, and content types. This provides visibility
+   * into available outputs without downloading them.
+   *
+   * **Simplified Signature Scheme:**
+   * Uses the same signature as downloadArtifact - signs only operation_id.
+   * This allows reusing the same signature for listing and downloading.
+   *
+   * @param operationId - The operation ID that generated the artifacts
+   * @returns Promise resolving to array of artifact metadata objects
+   * @throws {PersonalServerError} When artifacts cannot be listed
+   * @throws {NetworkError} When unable to reach the personal server API
+   * @throws {SignatureError} When unable to create the required signature
+   * @example
+   * ```typescript
+   * // List artifacts from a Gemini operation
+   * const artifacts = await vana.server.listArtifacts('op_123');
+   *
+   * console.log(`Found ${artifacts.length} artifacts:`);
+   * artifacts.forEach(artifact => {
+   *   console.log(`- ${artifact.path} (${artifact.size} bytes)`);
+   * });
+   *
+   * // Download a specific artifact
+   * const blob = await vana.server.downloadArtifact({
+   *   operationId: 'op_123',
+   *   artifactPath: artifacts[0].path
+   * });
+   * ```
+   */
+  async listArtifacts(operationId) {
+    this.assertWallet();
+    try {
+      const signatureData = {
+        operation_id: operationId
+      };
+      const requestJson = JSON.stringify(signatureData);
+      const messageHash = SignatureCache.hashMessage(signatureData);
+      let signature = SignatureCache.get(
+        this.context.platform.cache,
+        this.getAccountAddress(),
+        messageHash
+      );
+      if (!signature) {
+        signature = await this.createSignature(requestJson);
+        SignatureCache.set(
+          this.context.platform.cache,
+          this.getAccountAddress(),
+          messageHash,
+          signature,
+          24
+          // Cache for 24 hours since operation_id doesn't change
+        );
+      }
+      const requestBody = {
+        operation_id: operationId,
+        signature
+      };
+      const response = await fetch(
+        `${this.personalServerBaseUrl}${SERVER_PATHS.listArtifacts(operationId)}`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(requestBody)
+        }
+      );
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new PersonalServerError(
+          `Failed to list artifacts: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      const data = await response.json();
+      return data.artifacts ?? [];
+    } catch (error) {
+      if (error instanceof NetworkError || error instanceof PersonalServerError || error instanceof SignatureError) {
+        throw error;
+      }
+      throw new PersonalServerError(
+        `Failed to list artifacts: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * 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(
+        `${this.personalServerBaseUrl}${SERVER_PATHS.cancelOperation(operationId)}`,
+        {
+          method: "POST"
+        }
+      );
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new PersonalServerError(
+          `Failed to cancel operation: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+    } catch (error) {
+      if (error instanceof NetworkError) {
+        throw error;
+      }
+      throw new NetworkError(
+        `Failed to cancel operation: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Makes the request to the personal server API.
+   *
+   * @param requestBody - The post request parameters to serialize
+   * @returns JSON string representation of the request data
+   */
+  async makeRequest(requestBody) {
+    try {
+      console.debug("Personal Server Request:", {
+        url: `${this.personalServerBaseUrl}${SERVER_PATHS.operations}`,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: requestBody
+      });
+      const response = await fetch(
+        `${this.personalServerBaseUrl}${SERVER_PATHS.operations}`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(requestBody)
+        }
+      );
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.debug("Personal Server Error Response:", {
+          status: response.status,
+          statusText: response.statusText,
+          error: errorText
+        });
+        throw new NetworkError(
+          `Personal server API request failed: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      const data = await response.json();
+      console.debug("Personal Server Success Response:", data);
+      return data;
+    } catch (error) {
+      if (error instanceof NetworkError) {
+        throw error;
+      }
+      throw new NetworkError(
+        `Failed to make personal server API request: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+  /**
+   * Gets the account address from the wallet client.
+   *
+   * @returns The account address
+   * @throws {Error} When no account is available
+   */
+  getAccountAddress() {
+    const client = this.context.applicationClient ?? this.context.walletClient;
+    if (!client) {
+      throw new Error("No client available for getting account address");
+    }
+    const { account } = client;
+    if (!account) {
+      throw new Error("No account available");
+    }
+    return typeof account === "string" ? account : account.address;
+  }
+  /**
+   * Creates a signature for the request JSON.
+   *
+   * @param requestJson - The JSON string to sign
+   * @returns Promise resolving to the cryptographic signature
+   */
+  async createSignature(requestJson) {
+    try {
+      console.debug("\u{1F50D} Debug - createSignature", requestJson);
+      const client = this.context.applicationClient ?? this.context.walletClient;
+      if (!client) {
+        throw new SignatureError("No client available for signing");
+      }
+      const { account } = client;
+      if (!account) {
+        throw new SignatureError("No account available for signing");
+      }
+      console.debug("\u{1F50D} Debug - createSignature account", account);
+      const signature = await client.signMessage({
+        account,
+        message: requestJson
+      });
+      return signature;
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("User rejected")) {
+        throw new SignatureError("User rejected the signature request");
+      }
+      throw new SignatureError(
+        `Failed to create signature: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+}
+export {
+  ServerController
+};
+//# sourceMappingURL=server.js.map