@phala/cloud 0.1.1 → 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 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 };
     }
   }
@@ -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) {
@@ -1025,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(),
@@ -1458,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) {
@@ -2727,7 +2946,9 @@ import { verifyEnvEncryptPublicKey } from "@phala/dstack-sdk/verify-env-encrypt-
 export {
   AddComposeHashSchema,
   ApiErrorSchema,
+  AuthError,
   AvailableNodesSchema,
+  BusinessError,
   CommitCvmComposeFileUpdateRequestSchema,
   CommitCvmComposeFileUpdateSchema,
   CommitCvmProvisionRequestSchema,
@@ -2769,6 +2990,7 @@ export {
   NetworkError,
   PaginatedInstanceTypesSchema,
   PaginationMetadataSchema,
+  PhalaCloudError,
   ProvisionCvmComposeFileUpdateRequestSchema,
   ProvisionCvmComposeFileUpdateResultSchema,
   ProvisionCvmRequestSchema,
@@ -2776,13 +2998,16 @@ export {
   RequestError,
   RestartCvmRequestSchema,
   SUPPORTED_CHAINS,
+  ServerError,
   ShutdownCvmRequestSchema,
   StartCvmRequestSchema,
   StopCvmRequestSchema,
   TransactionError,
+  UnknownError,
   UpdateCvmResourcesRequestSchema,
   UpdateCvmVisibilityRequestSchema,
   VMSchema,
+  ValidationError,
   VmInfoSchema,
   WalletError,
   WorkspaceResponseSchema,
@@ -2811,6 +3036,8 @@ export {
   executeTransaction,
   executeTransactionWithRetry,
   extractNetworkClients,
+  formatErrorMessage,
+  formatValidationErrors,
   getAppEnvEncryptPubKey,
   getAvailableNodes,
   getComposeHash2 as getComposeHash,
@@ -2826,9 +3053,11 @@ export {
   getErrorMessage,
   getKmsInfo,
   getKmsList,
+  getValidationFields,
   getWorkspace,
   listInstanceTypes,
   listWorkspaces,
+  parseApiError,
   parseEnv,
   parseEnvVars,
   preprocessAppCompose,

package/dist/types/client.d.ts

@@ -1,46 +1,10 @@
 import { z } from "zod";
-import type { FetchError, FetchOptions, FetchRequest } from "ofetch";
-/**
- * API Error Response Schema
- */
-export declare const ApiErrorSchema: z.ZodObject<{
-    detail: 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, {
-    detail: string | Record<string, unknown> | {
-        msg: string;
-        type?: string | undefined;
-        ctx?: Record<string, unknown> | undefined;
-    }[];
-    code?: string | undefined;
-    type?: string | undefined;
-}, {
-    detail: string | Record<string, unknown> | {
-        msg: string;
-        type?: string | undefined;
-        ctx?: Record<string, unknown> | undefined;
-    }[];
-    code?: string | undefined;
-    type?: string | undefined;
-}>;
-export type ApiError = z.infer<typeof ApiErrorSchema>;
+import type { FetchOptions, FetchRequest } from "ofetch";
+import type { PhalaCloudError } from "../utils/errors";
 /**
  * Enhanced error type that includes both HTTP and validation errors
  */
-export type SafeError = RequestError | z.ZodError;
+export type SafeError = PhalaCloudError | z.ZodError;
 /**
  * Result type for safe operations, similar to zod's SafeParseResult
  * Enhanced to handle both HTTP and validation errors by default
@@ -54,49 +18,6 @@ export type SafeResult<T, E = SafeError> = {
     data?: never;
     error: E;
 };
-/**
- * Base error class for HTTP requests
- * Compatible with ApiError interface for Result type compatibility
- */
-export declare class RequestError extends Error implements ApiError {
-    readonly name = "RequestError";
-    readonly isRequestError: true;
-    readonly status?: number | undefined;
-    readonly statusText?: string | undefined;
-    readonly data?: unknown;
-    readonly request?: FetchRequest | undefined;
-    readonly response?: Response | undefined;
-    readonly detail: string | Record<string, unknown> | Array<{
-        msg: string;
-        type?: string;
-        ctx?: Record<string, unknown>;
-    }>;
-    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;
-}
 /**
  * Client configuration - extends FetchOptions and adds predefined API-specific options
  *