@miaixz/sdk 0.5.0

package/dist/api/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"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","sourcesContent":["import { translateMiaixzDefaultMessage } from \"../i18n/default-translator.js\";\nimport type { MiaixzTranslator } from \"../i18n/index.js\";\n\n/**\n * Configures metadata attached to a Miaixz SDK error.\n *\n * @public\n */\nexport interface MiaixzSdkErrorOptions {\n  /**\n   * Optional stable machine-readable error code.\n   */\n  readonly code?: string;\n\n  /**\n   * Optional diagnostic details associated with the error.\n   */\n  readonly details?: unknown;\n\n  /**\n   * Optional original value that caused the error.\n   */\n  readonly cause?: unknown;\n}\n\n/**\n * Base class for errors created by the Miaixz SDK.\n *\n * @public\n */\nexport class MiaixzSdkError extends Error {\n  /**\n   * Original Error preserved for local diagnostics when one was supplied.\n   */\n  declare readonly cause?: Error;\n\n  /**\n   * Stable machine-readable error code.\n   */\n  readonly code: string;\n\n  /**\n   * Optional diagnostic details associated with the error.\n   */\n  readonly details?: unknown;\n\n  /**\n   * Creates an SDK error.\n   *\n   * @param message - Localized human-readable error message.\n   * @param options - Stable code, diagnostic details, and original cause.\n   */\n  constructor(message: string, options: MiaixzSdkErrorOptions = {}) {\n    const safeCause = options.cause instanceof Error ? options.cause : undefined;\n    super(message, safeCause === undefined ? undefined : { cause: safeCause });\n    this.name = \"MiaixzSdkError\";\n    this.code = options.code ?? \"SDK_ERROR\";\n    if (options.details !== undefined) this.details = options.details;\n    else if (options.cause !== undefined && safeCause === undefined) {\n      this.details = Object.freeze({ type: typeof options.cause });\n    }\n  }\n}\n\n/**\n * Configures request and response metadata attached to an API error.\n *\n * @public\n */\nexport interface MiaixzApiErrorOptions extends MiaixzSdkErrorOptions {\n  /**\n   * HTTP status code, or zero when no HTTP response exists.\n   */\n  readonly status: number;\n\n  /**\n   * HTTP method or request operation name.\n   */\n  readonly method: string;\n\n  /**\n   * URL associated with the failed request.\n   */\n  readonly url: string;\n\n  /**\n   * Optional request identifier returned by the server.\n   */\n  readonly requestId?: string;\n\n  /**\n   * Indicates whether retrying the request may succeed.\n   */\n  readonly retryable?: boolean;\n}\n\n/**\n * Error returned for HTTP failures, invalid envelopes, or non-zero business codes.\n *\n * @public\n */\nexport class MiaixzApiError extends MiaixzSdkError {\n  /**\n   * HTTP status code, or zero when no HTTP response exists.\n   */\n  readonly status: number;\n\n  /**\n   * HTTP method or request operation name.\n   */\n  readonly method: string;\n\n  /**\n   * URL associated with the failed request.\n   */\n  readonly url: string;\n\n  /**\n   * Optional request identifier returned by the server.\n   */\n  readonly requestId?: string;\n\n  /**\n   * Indicates whether retrying the request may succeed.\n   */\n  readonly retryable?: boolean;\n\n  /**\n   * Creates a structured API error.\n   *\n   * @param message - Backend or localized fallback message.\n   * @param options - Request, response, and retry metadata.\n   */\n  constructor(message: string, options: MiaixzApiErrorOptions) {\n    super(message, options);\n    this.name = \"MiaixzApiError\";\n    this.status = options.status;\n    this.method = options.method;\n    this.url = options.url;\n    if (options.retryable !== undefined) this.retryable = options.retryable;\n    if (options.requestId !== undefined) this.requestId = options.requestId;\n  }\n}\n\n/**\n * Represents a transport failure before a valid HTTP response was received.\n *\n * @public\n */\nexport class MiaixzNetworkError extends MiaixzSdkError {\n  /**\n   * Creates a transport error.\n   *\n   * @param cause - Original transport error.\n   * @param translate - Message translator.\n   */\n  constructor(cause?: unknown, translate: MiaixzTranslator = translateMiaixzDefaultMessage) {\n    super(translate(\"sdk.error.network\"), { code: \"NETWORK_ERROR\", cause });\n    this.name = \"MiaixzNetworkError\";\n  }\n}\n\n/**\n * Represents a request cancelled after exceeding its configured timeout.\n *\n * @public\n */\nexport class MiaixzTimeoutError extends MiaixzSdkError {\n  /**\n   * Timeout threshold in milliseconds that cancelled the request.\n   */\n  readonly timeoutMs: number;\n\n  /**\n   * Creates a timeout error.\n   *\n   * @param timeoutMs - Timeout threshold in milliseconds.\n   * @param cause - Original abort or transport error.\n   * @param translate - Message translator.\n   */\n  constructor(\n    timeoutMs: number,\n    cause?: unknown,\n    translate: MiaixzTranslator = translateMiaixzDefaultMessage,\n  ) {\n    super(translate(\"sdk.error.timeout\", { timeoutMs }), { code: \"TIMEOUT\", cause });\n    this.name = \"MiaixzTimeoutError\";\n    this.timeoutMs = timeoutMs;\n  }\n}\n\n/**\n * Represents cancellation requested by the caller.\n *\n * @public\n */\nexport class MiaixzAbortError extends MiaixzSdkError {\n  /**\n   * Creates a caller-requested cancellation error.\n   *\n   * @param cause - Original cancellation reason.\n   * @param translate - Message translator.\n   */\n  constructor(cause?: unknown, translate: MiaixzTranslator = translateMiaixzDefaultMessage) {\n    super(translate(\"sdk.error.aborted\"), { code: \"ABORTED\", cause });\n    this.name = \"MiaixzAbortError\";\n  }\n}\n\n/**\n * Determines whether a value is an error created by the Miaixz SDK.\n *\n * @param value - Value to inspect.\n * @returns Whether `value` is an SDK-created error.\n * @public\n */\nexport function isMiaixzSdkError(value: unknown): value is MiaixzSdkError {\n  return value instanceof MiaixzSdkError;\n}\n\n/**\n * Determines whether a value contains Miaixz API request metadata.\n *\n * @param value - Value to inspect.\n * @returns Whether `value` contains Miaixz API request metadata.\n * @public\n */\nexport function isMiaixzApiError(value: unknown): value is MiaixzApiError {\n  return value instanceof MiaixzApiError;\n}\n\n/**\n * Converts an arbitrary thrown value into a stable SDK error.\n *\n * @param value - Unknown caught value.\n * @param translate - Translator used for non-Error values.\n * @returns The original SDK error or a normalized wrapper.\n * @public\n */\nexport function normalizeMiaixzError(\n  value: unknown,\n  translate: MiaixzTranslator = translateMiaixzDefaultMessage,\n): MiaixzSdkError {\n  if (value instanceof MiaixzSdkError) return value;\n  if (value instanceof Error) {\n    return new MiaixzSdkError(translate(\"sdk.error.unknown\"), {\n      cause: value,\n    });\n  }\n  return new MiaixzSdkError(translate(\"sdk.error.unknown\"), { cause: value });\n}\n"]}

