@phala/cloud 0.2.1-beta.3 → 0.2.1

package/dist/types/index.d.ts

@@ -1,6 +1,12 @@
 export * from "./client";
 export * from "./kms_info";
 export * from "./cvm_info";
+export * from "./cvm_info_v20251028";
+export * from "./cvm_info_v20260121";
 export * from "./cvm_id";
 export * from "./common";
 export * from "./supported_chains";
+export * from "./version-mappings";
+export * from "./app_info_v20251028";
+export * from "./app_info_v20260121";
+export * from "./app_revision";

package/dist/types/version-mappings.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Version-specific type mappings for API responses
+ *
+ * This file contains conditional types that map API versions to their
+ * corresponding response types, enabling TypeScript to infer the correct
+ * types based on the client's API version.
+ */
+import type { CurrentUserV20260121 } from "../credentials/current_user_v20260121";
+import type { CurrentUserV20251028 } from "../credentials/current_user_v20251028";
+import type { DstackAppListResponseV20251028, DstackAppWithCvmResponseV20251028 } from "./app_info_v20251028";
+import type { DstackAppListResponseV20260121, DstackAppWithCvmResponseV20260121 } from "./app_info_v20260121";
+import type { ApiVersion } from "./client";
+import type { CvmDetailV20251028, CvmInfoV20251028, PaginatedCvmInfosV20251028 } from "./cvm_info_v20251028";
+import type { CvmInfoDetailV20260121, CvmInfoV20260121, PaginatedCvmInfosV20260121 } from "./cvm_info_v20260121";
+/**
+ * Maps API version to the auth/me response type
+ */
+export type GetCurrentUserResponse<V extends ApiVersion> = V extends "2026-01-21" ? CurrentUserV20260121 : V extends "2025-10-28" ? CurrentUserV20251028 : CurrentUserV20260121;
+/**
+ * Maps API version to the paginated CVM list response type
+ */
+export type GetCvmListResponse<V extends ApiVersion> = V extends "2026-01-21" ? PaginatedCvmInfosV20260121 : V extends "2025-10-28" ? PaginatedCvmInfosV20251028 : PaginatedCvmInfosV20260121;
+/**
+ * Maps API version to the CVM info detail response type
+ */
+export type GetCvmInfoResponse<V extends ApiVersion> = V extends "2026-01-21" ? CvmInfoDetailV20260121 : V extends "2025-10-28" ? CvmDetailV20251028 : CvmInfoDetailV20260121;
+/**
+ * Maps API version to the app list response type
+ */
+export type GetAppListResponse<V extends ApiVersion> = V extends "2026-01-21" ? DstackAppListResponseV20260121 : V extends "2025-10-28" ? DstackAppListResponseV20251028 : DstackAppListResponseV20260121;
+/**
+ * Maps API version to the app info response type
+ */
+export type GetAppInfoResponse<V extends ApiVersion> = V extends "2026-01-21" ? DstackAppWithCvmResponseV20260121 : V extends "2025-10-28" ? DstackAppWithCvmResponseV20251028 : DstackAppWithCvmResponseV20260121;
+/**
+ * Maps API version to the app CVMs list response type
+ */
+export type GetAppCvmsResponse<V extends ApiVersion> = V extends "2026-01-21" ? CvmInfoV20260121[] : V extends "2025-10-28" ? CvmInfoV20251028[] : CvmInfoV20260121[];

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

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type Client, type SafeResult } from "../client";
+import type { ApiVersion } from "../types/client";
 /**
  * Defines an action that takes no additional parameters (only client + optional schema)
  *
@@ -8,51 +9,51 @@ import { type Client, type SafeResult } from "../client";
  * - action(client, { schema: CustomSchema }) → returns z.infer<CustomSchema>
  * - action(client, { schema: false }) → returns unknown
  */
