@phala/cloud 0.1.1-beta.3 → 0.1.2

package/dist/index.mjs

@@ -1,8 +1,9 @@
 // src/client.ts
 import { ofetch } from "ofetch";
 import debug from "debug";
+import mitt from "mitt";
 
-// src/types/client.ts
+// src/utils/errors.ts
 import { z } from "zod";
 var ApiErrorSchema = z.object({
   detail: z.union([
@@ -15,21 +16,34 @@ var ApiErrorSchema = z.object({
       })
     ),
     z.record(z.unknown())
-  ]),
+  ]).optional(),
   type: z.string().optional(),
   code: 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;
   }
@@ -70,9 +84,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 = debug("phala::api-client");
 function formatHeaders(headers) {
   return Object.entries(headers).map(([key, value]) => `    -H "${key}: ${value}"`).join("\n");
@@ -98,18 +275,14 @@ function formatResponse(status, statusText, headers, body) {
 }
 var Client = class {
   constructor(config = {}) {
+    this.emitter = mitt();
     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,
@@ -192,75 +365,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 Error) {
-        const requestError2 = RequestError.fromError(error);
-        return { success: false, error: requestError2 };
+      if (error instanceof PhalaCloudError) {
+        return { success: false, error };
       }
-      const requestError = new RequestError("Unknown error occurred", {
-        detail: "Unknown error occurred"
-      });
+      const requestError = this.convertToRequestError(error);
+      this.emitError(requestError);
       return { success: false, error: requestError };
     }
   }
@@ -383,7 +618,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) {
@@ -440,7 +675,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) {
@@ -855,18 +1090,6 @@ var ProvisionCvmRequestSchema = z10.object({
   kms_id: z10.string().optional(),
   env_keys: z10.array(z10.string()).optional()
 }).passthrough();
-function autofillComposeFileName(appCompose) {
-  if (appCompose.compose_file && !appCompose.compose_file.name) {
-    return {
-      ...appCompose,
-      compose_file: {
-        ...appCompose.compose_file,
-        name: appCompose.name
-      }
-    };
-  }
-  return appCompose;
-}
 function handleGatewayCompatibility(appCompose) {
   if (!appCompose.compose_file) {
     return appCompose;
@@ -889,7 +1112,7 @@ function handleGatewayCompatibility(appCompose) {
   };
 }
 var { action: provisionCvm, safeAction: safeProvisionCvm } = defineAction(ProvisionCvmSchema, async (client, appCompose) => {
-  const body = handleGatewayCompatibility(autofillComposeFileName(appCompose));
+  const body = handleGatewayCompatibility(appCompose);
   let requestBody = { ...body };
   if (typeof body.node_id === "number") {
     requestBody = { ...body, teepod_id: body.node_id };
@@ -960,9 +1183,61 @@ var LooseAppComposeSchema = z12.object({
   salt: z12.string().optional().nullable()
 }).passthrough();
 
+// src/utils/get_compose_hash.ts
+import crypto from "crypto";
+function sortObject(obj) {
+  if (obj === void 0 || obj === null) {
+    return obj;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(sortObject);
+  } else if (obj && typeof obj === "object" && obj.constructor === Object) {
+    return Object.keys(obj).sort().reduce((result, key) => {
+      const value = obj[key];
+      result[key] = sortObject(value);
+      return result;
+    }, {});
+  }
+  return obj;
+}
+function preprocessAppCompose(dic) {
+  const obj = { ...dic };
+  if (obj.runner === "bash" && "docker_compose_file" in obj) {
+    delete obj.docker_compose_file;
+  } else if (obj.runner === "docker-compose" && "bash_script" in obj) {
+    delete obj.bash_script;
+  }
+  if ("pre_launch_script" in obj && !obj.pre_launch_script) {
+    delete obj.pre_launch_script;
+  }
+  return obj;
+}
+function dumpAppCompose(dic) {
+  const ordered = sortObject(dic);
+  let json = JSON.stringify(ordered, null, 4);
+  json = json.replace(/": /g, '":');
+  return json;
+}
+function getComposeHash(app_compose) {
+  const preprocessed = preprocessAppCompose(app_compose);
+  const manifest_str = dumpAppCompose(preprocessed);
+  return crypto.createHash("sha256").update(manifest_str, "utf8").digest("hex");
+}
+function withComposeMethods(compose) {
+  const appCompose = compose;
+  return {
+    ...compose,
+    getHash: () => getComposeHash(appCompose),
+    toString: () => dumpAppCompose(preprocessAppCompose(appCompose))
+  };
+}
+
 // src/actions/cvms/get_cvm_compose_file.ts
+var GetCvmComposeFileResultSchema = LooseAppComposeSchema.transform(
+  (data) => withComposeMethods(data)
+);
 var GetCvmComposeFileRequestSchema = CvmIdSchema;
-var { action: getCvmComposeFile, safeAction: safeGetCvmComposeFile } = defineAction(LooseAppComposeSchema, async (client, request) => {
+var { action: getCvmComposeFile, safeAction: safeGetCvmComposeFile } = defineAction(GetCvmComposeFileResultSchema, async (client, request) => {
   const { cvmId } = GetCvmComposeFileRequestSchema.parse(request);
   return await client.get(`/cvms/${cvmId}/compose_file`);
 });
@@ -985,12 +1260,13 @@ var ProvisionCvmComposeFileUpdateRequestSchema = z13.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 = z13.object({
   app_id: z13.string().nullable(),
   device_id: z13.string().nullable(),
@@ -1418,23 +1694,6 @@ import { privateKeyToAccount as privateKeyToAccount2 } from "viem/accounts";
 // src/utils/index.ts
 import { encryptEnvVars } from "@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
 import { isHex } from "viem";
 function asHex(value) {
@@ -2687,7 +2946,9 @@ import { verifyEnvEncryptPublicKey } from "@phala/dstack-sdk/verify-env-encrypt-
 export {
   AddComposeHashSchema,
   ApiErrorSchema,
+  AuthError,
   AvailableNodesSchema,
+  BusinessError,
   CommitCvmComposeFileUpdateRequestSchema,
   CommitCvmComposeFileUpdateSchema,
   CommitCvmProvisionRequestSchema,
@@ -2729,6 +2990,7 @@ export {
   NetworkError,
   PaginatedInstanceTypesSchema,
   PaginationMetadataSchema,
+  PhalaCloudError,
   ProvisionCvmComposeFileUpdateRequestSchema,
   ProvisionCvmComposeFileUpdateResultSchema,
   ProvisionCvmRequestSchema,
@@ -2736,13 +2998,16 @@ export {
   RequestError,
   RestartCvmRequestSchema,
   SUPPORTED_CHAINS,
+  ServerError,
   ShutdownCvmRequestSchema,
   StartCvmRequestSchema,
   StopCvmRequestSchema,
   TransactionError,
+  UnknownError,
   UpdateCvmResourcesRequestSchema,
   UpdateCvmVisibilityRequestSchema,
   VMSchema,
+  ValidationError,
   VmInfoSchema,
   WalletError,
   WorkspaceResponseSchema,
@@ -2764,12 +3029,15 @@ export {
   defineSimpleAction,
   deleteCvm,
   deployAppAuth,
+  dumpAppCompose,
   encryptEnvVars2 as encryptEnvVars,
   estimateTransactionGas,
   executeBatchTransactions,
   executeTransaction,
   executeTransactionWithRetry,
   extractNetworkClients,
+  formatErrorMessage,
+  formatValidationErrors,
   getAppEnvEncryptPubKey,
   getAvailableNodes,
   getComposeHash2 as getComposeHash,
@@ -2785,11 +3053,14 @@ export {
   getErrorMessage,
   getKmsInfo,
   getKmsList,
+  getValidationFields,
   getWorkspace,
   listInstanceTypes,
   listWorkspaces,
+  parseApiError,
   parseEnv,
   parseEnvVars,
+  preprocessAppCompose,
   provisionCvm,
   provisionCvmComposeFileUpdate,
   refineCvmId,
@@ -2825,6 +3096,7 @@ export {
   safeUpdateCvmVisibility,
   safeValidateActionParameters,
   shutdownCvm,
+  sortObject,
   startCvm,
   stopCvm,
   switchToNetwork,
@@ -2833,5 +3105,6 @@ export {
   validateActionParameters,
   validateNetworkPrerequisites,
   verifyEnvEncryptPublicKey,
-  waitForTransactionReceipt
+  waitForTransactionReceipt,
+  withComposeMethods
 };