@openviking/react 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @openviking/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English / [中文](README_CN.md)
+
+React foundations for OpenViking AI application interfaces: build tooling, documentation, layered directories, and scoped styles. FileTree and FilePreview provide placeholder views, alongside five file-type icons. Three business module placeholders support early layout integration; ScopeCascade provides a working cascade Hook and composition.
+
+This package inherits the repository's AGPL-3.0-only license. The release workflow publishes it to npm when a `react@<version>` tag matches the version in this package's manifest.
+
+## Module map
+
+| Source directory                                                       | Public entry                                  | Responsibility                                                                            |
+| ---------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| [components/file-tree](./src/components/file-tree/README.md)           | `@openviking/react/components/file-tree`      | Directory tree rendering, expansion, selection and event callbacks; view is a placeholder |
+| [components/file-preview](./src/components/file-preview/README.md)     | `@openviking/react/components/file-preview`   | Read-only preview state and extension tabs; view is a placeholder                         |
+| [components/tui](./src/components/tui/README.md)                       | `@openviking/react/components/tui`            | Reviewed command record, result and input types; view is a placeholder                    |
+| [components/scope-switcher](./src/components/scope-switcher/README.md) | `@openviking/react/components/scope-switcher` | Stateless scope layout and independent ScopeSelector options, panels and search           |
+| [components/agent-connect](./src/components/agent-connect/README.md)   | `@openviking/react/components/agent-connect`  | Agent connection tab, list and detail contract; view is a placeholder                     |
+| [modules](./src/modules/README.md)                                     | `@openviking/react/modules/<module>`          | ScopeCascade Hooks and composition, plus three placeholder business modules               |
+| [client](./src/client/index.ts)                                        | `@openviking/react/client`                    | Framework-neutral request client: `createOvClient`, `OvClient`, `OvClientError`           |
+| [hooks](./src/hooks/README.md), [utils](./src/utils/README.md)         | Internal only                                 | Cross-module Hooks and pure utilities                                                     |
+
+Components implement their reviewed contracts incrementally. FileTree renders every documented row type with keyboard interaction; FilePreview implements the tab shell, header actions and the plain-text preview and editing foundation, with its body not yet wired to FileViewer. ScopeSwitcher is a stateless layout container; independently rendered ScopeSelector children own visibility, with host-owned per-level data subscriptions, search and requests. Tui and AgentConnect render a fixed-size shell only. Limits are described in each component's own docs. The package also ships five file-type icons.
+
+Components receive view data and state through props and express user intent through callbacks, following the [component directory conventions](./src/components/AGENTS.md). [modules](./src/modules/README.md) plan Hooks and views per business capability: Hooks load data, hold state and expose operations, and composite views wire them into components. Full pages and product-specific flows belong to the host; the admin console is out of scope for this phase. `file-browser`, `console` and `task-center` currently ship placeholder components, base Props / Labels types and styles so hosts can integrate layout first; business Hooks, data loading and cross-component coordination are not implemented yet.
+
+Modules consume the native OpenViking API through a shared Client by default, with the Provider supplying `baseURL`, headers and other configuration, and modules or standalone Hooks overriding individual fields through `requestOptions`. Standard integration needs no per-module Adapter; nonstandard gateways are adapted at the host's request boundary. The request contract — `OvRequestOptions`, `OvClient` and `OvClientError` — comes from the `@openviking/react/client` subpath, which ships a `fetch`-based `createOvClient`; the Provider is exported from the same subpath; these native API module Hooks are not implemented yet. ScopeCascade instead accepts three host API adapters and needs no Provider. See [request conventions](./src/modules/README.md#request-conventions-and-default-configuration).
+
+### Props conventions
+
+The same props are consumed by different hosts. Hosts differ in flows and interfaces while matching in interaction and UI, so:
+
+- Components receive **already adapted data**: file entries, tabs and content sources are mapped into package types by module Hooks or the host, and components reference no host data model.
+- State is expressed with controlled fields, and callbacks only report intent without returning business data.
+- Copy is passed through labels, defaulting to English; hosts map i18next or Starling in their integration layer.
+- Icons, extension tabs, extra fields and toolbar actions come in as slots or nodes; components bind to no third-party UI library.
+- List components render the rows or items the caller has already expanded; paging, loading, error and empty states come from module Hooks or the host.
+
+## Public entries and styles
+
+- The root entry exports each component and each business module placeholder with its main Props type (`<Component>Props`) only — currently `FileTree`, `Tui`, `ScopeSwitcher`, `ScopeSelector`, `ScopeCascade`, `AgentConnect` and the three business module placeholders. Row types, option types, handles and label bags come from the `components/<component>` and `modules/<module>` subpaths. `FilePreview` is not on the root entry: its types reference the optional `@ark-design/ui`, and putting it there would make that peer required. ScopeCascade exports a working three-level composition and per-level subscription Hooks from `modules/scope-cascade`; other business modules remain placeholders. No aggregate `@openviking/react/components` or `@openviking/react/modules` JavaScript entry. Package exports are listed explicitly and internal files stay closed.
+- Components expose only the explicitly listed layered subpaths, with no legacy path aliases.
+- JS entries share implementations and never load CSS implicitly. Whole-package, component-set and single-module stylesheets are built from the same source, so import the scope you need.
+
+| Scope                  | CSS entry                                         |
+| ---------------------- | ------------------------------------------------- |
+| Whole package          | `@openviking/react/style.css`                     |
+| Component set          | `@openviking/react/components/style.css`          |
+| Single component       | `@openviking/react/components/<module>/style.css` |
+| Business module set    | `@openviking/react/modules/style.css`             |
+| Single business module | `@openviking/react/modules/<module>/style.css`    |
+
+Each CSS entry works standalone, and the whole-package CSS already includes module placeholder styles. Once real capability lands, module CSS must also include the composite view and the styles of the components it uses; using a module Hook alone needs no CSS. Cross-module public Hooks open `@openviking/react/hooks` only after a real implementation; module-specific public Hooks are exported from their module entry, and private Hooks and utilities stay out of public exports.
+
+```tsx
+import { FileBrowser } from '@openviking/react/modules/file-browser';
+import '@openviking/react/modules/file-browser/style.css';
+
+<FileBrowser
+  labels={{ title: 'File browser', description: 'Placeholder component.' }}
+/>;
+```
+
+The other modules export `Console` and `TaskCenter`; all currently accept `className`, `style` and `labels`, and need no Provider or request configuration.
+
+Experience dashboards belong to preview extensions; task progress starts inside its owning module; API Key display controls are reused on demand while credential creation and management belong to the host. No separate modules are added for these now.
+
+## Icons
+
+```tsx
+import { PdfIcon } from '@openviking/react/icons';
+
+<PdfIcon width={20} height={20} className="file-icon" alt="PDF" />;
+```
+
+Icons render as 16 × 16 images by default. Decorative icons can keep the empty `alt`, while icons that convey file type can provide a description. SVGs are inlined into the build output, and hosts consume them directly from the package exports.
+
+React and ReactDOM are peer dependencies (`^18.2.0 || ^19.0.0`), automatically externalized by Rslib. Rslib emits shared ESM JavaScript and declarations, plus independently built CSS entries. The public `@openviking/react/style.css` entry resolves to `dist/style.css`. Styles are scoped and do not reset application styles.
+
+From `frontend/`, run `npm run build:lib` to generate `packages/react/dist/`. See the [workspace README](../../README.md) for documentation development and deployment.
+
+### ScopeCascade
+
+Pass three stable API adapter functions to `useScopeCascade({ loadLibraries, loadSpaces, loadUsers })`, then render `<ScopeCascade controller={controller} />`. Adapters return `{ id, label }` options and receive an `AbortSignal`. The module handles dependent requests, descendant resets, loading, errors, retries and stale responses. Each selector subscribes independently; the Hook caller does not subscribe to request state. Import the Hook and composition from `@openviking/react/modules/scope-cascade` and its CSS from the corresponding `/style.css` entry.

