@lobehub/sdk 1.0.20261118021711 → 1.1.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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,28 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@lobehub/sdk`. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org/).
4
+
5
+ Each release sorts its entries into `### Breaking`, `### Added`, `### Changed` and `### Fixed`. A `Breaking` entry needs a major bump and an `Added` one at least a minor bump; the release workflow refuses to publish a version whose bump is smaller than its section requires (see "Releasing" in the README).
6
+
7
+ ## \[1.1.0] - 2026-11-17
8
+
9
+ First semver release. Versions before it were published as `1.0.<UTC timestamp>` on every push.
10
+
11
+ ### Added
12
+
13
+ - `createLobeHub({ workspaceId })` sends `X-Workspace-Id` on every request; a per-call header still overrides it.
14
+ - `timeout` (default 10 minutes, until the response headers) and `maxRetries` (default 2) on the client and on every call. Retries back off exponentially on 408, 429, 5xx and network errors, honor `Retry-After`, and only resend idempotent methods (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`) or a `POST` that carries an `Idempotency-Key` (whose in-flight 409 `idempotency_conflict` is waited out too).
15
+ - `idempotencyKey` call option, sent as the `Idempotency-Key` header.
16
+ - Typed errors: `LobeHubAPIError` (`status`, `code`, `requestId`, `details`, `headers`, `body`), `LobeHubConnectionError` and `LobeHubTimeoutError`.
17
+ - `createLobeHub({ throwOnError: true })` makes every method reject with `LobeHubAPIError` and types `data` as always present.
18
+ - `lobehub.paginate(method, options)`: an async iterator over every item of a cursor-paginated list (`hasMore` / `nextCursor`).
19
+ - `lobehub.responses.stream(body)`: typed OpenResponses server-sent events (`ResponseStreamEvent`) as an `AsyncIterable`, plus `finalResponse()` and `abort()`.
20
+ - `lobehub.files.upload(source, options)` for a `File`, `Blob`, `Buffer` / `Uint8Array` / `ArrayBuffer`, or a local file path.
21
+ - Generated types for every streaming event (`ResponseCreatedEvent`, `ResponseOutputTextDeltaEvent`, …) and the `X-Workspace-Id` / `Idempotency-Key` headers on each operation.
22
+ - Each method's JSDoc lists the API key scopes it needs.
23
+
24
+ ### Changed
25
+
26
+ - An error answer now comes back as a `LobeHubAPIError` instance instead of the plain JSON body. It still carries the body's fields (`success`, `code`, `message`, `details`, `requestId`, `timestamp`, `error`), so code reading them is unaffected; code that compared the error with `toEqual` against a plain object, or serialized it, sees an `Error` now.
27
+ - Idempotent requests are retried twice by default; pass `maxRetries: 0` for the previous behavior.
28
+ - Method names now come from the spec's `operationId`s (`agents.list`, `files.uploadBatch`, …) instead of a naming table in the generator config. Every method and type name is unchanged.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Official TypeScript SDK for the [LobeHub REST API](https://app.lobehub.com/api/v1/docs), generated from the OpenAPI spec in [`packages/openapi`](../openapi) via [@hey-api/openapi-ts](https://heyapi.dev).
4
4
 
5
- Resource-style methods with full typing — every path, parameter, request body, and response comes from `openapi.yml`, and the HTTP runtime is inlined (zero dependencies).
5
+ Resource-style methods with full typing — every path, parameter, request body, and response comes from `openapi.yml` — plus a hand-written layer for workspaces, retries, typed errors, pagination, streaming and uploads. The HTTP runtime is inlined (zero dependencies). See [`CHANGELOG.md`](./CHANGELOG.md) for release notes and [`examples/`](./examples) for runnable scripts.
6
6
 
7
7
  ## Installation
8
8
 
@@ -21,41 +21,161 @@ const lobehub = createLobeHub({
21
21
  });
22
22
 
23
23
  const me = await lobehub.users.me();
24
- const { data, error } = await lobehub.agents.list();
24
+ const { data, error } = await lobehub.agents.list({ query: { limit: 20 } });
25
25
  const agent = await lobehub.agents.get({ path: { id: 'agt_...' } });
26
26
 
27
- await lobehub.agentGroups.create({ body: { name: 'My group' } });
28
- await lobehub.files.uploadBatch({ body: { files: [/* … */] } });
27
+ await lobehub.topics.create({ body: { agentId: 'agt_...', title: 'Planning' } });
29
28
  ```
30
29
 
31
- Resources map to the API's top-level path segments: `health`, `agentGroups`, `agents`, `files`, `knowledgeBases`, `messageTranslations`, `messages`, `models`, `permissions`, `providers`, `responses`, `roles`, `topics`, `users`. Method names follow a fixed rule — `list` / `get` / `create` / `update` / `delete` plus PascalCase sub-segments (`files.listChunks`, `roles.updatePermissions`) — with a few curated names (`files.uploadBatch`, `files.query`, `knowledgeBases.addFiles`, `users.me`).
30
+ Every method resolves to `{ data, error, request, response }`: `data` is the response body (the `{ success, data, timestamp }` envelope for most routes) and `error` is set instead when the API answers with an error — see [Errors](#errors).
32
31
 
33
32
  Point the client at another deployment with `baseURL`, and pass any other client option (custom `fetch`, `headers`, …):
34
33
 
35
34
  ```ts
36
- const lobehub = createLobeHub({
37
- apiKey: 'sk-lh-...',
38
- baseURL: 'http://localhost:3010',
39
- });
35
+ const lobehub = createLobeHub({ apiKey: 'sk-lh-...', baseURL: 'http://localhost:3010' });
36
+ ```
37
+
38
+ Raw spec types are exported from `@lobehub/sdk` and `@lobehub/sdk/types`.
39
+
40
+ ## Resources
41
+
42
+ 30 resources, one per top-level path segment of the API. Method names come from each operation's `operationId` (`<resource>.<method>`) in the spec: `list` / `get` / `create` / `update` / `delete` plus PascalCase sub-segments (`files.listChunks`, `roles.updatePermissions`), and a few verbs declared by the route itself (`files.uploadBatch`, `tasks.run`, `notifications.markRead`). Each method's JSDoc names the API key scopes it needs.
43
+
44
+ | Resource | Methods |
45
+ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
46
+ | `agentGroups` | `create`, `delete`, `get`, `list`, `update` |
47
+ | `agents` | `create`, `createAccount`, `createDuplicate`, `delete`, `deleteAccount`, `get`, `getAccount`, `list`, `listAccounts`, `update`, `updateAccount`, `updateAccountCredential` |
48
+ | `apiKeys` | `create`, `delete`, `get`, `list`, `update` |
49
+ | `audio` | `createSpeech` |
50
+ | `chat` | `create`, `createGenerateReply`, `createTranslate` |
51
+ | `chatGroups` | `addMembers`, `create`, `delete`, `get`, `list`, `removeMembers`, `update` |
52
+ | `documents` | `create`, `get`, `list`, `update` |
53
+ | `eval` | `createBenchmarks`, `createDatasets`, `createDatasetsTestCases`, `createRuns`, `createRunsClaim`, `createRunsResults`, `createRunsRetryErrors`, `deleteBenchmarks`, `deleteDatasets`, `deleteTestCases`, `getBenchmarks`, `getDatasets`, `getRuns`, `getTestCases`, `listBenchmarks`, `listDatasets`, `listDatasetsTestCases`, `listRuns`, `listRunsResults`, `listRunsTopics`, `updateBenchmarks`, `updateDatasets`, `updateRunsStatus`, `updateRunsTopicsResult`, `updateTestCases` |
54
+ | `files` | `create`, `createChunks`, `delete`, `get`, `getUrl`, `list`, `listChunks`, `parse`, `query`, `update`, `uploadBatch` |
55
+ | `goals` | `advance`, `create`, `delete`, `get`, `getSupervision`, `list`, `pause`, `restart`, `resume`, `update` |
56
+ | `health` | `check` |
57
+ | `im` | `markRead`, `send`, `sync` |
58
+ | `knowledgeBases` | `addFiles`, `create`, `delete`, `get`, `list`, `listFiles`, `moveFiles`, `removeFiles`, `update` |
59
+ | `mcpServers` | `create`, `createSync`, `delete`, `get`, `list`, `update` |
60
+ | `memories` | `deleteAll`, `deleteEntry`, `getPersona`, `listCategory`, `listPersonaVersions` |
61
+ | `messageTranslations` | `create`, `delete`, `get`, `update` |
62
+ | `messages` | `create`, `createReply`, `delete`, `deleteMany`, `get`, `getCount`, `list` |
63
+ | `models` | `create`, `get`, `list`, `update` |
64
+ | `notifications` | `archive`, `archiveAll`, `getCounts`, `getUnreadCount`, `list`, `listSettings`, `markAllRead`, `markRead`, `updateSettings` |
65
+ | `permissions` | `create`, `delete`, `get`, `list`, `update` |
66
+ | `plugins` | `list` |
67
+ | `providers` | `create`, `delete`, `get`, `list`, `update` |
68
+ | `pushTokens` | `register`, `unregister` |
69
+ | `responses` | `create` |
70
+ | `roles` | `create`, `delete`, `deletePermissions`, `get`, `list`, `listPermissions`, `update`, `updatePermissions` |
71
+ | `signals` | `emit`, `listReceipts`, `trigger` |
72
+ | `tasks` | `create`, `delete`, `get`, `list`, `listRuns`, `run`, `update`, `updateStatus` |
73
+ | `topics` | `create`, `delete`, `get`, `list`, `listThreads`, `update` |
74
+ | `usage` | `list` |
75
+ | `users` | `create`, `delete`, `deleteRoles`, `get`, `list`, `listRoles`, `me`, `update`, `updateRoles` |
76
+
77
+ ## Workspaces
78
+
79
+ Pass `workspaceId` to act inside a workspace: every request then carries `X-Workspace-Id`. A per-call header still wins.
80
+
81
+ ```ts
82
+ const team = createLobeHub({ apiKey: process.env.LOBEHUB_API_KEY!, workspaceId: 'ws_...' });
83
+ await team.agents.list(); // the workspace's agents
84
+
85
+ await team.agents.list({ headers: { 'X-Workspace-Id': 'ws_other' } });
86
+ ```
87
+
88
+ A personal API key cannot send the header (403 `workspace_mismatch`); a workspace API key is bound to its workspace, so `workspaceId` may be omitted and, when set, must name that workspace.
89
+
90
+ ## Errors
91
+
92
+ An error answer comes back as a `LobeHubAPIError` with `status`, `code` (stable, see `ApiErrorCode` — branch on it, not on `message`), `requestId` (quote it when reporting an issue), `details` (one `{ path, message }` per field for `validation_error`), `headers` and the raw `body`. Network failures are `LobeHubConnectionError`, and `LobeHubTimeoutError` when the [`timeout`](#retries-and-timeouts) runs out.
93
+
94
+ By default methods do not throw:
95
+
96
+ ```ts
97
+ import { LobeHubAPIError } from '@lobehub/sdk';
98
+
99
+ const { data, error } = await lobehub.agents.get({ path: { id } });
100
+ if (error) {
101
+ if (error instanceof LobeHubAPIError && error.code === 'not_found') return null;
102
+ throw error;
103
+ }
104
+ ```
105
+
106
+ Opt into throwing per call with `throwOnError: true`, or for the whole client — then every method rejects with the error and `data` is typed as always present:
107
+
108
+ ```ts
109
+ const lobehub = createLobeHub({ apiKey, throwOnError: true });
110
+
111
+ try {
112
+ const { data } = await lobehub.agents.get({ path: { id } });
113
+ console.log(data.data.title);
114
+ } catch (error) {
115
+ if (error instanceof LobeHubAPIError) console.error(error.status, error.code, error.requestId);
116
+ }
40
117
  ```
41
118
 
42
- Raw spec types are exported from `@lobehub/sdk/types`.
119
+ ## Retries and timeouts
43
120
 
44
- ### Streaming responses
121
+ Requests that are safe to resend are retried up to `maxRetries` times (default 2) on 408, 429, 5xx and network errors, with exponential backoff (\~0.5s, 1s, 2s … up to 8s, with jitter) or exactly the server's `Retry-After`. Safe means an idempotent method (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`) or a `POST` with an idempotency key — a plain `POST` is never resent, and the server only deduplicates keyed `POST`s, so a key on `PATCH` does not make it retryable. A keyed `POST` resent while the first attempt is still running gets 409 `idempotency_conflict`; the SDK waits and retries it, until the stored answer comes back or the retries run out.
45
122
 
46
- `responses.create` returns Server-Sent Events when `body.stream: true`. Opt out of JSON parsing with `parseAs: 'stream'` and read the raw stream from `response.body`:
123
+ `timeout` (default 10 minutes, `0` disables) bounds the wait for the response headers of each attempt. Both work on the client and per call:
47
124
 
48
125
  ```ts
49
- const { response } = await lobehub.responses.create({
50
- body: { input: '…', model: '…', stream: true },
51
- parseAs: 'stream',
126
+ const lobehub = createLobeHub({ apiKey, maxRetries: 4, timeout: 30_000 });
127
+
128
+ await lobehub.agents.list({ maxRetries: 0, timeout: 5000 });
129
+
130
+ // The server runs a keyed request once and replays its answer for repeats,
131
+ // so the key also makes this POST retryable.
132
+ await lobehub.agents.create({
133
+ body: { title: 'Researcher' },
134
+ idempotencyKey: crypto.randomUUID(),
52
135
  });
53
- for await (const chunk of response.body!) {
54
- // decode SSE chunks
136
+ ```
137
+
138
+ ## Pagination
139
+
140
+ List endpoints answer `{ hasMore, nextCursor }` pages. `paginate` walks all of them and yields the items (`items`, or the endpoint's own key such as `agents`):
141
+
142
+ ```ts
143
+ for await (const agent of lobehub.paginate(lobehub.agents.list, { query: { limit: 100 } })) {
144
+ console.log(agent.id, agent.title);
55
145
  }
56
146
  ```
57
147
 
58
- (First-class typed SSE methods will come with the spec's response schemas.)
148
+ The method can be passed unbound; query parameters other than `cursor` are sent with every page.
149
+
150
+ ## Streaming responses
151
+
152
+ `responses.stream` starts a response with `stream: true` and yields typed OpenResponses events (`ResponseStreamEvent`, generated from the spec). `finalResponse()` drains it and resolves with the response object of the last event; `abort()` (or breaking out of the loop) closes the connection.
153
+
154
+ ```ts
155
+ const stream = lobehub.responses.stream({ input: 'Summarize my week', model: 'agt_...' });
156
+
157
+ for await (const event of stream) {
158
+ if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
159
+ if (event.type === 'response.failed') console.error(event.response.error);
160
+ }
161
+ ```
162
+
163
+ ```ts
164
+ const response = await lobehub.responses.stream({ input, model }).finalResponse();
165
+ console.log(response.output_text);
166
+ ```
167
+
168
+ ## Uploads
169
+
170
+ `files.upload` takes a `File`, a `Blob`, raw bytes (`Buffer`, `Uint8Array`, `ArrayBuffer`) or a local file path (Node, Bun, Deno), plus the other upload fields:
171
+
172
+ ```ts
173
+ await lobehub.files.upload('./report.pdf', { knowledgeBaseId: 'kb_...' });
174
+ await lobehub.files.upload(new File([text], 'notes.md', { type: 'text/markdown' }));
175
+ await lobehub.files.upload(buffer, { name: 'image.png', type: 'image/png' });
176
+ ```
177
+
178
+ The file name defaults to the `File` name or the path's base name, and the type to the `Blob` type.
59
179
 
60
180
  ### Signing in with OAuth (native apps)
61
181
 
@@ -95,12 +215,17 @@ Refresh tokens rotate, so persist the one returned by every refresh. A `LobeHubO
95
215
 
96
216
  ## Development
97
217
 
98
- - `bun generate` — regenerate `src/generated/` from `../openapi/openapi.yml` (run after the spec changes; naming rules live in `openapi-ts.config.ts`)
218
+ - `bun generate` — regenerate `src/generated/` from `../openapi/openapi.yml` (run after the spec changes). Names come from the spec's operationIds; the naming rule lives in `packages/openapi/src/common/operation-id.ts`.
99
219
  - `bun run build` — build ESM + d.ts to `dist/`
100
- - `bun run test` — unit tests + generated-output drift check (local and release workflow only; not wired into PR CI)
220
+ - `bun run test` — unit tests (mock `fetch`) + the generated-output drift check
221
+
222
+ PR CI runs this package's tests (it is in the `PACKAGES` list of [`test.yml`](../../.github/workflows/test.yml)), so a spec change without the regenerated SDK fails the PR.
101
223
 
102
224
  ## Releasing
103
225
 
104
- Publishing is automated by [`release-sdk.yml`](../../.github/workflows/release-sdk.yml): every push to `canary` touching `packages/sdk/**` publishes `1.0.<UTC timestamp>` to npm with provenance (manual `workflow_dispatch` also available). To ship a spec change, run `bun generate` and commit the regenerated output — the workflow's drift check (`bun scripts/generate-sdk.ts --check`) guards the published artifact.
226
+ [`release-sdk.yml`](../../.github/workflows/release-sdk.yml) publishes on every push to `canary` that touches `packages/sdk/**` or `packages/openapi/openapi.yml` (and on `workflow_dispatch`), after the drift check, tests and build. [`scripts/release-version.ts`](./scripts/release-version.ts) picks the version:
227
+
228
+ - `package.json` `version` not on npm yet → published to `latest`. It needs a `## [x.y.z] - date` section in `CHANGELOG.md`, and the bump has to match the section: `### Breaking` → major, `### Added` → at least minor, `### Changed` / `### Fixed` → patch. A breaking change is expressed this way and cannot go out as a smaller bump.
229
+ - Already on npm → `x.y.(z+1)-canary.<UTC timestamp>` under the `canary` dist-tag, so `latest` only moves on a changelogged release.
105
230
 
106
- Regular PR CI does not gate on spec drift — the check runs locally (`bun run test`) and inside the release workflow only.
231
+ To cut a release, bump `version` and add its CHANGELOG section in the PR that changes the SDK's surface.