API 参考

各模块共同遵循 API 约定。

业务方优先从根入口使用稳定 API：

import {
  BridgeError,
  ClipboardError,
  StorageError,
  DbError,
  createBridgeLogTransport,
  unwrapBusinessEnvelope,
  createBridge,
  createClipboard,
  createDb,
  createEnvironment,
  createHttp,
  createLogger,
  createStorage,
  HttpError,
  type ApiContractBuilder,
  type ApiType,
  type Bridge,
  type ClipboardClient,
  type Db,
  type Environment,
  type HttpApiDefinitionTree,
  type HttpApiFromDefinition,
  type HttpCallInput,
  type HttpCallOptions,
  type HttpEndpointDefinition,
  type HttpOptions,
  type HttpClient,
  type Logger,
  type StorageArea
} from '@freenotes/web-runtime';

常用工厂

API	说明
createStorage(type?, options?)	创建 localStorage 或 sessionStorage 实例。
createDb()	创建 IndexedDB manager。
createEnvironment(options?)	创建不可变环境与 capability 快照。
createClipboard()	创建文本剪贴板实例。
createBridge(options?)	创建 H5 和宿主环境通信的 Bridge 实例。
createLogger(options)	创建使用显式 transport 的平台无关 Logger。
createHttp(options?)	创建配置式业务 HTTP API 实例。

Capability 实例类型

API	返回类型
createBridge(options?)	Bridge
createClipboard()	ClipboardClient
createDb()	Db
createEnvironment(options?)	Environment
createHttp()	HttpClient
createLogger(options)	Logger
createStorage(type?, options?)	StorageArea

实例类型按领域角色命名，不统一添加信息量较低的 Runtime 后缀。ClipboardClient 避免与 DOM 的 Clipboard 类型冲突，HttpClient 表达配置后的请求客户端，StorageArea 表达具体的 local/session storage 区域。

HTTP 类型

类型	说明
HttpClient	createHttp() 的返回类型。
HttpOptions	baseURL、headers、timeout、retry 和 interceptors 配置。
HttpApiDefinitionTree	createApi() 接收的递归 endpoint 配置树。
HttpApiFromDefinition	根据配置树推导出的业务方法树。
ApiContractBuilder	createApi((contract) => ...) 回调中的契约辅助对象。
ApiType<T>	contract.type<T>() 返回的编译期标记类型。
ApiContract<T>	编译期 marker 或 Standard Schema 契约。
StandardSchemaV1	HTTP 接受的框架无关运行时 schema 接口。
StandardSchemaIssue	schema 校验失败时保留在 HttpError.issues 的问题项。
HttpEndpointDefinition	单个 endpoint 的 method、url、契约标记和 transport 配置。
HttpCallInput	未声明契约标记时的通用 path、query、data、options 输入。
HttpCallOptions	单次请求的 timeout、headers、signal 等覆盖配置。
HttpError	HTTP、业务 envelope 或请求构造失败时抛出的错误。

配置本身就是 HTTP 契约。业务不需要维护 Get/Post/... 类型树，也不需要为 method 添加 as const。详细示例见 HTTP 指南。

生成文档

完整的根入口类型由 TypeDoc 生成：

• 根入口 API

当前 package 同时暴露根入口和 bridge、clipboard、db、environment、http、logger、storage 显式 subpath。

维护者重新生成 API 文档：

pnpm docs:api