@phala/cloud 0.1.2 → 0.2.1-beta.1

package/dist/utils/define-action.d.ts

@@ -10,22 +10,22 @@ import { type Client, type SafeResult } from "../client";
  */
 export declare function defineSimpleAction<TSchema extends z.ZodTypeAny, TReturnOverride = never>(schema: TSchema, fn: (client: Client) => Promise<unknown>): {
     action: {
-        (client: Client): Promise<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>;
-        <T extends z.ZodTypeAny>(client: Client, parameters: {
-            schema: T;
-        }): Promise<z.infer<T>>;
         (client: Client, parameters: {
             schema: false;
         }): Promise<unknown>;
-    };
-    safeAction: {
-        (client: Client): Promise<SafeResult<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>>;
         <T extends z.ZodTypeAny>(client: Client, parameters: {
             schema: T;
-        }): Promise<SafeResult<z.infer<T>>>;
+        }): Promise<z.infer<T>>;
+        (client: Client): Promise<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>;
+    };
+    safeAction: {
         (client: Client, parameters: {
             schema: false;
         }): Promise<SafeResult<unknown>>;
+        <T extends z.ZodTypeAny>(client: Client, parameters: {
+            schema: T;
+        }): Promise<SafeResult<z.infer<T>>>;
+        (client: Client): Promise<SafeResult<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>>;
     };
 };
 /**

package/dist/utils/errors.d.ts

@@ -8,33 +8,43 @@ export declare const ApiErrorSchema: 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>]>>;
+        loc: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">>;
+        input: z.ZodOptional<z.ZodUnknown>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        msg: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        loc: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">>;
+        input: z.ZodOptional<z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        msg: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        loc: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">>;
+        input: z.ZodOptional<z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">>, "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;
+    detail?: string | Record<string, unknown> | z.objectOutputType<{
+        msg: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        loc: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">>;
+        input: z.ZodOptional<z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">[] | undefined;
 }, {
     code?: string | undefined;
     type?: string | undefined;
-    detail?: string | Record<string, unknown> | {
-        msg: string;
-        type?: string | undefined;
-        ctx?: Record<string, unknown> | undefined;
-    }[] | undefined;
+    detail?: string | Record<string, unknown> | z.objectInputType<{
+        msg: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        ctx: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        loc: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber]>, "many">>;
+        input: z.ZodOptional<z.ZodUnknown>;
+    }, z.ZodTypeAny, "passthrough">[] | undefined;
 }>;
 export type ApiError = z.infer<typeof ApiErrorSchema>;
 /**
@@ -94,6 +104,9 @@ export declare class RequestError extends PhalaCloudError implements ApiError {
             msg: string;
             type?: string;
             ctx?: Record<string, unknown>;
+            loc?: (string | number)[];
+            input?: unknown;
+            [key: string]: unknown;
         }>;
         code?: string | undefined;
         type?: string | undefined;
@@ -122,6 +135,9 @@ export declare class ValidationError extends PhalaCloudError {
             msg: string;
             type?: string;
             ctx?: Record<string, unknown>;
+            loc?: (string | number)[];
+            input?: unknown;
+            [key: string]: unknown;
         }>;
         validationErrors: ValidationErrorItem[];
     });
@@ -162,6 +178,7 @@ export declare class UnknownError extends PhalaCloudError {
  * Parse RequestError into PhalaCloudError instance
  *
  * Returns the appropriate error subclass based on status code:
+ * - New structured errors (with error_code) → ResourceError
  * - 422 → ValidationError (with validationErrors array)
  * - 401, 403 → AuthError
  * - 400, 409, etc. → BusinessError
@@ -176,7 +193,13 @@ export declare class UnknownError extends PhalaCloudError {
  * try {
  *   await client.post('/cvms', data);
  * } catch (error) {
- *   if (error instanceof ValidationError) {
+ *   if (error instanceof ResourceError) {
+ *     // New structured error with error code
+ *     console.error(`Error [${error.errorCode}]: ${error.message}`);
+ *     if (error.suggestions) {
+ *       error.suggestions.forEach(s => console.log(s));
+ *     }
+ *   } else if (error instanceof ValidationError) {
  *     // TypeScript knows error.validationErrors exists
  *     error.validationErrors.forEach(e => {
  *       console.error(`${e.field}: ${e.message}`);
@@ -259,3 +282,97 @@ export declare function formatErrorMessage(error: PhalaCloudError, options?: {
  * @returns Error message string
  */
 export declare function getErrorMessage(error: ApiError): string;
