@miaixz/sdk 0.5.0

package/dist/api/client.d.ts

@@ -0,0 +1,223 @@
+import { type MiaixzTranslator } from "../i18n/index.js";
+import type { MiaixzEnvironment } from "../types/index.js";
+import type { MiaixzQuery, MiaixzRequestBody, MiaixzRequestInterceptor, MiaixzRequestOptions } from "./request.js";
+import { type MiaixzHttpResponse, type MiaixzResponseInterceptor } from "./response.js";
+import type { MiaixzApiTelemetryHooks } from "./telemetry.js";
+/**
+ * Supplies a bearer token to the API client on demand.
+ *
+ * @returns A bearer token, or `undefined` when no token is available.
+ * @public
+ */
+export type MiaixzTokenProvider = () => string | undefined | Promise<string | undefined>;
+/**
+ * Supplies a complete Authorization header value on demand.
+ *
+ * @returns A complete Authorization value, or `undefined` when unavailable.
+ * @public
+ */
+export type MiaixzAuthorizationProvider = () => string | undefined | Promise<string | undefined>;
+/**
+ * Supplies runtime-context headers to the API client on demand.
+ *
+ * @returns Runtime-context headers, or `undefined` when no context is active.
+ * @public
+ */
+export type MiaixzContextHeadersProvider = () => HeadersInit | undefined | Promise<HeadersInit | undefined>;
+/**
+ * Supplies a CSRF token to a Cookie/BFF API client on demand.
+ *
+ * @returns A CSRF token, or `undefined` when no token is available.
+ * @public
+ */
+export type MiaixzCsrfTokenProvider = () => string | undefined | Promise<string | undefined>;
+/**
+ * Configures authoritative CSRF handling for an API client.
+ *
+ * @public
+ */
+export interface MiaixzCsrfOptions {
+    /**
+     * Determines whether Cookie/BFF write requests require a provider token.
+     */
+    readonly required: boolean;
+    /**
+     * Supplies the authoritative token for Cookie/BFF write requests.
+     */
+    readonly tokenProvider?: MiaixzCsrfTokenProvider;
+}
+/**
+ * Configures a reusable Miaixz API client.
+ *
+ * @public
+ */
+export interface MiaixzApiClientOptions {
+    /**
+     * Base URL used to resolve relative request paths.
+     */
+    readonly baseUrl: string;
+    /**
+     * Environment used to validate the endpoint transport policy.
+     *
+     * @defaultValue "production"
+     */
+    readonly environment?: MiaixzEnvironment;
+    /**
+     * Optional Fetch implementation used to send requests.
+     */
+    readonly fetch?: typeof fetch;
+    /**
+     * Optional headers included with every request.
+     */
+    readonly headers?: HeadersInit;
+    /**
+     * Optional default Fetch credentials mode.
+     *
+     * @defaultValue "same-origin"
+     */
+    readonly credentials?: RequestCredentials;
+    /**
+     * Optional default request timeout in milliseconds.
+     *
+     * @defaultValue 30000
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Optional default number of retry attempts.
+     *
+     * @defaultValue 0
+     */
+    readonly retry?: number;
+    /**
+     * Provides the complete Authorization header value, including its authentication scheme.
+     */
+    readonly authorizationProvider?: MiaixzAuthorizationProvider;
+    /**
+     * Provides a bearer token. Ignored when `authorizationProvider` returns a value.
+     */
+    readonly tokenProvider?: MiaixzTokenProvider;
+    /**
+     * Optional provider for active runtime-context headers.
+     */
+    readonly contextHeadersProvider?: MiaixzContextHeadersProvider;
+    /**
+     * Optional request interceptors executed in registration order.
+     */
+    readonly requestInterceptors?: readonly MiaixzRequestInterceptor[];
+    /**
+     * Optional response interceptors executed in registration order.
+     */
+    readonly responseInterceptors?: readonly MiaixzResponseInterceptor[];
+    /**
+     * Optional translator used for SDK-generated messages.
+     */
+    readonly translate?: MiaixzTranslator;
+    /**
+     * Optional authoritative CSRF policy for Cookie/BFF requests.
+     */
+    readonly csrf?: MiaixzCsrfOptions;
+    /**
+     * Optional observers for immutable, redacted request lifecycle events.
+     */
+    readonly telemetry?: MiaixzApiTelemetryHooks;
+}
+/**
+ * Sends typed requests to Miaixz services.
+ *
+ * @public
+ */
+export interface MiaixzApiClient {
+    /**
+     * Normalized base URL used by the client.
+     */
+    readonly baseUrl: string;
+    /**
+     * Sends a request with full method and body control.
+     *
+     * @typeParam TResponse - Final response-data type.
+     * @typeParam TBody - Request-body type.
+     * @param path - Relative or slash-relative same-origin request path.
+     * @param options - Optional request behavior and response parser.
+     * @returns The final parsed HTTP response.
+     * @throws MiaixzSdkError When request validation, transport, or response handling fails.
+     */
+    request<TResponse = unknown, TBody extends MiaixzRequestBody = MiaixzRequestBody>(path: string, options?: MiaixzRequestOptions<TResponse, TBody>): Promise<MiaixzHttpResponse<TResponse>>;
+    /**
+     * Sends a GET request.
+     *
+     * @typeParam TResponse - Final response-data type.
+     * @param path - Relative or slash-relative same-origin request path.
+     * @param options - Optional GET behavior and response parser.
+     * @returns The final parsed HTTP response.
+     * @throws MiaixzSdkError When request validation, transport, or response handling fails.
+     */
+    get<TResponse = unknown>(path: string, options?: Omit<MiaixzRequestOptions<TResponse>, "method" | "body">): Promise<MiaixzHttpResponse<TResponse>>;
+    /**
+     * Sends a POST request.
+     *
+     * @typeParam TResponse - Final response-data type.
+     * @typeParam TBody - Request-body type.
+     * @param path - Relative or slash-relative same-origin request path.
+     * @param body - Optional request body.
+     * @param options - Optional POST behavior and response parser.
+     * @returns The final parsed HTTP response.
+     * @throws MiaixzSdkError When request validation, CSRF, transport, or response handling fails.
+     */
+    post<TResponse = unknown, TBody extends MiaixzRequestBody = MiaixzRequestBody>(path: string, body?: TBody, options?: Omit<MiaixzRequestOptions<TResponse, TBody>, "method" | "body">): Promise<MiaixzHttpResponse<TResponse>>;
+    /**
+     * Sends a PUT request.
+     *
+     * @typeParam TResponse - Final response-data type.
+     * @typeParam TBody - Request-body type.
+     * @param path - Relative or slash-relative same-origin request path.
+     * @param body - Optional request body.
+     * @param options - Optional PUT behavior and response parser.
+     * @returns The final parsed HTTP response.
+     * @throws MiaixzSdkError When request validation, CSRF, transport, or response handling fails.
+     */
+    put<TResponse = unknown, TBody extends MiaixzRequestBody = MiaixzRequestBody>(path: string, body?: TBody, options?: Omit<MiaixzRequestOptions<TResponse, TBody>, "method" | "body">): Promise<MiaixzHttpResponse<TResponse>>;
+    /**
+     * Sends a PATCH request.
+     *
+     * @typeParam TResponse - Final response-data type.
+     * @typeParam TBody - Request-body type.
+     * @param path - Relative or slash-relative same-origin request path.
+     * @param body - Optional request body.
+     * @param options - Optional PATCH behavior and response parser.
+     * @returns The final parsed HTTP response.
+     * @throws MiaixzSdkError When request validation, CSRF, transport, or response handling fails.
+     */
+    patch<TResponse = unknown, TBody extends MiaixzRequestBody = MiaixzRequestBody>(path: string, body?: TBody, options?: Omit<MiaixzRequestOptions<TResponse, TBody>, "method" | "body">): Promise<MiaixzHttpResponse<TResponse>>;
+    /**
+     * Sends a DELETE request.
+     *
+     * @typeParam TResponse - Final response-data type.
+     * @param path - Relative or slash-relative same-origin request path.
+     * @param options - Optional DELETE behavior and response parser.
+     * @returns The final parsed HTTP response.
+     * @throws MiaixzSdkError When request validation, CSRF, transport, or response handling fails.
+     */
+    delete<TResponse = unknown>(path: string, options?: Omit<MiaixzRequestOptions<TResponse>, "method">): Promise<MiaixzHttpResponse<TResponse>>;
+}
+/**
+ * Appends scalar or repeated query values without disturbing an existing hash.
+ * `null` and `undefined` values are omitted.
+ *
+ * @param url - Request URL to update.
+ * @param query - Optional query parameters to append.
+ * @returns URL containing the serialized query parameters.
+ * @public
+ */
+export declare function appendMiaixzQuery(url: string, query?: MiaixzQuery): string;
+/**
+ * Creates a Fetch-based API client with auth, runtime context, retries, i18n,
+ * and automatic `{ errcode, errmsg, data }` validation and data unwrapping.
+ *
+ * @param options - Endpoint and runtime adapters shared by all requests.
+ * @returns A reusable typed client whose response `data` is already unwrapped.
+ * @throws MiaixzApiError When the configured base URL violates the endpoint policy.
+ * @throws MiaixzSdkError When no Fetch implementation is available.
+ * @public
+ */
+export declare function createApiClient(options: MiaixzApiClientOptions): MiaixzApiClient;
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"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"}