package/dist/3~0.js

@@ -0,0 +1,8 @@
+import { jsx } from "react/jsx-runtime";
+function Tui() {
+    return /*#__PURE__*/ jsx("div", {
+        className: "ov-tui",
+        children: "Tui"
+    });
+}
+export { Tui };

package/dist/a~0.js

@@ -0,0 +1,21 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+function Console({ className, style, labels }) {
+    return /*#__PURE__*/ jsxs("div", {
+        className: [
+            'ov-module-placeholder',
+            className
+        ].filter(Boolean).join(' '),
+        style: style,
+        children: [
+            /*#__PURE__*/ jsx("p", {
+                className: "ov-module-placeholder__title",
+                children: labels?.conversation ?? 'Console'
+            }),
+            /*#__PURE__*/ jsx("p", {
+                className: "ov-module-placeholder__description",
+                children: labels?.description ?? 'Placeholder. Functionality is not available yet.'
+            })
+        ]
+    });
+}
+export { Console };

package/dist/client/client.d.ts

@@ -0,0 +1,12 @@
+import type { OvClient, OvClientOptions } from './types.js';
+/**
+ * 用 `fetch` 实现 {@link OvClient}。这是库自带的默认传输层，调用方只需给服务
+ * 地址和身份字段；要换传输方式（例如复用宿主已有的 axios 实例）时才需要自己
+ * 实现 {@link OvClient}。
+ *
+ * Implements {@link OvClient} with `fetch`. This is the library's default
+ * transport, so a caller supplies only the service address and identity fields.
+ * Implement {@link OvClient} yourself only to replace the transport, for example
+ * to reuse the host's existing axios instance.
+ */
+export declare function createOvClient(options?: OvClientOptions): OvClient;