package/dist/api/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./request.js";
+export * from "./response.js";
+export type { MiaixzApiTelemetryHooks, MiaixzErrorEvent, MiaixzRequestEvent, MiaixzResponseEvent, } from "./telemetry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,YAAY,EACV,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}

package/dist/api/index.js

@@ -0,0 +1,5 @@
+export * from "./client.js";
+export * from "./errors.js";
+export * from "./request.js";
+export * from "./response.js";
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC","sourcesContent":["export * from \"./client.js\";\nexport * from \"./errors.js\";\nexport * from \"./request.js\";\nexport * from \"./response.js\";\nexport type {\n  MiaixzApiTelemetryHooks,\n  MiaixzErrorEvent,\n  MiaixzRequestEvent,\n  MiaixzResponseEvent,\n} from \"./telemetry.js\";\n"]}

package/dist/api/request.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Represents an HTTP method supported by the Miaixz API client.
+ *
+ * @public
+ */
+export type MiaixzHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+/**
+ * Selects how the API client parses an HTTP response body.
+ *
+ * @public
+ */
+export type MiaixzResponseType = "auto" | "json" | "text" | "blob" | "arrayBuffer" | "void";
+/**
+ * Selects how the API client handles a Miaixz response envelope.
+ *
+ * @public
+ */
+export type MiaixzEnvelopeMode = "required" | "optional" | "none";
+/**
+ * Converts an untrusted API response value into a verified application value.
+ *
+ * @typeParam T - Verified value returned by the parser.
+ * @public
+ */
+export type MiaixzResponseParser<T> = (value: unknown) => T;
+/**
+ * Represents a scalar value accepted in a URL query parameter.
+ *
+ * @public
+ */
+export type MiaixzQueryPrimitive = string | number | boolean | Date | null | undefined;
+/**
+ * Represents a scalar or repeated URL query parameter value.
+ *
+ * @public
+ */
+export type MiaixzQueryValue = MiaixzQueryPrimitive | readonly MiaixzQueryPrimitive[];
+/**
+ * Maps URL query parameter names to supported values.
+ *
+ * @public
+ */
+export type MiaixzQuery = Readonly<Record<string, MiaixzQueryValue>>;
+/**
+ * Represents a body accepted by the Miaixz API client.
+ *
+ * @public
+ */
+export type MiaixzRequestBody = BodyInit | Readonly<Record<string, unknown>> | readonly unknown[];
+/**
+ * Describes a request after URL, headers, and options are prepared.
+ *
+ * @public
+ */
+export interface MiaixzPreparedRequest {
+    /**
+     * Fully resolved request URL.
+     */
+    readonly url: string;
+    /**
+     * Fetch initialization options for the request.
+     */
+    readonly init: RequestInit;
+    /**
+     * Zero-based request attempt number.
+     */
+    readonly attempt: number;
+}
+/**
+ * Transforms a prepared request before it is sent.
+ *
+ * @public
+ */
+export type MiaixzRequestInterceptor = (request: MiaixzPreparedRequest) => MiaixzPreparedRequest | Promise<MiaixzPreparedRequest>;
+/**
+ * Configures an individual request made by the Miaixz API client.
+ *
+ * @typeParam TBody - Type of the request body.
+ * @public
+ */
+export interface MiaixzRequestOptions<TResponse = unknown, TBody extends MiaixzRequestBody = MiaixzRequestBody> {
+    /**
+     * Optional HTTP method used for the request.
+     */
+    readonly method?: MiaixzHttpMethod;
+    /**
+     * Optional URL query parameters appended to the request path.
+     */
+    readonly query?: MiaixzQuery;
+    /**
+     * Optional request-specific HTTP headers.
+     */
+    readonly headers?: HeadersInit;
+    /**
+     * Optional request body.
+     */
+    readonly body?: TBody;
+    /**
+     * Optional signal used to cancel the request.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional request timeout in milliseconds.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Optional Fetch credentials mode.
+     */
+    readonly credentials?: RequestCredentials;
+    /**
+     * Optional response parsing mode.
+     */
+    readonly responseType?: MiaixzResponseType;
+    /**
+     * JSON responses use the Miaixz errcode/errmsg/data envelope by default.
+     */
+    readonly envelope?: MiaixzEnvelopeMode;
+    /**
+     * Indicates whether authentication headers should be attached.
+     */
+    readonly authenticate?: boolean;
+    /**
+     * Indicates whether active runtime-context headers should be attached.
+     */
+    readonly includeContext?: boolean;
+    /**
+     * Optional number of retry attempts for eligible requests.
+     */
+    readonly retry?: number;
+    /**
+     * Optional runtime parser applied after envelope handling and response interceptors.
+     */
+    readonly parse?: MiaixzResponseParser<TResponse>;
+}
+//# sourceMappingURL=request.d.ts.map

