@phala/cloud 0.2.0 → 0.2.1-beta.1

package/dist/index.mjs

@@ -12,8 +12,11 @@ var ApiErrorSchema = z.object({
       z.object({
         msg: z.string(),
         type: z.string().optional(),
-        ctx: z.record(z.unknown()).optional()
-      })
+        ctx: z.record(z.unknown()).optional(),
+        loc: z.array(z.union([z.string(), z.number()])).optional(),
+        input: z.unknown().optional()
+      }).passthrough()
+      // Allow additional fields
     ),
     z.record(z.unknown())
   ]).optional(),
@@ -116,6 +119,9 @@ var UnknownError = class extends PhalaCloudError {
   }
 };
 function extractFieldPath(loc) {
+  if (!loc || !Array.isArray(loc)) {
+    return "unknown";
+  }
   const filtered = loc.filter((part) => {
     if (typeof part === "string") {
       return !["body", "query", "path", "header"].includes(part);
@@ -131,12 +137,21 @@ function parseValidationErrors(detail) {
       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 errors = detail.map(
+    (item, index) => {
+      const field = extractFieldPath(item.loc);
+      let displayField = field;
+      if (field === "unknown" && item.type) {
+        displayField = item.type === "missing" ? "required field" : item.type;
+      }
+      return {
+        field: displayField,
+        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 };
@@ -179,13 +194,21 @@ function parseApiError(requestError) {
   const status = requestError.status ?? 0;
   const statusText = requestError.statusText ?? "Unknown Error";
   const detail = requestError.detail;
+  const structured = parseStructuredError(detail);
+  if (structured) {
+    return new ResourceError(structured.message, {
+      status,
+      statusText,
+      detail,
+      errorCode: structured.error_code,
+      structuredDetails: structured.details,
+      suggestions: structured.suggestions,
+      links: structured.links
+    });
+  }
   const errorType = categorizeErrorType(status);
   const message = extractPrimaryMessage(status, detail, requestError.message);
-  const commonData = {
-    status,
-    statusText,
-    detail
-  };
+  const commonData = { status, statusText, detail };
   if (errorType === "validation" && Array.isArray(detail)) {
     const { errors } = parseValidationErrors(detail);
     return new ValidationError(message, {
@@ -247,6 +270,67 @@ function getErrorMessage(error) {
   }
   return "Unknown error occurred";
 }
+var ResourceError = class extends BusinessError {
+  constructor(message, data) {
+    super(message, data);
+    this.isResourceError = true;
+    this.errorCode = data.errorCode;
+    this.structuredDetails = data.structuredDetails;
+    this.suggestions = data.suggestions;
+    this.links = data.links;
+  }
+};
+function parseStructuredError(detail) {
+  if (!detail || typeof detail !== "object") {
+    return null;
+  }
+  const obj = detail;
+  if (obj.error_code && typeof obj.error_code === "string" && obj.message && typeof obj.message === "string") {
+    return {
+      error_code: obj.error_code,
+      message: obj.message,
+      details: obj.details,
+      suggestions: obj.suggestions,
+      links: obj.links
+    };
+  }
+  return null;
+}
+function formatStructuredError(error, options) {
+  const { showErrorCode = true, showSuggestions = true, showLinks = true } = options ?? {};
+  const parts = [];
+  if (showErrorCode && error.errorCode) {
+    parts.push(`Error [${error.errorCode}]: ${error.message}`);
+  } else {
+    parts.push(error.message);
+  }
+  if (error.structuredDetails && error.structuredDetails.length > 0) {
+    parts.push("");
+    parts.push("Details:");
+    error.structuredDetails.forEach((d) => {
+      if (d.message) {
+        parts.push(`  - ${d.message}`);
+      } else if (d.field && d.value !== void 0) {
+        parts.push(`  - ${d.field}: ${d.value}`);
+      }
+    });
+  }
+  if (showSuggestions && error.suggestions && error.suggestions.length > 0) {
+    parts.push("");
+    parts.push("Suggestions:");
+    error.suggestions.forEach((s) => {
+      parts.push(`  - ${s}`);
+    });
+  }
+  if (showLinks && error.links && error.links.length > 0) {
+    parts.push("");
+    parts.push("Learn more:");
+    error.links.forEach((link) => {
+      parts.push(`  - ${link.label}: ${link.url}`);
+    });
+  }
+  return parts.join("\n");
+}
 
 // src/client.ts
 var SUPPORTED_API_VERSIONS = ["2025-05-31", "2025-10-28"];
@@ -804,10 +888,6 @@ var { action: getAvailableNodes, safeAction: safeGetAvailableNodes } = defineSim
 
 // src/actions/list-instance-types.ts
 import { z as z5 } from "zod";
-var ListInstanceTypesRequestSchema = z5.object({
-  page: z5.number().int().min(1).optional().default(1),
-  page_size: z5.number().int().min(1).max(1e3).optional().default(100)
-}).strict();
 var InstanceTypeSchema = z5.object({
   id: z5.string(),
   name: z5.string(),
@@ -816,22 +896,34 @@ var InstanceTypeSchema = z5.object({
   memory_mb: z5.number(),
   hourly_rate: z5.string(),
   requires_gpu: z5.boolean(),
-  public: z5.boolean(),
-  enabled: z5.boolean()
+  default_disk_size_gb: z5.number().default(20),
+  family: z5.string().nullable()
 }).passthrough();
-var PaginatedInstanceTypesSchema = z5.object({
+var FamilyGroupSchema = z5.object({
+  name: z5.string(),
+  items: z5.array(InstanceTypeSchema),
+  total: z5.number()
+}).strict();
+var AllFamiliesResponseSchema = z5.object({
+  result: z5.array(FamilyGroupSchema)
+}).strict();
+var FamilyInstanceTypesResponseSchema = z5.object({
   items: z5.array(InstanceTypeSchema),
   total: z5.number(),
-  page: z5.number(),
-  page_size: z5.number(),
-  pages: z5.number()
+  family: z5.string()
 }).strict();
-var { action: listInstanceTypes, safeAction: safeListInstanceTypes } = defineAction(PaginatedInstanceTypesSchema, async (client, request) => {
-  const validatedRequest = ListInstanceTypesRequestSchema.parse(request ?? {});
-  const queryParams = new URLSearchParams();
-  queryParams.append("page", validatedRequest.page.toString());
-  queryParams.append("page_size", validatedRequest.page_size.toString());
-  return await client.get(`/api/instance-types?${queryParams.toString()}`);
+var ListFamilyInstanceTypesRequestSchema = z5.object({
+  family: z5.string()
+}).strict();
+var { action: listAllInstanceTypeFamilies, safeAction: safeListAllInstanceTypeFamilies } = defineAction(
+  AllFamiliesResponseSchema,
+  async (client) => {
+    return await client.get("/instance-types");
+  }
+);
+var { action: listFamilyInstanceTypes, safeAction: safeListFamilyInstanceTypes } = defineAction(FamilyInstanceTypesResponseSchema, async (client, request) => {
+  const validated = ListFamilyInstanceTypesRequestSchema.parse(request);
+  return await client.get(`/instance-types/${validated.family}`);
 });
 
 // src/actions/workspaces/list_workspaces.ts
@@ -1051,6 +1143,7 @@ var ProvisionCvmSchema = z10.object({
   fmspc: z10.string().nullable().optional(),
   device_id: z10.string().nullable().optional(),
   os_image_hash: z10.string().nullable().optional(),
+  instance_type: z10.string().nullable().optional(),
   teepod_id: z10.number().nullable().optional(),
   // Will be transformed to node_id
   node_id: z10.number().nullable().optional(),
@@ -1064,19 +1157,24 @@ var ProvisionCvmSchema = z10.object({
 });
 var ProvisionCvmRequestSchema = z10.object({
   node_id: z10.number().optional(),
-  // recommended
+  // recommended - optional, system auto-selects if not specified
   teepod_id: z10.number().optional(),
   // deprecated, for compatibility
+  region: z10.string().optional(),
+  // optional - region filter for auto-selection
   name: z10.string(),
-  image: z10.string(),
-  vcpu: z10.number(),
-  memory: z10.number(),
-  disk_size: z10.number(),
+  instance_type: z10.string().default("tdx.small"),
+  // defaults to "tdx.small"
+  image: z10.string().optional(),
+  vcpu: z10.number().optional(),
+  memory: z10.number().optional(),
+  disk_size: z10.number().optional(),
   compose_file: z10.object({
     allowed_envs: z10.array(z10.string()).optional(),
     pre_launch_script: z10.string().optional(),
     docker_compose_file: z10.string().optional(),
-    name: z10.string().optional(),
+    name: z10.string().optional().default(""),
+    // optional with default empty string
     kms_enabled: z10.boolean().optional(),
     public_logs: z10.boolean().optional(),
     public_sysinfo: z10.boolean().optional(),
@@ -1086,8 +1184,11 @@ var ProvisionCvmRequestSchema = z10.object({
     // deprecated, for compatibility
   }),
   listed: z10.boolean().optional(),
-  instance_type: z10.string().nullable().optional(),
   kms_id: z10.string().optional(),
+  kms: z10.enum(["PHALA", "ETHEREUM", "BASE"]).optional(),
+  // KMS type selection (defaults to PHALA)
+  kms_contract: z10.string().optional(),
+  // KMS contract address for on-chain KMS
   env_keys: z10.array(z10.string()).optional()
 }).passthrough();
 function handleGatewayCompatibility(appCompose) {
@@ -1112,7 +1213,8 @@ function handleGatewayCompatibility(appCompose) {
   };
 }
 var { action: provisionCvm, safeAction: safeProvisionCvm } = defineAction(ProvisionCvmSchema, async (client, appCompose) => {
-  const body = handleGatewayCompatibility(appCompose);
+  const validated = ProvisionCvmRequestSchema.parse(appCompose);
+  const body = handleGatewayCompatibility(validated);
   let requestBody = { ...body };
   if (typeof body.node_id === "number") {
     requestBody = { ...body, teepod_id: body.node_id };
@@ -1156,7 +1258,7 @@ var CommitCvmProvisionSchema = z11.object({
 var CommitCvmProvisionRequestSchema = z11.object({
   encrypted_env: z11.string().optional().nullable(),
   app_id: z11.string(),
-  compose_hash: z11.string().optional(),
+  compose_hash: z11.string(),
   kms_id: z11.string().optional(),
   contract_address: z11.string().optional(),
   deployer_address: z11.string().optional(),
@@ -1699,8 +1801,10 @@ function createClient2(config = {}) {
     safeGetCurrentUser,
     getAvailableNodes,
     safeGetAvailableNodes,
-    listInstanceTypes,
-    safeListInstanceTypes,
+    listAllInstanceTypeFamilies,
+    safeListAllInstanceTypeFamilies,
+    listFamilyInstanceTypes,
+    safeListFamilyInstanceTypes,
     listWorkspaces,
     safeListWorkspaces,
     getWorkspace,
@@ -3220,6 +3324,7 @@ import { getComposeHash as getComposeHash2 } from "@phala/dstack-sdk/get-compose
 import { verifyEnvEncryptPublicKey } from "@phala/dstack-sdk/verify-env-encrypt-public-key";
 export {
   AddComposeHashSchema,
+  AllFamiliesResponseSchema,
   ApiErrorSchema,
   AuthError,
   AvailableNodesSchema,
@@ -3244,6 +3349,8 @@ export {
   DeleteCvmRequestSchema,
   DeployAppAuthRequestSchema,
   DeployAppAuthSchema,
+  FamilyGroupSchema,
+  FamilyInstanceTypesResponseSchema,
   GetAppEnvEncryptPubKeyRequestSchema,
   GetAppEnvEncryptPubKeySchema,
   GetAvailableOSImagesRequestSchema,
@@ -3263,7 +3370,7 @@ export {
   GetKmsListSchema,
   InstanceTypeSchema,
   KmsInfoSchema,
-  ListInstanceTypesRequestSchema,
+  ListFamilyInstanceTypesRequestSchema,
   ListWorkspacesSchema,
   ManagedUserSchema,
   MaxRetriesExceededError,
@@ -3271,7 +3378,6 @@ export {
   NextAppIdsRequestSchema,
   NextAppIdsSchema,
   OSImageVariantSchema,
-  PaginatedInstanceTypesSchema,
   PaginationMetadataSchema,
   PhalaCloudError,
   ProvisionCvmComposeFileUpdateRequestSchema,
@@ -3279,6 +3385,7 @@ export {
   ProvisionCvmRequestSchema,
   ProvisionCvmSchema,
   RequestError,
+  ResourceError,
   RestartCvmRequestSchema,
   SUPPORTED_CHAINS,
   ServerError,
@@ -3323,6 +3430,7 @@ export {
   executeTransactionWithRetry,
   extractNetworkClients,
   formatErrorMessage,
+  formatStructuredError,
   formatValidationErrors,
   getAppEnvEncryptPubKey,
   getAvailableNodes,
@@ -3343,7 +3451,8 @@ export {
   getKmsList,
   getValidationFields,
   getWorkspace,
-  listInstanceTypes,
+  listAllInstanceTypeFamilies,
+  listFamilyInstanceTypes,
   listWorkspaces,
   nextAppIds,
   parseApiError,
@@ -3375,7 +3484,8 @@ export {
   safeGetKmsInfo,
   safeGetKmsList,
   safeGetWorkspace,
-  safeListInstanceTypes,
+  safeListAllInstanceTypeFamilies,
+  safeListFamilyInstanceTypes,
   safeListWorkspaces,
   safeNextAppIds,
   safeProvisionCvm,

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.2.0",
+  "version": "0.2.1-beta.1",
   "description": "TypeScript SDK for Phala Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",