package/dist/client/errors.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 请求失败的统一错误。区分 HTTP 失败与原生响应里的 `status: 'error'`，
+ * 保留服务端错误码、状态与请求标识。
+ * The single error a failed request raises. It distinguishes an HTTP failure
+ * from a native `status: 'error'` response and keeps the server error code,
+ * status and request identifier.
+ */
+export declare class OvClientError extends Error {
+    /** 服务端错误码，HTTP 失败时为 `HTTP_<status>` 或 `NETWORK_ERROR`。 */
+    readonly code: string;
+    /** HTTP 状态码；请求未到达服务端时省略。 */
+    readonly statusCode?: number;
+    /** 服务端返回的附加信息。 */
+    readonly details?: unknown;
+    /** 服务端请求标识，便于与服务端日志对应。 */
+    readonly requestId?: string;
+    /** 原始响应体，便于诊断无法归一的响应。 */
+    readonly responseBody?: unknown;
+    constructor(options: {
+        code: string;
+        message: string;
+        statusCode?: number;
+        details?: unknown;
+        requestId?: string;
+        responseBody?: unknown;
+        cause?: unknown;
+    });
+}
+/** 判断一个值是否为 {@link OvClientError}。 */
+export declare function isOvClientError(value: unknown): value is OvClientError;

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export { createOvClient } from './client.js';
+export { OvClientError, isOvClientError } from './errors.js';
+export { OpenVikingProvider, type OpenVikingProviderProps, } from './provider.js';
+export type { OvClient, OvClientOptions, OvErrorEnvelope, OvIdentityValue, OvQueryValue, OvRequestOptions, OvRequestSpec, OvResolvedOptions, OvSuccessEnvelope, } from './types.js';

package/dist/client/options.d.ts

