@yorun-ai/vrpc 0.9.1 → 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.
@@ -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`, `type`, `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.1",
3
+ "version": "0.9.3",
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
  }