@lobehub/sdk 1.0.20261118164652 → 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/dist/index.mjs CHANGED
@@ -1,6 +1,178 @@
1
1
  //#region src/constants.ts
2
2
  const DEFAULT_BASE_URL = "https://app.lobehub.com";
3
3
  //#endregion
4
+ //#region src/auth.ts
5
+ /** The audience every `/api/v1` access token is issued for. */
6
+ const LOBEHUB_API_RESOURCE = "urn:lobehub:chat";
7
+ /** Scopes a native app needs to call `/api/v1` and keep a refresh token. */
8
+ const DEFAULT_OAUTH_SCOPE = "profile email offline_access";
9
+ var LobeHubOAuthError = class extends Error {
10
+ code;
11
+ status;
12
+ constructor(code, message, status) {
13
+ super(message ?? code);
14
+ this.name = "LobeHubOAuthError";
15
+ this.code = code;
16
+ this.status = status;
17
+ }
18
+ };
19
+ const encodeForm = (params) => Object.entries(params).filter((entry) => entry[1] !== void 0).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
20
+ const oidcUrl = (baseURL, path) => `${(baseURL ?? "https://app.lobehub.com").replace(/\/$/, "")}/oidc/${path}`;
21
+ const queryParam = (url, name) => {
22
+ const match = url.match(new RegExp(`[?&#]${name}=([^&#]*)`));
23
+ return match ? decodeURIComponent(match[1].replaceAll("+", " ")) : void 0;
24
+ };
25
+ const base64Url = (bytes) => {
26
+ let binary = "";
27
+ for (const byte of bytes) binary += String.fromCharCode(byte);
28
+ return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
29
+ };
30
+ /**
31
+ * Generate a PKCE verifier and its S256 challenge with Web Crypto.
32
+ * Hosts without `crypto.subtle` (JavaScriptCore, older RN) should create the
33
+ * pair natively and pass it to {@link createAuthorizationUrl} instead.
34
+ */
35
+ const createPkcePair = async () => {
36
+ const crypto = globalThis.crypto;
37
+ if (!crypto?.subtle) throw new LobeHubOAuthError("pkce_unavailable", "crypto.subtle is not available");
38
+ const verifier = base64Url(crypto.getRandomValues(new Uint8Array(32)));
39
+ const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
40
+ return {
41
+ challenge: base64Url(new Uint8Array(digest)),
42
+ verifier
43
+ };
44
+ };
45
+ /** Build the `/oidc/auth` URL to open in the system browser session. */
46
+ const createAuthorizationUrl = (options) => `${oidcUrl(options.baseURL, "auth")}?${encodeForm({
47
+ client_id: options.clientId,
48
+ code_challenge: options.codeChallenge,
49
+ code_challenge_method: "S256",
50
+ prompt: "consent",
51
+ redirect_uri: options.redirectUri,
52
+ resource: LOBEHUB_API_RESOURCE,
53
+ response_type: "code",
54
+ scope: options.scope ?? "profile email offline_access",
55
+ state: options.state
56
+ })}`;
57
+ /**
58
+ * Read the authorization code from the callback URL, rejecting a state that
59
+ * does not match the one sent with {@link createAuthorizationUrl}.
60
+ */
61
+ const parseAuthorizationCallback = (callbackUrl, expectedState) => {
62
+ const error = queryParam(callbackUrl, "error");
63
+ if (error) throw new LobeHubOAuthError(error, queryParam(callbackUrl, "error_description"));
64
+ if (queryParam(callbackUrl, "state") !== expectedState) throw new LobeHubOAuthError("state_mismatch");
65
+ const code = queryParam(callbackUrl, "code");
66
+ if (!code) throw new LobeHubOAuthError("missing_code");
67
+ return code;
68
+ };
69
+ const requestTokens = async (options, params) => {
70
+ const fetch = options.fetch ?? globalThis.fetch;
71
+ const requestedAt = Date.now();
72
+ const response = await fetch(oidcUrl(options.baseURL, "token"), {
73
+ body: encodeForm({
74
+ client_id: options.clientId,
75
+ ...params
76
+ }),
77
+ headers: { "Content-Type": "application/x-www-form-urlencoded" },
78
+ method: "POST"
79
+ });
80
+ const body = await response.json().catch(() => ({}));
81
+ if (!response.ok) throw new LobeHubOAuthError(typeof body.error === "string" ? body.error : `http_${response.status}`, typeof body.error_description === "string" ? body.error_description : void 0, response.status);
82
+ if (typeof body.access_token !== "string") throw new LobeHubOAuthError("missing_access_token");
83
+ return {
84
+ accessToken: body.access_token,
85
+ expiresAt: requestedAt + Number(body.expires_in ?? 0) * 1e3,
86
+ refreshToken: typeof body.refresh_token === "string" ? body.refresh_token : void 0,
87
+ scope: typeof body.scope === "string" ? body.scope : void 0,
88
+ tokenType: typeof body.token_type === "string" ? body.token_type : "Bearer"
89
+ };
90
+ };
91
+ /** Exchange the authorization code for tokens (`authorization_code` grant). */
92
+ const exchangeAuthorizationCode = (options) => requestTokens(options, {
93
+ code: options.code,
94
+ code_verifier: options.codeVerifier,
95
+ grant_type: "authorization_code",
96
+ redirect_uri: options.redirectUri
97
+ });
98
+ /**
99
+ * Trade a refresh token for a new access token. The refresh token rotates:
100
+ * replace the stored one with `refreshToken` from the result. `invalid_grant`
101
+ * means the grant is gone and the user has to sign in again.
102
+ */
103
+ const refreshAccessToken = (options) => requestTokens(options, {
104
+ grant_type: "refresh_token",
105
+ refresh_token: options.refreshToken
106
+ });
107
+ //#endregion
108
+ //#region src/errors.ts
109
+ const REQUEST_ID_HEADER = "X-Request-Id";
110
+ const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
111
+ /**
112
+ * An error answer from the API (any non-2xx status).
113
+ *
114
+ * It carries the fields of the `ApiError` body (`code`, `message`, `details`,
115
+ * `requestId`, …), so code that read `error.code` from the plain body keeps
116
+ * working. The OpenResponses route (`POST /responses`) answers
117
+ * `{ error: { type, message, code } }`; its `type` / `code` land in `code`.
118
+ */
119
+ var LobeHubAPIError = class extends Error {
120
+ /** Stable machine-readable code (see `ApiErrorCode`); branch on this, not on `message`. */
121
+ code;
122
+ /** Validation failures list `{ path, message }` per field. */
123
+ details;
124
+ /** Response headers, e.g. `Retry-After` on a 429. */
125
+ headers;
126
+ /** The parsed (or raw text) response body. */
127
+ body;
128
+ /** Quote it when reporting an issue; also sent as the `X-Request-Id` header. */
129
+ requestId;
130
+ status;
131
+ /** `ApiError` body fields, kept for code written against the plain body. */
132
+ success = false;
133
+ timestamp;
134
+ /** @deprecated alias of `message` from the `ApiError` body. */
135
+ error;
136
+ constructor(status, body, headers) {
137
+ const record = isRecord(body) ? body : {};
138
+ const nested = isRecord(record.error) ? record.error : void 0;
139
+ const message = typeof record.message === "string" && record.message || typeof nested?.message === "string" && nested.message || typeof body === "string" && body || `Request failed with status ${status}`;
140
+ super(message);
141
+ this.name = "LobeHubAPIError";
142
+ this.status = status;
143
+ this.body = body;
144
+ this.headers = headers;
145
+ this.code = typeof record.code === "string" && record.code || typeof nested?.code === "string" && nested.code || typeof nested?.type === "string" && nested.type || `http_${status}`;
146
+ this.details = record.details;
147
+ this.requestId = typeof record.requestId === "string" && record.requestId || headers?.get(REQUEST_ID_HEADER) || void 0;
148
+ this.timestamp = typeof record.timestamp === "string" ? record.timestamp : void 0;
149
+ this.error = record.error;
150
+ }
151
+ };
152
+ /** The request never got an HTTP answer: DNS, TLS, connection reset, … */
153
+ var LobeHubConnectionError = class extends Error {
154
+ constructor(message = "Connection error", options) {
155
+ super(message, options);
156
+ this.name = "LobeHubConnectionError";
157
+ }
158
+ };
159
+ /** No response headers arrived within `timeout` milliseconds. */
160
+ var LobeHubTimeoutError = class extends LobeHubConnectionError {
161
+ timeout;
162
+ constructor(timeout) {
163
+ super(`Request timed out after ${timeout}ms`);
164
+ this.name = "LobeHubTimeoutError";
165
+ this.timeout = timeout;
166
+ }
167
+ };
168
+ /**
169
+ * Turn an error body the generated client rejected with into a
170
+ * `LobeHubAPIError`. Transport failures are already `LobeHubConnectionError`s
171
+ * (see `transport.ts`), and anything else — a caller abort, a request that
172
+ * could not be built — passes through untouched.
173
+ */
174
+ const toLobeHubError = (error, response) => response && !response.ok && !(error instanceof Error) ? new LobeHubAPIError(response.status, error, response.headers) : error;
175
+ //#endregion
4
176
  //#region src/generated/core/bodySerializer.gen.ts
