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

package/dist/controllers/server.d.cts

@@ -0,0 +1,230 @@
+import { Operation, PollingOptions } from '../types/operations.cjs';
+import { ControllerContext } from '../types/controller-context.cjs';
+import { InitPersonalServerParams, PersonalServerIdentity, CreateOperationParams } from '../types/personal.cjs';
+import '../generated/event-types.cjs';
+import 'viem';
+import '../generated/server/server-exports.cjs';
+import '../generated/server/server.cjs';
+import '../platform/interface.cjs';
+import '../types/config.cjs';
+import '../types/chains.cjs';
+import '../types/storage.cjs';
+import '../types/permissions.cjs';
+import '../storage/manager.cjs';
+
+/**
+ * Manages interactions with Vana personal servers and identity infrastructure.
+ *
+ * @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.
+ *
+ * **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.
+ *
+ * **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
+ *
+ * **Workflow Pattern:**
+ * Typical flow: Get identity → Create operation → Poll status → Retrieve results
+ *
+ * @example
+ * ```typescript
+ * // Get a server's identity including public key for encryption
+ * const identity = await vana.server.getIdentity({
+ *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+ * });
+ *
+ * // Create an operation using a granted permission
+ * const response = await vana.server.createOperation({
+ *   permissionId: 123,
+ * });
+ *
+ * // Poll for computation results
+ * const result = await vana.server.getOperation(response.id);
+ * ```
+ * @category Server Management
+ * @see {@link https://docs.vana.com/developer/personal-servers | Vana Personal Servers} for conceptual overview
+ */
+declare class ServerController {
+    private readonly context;
+    constructor(context: ControllerContext);
+    private get personalServerBaseUrl();
+    /**
+     * Retrieves the cryptographic identity of 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
+     * @example
+     * ```typescript
+     * // Get server identity for data encryption
+     * const identity = await vana.server.getIdentity({
+     *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+     * });
+     *
+     * console.log(`Server: ${identity.name}`);
+     * console.log(`Address: ${identity.address}`);
+     * console.log(`Public Key: ${identity.public_key}`);
+     *
+     * // Use the public key for encrypting data to share with this server
+     * const encryptedData = await encryptWithWalletPublicKey(
+     *   userData,
+     *   identity.public_key
+     * );
+     * ```
+     */
+    getIdentity(request: InitPersonalServerParams): Promise<PersonalServerIdentity>;
+    /**
+     * Creates a server operation and returns its details as a plain object.
+     *
+     * @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.
+     *
+     * @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
+     * @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({
+     *   permissionId: 123
+     * });
+     * console.log(`Operation ID: ${operation.id}`);
+     *
+     * // Wait for completion
+     * const result = await vana.server.waitForOperation(operation.id);
+     * console.log("Result:", result.result);
+     * ```
+     */
+    createOperation<T = unknown>(params: CreateOperationParams): Promise<Operation<T>>;
+    /**
+     * Retrieves the current status and result of a server operation.
+     *
+     * @remarks
+     * Common status values: `starting`, `running`, `succeeded`, `failed`, `canceled`.
+     * When status is `succeeded`, the result field contains the operation output.
+     *
+     * @param operationId - The ID of the operation to query
+     * @returns The operation as a plain object containing status, result, and metadata
+     * @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);
+     * }
+     * ```
+     */
+    getOperation<T = unknown>(operationId: string): Promise<Operation<T>>;
+    /**
+     * 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.
+     *
+     * @param opOrId - Either an Operation object or operation ID string
+     * @param options - Optional polling configuration
+     * @returns The completed operation with result or error
+     * @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
+     * });
+     * ```
+     */
+    waitForOperation<T = unknown>(opOrId: Operation<T> | string, options?: PollingOptions): Promise<Operation<T>>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    cancelOperation(operationId: string): Promise<void>;
+    /**
+     * Makes the request to the personal server API.
+     *
+     * @param requestBody - The post request parameters to serialize
+     * @returns JSON string representation of the request data
+     */
+    private makeRequest;
+    /**
+     * Creates a signature for the request JSON.
+     *
+     * @param requestJson - The JSON string to sign
+     * @returns Promise resolving to the cryptographic signature
+     */
+    private createSignature;
+}
+
+export { ServerController };

