@h-ai/kit 0.1.0-alpha.13 → 0.1.0-alpha.16

package/dist/client/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
+{"version":3,"sources":["../../src/client/kit-nav-adapter.ts"],"names":[],"mappings":";;;;;AAmCO,SAAS,yBAAA,GAId;AACA,EAAA,OAAO;AAAA,IACL,IAAI,QAAA,GAAW;AACb,MAAA,OAAO,KAAK,GAAA,CAAI,QAAA;AAAA,IAClB,CAAA;AAAA,IACA,MAAM,SAAS,GAAA,EAAa;AAC1B,MAAA,MAAM,IAAA,CAAK,GAAA,EAAK,EAAE,aAAA,EAAe,MAAM,CAAA;AAAA,IACzC,CAAA;AAAA,IACA,MAAM,OAAA,GAAU;AACd,MAAA,MAAM,aAAA,EAAc;AAAA,IACtB;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * @h-ai/kit — SvelteKit 路由适配器\n *\n * 此前位于 `@h-ai/ui/sveltekit`，为避免 `@h-ai/ui` 耦合 SvelteKit，迁移至本模块。\n *\n * 为 `@h-ai/ui` 的 `CrudPage` 等需要“宿主路由”的场景组件提供 SvelteKit 实现。\n * 返回值结构与 `@h-ai/ui` 的 `NavAdapter` 完全一致；TS 通过结构类型自动匹配，\n * 无需在 `@h-ai/kit` 中显式依赖 `@h-ai/ui`。\n *\n * @example\n * ```svelte\n * <script lang='ts'>\n *   import { CrudPage } from '@h-ai/ui'\n *   import { createSvelteKitNavAdapter } from '@h-ai/kit/client'\n *\n *   const nav = createSvelteKitNavAdapter()\n * </script>\n *\n * <CrudPage {crud} {data} {nav} />\n * ```\n *\n * @module kit-nav-adapter\n */\n\nimport { goto, invalidateAll } from '$app/navigation'\nimport { page } from '$app/state'\n\n/**\n * SvelteKit `NavAdapter`：\n *\n * - `pathname` 来自 `$app/state` 的 `page.url.pathname`（响应式）。\n * - `navigate` 使用 `$app/navigation` 的 `goto`，并自动 `invalidateAll`，\n *   触发 `+page.server.ts` 的 `load` 重新执行。\n * - `refresh` 调用 `invalidateAll()`，常用于写操作后刷新列表数据。\n */\nexport function createSvelteKitNavAdapter(): {\n  readonly pathname: string\n  readonly navigate: (url: string) => Promise<void>\n  readonly refresh: () => Promise<void>\n} {\n  return {\n    get pathname() {\n      return page.url.pathname\n    },\n    async navigate(url: string) {\n      await goto(url, { invalidateAll: true })\n    },\n    async refresh() {\n      await invalidateAll()\n    },\n  }\n}\n"]}

package/dist/{index-BotXLTck.d.ts → index-M00CsNUR.d.ts}

@@ -1,7 +1,73 @@
+import { CryptoFunctions } from '@h-ai/crypto';
 import { HaiResult } from '@h-ai/core';
 import { PasswordCredentials, AuthResult, OtpCredentials, LdapCredentials, ApiKeyCredentials, RegisterOptions } from '@h-ai/iam';
