@lingxia/types 0.1.2 → 0.4.3

package/src/error.ts

@@ -0,0 +1,82 @@
+import { ERR_CODE_INFO_BY_CODE, type LxErrorCodeInfo } from "./generated/error";
+
+const ERR_CODE_INDEX = ERR_CODE_INFO_BY_CODE as Record<number, LxErrorCodeInfo>;
+
+export interface LxApiError {
+  readonly code: number;
+  readonly key: LxErrorCodeInfo["key"];
+  readonly message: string;
+  readonly raw: unknown;
+}
+
+export function isLxApiError(error: unknown): error is LxApiError {
+  return parseLxApiError(error) !== null;
+}
+
+function readMessage(error: unknown): string {
+  if (typeof error === "string") return error;
+  if (error instanceof Error && typeof error.message === "string") return error.message;
+  if (typeof error === "object" && error !== null) {
+    const value = (error as { message?: unknown }).message;
+    if (typeof value === "string") return value;
+  }
+  return "Unknown LingXia error";
+}
+
+function toRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null) return null;
+  return value as Record<string, unknown>;
+}
+
+function parseIntegerCode(value: unknown): number | null {
+  if (typeof value === "number" && Number.isInteger(value)) return value;
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    if (Number.isInteger(parsed)) return parsed;
+  }
+  return null;
+}
+
+export function extractLxErrorCode(error: unknown): number | null {
+  const root = toRecord(error);
+  if (!root) return null;
+
+  const rootCode = parseIntegerCode(root.code);
+  if (rootCode !== null) return rootCode;
+
+  const data = toRecord(root.data);
+  if (!data) return null;
+
+  return parseIntegerCode(data.bizCode) ?? parseIntegerCode(data.code);
+}
+
+export function isKnownLxErrorCode(code: number): boolean {
+  return Number.isInteger(code) && Object.prototype.hasOwnProperty.call(ERR_CODE_INDEX, code);
+}
+
+export function infoForLxErrorCode(code: number): LxErrorCodeInfo | null {
+  if (!isKnownLxErrorCode(code)) return null;
+  return ERR_CODE_INDEX[code];
+}
+
+export function parseLxApiError(error: unknown): LxApiError | null {
+  const code = extractLxErrorCode(error);
+  if (code === null) return null;
+  const info = infoForLxErrorCode(code);
+  if (!info) return null;
+  return {
+    ...info,
+    message: readMessage(error),
+    raw: error,
+  };
+}
+
+export function requireLxApiError(error: unknown): LxApiError {
+  const parsed = parseLxApiError(error);
+  if (parsed) return parsed;
+  throw new Error(`Unknown LingXia API error: ${readMessage(error)}`);
+}
+
+export function formatLxApiError(error: LxApiError): string {
+  return `[${error.code}] ${error.message}`;
+}

package/src/file/index.ts

@@ -0,0 +1,121 @@
+/**
+ * File system APIs.
+ * Corresponds to: lingxia-logic/src/fs.rs
+ */
+
+export interface OpenDocumentOptions {
+  filePath: string;
+  fileType?: string;
+  showMenu?: boolean;
+}
+
+/** Desktop only. Currently supported on macOS. Windows is planned. */
+export interface FileDialogFilter {
+  /** Optional label shown in the native dialog. */
+  name?: string;
+  /** Allowed extensions without dots, e.g. ['pdf', 'txt']. */
+  extensions: string[];
+}
+
+/** Desktop only. Currently supported on macOS. Windows is planned. */
+export interface ChooseFileOptions {
+  /** Allow selecting multiple files. Default: false */
+  multiple?: boolean;
+  /** Optional file filters. Empty or omitted means all file types. */
+  filters?: FileDialogFilter[];
+  /** Dialog window title. Platform provides a default if omitted. */
+  title?: string;
+  /** Initial directory the dialog opens in. Platform default if omitted. */
+  defaultPath?: string;
+}
+
+/** Desktop only. Currently supported on macOS. Windows is planned. */
+export interface ChooseFileResult {
+  /** True if the user dismissed the dialog without selecting. */
+  canceled: boolean;
+  /** Absolute system paths of selected files. Empty when canceled. */
+  paths: string[];
+}
+
+/** Desktop only. Currently supported on macOS. Windows is planned. */
+export interface ChooseDirectoryOptions {
+  /** Dialog window title. Platform provides a default if omitted. */
+  title?: string;
+  /** Initial directory the dialog opens in. Platform default if omitted. */
+  defaultPath?: string;
+}
+
+/** Desktop only. Currently supported on macOS. Windows is planned. */
+export interface ChooseDirectoryResult {
+  /** True if the user dismissed the dialog without selecting. */
+  canceled: boolean;
+  /** Absolute system path of the selected directory. Undefined when canceled. */
+  path?: string;
+}
+
+export interface DownloadOptions {
+  /** HTTP(S) source URL. */
+  url: string;
+  /**
+   * Optional external cancellation channel.
+   * When aborted, it has the same effect as calling `task.cancel()`.
+   * Useful for timeout/router/lifecycle composition.
+   */
+  signal?: AbortSignal;
+}
+
+export interface DownloadResult {
+  /** Downloaded file URI under user cache, e.g. lx://usercache/... */
+  tempFilePath: string;
+  /** Suggested filename resolved by runtime from headers/url. */
+  fileName: string;
+  /** MIME type when available. */
+  mimeType?: string;
+  /** File size in bytes. */
+  size: number;
+}
+
+export interface DownloadProgressEvent {
+  kind: 'progress';
+  downloadedBytes: number;
+  totalBytes?: number;
+  /**
+   * 0~1 progress value.
+   * - precise ratio when totalBytes is known
+   * - monotonic estimated progress when totalBytes is unknown
+   */
+  progress: number;
+}
+
+export interface DownloadSuccessEvent {
+  kind: 'success';
+  result: DownloadResult;
+}
+
+export interface DownloadPausedEvent {
+  kind: 'paused';
+}
+
+export interface DownloadResumedEvent {
+  kind: 'resumed';
+}
+
+export interface DownloadCanceledEvent {
+  kind: 'canceled';
+}
+
+export type DownloadEvent =
+  | DownloadProgressEvent
+  | DownloadSuccessEvent
+  | DownloadPausedEvent
+  | DownloadResumedEvent
+  | DownloadCanceledEvent;
+
+export interface DownloadTask extends AsyncIterable<DownloadEvent> {
+  /** Pause current download and keep resume metadata. */
+  pause(): Promise<void>;
+  /** Resume a paused download from persisted resume metadata. */
+  resume(): Promise<void>;
+  /** Cancel and remove downloaded temp artifacts. */
+  cancel(): Promise<void>;
+}