package/dist/controllers/server.d.ts

@@ -0,0 +1,230 @@
+import { Operation, PollingOptions } from '../types/operations.js';
+import { ControllerContext } from '../types/controller-context.js';
+import { InitPersonalServerParams, PersonalServerIdentity, CreateOperationParams } from '../types/personal.js';
+import '../generated/event-types.js';
+import 'viem';
+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/storage.js';
+import '../types/permissions.js';
+import '../storage/manager.js';
+
+/**
+ * Manages interactions with Vana personal servers and identity infrastructure.
+ *
+ * @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.
+ *
+ * **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.
+ *
+ * **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
+ *
+ * **Workflow Pattern:**
+ * Typical flow: Get identity → Create operation → Poll status → Retrieve results
+ *
+ * @example
+ * ```typescript
+ * // Get a server's identity including public key for encryption
+ * const identity = await vana.server.getIdentity({
+ *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+ * });
+ *
+ * // Create an operation using a granted permission
+ * const response = await vana.server.createOperation({
+ *   permissionId: 123,
+ * });
+ *
+ * // Poll for computation results
+ * const result = await vana.server.getOperation(response.id);
+ * ```
+ * @category Server Management
+ * @see {@link https://docs.vana.com/developer/personal-servers | Vana Personal Servers} for conceptual overview
+ */
+declare class ServerController {
+    private readonly context;
+    constructor(context: ControllerContext);
+    private get personalServerBaseUrl();
+    /**
+     * Retrieves the cryptographic identity of 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
+     * @example
+     * ```typescript
+     * // Get server identity for data encryption
+     * const identity = await vana.server.getIdentity({
+     *   userAddress: "0x742d35Cc6558Fd4D9e9E0E888F0462ef6919Bd36"
+     * });
+     *
+     * console.log(`Server: ${identity.name}`);
+     * console.log(`Address: ${identity.address}`);
+     * console.log(`Public Key: ${identity.public_key}`);
+     *
+     * // Use the public key for encrypting data to share with this server
+     * const encryptedData = await encryptWithWalletPublicKey(
+     *   userData,
+     *   identity.public_key
+     * );
+     * ```
+     */
+    getIdentity(request: InitPersonalServerParams): Promise<PersonalServerIdentity>;
+    /**
+     * Creates a server operation and returns its details as a plain object.
+     *
+     * @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.
+     *
+     * @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
+     * @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({
+     *   permissionId: 123
+     * });
+     * console.log(`Operation ID: ${operation.id}`);
+     *
+     * // Wait for completion
+     * const result = await vana.server.waitForOperation(operation.id);
+     * console.log("Result:", result.result);
+     * ```
+     */
+    createOperation<T = unknown>(params: CreateOperationParams): Promise<Operation<T>>;
+    /**
+     * Retrieves the current status and result of a server operation.
+     *
+     * @remarks
+     * Common status values: `starting`, `running`, `succeeded`, `failed`, `canceled`.
+     * When status is `succeeded`, the result field contains the operation output.
+     *
+     * @param operationId - The ID of the operation to query
+     * @returns The operation as a plain object containing status, result, and metadata
+     * @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);
+     * }
+     * ```
+     */
+    getOperation<T = unknown>(operationId: string): Promise<Operation<T>>;
+    /**
+     * 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.
+     *
+     * @param opOrId - Either an Operation object or operation ID string
+     * @param options - Optional polling configuration
+     * @returns The completed operation with result or error
+     * @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
+     * });
+     * ```
+     */
+    waitForOperation<T = unknown>(opOrId: Operation<T> | string, options?: PollingOptions): Promise<Operation<T>>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    cancelOperation(operationId: string): Promise<void>;
+    /**
+     * Makes the request to the personal server API.
+     *
+     * @param requestBody - The post request parameters to serialize
+     * @returns JSON string representation of the request data
+     */
+    private makeRequest;
+    /**
+     * Creates a signature for the request JSON.
+     *
+     * @param requestJson - The JSON string to sign
+     * @returns Promise resolving to the cryptographic signature
+     */
+    private createSignature;
+}
+
+export { ServerController };