-import { HandleFetch } from '@sveltejs/kit';
-import { T as TransportCryptoServiceLike } from './kit-crypto-types-C-gEvx04.js';
+import { z } from 'zod';
+
+/**
+ * @h-ai/kit — transport 配置
+ *
+ * 为 `config/_kit.yml` 提供统一的 transport 配置结构、默认值与校验逻辑，
+ * 方便应用层用一份配置同时驱动 `hooks.server.ts` 与 `kit.client.create()`。
+ * @module kit-config
+ */
+
+/** `config/_kit.yml` 中的 transport 配置。 */
+interface KitTransportConfig {
+    readonly keyExchangePath: `/${string}`;
+    readonly excludePaths: readonly `/${string}`[];
+    readonly requireEncryption: boolean;
+    readonly encryptResponse: boolean;
+    readonly maxClients: number;
+}
+/** `config/_kit.yml` 的顶层配置结构。 */
+interface KitConfig {
+    readonly transport: false | KitTransportConfig;
+}
+/** `config/_kit.yml` 中的 transport 输入类型。 */
+type KitTransportConfigInput = Partial<{
+    readonly keyExchangePath: `/${string}`;
+    readonly excludePaths: readonly `/${string}`[];
+    readonly requireEncryption: boolean;
+    readonly encryptResponse: boolean;
+    readonly maxClients: number;
+}>;
+/** `config/_kit.yml` 的顶层输入类型。 */
+interface KitConfigInput {
+    readonly transport?: false | KitTransportConfigInput;
+}
+/** `config/_kit.yml` 对应的配置 Schema。 */
+declare const KitConfigSchema: z.ZodPipe<z.ZodObject<{
+    transport: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
+        keyExchangePath: z.ZodDefault<z.ZodCustom<`/${string}`, `/${string}`>>;
+        excludePaths: z.ZodDefault<z.ZodArray<z.ZodCustom<`/${string}`, `/${string}`>>>;
+        requireEncryption: z.ZodDefault<z.ZodBoolean>;
+        encryptResponse: z.ZodDefault<z.ZodBoolean>;
+        maxClients: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>, z.ZodTransform<{
+    transport: false | KitTransportConfig;
+}, {
+    transport?: false | {
+        keyExchangePath: `/${string}`;
+        excludePaths: `/${string}`[];
+        requireEncryption: boolean;
+        encryptResponse: boolean;
+        maxClients: number;
+    } | undefined;
+}>>;
+/**
+ * 解析 transport 配置并补齐默认值。
+ *
+ * @param input - `config/_kit.yml` 中的 transport 配置
+ * @returns 完整 transport 配置；`false` 表示关闭
+ */
+declare function resolveKitTransportConfig(input?: false | KitTransportConfigInput): false | KitTransportConfig;
+/**
+ * 解析 `config/_kit.yml` 顶层配置并补齐默认值。
+ *
+ * 适合同一份配置同时供 SvelteKit 服务端 hook 与浏览器端 client 读取。
+ */
+declare function resolveKitConfig(input?: KitConfigInput): KitConfig;
 
 /**
  * @h-ai/kit — Bearer 认证工具
@@ -123,10 +189,6 @@ declare function setBrowserToken(token: string): void;
  * 清除浏览器端 Access Token。
  */
 declare function clearBrowserToken(): void;
-/**
- * 创建浏览器端同源请求自动附加 Access Token 的 HandleFetch。
- */
-declare function createHandleFetch(tokenStore?: BrowserTokenStore): HandleFetch;
 
 /**
  * @h-ai/kit — 统一客户端
@@ -140,10 +202,12 @@ declare function createHandleFetch(tokenStore?: BrowserTokenStore): HandleFetch;
  * 传输加密客户端配置
  */
 interface ClientTransportConfig {
-    /** 传输加密服务实例（@h-ai/crypto 的 asymmetric + symmetric） */
-    crypto: TransportCryptoServiceLike;
-    /** 密钥交换端点 URL（默认 `'/api/kit/key-exchange'`） */
+    /** @h-ai/crypto 服务实例 */
+    crypto: CryptoFunctions;
+    /** 密钥交换端点 URL（默认 `'/api/_hai/key-exchange'`） */
     keyExchangeUrl?: string;
+    /** 排除路径（命中后强制走明文），需与服务端 transport.excludePaths 保持一致 */
+    excludePaths?: string[];
 }
 /**
  * Kit 客户端配置
@@ -180,6 +244,44 @@ interface KitClient {
     /** 销毁密钥状态 */
     destroy: () => void;
 }