package/dist/api/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../src/api/request.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhG;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,GAAG,MAAM,CAAC;AAE5F;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAElE;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC;AAEvF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,SAAS,oBAAoB,EAAE,CAAC;AAEtF;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAErE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,OAAO,EAAE,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,qBAAqB,KAC3B,qBAAqB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CACnC,SAAS,GAAG,OAAO,EACnB,KAAK,SAAS,iBAAiB,GAAG,iBAAiB;IAEnD;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;CAClD"}

package/dist/api/request.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=request.js.map

package/dist/api/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/api/request.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Represents an HTTP method supported by the Miaixz API client.\n *\n * @public\n */\nexport type MiaixzHttpMethod = \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\" | \"HEAD\" | \"OPTIONS\";\n\n/**\n * Selects how the API client parses an HTTP response body.\n *\n * @public\n */\nexport type MiaixzResponseType = \"auto\" | \"json\" | \"text\" | \"blob\" | \"arrayBuffer\" | \"void\";\n\n/**\n * Selects how the API client handles a Miaixz response envelope.\n *\n * @public\n */\nexport type MiaixzEnvelopeMode = \"required\" | \"optional\" | \"none\";\n\n/**\n * Converts an untrusted API response value into a verified application value.\n *\n * @typeParam T - Verified value returned by the parser.\n * @public\n */\nexport type MiaixzResponseParser<T> = (value: unknown) => T;\n\n/**\n * Represents a scalar value accepted in a URL query parameter.\n *\n * @public\n */\nexport type MiaixzQueryPrimitive = string | number | boolean | Date | null | undefined;\n\n/**\n * Represents a scalar or repeated URL query parameter value.\n *\n * @public\n */\nexport type MiaixzQueryValue = MiaixzQueryPrimitive | readonly MiaixzQueryPrimitive[];\n\n/**\n * Maps URL query parameter names to supported values.\n *\n * @public\n */\nexport type MiaixzQuery = Readonly<Record<string, MiaixzQueryValue>>;\n\n/**\n * Represents a body accepted by the Miaixz API client.\n *\n * @public\n */\nexport type MiaixzRequestBody = BodyInit | Readonly<Record<string, unknown>> | readonly unknown[];\n\n/**\n * Describes a request after URL, headers, and options are prepared.\n *\n * @public\n */\nexport interface MiaixzPreparedRequest {\n  /**\n   * Fully resolved request URL.\n   */\n  readonly url: string;\n\n  /**\n   * Fetch initialization options for the request.\n   */\n  readonly init: RequestInit;\n\n  /**\n   * Zero-based request attempt number.\n   */\n  readonly attempt: number;\n}\n\n/**\n * Transforms a prepared request before it is sent.\n *\n * @public\n */\nexport type MiaixzRequestInterceptor = (\n  request: MiaixzPreparedRequest,\n) => MiaixzPreparedRequest | Promise<MiaixzPreparedRequest>;\n\n/**\n * Configures an individual request made by the Miaixz API client.\n *\n * @typeParam TBody - Type of the request body.\n * @public\n */\nexport interface MiaixzRequestOptions<\n  TResponse = unknown,\n  TBody extends MiaixzRequestBody = MiaixzRequestBody,\n> {\n  /**\n   * Optional HTTP method used for the request.\n   */\n  readonly method?: MiaixzHttpMethod;\n\n  /**\n   * Optional URL query parameters appended to the request path.\n   */\n  readonly query?: MiaixzQuery;\n\n  /**\n   * Optional request-specific HTTP headers.\n   */\n  readonly headers?: HeadersInit;\n\n  /**\n   * Optional request body.\n   */\n  readonly body?: TBody;\n\n  /**\n   * Optional signal used to cancel the request.\n   */\n  readonly signal?: AbortSignal;\n\n  /**\n   * Optional request timeout in milliseconds.\n   */\n  readonly timeoutMs?: number;\n\n  /**\n   * Optional Fetch credentials mode.\n   */\n  readonly credentials?: RequestCredentials;\n\n  /**\n   * Optional response parsing mode.\n   */\n  readonly responseType?: MiaixzResponseType;\n\n  /**\n   * JSON responses use the Miaixz errcode/errmsg/data envelope by default.\n   */\n  readonly envelope?: MiaixzEnvelopeMode;\n\n  /**\n   * Indicates whether authentication headers should be attached.\n   */\n  readonly authenticate?: boolean;\n\n  /**\n   * Indicates whether active runtime-context headers should be attached.\n   */\n  readonly includeContext?: boolean;\n\n  /**\n   * Optional number of retry attempts for eligible requests.\n   */\n  readonly retry?: number;\n\n  /**\n   * Optional runtime parser applied after envelope handling and response interceptors.\n   */\n  readonly parse?: MiaixzResponseParser<TResponse>;\n}\n"]}