@@ -0,0 +1,101 @@
+import type { OvClientOptions, OvIdentityValue, OvQueryValue, OvRequestOptions, OvResolvedOptions } from './types.js';
+/**
+ * 身份字段到请求头的映射。宿主传字段值，Client 负责组装，不暴露 header 名称。
+ * Mapping from identity fields to request headers. A host passes field values and
+ * the Client assembles the headers, so header names stay internal.
+ */
+export declare const IDENTITY_HEADERS: {
+    readonly apiKey: 'X-API-Key';
+    readonly accountId: 'X-OpenViking-Account';
+    readonly userId: 'X-OpenViking-User';
+    readonly resourceId: 'V-Resource-Id';
+};
+export type OvIdentityField = keyof typeof IDENTITY_HEADERS;
+/**
+ * 求值一层身份字段，保留空字符串，以便区分「未提供」与「显式清除」。
+ * Evaluates one identity layer, keeping empty strings so that "absent" and
+ * "explicitly cleared" stay distinguishable.
+ */
+export declare function resolveIdentityLayer(options: OvRequestOptions | undefined): Promise<OvIdentityLayer>;
+/**
+ * 合并两层身份字段：近的一层覆盖远的一层，近层显式传空字符串即清除该字段。
+ * Merges two identity layers: the nearer one wins, and an explicit empty string
+ * in it clears the field.
+ */
+export declare function mergeIdentityLayers(far: OvIdentityLayer, near: OvIdentityLayer): OvIdentityLayer;
+/**
+ * 把身份字段转成请求头。空字符串表示清除，不发送对应请求头。
+ * Turns identity fields into headers. An empty string means cleared, so that
+ * header is not sent.
+ */
+export declare function toHeaders(layer: OvIdentityLayer): Record<string, string>;
+/**
+ * 解析客户端级配置。`baseURL` 缺省为空字符串，表示浏览器同源请求。
+ *
+ * 身份层由调用方求值后传入：函数形式的身份字段每次请求只应求值一次，父层配置
+ * 与请求覆盖必须复用同一份结果，否则会重复刷新凭证并可能发出旧值。
+ *
+ * Resolves client-level configuration. A missing `baseURL` is an empty string,
+ * meaning a same-origin browser request.
+ *
+ * The caller passes an already-evaluated identity layer: a function-form
+ * identity field must be evaluated once per request, and both the parent
+ * configuration and the request override must reuse that one result. Evaluating
+ * twice would refresh a credential twice and could send the older value.
+ */
+export declare function resolveClientOptions(options: OvClientOptions, identity: OvIdentityLayer): OvResolvedOptions;
+/**
+ * 在已解析的客户端配置上叠加一次请求的覆盖。`baseURL` 传空字符串表示同源，
+ * 只有 `undefined` 才继承。
+ *
+ * Applies one request's override on top of resolved client configuration. An
+ * empty `baseURL` means same origin; only `undefined` inherits.
+ */
+export declare function resolveRequestOptions(local: OvRequestOptions | undefined, parent: OvResolvedOptions, mergedLayer: OvIdentityLayer): OvResolvedOptions;
+/**
+ * 拼接服务地址与接口路径。拼接只在这里做：`/gateway/ov` 加 `/api/v1/fs/ls`
+ * 得到 `/gateway/ov/api/v1/fs/ls`，接口路径以 `/` 开头也不会丢掉前缀。
+ *
+ * Joins the service address and the API path. Joining happens only here:
+ * `/gateway/ov` plus `/api/v1/fs/ls` yields `/gateway/ov/api/v1/fs/ls`, and a
+ * leading `/` in the path never drops the prefix.
+ */
+export declare function joinUrl(baseURL: string, path: string): string;
+/**
+ * 把查询参数序列化为查询串，跳过 `undefined` 与 `null`，数组按键重复。
+ * Serialises query parameters, skipping `undefined` and `null`; arrays repeat
+ * the key.
+ */
+export declare function buildQuery(query: Readonly<Record<string, OvQueryValue>> | undefined): string;
+/**
+ * 一层已求值的身份字段：`undefined` 表示未提供，空字符串表示显式清除，其余
+ * 为要发送的值。
+ * One evaluated identity layer: `undefined` means absent, an empty string means
+ * explicitly cleared, anything else is the value to send.
+ */
+export type OvIdentityLayer = Partial<Record<OvIdentityField, string>>;
+/**
+ * 一层未求值的身份字段，供 Provider 逐层合并。函数形式原样保留，由客户端在
+ * 每次请求时求值。
+ * One unevaluated identity layer for Provider merging. Function values are kept
+ * as-is so the client evaluates them per request.
+ */
+export type OvIdentityConfig = Partial<Record<OvIdentityField, OvIdentityValue>>;
+/** Provider 已解析的配置，供嵌套 Provider 继续继承。 */
+export interface OvProviderBase {
+    baseURL?: string;
+    credentials?: RequestCredentials;
+    signal?: AbortSignal;
+    /** 传输层覆盖。内层未声明时继承外层，否则内层会丢掉外层的自定义 fetch。 */
+    fetch?: typeof globalThis.fetch;
+    identity: OvIdentityConfig;
+}
+/**
+ * 把本层配置叠加到父层之上。只覆盖本层显式声明的字段：`undefined` 表示继承，
+ * 空字符串表示清除继承到的值。
+ *
+ * Applies one layer of configuration on top of its parent. Only fields this
+ * layer declares are overridden: `undefined` inherits, and an empty string
+ * clears the inherited value.
+ */
+export declare function mergeProviderConfig(inherited: OvProviderBase | undefined, local: OvClientOptions): OvProviderBase;

package/dist/client/provider.d.ts