+/**
+ * 在浏览器启动时安装同源 transport fetch 包装。
+ *
+ * 该包装作用于同源 `/api/*` 与 SvelteKit `__data.json` 请求，页面文档、
+ * 静态资源以及 multipart/form-data 等上传请求保持原样。应用只需安装一次，
+ * 后续 `fetch` / SvelteKit 内部 data fetch / `kit.client.create()` 明文发送路径
+ * 都会共用这层传输加密能力。
+ */
+declare function installBrowserTransportFetch(transportConfig?: ClientTransportConfig): void;
+/**
+ * 用 `config/_kit.yml` 解析后的 {@link KitConfig} 一次性安装浏览器端传输加密。
+ *
+ * 行为：
+ * - `config.transport === false` 时直接返回（不启用传输加密）；
+ * - 否则启动 {@link installBrowserTransportFetch}，并预热 {@link CryptoFunctions} 模块。
+ *
+ * 应用层（SvelteKit `+layout.svelte` 或浏览器入口）只需调用此函数一次，
+ * 之后所有同源 `/api/*` 与 `__data.json` 请求都会自动走传输加密。
+ *
+ * @param config 已解析的 kit 顶层配置
+ * @param deps  外部依赖
+ * @param deps.crypto `@h-ai/crypto` 模块实例
+ *
+ * @example
+ * ```ts
+ * import { browser } from '$app/environment'
+ * import { crypto } from '@h-ai/crypto'
+ * import { kit } from '@h-ai/kit'
+ * import { adminConsoleKitConfig } from '$lib/config/kit-config.js'
+ *
+ * if (browser) {
+ *   kit.client.installBrowserTransport(adminConsoleKitConfig, { crypto })
+ * }
+ * ```
+ */
+declare function installBrowserTransport(config: KitConfig, deps: {
+    crypto: CryptoFunctions;
+}): void;
 /**
  * 创建 Kit 客户端
  *
@@ -200,4 +302,41 @@ interface KitClient {
  */
 declare function createKitClient(config?: KitClientConfig): KitClient;
 
-export { type ClientTransportConfig as C, type KitClient as K, clearBrowserToken as a, createTokenStore as b, createKitClient as c, createHandleFetch as d, type KitClientConfig as e, loginWithOtp as f, loginWithLdap as g, loginWithApiKey as h, logout as i, login as l, registerAndLogin as r, setBrowserToken as s };
+/**
+ * @h-ai/kit — SvelteKit 路由适配器
+ *
+ * 此前位于 `@h-ai/ui/sveltekit`，为避免 `@h-ai/ui` 耦合 SvelteKit，迁移至本模块。
+ *
+ * 为 `@h-ai/ui` 的 `CrudPage` 等需要“宿主路由”的场景组件提供 SvelteKit 实现。
+ * 返回值结构与 `@h-ai/ui` 的 `NavAdapter` 完全一致；TS 通过结构类型自动匹配，
+ * 无需在 `@h-ai/kit` 中显式依赖 `@h-ai/ui`。
+ *
+ * @example
+ * ```svelte
+ * <script lang='ts'>
+ *   import { CrudPage } from '@h-ai/ui'
+ *   import { createSvelteKitNavAdapter } from '@h-ai/kit/client'
+ *
+ *   const nav = createSvelteKitNavAdapter()
+ * </script>
+ *
+ * <CrudPage {crud} {data} {nav} />
+ * ```
+ *
+ * @module kit-nav-adapter
+ */
+/**
+ * SvelteKit `NavAdapter`：
+ *
+ * - `pathname` 来自 `$app/state` 的 `page.url.pathname`（响应式）。
+ * - `navigate` 使用 `$app/navigation` 的 `goto`，并自动 `invalidateAll`，
+ *   触发 `+page.server.ts` 的 `load` 重新执行。
+ * - `refresh` 调用 `invalidateAll()`，常用于写操作后刷新列表数据。
+ */
+declare function createSvelteKitNavAdapter(): {
+    readonly pathname: string;
+    readonly navigate: (url: string) => Promise<void>;
+    readonly refresh: () => Promise<void>;
+};
+
+export { type ClientTransportConfig as C, type KitClient as K, installBrowserTransportFetch as a, clearBrowserToken as b, createKitClient as c, createTokenStore as d, type KitClientConfig as e, type KitConfig as f, type KitConfigInput as g, KitConfigSchema as h, installBrowserTransport as i, type KitTransportConfig as j, type KitTransportConfigInput as k, createSvelteKitNavAdapter as l, resolveKitTransportConfig as m, login as n, loginWithOtp as o, loginWithLdap as p, loginWithApiKey as q, resolveKitConfig as r, setBrowserToken as s, registerAndLogin as t, logout as u };