package/dist/api/response.d.ts

@@ -0,0 +1,69 @@
+import type { MiaixzApiEnvelope } from "../types/index.js";
+/**
+ * Describes a successful HTTP response returned by the Miaixz API client.
+ *
+ * @typeParam T - Type of the normalized response payload.
+ * @public
+ */
+export interface MiaixzHttpResponse<T> {
+    /**
+     * Normalized response payload.
+     */
+    readonly data: T;
+    /**
+     * HTTP status code.
+     */
+    readonly status: number;
+    /**
+     * HTTP status text.
+     */
+    readonly statusText: string;
+    /**
+     * Response headers returned by the server.
+     */
+    readonly headers: Headers;
+    /**
+     * Optional request identifier returned by the server.
+     */
+    readonly requestId?: string;
+    /**
+     * Final response URL after redirects.
+     */
+    readonly url: string;
+}
+/**
+ * Transforms a normalized response before it reaches the caller.
+ *
+ * @public
+ */
+export type MiaixzResponseInterceptor = (response: MiaixzHttpResponse<unknown>) => MiaixzHttpResponse<unknown> | Promise<MiaixzHttpResponse<unknown>>;
+/**
+ * Validates the standard `{ errcode, errmsg, data }` response shape.
+ *
+ * @param value - Parsed response body.
+ * @returns Whether the body is a Miaixz API envelope.
+ * @public
+ */
+export declare function isMiaixzApiEnvelope<T = unknown>(value: unknown): value is MiaixzApiEnvelope<T>;
+/**
+ * Determines whether an API result code represents success.
+ *
+ * @param value - API result code to inspect.
+ * @returns Whether an API envelope has the success code `0`.
+ * @public
+ */
+export declare function isMiaixzApiSuccess(value: {
+    /**
+     * Business result code returned by the API.
+     */
+    errcode: string | number;
+}): boolean;
+/**
+ * Returns an envelope's `data` value and leaves non-envelope values unchanged.
+ *
+ * @param value - Envelope or already-unwrapped value.
+ * @returns Unwrapped envelope data or the original non-envelope value.
+ * @public
+ */
+export declare function unwrapMiaixzData<T>(value: T | MiaixzApiEnvelope<T>): T;
+//# sourceMappingURL=response.d.ts.map

package/dist/api/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../src/api/response.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAEjB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,CACtC,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,KAClC,kBAAkB,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;AAExE;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAW9F;AAGD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;CAC1B,GAAG,OAAO,CAEV;AAGD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,CAAC,CAKtE"}

package/dist/api/response.js

@@ -0,0 +1,43 @@
+/**
+ * Validates the standard `{ errcode, errmsg, data }` response shape.
+ *
+ * @param value - Parsed response body.
+ * @returns Whether the body is a Miaixz API envelope.
+ * @public
+ */
+export function isMiaixzApiEnvelope(value) {
+    const record = value;
+    return (typeof value === "object" &&
+        value !== null &&
+        "errcode" in value &&
+        (typeof record.errcode === "string" || typeof record.errcode === "number") &&
+        "errmsg" in value &&
+        typeof record.errmsg === "string" &&
+        "data" in value);
+}
+/* eslint-disable jsdoc/check-param-names, jsdoc/require-param -- TSDoc documents the inline field on its TypeScript property. */
+/**
+ * Determines whether an API result code represents success.
+ *
+ * @param value - API result code to inspect.
+ * @returns Whether an API envelope has the success code `0`.
+ * @public
+ */
+export function isMiaixzApiSuccess(value) {
+    return String(value.errcode) === "0";
+}
+/* eslint-enable jsdoc/check-param-names, jsdoc/require-param */
+/**
+ * Returns an envelope's `data` value and leaves non-envelope values unchanged.
+ *
+ * @param value - Envelope or already-unwrapped value.
+ * @returns Unwrapped envelope data or the original non-envelope value.
+ * @public
+ */
+export function unwrapMiaixzData(value) {
+    if (isMiaixzApiEnvelope(value)) {
+        return value.data;
+    }
+    return value;
+}
+//# sourceMappingURL=response.js.map