@@ -0,0 +1,52 @@
+import type { ReactNode } from 'react';
+import type { OvClient, OvClientOptions } from './types.js';
+/**
+ * {@link OpenVikingProvider} 的属性。字段与 {@link OvClientOptions} 同形：
+ * 服务地址、身份与作用域、Cookie 策略，都按字段传值。
+ * Props of {@link OpenVikingProvider}, the same shape as {@link OvClientOptions}:
+ * the service address, identity and scope, and the cookie policy are all passed
+ * as fields.
+ */
+export interface OpenVikingProviderProps extends OvClientOptions {
+    children?: ReactNode;
+}
+/**
+ * 向子树下发请求配置。模块通过内部的 `useOvClient` 取用，宿主只需在应用根部
+ * 配置一次服务地址与身份字段，不必自己组装请求头。
+ *
+ * 开源版传 `apiKey`、`accountId`、`userId`；商业版由浏览器 Cookie 鉴权，只传
+ * `accountId`、`userId`、`resourceId`，并按需把 `credentials` 设为 `include`。
+ *
+ * 嵌套时内层只覆盖自己声明的字段，其余继承外层：外层配好服务地址与凭证后，
+ * 内层可以只改 `userId`。显式传空字符串表示清除继承到的值。
+ *
+ * 不传 `baseURL` 时按浏览器同源请求。挂载本身不发请求，也不读取浏览器里保存
+ * 的凭证。
+ *
+ * Provides request configuration to a subtree. Modules read it through the
+ * internal `useOvClient`, so a host configures the service address and identity
+ * fields once at the application root and never assembles headers itself.
+ *
+ * The open-source edition passes `apiKey`, `accountId` and `userId`; the
+ * commercial edition authenticates with a browser cookie, so it passes
+ * `accountId`, `userId` and `resourceId`, and sets `credentials` to `include`
+ * where needed.
+ *
+ * Nesting overrides only the fields the inner Provider declares and inherits the
+ * rest, so an outer Provider can own the service address and credential while an
+ * inner one changes only `userId`. An explicit empty string clears an inherited
+ * value.
+ *
+ * Without `baseURL` it targets the browser's own origin. Mounting it sends no
+ * request and reads no credential stored in the browser.
+ */
+export declare function OpenVikingProvider({ baseURL, apiKey, accountId, userId, resourceId, credentials, signal, fetch, children, }: OpenVikingProviderProps): import("react").JSX.Element;
+/**
+ * 读取最近的 Provider 提供的客户端。仅供模块内部使用，不从包入口导出：
+ * 调用方不需要知道该发什么请求，也就不会直接用它。
+ *
+ * Reads the client from the nearest Provider. Internal to modules and not
+ * exported from the package: a caller does not need to know which requests to
+ * send, so it has no reason to use this directly.
+ */
+export declare function useOvClient(): OvClient | null;

package/dist/client/types.d.ts

