@h-ai/serv 0.1.0-alpha.67 → 0.1.0-alpha.68

package/dist/{serv-context-CWzyrsdq.d.ts → serv-context-C48WdBcd.d.ts}

@@ -21,6 +21,17 @@ import { HaiResult, Logger } from '@h-ai/core';
 /**
  * Refresh 流程返回的 Token 对结构。
  * 与 `@h-ai/iam` 的 `TokenPair` 结构兼容；此处独立定义以避免对可选 peer dep 的强依赖。
+ *
+ * @example
+ * ```ts
+ * import type { RefreshTokenPair } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * function publicAccess(pair: RefreshTokenPair) {
+ *   return { accessToken: pair.accessToken, expiresIn: pair.expiresIn }
+ * }
+ * // 浏览器 refreshToken 只走 HttpOnly Cookie，不能写入可读持久存储。
+ * ```
  */
 interface RefreshTokenPair {
     readonly accessToken: string;
@@ -34,6 +45,17 @@ interface RefreshTokenPair {
  * 浏览器继续使用 httpOnly cookie；只有经过应用可信来源校验的原生请求，才允许在
  * JSON body 中接收和返回 refresh token。`isRequest` 必须同时校验客户端标识与 Origin，
  * 不能仅信任可伪造的单个请求头。
+ *
+ * @example
+ * ```ts
+ * import type { NativeRefreshTokenTransportConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * function configureNative(isTrustedRequest: NativeRefreshTokenTransportConfig['isRequest']): NativeRefreshTokenTransportConfig {
+ *   return { isRequest: isTrustedRequest }
+ * }
+ * // 宿主同时验证原生客户端标识与允许的 Origin，不能只检查单个可伪造头。
+ * ```
  */
 interface NativeRefreshTokenTransportConfig {
     /** 判断当前请求是否来自受信原生客户端。 */
@@ -48,6 +70,15 @@ interface NativeRefreshTokenTransportConfig {
  * 刷新回调来源（优先级从高到低）：
  * 1. `onRefresh`（显式覆盖）
  * 2. 顶层 `iam.session.refresh`（推荐：`createApp({ iam, refreshCookie: {} })` 即开箱可用）
+ *
+ * @example
+ * ```ts
+ * import type { RefreshCookieConfig } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const config: RefreshCookieConfig = { cookieName: 'hai_refresh_token', maxAge: 2592000, secure: true }
+ * // createApp 同时提供 iam 或 onRefresh；此配置只负责 refresh 传输，不校验 access。
+ * ```
  */
 interface RefreshCookieConfig {
     /** Cookie 名，默认 `hai_refresh_token`。 */
@@ -59,7 +90,7 @@ interface RefreshCookieConfig {
     readonly maxAge?: number;
     /**
      * 强制 Secure 属性。
-     * - 未传时：`NODE_ENV === 'production'` 时自动开启。
+     * - 未传时：`NODE_ENV` 或 `HAI_CORE_ENV` 为 `production` 时自动开启；测试开关不放宽此要求。
      * - 本地 HTTP 开发设为 `false` 可让 Cookie 在 HTTP 下正常工作。
      */
     readonly secure?: boolean;
@@ -93,7 +124,20 @@ interface RefreshCookieConfig {
  * @module serv-context
  */
 
-/** 当前请求解析出的会话摘要。 */
+/**
+ * 当前请求解析出的会话摘要。
+ *
+ * @example
+ * ```ts
+ * import type { ServSession } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * function canRead(session: ServSession): boolean {
+ *   return session.permissions.includes('reports.read')
+ * }
+ * // 会话来自可信 verifyToken，不能将客户端 userId/roles 直接提升为会话。
+ * ```
+ */
 interface ServSession {
     readonly userId: string;
     readonly username?: string;
@@ -109,6 +153,17 @@ interface ServSession {
  * - refresh token 轮换（仅当启用 `refreshCookie` 时使用）
  *
  * 模块消费者**无需**知道 IAM 内部 Session 类型与 ServSession 的差异：结构类型确保兼容。
+ *
+ * @example
+ * ```ts
+ * import type { ServIam } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * import { iam } from '@h-ai/iam'
+ *
+ * const auth: ServIam = iam
+ * const factory = serv.buildAuthContextFactory(token => auth.auth.verifyToken(token))
+ * ```
  */
 interface ServIam {
     readonly auth: {
@@ -116,11 +171,23 @@ interface ServIam {
         verifyToken: (accessToken: string) => Promise<HaiResult<ServSession>>;
     };
     readonly session: {
-        /** 使用 refresh token 换发新的 token 对。仅 `refreshCookie` 启用时被调用。 */
+        /** 使用 refresh token 换发新令牌对；refreshCookie 启用时调用，不要求旧 access 有效。 */
         refresh: (refreshToken: string) => Promise<HaiResult<RefreshTokenPair>>;
     };
 }
-/** `@h-ai/serv` 在 procedures 中传递的统一上下文。 */
+/**
+ * `@h-ai/serv` 在 procedures 中传递的统一上下文。
+ *
+ * @example
+ * ```ts
+ * import type { ServContext } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const context: ServContext = serv.parseRequestContext({ request: new Request('https://example.com/health'), remoteAddress: '192.0.2.10' })
+ * const locale = context.locale
+ * // parseRequestContext 只读元数据，不产生已认证 session。
+ * ```
+ */
 interface ServContext {
     readonly requestId: string;
     readonly locale: string;
@@ -131,17 +198,50 @@ interface ServContext {
     readonly request: Request;
     readonly logger: Logger;
 }
-/** 运行时提供的连接元数据；必须来自 socket/平台，不能从请求头复制。 */
+/**
+ * 运行时提供的连接元数据；必须来自 socket/平台，不能从请求头复制。
+ *
+ * @example
+ * ```ts
+ * import type { ServRequestMetadata } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const metadata: ServRequestMetadata = { remoteAddress: '192.0.2.10' }
+ * // 由运行时 socket 提供；转发头必须另经过 trustedProxies 策略。
+ * ```
+ */
 interface ServRequestMetadata {
     readonly remoteAddress?: string;
 }
-/** 创建上下文所需的输入。 */
+/**
+ * 创建上下文所需的输入。
+ *
+ * @example
+ * ```ts
+ * import type { CreateServContextInput } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const input: CreateServContextInput = { request: new Request('https://example.com/health'), remoteAddress: '192.0.2.10' }
+ * const context = serv.parseRequestContext(input)
+ * ```
+ */
 interface CreateServContextInput extends ServRequestMetadata {
     readonly request: Request;
     /** createApp 已按 trustedProxies 解析的客户端地址，供自定义上下文复用。 */
     readonly ip?: string;
 }
-/** 应用可传入的上下文工厂。 */
+/**
+ * 应用可传入的上下文工厂。
+ *
+ * @example
+ * ```ts
+ * import type { CreateServContext } from '@h-ai/serv'
+ * import { serv } from '@h-ai/serv'
+ *
+ * const factory: CreateServContext = input => serv.parseRequestContext(input)
+ * const context = await factory({ request: new Request('https://example.com/health') })
+ * ```
+ */
 type CreateServContext = (input: CreateServContextInput) => ServContext | Promise<ServContext>;
 /**
  * 解析 HTTP 请求元数据并构造基础 ServContext（**同步**，**不**填充 session）。
@@ -155,6 +255,15 @@ type CreateServContext = (input: CreateServContextInput) => ServContext | Promis
  *
  * @param input - 上下文输入
  * @returns 仅含元数据的 ServContext
+ *
+ * @example
+ * ```ts
+ * import { serv } from '@h-ai/serv'
+ *
+ * const request = new Request('https://example.com/health', { headers: { 'x-hai-locale': 'en-US' } })
+ * const context = serv.parseRequestContext({ request, remoteAddress: '192.0.2.10' })
+ * const locale = context.locale
+ * ```
  */
 declare function parseRequestContext(input: CreateServContextInput): ServContext;
 /**
@@ -176,6 +285,17 @@ declare function parseRequestContext(input: CreateServContextInput): ServContext
  *
  * @param verifyToken - 访问令牌校验回调（通常是 `token => iam.auth.verifyToken(token)` 或自定义函数）
  * @returns 异步上下文工厂
+ *
+ * @example
+ * ```ts
+ * import { iam } from '@h-ai/iam'
+ * import { serv } from '@h-ai/serv'
+ *
+ * // IAM 已初始化；每个请求重新验证 token 与当前持久凭据/权限状态。
+ * const factory = serv.buildAuthContextFactory(token => iam.auth.verifyToken(token))
+ * const context = await factory({ request: new Request('https://example.com/profile') })
+ * // 未携带/验证失败时 session 为空，由 route guard 决定是否拒绝。
+ * ```
  */
 declare function buildAuthContextFactory(verifyToken: (accessToken: string) => Promise<HaiResult<ServSession>>): CreateServContext;
 

package/dist/serv-router-BX8hgYxo.d.ts

@@ -0,0 +1,322 @@
+import { HaiResult } from '@h-ai/core';
+import { ContractRouter, Meta, Context, ContractProcedure, InferSchemaInput, ProcedureHandler, InferSchemaOutput, UnlaziedRouter, Router } from '@orpc/server';
+import { S as ServContext } from './serv-context-C48WdBcd.js';
+
+/**
+ * @h-ai/serv — contract-first 链式 procedure 实现器
+ *
+ * 在 oRPC `implement()` 之上提供 route 名只出现一次的链式 DSL。
+ * 应用只接触 contract 路径、上下文与 guard，不需要组装 oRPC router 对象。
+ *
+ * @module serv-router
+ */
+
+/**
+ * 内部初始 context 空约束，用于保持 oRPC 推导而不伪造运行时字段。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { serv } = await import('@h-ai/serv')
+ * const context: ServContext & EmptyContext = serv.parseRequestContext({ request: new Request('https://example.com/ping') })
+ * const requestId = context.requestId
+ * ```
+ */
+type EmptyContext = Record<never, never>;
+/**
+ * 提取 contract 的字符串键，排除 symbol/数字索引。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const path: StringKey<typeof contract> = 'ping'
+ * const procedure = contract[path]
+ * ```
+ */
+type StringKey<T> = Extract<keyof T, string>;
+/**
+ * 内部 contract 泛型边界；真实 procedure 输出须为 HaiResult。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const checked = contract satisfies ServContract
+ * const procedures = implement(checked).context<ServContext>().route('ping', () => ok({ ready: true })).build()
+ * ```
+ */
+type ServContract = ContractRouter<Meta>;
+/**
+ * contract 中所有 procedure 的点分路径。
+ *
+ * @example
+ * ```ts
+ * import type { ServRoutePath } from '@h-ai/serv'
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { ok } from '@h-ai/core'
+ * import { serv } from '@h-ai/serv'
+ * import { z } from 'zod'
+ *
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const path: ServRoutePath<typeof contract> = 'ping'
+ * const procedures = serv.implement(contract).context<ServContext>().route(path, () => ok({ ready: true })).build()
+ * ```
+ */
+type ServRoutePath<TContract extends ServContract> = TContract extends ContractProcedure<infer _TInputSchema, infer _TOutputSchema, infer _TErrorMap, infer _TMeta> ? never : {
+    [K in StringKey<TContract>]: TContract[K] extends ContractProcedure<infer _TChildInputSchema, infer _TChildOutputSchema, infer _TChildErrorMap, infer _TChildMeta> ? K : TContract[K] extends ServContract ? ServRoutePath<TContract[K]> extends infer TChild extends string ? `${K}.${TChild}` : never : never;
+}[StringKey<TContract>];
+/**
+ * 按点分路径查找原始 contract procedure；不存在的路径推导为 never。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const procedure: ContractAtPath<typeof contract, 'ping'> = contract.ping
+ * const scoped = implement({ ping: procedure }).context<ServContext>().route('ping', () => ok({ ready: true })).build()
+ * ```
+ */
+type ContractAtPath<TContract, TPath extends string> = TPath extends `${infer THead}.${infer TTail}` ? THead extends keyof TContract ? ContractAtPath<TContract[THead], TTail> : never : TPath extends keyof TContract ? TContract[TPath] : never;
+/**
+ * 将合法路由路径映射到对应 contract，供 handler 推导复用。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const procedure: RouteContract<typeof contract, 'ping'> = contract.ping
+ * const scoped = implement({ ping: procedure }).context<ServContext>().route('ping', () => ok({ ready: true })).build()
+ * ```
+ */
+type RouteContract<TContract extends ServContract, TPath extends ServRoutePath<TContract>> = ContractAtPath<TContract, TPath>;
+/**
+ * `.auth()`、`.permission()`、`.role()` 后的非空会话上下文。
+ *
+ * @example
+ * ```ts
+ * import type { AuthenticatedServContext } from '@h-ai/serv'
+ *
+ * function owner(context: AuthenticatedServContext): string {
+ *   return context.session.userId
+ * }
+ * // 仅成功 guard 或可信认证结果能建立此上下文，禁止用客户端字段断言。
+ * ```
+ */
+type AuthenticatedServContext<TContext extends ServContext = ServContext> = TContext & {
+    readonly session: NonNullable<TContext['session']>;
+};
+/**
+ * 内部从具体 procedure 的输入/输出与 context 推导 HaiResult handler。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const handler: RouteHandler<typeof contract.ping, ServContext> = () => ok({ ready: true })
+ * const procedures = implement(contract).context<ServContext>().route('ping', handler).build()
+ * ```
+ */
+type RouteHandler<TRouteContract, TContext extends Context> = TRouteContract extends ContractProcedure<infer TInputSchema, infer TOutputSchema, infer TErrorMap, infer TMeta> ? InferSchemaInput<TOutputSchema> extends HaiResult<unknown> ? ProcedureHandler<TContext, InferSchemaOutput<TInputSchema>, InferSchemaInput<TOutputSchema>, TErrorMap, TMeta> : never : never;
+/**
+ * 从 contract procedure 精确推导当前 route 的 HaiResult handler。
+ *
+ * @example
+ * ```ts
+ * import type { ServRouteHandler } from '@h-ai/serv'
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { ok } from '@h-ai/core'
+ * import { serv } from '@h-ai/serv'
+ * import { z } from 'zod'
+ *
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const handler: ServRouteHandler<typeof contract, 'ping', ServContext> = () => ok({ ready: true })
+ * const procedures = serv.implement(contract).context<ServContext>().route('ping', handler).build()
+ * ```
+ */
+type ServRouteHandler<TContract extends ServContract, TPath extends ServRoutePath<TContract>, TContext extends Context> = RouteHandler<RouteContract<TContract, TPath>, TContext>;
+/**
+ * 内部认证成功 handler 类型；session 在 guard 之后非空。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const handler: ServGuardedRouteHandler<typeof contract, 'ping', ServContext> = ({ context }) => ok({ ready: context.session.userId.length > 0 })
+ * const procedures = implement(contract).context<ServContext>().route('ping').auth().handle(handler).build()
+ * ```
+ */
+type ServGuardedRouteHandler<TContract extends ServContract, TPath extends ServRoutePath<TContract>, TContext extends ServContext> = RouteHandler<RouteContract<TContract, TPath>, AuthenticatedServContext<TContext>>;
+/**
+ * 一次注册后移除该路径的 builder；全部路径完成才提供 build。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const next: NextBuilder<typeof contract, ServContext, ServContext, 'ping', 'ping'> = implement(contract).context<ServContext>().route('ping', () => ok({ ready: true }))
+ * const procedures = next.build()
+ * ```
+ */
+type NextBuilder<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> = ServRouterBuilder<TContract, TInitialContext, TCurrentContext, Exclude<TRemaining, TPath>>;
+/**
+ * 尚未声明 guard 的单 route 注册器。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const route: ServRouteRegistration<typeof contract, ServContext, ServContext, 'ping', 'ping'> = implement(contract).context<ServContext>().route('ping')
+ * const procedures = route.auth().handle(() => ok({ ready: true })).build()
+ * ```
+ */
+interface ServRouteRegistration<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> {
+    readonly auth: () => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly permission: (permission: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly role: (role: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+}
+/**
+ * 已声明认证或授权 guard 的单 route 注册器。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const guarded: ServGuardedRouteRegistration<typeof contract, ServContext, ServContext, 'ping', 'ping'> = implement(contract).context<ServContext>().route('ping').permission('reports.read')
+ * const procedures = guarded.handle(() => ok({ ready: true })).build()
+ * ```
+ */
+interface ServGuardedRouteRegistration<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>, TPath extends TRemaining> {
+    readonly auth: () => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly permission: (permission: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly role: (role: string) => ServGuardedRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    readonly handle: (handler: ServGuardedRouteHandler<TContract, TPath, TCurrentContext>) => NextBuilder<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+}
+/**
+ * 内部 route 重载：直接 handler 或先声明 guard，再收窄剩余路径。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const route: ServRouteMethod<typeof contract, ServContext, ServContext, 'ping'> = implement(contract).context<ServContext>().route
+ * const procedures = route('ping', () => ok({ ready: true })).build()
+ * ```
+ */
+interface ServRouteMethod<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract>> {
+    <TPath extends TRemaining>(path: TPath, handler: ServRouteHandler<TContract, TPath, TCurrentContext>): NextBuilder<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+    <TPath extends TRemaining>(path: TPath): ServRouteRegistration<TContract, TInitialContext, TCurrentContext, TRemaining, TPath>;
+}
+/**
+ * 剩余路径为 never 时才暴露 build，否则仅提供缺失路径类型提示。
+ *
+ * @example
+ * ```ts
+ * // 模块内部上下文：示例复用当前声明所在模块的实际绑定。
+ * const { apiContract } = await import('@h-ai/api-contract')
+ * const { z } = await import('zod')
+ * const { ok } = await import('@h-ai/core')
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const complete: ServRouterBuilderBuild<typeof contract, ServContext, never> = implement(contract).context<ServContext>().route('ping', () => ok({ ready: true }))
+ * const procedures = complete.build()
+ * ```
+ */
+type ServRouterBuilderBuild<TContract extends ServContract, TInitialContext extends Context, TRemaining> = [TRemaining] extends [never] ? {
+    /** 同步返回完整的普通 router，允许按需选用嵌套的默认 procedures。 */
+    readonly build: () => UnlaziedRouter<Router<TContract, TInitialContext>>;
+} : {
+    /** 仅供 TypeScript/IDE 展示尚未实现的 route；运行时不存在。 */
+    readonly missingRoutes: TRemaining;
+};
+/**
+ * 链式 router builder。
+ *
+ * `TRemaining` 会随着 `.route()` 注册逐步收窄；未实现完整 contract 时没有 `.build()`。
+ *
+ * @example
+ * ```ts
+ * import type { ServRouterBuilder } from '@h-ai/serv'
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { ok } from '@h-ai/core'
+ * import { serv } from '@h-ai/serv'
+ * import { z } from 'zod'
+ *
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const builder: ServRouterBuilder<typeof contract, ServContext, ServContext> = serv.implement(contract).context<ServContext>()
+ * const procedures = builder.route('ping', () => ok({ ready: true })).build()
+ * ```
+ */
+type ServRouterBuilder<TContract extends ServContract, TInitialContext extends Context, TCurrentContext extends ServContext, TRemaining extends ServRoutePath<TContract> = ServRoutePath<TContract>> = {
+    readonly route: ServRouteMethod<TContract, TInitialContext, TCurrentContext, TRemaining>;
+} & ServRouterBuilderBuild<TContract, TInitialContext, TRemaining>;
+/**
+ * hai-framework 链式 contract 实现器。
+ *
+ * @example
+ * ```ts
+ * import type { ServImplementer } from '@h-ai/serv'
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { ok } from '@h-ai/core'
+ * import { serv } from '@h-ai/serv'
+ * import { z } from 'zod'
+ *
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const implementer: ServImplementer<typeof contract> = serv.implement(contract)
+ * const procedures = implementer.context<ServContext>().route('ping', () => ok({ ready: true })).build()
+ * ```
+ */
+interface ServImplementer<TContract extends ServContract> {
+    readonly context: <TContext extends ServContext>() => ServRouterBuilder<TContract, TContext & EmptyContext, TContext>;
+}
+/**
+ * 创建链式 contract 实现器。
+ *
+ * @example
+ * ```ts
+ * import type { ServContext } from '@h-ai/serv'
+ * import { apiContract } from '@h-ai/api-contract'
+ * import { ok } from '@h-ai/core'
+ * import { serv } from '@h-ai/serv'
+ * import { z } from 'zod'
+ *
+ * const contract = { ping: apiContract.route({ method: 'GET', path: '/ping' }).output(apiContract.haiResultSchema(z.object({ ready: z.boolean() }))) }
+ * const procedures = serv.implement(contract).context<ServContext>().route('ping', () => ok({ ready: true })).build()
+ * ```
+ */
+declare function implement<TContract extends ServContract>(contract: TContract): ServImplementer<TContract>;
+
+export { type AuthenticatedServContext as A, type ServImplementer as S, type ServRouteHandler as a, type ServRoutePath as b, type ServRouterBuilder as c, implement as i };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/serv",
   "type": "module",
-  "version": "0.1.0-alpha.67",
+  "version": "0.1.0-alpha.68",
   "description": "Hai Framework service runtime powered by Hono and oRPC.",
   "license": "Apache-2.0",
   "exports": {
@@ -35,9 +35,9 @@
     "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "peerDependencies": {
-    "@h-ai/ai": "0.1.0-alpha.67",
-    "@h-ai/iam": "0.1.0-alpha.67",
-    "@h-ai/storage": "0.1.0-alpha.67"
+    "@h-ai/ai": "0.1.0-alpha.68",
+    "@h-ai/iam": "0.1.0-alpha.68",
+    "@h-ai/storage": "0.1.0-alpha.68"
   },
   "peerDependenciesMeta": {
     "@h-ai/ai": {
@@ -51,9 +51,9 @@
     }
   },
   "dependencies": {
-    "@h-ai/api-contract": "0.1.0-alpha.67",
-    "@h-ai/core": "0.1.0-alpha.67",
-    "@h-ai/crypto": "0.1.0-alpha.67",
+    "@h-ai/api-contract": "0.1.0-alpha.68",
+    "@h-ai/core": "0.1.0-alpha.68",
+    "@h-ai/crypto": "0.1.0-alpha.68",
     "@hono/node-server": "^2.1.4",
     "@orpc/openapi": "^1.15.5",
     "@orpc/server": "^1.15.5",
@@ -64,12 +64,16 @@
     "zod": "^4.6.5"
   },
   "devDependencies": {
-    "@h-ai/ai": "0.1.0-alpha.67",
-    "@h-ai/iam": "0.1.0-alpha.67",
-    "@h-ai/storage": "0.1.0-alpha.67",
+    "@h-ai/ai": "0.1.0-alpha.68",
+    "@h-ai/api-client": "0.1.0-alpha.68",
+    "@h-ai/cache": "0.1.0-alpha.68",
+    "@h-ai/iam": "0.1.0-alpha.68",
+    "@h-ai/reldb": "0.1.0-alpha.68",
+    "@h-ai/storage": "0.1.0-alpha.68",
     "@types/node": "^26.6.5",
     "@types/ws": "^8.18.2",
     "rimraf": "^6.1.3",
+    "testcontainers": "^12.2.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11"

package/dist/chunk-27PCPE37.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/features/serv-feature-helpers.ts"],"names":[],"mappings":";;;AAgBO,SAAS,gBAAmB,MAAA,EAAmD;AACpF,EAAA,IAAI,CAAC,MAAA,CAAO,OAAA;AACV,IAAA,OAAO,MAAA;AACT,EAAA,OAAO,EAAA,CAAG,EAAE,KAAA,EAAO,MAAA,CAAO,MAAM,CAAA;AAClC;AAKO,SAAS,YAAA,CAAmB,QAAsB,MAAA,EAAsC;AAC7F,EAAA,IAAI,CAAC,MAAA,CAAO,OAAA;AACV,IAAA,OAAO,MAAA;AACT,EAAA,OAAO,EAAA,CAAG,MAAA,CAAO,MAAA,CAAO,IAAI,CAAC,CAAA;AAC/B","file":"chunk-27PCPE37.js","sourcesContent":["/**\n * @h-ai/serv — features 公共辅助\n *\n * 把多个 feature procedure 中重复出现的 `HaiResult` 包装逻辑收敛到一处。\n * @module features/serv-feature-helpers\n */\n\nimport type { HaiResult } from '@h-ai/core'\nimport { ok } from '@h-ai/core'\n\n/**\n * 把 `HaiResult<T[]>` 转换为 `HaiResult<{ items: T[] }>`。\n *\n * oRPC contract 中 list 类返回常用 `{ items: [...] }` 信封；\n * 业务模块通常直接返回数组，本工具负责套上信封。\n */\nexport function wrapItemsResult<T>(result: HaiResult<T[]>): HaiResult<{ items: T[] }> {\n  if (!result.success)\n    return result\n  return ok({ items: result.data })\n}\n\n/**\n * 把 `HaiResult<T>` 通过 mapper 映射为 `HaiResult<U>`，错误透传。\n */\nexport function mapHaiResult<T, U>(result: HaiResult<T>, mapper: (data: T) => U): HaiResult<U> {\n  if (!result.success)\n    return result\n  return ok(mapper(result.data))\n}\n"]}