package/src/generated/error.ts

@@ -0,0 +1,52 @@
+// Auto-generated by lingxia-gen. DO NOT EDIT.
+
+import type { I18nKey } from "./i18n";
+
+export const ERR_CODE_INFO_BY_CODE = {
+  1000: { code: 1000, key: "err_code_1000" },
+  1001: { code: 1001, key: "err_code_1001" },
+  1002: { code: 1002, key: "err_code_1002" },
+  1003: { code: 1003, key: "err_code_1003" },
+  1004: { code: 1004, key: "err_code_1004" },
+  1005: { code: 1005, key: "err_code_1005" },
+  2000: { code: 2000, key: "err_code_2000" },
+  2001: { code: 2001, key: "err_code_2001" },
+  3000: { code: 3000, key: "err_code_3000" },
+  3001: { code: 3001, key: "err_code_3001" },
+  3002: { code: 3002, key: "err_code_3002" },
+  3003: { code: 3003, key: "err_code_3003" },
+  3004: { code: 3004, key: "err_code_3004" },
+  3005: { code: 3005, key: "err_code_3005" },
+  3006: { code: 3006, key: "err_code_3006" },
+  3007: { code: 3007, key: "err_code_3007" },
+  4000: { code: 4000, key: "err_code_4000" },
+  4001: { code: 4001, key: "err_code_4001" },
+  4002: { code: 4002, key: "err_code_4002" },
+  4003: { code: 4003, key: "err_code_4003" },
+  5000: { code: 5000, key: "err_code_5000" },
+  5001: { code: 5001, key: "err_code_5001" },
+  5002: { code: 5002, key: "err_code_5002" },
+  5003: { code: 5003, key: "err_code_5003" },
+  5004: { code: 5004, key: "err_code_5004" },
+  6000: { code: 6000, key: "err_code_6000" },
+  6001: { code: 6001, key: "err_code_6001" },
+  6002: { code: 6002, key: "err_code_6002" },
+  12000: { code: 12000, key: "err_code_12000" },
+  12001: { code: 12001, key: "err_code_12001" },
+  12002: { code: 12002, key: "err_code_12002" },
+  12003: { code: 12003, key: "err_code_12003" },
+  12004: { code: 12004, key: "err_code_12004" },
+  12005: { code: 12005, key: "err_code_12005" },
+  12006: { code: 12006, key: "err_code_12006" },
+  12007: { code: 12007, key: "err_code_12007" },
+  12008: { code: 12008, key: "err_code_12008" },
+  12009: { code: 12009, key: "err_code_12009" },
+  12010: { code: 12010, key: "err_code_12010" },
+} as const;
+
+export type LxErrorCode = (typeof ERR_CODE_INFO_BY_CODE)[keyof typeof ERR_CODE_INFO_BY_CODE]["code"];
+export interface LxErrorCodeInfo {
+  readonly code: LxErrorCode;
+  readonly key: I18nKey;
+}
+

