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

package/dist/controllers/server.d.ts

@@ -1,69 +1,78 @@
-import type { CreateOperationParams, InitPersonalServerParams, PersonalServerIdentity } from "../types";
+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";
 /**
- * Manages interactions with Vana personal servers and identity infrastructure.
+ * Manages personal server interactions for secure data processing.
  *
  * @remarks
- * This controller handles communication with personal servers for data processing
- * and identity servers for public key derivation. It provides methods for posting
- * computation requests to personal servers, polling for results, and retrieving
- * cryptographic keys for secure data sharing. All server interactions use the
- * Replicate API infrastructure with proper authentication and error handling.
+ * Handles communication with personal servers for computation requests
+ * and identity retrieval. Personal servers process user data with
+ * cryptographic verification, ensuring privacy and permission compliance.
  *
- * **Server Identity System:**
- * Personal servers use deterministic key derivation: each user address maps to a specific server identity.
- * This enables secure communication without requiring servers to be online during key retrieval.
+ * **Architecture:**
+ * Servers use deterministic key derivation from user addresses.
+ * Identity cached for offline retrieval. Operations authenticated
+ * via wallet signatures and permission verification.
  *
  * **Method Selection:**
- * - `getIdentity()` retrieves server public keys and addresses for encryption setup
- * - `createOperation()` submits computation requests with signed permission verification
- * - `getOperation()` polls operation status and retrieves results when complete
- * - `cancelOperation()` stops running operations when cancellation is supported
+ * - `getIdentity()` - Retrieve server public key for encryption
+ * - `createOperation()` - Submit computation with permission ID
+ * - `getOperation()` - Check status and retrieve results
+ * - `waitForOperation()` - Poll until completion or timeout
+ * - `cancelOperation()` - Stop running operations
  *
- * **Workflow Pattern:**
- * Typical flow: Get identity → Create operation → Poll status → Retrieve results
+ * **Typical Workflow:**
+ * 1. Get server identity for encryption key
+ * 2. Create operation with permission ID
+ * 3. Poll for completion
+ * 4. Retrieve results
  *
  * @example
  * ```typescript
- * // Get a server's identity including public key for encryption
+ * // Get server identity for encryption
  * const identity = await vana.server.getIdentity({
  *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
  * });
+ * console.log(`Server key: ${identity.publicKey}`);
  *
- * // Create an operation using a granted permission
- * const response = await vana.server.createOperation({
- *   permissionId: 123,
+ * // Submit computation request
+ * const operation = await vana.server.createOperation({
+ *   permissionId: 123
  * });
  *
- * // Poll for computation results
- * const result = await vana.server.getOperation(response.id);
+ * // Wait for results
+ * const result = await vana.server.waitForOperation(operation.id);
+ * console.log("Processing complete:", result.result);
  * ```
+ *
  * @category Server Management
- * @see {@link https://docs.vana.com/developer/personal-servers | Vana Personal Servers} for conceptual overview
+ * @see For conceptual overview, visit {@link https://docs.vana.org/docs/personal-servers}
  */
 export declare class ServerController extends BaseController {
     constructor(context: ControllerContext);
     private get personalServerBaseUrl();
     /**
-     * Retrieves the cryptographic identity of a personal server.
+     * Retrieves cryptographic identity for 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
+     * 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
-     * // Get server identity for data encryption
      * const identity = await vana.server.getIdentity({
      *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
      * });
@@ -72,60 +81,63 @@ export declare class ServerController extends BaseController {
      * console.log(`Address: ${identity.address}`);
      * console.log(`Public Key: ${identity.publicKey}`);
      *
-     * // Use the public key for encrypting data to share with this server
-     * const encryptedData = await encryptWithWalletPublicKey(
-     *   userData,
+     * // Use for encryption before data sharing
+     * const encrypted = await encryptWithPublicKey(
+     *   data,
      *   identity.publicKey
      * );
      * ```
      */
     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.
      *
@@ -133,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
@@ -152,9 +165,94 @@ 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.
+     *
+     * @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();
+     * ```
+     */
+    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.
      *
@@ -207,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.
      *