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

package/dist/controllers/server.cjs

@@ -0,0 +1,643 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var server_exports = {};
+__export(server_exports, {
+  ServerController: () => ServerController
+});
+module.exports = __toCommonJS(server_exports);
+var import_server_exports = require("../generated/server/server-exports");
+var import_errors = require("../errors");
+var import_base = require("./base");
+var import_signatureCache = require("../utils/signatureCache");
+class ServerController extends import_base.BaseController {
+  constructor(context) {
+    super(context);
+  }
+  get personalServerBaseUrl() {
+    if (!this.context.defaultPersonalServerUrl) {
+      throw new import_errors.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}${import_server_exports.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 import_errors.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 import_errors.NetworkError || error instanceof import_errors.PersonalServerError) {
+        throw error;
+      }
+      throw new import_errors.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 import_errors.NetworkError || error instanceof import_errors.SerializationError || error instanceof import_errors.SignatureError || error instanceof import_errors.PersonalServerError) {
+          throw error;
+        }
+        throw new import_errors.PersonalServerError(
+          `Personal server operation creation failed: ${error.message}`,
+          error
+        );
+      }
+      throw new import_errors.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}${import_server_exports.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 import_errors.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 import_errors.NetworkError) {
+        throw error;
+      }
+      throw new import_errors.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 import_errors.PersonalServerError(
+          `Operation ${operation.status}: ${errorMessage}`
+        );
+      }
+      if (operation.status === "canceled") {
+        throw new import_errors.PersonalServerError(`Operation was canceled`);
+      }
+      if (Date.now() - startTime > timeout) {
+        throw new import_errors.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 = import_signatureCache.SignatureCache.hashMessage(signatureData);
+      let signature = import_signatureCache.SignatureCache.get(
+        this.context.platform.cache,
+        this.getAccountAddress(),
+        messageHash
+      );
+      if (!signature) {
+        signature = await this.createSignature(requestJson);
+        import_signatureCache.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}${import_server_exports.SERVER_PATHS.downloadArtifact}`,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json"
+          },
+          body: JSON.stringify(requestBody)
+        }
+      );
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new import_errors.PersonalServerError(
+          `Artifact download failed: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      return await response.blob();
+    } catch (error) {
+      if (error instanceof import_errors.NetworkError || error instanceof import_errors.PersonalServerError || error instanceof import_errors.SignatureError) {
+        throw error;
+      }
+      throw new import_errors.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 = import_signatureCache.SignatureCache.hashMessage(signatureData);
+      let signature = import_signatureCache.SignatureCache.get(
+        this.context.platform.cache,
+        this.getAccountAddress(),
+        messageHash
+      );
+      if (!signature) {
+        signature = await this.createSignature(requestJson);
+        import_signatureCache.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}${import_server_exports.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 import_errors.PersonalServerError(
+          `Failed to list artifacts: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+      const data = await response.json();
+      return data.artifacts ?? [];
+    } catch (error) {
+      if (error instanceof import_errors.NetworkError || error instanceof import_errors.PersonalServerError || error instanceof import_errors.SignatureError) {
+        throw error;
+      }
+      throw new import_errors.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}${import_server_exports.SERVER_PATHS.cancelOperation(operationId)}`,
+        {
+          method: "POST"
+        }
+      );
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new import_errors.PersonalServerError(
+          `Failed to cancel operation: ${response.status} ${response.statusText} - ${errorText}`
+        );
+      }
+    } catch (error) {
+      if (error instanceof import_errors.NetworkError) {
+        throw error;
+      }
+      throw new import_errors.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}${import_server_exports.SERVER_PATHS.operations}`,
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: requestBody
+      });
+      const response = await fetch(
+        `${this.personalServerBaseUrl}${import_server_exports.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 import_errors.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 import_errors.NetworkError) {
+        throw error;
+      }
+      throw new import_errors.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 import_errors.SignatureError("No client available for signing");
+      }
+      const { account } = client;
+      if (!account) {
+        throw new import_errors.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 import_errors.SignatureError("User rejected the signature request");
+      }
+      throw new import_errors.SignatureError(
+        `Failed to create signature: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ServerController
+});
+//# sourceMappingURL=server.cjs.map