@yorun-ai/vrpc 0.9.2 → 0.10.0

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.
@@ -0,0 +1,221 @@
1
+ # Browser CDN usage
2
+
3
+ This guide shows how to use `@yorun-ai/vrpc` from a CDN in a plain HTML page,
4
+ without a bundler or a package install. For packaged applications, prefer the
5
+ npm installation and the [Usage guide](./usage.md).
6
+
7
+ ## 1. Overview
8
+
9
+ Use the CDN builds when you want to:
10
+
11
+ - prototype against a real vRPC or HTTP endpoint from a static page,
12
+ - embed the client in a CodePen, JSFiddle, or documentation snippet,
13
+ - keep a small internal tool free of a build step.
14
+
15
+ Two constraints apply to every CDN setup:
16
+
17
+ - **ES modules only.** The published package ships ES module and CommonJS
18
+ builds, not an IIFE/UMD bundle. There is no `window.Vrpc` or `window.Http`
19
+ global, and a classic `<script src="...">` without `type="module"` fails with
20
+ a syntax error because the file contains `import` statements.
21
+ - **Pin the version.** Use an exact version such as `@0.9.3` so a new release
22
+ cannot change the behavior of a page you already published.
23
+
24
+ The runtime needs native ES modules, `fetch`, `AbortController`, and `Headers`.
25
+ All current evergreen browsers provide these.
26
+
27
+ ## 2. Available bundles
28
+
29
+ | Import | File | Format |
30
+ | ------------------------------ | ------------------- | -------------------------------------------------------- |
31
+ | vRPC client + protocol helpers | `dist/client.es.js` | ES module; imports one relative shared chunk |
32
+ | Generic HTTP client | `dist/http.es.js` | ES module; imports the same shared chunk |
33
+ | vRPC client (bundled) | `+esm` | ES module; single self-contained file, no extra requests |
34
+ | Generic HTTP client (bundled) | `/http/+esm` | ES module; single self-contained file, no extra requests |
35
+
36
+ Notes:
37
+
38
+ - `dist/client.cjs` and `dist/http.cjs` are CommonJS builds and cannot be
39
+ loaded directly by a browser.
40
+ - `dist/client.es.min.js` and `dist/http.es.min.js` are minified on demand by
41
+ jsDelivr from the published `.es.js` files. They are still ES modules, and
42
+ because they are generated they must not be used with subresource integrity
43
+ hashes.
44
+ - `dist/client.es.js` and `dist/http.es.js` import a build-specific shared chunk
45
+ whose name changes on every release. Do not copy a chunk filename into your
46
+ page; import the entry file and let the browser resolve it, or use `+esm` to
47
+ avoid the extra request entirely.
48
+
49
+ ## 3. Loading the module
50
+
51
+ Browser ESM with jsDelivr:
52
+
53
+ ```html
54
+ <script type="module">
55
+ import { createVrpcClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm";
56
+
57
+ // ...
58
+ </script>
59
+ ```
60
+
61
+ The same API is available from the unbundled entry file:
62
+
63
+ ```html
64
+ <script type="module">
65
+ import { createVrpcClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/dist/client.es.js";
66
+ </script>
67
+ ```
68
+
69
+ Import the HTTP client from its own module path:
70
+
71
+ ```html
72
+ <script type="module">
73
+ import { createHttpClient } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/http/+esm";
74
+ </script>
75
+ ```
76
+
77
+ This form does **not** work, because the bundle is an ES module:
78
+
79
+ ```html
80
+ <!-- Fails: the runtime has no global build. -->
81
+ <script src="https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/dist/client.es.js"></script>
82
+ <script>
83
+ const client = Vrpc.createVrpcClient({/* ... */}); // Vrpc is undefined
84
+ </script>
85
+ ```
86
+
87
+ ## 4. Complete vRPC example
88
+
89
+ Save this as `vrpc-demo.html` and open it in a browser. It creates a client,
90
+ invokes a method, and renders either the result or a classified error.
91
+
92
+ ```html
93
+ <!doctype html>
94
+ <html lang="en">
95
+ <head>
96
+ <meta charset="utf-8" />
97
+ <title>vRPC CDN demo</title>
98
+ </head>
99
+ <body>
100
+ <pre id="output">loading…</pre>
101
+
102
+ <script type="module">
103
+ import {
104
+ createVrpcClient,
105
+ getClientInstanceId,
106
+ isVrpcError,
107
+ } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm";
108
+
109
+ const output = document.getElementById("output");
110
+
111
+ const client = createVrpcClient({
112
+ prefixUrl: "https://api.example.com/invoke",
113
+ clientInfo: {
114
+ clientName: "demo.browser",
115
+ clientVersion: "1.0.0",
116
+ clientInstanceId: getClientInstanceId(),
117
+ },
118
+ });
119
+
120
+ try {
121
+ const profile = await client.invoke({
122
+ serviceName: "user.UserService",
123
+ methodName: "getProfile",
124
+ params: { userId: 1 },
125
+ });
126
+ output.textContent = JSON.stringify(profile, null, 2);
127
+ } catch (error) {
128
+ if (!isVrpcError(error)) {
129
+ output.textContent = String(error);
130
+ } else if (error.kind === "invoke") {
131
+ output.textContent = `${error.vrpcStatus} ${error.code} ${error.reason}`;
132
+ } else {
133
+ output.textContent = `${error.kind}: ${error.message}`;
134
+ }
135
+ }
136
+ </script>
137
+ </body>
138
+ </html>
139
+ ```
140
+
141
+ Top-level `await` is valid inside a module script, so no wrapper function is
142
+ required.
143
+
144
+ ## 5. Complete HTTP example
145
+
146
+ The generic HTTP client is a separate module and does not use vRPC protocol
147
+ headers.
148
+
149
+ ```html
150
+ <!doctype html>
151
+ <html lang="en">
152
+ <head>
153
+ <meta charset="utf-8" />
154
+ <title>HTTP CDN demo</title>
155
+ </head>
156
+ <body>
157
+ <pre id="output">loading…</pre>
158
+
159
+ <script type="module">
160
+ import {
161
+ createHttpClient,
162
+ isHttpError,
163
+ } from "https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/http/+esm";
164
+
165
+ const output = document.getElementById("output");
166
+
167
+ const http = createHttpClient({
168
+ prefixUrl: "https://api.example.com",
169
+ timeoutMs: 5_000,
170
+ });
171
+
172
+ try {
173
+ const profile = await http.request({ path: "/users/me" });
174
+ output.textContent = JSON.stringify(profile, null, 2);
175
+ } catch (error) {
176
+ output.textContent = isHttpError(error) ? `${error.kind}: ${error.message}` : String(error);
177
+ }
178
+ </script>
179
+ </body>
180
+ </html>
181
+ ```
182
+
183
+ ## 6. Version pinning
184
+
185
+ Always pin an exact version in the URL:
186
+
187
+ ```text
188
+ https://cdn.jsdelivr.net/npm/@yorun-ai/vrpc@0.9.3/+esm
189
+ ```
190
+
191
+ `@0.9.3` is immutable on jsDelivr. A floating range such as `@0` resolves to the
192
+ newest `0.x` release and can pick up behavior changes; use it only for a
193
+ throwaway prototype. Keep the pinned version aligned with the version in your
194
+ `package.json` when the same project uses both.
195
+
196
+ ## 7. Troubleshooting
197
+
198
+ | Symptom | Cause and fix |
199
+ | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
200
+ | `Cannot use import statement outside a module` | The script tag is missing `type="module"`. |
201
+ | `window.Vrpc is undefined` / `window.Http is undefined` | There is no global build. Import the module instead. |
202
+ | `Failed to resolve module specifier` | A bare specifier such as `@yorun-ai/vrpc` was used in a browser import without a CDN URL or an import map. |
203
+ | `404` when importing the shared chunk | A hashed chunk filename was copied into a page. Import `dist/client.es.js` / `dist/http.es.js` and let the browser resolve it, or use `+esm`. |
204
+ | Blocked by CORS | The target API must return `Access-Control-Allow-Origin`. Cookies additionally require `requestInit: { credentials: "include" }` on the client and `Access-Control-Allow-Credentials: true` on the server. |
205
+ | Unexpected behavior after a release | The CDN URL is not pinned to an exact version. |
206
+ | `fetch is not available in current runtime` | The page runs in an environment without a global `fetch`, such as a very old browser. |
207
+ | An interceptor is never called | `client.use(...)` must be called on the same client instance that performs the request. |
208
+
209
+ For protocol-level failures such as a missing `vrpc-status` or `vrpc-server`
210
+ header, see the [vRPC protocol](../maintainers/protocol.md) reference.
211
+
212
+ ## 8. Verification status
213
+
214
+ The examples in this guide were checked against the `0.9.3` bundle in a real
215
+ browser: the bundled `+esm` imports, the unbundled `dist/*.es.js` entry files,
216
+ and the jsDelivr-generated `dist/*.es.min.js` variants all load as ES modules
217
+ and complete a real invocation. Loading any of them as a classic script fails,
218
+ and no global variable is created.
219
+
220
+ Each version ships its own build, so re-check these loading modes when you move
221
+ the pinned version.
@@ -1,5 +1,10 @@
1
1
  # Usage