package/src/generated/i18n.ts

@@ -0,0 +1,123 @@
+// Auto-generated by lingxia-gen. DO NOT EDIT.
+
+export const I18N_KEYS = [
+  "album_add_more_media",
+  "album_add_more_photos",
+  "album_add_more_videos",
+  "album_all_media",
+  "album_all_photos",
+  "album_all_videos",
+  "album_label",
+  "album_original_image",
+  "album_selected",
+  "camera_access_denied",
+  "camera_audio_init_failed",
+  "camera_cancelling",
+  "camera_init_failed",
+  "camera_label",
+  "camera_long_press_to_record",
+  "camera_max_duration_reached",
+  "camera_preparing",
+  "camera_record_video",
+  "camera_release_to_stop",
+  "camera_switch",
+  "camera_switch_failed",
+  "camera_switch_to_back",
+  "camera_switch_to_front",
+  "camera_switching",
+  "camera_tap_to_capture",
+  "camera_tap_to_record",
+  "camera_tap_to_stop",
+  "camera_video_input_failed",
+  "camera_video_output_failed",
+  "capsule_clean_cache",
+  "capsule_restart",
+  "capsule_uninstall",
+  "common_auto",
+  "common_back",
+  "common_cancel",
+  "common_close",
+  "common_confirm",
+  "common_delete",
+  "common_done",
+  "common_edit",
+  "common_home",
+  "common_loading",
+  "common_ok",
+  "common_retry",
+  "common_save",
+  "common_settings",
+  "common_share",
+  "common_success",
+  "common_warning",
+  "date_last_30_days",
+  "date_last_7_days",
+  "date_last_month",
+  "date_last_week",
+  "date_this_month",
+  "date_this_week",
+  "document_pdf_page_preview",
+  "err_code_1000",
+  "err_code_1001",
+  "err_code_1002",
+  "err_code_1003",
+  "err_code_1004",
+  "err_code_1005",
+  "err_code_12000",
+  "err_code_12001",
+  "err_code_12002",
+  "err_code_12003",
+  "err_code_12004",
+  "err_code_12005",
+  "err_code_12006",
+  "err_code_12007",
+  "err_code_12008",
+  "err_code_12009",
+  "err_code_12010",
+  "err_code_2000",
+  "err_code_2001",
+  "err_code_3000",
+  "err_code_3001",
+  "err_code_3002",
+  "err_code_3003",
+  "err_code_3004",
+  "err_code_3005",
+  "err_code_3006",
+  "err_code_3007",
+  "err_code_4000",
+  "err_code_4001",
+  "err_code_4002",
+  "err_code_4003",
+  "err_code_5000",
+  "err_code_5001",
+  "err_code_5002",
+  "err_code_5003",
+  "err_code_5004",
+  "err_code_6000",
+  "err_code_6001",
+  "err_code_6002",
+  "error_network_error",
+  "error_save_failed",
+  "error_server_error",
+  "error_timeout",
+  "error_unauthorized",
+  "error_unknown",
+  "error_video_too_short",
+  "permission_limited_access_add_more_media",
+  "permission_limited_access_add_more_photos",
+  "permission_limited_access_add_more_videos",
+  "permission_limited_access_warning",
+  "permission_location_reason",
+  "permission_media_reason",
+  "permission_network_reason",
+  "permission_wifi_reason",
+  "update_confirm",
+  "update_download_failed",
+  "update_downloading",
+  "update_message",
+  "update_title",
+  "video_quality",
+  "video_speed",
+] as const;
+
+export type I18nKey = (typeof I18N_KEYS)[number];

package/src/index.ts

@@ -6,16 +6,24 @@
 
 export * from './app';
 export * from './device';
+export * from './display';
 export * from './input';
 export * from './storage';
+export * from './file';
 export * from './location';
+export * from './navigator';
 export * from './system';
+export * from './update';
 export * from './media';
 export * from './ui';
+export * from './error';
+export * from './generated/error';
+export * from './generated/i18n';
 
 import type {
   AppConfig,
   AppInstance,
+  LxAppInfo,
   PageConfig,
   PageInstance,
 } from './app';
@@ -27,8 +35,8 @@ import type {
   WifiInfo,
   ConnectWifiOptions,
   WifiConnectedCallback,
-  AppOrientationInfo,
-  SetAppOrientationOptions,
+  NetworkInfo,
+  NetworkChangeCallback,
 } from './device';
 
 import type { KeyEventCallback } from './input';
@@ -36,9 +44,23 @@ import type { KeyEventCallback } from './input';
 import type {
   LxEnv,
   Storage,
-  OpenDocumentOptions,
 } from './storage';
 
