@opendatalabs/vana-sdk 0.1.0-alpha.9b6ddbc → 0.1.0-alpha.9bbda27

package/dist/controllers/server.d.ts

@@ -1,4 +1,5 @@
 import type { CreateOperationParams, InitPersonalServerParams, PersonalServerIdentity, DownloadArtifactParams } from "../types";
+import type { CreateOperationResponse } from "../generated/server/server-exports";
 import type { ControllerContext } from "./permissions";
 import type { Operation, PollingOptions } from "../types/operations";
 import { BaseController } from "./base";
@@ -89,51 +90,54 @@ export declare class ServerController extends BaseController {
      */
     getIdentity(request: InitPersonalServerParams): Promise<PersonalServerIdentity>;
     /**
-     * Creates a server operation and returns its details as a plain object.
+     * 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
-     * an Operation object that can be serialized and passed across API boundaries.
-     * Use `waitForOperation()` to poll for completion.
+     * 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 An Operation object containing the operation ID and status
+     * @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 operation = await vana.server.createOperation({
+     * const response = await vana.server.createOperation({
      *   permissionId: 123
      * });
-     * console.log(`Operation ID: ${operation.id}`);
+     * console.log(`Operation ID: ${response.id}`);
      *
      * // Wait for completion
-     * const result = await vana.server.waitForOperation(operation.id);
+     * const result = await vana.server.waitForOperation(response.id);
      * console.log("Result:", result.result);
      * ```
      */
-    createOperation<T = unknown>(params: CreateOperationParams): Promise<Operation<T>>;
+    createOperation(params: CreateOperationParams): Promise<CreateOperationResponse>;
     /**
      * Retrieves the current status and result of a server operation.
      *
      * @remarks
-     * Common status values: `starting`, `running`, `succeeded`, `failed`, `canceled`.
+     * 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 as a plain object containing status, result, and metadata
+     * @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);
      * }
      * ```
      */
-    getOperation<T = unknown>(operationId: string): Promise<Operation<T>>;
+    getOperation(operationId: string): Promise<Operation>;
     /**
      * Waits for an operation to complete and returns the final result.
      *
@@ -141,10 +145,11 @@ export declare class ServerController extends BaseController {
      * 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 or error
+     * @returns The completed operation with result and timestamp data
      * @throws {PersonalServerError} When the operation fails or times out
      * @example
      * ```typescript
@@ -160,9 +165,13 @@ export declare class ServerController extends BaseController {
      *   timeout: 60000,
      *   pollingInterval: 1000
      * });
+     *
+     * // Access server-provided timestamps
+     * console.log('Started:', completed.started_at);
+     * console.log('Finished:', completed.finished_at);
      * ```
      */
-    waitForOperation<T = unknown>(opOrId: Operation<T> | string, options?: PollingOptions): Promise<Operation<T>>;
+    waitForOperation(opOrId: Operation | string, options?: PollingOptions): Promise<Operation>;
     /**
      * Downloads an artifact generated by a server operation.
      *
@@ -171,6 +180,12 @@ export declare class ServerController extends BaseController {
      * 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
@@ -199,6 +214,45 @@ export declare class ServerController extends BaseController {
      * ```
      */
     downloadArtifact(params: DownloadArtifactParams): Promise<Blob>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    listArtifacts(operationId: string): Promise<Array<{
+        path: string;
+        size: number;
+        content_type: string;
+    }>>;
     /**
      * Cancels a running operation on the personal server.
      *
@@ -251,6 +305,13 @@ export declare class ServerController extends BaseController {
      * @returns JSON string representation of the request data
      */
     private makeRequest;
+    /**
+     * Gets the account address from the wallet client.
+     *
+     * @returns The account address
+     * @throws {Error} When no account is available
+     */
+    private getAccountAddress;
     /**
      * Creates a signature for the request JSON.
      *

package/dist/controllers/server.js

@@ -1,3 +1,4 @@
+import { SERVER_PATHS } from "../generated/server/server-exports";
 import {
   NetworkError,
   SerializationError,
@@ -5,6 +6,7 @@ import {
   PersonalServerError
 } from "../errors";
 import { BaseController } from "./base";
+import { SignatureCache } from "../utils/signatureCache";
 class ServerController extends BaseController {
   constructor(context) {
     super(context);
@@ -15,7 +17,11 @@ class ServerController extends BaseController {
         "Personal server URL is required for server operations. Please configure defaultPersonalServerUrl in your VanaConfig."
       );
     }
-    return this.context.defaultPersonalServerUrl;
+    let url = this.context.defaultPersonalServerUrl;
+    if (url.endsWith("/api/v1")) {
+      url = url.slice(0, -7);
+    }
+    return url;
   }
   /**
    * Retrieves cryptographic identity for a personal server.
@@ -55,7 +61,7 @@ class ServerController extends BaseController {
   async getIdentity(request) {
     try {
       const response = await fetch(
-        `${this.personalServerBaseUrl}/identity?address=${request.userAddress}`,
+        `${this.personalServerBaseUrl}${SERVER_PATHS.getIdentityApiV1IdentityGet}?address=${request.userAddress}`,
         {
           method: "GET",
           headers: {
@@ -88,28 +94,28 @@ class ServerController extends BaseController {
     }
   }
   /**
-   * Creates a server operation and returns its details as a plain object.
+   * 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
-   * an Operation object that can be serialized and passed across API boundaries.
-   * Use `waitForOperation()` to poll for completion.
+   * 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 An Operation object containing the operation ID and status
+   * @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 operation = await vana.server.createOperation({
+   * const response = await vana.server.createOperation({
    *   permissionId: 123
    * });
-   * console.log(`Operation ID: ${operation.id}`);
+   * console.log(`Operation ID: ${response.id}`);
    *
    * // Wait for completion
-   * const result = await vana.server.waitForOperation(operation.id);
+   * const result = await vana.server.waitForOperation(response.id);
    * console.log("Result:", result.result);
    * ```
    */
@@ -127,11 +133,7 @@ class ServerController extends BaseController {
       };
       console.debug("\u{1F50D} Debug - createOperation requestBody", requestBody);
       const response = await this.makeRequest(requestBody);
-      return {
-        id: response.id,
-        status: "starting",
-        createdAt: Date.now()
-      };
+      return response;
     } catch (error) {
       if (error instanceof Error) {
         if (error instanceof NetworkError || error instanceof SerializationError || error instanceof SignatureError || error instanceof PersonalServerError) {
@@ -151,17 +153,20 @@ class ServerController extends BaseController {
    * Retrieves the current status and result of a server operation.
    *
    * @remarks
-   * Common status values: `starting`, `running`, `succeeded`, `failed`, `canceled`.
+   * 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 as a plain object containing status, result, and metadata
+   * @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);
    * }
    * ```
    */
@@ -169,7 +174,7 @@ class ServerController extends BaseController {
     try {
       console.debug("Polling Operation Status:", operationId);
       const response = await fetch(
-        `${this.personalServerBaseUrl}/operations/${operationId}`,
+        `${this.personalServerBaseUrl}${SERVER_PATHS.getOperationApiV1Operations_OperationId_Get(operationId)}`,
         {
           method: "GET",
           headers: {
@@ -190,14 +195,7 @@ class ServerController extends BaseController {
       }
       const data = await response.json();
       console.debug("Polling Success Response:", data);
-      return {
-        id: data.id,
-        status: data.status,
-        createdAt: Date.now(),
-        updatedAt: Date.now(),
-        result: data.status === "succeeded" ? data.result : void 0,
-        error: data.status === "failed" ? data.result ?? void 0 : void 0
-      };
+      return data;
     } catch (error) {
       if (error instanceof NetworkError) {
         throw error;
@@ -214,10 +212,11 @@ class ServerController extends BaseController {
    * 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 or error
+   * @returns The completed operation with result and timestamp data
    * @throws {PersonalServerError} When the operation fails or times out
    * @example
    * ```typescript
@@ -233,6 +232,10 @@ class ServerController extends BaseController {
    *   timeout: 60000,
    *   pollingInterval: 1000
    * });
+   *
+   * // Access server-provided timestamps
+   * console.log('Started:', completed.started_at);
+   * console.log('Finished:', completed.finished_at);
    * ```
    */
   async waitForOperation(opOrId, options) {
@@ -246,8 +249,13 @@ class ServerController extends BaseController {
         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}: ${operation.error ?? "Unknown error"}`
+          `Operation ${operation.status}: ${errorMessage}`
         );
       }
       if (operation.status === "canceled") {
@@ -267,6 +275,12 @@ class ServerController extends BaseController {
    * 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
@@ -297,18 +311,34 @@ class ServerController extends BaseController {
   async downloadArtifact(params) {
     this.assertWallet();
     try {
-      const requestData = {
-        operation_id: params.operationId,
-        artifact_path: params.artifactPath
+      const signatureData = {
+        operation_id: params.operationId
       };
-      const requestJson = JSON.stringify(requestData);
-      const signature = await this.createSignature(requestJson);
+      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 = {
-        ...requestData,
+        operation_id: params.operationId,
+        artifact_path: params.artifactPath,
         signature
       };
       const response = await fetch(
-        `${this.personalServerBaseUrl}/artifacts/download`,
+        `${this.personalServerBaseUrl}${SERVER_PATHS.downloadArtifactApiV1ArtifactsDownloadPost}`,
         {
           method: "POST",
           headers: {
@@ -333,6 +363,95 @@ class ServerController extends BaseController {
       );
     }
   }
+  /**
+   * 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.listArtifactsApiV1Artifacts_OperationId_ListPost(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.
    *
@@ -380,7 +499,7 @@ class ServerController extends BaseController {
   async cancelOperation(operationId) {
     try {
       const response = await fetch(
-        `${this.personalServerBaseUrl}/operations/${operationId}/cancel`,
+        `${this.personalServerBaseUrl}${SERVER_PATHS.cancelOperationApiV1Operations_OperationId_CancelPost(operationId)}`,
         {
           method: "POST"
         }
@@ -409,20 +528,23 @@ class ServerController extends BaseController {
   async makeRequest(requestBody) {
     try {
       console.debug("Personal Server Request:", {
-        url: `${this.personalServerBaseUrl}/operations`,
+        url: `${this.personalServerBaseUrl}${SERVER_PATHS.createOperationApiV1OperationsPost}`,
         method: "POST",
         headers: {
           "Content-Type": "application/json"
         },
         body: requestBody
       });
-      const response = await fetch(`${this.personalServerBaseUrl}/operations`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json"
-        },
-        body: JSON.stringify(requestBody)
-      });
+      const response = await fetch(
+        `${this.personalServerBaseUrl}${SERVER_PATHS.createOperationApiV1OperationsPost}`,
+        {
+          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:", {
@@ -446,6 +568,23 @@ class ServerController extends BaseController {
       );
     }
   }
+  /**
+   * 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.
    *
@@ -463,13 +602,9 @@ class ServerController extends BaseController {
       if (!account) {
         throw new SignatureError("No account available for signing");
       }
-      if (account.type !== "local") {
-        throw new SignatureError(
-          "Only local accounts are supported for signing"
-        );
-      }
       console.debug("\u{1F50D} Debug - createSignature account", account);
-      const signature = await account.signMessage({
+      const signature = await client.signMessage({
+        account,
         message: requestJson
       });
       return signature;