2
2
 
3
+ This guide is the canonical reference for client configuration and extension
4
+ points. For a no-build browser setup see [Browser CDN usage](./cdn.md), for the
5
+ public API surface see the [API Reference](../reference/README.md), and for
6
+ wire-level details see the [vRPC protocol](../maintainers/protocol.md).
7
+
3
8
  ## 1. Generic HTTP client
4
9
 
5
10
  ```ts
@@ -223,6 +228,20 @@ Recommended application policy:
223
228
  - Branch on expected `invoke` values such as `code` and `reason` near the feature that understands them. Use `suppressGlobalToast` when that feature owns the UI, preventing duplicate messages.
224
229
  - Treat values that fail `isVrpcError` as configuration, interceptor, or other unexpected application errors; do not silently classify them as network failures.
225
230
 
231
+ ### Upgrading to 0.10
232
+
233
+ Version 0.10 removes the obsolete `type` field from `HttpErrorPayload`,
234
+ `VrpcErrorPayload`, `HttpInvokeError`, and `VrpcInvokeError`. The current vRPC
235
+ error payload contains `code`, `message`, `reason`, and `detail`.
236
+
237
+ Replace checks of `error.type` according to their purpose: use `kind` after
238
+ `isHttpError` or `isVrpcError` to distinguish client error categories, use
239
+ `vrpcStatus` on vRPC invocation errors for the protocol outcome, and use `code`
240
+ with `reason` for business-specific handling. These fields already existed in
241
+ 0.9, so callers can migrate before upgrading. Generic HTTP callers that consume
242
+ a custom server field can still read the original response through `payload`
243
+ after validating its shape.
244
+
226
245
  ### Global `onError` and local `try/catch`
227
246
 
228
247
  Global and local handlers have different responsibilities. A global `onError` interceptor is suitable for shared logging, reporting, and fallback UI. A local `try/catch` is suitable for an expected business outcome that the current feature can explain or recover from.
@@ -46,7 +46,7 @@ An error response has a null result and may carry a structured error:
46
46
  }
47
47
  ```