@@ -0,0 +1,160 @@
+/**
+ * 一个身份字段的取值：字符串，或每次请求重新求值的函数。
+ * Value of one identity field: a string, or a function re-evaluated per request.
+ */
+export type OvIdentityValue = string | (() => string | Promise<string>);
+/**
+ * 一次请求的身份与作用域。字段省略表示继承上层配置；显式传空字符串表示移除
+ * 该字段继承到的值，请求里不再发送对应请求头。
+ *
+ * 这些字段一一对应 OpenViking 的请求头，宿主传值即可，不需要自己组装 header：
+ * `apiKey` → `X-API-Key`，`accountId` → `X-OpenViking-Account`，`userId` →
+ * `X-OpenViking-User`，`resourceId` → `V-Resource-Id`。
+ *
+ * Identity and scope of one request. An omitted field inherits from the layer
+ * above; an explicit empty string removes the inherited value so the header is
+ * not sent.
+ *
+ * The fields map one to one onto OpenViking's request headers, so a host passes
+ * values instead of assembling headers: `apiKey` → `X-API-Key`, `accountId` →
+ * `X-OpenViking-Account`, `userId` → `X-OpenViking-User`, `resourceId` →
+ * `V-Resource-Id`.
+ */
+export interface OvRequestOptions {
+    /**
+     * 服务地址及可选网关前缀，不含原生接口的 `/api/v1`。省略时继承上层配置，
+     * 空字符串表示同源请求。
+     *
+     * Service address with an optional gateway prefix, excluding the native
+     * `/api/v1`. Omitted inherits the layer above; an empty string means a
+     * same-origin request.
+     */
+    baseURL?: string;
+    /**
+     * 凭证。开源版为 `X-API-Key` 的取值；商业版由浏览器 Cookie 承载，无需传入。
+     * 函数形式每次请求重新求值，可读取轮换后的凭证。
+     *
+     * Credential. In the open-source edition it becomes `X-API-Key`; the
+     * commercial edition carries it in the browser cookie, so it is omitted
+     * there. A function is re-evaluated on every request, so it can read a rotated
+     * credential.
+     */
+    apiKey?: OvIdentityValue;
+    /**
+     * OpenViking 账号 ID，对应数据空间。
+     * OpenViking account ID, which corresponds to the data space.
+     */
+    accountId?: OvIdentityValue;
+    /**
+     * 账号内的用户 ID。
+     * User ID within the account.
+     */
+    userId?: OvIdentityValue;
+    /**
+     * 当前库 ID。数据面接口需要它确定请求落在哪个库。
+     * Current library ID. Data-plane requests need it to know which library they
+     * address.
+     */
+    resourceId?: OvIdentityValue;
+    /**
+     * 调用方中止请求的信号。
+     * Signal the caller uses to abort the request.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * 创建客户端时的配置。在 {@link OvRequestOptions} 之上增加 Cookie 策略与传输层
+ * 设置。
+ * Configuration when creating a client: {@link OvRequestOptions} plus the cookie
+ * policy and transport settings.
+ */
+export interface OvClientOptions extends OvRequestOptions {
+    /**
+     * 是否携带浏览器 Cookie。商业版的数据面与控制面接口都依赖 Cookie 鉴权，
+     * 跨源调用时需要设为 `include`。
+     *
+     * Whether browser cookies are sent. The commercial edition authenticates both
+     * data-plane and control-plane requests with a cookie, so a cross-origin call
+     * needs `include`.
+     */
+    credentials?: RequestCredentials;
+    /**
+     * 自定义 fetch 实现，用于测试或在没有全局 fetch 的环境运行。
+     * A custom fetch implementation, for tests or environments without a global
+     * fetch.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * 配置逐字段解析后的结果，所有字段均已确定。
+ * The result of resolving configuration field by field, with every field
+ * decided.
+ */
+export interface OvResolvedOptions {
+    baseURL: string;
+    credentials: RequestCredentials;
+    headers: Readonly<Record<string, string>>;
+    signal?: AbortSignal;
+}
+/**
+ * 原生接口的请求描述。Client 只按 method、path、query 与 body 发请求，不解析
+ * 业务含义。
+ * A native API request. The Client sends it by method, path, query and body
+ * without interpreting the payload.
+ */
+export interface OvRequestSpec {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+    /**
+     * 以 `/` 开头的接口路径，不含服务地址与网关前缀。
+     * API path starting with `/`, without the service address or gateway prefix.
+     */
+    path: string;
+    query?: Readonly<Record<string, OvQueryValue>>;
+    body?: unknown;
+    /**
+     * 本次请求的身份、作用域与服务地址覆盖，例如切换到另一个库或另一个网关。
+     * Identity, scope and service-address override for this request, for example
+     * switching to another library or another gateway.
+     */
+    options?: OvRequestOptions;
+}
+/** 查询参数可接受的值；`undefined` 与 `null` 表示不发送。 */
+export type OvQueryValue = string | number | boolean | null | undefined | readonly (string | number | boolean)[];
+/**
+ * 原生接口的成功响应外壳。`result` 承载业务数据，其余字段是外层元数据。
+ * The success envelope of a native response. `result` carries the payload and
+ * the remaining fields are outer metadata.
+ */
+export interface OvSuccessEnvelope<TResult = unknown> {
+    result?: TResult;
+    status?: string;
+    [key: string]: unknown;
+}
+/** 原生接口的错误响应外壳。The error envelope of a native response. */
+export interface OvErrorEnvelope {
+    status?: string;
+    error?: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/**
+ * 框架无关的请求能力。库自带基于 `fetch` 的实现，宿主也可以自行实现以复用
+ * 已有请求层；模块只依赖本接口。
+ * Framework-neutral request capability. The library ships a `fetch`-based
+ * implementation, and a host may implement it to reuse an existing request
+ * layer; modules depend only on this interface.
+ */
+export interface OvClient {
+    /**
+     * 发一次请求并返回原生响应的 `result`。
+     * Sends one request and returns the native response's `result`.
+     */
+    request<TResult>(spec: OvRequestSpec): Promise<TResult>;
+    /**
+     * 当前生效的服务地址，用于缓存键与订阅隔离。
+     * The effective service address, used to isolate caches and subscriptions.
+     */
+    readonly baseURL: string;
+}