package/dist/index.d.ts

@@ -1,18 +1,18 @@
-import { c as createKitClient, l as login, f as loginWithOtp, g as loginWithLdap, h as loginWithApiKey, r as registerAndLogin, i as logout, s as setBrowserToken, a as clearBrowserToken, b as createTokenStore, d as createHandleFetch } from './index-BotXLTck.js';
-export { C as ClientTransportConfig, K as KitClient, e as KitClientConfig } from './index-BotXLTck.js';
+import { c as createKitClient, i as installBrowserTransport, a as installBrowserTransportFetch, n as login, o as loginWithOtp, p as loginWithLdap, q as loginWithApiKey, t as registerAndLogin, u as logout, s as setBrowserToken, b as clearBrowserToken, d as createTokenStore } from './index-M00CsNUR.js';
+export { C as ClientTransportConfig, K as KitClient, e as KitClientConfig, f as KitConfig, g as KitConfigInput, h as KitConfigSchema, j as KitTransportConfig, k as KitTransportConfigInput, l as createSvelteKitNavAdapter, r as resolveKitConfig, m as resolveKitTransportConfig } from './index-M00CsNUR.js';
 import { d as defineCrud, s as setAllModulesLocale } from './kit-i18n-CgpNTh9G.js';
 export { C as CrudApiDef, a as CrudFieldDef, b as CrudFieldOption, c as CrudFieldOptions, e as CrudFieldType, f as CrudFieldValidation, g as CrudFilterParams, h as CrudOperations, i as CrudPaginatedResult, j as CrudPaginationParams, k as CrudResourceDef, l as CrudTableColumn, m as CrudText, r as resolveOptions, n as resolveText } from './kit-i18n-CgpNTh9G.js';
-import { S as SessionData, k as RouteGuard, l as SessionLike, h as HandleConfig, C as CorsConfig, M as Middleware } from './kit-types-BHlDNNpd.js';
-export { A as ApiResponse, a as AuthOperations, b as AuthOperationsProvider, F as FormError, c as FormValidationResult, G as GuardConfig, d as GuardResult, H as HaiRequestEvent, e as HandleA2AConfig, f as HandleA2AOperations, g as HandleAuthConfig, i as HookCryptoConfig, m as MemoryRateLimitStore, j as MiddlewareContext, R as RateLimitConfig, n as RateLimitEntry, o as RateLimitStore, T as TransportEncryptionOptions, r as rateLimitMiddleware } from './kit-types-BHlDNNpd.js';
+import { S as SessionData, k as RouteGuard, l as SessionLike, h as HandleConfig, C as CorsConfig, M as Middleware } from './kit-types-XUMggtk_.js';
+export { A as ApiResponse, a as AuthOperations, b as AuthOperationsProvider, F as FormError, c as FormValidationResult, G as GuardConfig, d as GuardResult, H as HaiRequestEvent, e as HandleA2AConfig, f as HandleA2AOperations, g as HandleAuthConfig, i as HookCryptoConfig, m as MemoryRateLimitStore, j as MiddlewareContext, R as RateLimitConfig, n as RateLimitEntry, o as RateLimitStore, T as TransportEncryptionOptions, r as rateLimitMiddleware } from './kit-types-XUMggtk_.js';
 import { RequestEvent, Cookies, Handle, RequestHandler } from '@sveltejs/kit';
-import { T as TransportCryptoServiceLike } from './kit-crypto-types-C-gEvx04.js';
-export { C as CryptoCsrfConfig, a as CryptoServiceLike, E as EncryptedCookieConfig, b as EncryptedPayload, c as TransportEncryptionConfig, d as TransportEncryptionManager, e as TransportKeyPair, W as WebhookVerifyConfig } from './kit-crypto-types-C-gEvx04.js';
+import { CryptoFunctions } from '@h-ai/crypto';
+export { EncryptedPayload, TransportEncryptionManager, TransportKeyPair } from '@h-ai/crypto';
+import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import { z } from 'zod';
-import * as zod_v4_core from 'zod/v4/core';
 import { HaiError } from '@h-ai/core';
 export { A2AApiKeyAuthConfig, KitA2AHandlerConfig, ResolvedA2AConfig, createA2AApiKeyAuthenticator, createA2AHandler, createAgentCardHandler, handleA2ARequest, resolveA2AConfig } from './modules/a2a/index.js';
