@yorun-ai/vrpc 0.9.2 → 0.9.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CONTRIBUTING.md +24 -2
- package/README.md +132 -248
- package/README.zh-CN.md +112 -242
- package/dist/client.cjs +2 -1
- package/dist/client.es.js +2 -1
- package/docs/guides/axios.md +3 -0
- package/docs/guides/cdn.md +221 -0
- package/docs/guides/usage.md +5 -0
- package/docs/reference/README.md +240 -0
- package/package.json +2 -2
package/CONTRIBUTING.md
CHANGED
|
@@ -5,7 +5,7 @@ This guide defines the development, verification, documentation, commit, and pul
|
|
|
5
5
|
## Prerequisites
|
|
6
6
|
|
|
7
7
|
- Node.js 24.11 or later.
|
|
8
|
-
- pnpm
|
|
8
|
+
- pnpm 12.5.1, using the repository lockfile.
|
|
9
9
|
|
|
10
10
|
Install dependencies from the repository root:
|
|
11
11
|
|
|
@@ -22,6 +22,7 @@ pnpm install --frozen-lockfile
|
|
|
22
22
|
- `src/entrypoints/`: public package entrypoints.
|
|
23
23
|
- `test/`: behavioral, compatibility, and release tests.
|
|
24
24
|
- `docs/guides/`: user-facing guides.
|
|
25
|
+
- `docs/reference/`: public API reference.
|
|
25
26
|
- `docs/maintainers/`: architecture, protocol, and release documentation.
|
|
26
27
|
|
|
27
28
|
Read `AGENTS.md`, `README.md`, and the applicable documentation before changing behavior or public contracts.
|
|
@@ -58,13 +59,34 @@ Do not commit generated `dist/` output or `node_modules/`.
|
|
|
58
59
|
|
|
59
60
|
## Documentation
|
|
60
61
|
|
|
61
|
-
|
|
62
|
+
Documentation is part of the public API contract. Repository documentation is
|
|
63
|
+
maintained in English; the root `README.zh-CN.md` is the Chinese entry point and
|
|
64
|
+
must stay structurally aligned with `README.md`. Keep both root README files
|
|
65
|
+
synchronized when their shared content changes.
|
|
62
66
|
|
|
63
67
|
- Keep package overview and documentation navigation in `README.md` and `README.zh-CN.md`.
|
|
64
68
|
- Put task-oriented material for package users in `docs/guides/`.
|
|
69
|
+
- Put public exports, option tables, defaults, and error fields in `docs/reference/`.
|
|
65
70
|
- Put architecture, protocol, release, and other repository-maintenance material in `docs/maintainers/`.
|
|
66
71
|
- Keep protocol details in `docs/maintainers/protocol.md` instead of duplicating them in the architecture overview.
|
|
67
72
|
|
|
73
|
+
Prefer linking to a canonical guide over duplicating long explanations across
|
|
74
|
+
the README and `docs/`. Do not shorten the README by deleting useful detail;
|
|
75
|
+
move that detail to the document that owns it.
|
|
76
|
+
|
|
77
|
+
### Documentation requirements
|
|
78
|
+
|
|
79
|
+
When changing public exports, types, defaults, request behavior, headers, error
|
|
80
|
+
handling, or transport behavior:
|
|
81
|
+
|
|
82
|
+
- Update the relevant user guide.
|
|
83
|
+
- Update `docs/reference/README.md` when public signatures or behavior change.
|
|
84
|
+
- Update `docs/maintainers/protocol.md` when wire behavior changes.
|
|
85
|
+
- Keep README examples valid and consistent with the published package.
|
|
86
|
+
- Keep `README.md` and `README.zh-CN.md` structurally aligned.
|
|
87
|
+
- Verify CDN examples in `docs/guides/cdn.md` against the actual published
|
|
88
|
+
bundles, including loading mode and version pinning.
|
|
89
|
+
|
|
68
90
|
## Commits
|
|
69
91
|
|
|
70
92
|
Create focused commits that explain the purpose of the change. Avoid mixing unrelated cleanup with functional work. Before committing, inspect the diff and run `git diff --check` in addition to the applicable project checks.
|
package/README.md
CHANGED
|
@@ -1,18 +1,42 @@
|
|
|
1
1
|
# @yorun-ai/vrpc
|
|
2
2
|
|
|
3
|
-
[](https://www.npmjs.com/package/@yorun-ai/vrpc)
|
|
4
|
+
[](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml)
|
|
5
|
+
[](https://packagephobia.com/result?p=%40yorun-ai%2Fvrpc)
|
|
6
|
+
[](https://www.npmjs.com/package/@yorun-ai/vrpc)
|
|
7
|
+
[](https://www.npmjs.com/package/@yorun-ai/vrpc)
|
|
8
|
+
[](https://github.com/yorun-ai/vrpc-ts/blob/main/LICENSE)
|
|
6
9
|
|
|
7
10
|
**English** | [简体中文](README.zh-CN.md)
|
|
8
11
|
|
|
9
|
-
|
|
12
|
+
A lightweight TypeScript client runtime for [Vine](https://github.com/yorun-ai/vine) vRPC and generic HTTP requests.
|
|
10
13
|
|
|
11
|
-
|
|
14
|
+
## What is this?
|
|
12
15
|
|
|
13
|
-
|
|
16
|
+
The package exposes two clients that share one request runtime:
|
|
17
|
+
|
|
18
|
+
- **vRPC client** — calls Vine vRPC methods over HTTP. It builds the vRPC path
|
|
19
|
+
and envelope, generates `vrpc-trace`, `vrpc-client`, and `vrpc-options`
|
|
20
|
+
headers, negotiates JSON or CBOR, and normalizes the vRPC response.
|
|
21
|
+
- **Generic HTTP client** — calls ordinary HTTP APIs with shared configuration,
|
|
22
|
+
interceptors, timeouts, cancellation, and normalized errors. It knows nothing
|
|
23
|
+
about the vRPC protocol.
|
|
24
|
+
|
|
25
|
+
Choose the vRPC client when your server is a Vine vRPC service. Choose the
|
|
26
|
+
generic HTTP client for everything else. Both are Fetch-based and browser-first,
|
|
27
|
+
and both run in any JavaScript runtime that provides `fetch`.
|
|
28
|
+
|
|
29
|
+
## Features
|
|
14
30
|
|
|
15
|
-
|
|
31
|
+
- TypeScript-first API with published types for every entry point.
|
|
32
|
+
- Browser Fetch-based transport, replaceable with a custom transport.
|
|
33
|
+
- Two clients: Vine vRPC and generic HTTP.
|
|
34
|
+
- Client-level defaults with per-request overrides.
|
|
35
|
+
- Interceptors for request, response, and error lifecycle hooks.
|
|
36
|
+
- Normalized, classified errors and `AbortSignal` cancellation.
|
|
37
|
+
- Optional CBOR integration through a user-provided codec, with no bundled
|
|
38
|
+
codec dependency.
|
|
39
|
+
- ESM and CommonJS builds, plus browser ES module CDN usage.
|
|
16
40
|
|
|
17
41
|
## Installation
|
|
18
42
|
|
|
@@ -20,20 +44,19 @@ The package starts at `0.9.0`. It is ready for use, but versions below `1.0.0` d
|
|
|
20
44
|
pnpm add @yorun-ai/vrpc
|
|
21
45
|
```
|
|
22
46
|
|
|
23
|
-
|
|
47
|
+
```bash
|
|
48
|
+
npm install @yorun-ai/vrpc
|
|
49
|
+
```
|
|
24
50
|
|
|
25
|
-
|
|
26
|
-
- `@yorun-ai/vrpc/http`: generic HTTP client.
|
|
51
|
+
## Quick start
|
|
27
52
|
|
|
28
|
-
|
|
53
|
+
### 1. Invoke a vRPC method
|
|
29
54
|
|
|
30
55
|
```ts
|
|
31
|
-
import { createVrpcClient, getClientInstanceId
|
|
56
|
+
import { createVrpcClient, getClientInstanceId } from "@yorun-ai/vrpc";
|
|
32
57
|
|
|
33
58
|
const client = createVrpcClient({
|
|
34
59
|
prefixUrl: "https://api.example.com/invoke",
|
|
35
|
-
timeoutMs: 15_000,
|
|
36
|
-
suppressGlobalToast: false,
|
|
37
60
|
clientInfo: {
|
|
38
61
|
clientName: "demo.browser",
|
|
39
62
|
clientVersion: "1.0.0",
|
|
@@ -41,132 +64,17 @@ const client = createVrpcClient({
|
|
|
41
64
|
},
|
|
42
65
|
});
|
|
43
66
|
|
|
44
|
-
client.use({
|
|
45
|
-
onError(error, context) {
|
|
46
|
-
if (isVrpcError(error) && error.kind === "abort") {
|
|
47
|
-
return;
|
|
48
|
-
}
|
|
49
|
-
if (context.options.suppressGlobalToast) {
|
|
50
|
-
return;
|
|
51
|
-
}
|
|
52
|
-
console.error(error);
|
|
53
|
-
},
|
|
54
|
-
});
|
|
55
|
-
|
|
56
67
|
const profile = await client.invoke<{ id: number; name: string }>({
|
|
57
68
|
serviceName: "user.UserService",
|
|
58
69
|
methodName: "getProfile",
|
|
59
70
|
params: { userId: 1 },
|
|
60
|
-
options: {
|
|
61
|
-
timeoutMs: 3_000,
|
|
62
|
-
suppressGlobalToast: true,
|
|
63
|
-
},
|
|
64
|
-
});
|
|
65
|
-
|
|
66
|
-
// An argument-free method accepts null or an empty object.
|
|
67
|
-
await client.invoke({
|
|
68
|
-
serviceName: "user.UserService",
|
|
69
|
-
methodName: "ping",
|
|
70
|
-
params: null,
|
|
71
71
|
});
|
|
72
|
-
|
|
73
|
-
try {
|
|
74
|
-
await client.invoke({
|
|
75
|
-
serviceName: "user.UserService",
|
|
76
|
-
methodName: "missing",
|
|
77
|
-
params: {},
|
|
78
|
-
});
|
|
79
|
-
} catch (error) {
|
|
80
|
-
if (isVrpcError(error) && error.kind === "invoke") {
|
|
81
|
-
console.error(error.status, error.vrpcStatus, error.code, error.reason);
|
|
82
|
-
}
|
|
83
|
-
}
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
`traceMode` controls only the automatically generated `vrpc-trace` header; it does not change routing or `prefixUrl`. Use the default `"portal"` mode through Vine Portal, where the header contains only an id. For a direct connection to a vRPC service, set `traceMode: "direct"` so the runtime generates both an id and a span. Per-call `options.trace` overrides the generated value.
|
|
87
|
-
|
|
88
|
-
### Request options
|
|
89
|
-
|
|
90
|
-
```ts
|
|
91
|
-
type VrpcRequestOptions = {
|
|
92
|
-
headers?: HeadersInit;
|
|
93
|
-
timeoutMs?: number;
|
|
94
|
-
requestInit?: Omit<RequestInit, "method" | "body" | "headers">;
|
|
95
|
-
suppressGlobalToast?: boolean;
|
|
96
|
-
trace?: { id: string; span?: string };
|
|
97
|
-
wire?: VrpcMethodWireSpec;
|
|
98
|
-
};
|
|
99
72
|
```
|
|
100
73
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
- `wire` is per-call only and never enters the HTTP payload.
|
|
104
|
-
- Argument-free methods accept both `params: null` and `params: {}`.
|
|
105
|
-
- The browser transport defaults to `credentials: "omit"`; use `requestInit.credentials` when cookies are needed.
|
|
74
|
+
The final URL is `<prefixUrl>/<serviceName>/<methodName>`. Methods without
|
|
75
|
+
arguments accept `params: null` or `params: {}`.
|
|
106
76
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
The runtime has no built-in CBOR dependency. A method without `wire` always uses JSON and requires no codec. Generated clients attach a sparse wire schema when a method's arguments or result contain Binary:
|
|
110
|
-
|
|
111
|
-
```ts
|
|
112
|
-
import type { VrpcCborCodec, VrpcWireSchema } from "@yorun-ai/vrpc";
|
|
113
|
-
|
|
114
|
-
const uploadArguments: VrpcWireSchema = {
|
|
115
|
-
kind: "object",
|
|
116
|
-
fields: {
|
|
117
|
-
content: { kind: "binary" },
|
|
118
|
-
},
|
|
119
|
-
};
|
|
120
|
-
|
|
121
|
-
const cborCodec: VrpcCborCodec = {
|
|
122
|
-
encode: (value) => yourCborLibrary.encode(value),
|
|
123
|
-
decode: (bytes) => yourCborLibrary.decode(bytes),
|
|
124
|
-
};
|
|
125
|
-
|
|
126
|
-
const client = createVrpcClient({
|
|
127
|
-
prefixUrl: "https://api.example.com/invoke",
|
|
128
|
-
clientInfo: {
|
|
129
|
-
clientName: "demo.browser",
|
|
130
|
-
clientVersion: "1.0.0",
|
|
131
|
-
clientInstanceId: getClientInstanceId(),
|
|
132
|
-
},
|
|
133
|
-
cborCodec,
|
|
134
|
-
});
|
|
135
|
-
|
|
136
|
-
await client.invoke({
|
|
137
|
-
serviceName: "file.FileService",
|
|
138
|
-
methodName: "upload",
|
|
139
|
-
params: { content: new Uint8Array([1, 2, 3]) },
|
|
140
|
-
options: {
|
|
141
|
-
wire: { arguments: uploadArguments },
|
|
142
|
-
},
|
|
143
|
-
});
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
Automatic selection:
|
|
147
|
-
|
|
148
|
-
- `wire.arguments`: the request `content-type` is `application/vrpc+cbor`.
|
|
149
|
-
- `wire.result`: `accept` is `application/vrpc+cbor, application/vrpc+json`.
|
|
150
|
-
- Neither: JSON.
|
|
151
|
-
- Wire without `cborCodec` throws a configuration error before network I/O.
|
|
152
|
-
|
|
153
|
-
`VrpcWireSchema` supports Binary, nullable, list, object, and `Map<Int|string, T>`. Binary remains raw bytes in CBOR, while an integer-keyed `Record` becomes a real integer-keyed CBOR Map.
|
|
154
|
-
|
|
155
|
-
## Vine Header
|
|
156
|
-
|
|
157
|
-
Generated by the runtime:
|
|
158
|
-
|
|
159
|
-
```text
|
|
160
|
-
content-type: application/vrpc+json
|
|
161
|
-
accept: application/vrpc+json
|
|
162
|
-
vrpc-trace: id=<32hex>
|
|
163
|
-
vrpc-client: name=demo.browser,version=1.0.0,instanceId=<uuid>
|
|
164
|
-
vrpc-options: timeout=3000ms
|
|
165
|
-
```
|
|
166
|
-
|
|
167
|
-
Custom `headers` cannot override `accept`, `content-type`, or any `vrpc-*` header. An explicit `timeoutMs` controls both the local `AbortController` and `vrpc-options`.
|
|
168
|
-
|
|
169
|
-
## Generic HTTP client
|
|
77
|
+
### 2. Call a plain HTTP API
|
|
170
78
|
|
|
171
79
|
```ts
|
|
172
80
|
import { createHttpClient } from "@yorun-ai/vrpc/http";
|
|
@@ -176,14 +84,7 @@ const http = createHttpClient({
|
|
|
176
84
|
timeoutMs: 5_000,
|
|
177
85
|
});
|
|
178
86
|
|
|
179
|
-
const profile = await http.request<{ id: number }>({
|
|
180
|
-
path: "/users/me",
|
|
181
|
-
query: { withProfile: true },
|
|
182
|
-
options: {
|
|
183
|
-
requestInit: { credentials: "include" },
|
|
184
|
-
suppressGlobalToast: true,
|
|
185
|
-
},
|
|
186
|
-
});
|
|
87
|
+
const profile = await http.request<{ id: number }>({ path: "/users/me" });
|
|
187
88
|
|
|
188
89
|
await http.request({
|
|
189
90
|
path: "/users",
|
|
@@ -192,140 +93,123 @@ await http.request({
|
|
|
192
93
|
});
|
|
193
94
|
```
|
|
194
95
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
Request paths are relative to `prefixUrl` by default. Absolute request URLs are rejected before transport so an untrusted `path` cannot redirect client-level headers to another origin. For a trusted use case that requires complete URLs, set `allowAbsoluteUrls: true` when creating the HTTP client. This opt-in accepts only `http:` and `https:` URLs, continues to send the configured headers to the selected URL, and does not permit protocol-relative URLs such as `//example.com/path`.
|
|
96
|
+
Use `json` for a JSON body and `body` for raw `BodyInit` values such as
|
|
97
|
+
`FormData`.
|
|
198
98
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
Use the single `isVrpcError` guard, then classify a normalized vRPC client error by `kind`:
|
|
99
|
+
### 3. Handle errors
|
|
202
100
|
|
|
203
101
|
```ts
|
|
204
102
|
import { isVrpcError } from "@yorun-ai/vrpc";
|
|
205
103
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
if (error.kind === "invoke") {
|
|
217
|
-
console.error(error.vrpcStatus, error.code, error.reason, error.message);
|
|
218
|
-
return;
|
|
104
|
+
try {
|
|
105
|
+
await client.invoke({
|
|
106
|
+
serviceName: "user.UserService",
|
|
107
|
+
methodName: "getProfile",
|
|
108
|
+
params: { userId: 1 },
|
|
109
|
+
});
|
|
110
|
+
} catch (error) {
|
|
111
|
+
if (isVrpcError(error) && error.kind === "invoke") {
|
|
112
|
+
// Server rejected the invocation.
|
|
113
|
+
console.error(error.vrpcStatus, error.code, error.reason);
|
|
219
114
|
}
|
|
220
|
-
|
|
221
|
-
console.error(error.kind, error.message, error.cause);
|
|
222
115
|
}
|
|
223
116
|
```
|
|
224
117
|
|
|
225
|
-
The
|
|
118
|
+
The generic HTTP client provides the equivalent `isHttpError` guard.
|
|
226
119
|
|
|
227
|
-
|
|
120
|
+
## Browser CDN
|
|
228
121
|
|
|
229
|
-
|
|
122
|
+
Use the published ES module builds when you want to try a client without
|
|
123
|
+
installing a package or configuring a bundler:
|
|
230
124
|
|
|
231
|
-
|
|
125
|
+
```html
|
|
126
|
+
<script type="module">
|
|
127
|
+
import { createVrpcClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm";
|
|
232
128
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
try {
|
|
236
|
-
return await client.invoke({
|
|
237
|
-
serviceName: "user.UserService",
|
|
238
|
-
methodName: "getProfile",
|
|
239
|
-
params: { userId: 1 },
|
|
240
|
-
options: { suppressGlobalToast: true },
|
|
241
|
-
});
|
|
242
|
-
} catch (error) {
|
|
243
|
-
if (!isVrpcError(error)) {
|
|
244
|
-
throw error;
|
|
245
|
-
}
|
|
246
|
-
if (error.kind === "abort") {
|
|
247
|
-
return;
|
|
248
|
-
}
|
|
249
|
-
if (error.kind === "invoke" && error.code === "USER" && error.reason === "NOT_FOUND") {
|
|
250
|
-
showToast(error.message);
|
|
251
|
-
return;
|
|
252
|
-
}
|
|
253
|
-
showToast("Unable to load the profile. Please try again.");
|
|
254
|
-
}
|
|
255
|
-
}
|
|
129
|
+
// ...
|
|
130
|
+
</script>
|
|
256
131
|
```
|
|
257
132
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
## Cancel requests
|
|
133
|
+
The package ships ES modules only. There is no global build, so a classic
|
|
134
|
+
`<script src="...">` tag cannot be used; the tag must have `type="module"`.
|
|
261
135
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
```ts
|
|
265
|
-
import { isVrpcError } from "@yorun-ai/vrpc";
|
|
136
|
+
See [Browser CDN usage](docs/guides/cdn.md) for complete HTML examples, the
|
|
137
|
+
generic HTTP entry, version pinning, and troubleshooting.
|
|
266
138
|
|
|
267
|
-
|
|
268
|
-
const request = client.invoke({
|
|
269
|
-
serviceName: "user.UserService",
|
|
270
|
-
methodName: "getProfile",
|
|
271
|
-
params: { userId: 1 },
|
|
272
|
-
options: {
|
|
273
|
-
requestInit: { signal: controller.signal },
|
|
274
|
-
},
|
|
275
|
-
});
|
|
276
|
-
|
|
277
|
-
controller.abort();
|
|
278
|
-
|
|
279
|
-
try {
|
|
280
|
-
await request;
|
|
281
|
-
} catch (error) {
|
|
282
|
-
if (!(isVrpcError(error) && error.kind === "abort")) {
|
|
283
|
-
throw error;
|
|
284
|
-
}
|
|
285
|
-
}
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
Handle `abort` once in a global `onError` interceptor when cancellation should be silent in the UI. Timeouts remain `kind: "timeout"` and are not treated as caller cancellation.
|
|
139
|
+
## Entry points
|
|
289
140
|
|
|
290
|
-
|
|
141
|
+
| Import | Contents |
|
|
142
|
+
| ----------------------- | ------------------------------------------------------------- |
|
|
143
|
+
| `@yorun-ai/vrpc` | vRPC client, protocol helpers, transport, errors, and types. |
|
|
144
|
+
| `@yorun-ai/vrpc/client` | Explicit vRPC entry; identical to the package root. |
|
|
145
|
+
| `@yorun-ai/vrpc/http` | Generic HTTP client, Fetch transport, HTTP errors, and types. |
|
|
146
|
+
|
|
147
|
+
## Configuration at a glance
|
|
148
|
+
|
|
149
|
+
Both clients accept `prefixUrl`, `headers`, `timeoutMs`, `requestInit`,
|
|
150
|
+
`suppressGlobalToast`, `fetchImpl`, `transport`, and `interceptors`. The vRPC
|
|
151
|
+
client additionally requires `clientInfo` and accepts `traceMode` and
|
|
152
|
+
`cborCodec`. Per-request `options` override client defaults, and
|
|
153
|
+
`context.options` always contains the merged result.
|
|
154
|
+
|
|
155
|
+
The vRPC client adds two request options: `trace` replaces the generated
|
|
156
|
+
`vrpc-trace` header, and `wire` selects JSON or CBOR for a single call. A wire
|
|
157
|
+
schema is never serialized into the HTTP body, and it requires a `cborCodec`.
|
|
158
|
+
|
|
159
|
+
## Advanced capabilities
|
|
160
|
+
|
|
161
|
+
- **Interceptors** — `beforeRequest`, `afterResponse`, and `onError` hooks
|
|
162
|
+
registered with `client.use()`. `onError` runs before the request promise
|
|
163
|
+
rejects and does not swallow the failure.
|
|
164
|
+
- **Cancellation** — pass an `AbortSignal` through `requestInit.signal`.
|
|
165
|
+
Cancellation rejects with `kind: "abort"`. Timeouts stay `kind: "timeout"`.
|
|
166
|
+
- **Tracing** — `traceMode: "portal"` (default) generates a trace id;
|
|
167
|
+
`traceMode: "direct"` also generates a span. It never changes routing or
|
|
168
|
+
`prefixUrl`.
|
|
169
|
+
- **CBOR** — provide a `cborCodec` and a per-call `wire` schema when arguments
|
|
170
|
+
or results contain `Binary`.
|
|
171
|
+
- **Custom transport** — implement `VrpcTransport` or `HttpTransport` to
|
|
172
|
+
replace Fetch with another I/O layer.
|
|
173
|
+
- **`suppressGlobalToast`** — application-defined error UI policy metadata.
|
|
174
|
+
The package never displays UI, skips `onError`, or consumes the rejection.
|
|
175
|
+
|
|
176
|
+
The [Usage guide](docs/guides/usage.md) covers each capability with runnable
|
|
177
|
+
examples.
|
|
291
178
|
|
|
292
|
-
|
|
293
|
-
import {
|
|
294
|
-
buildVrpcHeaders,
|
|
295
|
-
buildVrpcPath,
|
|
296
|
-
buildVrpcRequestBody,
|
|
297
|
-
generateVrpcId,
|
|
298
|
-
} from "@yorun-ai/vrpc";
|
|
299
|
-
|
|
300
|
-
const headers = buildVrpcHeaders({
|
|
301
|
-
clientInfo: {
|
|
302
|
-
clientName: "demo.browser",
|
|
303
|
-
clientVersion: "1.0.0",
|
|
304
|
-
clientInstanceId: getClientInstanceId(),
|
|
305
|
-
},
|
|
306
|
-
trace: { id: generateVrpcId() },
|
|
307
|
-
timeoutMs: 3_000,
|
|
308
|
-
});
|
|
179
|
+
## Documentation
|
|
309
180
|
|
|
310
|
-
|
|
311
|
-
const body = buildVrpcRequestBody({ userId: 1 });
|
|
312
|
-
```
|
|
181
|
+
### User guides
|
|
313
182
|
|
|
314
|
-
|
|
183
|
+
- [Usage](docs/guides/usage.md) — client configuration, request options,
|
|
184
|
+
interceptors, errors, cancellation, CBOR, and custom transports.
|
|
185
|
+
- [Browser CDN](docs/guides/cdn.md) — CDN loading modes and complete HTML
|
|
186
|
+
examples.
|
|
187
|
+
- [Axios integration](docs/guides/axios.md) — custom Axios transport and JSON
|
|
188
|
+
protocol helpers.
|
|
315
189
|
|
|
316
|
-
|
|
190
|
+
### Reference and maintainers
|
|
317
191
|
|
|
318
|
-
- [
|
|
319
|
-
|
|
192
|
+
- [API Reference](docs/reference/README.md) — public exports, types,
|
|
193
|
+
configuration options, defaults, and errors.
|
|
194
|
+
- [Architecture](docs/maintainers/architecture.md) — module boundaries and
|
|
195
|
+
request flow.
|
|
196
|
+
- [vRPC protocol](docs/maintainers/protocol.md) — paths, envelopes, headers,
|
|
197
|
+
content negotiation, wire schemas, and generated-client requirements.
|
|
198
|
+
- [Releasing](docs/maintainers/releasing.md) — version management and npm
|
|
199
|
+
publishing.
|
|
200
|
+
- [Contributing](CONTRIBUTING.md) — development, testing, documentation, and
|
|
201
|
+
pull-request workflow.
|
|
320
202
|
|
|
321
|
-
|
|
203
|
+
The root README and `docs/guides/` are for package users. `docs/maintainers/`
|
|
204
|
+
is for repository maintainers and integrators implementing transports or code
|
|
205
|
+
generation.
|
|
322
206
|
|
|
323
|
-
|
|
324
|
-
- [vRPC protocol](./docs/maintainers/protocol.md): paths, envelopes, headers, content negotiation, wire schemas, and generated-client requirements.
|
|
325
|
-
- [Releasing](./docs/maintainers/releasing.md): version management and npm publishing.
|
|
326
|
-
- [Contributing](./CONTRIBUTING.md): development, testing, documentation, commit, and pull-request workflow.
|
|
207
|
+
## Stability
|
|
327
208
|
|
|
328
|
-
The
|
|
209
|
+
The package is in the `0.x` release line. It is ready for use, but versions
|
|
210
|
+
below `1.0.0` do not guarantee a stable public API. A breaking change may be
|
|
211
|
+
released in a new `0.x` minor version and will include migration guidance.
|
|
212
|
+
Version `1.0.0` will mark the stable API commitment.
|
|
329
213
|
|
|
330
214
|
## License
|
|
331
215
|
|