@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 +28 -0
- package/README.md +147 -22
- package/dist/generated/types.gen.d.mts +3037 -62
- package/dist/index.d.mts +640 -66
- package/dist/index.mjs +1009 -109
- package/package.json +3 -2
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
|
|
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.
|
|
28
|
-
await lobehub.files.uploadBatch({ body: { files: [/* … */] } });
|
|
27
|
+
await lobehub.topics.create({ body: { agentId: 'agt_...', title: 'Planning' } });
|
|
29
28
|
```
|
|
30
29
|
|
|
31
|
-
|
|
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
|
-
|
|
38
|
-
|
|
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
|
-
|
|
119
|
+
## Retries and timeouts
|
|
43
120
|
|
|
44
|
-
|
|
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
|
-
`
|
|
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 {
|
|
50
|
-
|
|
51
|
-
|
|
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
|
-
|
|
54
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
231
|
+
To cut a release, bump `version` and add its CHANGELOG section in the PR that changes the SDK's surface.
|