-export { createCsrfManager, createEncryptedCookie, createKeyExchangeHandler, createTransportEncryption, isValidEncryptedPayload, signRequest, transportEncryptionMiddleware, verifyWebhookSignature } from './modules/crypto/index.js';
+export { CryptoCsrfConfig, CryptoServiceLike, EncryptedCookieConfig, TransportEncryptionConfig, WebhookVerifyConfig, createCsrfManager, createEncryptedCookie, signRequest, transportEncryptionMiddleware, verifyWebhookSignature } from './modules/crypto/index.js';
 import '@h-ai/iam';
 
 /**
@@ -349,7 +349,7 @@ interface CookieProxyConfig {
     /** 需要加密的 Cookie 名称集合 */
     names: Set<string>;
     /** 对称加密服务（SM4） */
-    symmetric: TransportCryptoServiceLike['symmetric'];
+    symmetric: CryptoFunctions['symmetric'];
     /** 加密密钥（32 字符十六进制） */
     encryptionKey: string;
 }
@@ -423,73 +423,6 @@ declare function createHandle(config?: HandleConfig): Handle;
  */
 declare function sequence(...handles: Handle[]): Handle;
 
-/**
- * @h-ai/kit — 契约 Handler
- *
- * 基于 EndpointDef 契约创建类型安全的 API handler：
- * - 自动从 request body/query 提取参数
- * - 自动使用契约的 input schema 校验
- * - handler 返回值类型必须匹配 output schema
- * - 自动包装为标准 kit.response.ok() 响应
- * @module kit-contract
- */
-
-/**
- * API 端点契约定义
- *
- * 客户端和服务端共享的唯一真相源，保证路径、入参、出参编译时一致。
- */
-interface EndpointDef<TInput = unknown, TOutput = unknown> {
-    /** HTTP 方法 */
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-    /** 相对路径（相对于 API 前缀，如 '/auth/login'） */
-    path: string;
-    /** 入参 Zod Schema（GET 请求为 query params，其他为 body） */
-    input: z.ZodType<TInput>;
-    /** 出参 Zod Schema */
-    output: z.ZodType<TOutput>;
-    /** 是否需要认证（默认 true） */
-    requireAuth?: boolean;
-    /** OpenAPI 描述元数据（可选） */
-    meta?: {
-        summary?: string;
-        tags?: string[];
-    };
-}
-/**
- * 辅助函数：创建端点定义（获得类型推导）
- *
- * @param def - 端点定义对象
- * @returns 同一个对象（类型安全）
- */
-declare function defineEndpoint<TInput, TOutput>(def: EndpointDef<TInput, TOutput>): EndpointDef<TInput, TOutput>;
-/**
- * 基于契约创建 API handler
- *
- * - 自动从 request body/query 提取参数
- * - 自动使用契约的 input schema 校验
- * - handler 返回值类型必须匹配 output schema
- * - 自动包装为标准 kit.response.ok() 响应
- *
- * @param endpoint - 端点契约定义
- * @param fn - 业务处理函数（接收校验后的 input 和 RequestEvent）
- * @returns SvelteKit RequestHandler
- *
- * @example
- * ```ts
- * import { iamEndpoints } from '@h-ai/iam/api'
- *
- * export const POST = kit.fromContract(iamEndpoints.login, async (input, event) => {
- *   const result = await iam.auth.login(input)
- *   if (!result.success) {
- *     throw kit.response.error('AUTH_FAILED', result.error.message, 401)
- *   }
- *   return result.data
- * })
- * ```
- */
-declare function fromContract<TInput, TOutput>(endpoint: EndpointDef<TInput, TOutput>, fn: (input: TInput, event: RequestEvent) => Promise<TOutput>): RequestHandler;
-
 /**
  * @h-ai/kit — API Handler 包装器
  *
@@ -696,6 +629,9 @@ declare function fromError(haiError: HaiError, requestId?: string): Response;
  * @h-ai/kit — 请求数据验证
  *
  * 基于 Zod 的请求数据验证工具，支持表单/JSON Body、URL 查询参数与路由参数。
+ * Zod 默认错误消息的本地化规则委托给 `core.zodValidation`，避免 kit / serv
+ * 等模块重复维护同一套 issue 解析与消息映射逻辑；模块前缀映射也统一交给
+ * `core.zodValidation.createPrefixedZodMessageGetter()` 处理。
  * 每种数据源都提供两类 API：
  * - 安全返回：`FormValidationResult`
  * - 失败抛出：`OrFail`（抛出 `Response` 以走 SvelteKit 控制流）
@@ -799,8 +735,6 @@ declare const kit: {
     sequence: typeof sequence;
     /** API Handler 包装器（自动错误边界） */
     handler: typeof handler;
