@h-ai/kit 0.1.0-alpha.67 → 0.1.0-alpha.69

package/dist/index.d.ts

@@ -1,20 +1,22 @@
-import { c as createKitClient, a as createKitAuthActions, i as installBrowserTransport, b as installBrowserTransportFetch, q as login, t as loginWithOtp, u as loginWithLdap, v as loginWithApiKey, w as registerAndLogin, x as logout, s as setBrowserToken, d as clearBrowserToken, e as createTokenStore } from './index-B7s-0mZl.js';
-export { C as ClientTransportConfig, K as KitClient, f as KitClientConfig, g as KitConfig, h as KitConfigInput, j as KitConfigSchema, k as KitServerConfig, l as KitServerConfigInput, m as KitTransportConfig, n as KitTransportConfigInput, o as createSvelteKitNavAdapter, r as resolveKitConfig, p as resolveKitTransportConfig } from './index-B7s-0mZl.js';
-import { d as defineCrud, s as setAllModulesLocale } from './kit-i18n-D9Qqk-1k.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-D9Qqk-1k.js';
-import { S as SessionData, k as RouteGuard, l as SessionLike, h as HandleConfig, C as CorsConfig, M as Middleware } from './kit-types-ByWdbCeO.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-ByWdbCeO.js';
-import * as _sveltejs_kit from '@sveltejs/kit';
-import { RequestEvent, Cookies, Handle, RequestHandler } from '@sveltejs/kit';
+import { c as createKitClient, a as createKitAuthActions, i as installBrowserTransport, b as installBrowserTransportFetch, o as login, p as loginWithOtp, q as loginWithLdap, t as loginWithApiKey, u as registerAndLogin, v as logout, s as setBrowserToken, d as clearBrowserToken } from './kit-client-auth-B5y1g5_A.js';
+export { C as ClientTransportConfig, K as KitClient, e as KitClientConfig, f as KitConfig, g as KitConfigInput, h as KitConfigSchema, j as KitServerConfig, k as KitServerConfigInput, l as KitTransportConfig, m as KitTransportConfigInput, r as resolveKitConfig, n as resolveKitTransportConfig } from './kit-client-auth-B5y1g5_A.js';
+import { d as defineCrud, s as setAllModulesLocale } from './kit-i18n-DEzmzE5T.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-DEzmzE5T.js';
+import { S as SessionData, l as SessionLike, h as HandleConfig, r as rateLimitMiddleware, m as createCacheRateLimitStore, n as createMemoryRateLimitStore } from './kit-types-DQYqP1Cn.js';
+export { A as ApiResponse, a as AuthOperations, b as AuthOperationsProvider, C as CorsConfig, 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, o as MemoryRateLimitStore, M as Middleware, j as MiddlewareContext, p as RateLimitCache, R as RateLimitConfig, q as RateLimitEntry, s as RateLimitStore, k as RouteGuard, T as TransportEncryptionOptions } from './kit-types-DQYqP1Cn.js';
 import { CryptoFunctions } from '@h-ai/crypto';
 export { EncryptedPayload, TransportEncryptionManager, TransportKeyPair } from '@h-ai/crypto';
+import { FeedbackFunctions, FeedbackContext } from '@h-ai/feedback';
+import * as _sveltejs_kit from '@sveltejs/kit';
+import { Handle, RequestEvent, RequestHandler } from '@sveltejs/kit';
+import * as _h_ai_core from '@h-ai/core';
+import { HaiError } from '@h-ai/core';
 import * as zod_v4_core from 'zod/v4/core';
 import * as zod from 'zod';
 import { z } from 'zod';
 import { IamFunctions } from '@h-ai/iam';