48
48
 
49
- The client treats a response as successful only when the HTTP status is successful and `vrpc-status` is `OK`. `vrpc-status` is the authoritative vRPC outcome; the body `error` supplies auxiliary `type`, `code`, `reason`, `message`, and `detail` fields. The runtime does not infer success from body fields or require `result` and `error` to form a strictly validated mutually exclusive envelope.
49
+ The client treats a response as successful only when the HTTP status is successful and `vrpc-status` is `OK`. `vrpc-status` is the authoritative vRPC outcome; the body `error` supplies auxiliary `code`, `reason`, `message`, and `detail` fields. The runtime does not infer success from body fields or require `result` and `error` to form a strictly validated mutually exclusive envelope.
50
50
 
51
51
  Other responses are unwrapped as `VrpcInvokeError`. If a response already carries a failing `vrpc-status` but its body or auxiliary protocol metadata cannot be decoded, it remains a `VrpcInvokeError` with `payload: null`, while the decoding failure is preserved as `cause`. Every response must contain valid `content-type`, `vrpc-status`, and `vrpc-server` headers; a JSON body must be non-empty and parseable. A missing `vrpc-status`, or an otherwise undecodable successful response, produces `VrpcProtocolError` with the HTTP response metadata intact.
52
52
 
@@ -37,29 +37,20 @@ Version examples use the initial `0.9.0` release as the starting point:
37
37
 