+import type {
+  OpenDocumentOptions,
+  ChooseDirectoryOptions,
+  ChooseDirectoryResult,
+  ChooseFileOptions,
+  ChooseFileResult,
+  DownloadTask,
+  DownloadOptions,
+} from './file';
+
+import type {
+  DeviceOrientation,
+  DeviceOrientationChangeEvent,
+} from './display';
+
 import type {
   GetLocationOptions,
   LocationInfo,
@@ -48,18 +70,27 @@ import type {
   AppBaseInfo,
   SystemSettingInfo,
   OpenURLOptions,
-  NavigateToLxAppOptions,
-  UpdateManager,
 } from './system';
 
+import type { NavigateToLxAppOptions } from './navigator';
+
+import type { UpdateManager } from './update';
+
 import type {
   GetImageInfoOptions,
   ImageInfo,
   CompressImageOptions,
   CompressImageResult,
+  CompressVideoOptions,
+  CompressVideoResult,
+  GetVideoInfoOptions,
+  VideoInfo,
+  ExtractVideoThumbnailOptions,
+  ExtractVideoThumbnailResult,
   ChooseMediaOptions,
   ChosenMediaEntry,
   PreviewMediaOptions,
+  PreviewMediaResult,
   SaveMediaOptions,
   ScanCodeOptions,
   ScanCodeResult,
@@ -106,11 +137,16 @@ export interface Lx {
   getConnectedWifi(): Promise<WifiInfo>;
   onWifiConnected(callback: WifiConnectedCallback): void;
   offWifiConnected(callback?: WifiConnectedCallback): void;
+  getNetworkInfo(): Promise<NetworkInfo>;
+  onNetworkChange(callback: NetworkChangeCallback): void;
+  offNetworkChange(callback?: NetworkChangeCallback): void;
 
-  getAppOrientation(): AppOrientationInfo;
-  setAppOrientation(options: SetAppOrientationOptions): boolean;
+  setDeviceOrientation(orientation: DeviceOrientation): boolean;
+  onDeviceOrientationChange(callback: (event: DeviceOrientationChangeEvent) => void): void;
+  offDeviceOrientationChange(callback?: (event: DeviceOrientationChangeEvent) => void): void;
 
   openDocument(options: OpenDocumentOptions): void;
+  downloadFile(options: DownloadOptions): DownloadTask;
 
   getStorage(): Storage;
 
@@ -120,6 +156,7 @@ export interface Lx {
   navigateBackLxApp(): Promise<void>;
 
   getAppBaseInfo(): AppBaseInfo;
+  getLxAppInfo(): LxAppInfo;
   getSystemSetting(): SystemSettingInfo;
   openURL(options: OpenURLOptions): void;
 
@@ -127,10 +164,25 @@ export interface Lx {
 
   getImageInfo(options: GetImageInfoOptions): Promise<ImageInfo>;
   compressImage(options: CompressImageOptions): Promise<CompressImageResult>;
+  compressVideo(options: CompressVideoOptions): Promise<CompressVideoResult>;
+  getVideoInfo(options: GetVideoInfoOptions): Promise<VideoInfo>;
+  extractVideoThumbnail(options: ExtractVideoThumbnailOptions): Promise<ExtractVideoThumbnailResult>;
 
   chooseMedia(options?: ChooseMediaOptions): Promise<ChosenMediaEntry[]>;
 
-  previewMedia(options: PreviewMediaOptions): void;
+  /**
+   * Opens native media preview.
+   *
+   * Supports:
+   * - a single source path string for the simplest case
+   * - a single-item object for per-item options like `rotate`, `objectFit`, or `durationMs`
+   * - a sequence object for multi-item preview with `sources`, `startIndex`, and `advance`
+   *
+   * Resolves when preview session is closed (manual/auto/interrupted/error).
+   * Rejects with a cancellation error if `signal` is aborted, and abort also requests
+   * the active native preview session to close immediately.
+   */
+  previewMedia(options: PreviewMediaOptions): Promise<PreviewMediaResult>;
 
   saveImageToPhotosAlbum(options: SaveMediaOptions): Promise<void>;
   saveVideoToPhotosAlbum(options: SaveMediaOptions): Promise<void>;
@@ -173,6 +225,11 @@ export interface Lx {
 
   getCapsuleRect(): Promise<CapsuleRect>;
 
+  /** Desktop only. Currently supported on macOS. Windows is planned. */
+  chooseFile(options?: ChooseFileOptions): Promise<ChooseFileResult>;
+  /** Desktop only. Currently supported on macOS. Windows is planned. */
+  chooseDirectory(options?: ChooseDirectoryOptions): Promise<ChooseDirectoryResult>;
+
   onKeyDown(callback: KeyEventCallback): void;
   offKeyDown(callback?: KeyEventCallback): void;
   onKeyUp(callback: KeyEventCallback): void;