package/dist/api/response.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.js","sourceRoot":"","sources":["../../src/api/response.ts"],"names":[],"mappings":"AAiDA;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAc,KAAc;IAC7D,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QAClB,CAAC,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,CAAC;QAC1E,QAAQ,IAAI,KAAK;QACjB,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;QACjC,MAAM,IAAI,KAAK,CAChB,CAAC;AACJ,CAAC;AAED,iIAAiI;AACjI;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAKlC;IACC,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,GAAG,CAAC;AACvC,CAAC;AACD,gEAAgE;AAEhE;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAI,KAA+B;IACjE,IAAI,mBAAmB,CAAI,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC,IAAI,CAAC;IACpB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["import type { MiaixzApiEnvelope } from \"../types/index.js\";\n\n/**\n * Describes a successful HTTP response returned by the Miaixz API client.\n *\n * @typeParam T - Type of the normalized response payload.\n * @public\n */\nexport interface MiaixzHttpResponse<T> {\n  /**\n   * Normalized response payload.\n   */\n  readonly data: T;\n\n  /**\n   * HTTP status code.\n   */\n  readonly status: number;\n\n  /**\n   * HTTP status text.\n   */\n  readonly statusText: string;\n\n  /**\n   * Response headers returned by the server.\n   */\n  readonly headers: Headers;\n\n  /**\n   * Optional request identifier returned by the server.\n   */\n  readonly requestId?: string;\n\n  /**\n   * Final response URL after redirects.\n   */\n  readonly url: string;\n}\n\n/**\n * Transforms a normalized response before it reaches the caller.\n *\n * @public\n */\nexport type MiaixzResponseInterceptor = (\n  response: MiaixzHttpResponse<unknown>,\n) => MiaixzHttpResponse<unknown> | Promise<MiaixzHttpResponse<unknown>>;\n\n/**\n * Validates the standard `{ errcode, errmsg, data }` response shape.\n *\n * @param value - Parsed response body.\n * @returns Whether the body is a Miaixz API envelope.\n * @public\n */\nexport function isMiaixzApiEnvelope<T = unknown>(value: unknown): value is MiaixzApiEnvelope<T> {\n  const record = value as Record<string, unknown>;\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"errcode\" in value &&\n    (typeof record.errcode === \"string\" || typeof record.errcode === \"number\") &&\n    \"errmsg\" in value &&\n    typeof record.errmsg === \"string\" &&\n    \"data\" in value\n  );\n}\n\n/* eslint-disable jsdoc/check-param-names, jsdoc/require-param -- TSDoc documents the inline field on its TypeScript property. */\n/**\n * Determines whether an API result code represents success.\n *\n * @param value - API result code to inspect.\n * @returns Whether an API envelope has the success code `0`.\n * @public\n */\nexport function isMiaixzApiSuccess(value: {\n  /**\n   * Business result code returned by the API.\n   */\n  errcode: string | number;\n}): boolean {\n  return String(value.errcode) === \"0\";\n}\n/* eslint-enable jsdoc/check-param-names, jsdoc/require-param */\n\n/**\n * Returns an envelope's `data` value and leaves non-envelope values unchanged.\n *\n * @param value - Envelope or already-unwrapped value.\n * @returns Unwrapped envelope data or the original non-envelope value.\n * @public\n */\nexport function unwrapMiaixzData<T>(value: T | MiaixzApiEnvelope<T>): T {\n  if (isMiaixzApiEnvelope<T>(value)) {\n    return value.data;\n  }\n  return value;\n}\n"]}

package/dist/api/telemetry.d.ts

