@phala/cloud 0.1.1 → 0.1.2

package/dist/utils/errors.d.ts

@@ -0,0 +1,261 @@
+import { z } from "zod";
+import type { FetchError, FetchRequest } from "ofetch";
+/**
+ * API Error Response Schema
+ */
+export declare const ApiErrorSchema: z.ZodObject<{
+    detail: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodObject<{
+        msg: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        msg: string;
+        type?: string | undefined;
+        ctx?: Record<string, unknown> | undefined;
+    }, {
+        msg: string;
+        type?: string | undefined;
+        ctx?: Record<string, unknown> | undefined;
+    }>, "many">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    type: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    code?: string | undefined;
+    type?: string | undefined;
+    detail?: string | Record<string, unknown> | {
+        msg: string;
+        type?: string | undefined;
+        ctx?: Record<string, unknown> | undefined;
+    }[] | undefined;
+}, {
+    code?: string | undefined;
+    type?: string | undefined;
+    detail?: string | Record<string, unknown> | {
+        msg: string;
+        type?: string | undefined;
+        ctx?: Record<string, unknown> | undefined;
+    }[] | undefined;
+}>;
+export type ApiError = z.infer<typeof ApiErrorSchema>;
+/**
+ * Structured validation error item from FastAPI/Pydantic
+ */
+export interface ValidationErrorItem {
+    /** Field path (e.g., "name", "body.memory", "query.page") */
+    field: string;
+    /** Human-readable error message */
+    message: string;
+    /** Error type from Pydantic (e.g., "string_too_short", "greater_than_equal") */
+    type: string;
+    /** Additional context (e.g., { min_length: 4 }) */
+    context?: Record<string, unknown>;
+}
+/**
+ * Base class for all Phala Cloud API errors
+ */
+export declare class PhalaCloudError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly detail?: string | Record<string, unknown> | Array<{
+        msg: string;
+        type?: string;
+        ctx?: Record<string, unknown>;
+    }>;
+    constructor(message: string, data: {
+        status: number;
+        statusText: string;
+        detail?: string | Record<string, unknown> | Array<{
+            msg: string;
+            type?: string;
+            ctx?: Record<string, unknown>;
+        }>;
+    });
+}
+/**
+ * Base error class for HTTP requests
+ * Extends PhalaCloudError with additional HTTP-specific properties
+ */
+export declare class RequestError extends PhalaCloudError implements ApiError {
+    readonly name = "RequestError";
+    readonly isRequestError: true;
+    readonly data?: unknown;
+    readonly request?: FetchRequest | undefined;
+    readonly response?: Response | undefined;
+    readonly code?: string | undefined;
+    readonly type?: string | undefined;
+    constructor(message: string, options?: {
+        status?: number | undefined;
+        statusText?: string | undefined;
+        data?: unknown;
+        request?: FetchRequest | undefined;
+        response?: Response | undefined;
+        cause?: unknown;
+        detail?: string | Record<string, unknown> | Array<{
+            msg: string;
+            type?: string;
+            ctx?: Record<string, unknown>;
+        }>;
+        code?: string | undefined;
+        type?: string | undefined;
+    });
+    /**
+     * Create RequestError from FetchError
+     */
+    static fromFetchError(error: FetchError): RequestError;
+    /**
+     * Create RequestError from generic Error
+     */
+    static fromError(error: Error, request?: FetchRequest): RequestError;
+}
+/**
+ * Validation error from FastAPI/Pydantic (422)
+ * Use instanceof to check: if (error instanceof ValidationError) { ... }
+ * Or use property: if (error.isValidationError) { ... }
+ */
+export declare class ValidationError extends PhalaCloudError {
+    readonly isValidationError: true;
+    readonly validationErrors: ValidationErrorItem[];
+    constructor(message: string, data: {
+        status: number;
+        statusText: string;
+        detail?: string | Record<string, unknown> | Array<{
+            msg: string;
+            type?: string;
+            ctx?: Record<string, unknown>;
+        }>;
+        validationErrors: ValidationErrorItem[];
+    });
+}
+/**
+ * Authentication/Authorization error (401, 403)
+ * Use instanceof to check: if (error instanceof AuthError) { ... }
+ * Or use property: if (error.isAuthError) { ... }
+ */
+export declare class AuthError extends PhalaCloudError {
+    readonly isAuthError: true;
+}
+/**
+ * Business logic error (400, 409, etc.)
+ * Use instanceof to check: if (error instanceof BusinessError) { ... }
+ * Or use property: if (error.isBusinessError) { ... }
+ */
+export declare class BusinessError extends PhalaCloudError {
+    readonly isBusinessError: true;
+}
+/**
+ * Server error (500+)
+ * Use instanceof to check: if (error instanceof ServerError) { ... }
+ * Or use property: if (error.isServerError) { ... }
+ */
+export declare class ServerError extends PhalaCloudError {
+    readonly isServerError: true;
+}
+/**
+ * Unknown error (network issues, etc.)
+ * Use instanceof to check: if (error instanceof UnknownError) { ... }
+ * Or use property: if (error.isUnknownError) { ... }
+ */
+export declare class UnknownError extends PhalaCloudError {
+    readonly isUnknownError: true;
+}
+/**
+ * Parse RequestError into PhalaCloudError instance
+ *
+ * Returns the appropriate error subclass based on status code:
+ * - 422 → ValidationError (with validationErrors array)
+ * - 401, 403 → AuthError
+ * - 400, 409, etc. → BusinessError
+ * - 500+ → ServerError
+ * - Other → UnknownError
+ *
+ * @param requestError - The RequestError from API call
+ * @returns PhalaCloudError subclass instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.post('/cvms', data);
+ * } catch (error) {
+ *   if (error instanceof ValidationError) {
+ *     // TypeScript knows error.validationErrors exists
+ *     error.validationErrors.forEach(e => {
+ *       console.error(`${e.field}: ${e.message}`);
+ *     });
+ *   } else if (error instanceof AuthError) {
+ *     // Handle auth error
+ *   }
+ * }
+ * ```
+ */
+export declare function parseApiError(requestError: RequestError): PhalaCloudError;
+/**
+ * Extract all field names from validation errors
+ *
+ * @deprecated Use `error instanceof ValidationError` and `error.validationErrors` directly
+ */
+export declare function getValidationFields(error: PhalaCloudError): string[];
+/**
+ * Format validation errors for display
+ *
+ * @param errors - Array of validation error items
+ * @param options - Formatting options
+ * @returns Formatted string for display
+ *
+ * @example
+ * ```typescript
+ * if (error instanceof ValidationError) {
+ *   const formatted = formatValidationErrors(error.validationErrors, {
+ *     numbered: true,
+ *     indent: 2
+ *   });
+ *   console.error(formatted);
+ * }
+ * // Output:
+ * //   1. name: String should have at least 4 characters
+ * //   2. memory: Input should be greater than or equal to 1024
+ * ```
+ */
+export declare function formatValidationErrors(errors: ValidationErrorItem[], options?: {
+    /** Add numbers to each error (default: true) */
+    numbered?: boolean;
+    /** Indent size in spaces (default: 2) */
+    indent?: number;
+    /** Show field names (default: true) */
+    showFields?: boolean;
+}): string;
+/**
+ * Create a user-friendly error message from PhalaCloudError
+ *
+ * @param error - Phala Cloud API error
+ * @param options - Formatting options
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.post('/cvms', data);
+ * } catch (error) {
+ *   if (error instanceof PhalaCloudError) {
+ *     console.error(formatErrorMessage(error));
+ *   }
+ * }
+ * // Output:
+ * // Validation failed (2 issues)
+ * //
+ * //   1. name: String should have at least 4 characters
+ * //   2. memory: Input should be greater than or equal to 1024
+ * ```
+ */
+export declare function formatErrorMessage(error: PhalaCloudError, options?: {
+    /** Include field names in validation errors (default: true) */
+    showFields?: boolean;
+    /** Include error class name in output (default: false) */
+    showType?: boolean;
+}): string;
+/**
+ * Extract error message from API error
+ *
+ * @param error - API error object
+ * @returns Error message string
+ */
+export declare function getErrorMessage(error: ApiError): string;