38
38
  Running an alpha command again on its prerelease line increments the prerelease number, for example from `0.9.1-alpha.0` to `0.9.1-alpha.1`. Running the matching stable command on that prerelease removes the prerelease suffix.
39
39
 
40
- Review and commit the version change before publishing. A prerelease automatically uses its SemVer identifier as the dist-tag, such as `alpha`; a stable version uses `latest`. A successful release creates and pushes only the Git tag `v<version>` for that release.
40
+ Review and commit the version change before publishing. A prerelease automatically uses its SemVer identifier as the dist-tag, such as `alpha`; a stable version uses `latest`. After the version PR passes CI and is merged, sync main and push only its reviewed `v<version>` tag. The tag starts publication.
41
41
 
42
42
  ## Publishing
43
43
 
44
- Before publishing, point `NPM_CONFIG_USERCONFIG` to the npm configuration used for publishing:
44
+ Run `pnpm release:dry-run` locally to check the package without publishing.
45
+ Actual publication runs only in GitHub Actions after pushing the version tag;
46
+ `pnpm release` does not publish from a developer machine. The workflow checks
47
+ that the checkout matches the tag, belongs to main history and has exactly the
48
+ same version in package.json. It never creates, moves or pushes tags.
45
49
 
46
- ```bash
47
- export NPM_CONFIG_USERCONFIG=/path/to/npmrc
48
- ```
49
-
50
- Run the full checks and an npm dry-run first:
51
-
52
- ```bash
53
- pnpm release:dry-run
54
- ```
55
-
56
- After confirming the package name, version, file list, and dist-tag, publish:
57
-
58
- ```bash
59
- pnpm release
60
- ```
61
-
62
- The release script publishes the committed version from the root `package.json` and never changes the version during publishing. Before contacting npm, it verifies that the target tag does not exist locally or on `origin`, pulls with fast-forward only, and pushes the release commit. It never pushes unrelated local tags.
50
+ Keep the `npm-publish` environment and npm trusted publisher configured for
51
+ this repository and `release.yml`. Environment deployment rules must allow
52
+ version tags, not only the main branch; existing required approvals still apply.
53
+ The workflow uses OIDC with `id-token: write` and the pinned npm CLI.
63
54
 
64
55
  ## Release gates
65
56
 
@@ -75,18 +66,27 @@ pnpm build
75
66
  pnpm test:package