@@ -0,0 +1,139 @@
+import type { MiaixzHttpMethod } from "./request.js";
+/**
+ * Receives immutable, redacted API lifecycle events without changing request behavior.
+ *
+ * @public
+ */
+export interface MiaixzApiTelemetryHooks {
+    /**
+     * Observes a request immediately before Fetch is invoked.
+     */
+    readonly onRequest?: (event: Readonly<MiaixzRequestEvent>) => void | Promise<void>;
+    /**
+     * Observes an HTTP response immediately after Fetch resolves.
+     */
+    readonly onResponse?: (event: Readonly<MiaixzResponseEvent>) => void | Promise<void>;
+    /**
+     * Observes a normalized request failure.
+     */
+    readonly onError?: (event: Readonly<MiaixzErrorEvent>) => void | Promise<void>;
+    /**
+     * Receives an exception thrown by a primary telemetry hook.
+     */
+    readonly onHookError?: (error: unknown, hook: "request" | "response" | "error") => void;
+}
+/**
+ * Describes a safe request attempt for host-provided telemetry.
+ *
+ * @public
+ */
+export interface MiaixzRequestEvent {
+    /**
+     * Correlates every attempt belonging to one logical request.
+     */
+    readonly requestId: string;
+    /**
+     * Contains the request HTTP method.
+     */
+    readonly method: MiaixzHttpMethod;
+    /**
+     * Contains the URL with credentials, fragments, and query values removed.
+     */
+    readonly url: string;
+    /**
+     * Contains the zero-based request attempt number.
+     */
+    readonly attempt: number;
+    /**
+     * Contains a frozen header snapshot with sensitive values redacted.
+     */
+    readonly headers: Readonly<Record<string, string>>;
+    /**
+     * Contains a frozen redacted JSON value or safe non-JSON body summary.
+     */
+    readonly body?: unknown;
+    /**
+     * Contains the attempt start time as Unix epoch milliseconds.
+     */
+    readonly startedAt: number;
+}
+/**
+ * Describes a safe HTTP response attempt for host-provided telemetry.
+ *
+ * @public
+ */
+export interface MiaixzResponseEvent {
+    /**
+     * Correlates the response with its logical request.
+     */
+    readonly requestId: string;
+    /**
+     * Contains the request HTTP method.
+     */
+    readonly method: MiaixzHttpMethod;
+    /**
+     * Contains the URL with credentials, fragments, and query values removed.
+     */
+    readonly url: string;
+    /**
+     * Contains the zero-based request attempt number.
+     */
+    readonly attempt: number;
+    /**
+     * Contains the HTTP response status.
+     */
+    readonly status: number;
+    /**
+     * Contains elapsed time from attempt start through response receipt.
+     */
+    readonly durationMs: number;
+    /**
+     * Contains a frozen header snapshot with sensitive values redacted.
+     */
+    readonly headers: Readonly<Record<string, string>>;
+}
+/**
+ * Describes a safe normalized failure for host-provided telemetry.
+ *
+ * @public
+ */
+export interface MiaixzErrorEvent {
+    /**
+     * Correlates the failure with its logical request.
+     */
+    readonly requestId: string;
+    /**
+     * Contains the request HTTP method.
+     */
+    readonly method: MiaixzHttpMethod;
+    /**
+     * Contains the URL with credentials, fragments, and query values removed.
+     */
+    readonly url: string;
+    /**
+     * Contains the zero-based request attempt number.
+     */
+    readonly attempt: number;
+    /**
+     * Contains elapsed time from attempt start through failure normalization.
+     */
+    readonly durationMs: number;
+    /**
+     * Contains a frozen error summary without causes or diagnostic payloads.
+     */
+    readonly error: Readonly<{
+        /**
+         * Contains the stable JavaScript error class name.
+         */
+        name: string;
+        /**
+         * Contains the stable machine-readable SDK error code.
+         */
+        code: string;
+        /**
+         * Contains the localized, content-safe error message.
+         */
+        message: string;
+    }>;
+}
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/api/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/api/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,kBAAkB,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnF;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,mBAAmB,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErF;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,gBAAgB,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/E;;OAEG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,KAAK,IAAI,CAAC;CACzF;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEnD;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;QACvB;;WAEG;QACH,IAAI,EAAE,MAAM,CAAC;QAEb;;WAEG;QACH,IAAI,EAAE,MAAM,CAAC;QAEb;;WAEG;QACH,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;CACJ"}

package/dist/api/telemetry.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=telemetry.js.map

