@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 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 11.15.0, using the repository lockfile.
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
- Repository documentation is maintained in English. The root `README.zh-CN.md` provides a Chinese project overview and links to the canonical English guides. Keep both root README files synchronized when their shared content changes.
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
- [![license](https://img.shields.io/github/license/yorun-ai/vrpc-ts)](https://github.com/yorun-ai/vrpc-ts/blob/main/LICENSE)
4
- [![version](https://img.shields.io/npm/v/%40yorun-ai%2Fvrpc?label=version&logo=npm)](https://www.npmjs.com/package/@yorun-ai/vrpc)
5
- [![CI](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml)
3
+ [![npm version](https://img.shields.io/npm/v/%40yorun-ai%2Fvrpc?label=version&logo=npm&style=flat-square)](https://www.npmjs.com/package/@yorun-ai/vrpc)
4
+ [![CI](https://img.shields.io/github/actions/workflow/status/yorun-ai/vrpc-ts/ci.yml?branch=main&label=CI&logo=github&style=flat-square)](https://github.com/yorun-ai/vrpc-ts/actions/workflows/ci.yml)
5
+ [![install size](https://img.shields.io/badge/dynamic/json?url=https://packagephobia.com/v2/api.json?p=%40yorun-ai%2Fvrpc&query=$.install.pretty&label=install%20size&style=flat-square)](https://packagephobia.com/result?p=%40yorun-ai%2Fvrpc)
6
+ [![npm downloads](https://img.shields.io/npm/dm/%40yorun-ai%2Fvrpc?logo=npm&style=flat-square)](https://www.npmjs.com/package/@yorun-ai/vrpc)
7
+ [![npm types](https://img.shields.io/npm/types/%40yorun-ai%2Fvrpc?style=flat-square)](https://www.npmjs.com/package/@yorun-ai/vrpc)
8
+ [![license](https://img.shields.io/github/license/yorun-ai/vrpc-ts?style=flat-square)](https://github.com/yorun-ai/vrpc-ts/blob/main/LICENSE)
6
9
 
7
10
  **English** | [简体中文](README.zh-CN.md)
8
11
 
9
- Client runtime for Vine vRPC and generic HTTP requests.
12
+ A lightweight TypeScript client runtime for [Vine](https://github.com/yorun-ai/vine) vRPC and generic HTTP requests.
10
13
 
11
- Repository: [github.com/yorun-ai/vrpc-ts](https://github.com/yorun-ai/vrpc-ts)
14
+ ## What is this?
12
15
 
13
- ## Stability
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
- The package starts at `0.9.0`. It is ready for use, but versions below `1.0.0` do not guarantee a stable public API. Breaking API changes may be released in a new `0.x` minor version and will include migration guidance. Version `1.0.0` will mark the stable API commitment.
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
- ## Entry points
47
+ ```bash
48
+ npm install @yorun-ai/vrpc
49
+ ```
24
50
 
25
- - `@yorun-ai/vrpc` / `@yorun-ai/vrpc/client`: vRPC client, protocol helpers, shared transport, and types.
26
- - `@yorun-ai/vrpc/http`: generic HTTP client.
51
+ ## Quick start
27
52
 
28
- ## vRPC quick start
53
+ ### 1. Invoke a vRPC method
29
54
 
30
55
  ```ts
31
- import { createVrpcClient, getClientInstanceId, isVrpcError } from "@yorun-ai/vrpc";
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
- - Create-time `suppressGlobalToast` is the default; a per-call `true` or `false` overrides it.
102
- - `timeoutMs` is disabled by default; without it, the built-in transport creates no local timeout and sends no `vrpc-options`.
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
- ## Automatic CBOR
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
- HTTP interceptors read merged request configuration from `context.options`. `json` and `body` are mutually exclusive. Generic HTTP response parsing is intentionally lenient and independent of `content-type`: an empty body returns `null`, valid JSON is decoded, and any other body is returned as text.
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
- ## Error handling
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
- function handleError(error: unknown) {
207
- if (!isVrpcError(error)) {
208
- console.error(error);
209
- return;
210
- }
211
-
212
- if (error.kind === "abort") {
213
- return;
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 vRPC error kinds are `abort`, `timeout`, `transport`, `invoke`, and `protocol`. The generic HTTP entry point provides the equivalent `isHttpError` guard with `abort`, `timeout`, `transport`, and `invoke`. Original adapter or vRPC decoding errors are preserved in `cause`. For vRPC invoke errors, `code` and `reason` remain server-defined business fields, and `message` continues to include a non-empty `detail`.
118
+ The generic HTTP client provides the equivalent `isHttpError` guard.
226
119
 
227
- Error classes remain exported for compatibility and specialized tests, but application policy normally needs only the guard and `kind`.
120
+ ## Browser CDN
228
121
 
229
- ### Local `try/catch` and `suppressGlobalToast`
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
- Use a local `try/catch` when a feature owns the error UI. Set `suppressGlobalToast: true` on that request so the global interceptor can skip its fallback toast:
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
- ```ts
234
- async function loadProfile() {
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
- `suppressGlobalToast` is only metadata for application interceptors; the package does not operate UI itself. It does not skip `onError` or consume the error. The lifecycle remains `onError` first, followed by Promise rejection and the local `catch`. A per-request value overrides the client-level default.
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
- Pass an `AbortSignal` through `requestInit.signal`. Cancellation rejects with an error whose `kind` is `"abort"`; it is not converted into a successful `undefined` result.
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
- const controller = new AbortController();
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
- ## Protocol helpers
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
- ```ts
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
- const path = buildVrpcPath("user.UserService", "getProfile");
311
- const body = buildVrpcRequestBody({ userId: 1 });
312
- ```
181
+ ### User guides
313
182
 
314
- ## Documentation
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
- User guides:
190
+ ### Reference and maintainers
317
191
 
318
- - [Usage](./docs/guides/usage.md): HTTP/vRPC client configuration and extension points.
319
- - [Axios integration](./docs/guides/axios.md): custom Axios transport and JSON protocol helpers.
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
- Maintainer documentation:
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
- - [Architecture](./docs/maintainers/architecture.md): module boundaries and request flow.
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 root README and `docs/guides/` are for package users. `docs/maintainers/` is for repository maintainers and integrators implementing transports or code generation. Changes to public exports, types, defaults, headers, errors, or request behavior must be reflected in both the user-facing and maintainer documentation.
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