package/dist/utils/index.d.ts

@@ -1,8 +1,8 @@
 export { encryptEnvVars } from "@phala/dstack-sdk/encrypt-env-vars";
 export { getComposeHash, dumpAppCompose, preprocessAppCompose, sortObject, withComposeMethods, type AppCompose, type AppComposeWithMethods, type SortableValue, type SortableObject, type SortableArray, } from "./get_compose_hash";
-export { getErrorMessage } from "./get_error_message";
 export { asHex } from "./as-hex";
 export { validateActionParameters, safeValidateActionParameters } from "./validate-parameters";
+export { parseApiError, PhalaCloudError, RequestError, ValidationError, AuthError, BusinessError, ServerError, UnknownError, formatValidationErrors, formatErrorMessage, getErrorMessage, getValidationFields, type ValidationErrorItem, ApiErrorSchema, type ApiError, } from "./errors";
 export { createNetworkClients, extractNetworkClients, checkNetworkStatus, checkBalance, validateNetworkPrerequisites, waitForTransactionReceipt, executeTransaction, NetworkError, WalletError, TransactionError, type NetworkConfig, type WalletConnection, type NetworkClients, type BalanceCheckResult, type TransactionOptions, type TransactionResult, } from "./network";
 export { createTransactionTracker, executeBatchTransactions, executeTransactionWithRetry, estimateTransactionGas, type TransactionState, type TransactionStatus, type TransactionTracker, type BatchTransactionOptions, type BatchTransactionResult, type RetryOptions, type GasEstimationOptions, } from "./transaction";
 export { createClientsFromPrivateKey, createClientsFromBrowser, autoCreateClients, switchToNetwork, addNetwork, } from "./client-factories";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phala/cloud",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TypeScript SDK for Phala Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -40,6 +40,7 @@
   "dependencies": {
     "@phala/dstack-sdk": "0.5.4-beta.6",
     "debug": "^4.4.1",
+    "mitt": "^3.0.1",
     "ofetch": "^1.3.3",
     "viem": "^2.7.0",
     "zod": "^3.22.4"

package/dist/utils/get_error_message.d.ts

@@ -1,2 +0,0 @@
-import type { ApiError } from "../types";
-export declare function getErrorMessage(error: ApiError): string;