package/dist/api/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/api/telemetry.ts"],"names":[],"mappings":"","sourcesContent":["import type { MiaixzHttpMethod } from \"./request.js\";\n\n/**\n * Receives immutable, redacted API lifecycle events without changing request behavior.\n *\n * @public\n */\nexport interface MiaixzApiTelemetryHooks {\n  /**\n   * Observes a request immediately before Fetch is invoked.\n   */\n  readonly onRequest?: (event: Readonly<MiaixzRequestEvent>) => void | Promise<void>;\n\n  /**\n   * Observes an HTTP response immediately after Fetch resolves.\n   */\n  readonly onResponse?: (event: Readonly<MiaixzResponseEvent>) => void | Promise<void>;\n\n  /**\n   * Observes a normalized request failure.\n   */\n  readonly onError?: (event: Readonly<MiaixzErrorEvent>) => void | Promise<void>;\n\n  /**\n   * Receives an exception thrown by a primary telemetry hook.\n   */\n  readonly onHookError?: (error: unknown, hook: \"request\" | \"response\" | \"error\") => void;\n}\n\n/**\n * Describes a safe request attempt for host-provided telemetry.\n *\n * @public\n */\nexport interface MiaixzRequestEvent {\n  /**\n   * Correlates every attempt belonging to one logical request.\n   */\n  readonly requestId: string;\n\n  /**\n   * Contains the request HTTP method.\n   */\n  readonly method: MiaixzHttpMethod;\n\n  /**\n   * Contains the URL with credentials, fragments, and query values removed.\n   */\n  readonly url: string;\n\n  /**\n   * Contains the zero-based request attempt number.\n   */\n  readonly attempt: number;\n\n  /**\n   * Contains a frozen header snapshot with sensitive values redacted.\n   */\n  readonly headers: Readonly<Record<string, string>>;\n\n  /**\n   * Contains a frozen redacted JSON value or safe non-JSON body summary.\n   */\n  readonly body?: unknown;\n\n  /**\n   * Contains the attempt start time as Unix epoch milliseconds.\n   */\n  readonly startedAt: number;\n}\n\n/**\n * Describes a safe HTTP response attempt for host-provided telemetry.\n *\n * @public\n */\nexport interface MiaixzResponseEvent {\n  /**\n   * Correlates the response with its logical request.\n   */\n  readonly requestId: string;\n\n  /**\n   * Contains the request HTTP method.\n   */\n  readonly method: MiaixzHttpMethod;\n\n  /**\n   * Contains the URL with credentials, fragments, and query values removed.\n   */\n  readonly url: string;\n\n  /**\n   * Contains the zero-based request attempt number.\n   */\n  readonly attempt: number;\n\n  /**\n   * Contains the HTTP response status.\n   */\n  readonly status: number;\n\n  /**\n   * Contains elapsed time from attempt start through response receipt.\n   */\n  readonly durationMs: number;\n\n  /**\n   * Contains a frozen header snapshot with sensitive values redacted.\n   */\n  readonly headers: Readonly<Record<string, string>>;\n}\n\n/**\n * Describes a safe normalized failure for host-provided telemetry.\n *\n * @public\n */\nexport interface MiaixzErrorEvent {\n  /**\n   * Correlates the failure with its logical request.\n   */\n  readonly requestId: string;\n\n  /**\n   * Contains the request HTTP method.\n   */\n  readonly method: MiaixzHttpMethod;\n\n  /**\n   * Contains the URL with credentials, fragments, and query values removed.\n   */\n  readonly url: string;\n\n  /**\n   * Contains the zero-based request attempt number.\n   */\n  readonly attempt: number;\n\n  /**\n   * Contains elapsed time from attempt start through failure normalization.\n   */\n  readonly durationMs: number;\n\n  /**\n   * Contains a frozen error summary without causes or diagnostic payloads.\n   */\n  readonly error: Readonly<{\n    /**\n     * Contains the stable JavaScript error class name.\n     */\n    name: string;\n\n    /**\n     * Contains the stable machine-readable SDK error code.\n     */\n    code: string;\n\n    /**\n     * Contains the localized, content-safe error message.\n     */\n    message: string;\n  }>;\n}\n"]}

package/dist/appearance/appearance.d.ts