+/**
+ * Structured error detail from new error format (ERR-xxxx codes)
+ */
+export interface StructuredErrorDetail {
+    field?: string;
+    value?: unknown;
+    message?: string;
+}
+/**
+ * Error link from structured error response
+ */
+export interface ErrorLink {
+    url: string;
+    label: string;
+}
+/**
+ * New structured error response format with unique error codes
+ */
+export interface StructuredErrorResponse {
+    error_code: string;
+    message: string;
+    details?: StructuredErrorDetail[];
+    suggestions?: string[];
+    links?: ErrorLink[];
+}
+/**
+ * Resource provisioning error with structured details
+ * Extends BusinessError to handle new error format from backend
+ *
+ * Use instanceof to check: if (error instanceof ResourceError) { ... }
+ * Or use property: if (error.isResourceError) { ... }
+ */
+export declare class ResourceError extends BusinessError {
+    readonly isResourceError: true;
+    readonly errorCode?: string;
+    readonly structuredDetails?: StructuredErrorDetail[];
+    readonly suggestions?: string[];
+    readonly links?: ErrorLink[];
+    constructor(message: string, data: {
+        status: number;
+        statusText: string;
+        detail?: string | Record<string, unknown> | Array<{
+            msg: string;
+            type?: string;
+            ctx?: Record<string, unknown>;
+            loc?: (string | number)[];
+            input?: unknown;
+            [key: string]: unknown;
+        }>;
+        errorCode?: string;
+        structuredDetails?: StructuredErrorDetail[];
+        suggestions?: string[];
+        links?: ErrorLink[];
+    });
+}
+/**
+ * Format structured error for display
+ *
+ * @param error - Resource error with structured details
+ * @param options - Formatting options
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await client.provisionCvm(payload);
+ * } catch (error) {
+ *   if (error instanceof ResourceError) {
+ *     console.error(formatStructuredError(error));
+ *   }
+ * }
+ * // Output:
+ * // Error [ERR-01-001]: The requested instance type does not exist
+ * //
+ * // Details:
+ * //   - Instance type 'invalid' is not recognized
+ * //
+ * // Suggestions:
+ * //   - Use a valid instance type: tdx.small, tdx.medium, or tdx.large
+ * //   - Alternatively, specify CPU and memory requirements manually
+ * //
+ * // Learn more:
+ * //   - View available instance types: https://cloud.phala.network/instances
+ * //   - Contact support: https://cloud.phala.network/support
+ * ```
+ */
+export declare function formatStructuredError(error: ResourceError, options?: {
+    /** Show error code in output (default: true) */
+    showErrorCode?: boolean;
+    /** Show suggestions (default: true) */
+    showSuggestions?: boolean;
+    /** Show links (default: true) */
+    showLinks?: boolean;
+}): string;

package/dist/utils/index.d.ts

@@ -2,7 +2,7 @@ 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 { 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 { parseApiError, PhalaCloudError, RequestError, ValidationError, AuthError, BusinessError, ServerError, UnknownError, ResourceError, formatValidationErrors, formatErrorMessage, formatStructuredError, getErrorMessage, getValidationFields, type ValidationErrorItem, type StructuredErrorDetail, type ErrorLink, type StructuredErrorResponse, 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.2",
+  "version": "0.2.1-beta.1",
   "description": "TypeScript SDK for Phala Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",