-export declare function defineSimpleAction<TSchema extends z.ZodTypeAny, TReturnOverride = never>(schema: TSchema, fn: (client: Client) => Promise<unknown>): {
+export declare function defineSimpleAction<TSchema extends z.ZodTypeAny, TReturnOverride = never>(schema: TSchema, fn: (client: Client<ApiVersion>) => Promise<unknown>): {
     action: {
-        (client: Client, parameters: {
+        (client: Client<ApiVersion>, parameters: {
             schema: false;
         }): Promise<unknown>;
-        <T extends z.ZodTypeAny>(client: Client, parameters: {
+        <T extends z.ZodTypeAny>(client: Client<ApiVersion>, parameters: {
             schema: T;
         }): Promise<z.infer<T>>;
-        (client: Client): Promise<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>;
+        (client: Client<ApiVersion>): Promise<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>;
     };
     safeAction: {
-        (client: Client, parameters: {
+        (client: Client<ApiVersion>, parameters: {
             schema: false;
         }): Promise<SafeResult<unknown>>;
-        <T extends z.ZodTypeAny>(client: Client, parameters: {
+        <T extends z.ZodTypeAny>(client: Client<ApiVersion>, parameters: {
             schema: T;
         }): Promise<SafeResult<z.infer<T>>>;
-        (client: Client): Promise<SafeResult<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>>;
+        (client: Client<ApiVersion>): Promise<SafeResult<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>>;
     };
 };
 /**
  * Defines an action with parameters
  */
-export declare function defineAction<TParams, TSchema extends z.ZodTypeAny, TReturnOverride = never>(schema: TSchema, fn: (client: Client, params: TParams) => Promise<unknown>): {
+export declare function defineAction<TParams, TSchema extends z.ZodTypeAny, TReturnOverride = never>(schema: TSchema, fn: (client: Client<ApiVersion>, params: TParams) => Promise<unknown>): {
     action: {
-        (client: Client, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams] : [params: TParams]): Promise<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>;
-        <T extends z.ZodTypeAny>(client: Client, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams, parameters?: {
+        (client: Client<ApiVersion>, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams] : [params: TParams]): Promise<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>;
+        <T extends z.ZodTypeAny>(client: Client<ApiVersion>, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams, parameters?: {
             schema: T;
         }] : [params: TParams, parameters: {
             schema: T;
         }]): Promise<z.infer<T>>;
-        (client: Client, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams, parameters?: {
+        (client: Client<ApiVersion>, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams, parameters?: {
             schema: false;
         }] : [params: TParams, parameters: {
             schema: false;
         }]): Promise<unknown>;
     };
     safeAction: {
-        (client: Client, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams] : [params: TParams]): Promise<SafeResult<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>>;
-        <T extends z.ZodTypeAny>(client: Client, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams, parameters?: {
+        (client: Client<ApiVersion>, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams] : [params: TParams]): Promise<SafeResult<[TReturnOverride] extends [never] ? z.TypeOf<TSchema> : TReturnOverride>>;
+        <T extends z.ZodTypeAny>(client: Client<ApiVersion>, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams, parameters?: {
             schema: T;
         }] : [params: TParams, parameters: {
             schema: T;
         }]): Promise<SafeResult<z.infer<T>>>;
-        (client: Client, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams, parameters?: {
+        (client: Client<ApiVersion>, ...args: (undefined extends TParams ? true : false) extends true ? [params?: TParams, parameters?: {
             schema: false;
         }] : [params: TParams, parameters: {
             schema: false;

package/dist/utils/errors.d.ts

@@ -364,8 +364,8 @@ export declare class ResourceError extends BusinessError {
  * //   - 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
+ * //   - View available instance types: https://cloud.phala.com/instances
+ * //   - Contact support: https://cloud.phala.com/support
  * ```
  */
 export declare function formatStructuredError(error: ResourceError, options?: {

package/dist/utils/hostname.d.ts

@@ -0,0 +1,77 @@
+/**
+ * CVM Hostname/Name utilities
+ *
+ * RFC 1123 Hostname Format with Phala Cloud requirements:
+ * - 5-63 characters (min 5 for generated names like "a-xyz")
+ * - Must start with letter (a-z, A-Z)
+ * - Can contain letters, numbers, and hyphens
+ * - Cannot end with hyphen
+ * - Cannot have consecutive hyphens
+ * - Uppercase letters are auto-converted to lowercase by convertToHostname()
+ *
+ * Pattern: ^[a-zA-Z](?!.*--)([a-zA-Z0-9-]*[a-zA-Z0-9])?$
+ * Note: Validator accepts both cases; conversion to lowercase happens in convertToHostname()
+ */
+/**
+ * Validate hostname format (RFC 1123 with letter-first requirement)
+ *
+ * Accepts both uppercase and lowercase letters. Actual names should be normalized
+ * using convertToHostname() before storing/display.
+ *
+ * @param name - Name to validate
+ * @returns true if valid hostname format (5-63 chars, starts with letter, no consecutive hyphens)
+ *
+ * @example
+ * isValidHostname("my-app")          // true
+ * isValidHostname("MyApp")           // true (validator accepts uppercase)
+ * isValidHostname("123app")          // false (starts with number)
+ * isValidHostname("-app")            // false (starts with hyphen)
+ * isValidHostname("app-")            // false (ends with hyphen)
+ * isValidHostname("app--test")       // false (consecutive hyphens not allowed)
+ */
+export declare function isValidHostname(name: string): boolean;
+/**
+ * Convert any string to hostname-compliant format (RFC 1123)
+ *
+ * Handles multiple naming styles:
+ * - camelCase: MyApp → my-app
+ * - snake_case: my_app → my-app
+ * - i18n chars: 我的应用 → fallback (dstack-app-{timestamp}-{random})
+ * - special chars: my app!@# → my-app
+ *
+ * @param input - Input string to convert
+ * @returns Valid hostname format (5-63 chars, RFC 1123)
+ *
+ * @example
+ * convertToHostname("MyAwesomeProject")     // "my-awesome-project"
+ * convertToHostname("my_python_project")    // "my-python-project"
+ * convertToHostname("我的应用")              // "dstack-app-{timestamp}-{random}"
+ * convertToHostname("test")                  // "dstack-app-test"
+ */
+export declare function convertToHostname(input: string): string;
+/**
+ * Generate a random hostname with fallback pattern
+ * Used when input cannot be reasonably converted
+ *
+ * Pattern: dstack-app-{base36-timestamp}-{random}
+ * Example: dstack-app-1y8a2b3c-4d5e
+ *
+ * @returns Valid random hostname
+ */
+export declare function generateFallbackHostname(): string;
+/**
+ * Generate a default CVM name with prefix and random suffix
+ *
+ * Pattern: {prefix}-{random5chars}
+ * - Always valid RFC 1123 format
+ * - Easy to recognize (prefix + random)
+ * - Consistent across platforms
+ *
+ * @param prefix - Descriptive prefix (default: "dstack-app")
+ * @returns Valid CVM name
+ *
+ * @example
+ * generateDefaultCvmName()                // "dstack-app-a1b2c"
+ * generateDefaultCvmName("my-project")    // "my-project-x9y8z"
+ */
+export declare function generateDefaultCvmName(prefix?: string): string;

package/dist/utils/index.d.ts

@@ -2,6 +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 { isValidHostname, convertToHostname, generateFallbackHostname, generateDefaultCvmName, } from "./hostname";
 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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phala/cloud",
-  "version": "0.2.1-beta.3",
+  "version": "0.2.1",
   "description": "TypeScript SDK for Phala Cloud API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -50,7 +50,7 @@
     "@types/debug": "^4.1.12",
     "@types/node": "^20.10.0",
     "dotenv": "^16.5.0",
-    "tsup": "^8.0.0",
+    "tsup": "^8.5.1",
     "typescript": "^5.3.0",
     "vitest": "^1.0.0"
   },