@@ -0,0 +1,161 @@
+import type { MiaixzEventBus, MiaixzSdkEventMap } from "../events/index.js";
+import type { MiaixzTranslator } from "../i18n/index.js";
+import { type MiaixzKeyValueStorage, type MiaixzStorageMigration } from "../storage/index.js";
+import { type MiaixzAppearanceSettings, type MiaixzColorMode, type MiaixzDensity, type MiaixzThemeColorToken } from "../types/index.js";
+/**
+ * Defines the complete built-in light theme used for validation and CSS mirroring.
+ *
+ * @public
+ */
+export declare const miaixzLightThemeColors: Readonly<Record<MiaixzThemeColorToken, string>>;
+/**
+ * Defines the complete built-in dark theme used for validation and CSS mirroring.
+ *
+ * @public
+ */
+export declare const miaixzDarkThemeColors: Readonly<Record<MiaixzThemeColorToken, string>>;
+/**
+ * Defines the default Miaixz appearance settings.
+ *
+ * @public
+ */
+export declare const miaixzDefaultAppearance: Readonly<MiaixzAppearanceSettings>;
+/**
+ * Configures a Miaixz appearance manager.
+ *
+ * @public
+ */
+export interface MiaixzAppearanceManagerOptions {
+    /**
+     * Identifies the consuming frontend application.
+     */
+    readonly appId: string;
+    /**
+     * Identifies the optional initial tenant persistence boundary.
+     */
+    readonly tenantId?: string;
+    /**
+     * Supplies complete settings merged over persisted settings at construction.
+     */
+    readonly initialAppearance?: MiaixzAppearanceSettings;
+    /**
+     * Supplies an optional versioned persistence adapter.
+     */
+    readonly storage?: MiaixzKeyValueStorage;
+    /**
+     * Supplies an optional continuous appearance migration chain.
+     */
+    readonly migrations?: readonly MiaixzStorageMigration[];
+    /**
+     * Supplies an optional event bus for local or cross-service synchronization.
+     */
+    readonly events?: MiaixzEventBus<MiaixzSdkEventMap>;
+    /**
+     * Supplies the translator used for appearance validation errors.
+     */
+    readonly translate?: MiaixzTranslator;
+}
+/**
+ * Determines whether a value is a supported Miaixz color mode.
+ *
+ * @param value - Value to inspect.
+ * @returns Whether the value is a supported color mode.
+ * @public
+ */
+export declare function isMiaixzColorMode(value: unknown): value is MiaixzColorMode;
+/**
+ * Determines whether a value is a supported Miaixz density.
+ *
+ * @param value - Value to inspect.
+ * @returns Whether the value is a supported density.
+ * @public
+ */
+export declare function isMiaixzDensity(value: unknown): value is MiaixzDensity;
+/**
+ * Parses, normalizes, validates, and freezes appearance settings.
+ *
+ * @param value - Untrusted appearance settings to parse.
+ * @returns A deeply frozen settings snapshot with uppercase custom colors.
+ * @throws MiaixzSdkError When object shape, values, colors, or contrast are invalid.
+ * @public
+ */
+export declare function parseMiaixzAppearanceSettings(value: unknown): MiaixzAppearanceSettings;
+/**
+ * Determines whether a value satisfies the complete appearance contract.
+ *
+ * @param value - Untrusted appearance settings to inspect.
+ * @returns Whether parsing and contrast validation both succeed.
+ * @public
+ */
+export declare function isMiaixzAppearanceSettings(value: unknown): value is MiaixzAppearanceSettings;
+/**
+ * Validates all frozen WCAG contrast pairs for an appearance.
+ *
+ * @param appearance - Appearance settings whose merged themes are validated.
+ * @throws MiaixzSdkError When a custom color is invalid or a pair misses its threshold.
+ * @public
+ */
+export declare function validateMiaixzThemeContrast(appearance: Readonly<MiaixzAppearanceSettings>): void;
+/**
+ * Manages versioned, tenant-scoped appearance state without accessing the DOM.
+ *
+ * @public
+ */
+export declare class MiaixzAppearanceManager {
+    #private;
+    /**
+     * Creates a validated appearance manager for one application and tenant scope.
+     *
+     * @param options - Required application identity and optional runtime adapters.
+     * @throws MiaixzSdkError When scope, migrations, initial settings, or contrast are invalid.
+     */
+    constructor(options: Readonly<MiaixzAppearanceManagerOptions>);
+    /**
+     * Returns the current deeply frozen appearance snapshot.
+     *
+     * @returns Current normalized appearance settings.
+     */
+    getSnapshot(): Readonly<MiaixzAppearanceSettings>;
+    /**
+     * Replaces the complete appearance after atomic validation.
+     *
+     * @param appearance - Complete appearance settings to commit.
+     * @throws MiaixzSdkError When settings, colors, or contrast are invalid.
+     */
+    set(appearance: MiaixzAppearanceSettings): void;
+    /**
+     * Shallowly merges and commits a partial appearance update.
+     *
+     * @param appearance - Top-level settings fields to replace.
+     * @throws MiaixzSdkError When merged settings, colors, or contrast are invalid.
+     */
+    patch(appearance: Partial<MiaixzAppearanceSettings>): void;
+    /**
+     * Reloads appearance state from a new validated tenant scope.
+     *
+     * @param tenantId - Optional tenant identifier, or undefined for global scope.
+     * @throws MiaixzSdkError When the new scope or migration configuration is invalid.
+     */
+    setScope(tenantId?: string): void;
+    /**
+     * Registers a listener for committed appearance snapshots.
+     *
+     * @param listener - Callback invoked synchronously after each committed change.
+     * @returns An idempotent function that removes the listener.
+     */
+    subscribe(listener: (appearance: Readonly<MiaixzAppearanceSettings>) => void): () => void;
+    /**
+     * Releases the event subscription and all local appearance listeners.
+     */
+    destroy(): void;
+}
+/**
+ * Creates a tenant-aware appearance manager without DOM side effects.
+ *
+ * @param options - Required application identity and optional runtime adapters.
+ * @returns Configured appearance manager.
+ * @throws MiaixzSdkError When scope, migrations, initial settings, or contrast are invalid.
+ * @public
+ */
+export declare function createMiaixzAppearanceManager(options: Readonly<MiaixzAppearanceManagerOptions>): MiaixzAppearanceManager;
+//# sourceMappingURL=appearance.d.ts.map

package/dist/appearance/appearance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appearance.d.ts","sourceRoot":"","sources":["../../src/appearance/appearance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAE5B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAKL,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,aAAa,EAElB,KAAK,qBAAqB,EAC3B,MAAM,mBAAmB,CAAC;AAmD3B;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CA8B/E,CAAC;AAEL;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CA+BjF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,wBAAwB,CAGrE,CAAC;AAEH;;;;GAIG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAExD;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAEpD;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAEtE;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,wBAAwB,CAEtF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,wBAAwB,CAO5F;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,QAAQ,CAAC,wBAAwB,CAAC,GAAG,IAAI,CAGhG;AAED;;;;GAIG;AACH,qBAAa,uBAAuB;;IAalC;;;;;OAKG;IACH,YAAY,OAAO,EAAE,QAAQ,CAAC,8BAA8B,CAAC,EA4B5D;IAED;;;;OAIG;IACH,WAAW,IAAI,QAAQ,CAAC,wBAAwB,CAAC,CAEhD;IAED;;;;;OAKG;IACH,GAAG,CAAC,UAAU,EAAE,wBAAwB,GAAG,IAAI,CAE9C;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,wBAAwB,CAAC,GAAG,IAAI,CAEzD;IAED;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAOhC;IAED;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,wBAAwB,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAQxF;IAED;;OAEG;IACH,OAAO,IAAI,IAAI,CAMd;CAoFF;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,QAAQ,CAAC,8BAA8B,CAAC,GAChD,uBAAuB,CAEzB"}