@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.d.cts 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
- * Get current authentication tokens.
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
- * Clear authentication tokens.
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 tokens.
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
- /** Visible to authenticated users within the organization */
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 | null;
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 external accounting service. The accounting service manages
393
- * user balances and transactions, and uses its own authentication separate
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
- * Transaction status in the accounting service.
695
+ * Wallet information for the current user.
398
696
  */
399
- declare const TransactionStatus: {
400
- /** Transaction created, awaiting confirmation */
401
- readonly PENDING: "pending";
402
- /** Transaction confirmed, funds transferred */
403
- readonly COMPLETED: "completed";
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
- * Transaction record from accounting service.
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 Transaction {
447
- readonly id: string;
448
- readonly senderEmail: string;
449
- readonly recipientEmail: string;
450
- readonly amount: number;
451
- readonly status: TransactionStatus;
452
- readonly createdBy: CreatorType;
453
- readonly resolvedBy: CreatorType | null;
454
- readonly createdAt: Date;
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
- * Input for creating a direct transaction.
717
+ * A wallet transaction record.
461
718
  */
462
- interface CreateTransactionInput {
463
- /** Email of the recipient */
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
- senderEmail: string;
498
- recipientEmail: string;
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: TransactionStatus;
501
- createdBy: CreatorType;
502
- resolvedBy: CreatorType | null;
503
- createdAt: string;
504
- resolvedAt: string | null;
505
- appName: string | null;
506
- appEpPath: string | null;
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
- * Token response from createTransactionToken.
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 TransactionTokenResponse {
512
- token: string;
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<User>;
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
- * // Get a token for querying alice's SyftAI-Space endpoints
918
- * const tokenResponse = await client.auth.getSatelliteToken('alice');
919
- * console.log(`Token expires in ${tokenResponse.expiresIn} seconds`);
1439
+ * const agg = await client.users.aggregators.update(1, {
1440
+ * name: 'Updated Name'
1441
+ * });
920
1442
  */
921
- getSatelliteToken(audience: string): Promise<SatelliteTokenResponse>;
1443
+ update(aggregatorId: number, input: UserAggregatorUpdateInput): Promise<UserAggregator>;
922
1444
  /**
923
- * Get satellite tokens for multiple audiences in parallel.
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 audiences - Array of unique audience identifiers (usernames)
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
- * // Get tokens for multiple endpoint owners
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
- getSatelliteTokens(audiences: string[]): Promise<Map<string, string>>;
1454
+ delete(aggregatorId: number): Promise<void>;
938
1455
  /**
939
- * Get transaction tokens for multiple endpoint owners.
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
- * This is used by the chat flow to enable billing for endpoint usage.
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 ownerUsernames - Array of endpoint owner usernames
948
- * @returns TransactionTokensResponse with tokens map and any errors
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
- * // Get transaction tokens for endpoint owners
953
- * const response = await client.auth.getTransactionTokens(['alice', 'bob']);
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
- getTransactionTokens(ownerUsernames: string[]): Promise<TransactionTokensResponse>;
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, organizationId?: number): Promise<Endpoint>;
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 - Pagination 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 connects to an external accounting/billing service for managing
1412
- * user balances and transactions. The accounting service is separate from SyftHub
1413
- * and uses its own authentication (Basic auth with email/password).
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
- * // Create accounting client
1418
- * const accounting = new AccountingResource({
1419
- * url: 'https://accounting.example.com',
1420
- * email: 'user@example.com',
1421
- * password: 'secret'
1422
- * });
1423
- *
1424
- * // Get user balance
1425
- * const user = await accounting.getUser();
1426
- * console.log(`Balance: ${user.balance}`);
1427
- *
1428
- * // Create a transaction
1429
- * const tx = await accounting.createTransaction({
1430
- * recipientEmail: 'recipient@example.com',
1431
- * amount: 10.0,
1432
- * appName: 'syftai-space',
1433
- * appEpPath: 'alice/my-model'
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
- /** Accounting service URL */
2055
+ /** @deprecated No longer used - wallet API is accessed via SyftHub */
1446
2056
  url: string;
1447
- /** Email for Basic auth */
2057
+ /** @deprecated No longer used */
1448
2058
  email: string;
1449
- /** Password for Basic auth */
2059
+ /** @deprecated No longer used */
1450
2060
  password: string;
1451
- /** Request timeout in milliseconds (default: 30000) */
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
- * Handle accounting/billing operations with external service.
2074
+ * Wallet and payment operations via the SyftHub API.
1463
2075
  *
1464
- * The accounting service manages user balances and transactions. It uses
1465
- * Basic auth (email/password) for authentication, which is separate from
1466
- * SyftHub's JWT-based authentication.
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
- * Transaction Workflow:
1469
- * 1. Sender creates transaction (status=PENDING)
1470
- * 2. Either party confirms (status=COMPLETED) or cancels (status=CANCELLED)
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
- * Delegated Transaction Workflow:
1473
- * 1. Sender creates a transaction token for recipient
1474
- * 2. Recipient uses token to create delegated transaction
1475
- * 3. Recipient confirms the transaction
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 baseUrl;
1479
- private readonly email;
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
- * List account transactions with pagination.
2099
+ * Get the current user's wallet information.
1535
2100
  *
1536
- * Returns a lazy iterator that fetches pages on demand.
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
- * // Iterate through all transactions
1544
- * for await (const tx of accounting.getTransactions()) {
1545
- * console.log(`${tx.createdAt}: ${tx.amount} from ${tx.senderEmail}`);
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
- createTransaction(input: CreateTransactionInput): Promise<Transaction>;
2114
+ getWallet(): Promise<WalletInfo>;
1595
2115
  /**
1596
- * Confirm a pending transaction.
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
- * @param transactionId - The transaction ID to confirm
1602
- * @returns Transaction in COMPLETED status
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 tx = await accounting.confirmTransaction('tx_123');
1609
- * console.log(`Confirmed: ${tx.status}`); // "completed"
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
- confirmTransaction(transactionId: string): Promise<Transaction>;
2128
+ getBalance(): Promise<WalletBalance>;
1613
2129
  /**
1614
- * Cancel a pending transaction.
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
- * @param transactionId - The transaction ID to cancel
1620
- * @returns Transaction in CANCELLED status
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 tx = await accounting.cancelTransaction('tx_123');
1627
- * console.log(`Cancelled: ${tx.status}`); // "cancelled"
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
- cancelTransaction(transactionId: string): Promise<Transaction>;
2143
+ getTransactions(): Promise<WalletTransaction[]>;
1631
2144
  /**
1632
- * Create a transaction token for delegated transfers.
2145
+ * Create a new wallet for the current user.
1633
2146
  *
1634
- * Creates a JWT token that authorizes the recipient to create a
1635
- * transaction on behalf of the sender (current user). The token
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
- * Use this when you want to pre-authorize a payment that will be
1639
- * initiated by the recipient (e.g., a service charging for usage).
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
- * // Sender creates token
1647
- * const token = await accounting.createTransactionToken('service@example.com');
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
- createTransactionToken(recipientEmail: string): Promise<string>;
2160
+ createWallet(): Promise<{
2161
+ address: string;
2162
+ }>;
1654
2163
  /**
1655
- * Create a delegated transaction using a pre-authorized token.
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
- * The token authenticates the request instead of Basic auth.
1661
- *
1662
- * @param senderEmail - Email of the sender who created the token
1663
- * @param amount - Amount to transfer (must be > 0)
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
- * // Recipient creates transaction using sender's token
1672
- * const tx = await accounting.createDelegatedTransaction(
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
- createDelegatedTransaction(senderEmail: string, amount: number, token: string): Promise<Transaction>;
2177
+ importWallet(privateKey: string): Promise<{
2178
+ address: string;
2179
+ }>;
1683
2180
  }
1684
2181
  /**
1685
2182
  * Create a new AccountingResource instance.
1686
2183
  *
1687
- * @param options - Configuration options
1688
- * @returns AccountingResource instance
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
- * @example
1691
- * ```typescript
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 transaction tokens for all unique endpoint owners.
1896
- * Returns a map of owner username to transaction token.
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 getTransactionTokensForOwners;
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 transaction_tokens mapping for billing authorization.
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. Fetches transaction tokens for billing authorization
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. Fetches transaction tokens for billing authorization
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 _accountingInitPromise;
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
- * Accounting resource for billing and transactions.
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
- * The accounting service is external and uses separate credentials
2190
- * (email/password Basic auth) from SyftHub's JWT authentication.
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
- * Credentials are automatically retrieved from the backend after login.
2193
- * You must call `initAccounting()` after login to initialize this resource.
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 user = await client.accounting.getUser();
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 by fetching credentials from the backend.
2979
+ * Initialize the accounting (wallet) resource.
2208
2980
  *
2209
- * This method retrieves accounting credentials from the SyftHub backend
2210
- * and initializes the accounting resource. Requires authentication.
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 user = await client.accounting.getUser();
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 user = await client.accounting.getUser();
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 AccountingUser, AggregatorError, type AuthTokens, AuthenticationError, AuthorizationError, type BrowseOptions, type ChatMetadata, type ChatOptions, ChatResource, type ChatResponse, type ChatStreamEvent, ConfigurationError, type Connection, type CreateDelegatedTransactionInput, type CreateTransactionInput, CreatorType, type Document, type DoneEvent, type Endpoint, type EndpointCreateInput, type EndpointPublic, type EndpointRef, EndpointResolutionError, EndpointType, type EndpointUpdateInput, type ErrorEvent, GenerationError, type GenerationStartEvent, InvalidAccountingPasswordError, type ListEndpointsOptions, type Message, NetworkError, NotFoundError, OrganizationRole, type PageFetcher, PageIterator, type PasswordChangeInput, type Policy, type QueryDataSourceOptions, type QueryModelOptions, type RetrievalCompleteEvent, RetrievalError, type RetrievalStartEvent, type SourceCompleteEvent, type SourceInfo, type SourceStatus, SyftAIResource, SyftHubClient, type SyftHubClientOptions, SyftHubError, type SyncEndpointsResponse, type TokenEvent, type Transaction, type TransactionResponse, TransactionStatus, type TransactionTokenResponse, type TransactionsOptions, type TrendingOptions, type UpdatePasswordInput, type User, UserAlreadyExistsError, type UserRegisterInput, UserRole, type UserUpdateInput, ValidationError, Visibility, createAccountingResource, getEndpointOwnerType, getEndpointPublicPath, isTransactionCancelled, isTransactionCompleted, isTransactionPending, parseTransaction };
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 };