76
67
  ```
77
68
 
78
- The script then assembles the package in a system temporary directory, verifies the npm identity, confirms that the target version does not already exist, and runs `npm publish`. The temporary directory is removed after either success or failure.
79
-
80
- ## Recovering a tag push
81
-
82
- Publishing to npm and pushing a Git tag cannot be one atomic operation. If npm publishing succeeds but the final tag push fails, do not publish the version again.
83
-
84
- If the local `v<version>` tag exists and points to the release commit, restore the remote tag with:
85
-
86
- ```bash
87
- git push origin refs/tags/v<version>
88
- ```
89
-
90
- If local tag creation failed, first verify the release commit, create `v<version>` at that exact commit, and then run the command above. Never use `git push --tags` as recovery because it may publish unrelated local tags.
91
-
92
- `package.json` must declare a reviewed license and the repository must contain the matching `LICENSE` file. Both staging and the post-build smoke test validate it. The published package contains JavaScript, type declarations, the bilingual root README, English guides and maintainer documentation, the contribution guide, LICENSE, and the package manifest.
69
+ The script assembles the package in a temporary directory, runs npm pack once,
70
+ and publishes that exact tarball with provenance. A stable version uses `latest`;
71
+ a prerelease uses its SemVer identifier. The registry SHA-512 integrity must match
72
+ the packed tarball before GitHub Release is created. Release notes are generated
73
+ from GitHub history; this repository does not maintain a CHANGELOG. Prerelease
74
+ tags create GitHub prereleases. Temporary package files are removed on exit.
75
+
76
+ ## Recovery
77
+
78
+ Rerun the failed workflow or dispatch it with the same existing tag. If npm
79
+ already contains the version, compare its integrity with the rebuilt tarball:
80
+ only an exact match skips npm upload and resumes GitHub Release creation.
81
+ A mismatch, authentication failure or registry error stops publication. Recovery
82
+ does not rewrite npm dist-tags, which may already point to a newer release.
83
+ An existing published GitHub Release is left unchanged; an unpublished draft
84
+ can finish publication. Do not move tags or unpublish npm versions to retry.
85
+
86
+ For workflow changes, run `bash .github/scripts/release_test.sh`, ShellCheck,
87
+ actionlint and the normal package checks. Full OIDC and hosted publication still
88
+ require an actual version-tag run.
89
+
90
+ `package.json` must declare a reviewed license and the repository must contain
91
+ the matching LICENSE. Published contents include JavaScript, declarations, both
92
+ READMEs, guides, maintainer documentation, CONTRIBUTING, LICENSE and the manifest.
@@ -0,0 +1,240 @@
1
+ # API Reference
2
+
3
+ Public exports of the published `@yorun-ai/vrpc` package. For task-oriented
4
+ guidance, start with the [Usage guide](../guides/usage.md); for wire-level
5
+ details, see the [vRPC protocol](../maintainers/protocol.md).
6
+
7
+ Everything listed here is exported from `src/entrypoints/`. Anything not listed
8
+ is internal and may change in any release.
9
+
10
+ ## Package entry points
11
+
12
+ | Import | Contents |
13
+ | ----------------------- | ------------------------------------------------------------------------ |
14
+ | `@yorun-ai/vrpc` | Identical to `@yorun-ai/vrpc/client`. |
15
+ | `@yorun-ai/vrpc/client` | vRPC client, protocol helpers, id helpers, transport, errors, and types. |
16
+ | `@yorun-ai/vrpc/http` | Generic HTTP client, Fetch transport, HTTP errors, and HTTP types. |
17
+
18
+ Each entry point publishes an ESM build (`import`), a CommonJS build
19
+ (`require`), and matching type declarations.
20
+
21
+ ## Client factories
22
+
23
+ ### `createVrpcClient(options)`
24
+
25
+ ```ts
26
+ function createVrpcClient(options: VrpcClientOptions): VrpcClient;
27
+ ```
28
+
29
+ | Option | Type | Default | Notes |
30
+ | --------------------- | ---------------------------------------------------- | --------------- | ----------------------------------------------------------------------------- |
31
+ | `prefixUrl` | `string \| URL` | required | Base URL. The runtime appends `/<serviceName>/<methodName>`. |
32
+ | `clientInfo` | `VrpcClientInfo` | required | Sent as `vrpc-client`; see the validation rules below. |
33
+ | `traceMode` | `"portal" \| "direct"` | `"portal"` | Controls only the generated `vrpc-trace` header. |
34
+ | `cborCodec` | `VrpcCborCodec` | — | Required when a request supplies `options.wire`. |
35
+ | `headers` | `HeadersInit` | — | Cannot override `accept`, `content-type`, or any `vrpc-*` header. |
36
+ | `timeoutMs` | `number` | — | Client default for the local timer and `vrpc-options`. Disabled when omitted. |
37
+ | `requestInit` | `Omit<RequestInit, "method" \| "body" \| "headers">` | — | Merged per request. |
38
+ | `suppressGlobalToast` | `boolean` | — | Interceptor-only metadata; a per-request value overrides it. |
39
+ | `fetchImpl` | `typeof fetch` | global `fetch` | Custom Fetch implementation for the built-in transport. |
40
+ | `transport` | `VrpcTransport` | Fetch transport | Replaces the built-in transport. |
41
+ | `interceptors` | `VrpcInterceptor[]` | `[]` | Same as calling `client.use()` for each entry. |
42
+
43
+ `VrpcClientInfo` fields are validated before the request is sent:
44
+
45
+ - `clientName`: lower-case dot-separated identifier, for example `demo.browser`.
46
+ - `clientVersion`: valid SemVer, for example `1.0.0`.
47
+ - `clientInstanceId`: UUID, for example from `getClientInstanceId()`.
48
+
49
+ ### `client.invoke(request)`
50
+
51
+ ```ts
52
+ client.invoke<TResponse = unknown>(request: VrpcInvokeRequest): Promise<TResponse>;
53
+ ```
54
+
55
+ `VrpcInvokeRequest`:
56
+
57
+ | Field | Type | Notes |
58
+ | ------------- | --------------------------------- | --------------------------------------------------------------- |
59
+ | `serviceName` | `string` | Encoded into the request path. |
60
+ | `methodName` | `string` | Encoded into the request path. |
61
+ | `params` | `Record<string, unknown> \| null` | Required. Both `null` and `{}` are accepted for no-arg methods. |
62
+ | `options` | `VrpcRequestOptions` | Optional per-request overrides. |
63
+
64
+ The returned promise resolves to the envelope `result` and rejects with a
65
+ `VrpcError` (or an ordinary developer error for invalid configuration). vRPC
66
+ always uses `POST`.
67
+
68
+ ### `createHttpClient(options)`
69
+
70
+ ```ts
71
+ function createHttpClient(options: HttpClientOptions): HttpClient;
72
+ ```
73
+
74
+ | Option | Type | Default | Notes |
75
+ | --------------------- | ---------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------- |
76
+ | `prefixUrl` | `string \| URL` | required | Base URL for relative request paths. |
77
+ | `allowAbsoluteUrls` | `boolean` | `false` | Allows absolute `http:`/`https:` request paths. Protocol-relative URLs stay rejected. |
78
+ | `headers` | `HeadersInit` | — | Merged with per-request headers. |
79
+ | `timeoutMs` | `number` | — | Disabled when omitted. |
80
+ | `requestInit` | `Omit<RequestInit, "method" \| "body" \| "headers">` | — | Merged per request. |
81
+ | `suppressGlobalToast` | `boolean` | — | Interceptor-only metadata. |
82
+ | `fetchImpl` | `typeof fetch` | global `fetch` | |
83
+ | `transport` | `HttpTransport` | Fetch transport | |
84
+ | `interceptors` | `HttpInterceptor[]` | `[]` | |
85
+
86
+ ### `client.request(config)`
87
+
88
+ ```ts
89
+ client.request<TResponse = unknown>(config: HttpRequestConfig): Promise<TResponse>;
90
+ ```
91
+
92
+ | Field | Type | Notes |
93
+ | --------- | ------------------------------------ | ------------------------------------------------------------------- |
94
+ | `path` | `string` | Required. Relative to `prefixUrl` unless absolute URLs are allowed. |
95
+ | `method` | `string` | Defaults to `GET`. |
96
+ | `query` | `HttpQueryParams \| URLSearchParams` | Appended to the URL. `null` and `undefined` values are skipped. |
97
+ | `json` | `unknown` | Serialized body; sets `content-type: application/json` when unset. |
98
+ | `body` | `BodyInit \| null` | Raw body, for example `FormData` or `URLSearchParams`. |
99
+ | `options` | `HttpRequestOptions` | Per-request overrides. |
100
+
101
+ `json` and `body` are mutually exclusive. Response parsing is independent of
102
+ `content-type`: an empty body resolves to `null`, valid JSON is decoded, and any
103
+ other body resolves to text.
104
+
105
+ ## Request options
106
+
107
+ `HttpRequestOptions` is the base shape; `VrpcRequestOptions` extends it.
108
+
109
+ | Field | Type | Applies to | Notes |
110
+ | --------------------- | ---------------------------------------------------- | ---------- | --------------------------------------------------------------- |
111
+ | `headers` | `HeadersInit` | both | Merged over client defaults. |
112
+ | `timeoutMs` | `number` | both | Overrides the client default. |
113
+ | `requestInit` | `Omit<RequestInit, "method" \| "body" \| "headers">` | both | Shallow-merged over the client default. |
114
+ | `suppressGlobalToast` | `boolean` | both | Read by application interceptors; the runtime never touches UI. |
115
+ | `trace` | `{ id: string; span?: string }` | vRPC | Replaces the generated trace. |
116
+ | `wire` | `VrpcMethodWireSpec` | vRPC | Selects JSON or CBOR. Never sent on the wire. |
117
+
118
+ Create-time scalar values and `requestInit` fields are overridden by
119
+ per-request values. `context.options` always contains the merged result.
120
+
121
+ ## Interceptors
122
+
123
+ ```ts
124
+ type VrpcInterceptor = {
125
+ beforeRequest?: (context: VrpcInvokeContext) => void | Promise<void>;
126
+ afterResponse?: (response: Response, context: VrpcInvokeContext) => void | Promise<void>;
127
+ onError?: (error: unknown, context: VrpcInvokeContext) => void | Promise<void>;
128
+ };
129
+
130
+ type VrpcInvokeContext = {
131
+ url: string;
132
+ init: RequestInit;
133
+ request: VrpcInvokeRequest;
134
+ options: VrpcRequestOptions;
135
+ };
136
+ ```
137
+
138
+ `HttpInterceptor` and `HttpInvokeContext` have the same shape with
139
+ `HttpRequestConfig` / `HttpRequestOptions`. Register an interceptor with
140
+ `client.use(interceptor)`.
141
+
142
+ - `options` is the merged configuration, including resolved headers, timeout,
143
+ trace, and `suppressGlobalToast`.
144
+ - `request` is the original call shape and `init` is the resolved `RequestInit`.
145
+ - `onError` completes before the request promise rejects. Returning normally
146
+ does not swallow the error.
147
+ - Request-construction failures that occur before a context exists reject
148
+ directly and never reach an interceptor.
149
+
150
+ ## Errors
151
+
152
+ Use the guard for your client, then branch on `kind`:
153
+
154
+ ```ts
155
+ isVrpcError(error): error is VrpcError;
156
+ isHttpError(error): error is HttpError;
157
+ ```
158
+
159
+ | `kind` | Class | Entry point | Extra fields |
160
+ | ----------- | -------------------- | ----------- | -------------------------------------------------------------------------------- |
161
+ | `abort` | `HttpAbortError` | both | `reason` (the `AbortSignal` reason), `url`, `method`, `cause` |
162
+ | `timeout` | `HttpTimeoutError` | both | `timeoutMs`, `code: "HTTP_TIMEOUT"`, `url`, `method`, `cause` |
163
+ | `transport` | `HttpTransportError` | both | `url`, `method`, `cause` |
164
+ | `invoke` | `HttpInvokeError` | both | `status`, `statusText`, `responseHeaders`, `payload`, `code`, `reason`, `detail` |
165
+ | `invoke` | `VrpcInvokeError` | vRPC | All `HttpInvokeError` fields plus `vrpcStatus` |
166
+ | `protocol` | `VrpcProtocolError` | vRPC only | `status`, `statusText`, `responseHeaders`, `vrpcStatus` |
167
+
168
+ `HttpError` is `HttpAbortError | HttpTimeoutError | HttpTransportError |
169
+ HttpInvokeError`. `VrpcError` adds `VrpcInvokeError` and `VrpcProtocolError`;
170
+ `isHttpError` does not accept a `VrpcProtocolError`.
171
+
172
+ `VrpcInvokeError.message` combines the server `message` and `detail` fields with
173
+ a newline. Use `vrpcStatus` for the protocol outcome and `code` plus `reason`
174
+ for business branching; do not parse `message`. Error classes remain exported
175
+ for advanced use, but application policy normally needs only the guard and
176
+ `kind`.
177
+
178
+ ## Protocol helpers
179
+
180
+ Exported from `@yorun-ai/vrpc` and `@yorun-ai/vrpc/client`:
181
+
182
+ | Export | Signature |
183
+ | --------------------------- | -------------------------------------------------------------------------------- |
184
+ | `buildVrpcPath` | `(serviceName: string, methodName: string) => string` |
185
+ | `buildVrpcRequestBody` | `(params: Record<string, unknown> \| null \| undefined) => string` |
186
+ | `encodeVrpcRequestBody` | `(params, schema, cborCodec) => Promise<string \| ArrayBuffer>` |
187
+ | `buildVrpcHeaders` | `(options: BuildVrpcHeadersOptions) => Headers` |
188
+ | `decodeVrpcResponsePayload` | `(response: Response, cborCodec, resultSchema) => Promise<unknown>` |
189
+ | `parseVrpcResponse` | `<T>(responseLike: VrpcResponseLike, payload: unknown) => ParsedVrpcResponse<T>` |
190
+ | `unwrapVrpcResponse` | `<T>(responseLike: VrpcResponseLike, payload: unknown) => T` |
191
+ | `generateVrpcId` | `() => string` (32 lowercase hex characters) |
192
+ | `generateVrpcSpan` | `() => string` (16 lowercase hex characters) |
193
+ | `generateClientInstanceId` | `() => string` (lowercase UUID) |
194
+ | `getClientInstanceId` | `(options?: { key?: string }) => string` |
195
+ | `createFetchTransport` | `(fetchImpl?: typeof fetch) => HttpTransport` |
196
+
197
+ Constants and stores:
198
+
199
+ | Export | Value |
200
+ | ---------------------------------------- | --------------------------- |
201
+ | `VRPC_JSON_CONTENT_TYPE` | `"application/vrpc+json"` |
202
+ | `VRPC_CBOR_CONTENT_TYPE` | `"application/vrpc+cbor"` |
203
+ | `HTTP_TIMEOUT_ERROR_CODE` | `"HTTP_TIMEOUT"` |
204
+ | `DEFAULT_CLIENT_INSTANCE_ID_STORAGE_KEY` | `"vrpc-client-instance-id"` |
205
+
206
+ `BuildVrpcHeadersOptions` is `{ clientInfo, trace, timeoutMs?, requestUsesCbor?,
207
+ responseUsesCbor? }`. `parseVrpcResponse` never throws and returns a
208
+ discriminated result; `unwrapVrpcResponse` throws `VrpcInvokeError` for a
209
+ non-OK response. `getClientInstanceId` reads and writes `localStorage`, and
210
+ falls back to a fresh id when storage is unavailable.
211
+
212
+ ## Types
213
+
214
+ Exported from `@yorun-ai/vrpc` and `@yorun-ai/vrpc/client`:
215
+
216
+ | Type | Purpose |
217
+ | ------------------------------------------------------------------------------------------------ | ------------------------------- |
218
+ | `VrpcClient`, `VrpcInvokeRequest`, `VrpcClientOptions` | vRPC client contracts. |
219
+ | `VrpcRequestOptions`, `VrpcRequestInit` | vRPC request configuration. |
220
+ | `VrpcInvokeContext`, `VrpcInterceptor`, `VrpcInterceptors` | Interceptor contracts. |
221
+ | `VrpcClientInfo`, `VrpcTrace`, `VrpcTraceMode` | Client identity and tracing. |
222
+ | `VrpcWireSchema`, `VrpcMethodWireSpec`, `VrpcCborCodec` | JSON/CBOR wire selection. |
223
+ | `VrpcResponseLike`, `ParsedVrpcResponse`, `ParsedVrpcSuccessResponse`, `ParsedVrpcErrorResponse` | Response helpers. |
224
+ | `VrpcTransport`, `VrpcTransportRequest`, `VrpcTransportResponse` | Custom transport contracts. |
225
+ | `VrpcError`, `VrpcErrorPayload`, `HttpClientErrorKind` | Error unions and payload shape. |
226
+ | `GetClientInstanceIdOptions`, `BuildVrpcHeadersOptions` | Helper options. |
227
+
228
+ `@yorun-ai/vrpc/http` exports the HTTP subset: `HttpClient`,
229
+ `HttpRequestConfig`, `HttpClientOptions`, `HttpRequestOptions`, `HttpRequestInit`,
230
+ `HttpQueryParams`, `HttpQueryValue`, `HttpQueryPrimitive`, `HttpInvokeContext`,
231
+ `HttpInterceptor`, `HttpTransport`, `HttpTransportRequest`,
232
+ `HttpTransportResponse`, `HttpError`, `HttpErrorPayload`,
233
+ `HttpErrorRequestMeta`, `HttpClientErrorOptions`, `HttpAbortErrorOptions`, and
234
+ `HttpClientErrorKind`.
235
+
236
+ ## Stability
237
+
238
+ The package is in the `0.x` line. The public API is not yet covered by a stable
239
+ `1.x` compatibility commitment, and a breaking change may ship in a new `0.x`
240
+ minor release with migration guidance.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yorun-ai/vrpc",
3
- "version": "0.9.2",
3
+ "version": "0.10.0",
4
4
  "description": "vRPC and HTTP request library",
5
5
  "homepage": "https://github.com/yorun-ai/vrpc-ts#readme",
6
6
  "bugs": {
@@ -61,5 +61,5 @@
61
61
  "access": "public",
62
62
  "registry": "https://registry.npmjs.org/"
63
63
  },
64
- "packageManager": "pnpm@11.15.0"
64
+ "packageManager": "pnpm@12.5.1"
65
65
  }