5
177
  const serializeFormDataPair = (data, key, value) => {
6
178
  if (typeof value === "string" || value instanceof Blob) data.append(key, value);
@@ -665,6 +837,8 @@ var AgentGroups = class extends HeyApiClient {
665
837
  * List agent groups
666
838
  *
667
839
  * Paginated with `limit` + `cursor`; answers `{ items, total, hasMore, nextCursor }`. Clients that still expect the former bare array can pass the deprecated `format=array`, which returns every item as a plain array.
840
+ *
841
+ * **API key scopes:** `agent:read`.
668
842
  */
669
843
  list(options) {
670
844
  return (options?.client ?? this.client).get({
@@ -678,6 +852,8 @@ var AgentGroups = class extends HeyApiClient {
678
852
  }
679
853
  /**
680
854
  * Create an agent group
855
+ *
856
+ * **API key scopes:** `agent:write`.
681
857
  */
682
858
  create(options) {
683
859
  return (options.client ?? this.client).post({
@@ -692,6 +868,8 @@ var AgentGroups = class extends HeyApiClient {
692
868
  }
693
869
  /**
694
870
  * Delete an agent group
871
+ *
872
+ * **API key scopes:** `agent:write`.
695
873
  */
696
874
  delete(options) {
697
875
  return (options.client ?? this.client).delete({
@@ -705,6 +883,8 @@ var AgentGroups = class extends HeyApiClient {
705
883
  }
706
884
  /**
707
885
  * Get an agent group
886
+ *
887
+ * **API key scopes:** `agent:read`.
708
888
  */
709
889
  get(options) {
710
890
  return (options.client ?? this.client).get({
@@ -718,6 +898,8 @@ var AgentGroups = class extends HeyApiClient {
718
898
  }
719
899
  /**
720
900
  * Update an agent group
901
+ *
902
+ * **API key scopes:** `agent:write`.
721
903
  */
722
904
  update(options) {
723
905
  return (options.client ?? this.client).patch({
@@ -734,6 +916,8 @@ var AgentGroups = class extends HeyApiClient {
734
916
  var Agents = class extends HeyApiClient {
735
917
  /**
736
918
  * List agents
919
+ *
920
+ * **API key scopes:** `agent:read`.
737
921
  */
738
922
  list(options) {
739
923
  return (options?.client ?? this.client).get({
@@ -747,6 +931,8 @@ var Agents = class extends HeyApiClient {
747
931
  }
748
932
  /**
749
933
  * Create an agent
934
+ *
935
+ * **API key scopes:** `agent:write`.
750
936
  */
751
937
  create(options) {
752
938
  return (options.client ?? this.client).post({
@@ -761,6 +947,8 @@ var Agents = class extends HeyApiClient {
761
947
  }
762
948
  /**
763
949
  * Delete an agent
950
+ *
951
+ * **API key scopes:** `agent:write`.
764
952
  */
765
953
  delete(options) {
766
954
  return (options.client ?? this.client).delete({
@@ -774,6 +962,8 @@ var Agents = class extends HeyApiClient {
774
962
  }
775
963
  /**
776
964
  * Get an agent with its mounted files and knowledge bases
965
+ *
966
+ * **API key scopes:** `agent:read`.
777
967
  */
778
968
  get(options) {
779
969
  return (options.client ?? this.client).get({
@@ -787,6 +977,8 @@ var Agents = class extends HeyApiClient {
787
977
  }
788
978
  /**
789
979
  * Update an agent
980
+ *
981
+ * **API key scopes:** `agent:write`.
790
982
  */
791
983
  update(options) {
792
984
  return (options.client ?? this.client).patch({
@@ -801,6 +993,8 @@ var Agents = class extends HeyApiClient {
801
993
  }
802
994
  /**
803
995
  * Duplicate an agent
996
+ *
997
+ * **API key scopes:** `agent:write`.
804
998
  */
805
999
  createDuplicate(options) {
806
1000
  return (options.client ?? this.client).post({
@@ -815,6 +1009,8 @@ var Agents = class extends HeyApiClient {
815
1009
  }
816
1010
  /**
817
1011
  * List an agent's accounts
1012
+ *
1013
+ * **API key scopes:** `agent:read`.
818
1014
  */
819
1015
  listAccounts(options) {
820
1016
  return (options.client ?? this.client).get({
@@ -828,6 +1024,8 @@ var Agents = class extends HeyApiClient {
828
1024
  }
829
1025
  /**
830
1026
  * Mount or provision an agent account
1027
+ *
1028
+ * **API key scopes:** `agent:write`.
831
1029
  */
832
1030
  createAccount(options) {
833
1031
  return (options.client ?? this.client).post({
@@ -844,6 +1042,8 @@ var Agents = class extends HeyApiClient {
844
1042
  * Revoke an agent account
845
1043
  *
846
1044
  * Releases the account and marks it revoked. The row is kept for audit, so the response is the revoked account.
1045
+ *
1046
+ * **API key scopes:** `agent:write`.
847
1047
  */
848
1048
  deleteAccount(options) {
849
1049
  return (options.client ?? this.client).delete({
@@ -857,6 +1057,8 @@ var Agents = class extends HeyApiClient {
857
1057
  }
858
1058
  /**
859
1059
  * Get an agent account
1060
+ *
1061
+ * **API key scopes:** `agent:read`.
860
1062
  */
861
1063
  getAccount(options) {
862
1064
  return (options.client ?? this.client).get({
@@ -870,6 +1072,8 @@ var Agents = class extends HeyApiClient {
870
1072
  }
871
1073
  /**
872
1074
  * Update an agent account
1075
+ *
1076
+ * **API key scopes:** `agent:write`.
873
1077
  */
874
1078
  updateAccount(options) {
875
1079
  return (options.client ?? this.client).patch({
@@ -886,6 +1090,8 @@ var Agents = class extends HeyApiClient {
886
1090
  * Write an agent account credential
887
1091
  *
888
1092
  * Write-only: the response carries the non-secret hint and `hasCredential`, never the secret.
1093
+ *
1094
+ * **API key scopes:** `agent:credential:write` + `agent:write`.
889
1095
  */
890
1096
  updateAccountCredential(options) {
891
1097
  return (options.client ?? this.client).put({
@@ -904,6 +1110,8 @@ var ApiKeys = class extends HeyApiClient {
904
1110
  * List API keys
905
1111
  *
906
1112
  * Paginated with `limit` + `cursor`; answers `{ items, total, hasMore, nextCursor }`. Clients that still expect the former bare array can pass the deprecated `format=array`, which returns every item as a plain array.
1113
+ *
1114
+ * **API key scopes:** a full-access API key (`*`).
907
1115
  */
908
1116
  list(options) {
909
1117
  return (options?.client ?? this.client).get({
@@ -919,6 +1127,8 @@ var ApiKeys = class extends HeyApiClient {
919
1127
  * Create an API key
920
1128
  *
921
1129
  * The plaintext key is returned only in this response.
1130
+ *
1131
+ * **API key scopes:** a full-access API key (`*`).
922
1132
  */
923
1133
  create(options) {
924
1134
  return (options.client ?? this.client).post({
@@ -933,6 +1143,8 @@ var ApiKeys = class extends HeyApiClient {
933
1143
  }
934
1144
  /**
935
1145
  * Delete an API key
1146
+ *
1147
+ * **API key scopes:** a full-access API key (`*`).
936
1148
  */
937
1149
  delete(options) {
938
1150
  return (options.client ?? this.client).delete({
@@ -946,6 +1158,8 @@ var ApiKeys = class extends HeyApiClient {
946
1158
  }
947
1159
  /**
948
1160
  * Get an API key
1161
+ *
1162
+ * **API key scopes:** a full-access API key (`*`).
949
1163
  */
950
1164
  get(options) {
951
1165
  return (options.client ?? this.client).get({
@@ -959,6 +1173,8 @@ var ApiKeys = class extends HeyApiClient {
959
1173
  }
960
1174
  /**
961
1175
  * Update an API key
1176
+ *
1177
+ * **API key scopes:** a full-access API key (`*`).
962
1178
  */
963
1179
  update(options) {
964
1180
  return (options.client ?? this.client).patch({
@@ -977,6 +1193,8 @@ var Audio = class extends HeyApiClient {
977
1193
  * Create speech
978
1194
  *
979
1195
  * OpenAI-compatible text-to-speech. Point an OpenAI SDK at `/api/v1` and call `audio.speech.create`. `model` takes `provider/model` (for example `lobehub/speech-2.8-hd`) or a bare model id; the optional `provider` and `params` (emotion, pitch, volume, sampleRate) are LobeHub extensions. Returns the audio bytes; usage is reported in `X-LobeHub-*` headers. Synthesis errors use OpenAI's `{ error: { message, type, code, param } }` body; authentication and permission errors use the platform `ApiError` envelope.
1196
+ *
1197
+ * **API key scopes:** `model:invoke`.
980
1198
  */
981
1199
  createSpeech(options) {
982
1200
  return (options?.client ?? this.client).post({
@@ -992,6 +1210,8 @@ var Audio = class extends HeyApiClient {
992
1210
  var Chat = class extends HeyApiClient {
993
1211
  /**
994
1212
  * Run a non-streaming chat completion
1213
+ *
1214
+ * **API key scopes:** `model:invoke`.
995
1215
  */
996
1216
  create(options) {
997
1217
  return (options.client ?? this.client).post({
@@ -1006,6 +1226,8 @@ var Chat = class extends HeyApiClient {
1006
1226
  }
1007
1227
  /**
1008
1228
  * Translate text
1229
+ *
1230
+ * **API key scopes:** `model:invoke`.
1009
1231
  */
1010
1232
  createTranslate(options) {
1011
1233
  return (options.client ?? this.client).post({
@@ -1020,6 +1242,8 @@ var Chat = class extends HeyApiClient {
1020
1242
  }
1021
1243
  /**
1022
1244
  * Generate a reply to a message
1245
+ *
1246
+ * **API key scopes:** `model:invoke`.
1023
1247
  */
1024
1248
  createGenerateReply(options) {
1025
1249
  return (options.client ?? this.client).post({
@@ -1036,6 +1260,8 @@ var Chat = class extends HeyApiClient {
1036
1260
  var ChatGroups = class extends HeyApiClient {
1037
1261
  /**
1038
1262
  * List chat groups
1263
+ *
1264
+ * **API key scopes:** `agent:read`.
1039
1265
  */
1040
1266
  list(options) {
1041
1267
  return (options?.client ?? this.client).get({
@@ -1049,6 +1275,8 @@ var ChatGroups = class extends HeyApiClient {
1049
1275
  }
1050
1276
  /**
1051
1277
  * Create a chat group with its supervisor and members
1278
+ *
1279
+ * **API key scopes:** `agent:write`.
1052
1280
  */
1053
1281
  create(options) {
1054
1282
  return (options.client ?? this.client).post({
@@ -1063,6 +1291,8 @@ var ChatGroups = class extends HeyApiClient {
1063
1291
  }
1064
1292
  /**
1065
1293
  * Delete a chat group
1294
+ *
1295
+ * **API key scopes:** `agent:write`.
1066
1296
  */
1067
1297
  delete(options) {
1068
1298
  return (options.client ?? this.client).delete({
@@ -1076,6 +1306,8 @@ var ChatGroups = class extends HeyApiClient {
1076
1306
  }
1077
1307
  /**
1078
1308
  * Get a chat group
1309
+ *
1310
+ * **API key scopes:** `agent:read`.
1079
1311
  */
1080
1312
  get(options) {
1081
1313
  return (options.client ?? this.client).get({
@@ -1089,6 +1321,8 @@ var ChatGroups = class extends HeyApiClient {
1089
1321
  }
1090
1322
  /**
1091
1323
  * Update a chat group
1324
+ *
1325
+ * **API key scopes:** `agent:write`.
1092
1326
  */
1093
1327
  update(options) {
1094
1328
  return (options.client ?? this.client).patch({
@@ -1105,6 +1339,8 @@ var ChatGroups = class extends HeyApiClient {
1105
1339
  * Remove members from a chat group
1106
1340
  *
1107
1341
  * Detaches the agents and answers with the updated group.
1342
+ *
1343
+ * **API key scopes:** `agent:write`.
1108
1344
  */
1109
1345
  removeMembers(options) {
1110
1346
  return (options.client ?? this.client).delete({
@@ -1119,6 +1355,8 @@ var ChatGroups = class extends HeyApiClient {
1119
1355
  }
1120
1356
  /**
1121
1357
  * Add members to a chat group
1358
+ *
1359
+ * **API key scopes:** `agent:write`.
1122
1360
  */
1123
1361
  addMembers(options) {
1124
1362
  return (options.client ?? this.client).post({
@@ -1132,9 +1370,79 @@ var ChatGroups = class extends HeyApiClient {
1132
1370
  });
1133
1371
  }
1134
1372
  };
1373
+ var Documents = class extends HeyApiClient {
1374
+ /**
1375
+ * List documents
1376
+ *
1377
+ * **API key scopes:** `knowledge:read`.
1378
+ */
1379
+ list(options) {
1380
+ return (options?.client ?? this.client).get({
1381
+ security: [{
1382
+ scheme: "bearer",
1383
+ type: "http"
1384
+ }],
1385
+ url: "/api/v1/documents",
1386
+ ...options
1387
+ });
1388
+ }
1389
+ /**
1390
+ * Create a document
1391
+ *
1392
+ * Creates a page from Markdown, or a folder with `fileType: "custom/folder"`.
1393
+ *
1394
+ * **API key scopes:** `knowledge:write`.
1395
+ */
1396
+ create(options) {
1397
+ return (options.client ?? this.client).post({
1398
+ security: [{
1399
+ scheme: "bearer",
1400
+ type: "http"
1401
+ }],
1402
+ url: "/api/v1/documents",
1403
+ ...options,
1404
+ headers: mergeMethodHeaders({ "Content-Type": "application/json" }, options.headers)
1405
+ });
1406
+ }
1407
+ /**
1408
+ * Get a document
1409
+ *
1410
+ * **API key scopes:** `knowledge:read`.
1411
+ */
1412
+ get(options) {
1413
+ return (options.client ?? this.client).get({
1414
+ security: [{
1415
+ scheme: "bearer",
1416
+ type: "http"
1417
+ }],
1418
+ url: "/api/v1/documents/{id}",
1419
+ ...options
1420
+ });
1421
+ }
1422
+ /**
1423
+ * Update a document
1424
+ *
1425
+ * Replaces the title and/or the whole Markdown body. A page open in the editor receives the write through its live room.
1426
+ *
1427
+ * **API key scopes:** `knowledge:write`.
1428
+ */
1429
+ update(options) {
1430
+ return (options.client ?? this.client).patch({
1431
+ security: [{
1432
+ scheme: "bearer",
1433
+ type: "http"
1434
+ }],
1435
+ url: "/api/v1/documents/{id}",
1436
+ ...options,
1437
+ headers: mergeMethodHeaders({ "Content-Type": "application/json" }, options.headers)
1438
+ });
1439
+ }
1440
+ };
1135
1441
  var Eval = class extends HeyApiClient {
1136
1442
  /**
1137
1443
  * List eval runs
1444
+ *
1445
+ * **API key scopes:** `eval:read`.
1138
1446
  */
1139
1447
  listRuns(options) {
1140
1448
  return (options?.client ?? this.client).get({
@@ -1150,6 +1458,8 @@ var Eval = class extends HeyApiClient {
1150
1458
  * Create an eval run
1151
1459
  *
1152
1460
  * Queues an asynchronous QStash-backed evaluation run and returns immediately.
1461
+ *
1462
+ * **API key scopes:** `eval:write`.
1153
1463
  */
1154
1464
  createRuns(options) {
1155
1465
  return (options.client ?? this.client).post({
@@ -1164,6 +1474,8 @@ var Eval = class extends HeyApiClient {
1164
1474
  }
1165
1475
  /**
1166
1476
  * List topic results of an eval run
1477
+ *
1478
+ * **API key scopes:** `eval:read`.
1167
1479
  */
1168
1480
  listRunsTopics(options) {
1169
1481
  return (options.client ?? this.client).get({
@@ -1177,6 +1489,8 @@ var Eval = class extends HeyApiClient {
1177
1489
  }
1178
1490
  /**
1179
1491
  * Get an eval run
1492
+ *
1493
+ * **API key scopes:** `eval:read`.
1180
1494
  */
1181
1495
  getRuns(options) {
1182
1496
  return (options.client ?? this.client).get({
@@ -1190,6 +1504,8 @@ var Eval = class extends HeyApiClient {
1190
1504
  }
1191
1505
  /**
1192
1506
  * List case results of an eval run
1507
+ *
1508
+ * **API key scopes:** `eval:read`.
1193
1509
  */
1194
1510
  listRunsResults(options) {
1195
1511
  return (options.client ?? this.client).get({
@@ -1205,6 +1521,8 @@ var Eval = class extends HeyApiClient {
1205
1521
  * Report results for a batch of run topics
1206
1522
  *
1207
1523
  * Claim: one pending worker succeeds, others receive 409. Reports: identical replays succeed; different results conflict. Batches are atomic. External workers can supply testCaseId to associate their own topic with a dataset case on first report. Retry: only terminal runs, concurrent repeats conflict.
1524
+ *
1525
+ * **API key scopes:** `eval:write`.
1208
1526
  */
1209
1527
  createRunsResults(options) {
1210
1528
  return (options.client ?? this.client).post({
@@ -1221,6 +1539,8 @@ var Eval = class extends HeyApiClient {
1221
1539
  * List benchmarks
1222
1540
  *
1223
1541
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1542
+ *
1543
+ * **API key scopes:** `eval:read`.
1224
1544
  */
1225
1545
  listBenchmarks(options) {
1226
1546
  return (options?.client ?? this.client).get({
@@ -1236,6 +1556,8 @@ var Eval = class extends HeyApiClient {
1236
1556
  * Create a benchmark
1237
1557
  *
1238
1558
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1559
+ *
1560
+ * **API key scopes:** `eval:write`.
1239
1561
  */
1240
1562
  createBenchmarks(options) {
1241
1563
  return (options.client ?? this.client).post({
@@ -1252,6 +1574,8 @@ var Eval = class extends HeyApiClient {
1252
1574
  * Delete a benchmark
1253
1575
  *
1254
1576
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1577
+ *
1578
+ * **API key scopes:** `eval:write`.
1255
1579
  */
1256
1580
  deleteBenchmarks(options) {
1257
1581
  return (options.client ?? this.client).delete({
@@ -1267,6 +1591,8 @@ var Eval = class extends HeyApiClient {
1267
1591
  * Get a benchmark
1268
1592
  *
1269
1593
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1594
+ *
1595
+ * **API key scopes:** `eval:read`.
1270
1596
  */
1271
1597
  getBenchmarks(options) {
1272
1598
  return (options.client ?? this.client).get({
@@ -1282,6 +1608,8 @@ var Eval = class extends HeyApiClient {
1282
1608
  * Update a benchmark
1283
1609
  *
1284
1610
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1611
+ *
1612
+ * **API key scopes:** `eval:write`.
1285
1613
  */
1286
1614
  updateBenchmarks(options) {
1287
1615
  return (options.client ?? this.client).patch({
@@ -1298,6 +1626,8 @@ var Eval = class extends HeyApiClient {
1298
1626
  * List datasets
1299
1627
  *
1300
1628
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1629
+ *
1630
+ * **API key scopes:** `eval:read`.
1301
1631
  */
1302
1632
  listDatasets(options) {
1303
1633
  return (options?.client ?? this.client).get({
@@ -1313,6 +1643,8 @@ var Eval = class extends HeyApiClient {
1313
1643
  * Create a dataset
1314
1644
  *
1315
1645
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1646
+ *
1647
+ * **API key scopes:** `eval:write`.
1316
1648
  */
1317
1649
  createDatasets(options) {
1318
1650
  return (options.client ?? this.client).post({
@@ -1329,6 +1661,8 @@ var Eval = class extends HeyApiClient {
1329
1661
  * Delete a dataset
1330
1662
  *
1331
1663
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1664
+ *
1665
+ * **API key scopes:** `eval:write`.
1332
1666
  */
1333
1667
  deleteDatasets(options) {
1334
1668
  return (options.client ?? this.client).delete({
@@ -1344,6 +1678,8 @@ var Eval = class extends HeyApiClient {
1344
1678
  * Get a dataset
1345
1679
  *
1346
1680
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1681
+ *
1682
+ * **API key scopes:** `eval:read`.
1347
1683
  */
1348
1684
  getDatasets(options) {
1349
1685
  return (options.client ?? this.client).get({
@@ -1359,6 +1695,8 @@ var Eval = class extends HeyApiClient {
1359
1695
  * Update a dataset
1360
1696
  *
1361
1697
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1698
+ *
1699
+ * **API key scopes:** `eval:write`.
1362
1700
  */
1363
1701
  updateDatasets(options) {
1364
1702
  return (options.client ?? this.client).patch({
@@ -1375,6 +1713,8 @@ var Eval = class extends HeyApiClient {
1375
1713
  * List test cases of a dataset
1376
1714
  *
1377
1715
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1716
+ *
1717
+ * **API key scopes:** `eval:read`.
1378
1718
  */
1379
1719
  listDatasetsTestCases(options) {
1380
1720
  return (options.client ?? this.client).get({
@@ -1390,6 +1730,8 @@ var Eval = class extends HeyApiClient {
1390
1730
  * Create a test case
1391
1731
  *
1392
1732
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1733
+ *
1734
+ * **API key scopes:** `eval:write`.
1393
1735
  */
1394
1736
  createDatasetsTestCases(options) {
1395
1737
  return (options.client ?? this.client).post({
@@ -1406,6 +1748,8 @@ var Eval = class extends HeyApiClient {
1406
1748
  * Delete a test case
1407
1749
  *
1408
1750
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1751
+ *
1752
+ * **API key scopes:** `eval:write`.
1409
1753
  */
1410
1754
  deleteTestCases(options) {
1411
1755
  return (options.client ?? this.client).delete({
@@ -1421,6 +1765,8 @@ var Eval = class extends HeyApiClient {
1421
1765
  * Get a test case
1422
1766
  *
1423
1767
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1768
+ *
1769
+ * **API key scopes:** `eval:read`.
1424
1770
  */
1425
1771
  getTestCases(options) {
1426
1772
  return (options.client ?? this.client).get({
@@ -1436,6 +1782,8 @@ var Eval = class extends HeyApiClient {
1436
1782
  * Update a test case
1437
1783
  *
1438
1784
  * Creates accept an optional id: an identical replay returns the resource; conflicting id or identifier returns 409. Lists are paginated.
1785
+ *
1786
+ * **API key scopes:** `eval:write`.
1439
1787
  */
1440
1788
  updateTestCases(options) {
1441
1789
  return (options.client ?? this.client).patch({
@@ -1452,6 +1800,8 @@ var Eval = class extends HeyApiClient {
1452
1800
  * Claim a pending external eval run
1453
1801
  *
1454
1802
  * Claim: one pending worker succeeds, others receive 409. Reports: identical replays succeed; different results conflict. Batches are atomic. External workers can supply testCaseId to associate their own topic with a dataset case on first report. Retry: only terminal runs, concurrent repeats conflict.
1803
+ *
1804
+ * **API key scopes:** `eval:write`.
1455
1805
  */
1456
1806
  createRunsClaim(options) {
1457
1807
  return (options.client ?? this.client).post({
@@ -1467,6 +1817,8 @@ var Eval = class extends HeyApiClient {
1467
1817
  * Set the status of an external eval run
1468
1818
  *
1469
1819
  * Claim: one pending worker succeeds, others receive 409. Reports: identical replays succeed; different results conflict. Batches are atomic. External workers can supply testCaseId to associate their own topic with a dataset case on first report. Retry: only terminal runs, concurrent repeats conflict.
1820
+ *
1821
+ * **API key scopes:** `eval:write`.
1470
1822
  */
1471
1823
  updateRunsStatus(options) {
1472
1824
  return (options.client ?? this.client).patch({
@@ -1483,6 +1835,8 @@ var Eval = class extends HeyApiClient {
1483
1835
  * Retry the errored cases of an eval run
1484
1836
  *
1485
1837
  * Claim: one pending worker succeeds, others receive 409. Reports: identical replays succeed; different results conflict. Batches are atomic. External workers can supply testCaseId to associate their own topic with a dataset case on first report. Retry: only terminal runs, concurrent repeats conflict.
1838
+ *
1839
+ * **API key scopes:** `eval:write`.
1486
1840
  */
1487
1841
  createRunsRetryErrors(options) {
1488
1842
  return (options.client ?? this.client).post({
@@ -1498,6 +1852,8 @@ var Eval = class extends HeyApiClient {
1498
1852
  * Report the result of one run topic
1499
1853
  *
1500
1854
  * Claim: one pending worker succeeds, others receive 409. Reports: identical replays succeed; different results conflict. Batches are atomic. External workers can supply testCaseId to associate their own topic with a dataset case on first report. Retry: only terminal runs, concurrent repeats conflict.
1855
+ *
1856
+ * **API key scopes:** `eval:write`.
1501
1857
  */
1502
1858
  updateRunsTopicsResult(options) {
1503
1859
  return (options.client ?? this.client).put({
@@ -1514,6 +1870,8 @@ var Eval = class extends HeyApiClient {
1514
1870
  var Plugins = class extends HeyApiClient {
1515
1871
  /**
1516
1872
  * List installed plugins in the current workspace or personal scope
1873
+ *
1874
+ * **API key scopes:** `agent:read`.
1517
1875
  */
1518
1876
  list(options) {
1519
1877
  return (options?.client ?? this.client).get({
@@ -1529,6 +1887,8 @@ var Plugins = class extends HeyApiClient {
1529
1887
  var Files = class extends HeyApiClient {
1530
1888
  /**
1531
1889
  * List files
1890
+ *
1891
+ * **API key scopes:** `file:read`.
1532
1892
  */
1533
1893
  list(options) {
1534
1894
  return (options?.client ?? this.client).get({
@@ -1542,6 +1902,8 @@ var Files = class extends HeyApiClient {
1542
1902
  }
1543
1903
  /**
1544
1904
  * Upload a file and return the corresponding file record
1905
+ *
1906
+ * **API key scopes:** `file:write`.
1545
1907
  */
1546
1908
  create(options) {
1547
1909
  return (options.client ?? this.client).post({
@@ -1557,6 +1919,8 @@ var Files = class extends HeyApiClient {
1557
1919
  }
1558
1920
  /**
1559
1921
  * Delete a file
1922
+ *
1923
+ * **API key scopes:** `file:write`.
1560
1924
  */
1561
1925
  delete(options) {
1562
1926
  return (options.client ?? this.client).delete({
@@ -1572,6 +1936,8 @@ var Files = class extends HeyApiClient {
1572
1936
  * Get a file
1573
1937
  *
1574
1938
  * Non-image files include their parse result. A file that does not exist answers 400.
1939
+ *
1940
+ * **API key scopes:** `file:read`.
1575
1941
  */
1576
1942
  get(options) {
1577
1943
  return (options.client ?? this.client).get({
@@ -1585,6 +1951,8 @@ var Files = class extends HeyApiClient {
1585
1951
  }
1586
1952
  /**
1587
1953
  * Update a file
1954
+ *
1955
+ * **API key scopes:** `file:write`.
1588
1956
  */
1589
1957
  update(options) {
1590
1958
  return (options.client ?? this.client).patch({
@@ -1599,6 +1967,8 @@ var Files = class extends HeyApiClient {
1599
1967
  }
1600
1968
  /**
1601
1969
  * Get a pre-signed file URL
1970
+ *
1971
+ * **API key scopes:** `file:read`.
1602
1972
  */
1603
1973
  getUrl(options) {
1604
1974
  return (options.client ?? this.client).get({
@@ -1612,6 +1982,8 @@ var Files = class extends HeyApiClient {
1612
1982
  }
1613
1983
  /**
1614
1984
  * Parse file content
1985
+ *
1986
+ * **API key scopes:** `file:write`.
1615
1987
  */
1616
1988
  parse(options) {
1617
1989
  return (options.client ?? this.client).post({
@@ -1625,6 +1997,8 @@ var Files = class extends HeyApiClient {
1625
1997
  }
1626
1998
  /**
1627
1999
  * Get file chunking status
2000
+ *
2001
+ * **API key scopes:** `file:read`.
1628
2002
  */
1629
2003
  listChunks(options) {
1630
2004
  return (options.client ?? this.client).get({
@@ -1638,6 +2012,8 @@ var Files = class extends HeyApiClient {
1638
2012
  }
1639
2013
  /**
1640
2014
  * Start a file chunking task
2015
+ *
2016
+ * **API key scopes:** `file:write`.
1641
2017
  */
1642
2018
  createChunks(options) {
1643
2019
  return (options.client ?? this.client).post({
@@ -1652,6 +2028,8 @@ var Files = class extends HeyApiClient {
1652
2028
  }
1653
2029
  /**
1654
2030
  * Batch file upload
2031
+ *
2032
+ * **API key scopes:** `file:write`.
1655
2033
  */
1656
2034
  uploadBatch(options) {
1657
2035
  return (options.client ?? this.client).post({
@@ -1667,6 +2045,8 @@ var Files = class extends HeyApiClient {
1667
2045
  }
1668
2046
  /**
1669
2047
  * Get several files
2048
+ *
2049
+ * **API key scopes:** `file:read`.
1670
2050
  */
1671
2051
  query(options) {
1672
2052
  return (options.client ?? this.client).post({
@@ -1683,6 +2063,8 @@ var Files = class extends HeyApiClient {
1683
2063
  var Goals = class extends HeyApiClient {
1684
2064
  /**
1685
2065
  * List goals
2066
+ *
2067
+ * **API key scopes:** `agent:read`.
1686
2068
  */
1687
2069
  list(options) {
1688
2070
  return (options?.client ?? this.client).get({
@@ -1698,6 +2080,8 @@ var Goals = class extends HeyApiClient {
1698
2080
  * Create a goal
1699
2081
  *
1700
2082
  * Creates the goal graph and hands it to the coordinator.
2083
+ *
2084
+ * **API key scopes:** `agent:write`.
1701
2085
  */
1702
2086
  create(options) {
1703
2087
  return (options.client ?? this.client).post({
@@ -1712,6 +2096,8 @@ var Goals = class extends HeyApiClient {
1712
2096
  }
1713
2097
  /**
1714
2098
  * Delete a goal
2099
+ *
2100
+ * **API key scopes:** `agent:write`.
1715
2101
  */
1716
2102
  delete(options) {
1717
2103
  return (options.client ?? this.client).delete({
@@ -1725,6 +2111,8 @@ var Goals = class extends HeyApiClient {
1725
2111
  }
1726
2112
  /**
1727
2113
  * Get a goal and its graph
2114
+ *
2115
+ * **API key scopes:** `agent:read`.
1728
2116
  */
1729
2117
  get(options) {
1730
2118
  return (options.client ?? this.client).get({
@@ -1738,6 +2126,8 @@ var Goals = class extends HeyApiClient {
1738
2126
  }
1739
2127
  /**
1740
2128
  * Update a goal requirement or budget
2129
+ *
2130
+ * **API key scopes:** `agent:write`.
1741
2131
  */
1742
2132
  update(options) {
1743
2133
  return (options.client ?? this.client).patch({
@@ -1752,6 +2142,8 @@ var Goals = class extends HeyApiClient {
1752
2142
  }
1753
2143
  /**
1754
2144
  * Get goal supervision state
2145
+ *
2146
+ * **API key scopes:** `agent:read`.
1755
2147
  */
1756
2148
  getSupervision(options) {
1757
2149
  return (options.client ?? this.client).get({
@@ -1765,6 +2157,8 @@ var Goals = class extends HeyApiClient {
1765
2157
  }
1766
2158
  /**
1767
2159
  * Run the goal coordinator now
2160
+ *
2161
+ * **API key scopes:** `agent:write`.
1768
2162
  */
1769
2163
  advance(options) {
1770
2164
  return (options.client ?? this.client).post({
@@ -1778,6 +2172,8 @@ var Goals = class extends HeyApiClient {
1778
2172
  }
1779
2173
  /**
1780
2174
  * Pause a goal
2175
+ *
2176
+ * **API key scopes:** `agent:write`.
1781
2177
  */
1782
2178
  pause(options) {
1783
2179
  return (options.client ?? this.client).post({
@@ -1791,6 +2187,8 @@ var Goals = class extends HeyApiClient {
1791
2187
  }
1792
2188
  /**
1793
2189
  * Resume a paused goal
2190
+ *
2191
+ * **API key scopes:** `agent:write`.
1794
2192
  */
1795
2193
  resume(options) {
1796
2194
  return (options.client ?? this.client).post({
@@ -1804,6 +2202,8 @@ var Goals = class extends HeyApiClient {
1804
2202
  }
1805
2203
  /**
1806
2204
  * Restart every unfinished task of a goal
2205
+ *
2206
+ * **API key scopes:** `agent:write`.
1807
2207
  */
1808
2208
  restart(options) {
1809
2209
  return (options.client ?? this.client).post({
@@ -1820,6 +2220,8 @@ var Goals = class extends HeyApiClient {
1820
2220
  var Im = class extends HeyApiClient {
1821
2221
  /**
1822
2222
  * Send a message to an agent; the reply arrives asynchronously via sync
2223
+ *
2224
+ * **API key scopes:** `agent:write` + `chat:write` + `model:invoke`.
1823
2225
  */
1824
2226
  send(options) {
1825
2227
  return (options.client ?? this.client).post({
@@ -1834,6 +2236,8 @@ var Im = class extends HeyApiClient {
1834
2236
  }
1835
2237
  /**
1836
2238
  * Long-poll a conversation for whole new messages, typing and read receipts
2239
+ *
2240
+ * **API key scopes:** `chat:read`.
1837
2241
  */
1838
2242
  sync(options) {
1839
2243
  return (options.client ?? this.client).get({
@@ -1847,6 +2251,8 @@ var Im = class extends HeyApiClient {
1847
2251
  }
1848
2252
  /**
1849
2253
  * Mark the agent's messages read up to a message
2254
+ *
2255
+ * **API key scopes:** `chat:write`.
1850
2256
  */
1851
2257
  markRead(options) {
1852
2258
  return (options.client ?? this.client).post({
@@ -1863,6 +2269,8 @@ var Im = class extends HeyApiClient {
1863
2269
  var KnowledgeBases = class extends HeyApiClient {
1864
2270
  /**
1865
2271
  * List knowledge bases
2272
+ *
2273
+ * **API key scopes:** `knowledge:read`.
1866
2274
  */
1867
2275
  list(options) {
1868
2276
  return (options?.client ?? this.client).get({
@@ -1876,6 +2284,8 @@ var KnowledgeBases = class extends HeyApiClient {
1876
2284
  }
1877
2285
  /**
1878
2286
  * Create a knowledge base
2287
+ *
2288
+ * **API key scopes:** `knowledge:write`.
1879
2289
  */
1880
2290
  create(options) {
1881
2291
  return (options.client ?? this.client).post({
@@ -1892,6 +2302,8 @@ var KnowledgeBases = class extends HeyApiClient {
1892
2302
  * Delete a knowledge base
1893
2303
  *
1894
2304
  * Also deletes the files that belong to no other knowledge base.
2305
+ *
2306
+ * **API key scopes:** `knowledge:write`.
1895
2307
  */
1896
2308
  delete(options) {
1897
2309
  return (options.client ?? this.client).delete({
@@ -1905,6 +2317,8 @@ var KnowledgeBases = class extends HeyApiClient {
1905
2317
  }
1906
2318
  /**
1907
2319
  * Get a knowledge base
2320
+ *
2321
+ * **API key scopes:** `knowledge:read`.
1908
2322
  */
1909
2323
  get(options) {
1910
2324
  return (options.client ?? this.client).get({
@@ -1918,6 +2332,8 @@ var KnowledgeBases = class extends HeyApiClient {
1918
2332
  }
1919
2333
  /**
1920
2334
  * Update a knowledge base
2335
+ *
2336
+ * **API key scopes:** `knowledge:write`.
1921
2337
  */
1922
2338
  update(options) {
1923
2339
  return (options.client ?? this.client).patch({
@@ -1932,6 +2348,8 @@ var KnowledgeBases = class extends HeyApiClient {
1932
2348
  }
1933
2349
  /**
1934
2350
  * List the files of a knowledge base
2351
+ *
2352
+ * **API key scopes:** `knowledge:read`.
1935
2353
  */
1936
2354
  listFiles(options) {
1937
2355
  return (options.client ?? this.client).get({
@@ -1947,6 +2365,8 @@ var KnowledgeBases = class extends HeyApiClient {
1947
2365
  * Remove files from a knowledge base
1948
2366
  *
1949
2367
  * Detaches the files from the knowledge base without deleting them, and reports per file which ones were detached.
2368
+ *
2369
+ * **API key scopes:** `knowledge:write`.
1950
2370
  */
1951
2371
  removeFiles(options) {
1952
2372
  return (options.client ?? this.client).delete({
@@ -1961,6 +2381,8 @@ var KnowledgeBases = class extends HeyApiClient {
1961
2381
  }
1962
2382
  /**
1963
2383
  * Add files to a knowledge base
2384
+ *
2385
+ * **API key scopes:** `knowledge:write`.
1964
2386
  */
1965
2387
  addFiles(options) {
1966
2388
  return (options.client ?? this.client).post({
@@ -1975,6 +2397,8 @@ var KnowledgeBases = class extends HeyApiClient {
1975
2397
  }
1976
2398
  /**
1977
2399
  * Move files to another knowledge base
2400
+ *
2401
+ * **API key scopes:** `knowledge:write`.
1978
2402
  */
1979
2403
  moveFiles(options) {
1980
2404
  return (options.client ?? this.client).post({
@@ -1993,6 +2417,8 @@ var McpServers = class extends HeyApiClient {
1993
2417
  * List remote MCP servers
1994
2418
  *
1995
2419
  * Paginated with `limit` + `cursor`; answers `{ items, total, hasMore, nextCursor }`. Clients that still expect the former bare array can pass the deprecated `format=array`, which returns every item as a plain array.
2420
+ *
2421
+ * **API key scopes:** `mcp:read`.
1996
2422
  */
1997
2423
  list(options) {
1998
2424
  return (options?.client ?? this.client).get({
@@ -2006,6 +2432,8 @@ var McpServers = class extends HeyApiClient {
2006
2432
  }
2007
2433
  /**
2008
2434
  * Add a remote MCP server
2435
+ *
2436
+ * **API key scopes:** `mcp:write`.
2009
2437
  */
2010
2438
  create(options) {
2011
2439
  return (options.client ?? this.client).post({
@@ -2020,6 +2448,8 @@ var McpServers = class extends HeyApiClient {
2020
2448
  }
2021
2449
  /**
2022
2450
  * Delete a remote MCP server
2451
+ *
2452
+ * **API key scopes:** `mcp:write`.
2023
2453
  */
2024
2454
  delete(options) {
2025
2455
  return (options.client ?? this.client).delete({
@@ -2033,6 +2463,8 @@ var McpServers = class extends HeyApiClient {
2033
2463
  }
2034
2464
  /**
2035
2465
  * Get a remote MCP server
2466
+ *
2467
+ * **API key scopes:** `mcp:read`.
2036
2468
  */
2037
2469
  get(options) {
2038
2470
  return (options.client ?? this.client).get({
@@ -2048,6 +2480,8 @@ var McpServers = class extends HeyApiClient {
2048
2480
  * Update a remote MCP server
2049
2481
  *
2050
2482
  * Changing `serverUrl` or `credentials` resets the status to `disconnected`.
2483
+ *
2484
+ * **API key scopes:** `mcp:write`.
2051
2485
  */
2052
2486
  update(options) {
2053
2487
  return (options.client ?? this.client).patch({
@@ -2062,6 +2496,8 @@ var McpServers = class extends HeyApiClient {
2062
2496
  }
2063
2497
  /**
2064
2498
  * Discover and sync MCP tools
2499
+ *
2500
+ * **API key scopes:** `mcp:write`.
2065
2501
  */
2066
2502
  createSync(options) {
2067
2503
  return (options.client ?? this.client).post({
@@ -2079,6 +2515,8 @@ var Memories = class extends HeyApiClient {
2079
2515
  * Get the current persona document
2080
2516
  *
2081
2517
  * `data` is null until a persona has been written.
2518
+ *
2519
+ * **API key scopes:** `user:read`.
2082
2520
  */
2083
2521
  getPersona(options) {
2084
2522
  return (options?.client ?? this.client).get({
@@ -2092,6 +2530,8 @@ var Memories = class extends HeyApiClient {
2092
2530
  }
2093
2531
  /**
2094
2532
  * List persona document versions
2533
+ *
2534
+ * **API key scopes:** `user:read`.
2095
2535
  */
2096
2536
  listPersonaVersions(options) {
2097
2537
  return (options?.client ?? this.client).get({
@@ -2107,6 +2547,8 @@ var Memories = class extends HeyApiClient {
2107
2547
  * Delete all memory entries
2108
2548
  *
2109
2549
  * Removes every memory, the persona and the per-topic extraction status; `count` is the number of memories removed.
2550
+ *
2551
+ * **API key scopes:** `user:write`.
2110
2552
  */
2111
2553
  deleteAll(options) {
2112
2554
  return (options?.client ?? this.client).delete({
@@ -2120,6 +2562,8 @@ var Memories = class extends HeyApiClient {
2120
2562
  }
2121
2563
  /**
2122
2564
  * Delete a memory entry
2565
+ *
2566
+ * **API key scopes:** `user:write`.
2123
2567
  */
2124
2568
  deleteEntry(options) {
2125
2569
  return (options.client ?? this.client).delete({
@@ -2135,6 +2579,8 @@ var Memories = class extends HeyApiClient {
2135
2579
  * List the entries of a memory category
2136
2580
  *
2137
2581
  * Every identity, or the newest entries of the other categories; the array shape follows `category`.
2582
+ *
2583
+ * **API key scopes:** `user:read`.
2138
2584
  */
2139
2585
  listCategory(options) {
2140
2586
  return (options.client ?? this.client).get({
@@ -2152,6 +2598,8 @@ var MessageTranslations = class extends HeyApiClient {
2152
2598
  * Delete a message's translation
2153
2599
  *
2154
2600
  * `id` is the id of the message whose translation was removed.
2601
+ *
2602
+ * **API key scopes:** `chat:write`.
2155
2603
  */
2156
2604
  delete(options) {
2157
2605
  return (options.client ?? this.client).delete({
@@ -2167,6 +2615,8 @@ var MessageTranslations = class extends HeyApiClient {
2167
2615
  * Get a message's translation
2168
2616
  *
2169
2617
  * `null` when the message has no stored translation.
2618
+ *
2619
+ * **API key scopes:** `chat:read`.
2170
2620
  */
2171
2621
  get(options) {
2172
2622
  return (options.client ?? this.client).get({
@@ -2180,6 +2630,8 @@ var MessageTranslations = class extends HeyApiClient {
2180
2630
  }
2181
2631
  /**
2182
2632
  * Set a message's translation
2633
+ *
2634
+ * **API key scopes:** `chat:write`.
2183
2635
  */
2184
2636
  update(options) {
2185
2637
  return (options.client ?? this.client).patch({
@@ -2194,6 +2646,8 @@ var MessageTranslations = class extends HeyApiClient {
2194
2646
  }
2195
2647
  /**
2196
2648
  * Translate a message
2649
+ *
2650
+ * **API key scopes:** `chat:write` + `model:invoke`.
2197
2651
  */
2198
2652
  create(options) {
2199
2653
  return (options.client ?? this.client).post({
@@ -2210,6 +2664,8 @@ var MessageTranslations = class extends HeyApiClient {
2210
2664
  var Messages = class extends HeyApiClient {
2211
2665
  /**
2212
2666
  * Count messages
2667
+ *
2668
+ * **API key scopes:** `chat:read`.
2213
2669
  */
2214
2670
  getCount(options) {
2215
2671
  return (options?.client ?? this.client).get({
@@ -2225,6 +2681,8 @@ var Messages = class extends HeyApiClient {
2225
2681
  * Delete messages in batch
2226
2682
  *
2227
2683
  * Best effort: ids the caller may not delete or that no longer exist are skipped. `count` is the number of messages actually removed.
2684
+ *
2685
+ * **API key scopes:** `chat:write`.
2228
2686
  */
2229
2687
  deleteMany(options) {
2230
2688
  return (options.client ?? this.client).delete({
@@ -2239,6 +2697,8 @@ var Messages = class extends HeyApiClient {
2239
2697
  }
2240
2698
  /**
2241
2699
  * List messages
2700
+ *
2701
+ * **API key scopes:** `chat:read`.
2242
2702
  */
2243
2703
  list(options) {
2244
2704
  return (options?.client ?? this.client).get({
@@ -2252,6 +2712,8 @@ var Messages = class extends HeyApiClient {
2252
2712
  }
2253
2713
  /**
2254
2714
  * Create a message
2715
+ *
2716
+ * **API key scopes:** `chat:write`.
2255
2717
  */
2256
2718
  create(options) {
2257
2719
  return (options.client ?? this.client).post({
@@ -2266,6 +2728,8 @@ var Messages = class extends HeyApiClient {
2266
2728
  }
2267
2729
  /**
2268
2730
  * Delete a message
2731
+ *
2732
+ * **API key scopes:** `chat:write`.
2269
2733
  */
2270
2734
  delete(options) {
2271
2735
  return (options.client ?? this.client).delete({
@@ -2279,6 +2743,8 @@ var Messages = class extends HeyApiClient {
2279
2743
  }
2280
2744
  /**
2281
2745
  * Get a message
2746
+ *
2747
+ * **API key scopes:** `chat:read`.
2282
2748
  */
2283
2749
  get(options) {
2284
2750
  return (options.client ?? this.client).get({
@@ -2294,6 +2760,8 @@ var Messages = class extends HeyApiClient {
2294
2760
  * Create a user message and generate an AI reply
2295
2761
  *
2296
2762
  * Stores the user message, then generates and stores the assistant reply. Answers with the reply; `null` only if it could not be read back.
2763
+ *
2764
+ * **API key scopes:** `chat:write` + `model:invoke`.
2297
2765
  */
2298
2766
  createReply(options) {
2299
2767
  return (options.client ?? this.client).post({
@@ -2310,6 +2778,8 @@ var Messages = class extends HeyApiClient {
2310
2778
  var Models = class extends HeyApiClient {
2311
2779
  /**
2312
2780
  * List models
2781
+ *
2782
+ * **API key scopes:** `model:read`.
2313
2783
  */
2314
2784
  list(options) {
2315
2785
  return (options?.client ?? this.client).get({
@@ -2323,6 +2793,8 @@ var Models = class extends HeyApiClient {
2323
2793
  }
2324
2794
  /**
2325
2795
  * Create a model
2796
+ *
2797
+ * **API key scopes:** `model:write`.
2326
2798
  */
2327
2799
  create(options) {
2328
2800
  return (options.client ?? this.client).post({
@@ -2337,6 +2809,8 @@ var Models = class extends HeyApiClient {
2337
2809
  }
2338
2810
  /**
2339
2811
  * Get a model
2812
+ *
2813
+ * **API key scopes:** `model:read`.
2340
2814
  */
2341
2815
  get(options) {
2342
2816
  return (options.client ?? this.client).get({
@@ -2350,6 +2824,8 @@ var Models = class extends HeyApiClient {
2350
2824
  }
2351
2825
  /**
2352
2826
  * Update a model
2827
+ *
2828
+ * **API key scopes:** `model:write`.
2353
2829
  */
2354
2830
  update(options) {
2355
2831
  return (options.client ?? this.client).patch({
@@ -2368,6 +2844,8 @@ var Notifications = class extends HeyApiClient {
2368
2844
  * List notifications
2369
2845
  *
2370
2846
  * Unarchived notifications, newest first; pass the last `id` as `cursor` for the next page.
2847
+ *
2848
+ * **API key scopes:** any API key (no scope needed).
2371
2849
  */
2372
2850
  list(options) {
2373
2851
  return (options?.client ?? this.client).get({
@@ -2381,6 +2859,8 @@ var Notifications = class extends HeyApiClient {
2381
2859
  }
2382
2860
  /**
2383
2861
  * Get notification delivery settings
2862
+ *
2863
+ * **API key scopes:** any API key (no scope needed).
2384
2864
  */
2385
2865
  listSettings(options) {
2386
2866
  return (options?.client ?? this.client).get({
@@ -2396,6 +2876,8 @@ var Notifications = class extends HeyApiClient {
2396
2876
  * Update notification delivery settings
2397
2877
  *
2398
2878
  * Answers with the merged settings now stored for the scope.
2879
+ *
2880
+ * **API key scopes:** any API key (no scope needed).
2399
2881
  */
2400
2882
  updateSettings(options) {
2401
2883
  return (options.client ?? this.client).patch({
@@ -2410,6 +2892,8 @@ var Notifications = class extends HeyApiClient {
2410
2892
  }
2411
2893
  /**
2412
2894
  * Get the unread notification count
2895
+ *
2896
+ * **API key scopes:** any API key (no scope needed).
2413
2897
  */
2414
2898
  getUnreadCount(options) {
2415
2899
  return (options?.client ?? this.client).get({
@@ -2423,6 +2907,8 @@ var Notifications = class extends HeyApiClient {
2423
2907
  }
2424
2908
  /**
2425
2909
  * Get per-category notification counts
2910
+ *
2911
+ * **API key scopes:** any API key (no scope needed).
2426
2912
  */
2427
2913
  getCounts(options) {
2428
2914
  return (options?.client ?? this.client).get({
@@ -2436,6 +2922,8 @@ var Notifications = class extends HeyApiClient {
2436
2922
  }
2437
2923
  /**
2438
2924
  * Mark notifications as read
2925
+ *
2926
+ * **API key scopes:** `chat:write`.
2439
2927
  */
2440
2928
  markRead(options) {
2441
2929
  return (options.client ?? this.client).post({
@@ -2450,6 +2938,8 @@ var Notifications = class extends HeyApiClient {
2450
2938
  }
2451
2939
  /**
2452
2940
  * Mark every notification as read
2941
+ *
2942
+ * **API key scopes:** `chat:write`.
2453
2943
  */
2454
2944
  markAllRead(options) {
2455
2945
  return (options?.client ?? this.client).post({
@@ -2463,6 +2953,8 @@ var Notifications = class extends HeyApiClient {
2463
2953
  }
2464
2954
  /**
2465
2955
  * Archive every notification
2956
+ *
2957
+ * **API key scopes:** `chat:write`.
2466
2958
  */
2467
2959
  archiveAll(options) {
2468
2960
  return (options?.client ?? this.client).post({
@@ -2476,6 +2968,8 @@ var Notifications = class extends HeyApiClient {
2476
2968
  }
2477
2969
  /**
2478
2970
  * Archive a notification
2971
+ *
2972
+ * **API key scopes:** `chat:write`.
2479
2973
  */
2480
2974
  archive(options) {
2481
2975
  return (options.client ?? this.client).post({
@@ -2491,6 +2985,8 @@ var Notifications = class extends HeyApiClient {
2491
2985
  var Permissions = class extends HeyApiClient {
2492
2986
  /**
2493
2987
  * List permissions
2988
+ *
2989
+ * **API key scopes:** a full-access API key (`*`).
2494
2990
  */
2495
2991
  list(options) {
2496
2992
  return (options?.client ?? this.client).get({
@@ -2504,6 +3000,8 @@ var Permissions = class extends HeyApiClient {
2504
3000
  }
2505
3001
  /**
2506
3002
  * Create a permission
3003
+ *
3004
+ * **API key scopes:** a full-access API key (`*`).
2507
3005
  */
2508
3006
  create(options) {
2509
3007
  return (options.client ?? this.client).post({
@@ -2518,6 +3016,8 @@ var Permissions = class extends HeyApiClient {
2518
3016
  }
2519
3017
  /**
2520
3018
  * Delete a permission
3019
+ *
3020
+ * **API key scopes:** a full-access API key (`*`).
2521
3021
  */
2522
3022
  delete(options) {
2523
3023
  return (options.client ?? this.client).delete({
@@ -2531,6 +3031,8 @@ var Permissions = class extends HeyApiClient {
2531
3031
  }
2532
3032
  /**
2533
3033
  * Get a permission
3034
+ *
3035
+ * **API key scopes:** a full-access API key (`*`).
2534
3036
  */
2535
3037
  get(options) {
2536
3038
  return (options.client ?? this.client).get({
@@ -2544,6 +3046,8 @@ var Permissions = class extends HeyApiClient {
2544
3046
  }
2545
3047
  /**
2546
3048
  * Update a permission
3049
+ *
3050
+ * **API key scopes:** a full-access API key (`*`).
2547
3051
  */
2548
3052
  update(options) {
2549
3053
  return (options.client ?? this.client).patch({
@@ -2560,6 +3064,8 @@ var Permissions = class extends HeyApiClient {
2560
3064
  var Providers = class extends HeyApiClient {
2561
3065
  /**
2562
3066
  * List providers
3067
+ *
3068
+ * **API key scopes:** `model:read`.
2563
3069
  */
2564
3070
  list(options) {
2565
3071
  return (options?.client ?? this.client).get({
@@ -2573,6 +3079,8 @@ var Providers = class extends HeyApiClient {
2573
3079
  }
2574
3080
  /**
2575
3081
  * Create a provider
3082
+ *
3083
+ * **API key scopes:** `model:write`.
2576
3084
  */
2577
3085
  create(options) {
2578
3086
  return (options.client ?? this.client).post({
@@ -2589,6 +3097,8 @@ var Providers = class extends HeyApiClient {
2589
3097
  * Delete a provider
2590
3098
  *
2591
3099
  * Also removes the models configured under the provider.
3100
+ *
3101
+ * **API key scopes:** `model:write`.
2592
3102
  */
2593
3103
  delete(options) {
2594
3104
  return (options.client ?? this.client).delete({
@@ -2602,6 +3112,8 @@ var Providers = class extends HeyApiClient {
2602
3112
  }
2603
3113
  /**
2604
3114
  * Get a provider
3115
+ *
3116
+ * **API key scopes:** `model:read`.
2605
3117
  */
2606
3118
  get(options) {
2607
3119
  return (options.client ?? this.client).get({
@@ -2615,6 +3127,8 @@ var Providers = class extends HeyApiClient {
2615
3127
  }
2616
3128
  /**
2617
3129
  * Update a provider
3130
+ *
3131
+ * **API key scopes:** `model:write`.
2618
3132
  */
2619
3133
  update(options) {
2620
3134
  return (options.client ?? this.client).patch({
@@ -2633,6 +3147,8 @@ var PushTokens = class extends HeyApiClient {
2633
3147
  * Stop pushing to this device (sign-out)
2634
3148
  *
2635
3149
  * `id` is the device id. Idempotent: a stale `expoToken` removes nothing and leaves the rotated registration in place.
3150
+ *
3151
+ * **API key scopes:** `chat:read`.
2636
3152
  */
2637
3153
  unregister(options) {
2638
3154
  return (options.client ?? this.client).delete({
@@ -2646,6 +3162,8 @@ var PushTokens = class extends HeyApiClient {
2646
3162
  }
2647
3163
  /**
2648
3164
  * Register or rotate this device's push token
3165
+ *
3166
+ * **API key scopes:** `chat:read`.
2649
3167
  */
2650
3168
  register(options) {
2651
3169
  return (options.client ?? this.client).put({
@@ -2663,7 +3181,9 @@ var Responses = class extends HeyApiClient {
2663
3181
  /**
2664
3182
  * Create a model response
2665
3183
  *
2666
- * OpenResponses-compatible: `model` takes an agent id. Without `stream` the response object is the whole JSON body (no success envelope); a run that fails still answers 200 with `status: "failed"` and `error`. With `stream: true` the same object arrives through `response.*` server-sent events.
3184
+ * OpenResponses-compatible: `model` takes an agent id. Without `stream` the response object is the whole JSON body (no success envelope); a run that fails still answers 200 with `status: "failed"` and `error`. With `stream: true` the body is `text/event-stream`: each message is `event: <type>` plus `data: <ResponseStreamEvent JSON>`, and the final `response.completed` / `response.failed` / `response.incomplete` event carries the same response object.
3185
+ *
3186
+ * **API key scopes:** `agent:write` + `chat:write` + `model:invoke`.
2667
3187
  */
2668
3188
  create(options) {
2669
3189
  return (options.client ?? this.client).post({
@@ -2680,6 +3200,8 @@ var Responses = class extends HeyApiClient {
2680
3200
  var Roles = class extends HeyApiClient {
2681
3201
  /**
2682
3202
  * List roles
3203
+ *
3204
+ * **API key scopes:** a full-access API key (`*`).
2683
3205
  */
2684
3206
  list(options) {
2685
3207
  return (options?.client ?? this.client).get({
@@ -2693,6 +3215,8 @@ var Roles = class extends HeyApiClient {
2693
3215
  }
2694
3216
  /**
2695
3217
  * Create a role
3218
+ *
3219
+ * **API key scopes:** a full-access API key (`*`).
2696
3220
  */
2697
3221
  create(options) {
2698
3222
  return (options.client ?? this.client).post({
@@ -2707,6 +3231,8 @@ var Roles = class extends HeyApiClient {
2707
3231
  }
2708
3232
  /**
2709
3233
  * Delete a role
3234
+ *
3235
+ * **API key scopes:** a full-access API key (`*`).
2710
3236
  */
2711
3237
  delete(options) {
2712
3238
  return (options.client ?? this.client).delete({
@@ -2720,6 +3246,8 @@ var Roles = class extends HeyApiClient {
2720
3246
  }
2721
3247
  /**
2722
3248
  * Get a role
3249
+ *
3250
+ * **API key scopes:** a full-access API key (`*`).
2723
3251
  */
2724
3252
  get(options) {
2725
3253
  return (options.client ?? this.client).get({
@@ -2733,6 +3261,8 @@ var Roles = class extends HeyApiClient {
2733
3261
  }
2734
3262
  /**
2735
3263
  * Update a role
3264
+ *
3265
+ * **API key scopes:** a full-access API key (`*`).
2736
3266
  */
2737
3267
  update(options) {
2738
3268
  return (options.client ?? this.client).patch({
@@ -2749,6 +3279,8 @@ var Roles = class extends HeyApiClient {
2749
3279
  * Clear a role's permissions
2750
3280
  *
2751
3281
  * `count` is the number of permission mappings removed.
3282
+ *
3283
+ * **API key scopes:** a full-access API key (`*`).
2752
3284
  */
2753
3285
  deletePermissions(options) {
2754
3286
  return (options.client ?? this.client).delete({
@@ -2762,6 +3294,8 @@ var Roles = class extends HeyApiClient {
2762
3294
  }
2763
3295
  /**
2764
3296
  * List a role's permissions
3297
+ *
3298
+ * **API key scopes:** a full-access API key (`*`).
2765
3299
  */
2766
3300
  listPermissions(options) {
2767
3301
  return (options.client ?? this.client).get({
@@ -2777,6 +3311,8 @@ var Roles = class extends HeyApiClient {
2777
3311
  * Update a role's permissions
2778
3312
  *
2779
3313
  * Grants and revokes permissions by id; returns how many mappings changed.
3314
+ *
3315
+ * **API key scopes:** a full-access API key (`*`).
2780
3316
  */
2781
3317
  updatePermissions(options) {
2782
3318
  return (options.client ?? this.client).patch({
@@ -2793,6 +3329,8 @@ var Roles = class extends HeyApiClient {
2793
3329
  var Signals = class extends HeyApiClient {
2794
3330
  /**
2795
3331
  * Emit an agent signal source event
3332
+ *
3333
+ * **API key scopes:** `agent:write` + `model:invoke`.
2796
3334
  */
2797
3335
  emit(options) {
2798
3336
  return (options.client ?? this.client).post({
@@ -2807,6 +3345,8 @@ var Signals = class extends HeyApiClient {
2807
3345
  }
2808
3346
  /**
2809
3347
  * Trigger a synthesized agent signal source event
3348
+ *
3349
+ * **API key scopes:** `agent:write` + `model:invoke`.
2810
3350
  */
2811
3351
  trigger(options) {
2812
3352
  return (options.client ?? this.client).post({
@@ -2821,6 +3361,8 @@ var Signals = class extends HeyApiClient {
2821
3361
  }
2822
3362
  /**
2823
3363
  * List agent signal receipts for a topic
3364
+ *
3365
+ * **API key scopes:** `agent:read`.
2824
3366
  */
2825
3367
  listReceipts(options) {
2826
3368
  return (options.client ?? this.client).get({
@@ -2836,6 +3378,8 @@ var Signals = class extends HeyApiClient {
2836
3378
  var Tasks = class extends HeyApiClient {
2837
3379
  /**
2838
3380
  * List tasks
3381
+ *
3382
+ * **API key scopes:** `agent:read`.
2839
3383
  */
2840
3384
  list(options) {
2841
3385
  return (options?.client ?? this.client).get({
@@ -2849,6 +3393,8 @@ var Tasks = class extends HeyApiClient {
2849
3393
  }
2850
3394
  /**
2851
3395
  * Create a task
3396
+ *
3397
+ * **API key scopes:** `agent:write`.
2852
3398
  */
2853
3399
  create(options) {
2854
3400
  return (options.client ?? this.client).post({
@@ -2863,6 +3409,8 @@ var Tasks = class extends HeyApiClient {
2863
3409
  }
2864
3410
  /**
2865
3411
  * Delete a task
3412
+ *
3413
+ * **API key scopes:** `agent:write`.
2866
3414
  */
2867
3415
  delete(options) {
2868
3416
  return (options.client ?? this.client).delete({
@@ -2876,6 +3424,8 @@ var Tasks = class extends HeyApiClient {
2876
3424
  }
2877
3425
  /**
2878
3426
  * Get a task
3427
+ *
3428
+ * **API key scopes:** `agent:read`.
2879
3429
  */
2880
3430
  get(options) {
2881
3431
  return (options.client ?? this.client).get({
@@ -2889,6 +3439,8 @@ var Tasks = class extends HeyApiClient {
2889
3439
  }
2890
3440
  /**
2891
3441
  * Update a task
3442
+ *
3443
+ * **API key scopes:** `agent:write`.
2892
3444
  */
2893
3445
  update(options) {
2894
3446
  return (options.client ?? this.client).patch({
@@ -2903,6 +3455,8 @@ var Tasks = class extends HeyApiClient {
2903
3455
  }
2904
3456
  /**
2905
3457
  * Change a task status
3458
+ *
3459
+ * **API key scopes:** `agent:write`.
2906
3460
  */
2907
3461
  updateStatus(options) {
2908
3462
  return (options.client ?? this.client).patch({
@@ -2917,6 +3471,8 @@ var Tasks = class extends HeyApiClient {
2917
3471
  }
2918
3472
  /**
2919
3473
  * List past runs of a task
3474
+ *
3475
+ * **API key scopes:** `agent:read`.
2920
3476
  */
2921
3477
  listRuns(options) {
2922
3478
  return (options.client ?? this.client).get({
@@ -2932,6 +3488,8 @@ var Tasks = class extends HeyApiClient {
2932
3488
  * Run a task now
2933
3489
  *
2934
3490
  * Starts the run and answers once the agent operation is accepted; follow it with `operationId`.
3491
+ *
3492
+ * **API key scopes:** `agent:write`.
2935
3493
  */
2936
3494
  run(options) {
2937
3495
  return (options.client ?? this.client).post({
@@ -2948,6 +3506,8 @@ var Tasks = class extends HeyApiClient {
2948
3506
  var Topics = class extends HeyApiClient {
2949
3507
  /**
2950
3508
  * List topics
3509
+ *
3510
+ * **API key scopes:** `chat:read`.
2951
3511
  */
2952
3512
  list(options) {
2953
3513
  return (options?.client ?? this.client).get({
@@ -2961,6 +3521,8 @@ var Topics = class extends HeyApiClient {
2961
3521
  }
2962
3522
  /**
2963
3523
  * Create a topic
3524
+ *
3525
+ * **API key scopes:** `chat:write`.
2964
3526
  */
2965
3527
  create(options) {
2966
3528
  return (options.client ?? this.client).post({
@@ -2975,6 +3537,8 @@ var Topics = class extends HeyApiClient {
2975
3537
  }
2976
3538
  /**
2977
3539
  * Delete a topic
3540
+ *
3541
+ * **API key scopes:** `chat:write`.
2978
3542
  */
2979
3543
  delete(options) {
2980
3544
  return (options.client ?? this.client).delete({
@@ -2988,6 +3552,8 @@ var Topics = class extends HeyApiClient {
2988
3552
  }
2989
3553
  /**
2990
3554
  * Get a topic
3555
+ *
3556
+ * **API key scopes:** `chat:read`.
2991
3557
  */
2992
3558
  get(options) {
2993
3559
  return (options.client ?? this.client).get({
@@ -3001,6 +3567,8 @@ var Topics = class extends HeyApiClient {
3001
3567
  }
3002
3568
  /**
3003
3569
  * Update a topic
3570
+ *
3571
+ * **API key scopes:** `chat:write`.
3004
3572
  */
3005
3573
  update(options) {
3006
3574
  return (options.client ?? this.client).patch({
@@ -3015,6 +3583,8 @@ var Topics = class extends HeyApiClient {
3015
3583
  }
3016
3584
  /**
3017
3585
  * List topic threads
3586
+ *
3587
+ * **API key scopes:** `chat:read`.
3018
3588
  */
3019
3589
  listThreads(options) {
3020
3590
  return (options.client ?? this.client).get({
@@ -3032,6 +3602,8 @@ var Users = class extends HeyApiClient {
3032
3602
  * Get current authenticated user
3033
3603
  *
3034
3604
  * Reachable by every authenticated caller. An API key without `user:read` receives only `{ id }`; `messageCount` is included only with `?includeCount=1` and `chat:read`.
3605
+ *
3606
+ * **API key scopes:** any API key (no scope needed).
3035
3607
  */
3036
3608
  me(options) {
3037
3609
  return (options?.client ?? this.client).get({
@@ -3045,6 +3617,8 @@ var Users = class extends HeyApiClient {
3045
3617
  }
3046
3618
  /**
3047
3619
  * List users
3620
+ *
3621
+ * **API key scopes:** `user:read`.
3048
3622
  */
3049
3623
  list(options) {
3050
3624
  return (options?.client ?? this.client).get({
@@ -3058,6 +3632,8 @@ var Users = class extends HeyApiClient {
3058
3632
  }
3059
3633
  /**
3060
3634
  * Create a user
3635
+ *
3636
+ * **API key scopes:** `user:write`.
3061
3637
  */
3062
3638
  create(options) {
3063
3639
  return (options.client ?? this.client).post({
@@ -3072,6 +3648,8 @@ var Users = class extends HeyApiClient {
3072
3648
  }
3073
3649
  /**
3074
3650
  * Delete a user
3651
+ *
3652
+ * **API key scopes:** `user:write`.
3075
3653
  */
3076
3654
  delete(options) {
3077
3655
  return (options.client ?? this.client).delete({
@@ -3085,6 +3663,8 @@ var Users = class extends HeyApiClient {
3085
3663
  }
3086
3664
  /**
3087
3665
  * Get a user
3666
+ *
3667
+ * **API key scopes:** `user:read`.
3088
3668
  */
3089
3669
  get(options) {
3090
3670
  return (options.client ?? this.client).get({
@@ -3098,6 +3678,8 @@ var Users = class extends HeyApiClient {
3098
3678
  }
3099
3679
  /**
3100
3680
  * Update a user
3681
+ *
3682
+ * **API key scopes:** `user:write`.
3101
3683
  */
3102
3684
  update(options) {
3103
3685
  return (options.client ?? this.client).patch({
@@ -3114,6 +3696,8 @@ var Users = class extends HeyApiClient {
3114
3696
  * Clear a user's roles
3115
3697
  *
3116
3698
  * `count` is the number of role assignments removed.
3699
+ *
3700
+ * **API key scopes:** a full-access API key (`*`).
3117
3701
  */
3118
3702
  deleteRoles(options) {
3119
3703
  return (options.client ?? this.client).delete({
@@ -3127,6 +3711,8 @@ var Users = class extends HeyApiClient {
3127
3711
  }
3128
3712
  /**
3129
3713
  * List a user's roles
3714
+ *
3715
+ * **API key scopes:** a full-access API key (`*`).
3130
3716
  */
3131
3717
  listRoles(options) {
3132
3718
  return (options.client ?? this.client).get({
@@ -3142,6 +3728,8 @@ var Users = class extends HeyApiClient {
3142
3728
  * Update a user's roles
3143
3729
  *
3144
3730
  * Adds and removes role assignments, then returns all of the user's roles.
3731
+ *
3732
+ * **API key scopes:** a full-access API key (`*`).
3145
3733
  */
3146
3734
  updateRoles(options) {
3147
3735
  return (options.client ?? this.client).patch({
@@ -3158,6 +3746,8 @@ var Users = class extends HeyApiClient {
3158
3746
  var Usage = class extends HeyApiClient {
3159
3747
  /**
3160
3748
  * Get usage and quota summary
3749
+ *
3750
+ * **API key scopes:** `usage:read`.
3161
3751
  */
3162
3752
  list(options) {
3163
3753
  return (options?.client ?? this.client).get({
@@ -3204,6 +3794,10 @@ var LobeHub = class LobeHub extends HeyApiClient {
3204
3794
  get chatGroups() {
3205
3795
  return this._chatGroups ??= new ChatGroups({ client: this.client });
3206
3796
  }
3797
+ _documents;
3798
+ get documents() {
3799
+ return this._documents ??= new Documents({ client: this.client });
3800
+ }
3207
3801
  _eval;
3208
3802
  get eval() {
3209
3803
  return this._eval ??= new Eval({ client: this.client });
@@ -3294,126 +3888,430 @@ var LobeHub = class LobeHub extends HeyApiClient {
3294
3888
  }
3295
3889
  };
3296
3890
  //#endregion
3297
- //#region src/auth.ts
3298
- /** The audience every `/api/v1` access token is issued for. */
3299
- const LOBEHUB_API_RESOURCE = "urn:lobehub:chat";
3300
- /** Scopes a native app needs to call `/api/v1` and keep a refresh token. */
3301
- const DEFAULT_OAUTH_SCOPE = "profile email offline_access";
3302
- var LobeHubOAuthError = class extends Error {
3303
- code;
3304
- status;
3305
- constructor(code, message, status) {
3306
- super(message ?? code);
3307
- this.name = "LobeHubOAuthError";
3308
- this.code = code;
3309
- this.status = status;
3310
- }
3891
+ //#region src/pagination.ts
3892
+ const PAGE_FIELDS = new Set([
3893
+ "hasMore",
3894
+ "nextCursor",
3895
+ "total",
3896
+ "totalSize"
3897
+ ]);
3898
+ /** Find the item array on a page: `items` first, else the one array-valued key. */
3899
+ const pageItems = (page) => {
3900
+ if (Array.isArray(page.items)) return page.items;
3901
+ const arrays = Object.entries(page).filter(([key, value]) => !PAGE_FIELDS.has(key) && Array.isArray(value));
3902
+ if (arrays.length !== 1) throw new Error(`paginate: cannot tell the item array apart on a page with keys ${Object.keys(page).join(", ")}`);
3903
+ return arrays[0][1];
3311
3904
  };
3312
- const encodeForm = (params) => Object.entries(params).filter((entry) => entry[1] !== void 0).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
3313
- const oidcUrl = (baseURL, path) => `${(baseURL ?? "https://app.lobehub.com").replace(/\/$/, "")}/oidc/${path}`;
3314
- const queryParam = (url, name) => {
3315
- const match = url.match(new RegExp(`[?&#]${name}=([^&#]*)`));
3316
- return match ? decodeURIComponent(match[1].replaceAll("+", " ")) : void 0;
3905
+ /**
3906
+ * Walk every page of a cursor-paginated list, yielding its items: pass
3907
+ * `nextCursor` back as `cursor` until `hasMore` is false or `nextCursor` null.
3908
+ *
3909
+ * `method` may be passed unbound (`lobehub.agents.list`): the call carries the
3910
+ * client explicitly.
3911
+ */
3912
+ async function* paginate(client, method, options) {
3913
+ const base = options ?? {};
3914
+ let cursor = base.query?.cursor;
3915
+ while (true) {
3916
+ const { data } = await method({
3917
+ ...base,
3918
+ client,
3919
+ query: {
3920
+ ...base.query,
3921
+ ...cursor ? { cursor } : {}
3922
+ },
3923
+ responseStyle: "fields",
3924
+ throwOnError: true
3925
+ });
3926
+ const page = data.data;
3927
+ for (const item of pageItems(page)) yield item;
3928
+ if (!page.hasMore || !page.nextCursor || page.nextCursor === cursor) return;
3929
+ cursor = page.nextCursor;
3930
+ }
3931
+ }
3932
+ //#endregion
3933
+ //#region src/streaming.ts
3934
+ /**
3935
+ * Parse a `text/event-stream` body into its messages (WHATWG SSE framing:
3936
+ * `field: value` lines, a blank line ends a message, `:` lines are comments).
3937
+ */
3938
+ async function* parseServerSentEvents(body) {
3939
+ const decoder = new TextDecoder();
3940
+ const reader = body.getReader();
3941
+ let buffer = "";
3942
+ let data = [];
3943
+ let event;
3944
+ let id;
3945
+ /** Apply one line; returns a message when the line ends one. */
3946
+ const processLine = (line) => {
3947
+ if (line === "") {
3948
+ const message = data.length > 0 ? {
3949
+ data: data.join("\n"),
3950
+ event,
3951
+ id
3952
+ } : void 0;
3953
+ data = [];
3954
+ event = void 0;
3955
+ return message;
3956
+ }
3957
+ if (line.startsWith(":")) return;
3958
+ const colon = line.indexOf(":");
3959
+ const field = colon === -1 ? line : line.slice(0, colon);
3960
+ const raw = colon === -1 ? "" : line.slice(colon + 1);
3961
+ const value = raw.startsWith(" ") ? raw.slice(1) : raw;
3962
+ if (field === "data") data.push(value);
3963
+ else if (field === "event") event = value;
3964
+ else if (field === "id") id = value;
3965
+ };
3966
+ try {
3967
+ while (true) {
3968
+ const { done, value } = await reader.read();
3969
+ buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
3970
+ let newline;
3971
+ while ((newline = buffer.search(/\r\n|\r|\n/)) !== -1) {
3972
+ if (!done && buffer[newline] === "\r" && newline === buffer.length - 1) break;
3973
+ const line = buffer.slice(0, newline);
3974
+ buffer = buffer.slice(newline + (buffer.startsWith("\r\n", newline) ? 2 : 1));
3975
+ const message = processLine(line);
3976
+ if (message) yield message;
3977
+ }
3978
+ if (done) {
3979
+ if (buffer) processLine(buffer);
3980
+ const message = processLine("");
3981
+ if (message) yield message;
3982
+ return;
3983
+ }
3984
+ }
3985
+ } finally {
3986
+ await reader.cancel().catch(() => {});
3987
+ }
3988
+ }
3989
+ const TERMINAL_EVENTS = new Set([
3990
+ "response.completed",
3991
+ "response.failed",
3992
+ "response.incomplete"
3993
+ ]);
3994
+ /**
3995
+ * `responses.stream()` result: iterate it for typed OpenResponses events, or
3996
+ * await `finalResponse()` for the response object the last event carries.
3997
+ * Iterate it once; `abort()` (or breaking out of the loop) closes the stream.
3998
+ */
3999
+ var ResponseStream = class {
4000
+ controller = new AbortController();
4001
+ #consumed = false;
4002
+ #final;
4003
+ #open;
4004
+ constructor(open) {
4005
+ this.#open = open;
4006
+ }
4007
+ abort() {
4008
+ this.controller.abort();
4009
+ }
4010
+ async *[Symbol.asyncIterator]() {
4011
+ if (this.#consumed) throw new Error("A ResponseStream can only be iterated once");
4012
+ this.#consumed = true;
4013
+ const body = await this.#open(this.controller.signal);
4014
+ try {
4015
+ for await (const message of parseServerSentEvents(body)) {
4016
+ if (!message.data || message.data === "[DONE]") continue;
4017
+ const event = JSON.parse(message.data);
4018
+ if (TERMINAL_EVENTS.has(event.type) && "response" in event) this.#final = event.response;
4019
+ yield event;
4020
+ }
4021
+ } finally {
4022
+ if (!this.controller.signal.aborted) this.controller.abort();
4023
+ }
4024
+ }
4025
+ /** Drain the stream and resolve with the final response object. */
4026
+ async finalResponse() {
4027
+ if (!this.#consumed) for await (const _ of this);
4028
+ if (!this.#final) throw new Error("The stream ended without a final response event");
4029
+ return this.#final;
4030
+ }
3317
4031
  };
3318
- const base64Url = (bytes) => {
3319
- let binary = "";
3320
- for (const byte of bytes) binary += String.fromCharCode(byte);
3321
- return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
4032
+ //#endregion
4033
+ //#region src/transport.ts
4034
+ const IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
4035
+ const DEFAULT_TIMEOUT = 6e5;
4036
+ const DEFAULT_MAX_RETRIES = 2;
4037
+ /** Safe to resend as-is: the server applies them at most once by definition. */
4038
+ const IDEMPOTENT_METHODS = new Set([
4039
+ "DELETE",
4040
+ "GET",
4041
+ "HEAD",
4042
+ "OPTIONS",
4043
+ "PUT"
4044
+ ]);
4045
+ const RETRYABLE_STATUSES = new Set([
4046
+ 408,
4047
+ 429,
4048
+ 500,
4049
+ 502,
4050
+ 503,
4051
+ 504
4052
+ ]);
4053
+ const INITIAL_RETRY_DELAY = 500;
4054
+ const MAX_RETRY_DELAY = 8e3;
4055
+ /** A server asking for a longer pause than this gets its answer returned instead. */
4056
+ const MAX_RETRY_AFTER = 6e4;
4057
+ /**
4058
+ * Per-request settings, keyed by the `Request` the generated client built:
4059
+ * the request interceptor (which sees the call's options) records them, and
4060
+ * the fetch wrapper (which only sees the `Request`) reads them.
4061
+ */
4062
+ const requestSettings = /* @__PURE__ */ new WeakMap();
4063
+ /** `Retry-After` as delay-seconds or an HTTP date, in milliseconds. */
4064
+ const parseRetryAfter = (value, now = Date.now()) => {
4065
+ if (!value) return;
4066
+ const seconds = Number(value);
4067
+ if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
4068
+ const date = Date.parse(value);
4069
+ return Number.isNaN(date) ? void 0 : Math.max(0, date - now);
3322
4070
  };
4071
+ /** Exponential backoff with ±25% jitter: ~0.5s, 1s, 2s, … capped at 8s. */
4072
+ const backoffDelay = (attempt, random = Math.random) => Math.min(INITIAL_RETRY_DELAY * 2 ** attempt, MAX_RETRY_DELAY) * (.75 + random() * .5);
4073
+ const sleep = (ms, signal) => new Promise((resolve, reject) => {
4074
+ if (signal?.aborted) return reject(signal.reason);
4075
+ const timer = setTimeout(resolve, ms);
4076
+ signal?.addEventListener("abort", () => {
4077
+ clearTimeout(timer);
4078
+ reject(signal.reason);
4079
+ }, { once: true });
4080
+ });
3323
4081
  /**
3324
- * Generate a PKCE verifier and its S256 challenge with Web Crypto.
3325
- * Hosts without `crypto.subtle` (JavaScriptCore, older RN) should create the
3326
- * pair natively and pass it to {@link createAuthorizationUrl} instead.
4082
+ * Only resend what cannot double-apply: idempotent methods, or a POST the
4083
+ * server deduplicates through its `Idempotency-Key` (the server honors the key
4084
+ * on POST only, so a keyed PATCH is still not safe to resend).
3327
4085
  */
3328
- const createPkcePair = async () => {
3329
- const crypto = globalThis.crypto;
3330
- if (!crypto?.subtle) throw new LobeHubOAuthError("pkce_unavailable", "crypto.subtle is not available");
3331
- const verifier = base64Url(crypto.getRandomValues(new Uint8Array(32)));
3332
- const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
3333
- return {
3334
- challenge: base64Url(new Uint8Array(digest)),
3335
- verifier
3336
- };
4086
+ const isRetryable = (request) => {
4087
+ const method = request.method.toUpperCase();
4088
+ return IDEMPOTENT_METHODS.has(method) || method === "POST" && request.headers.has("Idempotency-Key");
3337
4089
  };
3338
- /** Build the `/oidc/auth` URL to open in the system browser session. */
3339
- const createAuthorizationUrl = (options) => `${oidcUrl(options.baseURL, "auth")}?${encodeForm({
3340
- client_id: options.clientId,
3341
- code_challenge: options.codeChallenge,
3342
- code_challenge_method: "S256",
3343
- prompt: "consent",
3344
- redirect_uri: options.redirectUri,
3345
- resource: LOBEHUB_API_RESOURCE,
3346
- response_type: "code",
3347
- scope: options.scope ?? "profile email offline_access",
3348
- state: options.state
3349
- })}`;
3350
4090
  /**
3351
- * Read the authorization code from the callback URL, rejecting a state that
3352
- * does not match the one sent with {@link createAuthorizationUrl}.
4091
+ * Whether an answer is worth another attempt. A keyed POST resent while the
4092
+ * first attempt is still running on the server (typical after a timeout or a
4093
+ * dropped connection) gets 409 `idempotency_conflict`; waiting and retrying
4094
+ * then yields the stored answer. A 422 with that code means a different
4095
+ * request reused the key, which a retry cannot fix.
3353
4096
  */
3354
- const parseAuthorizationCallback = (callbackUrl, expectedState) => {
3355
- const error = queryParam(callbackUrl, "error");
3356
- if (error) throw new LobeHubOAuthError(error, queryParam(callbackUrl, "error_description"));
3357
- if (queryParam(callbackUrl, "state") !== expectedState) throw new LobeHubOAuthError("state_mismatch");
3358
- const code = queryParam(callbackUrl, "code");
3359
- if (!code) throw new LobeHubOAuthError("missing_code");
3360
- return code;
4097
+ const shouldRetryStatus = async (request, response) => {
4098
+ if (RETRYABLE_STATUSES.has(response.status)) return true;
4099
+ if (response.status !== 409 || !request.headers.has("Idempotency-Key")) return false;
4100
+ return (await response.clone().json().catch(() => void 0))?.code === "idempotency_conflict";
3361
4101
  };
3362
- const requestTokens = async (options, params) => {
3363
- const fetch = options.fetch ?? globalThis.fetch;
3364
- const requestedAt = Date.now();
3365
- const response = await fetch(oidcUrl(options.baseURL, "token"), {
3366
- body: encodeForm({
3367
- client_id: options.clientId,
3368
- ...params
3369
- }),
3370
- headers: { "Content-Type": "application/x-www-form-urlencoded" },
3371
- method: "POST"
3372
- });
3373
- const body = await response.json().catch(() => ({}));
3374
- if (!response.ok) throw new LobeHubOAuthError(typeof body.error === "string" ? body.error : `http_${response.status}`, typeof body.error_description === "string" ? body.error_description : void 0, response.status);
3375
- if (typeof body.access_token !== "string") throw new LobeHubOAuthError("missing_access_token");
3376
- return {
3377
- accessToken: body.access_token,
3378
- expiresAt: requestedAt + Number(body.expires_in ?? 0) * 1e3,
3379
- refreshToken: typeof body.refresh_token === "string" ? body.refresh_token : void 0,
3380
- scope: typeof body.scope === "string" ? body.scope : void 0,
3381
- tokenType: typeof body.token_type === "string" ? body.token_type : "Bearer"
4102
+ /**
4103
+ * Wrap `fetch` with a per-attempt timeout (until the response headers arrive)
4104
+ * and retries with exponential backoff on 408/429/5xx, network failures and a
4105
+ * keyed POST's in-flight 409, honoring `Retry-After`. Network failures surface as `LobeHubConnectionError`
4106
+ * and timeouts as `LobeHubTimeoutError`; a caller abort stays an `AbortError`.
4107
+ */
4108
+ const createTransport = (baseFetch, defaults, options = {}) => {
4109
+ const transport = async (input, init) => {
4110
+ const request = input instanceof Request && !init ? input : new Request(input, init);
4111
+ const settings = requestSettings.get(request) ?? defaults;
4112
+ const { maxRetries, timeout } = settings;
4113
+ const retries = !settings.streaming && isRetryable(request) ? Math.max(0, maxRetries) : 0;
4114
+ const callerSignal = request.signal;
4115
+ for (let attempt = 0;; attempt++) {
4116
+ if (callerSignal.aborted) throw callerSignal.reason;
4117
+ const canRetry = attempt < retries;
4118
+ const current = canRetry ? request.clone() : request;
4119
+ const controller = new AbortController();
4120
+ const forwardAbort = () => controller.abort(callerSignal.reason);
4121
+ callerSignal.addEventListener("abort", forwardAbort, { once: true });
4122
+ let timedOut = false;
4123
+ const timer = timeout > 0 ? setTimeout(() => {
4124
+ timedOut = true;
4125
+ controller.abort();
4126
+ }, timeout) : void 0;
4127
+ let response;
4128
+ let failure;
4129
+ try {
4130
+ response = await baseFetch(current, { signal: controller.signal });
4131
+ } catch (error) {
4132
+ if (callerSignal.aborted) throw error;
4133
+ failure = timedOut ? new LobeHubTimeoutError(timeout) : new LobeHubConnectionError(error instanceof Error ? error.message : void 0, { cause: error });
4134
+ } finally {
4135
+ clearTimeout(timer);
4136
+ }
4137
+ if (response && !(canRetry && await shouldRetryStatus(current, response))) return response;
4138
+ if (!canRetry) throw failure;
4139
+ let delay = backoffDelay(attempt, options.random);
4140
+ if (response) {
4141
+ const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
4142
+ if (retryAfter !== void 0) {
4143
+ if (retryAfter > MAX_RETRY_AFTER) return response;
4144
+ delay = retryAfter;
4145
+ }
4146
+ await response.body?.cancel().catch(() => {});
4147
+ }
4148
+ callerSignal.removeEventListener("abort", forwardAbort);
4149
+ await sleep(delay, callerSignal);
4150
+ }
3382
4151
  };
4152
+ return transport;
4153
+ };
4154
+ //#endregion
4155
+ //#region src/uploads.ts
4156
+ const baseName = (path) => path.split(/[/\\]/).pop() || "file";
4157
+ /** Turn an `Uploadable` into a `File` the multipart serializer can send. */
4158
+ const toUploadFile = async (source, options = {}) => {
4159
+ const { name, type } = options;
4160
+ if (typeof source === "string") {
4161
+ const { readFile } = await import(
4162
+ /* @vite-ignore */
4163
+ "node:fs/promises"
4164
+ );
4165
+ const bytes = await readFile(source);
4166
+ return new File([bytes], name ?? baseName(source), { type: type ?? "application/octet-stream" });
4167
+ }
4168
+ if (source instanceof Blob) {
4169
+ const fileName = name ?? (source instanceof File ? source.name : "file");
4170
+ if (source instanceof File && !name && !type) return source;
4171
+ return new File([source], fileName, { type: type ?? source.type });
4172
+ }
4173
+ return new File([source], name ?? "file", { type: type ?? "application/octet-stream" });
4174
+ };
4175
+ //#endregion
4176
+ //#region src/client.ts
4177
+ const WORKSPACE_HEADER = "X-Workspace-Id";
4178
+ /** `lobehub.responses`, plus `stream()` for typed server-sent events. */
4179
+ var ResponsesResource = class extends Responses {
4180
+ /**
4181
+ * Start a response with `stream: true` and iterate its typed events:
4182
+ *
4183
+ * ```ts
4184
+ * for await (const event of lobehub.responses.stream({ input, model })) {
4185
+ * if (event.type === 'response.output_text.delta') process.stdout.write(event.delta);
4186
+ * }
4187
+ * ```
4188
+ */
4189
+ stream(body, options = {}) {
4190
+ return new ResponseStream(async (signal) => {
4191
+ const { response } = await this.create({
4192
+ ...options,
4193
+ body: {
4194
+ ...body,
4195
+ stream: true
4196
+ },
4197
+ client: options.client ?? this.client,
4198
+ signal: options.signal ? anySignal([options.signal, signal]) : signal,
4199
+ parseAs: "stream",
4200
+ responseStyle: "fields",
4201
+ throwOnError: true
4202
+ });
4203
+ if (!response.body) throw new Error("The streaming response has no body");
4204
+ return response.body;
4205
+ });
4206
+ }
4207
+ };
4208
+ /** `lobehub.files`, plus `upload()` for any file source. */
4209
+ var FilesResource = class extends Files {
4210
+ /**
4211
+ * Upload a `File` / `Blob`, raw bytes (`Buffer`, `Uint8Array`,
4212
+ * `ArrayBuffer`) or a local file path:
4213
+ *
4214
+ * ```ts
4215
+ * const { data } = await lobehub.files.upload('./report.pdf', { knowledgeBaseId });
4216
+ * ```
4217
+ */
4218
+ upload(source, options = {}) {
4219
+ const { agentId, directory, knowledgeBaseId, name, sessionId, skipCheckFileType, skipDeduplication, type, ...requestOptions } = options;
4220
+ return toUploadFile(source, {
4221
+ name,
4222
+ type
4223
+ }).then((file) => this.create({
4224
+ ...requestOptions,
4225
+ body: {
4226
+ agentId,
4227
+ directory,
4228
+ file,
4229
+ knowledgeBaseId,
4230
+ sessionId,
4231
+ skipCheckFileType,
4232
+ skipDeduplication
4233
+ }
4234
+ }));
4235
+ }
3383
4236
  };
3384
- /** Exchange the authorization code for tokens (`authorization_code` grant). */
3385
- const exchangeAuthorizationCode = (options) => requestTokens(options, {
3386
- code: options.code,
3387
- code_verifier: options.codeVerifier,
3388
- grant_type: "authorization_code",
3389
- redirect_uri: options.redirectUri
3390
- });
3391
4237
  /**
3392
- * Trade a refresh token for a new access token. The refresh token rotates:
3393
- * replace the stored one with `refreshToken` from the result. `invalid_grant`
3394
- * means the grant is gone and the user has to sign in again.
4238
+ * Abort when any of `signals` does. `AbortSignal.any` keeps no strong
4239
+ * reference to the inputs, so a long-lived caller signal reused across many
4240
+ * streams does not accumulate listeners; the fallback is for hosts without it.
3395
4241
  */
3396
- const refreshAccessToken = (options) => requestTokens(options, {
3397
- grant_type: "refresh_token",
3398
- refresh_token: options.refreshToken
3399
- });
3400
- //#endregion
3401
- //#region src/index.ts
4242
+ const anySignal = (signals) => {
4243
+ if (typeof AbortSignal.any === "function") return AbortSignal.any(signals);
4244
+ const controller = new AbortController();
4245
+ for (const signal of signals) {
4246
+ if (signal.aborted) {
4247
+ controller.abort(signal.reason);
4248
+ break;
4249
+ }
4250
+ signal.addEventListener("abort", () => controller.abort(signal.reason), {
4251
+ once: true,
4252
+ signal: controller.signal
4253
+ });
4254
+ }
4255
+ return controller.signal;
4256
+ };
3402
4257
  /**
3403
- * Create a resource-style LobeHub API client: `lobehub.agents.list()`,
3404
- * `lobehub.files.uploadBatch()`, `lobehub.users.me()`, …
3405
- *
3406
- * Resources, methods, and schemas are generated from
3407
- * `packages/openapi/openapi.yml` — run `bun generate` after the spec changes.
4258
+ * The resource-style client returned by `createLobeHub`: every generated
4259
+ * resource (`lobehub.agents`, `lobehub.topics`, …) plus `paginate`,
4260
+ * `responses.stream` and `files.upload`.
3408
4261
  */
3409
- const createLobeHub = (options) => {
3410
- const { accessToken, apiKey, baseURL = DEFAULT_BASE_URL, ...clientConfig } = options;
4262
+ var LobeHubClient = class extends LobeHub {
4263
+ #client;
4264
+ #files;
4265
+ #responses;
4266
+ constructor(args) {
4267
+ super(args);
4268
+ this.#client = args.client;
4269
+ }
4270
+ get files() {
4271
+ return this.#files ??= new FilesResource({ client: this.#client });
4272
+ }
4273
+ get responses() {
4274
+ return this.#responses ??= new ResponsesResource({ client: this.#client });
4275
+ }
4276
+ /**
4277
+ * Iterate every item of a cursor-paginated list across pages:
4278
+ *
4279
+ * ```ts
4280
+ * for await (const agent of lobehub.paginate(lobehub.agents.list, { query: { limit: 50 } })) {
4281
+ * console.log(agent.id);
4282
+ * }
4283
+ * ```
4284
+ */
4285
+ paginate(method, options) {
4286
+ return paginate(this.#client, method, options);
4287
+ }
4288
+ };
4289
+ function createLobeHub(options) {
4290
+ const { accessToken, apiKey, baseURL = DEFAULT_BASE_URL, fetch: baseFetch = globalThis.fetch, maxRetries = 2, timeout = DEFAULT_TIMEOUT, workspaceId, ...clientConfig } = options;
3411
4291
  if (!accessToken && !apiKey) throw new Error("createLobeHub needs an apiKey or an accessToken provider");
3412
- return new LobeHub({ client: createClient(createConfig({
4292
+ const client = createClient(createConfig({
3413
4293
  ...clientConfig,
3414
4294
  auth: accessToken ? () => accessToken() : () => apiKey,
3415
- baseUrl: baseURL
3416
- })) });
3417
- };
4295
+ baseUrl: baseURL,
4296
+ fetch: createTransport((...args) => baseFetch(...args), {
4297
+ maxRetries,
4298
+ timeout
4299
+ }),
4300
+ maxRetries,
4301
+ timeout
4302
+ }));
4303
+ client.interceptors.request.use((request, requestOptions) => {
4304
+ if (workspaceId && !request.headers.has("X-Workspace-Id")) request.headers.set(WORKSPACE_HEADER, workspaceId);
4305
+ if (requestOptions.idempotencyKey) request.headers.set(IDEMPOTENCY_KEY_HEADER, requestOptions.idempotencyKey);
4306
+ requestSettings.set(request, {
4307
+ maxRetries: requestOptions.maxRetries ?? maxRetries,
4308
+ streaming: requestOptions.parseAs === "stream",
4309
+ timeout: requestOptions.timeout ?? timeout
4310
+ });
4311
+ return request;
4312
+ });
4313
+ client.interceptors.error.use((error, response) => toLobeHubError(error, response));
4314
+ return new LobeHubClient({ client });
4315
+ }
3418
4316
  //#endregion
3419
- export { DEFAULT_BASE_URL, DEFAULT_OAUTH_SCOPE, LOBEHUB_API_RESOURCE, LobeHub, LobeHubOAuthError, createAuthorizationUrl, createLobeHub, createPkcePair, exchangeAuthorizationCode, parseAuthorizationCallback, refreshAccessToken };
4317
+ export { DEFAULT_BASE_URL, DEFAULT_MAX_RETRIES, DEFAULT_OAUTH_SCOPE, DEFAULT_TIMEOUT, IDEMPOTENCY_KEY_HEADER, LOBEHUB_API_RESOURCE, LobeHub, LobeHubAPIError, LobeHubClient, LobeHubConnectionError, LobeHubOAuthError, LobeHubTimeoutError, ResponseStream, WORKSPACE_HEADER, createAuthorizationUrl, createLobeHub, createPkcePair, exchangeAuthorizationCode, parseAuthorizationCallback, parseServerSentEvents, refreshAccessToken };