-import { HaiError } from '@h-ai/core';
-export { A2AApiKeyAuthConfig, KitA2AHandlerConfig, ResolvedA2AConfig, createA2AApiKeyAuthenticator, createA2AHandler, createAgentCardHandler, handleA2ARequest, resolveA2AConfig } from './modules/a2a/index.js';
-export { CryptoCsrfConfig, CryptoServiceLike, EncryptedCookieConfig, TransportEncryptionConfig, WebhookVerifyConfig, createCsrfManager, createEncryptedCookie, signRequest, transportEncryptionMiddleware, verifyWebhookSignature } from './modules/crypto/index.js';
+export { A as A2AApiKeyAuthConfig, K as KitA2AHandlerConfig, R as ResolvedA2AConfig } from './kit-a2a-types-DwcmE668.js';
+export { C as CryptoCsrfConfig, a as CryptoServiceLike, E as EncryptedCookieConfig, T as TransportEncryptionConfig, W as WebhookVerifyConfig } from './kit-crypto-types-Cwj9bprV.js';
 import '@h-ai/api-contract';
 
 /**
@@ -26,6 +28,13 @@ import '@h-ai/api-contract';
 
 /**
  * 认证守卫配置
+ * @example
+ * ```ts
+ * import type { AuthGuardConfig } from '@h-ai/kit'
+ *
+ * const value: AuthGuardConfig = { apiMode: true }
+ * void value
+ * ```
  */
 interface AuthGuardConfig {
     /** 未登录时重定向 URL（默认 `'/login'`） */
@@ -35,6 +44,13 @@ interface AuthGuardConfig {
 }
 /**
  * 会话守卫配置
+ * @example
+ * ```ts
+ * import type { SessionGuardConfig } from '@h-ai/kit'
+ *
+ * const value: SessionGuardConfig = { validateSession: async () => null }
+ * void value
+ * ```
  */
 interface SessionGuardConfig {
     /** 会话校验函数（通常由应用注入 iam.auth.verifyToken 封装） */
@@ -44,122 +60,6 @@ interface SessionGuardConfig {
     /** 为 `true` 时返回 JSON 401 而非重定向（适用于 API 路由） */
     apiMode?: boolean;
 }
-/**
- * 创建认证守卫
- *
- * 检查会话是否存在；未认证时：
- * - 页面模式：重定向到 `loginUrl`，并携带 `returnUrl` 参数以便登录后返回。
- * - API 模式：返回 JSON `{ allowed: false, status: 401 }`。
- *
- * @param config - 守卫配置
- * @returns RouteGuard 实例
- *
- * @example
- * ```ts
- * // Hook 配置
- * guards: [
- *   { guard: kit.guard.auth({ apiMode: true }), paths: ['/api/*'] },
- *   { guard: kit.guard.auth(), paths: ['/dashboard/*'] },
- * ]
- * ```
- */
-declare function authGuard(config?: AuthGuardConfig): RouteGuard;
-/**
- * 创建会话守卫（支持 Bearer + 固定 Access Token Cookie 自动恢复）。
- *
- * 处理流程：
- * 1. 若上游已注入 session，直接放行
- * 2. 否则从 request/cookies 解析 token（Bearer 优先）
- * 3. 调用 validateSession 恢复并写入 event.locals.session
- * 4. 失败则按页面/API模式返回重定向或 401
- */
-declare function sessionGuard(config: SessionGuardConfig): RouteGuard;
-
-/**
- * @h-ai/kit — 组合守卫
- *
- * 提供守卫组合器，支持 AND（allGuards）/ OR（anyGuard）/ NOT（notGuard）/ 条件分支（conditionalGuard）等逻辑组合，将多个 RouteGuard 聚合为一个。
- * @module kit-compose
- */
-
-/**
- * 所有守卫都通过才允许访问（AND 逻辑）
- *
- * 短路求值：第一个拒绝的守卫结果会被直接返回。
- *
- * @param guards - 需要全部通过的守卫列表
- * @returns 组合后的 RouteGuard
- *
- * @example
- * ```ts
- * const adminOnly = kit.guard.all(
- *   kit.guard.auth(),
- *   kit.guard.role({ roles: ['admin'] }),
- * )
- * ```
- */
-declare function allGuards(...guards: RouteGuard[]): RouteGuard;
-/**
- * 任意一个守卫通过就允许访问（OR 逻辑）
- *
- * 短路求值：第一个允许的守卫结果会被直接返回。
- * 全部拒绝时返回最后一个拒绝结果。
- *
- * @param guards - 守卫列表
- * @returns 组合后的 RouteGuard
- *
- * @example
- * ```ts
- * const canView = kit.guard.any(
- *   kit.guard.role({ roles: ['admin'] }),
- *   kit.guard.permission({ permissions: ['article:read'] }),
- * )
- * ```
- */
-declare function anyGuard(...guards: RouteGuard[]): RouteGuard;
-/**
- * 取反守卫
- *
- * 将原守卫的判定逻辑反转：原本放行变为拒绝，原本拒绝变为放行。
- * 典型场景：「仅未登录用户可访问登录页」。
- *
- * @param guard - 需要取反的守卫
- * @param options - 拒绝时的重定向/消息
- * @param options.redirect - 拒绝时重定向 URL
- * @param options.message - 拒绝时的提示消息
- * @returns 取反后的 RouteGuard
- *
- * @example
- * ```ts
- * // 仅未登录用户可访问
- * const guestOnly = kit.guard.not(kit.guard.auth(), { redirect: '/dashboard' })
- * ```
- */
-declare function notGuard(guard: RouteGuard, options?: {
-    redirect?: string;
-    message?: string;
-}): RouteGuard;
-/** 条件判断函数类型：返回 `true` 时才执行后续守卫 */
-type ConditionFn = (event: RequestEvent, session: SessionData | undefined) => boolean | Promise<boolean>;
-/**
- * 条件守卫
- *
- * 仅当 `condition` 返回 `true` 时才执行 `guard`；否则直接放行。
- *
- * @param condition - 条件判断函数
- * @param guard - 条件满足时执行的守卫
- * @returns 包装后的 RouteGuard
- *
- * @example
- * ```ts
- * // 仅 POST 请求检查 CSRF
- * kit.guard.conditional(
- *   (event) => event.request.method === 'POST',
- *   csrfGuard,
- * )
- * ```
- */
-declare function conditionalGuard(condition: ConditionFn, guard: RouteGuard): RouteGuard;
 
 /**
  * @h-ai/kit — 权限守卫
@@ -170,6 +70,13 @@ declare function conditionalGuard(condition: ConditionFn, guard: RouteGuard): Ro
 
 /**
  * 权限守卫配置
+ * @example
+ * ```ts
+ * import type { PermissionGuardConfig } from '@h-ai/kit'
+ *
+ * const value: PermissionGuardConfig = { permissions: ['article:read'] }
+ * void value
+ * ```
  */
 interface PermissionGuardConfig {
     /** 需要的权限列表（默认 OR 逻辑，满足任一即通过） */
@@ -181,24 +88,6 @@ interface PermissionGuardConfig {
     /** 为 `true` 时返回 JSON 403 而非重定向 */
     apiMode?: boolean;
 }
-/**
- * 创建权限守卫
- *
- * 检查用户 `session.permissions` 是否满足配置中的权限要求。
- * 支持通配符匹配：`admin:*` 可匹配 `admin:read`、`admin:write` 等。
- * 未认证时返回 401；权限不匹配时根据 `apiMode` 返回 JSON 403 或重定向。
- *
- * @param config - 权限守卫配置
- * @returns RouteGuard 实例
- *
- * @example
- * ```ts
- * guards: [
- *   { guard: kit.guard.permission({ permissions: ['user:read', 'user:write'], requireAll: true }), paths: ['/api/users/*'] },
- * ]
- * ```
- */
-declare function permissionGuard(config: PermissionGuardConfig): RouteGuard;
 /**
  * 匹配权限
  *
@@ -209,6 +98,13 @@ declare function permissionGuard(config: PermissionGuardConfig): RouteGuard;
  * @param required - 需要的权限码
  * @param userPermissions - 用户已有的权限列表
  * @returns 是否匹配
+ * @example
+ * ```ts
+ * import { matchPermission } from '@h-ai/kit'
+ *
+ * const allowed = matchPermission('article:read', ['article:*'])
+ * void allowed
+ * ```
  */
 declare function matchPermission(required: string, userPermissions: string[]): boolean;
 /**
@@ -219,35 +115,15 @@ declare function matchPermission(required: string, userPermissions: string[]): b
  * @param session - 当前会话数据，null/undefined 视为无权限
  * @param permission - 需要的权限码，如 `user:read`
  * @returns 是否拥有权限
- *
  * @example
  * ```ts
- * if (kit.guard.check(locals.session, 'user:read')) {
- *   // 有权限
- * }
- * ```
- */
-declare function hasPermission(session: SessionLike | null | undefined, permission: string): boolean;
-/**
- * 断言会话具有指定权限，不满足时返回 403 Response
+ * import { kit } from '@h-ai/kit'
  *
- * 适用于 SvelteKit API Handler 内部，不满足权限时直接返回 JSON 错误响应。
- * 调用者需检查返回值：若有返回值则表示权限不足，应直接 return。
- *
- * @param session - 当前会话数据，null/undefined 视为未认证
- * @param permission - 需要的权限码，如 `user:create`
- * @returns 权限不足时返回 Response；有权限时返回 undefined
- *
- * @example
- * ```ts
- * export const POST: RequestHandler = async ({ locals }) => {
- *   const denied = kit.guard.assertPermission(locals.session, 'user:create')
- *   if (denied) return denied
- *   // ... 正常逻辑
- * }
+ * const allowed = kit.guard.check({ userId: 'user_1', roles: ['editor'], permissions: ['article:read'] }, 'article:read')
+ * void allowed
  * ```
  */
-declare function assertPermission(session: SessionLike | null | undefined, permission: string): Response | undefined;
+declare function hasPermission(session: SessionLike | null | undefined, permission: string): boolean;
 /**
  * 要求会话具有指定权限，不满足时 throw Response
  *
@@ -257,47 +133,14 @@ declare function assertPermission(session: SessionLike | null | undefined, permi
  * @param session - 当前会话数据，null/undefined 视为未认证
  * @param permission - 需要的权限码，如 `user:create`
  * @throws Response - 未认证 401 / 无权限 403
- *
  * @example
  * ```ts
- * export const GET = kit.handler(async ({ locals }) => {
- *   kit.guard.require(locals.session, 'user:read')
- *   // 执行到这里说明权限已通过
- *   return kit.response.ok(data)
- * })
- * ```
- */
-declare function requirePermission(session: SessionLike | null | undefined, permission: string): void;
-/**
- * 权限守卫高阶函数包装器
+ * import { kit } from '@h-ai/kit'
  *
- * 将权限检查从业务逻辑中提取到装饰层，handler 内部无需关心权限。
- * 未认证返回 401、无权限返回 403（均通过 SvelteKit throw 控制流抛出）。
- *
- * 适用于 page load、API handler 等所有 SvelteKit server 函数。
- *
- * @param permission - 需要的权限码，如 `'user:read'`
- * @param handler - 原始处理函数
- * @returns 包装后的处理函数（签名不变）
- *
- * @example
- * ```ts
- * // +page.server.ts
- * export const load = kit.guard.withPermission('user:read', async ({ locals }) => {
- *   const result = await iam.user.listUsers()
- *   return { users: result.success ? result.data.items : [] }
- * })
- *
- * // +server.ts (API handler)
- * export const GET = kit.handler(kit.guard.withPermission('user:list', async ({ locals }) => {
- *   const result = await iam.user.listUsers()
- *   return kit.response.ok(result.data)
- * }))
+ * kit.guard.require({ userId: 'user_1', roles: ['editor'], permissions: ['article:read'] }, 'article:read') // 拒绝时抛出 Response，由框架传递。
  * ```
  */
-declare function withPermission<TEvent extends {
-    locals: Record<string, unknown>;
-}, TReturn>(permission: string, handler: (event: TEvent) => Promise<TReturn>): (event: TEvent) => Promise<TReturn>;
+declare function requirePermission(session: SessionLike | null | undefined, permission: string): void;
 
 /**
  * @h-ai/kit — 角色守卫
@@ -308,6 +151,13 @@ declare function withPermission<TEvent extends {
 
 /**
  * 角色守卫配置
+ * @example
+ * ```ts
+ * import type { RoleGuardConfig } from '@h-ai/kit'
+ *
+ * const value: RoleGuardConfig = { roles: ['editor'] }
+ * void value
+ * ```
  */
 interface RoleGuardConfig {
     /** 需要的角色列表（默认 OR 逻辑，满足任一即通过） */
@@ -319,23 +169,6 @@ interface RoleGuardConfig {
     /** 为 `true` 时返回 JSON 403 而非重定向 */
     apiMode?: boolean;
 }
-/**
- * 创建角色守卫
- *
- * 检查用户 `session.roles` 是否满足配置中的角色要求。
- * 未认证时返回 401；角色不匹配时根据 `apiMode` 返回 JSON 403 或重定向。
- *
- * @param config - 角色守卫配置
- * @returns RouteGuard 实例
- *
- * @example
- * ```ts
- * guards: [
- *   { guard: kit.guard.role({ roles: ['admin'], apiMode: true }), paths: ['/api/admin/*'] },
- * ]
- * ```
- */
-declare function roleGuard(config: RoleGuardConfig): RouteGuard;
 
 /**
  * @h-ai/kit — Cookie 加密代理
@@ -346,6 +179,15 @@ declare function roleGuard(config: RoleGuardConfig): RouteGuard;
 
 /**
  * Cookie 加密代理配置
+ * @example
+ * ```ts
+ * import type { CookieProxyConfig } from '@h-ai/kit'
+ * import { crypto } from '@h-ai/crypto'
+ *
+ * function config(encryptionKey: string): CookieProxyConfig {
+ *   return { names: new Set(['session']), symmetric: crypto.symmetric, encryptionKey }
+ * }
+ * ```
  */
 interface CookieProxyConfig {
     /** 需要加密的 Cookie 名称集合 */
@@ -355,20 +197,6 @@ interface CookieProxyConfig {
     /** 加密密钥（32 字符十六进制） */
     encryptionKey: string;
 }
-/**
- * 创建加密 Cookie 代理
- *
- * 返回一个 Proxy 包装的 Cookies 对象：
- * - `get(name)` —— 若 name 在加密列表中，自动解密后返回明文；格式或解密失败时返回 `undefined`
- * - `set(name, value, opts)` —— 若 name 在加密列表中，自动加密后存储；加密失败时拒绝写入
- * - `delete(name, opts)` —— 透传，无需解密
- * - 其他方法原样透传
- *
- * @param cookies - SvelteKit 原始 Cookies 对象
- * @param config - 加密配置
- * @returns 代理后的 Cookies 对象（类型不变）
- */
-declare function createEncryptedCookieProxy(cookies: Cookies, config: CookieProxyConfig): Cookies;
 
 /**
  * @h-ai/kit — SvelteKit Handle Hook
@@ -393,19 +221,12 @@ declare function createEncryptedCookieProxy(cookies: Cookies, config: CookieProx
  *
  * @param config - Handle 配置（均有合理默认值，可零配置使用）
  * @returns SvelteKit Handle 函数
- *
  * @example
  * ```ts
- * export const handle = kit.createHandle({
- *   auth: {
- *     verifyToken: validateSession,
- *     loginUrl: '/auth/login',
- *     protectedPaths: ['/admin/*', '/api/*'],
- *     publicPaths: ['/api/auth/*', '/api/public/*'],
- *   },
- *   rateLimit: { maxRequests: 100 },
- *   crypto: { crypto, transport: true },
- * })
+ * import { kit } from '@h-ai/kit'
+ *
+ * const handle = kit.createHandle({ auth: { verifyToken: async () => null, protectedPaths: ['/admin/**'] } })
+ * void handle
  * ```
  */
 declare function createHandle(config?: HandleConfig): Handle;
@@ -416,16 +237,58 @@ declare function createHandle(config?: HandleConfig): Handle;
  *
  * @param handles - 待组合的 handle 函数列表
  * @returns 组合后的单一 Handle 函数
- *
  * @example
  * ```ts
- * const haiHandle = kit.createHandle({ ... })
- * export const handle = kit.sequence(i18nHandle, haiHandle)
+ * import { kit } from '@h-ai/kit'
+ *
+ * const handle = kit.sequence(kit.createHandle({ logging: true }), kit.createHandle())
+ * void handle
  * ```
  */
 declare function sequence(...handles: Handle[]): Handle;
 
-/** 应用路由直接导出对应 handler；认证 ops 仍由 createHandle 注入。 */
+/** 可直接挂到 SvelteKit catch-all 路由的反馈适配，无 serv 或 Svelte UI 依赖。 */
+
+/**
+ * 反馈服务及可信范围解析。resolveContext 必须使用已验证 session/宿主策略。
+ * @example
+ * ```ts
+ * import type { FeedbackHandlerOptions } from '@h-ai/kit'
+ * import { feedback } from '@h-ai/feedback'
+ * const options: FeedbackHandlerOptions = { feedback, resolveContext: () => null }
+ * // 应用实现真实 session 映射；null 拒绝访问，不能从 JSON 取得身份。
+ * ```
+ */
+interface FeedbackHandlerOptions {
+    readonly feedback: FeedbackFunctions;
+    readonly resolveContext: (event: RequestEvent) => FeedbackContext | null | Promise<FeedbackContext | null>;
+    readonly basePath?: string;
+}
+/**
+ * 装配反馈 REST 路由；默认路径 /api/feedback，由宿主 handle 保持 CSRF、认证和传输加密。
+ * @param options - 已初始化服务与可信范围映射。
+ * @returns 可赋值给 catch-all 路由 GET/POST/PATCH 的同一 handler。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ * import { feedback } from '@h-ai/feedback'
+ * const handler = kit.createFeedbackHandler({ feedback, resolveContext: () => null })
+ * // 路由 export const GET = handler；真实应用从受信 session 返回范围，null 默认拒绝。
+ * ```
+ */
+declare function createFeedbackHandler(options: FeedbackHandlerOptions): RequestHandler;
+
+/**
+ * 应用路由直接导出对应 handler；认证 ops 仍由 createHandle 注入。
+ * @param iam - 已由应用初始化的 IAM 服务对象。
+ * @returns 标准认证端点的 RequestHandler 集合。
+ * @example 模块内部上下文
+ * ```ts
+ * function build(iam: IamFunctions) {
+ *   return createAuthApi(iam) // 调用方负责初始化 IAM；工厂只装配 handler。
+ * }
+ * ```
+ */
 declare function createAuthApi(iam: IamFunctions): {
     publicConfig: _sveltejs_kit.RequestHandler;
     login: _sveltejs_kit.RequestHandler;
@@ -455,13 +318,12 @@ declare function createAuthApi(iam: IamFunctions): {
  *
  * @param fn - 业务处理函数
  * @returns SvelteKit RequestHandler
- *
  * @example
  * ```ts
- * export const GET = kit.handler(async ({ locals }) => {
- *   kit.guard.require(locals.session, 'user:read')
- *   return kit.response.ok(await getUsers())
- * })
+ * import { kit } from '@h-ai/kit'
+ *
+ * const GET = kit.handler(() => kit.response.ok({ healthy: true }))
+ * void GET
  * ```
  */
 declare function handler(fn: (event: RequestEvent) => Promise<Response> | Response): RequestHandler;
@@ -482,10 +344,12 @@ declare function handler(fn: (event: RequestEvent) => Promise<Response> | Respon
  * @param data - 响应数据，序列化为 JSON
  * @param requestId - 可选请求 ID，用于链路追踪
  * @returns `{ success: true, data, requestId }` 格式的 JSON Response
- *
  * @example
  * ```ts
- * return kit.response.ok({ id: '1', name: 'Alice' })
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.ok({ id: 'article_1' })
+ * void response.status
  * ```
  */
 declare function ok<T>(data: T, requestId?: string): Response;
@@ -495,10 +359,12 @@ declare function ok<T>(data: T, requestId?: string): Response;
  * @param data - 新创建的资源数据
  * @param requestId - 可选请求 ID
  * @returns `{ success: true, data }` 格式的 JSON Response（status 201）
- *
  * @example
  * ```ts
- * return kit.response.created({ id: 'new_1' })
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.created({ id: 'article_1' })
+ * void response.status
  * ```
  */
 declare function created<T>(data: T, requestId?: string): Response;
@@ -508,6 +374,13 @@ declare function created<T>(data: T, requestId?: string): Response;
  * 通常用于 DELETE 成功或无返回值的更新操作。
  *
  * @returns 空 body、status 204 的 Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.noContent()
+ * void response.status
+ * ```
  */
 declare function noContent(): Response;
 /**
@@ -519,10 +392,12 @@ declare function noContent(): Response;
  * @param requestId - 可选请求 ID
  * @param details - 可选额外详情
  * @returns `{ success: false, error: { code, message, details } }` 格式的 JSON Response
- *
  * @example
  * ```ts
- * return kit.response.error('QUOTA_EXCEEDED', '配额已用尽', 429)
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.error('ARTICLE_MISSING', 'Article missing', 404)
+ * void response.status
  * ```
  */
 declare function error(code: string, message: string, status?: number, requestId?: string, details?: unknown): Response;
@@ -533,6 +408,13 @@ declare function error(code: string, message: string, status?: number, requestId
  * @param requestId - 可选请求 ID
  * @param details - 可选额外详情
  * @returns error code 为 `'BAD_REQUEST'` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.badRequest('Invalid article')
+ * void response.status
+ * ```
  */
 declare function badRequest(message: string, requestId?: string, details?: unknown): Response;
 /**
@@ -541,6 +423,13 @@ declare function badRequest(message: string, requestId?: string, details?: unkno
  * @param message - 错误消息，默认 `'Authentication required'`
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'UNAUTHORIZED'` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.unauthorized()
+ * void response.status
+ * ```
  */
 declare function unauthorized(message?: string, requestId?: string): Response;
 /**
@@ -549,6 +438,13 @@ declare function unauthorized(message?: string, requestId?: string): Response;
  * @param message - 错误消息，默认 `'Access denied'`
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'FORBIDDEN'` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.forbidden()
+ * void response.status
+ * ```
  */
 declare function forbidden(message?: string, requestId?: string): Response;
 /**
@@ -557,6 +453,13 @@ declare function forbidden(message?: string, requestId?: string): Response;
  * @param message - 错误消息，默认 `'Resource not found'`
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'NOT_FOUND'` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.notFound()
+ * void response.status
+ * ```
  */
 declare function notFound(message?: string, requestId?: string): Response;
 /**
@@ -565,6 +468,13 @@ declare function notFound(message?: string, requestId?: string): Response;
  * @param message - 冲突描述（如重复创建等）
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'CONFLICT'` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.conflict('Already updated')
+ * void response.status
+ * ```
  */
 declare function conflict(message: string, requestId?: string): Response;
 /**
@@ -573,12 +483,12 @@ declare function conflict(message: string, requestId?: string): Response;
  * @param errors - 字段级别的验证错误列表
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'VALIDATION_ERROR'`，details 包含 `errors` 数组
- *
  * @example
  * ```ts
- * return kit.response.validationError([
- *   { field: 'email', message: '格式无效' },
- * ])
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.validationError([{ field: 'title', message: 'Title is required' }])
+ * void response.status
  * ```
  */
 declare function validationError(errors: Array<{
@@ -591,6 +501,13 @@ declare function validationError(errors: Array<{
  * @param message - 错误消息，默认 `'Internal server error'`
  * @param requestId - 可选请求 ID
  * @returns error code 为 `'INTERNAL_ERROR'` 的 JSON Response
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.internalError()
+ * void response.status
+ * ```
  */
 declare function internalError(message?: string, requestId?: string): Response;
 /**
@@ -599,10 +516,12 @@ declare function internalError(message?: string, requestId?: string): Response;
  * @param url - 目标 URL
  * @param status - HTTP 状态码，默认 302；常用 303（POST 后重定向）
  * @returns 带 `Location` 头的空 body Response
- *
  * @example
  * ```ts
- * return kit.response.redirect('/dashboard', 303)
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.redirect('/articles', 303)
+ * void response.status
  * ```
  */
 declare function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
@@ -616,14 +535,12 @@ declare function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Re
  * @param httpStatusMap - 模块导出的错误码 → HTTP 状态码映射表（如 IamErrorHttpStatus）
  * @param requestId - 可选请求 ID，用于链路追踪
  * @returns 标准化 JSON Response
- *
  * @example
  * ```ts
- * // 无映射（默认 400）
- * return kit.response.fromResult(result)
+ * import { kit } from '@h-ai/kit'
  *
- * // 带模块错误码映射
- * return kit.response.fromResult(result, IamErrorHttpStatus)
+ * const response = kit.response.fromResult({ success: true, data: { id: 'article_1' } })
+ * void response.status
  * ```
  */
 declare function fromResult<T>(result: {
@@ -637,6 +554,19 @@ declare function fromResult<T>(result: {
         [key: string]: unknown;
     };
 }, httpStatusMap?: Record<number | string, number>, requestId?: string): Response;
+/**
+ * 按模块错误的 HTTP 状态构建安全的统一 API 错误响应。
+ * @param haiError - 包含 code、message 和可选 httpStatus 的模块错误。
+ * @param requestId - 可选的请求追踪标识。
+ * @returns 包含统一错误结构和对应 HTTP 状态的 Response。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const response = kit.response.fromError({ code: 'app:articles:001', message: 'Article missing', httpStatus: 404 })
+ * void response.status
+ * ```
+ */
 declare function fromError(haiError: HaiError, requestId?: string): Response;
 
 /**
@@ -662,13 +592,12 @@ declare function fromError(haiError: HaiError, requestId?: string): Response;
  * @param schema - Zod Schema
  * @returns 校验通过的数据（类型安全）
  * @throws Response - 400 BadRequest（含首条错误消息）
- *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * export const POST = kit.handler(async ({ request }) => {
- *   const data = await kit.validate.body(request, CreateUserSchema)
- *   // data 类型安全，校验已通过
- * })
+ * const schema = zod.object({ title: zod.string().min(1) })
+ * const result = await validateFormOrFail(new Request('https://app.example.com/api', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'Example' }) }), schema)
+ * // 校验失败抛出 Response，由框架错误边界透传。
+ * void result.title
  * ```
  */
 declare function validateFormOrFail<T extends z.ZodType>(request: Request, schema: T): Promise<z.infer<T>>;
@@ -679,10 +608,12 @@ declare function validateFormOrFail<T extends z.ZodType>(request: Request, schem
  * @param schema - Zod Schema
  * @returns 校验通过的数据
  * @throws Response - 400 BadRequest
- *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * const query = kit.validate.query(event.url, PaginationSchema)
+ * const schema = zod.object({ title: zod.string().min(1) })
+ * const result = validateQueryOrFail(new URL('https://app.example.com/articles?title=Example'), schema)
+ * // 校验失败抛出 Response，由框架错误边界透传。
+ * void result.title
  * ```
  */
 declare function validateQueryOrFail<T extends z.ZodType>(url: URL, schema: T): z.infer<T>;
@@ -693,10 +624,12 @@ declare function validateQueryOrFail<T extends z.ZodType>(url: URL, schema: T):
  * @param schema - Zod Schema
  * @returns 校验通过的数据
  * @throws Response - 400 BadRequest
- *
- * @example
+ * @example 模块内部上下文
  * ```ts
- * const { id } = kit.validate.params(event.params, IdParamSchema)
+ * const schema = zod.object({ title: zod.string().min(1) })
+ * const result = validateParamsOrFail({ title: 'Example' }, schema)
+ * // 校验失败抛出 Response，由框架错误边界透传。
+ * void result.title
  * ```
  */
 declare function validateParamsOrFail<T extends z.ZodType>(params: Record<string, string>, schema: T): z.infer<T>;
@@ -704,10 +637,12 @@ declare function validateParamsOrFail<T extends z.ZodType>(params: Record<string
  * 路径参数 id 校验 Schema
  *
  * 验证 `event.params.id` 为非空字符串。
- *
  * @example
  * ```ts
- * const { id } = kit.validate.params(event.params, IdParamSchema)
+ * import { IdParamSchema } from '@h-ai/kit'
+ *
+ * const value = IdParamSchema.parse({ id: 'article_1' })
+ * void value
  * ```
  */
 declare const IdParamSchema: z.ZodObject<{
@@ -718,16 +653,12 @@ declare const IdParamSchema: z.ZodObject<{
  *
  * 包含 page（默认 1）、pageSize（默认 20，上限 100）、search（可选）。
  * 可通过 `.extend()` 扩展业务字段。
- *
  * @example
  * ```ts
- * // 直接使用
- * const { page, pageSize, search } = kit.validate.query(url, PaginationQuerySchema)
+ * import { PaginationQuerySchema } from '@h-ai/kit'
  *
- * // 扩展业务字段
- * const ListUsersSchema = PaginationQuerySchema.extend({
- *   enabled: z.enum(['true', 'false']).transform(v => v === 'true').optional(),
- * })
+ * const value = PaginationQuerySchema.parse({ page: '1', pageSize: '20' })
+ * void value
  * ```
  */
 declare const PaginationQuerySchema: z.ZodObject<{
@@ -740,9 +671,24 @@ declare const PaginationQuerySchema: z.ZodObject<{
  * Kit 模块统一出口。
  *
  * 作为纯工具模块，kit 不需要 init/close 生命周期，
- * 所有功能均为无状态工厂函数或工具函数。
+ * 依赖服务、请求上下文和创建后句柄的状态由调用方按各自契约管理。
+ * @example
+ * ```ts
+ * import { kit } from '@h-ai/kit'
+ *
+ * const handle = kit.createHandle({ logging: true })
+ * void handle
+ * ```
  */
 declare const kit: {
+    /** 创建反馈的受控 catch-all HTTP handler，身份范围由宿主解析。 */
+    createFeedbackHandler: typeof createFeedbackHandler;
+    /** 原子限流工厂；共享store生命周期由应用管理。 */
+    middleware: {
+        rateLimit: typeof rateLimitMiddleware;
+        createCacheRateLimitStore: typeof createCacheRateLimitStore;
+        createMemoryRateLimitStore: typeof createMemoryRateLimitStore;
+    };
     /** 创建 SvelteKit Handle Hook（含 auth / logging / rateLimit 内置配置） */
     createHandle: typeof createHandle;
     /** 组合多个 Handle */
@@ -837,8 +783,6 @@ declare const kit: {
         setBrowserToken: typeof setBrowserToken;
         /** 清除浏览器端 Access Token（客户端 logout 用） */
         clearBrowserToken: typeof clearBrowserToken;
-        /** 创建浏览器端 Token 存储器（自定义 key 时使用） */
-        createTokenStore: typeof createTokenStore;
     };
     crud: {
         /** 定义 CRUD 资源（声明式配置 → 操作对象） */
@@ -847,38 +791,11 @@ declare const kit: {
     i18n: {
         /** 统一设置所有 hai 模块的默认语言 */
         setLocale: typeof setAllModulesLocale;
+        /** 请求/SSR 语言隔离；异步处理使用同一请求上下文。 */
+        runWithLocale: <T>(locale: _h_ai_core.Locale, operation: () => T) => T;
     };
 };
 
-/**
- * @h-ai/kit — CORS 中间件
- *
- * 配置跨域资源共享（CORS）策略，自动处理 OPTIONS 预检请求与响应头注入。
- * 支持精确 origin、数组白名单、通配符模式与函数匹配四种模式。
- * 自动预置 Capacitor WebView origin（Android/iOS）。
- * @module kit-cors
- */
-
-/**
- * 创建 CORS 中间件
- *
- * 处理跨域资源共享：
- * - OPTIONS 预检请求返回 204 + CORS 头
- * - 其他请求在业务响应上附加 CORS 头
- * - 默认预置 Capacitor WebView origin
- *
- * @param config - CORS 配置（省略则允许所有 origin）
- * @returns Middleware 实例
- *
- * @example
- * ```ts
- * middleware: [
- *   kit.middleware.cors({ origin: ['https://example.com'], credentials: true }),
- * ]
- * ```
- */
-declare function corsMiddleware(config?: CorsConfig): Middleware;
-
 /**
  * @h-ai/kit — 日志中间件
  *
@@ -889,6 +806,13 @@ declare function corsMiddleware(config?: CorsConfig): Middleware;
 
 /**
  * 日志中间件配置
+ * @example
+ * ```ts
+ * import type { LoggingMiddlewareConfig } from '@h-ai/kit'
+ *
+ * const value: LoggingMiddlewareConfig = { logBody: false }
+ * void value
+ * ```
  */
 interface LoggingMiddlewareConfig {
     /** 为 `true` 时记录非 GET 请求体（自动脱敏） */
@@ -898,25 +822,5 @@ interface LoggingMiddlewareConfig {
     /** 指定需要脱敏的字段名（默认 `['password', 'token', 'secret']`） */
     redactFields?: string[];
 }
-/**
- * 创建日志中间件
- *
- * 以 `core.logger.trace` 级别记录请求进出信息，包含：
- * - 请求：method / path / query / userAgent / ip
- * - 响应：status / duration
- *
- * 敏感字段会被自动替换为 `[REDACTED]`。
- *
- * @param config - 日志配置
- * @returns Middleware 实例
- *
- * @example
- * ```ts
- * middleware: [
- *   kit.middleware.logging({ logBody: true, redactFields: ['password', 'creditCard'] }),
- * ]
- * ```
- */
-declare function loggingMiddleware(config?: LoggingMiddlewareConfig): Middleware;
 
-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, createKitAuthActions, createKitClient, defineCrud, hasPermission, installBrowserTransport, installBrowserTransportFetch, kit, loggingMiddleware, matchPermission, notGuard, permissionGuard, requirePermission, roleGuard, sequence, sessionGuard, withPermission };
+export { type AuthGuardConfig, type CookieProxyConfig, type FeedbackHandlerOptions, HandleConfig, IdParamSchema, type LoggingMiddlewareConfig, PaginationQuerySchema, type PermissionGuardConfig, type RoleGuardConfig, SessionData, type SessionGuardConfig, SessionLike, defineCrud, kit, matchPermission };