@syfthub/sdk 0.1.1 → 0.2.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.cjs +1300 -706
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1249 -454
- package/dist/index.d.ts +1249 -454
- package/dist/index.js +1296 -699
- package/dist/index.js.map +1 -1
- package/package.json +6 -7
- package/README.md +0 -276
package/dist/index.d.ts
CHANGED
|
@@ -21,8 +21,8 @@ interface AuthTokens {
|
|
|
21
21
|
* Internal HTTP client for making API requests.
|
|
22
22
|
*
|
|
23
23
|
* Handles:
|
|
24
|
-
* - Bearer token authentication
|
|
25
|
-
* - Automatic token refresh on 401 responses
|
|
24
|
+
* - Bearer token authentication (JWT or API token)
|
|
25
|
+
* - Automatic token refresh on 401 responses (JWT only)
|
|
26
26
|
* - JSON serialization/deserialization
|
|
27
27
|
* - snake_case <-> camelCase conversion
|
|
28
28
|
* - Error handling and exception mapping
|
|
@@ -32,6 +32,7 @@ declare class HTTPClient {
|
|
|
32
32
|
private readonly timeout;
|
|
33
33
|
private accessToken;
|
|
34
34
|
private refreshToken;
|
|
35
|
+
private apiToken;
|
|
35
36
|
private isRefreshing;
|
|
36
37
|
private refreshPromise;
|
|
37
38
|
/**
|
|
@@ -42,21 +43,38 @@ declare class HTTPClient {
|
|
|
42
43
|
*/
|
|
43
44
|
constructor(baseUrl: string, timeout?: number);
|
|
44
45
|
/**
|
|
45
|
-
* Set authentication tokens.
|
|
46
|
+
* Set JWT authentication tokens.
|
|
47
|
+
* Clears any API token if set.
|
|
46
48
|
*/
|
|
47
49
|
setTokens(access: string, refresh: string): void;
|
|
48
50
|
/**
|
|
49
|
-
*
|
|
51
|
+
* Set API token for authentication.
|
|
52
|
+
* Clears any JWT tokens if set.
|
|
53
|
+
*
|
|
54
|
+
* @param token - The API token (starts with "syft_")
|
|
55
|
+
*/
|
|
56
|
+
setApiToken(token: string): void;
|
|
57
|
+
/**
|
|
58
|
+
* Get current JWT authentication tokens.
|
|
59
|
+
* Returns null if using API token authentication.
|
|
50
60
|
*/
|
|
51
61
|
getTokens(): AuthTokens | null;
|
|
52
62
|
/**
|
|
53
|
-
*
|
|
63
|
+
* Check if using API token authentication.
|
|
64
|
+
*/
|
|
65
|
+
isUsingApiToken(): boolean;
|
|
66
|
+
/**
|
|
67
|
+
* Clear all authentication (JWT and API tokens).
|
|
54
68
|
*/
|
|
55
69
|
clearTokens(): void;
|
|
56
70
|
/**
|
|
57
|
-
* Check if the client has valid
|
|
71
|
+
* Check if the client has valid authentication (JWT or API token).
|
|
58
72
|
*/
|
|
59
73
|
hasTokens(): boolean;
|
|
74
|
+
/**
|
|
75
|
+
* Get the current bearer token (API token or JWT access token).
|
|
76
|
+
*/
|
|
77
|
+
private getBearerToken;
|
|
60
78
|
/**
|
|
61
79
|
* Make a GET request.
|
|
62
80
|
*/
|
|
@@ -108,6 +126,184 @@ declare class HTTPClient {
|
|
|
108
126
|
private attemptTokenRefresh;
|
|
109
127
|
}
|
|
110
128
|
|
|
129
|
+
/**
|
|
130
|
+
* API Token models for managing personal access tokens.
|
|
131
|
+
*/
|
|
132
|
+
/**
|
|
133
|
+
* Permission scopes for API tokens.
|
|
134
|
+
*/
|
|
135
|
+
type APITokenScope = 'read' | 'write' | 'full';
|
|
136
|
+
/**
|
|
137
|
+
* API token representation (without the actual token value).
|
|
138
|
+
*/
|
|
139
|
+
interface APIToken {
|
|
140
|
+
/** Unique token identifier */
|
|
141
|
+
id: number;
|
|
142
|
+
/** User-friendly label for the token */
|
|
143
|
+
name: string;
|
|
144
|
+
/** First characters of the token for identification (e.g., 'syft_pat_aB3d') */
|
|
145
|
+
tokenPrefix: string;
|
|
146
|
+
/** Permission scopes */
|
|
147
|
+
scopes: readonly APITokenScope[];
|
|
148
|
+
/** Expiration timestamp, null if never expires */
|
|
149
|
+
expiresAt: Date | null;
|
|
150
|
+
/** Last time the token was used for authentication */
|
|
151
|
+
lastUsedAt: Date | null;
|
|
152
|
+
/** IP address from the last authentication */
|
|
153
|
+
lastUsedIp: string | null;
|
|
154
|
+
/** Whether the token is active (not revoked) */
|
|
155
|
+
isActive: boolean;
|
|
156
|
+
/** When the token was created */
|
|
157
|
+
createdAt: Date;
|
|
158
|
+
/** When the token was last updated */
|
|
159
|
+
updatedAt: Date | null;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Response when creating a new API token.
|
|
163
|
+
* IMPORTANT: The token is only shown ONCE in this response!
|
|
164
|
+
*/
|
|
165
|
+
interface APITokenCreateResponse extends APIToken {
|
|
166
|
+
/** The full API token. SAVE THIS NOW - it will not be shown again! */
|
|
167
|
+
token: string;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Input for creating a new API token.
|
|
171
|
+
*/
|
|
172
|
+
interface CreateAPITokenInput {
|
|
173
|
+
/** User-friendly label for the token (e.g., 'CI/CD Pipeline') */
|
|
174
|
+
name: string;
|
|
175
|
+
/** Permission scopes. Defaults to ['full'] if not specified. */
|
|
176
|
+
scopes?: APITokenScope[];
|
|
177
|
+
/** Optional expiration timestamp. Null means never expires. */
|
|
178
|
+
expiresAt?: Date | null;
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* Input for updating an API token.
|
|
182
|
+
*/
|
|
183
|
+
interface UpdateAPITokenInput {
|
|
184
|
+
/** New name for the token */
|
|
185
|
+
name: string;
|
|
186
|
+
}
|
|
187
|
+
/**
|
|
188
|
+
* Response for listing API tokens.
|
|
189
|
+
*/
|
|
190
|
+
interface APITokenListResponse {
|
|
191
|
+
/** List of API tokens */
|
|
192
|
+
tokens: APIToken[];
|
|
193
|
+
/** Total number of tokens */
|
|
194
|
+
total: number;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Resource for managing API tokens.
|
|
199
|
+
*/
|
|
200
|
+
|
|
201
|
+
/**
|
|
202
|
+
* Resource for managing API tokens.
|
|
203
|
+
*
|
|
204
|
+
* API tokens provide an alternative to username/password authentication.
|
|
205
|
+
* They are ideal for CI/CD pipelines, scripts, and programmatic access.
|
|
206
|
+
*
|
|
207
|
+
* @example
|
|
208
|
+
* // Create a new token
|
|
209
|
+
* const result = await client.apiTokens.create({
|
|
210
|
+
* name: 'CI/CD Pipeline',
|
|
211
|
+
* scopes: ['write'],
|
|
212
|
+
* });
|
|
213
|
+
* console.log('Save this token:', result.token);
|
|
214
|
+
*
|
|
215
|
+
* // List all tokens
|
|
216
|
+
* const { tokens } = await client.apiTokens.list();
|
|
217
|
+
*
|
|
218
|
+
* // Revoke a token
|
|
219
|
+
* await client.apiTokens.revoke(tokenId);
|
|
220
|
+
*/
|
|
221
|
+
declare class APITokensResource {
|
|
222
|
+
private readonly http;
|
|
223
|
+
constructor(http: HTTPClient);
|
|
224
|
+
/**
|
|
225
|
+
* Create a new API token.
|
|
226
|
+
*
|
|
227
|
+
* IMPORTANT: The returned token is only shown ONCE!
|
|
228
|
+
* Make sure to save it immediately - it cannot be retrieved later.
|
|
229
|
+
*
|
|
230
|
+
* @param input - Token creation options
|
|
231
|
+
* @returns The created token with the full token value
|
|
232
|
+
*
|
|
233
|
+
* @example
|
|
234
|
+
* const result = await client.apiTokens.create({
|
|
235
|
+
* name: 'CI/CD Pipeline',
|
|
236
|
+
* scopes: ['write'],
|
|
237
|
+
* expiresAt: new Date('2025-12-31'),
|
|
238
|
+
* });
|
|
239
|
+
*
|
|
240
|
+
* // SAVE THIS TOKEN - it will not be shown again!
|
|
241
|
+
* console.log(result.token);
|
|
242
|
+
*/
|
|
243
|
+
create(input: CreateAPITokenInput): Promise<APITokenCreateResponse>;
|
|
244
|
+
/**
|
|
245
|
+
* List all API tokens for the current user.
|
|
246
|
+
*
|
|
247
|
+
* By default, only active tokens are returned.
|
|
248
|
+
* Note: The full token value is never returned - only the prefix.
|
|
249
|
+
*
|
|
250
|
+
* @param options - List options
|
|
251
|
+
* @returns List of tokens and total count
|
|
252
|
+
*
|
|
253
|
+
* @example
|
|
254
|
+
* // List active tokens
|
|
255
|
+
* const { tokens, total } = await client.apiTokens.list();
|
|
256
|
+
*
|
|
257
|
+
* // Include revoked tokens
|
|
258
|
+
* const all = await client.apiTokens.list({ includeInactive: true });
|
|
259
|
+
*/
|
|
260
|
+
list(options?: {
|
|
261
|
+
includeInactive?: boolean;
|
|
262
|
+
skip?: number;
|
|
263
|
+
limit?: number;
|
|
264
|
+
}): Promise<APITokenListResponse>;
|
|
265
|
+
/**
|
|
266
|
+
* Get a single API token by ID.
|
|
267
|
+
*
|
|
268
|
+
* Note: The full token value is never returned - only the prefix.
|
|
269
|
+
*
|
|
270
|
+
* @param tokenId - The token ID
|
|
271
|
+
* @returns The token details
|
|
272
|
+
*
|
|
273
|
+
* @example
|
|
274
|
+
* const token = await client.apiTokens.get(123);
|
|
275
|
+
* console.log(token.name, token.lastUsedAt);
|
|
276
|
+
*/
|
|
277
|
+
get(tokenId: number): Promise<APIToken>;
|
|
278
|
+
/**
|
|
279
|
+
* Update an API token's name.
|
|
280
|
+
*
|
|
281
|
+
* Only the name can be updated. Scopes and expiration cannot be
|
|
282
|
+
* changed after creation.
|
|
283
|
+
*
|
|
284
|
+
* @param tokenId - The token ID
|
|
285
|
+
* @param input - Update options
|
|
286
|
+
* @returns The updated token
|
|
287
|
+
*
|
|
288
|
+
* @example
|
|
289
|
+
* const updated = await client.apiTokens.update(123, {
|
|
290
|
+
* name: 'New Name',
|
|
291
|
+
* });
|
|
292
|
+
*/
|
|
293
|
+
update(tokenId: number, input: UpdateAPITokenInput): Promise<APIToken>;
|
|
294
|
+
/**
|
|
295
|
+
* Revoke an API token.
|
|
296
|
+
*
|
|
297
|
+
* The token becomes immediately unusable. This action cannot be undone.
|
|
298
|
+
*
|
|
299
|
+
* @param tokenId - The token ID to revoke
|
|
300
|
+
*
|
|
301
|
+
* @example
|
|
302
|
+
* await client.apiTokens.revoke(123);
|
|
303
|
+
*/
|
|
304
|
+
revoke(tokenId: number): Promise<void>;
|
|
305
|
+
}
|
|
306
|
+
|
|
111
307
|
/**
|
|
112
308
|
* Visibility levels for endpoints.
|
|
113
309
|
*/
|
|
@@ -116,7 +312,7 @@ declare const Visibility: {
|
|
|
116
312
|
readonly PUBLIC: "public";
|
|
117
313
|
/** Only visible to the owner and collaborators */
|
|
118
314
|
readonly PRIVATE: "private";
|
|
119
|
-
/**
|
|
315
|
+
/** Behaves like private — only visible to the owner */
|
|
120
316
|
readonly INTERNAL: "internal";
|
|
121
317
|
};
|
|
122
318
|
type Visibility = (typeof Visibility)[keyof typeof Visibility];
|
|
@@ -128,6 +324,10 @@ declare const EndpointType: {
|
|
|
128
324
|
readonly MODEL: "model";
|
|
129
325
|
/** Data source endpoint */
|
|
130
326
|
readonly DATA_SOURCE: "data_source";
|
|
327
|
+
/** Both model and data source endpoint */
|
|
328
|
+
readonly MODEL_DATA_SOURCE: "model_data_source";
|
|
329
|
+
/** Agent endpoint with session-based interaction */
|
|
330
|
+
readonly AGENT: "agent";
|
|
131
331
|
};
|
|
132
332
|
type EndpointType = (typeof EndpointType)[keyof typeof EndpointType];
|
|
133
333
|
/**
|
|
@@ -142,18 +342,6 @@ declare const UserRole: {
|
|
|
142
342
|
readonly GUEST: "guest";
|
|
143
343
|
};
|
|
144
344
|
type UserRole = (typeof UserRole)[keyof typeof UserRole];
|
|
145
|
-
/**
|
|
146
|
-
* Organization member roles.
|
|
147
|
-
*/
|
|
148
|
-
declare const OrganizationRole: {
|
|
149
|
-
/** Organization owner with full control */
|
|
150
|
-
readonly OWNER: "owner";
|
|
151
|
-
/** Administrator with management privileges */
|
|
152
|
-
readonly ADMIN: "admin";
|
|
153
|
-
/** Regular member */
|
|
154
|
-
readonly MEMBER: "member";
|
|
155
|
-
};
|
|
156
|
-
type OrganizationRole = (typeof OrganizationRole)[keyof typeof OrganizationRole];
|
|
157
345
|
|
|
158
346
|
/**
|
|
159
347
|
* User account information.
|
|
@@ -172,6 +360,10 @@ interface User {
|
|
|
172
360
|
readonly domain: string | null;
|
|
173
361
|
/** Custom aggregator URL for RAG/chat workflows */
|
|
174
362
|
readonly aggregatorUrl: string | null;
|
|
363
|
+
/** Markdown bio shown on the user's public profile */
|
|
364
|
+
readonly bio?: string | null;
|
|
365
|
+
/** Whether the user's email is shown on their public profile */
|
|
366
|
+
readonly isEmailPublic?: boolean;
|
|
175
367
|
}
|
|
176
368
|
/**
|
|
177
369
|
* Input for user registration.
|
|
@@ -208,6 +400,52 @@ interface UserUpdateInput {
|
|
|
208
400
|
domain?: string;
|
|
209
401
|
/** Custom aggregator URL for RAG/chat workflows */
|
|
210
402
|
aggregatorUrl?: string;
|
|
403
|
+
/** Markdown bio shown on the user's public profile */
|
|
404
|
+
bio?: string;
|
|
405
|
+
/** Whether the user's email is shown on their public profile */
|
|
406
|
+
isEmailPublic?: boolean;
|
|
407
|
+
}
|
|
408
|
+
/**
|
|
409
|
+
* Result of user registration.
|
|
410
|
+
*
|
|
411
|
+
* When `requiresEmailVerification` is true, tokens are null and the client
|
|
412
|
+
* must call `auth.verifyOtp()` before the user can log in.
|
|
413
|
+
*/
|
|
414
|
+
interface RegisterResult {
|
|
415
|
+
readonly user: User;
|
|
416
|
+
/** Whether the user must verify their email via OTP before receiving tokens. */
|
|
417
|
+
readonly requiresEmailVerification: boolean;
|
|
418
|
+
}
|
|
419
|
+
/**
|
|
420
|
+
* Input for verifying a registration OTP.
|
|
421
|
+
*/
|
|
422
|
+
interface VerifyOTPInput {
|
|
423
|
+
email: string;
|
|
424
|
+
/** 6-digit numeric code sent to the user's email */
|
|
425
|
+
code: string;
|
|
426
|
+
}
|
|
427
|
+
/**
|
|
428
|
+
* Input for requesting a password reset.
|
|
429
|
+
*/
|
|
430
|
+
interface PasswordResetRequestInput {
|
|
431
|
+
email: string;
|
|
432
|
+
}
|
|
433
|
+
/**
|
|
434
|
+
* Input for confirming a password reset with OTP.
|
|
435
|
+
*/
|
|
436
|
+
interface PasswordResetConfirmInput {
|
|
437
|
+
email: string;
|
|
438
|
+
/** 6-digit numeric OTP code */
|
|
439
|
+
code: string;
|
|
440
|
+
newPassword: string;
|
|
441
|
+
}
|
|
442
|
+
/**
|
|
443
|
+
* Platform authentication configuration (from GET /auth/config).
|
|
444
|
+
*/
|
|
445
|
+
interface AuthConfig {
|
|
446
|
+
readonly requireEmailVerification: boolean;
|
|
447
|
+
readonly smtpConfigured: boolean;
|
|
448
|
+
readonly passwordResetEnabled: boolean;
|
|
211
449
|
}
|
|
212
450
|
/**
|
|
213
451
|
* Input for changing password.
|
|
@@ -228,6 +466,75 @@ interface AccountingCredentials {
|
|
|
228
466
|
/** Password for authenticating with the accounting service (null if not configured) */
|
|
229
467
|
readonly password: string | null;
|
|
230
468
|
}
|
|
469
|
+
/**
|
|
470
|
+
* Input for sending a heartbeat.
|
|
471
|
+
*/
|
|
472
|
+
interface HeartbeatInput {
|
|
473
|
+
/** Full URL of this space (e.g., "https://myspace.example.com") */
|
|
474
|
+
url: string;
|
|
475
|
+
/** Time-to-live in seconds (1-3600, server caps at 600). Default is 300. */
|
|
476
|
+
ttlSeconds?: number;
|
|
477
|
+
}
|
|
478
|
+
/**
|
|
479
|
+
* Response from the heartbeat endpoint.
|
|
480
|
+
*
|
|
481
|
+
* The heartbeat mechanism allows SyftAI Spaces to signal their availability
|
|
482
|
+
* to SyftHub. The server returns the effective TTL (which may be capped)
|
|
483
|
+
* and the expiration time.
|
|
484
|
+
*/
|
|
485
|
+
interface HeartbeatResponse {
|
|
486
|
+
/** Status of the heartbeat (typically 'ok') */
|
|
487
|
+
readonly status: string;
|
|
488
|
+
/** When the heartbeat was received (ISO 8601 string) */
|
|
489
|
+
readonly receivedAt: Date;
|
|
490
|
+
/** When the heartbeat will expire (ISO 8601 string) */
|
|
491
|
+
readonly expiresAt: Date;
|
|
492
|
+
/** Extracted domain from the URL */
|
|
493
|
+
readonly domain: string;
|
|
494
|
+
/** Effective TTL applied (may be capped by server) */
|
|
495
|
+
readonly ttlSeconds: number;
|
|
496
|
+
}
|
|
497
|
+
/**
|
|
498
|
+
* A user's aggregator configuration.
|
|
499
|
+
*
|
|
500
|
+
* Aggregators are custom RAG orchestration service endpoints that users can
|
|
501
|
+
* configure to use for chat operations. Each user can have multiple aggregator
|
|
502
|
+
* configurations, with one set as the default.
|
|
503
|
+
*/
|
|
504
|
+
interface UserAggregator {
|
|
505
|
+
/** Unique aggregator configuration ID */
|
|
506
|
+
readonly id: number;
|
|
507
|
+
/** Owner user ID */
|
|
508
|
+
readonly userId: number;
|
|
509
|
+
/** Display name for the aggregator */
|
|
510
|
+
readonly name: string;
|
|
511
|
+
/** Aggregator service URL */
|
|
512
|
+
readonly url: string;
|
|
513
|
+
/** Whether this is the user's default aggregator */
|
|
514
|
+
readonly isDefault: boolean;
|
|
515
|
+
/** When the aggregator was created */
|
|
516
|
+
readonly createdAt: Date;
|
|
517
|
+
/** When the aggregator was last updated */
|
|
518
|
+
readonly updatedAt: Date;
|
|
519
|
+
}
|
|
520
|
+
/**
|
|
521
|
+
* Input for creating an aggregator configuration.
|
|
522
|
+
*/
|
|
523
|
+
interface UserAggregatorCreateInput {
|
|
524
|
+
/** Display name for the aggregator */
|
|
525
|
+
name: string;
|
|
526
|
+
/** Aggregator service URL */
|
|
527
|
+
url: string;
|
|
528
|
+
}
|
|
529
|
+
/**
|
|
530
|
+
* Input for updating an aggregator configuration.
|
|
531
|
+
*/
|
|
532
|
+
interface UserAggregatorUpdateInput {
|
|
533
|
+
/** New display name (optional) */
|
|
534
|
+
name?: string;
|
|
535
|
+
/** New aggregator URL (optional) */
|
|
536
|
+
url?: string;
|
|
537
|
+
}
|
|
231
538
|
|
|
232
539
|
/**
|
|
233
540
|
* Policy configuration for an endpoint.
|
|
@@ -253,8 +560,7 @@ interface Connection {
|
|
|
253
560
|
*/
|
|
254
561
|
interface Endpoint {
|
|
255
562
|
readonly id: number;
|
|
256
|
-
readonly userId: number
|
|
257
|
-
readonly organizationId: number | null;
|
|
563
|
+
readonly userId: number;
|
|
258
564
|
readonly name: string;
|
|
259
565
|
readonly slug: string;
|
|
260
566
|
readonly description: string;
|
|
@@ -357,13 +663,6 @@ interface EndpointUpdateInput {
|
|
|
357
663
|
connect?: Connection[];
|
|
358
664
|
contributors?: number[];
|
|
359
665
|
}
|
|
360
|
-
/**
|
|
361
|
-
* Get the owner type for an endpoint.
|
|
362
|
-
*
|
|
363
|
-
* @param endpoint - The endpoint to check
|
|
364
|
-
* @returns 'user' if user-owned, 'organization' if org-owned
|
|
365
|
-
*/
|
|
366
|
-
declare function getEndpointOwnerType(endpoint: Endpoint): 'user' | 'organization';
|
|
367
666
|
/**
|
|
368
667
|
* Get the full path for a public endpoint (owner/slug format).
|
|
369
668
|
*
|
|
@@ -387,146 +686,66 @@ interface SyncEndpointsResponse {
|
|
|
387
686
|
}
|
|
388
687
|
|
|
389
688
|
/**
|
|
390
|
-
* Accounting Models
|
|
689
|
+
* Accounting Models (MPP Wallet)
|
|
391
690
|
*
|
|
392
|
-
* Models for the
|
|
393
|
-
*
|
|
394
|
-
* from SyftHub.
|
|
691
|
+
* Models for the MPP wallet system. Replaces the previous external accounting
|
|
692
|
+
* service models with wallet-based types for the Micropayment Protocol.
|
|
395
693
|
*/
|
|
396
694
|
/**
|
|
397
|
-
*
|
|
695
|
+
* Wallet information for the current user.
|
|
398
696
|
*/
|
|
399
|
-
|
|
400
|
-
/**
|
|
401
|
-
|
|
402
|
-
/**
|
|
403
|
-
|
|
404
|
-
/** Transaction cancelled, no funds transferred */
|
|
405
|
-
readonly CANCELLED: "cancelled";
|
|
406
|
-
};
|
|
407
|
-
type TransactionStatus = (typeof TransactionStatus)[keyof typeof TransactionStatus];
|
|
408
|
-
/**
|
|
409
|
-
* Who created or resolved a transaction.
|
|
410
|
-
*/
|
|
411
|
-
declare const CreatorType: {
|
|
412
|
-
/** System-initiated transaction */
|
|
413
|
-
readonly SYSTEM: "system";
|
|
414
|
-
/** Sender-initiated transaction */
|
|
415
|
-
readonly SENDER: "sender";
|
|
416
|
-
/** Recipient-initiated transaction (delegated) */
|
|
417
|
-
readonly RECIPIENT: "recipient";
|
|
418
|
-
};
|
|
419
|
-
type CreatorType = (typeof CreatorType)[keyof typeof CreatorType];
|
|
420
|
-
/**
|
|
421
|
-
* User from accounting service with balance.
|
|
422
|
-
*
|
|
423
|
-
* This represents the user's account in the external accounting service,
|
|
424
|
-
* which is separate from the SyftHub user account.
|
|
425
|
-
*/
|
|
426
|
-
interface AccountingUser {
|
|
427
|
-
readonly id: string;
|
|
428
|
-
readonly email: string;
|
|
429
|
-
readonly balance: number;
|
|
430
|
-
readonly organization: string | null;
|
|
697
|
+
interface WalletInfo {
|
|
698
|
+
/** Wallet address (null if no wallet configured) */
|
|
699
|
+
address: string | null;
|
|
700
|
+
/** Whether a wallet exists for this user */
|
|
701
|
+
exists: boolean;
|
|
431
702
|
}
|
|
432
703
|
/**
|
|
433
|
-
*
|
|
434
|
-
*
|
|
435
|
-
* Transactions go through a lifecycle:
|
|
436
|
-
* 1. Created (status=PENDING)
|
|
437
|
-
* 2. Confirmed or Cancelled (status=COMPLETED or CANCELLED)
|
|
438
|
-
*
|
|
439
|
-
* The createdBy field indicates who initiated the transaction:
|
|
440
|
-
* - SENDER: Direct transaction by the payer
|
|
441
|
-
* - RECIPIENT: Delegated transaction using a token
|
|
442
|
-
* - SYSTEM: System-initiated transaction
|
|
443
|
-
*
|
|
444
|
-
* The resolvedBy field indicates who confirmed/cancelled.
|
|
704
|
+
* Wallet balance and recent activity.
|
|
445
705
|
*/
|
|
446
|
-
interface
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
readonly resolvedAt: Date | null;
|
|
456
|
-
readonly appName: string | null;
|
|
457
|
-
readonly appEpPath: string | null;
|
|
706
|
+
interface WalletBalance {
|
|
707
|
+
/** Current balance amount */
|
|
708
|
+
balance: number;
|
|
709
|
+
/** Currency identifier */
|
|
710
|
+
currency: string;
|
|
711
|
+
/** Recent transactions for this wallet */
|
|
712
|
+
recent_transactions: WalletTransaction[];
|
|
713
|
+
/** Whether a wallet is configured */
|
|
714
|
+
wallet_configured: boolean;
|
|
458
715
|
}
|
|
459
716
|
/**
|
|
460
|
-
*
|
|
717
|
+
* A wallet transaction record.
|
|
461
718
|
*/
|
|
462
|
-
interface
|
|
463
|
-
/**
|
|
464
|
-
recipientEmail: string;
|
|
465
|
-
/** Amount to transfer (must be > 0) */
|
|
466
|
-
amount: number;
|
|
467
|
-
/** Optional app name for context (e.g., "syftai-space") */
|
|
468
|
-
appName?: string;
|
|
469
|
-
/** Optional endpoint path for context (e.g., "alice/model") */
|
|
470
|
-
appEpPath?: string;
|
|
471
|
-
}
|
|
472
|
-
/**
|
|
473
|
-
* Input for creating a delegated transaction.
|
|
474
|
-
*/
|
|
475
|
-
interface CreateDelegatedTransactionInput {
|
|
476
|
-
/** Email of the sender who created the token */
|
|
477
|
-
senderEmail: string;
|
|
478
|
-
/** Amount to transfer (must be > 0) */
|
|
479
|
-
amount: number;
|
|
480
|
-
/** JWT token from sender's createTransactionToken() */
|
|
481
|
-
token: string;
|
|
482
|
-
}
|
|
483
|
-
/**
|
|
484
|
-
* Input for updating password.
|
|
485
|
-
*/
|
|
486
|
-
interface UpdatePasswordInput {
|
|
487
|
-
/** Current password for verification */
|
|
488
|
-
currentPassword: string;
|
|
489
|
-
/** New password to set */
|
|
490
|
-
newPassword: string;
|
|
491
|
-
}
|
|
492
|
-
/**
|
|
493
|
-
* Raw transaction response from API (before date parsing).
|
|
494
|
-
*/
|
|
495
|
-
interface TransactionResponse {
|
|
719
|
+
interface WalletTransaction {
|
|
720
|
+
/** Unique transaction identifier */
|
|
496
721
|
id: string;
|
|
497
|
-
|
|
498
|
-
|
|
722
|
+
/** Email of the sender */
|
|
723
|
+
sender_email: string;
|
|
724
|
+
/** Email of the recipient */
|
|
725
|
+
recipient_email: string;
|
|
726
|
+
/** Transaction amount */
|
|
499
727
|
amount: number;
|
|
500
|
-
status
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
728
|
+
/** Transaction status (e.g., "completed", "pending") */
|
|
729
|
+
status: string;
|
|
730
|
+
/** When the transaction was created (ISO 8601) */
|
|
731
|
+
created_at: string;
|
|
732
|
+
/** App name associated with the transaction */
|
|
733
|
+
app_name?: string;
|
|
734
|
+
/** Endpoint path associated with the transaction */
|
|
735
|
+
app_ep_path?: string;
|
|
507
736
|
}
|
|
508
737
|
/**
|
|
509
|
-
*
|
|
738
|
+
* Response from transaction tokens endpoint.
|
|
739
|
+
*
|
|
740
|
+
* @deprecated Transaction tokens are no longer used. Payments are handled
|
|
741
|
+
* via the MPP 402 flow. Kept for backward compatibility with getTransactionTokens().
|
|
510
742
|
*/
|
|
511
|
-
interface
|
|
512
|
-
token
|
|
743
|
+
interface TransactionTokensResponse {
|
|
744
|
+
/** Mapping of owner_username to transaction token */
|
|
745
|
+
tokens: Record<string, string>;
|
|
746
|
+
/** Mapping of owner_username to error message (for failed tokens) */
|
|
747
|
+
errors: Record<string, string>;
|
|
513
748
|
}
|
|
514
|
-
/**
|
|
515
|
-
* Parse a transaction response into a Transaction object.
|
|
516
|
-
*/
|
|
517
|
-
declare function parseTransaction(response: TransactionResponse): Transaction;
|
|
518
|
-
/**
|
|
519
|
-
* Check if a transaction is pending.
|
|
520
|
-
*/
|
|
521
|
-
declare function isTransactionPending(tx: Transaction): boolean;
|
|
522
|
-
/**
|
|
523
|
-
* Check if a transaction is completed.
|
|
524
|
-
*/
|
|
525
|
-
declare function isTransactionCompleted(tx: Transaction): boolean;
|
|
526
|
-
/**
|
|
527
|
-
* Check if a transaction is cancelled.
|
|
528
|
-
*/
|
|
529
|
-
declare function isTransactionCancelled(tx: Transaction): boolean;
|
|
530
749
|
|
|
531
750
|
/**
|
|
532
751
|
* Chat-related types for the SyftHub SDK.
|
|
@@ -633,6 +852,8 @@ interface ChatResponse {
|
|
|
633
852
|
metadata: ChatMetadata;
|
|
634
853
|
/** Token usage if available */
|
|
635
854
|
usage?: TokenUsage;
|
|
855
|
+
/** Normalized contribution scores per source (owner/slug to fraction 0-1) */
|
|
856
|
+
profitShare?: Record<string, number>;
|
|
636
857
|
}
|
|
637
858
|
/**
|
|
638
859
|
* A chat message for model queries.
|
|
@@ -665,6 +886,14 @@ interface ChatOptions {
|
|
|
665
886
|
signal?: AbortSignal;
|
|
666
887
|
/** Custom aggregator URL to use instead of the default */
|
|
667
888
|
aggregatorUrl?: string;
|
|
889
|
+
/** Peer token for NATS tunneling (auto-fetched if tunneling endpoints detected) */
|
|
890
|
+
peerToken?: string;
|
|
891
|
+
/** Peer channel for NATS replies (auto-fetched if tunneling endpoints detected) */
|
|
892
|
+
peerChannel?: string;
|
|
893
|
+
/** Use guest mode for unauthenticated access to policy-free endpoints */
|
|
894
|
+
guestMode?: boolean;
|
|
895
|
+
/** Conversation history (prior turns) for multi-turn context */
|
|
896
|
+
messages?: Message[];
|
|
668
897
|
}
|
|
669
898
|
/**
|
|
670
899
|
* Options for querying a data source directly.
|
|
@@ -720,16 +949,43 @@ interface RetrievalCompleteEvent {
|
|
|
720
949
|
totalDocuments: number;
|
|
721
950
|
timeMs: number;
|
|
722
951
|
}
|
|
952
|
+
/**
|
|
953
|
+
* Fired when document reranking begins (after all sources complete).
|
|
954
|
+
*/
|
|
955
|
+
interface RerankingStartEvent {
|
|
956
|
+
type: 'reranking_start';
|
|
957
|
+
/** Number of documents being reranked */
|
|
958
|
+
documents: number;
|
|
959
|
+
}
|
|
960
|
+
/**
|
|
961
|
+
* Fired when document reranking completes.
|
|
962
|
+
*/
|
|
963
|
+
interface RerankingCompleteEvent {
|
|
964
|
+
type: 'reranking_complete';
|
|
965
|
+
/** Number of documents after reranking */
|
|
966
|
+
documents: number;
|
|
967
|
+
/** Time taken for reranking in milliseconds */
|
|
968
|
+
timeMs: number;
|
|
969
|
+
}
|
|
723
970
|
/**
|
|
724
971
|
* Fired when model generation begins.
|
|
725
972
|
*/
|
|
726
973
|
interface GenerationStartEvent {
|
|
727
974
|
type: 'generation_start';
|
|
728
975
|
}
|
|
976
|
+
/**
|
|
977
|
+
* Fired periodically during non-streaming model generation to indicate progress.
|
|
978
|
+
* Emitted every ~3 seconds while waiting for the model response.
|
|
979
|
+
*/
|
|
980
|
+
interface GenerationHeartbeatEvent {
|
|
981
|
+
type: 'generation_heartbeat';
|
|
982
|
+
/** Milliseconds elapsed since generation_start */
|
|
983
|
+
elapsedMs: number;
|
|
984
|
+
}
|
|
729
985
|
/**
|
|
730
986
|
* Fired for each token from the model.
|
|
731
987
|
*/
|
|
732
|
-
interface TokenEvent {
|
|
988
|
+
interface TokenEvent$1 {
|
|
733
989
|
type: 'token';
|
|
734
990
|
content: string;
|
|
735
991
|
}
|
|
@@ -745,6 +1001,14 @@ interface DoneEvent {
|
|
|
745
1001
|
metadata: ChatMetadata;
|
|
746
1002
|
/** Token usage if available (only from non-streaming mode) */
|
|
747
1003
|
usage?: TokenUsage;
|
|
1004
|
+
/** Normalized contribution scores per source (owner/slug to fraction 0-1) */
|
|
1005
|
+
profitShare?: Record<string, number>;
|
|
1006
|
+
/**
|
|
1007
|
+
* Clean response text with attribution markers stripped.
|
|
1008
|
+
* Present when attribution ran (data sources were used). Frontends should
|
|
1009
|
+
* replace the streamed content with this field to remove raw <cite:[N]> tags.
|
|
1010
|
+
*/
|
|
1011
|
+
response?: string;
|
|
748
1012
|
}
|
|
749
1013
|
/**
|
|
750
1014
|
* Fired on error.
|
|
@@ -773,7 +1037,7 @@ interface ErrorEvent {
|
|
|
773
1037
|
* }
|
|
774
1038
|
* }
|
|
775
1039
|
*/
|
|
776
|
-
type ChatStreamEvent = RetrievalStartEvent | SourceCompleteEvent | RetrievalCompleteEvent | GenerationStartEvent | TokenEvent | DoneEvent | ErrorEvent;
|
|
1040
|
+
type ChatStreamEvent = RetrievalStartEvent | SourceCompleteEvent | RetrievalCompleteEvent | RerankingStartEvent | RerankingCompleteEvent | GenerationStartEvent | GenerationHeartbeatEvent | TokenEvent$1 | DoneEvent | ErrorEvent;
|
|
777
1041
|
|
|
778
1042
|
/**
|
|
779
1043
|
* Authentication resource for login, register, and session management.
|
|
@@ -859,7 +1123,7 @@ declare class AuthResource {
|
|
|
859
1123
|
* }
|
|
860
1124
|
* }
|
|
861
1125
|
*/
|
|
862
|
-
register(input: UserRegisterInput): Promise<
|
|
1126
|
+
register(input: UserRegisterInput): Promise<RegisterResult>;
|
|
863
1127
|
/**
|
|
864
1128
|
* Login with username/email and password.
|
|
865
1129
|
*
|
|
@@ -901,6 +1165,81 @@ declare class AuthResource {
|
|
|
901
1165
|
* @throws {ValidationError} If new password doesn't meet requirements
|
|
902
1166
|
*/
|
|
903
1167
|
changePassword(currentPassword: string, newPassword: string): Promise<void>;
|
|
1168
|
+
/**
|
|
1169
|
+
* Get the platform's authentication configuration.
|
|
1170
|
+
*
|
|
1171
|
+
* No authentication required. Use this to determine whether email
|
|
1172
|
+
* verification or password reset is available.
|
|
1173
|
+
*
|
|
1174
|
+
* @returns AuthConfig with feature flags
|
|
1175
|
+
*/
|
|
1176
|
+
getAuthConfig(): Promise<AuthConfig>;
|
|
1177
|
+
/**
|
|
1178
|
+
* Verify a registration OTP and receive auth tokens.
|
|
1179
|
+
*
|
|
1180
|
+
* After registering when email verification is required, call this with
|
|
1181
|
+
* the 6-digit code sent to the user's email.
|
|
1182
|
+
*
|
|
1183
|
+
* Idempotent: if the user is already verified, tokens are issued immediately.
|
|
1184
|
+
*
|
|
1185
|
+
* @param input - Email and 6-digit code
|
|
1186
|
+
* @returns The authenticated User
|
|
1187
|
+
* @throws {APIError} If the code is invalid or max attempts exceeded
|
|
1188
|
+
*/
|
|
1189
|
+
verifyOtp(input: VerifyOTPInput): Promise<User>;
|
|
1190
|
+
/**
|
|
1191
|
+
* Resend the registration OTP code.
|
|
1192
|
+
*
|
|
1193
|
+
* Rate-limited. Always returns successfully to prevent email enumeration.
|
|
1194
|
+
*
|
|
1195
|
+
* @param email - Email address to resend the OTP to
|
|
1196
|
+
*/
|
|
1197
|
+
resendOtp(email: string): Promise<void>;
|
|
1198
|
+
/**
|
|
1199
|
+
* Request a password reset OTP.
|
|
1200
|
+
*
|
|
1201
|
+
* Always returns successfully to prevent email enumeration.
|
|
1202
|
+
* If SMTP is not configured on the server, this is a no-op.
|
|
1203
|
+
*
|
|
1204
|
+
* @param input - Email address for password reset
|
|
1205
|
+
*/
|
|
1206
|
+
requestPasswordReset(input: PasswordResetRequestInput): Promise<void>;
|
|
1207
|
+
/**
|
|
1208
|
+
* Confirm a password reset with OTP and set a new password.
|
|
1209
|
+
*
|
|
1210
|
+
* @param input - Email, 6-digit code, and new password
|
|
1211
|
+
* @throws {APIError} If the code is invalid or max attempts exceeded
|
|
1212
|
+
*/
|
|
1213
|
+
confirmPasswordReset(input: PasswordResetConfirmInput): Promise<void>;
|
|
1214
|
+
/**
|
|
1215
|
+
* Get a peer token for NATS communication with tunneling spaces.
|
|
1216
|
+
*
|
|
1217
|
+
* Peer tokens are short-lived credentials that allow the aggregator to
|
|
1218
|
+
* communicate with tunneling SyftAI Spaces via NATS pub/sub.
|
|
1219
|
+
*
|
|
1220
|
+
* @param targetUsernames - Usernames of the tunneling spaces to communicate with
|
|
1221
|
+
* @returns PeerTokenResponse with token, channel, expiry, and NATS URL
|
|
1222
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1223
|
+
*
|
|
1224
|
+
* @example
|
|
1225
|
+
* const peer = await client.auth.getPeerToken(['alice', 'bob']);
|
|
1226
|
+
* console.log(`Peer channel: ${peer.peerChannel}, expires in ${peer.expiresIn}s`);
|
|
1227
|
+
*/
|
|
1228
|
+
getPeerToken(targetUsernames: string[]): Promise<PeerTokenResponse>;
|
|
1229
|
+
/**
|
|
1230
|
+
* Get a guest peer token for NATS communication without authentication.
|
|
1231
|
+
*
|
|
1232
|
+
* Guest peer tokens are rate-limited by IP address. They use the same
|
|
1233
|
+
* response format as authenticated peer tokens.
|
|
1234
|
+
*
|
|
1235
|
+
* @param targetUsernames - Usernames of the tunneling spaces to communicate with
|
|
1236
|
+
* @returns PeerTokenResponse with token, channel, expiry, and NATS URL
|
|
1237
|
+
*
|
|
1238
|
+
* @example
|
|
1239
|
+
* const peer = await client.auth.getGuestPeerToken(['alice']);
|
|
1240
|
+
* console.log(`Guest peer channel: ${peer.peerChannel}`);
|
|
1241
|
+
*/
|
|
1242
|
+
getGuestPeerToken(targetUsernames: string[]): Promise<PeerTokenResponse>;
|
|
904
1243
|
/**
|
|
905
1244
|
* Get a satellite token for a specific audience (target service).
|
|
906
1245
|
*
|
|
@@ -911,70 +1250,224 @@ declare class AuthResource {
|
|
|
911
1250
|
* @param audience - Target service identifier (username of the service owner)
|
|
912
1251
|
* @returns Satellite token response with token and expiry
|
|
913
1252
|
* @throws {AuthenticationError} If not authenticated
|
|
914
|
-
* @throws {ValidationError} If audience is invalid or inactive
|
|
1253
|
+
* @throws {ValidationError} If audience is invalid or inactive
|
|
1254
|
+
*
|
|
1255
|
+
* @example
|
|
1256
|
+
* // Get a token for querying alice's SyftAI-Space endpoints
|
|
1257
|
+
* const tokenResponse = await client.auth.getSatelliteToken('alice');
|
|
1258
|
+
* console.log(`Token expires in ${tokenResponse.expiresIn} seconds`);
|
|
1259
|
+
*/
|
|
1260
|
+
getSatelliteToken(audience: string): Promise<SatelliteTokenResponse>;
|
|
1261
|
+
/**
|
|
1262
|
+
* Get satellite tokens for multiple audiences in parallel.
|
|
1263
|
+
*
|
|
1264
|
+
* This is useful when making requests to endpoints owned by different users.
|
|
1265
|
+
* Tokens are cached and reused where possible.
|
|
1266
|
+
*
|
|
1267
|
+
* @param audiences - Array of unique audience identifiers (usernames)
|
|
1268
|
+
* @returns Map of audience to satellite token
|
|
1269
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1270
|
+
*
|
|
1271
|
+
* @example
|
|
1272
|
+
* // Get tokens for multiple endpoint owners
|
|
1273
|
+
* const tokens = await client.auth.getSatelliteTokens(['alice', 'bob']);
|
|
1274
|
+
* console.log(`Got ${tokens.size} tokens`);
|
|
1275
|
+
*/
|
|
1276
|
+
getSatelliteTokens(audiences: string[]): Promise<Map<string, string>>;
|
|
1277
|
+
/**
|
|
1278
|
+
* Get a guest satellite token for a specific audience (target service).
|
|
1279
|
+
*
|
|
1280
|
+
* Guest tokens allow unauthenticated users to access policy-free endpoints.
|
|
1281
|
+
* No authentication is required to call this method.
|
|
1282
|
+
*
|
|
1283
|
+
* @param audience - Target service identifier (username of the service owner)
|
|
1284
|
+
* @returns Satellite token response with token and expiry
|
|
1285
|
+
* @throws {ValidationError} If audience is invalid or inactive
|
|
1286
|
+
*
|
|
1287
|
+
* @example
|
|
1288
|
+
* // Get a guest token for querying alice's policy-free endpoints
|
|
1289
|
+
* const tokenResponse = await client.auth.getGuestSatelliteToken('alice');
|
|
1290
|
+
*/
|
|
1291
|
+
getGuestSatelliteToken(audience: string): Promise<SatelliteTokenResponse>;
|
|
1292
|
+
/**
|
|
1293
|
+
* Get guest satellite tokens for multiple audiences in parallel.
|
|
1294
|
+
*
|
|
1295
|
+
* No authentication is required to call this method.
|
|
1296
|
+
*
|
|
1297
|
+
* @param audiences - Array of unique audience identifiers (usernames)
|
|
1298
|
+
* @returns Map of audience to satellite token
|
|
1299
|
+
*
|
|
1300
|
+
* @example
|
|
1301
|
+
* const tokens = await client.auth.getGuestSatelliteTokens(['alice', 'bob']);
|
|
1302
|
+
*/
|
|
1303
|
+
getGuestSatelliteTokens(audiences: string[]): Promise<Map<string, string>>;
|
|
1304
|
+
/**
|
|
1305
|
+
* Get transaction tokens for multiple endpoint owners.
|
|
1306
|
+
*
|
|
1307
|
+
* @deprecated Transaction tokens are no longer needed. Payments are handled
|
|
1308
|
+
* via the MPP 402 flow. This method is kept for backward compatibility and
|
|
1309
|
+
* always returns empty tokens/errors.
|
|
1310
|
+
*
|
|
1311
|
+
* @param ownerUsernames - Array of endpoint owner usernames (ignored)
|
|
1312
|
+
* @returns TransactionTokensResponse with empty tokens and errors
|
|
1313
|
+
*/
|
|
1314
|
+
getTransactionTokens(ownerUsernames: string[]): Promise<TransactionTokensResponse>;
|
|
1315
|
+
/**
|
|
1316
|
+
* Get the current access token (JWT or API token).
|
|
1317
|
+
*
|
|
1318
|
+
* This is used by the chat flow to pass the user's Hub token to the
|
|
1319
|
+
* aggregator for the MPP payment callback.
|
|
1320
|
+
*
|
|
1321
|
+
* @returns The current access token, or null if not authenticated
|
|
1322
|
+
*/
|
|
1323
|
+
getAccessToken(): string | null;
|
|
1324
|
+
}
|
|
1325
|
+
/**
|
|
1326
|
+
* Response from peer token endpoint.
|
|
1327
|
+
*/
|
|
1328
|
+
interface PeerTokenResponse {
|
|
1329
|
+
/** Short-lived token for NATS authentication */
|
|
1330
|
+
peerToken: string;
|
|
1331
|
+
/** Unique reply channel for receiving responses */
|
|
1332
|
+
peerChannel: string;
|
|
1333
|
+
/** Seconds until the token expires */
|
|
1334
|
+
expiresIn: number;
|
|
1335
|
+
/** NATS server URL for WebSocket connections */
|
|
1336
|
+
natsUrl: string;
|
|
1337
|
+
}
|
|
1338
|
+
/**
|
|
1339
|
+
* Response from satellite token endpoint.
|
|
1340
|
+
*/
|
|
1341
|
+
interface SatelliteTokenResponse {
|
|
1342
|
+
/** RS256-signed JWT for the target service */
|
|
1343
|
+
targetToken: string;
|
|
1344
|
+
/** Seconds until the token expires */
|
|
1345
|
+
expiresIn: number;
|
|
1346
|
+
}
|
|
1347
|
+
|
|
1348
|
+
/**
|
|
1349
|
+
* Resource for managing user's aggregator configurations.
|
|
1350
|
+
*
|
|
1351
|
+
* Aggregators are custom RAG orchestration service endpoints that users can
|
|
1352
|
+
* configure to use for chat operations. Each user can have multiple aggregator
|
|
1353
|
+
* configurations, with one set as the default.
|
|
1354
|
+
*
|
|
1355
|
+
* The first aggregator created is automatically set as the default. Only one
|
|
1356
|
+
* aggregator can be the default at a time; setting a new default automatically
|
|
1357
|
+
* unsets the previous one.
|
|
1358
|
+
*
|
|
1359
|
+
* @example
|
|
1360
|
+
* // List all aggregators
|
|
1361
|
+
* const aggregators = await client.users.aggregators.list();
|
|
1362
|
+
* for (const agg of aggregators) {
|
|
1363
|
+
* console.log(`${agg.name}: ${agg.url}`);
|
|
1364
|
+
* }
|
|
1365
|
+
*
|
|
1366
|
+
* @example
|
|
1367
|
+
* // Create a new aggregator
|
|
1368
|
+
* const agg = await client.users.aggregators.create({
|
|
1369
|
+
* name: 'My Custom Aggregator',
|
|
1370
|
+
* url: 'https://my-aggregator.example.com'
|
|
1371
|
+
* });
|
|
1372
|
+
*
|
|
1373
|
+
* @example
|
|
1374
|
+
* // Set as default
|
|
1375
|
+
* const defaultAgg = await client.users.aggregators.setDefault(agg.id);
|
|
1376
|
+
*/
|
|
1377
|
+
declare class AggregatorsResource {
|
|
1378
|
+
private readonly http;
|
|
1379
|
+
constructor(http: HTTPClient);
|
|
1380
|
+
/**
|
|
1381
|
+
* List all aggregator configurations for the current user.
|
|
1382
|
+
*
|
|
1383
|
+
* @returns Array of UserAggregator objects
|
|
1384
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1385
|
+
*
|
|
1386
|
+
* @example
|
|
1387
|
+
* const aggregators = await client.users.aggregators.list();
|
|
1388
|
+
* for (const agg of aggregators) {
|
|
1389
|
+
* if (agg.isDefault) {
|
|
1390
|
+
* console.log(`Default: ${agg.name}`);
|
|
1391
|
+
* }
|
|
1392
|
+
* }
|
|
1393
|
+
*/
|
|
1394
|
+
list(): Promise<UserAggregator[]>;
|
|
1395
|
+
/**
|
|
1396
|
+
* Get a specific aggregator configuration by ID.
|
|
1397
|
+
*
|
|
1398
|
+
* @param aggregatorId - The aggregator ID
|
|
1399
|
+
* @returns The UserAggregator object
|
|
1400
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1401
|
+
* @throws {NotFoundError} If aggregator not found
|
|
1402
|
+
*
|
|
1403
|
+
* @example
|
|
1404
|
+
* const agg = await client.users.aggregators.get(1);
|
|
1405
|
+
* console.log(`${agg.name}: ${agg.url}`);
|
|
1406
|
+
*/
|
|
1407
|
+
get(aggregatorId: number): Promise<UserAggregator>;
|
|
1408
|
+
/**
|
|
1409
|
+
* Create a new aggregator configuration.
|
|
1410
|
+
*
|
|
1411
|
+
* The first aggregator created is automatically set as the default.
|
|
1412
|
+
*
|
|
1413
|
+
* @param input - Aggregator creation input
|
|
1414
|
+
* @returns The created UserAggregator object
|
|
1415
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1416
|
+
* @throws {ValidationError} If input is invalid
|
|
1417
|
+
*
|
|
1418
|
+
* @example
|
|
1419
|
+
* const agg = await client.users.aggregators.create({
|
|
1420
|
+
* name: 'My Custom Aggregator',
|
|
1421
|
+
* url: 'https://my-aggregator.example.com'
|
|
1422
|
+
* });
|
|
1423
|
+
* console.log(`Created: ${agg.id}`);
|
|
1424
|
+
*/
|
|
1425
|
+
create(input: UserAggregatorCreateInput): Promise<UserAggregator>;
|
|
1426
|
+
/**
|
|
1427
|
+
* Update an aggregator configuration.
|
|
1428
|
+
*
|
|
1429
|
+
* Only provided fields will be updated.
|
|
1430
|
+
*
|
|
1431
|
+
* @param aggregatorId - The aggregator ID to update
|
|
1432
|
+
* @param input - Fields to update
|
|
1433
|
+
* @returns The updated UserAggregator object
|
|
1434
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1435
|
+
* @throws {NotFoundError} If aggregator not found
|
|
1436
|
+
* @throws {ValidationError} If input is invalid
|
|
915
1437
|
*
|
|
916
1438
|
* @example
|
|
917
|
-
*
|
|
918
|
-
*
|
|
919
|
-
*
|
|
1439
|
+
* const agg = await client.users.aggregators.update(1, {
|
|
1440
|
+
* name: 'Updated Name'
|
|
1441
|
+
* });
|
|
920
1442
|
*/
|
|
921
|
-
|
|
1443
|
+
update(aggregatorId: number, input: UserAggregatorUpdateInput): Promise<UserAggregator>;
|
|
922
1444
|
/**
|
|
923
|
-
*
|
|
924
|
-
*
|
|
925
|
-
* This is useful when making requests to endpoints owned by different users.
|
|
926
|
-
* Tokens are cached and reused where possible.
|
|
1445
|
+
* Delete an aggregator configuration.
|
|
927
1446
|
*
|
|
928
|
-
* @param
|
|
929
|
-
* @returns Map of audience to satellite token
|
|
1447
|
+
* @param aggregatorId - The aggregator ID to delete
|
|
930
1448
|
* @throws {AuthenticationError} If not authenticated
|
|
1449
|
+
* @throws {NotFoundError} If aggregator not found
|
|
931
1450
|
*
|
|
932
1451
|
* @example
|
|
933
|
-
*
|
|
934
|
-
* const tokens = await client.auth.getSatelliteTokens(['alice', 'bob']);
|
|
935
|
-
* console.log(`Got ${tokens.size} tokens`);
|
|
1452
|
+
* await client.users.aggregators.delete(1);
|
|
936
1453
|
*/
|
|
937
|
-
|
|
1454
|
+
delete(aggregatorId: number): Promise<void>;
|
|
938
1455
|
/**
|
|
939
|
-
*
|
|
940
|
-
*
|
|
941
|
-
* Transaction tokens are short-lived JWTs that pre-authorize the endpoint owner
|
|
942
|
-
* (recipient) to charge the current user (sender) for usage. These tokens are
|
|
943
|
-
* created via the accounting service and passed to the aggregator.
|
|
1456
|
+
* Set an aggregator as the default.
|
|
944
1457
|
*
|
|
945
|
-
*
|
|
1458
|
+
* Only one aggregator can be the default at a time. Setting a new default
|
|
1459
|
+
* automatically unsets the previous one.
|
|
946
1460
|
*
|
|
947
|
-
* @param
|
|
948
|
-
* @returns
|
|
1461
|
+
* @param aggregatorId - The aggregator ID to set as default
|
|
1462
|
+
* @returns The updated UserAggregator object with isDefault=true
|
|
949
1463
|
* @throws {AuthenticationError} If not authenticated
|
|
1464
|
+
* @throws {NotFoundError} If aggregator not found
|
|
950
1465
|
*
|
|
951
1466
|
* @example
|
|
952
|
-
*
|
|
953
|
-
*
|
|
954
|
-
* console.log(`Got ${Object.keys(response.tokens).length} tokens`);
|
|
955
|
-
* if (Object.keys(response.errors).length > 0) {
|
|
956
|
-
* console.log('Some tokens failed:', response.errors);
|
|
957
|
-
* }
|
|
1467
|
+
* const agg = await client.users.aggregators.setDefault(2);
|
|
1468
|
+
* console.log(`${agg.name} is now the default`);
|
|
958
1469
|
*/
|
|
959
|
-
|
|
960
|
-
}
|
|
961
|
-
/**
|
|
962
|
-
* Response from satellite token endpoint.
|
|
963
|
-
*/
|
|
964
|
-
interface SatelliteTokenResponse {
|
|
965
|
-
/** RS256-signed JWT for the target service */
|
|
966
|
-
targetToken: string;
|
|
967
|
-
/** Seconds until the token expires */
|
|
968
|
-
expiresIn: number;
|
|
969
|
-
}
|
|
970
|
-
/**
|
|
971
|
-
* Response from transaction tokens endpoint.
|
|
972
|
-
*/
|
|
973
|
-
interface TransactionTokensResponse {
|
|
974
|
-
/** Mapping of owner_username to transaction token */
|
|
975
|
-
tokens: Record<string, string>;
|
|
976
|
-
/** Mapping of owner_username to error message (for failed tokens) */
|
|
977
|
-
errors: Record<string, string>;
|
|
1470
|
+
setDefault(aggregatorId: number): Promise<UserAggregator>;
|
|
978
1471
|
}
|
|
979
1472
|
|
|
980
1473
|
/**
|
|
@@ -994,10 +1487,41 @@ interface TransactionTokensResponse {
|
|
|
994
1487
|
* @example
|
|
995
1488
|
* // Check if email is available
|
|
996
1489
|
* const available = await client.users.checkEmail('new@example.com');
|
|
1490
|
+
*
|
|
1491
|
+
* @example
|
|
1492
|
+
* // Manage aggregators
|
|
1493
|
+
* const aggregators = await client.users.aggregators.list();
|
|
1494
|
+
* const newAgg = await client.users.aggregators.create({
|
|
1495
|
+
* name: 'My Aggregator',
|
|
1496
|
+
* url: 'https://my-aggregator.example.com'
|
|
1497
|
+
* });
|
|
997
1498
|
*/
|
|
998
1499
|
declare class UsersResource {
|
|
999
1500
|
private readonly http;
|
|
1501
|
+
private _aggregators?;
|
|
1000
1502
|
constructor(http: HTTPClient);
|
|
1503
|
+
/**
|
|
1504
|
+
* Access aggregator management operations.
|
|
1505
|
+
*
|
|
1506
|
+
* @returns AggregatorsResource for managing user's aggregator configurations
|
|
1507
|
+
*
|
|
1508
|
+
* @example
|
|
1509
|
+
* // List aggregators
|
|
1510
|
+
* const aggregators = await client.users.aggregators.list();
|
|
1511
|
+
* for (const agg of aggregators) {
|
|
1512
|
+
* console.log(`${agg.name}: ${agg.url}`);
|
|
1513
|
+
* }
|
|
1514
|
+
*
|
|
1515
|
+
* // Create aggregator
|
|
1516
|
+
* const agg = await client.users.aggregators.create({
|
|
1517
|
+
* name: 'My Aggregator',
|
|
1518
|
+
* url: 'https://my-aggregator.example.com'
|
|
1519
|
+
* });
|
|
1520
|
+
*
|
|
1521
|
+
* // Set as default
|
|
1522
|
+
* await client.users.aggregators.setDefault(agg.id);
|
|
1523
|
+
*/
|
|
1524
|
+
get aggregators(): AggregatorsResource;
|
|
1001
1525
|
/**
|
|
1002
1526
|
* Update the current user's profile.
|
|
1003
1527
|
*
|
|
@@ -1039,6 +1563,38 @@ declare class UsersResource {
|
|
|
1039
1563
|
* }
|
|
1040
1564
|
*/
|
|
1041
1565
|
getAccountingCredentials(): Promise<AccountingCredentials>;
|
|
1566
|
+
/**
|
|
1567
|
+
* Send a heartbeat to indicate this SyftAI Space is alive.
|
|
1568
|
+
*
|
|
1569
|
+
* The heartbeat mechanism allows SyftAI Spaces to signal their availability
|
|
1570
|
+
* to SyftHub. This should be called periodically (before the TTL expires)
|
|
1571
|
+
* to maintain the "active" status.
|
|
1572
|
+
*
|
|
1573
|
+
* @param input - Heartbeat parameters
|
|
1574
|
+
* @param input.url - Full URL of this space (e.g., "https://myspace.example.com").
|
|
1575
|
+
* The server extracts the domain from this URL.
|
|
1576
|
+
* @param input.ttlSeconds - Time-to-live in seconds (1-3600). The server caps this
|
|
1577
|
+
* at a maximum of 600 seconds (10 minutes). Default is 300
|
|
1578
|
+
* seconds (5 minutes).
|
|
1579
|
+
* @returns HeartbeatResponse containing status, expiry time, domain, and effective TTL
|
|
1580
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1581
|
+
* @throws {ValidationError} If URL or TTL is invalid
|
|
1582
|
+
*
|
|
1583
|
+
* @example
|
|
1584
|
+
* // Send heartbeat with default TTL (300 seconds)
|
|
1585
|
+
* const response = await client.users.sendHeartbeat({
|
|
1586
|
+
* url: 'https://myspace.example.com'
|
|
1587
|
+
* });
|
|
1588
|
+
* console.log(`Next heartbeat before: ${response.expiresAt}`);
|
|
1589
|
+
*
|
|
1590
|
+
* @example
|
|
1591
|
+
* // Send heartbeat with custom TTL
|
|
1592
|
+
* const response = await client.users.sendHeartbeat({
|
|
1593
|
+
* url: 'https://myspace.example.com',
|
|
1594
|
+
* ttlSeconds: 600 // Maximum allowed
|
|
1595
|
+
* });
|
|
1596
|
+
*/
|
|
1597
|
+
sendHeartbeat(input: HeartbeatInput): Promise<HeartbeatResponse>;
|
|
1042
1598
|
}
|
|
1043
1599
|
|
|
1044
1600
|
/**
|
|
@@ -1178,12 +1734,11 @@ declare class MyEndpointsResource {
|
|
|
1178
1734
|
* Create a new endpoint.
|
|
1179
1735
|
*
|
|
1180
1736
|
* @param input - Endpoint creation details
|
|
1181
|
-
* @param organizationId - Optional organization ID (for org-owned endpoints)
|
|
1182
1737
|
* @returns The created Endpoint
|
|
1183
1738
|
* @throws {AuthenticationError} If not authenticated
|
|
1184
1739
|
* @throws {ValidationError} If input validation fails
|
|
1185
1740
|
*/
|
|
1186
|
-
create(input: EndpointCreateInput
|
|
1741
|
+
create(input: EndpointCreateInput): Promise<Endpoint>;
|
|
1187
1742
|
/**
|
|
1188
1743
|
* Get a specific endpoint by path.
|
|
1189
1744
|
*
|
|
@@ -1225,7 +1780,6 @@ declare class MyEndpointsResource {
|
|
|
1225
1780
|
* 3. Is ATOMIC: either all endpoints sync successfully, or none do
|
|
1226
1781
|
*
|
|
1227
1782
|
* Important Notes:
|
|
1228
|
-
* - Organization endpoints are NOT affected
|
|
1229
1783
|
* - Stars on existing endpoints will be lost (reset to 0)
|
|
1230
1784
|
* - Endpoint IDs will change (new IDs assigned)
|
|
1231
1785
|
* - Maximum 100 endpoints per sync request
|
|
@@ -1256,6 +1810,8 @@ declare class MyEndpointsResource {
|
|
|
1256
1810
|
* Options for browsing endpoints.
|
|
1257
1811
|
*/
|
|
1258
1812
|
interface BrowseOptions {
|
|
1813
|
+
/** Filter by endpoint type ('model' or 'data_source') */
|
|
1814
|
+
endpointType?: string;
|
|
1259
1815
|
/** Number of items per page (default: 20) */
|
|
1260
1816
|
pageSize?: number;
|
|
1261
1817
|
}
|
|
@@ -1263,11 +1819,22 @@ interface BrowseOptions {
|
|
|
1263
1819
|
* Options for trending endpoints.
|
|
1264
1820
|
*/
|
|
1265
1821
|
interface TrendingOptions {
|
|
1822
|
+
/** Filter by endpoint type ('model' or 'data_source') */
|
|
1823
|
+
endpointType?: string;
|
|
1266
1824
|
/** Minimum number of stars */
|
|
1267
1825
|
minStars?: number;
|
|
1268
1826
|
/** Number of items per page (default: 20) */
|
|
1269
1827
|
pageSize?: number;
|
|
1270
1828
|
}
|
|
1829
|
+
/**
|
|
1830
|
+
* Options for listing guest-accessible endpoints.
|
|
1831
|
+
*/
|
|
1832
|
+
interface GuestAccessibleOptions {
|
|
1833
|
+
/** Filter by endpoint type ('model' or 'data_source') */
|
|
1834
|
+
endpointType?: string;
|
|
1835
|
+
/** Number of items per page (default: 20) */
|
|
1836
|
+
pageSize?: number;
|
|
1837
|
+
}
|
|
1271
1838
|
/**
|
|
1272
1839
|
* Hub resource for browsing and discovering public endpoints.
|
|
1273
1840
|
*
|
|
@@ -1327,8 +1894,12 @@ declare class HubResource {
|
|
|
1327
1894
|
/**
|
|
1328
1895
|
* Browse all public endpoints.
|
|
1329
1896
|
*
|
|
1330
|
-
* @param options -
|
|
1897
|
+
* @param options - Filter and pagination options
|
|
1331
1898
|
* @returns PageIterator that lazily fetches endpoints
|
|
1899
|
+
*
|
|
1900
|
+
* @example
|
|
1901
|
+
* // Browse only model endpoints
|
|
1902
|
+
* const models = await client.hub.browse({ endpointType: 'model' }).firstPage();
|
|
1332
1903
|
*/
|
|
1333
1904
|
browse(options?: BrowseOptions): PageIterator<EndpointPublic>;
|
|
1334
1905
|
/**
|
|
@@ -1336,8 +1907,32 @@ declare class HubResource {
|
|
|
1336
1907
|
*
|
|
1337
1908
|
* @param options - Filter and pagination options
|
|
1338
1909
|
* @returns PageIterator that lazily fetches endpoints
|
|
1910
|
+
*
|
|
1911
|
+
* @example
|
|
1912
|
+
* // Get trending models only
|
|
1913
|
+
* const models = await client.hub.trending({ endpointType: 'model' }).firstPage();
|
|
1339
1914
|
*/
|
|
1340
1915
|
trending(options?: TrendingOptions): PageIterator<EndpointPublic>;
|
|
1916
|
+
/**
|
|
1917
|
+
* List endpoints accessible to unauthenticated (guest) users.
|
|
1918
|
+
*
|
|
1919
|
+
* Guest-accessible endpoints are public, active, and have no policies attached.
|
|
1920
|
+
* No authentication is required to call this method.
|
|
1921
|
+
*
|
|
1922
|
+
* @param options - Filter and pagination options
|
|
1923
|
+
* @returns PageIterator that lazily fetches guest-accessible endpoints
|
|
1924
|
+
*
|
|
1925
|
+
* @example
|
|
1926
|
+
* // List all guest-accessible endpoints
|
|
1927
|
+
* for await (const endpoint of client.hub.guestAccessible()) {
|
|
1928
|
+
* console.log(`${endpoint.ownerUsername}/${endpoint.slug}: ${endpoint.name}`);
|
|
1929
|
+
* }
|
|
1930
|
+
*
|
|
1931
|
+
* @example
|
|
1932
|
+
* // List only guest-accessible models
|
|
1933
|
+
* const models = await client.hub.guestAccessible({ endpointType: 'model' }).firstPage();
|
|
1934
|
+
*/
|
|
1935
|
+
guestAccessible(options?: GuestAccessibleOptions): PageIterator<EndpointPublic>;
|
|
1341
1936
|
/**
|
|
1342
1937
|
* Search for endpoints using semantic search.
|
|
1343
1938
|
*
|
|
@@ -1394,6 +1989,22 @@ declare class HubResource {
|
|
|
1394
1989
|
* @throws {NotFoundError} If endpoint not found
|
|
1395
1990
|
*/
|
|
1396
1991
|
unstar(path: string): Promise<void>;
|
|
1992
|
+
/**
|
|
1993
|
+
* Get the owner/slug paths of a collective's approved member endpoints,
|
|
1994
|
+
* optionally narrowed to a single shared-endpoint subset.
|
|
1995
|
+
*
|
|
1996
|
+
* Used by the chat resource to expand both `collective/<slug>` and
|
|
1997
|
+
* `collective/<slug>/<shared-slug>` data-source references into the
|
|
1998
|
+
* individual endpoint paths before building the aggregator request.
|
|
1999
|
+
*
|
|
2000
|
+
* @param slug - The collective slug (e.g. "genomics-research")
|
|
2001
|
+
* @param sharedSlug - Optional curated-subset slug. When provided, only the
|
|
2002
|
+
* intersection of the subset's configured endpoints with the collective's
|
|
2003
|
+
* currently approved members is returned. Omit for "all approved members".
|
|
2004
|
+
* @returns Array of "owner/slug" path strings
|
|
2005
|
+
* @throws {NotFoundError} If the collective (or shared endpoint) does not exist
|
|
2006
|
+
*/
|
|
2007
|
+
getCollectiveEndpointPaths(slug: string, sharedSlug?: string): Promise<string[]>;
|
|
1397
2008
|
/**
|
|
1398
2009
|
* Check if you have starred an endpoint.
|
|
1399
2010
|
*
|
|
@@ -1406,295 +2017,176 @@ declare class HubResource {
|
|
|
1406
2017
|
}
|
|
1407
2018
|
|
|
1408
2019
|
/**
|
|
1409
|
-
* Accounting Resource for SyftHub SDK
|
|
2020
|
+
* Accounting Resource for SyftHub SDK (MPP Wallet)
|
|
1410
2021
|
*
|
|
1411
|
-
* This module
|
|
1412
|
-
*
|
|
1413
|
-
*
|
|
2022
|
+
* This module provides wallet management operations via the SyftHub API.
|
|
2023
|
+
* Payments are handled through the MPP (Micropayment Protocol) 402 flow,
|
|
2024
|
+
* replacing the previous external accounting service with direct wallet support.
|
|
1414
2025
|
*
|
|
1415
2026
|
* @example
|
|
1416
2027
|
* ```typescript
|
|
1417
|
-
* //
|
|
1418
|
-
*
|
|
1419
|
-
*
|
|
1420
|
-
*
|
|
1421
|
-
*
|
|
1422
|
-
*
|
|
1423
|
-
*
|
|
1424
|
-
*
|
|
1425
|
-
*
|
|
1426
|
-
*
|
|
1427
|
-
*
|
|
1428
|
-
*
|
|
1429
|
-
*
|
|
1430
|
-
*
|
|
1431
|
-
*
|
|
1432
|
-
*
|
|
1433
|
-
*
|
|
1434
|
-
* });
|
|
1435
|
-
*
|
|
1436
|
-
* // Confirm the transaction
|
|
1437
|
-
* await accounting.confirmTransaction(tx.id);
|
|
2028
|
+
* // Initialize via client (after login)
|
|
2029
|
+
* await client.auth.login('alice', 'password');
|
|
2030
|
+
* await client.initAccounting();
|
|
2031
|
+
*
|
|
2032
|
+
* // Get wallet info
|
|
2033
|
+
* const wallet = await client.accounting.getWallet();
|
|
2034
|
+
* console.log(`Wallet address: ${wallet.address}`);
|
|
2035
|
+
*
|
|
2036
|
+
* // Get balance
|
|
2037
|
+
* const balance = await client.accounting.getBalance();
|
|
2038
|
+
* console.log(`Balance: ${balance.balance} ${balance.currency}`);
|
|
2039
|
+
*
|
|
2040
|
+
* // Get transactions
|
|
2041
|
+
* const transactions = await client.accounting.getTransactions();
|
|
2042
|
+
* for (const tx of transactions) {
|
|
2043
|
+
* console.log(`${tx.created_at}: ${tx.amount} from ${tx.sender_email}`);
|
|
2044
|
+
* }
|
|
1438
2045
|
* ```
|
|
1439
2046
|
*/
|
|
1440
2047
|
|
|
1441
2048
|
/**
|
|
1442
2049
|
* Options for creating an AccountingResource.
|
|
2050
|
+
*
|
|
2051
|
+
* @deprecated The old AccountingResourceOptions with external service credentials
|
|
2052
|
+
* are no longer needed. Use the HTTPClient-based constructor instead.
|
|
1443
2053
|
*/
|
|
1444
2054
|
interface AccountingResourceOptions {
|
|
1445
|
-
/**
|
|
2055
|
+
/** @deprecated No longer used - wallet API is accessed via SyftHub */
|
|
1446
2056
|
url: string;
|
|
1447
|
-
/**
|
|
2057
|
+
/** @deprecated No longer used */
|
|
1448
2058
|
email: string;
|
|
1449
|
-
/**
|
|
2059
|
+
/** @deprecated No longer used */
|
|
1450
2060
|
password: string;
|
|
1451
|
-
/**
|
|
2061
|
+
/** @deprecated No longer used */
|
|
1452
2062
|
timeout?: number;
|
|
1453
2063
|
}
|
|
1454
2064
|
/**
|
|
1455
2065
|
* Options for listing transactions.
|
|
2066
|
+
*
|
|
2067
|
+
* @deprecated Use getTransactions() which returns all transactions directly.
|
|
1456
2068
|
*/
|
|
1457
2069
|
interface TransactionsOptions {
|
|
1458
2070
|
/** Number of items per page (default: 20) */
|
|
1459
2071
|
pageSize?: number;
|
|
1460
2072
|
}
|
|
1461
2073
|
/**
|
|
1462
|
-
*
|
|
2074
|
+
* Wallet and payment operations via the SyftHub API.
|
|
1463
2075
|
*
|
|
1464
|
-
*
|
|
1465
|
-
*
|
|
1466
|
-
*
|
|
2076
|
+
* Manages MPP (Micropayment Protocol) wallets for users. Payments for
|
|
2077
|
+
* endpoint usage are handled automatically via the 402 payment flow
|
|
2078
|
+
* between the aggregator and SyftAI-Space instances.
|
|
1467
2079
|
*
|
|
1468
|
-
*
|
|
1469
|
-
*
|
|
1470
|
-
*
|
|
2080
|
+
* @example
|
|
2081
|
+
* ```typescript
|
|
2082
|
+
* // Get wallet info
|
|
2083
|
+
* const wallet = await client.accounting.getWallet();
|
|
2084
|
+
* if (!wallet.exists) {
|
|
2085
|
+
* // Create a new wallet
|
|
2086
|
+
* const result = await client.accounting.createWallet();
|
|
2087
|
+
* console.log(`Created wallet: ${result.address}`);
|
|
2088
|
+
* }
|
|
1471
2089
|
*
|
|
1472
|
-
*
|
|
1473
|
-
*
|
|
1474
|
-
*
|
|
1475
|
-
*
|
|
2090
|
+
* // Check balance
|
|
2091
|
+
* const balance = await client.accounting.getBalance();
|
|
2092
|
+
* console.log(`Balance: ${balance.balance} ${balance.currency}`);
|
|
2093
|
+
* ```
|
|
1476
2094
|
*/
|
|
1477
2095
|
declare class AccountingResource {
|
|
1478
|
-
private readonly
|
|
1479
|
-
|
|
1480
|
-
private readonly password;
|
|
1481
|
-
private readonly timeout;
|
|
1482
|
-
private readonly authHeader;
|
|
1483
|
-
constructor(options: AccountingResourceOptions);
|
|
1484
|
-
/**
|
|
1485
|
-
* Make an authenticated request to the accounting service.
|
|
1486
|
-
*/
|
|
1487
|
-
private request;
|
|
1488
|
-
/**
|
|
1489
|
-
* Make a request using Bearer token auth (for delegated transactions).
|
|
1490
|
-
*/
|
|
1491
|
-
private requestWithToken;
|
|
1492
|
-
/**
|
|
1493
|
-
* Get the current user's account information including balance.
|
|
1494
|
-
*
|
|
1495
|
-
* @returns AccountingUser with id, email, balance, and organization
|
|
1496
|
-
* @throws {AuthenticationError} If authentication fails
|
|
1497
|
-
* @throws {APIError} On other errors
|
|
1498
|
-
*
|
|
1499
|
-
* @example
|
|
1500
|
-
* ```typescript
|
|
1501
|
-
* const user = await accounting.getUser();
|
|
1502
|
-
* console.log(`Balance: ${user.balance}`);
|
|
1503
|
-
* console.log(`Organization: ${user.organization}`);
|
|
1504
|
-
* ```
|
|
1505
|
-
*/
|
|
1506
|
-
getUser(): Promise<AccountingUser>;
|
|
1507
|
-
/**
|
|
1508
|
-
* Update the user's password.
|
|
1509
|
-
*
|
|
1510
|
-
* @param currentPassword - Current password for verification
|
|
1511
|
-
* @param newPassword - New password to set
|
|
1512
|
-
* @throws {AuthenticationError} If current password is wrong
|
|
1513
|
-
* @throws {ValidationError} If new password doesn't meet requirements
|
|
1514
|
-
*
|
|
1515
|
-
* @example
|
|
1516
|
-
* ```typescript
|
|
1517
|
-
* await accounting.updatePassword('old_secret', 'new_secret');
|
|
1518
|
-
* ```
|
|
1519
|
-
*/
|
|
1520
|
-
updatePassword(currentPassword: string, newPassword: string): Promise<void>;
|
|
1521
|
-
/**
|
|
1522
|
-
* Update the user's organization.
|
|
1523
|
-
*
|
|
1524
|
-
* @param organization - New organization name
|
|
1525
|
-
* @throws {AuthenticationError} If authentication fails
|
|
1526
|
-
*
|
|
1527
|
-
* @example
|
|
1528
|
-
* ```typescript
|
|
1529
|
-
* await accounting.updateOrganization('OpenMined');
|
|
1530
|
-
* ```
|
|
1531
|
-
*/
|
|
1532
|
-
updateOrganization(organization: string): Promise<void>;
|
|
2096
|
+
private readonly http;
|
|
2097
|
+
constructor(http: HTTPClient);
|
|
1533
2098
|
/**
|
|
1534
|
-
*
|
|
2099
|
+
* Get the current user's wallet information.
|
|
1535
2100
|
*
|
|
1536
|
-
*
|
|
1537
|
-
*
|
|
1538
|
-
* @param options - Pagination options
|
|
1539
|
-
* @returns PageIterator that yields Transaction objects
|
|
2101
|
+
* @returns WalletInfo with address and existence status
|
|
2102
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1540
2103
|
*
|
|
1541
2104
|
* @example
|
|
1542
2105
|
* ```typescript
|
|
1543
|
-
*
|
|
1544
|
-
*
|
|
1545
|
-
* console.log(
|
|
2106
|
+
* const wallet = await client.accounting.getWallet();
|
|
2107
|
+
* if (wallet.exists) {
|
|
2108
|
+
* console.log(`Wallet address: ${wallet.address}`);
|
|
2109
|
+
* } else {
|
|
2110
|
+
* console.log('No wallet configured');
|
|
1546
2111
|
* }
|
|
1547
|
-
*
|
|
1548
|
-
* // Get first page only
|
|
1549
|
-
* const firstPage = await accounting.getTransactions().firstPage();
|
|
1550
|
-
*
|
|
1551
|
-
* // Get all transactions
|
|
1552
|
-
* const allTxs = await accounting.getTransactions().all();
|
|
1553
|
-
* ```
|
|
1554
|
-
*/
|
|
1555
|
-
getTransactions(options?: TransactionsOptions): PageIterator<Transaction>;
|
|
1556
|
-
/**
|
|
1557
|
-
* Get a specific transaction by ID.
|
|
1558
|
-
*
|
|
1559
|
-
* @param transactionId - The transaction ID
|
|
1560
|
-
* @returns Transaction object
|
|
1561
|
-
* @throws {NotFoundError} If transaction not found
|
|
1562
|
-
*
|
|
1563
|
-
* @example
|
|
1564
|
-
* ```typescript
|
|
1565
|
-
* const tx = await accounting.getTransaction('tx_123');
|
|
1566
|
-
* console.log(`Status: ${tx.status}`);
|
|
1567
|
-
* ```
|
|
1568
|
-
*/
|
|
1569
|
-
getTransaction(transactionId: string): Promise<Transaction>;
|
|
1570
|
-
/**
|
|
1571
|
-
* Create a new transaction (direct transfer).
|
|
1572
|
-
*
|
|
1573
|
-
* Creates a PENDING transaction that must be confirmed or cancelled.
|
|
1574
|
-
* The transaction is created by the sender (current user).
|
|
1575
|
-
*
|
|
1576
|
-
* @param input - Transaction details
|
|
1577
|
-
* @returns Transaction in PENDING status
|
|
1578
|
-
* @throws {ValidationError} If amount <= 0 or insufficient balance
|
|
1579
|
-
*
|
|
1580
|
-
* @example
|
|
1581
|
-
* ```typescript
|
|
1582
|
-
* const tx = await accounting.createTransaction({
|
|
1583
|
-
* recipientEmail: 'bob@example.com',
|
|
1584
|
-
* amount: 10.0,
|
|
1585
|
-
* appName: 'syftai-space',
|
|
1586
|
-
* appEpPath: 'alice/my-model'
|
|
1587
|
-
* });
|
|
1588
|
-
* console.log(`Created transaction ${tx.id}: ${tx.status}`);
|
|
1589
|
-
*
|
|
1590
|
-
* // Later, confirm or cancel
|
|
1591
|
-
* await accounting.confirmTransaction(tx.id);
|
|
1592
2112
|
* ```
|
|
1593
2113
|
*/
|
|
1594
|
-
|
|
2114
|
+
getWallet(): Promise<WalletInfo>;
|
|
1595
2115
|
/**
|
|
1596
|
-
*
|
|
1597
|
-
*
|
|
1598
|
-
* Confirms the transaction, transferring funds from sender to recipient.
|
|
1599
|
-
* Can be called by either the sender or recipient.
|
|
2116
|
+
* Get the current user's wallet balance and recent transactions.
|
|
1600
2117
|
*
|
|
1601
|
-
* @
|
|
1602
|
-
* @
|
|
1603
|
-
* @throws {NotFoundError} If transaction not found
|
|
1604
|
-
* @throws {ValidationError} If transaction is not in PENDING status
|
|
2118
|
+
* @returns WalletBalance with balance, currency, and recent transactions
|
|
2119
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1605
2120
|
*
|
|
1606
2121
|
* @example
|
|
1607
2122
|
* ```typescript
|
|
1608
|
-
* const
|
|
1609
|
-
* console.log(`
|
|
2123
|
+
* const balance = await client.accounting.getBalance();
|
|
2124
|
+
* console.log(`Balance: ${balance.balance} ${balance.currency}`);
|
|
2125
|
+
* console.log(`Wallet configured: ${balance.wallet_configured}`);
|
|
1610
2126
|
* ```
|
|
1611
2127
|
*/
|
|
1612
|
-
|
|
2128
|
+
getBalance(): Promise<WalletBalance>;
|
|
1613
2129
|
/**
|
|
1614
|
-
*
|
|
1615
|
-
*
|
|
1616
|
-
* Cancels the transaction without transferring funds.
|
|
1617
|
-
* Can be called by either the sender or recipient.
|
|
2130
|
+
* Get the current user's wallet transactions.
|
|
1618
2131
|
*
|
|
1619
|
-
* @
|
|
1620
|
-
* @
|
|
1621
|
-
* @throws {NotFoundError} If transaction not found
|
|
1622
|
-
* @throws {ValidationError} If transaction is not in PENDING status
|
|
2132
|
+
* @returns Array of WalletTransaction objects
|
|
2133
|
+
* @throws {AuthenticationError} If not authenticated
|
|
1623
2134
|
*
|
|
1624
2135
|
* @example
|
|
1625
2136
|
* ```typescript
|
|
1626
|
-
* const
|
|
1627
|
-
*
|
|
2137
|
+
* const transactions = await client.accounting.getTransactions();
|
|
2138
|
+
* for (const tx of transactions) {
|
|
2139
|
+
* console.log(`${tx.created_at}: ${tx.amount} ${tx.status}`);
|
|
2140
|
+
* }
|
|
1628
2141
|
* ```
|
|
1629
2142
|
*/
|
|
1630
|
-
|
|
2143
|
+
getTransactions(): Promise<WalletTransaction[]>;
|
|
1631
2144
|
/**
|
|
1632
|
-
* Create a
|
|
2145
|
+
* Create a new wallet for the current user.
|
|
1633
2146
|
*
|
|
1634
|
-
*
|
|
1635
|
-
*
|
|
1636
|
-
* is short-lived (typically ~5 minutes).
|
|
2147
|
+
* Generates a new wallet with a fresh keypair. The wallet address
|
|
2148
|
+
* is returned and stored on the server.
|
|
1637
2149
|
*
|
|
1638
|
-
*
|
|
1639
|
-
*
|
|
1640
|
-
*
|
|
1641
|
-
* @param recipientEmail - Email of the authorized recipient
|
|
1642
|
-
* @returns JWT token string to share with recipient
|
|
2150
|
+
* @returns Object with the new wallet address
|
|
2151
|
+
* @throws {AuthenticationError} If not authenticated
|
|
2152
|
+
* @throws {ValidationError} If user already has a wallet
|
|
1643
2153
|
*
|
|
1644
2154
|
* @example
|
|
1645
2155
|
* ```typescript
|
|
1646
|
-
*
|
|
1647
|
-
*
|
|
1648
|
-
*
|
|
1649
|
-
* // Share token with recipient out-of-band
|
|
1650
|
-
* // Recipient uses token to create delegated transaction
|
|
2156
|
+
* const result = await client.accounting.createWallet();
|
|
2157
|
+
* console.log(`New wallet address: ${result.address}`);
|
|
1651
2158
|
* ```
|
|
1652
2159
|
*/
|
|
1653
|
-
|
|
2160
|
+
createWallet(): Promise<{
|
|
2161
|
+
address: string;
|
|
2162
|
+
}>;
|
|
1654
2163
|
/**
|
|
1655
|
-
*
|
|
1656
|
-
*
|
|
1657
|
-
* Creates a transaction on behalf of the sender using their token.
|
|
1658
|
-
* This is typically used by services to charge users for usage.
|
|
2164
|
+
* Import an existing wallet using a private key.
|
|
1659
2165
|
*
|
|
1660
|
-
*
|
|
1661
|
-
*
|
|
1662
|
-
* @
|
|
1663
|
-
* @
|
|
1664
|
-
* @param token - JWT token from sender's createTransactionToken()
|
|
1665
|
-
* @returns Transaction in PENDING status (createdBy=RECIPIENT)
|
|
1666
|
-
* @throws {AuthenticationError} If token is invalid or expired
|
|
1667
|
-
* @throws {ValidationError} If amount <= 0
|
|
2166
|
+
* @param privateKey - The private key to import
|
|
2167
|
+
* @returns Object with the imported wallet address
|
|
2168
|
+
* @throws {AuthenticationError} If not authenticated
|
|
2169
|
+
* @throws {ValidationError} If the private key is invalid
|
|
1668
2170
|
*
|
|
1669
2171
|
* @example
|
|
1670
2172
|
* ```typescript
|
|
1671
|
-
*
|
|
1672
|
-
*
|
|
1673
|
-
* 'alice@example.com',
|
|
1674
|
-
* 5.0,
|
|
1675
|
-
* aliceToken
|
|
1676
|
-
* );
|
|
1677
|
-
*
|
|
1678
|
-
* // Recipient confirms the transaction
|
|
1679
|
-
* await accounting.confirmTransaction(tx.id);
|
|
2173
|
+
* const result = await client.accounting.importWallet('0x...');
|
|
2174
|
+
* console.log(`Imported wallet address: ${result.address}`);
|
|
1680
2175
|
* ```
|
|
1681
2176
|
*/
|
|
1682
|
-
|
|
2177
|
+
importWallet(privateKey: string): Promise<{
|
|
2178
|
+
address: string;
|
|
2179
|
+
}>;
|
|
1683
2180
|
}
|
|
1684
2181
|
/**
|
|
1685
2182
|
* Create a new AccountingResource instance.
|
|
1686
2183
|
*
|
|
1687
|
-
* @
|
|
1688
|
-
*
|
|
2184
|
+
* @deprecated Use the SyftHubClient's built-in accounting resource instead.
|
|
2185
|
+
* The wallet API is now accessed through the SyftHub HTTP client, not
|
|
2186
|
+
* a separate external service.
|
|
1689
2187
|
*
|
|
1690
|
-
* @
|
|
1691
|
-
*
|
|
1692
|
-
* const accounting = createAccountingResource({
|
|
1693
|
-
* url: process.env.ACCOUNTING_URL!,
|
|
1694
|
-
* email: process.env.ACCOUNTING_EMAIL!,
|
|
1695
|
-
* password: process.env.ACCOUNTING_PASSWORD!
|
|
1696
|
-
* });
|
|
1697
|
-
* ```
|
|
2188
|
+
* @param options - Configuration options (ignored, kept for backward compatibility)
|
|
2189
|
+
* @returns AccountingResource instance
|
|
1698
2190
|
*/
|
|
1699
2191
|
declare function createAccountingResource(options: AccountingResourceOptions): AccountingResource;
|
|
1700
2192
|
|
|
@@ -1823,6 +2315,225 @@ declare class AccountingServiceUnavailableError extends SyftHubError {
|
|
|
1823
2315
|
constructor(message?: string, detail?: unknown | undefined);
|
|
1824
2316
|
}
|
|
1825
2317
|
|
|
2318
|
+
/**
|
|
2319
|
+
* TypeScript type definitions for agent events, session state, and message payloads.
|
|
2320
|
+
*/
|
|
2321
|
+
/**
|
|
2322
|
+
* Agent session state machine states.
|
|
2323
|
+
*/
|
|
2324
|
+
type AgentSessionState = 'idle' | 'connecting' | 'running' | 'awaiting_input' | 'completed' | 'failed' | 'cancelled' | 'error';
|
|
2325
|
+
interface ThinkingEvent {
|
|
2326
|
+
type: 'agent.thinking';
|
|
2327
|
+
payload: {
|
|
2328
|
+
content: string;
|
|
2329
|
+
is_streaming: boolean;
|
|
2330
|
+
};
|
|
2331
|
+
}
|
|
2332
|
+
interface ToolCallEvent {
|
|
2333
|
+
type: 'agent.tool_call';
|
|
2334
|
+
payload: {
|
|
2335
|
+
tool_call_id: string;
|
|
2336
|
+
tool_name: string;
|
|
2337
|
+
arguments: Record<string, unknown>;
|
|
2338
|
+
requires_confirmation: boolean;
|
|
2339
|
+
description?: string;
|
|
2340
|
+
};
|
|
2341
|
+
}
|
|
2342
|
+
interface ToolResultEvent {
|
|
2343
|
+
type: 'agent.tool_result';
|
|
2344
|
+
payload: {
|
|
2345
|
+
tool_call_id: string;
|
|
2346
|
+
status: 'success' | 'error';
|
|
2347
|
+
result?: unknown;
|
|
2348
|
+
error?: string;
|
|
2349
|
+
duration_ms?: number;
|
|
2350
|
+
};
|
|
2351
|
+
}
|
|
2352
|
+
interface AgentMessageEvent {
|
|
2353
|
+
type: 'agent.message';
|
|
2354
|
+
payload: {
|
|
2355
|
+
content: string;
|
|
2356
|
+
is_complete: boolean;
|
|
2357
|
+
};
|
|
2358
|
+
}
|
|
2359
|
+
interface TokenEvent {
|
|
2360
|
+
type: 'agent.token';
|
|
2361
|
+
payload: {
|
|
2362
|
+
token: string;
|
|
2363
|
+
};
|
|
2364
|
+
}
|
|
2365
|
+
interface StatusEvent {
|
|
2366
|
+
type: 'agent.status';
|
|
2367
|
+
payload: {
|
|
2368
|
+
status: string;
|
|
2369
|
+
detail: string;
|
|
2370
|
+
progress?: number;
|
|
2371
|
+
};
|
|
2372
|
+
}
|
|
2373
|
+
interface RequestInputEvent {
|
|
2374
|
+
type: 'agent.request_input';
|
|
2375
|
+
payload: {
|
|
2376
|
+
prompt: string;
|
|
2377
|
+
};
|
|
2378
|
+
}
|
|
2379
|
+
interface SessionCreatedEvent {
|
|
2380
|
+
type: 'session.created';
|
|
2381
|
+
payload: {
|
|
2382
|
+
session_id: string;
|
|
2383
|
+
};
|
|
2384
|
+
}
|
|
2385
|
+
interface SessionCompletedEvent {
|
|
2386
|
+
type: 'session.completed';
|
|
2387
|
+
payload: {
|
|
2388
|
+
session_id: string;
|
|
2389
|
+
};
|
|
2390
|
+
}
|
|
2391
|
+
interface SessionFailedEvent {
|
|
2392
|
+
type: 'session.failed';
|
|
2393
|
+
payload: {
|
|
2394
|
+
error: string;
|
|
2395
|
+
reason: string;
|
|
2396
|
+
};
|
|
2397
|
+
}
|
|
2398
|
+
interface AgentErrorEvent {
|
|
2399
|
+
type: 'agent.error';
|
|
2400
|
+
payload: {
|
|
2401
|
+
code: string;
|
|
2402
|
+
message: string;
|
|
2403
|
+
recoverable: boolean;
|
|
2404
|
+
};
|
|
2405
|
+
}
|
|
2406
|
+
/**
|
|
2407
|
+
* Union type of all possible agent events.
|
|
2408
|
+
*/
|
|
2409
|
+
type AgentEvent = ThinkingEvent | ToolCallEvent | ToolResultEvent | AgentMessageEvent | TokenEvent | StatusEvent | RequestInputEvent | SessionCreatedEvent | SessionCompletedEvent | SessionFailedEvent | AgentErrorEvent;
|
|
2410
|
+
/**
|
|
2411
|
+
* Configuration for agent sessions.
|
|
2412
|
+
*/
|
|
2413
|
+
interface AgentConfig {
|
|
2414
|
+
maxTokens?: number;
|
|
2415
|
+
temperature?: number;
|
|
2416
|
+
systemPrompt?: string;
|
|
2417
|
+
metadata?: Record<string, unknown>;
|
|
2418
|
+
}
|
|
2419
|
+
/**
|
|
2420
|
+
* Message in conversation history.
|
|
2421
|
+
*/
|
|
2422
|
+
interface AgentHistoryMessage {
|
|
2423
|
+
role: string;
|
|
2424
|
+
content: string;
|
|
2425
|
+
}
|
|
2426
|
+
/**
|
|
2427
|
+
* Options for starting an agent session.
|
|
2428
|
+
*/
|
|
2429
|
+
interface AgentSessionOptions {
|
|
2430
|
+
/** The initial prompt */
|
|
2431
|
+
prompt: string;
|
|
2432
|
+
/** Endpoint in "owner/slug" format or { owner, slug } object */
|
|
2433
|
+
endpoint: string | {
|
|
2434
|
+
owner: string;
|
|
2435
|
+
slug: string;
|
|
2436
|
+
};
|
|
2437
|
+
/** Optional agent configuration */
|
|
2438
|
+
config?: AgentConfig;
|
|
2439
|
+
/** Optional conversation history */
|
|
2440
|
+
messages?: AgentHistoryMessage[];
|
|
2441
|
+
/** Optional AbortSignal for cancellation */
|
|
2442
|
+
signal?: AbortSignal;
|
|
2443
|
+
}
|
|
2444
|
+
|
|
2445
|
+
/**
|
|
2446
|
+
* Agent resource for bidirectional agent sessions via WebSocket.
|
|
2447
|
+
*
|
|
2448
|
+
* @example
|
|
2449
|
+
* const session = await client.agent.startSession({
|
|
2450
|
+
* prompt: 'Help me refactor this code',
|
|
2451
|
+
* endpoint: 'alice/code-assistant',
|
|
2452
|
+
* });
|
|
2453
|
+
*
|
|
2454
|
+
* for await (const event of session.events()) {
|
|
2455
|
+
* switch (event.type) {
|
|
2456
|
+
* case 'agent.message':
|
|
2457
|
+
* console.log(event.payload.content);
|
|
2458
|
+
* break;
|
|
2459
|
+
* case 'agent.tool_call':
|
|
2460
|
+
* if (event.payload.requires_confirmation) {
|
|
2461
|
+
* await session.confirm(event.payload.tool_call_id);
|
|
2462
|
+
* }
|
|
2463
|
+
* break;
|
|
2464
|
+
* }
|
|
2465
|
+
* }
|
|
2466
|
+
*/
|
|
2467
|
+
|
|
2468
|
+
/**
|
|
2469
|
+
* Error thrown during agent session operations.
|
|
2470
|
+
*/
|
|
2471
|
+
declare class AgentSessionError extends SyftHubError {
|
|
2472
|
+
readonly code?: string | undefined;
|
|
2473
|
+
constructor(message: string, code?: string | undefined);
|
|
2474
|
+
}
|
|
2475
|
+
/**
|
|
2476
|
+
* AgentResource manages agent session lifecycle.
|
|
2477
|
+
*/
|
|
2478
|
+
declare class AgentResource {
|
|
2479
|
+
private readonly auth;
|
|
2480
|
+
private readonly aggregatorUrl;
|
|
2481
|
+
constructor(auth: AuthResource, aggregatorUrl: string);
|
|
2482
|
+
/**
|
|
2483
|
+
* Start a new agent session.
|
|
2484
|
+
*
|
|
2485
|
+
* @param options - Session options including prompt, endpoint, and config
|
|
2486
|
+
* @returns An AgentSessionClient for interacting with the session
|
|
2487
|
+
*/
|
|
2488
|
+
startSession(options: AgentSessionOptions): Promise<AgentSessionClient>;
|
|
2489
|
+
}
|
|
2490
|
+
/**
|
|
2491
|
+
* Client for an active agent session.
|
|
2492
|
+
* Provides both async iterable and callback-based APIs for receiving events.
|
|
2493
|
+
*/
|
|
2494
|
+
declare class AgentSessionClient {
|
|
2495
|
+
private readonly ws;
|
|
2496
|
+
readonly sessionId: string;
|
|
2497
|
+
private _state;
|
|
2498
|
+
private _sequenceCounter;
|
|
2499
|
+
private _messageQueue;
|
|
2500
|
+
private _messageResolvers;
|
|
2501
|
+
private _closed;
|
|
2502
|
+
constructor(ws: WebSocket, sessionId: string);
|
|
2503
|
+
/** Current session state */
|
|
2504
|
+
get state(): AgentSessionState;
|
|
2505
|
+
/**
|
|
2506
|
+
* Async generator yielding agent events.
|
|
2507
|
+
*
|
|
2508
|
+
* @example
|
|
2509
|
+
* for await (const event of session.events()) {
|
|
2510
|
+
* console.log(event.type, event.payload);
|
|
2511
|
+
* }
|
|
2512
|
+
*/
|
|
2513
|
+
events(): AsyncGenerator<AgentEvent>;
|
|
2514
|
+
/**
|
|
2515
|
+
* Register an event handler.
|
|
2516
|
+
*
|
|
2517
|
+
* @param eventType - The event type to listen for, or '*' for all events
|
|
2518
|
+
* @param handler - Callback function
|
|
2519
|
+
*/
|
|
2520
|
+
on(eventType: string, handler: (event: AgentEvent) => void): void;
|
|
2521
|
+
/** Send a user message to the agent */
|
|
2522
|
+
sendMessage(content: string): void;
|
|
2523
|
+
/** Confirm a tool call */
|
|
2524
|
+
confirm(toolCallId: string): void;
|
|
2525
|
+
/** Deny a tool call */
|
|
2526
|
+
deny(toolCallId: string, reason?: string): void;
|
|
2527
|
+
/** Cancel the session */
|
|
2528
|
+
cancel(): void;
|
|
2529
|
+
/** Close the session and WebSocket */
|
|
2530
|
+
close(): void;
|
|
2531
|
+
private _send;
|
|
2532
|
+
private _handleMessage;
|
|
2533
|
+
private _handleClose;
|
|
2534
|
+
private _nextEvent;
|
|
2535
|
+
}
|
|
2536
|
+
|
|
1826
2537
|
/**
|
|
1827
2538
|
* Chat resource for RAG-augmented conversations via the Aggregator service.
|
|
1828
2539
|
*
|
|
@@ -1876,6 +2587,11 @@ declare class ChatResource {
|
|
|
1876
2587
|
private readonly auth;
|
|
1877
2588
|
private readonly aggregatorUrl;
|
|
1878
2589
|
constructor(hub: HubResource, auth: AuthResource, aggregatorUrl: string);
|
|
2590
|
+
/**
|
|
2591
|
+
* Check if an endpoint type matches the expected type.
|
|
2592
|
+
* A model_data_source endpoint matches both 'model' and 'data_source'.
|
|
2593
|
+
*/
|
|
2594
|
+
private static typeMatches;
|
|
1879
2595
|
/**
|
|
1880
2596
|
* Convert any endpoint format to EndpointRef with URL and owner info.
|
|
1881
2597
|
* The ownerUsername is critical for satellite token authentication.
|
|
@@ -1889,16 +2605,16 @@ declare class ChatResource {
|
|
|
1889
2605
|
/**
|
|
1890
2606
|
* Get satellite tokens for all unique endpoint owners.
|
|
1891
2607
|
* Returns a map of owner username to satellite token.
|
|
2608
|
+
*
|
|
2609
|
+
* @param owners - Array of unique owner usernames
|
|
2610
|
+
* @param guestMode - If true, fetch guest tokens (no auth required)
|
|
1892
2611
|
*/
|
|
1893
2612
|
private getSatelliteTokensForOwners;
|
|
1894
2613
|
/**
|
|
1895
|
-
* Get
|
|
1896
|
-
* Returns
|
|
1897
|
-
*
|
|
1898
|
-
* Transaction tokens are used for billing - they authorize the endpoint
|
|
1899
|
-
* owner to charge the current user for usage.
|
|
2614
|
+
* Get the user's Hub access token for MPP payment flow.
|
|
2615
|
+
* Returns null if in guest mode or not authenticated.
|
|
1900
2616
|
*/
|
|
1901
|
-
private
|
|
2617
|
+
private getUserToken;
|
|
1902
2618
|
/**
|
|
1903
2619
|
* Type guard for EndpointRef.
|
|
1904
2620
|
*/
|
|
@@ -1907,10 +2623,42 @@ declare class ChatResource {
|
|
|
1907
2623
|
* Type guard for EndpointPublic.
|
|
1908
2624
|
*/
|
|
1909
2625
|
private isEndpointPublic;
|
|
2626
|
+
private static readonly COLLECTIVE_PREFIX;
|
|
2627
|
+
private static readonly TUNNELING_PREFIX;
|
|
2628
|
+
/**
|
|
2629
|
+
* Expand any `collective/<slug>` (or `collective/<slug>/<shared-slug>`)
|
|
2630
|
+
* entries in the data-sources list into the individual `owner/slug` paths
|
|
2631
|
+
* of the collective's approved members.
|
|
2632
|
+
*
|
|
2633
|
+
* Path forms recognised:
|
|
2634
|
+
* - `collective/<slug>` → every approved member (backward-compatible)
|
|
2635
|
+
* - `collective/<slug>/all` → equivalent alias of the above
|
|
2636
|
+
* - `collective/<slug>/<shared-slug>` → the named subset, intersected with
|
|
2637
|
+
* the collective's currently approved members
|
|
2638
|
+
*
|
|
2639
|
+
* Non-collective entries pass through unchanged. String paths are
|
|
2640
|
+
* deduplicated so a regular endpoint that also belongs to a selected
|
|
2641
|
+
* collective is not queried twice.
|
|
2642
|
+
*/
|
|
2643
|
+
private expandCollectivePaths;
|
|
2644
|
+
/**
|
|
2645
|
+
* Check if any endpoints use tunneling URLs and extract target usernames.
|
|
2646
|
+
*/
|
|
2647
|
+
private collectTunnelingUsernames;
|
|
2648
|
+
/**
|
|
2649
|
+
* Shared request preparation for complete() and stream().
|
|
2650
|
+
* Resolves endpoints, fetches tokens, and builds the aggregator request body.
|
|
2651
|
+
* Returns the request body and the resolved aggregator URL.
|
|
2652
|
+
*/
|
|
2653
|
+
private prepareRequest;
|
|
2654
|
+
/**
|
|
2655
|
+
* Parse an error response from the aggregator into an AggregatorError.
|
|
2656
|
+
*/
|
|
2657
|
+
private handleAggregatorErrorResponse;
|
|
1910
2658
|
/**
|
|
1911
2659
|
* Build the request body for the aggregator.
|
|
1912
2660
|
* Includes endpoint_tokens mapping for satellite token authentication.
|
|
1913
|
-
* Includes
|
|
2661
|
+
* Includes user_token for MPP payment callback authorization.
|
|
1914
2662
|
* User identity is derived from satellite tokens, not passed in request body.
|
|
1915
2663
|
*/
|
|
1916
2664
|
private buildRequestBody;
|
|
@@ -1941,7 +2689,7 @@ declare class ChatResource {
|
|
|
1941
2689
|
* This method automatically:
|
|
1942
2690
|
* 1. Resolves endpoints and extracts owner information
|
|
1943
2691
|
* 2. Exchanges Hub tokens for satellite tokens (one per unique owner)
|
|
1944
|
-
* 3.
|
|
2692
|
+
* 3. Passes the user's Hub access token for MPP payment authorization
|
|
1945
2693
|
* 4. Sends tokens to the aggregator for forwarding to SyftAI-Space
|
|
1946
2694
|
*
|
|
1947
2695
|
* @param options - Chat completion options
|
|
@@ -1956,7 +2704,7 @@ declare class ChatResource {
|
|
|
1956
2704
|
* This method automatically:
|
|
1957
2705
|
* 1. Resolves endpoints and extracts owner information
|
|
1958
2706
|
* 2. Exchanges Hub tokens for satellite tokens (one per unique owner)
|
|
1959
|
-
* 3.
|
|
2707
|
+
* 3. Passes the user's Hub access token for MPP payment authorization
|
|
1960
2708
|
* 4. Sends tokens to the aggregator for forwarding to SyftAI-Space
|
|
1961
2709
|
*
|
|
1962
2710
|
* @param options - Chat completion options
|
|
@@ -1967,6 +2715,7 @@ declare class ChatResource {
|
|
|
1967
2715
|
* Parse an SSE event into a typed event object.
|
|
1968
2716
|
*/
|
|
1969
2717
|
private parseSSEEvent;
|
|
2718
|
+
private getAvailableEndpoints;
|
|
1970
2719
|
/**
|
|
1971
2720
|
* Get model endpoints that have connection URLs configured.
|
|
1972
2721
|
*
|
|
@@ -2087,6 +2836,13 @@ interface SyftHubClientOptions {
|
|
|
2087
2836
|
* Defaults to {baseUrl}/aggregator/api/v1
|
|
2088
2837
|
*/
|
|
2089
2838
|
aggregatorUrl?: string;
|
|
2839
|
+
/**
|
|
2840
|
+
* API token for authentication (alternative to username/password login).
|
|
2841
|
+
* If provided, the client will be authenticated immediately without needing to call login().
|
|
2842
|
+
* Falls back to SYFTHUB_API_TOKEN environment variable.
|
|
2843
|
+
* @example 'syft_pat_xxxxx...'
|
|
2844
|
+
*/
|
|
2845
|
+
apiToken?: string;
|
|
2090
2846
|
}
|
|
2091
2847
|
/**
|
|
2092
2848
|
* SyftHub SDK client for interacting with the SyftHub API.
|
|
@@ -2133,16 +2889,16 @@ interface SyftHubClientOptions {
|
|
|
2133
2889
|
*/
|
|
2134
2890
|
declare class SyftHubClient {
|
|
2135
2891
|
private readonly http;
|
|
2136
|
-
private readonly options;
|
|
2137
2892
|
private readonly aggregatorUrl;
|
|
2138
2893
|
private _auth?;
|
|
2139
2894
|
private _users?;
|
|
2140
2895
|
private _myEndpoints?;
|
|
2141
2896
|
private _hub?;
|
|
2142
2897
|
private _accounting?;
|
|
2143
|
-
private
|
|
2898
|
+
private _agent?;
|
|
2144
2899
|
private _chat?;
|
|
2145
2900
|
private _syftai?;
|
|
2901
|
+
private _apiTokens?;
|
|
2146
2902
|
/**
|
|
2147
2903
|
* Create a new SyftHub client.
|
|
2148
2904
|
*
|
|
@@ -2184,13 +2940,28 @@ declare class SyftHubClient {
|
|
|
2184
2940
|
*/
|
|
2185
2941
|
get hub(): HubResource;
|
|
2186
2942
|
/**
|
|
2187
|
-
*
|
|
2943
|
+
* Agent resource for bidirectional agent sessions via WebSocket.
|
|
2944
|
+
*
|
|
2945
|
+
* @example
|
|
2946
|
+
* const session = await client.agent.startSession({
|
|
2947
|
+
* prompt: 'Help me refactor this code',
|
|
2948
|
+
* endpoint: 'alice/code-assistant',
|
|
2949
|
+
* });
|
|
2950
|
+
*
|
|
2951
|
+
* for await (const event of session.events()) {
|
|
2952
|
+
* console.log(event.type, event.payload);
|
|
2953
|
+
* }
|
|
2954
|
+
*/
|
|
2955
|
+
get agent(): AgentResource;
|
|
2956
|
+
/**
|
|
2957
|
+
* Accounting resource for wallet and payment operations.
|
|
2188
2958
|
*
|
|
2189
|
-
*
|
|
2190
|
-
*
|
|
2959
|
+
* Provides access to MPP wallet management (balance, transactions,
|
|
2960
|
+
* wallet creation/import). Uses the same SyftHub JWT authentication
|
|
2961
|
+
* as other resources.
|
|
2191
2962
|
*
|
|
2192
|
-
*
|
|
2193
|
-
*
|
|
2963
|
+
* You must call `initAccounting()` after login to initialize this resource,
|
|
2964
|
+
* or access it directly if already initialized.
|
|
2194
2965
|
*
|
|
2195
2966
|
* @throws {AuthenticationError} If not initialized
|
|
2196
2967
|
*
|
|
@@ -2200,18 +2971,18 @@ declare class SyftHubClient {
|
|
|
2200
2971
|
* await client.initAccounting();
|
|
2201
2972
|
*
|
|
2202
2973
|
* // Now accounting is available
|
|
2203
|
-
* const
|
|
2974
|
+
* const wallet = await client.accounting.getWallet();
|
|
2975
|
+
* const balance = await client.accounting.getBalance();
|
|
2204
2976
|
*/
|
|
2205
2977
|
get accounting(): AccountingResource;
|
|
2206
2978
|
/**
|
|
2207
|
-
* Initialize accounting resource
|
|
2979
|
+
* Initialize the accounting (wallet) resource.
|
|
2208
2980
|
*
|
|
2209
|
-
*
|
|
2210
|
-
* and
|
|
2981
|
+
* The wallet API uses the same SyftHub authentication as other resources.
|
|
2982
|
+
* This method simply verifies authentication and creates the resource.
|
|
2211
2983
|
*
|
|
2212
2984
|
* @returns The initialized AccountingResource
|
|
2213
2985
|
* @throws {AuthenticationError} If not authenticated
|
|
2214
|
-
* @throws {ConfigurationError} If user has no accounting service configured
|
|
2215
2986
|
*
|
|
2216
2987
|
* @example
|
|
2217
2988
|
* // Login first, then initialize accounting
|
|
@@ -2219,13 +2990,10 @@ declare class SyftHubClient {
|
|
|
2219
2990
|
* await client.initAccounting();
|
|
2220
2991
|
*
|
|
2221
2992
|
* // Now accounting is available
|
|
2222
|
-
* const
|
|
2993
|
+
* const wallet = await client.accounting.getWallet();
|
|
2994
|
+
* const balance = await client.accounting.getBalance();
|
|
2223
2995
|
*/
|
|
2224
2996
|
initAccounting(): Promise<AccountingResource>;
|
|
2225
|
-
/**
|
|
2226
|
-
* Internal method to perform accounting initialization.
|
|
2227
|
-
*/
|
|
2228
|
-
private _doInitAccounting;
|
|
2229
2997
|
/**
|
|
2230
2998
|
* Chat resource for RAG-augmented conversations via the Aggregator.
|
|
2231
2999
|
*
|
|
@@ -2278,6 +3046,33 @@ declare class SyftHubClient {
|
|
|
2278
3046
|
* });
|
|
2279
3047
|
*/
|
|
2280
3048
|
get syftai(): SyftAIResource;
|
|
3049
|
+
/**
|
|
3050
|
+
* API Tokens resource for managing personal access tokens.
|
|
3051
|
+
*
|
|
3052
|
+
* API tokens provide an alternative to username/password authentication.
|
|
3053
|
+
* They are ideal for CI/CD pipelines, scripts, and programmatic access.
|
|
3054
|
+
*
|
|
3055
|
+
* @example
|
|
3056
|
+
* // Create a new token
|
|
3057
|
+
* const result = await client.apiTokens.create({
|
|
3058
|
+
* name: 'CI/CD Pipeline',
|
|
3059
|
+
* scopes: ['write'],
|
|
3060
|
+
* });
|
|
3061
|
+
* console.log('Save this token:', result.token);
|
|
3062
|
+
*
|
|
3063
|
+
* // List all tokens
|
|
3064
|
+
* const { tokens } = await client.apiTokens.list();
|
|
3065
|
+
*
|
|
3066
|
+
* // Revoke a token
|
|
3067
|
+
* await client.apiTokens.revoke(tokenId);
|
|
3068
|
+
*/
|
|
3069
|
+
get apiTokens(): APITokensResource;
|
|
3070
|
+
/**
|
|
3071
|
+
* Check if the client is using API token authentication.
|
|
3072
|
+
*
|
|
3073
|
+
* @returns True if authenticated with an API token (vs JWT)
|
|
3074
|
+
*/
|
|
3075
|
+
get isUsingApiToken(): boolean;
|
|
2281
3076
|
/**
|
|
2282
3077
|
* Get current authentication tokens.
|
|
2283
3078
|
*
|
|
@@ -2313,7 +3108,7 @@ declare class SyftHubClient {
|
|
|
2313
3108
|
*/
|
|
2314
3109
|
get isAuthenticated(): boolean;
|
|
2315
3110
|
/**
|
|
2316
|
-
* Check if accounting has been initialized.
|
|
3111
|
+
* Check if the accounting (wallet) resource has been initialized.
|
|
2317
3112
|
*
|
|
2318
3113
|
* Use this to check if accounting is available before accessing
|
|
2319
3114
|
* the `accounting` property, which will throw if not initialized.
|
|
@@ -2322,7 +3117,7 @@ declare class SyftHubClient {
|
|
|
2322
3117
|
*
|
|
2323
3118
|
* @example
|
|
2324
3119
|
* if (client.isAccountingInitialized) {
|
|
2325
|
-
* const
|
|
3120
|
+
* const wallet = await client.accounting.getWallet();
|
|
2326
3121
|
* }
|
|
2327
3122
|
*/
|
|
2328
3123
|
get isAccountingInitialized(): boolean;
|
|
@@ -2334,4 +3129,4 @@ declare class SyftHubClient {
|
|
|
2334
3129
|
close(): void;
|
|
2335
3130
|
}
|
|
2336
3131
|
|
|
2337
|
-
export { APIError, AccountingAccountExistsError, type AccountingCredentials, AccountingResource, type AccountingResourceOptions, AccountingServiceUnavailableError, type
|
|
3132
|
+
export { APIError, type APIToken, type APITokenCreateResponse, type APITokenListResponse, type APITokenScope, APITokensResource, AccountingAccountExistsError, type AccountingCredentials, AccountingResource, type AccountingResourceOptions, AccountingServiceUnavailableError, type AgentConfig, type AgentErrorEvent, type AgentEvent, type AgentHistoryMessage, type AgentMessageEvent, type RequestInputEvent as AgentRequestInputEvent, AgentResource, AgentSessionClient, type SessionCompletedEvent as AgentSessionCompletedEvent, type SessionCreatedEvent as AgentSessionCreatedEvent, AgentSessionError, type SessionFailedEvent as AgentSessionFailedEvent, type AgentSessionOptions, type AgentSessionState, type StatusEvent as AgentStatusEvent, type ThinkingEvent as AgentThinkingEvent, type TokenEvent as AgentTokenEvent, type ToolCallEvent as AgentToolCallEvent, type ToolResultEvent as AgentToolResultEvent, AggregatorError, AggregatorsResource, type AuthConfig, type AuthTokens, AuthenticationError, AuthorizationError, type BrowseOptions, type ChatMetadata, type ChatOptions, ChatResource, type ChatResponse, type ChatStreamEvent, ConfigurationError, type Connection, type CreateAPITokenInput, type Document, type DocumentSource, type DoneEvent, type Endpoint, type EndpointCreateInput, type EndpointPublic, type EndpointRef, EndpointResolutionError, EndpointType, type EndpointUpdateInput, type ErrorEvent, GenerationError, type GenerationStartEvent, type HeartbeatInput, type HeartbeatResponse, InvalidAccountingPasswordError, type ListEndpointsOptions, type Message, NetworkError, NotFoundError, type PageFetcher, PageIterator, type PasswordChangeInput, type PasswordResetConfirmInput, type PasswordResetRequestInput, type Policy, type QueryDataSourceOptions, type QueryModelOptions, type RegisterResult, type RetrievalCompleteEvent, RetrievalError, type RetrievalStartEvent, type SourceCompleteEvent, type SourceInfo, type SourceStatus, SyftAIResource, SyftHubClient, type SyftHubClientOptions, SyftHubError, type SyncEndpointsResponse, type TokenEvent$1 as TokenEvent, type TransactionTokensResponse, type TransactionsOptions, type TrendingOptions, type UpdateAPITokenInput, type User, type UserAggregator, type UserAggregatorCreateInput, type UserAggregatorUpdateInput, UserAlreadyExistsError, type UserRegisterInput, UserRole, type UserUpdateInput, ValidationError, type VerifyOTPInput, Visibility, type WalletBalance, type WalletInfo, type WalletTransaction, createAccountingResource, getEndpointPublicPath };
|