-    /** 基于 API 契约创建类型安全的路由 handler */
-    fromContract: typeof fromContract;
     guard: {
         /** 要求权限，不满足时 throw Response（SvelteKit 控制流） */
         require: typeof requirePermission;
@@ -858,6 +792,13 @@ declare const kit: {
     client: {
         /** 创建统一客户端（CSRF + 传输加密透明合并） */
         create: typeof createKitClient;
+        /**
+         * 用解析后的 {@link KitConfig} 一键安装浏览器端传输加密
+         * （应用层推荐入口；内部预热 crypto 并调用 installBrowserTransportFetch）
+         */
+        installBrowserTransport: typeof installBrowserTransport;
+        /** 底层入口：直接传 transport 配置安装浏览器全局 fetch 包装 */
+        installBrowserTransportFetch: typeof installBrowserTransportFetch;
     };
     auth: {
         /** 服务端登录（密码）：内部调用 iam.auth.login + 自动写入 Token Cookie */
@@ -878,8 +819,6 @@ declare const kit: {
         clearBrowserToken: typeof clearBrowserToken;
         /** 创建浏览器端 Token 存储器（自定义 key 时使用） */
         createTokenStore: typeof createTokenStore;
-        /** 创建浏览器端同源请求自动附加 Authorization 的 HandleFetch */
-        createHandleFetch: typeof createHandleFetch;
     };
     crud: {
         /** 定义 CRUD 资源（声明式配置 → 操作对象） */
@@ -960,4 +899,4 @@ interface LoggingMiddlewareConfig {
  */
 declare function loggingMiddleware(config?: LoggingMiddlewareConfig): Middleware;
 
-export { type AuthGuardConfig, type CookieProxyConfig, CorsConfig, type EndpointDef, HandleConfig, IdParamSchema, type LoggingMiddlewareConfig, Middleware, PaginationQuerySchema, type PermissionGuardConfig, type RoleGuardConfig, RouteGuard, SessionData, type SessionGuardConfig, SessionLike, TransportCryptoServiceLike, allGuards, anyGuard, assertPermission, authGuard, conditionalGuard, corsMiddleware, createEncryptedCookieProxy, createHandle, createKitClient, defineCrud, defineEndpoint, hasPermission, kit, loggingMiddleware, matchPermission, notGuard, permissionGuard, requirePermission, roleGuard, sequence, sessionGuard, withPermission };
+export { type AuthGuardConfig, type CookieProxyConfig, CorsConfig, HandleConfig, IdParamSchema, type LoggingMiddlewareConfig, Middleware, PaginationQuerySchema, type PermissionGuardConfig, type RoleGuardConfig, RouteGuard, SessionData, type SessionGuardConfig, SessionLike, allGuards, anyGuard, assertPermission, authGuard, conditionalGuard, corsMiddleware, createEncryptedCookieProxy, createHandle, createKitClient, defineCrud, hasPermission, installBrowserTransport, installBrowserTransportFetch, kit, loggingMiddleware, matchPermission, notGuard, permissionGuard, requirePermission, roleGuard, sequence, sessionGuard, withPermission };