@phala/cloud 0.1.1 → 0.1.2

package/dist/index.js

@@ -32,7 +32,9 @@ var index_exports = {};
 __export(index_exports, {
   AddComposeHashSchema: () => AddComposeHashSchema,
   ApiErrorSchema: () => ApiErrorSchema,
+  AuthError: () => AuthError,
   AvailableNodesSchema: () => AvailableNodesSchema,
+  BusinessError: () => BusinessError,
   CommitCvmComposeFileUpdateRequestSchema: () => CommitCvmComposeFileUpdateRequestSchema,
   CommitCvmComposeFileUpdateSchema: () => CommitCvmComposeFileUpdateSchema,
   CommitCvmProvisionRequestSchema: () => CommitCvmProvisionRequestSchema,
@@ -74,6 +76,7 @@ __export(index_exports, {
   NetworkError: () => NetworkError,
   PaginatedInstanceTypesSchema: () => PaginatedInstanceTypesSchema,
   PaginationMetadataSchema: () => PaginationMetadataSchema,
+  PhalaCloudError: () => PhalaCloudError,
   ProvisionCvmComposeFileUpdateRequestSchema: () => ProvisionCvmComposeFileUpdateRequestSchema,
   ProvisionCvmComposeFileUpdateResultSchema: () => ProvisionCvmComposeFileUpdateResultSchema,
   ProvisionCvmRequestSchema: () => ProvisionCvmRequestSchema,
@@ -81,13 +84,16 @@ __export(index_exports, {
   RequestError: () => RequestError,
   RestartCvmRequestSchema: () => RestartCvmRequestSchema,
   SUPPORTED_CHAINS: () => SUPPORTED_CHAINS,
+  ServerError: () => ServerError,
   ShutdownCvmRequestSchema: () => ShutdownCvmRequestSchema,
   StartCvmRequestSchema: () => StartCvmRequestSchema,
   StopCvmRequestSchema: () => StopCvmRequestSchema,
   TransactionError: () => TransactionError,
+  UnknownError: () => UnknownError,
   UpdateCvmResourcesRequestSchema: () => UpdateCvmResourcesRequestSchema,
   UpdateCvmVisibilityRequestSchema: () => UpdateCvmVisibilityRequestSchema,
   VMSchema: () => VMSchema,
+  ValidationError: () => ValidationError,
   VmInfoSchema: () => VmInfoSchema,
   WalletError: () => WalletError,
   WorkspaceResponseSchema: () => WorkspaceResponseSchema,
@@ -116,6 +122,8 @@ __export(index_exports, {
   executeTransaction: () => executeTransaction,
   executeTransactionWithRetry: () => executeTransactionWithRetry,
   extractNetworkClients: () => extractNetworkClients,
+  formatErrorMessage: () => formatErrorMessage,
+  formatValidationErrors: () => formatValidationErrors,
   getAppEnvEncryptPubKey: () => getAppEnvEncryptPubKey,
   getAvailableNodes: () => getAvailableNodes,
   getComposeHash: () => import_get_compose_hash3.getComposeHash,
@@ -131,9 +139,11 @@ __export(index_exports, {
   getErrorMessage: () => getErrorMessage,
   getKmsInfo: () => getKmsInfo,
   getKmsList: () => getKmsList,
+  getValidationFields: () => getValidationFields,
   getWorkspace: () => getWorkspace,
   listInstanceTypes: () => listInstanceTypes,
   listWorkspaces: () => listWorkspaces,
+  parseApiError: () => parseApiError,
   parseEnv: () => parseEnv,
   parseEnvVars: () => parseEnvVars,
   preprocessAppCompose: () => preprocessAppCompose,
@@ -189,8 +199,9 @@ module.exports = __toCommonJS(index_exports);
 // src/client.ts
 var import_ofetch = require("ofetch");
 var import_debug = __toESM(require("debug"));
+var import_mitt = __toESM(require("mitt"));
 
-// src/types/client.ts
+// src/utils/errors.ts
 var import_zod = require("zod");
 var ApiErrorSchema = import_zod.z.object({
   detail: import_zod.z.union([
@@ -203,21 +214,34 @@ var ApiErrorSchema = import_zod.z.object({
       })
     ),
     import_zod.z.record(import_zod.z.unknown())
-  ]),
+  ]).optional(),
   type: import_zod.z.string().optional(),
   code: import_zod.z.string().optional()
 });
-var RequestError = class _RequestError extends Error {
-  constructor(message, options) {
+var PhalaCloudError = class extends Error {
+  constructor(message, data) {
     super(message);
+    this.name = this.constructor.name;
+    this.status = data.status;
+    this.statusText = data.statusText;
+    this.detail = data.detail;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var RequestError = class _RequestError extends PhalaCloudError {
+  constructor(message, options) {
+    super(message, {
+      status: options?.status ?? 0,
+      statusText: options?.statusText ?? "Unknown Error",
+      detail: options?.detail || message
+    });
     this.name = "RequestError";
     this.isRequestError = true;
-    this.status = options?.status;
-    this.statusText = options?.statusText;
     this.data = options?.data;
     this.request = options?.request;
     this.response = options?.response;
-    this.detail = options?.detail || message;
     this.code = options?.code;
     this.type = options?.type;
   }
@@ -258,9 +282,172 @@ var RequestError = class _RequestError extends Error {
     });
   }
 };
+var ValidationError = class extends PhalaCloudError {
+  constructor(message, data) {
+    super(message, data);
+    this.isValidationError = true;
+    this.validationErrors = data.validationErrors;
+  }
+};
+var AuthError = class extends PhalaCloudError {
+  constructor() {
+    super(...arguments);
+    this.isAuthError = true;
+  }
+};
+var BusinessError = class extends PhalaCloudError {
+  constructor() {
+    super(...arguments);
+    this.isBusinessError = true;
+  }
+};
+var ServerError = class extends PhalaCloudError {
+  constructor() {
+    super(...arguments);
+    this.isServerError = true;
+  }
+};
+var UnknownError = class extends PhalaCloudError {
+  constructor() {
+    super(...arguments);
+    this.isUnknownError = true;
+  }
+};
+function extractFieldPath(loc) {
+  const filtered = loc.filter((part) => {
+    if (typeof part === "string") {
+      return !["body", "query", "path", "header"].includes(part);
+    }
+    return true;
+  });
+  return filtered.length > 0 ? filtered.join(".") : "unknown";
+}
+function parseValidationErrors(detail) {
+  if (!Array.isArray(detail)) {
+    return {
+      errors: [],
+      message: typeof detail === "string" ? detail : "Validation error"
+    };
+  }
+  const errors = detail.map((item) => ({
+    field: extractFieldPath(item.loc),
+    message: item.msg,
+    type: item.type,
+    context: item.ctx
+  }));
+  const count = errors.length;
+  const message = count === 1 ? `Validation failed: ${errors[0].message}` : `Validation failed (${count} issue${count > 1 ? "s" : ""})`;
+  return { errors, message };
+}
+function categorizeErrorType(status) {
+  if (status === 422) {
+    return "validation";
+  }
+  if (status === 401) {
+    return "auth";
+  }
+  if (status === 403) {
+    return "auth";
+  }
+  if (status >= 400 && status < 500) {
+    return "business";
+  }
+  if (status >= 500) {
+    return "server";
+  }
+  return "unknown";
+}
+function extractPrimaryMessage(status, detail, defaultMessage) {
+  if (status === 422 && Array.isArray(detail)) {
+    const { message } = parseValidationErrors(detail);
+    return message;
+  }
+  if (typeof detail === "string") {
+    return detail;
+  }
+  if (detail && typeof detail === "object" && "message" in detail) {
+    const msg = detail.message;
+    if (typeof msg === "string") {
+      return msg;
+    }
+  }
+  return defaultMessage;
+}
+function parseApiError(requestError) {
+  const status = requestError.status ?? 0;
+  const statusText = requestError.statusText ?? "Unknown Error";
+  const detail = requestError.detail;
+  const errorType = categorizeErrorType(status);
+  const message = extractPrimaryMessage(status, detail, requestError.message);
+  const commonData = {
+    status,
+    statusText,
+    detail
+  };
+  if (errorType === "validation" && Array.isArray(detail)) {
+    const { errors } = parseValidationErrors(detail);
+    return new ValidationError(message, {
+      ...commonData,
+      validationErrors: errors
+    });
+  }
+  if (errorType === "auth") {
+    return new AuthError(message, commonData);
+  }
+  if (errorType === "business") {
+    return new BusinessError(message, commonData);
+  }
+  if (errorType === "server") {
+    return new ServerError(message, commonData);
+  }
+  return new UnknownError(message, commonData);
+}
+function getValidationFields(error) {
+  if (error instanceof ValidationError) {
+    return error.validationErrors.map((e) => e.field);
+  }
+  return [];
+}
+function formatValidationErrors(errors, options) {
+  const { numbered = true, indent = 2, showFields = true } = options ?? {};
+  const indentStr = " ".repeat(indent);
+  return errors.map((error, index) => {
+    const prefix = numbered ? `${index + 1}. ` : "\u2022 ";
+    const field = showFields ? `${error.field}: ` : "";
+    return `${indentStr}${prefix}${field}${error.message}`;
+  }).join("\n");
+}
+function formatErrorMessage(error, options) {
+  const { showFields = true, showType = false } = options ?? {};
+  const parts = [];
+  if (showType) {
+    parts.push(`[${error.constructor.name.toUpperCase()}]`);
+  }
+  parts.push(error.message);
+  if (error instanceof ValidationError && error.validationErrors.length > 0) {
+    parts.push("");
+    parts.push(formatValidationErrors(error.validationErrors, { showFields }));
+  }
+  return parts.join("\n");
+}
+function getErrorMessage(error) {
+  if (typeof error.detail === "string") {
+    return error.detail;
+  }
+  if (Array.isArray(error.detail)) {
+    if (error.detail.length > 0) {
+      return error.detail[0]?.msg || "Validation error";
+    }
+    return "Validation error";
+  }
+  if (typeof error.detail === "object" && error.detail !== null) {
+    return JSON.stringify(error.detail);
+  }
+  return "Unknown error occurred";
+}
 
 // src/client.ts
-var SUPPORTED_API_VERSIONS = ["2025-05-31"];
+var SUPPORTED_API_VERSIONS = ["2025-05-31", "2025-10-28"];
 var logger = (0, import_debug.default)("phala::api-client");
 function formatHeaders(headers) {
   return Object.entries(headers).map(([key, value]) => `    -H "${key}: ${value}"`).join("\n");
@@ -286,18 +473,14 @@ function formatResponse(status, statusText, headers, body) {
 }
 var Client = class {
   constructor(config = {}) {
+    this.emitter = (0, import_mitt.default)();
     const resolvedConfig = {
       ...config,
       apiKey: config.apiKey || process?.env?.PHALA_CLOUD_API_KEY,
       baseURL: config.baseURL || process?.env?.PHALA_CLOUD_API_PREFIX || "https://cloud-api.phala.network/api/v1"
     };
-    const version = resolvedConfig.version && SUPPORTED_API_VERSIONS.includes(resolvedConfig.version) ? resolvedConfig.version : SUPPORTED_API_VERSIONS[0];
+    const version = resolvedConfig.version && SUPPORTED_API_VERSIONS.includes(resolvedConfig.version) ? resolvedConfig.version : SUPPORTED_API_VERSIONS[SUPPORTED_API_VERSIONS.length - 1];
     this.config = resolvedConfig;
-    if (!resolvedConfig.useCookieAuth && !resolvedConfig.apiKey) {
-      throw new Error(
-        "API key is required. Provide it via config.apiKey or set PHALA_CLOUD_API_KEY environment variable."
-      );
-    }
     const { apiKey, baseURL, timeout, headers, useCookieAuth, onResponseError, ...fetchOptions } = resolvedConfig;
     const requestHeaders = {
       "X-Phala-Version": version,
@@ -380,75 +563,137 @@ var Client = class {
   get raw() {
     return this.fetchInstance;
   }
+  on(type, handler) {
+    this.emitter.on(type, handler);
+  }
+  off(type, handler) {
+    this.emitter.off(type, handler);
+  }
+  once(type, handler) {
+    const wrappedHandler = (event) => {
+      handler(event);
+      this.emitter.off(type, wrappedHandler);
+    };
+    this.emitter.on(type, wrappedHandler);
+  }
   // ===== Direct methods (throw on error) =====
   /**
-   * Perform GET request (throws on error)
+   * Perform GET request (throws PhalaCloudError on error)
    */
   async get(request, options) {
-    return this.fetchInstance(request, {
-      ...options,
-      method: "GET"
-    });
+    try {
+      return await this.fetchInstance(request, {
+        ...options,
+        method: "GET"
+      });
+    } catch (error) {
+      const requestError = this.convertToRequestError(error);
+      const phalaCloudError = this.emitError(requestError);
+      throw phalaCloudError;
+    }
   }
   /**
-   * Perform POST request (throws on error)
+   * Perform POST request (throws PhalaCloudError on error)
    */
   async post(request, body, options) {
-    return this.fetchInstance(request, {
-      ...options,
-      method: "POST",
-      body
-    });
+    try {
+      return await this.fetchInstance(request, {
+        ...options,
+        method: "POST",
+        body
+      });
+    } catch (error) {
+      const requestError = this.convertToRequestError(error);
+      const phalaCloudError = this.emitError(requestError);
+      throw phalaCloudError;
+    }
   }
   /**
-   * Perform PUT request (throws on error)
+   * Perform PUT request (throws PhalaCloudError on error)
    */
   async put(request, body, options) {
-    return this.fetchInstance(request, {
-      ...options,
-      method: "PUT",
-      body
-    });
+    try {
+      return await this.fetchInstance(request, {
+        ...options,
+        method: "PUT",
+        body
+      });
+    } catch (error) {
+      const requestError = this.convertToRequestError(error);
+      const phalaCloudError = this.emitError(requestError);
+      throw phalaCloudError;
+    }
   }
   /**
-   * Perform PATCH request (throws on error)
+   * Perform PATCH request (throws PhalaCloudError on error)
    */
   async patch(request, body, options) {
-    return this.fetchInstance(request, {
-      ...options,
-      method: "PATCH",
-      body
-    });
+    try {
+      return await this.fetchInstance(request, {
+        ...options,
+        method: "PATCH",
+        body
+      });
+    } catch (error) {
+      const requestError = this.convertToRequestError(error);
+      const phalaCloudError = this.emitError(requestError);
+      throw phalaCloudError;
+    }
   }
   /**
-   * Perform DELETE request (throws on error)
+   * Perform DELETE request (throws PhalaCloudError on error)
    */
   async delete(request, options) {
-    return this.fetchInstance(request, {
-      ...options,
-      method: "DELETE"
-    });
+    try {
+      return await this.fetchInstance(request, {
+        ...options,
+        method: "DELETE"
+      });
+    } catch (error) {
+      const requestError = this.convertToRequestError(error);
+      const phalaCloudError = this.emitError(requestError);
+      throw phalaCloudError;
+    }
   }
   // ===== Safe methods (return SafeResult) =====
+  /**
+   * Convert any error to RequestError
+   */
+  convertToRequestError(error) {
+    if (error && typeof error === "object" && "data" in error) {
+      return RequestError.fromFetchError(error);
+    }
+    if (error instanceof Error) {
+      return RequestError.fromError(error);
+    }
+    return new RequestError("Unknown error occurred", {
+      detail: "Unknown error occurred"
+    });
+  }
+  /**
+   * Broadcast error to event listeners (fire-and-forget)
+   * @param requestError - The request error to handle
+   * @returns PhalaCloudError instance to throw immediately
+   */
+  emitError(requestError) {
+    const phalaCloudError = parseApiError(requestError);
+    this.emitter.emit("error", phalaCloudError);
+    return phalaCloudError;
+  }
   /**
    * Safe wrapper for any request method (zod-style result)
+   * Returns PhalaCloudError (all errors extend this base class)
    */
   async safeRequest(fn) {
     try {
       const data = await fn();
       return { success: true, data };
     } catch (error) {
-      if (error && typeof error === "object" && "data" in error) {
-        const requestError2 = RequestError.fromFetchError(error);
-        return { success: false, error: requestError2 };
+      if (error instanceof PhalaCloudError) {
+        return { success: false, error };
       }
-      if (error instanceof Error) {
-        const requestError2 = RequestError.fromError(error);
-        return { success: false, error: requestError2 };
-      }
-      const requestError = new RequestError("Unknown error occurred", {
-        detail: "Unknown error occurred"
-      });
+      const requestError = this.convertToRequestError(error);
+      this.emitError(requestError);
       return { success: false, error: requestError };
     }
   }
@@ -571,7 +816,7 @@ function defineSimpleAction(schema, fn) {
         const data = await fn(client);
         return { success: true, data };
       } catch (error) {
-        if (error && typeof error === "object" && "isRequestError" in error) {
+        if (error && typeof error === "object" && "status" in error) {
           return { success: false, error };
         }
         if (error && typeof error === "object" && "issues" in error) {
@@ -628,7 +873,7 @@ function defineAction(schema, fn) {
         const data = await fn(client, params);
         return { success: true, data };
       } catch (error) {
-        if (error && typeof error === "object" && "isRequestError" in error) {
+        if (error && typeof error === "object" && "status" in error) {
           return { success: false, error };
         }
         if (error && typeof error === "object" && "issues" in error) {
@@ -1213,12 +1458,13 @@ var ProvisionCvmComposeFileUpdateRequestSchema = import_zod13.z.object({
 }).refine(
   (data) => !!(data.id || data.uuid || data.app_id || data.instance_id),
   "One of id, uuid, app_id, or instance_id must be provided"
-).transform((data) => ({
-  cvmId: data.id || data.uuid || data.app_id || data.instance_id,
-  request: data.app_compose,
-  update_env_vars: data.update_env_vars,
-  _raw: data
-}));
+).transform((data) => {
+  return {
+    cvmId: data.id || data.uuid || data.app_id || data.instance_id,
+    request: { ...data.app_compose, update_env_vars: data.update_env_vars },
+    _raw: data
+  };
+});
 var ProvisionCvmComposeFileUpdateResultSchema = import_zod13.z.object({
   app_id: import_zod13.z.string().nullable(),
   device_id: import_zod13.z.string().nullable(),
@@ -1640,23 +1886,6 @@ var import_accounts2 = require("viem/accounts");
 // src/utils/index.ts
 var import_encrypt_env_vars = require("@phala/dstack-sdk/encrypt-env-vars");
 
-// src/utils/get_error_message.ts
-function getErrorMessage(error) {
-  if (typeof error.detail === "string") {
-    return error.detail;
-  }
-  if (Array.isArray(error.detail)) {
-    if (error.detail.length > 0) {
-      return error.detail[0]?.msg || "Validation error";
-    }
-    return "Validation error";
-  }
-  if (typeof error.detail === "object" && error.detail !== null) {
-    return JSON.stringify(error.detail);
-  }
-  return "Unknown error occurred";
-}
-
 // src/utils/as-hex.ts
 var import_viem = require("viem");
 function asHex(value) {
@@ -2897,7 +3126,9 @@ var import_verify_env_encrypt_public_key = require("@phala/dstack-sdk/verify-env
 0 && (module.exports = {
   AddComposeHashSchema,
   ApiErrorSchema,
+  AuthError,
   AvailableNodesSchema,
+  BusinessError,
   CommitCvmComposeFileUpdateRequestSchema,
   CommitCvmComposeFileUpdateSchema,
   CommitCvmProvisionRequestSchema,
@@ -2939,6 +3170,7 @@ var import_verify_env_encrypt_public_key = require("@phala/dstack-sdk/verify-env
   NetworkError,
   PaginatedInstanceTypesSchema,
   PaginationMetadataSchema,
+  PhalaCloudError,
   ProvisionCvmComposeFileUpdateRequestSchema,
   ProvisionCvmComposeFileUpdateResultSchema,
   ProvisionCvmRequestSchema,
@@ -2946,13 +3178,16 @@ var import_verify_env_encrypt_public_key = require("@phala/dstack-sdk/verify-env
   RequestError,
   RestartCvmRequestSchema,
   SUPPORTED_CHAINS,
+  ServerError,
   ShutdownCvmRequestSchema,
   StartCvmRequestSchema,
   StopCvmRequestSchema,
   TransactionError,
+  UnknownError,
   UpdateCvmResourcesRequestSchema,
   UpdateCvmVisibilityRequestSchema,
   VMSchema,
+  ValidationError,
   VmInfoSchema,
   WalletError,
   WorkspaceResponseSchema,
@@ -2981,6 +3216,8 @@ var import_verify_env_encrypt_public_key = require("@phala/dstack-sdk/verify-env
   executeTransaction,
   executeTransactionWithRetry,
   extractNetworkClients,
+  formatErrorMessage,
+  formatValidationErrors,
   getAppEnvEncryptPubKey,
   getAvailableNodes,
   getComposeHash,
@@ -2996,9 +3233,11 @@ var import_verify_env_encrypt_public_key = require("@phala/dstack-sdk/verify-env
   getErrorMessage,
   getKmsInfo,
   getKmsList,
+  getValidationFields,
   getWorkspace,
   listInstanceTypes,
   listWorkspaces,
+  parseApiError,
   parseEnv,
   parseEnvVars,
   preprocessAppCompose,